@llblab/pi-kit 0.26.0 → 0.27.0

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

@@ -2,11 +2,15 @@
 
 ## Supported Pi stack
 
-State Flow requires matching `pi-coding-agent`, `pi-agent-core`, `pi-ai`, and `pi-tui` packages at `>=1.0.0`. Keep all four on the same release line. The open-ended peer range permits newer SDK releases; it does not certify them.
+State Flow requires matching `pi-coding-agent`, `pi-agent-core`, `pi-ai` and `pi-tui` packages at `>=1.0.0`. Keep all four on the same release line. The open-ended peer range permits newer SDK releases; it does not certify them.
 
-The repository-local verified stack is Linux/x64, Node 26.8.1, Git 2.55.0 and matching Pi SDK 1.0.0 packages. Earlier source-bound measurements on Pi 0.87.0 remain historical evidence, not 1.0.0 performance results. Repository validation covers tests, typecheck, build, compiled imports and package dry-run; successful results are bound to the validated source and dependency identities. The release workflow uses Node 24; its result is a separate verification gate.
+**Verified environment:** Linux/x64, Node 26.8.1, Git 2.55.0 and matching Pi SDK 1.0.0 packages.
 
-Tests use isolated stores and scripted providers through the real Pi SDK. They do not certify installed Telegram/TUI reachability, live provider behavior, other operating systems, mixed SDK versions or untested newer SDK releases. Detailed behavioral witnesses live in [temporal acceptance](temporal-acceptance.md); benchmark methodology and source-bound results live in [performance](performance.md).
+- Repository validation covers tests, typecheck, build, compiled imports and package dry-run. Results apply to the exact source and dependency identities validated.
+- The release workflow uses Node 24; its result is a separate verification gate.
+- Tests use isolated stores and scripted providers through the real Pi SDK. They do not certify installed Telegram/TUI reachability, live provider behavior, other operating systems, mixed SDK versions or untested newer SDK releases.
+
+Detailed behavioral witnesses live in [temporal acceptance](temporal-acceptance.md); benchmark methodology and source-bound results live in [performance](performance.md).
 
 ## Public host seams
 
@@ -24,79 +28,149 @@ An embedding must deliver the native lifecycle, not merely construct or dispose
 
 ## Context, tools and provider input
 
-State Flow contributes its protocol through `systemPromptOptions.sections.state_flow` and refreshes only that section at `context_with_system`. Companion sections, native system deltas, tool declarations and non-system message identities remain intact; an explicit foreign forced prompt retains Pi's precedence. Mode changes update the next provider request without requiring another `before_agent_start`.
+**System prompt.** State Flow contributes protocol through `systemPromptOptions.sections.state_flow` and refreshes only that section at `context_with_system`.
+
+- Companion sections, native system deltas, tool declarations and non-system message identities remain intact.
+- An explicit foreign forced prompt retains Pi's precedence.
+- Mode changes update the next provider request without requiring another `before_agent_start`.
+
+**Conversation and recovery:**
 
-Native context edits, omitted messages and replaced tool results reach the provider through Pi's canonical context. Raw native trace remains inspectable. Branch selection applies branch-relative edits without rewriting separately owned memory. Retry, length and overflow recovery omit failed attempts from subsequent provider input without accepting them as State Flow responses or advancing semantic history. Edited-context usage accounting must not trigger phantom compaction.
+- Native context edits, omitted messages and replaced tool results reach the provider through Pi's canonical context. Raw native trace remains inspectable.
+- Branch selection applies branch-relative edits without rewriting separately owned memory.
+- Retry, length and overflow recovery omit failed attempts from subsequent provider input, without accepting them as State Flow responses or advancing semantic history.
+- Edited-context usage accounting must not trigger phantom compaction.
 
-Image resizing, encoding and provider limits remain SDK-owned. Tests exercise prompt images, built-in reads and generic tool results across model-specific resize profiles while preserving historical payloads. State Flow supplies no image pipeline or provider-limit enforcement. Provider strict schemas, cache behavior, diagnostics and other SDK capabilities are not independently certified by State Flow's tests.
+**Images and provider limits.** Image resizing, encoding and provider limits remain SDK-owned. Tests exercise prompt images, built-in reads and generic tool results across model-specific resize profiles while preserving historical payloads. State Flow supplies no image pipeline or provider-limit enforcement. Its tests do not independently certify provider strict schemas, cache behavior, diagnostics or other SDK capabilities.
 
-Active boundary continuation receives accepted memory even when no new `before_agent_start` occurs. A completed specification is not resurrected. State Flow does not become the owner of the host's continuation scheduler.
+**Continuation.** Active boundary continuation receives accepted memory even without a new `before_agent_start`. A completed specification is not resurrected, and State Flow does not own the host's continuation scheduler.
 
 ## Pre-inference cancellation
 
-On the tested SDK, `before_agent_start` precedes the low-level agent's `prompt`; `ExtensionContext.signal` is undefined there. State Flow captures the specification at that hook without canonical publication. The active `context` hook supplies the operation signal and awaits preparation/maintenance before provider inference.
+On the tested SDK, `before_agent_start` precedes the low-level agent's `prompt`; `ExtensionContext.signal` is undefined there.
 
