@llblab/pi-kit 0.26.0 → 0.27.1

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

@@ -4,13 +4,18 @@
 
 **Incremental scoped context/memory compiler for Pi.**
 
-When enabled, State Flow maintains explicit state across requests and sessions. The agent incrementally compiles requirements, decisions, findings and source knowledge into durable memory rather than carrying every completed exchange into the next request.
+When enabled, State Flow maintains explicit state across requests and sessions. Instead of carrying every completed exchange into the next request, the agent incrementally compiles requirements, decisions, findings and source knowledge into durable memory.
 
-Drawing on the explicit-state approach of [SKILL.state](https://arxiv.org/html/2608.26263v2), State Flow combines durable state with Pi's native conversation context. In this hybrid, **state carries continuity between user runs; Pi's native context carries the working trajectory within a run.** The conversation is not reset after each model response or tool call. Pi retains ownership of execution, session navigation and the full inspectable trace.
+The idea comes from the explicit-state approach of [SKILL.state](https://arxiv.org/html/2608.26263v2), combined with Pi's native conversation context:
+
+- **State carries continuity between user runs.**
+- **Pi's native context carries the working trajectory within a run.**
+
+The conversation is not reset after each model response or tool call. Pi keeps ownership of execution, session navigation and the full inspectable trace.
 
 ## How it works
 
-In Active mode, a user run starts with effective memory and a new request. The agent works through Pi's ordinary inference/tool loop, updates memory when useful information changes, and returns an ordinary answer. The next run receives the accepted state and compact recent transitions instead of the completed ordinary conversation history.
+In Active mode, each user run starts with the effective memory plus the new request. The agent works through Pi's ordinary inference/tool loop, updates memory when useful information changes, and returns an ordinary answer. The next run receives the accepted state and compact recent transitions instead of the completed conversation history.
 
 ```text
 Current state + Request
@@ -22,11 +27,23 @@ Patched state + Answer
 Updated state
 ```
 
-Within a run, the available request, intermediate responses, tool results and steering remain in context. The initial memory head stays byte-stable: accepted changes arrive in patch results, and changing runtime notices append at the tail without moving earlier messages. Passive memory uses the same approach across ordinary user turns, rebasing at native or mode boundaries. Projection IDs distinguish current updates from retained historical results. A state patch neither rewrites the head nor discards the working trajectory. Persistent context-bearing messages from other extensions are preserved as well.
+What the model sees during a run:
+
+- The request, intermediate responses, tool results and steering stay in context.
+- The initial memory head stays byte-stable. Accepted changes arrive in patch results, and changing runtime notices are appended at the tail without moving earlier messages.
+- Projection IDs tell current updates apart from retained historical results.
+- A state patch neither rewrites the head nor discards the working trajectory.
+- Persistent context-bearing messages from other extensions are preserved.
+
+Passive memory uses the same approach across ordinary user turns and rebases only at native or mode boundaries.
+
+Why this helps:
 
-This reduces reliance on repeated model-generated summaries of an accumulating transcript. Retaining the current trajectory also allows prompt-cache reuse while the relevant prefix remains unchanged. Avoiding summary calls and repeated prompt processing can improve responsiveness; the result depends on the model, provider, workload and frequency of state changes, not a fixed latency guarantee.
+- It reduces reliance on repeated model-generated summaries of a growing transcript.
+- Keeping the current trajectory lets prompt caches be reused while the relevant prefix is unchanged.
+- Avoiding summary calls and repeated prompt processing can improve responsiveness. The effect depends on the model, provider, workload and how often state changes; there is no fixed latency guarantee.
 
-Native compaction remains available for long runs. State Flow may also request a completed-history boundary without another model summary, retaining the complete latest accepted run. Neither mechanism deletes Pi's append-only session trace. See [lifecycle behavior](docs/usage.md#session-behavior) and [performance evidence](docs/performance.md).
+Native compaction remains available for long runs. State Flow may also request a completed-history boundary without another model summary, keeping the complete latest accepted run. Neither mechanism deletes Pi's append-only session trace. See [lifecycle behavior](docs/usage.md#session-behavior) and [performance evidence](docs/performance.md).
 
 ## Installation and activation
 
@@ -50,22 +67,28 @@ Enable active State Flow on the current branch:
 /state-flow-active
 ```
 
-Starting in an existing conversation retains its context for one complete bootstrap run so the agent can compile what matters.
+Starting in an existing conversation keeps its context for one complete bootstrap run, so the agent can compile what matters.
+
+Commands:
 
 - `/state-flow-active`: Select the active, state-driven iteration workflow.
 - `/state-flow-passive`: Select ordinary conversation with both memory tools and existing-memory projection.
 - `/state-flow-off`: Remove both memory tools and all State Flow model context, without deleting memory.
 - `/state-flow-status`: Inspect effective state, retained history and known recovery issues without scanning sources or changing state.
 
-New sessions default to **Off**; select Passive for ordinary conversation with memory tools, or Active for state-driven episodes. Passive projects state only after a validated memory view is available. Off removes State Flow's model-facing tools and context without deleting memory. Mode changes affect only this session; the global default applies only to new sessions. See [mode semantics](docs/usage.md#active-passive-and-configured-off), [configuration](docs/usage.md#configuration) and [status and controls](docs/usage.md#status-and-controls).
+New sessions default to **Off**. Choose Passive for ordinary conversation with memory tools, or Active for state-driven episodes. A mode change affects only the current session; the global default applies only to new sessions. See [mode semantics](docs/usage.md#active-passive-and-configured-off), [configuration](docs/usage.md#configuration) and [status and controls](docs/usage.md#status-and-controls).
 
 ### Active, passive, off
 
-- `Active`: Memory tools are available; the agent consolidates necessary final state changes before completing an iteration. Subsequent iterations use accepted state and new input rather than completed prior reasoning.
-- `Passive`: Both memory tools and existing-state projection remain available. Patching is on demand, and ordinary conversation context continues without State Flow's active iteration reset.
-- `Off`: Neither memory tool nor State Flow context—including a frozen passive handoff—is exposed to the model. Startup/reload/tree attachment does not read or restore memory; selecting Off cancels pending memory waits and records only native policy/bookmarks. Explicit Passive/Active acquires memory later. Stored memory and Pi's native trace remain intact.
+- `Active`: Memory tools are available, and the agent consolidates necessary final state changes before completing an iteration. Later iterations use accepted state and new input rather than completed prior reasoning.
+- `Passive`: Both memory tools are available, and existing state is projected once a validated memory view is available. The agent patches on demand, and ordinary conversation context continues without State Flow's active iteration reset.
+- `Off`: The model sees neither memory tool nor any State Flow context, including a frozen passive handoff.
+  - Startup, reload and tree attachment do not read or restore memory.
+  - Selecting Off cancels pending memory waits and records only native policy/bookmarks.
+  - Choosing Passive or Active later acquires memory.
+  - Stored memory and Pi's native trace stay intact.
 
-Modes select agent behavior, not a different disk persistence or fork-copy mechanism. Final consolidation does not require an empty ceremonial patch, and context projection does not delete native history. See [mode semantics and bootstrap terminology](docs/usage.md#active-passive-and-configured-off).
+Modes select agent behavior; they do not change disk persistence or fork copying. Final consolidation needs no empty ceremonial patch, and context projection does not delete native history. See [mode semantics and bootstrap terminology](docs/usage.md#active-passive-and-configured-off).
 
 ## State model
 
@@ -77,30 +100,51 @@ 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. More-specific values override lower-scope values, while object fields merge. Removing a local value can reveal an inherited value again.
+They 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 an individual scope when ownership matters. `effective` is a computed view, not a fourth storage scope. Scope precedence does not elevate memory into system-level instructions.
+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.
 
 ### Semantic planes
 
 Runtime views provide these documented planes:
 
-- `intents`: Active commitments to future action.
-- `contract`: Requirements, decisions, constraints and interface commitments.
-- `working`: Observations, results, uncertainties and current continuation.
+- `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.
 - `artifacts`: Source-addressed descriptions and compiled knowledge.
-- `response`: The exact latest accepted answer, including an empty string, captured by the runtime only in Session. Global/CWD receive no newly accepted answers; stored scopes may omit response entirely. Effective uses the highest-priority nonempty value.
-- `lazy`: Supporting memory available through explicit reads, with its body omitted from baseline model context.
+- `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.
+- `lazy`: Supporting memory available through explicit reads; its body is omitted from baseline model context.
+
+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.
+- 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.
 
-Stored checkpoints and patches may omit any documented plane, including `intents`, `lazy` or `response`. Current and historical views assemble only known fields actually present in the selected scopes, without filling absent fields. Empty `response` is treated as absent. Checkpoint and patch readers ignore unknown top-level fields; writers emit only known fields. Nested data within known planes is unrestricted. Reading or starting never rewrites data just to normalize it; missing fields are not a storage-format error.
+Revisions:
 
-These planes organize ordinary JSON rather than imposing a project-specific schema. The model updates the semantic planes except `response`, which is runtime-owned. Global and CWD revisions are shared by their canonical stores, Session has its own revision, and Effective has no scalar owner: its identity is the `g#c#s#` vector. One atomic patch advances each materially changed scope once. Memory remains fallible: storing an observation does not make it current or correct.
+- 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.
+- One atomic patch advances each materially changed scope once.
 
-Registered Pi Skills may be compiled into source-addressed artifacts when durable guidance is useful. Pi's resource provenance determines ownership: user Skills map to global, project Skills to CWD and temporary Skills to session. A matching source hash needs no update; an uncompiled read remains ordinary volatile context and does not block unrelated patches.
+Memory remains fallible: storing an observation does not make it current or correct.
+
+Registered Pi Skills may be compiled into source-addressed artifacts when durable guidance is useful. Pi's resource provenance decides the owner: user Skills map to global, project Skills to CWD and temporary Skills to session. A matching source hash needs no update. An uncompiled read stays ordinary volatile context and does not block unrelated patches.
 
 ## Incremental updates and history
 
-`patch_state` updates one or more named scopes atomically. It waits cancelably for the store lock, then applies authored Global/CWD patches to current canonical values, preserving other writers' untouched fields. Overlapping assignments follow successful acceptance order; correct repeats succeed without new semantic revisions. Session remains private. Object patches merge recursively, and `null` deletes an object key rather than becoming stored data.
+`patch_state` updates one or more named scopes atomically:
+
+- 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.
+- Session remains private.
+- Object patches merge recursively, and `null` deletes an object key instead of being stored.
 
 ```json
 {
@@ -114,7 +158,7 @@ Registered Pi Skills may be compiled into source-addressed artifacts when durabl
 }
 ```
 
-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 additional State Flow reasoning loop.
+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:
 
@@ -127,29 +171,67 @@ During an active episode, a material patch is an inference barrier: sibling tool
 - `cwd.patches[0]`: The latest retained CWD semantic patch.
 - `effective.lazy.memory[0..3]`: A bounded slice of a stored collection.
 
-Historical materializations and scope patch histories use the configurable **`historyLimit`**, from **0 to 100**, with a default of **7**. Materialized offsets refer to accepted semantic transitions, not user messages or an independent counter for each scope. Requested history must still exist in the active lineage; increasing the limit cannot recreate discarded history. Older patches fold into the checkpoint without removing current values.
+How much history is kept:
+
+- Historical materializations and scope patch histories use the configurable **`historyLimit`**, from **0 to 100**, default **7**.
+- Offsets count accepted semantic transitions, not user messages or a separate counter per scope.
+- Requested history must still exist in the active lineage; raising the limit cannot recreate discarded history.
+- Older patches fold into the checkpoint without removing current values.
 
-Array ranges, structural `keys` reads and path-intersected `patch` projections support progressive access without loading whole memory collections. See [progressive memory](docs/lazy-state.md) and [tool contracts](docs/architecture.md#model-tools).
+Array ranges, structural `keys` reads and path-intersected `patch` projections let the agent explore memory without loading whole collections. See [progressive memory](docs/lazy-state.md) and [tool contracts](docs/architecture.md#model-tools).
 
 ## Persistence, backups and continuity
 
-The default store is `~/.pi/agent/state-flow/`, independent of registered source files. Canonical `checkpoint.json`, `patches.jsonl` and `meta.json` files hold each scope's state, retained changes and metadata; session configuration and runtime identity are stored separately.
+The default store is `~/.pi/agent/state-flow/`, independent of registered source files. Each scope keeps its state, retained changes and metadata in canonical `checkpoint.json`, `patches.jsonl` and `meta.json` files. Session configuration and runtime identity are stored separately.
+
+**Persistence is optimistic across abrupt shutdown.**
+
+- Short publication exclusion keeps independent shared fields from cooperating writers; on overlap, the last accepted write wins.
+- Per-file atomic replacement does not guarantee power-loss survival or crash-atomic recovery.
+- This is an [accepted limitation](docs/filesystem-recovery.md#power-loss-durability), not a release gate; no additional recovery journal or storage format is planned.
+
+**Git backups are optional.** When the store is a configured Git repository:
+
+- Accepted active turns may create versioned backups of State Flow-owned files.
+- If the store is busy and Pi provides no cancellable settlement wait, the backup is explicitly deferred. A later accepted turn retries, without changing memory or blocking native Abort.
+- If the attached branch has an explicitly configured remote, State Flow then pushes the exact current backup commit there, asynchronously and without force.
+- Within one Pi process, at most one push per repository runs at a time. Overlapping attempts are skipped, and a later accepted turn pushes the latest backup.
+- Off cancels pending captures and its admitted push, without rolling back accepted state or backup commits; canceled work emits no late memory warnings.
+- Shutdown cancels owned pushes and waits for that repository's active push to close or time out.
+- Commit failures warn locally. Repeated push failures produce one concise warning until a push succeeds, with redacted Git detail kept in the local diagnostic log. Neither failure rejects or rolls back accepted memory.
+- Backup needs a Git commit identity; accepting and persisting state does not.
+- Git history can be inspected separately, but it is not the authority for `read_state` or for automatic restoration of expired semantic boundaries.
+
+**Resume, tree navigation and forks:**
+
+- Memory-enabled resume and tree navigation restore the selected retained session boundary over the current shared global/CWD memory. Off defers this acquisition.
+- A new session gets its own session layer.
+- Supported native forks copy the selected session state into a new owner without changing the parent's private data.
+- Expired, incomplete or contradictory boundaries never silently substitute newer private state during restoration.
+- Explicit Start is a mode change, not historical restoration. It activates the validated **current** memory of that same session, including private state, even after expired active/passive, interrupted or pre-runtime selections. Available aligned history and revisions survive; unavailable history is not recreated.
+- Malformed storage, unsafe fork copying and concurrent writes remain fenced.
+
+See [fork support](docs/usage.md#fork-support-and-limits) and [storage recovery](docs/usage.md#storage-and-recovery).
 
-**Persistence is optimistic across abrupt shutdown.** Short publication exclusion preserves independent shared fields between cooperating writers; the last accepted write wins on overlap. Per-file atomic replacement does not guarantee power-loss survival or crash-atomic recovery. That [accepted limitation](docs/filesystem-recovery.md#power-loss-durability) is not a release gate; no additional recovery journal or storage format is planned.
+**For SDK and launcher integrations:**
 
-**Git backups are optional.** When the store is a configured Git repository, accepted active turns may create versioned backups of State Flow-owned files. A busy store explicitly defers backup when Pi provides no cancellable settlement wait (including SDK 0.87); a later accepted turn retries without changing memory or blocking native Abort. If the attached branch has an explicitly configured remote, State Flow then pushes the exact current backup commit there asynchronously and without force. Within one Pi process, only one push per repository can run at a time; overlapping attempts are skipped and a later accepted turn pushes the latest backup. Off cancels pending captures and its admitted push without rolling back accepted state or backup commits; canceled work emits no late memory warnings. Shutdown cancels owned pushes and waits for that repository's active push to close or time out. Commit failures warn locally; repeated push failures produce one concise warning until a successful push, with redacted Git detail kept in the local diagnostic log. Neither failure rejects or rolls back accepted memory. Backup needs a Git commit identity, but accepting and persisting state does not. Git history can be inspected separately, but it is not the authority for `read_state` or automatic restoration of expired semantic boundaries.
+- [Advisory continuation APIs](docs/architecture.md#session-continuation) inspect provenance and build candidates asynchronously with host cancellation. They neither open native sessions nor install automatic resume.
+- Run preparation and missing-artifact maintenance wait cancelably before inference; embeddings can also use the [transaction APIs](docs/architecture.md#asynchronous-storage-transaction).
 
-Memory-enabled resume and tree navigation restore the selected retained session boundary over current shared global/CWD memory; Off defers this acquisition. A new session gets its own session layer. Supported native forks copy selected session state into a new owner without changing the parent's private data. Expired, incomplete or contradictory boundaries never silently substitute newer private state during restoration. Explicit Start is a mode change, not historical restoration: it activates validated **current** memory of that same session, including private state, even after expired active/passive, interrupted or pre-runtime selections. Available aligned history and revisions survive; unavailable history is not recreated. Malformed storage, unsafe fork copying and concurrent writes remain fenced. See [fork support](docs/usage.md#fork-support-and-limits) and [storage recovery](docs/usage.md#storage-and-recovery).
+How mode changes interact with storage:
 
-SDK/launcher integrations can use [advisory continuation APIs](docs/architecture.md#session-continuation). Provenance inspection and candidate building are now asynchronous and accept host cancellation; they neither open native sessions nor install automatic resume. Run preparation and missing-artifact maintenance now wait cancelably before inference; embeddings can also use the [transaction APIs](docs/architecture.md#asynchronous-storage-transaction). Selecting Passive switches local policy/context immediately and awaits runtime-only persistence. Off instead cancels owned memory waits and saves only native mode/continuation/fork bookkeeping, without validating or rewriting canonical storage. Explicit Off inspection may read current stored values through a disposable validated reader; it does not activate memory, install cache or change the selected historical/fork boundary. Missing private authority remains unavailable. Active waits for coherent capture/acceptance; another mode or selection can withdraw its wait. Passive retains independently owned restoration/fork work; Off cancels it and defers later acquisition. Failed Passive persistence preserves local policy and fences publication until accepted activation.
+- Selecting Passive switches local policy/context immediately and awaits runtime-only persistence. Passive keeps independently owned restoration/fork work. If its persistence fails, local policy stays and publication is fenced until an accepted activation.
+- Off cancels owned memory waits and saves only native mode/continuation/fork bookkeeping, without validating or rewriting canonical storage. It also cancels restoration/fork work and defers later acquisition.
+- Explicit Off inspection may read current stored values through a disposable validated reader. It does not activate memory, install cache or change the selected historical/fork boundary. Missing private authority stays unavailable.
+- Active waits for a coherent capture and acceptance; another mode or selection can withdraw its wait.
 
-The canonical storage-format boundary introduced in 0.17 still applies: current versions accept only the canonical store contract and provide no in-place predecessor converter. Preserve existing data and check the [format boundary](docs/usage.md#moving-a-store-and-the-017-format-boundary) before changing versions or moving a store.
+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.
 
 ## Operational boundaries
 
-State Flow adds memory, not another agent controller. It does not introduce background reasoning, a scheduler, automatic reference hydration or rollback of external tool effects. State and the current trajectory are not size-capped; performance depends on how much useful information the agent retains.
+State Flow adds memory, not another agent controller. It does not add background reasoning, a scheduler, automatic reference hydration or rollback of external tool effects. State and the current trajectory are not size-capped; performance depends on how much useful information the agent retains.
 
-The packaged `state-flow-guide` Skill covers concrete operations and recovery. `state-flow-memory` supports explicitly requested curation, for example: **“Review and clean State Flow state”** Normal handoffs reconcile touched memory; dedicated cleanup is not an automatic audit after each task.
+The packaged `state-flow-guide` Skill covers concrete operations and recovery. `state-flow-memory` supports explicitly requested curation, for example: **“Review and clean State Flow state”** Normal handoffs reconcile the memory they touch; dedicated cleanup is not an automatic audit after each task.
 
 Treat state, diagnostic logs and backups as private data. Revalidate consequential observations before acting, and verify a transfer's destination before deleting its source. Removing a value from current state does not erase older histories or remote copies.
 

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

@@ -1,4 +1,5 @@
-import { type ArtifactInvalidationReason, type ArtifactInvalidationRequest, type ArtifactSourceIdentity } from "./artifact.ts";
+import { type ArtifactInvalidationReason, type ArtifactInvalidationRequest, type ArtifactSourceIdentity, type ArtifactProvenanceRegistry } from "./artifact.ts";
+import type { AtomicScopePatches, ScopedSemanticStates, ScopedStates, StateScope } from "./state.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";
@@ -37,3 +38,25 @@ export declare class ArtifactReadTracker {
  * stay on materialized state; only a concrete source need permits rereading.
  */
 export declare function decideArtifactAcquisition(source: ArtifactSourceIdentity, metadata: unknown, compiler: string, options: ArtifactAcquisitionOptions): ArtifactAcquisitionDecision;
+export declare const SOURCE_CHANGED_HINT = "Source changed since this artifact was compiled. Read and recompile it before relying on it.";
+/**
+ * One selected branch's ordinary-artifact acquisition plan: runtime-observed
+ * invalidations, their model hints and the read tracker correlated to them.
+ * The tracker's candidates always equal the current invalidation plan.
+ */
+export declare class ArtifactAcquisitionState {
+    #private;
+    readonly reads: ArtifactReadTracker;
+    get invalidations(): readonly ArtifactInvalidationRequest[];
+    get hints(): Record<string, string>;
+    /** Drop the invalidation plan; hints remain until the next refresh. */
+    clearInvalidations(): void;
+    /** 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;
+    /** Accepted compilations leave the plan; correlated read evidence is single-use. */
+    acceptAcquired(paths?: ReadonlySet<string>): void;
+}
+/** Deletion patches for registered artifacts whose exact source is observed missing, in every owning scope. */
+export declare function missingArtifactRemovals(states: ScopedSemanticStates): AtomicScopePatches;

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

@@ -1,4 +1,4 @@
-import { classifyArtifactCompilationNeed, inspectRegisteredArtifactPaths, sameArtifactSourceFingerprint, } from "./artifact.js";
+import { classifyArtifactCompilationNeed, inspectRegisteredArtifactPaths, sameArtifactSourceFingerprint, ORDINARY_ARTIFACT_COMPILER, } from "./artifact.js";
 import { isObject } from "./json.js";
 function readPath(toolName, args) {
     return toolName === "read" && isObject(args) && typeof args.path === "string"
@@ -89,3 +89,82 @@ export function decideArtifactAcquisition(source, metadata, compiler, options) {
             return { kind: "read-source", reason: "maintenance" };
     }
 }
+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.
+ * The tracker's candidates always equal the current invalidation plan.
+ */
+export class ArtifactAcquisitionState {
+    reads = new ArtifactReadTracker();
+    #invalidations = [];
+    #hints = {};
+    get invalidations() { return this.#invalidations; }
+    get hints() { return this.#hints; }
+    /** Drop the invalidation plan; hints remain until the next refresh. */
+    clearInvalidations() { this.#setInvalidations([]); }
+    /** Forget plan and hints when no memory view is selected. */
+    reset() {
+        this.#hints = {};
+        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);
+        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 });
+            }
+        }
+        this.#hints = hints;
+        this.#setInvalidations([...invalidations.values()].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())) {
+        this.#setInvalidations(this.#invalidations.filter(({ path }) => !paths.has(path)));
+        this.reads.clear();
+    }
+    #setInvalidations(invalidations) {
+        this.#invalidations = invalidations;
+        this.reads.setCandidates(invalidations);
+    }
+}
+/** Deletion patches for registered artifacts whose exact source is observed missing, in every owning scope. */
+export function missingArtifactRemovals(states) {
+    const owners = new Map();
+    for (const scope of SCOPES)
+        for (const path of Object.keys(states[scope].artifacts ?? {})) {
+            owners.set(path, [...owners.get(path) ?? [], scope]);
+        }
+    const removals = {};
+    for (const observation of inspectRegisteredArtifactPaths(owners.keys())) {
+        if (observation.kind !== "missing")
+            continue;
+        for (const scope of owners.get(observation.path) ?? []) {
+            const artifacts = (removals[scope]?.artifacts ?? {});
+            removals[scope] = { ...(removals[scope] ?? {}), artifacts: { ...artifacts, [observation.path]: null } };
+        }
+    }
+    return removals;
+}

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

@@ -47,4 +47,21 @@ export declare function stateFlowCompactionResult(plan: StateFlowCompactionPlan,
 }): CompactionResult<StateFlowCompactionDetails> | {
     cancel: true;
 } | undefined;
+type CompactionEvent = Parameters<typeof stateFlowCompactionResult>[2];
+/** Completed-history compaction request state owned by one extension instance. */
+export declare class StateFlowCompactionRequests {
+    #private;
+    get inFlight(): boolean;
+    get stopped(): boolean;
+    /** Permanently refuse owned requests (shutdown). */
+    stop(): void;
+    /** Drop the run-local plan; a stale callback can no longer clear a newer one. */
+    clear(): void;
+    /** Install a plan and return its unique per-request marker. */
+    begin(plan: StateFlowCompactionPlan): string;
+    /** Native completion clears only its own request. */
+    finish(marker: string): void;
+    /** Answer session_before_compact: foreign requests pass, stale or unpermitted owned ones cancel. */
+    resolve(event: CompactionEvent, permitted: boolean): ReturnType<typeof stateFlowCompactionResult>;
+}
 export {};

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

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { estimateTokens } from "@earendil-works/pi-coding-agent";
 export const STATE_FLOW_COMPACTION_SUMMARY = "State Flow accepted the completed work before this boundary. Current memory is restored from its retained semantic boundary and projected separately; use the retained native entries for subsequent work.";
 /** A modest margin above Pi's default 20k retained suffix absorbs estimation drift. */
@@ -65,3 +66,42 @@ export function stateFlowCompactionResult(plan, marker, event) {
         details: structuredClone(plan.details),
     };
 }
+const STATE_FLOW_COMPACTION_MARKER_PREFIX = "state-flow-boundary:";
+/** Completed-history compaction request state owned by one extension instance. */
+export class StateFlowCompactionRequests {
+    #plan;
+    #marker;
+    #inFlight = false;
+    #stopped = false;
+    #prefix = `${STATE_FLOW_COMPACTION_MARKER_PREFIX}${randomUUID()}:`;
+    get inFlight() { return this.#inFlight; }
+    get stopped() { return this.#stopped; }
+    /** Permanently refuse owned requests (shutdown). */
+    stop() { this.#stopped = true; }
+    /** Drop the run-local plan; a stale callback can no longer clear a newer one. */
+    clear() {
+        this.#plan = undefined;
+        this.#inFlight = false;
+    }
+    /** Install a plan and return its unique per-request marker. */
+    begin(plan) {
+        this.#plan = plan;
+        const marker = this.#marker = `${this.#prefix}${randomUUID()}`;
+        this.#inFlight = true;
+        return marker;
+    }
+    /** Native completion clears only its own request. */
+    finish(marker) {
+        if (this.#marker === marker)
+            this.clear();
+    }
+    /** Answer session_before_compact: foreign requests pass, stale or unpermitted owned ones cancel. */
+    resolve(event, permitted) {
+        if (event.reason !== "manual" || !event.customInstructions?.startsWith(STATE_FLOW_COMPACTION_MARKER_PREFIX))
+            return undefined;
+        const marker = this.#marker;
+        if (!permitted || this.#stopped || !this.#plan || !marker || event.customInstructions !== marker)
+            return { cancel: true };
+        return stateFlowCompactionResult(this.#plan, marker, event);
+    }
+}