@llblab/pi-state-flow 0.16.2 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/AGENTS.md +35 -37
  2. package/BACKLOG.md +5 -3
  3. package/CHANGELOG.md +15 -1
  4. package/README.md +11 -11
  5. package/dist/index.d.ts +6 -9
  6. package/dist/index.js +6 -9
  7. package/dist/lib/acquisition.d.ts +2 -2
  8. package/dist/lib/acquisition.js +21 -8
  9. package/dist/lib/artifact.d.ts +40 -24
  10. package/dist/lib/artifact.js +93 -63
  11. package/dist/lib/compaction.d.ts +4 -3
  12. package/dist/lib/compaction.js +9 -9
  13. package/dist/lib/config.d.ts +1 -1
  14. package/dist/lib/config.js +6 -5
  15. package/dist/lib/context.d.ts +8 -7
  16. package/dist/lib/context.js +56 -58
  17. package/dist/lib/continuation.js +12 -24
  18. package/dist/lib/durable.d.ts +7 -18
  19. package/dist/lib/durable.js +47 -78
  20. package/dist/lib/extension.d.ts +4 -6
  21. package/dist/lib/extension.js +241 -437
  22. package/dist/lib/git.d.ts +2 -72
  23. package/dist/lib/git.js +120 -499
  24. package/dist/lib/history.d.ts +2 -1
  25. package/dist/lib/history.js +4 -3
  26. package/dist/lib/json.d.ts +3 -0
  27. package/dist/lib/json.js +43 -22
  28. package/dist/lib/logging.d.ts +1 -5
  29. package/dist/lib/logging.js +0 -2
  30. package/dist/lib/memory.d.ts +1 -14
  31. package/dist/lib/memory.js +5 -37
  32. package/dist/lib/protocol.d.ts +2 -3
  33. package/dist/lib/protocol.js +14 -33
  34. package/dist/lib/query.d.ts +6 -6
  35. package/dist/lib/query.js +25 -21
  36. package/dist/lib/recovery.d.ts +3 -3
  37. package/dist/lib/recovery.js +15 -12
  38. package/dist/lib/rehydration.d.ts +2 -4
  39. package/dist/lib/rehydration.js +5 -1
  40. package/dist/lib/runtime.d.ts +26 -88
  41. package/dist/lib/runtime.js +159 -255
  42. package/dist/lib/skills.d.ts +0 -3
  43. package/dist/lib/skills.js +1 -47
  44. package/dist/lib/snapshot.d.ts +16 -33
  45. package/dist/lib/snapshot.js +48 -137
  46. package/dist/lib/state.d.ts +16 -11
  47. package/dist/lib/state.js +13 -14
  48. package/dist/lib/status.d.ts +1 -9
  49. package/dist/lib/status.js +15 -43
  50. package/dist/lib/storage.d.ts +5 -9
  51. package/dist/lib/storage.js +13 -45
  52. package/dist/lib/telegram.js +1 -1
  53. package/dist/lib/temporal.d.ts +15 -7
  54. package/dist/lib/temporal.js +104 -24
  55. package/dist/lib/transition.d.ts +0 -2
  56. package/dist/lib/transition.js +9 -12
  57. package/dist/package.json +9 -6
  58. package/dist/skills/state-flow-guide/SKILL.md +11 -17
  59. package/dist/skills/state-flow-memory/SKILL.md +8 -8
  60. package/docs/README.md +2 -2
  61. package/docs/architecture.md +64 -67
  62. package/docs/compatibility.md +41 -78
  63. package/docs/filesystem-recovery.md +12 -15
  64. package/docs/fork-contract.md +22 -27
  65. package/docs/lazy-state.md +25 -41
  66. package/docs/performance.md +38 -421
  67. package/docs/temporal-acceptance.md +33 -46
  68. package/docs/usage.md +38 -62
  69. package/index.ts +7 -71
  70. package/lib/acquisition.ts +26 -11
  71. package/lib/artifact.ts +116 -88
  72. package/lib/compaction.ts +12 -10
  73. package/lib/config.ts +6 -6
  74. package/lib/context.ts +52 -59
  75. package/lib/continuation.ts +11 -20
  76. package/lib/durable.ts +44 -86
  77. package/lib/extension.ts +237 -460
  78. package/lib/git.ts +110 -552
  79. package/lib/history.ts +4 -3
  80. package/lib/json.ts +39 -23
  81. package/lib/logging.ts +1 -7
  82. package/lib/memory.ts +5 -44
  83. package/lib/protocol.ts +15 -26
  84. package/lib/query.ts +26 -22
  85. package/lib/recovery.ts +17 -11
  86. package/lib/rehydration.ts +7 -5
  87. package/lib/runtime.ts +154 -254
  88. package/lib/skills.ts +1 -49
  89. package/lib/snapshot.ts +58 -142
  90. package/lib/state.ts +27 -19
  91. package/lib/status.ts +16 -54
  92. package/lib/storage.ts +12 -40
  93. package/lib/telegram.ts +1 -1
  94. package/lib/temporal.ts +104 -22
  95. package/lib/transition.ts +14 -24
  96. package/package.json +9 -6
  97. package/skills/state-flow-guide/SKILL.md +11 -17
  98. package/skills/state-flow-memory/SKILL.md +8 -8
  99. package/dist/lib/discovery.d.ts +0 -21
  100. package/dist/lib/discovery.js +0 -125
  101. package/dist/lib/maintenance.d.ts +0 -36
  102. package/dist/lib/maintenance.js +0 -98
  103. package/dist/lib/migration.d.ts +0 -13
  104. package/dist/lib/migration.js +0 -167
  105. package/dist/lib/publication.d.ts +0 -86
  106. package/dist/lib/publication.js +0 -437
  107. package/lib/discovery.ts +0 -133
  108. package/lib/maintenance.ts +0 -147
  109. package/lib/migration.ts +0 -171
  110. package/lib/publication.ts +0 -458
