jason.woltje
13968e9a8b
Addresses CPS-PRD-REV1-REVIEW-Q90 findings F1 and F3 on PR #1491: F1 (format gate): `prettier --write` on the 18 rev1 bundle documents. Whitespace, table padding, list markers and emphasis delimiters only — a normalized token comparison of every file before/after shows zero content difference, so the ratified text is unchanged and no re-ratification applies. F3 (rev0 relative links): the archived rev0 PRD stays byte-identical (sha256 60cc2f98...36afdf verified) per GOV.1 archive-never-edit. A sibling docs/PRDs/2026-08-26_PRD_rev0/README.md records the digest, the original location, the owner disposition that the in-file links are intentionally historical, and a resolution table for all 9 targets (11 occurrences), each verified to exist. Future relocated archives ship the same README instead of edited bytes. F2 (test step) is investigated separately against the CI log.
6.5 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.