jason.woltje
ad21ad7ac5
ci/woodpecker/pr/ci Pipeline failed
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.
121 lines
6.3 KiB
Markdown
121 lines
6.3 KiB
Markdown
---
|
||
id: SESS.1
|
||
status: ratified
|
||
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.
|