@llblab/pi-kit 0.18.1 → 0.19.0

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

@@ -1,6 +1,6 @@
 # Temporal acceptance
 
-The numbering below follows the twenty required tests in the temporal design correction. This is a maintained property-to-test map, not a second backlog or a substitute for running tests. Paths and quoted test names refer to a source checkout; tests are not shipped in the npm runtime package.
+This is a maintained property-to-test map for the current canonical-file contract, not a second backlog or a substitute for running tests. Paths and quoted test names refer to a source checkout; tests are not shipped in the npm runtime package.
 
 ## Required properties and witnesses
 
@@ -8,62 +8,49 @@ The numbering below follows the twenty required tests in the temporal design cor
 2. **One patch:** `tests/temporal.test.ts` — “one patch shifts current to history and reads return detached materializations” checks new current state and the preceding checkpoint state.
 3. **Seven patches:** `tests/temporal.test.ts` — “seven patches and repeated eighth-patch folding preserve every hot state exactly” compares every effective/scoped offset with retained snapshots at seven transitions.
 4. **Eighth-patch folding:** The same test explicitly checks checkpoint advancement through T1, its absorbed value, and the retained T2–T8 tail, alongside every hot offset.
-5. **Repeated folding:** The same test repeats through forty transitions. `tests/git.test.ts` — “temporal Git writer preserves all hot states through sparse folding and cold revision reads” exercises persisted representation too.
+5. **Repeated folding:** The same test repeats through forty transitions; `tests/storage.test.ts` exercises the persisted canonical representation.
 6. **Sparse scopes share one target:** `tests/temporal.test.ts` — “sparse scope patches use effective boundaries, not each scope's mutation count” reproduces the T181–T184 example.
-7. **CWD indexing is not local-patch indexing:** That sparse test explicitly asserts both CWD offsets 1 and 2 equal C′. `tests/extension.test.ts` — “read_state lazily projects all hot offsets and scopes at one boundary without publication or Git calls” checks all 32 offset/scope combinations.
+7. **CWD indexing is not local-patch indexing:** That sparse test explicitly asserts both CWD offsets 1 and 2 equal C′. `tests/extension.test.ts` — “read_state lazily projects all hot historical paths and scopes without publication or Git calls” checks all 32 offset/scope combinations.
 8. **Shared multi-scope identity:** `tests/transition.test.ts` — “publishes one exact multi-scope replay cohort without explanatory windows or current-state DTOs” verifies one identity across changed scope records and exact replay.
 9. **Unchanged scopes stay stable:** The sparse temporal example checks global state at a boundary where only CWD/session change; “true no-ops do not enter history while response-only changes do” also checks that an unchanged session receives no new patch.
 10. **Historical deletion overlay:** `tests/temporal.test.ts` — “mixed sparse changes and deletion overlays match an independent snapshot oracle through compaction” explicitly checks session → CWD → global fallback and retained historical values.
 11. **Barrier shifts current to offset 1:** `tests/integration.test.ts` — “real Pi patch_state barriers rematerialize every scope before the next inference” observes the predecessor immediately after a barrier.
-12. **Next inference sees new current state:** The same real-Pi test inspects actual model-input projections after session, CWD, and global barriers. “real Pi reads prior scoped state lazily after a barrier and rejects offset eight without a transition” adds model-tool access to the predecessor.
+12. **Next inference sees new current state:** The same real-Pi test inspects actual model-input projections after session, CWD, and global barriers. “real Pi reads prior scoped state lazily after a barrier and rejects path offset eight without a transition” adds model-tool access to the predecessor.
 13. **No automatic old full-state duplication:** `tests/context.test.ts` — “projects only the latest seven compact accepted transitions” rejects full-state records in transition context. The real-Pi barrier test requires exactly one current runtime projection per inference. Explicitly requested history remains ordinary tool-result trajectory, not eager snapshot injection.
-14. **Accepted response changes are transitions:** `tests/extension.test.ts` — “the preserved answer stands after two fallback turns without final:true” and `tests/skills.test.ts` — “a late Skill obligation that outlives the fallback budget keeps the preserved answer” verify that a primary draft without a reconciled `final:true` is preserved as the runtime-owned response, fallback turns never enter `response`, and an exhausted fallback budget keeps the preserved answer with its current state. `tests/integration.test.ts` — “real Pi keeps the preserved answer after the fallback budget” repeats the closure through the native Pi turn loop.
-15. **Final-only eligibility creates no fake history:** `tests/extension.test.ts` — “a primary draft without eligibility is preserved as the response and final-only fallback resolution keeps it” checks that `{final:true}` latches turn eligibility without changing semantic lineage, tails, step, or Git. A later changed accepted response remains a runtime-owned transition.
-16. **Offset eight is outside hot history:** `tests/temporal.test.ts` — “hot range and unproven pre-migration history are explicit read boundaries”; the real-Pi history-reader test also exercises native tool rejection without a transition.
-17. **Cold Git history remains recoverable:** `tests/git.test.ts` — “temporal Git writer preserves all hot states through sparse folding and cold revision reads” loads older committed states without moving the worktree.
-18. **Tree/resume select the correct lineage:** `tests/integration.test.ts` — “real Pi preserves branch-local state through compaction, tree navigation, stop, and restart” and “real Pi old tree branch stop and resume preserve selected semantics without rewinding shared files”.
-19. **Stop changes config, not semantic history:** `tests/git.test.ts` verifies config-only persistence; `tests/runtime.test.ts` — “runtime-only Stop preserves live shared provenance and selected cold evidence” covers running/resumed sessions with a separate-process publisher: shared checkpoint/tail/provenance bytes remain unchanged, only the stopped session's runtime pair changes, and cold restoration pairs its selected state with matching provenance without a semantic step; `tests/integration.test.ts` — “real Pi mid-tool Stop retains the active trajectory through tree, reload, resume, and restart” covers ordinary/bootstrap runs, results on both sides of Stop, paired calls/results, preserved native trace, and exclusion of completed or abandoned branch history. `tests/extension.test.ts` covers idle/legacy cutoffs and new/fork boundaries; `tests/context.test.ts` covers steering, foreign custom context, and removal of private feedback.
-20. **Lossless current-state migration:** `tests/migration.test.ts` — “migration anchors exact current materializations and never replays explanatory journals”; `tests/git.test.ts` — “migrates all three current snapshots in one isolated commit without losing semantic or cold history”; runtime tests cover revision-linked migration with malformed explanatory history.
+14. **Accepted response changes are transitions:** `tests/extension.test.ts` — “accepts only canonical materially changing atomic scope patches” verifies that an ordinary accepted answer becomes runtime-owned `response` without a finalization patch or fallback inference.
+15. **No-op mutation signals are rejected:** The same extension test rejects empty and obsolete finalization-shaped calls, while a changed accepted response remains a runtime-owned transition.
+16. **Configured hot-history bounds:** `tests/temporal.test.ts` verifies hot-range and unavailable pre-origin boundaries; the real-Pi history-reader test rejects offset eight at the default limit seven without a transition. `tests/config.test.ts` exercises materialized and scope patch-history paths at limits 0, 1, 7, and 12, including single-path/one-item batch reads above seven and distinct configured versus actually retained boundaries.
+17. **Selected history fails closed:** `tests/recovery.test.ts` proves every failure resolving a selected retained boundary refuses without falling through to older boundaries or disabled markers. `tests/extension.test.ts` covers all passive bootstrap/tool combinations; the native “real Pi expired selection cannot reset private state through passive Start, Stop, patch, or reload” witness preserves exact canonical bytes and Pi checkpoints while allowing shared reads. Fork identity/CWD repair witnesses retry the original source with passive access both enabled and disabled.
+18. **Tree/resume select the correct lineage:** `tests/integration.test.ts` — “real Pi preserves branch-local state through compaction and rejects an expired sibling after fresh-origin navigation” and “real Pi old tree branch stop and resume preserve selected semantics without rewinding shared files”.
+19. **Stop changes config, not semantic history:** `tests/runtime.test.ts` lifecycle-only witnesses use a separate process to advance global/CWD semantics or provenance, including wider foreign retention, then prove exact semantic/sidecar preservation, unchanged steps, idempotent Stop, and same-session/stale-evidence refusal. Native Stop/new-request witnesses verify the accepted shared view reaches handoff/inference without a lifecycle semantic write, while a shared write racing after inference still fails closed. Mid-tool Stop tests preserve ordinary/bootstrap trajectories through tree, reload, resume, and restart. The native “real Pi retains a native split-turn continuation through late tools” Stop/no-Stop controls actually remove the original user with native threshold compaction, then require summary, paired reads and foreign context in model input. The Stop case also checks frozen semantics/step, unchanged trace prefix, tree/reload/cold resume/bootstrap restart, no resurrection of discarded input, and persistent foreign context after the next active run. Pure passive-selector tests cover missing, colliding and nonfinite recorded active anchors without changing idle/legacy cutoffs. `tests/storage.test.ts` fences lifecycle-only writes to config/runtime files; `tests/extension.test.ts` covers idle/legacy cutoffs and new/fork boundaries.
 
 ## Additional preservation boundaries
 
