instar 1.3.91 → 1.3.92

package/upgrades/side-effects/session-pool-track-h-mesh-client.md

@@ -0,0 +1,15 @@
+# Side effects — Track H part 4: outbound MeshRpcClient (§L0 send side, dark)
+
+## What this adds
+`src/core/MeshRpcClient.ts` — the SEND side of MeshRpc, the outbound counterpart to MeshRpcDispatcher (receive). Builds a §L0 envelope (recipient-bound, Ed25519-signed, nonce + timestamp), POSTs to a peer's /mesh/rpc, returns the typed result (maps the dispatcher's reason/status on a non-200; throws only on transport error/timeout so the caller's retry loop catches it). Per-attempt timeout via AbortController; fully injected (fetch/sign/nonce/clock).
+
+This is the activation transport (D11): it's what makes the SessionRouter's deliverMessage/spawnOnMachine deps and the TransferOrchestrator's sendTransferRpc dep live ACROSS machines.
+
+## Risk / blast radius
+None — pure transport class, not wired into the router yet (the activation step wires it as the router's outbound deps). No behavior change.
+
+## Tests
+- `tests/integration/mesh-rpc-client-roundtrip.test.ts` — 4 over a real MeshRpcDispatcher + real Ed25519 keys + loopback /mesh/rpc: full router→owner deliverMessage round-trip (200 + result + handler ran); RBAC rejection mapped (non-router → 403 not-router); replayed-nonce → 409 on the second send; transport error throws.
+
+## Status — m2m transport COMPLETE
+Send (MeshRpcClient) + receive (MeshRpcDispatcher) are both built + round-trip-proven. The remaining Track-H work is the ACTIVATION (wire MeshRpcClient as the SessionRouter's outbound deps + flip live-ingress to route through the router) + the staged real-hardware (laptop+mini) + test-as-self nickname-swap proof.

package/upgrades/side-effects/session-pool-track-h-rebalance.md

@@ -0,0 +1,13 @@
+# Side effects — Track H part 3: load-rebalance planner (§L4 Stage-3, dark)
+
+## What this adds
+`src/core/RebalancePlanner.ts` — the pure Stage-3 load-rebalance decision. `planRebalance(input, placementExecutor)` proposes a BOUNDED set of transfers off over-saturated machines (session ratio > rebalanceThresholdPercent), only for non-pinned, low-priority, off-cooldown sessions; at most one move per source per cycle (cascade guard); the target is chosen by the same PlacementExecutor.decide(reason:'rebalance') the router uses; a working copy of capacities is updated as moves are proposed so it never piles onto one target. No qualifying session ⇒ no move.
+
+## Risk / blast radius
+None — pure function, not wired into a tick yet. The caller (a heartbeat-interval rebalance tick, post-activation) performs the actual transfers via TransferOrchestrator. Evaluated ONLY on the heartbeat interval by design, never per message.
+
+## Tests
+- `tests/unit/RebalancePlanner.test.ts` — 8: moves off-saturated→free; no-move-under-threshold; never moves pinned/hard-pinned; never moves within cooldown; never moves a non-low-priority/critical session; one-move-per-source cascade cap; distinct-sessions across sources; purity.
+
+## Follow-ups (Track H — the remaining frontier)
+The heartbeat rebalance tick that drives planRebalance → TransferOrchestrator; the live-ingress interception + outbound mesh client (D11 activation); real-hardware (laptop+mini) + test-as-self nickname-swap proof.

package/upgrades/side-effects/session-pool-track-h-rollout-gate.md

@@ -0,0 +1,17 @@
+# Side effects — Track H part 1: rollout gate (StageAdvancer + E2E result store) (§Rollout)
+
+## What this adds
+The mechanical rollout gate for the staged dark→shadow→live-transfer→rebalance ladder. Pure components, shipped DARK (constructed in boot when the pool is enabled; the stage stays 'dark' until a green prior-stage E2E exists).
+
+- `src/core/SessionPoolE2EResultStore.ts` — signed, append-only log of each stage's Tier-3 E2E outcome (`StageE2EResult`). recordResult (the E2E harness is the only writer) signs each row; getLatestForStage returns the most recent (a later red supersedes an earlier green); verify() is tamper-evidence; append-only history preserved.
+- `src/core/StageAdvancer.ts` — the SOLE stage-config writer + the gate. advanceTo(stage) REFUSES (e2e-gate-not-passed) unless the prior stage's E2E is green for the CURRENT commit (missing/red/stale-commit/tampered → refused). reconcile() mechanically REVERTS to the prior stage when a live stage records red. 'dark' is the floor.
+
+## Risk / blast radius
+None — pure components, not yet wired into boot (the Config.ts stage-write guard + boot construction + GET /session-pool/e2e-results route land in part 2). No runtime behavior change.
+
+## Tests
+- `tests/unit/SessionPoolE2EResultStore.test.ts` — 5: signed record/read, latest-per-stage (red supersedes green), stage independence, tamper-evidence, missing-file/torn-line tolerance.
+- `tests/unit/StageAdvancer.test.ts` — 9: refuse-no-result / advance-on-green / refuse stale-commit / refuse red / refuse bad-signature / refuse already-at-or-past; reconcile reverts-on-red / stays-on-green / dark-floor-noop.
+
+## Follow-ups (Track H)
+Part 2: Config.ts stage-write guard (stage-write-not-permitted for non-StageAdvancer writes) + boot wiring + GET /session-pool/e2e-results + the CI release-boundary check. The real-hardware + test-as-self proof (nickname-driven mid-conversation swap) is the culmination, which also needs the live-ingress interception + outbound mesh client (D11 activation).

package/upgrades/side-effects/session-pool-track-h-stage-guard.md

@@ -0,0 +1,16 @@
+# Side effects — Track H part 2a: stage-write guard (§Rollout, Structure > Willpower)
+
+## What this adds
+The structural enforcement that `multiMachine.sessionPool.stage` is StageAdvancer-write-only.
+
+- `src/config/stageWriteGuard.ts` (NEW) — `STAGE_CONFIG_PATH`, a module-private `STAGE_WRITE_TOKEN` capability symbol, `assertStageWriteAuthorized(dotPath, token)` (throws `StageWriteNotPermittedError` / code `stage-write-not-permitted` on a stage write without the token; no-op for any other path).
+- `src/config/LiveConfig.ts` — `set(dotPath, value, opts?)` now calls the guard first. A direct runtime write to the rollout stage without the token is refused; every other config write is unaffected (opts is optional, backward-compatible). StageAdvancer's boot wiring passes the token.
+
+## Risk / blast radius
+None for existing callers — the guard only fires for the exact stage path, and `opts` is optional so all current `set()` callsites are unchanged. The stage field is already only written by StageAdvancer; this makes that structural (a stray ad-hoc write now throws instead of silently flipping the rollout).
+
+## Tests
+- `tests/unit/stageWriteGuard.test.ts` — 6: assert throws without/with-forged token, allows with token, no-op for other paths; LiveConfig refuses a direct stage write (unchanged on disk), allows it with the token, and does not gate other writes.
+
+## Follow-ups (Track H)
+StageAdvancer + E2EResultStore boot construction + `GET /session-pool/e2e-results` route + the CI release-boundary check; rebalance; live-ingress interception + outbound mesh client (D11); real-hardware + test-as-self proof.