-Pi catches context-hook errors and may otherwise continue inference. State Flow therefore calls public `ctx.abort()` on preparation failure rather than relying on a thrown error as a fence. Native tests prove no provider call before coherent acceptance, cancellation while an independent writer remains held, rollback without draft installation and preservation of uncompiled native input.
+1. State Flow captures the specification at that hook without canonical publication.
+2. The active `context` hook supplies the operation signal and awaits preparation/maintenance before provider inference.
+3. If preparation fails, State Flow calls public `ctx.abort()`. Pi catches context-hook errors and may otherwise continue inference, so a thrown error alone is not a fence.
 
-Operation signals are not universal. Idle commands and session events can lack them. Do not infer native Abort cancellation from an extension-owned shutdown signal or generalize active-run tests to idle waits.
+Native tests prove no provider call before coherent acceptance, cancellation while an independent writer remains held, rollback without draft installation and preservation of uncompiled native input.
+
+**Signals are not universal.** Idle commands and session events can lack them. Do not infer native Abort cancellation from an extension-owned shutdown signal or generalize active-run tests to idle waits.
 
 ## Mode configuration compatibility
 
-Global `config.json` accepts `mode: "active" | "passive" | "off"`, defaulting to Off when no mode policy is configured, solely as the initial policy for new sessions. Session `config.json` uses the same key for the concrete retained choice; commands and Telegram never edit the global default. Before semantic initialization, an inactive choice is retained in a native `{mode}` checkpoint instead.
+**Preferred representation:**
+
+- Global `config.json` accepts `mode: "active" | "passive" | "off"`. It defaults to Off when no mode policy is configured and supplies only the initial policy for new sessions.
+- Session `config.json` uses the same key for the concrete retained choice. Commands and Telegram never edit the global default.
+- Before semantic initialization, an inactive choice is retained in a native `{mode}` checkpoint instead.
 
-Legacy decoding is read-only. Without explicit global mode, the absence of all legacy mode flags means Off; `autoStart: true` means Active, while any present legacy mode flag retains its former mapping: `passiveBootstrap: false` together with `passiveTools: false` means Off, and otherwise the fallback is Passive. An operator who previously relied on an absent configuration for implicit Passive must now select Passive in that session or set global `mode: "passive"` for new sessions. Explicit global mode overrides valid legacy flags; invalid values still fail validation. Session `enabled:true` remains Active, and `enabled:false` is non-active. Native legacy inactive checkpoints use the configured inactive fallback, never an Active default. Session config and native checkpoints reject mixed `mode`/`enabled` representations, even when apparently consistent, rather than choosing between two stored policies. Ordinary writers emit only mode; no eager migration or semantic normalization runs.
+**Other readable representations.** Decoding is read-only; ordinary writers emit only mode, with no eager migration or semantic normalization.
 
-The extension SDK uses an optional `mode` default override, and both Telegram port variants use `snapshot.mode` plus `select(mode)`. Old callback keyboards may refresh the view without selecting a mode. Synchronous enum-based ports remain supported; this does not promise the removed Start/Stop port signatures.
+- Without explicit global mode, absence of all flag-based mode settings means Off.
+- `autoStart: true` means Active. With any flag-based mode setting present, `passiveBootstrap: false` together with `passiveTools: false` means Off; otherwise the fallback is Passive.
+- Explicit global mode overrides valid flags; invalid values still fail validation.
+- Session `enabled:true` means Active, and `enabled:false` means non-active.
+- Native inactive checkpoints without an explicit mode use the configured inactive fallback, never an Active default.
+- Session config and native checkpoints reject mixed `mode`/`enabled` representations, even when apparently consistent, rather than choosing between two stored policies.
+
+To use Passive, select it in the current session or set global `mode: "passive"` for new sessions.
+
+**SDK and Telegram controls.** The extension SDK accepts an optional `mode` default override. Both Telegram port variants use `snapshot.mode` plus `select(mode)`. A stale callback keyboard may refresh the view without selecting a mode. Synchronous enum-based ports are supported; Start/Stop port signatures are not.
 
 ## Mode selection and memory restoration
 
-Start activates current same-session authority under awaited exclusion. It rechecks physical identity and initialization permission after waiting, accepts once, then installs policy, memory and checkpoint. Explicit Start does not claim to restore an expired historical boundary. Native tests prove current shared plus local-private memory at the next provider and actual Abort withdrawal for in-run Start with an operation signal.
+**Start:**
+
+- Activates current same-session authority under awaited exclusion.
+- Rechecks physical identity and initialization permission after waiting, accepts once, then installs policy, memory and checkpoint.
+- Does not claim to restore an expired historical boundary.
+- Native tests prove current shared plus local-private memory at the next provider, and actual Abort withdrawal for in-run Start with an operation signal.
+
+**Passive:**
+
+- Selects local tools/context policy before waiting for persistence.
+- For accepted memory, publishes lifecycle metadata without rewriting semantic/provenance files. Pending inactive choices share one acceptance of the latest mode.
+- Keeps independently owned retained restoration, Active-default initialization and fork copying; the latest inactive policy is applied at acceptance.
+- Read-only recovery preserves an intervening Passive choice and its write fence.
+- Selection, shutdown and accepted Start cancel obsolete Stop persistence; rejected Start does not.
+- Genuine persistence failure retains readable memory and native context while fencing writes until accepted Start.
 
