@llblab/pi-kit 0.37.1 → 0.38.1

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

@@ -4,24 +4,31 @@
 
 State Flow is a Pi extension that materializes compact, scoped semantic state across agent runs while preserving Pi's native session trace and tool loop. It is inspired by SKILL.state but uses its own temporal model, storage plane, artifact compiler and publication lifecycle.
 
-The extension owns durable memory while enabled. Global semantic memory is always available; there are no ownership or global-memory feature switches.
+The extension owns durable memory while enabled. The native bridge admits all seven nonempty captured selections through one selected runtime; missing configured scopes retains all three. Scope participation is neither an authority ranking nor an acquisition grant. Native policy DATA, accepted storage, model requests and independently owned controls retain distinct proof boundaries. Existing mode commands bind optional scope tokens to these same owners; mode-only Telegram actions preserve the captured choice. See [public command boundary](scope-selection-contract.md#public-mode-command-scope-overrides) and [retained native integration](scope-selection-contract.md#retained-native-seven-selection-integration).
 
 ## Composition
 
 `index.ts` is the minimal public export boundary. `lib/extension.ts` is the Pi lifecycle composition root: it wires configuration and domain capabilities into commands, tools, event subscriptions and handlers, and delegates imperative mechanics to their owning modules. Each independent module under `lib/` owns one concern and is mirrored by tests:
 
 - `state`, `json`: semantic shape, validation, recursive overlay and deletion.
-- `temporal`, `history`: causal boundaries, checkpoint/tail folding and hot history.
-- `durable`, `storage`, `git`: exact canonical files, file-cohort CAS, and optional settled-turn backup, including its due/permitted/cancellation state (`SettledTurnBackup`).
-- `snapshot`, `session`, `runtime`, `recovery`, `episode`: Pi branch/runtime lifecycle, branch traversal, and passive-boundary interpretation.
-- `transition`, `ownership`, `context`: inference barriers, turn resolution, intent-ownership cascades, passive projection, and response reconciliation.
+- `config`: read-only load-time repository defaults, including immutable configured scope data. [Native capture](scope-selection-contract.md#configured-scope-defaults-and-native-capture) freezes defaults once into branch policy, without itself granting memory authority.
+- `selection`: pure immutable nonempty owner selections and command-token parsing. Value capture grants no mode, lifecycle authority, I/O or storage participation by itself; see the [selection boundary](scope-selection-contract.md#internal-value-boundary-and-lifecycle-encoding-direction).
+- `temporal`, `history`: causal boundaries, checkpoint/tail folding and hot history. Internal [selected temporal algebra](scope-selection-contract.md#selected-temporal-value-algebra) retains only participating streams and metadata-only excluded-step witnesses; algebra alone grants no native storage/runtime admission.
+- `migration`: temporary pure legacy-to-target conversion, root-name guards, reference translation and serialized preflight. `durable` consumes it before known-field filtering; `storage` alone owns backup and guarded conversion publication. It does not own I/O or lifecycle; see the [migration boundary](semantic-compatibility-decision.md#serialized-owner-cohort-preflight).
+- `durable`, `storage`, `git`: exact canonical files, file-cohort CAS, and optional settled-turn backup, including its due/permitted/cancellation state (`SettledTurnBackup`). Internal [selected admission](scope-selection-contract.md#read-only-selected-cohort-durable-admission) binds v2 owner witnesses and separates exact byte dependencies from private/layout presence. [Selected publication](scope-selection-contract.md#guarded-selected-cohort-publication) derives replay/witnesses and backs up lifecycle upgrades; the [explicit origin boundary](scope-selection-contract.md#explicit-new-shared-only-origins) and [first Session acquisition](scope-selection-contract.md#explicit-first-session-acquisition) can create/adopt selected storage; [child-owned fork deferral](scope-selection-contract.md#child-owned-selected-fork-deferral) avoids parent reads while Session is excluded. The [selected parent-current copy boundary](scope-selection-contract.md#selected-parent-current-private-copy) accepts independently proven eager/deferred copies; [selected current-session acceptance](scope-selection-contract.md#selected-current-session-acceptance) preserves aligned history or admits current shared drift. The [private reselection basis](scope-selection-contract.md#acquired-private-reselection-proof-boundary) retains acquired Session authority independently across shared-only origins without opening excluded private bodies; missing/false proof never becomes empty or foreign memory. [Accepted selected cache/reads](scope-selection-contract.md#accepted-selected-runtime-cache-and-reads) now use one discriminated memory slot. [Selected semantic transactions](scope-selection-contract.md#selected-semantic-transactions-and-provenance-publication) reuse one staging/commit and successor planner with guarded targets and opaque-preserving metadata deltas. [First authoring](scope-selection-contract.md#selected-first-authoring-origin-routing) captures the selection before waiting and chooses the existing shared/private origin path without an intermediate empty publication. [Selected source-facility admission](scope-selection-contract.md#selected-source-facility-admission) now filters acquisition/maintenance/rehydration and Skill evidence before disabled-source observation. [Complete native policy/marker admission](scope-selection-contract.md#complete-native-policy-and-marker-admission) now resolves scoped branch choices independently from fences/pending copy. [Default-all-three native turn/tool/answer correlation](scope-selection-contract.md#native-turn-and-tool-batch-request-correlation) is now installed using SDK turn/finalized-ID evidence, not provider payloads. [Native context/preparation leases](scope-selection-contract.md#native-context-and-preparation-request-admission) now gate store waits and available pre-provider checkpoints through public Abort, without coupling independent control work to model cancellation. The [default-all-three native bridge](scope-selection-contract.md#default-all-three-native-bridge) composes these owners and passes aggregate integration. [Nonfork policy binding](scope-selection-contract.md#guarded-nonfork-native-selection-binding) forwards captured scopes and shares atomic first authoring; [header-only fork disposition](scope-selection-contract.md#canonical-fork-disposition-before-native-copy) distinguishes deferred acquisition from acquired child-current without semantic observation. [Explicit first-Session Start](scope-selection-contract.md#explicit-native-first-session-activation) separately grants exact-base unacquired acceptance without losing known private denial; ordinary resume cannot. [First mutation over unacquired source](scope-selection-contract.md#native-first-mutation-over-an-unacquired-source) composes the same staging/commit engine under live physical-owner receipts. [Fresh shared-fork deferral](scope-selection-contract.md#guarded-fresh-shared-only-fork-deferral) uses a mode-only late sampler and child pending retention; [Native scope-only lifetime evidence](scope-selection-contract.md#native-scope-only-lifetime-evidence-and-future-control-duty) validates existing request epochs/operation slots without another holder. [Native seven-selection integration](scope-selection-contract.md#retained-native-seven-selection-integration) exercises these same ports, not a second engine; public scope overrides now compose the same restoration/Start/Off owners without another runtime.
+- `snapshot`, `session`, `runtime`, `recovery`, `episode`: Pi branch/runtime lifecycle, branch traversal, and passive-boundary interpretation. Snapshot/session also provide detached [lifecycle-v2 candidate preflight](scope-selection-contract.md#detached-policy-and-lifecycle-preflight) and [selected policy-bound request lifetimes](scope-selection-contract.md#selected-policy-bound-request-lifetime), reusing renewable cancellation and synchronous native rechecks without storage/acquisition authority. Lower policy candidates do not confer canonical admission/publication. [Accepted selected lifecycle ports](scope-selection-contract.md#accepted-selected-lifecycle-ports) capture accepted run/v2 checkpoints without I/O and persist strictly Passive mode changes without current-origin adoption, semantic conversion or run resets; they do not themselves install native selected attachment. [Read-only observation ports](scope-selection-contract.md#selected-read-only-observation-ports) share that same runtime slot without accepted/publication authority: shared inspection never reads Session/lifecycle, while owned current observation retains required epoch/private proof and omits planned absent owners. The same policy lifetime binds selected native requests/context/preparation/tools/answers across all seven selections, including withdrawal before held exclusion releases; native policy selection alone still confers no publication permission.
+- `transition`, `ownership`, `context`: inference barriers, turn resolution, intent-ownership cascades, passive projection, and response reconciliation. Internal [selected semantic staging/commit](scope-selection-contract.md#selected-semantic-staging-and-commit) reuses the same engine without disabled owners; native response/policy composition uses the same seven-selection bridge. Session-excluded completion finalizes lifecycle without a semantic response transition or hidden private owner.
+- `query`: current/historical value projection and shared semantic-locator syntax; parsing alone resolves no target and confers no authority.
+- `model-interface`: Detached flat/canonical locator/ref and typed target/pointer presentation, consuming existing query/selection/JSON contracts, never storage/native authority. Actual native sole-flat/multi-explicit read/patch callers use it after original M2 admission. Arity-only schema refresh and fresh SDK definitions preserve old wrapper identity; the [deterministic functional interface](single-scope-interface-contract.md#deterministic-m3-checkpoint) is accepted, not live-model quality.
 - `compaction`: completed-history compaction planning and per-request marker state (`StateFlowCompactionRequests`).
-- `operation`: `OwnedOperationSlot`, the single-owner cancellation slot used by Start, inactive-mode persistence, branch restoration, inference preparation and response reconciliation; identity-guarded release keeps late completions from clearing newer work. `RenewableLifetime` owns the shared-inspection and memory-tool cancellation lifetimes.
+- `operation`: `OwnedOperationSlot`, the single-owner cancellation slot used by Start, inactive-mode persistence, branch restoration, inference preparation and response reconciliation; identity-guarded release keeps late completions from clearing newer work. `RenewableLifetime` owns the shared-inspection and memory-tool cancellation lifetimes and underpins internal selected policy requests. Slot cancellation/lifetime renewal expose replacement ownership before synchronous abort dispatch so reentrant listeners cannot erase newer work.
 - `artifact`, `acquisition`, `skills`, `rehydration`: source routing and compilation; `ArtifactAcquisitionState` owns the selected branch's invalidation plan, model hints and correlated read candidates.
-- `memory`: generic memory-bearing scope diagnostics.
+- `memory`: memory-bearing scope diagnostics; explicit selection returns only present selected flags while the legacy no-selection signature retains all-three behavior.
 - `continuation`: native-header discovery, runtime-provenance inspection, deterministic recommendation, and host startup precedence.
-- `protocol`, `logging`: model/tool presentation and bounded diagnostic persistence.
-- `status`, `telegram`, `extension`: operator projection, the optional fail-open pi-telegram presentation adapter, and high-level Pi adapter wiring.
+- `protocol`, `logging`: Model/tool presentation and bounded diagnostic persistence. Existing trusted plain renderers/private snippets and their context/extension trust boundaries are evaluated in the [protocol composition decision](protocol-composition-decision.md), without moving semantic execution into prompt hooks.
+- `status`, `telegram`, `extension`: operator projection, the optional fail-open pi-telegram presentation adapter, and high-level Pi adapter wiring. Internal [selected observational diagnostics](scope-selection-contract.md#selected-observational-diagnostics-and-projector-admission) render exact sparse owners/revisions without disabled values or fabricated zeros. Existing context/cascade/handoff projectors need no second selection API when fed accepted selected read projections; native presentation uses the selected bridge. Status separates captured requested policy from exact available materialization, including an unacquired Session requested alongside observable shared owners. Neither status nor Off invents an owner/revision or performs acquisition; command scopes use the existing native policy/mode owners.
+
+Test placement is checked in both directions by `tests/invariants.test.ts`: LIB modules have same-named mirrors, and every suite has an exact production owner or a reasoned cross-domain exception. The benchmark suites mirror `benchmarks/benchmark.ts` and `benchmarks/benchmark-session.ts` rather than being exceptions. The four exception reasons live in the invariant itself. Shared fixture modules may set up, read and assert, but cannot be hidden suites: the source-hygiene check erases TypeScript types before checking literal test-runner/suite dependencies and direct registration forms. This is not an arbitrary-code sandbox or a proof of semantic case ownership; independent organization review remains necessary.
 
 ## Semantic state
 
@@ -30,17 +37,17 @@ Runtime views select these documented semantic planes when present. Stored scope
 ```json
 {
   "intents": {},
-  "contract": {},
-  "working": {},
+  "strategy": {},
+  "tactics": {},
   "artifacts": {},
   "response": "",
   "lazy": {}
 }
 ```
 
-- `intents` is the queue of chosen actions, not a planner, scheduler, task manager or execution loop. An intent may own same-scope `working`/`lazy` keys by structured reference; see [model tools](#model-tools).
-- `contract` retains durable requirements, decisions, interfaces and rejected approaches.
-- `working` is the temporary working context of those actions: verified current facts, results and uncertainties.
+- `intents` is the queue of chosen actions, not a planner, scheduler, task manager or execution loop. An intent may own same-scope `tactics`/`lazy` keys by structured reference; see [model tools](#model-tools).
+- `strategy` retains binding requirements, accepted approaches/plans, decisions, interfaces and rejected alternatives. Proposals remain distinguishable from commitments; operational contradiction does not silently cancel a binding requirement.
+- `tactics` is the temporary working context of those actions: verified current facts, results and uncertainties.
 - `artifacts` maps exact source paths to compiled routing metadata.
 - `response` is owned only by the session scope and stores the exact latest accepted assistant answer, including the empty string. Global/CWD do not receive newly accepted answers, and stored scopes may omit response entirely. An explicit nonempty Session answer overrides inherited values; an empty or absent response contributes nothing to Active projection. Automatic Passive context omits the response plane, including frozen Stop handoffs and state-update receipts. Canonical storage, explicit reads and native answer text are unchanged.
 - `lazy` is an optional stored object root for ordinary JSON detail. It defaults to `{}` only in internal compatibility views, is omitted from baseline model state and is read explicitly.
@@ -58,7 +65,7 @@ Later scopes win. A scope-local `null` deletion removes only that scope's key an
 
 **Sparse state.** Missing planes are valid sparse semantics, not incomplete storage.
 
-- Checkpoint/tail codecs select only known top-level fields on read and write; unknown fields are neither kept in runtime streams nor carried into later writes. Nested data within known planes stays intact.
+- Checkpoint/tail codecs admit declared versions before interpreting fields. Legacy v1/v2 cohorts normalize to target v3 through raw collision-checked conversion; target retired roots reject. Candidate metadata4 adds retained external-plane descriptors outside semantic content: declared object values and still-retained history survive missing definitions, unrelated core writes, folding and fork. Legacy unknown roots are not silently adopted; explicit conversion to4 checks raw external-namespace collisions before filtering. Owned conversion first backs up exact original bytes outside canonical authority. Public external tool/context activation remains separate from codec retention.
 - Retained record identities and positions survive even when filtering leaves an empty patch.
 - `readTemporalView` selects present known fields at the requested boundary, then overlays scopes without inventing fields.
 - Empty and absent responses mean the same for Active projection; clearing a nonempty response projects as a deletion. Passive omits the plane regardless of its value.
@@ -116,7 +123,7 @@ checkpoint.json + patches.jsonl
 `patch_state` is the sole mutation tool:
 
 1. It acquires store exclusion before selecting current Global/CWD.
-2. It stages the authored operations while preserving private Session ownership.
+2. Preserving private Session ownership, it applies intents only, clears deleted intents' eligible same-scope strategy/tactics/lazy object-key targets protected by no final remaining/new intent (including ancestor/descendant references), then applies remaining authored planes before existing compilation/normalization. These phases ignore JSON insertion order; rewriting a cleared target creates fresh knowledge without old fields. Unowned entries remain legal.
 3. It validates and publishes one atomic cohort. Replay, history and revisions use that actual basis; correct repeats create no semantic transition.
 4. It then acts as an inference barrier: Pi executes no sibling tools from the same assistant response, and the next inference sees the rematerialized current effective state.
 
@@ -131,10 +138,10 @@ A successful native tool result may include a `state_updates` block, separate fr
 - Indexed-array patch selectors become numeric update paths only against a communicated in-bounds array basis. Object keys with the same spelling are literal.
 - Artifact cards use the normal metadata filter, and touched cards replace their whole projected entry.
 - Lazy bodies never enter this block; a changed bounded `lazy_navigation` may accompany it.
-- An optional `cascaded` array lists owner-scoped paths removed by intent deletion, including nested lazy targets that do not change the top-level navigation. It contains paths only, never values, and is absent when no target cascaded.
+- An optional `cascaded` array lists owner-scoped paths cleared in the intermediate ownership phase, even if remaining authored planes recreate them, including nested lazy targets that do not change the top-level navigation. It contains paths only, never values, and is absent when no target cascaded.
 - Unrelated unchanged branches are omitted. A result with nothing left to reconcile and no cascade has only the acknowledgement.
 
-**What is always included.** Entries conservatively cover changed scope fallbacks, masked or overlapping multi-scope touches, and projected changes since the last communicated view, including shared refreshes before or during the transaction. `cascaded` lists every target computed during accepted staging, in deterministic per-scope order across Global, CWD and Session. It is never elided as predictable: a receipt with only `cascaded` and an empty `effective` array still reaches the model. The owner path does not imply effective absence; `effective` entries still describe any revealed fallback.
+**What is always included.** Entries conservatively cover changed scope fallbacks, masked or overlapping multi-scope touches, and projected changes since the last communicated view, including shared refreshes before or during the transaction. `cascaded` lists every target computed during accepted staging, in deterministic per-scope order across Global, CWD and Session. It is never elided as predictable: a receipt with only `cascaded` and an empty `effective` array still reaches the model. The owner path does not imply final absence; `effective` entries describe actual final values, including authored recreation or revealed fallback. Accepted history stores explicit net patches and never reruns cascade; existing strategy references affect future accepted intent deletions without rewriting history.
 
 **What may be omitted as predictable:**
 
@@ -193,7 +200,7 @@ The cache owns no persistence, publication authority or continuation scheduler,
 ## Lifecycle planes
 
 ```text
-SEMANTIC STATE       intents + contract + working + artifacts + response + lazy
+SEMANTIC STATE       intents + strategy + tactics + artifacts + response + lazy
 MUTATION BARRIER     patch_state(scope patches) → rematerialized next inference
 CONTEXT PROJECTION   Active state | Passive memory/handoff | Off: no injection
 ```
@@ -375,7 +382,7 @@ meta.json
 - Predecessor combined session metadata is unsupported; session `meta.json`, `config.json` and `runtime.json` must already satisfy their canonical ownership contracts.
 - Metadata writers replace only their owned leaves and preserve JSON-safe unknown siblings.
 - A scope without a revision counter initializes it from the still-retained semantic tail and persists that baseline on its next owned write; folded ancestry is not guessed.
-- Revision-aware writes emit scope metadata version 2 and still read version 1. The version fence makes an older writer refuse a scope after its first revision-aware write instead of silently dropping the counter; all cooperating instances should still upgrade together.
+- Scope metadata v3 declares Strategy/Tactics; candidate v4 additionally carries retained module descriptors, including unavailable/deleted-content slots. Legacy1/2 and explicit upgrades to4 use the same complete-cohort backup/exclusion/CAS boundary; raw external namespace collisions reject. Core-only streams keep v3 output, while v4 writes cannot drop or alter retained schema/policy descriptors. Representation alone changes no revision or causal identity; runtime-only persistence and inspection never upgrade. Quiesce old writers: version refusal cannot retrofit unsafe deployed callers.
 - Supported flag-based settings and native `{disabled:true}` markers decode read-only. Mixed session `mode`/`enabled` representations are rejected, and no eager migration runs.
 - Revision-pointer checkpoints are unsupported and fail closed without Git restoration.
 
@@ -594,7 +601,7 @@ A model-visible artifact entry requires only a non-empty description:
 - At artifact-entry level, every model scope patch rejects authored `hash`, `compiler`, `compiled_at`, `sourceHash`, `sourceFingerprint`, `compilerRevision`, `compiledAt`, `source_hash_verified` and `hint` fields, including field-deletion markers, even without a preceding read.
 - Retained embedded evidence stays readable, but its embedded `hash`/`compiler`/`compiled_at` fields are omitted from model projection. Ordinary semantic edits and whole-artifact deletion stay valid.
 - Compiler output may add other finite non-null JSON metadata. Known optional semantic fields include `kind`, `tags` and `compilation`. Tags are unique trimmed non-empty strings that support deterministic candidate filtering, but never authorize reading.
-- The `contract.compiled_skills` location is rejected. Skill compilations belong only in source-addressed artifacts, with no fabricated source hashes.
+- The `strategy.compiled_skills` location is rejected. Skill compilations belong only in source-addressed artifacts, with no fabricated source hashes.
 
 **Deciding whether to compile.** The public `classifyArtifactCompilationNeed` owns acquisition/rehydration and ordinary-artifact Pi decisions.
 
@@ -634,14 +641,14 @@ Curation may persist reusable guidance from a registered Skill at its provenance
 **Terminal state is a decision-relevant handoff, not a progress transcript:**
 
 - operational knowledge → source-addressed artifacts;
-- confirmed constraints/decisions and rejected approaches → contract;
-- observations/failures/uncertainties and exact continuation → working;
+- binding requirements, accepted plans/decisions and rejected approaches → strategy;
+- observations/failures/uncertainties and exact continuation → tactics;
 - only chosen active commitments → intents.
 
 Distinguish user requirements from assistant conclusions and hypotheses, and keep consequential negative evidence and reconsideration conditions. Do not:
 
 - silently overwrite established constraints when evidence conflicts;
-- treat working observations as live external facts;
+- treat tactical observations as live external facts;
 - infer success or absence of external effects from restored memory. After an interruption, inspect the relevant effects before repeating.
 
 These are model stewardship duties, not deterministic semantic gates.
@@ -689,27 +696,35 @@ The package exposes read-only host contracts that:
 
 ### Model tools
 
-**`patch_state` grammar.** It accepts one or more fixed `global`, `cwd` and `session` semantic patches.
+**`patch_state` grammar.** Captured WANTED participation, not the number of supplied targets or currently available owners, selects the model interface. One owner takes direct semantic planes without an owner wrapper; two/three owners take explicit participating `global`, `cwd` or `session` patches. See the [accepted interface boundary](single-scope-interface-contract.md#deterministic-m3-checkpoint); schema/selection DATA never grants source/private/publication authority.
 
-- Supplied scopes contain object-valued `artifacts`, `contract`, `working` and `intents`, plus object-valued `lazy` whose nested values are ordinary JSON.
+- Each supplied canonical owner patch contains object-valued `artifacts`, `strategy`, `tactics`, `intents` and `lazy`; in one-owner model arguments these planes are top-level. Nested values are ordinary JSON.
 - Recursive object merge updates fields, arrays/primitives replace, and nested object-key `null` deletes, including inside newly created objects. Deletion-only patches through absent ancestors create no empty parents. Accepted supplied scopes recursively omit empty object fields and empty planes: deleting the last child removes its empty ancestors, and explicit `{}` is not a retained value. Nonempty omitted fields persist; an object patch that turns a scalar/array into an empty object removes that field. Cleanup is scope-local and can reveal inherited values; it stops at the scope root and never removes array slots.
 - Against an existing array, a nonempty object containing only canonical `"[N]"` keys recursively patches those existing elements (zero-based). Out-of-bounds indices and indexed `null` deletions are rejected atomically; adding/removing elements requires replacing the whole array. Against objects, those keys remain literal object keys.
-- Missing authored object-key deletions succeed with nonfatal hints in the acknowledgement, for both unchanged and mixed patches. Each hint gives the owner-scoped target and first unavailable component as escaped JSON Pointers; a non-object ancestor is also unavailable. These hints are presentation-only: no state fields, revisions, history records, automatic path correction or cascade warnings.
-- Rejected: materialized null within documented semantic planes, empty supplied scopes, unknown top-level fields, model-authored `response`, and finalization or `{scope, patch}` / `unchanged` grammars. The semantic null rule does not apply to runtime envelopes such as an origin's null parent.
+- Missing authored object-key deletions succeed with nonfatal hints in the acknowledgement, for both unchanged and mixed patches. Each hint gives the target and first unavailable component as escaped JSON Pointers: relative to the sole owner in text, owner-qualified for multi; result details retain canonical owner-qualified pointers; a non-object ancestor is also unavailable. These hints are presentation-only: no state fields, revisions, history records, automatic path correction or cascade warnings.
+- Rejected: materialized null within documented semantic planes, empty patches/supplied scopes, wrong flat/scoped root family, unknown top-level fields, model-authored `response`, and finalization or `{scope, patch}` / `unchanged` grammars. The semantic null rule does not apply to runtime envelopes such as an origin's null parent.
 - Correct repeated results succeed as `State already current.` without another semantic revision or history record; avoid gratuitous acknowledgment patches.
 - Global/CWD overlap follows successful acceptance order, and unmentioned current fields survive. Session ownership is not a shared-memory merge.
 
+For exactly one wanted owner (for example Session):
+
+```json
+{"intents":{"next":"Verify the corrected behavior"}}
+```
+
+For multiple wanted owners including Session (for example Global+Session), an explicit selected target remains required even when only one is changed:
+
 ```json
 {"session":{"intents":{"next":"Verify the corrected behavior"}}}
 ```
 
-**Intents and ownership.** `intents` is the hot plane for active commitments, not requirements, observations, alternatives or completed plans. Removing an intent does not remove its consequences; it removes only the state it owns. Intent ownership is the one reference with runtime meaning:
+**Intents and ownership.** `intents` is the hot plane for active commitments, not requirements, observations, alternatives or completed plans. Removing an intent does not remove its consequences; it removes only the state it owns. Intent ownership is the one reference with runtime meaning. Eligible flat current refs are anchored to their captured canonical sole owner before this algorithm; unscoped-target exclusions below describe canonical inputs, not a reason to add a model owner wrapper:
 
-- When a patch deletes an intent key, structured `{"$ref"}` targets found anywhere inside the deleted value, naming an existing object key under `working` or `lazy` of the intent's own scope, are deleted after the authored operations, in the same atomic cohort and revision.
-- A target survives while a remaining intent in that scope references it, an ancestor or a descendant, so one patch can supersede an intent by deleting it and re-referencing the same targets.
-- Writes to an owned target in the deleting patch are discarded with it. Editing an intent to drop a reference leaves its target unowned.
-- Cross-scope, plane-root, array-element, unscoped, `effective`, historical and non-`working`/`lazy` targets, missing targets and textual `$path` mentions are skipped silently. Ownership never rejects, warns about or delays a patch.
-- The `ownership` domain computes the cascade by reading only that scope's `intents` plane. The accepted record stores the cascade as explicit deletions, so replay never re-derives it.
+- When a patch deletes an intent key, structured `{"$ref"}` targets found anywhere inside the deleted value, naming an existing object key under `strategy`, `tactics` or `lazy` of the intent's own scope, are cleared after intents and before remaining authored planes, in the same atomic cohort and revision.
+- A target survives while a final remaining/new intent in that scope references it, an ancestor or a descendant, so one patch can supersede an intent by deleting it and re-referencing the same targets.
+- Writes after cleanup recreate a cleared target as fresh knowledge without old fields. Editing an intent to drop a reference leaves its target unowned; unowned entries remain legal.
+- Cross-scope, plane-root, array-element, unscoped, `effective`, historical and non-`strategy`/`tactics`/`lazy` targets, missing targets and textual `$path` mentions are skipped silently. Ownership never rejects, warns about or delays a patch.
+- The `ownership` domain computes the cascade by reading only that scope's `intents` plane. The accepted record stores explicit net patches, so replay never reruns cascade; existing strategy refs apply to future accepted intent deletions without rewriting history.
 - Deleted targets are not archived beyond ordinary retained history.
 
 Full details: [intent ownership](lazy-state.md#intent-ownership).
@@ -729,24 +744,42 @@ Full details: [intent ownership](lazy-state.md#intent-ownership).
 
 **History is task-driven.** Missing paths or hints alone do not require historical search. The agent may independently choose targeted historical reading when a previous value is useful to the current task; no separate user permission is required. Historical values are evidence, not automatically current state or a reason to restore deleted memory. Runtime never scans history for reference owners, triggers repair inference or hydrates lazy bodies. Effective absence does not establish ownership, and unavailable history, external inaccessibility or a transient read failure does not prove a broken reference.
 
-**`read_state` addressing.** It accepts one unified path.
+**`read_state` addressing.** It accepts exactly one of scalar `path` or ordered semantic `paths`, with `value`, `keys` or `patch` projection; batches stay all-or-error. One wanted owner's ordinary flat paths bind that owner; multi-owner flat paths use the effective overlay, even when the available view has only one owner.
 
+- Explicit owner roots/examples below require that owner to participate and its requested current/historical authority to be available. Selection or an address alone does not acquire missing private memory.
 - `effective == effective[0]` is the current effective materialization; `global == global[0]` (and the CWD/session equivalents) selects that scope at the same composed causal boundary.
-- `global.patches == global.patches[0]` reads the latest accepted retained global patch; higher patch indices walk only that scope's retained accepted patches.
+- For selected/available Global, `global.patches == global.patches[0]` reads its latest retained accepted patch; higher patch indices walk only that owner's retained accepted patches. Exactly one wanted owner also admits a single-locator `patches[N]` alias. Scope-patch reads are value-only, not mixed semantic/patch-history batches.
+- `effective[N]` selects a retained causal boundary; ordinary nested array `[N]` still indexes an array, not history.
 - Indices are bounded by the configured `historyLimit`; unavailable pre-origin or pre-tail history is an error.
 - Resolver aliases are not literal JSON containers.
 - Object keys in paths must match `[A-Za-z_$][A-Za-z0-9_$-]*`. Both tool descriptions and the Skills ask the model to name keys in ASCII (values may use any language), and a non-ASCII key in a read path fails with that grammar in the error.
 - Reads stay cached and create no Git query, publication, checkpoint append or semantic step.
 
+When CWD participates and its older boundary is retained:
+
 ```json
 {"path":"cwd[1].intents"}
 ```
 
+When Global participates and its owner patch is retained:
+
 ```json
 {"path":"global.patches[0]"}
 ```
 
-Unscoped semantic paths such as `intents.next` alias the current effective overlay. `value`, `keys` and `patch` projections plus ordered `paths` batches stay all-or-error.
+For exactly one wanted owner with retained patch history:
+
+```json
+{"path":"patches[0]"}
+```
+
+Ordered semantic reads use the same wanted-owner/effective rule:
+
+```json
+{"paths":["strategy","tactics"]}
+```
+
+Current same-owner structured refs can render flat for one owner while storage retains canonical owners. Historical/cross-owner/effective/resource/text refs keep their identities; no read or projection ID is a publication capability.
 
 **Availability and responsibilities:**
 
@@ -784,7 +817,7 @@ The pure `readTemporalState(view, offset, scope?)` accessor is exported separate
 
 See the [fork contract](fork-contract.md) and [operating limits](usage.md#fork-support-and-limits).
 
-**Configuration.** Agent configuration is read once per extension load; session runtime configuration stays branch-selected. See [configuration](usage.md#configuration) for settings and path precedence. Memory ownership while enabled and global availability are invariants, not configuration switches.
+**Configuration.** Agent configuration is read once per extension load; session runtime configuration stays branch-selected. See [configuration](usage.md#configuration) for settings and path precedence. Ownership meanings and relative precedence are stable, but participation is a captured validated nonempty subset of Global/CWD/Session; omission defaults to all three, Global is not mandatory. Global defaults and explicit native scope choices remain separate from mode and current/private/source admission; see the [functional scope boundary](scope-selection-contract.md#m2-functional-acceptance-boundary).
 
 ## Observability
 
@@ -811,18 +844,18 @@ Status is a projection of the selected runtime and semantic view, not a second s
 **Telegram menu layout.** The optional Telegram leaf adapter shows, in order:
 
 1. the current mode as a monospace value in the submenu heading;
-2. matching Mode and Inspect memory headings (a long-dash-separated description ending in a colon), each separated by a blank line from its settings-style monospaced-key list;
-3. one radio row `Off | Passive | Active`, where selected Off uses 🟡, Passive 🟣 or Active 🟢, and inactive choices use ⚫️;
-4. four direct scope-inspection buttons. Inspection stays available in all three modes.
+2. matching Mode and Inspect participating memory headings (a long-dash-separated description ending in a colon), with a captured Participating scopes line and selection-aware settings-style descriptions;
+3. one radio row `Off | Passive | Active`, where selected Off uses 🟣, Passive 🟡 or Active 🟢, and inactive choices use ⚫️;
+4. only captured participating owner-inspection buttons, plus Effective for two or three owners. A sole owner is already effective. Inspection stays explicit and available in all three modes; unavailable memory is not invented.
 
 ### Inspection reads
 
 - Inspection may refresh live Global/CWD streams in memory so foreign accepted revisions become visible, but never publishes or increments a revision.
 - Memory-enabled inspection keeps its accepted-private/shared-refresh and failed-Passive cache rules.
-- Off inspection uses a fresh disposable `TemporalRuntime`. Global/CWD use coherent shared reads; Session/Effective use `refreshCurrentMemory` and reject absent, incomplete or malformed same-session private evidence, rather than manufacturing an empty layer/revision or borrowing foreign private data.
+- Off inspection uses a fresh disposable `TemporalRuntime`. A single selected Global/CWD or selected shared-only Effective uses `refreshSelectedShared`; inspections requiring selected Session use `refreshSelectedCurrent` under existing private proof. Effective never widens to excluded owners. Missing/invalid private evidence cannot become an empty layer/revision or foreign private data; legacy lifecycle admission retains its documented full-proof dependency.
 - No reader installs the extension runtime/cache, changes native policy or canonical bytes, clears a carried write fence, acquires an unaccepted fork parent or replaces the selected historical target.
 - Branch steps never select a past memory revision; inspection and acquisition always use current stored memory.
-- The awaited `StateFlowTelegramInspectionPort` returns a `StateFlowTelegramInspection` containing state and matching revisions, plus an optional revocation signal. A result checks its revocation lifetime and physical owner immediately before presentation.
+- `StateFlowTelegramSnapshot.scopes` supplies detached wanted selection DATA to rendering; omission preserves all-three legacy embedding behavior, while malformed explicit values reject. Buttons/help do not infer scope choice from available revisions or confer memory authority. The awaited `StateFlowTelegramInspectionPort` returns coherent state/revisions and an optional revocation signal. Target eligibility is checked before reader calls, selection is rechecked after acknowledgement/observation, and native inspection also revalidates its lifetime and physical owner before presentation.
 - Stop, selection changes and shutdown cancel obsolete reads without altering newer memory or clearing write fences.
 
 Local diagnostics stay outside semantic state and cannot change accepted state. Operator-facing fields and privacy boundaries are in [usage](usage.md#status-and-controls).

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

@@ -12,6 +12,14 @@ State Flow requires matching `pi-coding-agent`, `pi-agent-core`, `pi-ai` and `pi
 
 Detailed behavioral witnesses live in [temporal acceptance](temporal-acceptance.md); benchmark methodology and source-bound results live in [performance](performance.md).
 
+## Canonical scope format admission
+
+Core-only canonical scope metadata remains **version 3**, with `strategy` and `tactics` fields. The candidate **version 4** codec additionally retains external object-plane descriptors and opaque values independently of loaded definitions; absent internal `modules` metadata keeps existing v3 output. Declared legacy versions **1/2** translate before known-field filtering. Target-format `contract`/`working` roots reject; nested domain keys remain ordinary JSON. Unsupported versions fail closed. These scope versions are distinct from the unchanged Session lifecycle format and public module API version1. Public seventh-plane tool/context/producer activation remains separate open work; see the [public module boundary](public-module-contract.md).
+
+Legacy inspection is observational. Owned semantic acceptance may convert only admitted owner scopes, after complete target-cohort/identity validation, exact source CAS and a verified private backup outside canonical authority. Missing legacy revisions credit retained records only; conversion itself adds no learning transition. Opaque capture/rollback preserves arbitrary original bytes while semantic interpretation requires valid UTF-8. See [migration proof and support limits](semantic-compatibility-decision.md#guarded-publication-and-support-boundary) and [backup/recovery guidance](usage.md#moving-a-store-and-supported-formats).
+
+This is a locally implemented, unreleased breaking semantic API/storage change. Existing exported names remain where applicable but their fields, callbacks, schemas and paths use Strategy/Tactics; no permanent old-field aliases are provided. Upgrade/quiesce old consumers before deployment: already-deployed unsafe low-level callers cannot be universally fenced. No active store was operated on during development.
+
 ## Public host seams
 
 State Flow relies on:
@@ -53,7 +61,7 @@ On the tested SDK, `before_agent_start` precedes the low-level agent's `prompt`;
 2. The active `context` hook supplies the operation signal and awaits preparation/maintenance before provider inference.
 3. If preparation fails, State Flow calls public `ctx.abort()`. Pi catches context-hook errors and may otherwise continue inference, so a thrown error alone is not a fence.
 
-Native tests prove no provider call before coherent acceptance, cancellation while an independent writer remains held, rollback without draft installation and preservation of uncompiled native input. Unreadable current Active memory also aborts live inference before the provider; native witnesses cover contradictory private lineage and malformed runtime files without changing canonical bytes, while old-step tree selection/reload is not a failure. Failed attachment retains Active policy and exposes `active (blocked)` in terminal/Telegram; the fence is derived from selected mode plus unavailable-memory validation. Active controls retry current-memory acceptance rather than claiming it is already active. Explicit Passive accepts validated current memory and releases both fences; explicit Off releases only the inference fence.
+Native tests prove no provider call before coherent acceptance, cancellation while an independent writer remains held, rollback without draft installation and preservation of uncompiled native input. Unreadable current Active memory also aborts live inference before the provider; native witnesses cover contradictory private lineage and malformed runtime files without changing canonical bytes, while old-step tree selection/reload is not a failure. Pending or failed Active attachment retains Active policy and exposes `active (blocked)` in terminal/Telegram; the fence is derived from selected mode plus unavailable-memory validation. Active controls retry current-memory acceptance rather than claiming it is already active. Explicit Passive accepts validated current memory and releases both fences; explicit Off releases only the inference fence.
 
 **Signals are not universal.** Idle commands and session events can lack them. Do not infer native Abort cancellation from an extension-owned shutdown signal or generalize active-run tests to idle waits.
 

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

@@ -73,6 +73,12 @@ Memory-enabled native fork adoption and Start's fork retry use this transaction
 - A child inherits neither its parent's write fence nor its passive projection. Parent current memory must be valid, and copying must pass CAS; ordinary activation policy is not overridden.
 - Nested forks copy each direct parent's current memory. Ancestry is not recursively reconstructed.
 
+## Internal selected-scope copy boundary
+
+The [selected-scope contract](scope-selection-contract.md#selected-parent-current-private-copy) now implements shared-only child deferral and eager/deferred private copy over selected streams. The native adapter must validate persisted direct-parent identity before exclusion and recheck current in-memory child/parent/policy ownership after waiting. The storage owner verifies only parent-current private files/lineage/provenance plus selected live shared inputs, never recursive ancestry or unrelated disabled owners. Parent bytes stay read-only; occupied, malformed, lost-acquired or already-acquired child evidence cannot become empty memory or authorize recopy.
+
+These internal APIs return file receipts/sticky authority facts and install the [accepted selected cache](scope-selection-contract.md#accepted-selected-runtime-cache-and-reads) after durable acceptance. They do not yet replace the native all-owner `withForkTransaction` route described above, expose scope settings, or implement native pending-marker/selection-epoch attachment. Isolated selected-copy fixtures are local backend proof, not completed native selected-fork delivery.
+
 ## Support boundary
 
 Supported copying requires a persisted regular parent session file, matching header UUID/CWD, current canonical scope/runtime files, and an available retained boundary. Arbitrary session search, UUID aliases, cross-CWD imports, in-memory-only parent locators, conversion of unsupported storage formats, unlimited history, and Git recovery are unsupported.

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

@@ -42,8 +42,8 @@ Runtime views select present documented semantic planes in intent-first order, o
 ```text
 global | CWD | session
 ├── intents
-├── contract
-├── working
+├── strategy
+├── tactics
 ├── artifacts
 ├── response (session-owned; empty structural slot in Global/CWD)
 └── lazy
@@ -51,7 +51,7 @@ global | CWD | session
 
 Hot planes:
 
-- `intents`, `contract`, `working` and `artifacts` stay hot in every scope.
+- `intents`, `strategy`, `tactics` and `artifacts` stay hot in every scope.
 - Session-owned `response` is also hot. New Global and CWD states use an empty structural slot, and stored scopes may omit it. Effective uses the highest-priority present response, and each newly accepted answer is written only in Session.
 - `intents` may keep compact active direction while referring to large supporting detail in `lazy`.
 
@@ -71,7 +71,9 @@ A reference is semantic content, not a runtime type. There are two forms:
 
 File paths, document sections, URIs, artifact locators, Skill identities and agent identities keep their native syntax.
 
-**What State Flow does with references.** It preserves all forms exactly as ordinary JSON. It does not scan prose, index targets, validate existence, rewrite relative locators, or infer authority, dependency, hydration, execution or completion. The single exception is [intent ownership](#intent-ownership).
+**What State Flow does with references.** References are ordinary JSON, with a documented model/canonical translation: for exactly one WANTED owner, eligible flat current semantic `$ref` values anchor to that owner before ownership/staging. For example, `{"$ref":"lazy.plan"}` becomes `{"$ref":"cwd.lazy.plan"}` when only CWD is selected; model reads project eligible same-owner current refs back relatively. Historical, `effective`, explicit cross-owner and resource refs, as well as ordinary text, keep their identity. See the [single-scope interface](single-scope-interface-contract.md#detached-canonical-boundary).
+
+This translation does not scan prose, index targets, validate existence, or infer authority, hydration, execution or completion. The separate [intent ownership](#intent-ownership) rule gives eligible canonical refs their bounded cleanup meaning.
 
 When a reference matters, the agent resolves it explicitly: with `read_state` for semantic paths, or with the appropriate external read/tool for other resources. A locator helps retrieval but does not replace content required for the current decision.
 
@@ -116,32 +118,34 @@ State Flow does not inject IDs, provenance, revisions, range descriptors, or tru
 
 Intents can own the memory they create:
 
-- A structured `{"$ref"}` anywhere inside an `intents` entry means "delete with me" for an existing object key under `working` or `lazy` of the same scope, such as `{"$ref":"cwd.lazy.plan"}` inside `cwd.intents.release`.
+- A structured `{"$ref"}` anywhere inside an `intents` entry means "delete with me" for an existing object key under `strategy`, `tactics` or `lazy` of the same scope, such as `{"$ref":"cwd.lazy.plan"}` inside `cwd.intents.release`.
 - A textual `$cwd.lazy.plan` mention means "I use this" and never owns.
 
-**What happens when a patch deletes an intent key.** State Flow first applies the authored operations, then deletes each owned target that no remaining intent of that scope references, directly, through an ancestor or through a descendant. Everything happens in one atomic cohort, with one revision per changed scope.
+Ownership evaluates canonical references after model anchoring. A sole-CWD model intent containing `{"$ref":"lazy.plan"}` can therefore own `cwd.lazy.plan`; its flat presentation is not a non-owning unscoped canonical reference.
+
+**What happens when a patch deletes an intent key.** Independent of JSON insertion order, State Flow applies intents only, clears eligible targets of deleted intent keys unless final remaining/new same-scope intents reference them directly or through ancestors/descendants, then applies remaining authored planes before existing compilation/normalization and atomic publication. Everything happens in one atomic cohort, with one revision per changed scope.
 
 - **Supersession works in one patch:** delete the old intent and reference the same targets from its replacement.
-- **Writes in the deleting patch do not save a target.** Updates, nested additions and keys created by that same patch are deleted silently along with it, and the accepted record stores only the net deletion. Save survivors to an unowned path instead.
+- **Rewrite survivors in the deleting patch.** Remaining authored planes run after cleanup. An explicit rewrite at the same or a new path creates fresh knowledge without old fields from a cleared target. Strategy is owned too, not an automatic safe haven.
 - **Editing is not deleting.** Editing an intent to drop a reference leaves the target as ordinary unowned state. Unowned entries remain legal.
 
-**What is never deleted.** The cascade reads only the `intents` plane of the intent's own scope. These targets are skipped silently, and no patch is rejected, warned about or delayed:
+**What ownership does not target.** After model anchoring, the cascade reads only the `intents` plane of the intent's own scope. These canonical targets are skipped silently, and no patch is rejected, warned about or delayed:
 
 - other scopes;
 - plane roots and array elements;
-- `contract`/`artifacts`/`response`/`intents` targets;
-- unscoped or `effective` paths;
+- `artifacts`/`response`/`intents` targets;
+- paths still unscoped in canonical data, or `effective` paths;
 - missing targets;
 - keys outside the `read_state` key grammar `[A-Za-z_$][A-Za-z0-9_$-]*`, for example keys with spaces, dots or non-Latin letters.
 
-**Receipt.** `state_updates.cascaded` lists all owner-scoped targets removed by intent deletion, for example `["session.lazy.plans.x", "session.working.draft"]`. Paths only, never lazy bodies or deleted values. The list is deterministic (Global, CWD, Session, then each scope's cascade order), absent when no target cascaded, and never omitted as a predictable write. Nested lazy deletions are reported even when the top-level `lazy_navigation` catalog is unchanged.
+**Receipt.** `state_updates.cascaded` lists all owner-scoped targets cleared in the intermediate ownership phase, even if later authored writes recreate them, for example `["session.lazy.plans.x", "session.tactics.draft"]`. Paths only, never lazy bodies or deleted values. The list is deterministic (Global, CWD, Session, then each scope's cascade order), absent when no target cascaded, and never omitted as a predictable write. Nested lazy deletions are reported even when the top-level `lazy_navigation` catalog is unchanged.
 
 **Edge cases:**
 
-- Deletion is scope-local, so an effective read may afterwards show a same-path value inherited from a broader scope. The receipt's `effective` entry then reports that value rather than `deleted: true`; `cascaded` still identifies the deleted owner path.
+- Deletion is scope-local, so an effective read may afterwards show a same-path value inherited from a broader scope. The receipt's `effective` entry then reports that value rather than `deleted: true`; `cascaded` still identifies the cleared owner path. A later authored rewrite can also recreate it; final `effective` values describe the actual accepted state.
 - Concurrent shared writers keep last-accepted-wins behaviour: a later write into an intent another session already deleted simply recreates a partial intent.
 
-**History and limits.** The accepted patch record stores cascaded keys as explicit deletions, so replay never re-derives them, and nothing is archived beyond ordinary retained history. Ownership adds no validation, unresolved-reference warning, cross-scope cascade, age-based cleanup, size budget, growth notice, archive of deleted entries or automatic hydration.
+**History and limits.** The accepted patch record stores the actual net patch, including explicit deletions or fresh replacements, so replay never reruns cascade. Old accepted history is unchanged; existing current strategy references acquire ownership only for future accepted intent deletions, and nothing is archived beyond ordinary retained history. Ownership adds no validation, unresolved-reference warning, cross-scope cascade, age-based cleanup, size budget, growth notice, archive of deleted entries or automatic hydration.
 
 ### Effective lazy overlay
 
@@ -169,7 +173,7 @@ Active obligations, current constraints, unresolved next actions, and facts requ
   "paths": [
     "effective.lazy.rules",
     "cwd.lazy.memory[0..10]",
-    "session.working.nextAction"
+    "session.tactics.nextAction"
   ],
   "projection": "value"
 }
@@ -199,7 +203,7 @@ A single-path request returns one payload. A multi-path request returns position
 One missing value path with exact current durable references returns this sentinel instead; it is diagnostic metadata, not semantic state:
 
 ```json
-{ "value": null, "hint": [{ "type": "dangling-reference", "message": "The requested value is unavailable in the selected state. These current values reference that path, not a verified new location. Use this evidence if relevant to the task.", "paths": ["cwd.working.note"] }] }
+{ "value": null, "hint": [{ "type": "dangling-reference", "message": "The requested value is unavailable in the selected state. These current values reference that path, not a verified new location. Use this evidence if relevant to the task.", "paths": ["cwd.tactics.note"] }] }
 ```
 
 What each projection contains:
@@ -214,7 +218,7 @@ Errors use the normal tool-error channel, never successful JSON with an `error`
 
 ### Path and range model
 
-Unscoped semantic paths alias current effective state. Explicit roots and selectors address:
+In the canonical read grammar, unscoped semantic paths alias current effective state. At the sole-WANTED-owner model boundary, eligible flat current paths instead bind to that selected owner before canonical reading; this is distinct from structured-reference ownership. Explicit roots and selectors address:
 
 - `effective` for the current composed overlay or an indexed historical effective root.
 - `global`, `cwd`, and `session` for explicit current or historical scopes.
@@ -227,7 +231,7 @@ Examples:
 
 ```text
 effective.lazy
-effective.working.nextAction
+effective.tactics.nextAction
 cwd.lazy.memory
 cwd.lazy.memory[4]
 cwd.lazy.memory[10:20]
@@ -447,8 +451,8 @@ A lazy read enriches only the current tool-result trajectory. It does not:
 
 When a retrieved fact becomes necessary for future correctness, the agent promotes a distilled consequence through an ordinary hot `patch_state` mutation:
 
-- Durable requirement or decision → `contract`.
-- Current fact, uncertainty, or continuation → `working`.
+- Durable requirement or decision → `strategy`.
+- Current fact, uncertainty, or continuation → `tactics`.
 - Source-addressed reusable compilation → `artifacts`.
 - Historical support with no current consequence → remain under `lazy`.
 

package/node_modules/@llblab/pi-state-flow/docs/protocol-composition-decision.md

@@ -0,0 +1,66 @@
+# Protocol composition decision
+
+## Scope and accepted decision
+
+The subsequent explicit request for a general internal module API is implemented separately in the [internal semantic-module contract](semantic-module-contract.md). It supersedes this checkpoint's no-extraction disposition only for that bounded internal contract. The historical review/evidence below is not retroactively upgraded, and protocol trust/order and public-loader deferral remain applicable.
+
+M4 is an earned-composition investigation, not a requirement to ship descriptors. **Retain the existing plain render functions and shared trusted snippets; do not extract another semantic module layer now.** No source, public API, emitted protocol, storage format, schema, runtime hook or lifecycle change is proposed. The complete actual terminal follow-up review is **APPROVE — R1 verified; retain implementation/defer further extraction**. [BACKLOG](../BACKLOG.md#12-ordered-implementation-backlog) alone owns subsequent work; M5 and gated quality evidence are not approved by this decision.
+
+The question is whether a further Core/Intents/Strategy/Tactics decomposition solves observed duplication, conflicting ownership or maintenance friction. It is not whether all code can be represented as a descriptor array. The accepted [M3 functional checkpoint](single-scope-interface-contract.md#deterministic-m3-checkpoint) already supplies actual scope-free required arguments and typed outputs; M4 must not reopen its admission/source/private contracts or infer model quality from a different source layout.
+
+## Actual composition and rule ownership
+
+- **Policy selection:** `lib/extension.ts` contributes the owned section at `before_agent_start`, then `context_with_system` checks physical/original context eligibility and accepted preparation and refreshes Active/bootstrap, available Passive, or no section for Off. These are two lifecycle delivery calls to the same producer, not two separately authored protocols. Validated captured WANTED scopes and bootstrap policy are the renderer inputs, not semantic memory values.
+- **Trusted text:** `lib/protocol.ts` owns `stateFlowProtocol(bootstrap, scopes)` and `passiveMemoryProtocol(scopes)`. Scope selection is captured against the closed owner set before interpolation. It is DATA, not an acquisition or publication capability. No arbitrary state content, file body or user-supplied module callback is an input to these renderers.
+- **Existing shared snippets:** `TASK_DRIVEN_HISTORY`, `PATCH_RESULT_PROTOCOL` and `FLAT_INTERFACE_PROTOCOL` each already serve Active and Passive consumers. `RESPONSE_PATCH_GUIDELINE` is reused by Passive and actual tool prompt guidelines; both native read/patch declarations also use `SCOPE_PARTICIPATION_GUIDELINE`. `scopeGuidance` shares selected-owner meaning/non-broadening rules. These are deliberate existing extractions, not a newly proposed framework.
+- **Semantic plane summaries:** Intents/Strategy/Tactics have one summary site in Active's STATE block. Bootstrap prepends a conditional notice to the same Active renderer, not a copied second three-plane protocol. Passive deliberately does not inherit Active iteration/reconciliation pressure. The larger MEMORY/REFS paragraphs express cross-plane preservation and ownership obligations, not three independently enableable features.
+- **Section membrane:** `lib/context.ts:projectSystemProtocol` replaces/removes only the owned `state_flow` section, preserves foreign sections/system frames and reuses an unchanged projection. It does not invent system authority when no native system frame exists. It accepts the trusted caller's text; it does not generate instructions from `ContextView.state`.
+- **Fallible state and output:** Context heads/notices/continuation state are user-level DATA owned by `context`, with policy/data translation by `model-interface`; they do not become instruction fragments or get publication authority from a projection ID.
+- **Enforced semantics:** Same-scope intent cascade, recursive patching, artifact/Skill placement and source provenance stay in `ownership`/`transition`/source owners. Causal replay/private/current publication stay in temporal/runtime/storage owners. A prompt fragment is not an `afterPatch` hook or a second engine.
+- **Diagnostics:** Existing diagnostic formatting in `protocol` and persistence in `logging` have named consumers/contracts. Splitting files merely to shorten the protocol file is not the M4 outcome. Error owner names preserve provenance and must not be flattened into local permission.
+
+Overlap between STATE summaries, detailed MEMORY/REFS guidance, tool guidelines and packaged Skill examples is not automatically producer duplication. They teach different scopes/authorities/detail levels. This inspection does not claim all natural language is perfect or all models interpret it consistently. It finds no executable mode/scope/trust conflict requiring a new composition mechanism.
+
+## Alternatives evaluated
+
+### A — Retain functions and current snippets (selected)
+
+Keeps a local, fixed-order trusted template with mode/scope/bootstrap distinctions visible together. Shared obligations with multiple consumers already have narrow names. Before/after retained production graph, emitted bytes, public surface and lifecycle dependencies are identical. The cost is continued local editing of the Active template and careful preservation of conditional wording. That is currently the simpler honest cost, not a demonstrated defect.
+
+### B — Additional private plain helpers or plane strings
+
+A small helper is appropriate when a second real trusted producer must share a rule. Today moving the three summary lines into an extra function/constant serves one Active site; bootstrap already reuses that site. Generalizing response/scope wording risks obscuring real differences: selected legacy response versus new Session-only answers, one-owner transfer refusal versus genuine multi-owner moves, and Passive access versus Active reconciliation. No second consumer or conflicting edit was found to repay another name/parameter boundary.
+
+The strongest real local duplication is the three owner meanings: `scopeGuidance`'s map and the compact inline all-three Active sentence both author them. They currently agree. Subset wording adds exclusion/participation obligations and ordering, while the default body is deliberately compact and hash-guarded. One private meaning helper could preserve exact bytes; no current bug or conflicting update requires it. A bug is not a prerequisite for preventive deduplication: a future authorized owner-meaning change may reasonably use that helper before drift occurs. Current retention weighs the small local synchronization cost against another boundary; it does not forbid that choice. This is real consistent duplication, not a claim of zero repeated text.
+
+This is not a prohibition on future small helpers. It rejects extraction solely for symmetry or file length. Exact output preservation would not itself reduce prompt bytes; wording changes are a separate semantic claim.
+
+### C — Static internal descriptors and fragment assembly
+
+A private ordered descriptor array could hold text or policy-only renderers without a public registry. In this code it adds fragment keys, assembly/dispatch and output-order obligations while carrying the same text. Three plane descriptions alone do not require per-plane enablement, versioning or execution. Moving MEMORY/REFS/source/lifecycle rules into plane callbacks would cross existing ownership boundaries rather than simplify them.
+
+No runnable descriptor prototype was created: no unresolved dependency or behavior question requires one after inspecting the current single producer and existing shared fragments. Equal text would mean equal output by construction, not an independently measured prototype result or cognitive improvement. A loader, declarative public manifest, external registration, optional-module UI, executable invariant or hidden reaction is outside this M4 choice; M5 separately owns any demonstrated demand.
+
+## M4 acceptance disposition
+
+- **M4.1:** The source-level rule/producer map and three alternatives support no further extraction now. Existing private shared fragments remain, rather than pretending M3 left an entirely uncomposed monolith.
+- **M4.2:** There is no candidate graph to integrate. Preserve the existing trusted mode/section composition and its accepted protocol/context/native witnesses unchanged; no before/after source rewrite, parser, storage or lifecycle dependency is introduced.
+- **M4.3:** No maintainability or cognitive benefit of an additional descriptor layer was demonstrated. Retain the simpler implementation and defer the refactor, not declare a positive/negative live-model result. The permitted neutral decision is not completion of an unrun cognitive experiment. Any later model-quality/retention/retry/cost assertion still belongs to explicitly gated M0.4b evidence.
+
+The M3 metric baseline is an honest counterweight: actual two flat declarations were2591 UTF-8 bytes versus multi2466, and flat owned protocol sections5234–5281 versus multi4425–4556. Those choices differ in participation; they are not identical-policy causal A/B. Source rearrangement preserving the text would not compress those strings. These observations do not prove a descriptor layer universally useless or make prompt-size optimization part of this decision.
+
+## Verification and limits
+
+There is no new behavior to test, so do not invent a descriptor test harness or rerun unchanged linked cases for a checklist. Reuse the accepted closed M3 snapshot and actual reported protocol19/context/native/Source1611/DIST7 evidence at their original proof levels; prior compiled299/compatibility36 are reused evidence, not new executions. Same raw all-three Active/bootstrap body SHA, same static renderers/section membrane, same imported lower authorities and source/runtime graph mean the proposed retained-state delta is zero production behavior. A finite certificate is not every vendor/provider/environment file or exhaustive interleaving proof.
+
+The bounded independent source-fact author read the actual producers/trust path, did not inspect this in-progress decision or execute tests, and found no demonstrated extraction requirement. Its strongest challenge—the consistent two-site owner-meaning wording—is retained above rather than hidden. This is inspection evidence, not integrated approval.
+
+Current verification: accepted64 closed135 passed before changes; afterward133/135 remain exact, with only CHANGELOG/docs-index deltas inside that certificate. Architecture/new decision are explicit out-of-certificate doc edits. All bound production/dist/tests/package/helper/probe/metric inputs remain unchanged. Context0errors/21warnings, DAG0/25, documentation1/1 and diff pass. New `npm pack --dry-run --ignore-scripts --json` inventories130 files, old129 names retained plus only this decision; no prepack build, publish or install. Package membership, not a promised final future-doc hash/size. An initial comparison mistakenly consumed rg's clipped25/129 preview plus metadata; reading its exact returned full tee fixed parsing, not package/source content.
+
+Relevant existing guards: `tests/protocol.test.ts` (including selected renderer properties), `tests/extension.test.ts` (native protocol composition), `tests/context.test.ts`, native structured-prompt/context-owner/mode-refresh and linked checkpoint cases. Actual default raw SHA/prefix and within-phase byte witnesses are in the M3 contract. Source getters/lower pure fixtures, SDK scripted sessions and local HTTP serialization retain separate scopes; none establishes model comprehension, external effects, universal nonaccess, token cost or cache behavior.
+
+Validate changed Markdown/index links and package inventory without invoking an unnecessary rebuild; no source/package contract changed. Do not advertise an unchanged-output alternative as an implemented optimization. Initial independent review was **REQUESTCHANGES**: it supported no-extraction but found one real medium documentation defect (R1). The architecture Model tools/read/config summaries still contradicted M3 despite the composition-bullet repair. After actual ROOT terminal/report consumption, nine targeted regions were corrected: sole-flat/multi-explicit paired examples, relative textual deletion pointers/canonical details, current-ref anchoring before cascade, scalar-or-batch reads and narrow sole patch alias, selected/available authority, and optional Global. Initial report/counterexample remain unchanged, not waived or relabeled. Follow-up independently inspected all nine against actual code, admitted all six actual Markdown examples through existing DIST DATA helpers (not SDK/existence/authority proof), passed documentation1/1 and diff, audited130-file membership, and checked current150/150 before/after. Its old144 check is141/144 with exactly BACKLOG/architecture/decision deltas, not a reissued initial144 pass. Context0/21 and DAG0/25 were inspected coordinator evidence in follow-up, independently executed in the initial review. No source/typecheck/SDK/protocol/full/build/pack execution is attributed to follow-up. Actual complete follow-up report was consumed after ROOT terminal before closure; no further remediation. Link checks alone never established prose accuracy. M4 is closed as a bounded retain/defer decision, not an implemented descriptor refactor or completed cognitive experiment. Preventive owner-meaning dedup remains credible and nonblocking, not forbidden until a bug. Closure changes decision/index/BACKLOG prose only; production/tests/dist remain unchanged. M5, M0.4b quality and retirement gates remain separate, not automatically completed.
+
+## Conditions for revisiting the decision
+
+Revisit for an authorized owner-meaning change where preventive single-source editing repays its cost, a concrete second trusted consumer with demonstrated rule duplication, a reproducible contradictory-mode edit that a smaller boundary prevents, or an accepted independently selectable internal protocol requirement with a clear fixed-order/trust contract. A proposed rewrite must preserve actual obligations and foreign/forced section precedence and show a concrete maintainability gain; behavioral/cognitive claims need their own authorized evaluation. These are falsification conditions, not tasks or a license for a registry/API. Canonical remaining work stays in BACKLOG.