Skip to content

m4-5-rfi-spike-2026-02-28.md

Latest commit

 

History

History
156 lines (110 loc) · 4.99 KB

m4-5-rfi-spike-2026-02-28.md

File metadata and controls

156 lines (110 loc) · 4.99 KB

M4-5 Multi-Crate Workspace RFI Spike (2026-02-28)

Status: RFI complete, extraction execution pending. Issue: #2263 Linear parent: RMN-243

Scope

This spike is strictly no-behavior-change planning for the M4-5 workspace split.

Goals:

  • capture reproducible compile baseline metrics
  • define crate boundary and dependency contract
  • define CI/feature-matrix impact and rollback posture
  • define stacked PR slicing plan (XS/S/M)

Out of scope:

  • broad API redesign
  • feature additions bundled with structure work
  • one-shot mega-PR extraction

Baseline Compile Metrics

Repro command

scripts/ci/m4_5_rfi_baseline.sh /tmp/zeroclaw-m4rfi-target

Preflight compile blockers observed on origin/main

Before timing could run cleanly, two compile blockers were found:

  • src/gateway/mod.rs:2176: run_gateway_chat_with_tools call missing session_id argument
  • src/providers/cursor.rs:233: ChatResponse initializer missing quota_metadata

RFI includes minimal compile-compat fixes for these two blockers so measurements are reproducible.

Measured results (Apple Silicon macOS, local workspace)

Phase real(s) status
A: cold cargo check --workspace --locked 306.47 pass
B: cold-ish cargo build --workspace --locked 219.07 pass
C: warm cargo check --workspace --locked 0.84 pass
D: incremental cargo check after touching src/main.rs 6.19 pass

Observations:

  • cold check is the dominant iteration tax
  • warm-check performance is excellent once target artifacts exist
  • incremental behavior is acceptable but sensitive to wide root-crate coupling

Current Workspace Snapshot

Current workspace members:

  • . (zeroclaw monolith crate)
  • crates/robot-kit

Code concentration still sits in the monolith. Large hotspots include:

  • src/config/schema.rs
  • src/channels/mod.rs
  • src/onboard/wizard.rs
  • src/agent/loop_.rs
  • src/gateway/mod.rs

Proposed Boundary Contract

Target crate topology for staged extraction:

  1. crates/zeroclaw-types
  • shared DTOs, enums, IDs, lightweight cross-domain traits
  • no provider/channel/network dependencies
  1. crates/zeroclaw-core
  • config structs + validation, provider trait contracts, routing primitives, policy helpers
  • depends on zeroclaw-types
  1. crates/zeroclaw-memory
  • memory traits/backends + hygiene/snapshot plumbing
  • depends on zeroclaw-types, zeroclaw-core contracts only where required
  1. crates/zeroclaw-channels
  • channel adapters + inbound normalization
  • depends on zeroclaw-types, zeroclaw-core, zeroclaw-memory
  1. crates/zeroclaw-api
  • gateway/webhook/http orchestration
  • depends on zeroclaw-types, zeroclaw-core, zeroclaw-memory, zeroclaw-channels
  1. crates/zeroclaw-bin (or keep root binary package name stable)
  • CLI entrypoints + wiring only

Dependency rules:

  • no downward imports from foundational crates into higher layers
  • channels must not depend on gateway/http crate
  • keep provider-specific SDK deps out of zeroclaw-types
  • maintain feature-flag parity at workspace root during migration

CI / Feature-Matrix Impact

Required CI adjustments during migration:

  • add workspace compile lane (cargo check --workspace --locked)
  • add package-focused lanes for extracted crates (-p zeroclaw-types, -p zeroclaw-core, etc.)
  • keep existing runtime behavior lanes (test, sec-audit, codeql) unchanged until final convergence
  • update path filters so crate-local changes trigger only relevant crate tests plus contract smoke tests

Guardrails:

  • changed-line strict-delta lint remains mandatory
  • each extraction PR must include no-behavior-change assertion in PR body
  • each step must include explicit rollback note

Rollback Strategy

Per-step rollback (stack-safe):

  1. revert latest extraction PR only
  2. re-run workspace compile + existing CI matrix
  3. keep binary entrypoint and config contract untouched until final extraction stage

Abort criteria:

  • unexpected runtime behavior drift
  • CI lane expansion causes recurring queue stalls without signal gain
  • feature-flag compatibility regressions

Stacked PR Slicing Plan

PR-1 (XS)

  • add crate shells + workspace wiring (types/core), no symbol moves
  • objective: establish scaffolding and CI package lanes

PR-2 (S)

  • extract low-churn shared types into zeroclaw-types
  • add re-export shim layer to preserve existing import paths

PR-3 (S)

  • extract config/provider contracts into zeroclaw-core
  • keep runtime call sites unchanged via compatibility re-exports

PR-4 (M)

  • extract memory subsystem crate and move wiring boundaries
  • run full memory + gateway regression suite

PR-5 (M)

  • extract channels/api orchestration seams
  • finalize package ownership and remove temporary re-export shims

Next Execution Step

Open first no-behavior-change extraction PR from this RFI baseline:

  • scope: workspace crate scaffolding + CI package lanes only
  • no runtime behavior changes
  • explicit rollback command included in PR body