@llblab/pi-kit 0.37.1 → 0.38.0

package/node_modules/@llblab/pi-state-flow/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## Unreleased
+
+## 0.27.1: Selected Scope Read Diagnostics
+
+- `Read availability`: Explicit reads now distinguish a selected owner with no available read view from an excluded owner. In pre-runtime Passive sessions, an unacquired Session no longer incorrectly reports itself excluded. Reads still do not create private memory, widen the selection or return partial multi-path results; normal accepted writes retain their acquisition rules.
+
+## 0.27.0: Semantic Memory and Scope Selection
+
+- `Semantic API (breaking)`: `strategy`/`tactics` replace `contract`/`working` in runtime fields, public types, schemas, queries, receipts and Skills. Strategy retains binding requirements, accepted approaches and rejection reasons; tactics holds operational evidence. Proposals are not commitments. New-format retired-root writes reject; ordinary nested keys remain legal.
+- `Scope selection and tools (breaking)`: All seven nonempty Global/CWD/Session choices work independently of Active/Passive/Off. Commands accept explicit owners and completion; Telegram preserves the choice, filters inspection/help, and shows Effective only for2+ owners. One WANTED owner uses direct semantic planes and relative current refs; multiple owners use explicit atomic patches. Wanted selection is distinct from available memory. New accepted answers remain Session-only.
+- `Intent ownership (breaking)`: Structured refs in intents now own same-scope strategy/tactics/lazy object keys. Fixed phases apply intents, clear unprotected targets, then other fields; remaining/new related refs protect targets. Later writes recreate cleared paths without old fields, independent of JSON key order. Existing strategy refs acquire ownership for future intent deletions; accepted history replays net patches without re-running cleanup.
+- `Recoverable conversion`: Legacy1/2 translate to Strategy/Tactics before filtering. Candidate metadata4 retains declared external object planes/descriptors without definitions through core writes, folding and fork; core-only streams keep3. Explicit upgrades reject raw namespace collisions and require private exact-byte backup/CAS with foreign-edit-safe rollback. Reads/mode persistence never upgrade. Quiesce old writers; universal old-writer safety is not promised. Legacy support remains throughout0.x.
+- `Request and acceptance authority`: Original-ID receipts, physical runtime/CWD/storage identity, captured selection and operation signals gate tools/context/answers before semantic interpretation or source callbacks. Real scope changes revoke stale work without ABA revival; equal choices preserve eligible work. Pending/failed Active acceptance fences inference, Off stays native-only, controls remain independent, and accepted publication survives later cancellation or bookkeeping failure.
+- `Current memory and private forks`: One accepted/observed runtime preserves sparse current state, independent revisions and private causal proof. Observation cannot acquire or publish. Shared drift yields a validated current-only origin without private reset. Deferred forks copy only the direct parent’s current state under exact source/target proof; acquired children never recopy. Opaque future/malformed metadata stays intact, and single-use callback publishers expire.
+- `Source-bound artifacts and Skills`: Selected owner/provenance gates maintenance and compilation; excluded owners do not become flat destinations. Ordinary artifacts retain fingerprints, Skills retain read-driven hashes, and foreign native reads stay volatile rather than being relocated. Compilation/provenance publish with semantic output; caller-forged provenance rejects. Source reads stay outside canonical exclusion; exact CAS is rechecked before publication.
+- `Context and modules`: Built-ins use executable immutable/context and async-producer contracts. Candidate public modules have revocable native-host lifetimes, retained metadata4 identities and matched mutable roots and captured Active/Passive user-level context; Active producers commit cohort-atomic replacements. Sparse history/IDs, special keys/provenance and one atomic engine retained. No measured quality/cost/cache gain. Calibration: `769eed097736760360cae612d2b331c7549787d15617d90c065df510a507544c`.
+
 ## 0.26.5: Telegram Mode Receipt Hotfix
 
 - `Telegram mode controls`: Passive now refreshes the selected button on the first accepted click after Off, including existing-memory restoration and write-fence recovery during an active run. Accepted controls retain their renewed presentation receipt instead of being mistaken for canceled work; later mode choices, branch changes and shutdown still suppress obsolete updates. Memory storage and mode semantics are unchanged; no migration is required.

package/node_modules/@llblab/pi-state-flow/README.md

@@ -100,20 +100,24 @@ Memory has three ownership scopes:
 - `cwd`: Knowledge shared by sessions in the same working directory.
 - `session`: State belonging to the current session and its selected branch.
 