@@ -1,101 +1,64 @@
1
1
  # Pi SDK compatibility
2
2
 
3
- This matrix records exact tested dependency stacks, not the version of an operator's running Pi process. Package peer ranges admit `^0.84.4 || ^0.85.1`; keep Pi, AI and agent-core on a matching release line. Mixed-version stacks and later releases are not separate test evidence.
3
+ 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.
4
4
 
5
- ## Current release candidate
5
+ 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.
6
6
 
7
- The 0.16.0 candidate passes `npm run validate` on the repository-local 0.84.4 dependency graph: build, typecheck, import check, package dry run, and 444/444 tests. Its focused context/Skill/invariant cohort passes 43/43, including discovery of the separate operational and memory-curation Skills and release-package inventory checks for both compiled Skill paths. Current and historical reads use semantic `path`/`paths`; the retired top-level `state` segment and legacy top-level `offset`/`scope` inputs are rejected. The 0.85.1 full-suite evidence below belongs to the earlier recorded source checkpoint and has not been repeated for this candidate.
7
+ ## Tested stacks
8
8
 
9
- ## Tested matrix
9
+ The current repository-local stack uses Linux/x64, Node 26.8.1, Git 2.55.0, and Pi SDK 0.87.0.
10
10
 
11
- The historical compatibility checks use Linux/x64, Node 26.8.1, Git 2.55.0, TypeScript 7.0.2 and Node types 26.4.0.
11
+ | Pi SDK stack | Validation | Evidence status |
12
+ | --- | --- | --- |
13
+ | 0.87.0 | Build, typecheck, import, package dry-run, 437/437 tests | Current full-suite baseline |
14
+ | 0.84.4 | Historical full-suite baseline | Unsupported by State Flow 0.17.0 |
15
+ | 0.85.1 | Historical full-suite baseline | Unsupported by State Flow 0.17.0 |
12
16
 
