@llblab/pi-kit 0.18.2 → 0.19.0

package/node_modules/@llblab/pi-state-flow/docs/compatibility.md

@@ -1,17 +1,18 @@
 # Pi SDK compatibility
 
-State Flow requires matching Pi SDK packages at `>=0.84.4` without an upper peer-dependency bound. Keep `pi-coding-agent`, `pi-agent-core`, `pi-ai`, and `pi-tui` on the same release line.
+State Flow requires matching Pi SDK packages at `>=0.87.0` without an upper peer-dependency bound. Keep `pi-coding-agent`, `pi-agent-core`, `pi-ai`, and `pi-tui` on the same release line.
 
 The peer range permits newer releases so npm does not impose an artificial ceiling. It does not claim that every future SDK release has been tested. Revalidate the public host seams below when adopting a new Pi release line.
 
 ## Tested stacks
 
-The current repository-local stack uses Linux/x64, Node 26.8.1, Git 2.55.0, and Pi SDK 0.84.4.
+The current repository-local stack uses Linux/x64, Node 26.8.1, Git 2.55.0, and Pi SDK 0.87.0.
 
 | Pi SDK stack | Validation | Evidence status |
 | --- | --- | --- |
-| 0.84.4 | Build, typecheck, import, package dry-run, 445/445 tests | Current full-suite baseline |
-| 0.85.1 | Build, typecheck, import, full suite | Earlier compatibility baseline; not rerun for every later State Flow change |
+| 0.87.0 | Build, typecheck, import, package dry-run, 438/438 tests | Current full-suite baseline |
+| 0.84.4 | Historical full-suite baseline | Unsupported by State Flow 0.17.0 |
+| 0.85.1 | Historical full-suite baseline | Unsupported by State Flow 0.17.0 |
 
 Only exact matching stacks that were actually exercised are test evidence. Mixed SDK versions and untested newer releases are permitted by package metadata but remain unverified.
 
@@ -21,14 +22,29 @@ State Flow depends on these public Pi SDK behaviors:
 
 - Extension lifecycle events and branch metadata for start, stop, reload, resume, fork, and tree navigation.
 - Read-only session parent traversal through `getLeafEntry()` and `getEntry(id)`.
-- `message_end` and `turn_end` ordering before accepted assistant messages are reconciled.
-- Context transformation through the extension runner.
+- `message_end`, actionable `turn_end`, `agent_before_settle`, and `agent_settled` ordering around accepted assistant messages.
+- Canonical session context, `ContextEditEntry`, ordinary context transformation, and `context_with_system` extension boundaries.
 - `getContextUsage()` and native compaction hooks.
 - Sequential tool execution and tool-call preflight.
 - Session replacement awaiting outgoing shutdown before invalidation.
 
 Compatibility with those seams does not prove every UI mode, provider, operating system, extension combination, or future SDK release.
 