-Passive/Off selects local tools/context policy before waiting for persistence; Off injects no State Flow context, including a frozen handoff. For accepted memory it publishes lifecycle metadata without rewriting semantic/provenance files. Pending inactive choices share one acceptance of the latest mode. Selection, shutdown and accepted Start cancel obsolete Stop work; rejected Start does not. Genuine persistence failure retains readable memory and native context while fencing writes until accepted Start.
+**Off:**
 
-Mode choices select workflow policy, not whether canonical memory exists. Passive/Off never cancels retained restoration, Active-default initialization or fork copying: the latest inactive policy is applied at acceptance. Read-only recovery likewise preserves an intervening mode choice and its write fence. Cancelling a Start waiter does not cancel independently owned restoration. Selection changes, shutdown and an available native operation signal can revoke obsolete restoration; post-acceptance ancillary failure cannot undo memory.
+- Selects local tools/context policy immediately and injects no State Flow context, including a frozen handoff.
+- Cancels owned restoration/fork and persistence waits, clears semantic caches and records native policy only, without canonical publication.
+- Keeps the deferred boundary/source bookkeeping for later explicit Passive/Active acquisition.
 
-Native startup and tree handlers await restoration. Tests cover held-store tree/fork selection, exact private state over live shared streams, unchanged parent-private files, cold reopening, failed-Stop recovery and next-provider input without later-branch private values. A public SDK host can observe the child factory result before awaiting extension binding and send Stop or Stop→Start through the child's public `prompt` method while copying waits. This proves that embedding route, not that the installed CLI or Telegram exposes the child before runtime replacement finishes.
+Modes select workflow policy, not whether canonical memory exists. Cancelling a Start waiter does not cancel independently owned restoration. Selection changes, shutdown and an available native operation signal can revoke obsolete restoration; failure after acceptance cannot undo memory.
 
-Read-only recovery validates current private memory without initializing absent storage or granting patch/lifecycle publication authority. Invalid or expired historical evidence never authorizes newer, empty or unrelated private memory as fallback.
+**Native restoration evidence.** Startup and tree handlers await restoration. Tests cover held-store tree/fork selection, exact private state over live shared streams, unchanged parent-private files, cold reopening, failed-Stop recovery and next-provider input without later-branch private values.
+
+A public SDK host can observe the child factory result before awaiting extension binding and send Stop or Stop→Start through the child's public `prompt` method while copying waits. This proves that embedding route, not that the installed CLI or Telegram exposes the child before runtime replacement finishes.
+
+**Read-only recovery** validates current private memory without initializing absent storage or granting patch/lifecycle publication authority. Invalid or expired historical evidence never authorizes newer, empty or unrelated private memory as fallback.
 
 ## Settlement cancellation
 
-On Pi SDK 0.87.0, the agent clears its active run before `agent_before_settle`, so that event has no operation signal. Native `AgentSession.abort()` cannot withdraw an extension's lock wait at this boundary.
+Native `AgentSession.abort()` can withdraw a settlement lock wait only when the host supplies a suitable operation signal. An extension-owned cancellation lifetime is not a substitute for that signal.
+
+**Optional Git backup** remains at `agent_before_settle`:
 
