ceos/opencode
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(v2): render context epoch diagrams

Browse source
This commit is contained in:
Kit Langton 2026-06-04 23:20:09 -04:00
commit 2187c2a423
1 changed files with 36 additions and 28 deletions
Download patch file Download diff file Expand all files Collapse all files

64
specs/v2/session.md
View file

@ -43,38 +43,46 @@ V2 Sessions persist the exact privileged System Context shown to the model. A Co
The first complete observation initializes the epoch before any pending prompt becomes model-visible. If initial context is temporarily unavailable, execution stops while the prompt remains pending and retryable. On later provider turns, the runner promotes eligible input first, then reconciles current sources at the safe boundary. Changed context becomes one durable chronological System message, and its event commit advances the epoch snapshot atomically. The first complete observation initializes the epoch before any pending prompt becomes model-visible. If initial context is temporarily unavailable, execution stops while the prompt remains pending and retryable. On later provider turns, the runner promotes eligible input first, then reconciles current sources at the safe boundary. Changed context becomes one durable chronological System message, and its event commit advances the epoch snapshot atomically.
```mermaid ```text
sequenceDiagram Client Runner System Context Registry Context Epoch Store Session History LLM
participant Client │ │ │ │ │ │
participant Runner ├─ Admit prompt ─────────────────────────────────────────────────────────────────────────────────────────────▶ │
participant Registry as System Context Registry │ │ │ │ │ │
participant Epoch as Context Epoch Store │ ├─ Observe initial context ────────────▶ │ │ │
participant History as Session History │ │ │ │ │ │
participant LLM │ ◀─ Complete baseline or unavailable ───┤ │ │ │
│ │ │ │ │ │
Client->>History: Admit prompt │ ├─ Initialize missing epoch ───────────────────────────────────────▶ │ │
Runner->>Registry: Observe initial context │ │ │ │ │ │
Registry-->>Runner: Complete baseline or unavailable │ ├─ Promote eligible input ─────────────────────────────────────────────────────────────────▶ │
Runner->>Epoch: Initialize missing epoch │ │ │ │ │ │
Runner->>History: Promote eligible input │ ├─ Reconcile at safe boundary ─────────▶ │ │ │
Runner->>Registry: Reconcile at safe boundary │ │ │ │ │ │
Registry-->>Runner: Unchanged or chronological update │ ◀─ Unchanged or chronological update ──┤ │ │ │
Runner->>Epoch: Advance snapshot atomically with update │ │ │ │ │ │
Runner->>LLM: Baseline + chronological history │ ├─ Advance snapshot atomically with update ────────────────────────▶ │ │
│ │ │ │ │ │
│ ├─ Baseline + chronological history ─────────────────────────────────────────────────────────────────────────▶
``` ```
Model switches and completed compactions request lazy baseline replacement. A Session move clears the epoch so the destination Location must initialize a complete baseline before promoting more input. Epoch creation is fenced against the authoritative Session Location, preventing an old-Location runner from recreating stale privileged context after a concurrent move. Model switches and completed compactions request lazy baseline replacement. A Session move clears the epoch so the destination Location must initialize a complete baseline before promoting more input. Epoch creation is fenced against the authoritative Session Location, preventing an old-Location runner from recreating stale privileged context after a concurrent move.
```mermaid ```text
stateDiagram-v2 Session Epoch
[*] --> Missing │ │
Missing --> Active: complete initial observation ├─ initialize complete baseline ──▶
Missing --> Missing: initial context unavailable │ │
Active --> Active: reconcile change │ ├─────────────────────────────────╮
Active --> ReplacementPending: model switch or compaction │ │ reconcile chronological update │
ReplacementPending --> Active: complete replacement observation │ ◀─────────────────────────────────╯
Active --> Missing: Session moves Location │ │
ReplacementPending --> Missing: Session moves Location ├─ request replacement ───────────▶
│ │
│ ├─────────────────────────────────────╮
│ │ replace after complete observation │
│ ◀─────────────────────────────────────╯
│ │
├─ clear after Location move ─────▶
``` ```
Ambient project discovery canonicalizes and contains traversal within the project root and honors `OPENCODE_DISABLE_PROJECT_CONFIG`. An unavailable observation preserves the previously admitted value. A confirmed partial instruction removal emits the complete remaining aggregate with explicit supersession text; removing the final instruction emits a revocation message. Ambient project discovery canonicalizes and contains traversal within the project root and honors `OPENCODE_DISABLE_PROJECT_CONFIG`. An unavailable observation preserves the previously admitted value. A confirmed partial instruction removal emits the complete remaining aggregate with explicit supersession text; removing the final instruction emits a revocation message.