@llblab/pi-kit 0.37.0 → 0.38.0

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

@@ -2,6 +2,24 @@
 
 This is a maintained property-to-test map for the current canonical-file contract, not a second backlog or a substitute for running tests. Paths and quoted test names refer to a source checkout; tests are not shipped in the npm runtime package. Some test labels retain internal Start/Stop terminology: activation uses `/state-flow-active`; inactive scenarios explicitly select Passive or Off according to their tools/context assertions.
 
+## Native seven-selection integration
+
+The seven-core group in `tests/extension.test.ts` retains all seven × Active/Passive original-ID writes/queries/history/no-op/atomic-refusal, Session-only response capture, reload, selected Stop/Passive/Off context, captured defaults and old-tree current-memory witnesses. Unloaded/Off status must report captured scopes without acquiring memory. The seven-fork group in `tests/extension.test.ts` covers selected parent-current copy, shared-only deferred child/pending preservation, late direct-parent Session acquisition and acquired child-current/no recopy. Its native-policy DATA adapters are not public scope controls or acquisition grants.
+
+The seven-facility group in `tests/extension.test.ts` natively creates registrations/provenance before selected source planning, ordinary invalidations/removal and read-driven Skill compilation. Excluded ordinary native reads remain legal; excluded State Flow hints/hash/relocation and semantic-owner mutation do not. Generic maintenance uses presence/fingerprints, not automatic content hashing. The seven-shared-peers group in `tests/extension.test.ts` creates both peers through the SDK and preserves untargeted shared drift without a private owner.
+
+The seven-cancellation group in `tests/extension.test.ts` admits each selected Start, then uses a fixture-owned native Off-tree scope DATA adapter for ABA to prove withdrawal before lock release and fresh-owner recovery. The seven-publication-cancellation group in `tests/extension.test.ts` uses actual tool/message events to hold each selected patch/response publication; public Off cancels owned waits while preserving earlier accepted preparation, native answer delivery and independent fresh work. The native scope-lifetime group in `tests/extension.test.ts` separately proves same-mode pending-restoration ABA and equal-policy observation without awaiting a newly enabled replacement while retaining its required exclusion. These are bounded exact-path/SDK functional witnesses, not model-quality, confidentiality or universal syscall/ancestry proofs.
+
+## Public scope controls and mode-only Telegram
+
+The public-scope group in `tests/extension.test.ts` proves public command tokens, not policy-DATA adapters, select all seven sets from configured Off/all-three; malformed inputs fail atomically, defaults remain unchanged and mode-only/reload retain choice. The public-scope-lifetime group in `tests/extension.test.ts` adds actual public scope ABA, equal canonical held-patch preservation, Off exact-canonical-path I/O guards, different-selection inactive-persistence withdrawal, both late Passive observation kinds and acquired/deferred/fenced refusal. `tests/selection.test.ts` owns full-prefix unused-owner completion; `tests/extension.test.ts` owns parser-before-effects command registration. Requested status and available materialization remain separate exact proofs.
+
+`tests/native-telegram-selection.test.ts` publicly captures each of the seven sets, creates native original-ID memory, then invokes the actual optional registered section handlers for mode-only Passive/Off/Active before and after default changes/reload. Mode payload text cannot become a selector; excluded bytes/private absence, native model tools/context, response ownership and explicit disposable Off inspection remain correct. Only the presentation registry/edit/ack/Rich callbacks are fake; native SDK/mode owners/storage are real. Assertions on collected provider inputs/results run outside callbacks.
+
+The native-telegram-lifetime group in `tests/extension.test.ts` adds seven held-Start → Telegram Off withdrawals with exact canonical-path guards, seven accepted-Passive receipt → public scope-ABA stale-menu refusals, and two real busy native-operation deferrals (accepted same choice versus newer Off changing scopes). One pure copy/radio-layout property distinguishes operator Effective from participating model owners without adding a chooser. `tests/telegram.test.ts` retains optional registration/failure/inspection/fence/lifetime checks; its CAS-failure inspector now explicitly observes the peer's newer field without installing cache or clearing the write fence. No real Telegram delivery or rendered-device claim follows.
+
+See the [M2 functional boundary](scope-selection-contract.md#m2-functional-acceptance-boundary) for the complete property/owner map, legacy-v1 full-cohort dependency, acquired-private presence requirement and explicit-operator exception. These deterministic fixtures are not exhaustive interleavings or universal alias/async filesystem nonaccess.
+
 ## Required properties and witnesses
 
 ### 1. Zero patches
@@ -309,7 +327,10 @@ This is a maintained property-to-test map for the current canonical-file contrac
 ### 44. Intent-owned memory
 
 - `tests/ownership.test.ts` proves same-scope object-key eligibility, recursive structured-reference extraction, shared/ancestor/descendant protection, minimal cascade sets and prototype-safe deletion patches. Textual mentions do not own targets.
-- `tests/transition.test.ts` checks authored operations before cascading, explicit stored deletions in each scope, one-patch supersession, edit-only behavior and no-op repeats. “writes into owned targets in the same patch that deletes their intent are deleted silently” also covers nested additions and newly created targets.
+- `tests/transition.test.ts` now proves intents → cleanup → other authored planes for same-scope strategy/tactics/lazy, fresh same-path writes, supersession, edit-only behavior and no-op repeats. The exact one-cold-copy and rejected-draft detachment checks remain. The former authored-first ordering is superseded; `cascaded` records intermediate clears, not final deletion commands, and final effective values govern.
+- `tests/transition.test.ts` includes the selected properties covering seven selections × retention0/1/7/100 × two JSON key orders (56 cohorts), clearing old fields before all-three-plane rewrites, immutable current state and exact final/previous replay. Eighteen plane × related-path × surviving/new-owner cases preserve protected targets; a later invalid owner rejects the whole cohort without publication.
+- New `native intent-first rewrite` cases in `tests/extension.test.ts` cover all seven choices through actual SDK dispatch, original declared arguments with intents deliberately last, reload and retained fresh values. The runtime inspector's model-visible empty intents/lazy omission is not mistaken for canonical absence: actual owned checkpoint/tail replay checks sparse intent removal and fresh lazy content. Source7/7 and import-only actual-DIST7/7 are bounded scripted-provider evidence, not model reasoning or external fact proof.
+- The completed full coordinator gate passed1621/1621 plus build/typecheck/import/prepack dry-run packaging. Initial independent review executed129 focused,29 guidance,7 Source-SDK,7 actual DIST and3 additional DATA counterexamples; counts overlap the full corpus and are not added. It requested a real guidance correction rather than an engine fix. Subsequent actual terminal follow-ups verified the handoff/backlog lifetime and support-policy prose; initial dissent remains retained, not relabeled earlier approval. Final documentation-only approval was consumed after ROOT terminal before closure; unchanged engine evidence is reused, not rerun or recounted.
 - `tests/temporal.test.ts` proves replay equality from explicit stored deletions through retained history and checkpoint folding; replay does not re-derive ownership.
 - `tests/context.test.ts` requires deleted hot paths and changed lazy navigation in the receipt while the frozen head remains untouched.
 - Per-scope native cases in `tests/integration.test.ts` exercise the cascade in both Active and Passive, preserve textual-reference targets and check one revision per patch cohort. Active response reconciliation is a separate Session revision.

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

@@ -43,12 +43,16 @@ Active, Passive and Off select the session's workflow and model-facing access, n
 **`/state-flow-active`** activates the current Pi branch over validated current same-session memory, initializing absent storage when safe. No remote is required.
 
 - Starting mid-conversation keeps Pi's active context for one complete bootstrap run, during which the agent must compile future-relevant information into state.
-- Repeating Active while already active leaves the in-progress run unchanged.
+- Repeating Active with the same captured scopes leaves the in-progress run unchanged; a different explicit selection is an owned reselection, not an already-active no-op.
 - On an attached branch, activation waits asynchronously for a coherent canonical cohort; pending repeats share the wait.
 - Until acceptance, the existing inactive mode and any write fence stay in effect.
 - Cancelling a pending Active from Off preserves later acquisition choices; ordinary cancellation creates no write fence.
 - Passive, Off or a branch selection can withdraw an obsolete activation. An error after acceptance does not undo accepted memory.
 
+All three mode commands accept optional exact owner tokens, in any order: `/state-flow-active session`, `/state-flow-passive cwd global`, `/state-flow-off cwd session`. Any nonempty unique subset of `global cwd session` is valid; autocomplete offers only unused matching tokens and replaces the full argument prefix. Blank/whitespace-only arguments preserve the captured choice. Unknown/duplicate names, flags and comma-separated forms fail before policy or mode changes. Commands never edit global defaults. Off scope changes record native policy only, without reading or initializing canonical memory. Active explicitly owns acquisition where independently permitted; Passive observation alone cannot acquire missing Session or borrow pending fork permission.
+
+Selection is not materialization: all three scopes are selected by default, but a pre-runtime Passive session can have no private Session cohort yet. Read-only observation exposes existing shared owners without inventing empty Session state. An explicit read of a selected owner missing from that read view reports `selected, unavailable`, not `excluded`; an actually excluded owner is rejected by the selection guard. A legitimate first Session patch on an eligible non-fork branch can acquire private memory through normal atomic acceptance. Do not send an empty patch just to initialize it or bypass pending-fork authority.
+
 How each lifecycle event behaves:
 
 - **New session:** Adopts the global `mode`, defaulting to Off.
@@ -145,6 +149,7 @@ The canonical store is `state-flow/` beneath the agent directory. Keeping config
   - Active initializes missing storage when safe.
   - Passive reads existing memory without publishing; its first explicit patch may initialize absent storage without starting an episode or compaction.
   - Off exposes neither memory tools nor State Flow context.
+- `scopes`: Missing means `global`, `cwd`, `session`. Any of the seven nonempty unique subsets is supported; order is canonicalized without rewriting the file. For example, `"scopes": ["cwd"]` selects project-only memory. The default is captured once for a new or not-yet-captured legacy branch; an existing choice survives reload, tree navigation and later default edits, and forks inherit their parent branch's choice. Mode-only commands/Telegram actions preserve it. Use explicit owner tokens on an existing mode command to change only the current branch's choice; a settings chooser is not required. Never edit accepted lifecycle files to select scopes. Disabled owners cannot be read/patched as model memory or relocated into another owner. Without Session, native answers are delivered but not stored/backfilled; a fork defers private acquisition rather than creating a hidden Session stream. See [native seven-selection integration](scope-selection-contract.md#retained-native-seven-selection-integration) and the [capture boundary](scope-selection-contract.md#configured-scope-defaults-and-native-capture).
 - `logging`: Defaults to `false`. When enabled, rejected patch executions, active barrier blocks, preparation failures and accepted-answer reconciliation failures are recorded locally at `tmp/pi-state-flow/logs.jsonl` beneath the agent directory. Older `tmp/state-flow` logs are left untouched and are not migrated. Asynchronous Git push failures are recorded there even when this setting is off.
 - `showSuccessfulPatches`: Defaults to `true`. In interactive Pi, `patch_state` rows show pretty-printed JSON arguments once in the call, with blank lines between adjacent memory sections; the result shows the acceptance or no-op acknowledgement, never a second patch. Set it to `false` to hide call arguments and keep the compact acknowledgement. Rejected calls retain their arguments and error acknowledgement; State Flow adds no private validation turn.
 - `historyLimit`: Defaults to `7` and accepts integers from `0` through `100`. It counts accepted semantic transitions, **not elapsed time or conversation length**, and bounds materialized-history and scope patch-history offsets.
@@ -152,9 +157,9 @@ The canonical store is `state-flow/` beneath the agent directory. Keeping config
   - Zero keeps only current checkpoints.
   - Raising it affects only future retention and cannot reconstruct discarded history.
 
-**Session configuration.** A session's `config.json` uses the same `mode` key for its concrete choice; commands and Telegram change that session only.
+**Session configuration.** A session's `config.json` uses the same `mode` key for its concrete choice; accepted v2 lifecycle also records concrete `scopes`. Commands and Telegram change that session only and do not edit global defaults.
 
-- Before canonical runtime acceptance, Pi's native `{mode}` checkpoint owns the choice instead of a manufactured storage pair.
+- Before canonical runtime acceptance, an owner-bound native v2 policy record captures `{mode, scopes}` instead of a manufactured storage pair or accepted semantic boundary. A captured branch/fork choice survives later global-default edits.
 - Off stays native-only even after an accepted runtime: its mode/bookmark overrides the earlier canonical mode without needing store access or granting semantic authority.
 - Edit global defaults manually or through an authorized agent, not through `patch_state`.
 - Legacy flag decoding is read-only; see [mode compatibility](compatibility.md#mode-configuration-compatibility).
@@ -190,10 +195,10 @@ Treat logs and state files as private. Removing a secret from current state does
 
 `/state-flow-status` separates runtime configuration/metadata from semantic state. It reports:
 
-- Selected CWD/session keys, internal step, effective `g#c#s#` scope-revision vector, and available hot-history depth.
+- Captured selected owners and, when different, available materialized owners; their known keys, local run step, exact available owner-revision vector and hot-history depth. Unavailable owners receive no fabricated value or zero revision.
 - Known recovery or publication failures, actual artifact counts when nonzero, and pending invalidations. Status does not discover or validate sources.
-- A `Scope memory:` block with one line per scope that has content: the UTF-8 byte size of each present nonempty plane and, when `working` or `lazy` has top-level entries, the share owned by an open intent of that scope (for example `- cwd: intents 137 B, working 32 B; intent-owned working 1/2`). It is operator-only: no notice, threshold or model-facing effect.
-- One JSON representation of effective global → CWD → session memory, with a blank line between top-level semantic planes. Nested JSON is unchanged; individual scope JSON remains available through `read_state`.
+- A `Scope memory:` block with one line per scope that has content: the UTF-8 byte size of each present nonempty plane and, when `tactics` or `lazy` has top-level entries, the share owned by an open intent of that scope (for example `- cwd: intents 137 B, tactics 32 B; intent-owned tactics 1/2`). It is operator-only: no notice, threshold or model-facing effect.
+- One JSON representation of available selected memory in relative global → CWD → session order, with a blank line between top-level semantic planes. Nested JSON is unchanged; individual scope JSON remains available through `read_state`.
 
 Status reports the selected mode and any Active restoration inference fence, while omitting generic ownership/configuration prose. Failed inspection reports unavailable evidence, not invented empty state. Status is observational: it does not read source files, calculate fingerprints, create invalidations or mutate semantic state.
 
@@ -201,7 +206,7 @@ Status reports the selected mode and any Active restoration inference fence, whi
 
 - The terminal indicator is accent `state-flow` plus dim `active` or `passive`; Off hides it. Failed Active restoration stays visible as `active (blocked)`, never as an apparently inactive mode.
 - Global, CWD and Session own independent semantic revisions. One atomic transition advances each materially changed scope once, including session-only response reconciliation.
-- Effective has no scalar counter. It uses the compact lowercase `g#c#s#` revision vector (for example, `g15c8s31`), with no slashes or spaces between counters. The vector appears in `/state-flow-status` and in Telegram's Effective inspection, not in the compact indicators.
+- Effective has no scalar counter. It uses the compact lowercase available-owner revision vector (for example, `g15c8s31` for all three or `c8` for only CWD), with no slashes, spaces or invented excluded counters. The vector appears in `/state-flow-status` and in Telegram's Effective inspection, not in the compact indicators.
 
 ### Telegram controls
 
@@ -210,7 +215,8 @@ When `pi-telegram` is available, its main-menu section shows `State Flow: active
 **Mode controls:**
 
 - A horizontal radio row presents `Off | Passive | Active`. The selected option uses 🟣, 🟡 or 🟢 respectively; each inactive option uses ⚫️.
-- Telegram Active requested during a run waits for settlement; Passive and Off apply immediately.
+- All three mode buttons preserve the current captured scope set, even if callback payload text names another owner. They are not a participation chooser; use explicit owner arguments on the existing commands when changing participation.
+- Telegram Active requested during a run waits for settlement; Passive and Off apply immediately. Off withdraws an old deferred Start, and scope changes cannot revive it when settlement arrives.
 - The first accepted Passive click refreshes the selected button after memory restoration or write-fence recovery, including while the agent is busy. A later mode or branch selection still suppresses an obsolete menu update.
 - Ordinary successful controls add no redundant mode receipt; diagnostic outcomes stay visible.
 - Off exposes neither tool nor State Flow model context.
@@ -220,24 +226,27 @@ When `pi-telegram` is available, its main-menu section shows `State Flow: active
 - The submenu heading shows the current value in monospace.
 - The bold Mode heading uses a long dash, a description ending in a colon, and a blank line before its settings-style list. Each line has a monospaced minus and lowercase monospaced mode value, then a plain colon and description.
 - The descriptions progress from regular chat with no memory (Off, the new-session default), to ordinary chat with memory tools and an available combined memory view (Passive), to the same memory access with completed answers followed by memory-first continuation (Active). They do not claim a new physical Pi session or disabled native compaction.
-- The bold Inspect memory heading follows the same long-dash, description, colon and blank-line pattern. Its four lines use the same monospaced minus/value and plain colon format for `global`, `cwd`, `session` and `effective`, describing the individual scopes and their combined view.
-- Four direct Global/CWD/Session/Effective buttons follow without another chooser.
+- A Participating scopes line shows the captured current choice, initially from global defaults; later default edits do not replace an existing session choice. Mode/help text describes only that set and states when excluded Session means new answers are delivered without storage.
+- The bold Inspect participating memory heading follows the same long-dash, description, colon and blank-line pattern. Only selected owners get a monospaced description and direct button; this is not a scope chooser.
+- With one selected owner, its state is also effective and no separate Effective button appears. With two or three, Effective shows the validated available overlay of those selected owners only, in Global→CWD→Session order. Excluded owners do not contribute or gain an inspection action.
 
 **Memory inspection:**
 
 - Owner-scope Rich snapshots show `#revision`; Effective shows the vector.
 - Fields show pretty-printed JSON directly. Large fields show a bounded JSON prefix with a separate truncation notice and omitted-character count, not a JSON-encoded `preview` string. The preview may end mid-value; actual escapes inside JSON string values remain intact. These presentation limits never truncate stored memory or successful `read_state` results.
-- During a failed-Passive write fence, memory-enabled inspection uses the accepted cache without a potentially conflicting refresh.
-- Otherwise, inspection waits cancelably to load or refresh one coherent shared view, even when passive model tools are disabled. It does not initialize, publish or advance storage.
+- A failed-Passive write fence does not grant repair or cached fallback: explicit operator inspection still validates current canonical memory through a disposable reader. Peer-accepted current values remain observable without clearing the fence or installing a model cache.
+- Inspection waits cancelably for its required current authority, even when model tools are disabled. It does not initialize, publish or advance storage.
 - Data and displayed revisions come from the same observation; absent or invalid memory stays unavailable.
 - Stop, session/tree changes and shutdown cancel obsolete observations.
 - The button acknowledges immediately, and a late failure appears in the menu instead of an expired callback popup.
 
 **Inspecting while Off.** Explicit Off inspection reads current stored memory through a disposable reader.
 
-- Session and Effective require validated same-session private authority and cannot show a fabricated empty layer or revision. Shared Global/CWD inspection stays available independently of private failures.
+- Session, and any Effective view containing selected Session, require the existing validated same-session private authority; a missing private layer/revision is not fabricated. A selected shared-only Effective view uses shared observation and does not read excluded Session bodies. Legacy lifecycle proof may still require its documented complete cohort.
 - These reads install no model/runtime cache, change no bytes or mode, clear no write fence, and leave pending fork acquisition intact for a future Passive/Active selection.
-- Automatic Off callbacks never acquire memory.
+- Automatic Off callbacks never acquire memory. Explicit inspection is read-only even in Off, but the Telegram surface still restricts targets to the captured owners. Obsolete excluded-owner or singleton-Effective callbacks reject before invoking readers; selection changes during acknowledgement/observation withdraw stale results. This presentation rule is not confidentiality, transcript erasure or private-acquisition authority.
+
+The [M2 functional acceptance map](scope-selection-contract.md#m2-functional-acceptance-boundary) records deterministic SDK/presentation witnesses and unavoidable legacy/full-proof dependencies. Scripted provider plus fake presentation is not actual Telegram delivery or live-model quality evidence.
 
 Open implementation work is tracked in [BACKLOG.md](../BACKLOG.md).
 
@@ -332,11 +341,12 @@ Commit or push failure is diagnostic-only; repeated push failures warn once per
 
 **Supported formats.** State Flow accepts only canonical checkpoint/tail files, temporal metadata and the separate session config/runtime contract.
 
-- A canonical scope without a revision counter is readable. Its initial counter uses only the retained semantic tail and is persisted in metadata version 2 on the next owned write, without inventing folded ancestry.
-- Version 1 stays readable. Older writers refuse version 2 through the existing provenance-version fence, so cooperating instances should upgrade together.
+- Scope metadata versions 1/2 remain readable through explicit `contract → strategy`, `working → tactics` translation before field filtering. Current/historical tools expose only the target dialect; retired root writes reject rather than becoming aliases. Legacy missing revisions credit only retained tail records.
+- New writes use scope metadata version 3. On an owned semantic acceptance, legacy cohorts convert with unchanged semantic revisions/causal identities, under the existing lock/CAS and rollback checks. Ordinary inspection and runtime-only mode persistence do not convert files. Upgrade/quiesce all writers before enabling the new code: already-deployed low-level readers cannot be universally fenced by a format number.
 - Unsupported checkpoint envelopes, combined session metadata, `state.json`, hashed layouts and semantic Pi checkpoint envelopes fail as unsupported, without rewriting existing bytes.
 - Canonical semantic objects lacking optional fields, such as `intents` or `lazy`, are valid sparse state and do not cross this boundary.
-- There is no in-place converter; external conversion or a fresh store is up to the operator.
+- Before any v1/v2-to-v3 canonical publication, the storage owner writes and verifies an exact-byte JSON backup at `<parent-of-store>/<store-name>-migration-backups/<sha256>.json` (created with directory mode 0700, file mode 0600 on the verified platform; existing non-private paths reject). It lists converted scopes and updated paths alongside the transaction's owned file basis, relative paths, identities, Base64 originals and explicit missing entries, including required Session config/runtime. It never discovers unrelated projects/sessions or source bodies. The returned publication exposes `migrationBackup`; completed backups survive rollback and exact retries reuse them. Backup failure blocks canonical writes.
+- This backup is recovery evidence outside canonical authority, not a Git commit, journal, automatic fallback or power-loss guarantee. Quiesce writers and request a reviewed complete-cohort recovery before downgrade/restoration; do not overwrite intervening foreign data or restore just one file. Retain backups privately. State Flow 0.x retains legacy conversion and retired-root reservations; the temporary support window ends at State Flow 1.0.0, with unsupported versions still explicitly rejected. The prepared0.27.0 candidate keeps its converter/reservations unchanged; no automatic removal, release or working-store migration follows. See the [settled support policy](semantic-compatibility-decision.md#implementation-direction-and-reserved-names).
 
 ### Conflicts and interrupted publication
 
@@ -375,6 +385,10 @@ No automatic crash repair or power-loss durability is promised, and Git backup h
 
 ## Lazy navigation and historical reading
 
+With exactly one captured participating owner, `read_state` needs no scope token: `lazy.releasePlan` reads current data, `effective[3].lazy.releasePlan` selects its retained older boundary, and a scalar `patches[0]` reads its latest retained owner patch. Ordinary `lazy.items[3]` still indexes an array. Optional explicit selected-owner paths remain legal. With multiple wanted owners, ordinary flat paths use the effective overlay and owner patch history requires `owner.patches[N]`; sparse available memory does not turn a multi-owner choice into one-owner mode. Unavailable history/owners still fail rather than returning invented empty data.
+
+Returned current same-owner structured refs may be scope-free; persisted refs retain canonical ownership. For one wanted owner, `patch_state` now takes planes directly (for example `{ "tactics": { "ready": true } }`) and anchors eligible refs after native admission; do not add an owner wrapper. For multiple wanted owners, keep explicit participating owner patches in one atomic call. Canonical ownership/replay never become scope-free, and changing schema cannot admit an old call under a new owner. Single-owner Active/Passive/bootstrap instructions and packaged Skills use that same grammar. Active/Passive heads and projection-bound updates now render eligible same-owner current refs relatively; the lazy catalog points to `lazy` for one WANTED owner and `effective.lazy` for several. Active recent context uses `{id,at,patch}` for one owner and explicit `transitions` for several, retaining IDs/positions while omitting lazy bodies. These are read-only context DTOs, not patch arguments or storage/replay formats. Canonical provenance, source paths, history and cross-owner/resource refs remain intact. Registered Skill acquisition targets use direct `artifacts[exact source key]` in one-owner mode, explicit owners in multi mode; this target syntax is not a `read_state` locator. Deletion text uses relative JSON pointers such as `/tactics/missing` for one owner, while result details retain canonical owners/paths. Newly generated Stop/reload/bootstrap handoffs render eligible current refs in the same captured interface. Canonical compiler diagnostics may name provenance owners; those are not extra patch wrappers, and retries use the declared flat planes. Exact source keys and canonical operator/error evidence are never broadly prefix-stripped. See the [context presentation boundary](single-scope-interface-contract.md#runtime-context-presentation).
+
 Lazy bodies require explicit reads:
 
 - Automatic state and recent-transition projections omit them, including lazy deletions. Bounded `lazy_navigation` can still show the current layer's presence, path and key types.
@@ -396,7 +410,7 @@ Lazy bodies require explicit reads:
 - A proven stale reference may be repaired within touched work, without resurrecting its target.
 - Without a match, ordinary missing-path errors remain; keys, patch and batch projections keep their existing contracts.
 
-Intent-owned lazy or working keys disappear when their owning intent is deleted, so a later missing path may be an expected cascade rather than a broken reference. The deletion appears in the accepted `patch_state` receipt and in the scope's retained patch history. See [intent ownership](lazy-state.md#intent-ownership).
+Intent-owned strategy, tactics or lazy object keys are cleared after applying intents and before remaining authored planes, independent of JSON insertion order. Final remaining/new same-scope intent references protect direct and ancestor/descendant targets. Rewrite survivors at the same/new path in the closing patch; cleared targets retain no old fields. `cascaded` reports intermediate cleared paths even if recreated; final effective values and retained explicit net patches describe actual state. Historical replay never reruns cascade or rewrites old history. See [intent ownership](lazy-state.md#intent-ownership).
 
 Artifact freshness/invalidations and optional Skill acquisition hints keep their exact source/scope targets. Hints expose possibilities and diagnostic evidence; the current task decides whether action is necessary.
 

package/node_modules/@llblab/pi-state-flow/lib/acquisition.ts

@@ -8,9 +8,11 @@ import {
   type ArtifactSourceIdentity,
   ORDINARY_ARTIFACT_COMPILER,
   type ArtifactProvenanceRegistry,
+  type ArtifactMetadata,
 } from "./artifact.ts";
-import { isObject, type JsonObject } from "./json.ts";
-import type { AtomicScopePatches, ScopedSemanticStates, ScopedStates, StateScope } from "./state.ts";
+import { isObject, sameJson, type JsonObject } from "./json.ts";
+import { assertScopeStateValues, type AtomicScopePatches, type ScopeStateValues, type StateScope } from "./state.ts";
+import { captureScopeSelection, DEFAULT_SCOPE_SELECTION, type ScopeSelection } from "./selection.ts";
 
 /** Why the caller is considering source-body acquisition. */
 export type ArtifactAcquisitionIntent =
@@ -52,6 +54,8 @@ interface PendingRead {
 	toolName: string;
 	args: unknown;
 	fingerprint?: ArtifactSourceFingerprint;
+	path?: string;
+	candidate?: ArtifactInvalidationRequest;
 }
 
 function readPath(toolName: unknown, args: unknown): string | undefined {
@@ -66,9 +70,29 @@ export class ArtifactReadTracker {
 	readonly #pending = new Map<string, PendingRead>();
 	readonly #candidates = new Map<string, ArtifactInvalidationRequest>();
 
-	setCandidates(candidates: Iterable<ArtifactInvalidationRequest>): void {
+	#selection = DEFAULT_SCOPE_SELECTION;
+
+	setCandidates(candidates: Iterable<ArtifactInvalidationRequest>, selection: ScopeSelection = DEFAULT_SCOPE_SELECTION): void {
+		const wanted = captureScopeSelection(selection);
+		const next = new Map<string, ArtifactInvalidationRequest>();
+		for (const candidate of candidates) {
+			if (!wanted.includes(candidate.scope ?? "global")) continue;
+			const captured = structuredClone(candidate);
+			for (const key of ["scope", "hash", "sourceFingerprint"] as const) if (captured[key] === undefined) delete captured[key];
+			next.set(candidate.path, captured);
+		}
+		if (!sameJson(wanted, this.#selection)) this.clear();
+		this.#selection = wanted;
+		for (const [path] of this.successful) {
+			const previous = this.#candidates.get(path), current = next.get(path);
+			if (previous === undefined || current === undefined || !sameJson(previous, current)) this.successful.delete(path);
+		}
 		this.#candidates.clear();
-		for (const candidate of candidates) this.#candidates.set(candidate.path, structuredClone(candidate));
+		for (const [path, candidate] of next) this.#candidates.set(path, candidate);
+		for (const [id, pending] of this.#pending) {
+			const current = pending.path === undefined ? undefined : next.get(pending.path);
+			if (current === undefined || pending.candidate === undefined || !sameJson(current, pending.candidate)) this.#pending.delete(id);
+		}
 	}
 
 	clear(): void {
@@ -89,9 +113,9 @@ export class ArtifactReadTracker {
 		this.#pending.delete(toolCallId);
 		if (isError || !pending || toolName !== pending.toolName) return;
 		const path = readPath(pending.toolName, pending.args);
-		if (path === undefined) return;
+		if (path === undefined || path !== pending.path) return;
 		const candidate = this.#candidates.get(path);
-		if (candidate === undefined || pending.fingerprint === undefined) return;
+		if (candidate === undefined || pending.candidate === undefined || pending.fingerprint === undefined || !sameJson(candidate, pending.candidate)) return;
 		const observation = inspectRegisteredArtifactPaths([path])[0];
 		if (observation?.kind !== "present" || !sameArtifactSourceFingerprint(pending.fingerprint, observation.fingerprint)) return;
 		const finalObservation = inspectRegisteredArtifactPaths([path])[0];
@@ -108,7 +132,7 @@ export class ArtifactReadTracker {
 		const observation = path !== undefined && this.#candidates.has(path) ? inspectRegisteredArtifactPaths([path])[0] : undefined;
 		this.#pending.set(toolCallId, {
 			toolName,
-			args,
+			args, path, candidate: path === undefined ? undefined : this.#candidates.get(path),
 			...(observation?.kind === "present" ? { fingerprint: observation.fingerprint } : {}),
 		});
 	}
@@ -160,8 +184,6 @@ export function decideArtifactAcquisition(
 
 export const SOURCE_CHANGED_HINT = "Source changed since this artifact was compiled. Read and recompile it before relying on it.";
 
-const SCOPES = ["global", "cwd", "session"] as const;
-
 /**
  * One selected branch's ordinary-artifact acquisition plan: runtime-observed
  * invalidations, their model hints and the read tracker correlated to them.
@@ -171,6 +193,7 @@ export class ArtifactAcquisitionState {
 	readonly reads = new ArtifactReadTracker();
 	#invalidations: ArtifactInvalidationRequest[] = [];
 	#hints: Record<string, string> = {};
+	#selection = DEFAULT_SCOPE_SELECTION;
 
 	get invalidations(): readonly ArtifactInvalidationRequest[] { return this.#invalidations; }
 	get hints(): Record<string, string> { return this.#hints; }
@@ -185,29 +208,29 @@ export class ArtifactAcquisitionState {
 	}
 
 	/** Re-observe exact registered sources for the selected scope artifacts. */
-	refresh(states: ScopedStates, provenance: (scope: StateScope) => ArtifactProvenanceRegistry): void {
-		const paths = new Set<string>();
-		for (const scope of SCOPES) for (const path of Object.keys(states[scope].artifacts)) paths.add(path);
+	refresh(states: ScopeStateValues, provenance: (scope: StateScope) => ArtifactProvenanceRegistry, selection: ScopeSelection = DEFAULT_SCOPE_SELECTION): void {
+		const wanted = captureScopeSelection(selection);
+		assertScopeStateValues(states, wanted);
+		const effective = new Map<string, { scope: StateScope; metadata: ArtifactMetadata }>();
+		for (const scope of wanted) for (const [path, metadata] of Object.entries(states[scope]!.artifacts ?? {})) effective.set(path, { scope, metadata });
+		const paths = [...effective].filter(([, { metadata }]) => metadata.kind !== "skill").map(([path]) => path);
 		const observations = new Map(inspectRegisteredArtifactPaths(paths).map((observation) => [observation.path, observation]));
 		const hints: Record<string, string> = {};
-		const invalidations = new Map<string, ArtifactInvalidationRequest>();
-		for (const scope of SCOPES) {
-			const registry = provenance(scope);
-			for (const [path, metadata] of Object.entries(states[scope].artifacts)) {
-				// A narrower owner replaces broader evidence for the same path.
-				delete hints[path];
-				invalidations.delete(path);
-				if (metadata.kind === "skill") continue;
-				const observed = observations.get(path);
-				if (observed?.kind !== "present") continue;
-				const need = classifyArtifactCompilationNeed({ path, scope, sourceFingerprint: observed.fingerprint }, metadata, ORDINARY_ARTIFACT_COMPILER, false, registry[path]);
-				if (need.kind !== "requires-compilation") continue;
-				if (need.reason === "source-changed") hints[path] = SOURCE_CHANGED_HINT;
-				invalidations.set(path, { path, scope, reason: need.reason });
-			}
+		const invalidations: ArtifactInvalidationRequest[] = [];
+		const registries = new Map<StateScope, ArtifactProvenanceRegistry>();
+		for (const path of paths) {
+			const { scope, metadata } = effective.get(path)!;
+			const observed = observations.get(path);
+			if (observed?.kind !== "present") continue;
+			if (!registries.has(scope)) registries.set(scope, provenance(scope));
+			const need = classifyArtifactCompilationNeed({ path, scope, sourceFingerprint: observed.fingerprint }, metadata, ORDINARY_ARTIFACT_COMPILER, false, registries.get(scope)![path]);
+			if (need.kind !== "requires-compilation") continue;
+			if (need.reason === "source-changed") hints[path] = SOURCE_CHANGED_HINT;
+			invalidations.push({ path, scope, reason: need.reason });
 		}
+		this.#selection = wanted;
 		this.#hints = hints;
-		this.#setInvalidations([...invalidations.values()].sort((left, right) => left.path.localeCompare(right.path)));
+		this.#setInvalidations(invalidations.sort((left, right) => left.path.localeCompare(right.path)));
 	}
 
 	/** Accepted compilations leave the plan; correlated read evidence is single-use. */
@@ -218,14 +241,28 @@ export class ArtifactAcquisitionState {
 
 	#setInvalidations(invalidations: ArtifactInvalidationRequest[]): void {
 		this.#invalidations = invalidations;
-		this.reads.setCandidates(invalidations);
+		this.reads.setCandidates(invalidations, this.#selection);
+	}
+}
+
+/** Exact-path metadata revalidation only; callers acquire source bodies outside canonical exclusion. */
+export function validateArtifactReadEvidence(reads: Iterable<SuccessfulArtifactRead>, selection: ScopeSelection = DEFAULT_SCOPE_SELECTION): void {
+	const wanted = captureScopeSelection(selection);
+	for (const read of reads) {
+		if (!wanted.includes(read.scope ?? "global")) continue;
+		const observed = inspectRegisteredArtifactPaths([read.path])[0];
+		if (read.sourceFingerprint === undefined || observed?.kind !== "present" || !sameArtifactSourceFingerprint(read.sourceFingerprint, observed.fingerprint)) {
+			throw new Error(`Artifact source changed after acquisition: ${read.path}`);
+		}
 	}
 }
 
 /** Deletion patches for registered artifacts whose exact source is observed missing, in every owning scope. */
-export function missingArtifactRemovals(states: ScopedSemanticStates): AtomicScopePatches {
+export function missingArtifactRemovals(states: ScopeStateValues, selection: ScopeSelection = DEFAULT_SCOPE_SELECTION): AtomicScopePatches {
+	const wanted = captureScopeSelection(selection);
+	assertScopeStateValues(states, wanted);
 	const owners = new Map<string, StateScope[]>();
-	for (const scope of SCOPES) for (const path of Object.keys(states[scope].artifacts ?? {})) {
+	for (const scope of wanted) for (const path of Object.keys(states[scope]!.artifacts ?? {})) {
 		owners.set(path, [...owners.get(path) ?? [], scope]);
 	}
 	const removals: AtomicScopePatches = {};

package/node_modules/@llblab/pi-state-flow/lib/artifact.ts

@@ -270,42 +270,41 @@ function isProvenanceEntry(value: unknown): value is ArtifactProvenance {
 export function parseArtifactProvenanceRegistry(value: unknown, context = "Artifact provenance"): ArtifactProvenanceRegistry {
 	if (value === undefined) return {};
 	if (!isObject(value)) throw new Error(`${context} must be a path-keyed JSON object`);
-	const registry: ArtifactProvenanceRegistry = {};
-	for (const [path, entry] of Object.entries(value)) {
+	const known = new Set(["sourceHash", "sourceFingerprint", "compilerRevision", "compiledAt"]);
+	return Object.fromEntries(Object.entries(value).map(([path, entry]) => {
 		if (path.trim().length === 0) throw new Error(`${context} path keys must be non-empty`);
-		if (!isObject(entry) || !isJsonValue(entry)) {
-			registry[path] = { malformed: true };
-			continue;
-		}
-		const known = new Set(["sourceHash", "sourceFingerprint", "compilerRevision", "compiledAt"]);
-		if (Object.keys(entry).some((key) => !known.has(key))) {
-			registry[path] = { malformed: true };
-			continue;
-		}
-		registry[path] = {
+		if (!isObject(entry) || !isJsonValue(entry) || Object.keys(entry).some(key => !known.has(key))) return [path, { malformed: true }];
+		return [path, {
 			...(Object.hasOwn(entry, "sourceHash") ? { sourceHash: entry.sourceHash } : {}),
 			...(Object.hasOwn(entry, "sourceFingerprint") ? { sourceFingerprint: entry.sourceFingerprint } : {}),
 			...(Object.hasOwn(entry, "compilerRevision") ? { compilerRevision: entry.compilerRevision } : {}),
 			...(Object.hasOwn(entry, "compiledAt") ? { compiledAt: entry.compiledAt } : {}),
-		};
-	}
-	return registry;
+		}];
+	}));
 }
 
 /** Canonical retained form; uninterpretable entries cannot round-trip and are omitted. */
 export function serializeArtifactProvenanceRegistry(registry: Readonly<ArtifactProvenanceRegistry>): JsonObject {
-	const artifacts: JsonObject = {};
-	for (const [path, entry] of Object.entries(registry)) {
-		if (entry.malformed === true) continue;
+	return Object.fromEntries(Object.entries(registry).flatMap(([path, entry]) => {
+		if (entry.malformed === true) return [];
 		const fields: JsonObject = {};
 		if (entry.sourceHash !== undefined) fields.sourceHash = entry.sourceHash as JsonValue;
 		if (entry.sourceFingerprint !== undefined) fields.sourceFingerprint = entry.sourceFingerprint as JsonValue;
 		if (entry.compilerRevision !== undefined) fields.compilerRevision = entry.compilerRevision as JsonValue;
 		if (entry.compiledAt !== undefined) fields.compiledAt = entry.compiledAt as JsonValue;
-		if (Object.keys(fields).length === 0) continue;
-		artifacts[path] = fields;
-	}
-	return artifacts;
+		return Object.keys(fields).length === 0 ? [] : [[path, fields]];
+	}));
+}
+
+/** Eligibility to revoke known evidence, not retained-data admission or a sanitizer. */
+export function isInterpretableArtifactProvenance(entry: unknown): entry is ArtifactProvenance {
+	if (!isObject(entry)) return false;
+	const keys = Object.keys(entry);
+	return keys.length > 0 && keys.every(key => ["sourceHash", "sourceFingerprint", "compilerRevision", "compiledAt"].includes(key))
+		&& (!Object.hasOwn(entry, "sourceHash") || isArtifactHash(entry.sourceHash))
+		&& (!Object.hasOwn(entry, "sourceFingerprint") || parseArtifactSourceFingerprint(entry.sourceFingerprint) !== undefined)
+		&& (!Object.hasOwn(entry, "compilerRevision") || (typeof entry.compilerRevision === "string" && entry.compilerRevision.trim().length > 0))
+		&& (!Object.hasOwn(entry, "compiledAt") || typeof entry.compiledAt === "string");
 }
 
 function invalidField(value: unknown, validate: (candidate: unknown) => boolean): boolean {

package/node_modules/@llblab/pi-state-flow/lib/config.ts

@@ -5,6 +5,7 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getDurableRepositoryRoot } from "./durable.ts";
 import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT } from "./history.ts";
 import { isObject } from "./json.ts";
+import { captureScopeSelection, DEFAULT_SCOPE_SELECTION, type ScopeSelection } from "./selection.ts";
 import { isStateFlowMode, type InactiveMode, type StateFlowMode } from "./snapshot.ts";
 
 export interface StateFlowConfig {
@@ -12,6 +13,8 @@ export interface StateFlowConfig {
 	directory: string;
 	/** Default mode for genuinely new sessions only; each session owns its selected mode. */
 	mode: StateFlowMode;
+	/** Concrete default selection for genuinely new or not-yet-captured legacy sessions. */
+	scopes: ScopeSelection;
 	/** Non-active fallback for legacy `enabled:false` evidence and unavailable selections; never serialized. */
 	inactiveMode: InactiveMode;
 	/** Opt-in local capture of rejected patch attempts and unresolved terminal drafts. */
@@ -28,6 +31,7 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
 	const defaults: StateFlowConfig = {
 		directory,
 		mode: "off",
+		scopes: DEFAULT_SCOPE_SELECTION,
 		inactiveMode: "off",
 		logging: false,
 		showSuccessfulPatches: true,
@@ -41,7 +45,7 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
 		throw new Error(`Cannot read State Flow configuration: ${path}`, { cause: error });
 	}
 	// autoStart/passiveBootstrap/passiveTools are read-only compatibility inputs; explicit mode is authoritative.
-	const allowed = new Set(["mode", "autoStart", "passiveBootstrap", "passiveTools", "logging", "showSuccessfulPatches", "historyLimit"]);
+	const allowed = new Set(["scopes", "mode", "autoStart", "passiveBootstrap", "passiveTools", "logging", "showSuccessfulPatches", "historyLimit"]);
 	if (!isObject(value) || Object.keys(value).some((key) => !allowed.has(key))) {
 		throw new Error(`State Flow configuration contains unknown settings: ${path}`);
 	}
@@ -52,12 +56,21 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
 	if (Object.hasOwn(value, "logging") && typeof value.logging !== "boolean") throw new Error(`State Flow logging must be a boolean: ${path}`);
 	if (Object.hasOwn(value, "showSuccessfulPatches") && typeof value.showSuccessfulPatches !== "boolean") throw new Error(`State Flow showSuccessfulPatches must be a boolean: ${path}`);
 	if (Object.hasOwn(value, "historyLimit") && (!Number.isSafeInteger(value.historyLimit) || (value.historyLimit as number) < 0 || (value.historyLimit as number) > MAX_HISTORY_LIMIT)) throw new Error(`State Flow historyLimit must be an integer from 0 to ${MAX_HISTORY_LIMIT}: ${path}`);
+	let scopes = DEFAULT_SCOPE_SELECTION;
+	if (Object.hasOwn(value, "scopes")) {
+		try {
+			scopes = captureScopeSelection(value.scopes);
+		} catch {
+			throw new Error(`Invalid State Flow scopes configuration: ${path}`);
+		}
+	}
 	const legacyInactive: InactiveMode = value.passiveBootstrap !== false || value.passiveTools !== false ? "passive" : "off";
 	const hasLegacyMode = Object.hasOwn(value, "autoStart") || Object.hasOwn(value, "passiveBootstrap") || Object.hasOwn(value, "passiveTools");
 	const mode = isStateFlowMode(value.mode) ? value.mode : value.autoStart === true ? "active" : hasLegacyMode ? legacyInactive : "off";
 	return {
 		directory,
 		mode,
+		scopes,
 		inactiveMode: isStateFlowMode(value.mode) ? inactiveModeFor(value.mode) : hasLegacyMode ? legacyInactive : "off",
 		logging: value.logging === true,
 		showSuccessfulPatches: value.showSuccessfulPatches !== false,