@llblab/pi-kit 0.37.1 → 0.38.1

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

@@ -0,0 +1,212 @@
+# Semantic evolution compatibility decision brief
+
+## Status and scope
+
+**M1 target dialect and guarded migration locally implemented; not released or exercised on active stores.** On 2026-10-24 the owner requested the complete roadmap implementation and proposed a one-shot migration with temporary retired-name reservations. This supersedes the earlier approval-only stop, not the data-preservation proofs. [BACKLOG.md](../BACKLOG.md#11-compatibility-and-migration) owns remaining work. The [current compatibility guide](compatibility.md) describes retained runtime behavior; the [semantic handoff contract](semantic-handoff-contract.md) defines target meanings. No active store conversion is authorized by this document.
+
+Evidence baseline: package 0.26.5, commit `4494fee9da8258cdf5f02c42672a0eb9866a512a`, matching repository-local Pi SDK 1.0.0. Only repository code and synthetic in-memory values were inspected. No active store, external consumer, or production session was inventoried or converted.
+
+## Implementation direction and reserved names
+
+- **Owner direction:** Use a one-time `contract → strategy`, `working → tactics` migration rather than permanent dual model-facing planes. Temporarily reserve the retired names at the owner-root plane position; new-format creation/patches must explicitly reject them. Do not reserve ordinary nested data keys or blanket-rewrite prose.
+- **Implementation choice:** Prefer design B below: translate current and every retained boundary into one target dialect, preserve causal identities/owner revisions, and retain complete pre-conversion backup bytes outside canonical authority. Historical tools then promise translated semantic equality, not the original field spelling. Original-name model aliases are not the default public API. Prove the oracle before enabling publication.
+- **Admission before interpretation:** Select a decoder using explicit supported metadata versions before selecting known fields. Reject unknown versions before read acceptance or metadata rewrite; never interpret an unknown future dialect as empty legacy state. Known v1/v2 unknown metadata siblings remain preservable; they are not evidence of a new semantic dialect.
+- **One-time and recoverable:** Produce a detached, collision-checked conversion candidate, translate recognized semantic references, validate all retained replay boundaries, and publish checkpoint/tail/metadata together using existing exclusion/CAS/rollback. The accepted target version makes repeat acquisition idempotent. Ordinary inspection and history reads do not become migration writes; source discovery alone grants no publication authority.
+- **Fail closed:** Reject coexisting old/new root names for explicit reconciliation, unsupported versions, malformed replay, partial evidence and occupied/conflicting destinations. Do not silently merge or destroy evidence. Already-recorded ownership cascades do not run a second time.
+- **Retirement insight:** Removing the temporary converter does not remove version admission. An unsupported old store must fail explicitly after retirement, not be reinterpreted as newly available user-defined planes.
+- **Settled support timing:** These are State Flow package versions. Throughout **0.x**, retain legacy `contract`/`working` conversion and reserve those retired owner-root names. Beginning **1.0.0**, that temporary legacy support and reservation window ends; explicit unsupported-version refusal remains. There is no separate **1.1** deadline. The prepared **0.27.0** candidate keeps its converter and reservations unchanged. This policy does not authorize immediate code removal, release, working-store conversion or automatic registration of new planes. Package release numbers are not persisted schema identifiers.
+- **Operational boundary:** Version checks in this checkout cannot retrofit already-deployed old low-level callers. Upgrade/quiesce unsupported writers before converting shared cohorts; development only exercises temporary stores. No implicit active-store conversion, downgrade or release publication.
+
+## Pure conversion boundary
+
+`lib/migration.ts` owns the temporary, side-effect-free conversion candidate. `prepareSemanticMigration` requires an explicit source metadata version: 1/2 translate to candidate version **3**, while an already-target v3 candidate is validated/detached without another conversion. V3 is the current canonical scope identifier, independent of State Flow package SemVer and Pi SDK versions; native readers normalize supported legacy input into this one target dialect. This module is not exported from the package root and grants no file/publication authority.
+
+- Root `contract`/`working` become `strategy`/`tactics`; sparse absence, empty legacy branches, patch deletion markers, arrays, ordinary nested keys and opaque unknown root data remain intact. Any target root name in declared legacy data rejects, even without an old sibling. Target candidates reject retired roots in checkpoints and patches, including deletion attempts.
+- Recognized exact structured `$ref` locators and deliberate textual `$path` tokens translate only the plane position. Scope, historical selectors, array/range spelling and ownership classification remain unchanged. The query domain supplies shared selector syntax validation without target lookup. Unsupported/unparseable locators, unmarked prose and resource paths stay unchanged; no reference is hydrated or granted authority.
+- Artifact registry keys and retained embedded `hash`/`compiler`/`compiled_at` evidence stay opaque. Eligible semantic description/compilation references may translate, but provenance is not a semantic-reference namespace. Hidden provenance metadata is outside this stream candidate and is preserved unchanged by the serialized preflight below.
+- Candidate construction validates replay, preserves every transition identity/parent/position and owner revision, and returns detached data. It does not normalize empties, invent a transition, rerun ownership cascades, fold history or write a store.
+- Legacy objects translate before target semantic validation, with extra envelope fields retained until strict validation. The temporary reverse-validation bridge is removed. Malformed legacy/target fixtures ensure that conversion cannot sanitize an invalid envelope into acceptance.
+
+`tests/migration.test.ts` proves root reservation/collision handling, locator boundaries and opaque provenance, candidate detachment/idempotence, every retained owner boundary and aligned effective overlay at limits 0/1/7/100, and malformed replay refusal. These are deterministic conversion proofs, not interruption/CAS/backup tests or a live-model evaluation.
+
+## Serialized owner-cohort preflight
+
+`prepareSerializedScopeMigration` takes captured byte arrays for **all three** checkpoint/tail/metadata files, the owner scope and, for CWD, its expected canonical identity. It decodes the declared version before semantic interpretation, preserves raw roots until collision checks, validates local replay, and returns target strings plus detached `basis` byte receipts with SHA-256 identities compatible with the existing CAS convention. Empty tail bytes are present evidence; a missing file or wholly absent cohort is not migration authority and rejects instead of fabricating a new store.
+
+- Source bytes are copied before interpretation. Strict UTF-8 decoding rejects invalid bytes rather than replacing them with the Unicode replacement character; JSON documents are not silently BOM-stripped. Tail blank-line handling remains compatible with the existing JSONL decoder. These receipts describe the caller-supplied bytes, not independently observed files or a publication capability.
+- Supported legacy versions 1/2 produce canonical target v3 strings. If legacy revision metadata is absent, credit only the retained tail count, matching existing legacy decoding; discarded revisions/history are not reconstructed. Target v3 requires an explicit revision.
+- An already-target v3 cohort validates and returns **byte-identical** target contents, including noncanonical whitespace and JSONL blank lines, rather than rewriting on every open. Native v3 readers admit this target directly; legacy reads return translated semantics without publishing.
+- Metadata values change only at the declared format version and, when absent in legacy input, the inferred revision; legacy whitespace/property order may canonicalize. Preserve temporal boundaries, unknown siblings, extra temporal data, CWD owner, opaque identity/lineage/lifecycle values and original provenance registry data. Do not run the normal metadata serializer, which can remove legacy Session authority fields or normalize provenance. Uninterpretable provenance entries remain uninterpretable; preserving them is not new source-hash or compilation evidence.
+- CWD requires an explicit expected identity and an exact canonical owner match; non-CWD calls cannot borrow a CWD identity. Provenance registry framing is validated using its owning parser without substituting that parser's normalized output for raw evidence. Partial/malformed cohorts, unsupported versions, mismatched record counts, invalid replay and raw old/target collisions fail closed.
+
+The serialized tests require both preflight and the integrated native decoder to reject target-name collisions in declared legacy bytes; the baseline filtering defect is no longer accepted behavior. They also cover all incomplete-file subsets, exact-byte hashes/detachment, metadata/provenance preservation, legacy revision fallback, empty tails, byte-idempotent v3, UTF-8/BOM/finite-JSON boundaries and CWD identity admission.
+
+**Remaining integration boundary:** This function performs no I/O, backup, lock acquisition, CAS, rollback or cache installation. Local stream validation does not prove Session ownership or composed lineage: native header/config/runtime authority and regular-file/path evidence remain the existing lifecycle/storage owners' responsibility. Bind receipts to the exact owned paths, preserve complete backups of the converted owner cohorts and required owned lifecycle/config/runtime authority outside canonical authority, revalidate under exclusion and prove conflict/interruption refusal before publication. This does not authorize discovering unrelated projects/sessions or scanning the entire store. The integrated M1 runtime uses only `strategy`/`tactics` across types, ownership, tools, query, Skills and callbacks. A returned preflight candidate alone still grants no publication authority.
+
+## Guarded publication and support boundary
+
+`storage.planTemporalPublication` identifies legacy owners even when their normalized semantic stream is unchanged. The existing synchronous, single-use publication capability validates the complete Session runtime/identity/lineage cohort, checks the current exact-byte basis under store exclusion, and decodes the planned target cohort before any canonical write. A pure format change creates no learning transition or owner revision. Runtime-only mode persistence and read-only inspection do not convert.
+
+Before publishing a legacy-to-v3 update, storage creates and verifies `<parent>/<store-name>-migration-backups/<sha256>.json` outside canonical authority. The private manifest identifies converted scopes and updated paths alongside the captured transaction basis, original Base64 bytes/identities, missing entries and owner/runtime identity parameters; no unrelated session/project is discovered. Backup creation failure aborts before canonical writes. Completed backups survive rollback and exact retries reuse them. Existing guarded rollback preserves foreign concurrent output; this adds no power-loss, kernel-atomic or automatic recovery guarantee. See [operator backup guidance](usage.md#moving-a-store-and-supported-formats).
+
+The legacy-publication groups in `tests/runtime.test.ts` and `tests/storage.test.ts` prove observational legacy reads, converted history/revision equality, exact complete backup contents, opaque metadata preservation, one-time backup creation, backup failure, injected publication failure/retry, stale CAS refusal, cancellation while a foreign lock is still held, and private-identity/partial-cohort refusal. Semantic consumers require valid UTF-8, but opaque capture/rollback deliberately retains arbitrary original bytes. Direct string codecs reject lone UTF-16 surrogates before lossy UTF-8 encoding; escaped JSON values (including surrogate values) and valid Unicode pairs retain their exact meaning. A raw backup is evidence, not a fallback store or permission to overwrite later data.
+
+**Public API change:** Existing exported type/function names remain where applicable, but semantic fields, schemas, callbacks and read paths use only `strategy`/`tactics`. Old model/SDK root writes reject; no permanent aliases or old-field type views are added. Historical reads expose translated semantics, not original names. Scope versions 1/2 are migration inputs, version 3 is the target, and unknown versions fail closed. This is an unreleased breaking semantic API/storage change: upgrade/quiesce cooperating consumers before deploying it. Already-deployed unsafe low-level callers remain unsupported concurrent writers; no universal retrofit fence is claimed.
+
+### Source-bound M1 validation
+
+`npm run validate` completed with **892 tests, 0 failures**, typecheck, tracked compilation, extension import and 122-file dry-run package checks. Focused migration/publication witnesses cover source CAS, cancellation under held exclusion, backup/privacy failure, rollback/retry, omitted-owner byte stability, private authority, metadata siblings and retained histories. No active store was read or converted for this work.
+
+The updated isolated SDK calibration completed **41 faux calls** (Native 11, Passive 15, Active 15), all fixtures cleaned, with output limits forwarded. Input/source digest: `4ca8b5d7ff28a7ab031e8f51fc888987a5401badd356a9fb2c7b9b150af53fd2`. At Run 4, Active saw zero prior user prompts versus three in Native/Passive; retained target-schema strategy contained phases, binding requirement, rejected alternatives and the durable conclusion after intent/tactical closure. This is scripted preservation/transport evidence, not model-quality, billing or cache-performance evidence. Live comparison remains deferred.
+
+## What must remain exact
+
+**Agreed preservation:** Rename compatibility cannot silently discard known old planes, weaken existing commitments, change canonical ownership, invent causal history, or replace malformed evidence with empty state.
+
+“Exact historical read” needs a representation qualifier before a writer design can be approved:
+
+- **Original representation:** The known semantic JSON at the requested original boundary, including old plane names, original reference strings, sparse absence, and legacy empty branches. This is not the original file's whitespace or property-order bytes; model projections already have documented filtering.
+- **Translated representation:** The entire requested value at that same boundary after a declared, deterministic old-name-to-new-name translation. This can preserve semantic information and identity without being identical original JSON.
+- **Raw backup bytes:** An operator copy of complete canonical files before conversion. Such a copy can support manual rollback but is not automatically addressable by `read_state`.
+
+An index is still a causal offset, not a schema version or scope revision. Declaring translated history “exact” must never imply original field names remain readable, discarded history has returned, or the old JSON bytes are unchanged.
+
+**D1 implementation choice:** Ordinary target-dialect historical tools will promise translated representation. Original bytes remain recoverable from a separate complete backup, not a permanent original-name model API. This is a declared contract change, not a claim that renamed JSON is literally unchanged. Its replay/ref/collision proof remains required in M1.
+
+## Compared designs
+
+### A. Version-aware legacy history and a normalized current interface
+
+Keep original owner checkpoints/tails and decode a declared dialect before materialization. A target-facing projection can expose strategy/tactics without canonical rewriting.
+
+- Preserves original bytes and potentially original-name historical access.
+- Requires a named representation boundary so raw and normalized views cannot be confused.
+- Once target-dialect writes append, checkpoint/tail records require unambiguous dialect/epoch identification, including mixed epochs and folding. Merely checking which keys happen to occur is not enough.
+- Risks two long-lived model-facing representations and indefinite old path aliases if the compatibility boundary is not bounded.
+
+This is justified if literal original-name historical access is a supported product requirement. It is not justified only to avoid deciding what “exact” means.
+
+### B. Explicit canonical owner-cohort conversion
+
+Decode old checkpoint and every retained patch, translate them together, and publish a target-dialect checkpoint/tail/metadata cohort. Preserve semantic transition identities, independent revisions, and boundary alignment. Subsequent tools use one target dialect.
+
+- Simpler steady-state semantics, replay, and model guidance.
+- Rewrites retained syntax and recognized references; old-name history queries are no longer the normal interface.
+- Requires raw collision detection, reviewed writer fences, all cooperating writers upgraded/quiesced, exact-cohort CAS, rollback/recovery procedure, and a complete pre-conversion backup.
+- Does not by itself justify a new transition or revision: representation conversion is not a new learned fact.
+
+**Selected implementation direction:** Prepare version admission as the safety boundary, then implement B with the translation oracle and publication constraints below. Keep A as the documented alternative, not a second parallel implementation. If evidence exposes an unsupported preservation requirement, revise the contract explicitly rather than silently broadening the migration.
+
+## Translation contract and oracle
+
+Define a partial translation `T` on a fully decoded, supported owner cohort. It is undefined on ambiguous raw plane collisions or unsupported/malformed authority. The candidate must not become accepted when `T` is undefined.
+
+For every retained boundary and valid accepted patch `P`, the core oracle is:
+
+```text
+T(apply(S, P)) = apply(T(S), T(P))
+```
+
+The equation concerns sparse semantic values in the chosen dialect, including supported reference translation. It excludes current model-only pruning and lazy/provenance visibility filtering; test those projections separately. It must hold for checkpoint replay, explicit top-level plane deletions, nested deletions, arrays, whole-card replacements, and already-recorded ownership cascades.
+
+### Recommended translation rules
+
+1. Translate only recognized owner-root planes `contract → strategy` and `working → tactics`, including their deletion markers in replay patches. Preserve all other known planes and nested domain keys.
+2. Preserve absent fields, empty legacy branches, arrays/array slots, scalar values, and null-as-patch-deletion. No new stored semantic null, fabricated default object, or normalization-only revision.
+3. Inspect raw checkpoint and each tail record before known-field selection. If target names already coexist with old names, reject for explicit reconciliation even when a generic old reader would ignore the target names. Do not merge by precedence or silently decide that previously ignored data is disposable. An identical-dual-value shortcut is not needed initially.
+4. Translate a structured `$ref` only when its entire value is a recognized semantic locator containing a retired plane segment in the plane position. Translate intentional textual `$path` tokens using the same path grammar and token boundaries, never blanket string replacement. Preserve resources, artifact source paths, nested domain keys, and unmarked prose.
+5. Preserve unparseable reference-like ordinary data verbatim unless a concrete ambiguity requires operator reconciliation. Do not make previously legal ordinary JSON invalid simply because its text resembles an unsupported reference. Conversion diagnostics are not a runtime reference audit or automatic repair policy.
+6. Keep scope identities and temporal/index/range selectors unchanged. Cross-owner references remain cross-owner, textual references remain non-owning, and target existence or authority is never inferred. The same translation applies to eligible ownership references before and after conversion; old explicit cascade deletions never run again.
+7. A normalized reader may decode different supported owner dialects during a quiesced rollout, but each individual checkpoint/tail/metadata cohort must have one proven dialect contract. Do not infer dialect from field absence in sparse state. A translated reference uses logical target-plane names even if its referenced owner has not yet converted; the normalized reader must resolve that owner's declared representation, not move its data.
+8. Preserve current artifact source evidence and owner identity. Rewriting a reference does not create a new source hash or prove compilation fidelity. Old instructional prose in compiled cards is not eligible for blanket rewriting: current trusted tool guidance remains authoritative, and a concrete operational gap may justify targeted optional reacquisition through the existing source protocol.
+
+Required equalities include `T(materialize_old(boundary)) = materialize_new(boundary)`, unchanged transition IDs/parents/positions, unchanged independent owner revisions, and equivalent effective overlay at every retained aligned boundary. Original-representation equality is a different promise and is possible only under design A or an explicitly preserved original reader.
+
+## Writer-fence finding
+
+### Verified baseline call-path behavior
+
+The inspected `4494fee` baseline did not have one universal format-admission check:
+
+- `lib/durable.ts::classifyScopeStream` / `parseScopeStream` reads temporal metadata and applies `selectSemanticFields` to checkpoint/tail JSON. It does not check the metadata `version` before selecting fields.
+- `lib/durable.ts::parseScopeProvenance` accepts only metadata versions 1 and 2. Normal runtime loading also invokes it, so an unsupported metadata version is rejected on those full loading paths.
+- `lib/durable.ts::serializeScopeMetadata` parses JSON-safe existing metadata and emits `version: 2`; it is not a generic unknown-version rejection boundary.
+- `index.ts` exports `parseScopeStream`, `serializeScopeStream`, `loadScopeStream`, and other low-level codec functions in addition to `TemporalRuntime`. Their format admission cannot be inferred from the full runtime's behavior.
+- Publication planning and final cohort decoding in `lib/storage.ts` have additional checks. Whether a particular old API caller reaches them depends on the caller; a provenance-reader test alone does not prove every exported read/write composition is fenced.
+
+An in-memory probe used synthetic metadata version 3 with otherwise valid temporal boundaries and demonstrated all four distinctions:
+
+1. The old stream parser accepted the metadata and returned only old known planes.
+2. A checkpoint containing only proposed strategy/tactics planes decoded to an empty semantic checkpoint under the old parser.
+3. The provenance parser rejected that same metadata version.
+4. Direct metadata serialization of the parsed old stream emitted version 2.
+
+These observations are not evidence that the installed extension emits or accepts a new semantic format in ordinary operation. They establish that **“bump metadata version and all old callers refuse” is too broad a compatibility claim**. The probe performed no disk publication.
+
+### Current admission hardening
+
+Native `classifyScopeStream` (and therefore `parseScopeStream`/`loadScopeStream`) admits declared v1/v2/v3 before interpreting semantic fields. Legacy input translates before target validation; v3 retired roots reject. `serializeScopeMetadata` refuses unsupported/missing versions on nonempty input, emits v3 and preserves opaque temporal siblings. The provenance reader shares the same supported-version predicate. A semantic stream requires complete temporal evidence; empty metadata is not permission to synthesize history.
+
+`tests/durable.test.ts` covers all three owners, supported versions, metadata siblings, invalid/future/missing versions, direct codec paths, serializer refusal and unchanged fixture bytes. An isolated baseline-source probe at `4494fee9da8258cdf5f02c42672a0eb9866a512a` additionally exercised real target v3 bytes on matching SDK 1.0.0: missing/empty provenance, unknown metadata siblings and sparse checkpoint state. The old low-level decoder admitted and filtered target fields, and its serializer would downgrade to v2. The complete old `refreshCurrentMemory`, `loadPassive` and `withStartTransaction` compositions all refused through provenance-version admission, before cache installation or publisher callback; canonical byte revisions remained unchanged. This proves those compositions, not every historical consumer. No live data or inference was used.
+
+### Required admission and rollout policy
+
+- Use reviewed scope metadata v3 for the target dialect; do not overload version 2 or rely on an ignored additive `semanticVersion` key.
+- Require the new implementation to admit the dialect before known-plane filtering, replay, provenance interpretation, and every supported serialization/publication entrypoint. Refuse unsupported or contradictory dialect evidence before it can become an apparently empty valid scope.
+- Validate old-client refusal on each supported old runtime/codec composition against synthetic target-format fixtures. Record which older clients cannot be fenced by their existing behavior. New code cannot retroactively fix an already shipped low-level parser.
+- Quiesce and upgrade all cooperating store writers before conversion. If any legacy caller can still reinterpret or overwrite target semantics, it is not a supported mixed-version writer and must be removed/upgraded before conversion. Do not claim protection against arbitrary/nonparticipating writers.
+- Do not insert invalid old-plane sentinel values, materialized nulls, duplicated semantic aliases, or new hidden memory just to trip an older validator.
+- An owner-format fence must survive unknown metadata siblings, sparse state, absent provenance registries, and the first target write. Off, inspection and runtime-only mode persistence cannot convert. An accepted owned Start transaction can; a UI receipt or pure policy choice alone grants no publication authority.
+
+**Supported boundary:** Upgrade/quiesce all cooperating writers; unsafe low-level mixed-version clients are not supported. If a deployment requires coexistence with one, do not convert that store without a separately reviewed bridge/representation. Broad implementation authorization does not authorize exact-store rollout. Legacy conversion and retired-root reservations remain supported throughout State Flow 0.x; their temporary support window ends at State Flow 1.0.0, while explicit unsupported-version refusal remains. The prepared0.27.0 candidate keeps its converter/reservations unchanged; no immediate removal, release or working-store conversion is authorized.
+
+## Public API impact inventory
+
+This is the local exported surface, not an inventory of external users. Absence of in-repository callers does not prove a public export has no consumers.
+
+| Export group | Verified surface and impact |
+| --- | --- |
+| Semantic types/defaults | `MaterializedState`, `SemanticState`, `StateDocument`, `ScopedStates`, `ScopedSemanticStates`, `StatePatch`, `ScopePatch`, `AtomicScopePatches`, `ScopedPatch`, `SemanticTransition`, `TerminalTransition`; `emptyState`, validators, overlay/projection and artifact-update helpers. Plane-name changes affect TypeScript and runtime values; defaulted views remain distinct from sparse semantics. |
+| History/temporal values | `RecentScopePatch`, accepted/recent transitions/windows, `TemporalState` and nested stream shapes; `createAcceptedTransition`, validators, advance/read/revision accessors. Typed paths and patch values change; IDs and offsets must not. |
+| Durable codecs | `ScopeStreamSources`, `TemporalScopePaths`, `parseScopeStream`, `loadScopeStream`, `serializeScopeStream`, `serializeScopeProvenance`, path/capture/update helpers. Separate version admission from field selection; do not let old-name callers silently discard data. |
+| Runtime methods | Exported `TemporalRuntime`, its `read`/`readView`/`states` values, constructor/default retention, patch/lifecycle/Start/fork transaction contracts, public synchronous methods, raw publication, and provenance accessors. Preserve publication ownership/detachment while documenting value-type changes. |
+| Query/tool interface | `parseStateReadPath`, `readStatePath`, query/result types, model tool descriptions/schema/guidelines and emitted receipts. Old native tool-result strings remain historical text; new invocation paths must reject retired grammar actionably rather than read a missing plane silently. |
+| Embedding/default factory | `StateFlowExtensionOptions` and its `onRuntime` callback expose default-bearing `ModelState` values transitively even though `ModelState` is not separately re-exported by name. Rebuilt declarations must match actual callback values. |
+| Operational guidance | Both packaged Skills, documentation, examples, status/Telegram inspection, and compiled Skill cards can contain old plane names or path syntax. Update trusted/package guidance consistently; preserve source provenance and do not rewrite arbitrary retained prose. |
+| Scope/transport identities | `StateScope`, session addresses, artifact ownership and Telegram scope selectors need no semantic rename. Future selection is an additive policy question, not permission to change canonical owner identity. |
+
+**Recommended design for D2:** Use a documented breaking public contract boundary for the semantic rename, with a supported legacy-data reader and explicit operator conversion. Avoid permanent dual old/new object properties or model-facing aliases. If actual consumer evidence requires a bounded adapter, specify its exact export, accepted dialect, failure behavior, and retirement condition separately; do not make all new types ambiguous by default. Do not choose a release number or publish anything in M0.
+
+## Publication and recovery boundary
+
+The conversion unit is one proven owner checkpoint/tail/metadata cohort, plus any actually required session runtime metadata in the existing exact-cohort transaction. Do not invent a whole-store kernel-atomic transaction, new journal, or new semantic transition to make representation conversion look atomic.
+
+A reviewed M1 implementation must distinguish:
+
+- **Before acceptance:** Validate all raw authority and collisions, produce detached candidates, verify every retained replay boundary, acquire the existing exclusion, recheck exact bytes/identity and approved writer policy, and publish once. Rejection/cancellation changes no accepted bytes or caches.
+- **After acceptance:** Install the proven candidate and preserve accepted values; a later UI/native checkpoint failure cannot undo it or rerun an already accepted conversion.
+- **Crash/partial publication:** Preserve incomplete evidence and fail closed under the current optimistic durability limit. Quiesce writers and reconcile exact cohorts manually; no automatic Git restoration or fabricated empty scope.
+- **Downgrade:** Restore a proven complete compatible backup through a separately authorized recovery operation. Do not run an old writer over new owner files, nor promise that a backup can be combined with unrelated later shared writes without reconciliation.
+
+Global/CWD are shared across independent sessions; private Session state and fork copies retain their identities. Native Pi checkpoints carry lifecycle/boundary evidence rather than semantic plane JSON. Reader changes must not turn an old native checkpoint into a memory rewind or require rewriting Pi's append-only history merely to rename a plane.
+
+## Acceptance and current evidence
+
+M1's acceptance map must include the following failure partitions, not only happy-path conversion:
+
+- Sparse checkpoints and retained deletions; legacy empty branches and arrays; history limits 0, 1, 7, and 100; no semantic revision for representation alone.
+- Raw dual-plane collisions before filtering, malformed authority, future dialect, and unknown unrelated metadata siblings.
+- Recognized structured/textual references, invalid reference-like ordinary data, cross-owner/non-owning references, and explicit old cascade deletions.
+- Every supported read/write entrypoint, especially low-level codecs and synchronous library calls; no proof by inference from the full runtime alone.
+- Shared competing writers, exact-byte drift while waiting, private identity contradiction, fork copy, rejected publication, interrupted cohort, and downgrade refusal.
+- Original versus translated historical reads under the approved D1 contract; a backup must not count as a model-history API.
+
+Focused baseline command:
+
+```bash
+node --experimental-strip-types --test tests/durable.test.ts tests/snapshot.test.ts tests/query.test.ts
+```
+
+Result on the source identity above: **34 passed, 0 failed**. Together with the synthetic admission probe, this supports the current evidence map. It does not prove target-version admission, migration, crash consistency, safe coexistence with arbitrary older clients, or a new public API.
+
+**Current status, superseding the original M0.2 gate:** M1's translated-history, supported-writer, target API and guarded publication decisions are implemented with the proof boundaries recorded above; the34-test paragraph is historical M0 baseline evidence, not their sole current validation. The owner settled temporary legacy conversion/reservations through State Flow0.x with a cutoff beginning1.0.0 and explicit unsupported-version refusal retained. The prepared0.27.0 candidate keeps its converter/reservations unchanged. No retirement-policy approval, transition plan or compatibility-removal task remains for this release; real-model evaluation is separately M0.4b in [BACKLOG](../BACKLOG.md#12-ordered-implementation-backlog). Writer quiescence, exact-cohort backup/private authority and separate authorization for release or working-store conversion remain mandatory.

package/node_modules/@llblab/pi-state-flow/docs/semantic-extensibility-decision.md

@@ -0,0 +1,75 @@
+# Semantic extensibility decision
+
+## Scope and accepted disposition
+
+The later explicit module request supplied additional manual, read-only, exact-window and asynchronous-producer requirements. The [internal semantic-module contract](semantic-module-contract.md) implements their bounded internal seam. The no-new-API decision below records the earlier M5 checkpoint, not a current prohibition; public loading, new stored planes, production archive/scheduler and sandbox/quality claims remain deferred.
+
+**M5 accepted decision: no NEW semantic-module API at that checkpoint; explicitly defer declarative manifests, module loading and executable invariant registration.** Retain existing internal functions and reviewed private protocol snippets. This is a demand/alternatives decision, not implementation of a module framework, a ban on future helpers, or a claim that there are no existing public APIs. Actual independent integrated review is **APPROVE — bounded no-new-semantic-module-API / explicit expansion-deferral decision**; its complete report was consumed after ROOT terminal before acceptance. [BACKLOG](../BACKLOG.md#12-ordered-implementation-backlog) alone owns remaining work.
+
+The accepted [M4 retain/defer decision](protocol-composition-decision.md) found no earned descriptor layer. M5 asks whether an actual caller or invariant needs a new contract despite that result. The bounded repository/design/task evidence below establishes useful existing functions but no currently unmet semantic-module requirement. It cannot establish that no external user anywhere wants modules. No external discovery, live user/model experiment or production-store inspection was performed.
+
+## Actual demand and smallest existing contract
+
+The authorized roadmap's offline-bundle scenario needs continuity of a binding outcome, accepted method and rationale, failed prerequisite, revision on contradictory evidence, intent closure and retained consequence. These are requirements for meaningful ordinary JSON, not inherently for adding a fourth plane, task schema or callback. The [handoff contract](semantic-handoff-contract.md#purpose-and-reconstruction-boundary) distinguishes these facts without requiring fixed record keys.
+
+The accepted [linked native checkpoint](single-scope-interface-contract.md#deterministic-m3-checkpoint) and the linked-checkpoint group in `tests/extension.test.ts` are a concrete mechanical witness: requirements/accepted approach/unaccepted proposal/prerequisites/dependencies are supplied JSON; a real native reload, reasoned partial revision, historical read and intent closure retain the appropriate consequence across all seven choices. This is a fixture-backed instance of that handoff structure, not an execution of the offline-bundle scenario, observed production demand or model discovery of the right plan. It does not prove that the external report was published, the premise was true, or a model will retain every commitment. Those quality claims remain gated separately.
+
+A minimal existing model-facing contract for that use case is, with **exactly Session wanted**, a direct flat patch such as:
+
+```json
+{
+  "strategy": {
+    "requirements": { "constraint": "No account operations" },
+    "accepted": { "id": "verify-first", "rationale": "The initial assumption was contradicted by fixture evidence" },
+    "prerequisites": { "inputAssumption": "failed" }
+  },
+  "tactics": { "reportWork": { "observation": "Verification passed", "next": "publish" } }
+}
+```
+
+Those nested names are example data, not a new schema, trust grant or required module envelope. Multi-owner wanted choices instead require selected explicit owner roots even when supplying one target. The original native request, wanted owner, readable/private/source authority and canonical atomic staging/publication still apply. A stored prohibition does not enforce account permissions; external effects require the existing host/tool policy and fresh evidence. A pure memory validator could not establish those facts merely by checking this JSON.
+
+Other observed needs already have distinct owners:
+
+- **Procedural reuse and source knowledge:** Registered Pi Skills and exact-source artifact compilation are existing facilities. Skill competence is not a new semantic plane. Source provenance/freshness, optional compilation and selected-owner placement remain runtime-owned; a Skill read or artifact body is not admitted trusted system-protocol text or publication permission.
+- **Protocol maintenance:** M4's real two-site owner-meaning wording could earn a tiny preventive private helper on an authorized meaning change. This is a credible local maintenance opportunity without a current bug, not evidence for a public manifest ABI or executable hook.
+- **Deterministic invariants:** Recursive JSON semantics, selected/canonical admission, same-scope intent cascade, artifact provenance, causal/private proof and final publication already have centralized owners. No demonstrated additional core-plane invariant in this scoped task is obstructed by those internal functions. This is not a theorem about all future domains.
+- **Integration/presentation:** `index.ts` already exports embedding APIs, and the optional Telegram presentation leaf has its own existing public adapter/loader. Those are not semantic-plane registration. Pi's existing extension/tool mechanisms are not a new State Flow module ABI, nor a reason to bypass an original State Flow request or move source/private/publication authority into an arbitrary tool. Host extensions already execute code; no sandbox guarantee is inferred from their availability.
+
+The illustrative `hypotheses` idea is not a requested fourth-plane acceptance case. Assumptions, contrary evidence and reconsideration conditions already fit task-appropriate Strategy/Tactics data. This does not prove a dedicated cognitive role could never help. Reaching M5 alone does not authorize that role, automatic promotions, additional scopes, optional-plane controls or storage changes.
+
+## Alternatives against the same need
+
+### A — Existing functions and private snippets (selected)
+
+Expresses the current task with ordinary JSON and the existing single engine. Determinism, failure atomicity, source/intent/publication ownership and prompt order stay under their existing tests. There is no new loader, dependency graph, manifest admission, stored envelope or public support/versioning commitment. Costs are package-owned edits and existing local wording synchronization. This does not eliminate maintenance work or promise general module expressiveness; a small private helper remains available when an actual edit earns it.
+
+### B — Static internal declarative descriptors
+
+Can single-source a genuinely repeated contract while keeping package-owned trust and fixed order. Testability would focus on completeness/order/mode/selection and exact prompt behavior; storage, publication and intent cascade would remain centralized. It still needs no external loader or API. M4 found the current three plane summaries one actual producer with existing shared fragments, so additional descriptor keys/assembly are not earned now. A second producer or preventive helper opportunity can be addressed privately without first promising third-party compatibility.
+
+### C — New public declarative manifest
+
+Could serve independently authored, independently versioned cognitive roles only if there is a real consumer and a reason reviewed package code is insufficient. That requirement is not established here. Even without executable callbacks, new trusted instructions/plane names need admission, collision policy, deterministic order, compatibility and a support owner. A data manifest is not automatically trusted because it is JSON; ordinary memory, source text and compiled Skills must never supply system authority. New top-level planes would also interact with the closed patch/read grammar, sparse storage/replay, retired roots and migration rather than merely add prose. These are qualitative costs, not measured implementation effort. No manifest schema or public version is sketched or frozen without demand.
+
+### D — Narrowly pure executable invariants
+
+Might express a real cross-field rule a future accepted use case cannot represent declaratively. Start with the smallest internal validation in the existing staged transaction if that requirement appears, not external registration or rewrite callbacks. A new rejection can break previously valid memory, so input semantics, compatibility and all-or-error acceptance must be explicitly reviewed. Testability additionally needs detached inputs, determinism, mutation isolation, fail-before-publication and adversarial cross-plane/selection cases. Rewrites/order/dependencies can create hidden reactions; no current case earns them. A TypeScript `readonly` or synchronous function signature cannot enforce absence of ambient I/O, time, randomness, inference or arbitrary JavaScript effects. Purity is not an implemented sandbox; untrusted executable modules are not admitted by this decision.
+
+## Boundary, counterargument and falsification route
+
+The strongest counterargument is future application-specific atomic validation or independent cognitive-role authorship: ordinary JSON and package edits may not meet every downstream need. Advice or an off-transaction native validator is not the semantic commit gate and cannot itself guarantee atomic rejection of a required cross-field relation. A concrete mandatory relation could justify a narrow internal check first, then an external seam only for an actual independent consumer that cannot use the existing owner. None is demonstrated here. Missing evidence is not proof of impossibility. The current decision declines the new support/trust surface because no identified caller or invariant in this authorized task actually requires it, rather than assuming plugins are always bad. Do not create a dummy consumer or fourth plane to make the milestone look implemented.
+
+No expansion is warranted now, so there is no new registration signature, loader, plane-name namespace, manifest parser, module configuration, staging callback or root export to support. Existing public APIs retain their current contracts. Any future proposal must first name an actual unmet task/caller or invariant, the smallest failing case using existing facilities, and why an internal helper, data convention or current shared-runtime change is insufficient. Before any separately approved API implementation, it must settle trust/admission and versioning, collision behavior, acyclic ownership/dependencies, prompt order and wanted-selection stability, compatibility with retained stores and atomic failure. A new invariant's effect on formerly legal memory or stored formats needs an explicit compatibility decision, not silent rejection on reload.
+
+The conditional proof plan is deliberately not a parallel task list: demonstrate that failing case; compare the smallest internal/declarative/validation alternative; preserve existing mode/seven-choice/flat-multi/source/private/causal/publication witnesses; and test only the newly admitted boundary including malformed inputs and failure atomicity. No I/O, lifecycle control, publication, inference, arbitrary loading or hidden reaction is allowed as a future semantic contract without a separately reviewed requirement changing that boundary. Type-level claims alone cannot discharge those proof obligations. Real reasoning/quality/cost claims still need the separately authorized model evaluation.
+
+## M5 disposition
+
+M5.1 audits a real authorized handoff need against four alternatives; no unmet module-API need is established within this bounded evidence. That is grounds for explicit deferral, not a manufactured consumer to satisfy an expansion dependency. M5.2 adds no boundary to implement: its trust/versioning/collision/ownership/compatibility questions above remain proof obligations for any separately justified proposal, not an approved manifest or sandbox. M5.3 records the no-new-API/defer choice, costs, counterargument and falsifiers. This completes the bounded decision milestone without implementing or promising deferred capabilities; it does not claim that a universal no-demand proposition was proved.
+
+## Evidence and limits
+
+No production/source/test/dist/package contract changes or live evaluation are proposed. Reuse the accepted M3 execution and M4 ownership/prompt evidence at their original proof levels through finite unchanged-input binding, not newly executed Source1611/SDK/protocol/typecheck/build/compiled299/compat36 totals. The linked fixture is supplied data and mechanical acceptance, not a universal domain-schema or cognitive adequacy test. No new runnable API prototype or invariant test is needed for a decision adding no API or invariant.
+
+The independent source/demand author returned; its complete actual terminal report was consumed. It inspected the actual task, existing public exports/producers, ordinary-JSON representation and linked fixture without inspecting this draft, and recommends explicit no-new-API deferral. Its evidence is read-only inspection with zero source/SDK tests, not approval of this integrated decision. Its strongest atomic-cross-field counterargument is retained above. Pre-review coordinator documentation1/1, context0errors/20warnings, DAG0/25 and diff passed. Scripts-disabled package membership is131: all130 prior paths retained plus only this decision. A bounded probe admits the one actual JSON sketch through existing DIST DATA normalization and rejects the sole wrapper; this is not a new API/invariant/SDK/store or authority test. The pack predates final prose/status refinements; count/membership are audited, not a final future tarball hash/size. They cannot themselves establish semantic prose accuracy, absence of global market demand or purity of arbitrary JavaScript. The complete actual terminal integrated review approves this bounded deferral after source/prose inspection, including the atomic-relation countercase and the unmet-demand/valid-no-API dependency tension. It independently checked160/160 before/after, old150 at147/150 with exactly BACKLOG/CHANGELOG/docs-index deltas, ran the actual DATA example and diff check. Documentation1/1, context/DAG, package membership and changelog counts were inspected coordinator evidence, not new reviewer executions; no source/SDK/typecheck/protocol/full/build/package run was attributed to review. A finite certificate is not all workspace/vendor/provider files or unknown callers. Closure changes only decision/index/changelog/BACKLOG disposition prose and reconciles already accepted M2/M3 choices, not behavior. M5 is closed as explicit expansion deferral without a feature promise; remaining M0 retirement and authorized real-model gates stay in BACKLOG. No next API backlog or Grow Loop iteration is earned merely by hypothetical falsifiers.

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

@@ -0,0 +1,174 @@
+# Semantic handoff contract
+
+## Status and authority
+
+**M1 semantic contract — locally implemented names and guidance, not a live-model quality claim.** Runtime fields, tools, ownership and callbacks now use `intents`, `strategy`, and `tactics`. Declared legacy `contract`/`working` data is translated under the [migration contract](semantic-compatibility-decision.md). Configurable scopes, flattening and module decisions remain in the [evolution backlog](../BACKLOG.md), which alone owns remaining tasks. The original M0 preservation evidence below remains bound to its old-name baseline.
+
+This contract makes the semantic handoff reviewable before implementation. It distinguishes model responsibilities from deterministic acceptance. It does not claim that any unconstrained model already follows these rules, or that new names improve task performance.
+
+Baseline for the evidence below: package 0.26.5, source commit `4494fee9da8258cdf5f02c42672a0eb9866a512a`, repository-local matching Pi SDK 1.0.0. No source or test changes were needed for this slice.
+
+## Purpose and reconstruction boundary
+
+An Active run can finish while the wider intentional activity remains unfinished. The next user run normally receives compiled semantic state rather than the completed reasoning trajectory. Native bootstrap and conservative context-retention exceptions remain governed by the [architecture](architecture.md#pi-lifecycle), not this design artifact.
+
+The handoff must allow a fresh executor to recover:
+
+1. The chosen outcome and its continuing applicability.
+2. Binding requirements and the source and limits of accepted commitments.
+3. The accepted approach, phases, prerequisites, important rationale, and rejected alternatives.
+4. Verified progress, negative evidence, obstacles, and decision-relevant uncertainty.
+5. The next useful action and evidence that would justify revising the approach.
+6. Consequences that must survive completion, abandonment, or supersession of the current intent.
+
+A plan is memory of an actionable reasoning outcome, not a transcript of reasoning. Continuing a valid accepted approach should not require rediscovering why it was chosen. Nevertheless, memory is fallible evidence, not proof that external conditions or tool effects are unchanged.
+
+A Pi Skill supplies reusable procedural competence. Strategy preserves a particular accepted application of competence to a situation. Tactics preserves the actual circumstances of executing it. No competing Skill system, planner engine, workflow scheduler, or second execution loop is implied.
+
+## Semantic responsibilities
+
+### Intents: chosen outcomes
+
+**Agreed direction:** An intent expresses an outcome the agent has chosen or committed to achieve, not every anticipated tool call. It may be a small string or task-appropriate JSON. There is no required task-manager schema, identifier format, timestamp, status enum, phase graph, or success predicate enforced by runtime.
+
+- Keep active chosen commitments explicit when they are needed for continuation.
+- Do not record a possibility as an adopted intent merely because it was discussed.
+- Remove fulfilled, abandoned, superseded, or impossible intents when their consequences have been reconciled.
+- Do not infer completion from intent deletion: the runtime cannot verify that the outcome occurred.
+- Permit multiple intents to share temporary memory, and permit unowned tactical content.
+
+### Strategy: accepted approaches and governing commitments
+
+**Agreed direction:** Strategy holds how the agent has decided to achieve an outcome, including binding constraints, accepted plans and phases, important assumptions, dependencies, architectural decisions, rejected approaches and reasons, and reconsideration conditions. It is not limited to speculative planning.
+
+A useful strategy lets a fresh executor distinguish three semantic facts without imposing a record schema:
+
+- **Requirement:** What remains binding, and under whose applicable instruction or accepted contract.
+- **Accepted approach:** What the agent has committed to use while it remains valid, with consequential reasons.
+- **Proposal/assumption:** What is not yet accepted or not yet verified, including what would change that status.
+
+A JSON field named `acceptance` is an illustrative representation, not proof of user approval. Acceptance is grounded in the actual task instructions and decisions; do not invent a user approval event or treat assistant conclusions as higher-authority requirements. Existing binding `contract` data must not become optional simply because its plane is renamed.
+
+Continue an accepted approach while it remains applicable. A concrete contradiction, changed requirement, invalidated prerequisite, or evidenced failure can justify revision. Preserve still-binding constraints and consequential negative evidence when changing methods. One faulty implementation does not by itself disprove an entire approach.
+
+### Tactics: operational memory
+
+**Agreed direction:** Tactics holds what is actually happening: verified progress and tool outcomes, failures, obstacles, relevant uncertainty, immediate operational choices, and exact next work. It is neither a commands-only plan nor append-only tool chatter.
+
+- Record observations separately from predictions and assumptions when the distinction affects action.
+- Retain sufficient evidence to explain a strategic revision without copying raw tool output.
+- Distinguish “not yet checked,” “check failed,” and “check passed”; absence of a failure entry is not success.
+- Revalidate consequential volatile effects before repeating actions after interruption or restoration.
+- Remove superseded temporary progress from touched branches while preserving material corrections and rejection reasons.
+
+The runtime does not judge whether a claimed observation is true or important. Deterministic JSON acceptance and model evidence quality are different proof obligations.
+
+## Model reconciliation contract
+
+**Agreed direction:** Intents give direction; strategy guides execution; tactics supplies operational evidence. These relationships are enacted by reasoning over shared state through Pi's ordinary tools.
+
+A useful handoff is not a prescribed patch sequence. The model may plan, inspect, act, and revise in any task-appropriate order, provided future-relevant memory is accepted before relying on Active state-only continuation. If the required memory is already correct, completion needs no patch.
+
+For a consequential strategic revision, preserve enough information to answer:
+
+1. Which observation or changed instruction invalidated the former assumption/approach?
+2. Which requirement remains binding?
+3. What revised approach is now accepted, why, and what remains uncertain?
+4. What next operational work follows from the revision?
+
+Do not install an automatic rule that tactical failure rewrites strategy. The model must decide whether the failure is strategic, implementation-specific, transient, or still inconclusive. Do not silently replace a binding user requirement to make a failing validation appear successful.
+
+## Temporary-memory lifetime contract
+
+**Current lifetime rule:** Structured intent references own eligible same-scope `strategy`, `tactics` and `lazy` object keys. Apply intents, clear targets not protected by final remaining/new intents, then apply other authored planes; this intentional change supersedes the former strategy-ineligible/authored-first policy. Retained history replays explicit net patches, not a recomputed cascade.
+
+1. Apply only authored intents and their supplied-scope empty-object normalization, independent of JSON insertion order.
+2. Identify intent keys present before staging but absent afterward. This includes an intent removed by pruning its last child, not just an explicit top-level `null`.
+3. Extract structured `$ref` targets anywhere in each removed intent value.
+4. Consider only existing object-key targets under same-scope strategy, tactics or lazy content, using the supported ASCII path grammar.
+5. Retain any target referenced by a final remaining or newly added same-scope intent, including a reference to an ancestor or descendant.
+6. Clear the remaining minimal targets, then apply remaining authored planes before existing compilation/normalization and atomic publication. Same-path rewrites create fresh knowledge without old fields.
+7. Store the actual net result as explicit accepted patches; retained replay never reruns cascade. Existing strategy refs own future accepted intent deletions only, without rewriting old history. `cascaded` lists intermediate cleared paths even if recreated; final effective values govern.
+
+This does not confer dependency, hydration, existence, execution, completion, or instruction authority on references.
+
+### Boundaries that must survive
+
+- A textual `$path` mention is non-owning. Structured references outside intents are also non-owning.
+- Cross-scope, effective, historical, plane-root, array-element, missing, and non-strategy/non-tactics/non-lazy targets are silently ineligible for cascading. They must not reject, warn about, or delay an ordinary patch.
+- Editing an intent to drop a reference leaves its former target unowned; it is not intent deletion.
+- One-patch supersession can delete the old intent while a replacement protects the same target.
+- Writing to a cleared target in the closing patch recreates it after cleanup, without retaining old fields.
+- A cascade is scope-local. Deleting a local tactical value can reveal an inherited value at the same effective path.
+- Strategy cascades too. Preserve durable results, accepted decisions, rejection reasons and still-relevant plans by explicitly rewriting them at the same or a new appropriate path in the closing patch.
+- Lazy content can itself be temporary; no semantic plane is an automatic safe haven from ownership cleanup.
+- Consequential survivors can be saved at an unowned appropriate path in the same atomic patch. This is model-authored reconciliation, not runtime promotion, archiving, or movement between scopes.
+
+The current reference grammar is explicitly scoped. Single-scope normalization is M3 work, not permission for M0 to change how unscoped stored references acquire ownership.
+
+## Patch, mode, and trust constraints
+
+This contract inherits [model-tool semantics](architecture.md#model-tools); it does not define a second patch language.
+
+- Planes remain optional object roots; their domain content remains ordinary JSON.
+- Object patches merge, arrays/scalars replace, omitted nonempty fields persist, and object-key `null` deletes. Accepted supplied scopes prune empty object branches; array slots and empty arrays survive.
+- No materialized semantic nulls, model-authored response/config/provenance, or empty acknowledgement-only scope patches.
+- One atomic cohort produces explicit accepted changes. No-op repeats produce no new semantic transition. An Active patch remains an inference barrier; Passive does not gain a new barrier by implication.
+- Active preserves necessary handoff memory before completed prior trajectory leaves normal projection. Passive can use the same semantic distinctions on demand without mandatory consolidation or a State Flow iteration reset. Off exposes no State Flow model context or tools.
+- Global, CWD, and Session can all carry the three core semantic functions. Later overlay precedence is composition, never evidence of greater truth or instruction authority. Configurable participation is not implemented by this contract.
+- References and state values are data. Package-reviewed trusted protocol may explain the planes, but ordinary memory, artifact compilations, or lazy values cannot alter system instructions.
+- Runtime publication, source provenance, response capture, native lifecycle ownership, and frozen-head reconciliation retain their established independent owners. The semantic relationship is not a module callback or hidden event network.
+
+## Acceptance map
+
+The IDs below name contracts/oracles, not new runtime record types. Existing tests witness the old-name preservation mechanism. New-name native and model-behavior acceptance belongs to later milestones; this table is not a claim those tests already exist.
+
+| ID | Obligation and falsification scenario | Evidence owner |
+| --- | --- | --- |
+| SH-1 | Resume an accepted phased approach after an Active boundary without losing the binding requirement, rejected alternative, prerequisite, or next action. Fails if the model rediscovers or replaces a still-valid approach without grounds. | Current protocol/Skills provide stewardship guidance; M0.4 behavioral baseline and M1 native/model comparison prove use. |
+| SH-2 | Preserve proposal versus acceptance and requirement versus observation distinctions. Fails if storage location alone upgrades a hypothesis into a commitment or weakens an existing requirement. | Model rubric over authorized task evidence; runtime shape tests cannot establish acceptance or authority. |
+| SH-3 | Retain failed-check evidence while revising an invalidated assumption. Fails if a partial strategy patch loses the original requirement, prior rejection, or unaffected phase dependency. | Five-example mapped replay below; future M1 model continuation evaluation. |
+| SH-4 | Close an intent while explicitly rewriting durable consequences; clear owned strategy/tactics/lazy targets before remaining authored writes. Fails if old fields survive a cleared-target rewrite or another remaining/new intent loses its protected target. | `tests/ownership.test.ts`, `tests/transition.test.ts`, mapped example 5; future M1 native cascade receipt. |
+| SH-5 | Preserve same-scope shared/related-target protection, supersession, and edit-only behavior. Fails if another surviving intent loses its referenced target, text gains ownership, or cross-scope memory cascades. | `tests/ownership.test.ts` and `tests/transition.test.ts`; future M1 renamed references. |
+| SH-6 | Preserve sparse state, no-stored-null rules, detachment, explicit accepted cascade deletions, and exact retained replay. Fails if staging changes inputs, creates stored empty defaults, or replay needs to derive ownership again. | `tests/state.test.ts`, `tests/transition.test.ts`, `tests/temporal.test.ts`; future M1 codec/migration oracle. |
+| SH-7 | Preserve the frozen-prefix, trust, scope, response, and provenance boundaries while using the new semantic guidance. Fails if a memory patch changes system rules, relocates source ownership, or introduces a finalization inference. | Current `tests/protocol.test.ts`, `tests/context.test.ts`, response/Skill/native test families; M1–M4 integration checkpoints. |
+
+### Five-example review exercise and answer key
+
+The five JSON patches in [BACKLOG §5.2](../BACKLOG.md#52-coherent-target-examples) form one sequential example, not five unrelated snapshots. A reviewer should be able to reconstruct the following without the original design conversation:
+
+1. **Open outcome:** Prepare an offline-verifiable release bundle. The intent owns `session.tactics.release` through a structured reference. No claim of final validation success exists.
+2. **Accepted strategy:** Offline verification without credentials remains the user's binding requirement. Preparation precedes network-isolated validation. Bundled verifier v1 is the accepted approach; its self-containment is an assumption. Online-only verification was rejected because it cannot satisfy the requirement.
+3. **Contradictory observation:** Isolated validation failed because the verifier attempted to fetch a trust index. Whether an embedded index suffices is unresolved; inspecting the offline-index interface is the next useful action. Do not close the intent.
+4. **Reasoned revision:** Source inspection supports the local-index option. Accept an embedded trust index, preserve the offline requirement, original online-only rejection and validation dependency, and retain why default v1 was rejected. Delete only the resolved uncertainty. Previous failed validation remains recorded; a revised approach is not a passed revalidation.
+5. **Closure after verification:** The example's precondition supplies successful coverage and isolation checks. Preserve that conclusion in strategy, remove the release intent, and cascade its tactical context. The remaining strategy retains the requirement, revised decision, phases, and both rejection reasons in Session. Nothing moves to Global/CWD and no answer is model-patched.
+
+The fifth precondition is a semantic claim supplied by the scenario. A deterministic patch probe cannot establish that those external checks actually ran. M0.4 must use independently verifiable task evidence before rewarding a model for making that claim.
+
+## Source-bound validation evidence
+
+M0.1 checked the example against existing mechanisms without implementing the rename:
+
+- Extracted the five JSON patches from the linked backlog section.
+- Mapped only the scope-root plane names `strategy → contract`, `tactics → working`, and corresponding scoped structured-reference plane segments. Did not rewrite arbitrary prose/domain keys, change source files, or persist a converter.
+- Staged and committed each mapped patch entirely in memory with `stageAtomicScopePatches` / `commitScopedTransition`, no acquired sources and no run finalization; replayed the actual accepted records with `advanceTemporalState`.
+- Asserted staging detachment, unchanged Global/CWD, binding-requirement retention, both rejection reasons, surviving phase dependency, retained failed-check evidence after revision, deletion of only resolved uncertainty, and absence of authored response.
+- Asserted one closing cascade, disappearance of empty intent/tactical planes, retained strategic conclusion, and an explicit accepted tactical deletion. Re-read all six materializations: the origin and each of five accepted boundaries.
+- Result: five material transitions, Session revisions 1–5, Global/CWD revisions 0, one cascade only at closure, and all six retained materializations equal their captured snapshots. No live canonical store was read or written by this probe.
+
+Historical focused-source command (not validation of the current cascade contract):
+
+```bash
+node --experimental-strip-types --test tests/state.test.ts tests/ownership.test.ts tests/transition.test.ts tests/temporal.test.ts tests/protocol.test.ts
+```
+
+Result for the source identity above: **76 passed, 0 failed**. These tests cover current old-name semantics; they neither certify an unimplemented rename nor substitute for M0.4 real-model baseline evidence. The in-memory example probe did not exercise disk CAS, migration, provider schemas, new selection policy, or flat-reference conversion.
+
+## Remaining boundaries
+
+The semantic meanings and preservation obligations above are the M0.1 handoff. The [canonical backlog](../BACKLOG.md#12-ordered-implementation-backlog) owns outstanding work:
+
+- M0.2 must settle the historical representation, collision/dialect fence, and public-API compatibility contract before M1 changes codecs.
+- M0.3 must settle selection metadata, disabled-stream authority, response-without-Session, and fork policy before M2.
+- M0.4 must obtain source/model-bound behavioral observations; no such evaluation was performed in this slice.
+- Schema adaptation, flat paths, module loading/hooks, and later milestone implementation remain excluded from M0.1. Nothing in this document enables them implicitly.