13
- | Pi / AI / agent-core | SDK's pi-tui / TypeBox | Typecheck / import | Full suite |
14
- | --- | --- | --- | --- |
15
- | 0.84.4 / 0.84.4 / 0.84.4 | 0.84.4 / 1.3.7 | Pass / pass | 417/417 |
16
- | 0.85.1 / 0.85.1 / 0.85.1 | 0.85.1 / 1.3.7 | Pass / pass | 417/417 |
17
-
18
- The first row is the repository-local stack. The second used a disposable copy of the same working source, with read-only dependency links to the already installed 0.85.1 SDK and its actual AI/agent-core/pi-tui graph. All commands exited zero for the accepted results. The repository lockfile still resolves 0.84.4; broadening its root peer metadata did not install or upgrade dependencies. No live Pi process, installation, production session or state store was modified.
19
-
20
- Both stacks passed `npm run validate` after adding the four [fatal-writer interruption witnesses](temporal-acceptance.md#fatal-writer-interruption). No runtime correction was needed: runtime SHA-256 remains `ce820cd33c34c4c882c11fc55e93f3914cfc8dffae57683e32cdcaa70f225cd2` from the [context-copy correction](performance.md#context-projection-and-trajectory-selection). Sorted `index.ts`, `lib/*.ts` and `tests/*.ts`, framed as path + NUL + bytes + NUL, now yield `1c5fafc1433631fed33177381e925eeeca52827932ba327690f615d2a4db81ba`. Copied/original source, runtime, test and package bytes were checked unchanged through validation, along with both selected dependency-resolution graphs and their manifests. These hashes do not cover every installed binary or environmental influence. The [benchmark workload fingerprint](performance.md) remains `b861fae36798bf76f56f411cc654c70fc948597bb84cc7a422c83f69ba1ca3e9`. Subsequent [matched runtime-performance controls](performance.md#matched-final-candidate-controls) use the 0.84.4 graph only, not a two-SDK timing comparison. The earlier fork/context witnesses remain included; these results do not replace separate integrated-candidate acceptance.
21
-
22
- ### Post-measurement integrated acceptance
23
-
24
- After the nine-invocation performance series, inline review traced accumulated Git/CAS, provenance, worker ownership, fork/recovery, Stop/context and discovery changes against their callers and negative/native witnesses, without a confirmed blocker in that inspected closure. Separate `state-flow-integrated-0844` and `state-flow-integrated-0851` Runs repeated `npm run validate`: each passed 417/417 with no failed, cancelled, skipped or todo tests, plus typecheck and import-check, and actual command exit zero. Full captures are 47,957 and 47,950 bytes. All 78 selected runtime/test/package files and both actual dependency graphs remained unchanged; documentation is separately reviewed rather than represented by that source hash.
25
-
26
- The twenty-property map resolves its quoted witnesses; that structural check is not exhaustive semantic proof. Domain validation reports 31 source files/133 acyclic local edges and no reverse entrypoint imports, with 25 existing header warnings. Context validation reports zero errors/five warnings. The package dry run includes 44 files and no tests. This accepts the local candidate within the documented synthetic/Linux/SDK boundaries, not arbitrary-host compatibility, production-incident attribution, publication permission or remote release-CI success. That checkpoint preceded the final compaction/status slice and its intentional 0.10.0 version alignment.
27
-
28
- The final slice adds seven compaction policy/race tests and two native lifecycle witnesses, bringing the complete repository-local 0.84.4 suite to 426/426 with typecheck/import-check. On 0.85.1, all affected policy/status and native compaction/tree tests plus typecheck pass; the operator declined a redundant second full-suite repetition after this focused equivalence evidence. Native completed-history compaction preserves full JSONL/tree/state/UUID while shortening active/resumed entries without another model summary; threshold compaction before the first patch remains Pi-owned. Package version is 0.10.0. Remote release CI remains authoritative for the tagged tree.
29
-
30
- Matching versions do not imply one physical dependency instance. Before/after resolution walks retain separate root and SDK-local 0.84.4 AI/agent-core copies and three TypeBox 1.3.7 locations in the repository installation. The first row describes that actual graph, not a deduplicated installation. The disposable 0.85.1 copy explicitly shares the SDK's AI/agent-core/pi-tui instances. Record canonical resolution edges as well as versions for comparisons; no dependency installation was changed to force a verifier assumption.
31
-
32
- The focused parent-traversal and barrier cohort passed 3/3 on each stack. The earlier 0.85.1 native cohort passed 10/10: large state/answers, selected-tree restoration, quit/reload push ownership, ordinary/bootstrap mid-tool Stop, compaction/tree/restart, scoped barriers, historical reads, and sibling-tool rejection. The full suite includes those witnesses plus benchmark, persistence, provenance, migration and concurrency contracts; tests are available in a source checkout, not the published runtime package.
17
+ 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.
33
18
 
34
19
  ## Public host seams
35
20
 
36
- Inspect the installed package's `dist/core/` implementations and declarations alongside upstream [SDK documentation](https://github.com/earendil-works/pi-mono/blob/v0.85.1/packages/coding-agent/docs/sdk.md). Both tested stacks retain these seams:
37
-
38
- - `session-manager.js` / `session-manager.d.ts`: Read-only extension context exposes `getLeafEntry()`, `getEntry(id)` and each entry's `parentId`. Both lookups use the native ID map; `getBranch()` instead walks to the root and reverses a newly allocated path. State Flow now uses that public parent traversal for preflight without deleting or replacing native history.
39
- - `agent-session.js`, `_handleAgentEvent()` / `_installAgentToolHooks()`, and agent-core's `agent-loop.js`: `message_end` extension handlers run before session persistence; the awaited event then appends the accepted assistant message before tool preflight. Inspect that synchronized current assistant, not a presumed last persisted assistant inside `message_end`. The native sibling-tool regression is the executable barrier witness.
40
- - `sdk.js` and `extensions/runner.js`, `emitContext()`: Pi connects context transformation to the extension runner, which first `structuredClone`s native messages. State Flow projection runs after that host copy. Reducing extension traversal cannot make total inference work independent of history size.
41
- - `agent-session.js`, `prompt()` / `reload()` / `dispose()`: The system prompt is composed at `before_agent_start`; Stop can change tools/projection but not that already composed prompt for the current run. Reload awaits `session_shutdown` before replacement. Bare disposal invalidates/disconnects without emitting shutdown; use the [embedding contract](architecture.md#embedding).
42
- - `agent-session-runtime.js`, `teardownCurrent()`: Owner-driven new/resume/fork aborts the outgoing session, awaits shutdown, then disposes and creates the replacement. Active-push witnesses now cover new, same-file resume and fork teardown before invalidation, alongside quit and actual reload. Correct teardown does not imply successful fork restoration.
43
- - `sdk.js`, `createAgentSession()`: Session selection precedes default resource/extension loading. No extension-only pre-session resolver seam was established; native default continuation remains an [external integration boundary](architecture.md#session-continuation).
21
+ State Flow depends on these public Pi SDK behaviors:
44
22
 
45
- These observations establish the specific seams used here, not compatibility with every Pi UI mode, extension combination, provider or operating system. Native tests use deterministic faux inference, temporary sessions/stores and local remotes. An installed SDK version does not fingerprint a still-running host. Actual-process incident attribution remains unproven; final comparable measurements and integrated acceptance remain in [BACKLOG.md](../BACKLOG.md).
23
+ - Extension lifecycle events and branch metadata for start, stop, reload, resume, fork, and tree navigation.
24
+ - Read-only session parent traversal through `getLeafEntry()` and `getEntry(id)`.
25
+ - `message_end`, actionable `turn_end`, `agent_before_settle`, and `agent_settled` ordering around accepted assistant messages.
26
+ - Canonical session context, `ContextEditEntry`, ordinary context transformation, and `context_with_system` extension boundaries.
27
+ - `getContextUsage()` and native compaction hooks.
28
+ - Sequential tool execution and tool-call preflight.
29
+ - Session replacement awaiting outgoing shutdown before invalidation.
46
30
 
47
- ## Native replacement witnesses
31
+ Compatibility with those seams does not prove every UI mode, provider, operating system, extension combination, or future SDK release.
48
32
 
49
- `tests/pi-harness.ts` now constructs a public `AgentSessionRuntime` from its existing isolated sessions and coherent CWD-bound services, forwarding complete session-start metadata and binding each replacement. No private host hook or production runtime change was needed. The three `tests/integration.test.ts` replacement witnesses pass on both SDK stacks and require:
33
+ ## Pi 0.87.0 feature applicability
50
34
 
51
- - An accepted multi-scope patch and answer to supersede a still-running activation push.
52
- - The exact shutdown reason/target, child exit and a claimable lease at `setBeforeSessionInvalidate()`, before a successor can start.
53
- - Byte-identical outgoing JSONL and session checkpoint/tail/config/meta, the same selected leaf, and exact cold state at the accepted revision.
54
- - An empty private layer plus inherited shared state for configured new sessions, and exact selected state/identity for same-file resume.
55
- - No old-generation relaunch or queue writes after replacement; only a valid successor attempts the exact pending target and acknowledges its controlled child result.
35
+ 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).
56
36
 
57
- **Native fork replacement now creates a child-owned session copy over current shared memory.** The active-push case forks before the first user request: private state is empty at that selected origin, not the parent's later accepted private work. Current global/CWD state remains visible, and the new child publication target descends from the retained parent target. Native session naming still does not prove the child JSONL is already persisted when its prefix contains no assistant.
37
+ - **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.
38
+ - **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.
39
+ - **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.
40
+ - **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.
41
+ - **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.
42
+ - **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.
43
+ - **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.
44
+ - **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.
45
+ - **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.
46
+ - **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.
58
47
 
59
- Further native witnesses cover nonempty selected private state versus newer parent/shared state, retained native prefix and checkpoint/tail data, owned reload/resume, independent child writes and aligned post-origin history. Disabled sources remain disabled and copied parent Stop projection cannot reappear after child reload. Header UUID/CWD mismatches leave storage and selection unchanged; Start retries the exact source in the same loaded fork when evidence is corrected. Selecting inherited pre-origin pointers is unavailable, not permission to fall through to an older disabled marker and erase child state. That last witness failed with `true !== false` before the targeted ownership-aware recovery correction.
48
+ ## Validation procedure
60
49
 
61
- The fork-specific 13-test focused cohort covers these native cases plus runtime copying/CAS/file-expiration and header safety. An initial prefix assertion compared persisted JSON with in-memory objects containing explicit `undefined` fields; it was corrected to compare native persisted entries, without changing runtime behavior. The earlier outgoing-shutdown falsifier failed before invalidation with `null !== 'SIGKILL'`. Controlled push children do not prove external delivery; arbitrary cross-CWD replacement and every UI mode remain outside these witnesses. Ordinary inference abort retains accepted patches for same-session continuation and has no new immediate-enqueue requirement. See [fork support and limits](usage.md#fork-support-and-limits) and the [copy contract](fork-contract.md).
50
+ Validate another Pi SDK line in an isolated copy so the live extension, sessions, and runtime store remain unchanged:
62
51
 
63
- ## Isolated validation procedure
64
-
65
- Keep the live host and repository dependencies unchanged:
66
-
67
- 1. Copy the intended current source, including retained uncommitted files and tests, to a fresh temporary directory. Do not substitute baseline `HEAD` for a dirty candidate. Give the copy its own synthetic Git `HEAD` for benchmark source-identity checks; never copy production session/store data.
68
- 2. Create a real `node_modules` directory in the copy. Link the existing development dependencies, then link `@earendil-works/pi-coding-agent` to the selected installed SDK and AI/agent-core/pi-tui to the dependencies actually resolved by that SDK. Do not use `--preserve-symlinks` or install into the live package. Verify the SDK and extension resolve the same selected dependency instances.
69
- 3. Resolve import-only package manifests with `findPackageJSON(name, pathToFileURL(ownerManifest))`, not `require.resolve(name)`. Record canonical manifest paths, package names/versions and hashes before and after testing. For example, run the following inside the copy:
70
-
71
- ```bash
72
- node --input-type=module <<'JS'
73
- import { findPackageJSON } from 'node:module';
74
- import { readFileSync, realpathSync } from 'node:fs';
75
- import { pathToFileURL } from 'node:url';
76
- const owner = pathToFileURL(`${process.cwd()}/package.json`);
77
- for (const name of ['pi-coding-agent', 'pi-ai', 'pi-agent-core', 'pi-tui']) {
78
- const path = realpathSync(findPackageJSON(`@earendil-works/${name}`, owner));
79
- console.log(path, JSON.parse(readFileSync(path, 'utf8')).version);
80
- }
81
- JS
82
- ```
83
-
84
- Use a fresh `PI_CODING_AGENT_DIR`, `PI_OFFLINE=1`, `GIT_CONFIG_NOSYSTEM=1` and a temporary `GIT_CONFIG_GLOBAL` containing only a synthetic commit identity and disabled commit signing. Fixtures already supply in-memory credentials, no model-catalog refresh and explicit resource/session roots. Leave fixture-local Git hooks enabled: tests intentionally use temporary `pre-receive`/`post-receive` hooks.
85
-
86
- Inside that prepared copy, the compatibility checks are ordinary project commands:
52
+ 1. Copy the complete candidate source, including retained uncommitted changes, into a temporary directory.
53
+ 2. Install or link one matching version of `pi-coding-agent`, `pi-agent-core`, `pi-ai`, and `pi-tui`.
54
+ 3. Confirm all four packages resolve to the intended release line.
55
+ 4. Use isolated Pi agent/session directories and synthetic Git identity; do not copy production session or State Flow data.
56
+ 5. Run:
87
57
 
88
58
  ```bash
89
- npm run typecheck
90
- npm run check
91
- node --experimental-strip-types --test \
92
- --test-name-pattern='tool preflight walks only|patch_state is the only tool|real Pi executes only patch_state|replacement closes its outgoing publisher' \
93
- tests/extension.test.ts tests/integration.test.ts
94
- npm test
59
+ npm run validate
95
60
  ```
96
61
 
97
- `npm run validate` combines typecheck, the full suite and import smoke for subsequent candidates. Retain actual command exits, complete logs and source/dependency identities; a filtered command succeeding does not replace the full suite.
98
-
99
- ### Rejected setup and correction
62
+ A successful focused test does not replace the full suite. Record the exact dependency graph and command exit for any compatibility claim.
100
63
 
101
- The first 0.85.1 full run passed 395/397 because the temporary global Git config incorrectly set `core.hooksPath` to an empty directory. This disabled two fixtures' hooks: prepared receipts no longer observed the synthetic post-push write, and file-to-Git adoption no longer observed the intentionally pending push. The same two failures reproduced on 0.84.4 with that config. Removing only the temporary override made both witnesses pass on both SDKs, followed by 397/397 on 0.85.1. No runtime or test correction was needed; the failed run is not an SDK incompatibility or a successful full-suite result.
64
+ 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.
@@ -6,31 +6,28 @@ State Flow classifies absence separately from partial or malformed evidence. Rec
6
6
  | --- | --- | --- | --- | --- |
7
7
  | 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 |
8
8
  | 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 |
9
- | 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 |
9
+ | 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 |
10
10
  | 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 |
11
11
  | 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 |
12
- | 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 |
13
- | 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 |
14
- | 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 |
15
- | 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 |
16
- | 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 |
17
- | Worker lease | State Flow; operational ownership | Unclaimed | Malformed/foreign live evidence is preserved; live owner excludes peers | Existing dead-process reclamation protocol only |
18
- | Publication locks | State Flow; mutual exclusion | Unlocked | Present lock excludes publishers, including interrupted owners | Current owner releases; no opportunistic deletion |
19
- | 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 |
20
- | 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 |
21
- | 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 |
12
+ | 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 |
13
+ | 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 |
14
+ | 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 |
15
+ | Canonical writer lock | State Flow; file-cohort mutual exclusion | Unlocked | Present lock excludes cooperating publishers, including interrupted owners | Current owner releases; no opportunistic deletion |
16
+ | 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 |
17
+ | 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 |
22
18
  | 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 |
23
- | 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 |
19
+ | 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 |
20
+ | 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 |
24
21
 
25
22
  ## Transaction rule
26
23
 
27
24
  Every semantic repair follows the ordinary transaction path:
28
25
 
29
- 1. Capture the live Git or file basis under the existing publication lock.
26
+ 1. Capture the live canonical-file basis under the existing publication lock.
30
27
  2. Classify each cohort as present, absent, partial, or malformed.
31
28
  3. Derive only an authorized replacement.
32
29
  4. Stage the complete canonical cohort.
33
30
  5. Recheck CAS and ownership.
34
- 6. Atomically publish and install the resulting runtime state.
31
+ 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.
35
32
 
36
- 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.
33
+ 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.
@@ -1,47 +1,42 @@
1
- # Physical fork: session-stream copy
1
+ # Physical fork: retained session-stream copy
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
5
  ## Contract
6
6
 
7
- 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.
7
+ A physical Pi fork creates a fresh child session from a retained boundary in its direct parent's canonical session lineage:
8
8
 
9
9
  ```text
10
- B.global = existing shared global
11
- B.cwd = existing shared CWD
12
- B.session = copy of source session checkpoint + retained patch tail
10
+ child.global = current live global
11
+ child.cwd = current live CWD
12
+ child.session = parent session selected at retained boundary
13
13
  ```
14
14
 
15
- - Resolve the source session stream at the native fork boundary. An earlier selection does not copy the parent's later live private state.
16
- - 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.
17
- - 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.
18
- - 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.
19
- - Preserve A's private files, native trace and accepted history. Subsequent B session writes do not modify A's session layer.
20
- - Forking conversation/memory does not clone or roll back project files or tool effects.
15
+ 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.
21
16
 
22
- This is session inheritance, not an exact historical snapshot of the whole effective state. It adds no historical shared-owner reference or semantic mode.
17
+ The child receives:
23
18
 
24
- ## History and lifecycle
19
+ - its own UUID, native session key, runtime metadata, and fresh lineage origin;
20
+ - the selected parent session materialization and matching artifact provenance;
21
+ - current live global/CWD values and provenance without rewinding them;
22
+ - selected enablement and bootstrap lifecycle state, with step reset to zero and no inherited unfinished specification or validation diagnostic.
25
23
 
26
- `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.
24
+ 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.
27
25
 
28
- 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.
26
+ 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.
29
27
 
30
- 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.
28
+ ## Lifecycle and failure
31
29
 
32
- 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.
30
+ `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.
31
+
32
+ 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.
33
+
34
+ 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.
33
35
 
34
36
  ## Support boundary
35
37
 
36
- - 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.
37
- - 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.
38
- - 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.
39
- - Nested copying works only where the selected pointer is owned by the direct parent; inherited pointers to earlier ancestors are not recursively resolved.
40
- - 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.
41
- - Uncommitted shared streams, collisions and concurrent modifications retain the existing publication guards; failure does not authorize broadening the fork's writes.
38
+ 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.
42
39
 
43
40
  ## Evidence
44
41
 
45
- 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.
46
-
47
- `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.
42
+ 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.
@@ -1,10 +1,10 @@
1
1
  # Lazy state through progressive `read_state`
2
2
 
3
- **Status**: Implemented architecture for the next minor release. Final release validation and publication remain open.
3
+ 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.
4
4
 
5
5
  ## Thesis
6
6
 
7
- 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.
7
+ 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.
8
8
 
9
9
  The model-facing surface remains small:
10
10
 
@@ -34,19 +34,19 @@ The model-facing surface remains small:
34
34
 
35
35
  ## Semantic model
36
36
 
37
- Each scope may contain six semantic planes:
37
+ Each scope contains six semantic planes in intent-first presentation order:
38
38
 
39
39
  ```text
40
40
  global | CWD | session
41
- ├── artifacts
41
+ ├── intents
42
42
  ├── contract
43
43
  ├── working
44
- ├── intents
44
+ ├── artifacts
45
45
  ├── response (session-owned where applicable)
46
46
  └── lazy
47
47
  ```
48
48
 
49
- `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:
49
+ `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:
50
50
 
51
51
  - It is canonical semantic JSON, validated and versioned with its owning scope.
52
52
  - 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,
61
61
 
62
62
  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.
63
63
 
64
- Valid lazy values include:
64
+ The `lazy` root must be an object. Its nested values may include arrays, objects, and scalars, for example:
65
65
 
66
66
  ```json
67
67
  ["important thought", "next thought"]
@@ -136,7 +136,7 @@ Errors use the normal tool-error channel rather than successful JSON containing
136
136
 
137
137
  ### Path and range model
138
138
 
139
- Every path has an explicit root and addresses:
139
+ Unscoped semantic paths alias current effective state. Explicit roots and selectors address:
140
140
 
141
141
  - `effective` for the current composed overlay or an indexed historical effective root.
142
142
  - `global`, `cwd`, and `session` for explicit current or historical scopes.
@@ -156,11 +156,11 @@ cwd.lazy.memory[10:20]
156
156
  session[3].lazy.investigation
157
157
  ```
158
158
 
159
- Indices are zero-based. Negative indices, open-ended ranges, steps, predicates, wildcards, unions, and cross-array expressions are rejected in the first version.
159
+ Indices are zero-based. Negative indices, open-ended ranges, steps, predicates, wildcards, unions, and cross-array expressions are rejected.
160
160
 
161
161
  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.
162
162
 
163
- The implementation must reuse or compatibly extend existing member escaping rather than inventing a second object-path language.
163
+ All projections use the same strict member grammar; no separate lazy path language exists.
164
164
 
165
165
  ## Projections
166
166
 
@@ -396,8 +396,7 @@ Array index selectors extend recursive addressing:
396
396
  "[4]": "corrected fifth thought"
397
397
  }
398
398
  }
399
- },
400
- "final": true
399
+ }
401
400
  }
402
401
  ```
403
402
 
@@ -425,8 +424,7 @@ Nested addressing remains ordinary patch structure:
425
424
  }
426
425
  }
427
426
  }
