M-0: pre-migration gates (JarvisAPI package, harness, behavioral gates, dual-handshake) #4

New Issue

2026-05-12T19:01:39Z

KofTwentyTwo commented

2026-05-12 19:01:39 +00:00

(Migrated from github.com)

Goal

Land the substrate the rest of the migration assumes (API package, harness, behavioral gates, dual-version handshake) before any surface migrates. Pure additive substrate on develop: new JarvisAPI package, parametric harness driver, dual-version bus handshake, two grep gates promoted to behavioral.

Scope — surfaces in this phase

No live API surfaces. Substrate only:

JarvisAPI package skeleton — types-only (Surfaces, Commands, Events, Queries, Errors, JarvisHost)
APIClock protocol + RealClock + ManualClock (G-002)
TransportMode.{inProcessActor, jsonRoundTripWebView} + parametric scenario runner stub (UQ-5)
JARVIS_HARNESS=1 runtime gate + ProviderOverrides plumbing (UQ-1, G-001/G-003/G-004)
Dual-channel bus handshake (accept ["2.3.0", "2.4.0-rc"])
18th boundary gate: check-fanout-drainer.sh
Behavioral promotion of two grep gates: check-single-writer-hudstate.sh + check-install-order.sh
BusForwarder.drain takes sink fan-out (1 drainer, N≥1 sinks)
Hoist test doubles (MockTTSForController, CapturingSTTProvider, MockVADEngine, FakeKeychain, FakeStore) from @testable test targets into Sources/Harness/

Files (created/modified)

packages/JarvisAPI/Package.swift (new)
packages/JarvisAPI/Sources/JarvisAPI/{Surfaces,Commands,Events,Queries,Errors,JarvisHost,Clock}.swift (new)
packages/Harness/Sources/Harness/TransportMode.swift (new) + scenario runner
packages/Bus/Sources/Bus/WebviewBridge.swift:147-288 + Protocol.swift:28
scripts/check-single-writer-hudstate.sh (rewrite as harness probe wrapper; grep kept)
scripts/check-install-order.sh (rewrite as behavioral; grep kept)
scripts/check-fanout-drainer.sh (new)
scripts/check-no-schema-migration-in-turn.sh (new — referenced by M-7)
packages/AgentCore/Sources/AgentOrchestrator/BusForwarder.swift (sink fan-out)
packages/Harness/Sources/Harness/{Mock,Stub,Fake}*.swift (hoisted from test targets)

Test contract

No surface scenarios yet. Substrate validation:

swift test --package-path packages/JarvisAPI green (types compile)
swift test --package-path packages/Harness green (parametric runner scaffolding compiles)
Behavioral install-order probe passes (M-0.7)
Behavioral single-writer-HUD probe passes (M-0.6)
scripts/check-fanout-drainer.sh green (M-0.8 single drainer, multiple sinks)
Per UQ-5 ratification, the parametric runner scaffolding itself is verified to invoke a stub scenario in both modes.

Acceptance criteria

swift test --package-path packages/JarvisAPI green (types compile)
swift test --package-path packages/Harness green (parametric runner scaffolding compiles)
bash scripts/check-app-builds.sh green
bash scripts/check-bus-protocol-version.sh adapted for dual-version, green
Behavioral install-order test passes
Behavioral single-writer-HUD test passes
New scripts/check-fanout-drainer.sh green
New scripts/check-no-schema-migration-in-turn.sh present (used by M-7)
All existing boundary gates remain green (no regression from substrate changes)
JARVIS_HARNESS=1 runtime gate verified: test seams no-op when env var absent
All scenarios pass via .inProcessActor runner (scaffolding stub)
All scenarios pass via .jsonRoundTripWebView runner (scaffolding stub)
PR merged to develop (actually direct-on-develop per plan — M-0 is additive substrate with no PR per §2.1)

Carry-forward closures

None — substrate only. B-02 already closed by tactical patch (2026-05-11, commit 48ad8d6).

Dependencies

Blocked by: B-02 tactical patch (DONE 2026-05-11)
Blocks: #5 (M-1), and transitively #6–#11

Sub-issues

#90 — M-0: scaffold packages/JarvisAPI/ package skeleton (types only, no conformers)
#91 — M-0: APIClock protocol + RealClock + ManualClock (G-002)
#92 — M-0: TransportMode + parametric harness ScenarioRunner scaffolding (UQ-5)
#93 — M-0: JARVIS_HARNESS=1 runtime gate + ProviderOverrides (UQ-1)
#94 — M-0: WebviewBridge dual-channel handshake — accept [2.3.0, 2.4.0-rc]
#95 — M-0: Promote check-single-writer-hudstate.sh to behavioral probe (R-004)
#96 — M-0: Promote check-install-order.sh to behavioral probe (R-001)
#97 — M-0: BusForwarder sink fanout + check-fanout-drainer.sh boundary gate (R-009)
#98 — M-0: hoist Mock*/Stub*/Fake* test doubles into packages/Harness/Sources
#99 — M-0: check-no-schema-migration-in-turn.sh boundary gate (Failure Mode 5)

Estimate

2.5–3.5 engineer-days

Source