-- `tests/durable.test.ts`, `tests/git.test.ts`, and `tests/migration.test.ts` cover owned regular files, raw-byte rollback, prepared-output receipts, stale/omitted-scope CAS, linked-worktree publication exclusion, unrelated staging, and exact-commit push retry.
-- `tests/git.test.ts` prepared-index witnesses require one batch for all prepared blobs, exact committed bytes despite ordinary staging ignores, literal punctuation/tab/newline paths, complete non-ignored worktree capture, and private-index cleanup. A malformed record appended after valid records must leave HEAD, owned files, caller index, and unrelated bytes unchanged, then permit one accepted retry. The same focused family passes in existing SHA-256 stores with `GIT_DEFAULT_HASH=sha256 node --test --test-name-pattern='prepared Git cohorts|malformed batch after' tests/git.test.ts`; it asserts actual 64-digit commits rather than assuming the environment setting was honored. Migration deletion and failed caller-index synchronization remain covered separately.
-- `tests/publication.test.ts` uses `tests/publication-worker.ts` to pause real dead-PID observations and the removal/creation gap in separate processes. It proves one live lease, retention of a winning fresh claim, malformed/symlink and foreign-owner protection, and fresh acquisition/release remaining possible during queue writes. These are cooperating-writer guarantees, not arbitrary crash-window or nonparticipating-writer CAS.
-- `tests/git.test.ts` verifies native exact-target push/fast-forward protection, spawn failure, a real blocked child's hard termination at the simulated 15,000ms deadline, abort-listener cleanup, and an inherited pipe outliving its child. `tests/extension.test.ts` checks retryable timeout state, a 2,000ms shutdown wait with a refused signal, retained ownership until actual exit, and fencing of a late successful callback. `tests/integration.test.ts` exercises native Pi quit dispatch and actual reload with blocked synthetic push processes: the old child exits before lease handoff, newer targets survive unchanged, and only the replacement generation resumes the queue. `tests/push-fixture.ts` intercepts asynchronous Git execution only; no external remote or model actor is involved.
-- `tests/integration.test.ts` native new/resume/fork replacement witnesses use public `AgentSessionRuntime` and `setBeforeSessionInvalidate()` to require child exit and lease handoff before replacement. They preserve outgoing files, accepted cold state, descendant queued targets and old-generation fencing. Fork witnesses additionally cover selected session-stream copying over current shared layers, child-owned reload/resume and mutation, stopped-source projection fencing, identity/CWD refusal with same-instance Start retry, and inherited-pointer refusal without falling through to a reset marker. `tests/runtime.test.ts` adds seven-record/provenance copying, live/HEAD namespace collision, CAS and file-source expiration checks. This supports the bounded [fork contract](fork-contract.md), not arbitrary pre-fork Git-history adoption.
-- `tests/recovery.test.ts` and `tests/runtime.test.ts` distinguish invalid immutable targets from transient publication failures, preserve checkpoint provenance, and prevent invalid-only recovery from becoming permission to replace runtime. Prepared-restore witnesses require detached inspection data, single use, fresh same-session publication bases, no partial installation under live exclusion, owner normalization, and revalidation of expired file cohorts. The native “real Pi restoration reads each selected Git tree once across reload and resume” witness counts actual tree queries for enabled and config-only stopped pointers while checking every offset/scope projection.
-- `tests/git.test.ts` — “large Git-backed checkpoint, tail and runtime blobs survive cold reads and later publication” checks UTF-8 documents beyond Node's default subprocess-output budget, selected cold semantics, runtime-only Stop and unchanged live files/branch during inspection. The native “real Pi retains large state and accepted answers across reload, resume and a large specification” witness preserves the exact session/leaf/revision and earlier response boundaries, then accepts a new run with large runtime metadata.
-- `tests/git.test.ts` tree-catalog witnesses cover one exact tree query per selected revision/cohort, per-path blob reuse, literal metacharacter/tab/newline paths and inherited literal-path settings, unused malformed fallback isolation, incomplete/ambiguous catalog rejection, and fresh mode validation after HEAD advances. Existing symlink, omitted-stream, cold-history, migration, prepared-output and CAS regressions remain required; batching cannot replace file validation with working-tree equality.
-- `tests/publication.test.ts` — “queue commit boundaries reject non-string values without coercion or side effects” covers constructor, parser/serializer, store, coalescing, confirmation, and worker input. Malformed files remain byte-identical, ancestry/push callbacks stay unused, and exact scalar strings still round-trip. `tests/git.test.ts` rejects coercible asynchronous push targets before creating a child.
+- `tests/continuation.test.ts` independently advances global/CWD at limits 0/7, then proves read-only eligibility agrees with actual restore and preserves the session layer, including shared-only transitions. `tests/temporal.test.ts` covers sparse/inherited session lineage, conflicting checkpoint/tail identities and parents, future patches, and immutable inputs. The runtime restore/fork contradiction witnesses preserve source/target files rather than accepting a new origin over mixed session files. The native “real Pi refuses contradictory session files without passive substitution and retries the repaired selection” witness retains shared access, fences session access/Start/Stop, preserves the selected checkpoint, and succeeds after exact-source repair. These are synthetic integrity tests, not evidence of spontaneous cross-session leakage.
+- `tests/extension.test.ts` distinguishes pre-runtime Stop from accepted-runtime Stop across passive configurations: global-only and shared storage remain unchanged, repeated Stop/reload retain the disabled marker, and subsequent Start/passive patch establishes a retained session boundary. Malformed/incomplete scope files remain unavailable; Stop does not repair CWD-only storage, while explicit Start may initialize its wholly absent global scope. The native “real Pi Stop preserves a global-only passive branch through reload, patch, and Start” witness checks the same lifecycle without Git. `tests/invariants.test.ts` rejects the retired Skill converter in both package and domain exports; existing Skill/transition witnesses preserve real source hashing, hashing failure, and retired-field rejection.
+- `tests/durable.test.ts` and `tests/storage.test.ts` cover canonical-format rejection, owned regular files, raw-byte rollback, prepared-output receipts, stale/omitted-scope CAS, literal paths, malformed cohorts, and shared-writer exclusion.
+- `tests/git.test.ts` proves settled backup preserves unrelated staged/index-only/worktree data, already-staged owned deletions, Git ignore/filter policy, literal paths, and opaque bytes. Controlled Git pauses before/after snapshot capture allow an independent canonical writer to advance and create a new scope; the commit must match exactly one captured cohort, never mixed live bytes. Every observed Git command runs outside the backup's canonical lock. Namespace/type witnesses exclude unrelated traversal and refuse non-regular sources. No-op/unowned-only initial backups skip; Git/index failures preserve canonical acceptance and caller data. `tests/episode.test.ts` proves one diagnostic-only attempt at `agent_before_settle`, without answer changes or an automatic retry.
+- `tests/integration.test.ts` native new/resume/fork witnesses preserve canonical files and retained boundaries. Fork witnesses cover selected private state over current shared layers, fresh child ownership, reload/resume, disabled-source fencing, identity/CWD refusal, retry, and expired-boundary refusal. `tests/runtime.test.ts` restore/fork provenance witnesses preserve current-head, untouched-path, and shared evidence while discarding evidence for later-changed private artifacts, including change-away-and-back. The test-only provenance reader is checked against nonempty canonical `meta.json` evidence in every scope before and after reload; native restore/fork tests verify missing-evidence invalidation, explicit recompilation, parent preservation, and provenance across reload.
+- `tests/recovery.test.ts` and `tests/runtime.test.ts` distinguish malformed checkpoints from expired retained boundaries, prevent fallthrough or newer-state substitution, and require detached single-use restoration followed by canonical origin acceptance.
 - `tests/extension.test.ts` — “tool preflight walks only the selected native suffix for matching calls, without rebuilding a branch” uses real in-memory `SessionManager` trees with zero/two hundred prior request-answer pairs, intervening custom/results, and a later unselected assistant reusing a call ID. It requires exact parent visits, no full-branch construction, preserved sibling/duplicate-patch rejection and unchanged complete native entries. The native sibling-tool witness in `tests/integration.test.ts` separately observes all three start/end events and requires zero branch reads during preflight/execution while accepting the correct state/answer.
