jason.woltje
ad21ad7ac5
Ratifies the Mosaic Stack PRD rev1 (Jason Woltje, 2026-09-01) as project source of truth and installs the GOV.1 lifecycle model: - docs/PRD.md becomes a permanent shim (kind: shim, current_rev -> docs/PRDs/2026-08-31_PRD_rev1/). Its path never changes again. - docs/PRDs/2026-08-26_PRD_rev0/PRD.md archives the 2026-08-26 North Star verbatim (sha256 60cc2f98...36afdf unchanged). Archive, never delete. - docs/PRDs/2026-08-31_PRD_rev1/ is the frozen rev1 bundle: 18 sectioned documents (VIS, DATA, AUTHN, AUTHZ, SEAT, ROLE, HARN, PROV, SESS, UI, CLI, GOV.1-5) consolidating rev0 D1-D15, the fleet north star, the agent-runtime L1/L2 contracts and the control-plane-surfaces lane findings, with a single decision map (GOV.3) and a closed open-questions frontier (GOV.5, grill rounds 1-8). Drafting inputs (_source-* snapshots) are not shipped. Consequences of the ratified rulings carried in the same change: - Q-T1 (ruling B, "shipped but frozen"): D3 amended in GOV.3/VIS.1; federation M1-M3 acknowledged as shipped behind tier === 'federated', excluded from the v1 bar and frozen, with a security re-audit gate before any resumption. docs/MISSION-MANIFEST.md, docs/federation/MISSION-MANIFEST.md and docs/scratchpads/mvp-20260312.md get status: superseded + banners (content preserved verbatim); docs/guides/deployment.md gains a "Relationship to the PRD (D15)" section. NORTH_STAR.yaml adds dormant workstream M (projects no goals by design); NORTH_STAR.md regenerated. - Q-G2 (distinct registry prefixes): every citation of the operator DECISION-REGISTER in the bundle reads OD-nn; the stack registry stays D1-D15; L1-Dnn/L2-Dnn untouched. Prefix rule recorded in GOV.1. Follow-ups (not in this PR): CI parity drift-gate witness (Q-C1); brain-side DECISION-REGISTER rename to OD- with redirect table on its next touch.
6.3 KiB
id, status, ratified
| id | status | ratified |
|---|---|---|
| SESS.1 | ratified | 2026-09-01 (Jason Woltje; PRD rev1 ratification PR) |
SESS.1 — Session identity and mid-stream switching
Requirement (Jason, 2026-08-31)
An agent session stays active on the system, tied to a Stack session id. Changing harness, model, or provider mid-stream preserves the session id and fully switches context from one provider/harness to another, with no user intervention and no noticeable performance degradation.
Two operations, two code paths — never merged
| Harness / model / provider switch | Role switch | |
|---|---|---|
| Session id | preserved | seat identity preserved; session is clean |
| Context | fully transferred | ephemeral context discarded (register OD-03) |
| Governed by | this section | SEAT.1-seat-profile §role-binding |
| Why | continuity requirement | an active session never switches roles (register OD-02) |
The ratified mechanism already exists: register OD-57–OD-61
The 2026-08-28 register confirms the machinery this requirement needs:
- OD-57 checkpoints — atomic, schema-valid, revisioned seat checkpoints tied to incarnation and lease; freshness enforced mechanically.
- OD-59 relaunch — the coordinator requests and validates a checkpoint, stops the session, applies configuration, starts a clean incarnation, restores the assignment, verifies readiness.
- OD-60 fencing — leases, epochs, incarnation IDs, fencing tokens prevent a stale session from mutating state after the switch.
- OD-61 restart recovery — the relaunched seat restores role, mission, task, PRD pin, constraints, evidence, blockers, leases, dependencies, and next action without prior conversation.
A mid-stream harness switch is therefore an OD-59 relaunch keyed to a persistent Stack session id: checkpoint → stop → reconfigure → new incarnation → restore → resume. What OD-59 does not yet promise is the experience bar — no user intervention, no noticeable degradation — which is this PRD's addition.
Identity layering
mosaic-core mints a per-launch incarnation id and keys its journal on it,
deliberately not on any session id. A harness switch is a new process → new
incarnation → new journal, while the Stack session id persists. So:
Stack session id (durable; user-facing continuity)
└─ incarnation id (per launch; enforcement journal, fencing per OD-60)
The precise contract between the two ids — minting, custody, what the coordinator records at each relaunch — must be specified before build: GOV.5-open-questions Q-S1.
Open hard problem
Context-transfer fidelity between harnesses with different context formats, tool-call encodings, and system-prompt injection points. The checkpoint (OD-57) is the transfer vehicle; whether a checkpoint alone meets "no noticeable degradation" across harness families is unproven: GOV.5-open-questions Q-S3.
Session lifecycle state machine (pulled 2026-08-31 from the session-lifecycle draft — with one required extension)
The operator draft (workflows/session-lifecycle.md, the densest
decision-register consumer: OD-03/OD-04/OD-08, OD-56–OD-65) supplies the checkpoint/
lease/fencing machinery this section's continuity requirement runs on:
- States: Active → Relaunch-requested (triggers per OD-59: context utilization, session age, milestone, drift, degraded health, role reconfiguration, authorized request) → Checkpointing (atomic, revisioned, bound to identity + incarnation + epoch + lease, OD-57) → Relaunching (validated checkpoint, old lease revoked → new incarnation, new fencing token, OD-59) → Restoring (readiness proof: role, task, PRD pin, blockers, next action, OD-61) → Active/Degraded. Role change routes through Reconfiguring first (old-role record, transition history, revoked lease, OD-03/OD-04).
- Fencing: a stale session cannot mutate after its replacement holds the new token (OD-60); mutation authority is lease-gated and not renewed while the checkpoint is stale. Coordinator outage fails closed for new assignments/relaunches/renewals; existing leases run to expiry; read-only work continues (OD-63).
- Checkpoint contents (required fields): role, config version, mission, outcome node, task, PRD pin, constraints, completed work with evidence refs, blockers and failed attempts, active leases/external ops, next action with required inputs. The checkpoint is an operational projection — mission truth stays in the ledger (OD-58). Telemetry is append-only and never the resumable checkpoint (OD-56).
Structural gap found at extraction (must be fixed before this machine ratifies): the draft models exactly one relaunch mechanism — every trigger, without exception, mints a new incarnation and fencing token. There is no continuity-preserving path at all, and harness/model/provider switching does not appear among the triggers. This PRD's two-operations rule (above) requires two code paths: the state machine must gain a switch path that preserves the Stack session id and full context per OD-57–OD-61 while still rotating the fencing token safely. Adopting the draft's table verbatim would silently collapse the two operations back into one — the exact defect register OD-02/OD-03 vs the continuity requirement exists to prevent.
E2 inputs (triage 2026-08-31; see GOV.2-docs-inventory)
Canonical ground truth: DEVELOPER-GUIDE/architecture/compaction-revocation.md
(the only current continuity/revocation lifecycle — observer/generation-fencing,
test-consumed), channel-protocol.md.
Pending pulls: brain docs/guides/proposed/workflows/session-lifecycle.md
(checkpoint/relaunch/recovery/role-reconfig — complements this section's
switching focus; its role-reconfig path must respect the OD-02/OD-03 clean-session rule).
Two-path requirement ratified (Q-S4, Jason 2026-09-01)
The state-machine gap flagged above is now a binding requirement: the session-lifecycle draft may not land with a single relaunch path. Role change → clean-session path (new incarnation + fencing token, context discarded, OD-02/OD-03). Harness/model/provider change → continuity path (same Stack session id, OD-57 checkpoint restored under OD-61, no noticeable degradation). The two paths must not share a code path.