+## Pi 0.87.0 feature applicability
+
+This inventory follows the [tagged release](https://github.com/earendil-works/pi/releases/tag/v0.87.0), its linked [extension contract](https://github.com/earendil-works/pi/blob/v0.87.0/packages/coding-agent/docs/extensions.md), [session format](https://github.com/earendil-works/pi/blob/v0.87.0/packages/coding-agent/docs/session-format.md) and [image limits](https://github.com/earendil-works/pi/blob/v0.87.0/packages/coding-agent/docs/models.md#image-input-limits). It separates extension-owned behavior from inherited SDK behavior. The scoped 0.87 applicability pass is complete for the pinned scripted SDK stack; this is not a release, live-provider or cross-platform readiness claim. Open implementation work belongs to [BACKLOG.md](../BACKLOG.md).
+
+- **Actionable `turn_end` / `agent_before_settle` — adapted and native-tested.** A companion can append context-bearing drafts and request continuation without another `before_agent_start`. State Flow now projects accepted memory on every enabled request even after completion removed `specification`; it neither resurrects that prompt nor creates a second continuation owner. The native boundary-continuation pair checks actual event fields, accepted state/response before and after another patch, model-visible tool declarations, retained runtime checkpoints, one user-run preparation and the exact provider-call count.
+- **Canonical `SessionManager` and `ContextEditEntry` — native-tested without an extra projection owner.** Native user replacement, assistant/custom-message omission and tool-result replacement inside the tool loop reach the provider correctly. Tree selection applies only branch-relative edits; fixture reload preserves the edited projection. Raw trace bytes remain intact and selecting a pre-runtime branch does not overwrite accepted semantic files. State Flow neither assigns `agent.state.messages` as history authority nor reconstructs omitted raw entries; trajectory edits do not authorize rewriting separately owned semantic memory. Pi retains ownership of string-replacement normalization, protection of unseen boundary input and edited-usage freshness; no alternative transcript or accounting implementation is added.
+- **Conversation `context` versus full `context_with_system` — adapted and native-tested.** State Flow supplies protocol via `before_agent_start.systemPromptOptions.sections.state_flow`, no longer forcing the entire prompt. Companion before-run sections and full-system additions now survive active/passive requests and tools; conversation hooks exclude systems while full-system hooks include them. Tests inspect model-visible declarations and read evidence, not just scripted execution. Explicit foreign forced prompts still override per-request system additions by Pi's contract. Native section diffs remove/reinstate State Flow's protocol on subsequent user requests after Stop/Start.
+- **Mid-tool protocol-mode refresh — adapted and native-tested.** The next request after mid-read Stop, passive Stop, mid-read Start or accepted-boundary Stop/continuation now receives current protocol without another user-run preparation. `context_with_system` projects only the owned section; it keeps source frames immutable, conversation identities/order, foreign sections/content/tools and explicit forced-prompt precedence. Unchanged effective protocol is a no-op, including native later system deltas. No missing system frame, lifecycle field, controller or State Flow persistence format is invented. Retained red-to-green tests supersede the earlier defect-only diagnostic.
+- **Deferred work from `agent_settled` — adapted and native-tested.** State Flow awaits its admitted native compaction's completion/error callback before returning from the settled handler. Fire-and-forget compaction previously overlapped Pi's deferred companion prompt dispatch and rejected that prompt. Native low-pressure, admitted-compaction and explicit-refusal cases now complete all settled observers before one follow-up starts, with correct memory/step and no lost or duplicate inference. Existing eligibility/leaf/generation/shutdown guards remain; backup stays at `agent_before_settle`. No new timer, queue or continuation owner is introduced.
+- **Retain-none compaction — deliberately unused for State Flow-owned shortening.** Canonical memory is not a lossless replacement for the original request, images, tools or foreign custom context. Owned compaction therefore retains the complete accepted run; ordinary native manual/threshold/overflow compaction stays Pi-owned. R12/R14 native witnesses cover normalized images, steering and split-turn Stop continuation without trace rewriting.
+- **Persisted retry/length/overflow omissions and edited-context accounting — inherited SDK behavior, now native-tested.** Retryable error, recoverable length and explicit overflow keep failed attempts raw while persisting omission edits; recovery and reload exclude them. Native split-turn recovery uses two summary requests within one compaction and one coding continuation. Failed attempts/summaries never advance State Flow response or semantic step. Separate accounting coverage replaces a large source message, observes reduced native usage without changing raw trace/memory, and rules out phantom recovery/compaction from stale provider counts. These are scripted SDK witnesses, not live-provider guarantees.
+- **Per-model image resize profiles — SDK-owned and native-tested.** Real wide/tall PNG payloads exercise `inputLimits.images.resize` on prompt images, built-in image reads and generic tool-result images. Native model selection changes bounds from 1800×1200 to 900×600: new payloads use the smaller profile while historical user/read/generic-tool payloads remain byte-identical through later provider inputs and fixture reload. Disabled and bootstrap-enabled State Flow controls pass, alongside normalized-image steering/compaction and actual prompt/tool declarations after owned compaction. No State Flow image pipeline is introduced. Pi 0.87 describes other hard image/request-limit fields as metadata; codec byte/quality settings and provider enforcement remain upstream-owned, not independently live-provider/cross-platform certified here.
+- **Removed `shouldStopAfterTurn` and changed runner/event shapes — no direct low-level migration required.** State Flow registers typed extension handlers rather than configuring an Agent termination option or calling `ExtensionRunner.emit("turn_end")`. Native SDK fixtures dispatch through Pi's `finishTurn`/`emitBoundary` implementation; the new companion tests exercise required boundary fields and draft persistence.
+- **Other release fixes — inherited or outside this extension's ownership.** GIF-prefixed text detection belongs to built-in `read`; provider strict-schema defaults, cache-warming timing and crash diagnostics belong to Pi. Offline `/bug` upload behavior and prompt-template frontmatter diagnostics do not require State Flow features. No duplicate image pipeline, HTTP adapter, diagnostics service or cache scheduler is introduced. This classification is not a live-provider or cross-platform verification claim.
+
 ## Validation procedure
 
 Validate another Pi SDK line in an isolated copy so the live extension, sessions, and runtime store remain unchanged:
@@ -44,3 +60,5 @@ npm run validate
 ```
 
 A successful focused test does not replace the full suite. Record the exact dependency graph and command exit for any compatibility claim.
+
+For compiled public-API checks, follow `package.json.exports["."].default` (`dist/index.js`). Pi loads the separate `pi.extensions` entry (`dist/pi-state-flow/index.js`), a default-only registration shim: importing it proves extension loadability, not the presence or absence of named library exports. Check both surfaces and compare packaged Skills with their source. Documentation-only changes may reuse source-bound build/test/benchmark evidence when its actual inputs remain identical; refresh the package inventory after the final documentation edits.

package/node_modules/@llblab/pi-state-flow/docs/filesystem-recovery.md

@@ -6,31 +6,28 @@ State Flow classifies absence separately from partial or malformed evidence. Rec
 | --- | --- | --- | --- | --- |
 | Global `checkpoint.json` + `patches.jsonl` | State Flow; authoritative shared semantics | Untouched publication adopts a fresh empty scope; a targeted patch conflicts | Either half missing, malformed replay, or invalid envelope fails closed | Normal CAS publication may materialize the complete empty pair |
 | CWD `checkpoint.json` + `patches.jsonl` | State Flow; authoritative shared semantics with CWD identity | Same as global; selected values are not resurrected | Same as global; owner mismatch also fails closed | Normal CAS publication may materialize the complete empty pair |
-| Session `checkpoint.json` + `patches.jsonl` | State Flow; authoritative private semantics | Fresh lifecycle origin may initialize; an existing selected session requires exact retained authority | Partial or malformed pair fails closed | Fresh initialization or exact selected-revision recovery only |
+| Session `checkpoint.json` + `patches.jsonl` | State Flow; authoritative private semantics | Fresh lifecycle origin may initialize; an existing selected session requires exact retained authority | Partial or malformed pair fails closed | Fresh initialization or exact retained-boundary recovery only |
 | Global/CWD `meta.json` | State Flow; temporal boundaries, CWD identity, and artifact provenance | Missing metadata removes temporal authority and fails closed; only an omitted `artifacts` leaf degrades provenance to `{}` | Malformed metadata or semantic/boundary mismatch fails closed | Normal CAS publication from a complete proven cohort |
 | Session `meta.json` | State Flow; session temporal boundaries and artifact provenance | Fresh origin may initialize; selected sessions recover only from exact scope authority | Partial, malformed, or contradictory boundary evidence fails closed | Canonical scope publication from the selected temporal state |
-| Session `config.json` + `runtime.json` | State Flow; behavior plus authoritative runtime identity, lineage, counters, and publication recovery | Fresh origin may initialize; selected sessions recover only from exact authority | Partial, malformed, contradictory identity, lineage, or revision fails closed | Canonical runtime publication from proven lifecycle/selected state; predecessor combined `meta.json` is migration input only |
-| Unsupported `state.json`, hashed layouts, or semantic Pi checkpoints | No current authority | Ignored | Presence never becomes recovery or migration input | Operator-managed removal or external conversion only |
-| Selected Git revision blobs/modes | Git object database; immutable cold authority | A required blob/revision is unavailable | Mode, owner, hash, or cohort contradiction fails closed | Read-only reconstruction; never checkout/reset the live worktree |
-| File-only revision pointer/cohort | State Flow/Pi entry; current exact authority only | No cold history can be invented | Any identity mismatch or incomplete retained cohort fails closed | Exact current cohort only; normal locked publication writes repairs |
-| Publication queue | State Flow; operational effect intent | Empty queue / no pending publication | Malformed or contradictory bytes are preserved and publication fails locally | CAS save/remove and atomic temporary rename only |
-| Worker lease | State Flow; operational ownership | Unclaimed | Malformed/foreign live evidence is preserved; live owner excludes peers | Existing dead-process reclamation protocol only |
-| Publication locks | State Flow; mutual exclusion | Unlocked | Present lock excludes publishers, including interrupted owners | Current owner releases; no opportunistic deletion |
-| Temporary queue files / isolated Git index | Creating State Flow operation; transient | No pending preparation | Unknown surviving files grant no authority | Creating operation cleans its own temporary path; fatal residue is not adopted |
-| Repository-root `config.json` | Operator; optional global configuration, versioned with the store | Built-in defaults | Present unreadable/malformed/unknown settings fail extension configuration | State Flow never creates or rewrites it; ordinary repository publication preserves and versions operator edits |
-| Knowledge root and Markdown | External Knowledge owner | Freshness unavailable; durable semantic state remains | Unsafe paths or malformed/unreadable sources disable acquisition locally | Never create; semantic removal only under existing confirmed ownership rules |
+| Session `config.json` + `runtime.json` | State Flow; behavior plus authoritative runtime identity, lineage, and counters | Fresh origin may initialize; selected sessions recover only from exact authority | Partial, malformed, contradictory identity or lineage fails closed | Canonical runtime publication from proven lifecycle/selected state; combined predecessor metadata is unsupported |
+| Unsupported predecessor envelopes, `state.json`, hashed layouts, or semantic Pi checkpoints | No current authority | Ignored | Presence never becomes recovery or conversion input | Preserve bytes; operator-managed removal or external conversion only |
+| Retained Pi boundary | State Flow/Pi entry; current canonical lineage | Expired or missing boundary is unavailable | Identity, lifecycle, or lineage contradiction fails closed | Select exact retained private history over live shared scopes; never consult Git |
+| Canonical writer lock | State Flow; file-cohort mutual exclusion | Unlocked | Present lock excludes cooperating publishers, including interrupted owners | Current owner releases; no opportunistic deletion |
+| Repository-root `config.json` | Operator; optional read-only global configuration | Built-in defaults | Present unreadable/malformed/unknown settings fail extension configuration | State Flow never creates, rewrites, or stages operator edits; include it in operator-managed copies/versioning |
+| Registered artifact source path | External source owner | Exact proven absence permits owning-scope artifact/provenance removal | Relative, symlink, directory, malformed, or unreadable paths disable maintenance locally | Never create; semantic removal only for exact proven absence |
 | Skill and external artifact sources | External package/user owner | Freshness unavailable unless ownership proves removal semantics | Unsafe/non-regular/unreadable sources disable acquisition locally | Never create or fabricate source/provenance |
-| Pi State Flow entries and diagnostics | Pi session log / State Flow entry owner | Missing optional diagnostics provide no evidence; missing required selected pointer blocks that restore | Malformed or contradictory owner/version/pointer fails the dependent restore | Append through Pi entry APIs only; no standalone diagnostics file exists |
+| Pi State Flow entries | Pi session log / State Flow entry owner | Missing required selected boundary blocks that restore | Malformed or contradictory owner/version/boundary fails the dependent restore | Append through Pi entry APIs only; never replace failed selection with passive state |
+| Optional diagnostic log | State Flow logger; outside the canonical repository | No diagnostic evidence | I/O failure warns once without changing accepted state | Append local JSONL only when opted in; never use it as semantic recovery authority |
 
 ## Transaction rule
 
 Every semantic repair follows the ordinary transaction path:
 
-1. Capture the live Git or file basis under the existing publication lock.
+1. Capture the live canonical-file basis under the existing publication lock.
 2. Classify each cohort as present, absent, partial, or malformed.
 3. Derive only an authorized replacement.
 4. Stage the complete canonical cohort.
 5. Recheck CAS and ownership.
-6. Atomically publish and install the resulting runtime state.
+6. Publish with per-file atomic replacement, conflict-preserving rollback, and then install the accepted runtime state; this is not kernel-atomic multi-file CAS.
 
-A current wholly absent shared scope is newer live reality for an untouched transition dependency. Its replacement begins empty at a fresh reconciliation origin. If the accepted transition targets that missing scope, publication refuses the stale target and requires a later inference against the refreshed basis. Cold Git history remains inspectable but is never silently promoted back into current shared memory.
+A current wholly absent shared scope is newer live reality for an untouched transition dependency. Its replacement begins empty at a fresh reconciliation origin. If the accepted transition targets that missing scope, publication refuses the stale target and requires a later inference against the refreshed basis. Discarded history is unavailable and is never reconstructed or promoted back into current shared memory.

package/node_modules/@llblab/pi-state-flow/docs/fork-contract.md

@@ -1,47 +1,42 @@
-# Physical fork: session-stream copy
+# Physical fork: retained session-stream copy
 
-Status: **locally implemented and validated; not released**. [Usage](usage.md#fork-support-and-limits) owns operation and recovery; [BACKLOG.md](../BACKLOG.md) owns the remaining 0.10.0 work.
+Status: **locally implemented and validated; not released**. [Usage](usage.md#fork-support-and-limits) owns operation and recovery; [BACKLOG.md](../BACKLOG.md) owns release tracking.
 
 ## Contract
 
-A physical Pi fork creates a new session with a separate copy of the source's session memory. Global and CWD memory remain the existing shared layers, not historical copies for the child.
+A physical Pi fork creates a fresh child session from a retained boundary in its direct parent's canonical session lineage:
 
 ```text
-B.global  = existing shared global
-B.cwd     = existing shared CWD
-B.session = copy of source session checkpoint + retained patch tail
+child.global  = current live global
+child.cwd     = current live CWD
+child.session = parent session selected at retained boundary
 ```
 
-- Resolve the source session stream at the native fork boundary. An earlier selection does not copy the parent's later live private state.
-- Copy the session checkpoint, retained tail of up to seven patches and matching session artifact provenance. Preserve replay records and transition identities rather than flattening them into a new materialized-only snapshot.
-- Adopt current proven live global/CWD streams and provenance without rewriting or pruning them. They need not equal the selected source revision's older shared layers.
-- Give B its own UUID, native session key, config/meta and durable checkpoint. Retain selected enablement/publication policy and any pending bootstrap requirement, but start at step zero without the parent's run specification, validation feedback, publication acknowledgement or process ownership.
-- Preserve A's private files, native trace and accepted history. Subsequent B session writes do not modify A's session layer.
-- Forking conversation/memory does not clone or roll back project files or tool effects.
+The adapter reads Pi's persisted direct-parent header, requires matching CWD and session identity, and selects the boundary only if it remains in the parent's retained canonical lineage. It never consults Git, a storage receipt, an older checkpoint entry, or the parent's newer private state.
 
-This is session inheritance, not an exact historical snapshot of the whole effective state. It adds no historical shared-owner reference or semantic mode.
+The child receives:
 
-## History and lifecycle
+- its own UUID, native session key, runtime metadata, and fresh lineage origin;
+- the selected parent session materialization and matching artifact provenance;
+- current live global/CWD values and provenance without rewinding them;
+- selected enablement and bootstrap lifecycle state, with step reset to zero and no inherited unfinished specification or validation diagnostic.
 
-`TemporalRuntime.prepareFork()` validates the source before any installation and returns a detached inspection snapshot plus a single-use copy operation. Git source inspection is immutable; file-only input is revalidated against its exact complete cohort. Installation captures a fresh live basis, uses existing stream adoption at a new origin, and publishes only the new session cohort under the existing CAS/exclusion rules. An occupied live or current-HEAD namespace is not a fresh target. Forking does not initialize missing shared storage or run migrations.
+The parent's private files and native trace remain unchanged. Later child session writes cannot modify the parent's private layer. Applying a smaller configured `historyLimit` may fold excess shared tails during child acceptance under file-cohort CAS, without changing current shared materialization or provenance. Without retention reduction, the shared files remain unchanged too. Forking semantic memory does not clone or roll back project files or tool effects.
 
-The checkpoint/tail copy retains replay data, but its length is not B's available hot-history depth. B begins at a new origin with `state[0]`; subsequent accepted transitions build its aligned `state[0..7]` window. Pre-origin records are not newly fabricated child transitions or indexes into independent local-scope clocks.
+Artifact provenance is current-only, not a historical registry. Any retained parent session patch touching an artifact after the selected boundary makes its current provenance unproven for that selection, even if a later patch restores an equal value. The child keeps the selected artifact semantics but omits that provenance until explicit reacquisition and compilation. Untouched artifact paths retain their evidence, including provenance-only refreshes of unchanged semantics; shared provenance remains live.
 
-B's own Git-backed runtime history begins with its first child-owned cohort. A's earlier Git history remains intact under A. Copied Pi checkpoint entries do not become B-owned historical references: selecting one cannot fall through to an older disabled marker and reset B. Select an owned child checkpoint or resume the parent instead.
+## Lifecycle and failure
 
-The adapter handles native `session_start` with reason `fork`, verifies a regular canonical parent header and matching CWD, then records the child checkpoint. A child-owned passive-projection reset prevents copied parent Stop markers from resurfacing after child reload/resume. Disabled sources remain disabled; ordinary activation policy is not overridden.
+`TemporalRuntime.prepareBoundaryFork()` prepares a detached, single-use copy from current canonical files. Acceptance publishes the fresh child origin before any runtime-only lifecycle write. Existing child storage, identity mismatch, missing parent files, malformed storage, concurrency conflict, or an expired boundary fails closed.
+
+A failed or expired selection never substitutes the parent's current/newer private state and never falls through to an older disabled marker. Explicit Start may retry the same unaccepted fork after missing identity or storage evidence is corrected. Child-owned checkpoints subsequently use ordinary retained-boundary reload/resume without rereading the parent header.
+
+A child-owned passive-projection reset prevents copied parent Stop markers from resurfacing after child reload. Disabled sources remain disabled; ordinary activation policy is not overridden. Nested forks require each direct parent boundary to remain retained; ancestry is not recursively reconstructed.
 
 ## Support boundary
 
-- Initial native copying requires a persisted direct-parent locator and a readable temporal source. The parent filename/key, header UUID and selected runtime identity must agree; no arbitrary session search or UUID aliasing occurs.
-- Source or publication failure leaves the selected reference intact. Explicit Start can retry an unaccepted copy in that same loaded fork instance after evidence or contention is corrected.
-- Cold recovery before the first child checkpoint, startup/CLI paths that do not emit the native fork reason, in-memory parent locators and arbitrary cross-CWD imports are not added by this slice. Existing child-owned checkpoints use normal reload/resume without rereading the parent header.
-- Nested copying works only where the selected pointer is owned by the direct parent; inherited pointers to earlier ancestors are not recursively resolved.
-- The file backend copies only an available exact current cohort. Expired file references do not authorize copying newer parent data. Legacy Git storage requires its existing explicit migration path rather than migration during fork.
-- Uncommitted shared streams, collisions and concurrent modifications retain the existing publication guards; failure does not authorize broadening the fork's writes.
+Supported copying requires a persisted regular parent session file, matching header UUID/CWD, current canonical scope/runtime files, and an available retained boundary. Arbitrary session search, UUID aliases, cross-CWD imports, in-memory-only parent locators, predecessor conversion, unlimited history, and Git recovery are unsupported.
 
 ## Evidence
 
-Both supported [SDK stacks](compatibility.md) pass the full suite. Native Git-backed witnesses cover selected private state versus newer parent/shared state, independent child mutation, owned reload/resume, disabled sources, Stop projection fencing, malformed parent identity/CWD and retry, inherited-pointer reset refusal, plus active-push replacement ownership.
-
-`tests/runtime.test.ts` covers an exact seven-record session copy with provenance, unchanged live shared files including unreferenced provenance, detached/single-use preparation, occupied live/HEAD targets, CAS races and file-only source expiration. `tests/continuation.test.ts` checks header-only reading and refusal of non-regular/symlink locators. These are synthetic fixtures, not production-session or arbitrary-host validation.
+Native integration tests cover retained private selection versus newer parent/shared state, fresh child origin, independent child mutation, child reload/resume, disabled sources, Stop projection fencing, malformed parent identity/CWD, retry, and expired-boundary refusal. Runtime tests cover single-use preparation, canonical child publication, live shared ownership, artifact provenance, occupied child storage, and retention reduction/increase without parent-private mutation or reconstructed history. Continuation tests cover header-only reading and refusal of non-regular or symlinked locators.

package/node_modules/@llblab/pi-state-flow/docs/lazy-state.md

@@ -1,10 +1,10 @@
 # Lazy state through progressive `read_state`
 
-**Status**: Implemented architecture for the next minor release. Final release validation and publication remain open.
+This document describes the implemented lazy-state contract. [BACKLOG.md](../BACKLOG.md) owns release readiness; [temporal acceptance](temporal-acceptance.md) maps behavior to executable evidence.
 
 ## Thesis
 
-State Flow should add `lazy` as a fifth semantic plane in every scope. Lazy values are ordinary JSON: durable and versioned with the same causal lineage as hot state, but excluded from ordinary baseline hydration.
+State Flow provides `lazy` as a required object-root semantic plane in every scope. Nested lazy values are ordinary JSON: durable and versioned with the same causal lineage as hot state, but excluded from ordinary baseline hydration.
 
 The model-facing surface remains small:
 
@@ -34,19 +34,19 @@ The model-facing surface remains small:
 
 ## Semantic model
 
-Each scope may contain six semantic planes:
+Each scope contains six semantic planes in intent-first presentation order:
 
 ```text
 global | CWD | session
-├── artifacts
+├── intents
 ├── contract
 ├── working
-├── intents
+├── artifacts
 ├── response (session-owned where applicable)
 └── lazy
 ```
 
-`artifacts`, `contract`, `working`, `intents`, and `response` remain hot. `intents` may keep compact active direction while referring to large supporting detail in `lazy`. `lazy` differs only in projection policy:
+`intents`, `contract`, `working`, `artifacts`, and `response` remain hot. `intents` may keep compact active direction while referring to large supporting detail in `lazy`. `lazy` differs only in projection policy:
 
 - It is canonical semantic JSON, validated and versioned with its owning scope.
 - It is excluded from the ordinary baseline effective-state body.
@@ -61,7 +61,7 @@ State Flow preserves all forms exactly as ordinary JSON. It does not scan prose,
 
 Reference repair is reactive, not a maintenance scan. The agent does not enumerate, audit, or resolve references merely to test them. Only after one requested `read_state` value path is missing does State Flow perform one bounded reverse lookup over current model-patchable semantic planes for exact structured `$ref` and `$path` matches. If found, the tool returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. `hint` is explicit top-level metadata rather than state data; its action message asks for reconciliation and its path array contains at most three runtime-verified current owners. The null sentinel is never returned alone for this case. Keys, patch, and multi-path reads keep ordinary all-or-error semantics; no durable match retains the missing-path error and does not prove the agent invented the path. The agent may then reconcile a proven stale owning value while preserving surrounding meaning. This applies equally to `$ref` objects and contextual references in prose. Effective-state absence alone does not identify the owner, and unavailable history, inaccessible external resources, or transient read failure do not prove that a durable reference is broken.
 
-Valid lazy values include:
+The `lazy` root must be an object. Its nested values may include arrays, objects, and scalars, for example:
 
 ```json
 ["important thought", "next thought"]
@@ -136,7 +136,7 @@ Errors use the normal tool-error channel rather than successful JSON containing
 
 ### Path and range model
 
-Every path has an explicit root and addresses:
+Unscoped semantic paths alias current effective state. Explicit roots and selectors address:
 
 - `effective` for the current composed overlay or an indexed historical effective root.
 - `global`, `cwd`, and `session` for explicit current or historical scopes.
@@ -156,11 +156,11 @@ cwd.lazy.memory[10:20]
 session[3].lazy.investigation
 ```
 
-Indices are zero-based. Negative indices, open-ended ranges, steps, predicates, wildcards, unions, and cross-array expressions are rejected in the first version.
+Indices are zero-based. Negative indices, open-ended ranges, steps, predicates, wildcards, unions, and cross-array expressions are rejected.
 
 A range must fit entirely within the current array. If an array has length 10, `[0:10]` and `[10:10]` are valid, while `[0:15]` and `[11:11]` fail. The fallback `..` spelling has identical semantics. A successful result always contains exactly the requested range. State Flow never returns a shorter successful range with truncation metadata.
 
-The implementation must reuse or compatibly extend existing member escaping rather than inventing a second object-path language.
+All projections use the same strict member grammar; no separate lazy path language exists.
 
 ## Projections
 
@@ -396,8 +396,7 @@ Array index selectors extend recursive addressing:
         "[4]": "corrected fifth thought"
       }
     }
-  },
-  "final": true
+  }
 }
 ```
 
@@ -425,8 +424,7 @@ Nested addressing remains ordinary patch structure:
         }
       }
     }