-- `tests/context.test.ts` — “enabled context projects the complete overlay once in ordinary and bootstrap runs” counts one full-overlay clone at 8 KiB and 1 MiB while preserving selected/cached state, native entries, input messages and artifact semantics. “current run trajectory allocates no arrays of discarded ordinary history” observes source-derived arrays after zero/two hundred historical request-answer pairs while preserving foreign context, current tools, steering, reference identity and order. Anchor tests cover repeated requests, stale/missing anchors, absent users and empty specifications. The native barrier witness separately counts one marked full-overlay clone per post-barrier `emitContext()` invocation; it still requires each next inference to see all accepted scope changes.
-- `tests/compaction.test.ts` owns State Flow's completed-run compaction policy: large-history eligibility, final-assistant retention, generation-private invocation, foreign-custom refusal, queued-work exclusion, stale selection, benign preparation refusal and shutdown fencing. Native integration proves one accepted run compacts without another faux-model call, shortens `buildContextEntries()` across reload/cold resume while preserving full JSONL/tree/state/UUID, and leaves threshold compaction after partial tool work native until a later accepted patch/answer.
+- `tests/context.test.ts` — “enabled context projects the complete overlay once in ordinary and bootstrap runs” counts one full-overlay clone at 8 KiB and 1 MiB while preserving selected/cached state, native entries, input messages and artifact semantics. “current run trajectory allocates no arrays of discarded ordinary history” observes source-derived arrays after zero/two hundred historical request-answer pairs while preserving foreign context, current tools, steering, reference identity and order. Anchor tests prefer captured identity over normalized text, retain images/tools/steering, and preserve available context on missing/nonfinite/colliding identities or ambiguous specification matches; unique text fallback remains projection-only. The native barrier witness separately counts one marked full-overlay clone per post-barrier `emitContext()` invocation; it still requires each next inference to see all accepted scope changes.
+- `tests/compaction.test.ts` owns State Flow's completed-run compaction policy: captured run-anchor retention across steering/tools, missing/ambiguous/unfinished-anchor refusal, large-history eligibility, generation-owned invocation, foreign `custom`/`custom_message` prefix refusal, queued-work exclusion, stale selection, benign preparation refusal and shutdown fencing. Its harness emits native user `message_end` and checks that repeated projection plus steering cannot promote missing, ambiguous or unobserved anchors into compaction authority. The native “real Pi compaction retains the original run through steering, tool results, and foreign context” cases actually compact plaintext and SDK-normalized image requests with two steering messages, a successful read/patch, and persisted custom context; image/read-result evidence reaches later model calls, exact message ids survive reload, the trace prefix stays byte-identical, and no model summary is requested. The short “real Pi retains a normalized image and read evidence through steering without compaction” controls check State Flow enabled/disabled parity before any compaction. Existing native witnesses cover ordinary compaction/cold resume and leave threshold compaction after partial tool work native.
+- `tests/integration.test.ts` — “real Pi boundary continuation keeps accepted State Flow memory” exercises actual companion `turn_end` and `agent_before_settle` draft entries and continuation. Each next provider input has exactly one current-memory projection before/after a continued patch, the accepted response and current tool declarations. There is only one `before_agent_start`, no restored specification in runtime checkpoints or model projection, exactly one requested continuation and correct final response/step. The pure “projects accepted memory without resurrecting a completed specification for boundary continuation” witness preserves source state, omits lazy bodies, and keeps available context when both specification and native capture are absent.
+- `tests/integration.test.ts` — “real Pi context edits remain canonical through tools, tree selection and reload” proves native user-content replacement, assistant/custom-message omission and live tool-result replacement reach provider input without resurrecting raw history. Selecting an unedited branch restores its native view without overwriting accepted semantic files; selecting the edited branch and reloading preserves its edits and independent memory. Raw JSONL stays append-only.
+- `tests/integration.test.ts` — “real Pi structured prompt composes with context hooks” covers active, passive, disabled and explicit foreign-force modes. Conversation hooks exclude systems; full-system hooks receive them; companion before-run and per-request sections plus actual tool declarations survive. User specifications remain outside system authority. Stop/Start on subsequent user requests removes/reinstates the owned section once.
+- `tests/integration.test.ts` — “real Pi preserves native run identity across mode toggles” covers initially enabled, mid-tool Start and repeated Start/Stop with passive bootstrap on/off. Actual provider inputs retain original user/read evidence but not the preceding disabled request; persisted Stop markers name the observed native user, and fixture reload preserves trajectory, frozen state and raw trace prefix. `tests/compaction.test.ts` — “native session boundaries invalidate observed run capture without projection reacquisition” pairs session-start/tree resets with an admitted unchanged-run control. No new stored field or guessed anchor is used.
+- `tests/integration.test.ts` — “real Pi refreshes protocol within the same run” covers mid-read Stop, passive Stop, mid-read Start and accepted-boundary Stop/continuation. The next provider request has current protocol/tools, foreign context and tool evidence, no elevated specification and only one user-run preparation; response reconciliation follows the actual mode and earlier native system frames remain intact. `tests/context.test.ts` — “refreshes only owned system protocol without mutating native frames” covers old/replaced/deleted sections, foreign content/tools, conversation identity/order, frozen inputs, absent-frame non-synthesis and unchanged-delta no-ops.
+- `tests/integration.test.ts` — “real Pi recovery omits failed attempts without accepting them” checks retry/length/overflow through actual SDK dispatch: durable omission edits, raw trace preservation, unchanged accepted response/step until successful recovery, native split-turn summaries and fixture reload. “real Pi edited-context accounting discards stale provider usage” checks reduced native usage after replacement and one subsequent inference without phantom compaction.
+- `tests/integration.test.ts` — “real Pi settled dispatch preserves deferred companion work” covers low pressure, real owned compaction and explicit compaction refusal. The native completion/error callback finishes before settled dispatch returns; all companion observers precede exactly one deferred request, which sees accepted memory and reconciles the expected response/step. The admitted case verifies an actual State Flow-owned compaction rather than relying only on a token estimate.
+- `tests/integration.test.ts` — “real Pi applies image profiles only to newly admitted images” compares actual PNG payload dimensions for wide/tall prompt images, built-in image reads and generic tool-result images under two native model profiles. Switching to smaller bounds preserves prior user/read/tool payload bytes through later provider inputs and reload, with disabled/enabled controls and detached caller images. The settled-dispatch witness also inspects actual system prompt and tool declarations after owned compaction, not just scripted execution.
+- `tests/json.test.ts` and `tests/transition.test.ts` characterize detached public results and rejected mutable drafts, prototype-named merge isolation, signed zero and single-copy cold-data boundaries. Existing artifact replacement, failed publication, replay/fork and late-response tests remain applicable. The owned-draft COW differential/copy-work evidence in [performance](performance.md#memory-only-owned-draft-cow) is semantic/alias evidence, not a persistence-format or end-to-end speed claim.
 - `tests/context.test.ts` and `tests/extension.test.ts` prohibit process queries during ordinary context/history reads. `tests/transition.test.ts` rejects stale staging even when semantic values coincide across different causal boundaries.
 - `tests/status.test.ts` distinguishes selected temporal history depth from retained per-scope tails and unavailable materialization from an empty state.
-- `tests/artifact.test.ts` and `tests/discovery.test.ts` require explicit removal evidence, partition root/extension/symlink ownership, and preserve state when the root is unavailable. The native “real Pi discovery preserves foreign artifacts and unavailable roots, then removes only proven missing Markdown after status and reload” witness checks byte preservation, truthful status, and replayable removal after inspection/reload.
-- `tests/transition.test.ts` rejects authored provenance fields and field deletions in every scope through both staging entrypoints, without requiring a preceding read; legacy semantic edits and whole-artifact deletion remain valid. The native “real Pi rejects no-read freshness forgery atomically and accepts a corrected model patch” witness proves whole-cohort rejection and recovery, while existing artifact/Skill tests preserve runtime-owned refresh and legacy decoding.
-- `tests/storage.test.ts` covers Git absence, exact file-cohort references, file CAS/rollback and shared writer exclusion. `tests/runtime.test.ts` and the native Pi Git-absent lifecycle test cover file-pointer restart, immediate barriers, finalized response, config-only stop, and unavailable-reference provenance. File-only mode supplies current/hot state; Git-dependent cold and arbitrary branch recovery require Git and the original committed objects.
-- File-to-Git tests in `tests/storage.test.ts`, `tests/runtime.test.ts` and the native Pi lifecycle cover full-cohort adoption over unborn/stale HEAD, exact inherited bytes, unchanged semantic step/hot history, rollback, staging preservation and subsequent configured-remote publication. `tests/git.test.ts` rejects omitted uncommitted streams; working-tree equality alone cannot prove a Git commit contains the selected state.
-- `tests/config.test.ts` covers optional agent configuration, path precedence/expansion, invalid input, load-time caching and read-only behavior. Session tests and native Pi distinguish configured new-session auto-start from branch-local resume/tree/stop. `tests/extension.test.ts` proves activation defers Markdown discovery until the next enabled inference. The global default is manual; CWD materialization alone no longer grants automatic activation.
-
-## Fatal writer interruption
-
-`tests/runtime.test.ts` — “fatal publisher interruption preserves selected history and fails closed” uses `tests/runtime-worker.ts` for four same/different-CWD × before/after-ref cases. A separate process first accepts a global/CWD/session cohort while session A retains an older seven-transition selection, then pauses its next real publication around `git update-ref`:
-
-| Boundary | HEAD at termination | Caller-visible index |
-| --- | --- | --- |
-| Before ref CAS | Previous accepted peer commit; the attempted commit object already exists | Exact pre-attempt bytes |
-| After successful ref CAS | New, unacknowledged peer commit | Still the pre-attempt bytes; synchronization was not reached |
-
-The parent sends `SIGKILL` only to its owned, paused process group and requires actual closure with that signal and a gone PID. Both cases retain the publication locks; attempted writes and prepared/fresh restore installation fail closed without installing a partial runtime. Exact earlier commits, all 32 selected hot/cold projections, another session's private files, interrupted owned bytes/modes, unrelated worktree bytes and caller index survive. The attempted commit contains the complete non-ignored worktree delta and all three new scope values, but the interrupted call never returns success. Tests perform no lock clearing, automatic repair, ref reset or store checkout.
-
-The pause is synchronous after previous Git subprocesses have exited. This is process-death evidence at those Git boundaries, not in-flight Git-child containment, file-only crash recovery, power-loss/fsync durability, native Pi trace interruption or Windows signal behavior; these four POSIX tests are skipped on Windows. Ordinary inference abort remains the [same-session preservation behavior](usage.md#session-behavior), not this fatal-publication scenario.
-
-```bash
-node --experimental-strip-types --test \
-  --test-name-pattern='fatal publisher interruption' tests/runtime.test.ts
-```
+- `tests/artifact.test.ts` and extension/native integration witnesses prove exact registered-path inspection, `size + mtimeNs` evidence, non-destructive unavailable/symlink handling, owning-scope removal, runtime-only changed-source hints, and stable-read acceptance without directory discovery. The native newly-adopted-artifact witness proves run preparation refreshes live shared state before proven-missing maintenance and the first inference. Artifact/acquisition/rehydration tests and “real Pi ordinary artifact invalidations share the public fingerprint classifier” cover equal/changed/missing/malformed fingerprints, pre-epoch timestamps, compiler invalidation, detached read plans, legacy hash handling, and effective Skill masking while preserving Skill hashing.
+- `tests/protocol.test.ts` checks runtime/Skill guidance names the reported artifact owner. Transition and native three-scope compilation witnesses reject wrong-scope output with an exact owning-scope target, preserve canonical bytes on failure, and accept stable recompilation without unrelated-scope writes; native reload retains the accepted provenance.
+- `tests/transition.test.ts` rejects authored provenance fields and field deletions in every scope through both staging entrypoints, without requiring a preceding read; legacy semantic edits and whole-artifact deletion remain valid. The native “real Pi rejects no-read provenance forgery atomically and accepts a corrected model patch” witness proves whole-cohort rejection and recovery, while existing artifact/Skill tests preserve runtime-owned compilation evidence and legacy decoding.
+- `tests/storage.test.ts` covers exact file-cohort references, file CAS/rollback, and shared writer exclusion. `tests/runtime.test.ts` and native Pi lifecycle tests cover retained-boundary restart, immediate barriers, finalized response, config-only stop, and unavailable-reference provenance. Canonical files supply current state and bounded hot history; arbitrary cold revision recovery is unsupported.
+- `tests/runtime.test.ts` and native integration cover retained-boundary restoration and fork after lowering `historyLimit` to 0/1: current shared values/provenance and selected private state survive folding, parent-private fork files remain unchanged, out-of-window selections fail closed, and later increases do not reconstruct discarded history. `tests/config.test.ts` covers optional agent configuration, path precedence/expansion, invalid input, load-time caching and read-only behavior. Session tests and native Pi distinguish configured new-session auto-start from branch-local resume/tree/stop. `tests/extension.test.ts` proves registered artifacts are reconciled only at enabled inference boundaries. The global default is manual; CWD materialization alone no longer grants automatic activation.
 
 ## Validation and limits
 
@@ -71,4 +58,4 @@ Run `npm run validate` in the source checkout; the [SDK compatibility matrix](co
 
 Benchmark contracts in `tests/benchmark.test.ts` and `tests/benchmark-session.test.ts` separately verify source-drift rejection, oversized terminal-report delivery with correct failure status, optional phase resources, immutable prefix counters, release after measurement failure, and isolated post-resume probes. Probes check selected model projection and exact delivery of the current native read content; workers that mutate baseline JSONL or repository files after reporting success are rejected. Native-read witnesses distinguish full UTF-8, byte-truncated and line-truncated output, retain source-versus-notice byte counts and release observers after success/failure. A rewritten model-facing read that becomes a faux assistant error must fail the native terminal check, not be counted as a successful run. These correctness tests impose no wall-time performance threshold. The [performance guide](performance.md) owns measurements and their limits.
 
-Real-Pi tests use the actual Pi SDK and native tool loop with a deterministic faux model and temporary Git repositories. They do not prove that an unconstrained model always follows the memory protocol, nor do they migrate production Knowledge or publish the real repository. Complete native trace remains available; normal model projection retains only the required active context. Cooperative locking and conflict preservation are not kernel-atomic multi-file transactions against nonparticipating writers. Test counts do not establish exhaustive equivalence with every removed predecessor assertion.
+Real-Pi tests use the actual Pi SDK and native tool loop with a deterministic faux model and temporary Git repositories. They do not prove that an unconstrained model always follows the memory protocol, nor do they inspect/repair production stores or publish the real repository. Complete native trace remains available; normal model projection retains only the required active context. Cooperative locking and conflict preservation are not kernel-atomic multi-file transactions against nonparticipating writers. Test counts do not establish exhaustive equivalence with every removed predecessor assertion.

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

@@ -8,19 +8,20 @@ For the concept and installation, start with the [README](../README.md). This gu
 
 - **New session:** Passive durable memory is available by default without starting an episode. `autoStart` promotes genuinely new sessions into active State Flow; an active new session has its own empty session layer and inherits global/CWD state, never another session's private continuation.
 - **Resume:** Restores the selected session's stored enablement, state, and lineage. Agent-level `autoStart` does not override a resumed branch.
-- **Tree navigation:** Restores the selected checkpoint and recorded state revision without checking out or resetting the shared store.
+- **Tree navigation:** Restores the selected retained private boundary over live shared scopes without checking out or resetting the shared store.
 - **Abort inference:** Stops generation while already accepted patches remain durable for continued work and corrected direction in the same session. It does not roll back memory or require immediate remote replication.
-- **Stop:** Ends active episode semantics and returns to the configured passive bootstrap/tool combination. It preserves state, creates no semantic transition, and does not change passive or automatic-start policy.
-- **Continue after Stop:** The same physical session retains a frozen state handoff, any interrupted current request and tool trajectory (including late results), and post-stop conversation. Completed earlier conversation stays excluded, while other extensions' custom context survives. Reload/resume/tree preserve this projection; new/forked physical sessions do not inherit it. Active restart uses it for one bootstrap run.
-- **Completed-history compaction:** After an accepted run settles without queued input, State Flow asks Pi for a native compaction boundary only when public context usage reaches 24,000 tokens. No extra model summary is requested; Pi keeps the complete latest user iteration—from its request through tools and final answer—in active history and retains the complete append-only JSONL/tree. On resume, native `buildContextEntries()` and TUI rendering omit the older completed prefix. Unknown or smaller usage skips the request, and custom Pi retention settings may still decline it benignly. Foreign custom context in the removed prefix, bootstrap/fallback/abort/error, Stop and pending input prevent State Flow-owned shortening; ordinary manual/threshold/overflow compaction remains native and may preserve unfinished work not yet patched into memory.
+- **Native boundary continuation:** A companion may continue through Pi's `turn_end` or `agent_before_settle` boundary without a new user prompt. State Flow keeps projecting current memory and accepted response across those requests and subsequent patches; it does not restore the completed specification or request another turn itself.
+- **Stop:** Ends active episode semantics and returns to the configured passive bootstrap/tool combination. For a proven pre-runtime branch, it records only the existing disabled checkpoint in Pi, without creating canonical files or publishing the passive view; later Start or passive patch remains available. For an accepted runtime, it adopts unrelated shared-state changes without semantic/provenance writes or step changes, while same-session conflicts still fail closed. Its frozen handoff uses the accepted view. It does not change passive or automatic-start policy.
+- **Continue after Stop:** The same physical session retains a frozen state handoff, any interrupted current request and tool trajectory (including late results), and post-stop conversation. A proven active boundary excludes completed earlier conversation; when native split-turn compaction removed the original request anchor, Stop instead preserves the available summary and tools without reconstructing discarded raw input. Other extensions' custom context survives. Idle Stop still retains only later conversation plus foreign custom context. Reload/resume/tree preserve this projection; new/forked physical sessions do not inherit it. Mid-tool Start and repeated Start/Stop retain the first user event already observed while disabled, so subsequent Stop does not mistake that busy run for idle. Active restart uses the retained projection for one bootstrap run.
+- **Completed-history compaction:** After an accepted run settles without queued input, State Flow asks Pi for a native compaction boundary only when public context usage reaches 24,000 tokens. No extra model summary is requested; Pi keeps the complete latest run—from its original request through steering, tools, foreign context and final answer—in active history and retains the complete append-only JSONL/tree. State Flow uses the native first-user anchor, independent of image-normalization hints or later steering; images and earlier tool results remain available to the model. Uncertain projection retains available context without changing that anchor. A missing or ambiguous native anchor skips compaction instead of choosing the last steering message. On resume, native `buildContextEntries()` and TUI rendering omit the older completed prefix. Unknown or smaller usage skips the request, and custom Pi retention settings may still decline it benignly. Foreign custom context in the removed prefix, bootstrap/abort/error, Stop and pending input prevent State Flow-owned shortening; ordinary manual/threshold/overflow compaction remains native and may preserve unfinished work not yet patched into memory.
 
 State Flow does not undo tool effects. After interruption or returning to an older branch, check the relevant workspace or external system before repeating consequential operations. Restored memory is not restored reality.
 
 ### Fork support and limits
 
-Native fork replacement copies the source session checkpoint, retained patch tail and matching provenance into the new session's own storage. Global/CWD streams and provenance stay current and unchanged. An earlier fork selection copies that point's private state, not the parent's later private work. Parent data/history remain intact; selected enablement is retained, so a stopped source does not become enabled automatically.
+Native fork replacement copies the source session checkpoint, retained patch tail and matching provenance into the new session's own storage. Global/CWD values and provenance stay current; applying a smaller `historyLimit` may fold shared tails under CAS. An earlier fork selection copies that point's private state, not the parent's later private work. Parent-private data/history remain intact; selected enablement is retained, so a stopped source does not become enabled automatically.
 
-The child starts at step zero and a new temporal origin. Its copied tail is preserved, but pre-origin records are not seven past aligned causal boundaries addressable through `effective[n]` or scoped paths. The child's own transitions build its hot window; owned checkpoints support normal reload/resume. Parent Stop projection is not inherited, including after child reload.
+The child starts at step zero and a new temporal origin. Its copied tail obeys the configured retention limit, but pre-origin records are not additional aligned causal boundaries addressable through `effective[n]` or scoped paths. The child's own transitions build its hot window; owned checkpoints support normal reload/resume. Parent Stop projection is not inherited, including after child reload.
 
 Initial copying requires a native fork start event, a regular canonical direct-parent session file, matching CWD/identity, a readable temporal source and an unused child namespace. Missing/unsafe evidence or CAS conflicts leave the copy unavailable rather than importing unrelated or newer private state. Explicit Start can retry an unaccepted copy in the same loaded fork after the cause is corrected.
 
@@ -37,25 +38,25 @@ Optional global `config.json` at the root of the State Flow repository, normally
   "passiveTools": true,
   "logging": false,
   "showSuccessfulPatches": true,
-  "remotePublication": "turn-end"
+  "historyLimit": 7
 }
 ```
 
 The canonical store is `state-flow/` beneath the agent directory. Keeping configuration inside that repository removes the separate agent-level `state-flow.json`; SDK embeddings may still provide an explicit repository override.
 - `autoStart`: Defaults to `false`. When `true`, genuinely new sessions use the same initialization as explicit Start, including fresh CWDs.
-- `passiveBootstrap`: Defaults to `true`. Projects existing effective durable memory into ordinary model context without creating scopes, migrating storage, publishing, or starting an episode.
-- `passiveTools`: Defaults to `true`. Exposes `read_state` and `patch_state` outside active episodes. Reads remain side-effect free; the first explicit patch may initialize or migrate storage but does not enable continuation, terminal barriers, or compaction.
-- `logging`: Defaults to `false`. When enabled, records rejected patches and unresolved terminal/fallback diagnostics locally at `tmp/state-flow/logs.jsonl` beneath the agent directory.
-- `showSuccessfulPatches`: Defaults to `true`. In interactive Pi, successful `patch_state` rows show only the applied pretty-printed JSON arguments, with blank lines between adjacent memory sections; set it to `false` to keep only the compact summary. Rejected calls still use ordinary error rendering and private validation details are never added.
-- `remotePublication`: New-runtime policy: `turn-end` queues the newest accepted commit for asynchronous push; `off` keeps commits local; `transition` retains synchronous compatibility behavior. Existing branches keep their persisted policy.
+- `passiveBootstrap`: Defaults to `true`. Projects existing effective durable memory into ordinary model context without creating scopes, publishing, or starting an episode.
+- `passiveTools`: Defaults to `true`. Exposes `read_state` and `patch_state` outside active episodes. Reads remain side-effect free; the first explicit patch may initialize absent canonical storage but never converts predecessor formats or enables an episode or State Flow compaction.
+- `logging`: Defaults to `false`. When enabled, records rejected patches and accepted-answer reconciliation failures locally at `tmp/state-flow/logs.jsonl` beneath the agent directory.
+- `showSuccessfulPatches`: Defaults to `true`. In interactive Pi, successful `patch_state` rows show only the applied pretty-printed JSON arguments, with blank lines between adjacent memory sections; set it to `false` to keep only the compact summary. Rejected calls still use ordinary error rendering; State Flow adds no private validation turn.
+- `historyLimit`: Defaults to `7` and accepts integers from `0` through `100`. It bounds materialized-history and scope patch-history offsets. Lowering it on reload/restore/fork folds excess tails forward without losing current state; selected boundaries outside the new window are unavailable. Zero retains only current checkpoints. Raising the limit affects only future retention and cannot reconstruct discarded history.
 
 Settings are read once at extension load. After editing, use `/reload` or restart Pi. A missing file uses defaults without creating a configuration file; malformed JSON, unknown keys, or invalid values fail loading rather than silently selecting another store.
 
-`PI_CODING_AGENT_DIR` changes both the default State Flow repository and its global configuration location. It does not redirect Knowledge discovery, whose default remains `knowledge/` beneath the agent directory. SDK repository overrides are documented under [embedding](architecture.md#embedding); an overridden repository owns its own root `config.json`.
+`PI_CODING_AGENT_DIR` changes both the default State Flow repository and its global configuration location. State Flow has no source-directory or Knowledge-root configuration. SDK repository overrides are documented under [embedding](architecture.md#embedding); an overridden repository owns its own root `config.json`.
 
 ### Diagnostic logging and privacy
 
-Rejected-call records may contain exact attempted arguments and useful draft text, plus the error, tool/call identity, and resolution state. Successful patches are not logged; reasoning bodies are excluded. Logs are not semantic state, scope metadata, Pi checkpoints, or publication input. If the log path overlaps a custom state repository, capture fails closed instead of committing it. A logging failure changes no accepted state and produces at most one local warning.
+Rejected-call records may contain exact attempted arguments and useful draft text, plus the error category and tool/call identity. Successful patches are not logged; reasoning bodies are excluded. Logs are not semantic state, scope metadata, Pi checkpoints, or publication input. If the log path overlaps a custom state repository, capture fails closed instead of committing it. A logging failure changes no accepted state and produces at most one local warning.
 
 Logs remain local unless you move them; rotation/deletion is operator-owned. Treat them and state files as private. Removing a secret from current state does not erase older offsets, Git history, native sessions, or remote copies.
 
@@ -63,85 +64,60 @@ Logs remain local unless you move them; rotation/deletion is operator-owned. Tre
 
 `/state-flow-status` separates runtime configuration/metadata from semantic state. It reports:
 
-- Selected CWD/session keys, step, temporal head, durable revision, and available hot history.
+- Selected CWD/session keys, step, temporal head, recovery failures, and available hot history.
 - Per-scope retained patch tails and artifact counts, plus one JSON representation of effective global → CWD → session memory. Individual scope JSON is available through `read_state`, not duplicated in status.
-- Discovered Markdown invalidations or unavailable freshness evidence.
-- Remote policy, queued/unconfirmed publication, and relevant errors.
-- Memory-bearing scopes and external-promotion records, including invalid or incompletely evidenced acceptance.
+- Already-known runtime hints or pending artifact invalidations; status does not discover or validate sources.
+- Memory-bearing scopes. Promotion-shaped values receive no special interpretation.
 
-Tail counts are not history depth: inherited records may predate the active origin. Failed inspection reports unavailable evidence, not invented empty state or a clean freshness count. Status hashes source bytes as needed for freshness diagnostics; it does not dump Markdown bodies.
+Tail counts are not history depth: inherited records may predate the active origin. Failed inspection reports unavailable evidence, not invented empty state. Status is observational: it does not read source files, calculate fingerprints, create invalidations, or mutate semantic state.
 
-The terminal indicator is `state-flow #N`. When `pi-telegram` is available, one main-menu section carries the live State Flow status and opens Start/Stop controls. Start requested during a run waits for settlement; Stop currently applies immediately. The adapter is optional and the Pi commands remain available without it. Remaining hardening work is tracked in [BACKLOG.md](../BACKLOG.md).
+The terminal indicator is `state-flow #N`. When `pi-telegram` is available, one main-menu section carries the live State Flow status and opens Start/Stop controls. Start requested during a run waits for settlement; Stop currently applies immediately. The adapter is optional and the Pi commands remain available without it. Open implementation work is tracked in [BACKLOG.md](../BACKLOG.md).
 
 ## Storage and recovery
 
-Use a dedicated directory. State storage and Knowledge Markdown have separate responsibilities:
+Use a dedicated directory. State storage and registered artifact sources have separate responsibilities:
 
 ```text
 <agentDir>/state-flow/   global config, accepted state, and runtime metadata
-<agentDir>/knowledge/    optional Markdown sources for compilation
+<any exact registered path>   optional external source owned outside State Flow
 ```
 
 Each scope materializes an anchored semantic-only `checkpoint.json` plus semantic-only lines in `patches.jsonl`. Scope `meta.json` holds temporal boundaries, CWD ownership where applicable, and runtime-owned artifact evidence. The session additionally uses `config.json` for behavior and `runtime.json` for branch/run recovery metadata; a full prompt is retained there only while its run is unfinished. CWD/session directories mirror Pi's native naming while validating canonical identities separately. See the [storage contract](architecture.md#storage-and-identity) for the exact layout.
 
 ### Missing, partial, and malformed storage
 
-A checkpoint and tail are one semantic pair. If both live files for an untouched global or CWD scope disappear, State Flow treats that complete absence as current empty shared reality during the next accepted publication. It creates a fresh canonical pair through the normal publication lock and CAS path; selected values remain only in cold Git history and are not silently resurrected. A patch targeting the disappeared scope is rejected once as stale so a later inference can work from the actual empty basis.
+A checkpoint and tail are one semantic pair. If both live files for an untouched global or CWD scope disappear, State Flow treats that complete absence as current empty shared reality during the next accepted publication. It creates a fresh canonical pair through normal file-cohort exclusion and CAS; no cold Git value is resurrected. A patch targeting the disappeared scope is rejected once as stale so a later inference can work from the actual empty basis.
 
-Exactly one surviving pair member is corruption and fails closed. Present malformed JSON, incomplete predecessor envelopes, semantic/metadata boundary mismatches, identity contradictions, and partial session runtime evidence also remain fail-closed and are not replaced. A selected Git revision may reconstruct a missing private session cohort exactly; file-only mode refuses when its exact current cohort is gone because it has no cold history to invent.
+Exactly one surviving pair member is corruption and fails closed. Present malformed JSON, incomplete predecessor envelopes, semantic/metadata boundary mismatches, identity contradictions, and partial session runtime evidence also remain fail-closed and are not replaced. A missing or expired private retained boundary is unavailable; State Flow does not substitute Git history or newer private files.
 
-Missing artifact provenance inside an otherwise complete scope `meta.json` means freshness evidence is unavailable while semantic state remains usable; removing the whole metadata file also removes temporal authority and fails closed. A missing whole Knowledge root does not prove that durable artifact routing was deleted, and external files are never created. Queue, worker lease, and lock absence keep their existing meanings—empty, unclaimed, and unlocked—while malformed or foreign present evidence is preserved. See the complete [filesystem recovery contract](filesystem-recovery.md).
+After a selected-boundary failure, configured passive access may still expose current global/CWD memory, but it never grants access to the unavailable session layer or permission to publish an empty replacement. Session reads, every `patch_state`, and Stop refuse without changing canonical files or appending substitute checkpoints. Status retains the restoration error even when shared reads work. Start retries the original selection; repair its missing or invalid evidence, select a still-retained boundary, or use a genuinely new Pi session instead of forcing a reset.
 
-### With Git
+Missing artifact provenance inside an otherwise complete scope `meta.json` means compilation evidence is unavailable while semantic state remains usable; removing the whole metadata file also removes temporal authority and fails closed. An unavailable registered source path does not prove that durable artifact routing was deleted, and external files are never created. State Flow has no durable push queue or publication-worker lease. See the complete [filesystem recovery contract](filesystem-recovery.md).
 
-Start initializes an exact-root repository when needed, preserving existing contents. Git must have a configured commit identity. A containing ancestor repository is not a substitute. Manual-mode startup/status/restore do not initialize Git; explicit Start and automatic activation of genuinely new sessions may do so.
+### Canonical files and optional Git backup
 
-Every effective semantic transition, including a changed answer, receives an immediate local commit. Each commit includes the complete non-ignored worktree delta before overlaying the prepared State Flow outputs, and synchronizes the visible index to the accepted tree. This is why the store must not be an unrelated working repository. Untracked ignored files remain untouched; State Flow-owned active files stay under its publication/CAS contract.
+Canonical scope/runtime files own current materialization and retained hot history regardless of Git availability. Pi checkpoints identify a retained semantic boundary, not a Git commit or arbitrary historical snapshot. Restart and branch restoration fail closed when the selected boundary has expired rather than substituting newer files as the selected past.
 
-A remote is optional and operator-owned. State Flow creates no account, hosted repository, credentials, or remote configuration. Remote failure does not undo an accepted local commit or require regenerating an answer; retry targets that existing commit. With no remote, the store is intentionally local-only.
+After an accepted turn has reconciled its response, Pi 0.87's final actionable `agent_before_settle` boundary may create one best-effort backup commit when Git is available. Backup failure is diagnostic-only. Git availability never changes semantic authority, step, or retained lineage.
 
-An asynchronous push has a 15-second budget. Pi shutdown, reload and native session replacement cancel owned pushes and wait up to two seconds for cleanup; it leaves unconfirmed targets queued, without advancing semantic history. If child exit cannot be confirmed, a warning reports the retained lease. Do not delete it to force a retry while its owner is still live. A later activation can retry after cleanup; timeouts do not spin an immediate retry loop for the same target. The compatibility `transition` mode keeps its existing synchronous behavior. SDK embedders must deliver the [shutdown event](architecture.md#embedding), not just discard the session object.
+### Moving a store and the 0.17 format boundary
 
-Inspect a Git-backed store without modifying it:
+An SDK `repositoryRoot` override or a different `PI_CODING_AGENT_DIR` selects a location; it does not relocate existing state or retained history. Copy the complete canonical store while all writers are quiescent, or use a genuinely new Pi session for an independent store. Copying only current checkpoints without their tails and metadata cannot preserve retained boundaries.
 
-```bash
-git -C ~/.pi/agent/state-flow status --short
-git -C ~/.pi/agent/state-flow log --oneline -10
-git -C ~/.pi/agent/state-flow show <selected-revision>:checkpoint.json
-```
-
-Use the revision reported for the selected Pi branch. Shared live files may belong to a newer branch, so `HEAD` is not automatically that branch's memory.
-
-### Without Git
-
-Only an absent Git executable selects file-only mode; Git corruption, permission errors, and command failures remain errors. Files retain current materialization and its proven hot history. Their `file:<hash>` checkpoint reference identifies one exact current cohort, not an arbitrary historical snapshot.
-
-Restart can restore that reference while its complete cohort remains available. An older branch or a crash between file publication and Pi checkpoint append can leave a reference unavailable even though newer files exist. State Flow must not pass those newer files off as the selected past. Preserve the store and diagnose the reference rather than resetting it.
-
-If Git becomes available later, explicit Start can adopt the proven current file cohort. It preserves state, step, and hot lineage; Git cold history begins at adoption rather than inventing earlier commits.
-
-### Moving or migrating a store
-
-Changing `directory` selects a location; it does not relocate existing state or history. Git-backed Pi checkpoints require their original commit objects. Copying only current checkpoint/tail files cannot preserve old branch recovery. Keep the original store intact until an explicit history-preserving relocation is complete, or use a genuinely new Pi session for an independent store.
-
-The only supported in-store migration converts complete predecessor checkpoint/tail envelopes into semantic-only files plus temporal `meta.json`. `state.json`, pre-0.4 hashed layouts, and semantic Pi checkpoint envelopes are unsupported and fail closed; manually renaming files is not a valid conversion.
-
-Pre-0.4 hashed-path layouts remain readable at their historical revisions and can be adopted into native paths at current HEAD. A missing revision or failed restoration is not permission to import another session or reset existing files.
+State Flow 0.17 accepts only its canonical checkpoint/tail, temporal metadata, and separate session config/runtime contract. Predecessor checkpoint envelopes, combined session metadata, pre-intents checkpoints, `state.json`, hashed layouts, and semantic Pi checkpoint envelopes fail as unsupported without rewriting existing bytes. State Flow does not provide an in-place converter; external conversion or a fresh store is operator-owned.
 
 ### Conflicts and interrupted publication
 
-Cooperating writers use publication locks, exact prepared bytes, and compare-and-swap checks. These are not kernel-atomic multi-file transactions against nonparticipating writers. A busy publication lock fails before writes and is not silently stolen; reconcile the active or interrupted owner before retrying. Do not delete locks or state directories merely because an operation is slow.
-
-Fatal process termination during local Git publication can leave attempted worktree files, a private index and publication locks. HEAD may or may not have advanced; a new commit need not have returned success or reached a Pi checkpoint. The [fatal-writer witnesses](temporal-acceptance.md#fatal-writer-interruption) preserve earlier accepted revisions and read-only inspection while new writes and live restore installation remain blocked. A dead PID alone does not establish which effects completed or whether Git children stopped. Before any repair, quiesce all store writers and preserve the complete store, Git/index data and selected Pi references; reconcile the exact interrupted attempt before clearing ownership. No automatic crash repair or power-loss durability is promised.
+Cooperating canonical writers use file-cohort exclusion, exact prepared bytes, and compare-and-swap checks. These are not kernel-atomic multi-file transactions against nonparticipating writers. A busy writer lock fails before writes and is not silently stolen; reconcile the active or interrupted owner before retrying. Do not delete locks or state directories merely because an operation is slow.
 
-Worker lease recovery is separate from stealing a publication lock: it accepts only a validated regular-file record whose PID is proven gone, then rechecks ownership under the queue writer lock. Malformed and symlink lease records stay untouched. Upgrade/reload all publishing instances together; older still-running code can bypass the updated reclamation gate.
+Fatal process termination can leave an incomplete canonical file cohort. Before repair, quiesce all store writers and preserve the complete store plus selected Pi retained-boundary references. Reconcile exact files against the last complete checkpoint/tail/metadata cohort; no automatic crash repair or power-loss durability is promised. Git backup has no semantic recovery authority.
 
-An untouched shared scope may be adopted from newer proven live state at a fresh origin. A patch that actually changes an advanced shared scope fails with a named conflict instead of silently overwriting it. Rollback restores only bytes still matching that publisher's output and preserves detected external changes. See [performance evidence](performance.md) for measured contention and the [acceptance map](temporal-acceptance.md) for the tested boundaries; the [backlog](../BACKLOG.md) owns remaining release gates.
+An untouched shared scope may be adopted from newer proven live state at a fresh origin. A patch that actually changes an advanced shared scope fails with a named conflict instead of silently overwriting it. Rollback restores only bytes still matching that publisher's output and preserves detected external changes. See [performance evidence](performance.md) for measured contention and the [acceptance map](temporal-acceptance.md) for the tested boundaries; the [backlog](../BACKLOG.md) owns open implementation work.
 
 ## Memory and source acquisition
 
 The agent should use sufficient materialized knowledge before rereading files. Read for a concrete gap, exact-source/edit operation, evidenced invalidation, contradiction/failure, explicit request, or bounded maintenance—not simply because a new session began.
 
-Knowledge discovery finds regular lowercase `*.md` beneath its configured root, hashes opaque bytes, and skips symlinks. Only confirmed missing Markdown paths within an available root are pruned; external/non-Markdown artifacts and state under a missing whole root are preserved. An unavailable root makes freshness unknown in status. Successful reads of stale ordinary candidates require same-path global compilation; Skill reads require CWD compilation. The runtime owns provenance: model patches cannot write or delete individual freshness fields, including legacy spellings. Existing legacy entries remain readable and semantically editable. Missing freshness evidence means unknown-but-usable, not proof that a source was acquired.
+Artifact maintenance inspects only exact paths already registered in global, CWD, or session state, using `size + mtimeNs` without directory traversal or generic content hashing. Proven-missing paths are pruned from their exact owning scopes; unavailable, relative, directory, and symlink paths are preserved. Changed sources keep their artifact value and receive a runtime-only model `hint` until a stable read and same-path compilation updates hidden provenance. Skill reads retain their separate CWD compilation protocol. Model patches cannot author or delete runtime provenance or hints.
 
-The packaged `state-flow-guide` Skill answers concrete operational questions about reads, patches, inheritance, acquisition, finalization, and recovery without initiating cleanup. The separate `state-flow-memory` Skill handles explicit bounded curation, feature/release/project phase-boundary reconciliation, and external promotion. Ordinary handoffs clean only touched and obviously stale visible branches; neither Skill is a background maintenance loop. Promotion must verify the destination before removing the only accepted source copy. Artifact/compiler details and model-tool contracts belong in the [architecture](architecture.md#artifact-routing).
+The packaged `state-flow-guide` Skill answers concrete operational questions about reads, patches, inheritance, acquisition, completion, and recovery without initiating cleanup. The separate `state-flow-memory` Skill handles explicitly requested bounded curation and externally verified transfers. Feature/release/project boundaries may motivate recommending cleanup, not starting an audit. Ordinary handoffs reconcile touched state; neither Skill is a background maintenance loop. External transfers use the destination's native receipt and preserve the source whenever acceptance is uncertain. Artifact/compiler details and model-tool contracts belong in the [architecture](architecture.md#artifact-routing).

package/node_modules/@llblab/pi-state-flow/index.ts

@@ -8,7 +8,7 @@ export {
   type SuccessfulArtifactRead
 } from "./lib/acquisition.ts";
 export {
-  classifyArtifactFreshness,
+  classifyArtifactCompilationNeed,
   compileArtifact,
   hashArtifactSource,
   isArtifactHash,
@@ -16,7 +16,6 @@ export {
   isArtifactRegistry,
   ORDINARY_ARTIFACT_COMPILER,
   parseArtifactProvenanceRegistry,
-  planArtifactInvalidation,
   projectArtifactForModel,
   projectArtifactsForModel,
   pruneArtifactProvenance,
@@ -28,10 +27,8 @@ export {
   validateArtifactRegistry,
   type ArtifactCompilationUpdate,
   type ArtifactCompilerOutput,
-  type ArtifactFreshness,
+  type ArtifactCompilationNeed,
   type ArtifactInvalidationNotice,
-  type ArtifactInvalidationOptions,
-  type ArtifactInvalidationPlan,
   type ArtifactInvalidationReason,
   type ArtifactInvalidationRequest,
   type ArtifactMetadata,
@@ -60,13 +57,6 @@ export {
   type ContinuationTransport,
   type NativeSessionHeader
 } from "./lib/continuation.ts";
-export {
-  discoverGlobalMarkdownSources,
-  getKnowledgeRoot,
-  GlobalMarkdownDiscovery,
-  type ArtifactSourceCandidate,
-  type GlobalMarkdownDiscoveryResult
-} from "./lib/discovery.ts";
 export {
   captureTemporalFileBases,
   cwdScopeKey,
@@ -80,21 +70,13 @@ export {
   sessionStorageKey, temporalScopePaths,
   temporalStateFileUpdates, type ScopeStreamSources, type TemporalScopePaths
 } from "./lib/durable.ts";
-export { default, MAX_FALLBACK_ATTEMPTS, PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME, type StateFlowExtensionOptions } from "./lib/extension.ts";
-export {
-  captureTemporalGitBase,
-  isGitCommitAncestor,
-  loadTemporalRevision,
-  migrateLegacyStorageToGit,
-  publishTemporalStateToGit,
-  pushGitCommit,
-  resolveGitPushDestination, type GitPushResult, type TemporalGitBase,
-  type TemporalRevisionLoad
-} from "./lib/git.ts";
+export { default, PATCH_STATE_TOOL_NAME, READ_STATE_TOOL_NAME, type StateFlowExtensionOptions } from "./lib/extension.ts";
+export { backupCurrentStateFlowFiles } from "./lib/git.ts";
 export {
   createAcceptedTransition,
+  DEFAULT_HISTORY_LIMIT,
+  MAX_HISTORY_LIMIT,
   projectRecentTransitionsWithLimit,
-  RECENT_TRANSITION_LIMIT,
   validateRecentTransition, type AcceptedTransition, type RecentScopePatch,
   type RecentTransition,
   type RecentTransitionWindow
@@ -109,52 +91,7 @@ export {
   type StateFlowDiagnosticCategory,
   type StateFlowDiagnosticRecord
 } from "./lib/logging.ts";
-export {
-  DEFAULT_ARTIFACT_MAINTENANCE_MAX_READS,
-  DEFAULT_ARTIFACT_MAINTENANCE_MAX_SOURCE_BYTES,
-  DEFAULT_ARTIFACT_MAINTENANCE_MINIMUM_AGE_MS,
-  planArtifactMaintenance,
-  type ArtifactMaintenanceOptions,
-  type ArtifactMaintenancePlan,
-  type ArtifactMaintenanceRequest
-} from "./lib/maintenance.ts";
-export {
-  inspectMemoryPromotions, MEMORY_PROMOTION_STATUSES, MEMORY_PROMOTIONS_KEY, retainedMemoryScopes,
-  type MemoryPromotionDiagnostic,
-  type MemoryPromotionStatus
-} from "./lib/memory.ts";
-export {
-  acquirePublicationWorkerLease,
-  beginPublicationAttempt,
-  coalescePublicationTarget,
-  confirmPublicationTarget,
-  createPublicationQueue,
-  failPublicationAttempt,
-  loadPublicationQueue,
-  parsePublicationQueue,
-  parseRemotePublicationPolicyDocument,
-  publicationQueuePath,
-  recoverPublicationQueue,
-  remotePublicationDestinationKey,
-  removePublicationQueue,
-  resolveRemotePublicationPolicy,
-  runPublicationWorker,
-  savePublicationQueue,
-  serializePublicationQueue,
-  serializeRemotePublicationPolicyDocument,
-  validatePublicationQueue,
-  type CommitAncestor,
-  type PublicationPush,
-  type PublicationQueueReceipt,
-  type PublicationQueueState,
-  type PublicationQueueStatus,
-  type PublicationWorkerLease,
-  type PublicationWorkerResult,
-  type RemotePublicationDestination,
-  type RemotePublicationMode,
-  type RemotePublicationPolicy,
-  type RemotePublicationPolicyDocument
-} from "./lib/publication.ts";
+export { retainedMemoryScopes } from "./lib/memory.ts";
 export {
   planKnowledgeRehydration,
   type RehydrationOptions,
@@ -167,7 +104,6 @@ export { TemporalRuntime } from "./lib/runtime.ts";
 export {
   hasCompiledSkillArtifact,
   hashSkillSource,
-  migrateLegacySkillCompilations,
   SKILL_ARTIFACT_COMPILER,
   type SuccessfulSkillRead
 } from "./lib/skills.ts";