.planning/architecture/JARVIS-API-MIGRATION-PLAN.md §2.1
.planning/architecture/JARVIS-API-DESIGN-v0.2.md §5 (UQ-1, UQ-5)
.planning/architecture/REVIEW-MIGRATION-RISK.md R-001, R-004, R-005, R-009
Parent epic: v1.0 API Migration — UI/Backend separation (M-0..M-7) (#76)

## Goal Land the substrate the rest of the migration assumes (API package, harness, behavioral gates, dual-version handshake) before any surface migrates. Pure additive substrate on `develop`: new `JarvisAPI` package, parametric harness driver, dual-version bus handshake, two grep gates promoted to behavioral. ## Scope — surfaces in this phase No live API surfaces. Substrate only: - `JarvisAPI` package skeleton — types-only (`Surfaces`, `Commands`, `Events`, `Queries`, `Errors`, `JarvisHost`) - `APIClock` protocol + `RealClock` + `ManualClock` (G-002) - `TransportMode.{inProcessActor, jsonRoundTripWebView}` + parametric scenario runner stub (UQ-5) - `JARVIS_HARNESS=1` runtime gate + `ProviderOverrides` plumbing (UQ-1, G-001/G-003/G-004) - Dual-channel bus handshake (accept `["2.3.0", "2.4.0-rc"]`) - 18th boundary gate: `check-fanout-drainer.sh` - Behavioral promotion of two grep gates: `check-single-writer-hudstate.sh` + `check-install-order.sh` - `BusForwarder.drain` takes sink fan-out (1 drainer, N≥1 sinks) - Hoist test doubles (`MockTTSForController`, `CapturingSTTProvider`, `MockVADEngine`, `FakeKeychain`, `FakeStore`) from `@testable` test targets into `Sources/Harness/` ## Files (created/modified) - `packages/JarvisAPI/Package.swift` (new) - `packages/JarvisAPI/Sources/JarvisAPI/{Surfaces,Commands,Events,Queries,Errors,JarvisHost,Clock}.swift` (new) - `packages/Harness/Sources/Harness/TransportMode.swift` (new) + scenario runner - `packages/Bus/Sources/Bus/WebviewBridge.swift:147-288` + `Protocol.swift:28` - `scripts/check-single-writer-hudstate.sh` (rewrite as harness probe wrapper; grep kept) - `scripts/check-install-order.sh` (rewrite as behavioral; grep kept) - `scripts/check-fanout-drainer.sh` (new) - `scripts/check-no-schema-migration-in-turn.sh` (new — referenced by M-7) - `packages/AgentCore/Sources/AgentOrchestrator/BusForwarder.swift` (sink fan-out) - `packages/Harness/Sources/Harness/{Mock,Stub,Fake}*.swift` (hoisted from test targets) ## Test contract No surface scenarios yet. Substrate validation: - `swift test --package-path packages/JarvisAPI` green (types compile) - `swift test --package-path packages/Harness` green (parametric runner scaffolding compiles) - Behavioral install-order probe passes (M-0.7) - Behavioral single-writer-HUD probe passes (M-0.6) - `scripts/check-fanout-drainer.sh` green (M-0.8 single drainer, multiple sinks) - Per UQ-5 ratification, the parametric runner scaffolding itself is verified to invoke a stub scenario in both modes. ## Acceptance criteria - [ ] `swift test --package-path packages/JarvisAPI` green (types compile) - [ ] `swift test --package-path packages/Harness` green (parametric runner scaffolding compiles) - [ ] `bash scripts/check-app-builds.sh` green - [ ] `bash scripts/check-bus-protocol-version.sh` adapted for dual-version, green - [ ] Behavioral install-order test passes - [ ] Behavioral single-writer-HUD test passes - [ ] New `scripts/check-fanout-drainer.sh` green - [ ] New `scripts/check-no-schema-migration-in-turn.sh` present (used by M-7) - [ ] All existing boundary gates remain green (no regression from substrate changes) - [ ] `JARVIS_HARNESS=1` runtime gate verified: test seams no-op when env var absent - [ ] All scenarios pass via `.inProcessActor` runner (scaffolding stub) - [ ] All scenarios pass via `.jsonRoundTripWebView` runner (scaffolding stub) - [ ] PR merged to develop (actually direct-on-develop per plan — M-0 is additive substrate with no PR per §2.1) ## Carry-forward closures None — substrate only. B-02 already closed by tactical patch (2026-05-11, commit `48ad8d6`). ## Dependencies - Blocked by: B-02 tactical patch (DONE 2026-05-11) - Blocks: #5 (M-1), and transitively #6–#11 ## Sub-issues - #90 — M-0: scaffold packages/JarvisAPI/ package skeleton (types only, no conformers) - #91 — M-0: APIClock protocol + RealClock + ManualClock (G-002) - #92 — M-0: TransportMode + parametric harness ScenarioRunner scaffolding (UQ-5) - #93 — M-0: JARVIS_HARNESS=1 runtime gate + ProviderOverrides (UQ-1) - #94 — M-0: WebviewBridge dual-channel handshake — accept [2.3.0, 2.4.0-rc] - #95 — M-0: Promote check-single-writer-hudstate.sh to behavioral probe (R-004) - #96 — M-0: Promote check-install-order.sh to behavioral probe (R-001) - #97 — M-0: BusForwarder sink fanout + check-fanout-drainer.sh boundary gate (R-009) - #98 — M-0: hoist Mock*/Stub*/Fake* test doubles into packages/Harness/Sources - #99 — M-0: check-no-schema-migration-in-turn.sh boundary gate (Failure Mode 5) ## Estimate 2.5–3.5 engineer-days ## Source - `.planning/architecture/JARVIS-API-MIGRATION-PLAN.md` §2.1 - `.planning/architecture/JARVIS-API-DESIGN-v0.2.md` §5 (UQ-1, UQ-5) - `.planning/architecture/REVIEW-MIGRATION-RISK.md` R-001, R-004, R-005, R-009 - Parent epic: #76

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: KofTwentyTwo/Jarvis#4