-  },
-  "final": true
+  }
 }
 ```
 
@@ -440,24 +438,23 @@ Lazy mutations inherit existing guarantees:
 - One lock/CAS publication cohort.
 - Atomic hot-plus-lazy multi-scope changes.
 - Scope-local deletion and effective revelation semantics.
-- Exact revision selection on restore and branch navigation.
+- Exact retained-boundary selection on restore and branch navigation.
 - Read-only discovery with no commit, timestamp update, or transition.
 
-The first implementation keeps lazy trees co-located in the existing scope semantic files. A local Git-backed probe with incompressible 1 KiB, 100 KiB, and 1 MiB lazy payloads observed 0.33–0.42 s publication, 0.24–0.30 s cold restoration, and approximately linear loose-store growth; the 1 MiB case occupied about 2.2 MiB including the worktree and loose Git history. This does not justify sharding before real workload evidence. A future path-sharded or content-addressed optimization must expose one logical State Flow revision, preserve symlink and ownership safety, and keep normalized semantic JSON authoritative while indexes and caches remain rebuildable projections.
+Lazy trees are co-located in canonical scope checkpoints/tails and use the same bounded lineage as hot state. Git-era publication and cold-restoration measurements do not describe this implementation. The [performance guide](performance.md) owns current synthetic workloads and measurement limits. No separate lazy index or sharded authority exists; any future layout change requires measured need and must preserve canonical semantics, ownership, and one causal lineage.
 
 ## Failure semantics
 
 - A nonexistent path, wrong target kind, malformed selector, or out-of-bounds index/range is a tool error.
 - One invalid member of a path batch fails the entire read before returning partial success.
 - One invalid indexed patch fails the entire mutation before publication.
-- A malformed lazy subtree fails closed at the smallest affected path and reports that path.
-- Missing or corrupt optional indexes cannot make canonical lazy JSON disappear.
-- Read failures create no semantic transition and do not affect ordinary hot state.
-- Mechanical index rebuilds create no semantic transition.
+- Malformed canonical lazy data fails the dependent scope/runtime load without rewriting retained bytes; it is not silently discarded to manufacture valid hot state.
+- Invalid reads and rejected patches create no semantic transition and preserve accepted hot state.
+- Independent scopes remain usable only where the ordinary filesystem/recovery contract proves their authority.
 
 ## Normative invariants
 
-1. **Ordinary JSON**: Lazy values contain domain semantics, never mandatory State Flow record wrappers.
+1. **Object root, ordinary JSON children**: Every scope has a lazy object whose nested values contain domain semantics, never mandatory State Flow record wrappers.
 2. **Semantic snapshots**: `value` contains only the selected state snapshot and `patch` only the selected semantic patch; `keys` alone adds closed structural `meta` before `keys`.
 3. **Exact success**: A successful read returns everything requested; it never truncates or paginates silently.
 4. **Runtime-owned concurrency**: Revisions, locks, and CAS remain internal unless explicitly needed for diagnostics.
@@ -468,7 +465,7 @@ The first implementation keeps lazy trees co-located in the existing scope seman
 9. **Explicit frontier crossing**: Only a visible hot-state patch promotes a lazy consequence.
 10. **Patch remains patch**: Array indices extend recursive addressing without introducing an edit-command language.
 11. **Index safety**: Array indices are interpreted only against one captured basis under lock/CAS.
-12. **Failure isolation**: Lazy corruption or unavailable indexes do not damage valid hot state.
+12. **Failure preservation**: Invalid reads or patches preserve accepted bytes; canonical corruption fails closed rather than granting partial authority.
 
 ## Validation contract
 
@@ -487,27 +484,14 @@ Before release, implementation evidence must prove:
 - `effective.lazy` follows global → CWD → session overlay while explicit scope paths preserve ownership.
 - Reads create no semantic transition, Git commit, publication, freshness update, or future activation.
 - Whole-array replacement and indexed scalar, array, object, nested, multi-index, and stale-basis patches remain atomic.
-- Restore, fork, file-only, and Git-backed paths select lazy state from the same owning State Flow revision.
-- Corrupt lazy data or optional indexes do not damage ordinary hot State Flow.
-- Legacy stores and legacy `read_state` inputs either migrate deterministically or fail actionably.
-
-## Remaining evolution decisions
-
-- Exact member escaping beyond the current strict grammar for names containing separators or brackets.
-- A measured real-workload threshold that would justify replacing the initial co-located semantic layout.
-- Cold Git-history access beyond retained hot history.
+- Restore and fork select lazy state from the same retained canonical boundary as the rest of the owning session scope.
+- Malformed canonical lazy data fails closed without rewriting the store; rejected queries and patches preserve accepted hot state.
+- Unsupported predecessor stores and retired `read_state` inputs fail actionably without rewriting retained bytes.
 
-These decisions cannot introduce mandatory record objects, default metadata envelopes, pagination, typed queries, search, ranking, or a second mutation language without a new design decision.
+## Limits and change authority
 
-## Next minor release sequence
+Retained hot history is the entire semantic history available to these readers; cold Git-history access is unsupported. Names must fit the shared path grammar. Generalized querying, sharding, mandatory record objects, metadata envelopes, pagination, and a second mutation language are not implied future work and require a separate evidence-backed design decision.
 
-1. Extend the existing path parser with canonical escaping, ordered batches, strict indices, and half-open ranges.
-2. Implement semantic-snapshot `value`, structural `meta` + `keys`, and semantic `patch` reads over current hot state first.
-3. Add indexed recursive array patching through the existing lock/CAS barrier.
-4. Add `lazy` to scope validation, persistence, history, restore, and explicit scoped reads.
-5. Add the read-only `effective.lazy` overlay and bounded baseline navigation hint.
-6. Add migration, corruption, stale-basis, restore, fork, file-only, Git-backed, and concurrency coverage.
-7. Measure repository growth, publication latency, restoration latency, and package/store size before selecting any sharded layout.
-8. Update runtime protocol and user documentation, run full validation, and release through the repository's guarded minor-release flow.
+The [canonical backlog](../BACKLOG.md) owns remaining implementation and release gates. This contract is not a parallel delivery plan.
 
 The stopping rule is conceptual economy: ordinary JSON, one effective lazy overlay, pure state and patch snapshots, one narrow structural `meta` + `keys` projection, recursive patches with indexed array addressing, and one mutation/publication barrier.