428
- },
429
- "final": true
427
+ }
430
428
  }
431
429
  ```
432
430
 
@@ -440,24 +438,23 @@ Lazy mutations inherit existing guarantees:
440
438
  - One lock/CAS publication cohort.
441
439
  - Atomic hot-plus-lazy multi-scope changes.
442
440
  - Scope-local deletion and effective revelation semantics.
443
- - Exact revision selection on restore and branch navigation.
441
+ - Exact retained-boundary selection on restore and branch navigation.
444
442
  - Read-only discovery with no commit, timestamp update, or transition.
445
443
 
446
- 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.
444
+ 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.
447
445
 
448
446
  ## Failure semantics
449
447
 
450
448
  - A nonexistent path, wrong target kind, malformed selector, or out-of-bounds index/range is a tool error.
451
449
  - One invalid member of a path batch fails the entire read before returning partial success.
452
450
  - One invalid indexed patch fails the entire mutation before publication.
453
- - A malformed lazy subtree fails closed at the smallest affected path and reports that path.
454
- - Missing or corrupt optional indexes cannot make canonical lazy JSON disappear.
455
- - Read failures create no semantic transition and do not affect ordinary hot state.
456
- - Mechanical index rebuilds create no semantic transition.
451
+ - Malformed canonical lazy data fails the dependent scope/runtime load without rewriting retained bytes; it is not silently discarded to manufacture valid hot state.
452
+ - Invalid reads and rejected patches create no semantic transition and preserve accepted hot state.
453
+ - Independent scopes remain usable only where the ordinary filesystem/recovery contract proves their authority.
457
454
 
458
455
  ## Normative invariants
459
456
 
460
- 1. **Ordinary JSON**: Lazy values contain domain semantics, never mandatory State Flow record wrappers.
457
+ 1. **Object root, ordinary JSON children**: Every scope has a lazy object whose nested values contain domain semantics, never mandatory State Flow record wrappers.
461
458
  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`.