-Optional Git backup remains at `agent_before_settle`. It waits for exclusion only when the host supplies a suitable signal; otherwise contention produces an explicit diagnostic-only deferral to a later eligible turn. Malformed/interrupted ownership remains a failure, not permission to steal a lock. Git commands run outside canonical exclusion. Shutdown drains owned attempts and pending pushes. Backup failure does not roll back memory, suppress an answer or request repair inference.
+- It waits for exclusion only when the host supplies a suitable signal. Otherwise contention produces an explicit diagnostic-only deferral to a later eligible turn.
+- Malformed or interrupted ownership remains a failure, not permission to steal a lock.
+- Git commands run outside canonical exclusion. Shutdown drains owned attempts and pending pushes.
+- Backup failure neither rolls back memory, suppresses an answer nor requests repair inference.
 
 This optional-backup policy does not apply to required semantic publication or restoration. The persistence model is [optimistic canonical storage](filesystem-recovery.md#power-loss-durability), not power-loss-safe acknowledgement or crash-atomic multi-file publication. No journal, replacement Abort handler or background publication worker supplies a stronger guarantee.
 
-State Flow-owned compaction requires known sufficient context usage and a proven retained run anchor. It preserves the complete accepted run, skips protected foreign context and never requests retain-none shortening. Native manual/threshold/overflow compaction remains Pi-owned. The settled handler awaits native compaction completion or refusal so deferred companion prompts do not race it. Unknown or insufficient usage skips compaction; a benign refusal permits a later attempt.
+**State Flow-owned compaction:**
+
+- Requires known sufficient context usage and a proven retained run anchor.
+- Preserves the complete accepted run, skips protected foreign context and never requests retain-none shortening.
+- Leaves native manual/threshold/overflow compaction to Pi.
+- Awaits native compaction completion or refusal in the settled handler, so deferred companion prompts do not race it.
+- Skips compaction when usage is unknown or insufficient; a benign refusal permits a later attempt.
 
 ## Telegram adapter
 
-The optional adapter presents one Off | Passive | Active row and uses the same mode-selection and inspection owners as native commands. Inspection returns coherent state plus matching revisions without publication. Controls and inspections acknowledge callbacks before waiting, suppress revoked results and escape late failures in the current menu. Synchronous mode-selection ports remain supported. A first Passive selection may install a read-only shared cache without invalidating its own success receipt; later controls, branch changes and cancellation still revoke obsolete presentation.
+The optional adapter presents one Off | Passive | Active row and uses the same mode-selection and inspection owners as native commands.
+
+- Inspection returns coherent state plus matching revisions, without publication.
+- Controls and inspections acknowledge callbacks before waiting, suppress revoked results and escape late failures in the current menu.
+- Synchronous mode-selection ports are supported.
+- A first Passive selection may install a read-only shared cache without invalidating its own success receipt. Later controls, branch changes and cancellation still revoke obsolete presentation.
 
-Adapter tests establish those contracts with isolated transport fixtures. They are not a live Telegram smoke test. Missing or unready transport remains fail-open and cannot change core memory behavior.
+Adapter tests establish these contracts with isolated transport fixtures; they are not a live Telegram smoke test. Missing or unready transport remains fail-open and cannot change core memory behavior.
 
 ## State Flow library API compatibility
 
 The package root exports `TemporalRuntime`. The Pi registration shim is a separate default-only entrypoint, not the named library API.
 
-Use these awaited runtime operations:
+**Awaited runtime operations:**
 
-| Operation | API | Authority boundary |
-| --- | --- | --- |
-| Shared inspection | `refreshShared` | Read-only; no initialization or revision advance |
-| Current private recovery | `refreshCurrentMemory` | Read-only; no publication authority |
-| Authored semantic patch | `withPatchTransaction` | Current shared basis and selected private authority; one atomic acceptance |
-| Accepted-runtime lifecycle | `withLifecycleTransaction` | Config/runtime only; cannot initialize or repair semantic storage |
-| Current-head activation | `withStartTransaction` | Origin creation defaults off and requires explicit authorization |
-| Retained restoration | `withRestoreTransaction` | Exact retained private boundary beside current shared streams |
-| Child creation | `withForkTransaction` | Exact parent authority and an unoccupied independent child |
+- **Shared inspection — `refreshShared`:** read-only; no initialization or revision advance.
+- **Current private recovery — `refreshCurrentMemory`:** read-only; no publication authority.
+- **Authored semantic patch — `withPatchTransaction`:** current shared basis and selected private authority; one atomic acceptance.
+- **Accepted-runtime lifecycle — `withLifecycleTransaction`:** config/runtime only; cannot initialize or repair semantic storage.
+- **Current-head activation — `withStartTransaction`:** origin creation defaults off and requires explicit authorization.
+- **Retained restoration — `withRestoreTransaction`:** exact retained private boundary beside current shared streams.
+- **Child creation — `withForkTransaction`:** exact parent authority and an unoccupied independent child.
 
-Await completion before consuming results. Transaction callbacks stage and publish synchronously, recheck caller selection/policy after waiting and use their publication capability once within its lifetime. Install host state only after acceptance. Keep inference, source acquisition and Git outside canonical exclusion. Raw precomputed replay retains its selected-basis guards.
+Await completion before consuming results. Transaction callbacks:
 
-Continuation inspection/candidate building and Git backup also return Promises. Callers must await them rather than treating a Promise as a boolean or accessing a result before completion. Continuation inspection is advisory: it cannot initialize, restore or select a session on the host's behalf.
+1. Recheck caller selection/policy after waiting.
+2. Stage and publish synchronously, using their publication capability once within its lifetime.
+3. Install host state only after acceptance.
 
-The supported synchronous runtime methods are `loadPassive`, `prepareBoundaryRestore`, `restoreBoundary`, `acceptRestoredOrigin`, `prepareBoundaryFork` and `initialize`. They remain available to library consumers and local tests/benchmarks, but production lifecycle wiring uses the awaited APIs. They are not signature-compatible substitutes and do not acquire the awaited APIs' cancellation behavior. Their presence is not permission to bypass ownership, retained-history or raw-replay checks.
+Keep inference, source acquisition and Git outside canonical exclusion. Raw precomputed replay retains its selected-basis guards.
+
+Continuation inspection/candidate building and Git backup also return Promises. Await them rather than treating a Promise as a boolean or accessing a result before completion. Continuation inspection is advisory: it cannot initialize, restore or select a session on the host's behalf.
+
+**Synchronous runtime methods:** `loadPassive`, `prepareBoundaryRestore`, `restoreBoundary`, `acceptRestoredOrigin`, `prepareBoundaryFork` and `initialize`.
+
+- They are supported for library consumers and local tests/benchmarks; production lifecycle wiring uses the awaited APIs.
+- They are not signature-compatible substitutes and do not acquire the awaited APIs' cancellation behavior.
+- Their presence is not permission to bypass ownership, retained-history or raw-replay checks.
 
 ## Validation procedure
 
@@ -109,4 +183,9 @@ Validate another SDK line in an isolated copy so the installed extension, sessio
 5. Inspect the compiled public API through `dist/index.js` and the Pi default registration through `dist/pi-state-flow/index.js`.
 6. Compare generated `dist` and packaged Skills with source, and verify package inventory after final documentation edits.
 
-Focused tests do not replace the full integration suite. Tree-bound evidence can be reused only when its relevant inputs are unchanged. Ref-, environment- and external-publication-sensitive checks require their own verification. A successful tag push is not release completion: verify the owning workflow, published GitHub Release and exact npm package identity.
+**Evidence limits:**
+
+- Focused tests do not replace the full integration suite.
+- Tree-bound evidence can be reused only when its relevant inputs are unchanged.
+- Ref-, environment- and external-publication-sensitive checks require their own verification.
+- A successful tag push is not release completion: verify the owning workflow, published GitHub Release and exact npm package identity.

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

@@ -2,32 +2,125 @@
 
 State Flow classifies absence separately from partial or malformed evidence. Recovery may derive bytes only from an authoritative surviving cohort or from a semantic default that the owner explicitly permits. It never invents history, ownership, provenance, or external success.
 
-| Resource or cohort | Owner / authority | Total absence | Partial or malformed presence | Allowed repair and writes |
-| --- | --- | --- | --- | --- |
-| Global `checkpoint.json` + `patches.jsonl` | State Flow; authoritative shared semantics | Authored patches use current empty reality; stale precomputed replay refuses it | 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 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, 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 | 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 |
+## Resource rules
+
+### Global `checkpoint.json` + `patches.jsonl`
+
+- **Authority:** State Flow; authoritative shared semantics.
+- **Wholly absent:** Authored patches use current empty reality; stale precomputed replay refuses it.
+- **Partial or malformed:** Either half missing, malformed replay, or invalid envelope fails closed.
+- **Allowed repair and writes:** Normal CAS publication may materialize the complete empty pair.
+
+### CWD `checkpoint.json` + `patches.jsonl`
+
+- **Authority:** State Flow; authoritative shared semantics with CWD identity.
+- **Wholly absent:** Same as global; selected values are not resurrected.
+- **Partial or malformed:** Same as global; owner mismatch also fails closed.
+- **Allowed repair and writes:** Normal CAS publication may materialize the complete empty pair.
+
+### Session `checkpoint.json` + `patches.jsonl`
+
+- **Authority:** State Flow; authoritative private semantics.
+- **Wholly absent:** Fresh lifecycle origin may initialize; an existing selected session requires exact retained authority.
+- **Partial or malformed:** Partial or malformed pair fails closed.
+- **Allowed repair and writes:** Fresh initialization or exact retained-boundary recovery only.
+
+### Global/CWD `meta.json`
+
+- **Authority:** State Flow; temporal boundaries, CWD identity, and artifact provenance.
+- **Wholly absent:** Missing metadata removes temporal authority and fails closed; only an omitted `artifacts` leaf degrades provenance to `{}`.
+- **Partial or malformed:** Malformed metadata or semantic/boundary mismatch fails closed.
+- **Allowed repair and writes:** Normal CAS publication from a complete proven cohort.
+
+### Session `meta.json`
+
+- **Authority:** State Flow; session temporal boundaries and artifact provenance.
+- **Wholly absent:** Fresh origin may initialize; selected sessions recover only from exact scope authority.
+- **Partial or malformed:** Partial, malformed, or contradictory boundary evidence fails closed.
+- **Allowed repair and writes:** Canonical scope publication from the selected temporal state.
+
+### Session `config.json` + `runtime.json`
+
+- **Authority:** State Flow; behavior plus authoritative runtime identity, lineage, and counters.
+- **Wholly absent:** Fresh origin may initialize; selected sessions recover only from exact authority.
+- **Partial or malformed:** Partial, malformed, contradictory identity or lineage fails closed.
+- **Allowed repair and writes:** Canonical runtime publication from proven lifecycle/selected state; combined session metadata is unsupported.
+
+### Unsupported checkpoint envelopes, `state.json`, hashed layouts, or semantic Pi checkpoints
+
+- **Authority:** No current authority.
+- **Wholly absent:** Ignored.
+- **Partial or malformed:** Presence never becomes recovery or conversion input.
+- **Allowed repair and writes:** Preserve bytes; operator-managed removal or external conversion only.
+
+### Retained Pi boundary
+
+- **Authority:** State Flow/Pi entry; current canonical lineage.
+- **Wholly absent:** Expired or missing boundary is unavailable.
+- **Partial or malformed:** Identity, lifecycle, or lineage contradiction fails closed.
+- **Allowed repair and writes:** Select exact retained private history over live shared scopes; never consult Git.
+
+### Canonical writer lock
+
+- **Authority:** State Flow; file-cohort mutual exclusion.
+- **Wholly absent:** Unlocked.
+- **Partial or malformed:** Present lock excludes cooperating publishers, including interrupted owners.
+- **Allowed repair and writes:** Current owner releases; no opportunistic deletion.
+
+### Repository-root `config.json`
+
+- **Authority:** Operator; optional read-only global configuration.
+- **Wholly absent:** Built-in defaults.
+- **Partial or malformed:** Present unreadable/malformed/unknown settings fail extension configuration.
+- **Allowed repair and writes:** State Flow never creates, rewrites, or stages operator edits; include it in operator-managed copies/versioning.
+
+### Registered artifact source path
+
+- **Authority:** External source owner.
+- **Wholly absent:** Exact proven absence permits owning-scope artifact/provenance removal.
+- **Partial or malformed:** Relative, symlink, directory, malformed, or unreadable paths disable maintenance locally.
+- **Allowed repair and writes:** Never create; semantic removal only for exact proven absence.
+
+### Skill and external artifact sources
+
+- **Authority:** External package/user owner.
+- **Wholly absent:** Freshness unavailable unless ownership proves removal semantics.
+- **Partial or malformed:** Unsafe/non-regular/unreadable sources disable acquisition locally.
+- **Allowed repair and writes:** Never create or fabricate source/provenance.
+
+### Pi State Flow entries
+
+- **Authority:** Pi session log / State Flow entry owner.
+- **Wholly absent:** Missing required selected boundary blocks that restore.
+- **Partial or malformed:** Malformed or contradictory owner/version/boundary fails the dependent restore.
+- **Allowed repair and writes:** Append through Pi entry APIs only; never replace failed selection with passive state.
+
+### Optional diagnostic log
+
+- **Authority:** State Flow logger; outside the canonical repository.
+- **Wholly absent:** No diagnostic evidence.
+- **Partial or malformed:** I/O failure warns once without changing accepted state.
+- **Allowed repair and writes:** Append local JSONL only when opted in; never use it as semantic recovery authority.
 
 ## Power-loss durability
 
-**Current limitation:** `lib/durable.ts` writes same-directory temporary files with `writeFileSync`, then replaces owned paths one at a time with `renameSync`. There is no file/directory `fsync` barrier. A successful call or subsequent readback proves filesystem-visible bytes, not persistence beyond volatile OS/device caches. Guarded rollback handles caught errors while the process is alive; it cannot run after abrupt termination, and several individually atomic replacements are not one crash-atomic cohort. A crash may leave mixed old/new files or unavailable evidence. Existing rollback and cancellation tests do not establish power-loss survival.
+**Persistence is optimistic, not power-loss safe.** `lib/durable.ts` writes same-directory temporary files with `writeFileSync`, then replaces owned paths one at a time with `renameSync`.
 
-**Selected contract (operator decision, 2026-09-24):** optimistic ordinary-operation persistence is sufficient for this release. Loss of recent work after abrupt power loss is an accepted risk, not a requirement for a new recovery mechanism. Power-loss-safe acknowledgement is removed from the release gates; do not add a patch journal, temporary recovery store, flush protocol or storage-format redesign for that scenario. Existing same-directory temporary replacement files remain an implementation detail, not a new patch store. No at-most-one-patch loss bound is promised: an interrupted multi-file publication can leave incomplete evidence and require operator recovery.
+- There is no file/directory `fsync` barrier. A successful call or subsequent readback proves filesystem-visible bytes, not persistence beyond volatile OS/device caches.
+- Guarded rollback handles caught errors while the process is alive. It cannot run after abrupt termination, and several individually atomic replacements are not one crash-atomic cohort.
+- A crash may leave mixed old/new files or unavailable evidence. Rollback, cancellation and process-kill tests do not establish power-loss survival.
 
-Ordinary concurrent publication still preserves unrelated current Global/CWD fields, orders overlapping writes by acceptance and protects private Session authority. Use one short asynchronously awaited capture/stage/publication exclusion plus CAS; inference, source acquisition and Git stay outside it. Optimism does not authorize replacing a stale whole state, accepting a partial cohort, fabricating empty memory, ignoring a reported write failure or stealing an unavailable lock. Optional Git backup and remote synchronization may defer to a later eligible settled turn; neither every intermediate commit nor immediate remote replication is required.
+**Accepted risk.** Loss of recent work after abrupt power loss is an accepted risk. There is no power-loss-safe acknowledgement or at-most-one-patch loss bound: an interrupted multi-file publication can leave incomplete evidence and require operator recovery.
 
-**Native Pi comparison:** inspection of Pi SDK 0.87.0 `dist/core/session-manager.js` shows `_persist()` appending JSONL with `appendFileSync` and initially writing entries with `writeFileSync`; `_rewriteFile()` writes through an opened file descriptor and closes it. These paths specify no `fsync`, `fdatasync` or `flush: true` barrier. Its `flushed` flag tracks whether the initial in-memory entries were written, not stable-media acknowledgement. This is source evidence for that SDK line, not a power-failure experiment or a guarantee about other versions/filesystems. Stronger durability is technically possible with persistence barriers and a coherent recovery protocol, but is deliberately outside this release scope. Process-kill tests alone would not prove volatile-cache survival.
+- Do not add a patch journal, temporary recovery store, flush protocol or storage-format redesign for this scenario without a separate design decision.
+- Same-directory temporary replacement files are an implementation detail, not a separate patch store.
+- Stronger durability would require persistence barriers and a coherent recovery protocol; it is outside the current contract.
+
+**Concurrency guarantees still apply.** Ordinary concurrent publication preserves unrelated current Global/CWD fields, orders overlapping writes by acceptance and protects private Session authority.
+
+- Use one short asynchronously awaited capture/stage/publication exclusion plus CAS. Inference, source acquisition and Git stay outside it.
+- Optimism does not authorize replacing a stale whole state, accepting a partial cohort, fabricating empty memory, ignoring a reported write failure or stealing an unavailable lock.
+- Optional Git backup and remote synchronization may defer to a later eligible settled turn. Neither every intermediate commit nor immediate remote replication is required.
 
 ## Transaction rule
 
@@ -40,4 +133,8 @@ Every semantic repair follows the ordinary transaction path:
 5. Recheck CAS and ownership.
 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 wholly absent shared scope is current empty reality, not permission to restore cached cold values or leftover compilation evidence. Authored `patch_state` operations select this basis under the awaited store lock and publish only after complete validation; a rejected first patch never leaves separately published empty initialization. Raw precomputed replay targeting a disappeared selected basis still fails closed. Discarded history is unavailable and is never reconstructed or promoted back into current shared memory.
+**A wholly absent shared scope is current empty reality**, not permission to restore cached cold values or leftover compilation evidence.
+
+- Authored `patch_state` operations select this basis under the awaited store lock and publish only after complete validation. A rejected first patch never leaves separately published empty initialization.
+- Raw precomputed replay targeting a disappeared selected basis still fails closed.
+- 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

@@ -21,26 +21,86 @@ The child receives:
 - current live global/CWD values and provenance without rewinding them;
 - selected `mode` and bootstrap lifecycle state, with step reset to zero and no inherited unfinished specification or validation diagnostic.
 
-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.
+**What stays unchanged:**
 
-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.
+- 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.
+
+**Artifact evidence 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.
 
 ## Lifecycle and failure
 
-`TemporalRuntime.withForkTransaction(source, checkpoint, action, signal?)` pins source identity/boundary before waiting and selects exact parent authority plus an unoccupied child under one awaited exclusion. The caller rechecks native selection/policy and publishes its child lifecycle synchronously once. Parent evidence is revalidated before publication, the child cohort is CAS-protected, and only accepted memory installs. Cancellation or rejection cannot initialize an empty child; post-acceptance failure cannot roll it back or authorize another parent copy. Existing child storage, identity mismatch, missing parent files, malformed storage, concurrency conflict, or an expired boundary fails closed.
+**Copying and acceptance.** `TemporalRuntime.withForkTransaction(source, checkpoint, action, signal?)`:
+
+1. Pins source identity/boundary before waiting.
+2. Selects exact parent authority plus an unoccupied child under one awaited exclusion.
+3. Lets the caller recheck native selection/policy and publish its child lifecycle synchronously, once.
+4. Revalidates parent evidence before publication and protects the child cohort with CAS. Only accepted memory installs.
+
+Cancellation or rejection cannot initialize an empty child. Failure after acceptance cannot roll it back or authorize another parent copy. Existing child storage, an identity mismatch, missing parent files, malformed storage, a concurrency conflict or an expired boundary fails closed.
+
+**Forking while Off:**
 
-An Off native fork defers parent-header acquisition and canonical copying. Only a child-owned pending-fork marker is appended to the native trace; it carries no semantic authority. The marker survives cold extension reload and permits later explicit Passive/Active acquisition of the still-selected exact parent boundary, subject to the same identity, retention and occupied-child checks. Accepted initialization resets the marker. Parent expiry while Off is diagnosed only on explicit acquisition, never silently replaced with newer parent memory.
+- Parent-header acquisition and canonical copying are deferred. Only a child-owned pending-fork marker is appended to the native trace; it carries no semantic authority.
+- The marker survives cold extension reload and permits later explicit Passive/Active acquisition of the still-selected exact parent boundary, subject to the same identity, retention and occupied-child checks.
+- Accepted initialization resets the marker.
+- Parent expiry while Off is diagnosed only on explicit acquisition, never silently replaced with newer parent memory.
 
 Memory-enabled native fork adoption and Start's exact-source retry use this transaction inside the extension's owned restoration lifetime; the synchronous `prepareBoundaryFork()` adapter remains supported for library consumers. Both paths publish the fresh child origin before any runtime-only lifecycle write. Native evidence holds a publisher across fork adoption; it does not certify idle native Abort.
 
-A failed or expired selection never substitutes the parent's current/newer private state and never falls through to an older disabled marker. In the same live extension instance, explicit Start may retry the unaccepted fork after missing identity or storage evidence is corrected. Passive selection retains an in-flight fork or its activation-owned retry and applies Passive inside that existing acceptance. Off instead aborts the owned copy/retry before acceptance and records child-owned native Off/pending-fork policy without publishing memory; a later explicit Passive/Active request reacquires the exact source. Cancelling the Start waiter does not cancel that independently owned copy. After acceptance, Passive exposes both tools for child memory without active episode behavior, while Off exposes neither; ordinary memory-enabled cold reopening loads that child-owned state, while Off defers loading it. Off, selection, shutdown, native Abort, invalid source evidence and expired history still can prevent acceptance. Cold recovery before the first child-owned checkpoint remains unsupported without the explicit Off-deferred pending marker; missing child files alone never authorize a parent recopy. Once child storage has been accepted, explicit Start can activate its validated current child-owned memory even after selecting an inherited parent checkpoint; this neither restores parent history nor copies newer parent data. Child-owned checkpoints subsequently use ordinary retained-boundary reload/resume without rereading the parent header.
+**Retry and cancellation:**
+
+- A failed or expired selection never substitutes the parent's current/newer private state and never falls through to an older disabled marker.
+- In the same live extension instance, explicit Start may retry the unaccepted fork after missing identity or storage evidence is corrected.
+- Passive selection retains an in-flight fork or its activation-owned retry and applies Passive inside that existing acceptance.
+- Off aborts the owned copy/retry before acceptance and records child-owned native Off/pending-fork policy without publishing memory. A later explicit Passive/Active request reacquires the exact source.
+- Cancelling the Start waiter does not cancel that independently owned copy.
+- Off, selection, shutdown, native Abort, invalid source evidence and expired history can prevent acceptance.
+
+**After acceptance:**
+
+- Passive exposes both tools for child memory without active episode behavior; Off exposes neither.
+- Ordinary memory-enabled cold reopening loads that child-owned state; Off defers loading it.
+- Explicit Start can activate validated current child-owned memory even after selecting an inherited parent checkpoint. This neither restores parent history nor copies newer parent data.
+- Child-owned checkpoints use ordinary retained-boundary reload/resume without rereading the parent header.
+
+**Before the first child-owned checkpoint:** cold recovery requires the explicit Off-deferred pending marker. Missing child files alone never authorize a parent recopy.
 
-A child-owned passive-projection reset prevents copied parent Stop markers from resurfacing after child reload. Inactive sources retain their selected mode, including a same-owner native failed-Stop policy that could not reach canonical config. A child inherits neither that parent's write fence nor its passive projection; source history must still be provable and copying must pass CAS. Ordinary activation policy is not overridden. Nested forks require each direct parent boundary to remain retained; ancestry is not recursively reconstructed.
+**Mode and projection:**
+
+- A child-owned passive-projection reset prevents copied parent Stop markers from resurfacing after child reload.
+- Inactive sources retain their selected mode, including a same-owner native failed-Stop policy that could not reach canonical config.
+- A child inherits neither its parent's write fence nor its passive projection. Source history must still be provable, and copying must pass CAS; ordinary activation policy is not overridden.
+- Nested forks require each direct parent boundary to remain retained. Ancestry is not recursively reconstructed.
 
 ## Support boundary
 
-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.
+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, conversion of unsupported storage formats, unlimited history, and Git recovery are unsupported.
 
 ## Evidence
 
-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. Awaited runtime witnesses additionally hold an independent partial writer for over two seconds, cancel waiting copies, mutate admitted locators, expire source history during waiting, race parent/child bytes, serialize competing child acceptances, reject every occupied child file, roll back injected publication failure and retain accepted memory after checkpoint failure. Shared unknown metadata and unrelated provenance remain intact. Continuation tests cover header-only reading and refusal of non-regular or symlinked locators. The extension mode matrix holds storage across native fork selection or Start-owned fork retry. Stop returns with passive policy while the copy remains pending; release permits selected memory to be accepted with disabled policy. Passive patching and subsequent cold header/trace reopening through `SessionManager.open` retain independent child memory. Expired parent history still refuses without canonical writes or replacement checkpoints. These are isolated extension fixtures. A separate native SDK fixture observes the child through the public session factory before awaiting extension binding, sends Stop and optionally Start through the child's public `prompt` method while fork copying waits, and checks the requested mode, independent private state and next-provider patch after release. No private SDK hook or direct State Flow handler invocation is used. This proves a supported embedding route, not installed Telegram/TUI reachability before the child replaces the current runtime session.
+**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.
+
+**Awaited runtime witnesses** also:
+
+- hold an independent partial writer for over two seconds and cancel waiting copies;
+- mutate admitted locators and expire source history during waiting;
+- race parent/child bytes and serialize competing child acceptances;
+- reject every occupied child file;
+- roll back injected publication failure and retain accepted memory after checkpoint failure;
+- preserve shared unknown metadata and unrelated provenance.
+
+**Continuation tests** cover header-only reading and refusal of non-regular or symlinked locators.
+
+**The extension mode matrix** holds storage across native fork selection or Start-owned fork retry. Stop returns with passive policy while the copy remains pending; release permits selected memory to be accepted with disabled policy. Passive patching and subsequent cold header/trace reopening through `SessionManager.open` retain independent child memory. Expired parent history still refuses without canonical writes or replacement checkpoints. These are isolated extension fixtures.
+
+**A separate native SDK fixture** observes the child through the public session factory before awaiting extension binding. It sends Stop and optionally Start through the child's public `prompt` method while fork copying waits, then checks the requested mode, independent private state and next-provider patch after release. No private SDK hook or direct State Flow handler invocation is used.
+
+These tests prove a supported embedding route, not installed Telegram/TUI reachability before the child replaces the current runtime session.