-They compose recursively in **global → CWD → session** order:
+Participation is configured with a nonempty `scopes` array in [global configuration](docs/usage.md#configuration); omission selects all three. Each native branch captures that choice once, and forks inherit it. All seven nonempty selections use the same runtime. The existing mode commands accept optional whitespace-separated owners, for example `/state-flow-active session`, `/state-flow-passive cwd global`, or `/state-flow-off cwd`. Blank/mode-only commands and Telegram controls preserve the captured choice. Duplicate/unknown tokens reject before changing policy; Off records a new choice without canonical memory I/O. No settings chooser is required. Excluded owners receive no automatic memory contribution or semantic writes; new answers are stored only when Active and Session participates. Mode-only Telegram buttons retain that choice; explicit operator inspection is separate from model participation. See the [functional boundary and legacy proof dependencies](docs/scope-selection-contract.md#m2-functional-acceptance-boundary).
+
+Participating owners compose recursively in **global → CWD → session** order:
 
 - More-specific values override broader ones, while object fields merge.
 - Removing a local value can reveal an inherited value again.
 
 The agent receives the **effective view** of this composition, not three unrelated memory dumps. It can read that view, or inspect one scope when ownership matters. `effective` is a computed view, not a fourth storage scope. Scope precedence does not turn memory into system-level instructions.
 
+With one captured owner, current same-owner structured references in Active/Passive heads and projection-bound updates are relative, lazy navigation points to `lazy`, and Active recent context records use `{id,at,patch}` without an owner wrapper. Multi-owner records stay explicit. Canonical storage, internal comparisons and causal IDs remain scoped; provenance and historical/cross-owner/resource references retain their identities. Skill acquisition targets and deletion text also follow wanted arity; new Stop/reload/bootstrap handoffs render eligible refs relatively. Source keys and canonical provenance/compiler diagnostics retain their identities, not extra flat patch wrappers. These DTOs are data, not authoring permission. See the [context presentation boundary](docs/single-scope-interface-contract.md#runtime-context-presentation).
+
 ### Semantic planes
 
 Runtime views provide these documented planes:
 
-- `intents`: The queue of chosen actions. Work from intents: a structured `{"$ref"}` inside an intent owns a same-scope `working`/`lazy` key, and deleting the intent deletes what it owns unless another intent still references it. Textual `$path` mentions only use; unowned entries remain legal.
-- `contract`: Requirements, decisions, rejected approaches, constraints and interface commitments.
-- `working`: Temporary context of those actions: observations, results and uncertainties.
+- `intents`: The queue of chosen actions. Work from intents: a structured `{"$ref"}` inside an intent owns a same-scope `strategy`/`tactics`/`lazy` object key. Fixed phases ignore JSON insertion order: intents first, ownership cleanup with final remaining/new intents protecting direct and ancestor/descendant targets, then remaining authored planes and existing compilation/normalization/atomic publication. Rewrite survivors at the same/new path in that patch; cleared targets start fresh without old fields. Textual `$path` mentions only use; unowned entries remain legal.
+- `strategy`: Binding requirements, accepted approaches/plans, decisions, rejected alternatives and interface commitments. A proposal is not a commitment.
+- `tactics`: Temporary execution context: verified progress, consequential failures, blockers, uncertainties and next checks.
 - `artifacts`: Source-addressed descriptions and compiled knowledge.
 - `response`: The exact latest accepted answer, including an empty string. The runtime captures it only in Session; Global/CWD receive no newly accepted answers, and stored scopes may omit it entirely. Effective uses the highest-priority nonempty value. Active automatically projects it; Passive omits it from automatic context while keeping storage and explicit reads intact.
 - `lazy`: Supporting memory available through explicit reads; its body is omitted from baseline model context.
@@ -122,7 +126,7 @@ Every plane is optional on disk:
 
 - Stored checkpoints and patches may omit any documented plane, including `intents`, `lazy` or `response`.
 - Current and historical views assemble only the known fields actually present in the selected scopes; absent fields are not filled in. Empty `response` counts as absent.
-- Readers ignore unknown top-level fields, and writers emit only known fields. Nested data inside known planes is unrestricted.
+- Readers ignore unrelated unknown top-level fields, and writers emit only known fields. Retired `contract`/`working` roots explicitly reject in the target format; nested ordinary keys remain unrestricted.
 - Reading or starting never rewrites data just to normalize it, and a missing field is not a storage-format error.
 
 These planes organize ordinary JSON; there is no project-specific schema. The model updates every plane except `response`, which is runtime-owned.
@@ -130,7 +134,7 @@ These planes organize ordinary JSON; there is no project-specific schema. The mo
 Revisions:
 
 - Global and CWD revisions are shared by their canonical stores; Session has its own revision.
-- Effective has no single owner: its identity is the `g#c#s#` vector.
+- Effective combines participating owners: with multiple owners its identity is their revision vector (for example `g#c#s#` when all three participate), not one universal revision. Excluded owners do not become fabricated vector entries.
 - One atomic patch advances each materially changed scope once.
 
 Memory remains fallible: storing an observation does not make it current or correct.
@@ -139,7 +143,13 @@ Registered Pi Skills may be compiled into source-addressed artifacts when durabl
 
 ## Incremental updates and history
 
-`patch_state` updates one or more named scopes atomically:
+`patch_state` uses the captured wanted interface, not the number of currently available views. With **one participating owner**, supply semantic planes directly, without an owner wrapper:
+
+```json
+{ "strategy": { "verification": { "command": "npm test" } } }
+```
+
+With **multiple participating owners**, name the supplied owners explicitly; they commit atomically. Canonical ownership remains explicit internally in both cases:
 
 - It waits cancelably for the store lock, then applies authored Global/CWD patches to the current canonical values, so other writers' untouched fields survive.
 - Overlapping assignments follow successful acceptance order. Correct repeats succeed without new semantic revisions.
@@ -147,28 +157,32 @@ Registered Pi Skills may be compiled into source-addressed artifacts when durabl
 - Object patches merge recursively, and `null` deletes an object key instead of being stored.
 - Accepted supplied scopes recursively drop empty object fields and planes, including explicit `{}`; empty ancestors disappear. Array slots and empty arrays stay intact. Cleanup is scope-local and may reveal inherited values. Model context hides legacy empty branches, but reading never rewrites history. See [patch semantics](docs/architecture.md#model-tools).
 
+Multi-owner example, requiring CWD and Session to participate:
+
 ```json
 {
   "cwd": {
-    "contract": { "verification": { "command": "npm test" } }
+    "strategy": { "verification": { "command": "npm test" } }
   },
   "session": {
     "intents": { "verify": { "action": "Run the checks before publishing" } },
-    "working": { "checks": "Pending" }
+    "tactics": { "checks": "Pending" }
   }
 }
 ```
 
 During an active episode, a material patch is an inference barrier: sibling tool calls are blocked, and the next inference sees the accepted effective state. Ordinary completion needs no finalization patch or extra State Flow reasoning loop.
 
-`read_state` provides targeted current and historical access:
+`read_state` accepts flat ordinary paths with one owner (for example `{ "path": "tactics" }`); `effective[N]` selects that owner's retained temporal boundary and scalar `patches[N]` its retained patch. Current same-owner structured refs may use `{ "$ref": "lazy.plan" }`; persistence anchors them to the exact owner. Never reinterpret different-owner/historical/effective refs, resources or text as local permission.
+
+With multiple owners, unscoped reads use the effective overlay. This multi-owner example requires every explicit owner to participate:
 
 ```json
-{ "paths": ["effective.contract", "cwd.working", "session.intents"] }
+{ "paths": ["effective.strategy", "cwd.tactics", "session.intents"] }
 ```
 
-- `working`: Current effective working memory; unscoped paths are effective aliases.
-- `effective[1].working`: Working memory at the preceding accepted transition boundary, when retained.
+- `tactics`: Current sole-owner memory, or the effective overlay when multiple owners participate.
+- `effective[1].tactics`: Working memory at the preceding accepted transition boundary, when retained.
 - `cwd.patches[0]`: The latest retained CWD semantic patch.
 - `effective.lazy.memory[0..3]`: A bounded slice of a stored collection.
 
@@ -225,7 +239,7 @@ How mode changes interact with storage:
 - Explicit Off inspection may read current stored values through a disposable validated reader. It does not activate memory, install cache or change pending fork acquisition. Missing private authority stays unavailable.
 - Active waits for a coherent capture and acceptance; another mode or selection can withdraw its wait.
 
-State Flow accepts only the canonical store contract and provides no in-place format converter. Preserve existing data and check the [format boundary](docs/usage.md#moving-a-store-and-supported-formats) before changing versions or moving a store.
+Canonical scope metadata v3 uses `strategy` and `tactics`. Supported v1/v2 checkpoint/tail cohorts are read through a declared translation and converted once on an owned semantic acceptance, after a verified exact-byte backup outside the canonical store. Upgrade/quiesce all writers first; unsupported layouts are not repaired. See the [format and backup boundary](docs/usage.md#moving-a-store-and-supported-formats) before upgrading or moving a store.
 
 ## Operational boundaries
 
@@ -244,6 +258,8 @@ Treat state, diagnostic logs and backups as private data. Revalidate consequenti
 - [Acceptance map](docs/temporal-acceptance.md) — Properties tied to concrete tests.
 - [Documentation index](docs/README.md) — All maintained guides.
 
+The six built-in planes use an [internal semantic-module contract](docs/semantic-module-contract.md) for authoring policy and mode-aware context. It also supplies isolated context/producer executors. The candidate [public module entry](docs/public-module-contract.md) adds native-host-scoped registration/lifetime binding; metadata4 opaque-retention codecs have bounded local acceptance, and registered mutable external roots now use the existing read/patch tools in the local candidate; captured inputs and Active/Passive module context now execute with source and native-identity fences, and Active async producers commit complete replacements through the same atomic engine. Ordinary public consumers now have SOURCE/built-SDK acceptance evidence for current-only forks and opaque retention across folding, reload, absence and re-registration. This remains an unpublished local candidate, not a new independent activation approval. Neither contract implies a new loader or automatic background reasoning.
+
 For development, run `npm install` and `npm run validate`. `npm run benchmark` is opt-in and separate from the normal suite; see `benchmarks/README.md` in a source checkout.
 
 Project context: [AGENTS.md](AGENTS.md), [BACKLOG.md](BACKLOG.md), [CHANGELOG.md](CHANGELOG.md).

package/node_modules/@llblab/pi-state-flow/api/modules.ts

@@ -0,0 +1,11 @@
+// Domain: public State Flow module registration membrane.
+// Registry ownership and semantic publication remain package-private.
+export { registerStateFlowModule } from "../lib/module-registry.ts";
+export type {
+	ModuleContextContribution,
+	StateFlowModule,
+	StateFlowModuleFrame,
+	StateFlowModuleInput,
+	StateFlowModuleSource,
+} from "../lib/semantic-module.ts";
+export type { JsonObject, JsonValue } from "../lib/json.ts";

package/node_modules/@llblab/pi-state-flow/dist/api/modules.d.ts

@@ -0,0 +1,3 @@
+export { registerStateFlowModule } from "../lib/module-registry.ts";
+export type { ModuleContextContribution, StateFlowModule, StateFlowModuleFrame, StateFlowModuleInput, StateFlowModuleSource, } from "../lib/semantic-module.ts";
+export type { JsonObject, JsonValue } from "../lib/json.ts";

package/node_modules/@llblab/pi-state-flow/dist/api/modules.js

@@ -0,0 +1,3 @@
+// Domain: public State Flow module registration membrane.
+// Registry ownership and semantic publication remain package-private.
+export { registerStateFlowModule } from "../lib/module-registry.js";

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

@@ -1,5 +1,6 @@
 import { type ArtifactInvalidationReason, type ArtifactInvalidationRequest, type ArtifactSourceIdentity, type ArtifactProvenanceRegistry } from "./artifact.ts";
-import type { AtomicScopePatches, ScopedSemanticStates, ScopedStates, StateScope } from "./state.ts";
+import { type AtomicScopePatches, type ScopeStateValues, type StateScope } from "./state.ts";
+import { type ScopeSelection } from "./selection.ts";
 /** Why the caller is considering source-body acquisition. */
 export type ArtifactAcquisitionIntent = "routine" | "new-session" | "relevant-gap" | "exact-source" | "exact-edit" | "contradiction-or-failure" | "explicit-request" | "maintenance";
 export type ArtifactAcquisitionReason = ArtifactInvalidationReason | "materialized-gap" | "exact-source" | "exact-edit" | "contradiction-or-failure" | "explicit-request" | "maintenance";
@@ -25,7 +26,7 @@ export interface SuccessfulArtifactRead extends ArtifactInvalidationRequest {
 export declare class ArtifactReadTracker {
     #private;
     readonly successful: Map<string, SuccessfulArtifactRead>;
-    setCandidates(candidates: Iterable<ArtifactInvalidationRequest>): void;
+    setCandidates(candidates: Iterable<ArtifactInvalidationRequest>, selection?: ScopeSelection): void;
     clear(): void;
     recordStart(toolCallId: string, toolName: string, args: unknown): void;
     recordCall(toolCallId: string, toolName: string, input: unknown): void;
@@ -54,9 +55,11 @@ export declare class ArtifactAcquisitionState {
     /** Forget plan and hints when no memory view is selected. */
     reset(): void;
     /** Re-observe exact registered sources for the selected scope artifacts. */
-    refresh(states: ScopedStates, provenance: (scope: StateScope) => ArtifactProvenanceRegistry): void;
+    refresh(states: ScopeStateValues, provenance: (scope: StateScope) => ArtifactProvenanceRegistry, selection?: ScopeSelection): void;
     /** Accepted compilations leave the plan; correlated read evidence is single-use. */
     acceptAcquired(paths?: ReadonlySet<string>): void;
 }
+/** Exact-path metadata revalidation only; callers acquire source bodies outside canonical exclusion. */
+export declare function validateArtifactReadEvidence(reads: Iterable<SuccessfulArtifactRead>, selection?: ScopeSelection): void;
 /** Deletion patches for registered artifacts whose exact source is observed missing, in every owning scope. */
-export declare function missingArtifactRemovals(states: ScopedSemanticStates): AtomicScopePatches;
+export declare function missingArtifactRemovals(states: ScopeStateValues, selection?: ScopeSelection): AtomicScopePatches;

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

@@ -1,5 +1,7 @@
 import { classifyArtifactCompilationNeed, inspectRegisteredArtifactPaths, sameArtifactSourceFingerprint, ORDINARY_ARTIFACT_COMPILER, } from "./artifact.js";
-import { isObject } from "./json.js";
+import { isObject, sameJson } from "./json.js";
+import { assertScopeStateValues } from "./state.js";
+import { captureScopeSelection, DEFAULT_SCOPE_SELECTION } from "./selection.js";
 function readPath(toolName, args) {
     return toolName === "read" && isObject(args) && typeof args.path === "string"
         ? args.path
@@ -10,10 +12,35 @@ export class ArtifactReadTracker {
     successful = new Map();
     #pending = new Map();
     #candidates = new Map();
-    setCandidates(candidates) {
+    #selection = DEFAULT_SCOPE_SELECTION;
+    setCandidates(candidates, selection = DEFAULT_SCOPE_SELECTION) {
+        const wanted = captureScopeSelection(selection);
+        const next = new Map();
+        for (const candidate of candidates) {
+            if (!wanted.includes(candidate.scope ?? "global"))
+                continue;
+            const captured = structuredClone(candidate);
+            for (const key of ["scope", "hash", "sourceFingerprint"])
+                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() {
         this.successful.clear();
@@ -31,10 +58,10 @@ export class ArtifactReadTracker {
         if (isError || !pending || toolName !== pending.toolName)
             return;
         const path = readPath(pending.toolName, pending.args);
-        if (path === undefined)
+        if (path === undefined || path !== pending.path)
             return;
         const candidate = this.#candidates.get(path);
-        if (candidate === undefined || pending.fingerprint === undefined)
+        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))
@@ -53,7 +80,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 } : {}),
         });
     }
@@ -90,7 +117,6 @@ export function decideArtifactAcquisition(source, metadata, compiler, options) {
     }
 }
 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"];
 /**
  * One selected branch's ordinary-artifact acquisition plan: runtime-observed
  * invalidations, their model hints and the read tracker correlated to them.
@@ -100,6 +126,7 @@ export class ArtifactAcquisitionState {
     reads = new ArtifactReadTracker();
     #invalidations = [];
     #hints = {};
+    #selection = DEFAULT_SCOPE_SELECTION;
     get invalidations() { return this.#invalidations; }
     get hints() { return this.#hints; }
     /** Drop the invalidation plan; hints remain until the next refresh. */
@@ -110,35 +137,35 @@ export class ArtifactAcquisitionState {
         this.#setInvalidations([]);
     }
     /** Re-observe exact registered sources for the selected scope artifacts. */
-    refresh(states, provenance) {
-        const paths = new Set();
-        for (const scope of SCOPES)
-            for (const path of Object.keys(states[scope].artifacts))
-                paths.add(path);
+    refresh(states, provenance, selection = DEFAULT_SCOPE_SELECTION) {
+        const wanted = captureScopeSelection(selection);
+        assertScopeStateValues(states, wanted);
+        const effective = new Map();
+        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 = {};
-        const invalidations = new Map();
-        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 = [];
+        const registries = new Map();
+        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. */
     acceptAcquired(paths = new Set(this.reads.successful.keys())) {
@@ -147,13 +174,27 @@ export class ArtifactAcquisitionState {
     }
     #setInvalidations(invalidations) {
         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, selection = DEFAULT_SCOPE_SELECTION) {
+    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) {
+export function missingArtifactRemovals(states, selection = DEFAULT_SCOPE_SELECTION) {
+    const wanted = captureScopeSelection(selection);
+    assertScopeStateValues(states, wanted);
     const owners = new Map();
-    for (const scope of SCOPES)
+    for (const scope of wanted)
         for (const path of Object.keys(states[scope].artifacts ?? {})) {
             owners.set(path, [...owners.get(path) ?? [], scope]);
         }

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

@@ -107,6 +107,8 @@ export declare function isArtifactRegistry(value: unknown): value is ArtifactReg
 export declare function parseArtifactProvenanceRegistry(value: unknown, context?: string): ArtifactProvenanceRegistry;
 /** Canonical retained form; uninterpretable entries cannot round-trip and are omitted. */
 export declare function serializeArtifactProvenanceRegistry(registry: Readonly<ArtifactProvenanceRegistry>): JsonObject;
+/** Eligibility to revoke known evidence, not retained-data admission or a sanitizer. */
+export declare function isInterpretableArtifactProvenance(entry: unknown): entry is ArtifactProvenance;
 /** Decide whether retained compilation evidence requires source reacquisition. */
 export declare function classifyArtifactCompilationNeed(source: ArtifactSourceIdentity, metadata: unknown, compiler: string, explicitRefresh?: boolean, provenance?: unknown): ArtifactCompilationNeed;
 /** Split one compiler output into model-visible semantics and runtime-owned provenance. */

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

@@ -160,34 +160,25 @@ export function parseArtifactProvenanceRegistry(value, context = "Artifact prove
         return {};
     if (!isObject(value))
         throw new Error(`${context} must be a path-keyed JSON object`);
-    const registry = {};
-    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] = {
-            ...(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;
+        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 } : {}),
+            }];
+    }));
 }
 /** Canonical retained form; uninterpretable entries cannot round-trip and are omitted. */
 export function serializeArtifactProvenanceRegistry(registry) {
-    const artifacts = {};
-    for (const [path, entry] of Object.entries(registry)) {
+    return Object.fromEntries(Object.entries(registry).flatMap(([path, entry]) => {
         if (entry.malformed === true)
-            continue;
+            return [];
         const fields = {};
         if (entry.sourceHash !== undefined)
             fields.sourceHash = entry.sourceHash;
@@ -197,11 +188,19 @@ export function serializeArtifactProvenanceRegistry(registry) {
             fields.compilerRevision = entry.compilerRevision;
         if (entry.compiledAt !== undefined)
             fields.compiledAt = entry.compiledAt;
-        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) {
+    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, validate) {
     return value !== undefined && !validate(value);

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

@@ -1,9 +1,12 @@
+import { type ScopeSelection } from "./selection.ts";
 import { type InactiveMode, type StateFlowMode } from "./snapshot.ts";
 export interface StateFlowConfig {
     /** Canonical State Flow repository. SDK callers may still override it explicitly. */
     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. */

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

@@ -5,6 +5,7 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getDurableRepositoryRoot } from "./durable.js";
 import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT } from "./history.js";
 import { isObject } from "./json.js";
+import { captureScopeSelection, DEFAULT_SCOPE_SELECTION } from "./selection.js";
 import { isStateFlowMode } from "./snapshot.js";
 /** Read the repository-global config once at extension load/reload. Missing config uses defaults; invalid config never falls back. */
 export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = getDurableRepositoryRoot(agentDir)) {
@@ -13,6 +14,7 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
     const defaults = {
         directory,
         mode: "off",
+        scopes: DEFAULT_SCOPE_SELECTION,
         inactiveMode: "off",
         logging: false,
         showSuccessfulPatches: true,
@@ -28,7 +30,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}`);
     }
@@ -46,12 +48,22 @@ export function loadStateFlowConfig(agentDir = getAgentDir(), repositoryRoot = g
         throw new Error(`State Flow showSuccessfulPatches must be a boolean: ${path}`);
     if (Object.hasOwn(value, "historyLimit") && (!Number.isSafeInteger(value.historyLimit) || value.historyLimit < 0 || value.historyLimit > 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 = 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,