462
459
  3. **Exact success**: A successful read returns everything requested; it never truncates or paginates silently.
463
460
  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
468
465
  9. **Explicit frontier crossing**: Only a visible hot-state patch promotes a lazy consequence.
469
466
  10. **Patch remains patch**: Array indices extend recursive addressing without introducing an edit-command language.
470
467
  11. **Index safety**: Array indices are interpreted only against one captured basis under lock/CAS.
471
- 12. **Failure isolation**: Lazy corruption or unavailable indexes do not damage valid hot state.
468
+ 12. **Failure preservation**: Invalid reads or patches preserve accepted bytes; canonical corruption fails closed rather than granting partial authority.
472
469
 
473
470
  ## Validation contract
474
471
 
@@ -487,27 +484,14 @@ Before release, implementation evidence must prove:
487
484
  - `effective.lazy` follows global → CWD → session overlay while explicit scope paths preserve ownership.
488
485
  - Reads create no semantic transition, Git commit, publication, freshness update, or future activation.
489
486
  - Whole-array replacement and indexed scalar, array, object, nested, multi-index, and stale-basis patches remain atomic.
490
- - Restore, fork, file-only, and Git-backed paths select lazy state from the same owning State Flow revision.
491
- - Corrupt lazy data or optional indexes do not damage ordinary hot State Flow.
492
- - Legacy stores and legacy `read_state` inputs either migrate deterministically or fail actionably.
493
-
494
- ## Remaining evolution decisions
495
-
496
- - Exact member escaping beyond the current strict grammar for names containing separators or brackets.
497
- - A measured real-workload threshold that would justify replacing the initial co-located semantic layout.
498
- - Cold Git-history access beyond retained hot history.
487
+ - Restore and fork select lazy state from the same retained canonical boundary as the rest of the owning session scope.
488
+ - Malformed canonical lazy data fails closed without rewriting the store; rejected queries and patches preserve accepted hot state.
489
+ - Unsupported predecessor stores and retired `read_state` inputs fail actionably without rewriting retained bytes.
499
490
 
500
- 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.
491
+ ## Limits and change authority
501
492
 
502
- ## Next minor release sequence
493
+ 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.
503
494
 
504
- 1. Extend the existing path parser with canonical escaping, ordered batches, strict indices, and half-open ranges.
505
- 2. Implement semantic-snapshot `value`, structural `meta` + `keys`, and semantic `patch` reads over current hot state first.
506
- 3. Add indexed recursive array patching through the existing lock/CAS barrier.
507
- 4. Add `lazy` to scope validation, persistence, history, restore, and explicit scoped reads.
508
- 5. Add the read-only `effective.lazy` overlay and bounded baseline navigation hint.
509
- 6. Add migration, corruption, stale-basis, restore, fork, file-only, Git-backed, and concurrency coverage.
510
- 7. Measure repository growth, publication latency, restoration latency, and package/store size before selecting any sharded layout.
511
- 8. Update runtime protocol and user documentation, run full validation, and release through the repository's guarded minor-release flow.
495
+ The [canonical backlog](../BACKLOG.md) owns remaining implementation and release gates. This contract is not a parallel delivery plan.
512
496
 
513
497
  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.