@llblab/pi-kit 0.15.0 → 0.17.0

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

@@ -333,3 +333,105 @@ export async function runPublicationWorker(state, push, current, isAncestor) {
         };
     }
 }
+/** Own durable queue coalescing, worker leases, retries, generation fencing, and bounded shutdown. */
+export class PublicationWorkerController {
+    active = new Map();
+    ports;
+    stopped = false;
+    shutdownPromise;
+    constructor(ports) {
+        this.ports = ports;
+    }
+    enqueue(target) {
+        const destination = this.ports.resolveDestination();
+        if (!destination)
+            return;
+        const path = publicationQueuePath(destination);
+        const previous = loadPublicationQueue(path);
+        const next = previous
+            ? coalescePublicationTarget(previous, destination, target, this.ports.isAncestor, {
+                onDivergedLineage: (dropped) => this.ports.onDiverged(dropped, target),
+            })
+            : createPublicationQueue(destination, target);
+        savePublicationQueue(path, next, previous);
+    }
+    launch() {
+        if (this.stopped)
+            return;
+        let destination;
+        try {
+            destination = this.ports.resolveDestination();
+        }
+        catch (error) {
+            if (error instanceof Error && /ENOENT/.test(error.message))
+                return;
+            throw error;
+        }
+        if (!destination)
+            return;
+        const path = publicationQueuePath(destination);
+        if (this.active.has(path))
+            return;
+        let queued;
+        let lease;
+        try {
+            queued = loadPublicationQueue(path);
+            if (!queued)
+                return;
+            lease = acquirePublicationWorkerLease(path);
+        }
+        catch {
+            return;
+        }
+        if (!lease)
+            return;
+        const controller = new AbortController();
+        const done = runPublicationWorker(queued, ({ target }) => this.ports.push(destination, target, controller.signal), () => loadPublicationQueue(path) ?? queued, this.ports.isAncestor).then((result) => {
+            if (this.stopped)
+                return;
+            const current = loadPublicationQueue(path);
+            if (!current)
+                return;
+            if (result.next === undefined) {
+                if (current.target === result.attempted.target)
+                    removePublicationQueue(path, current);
+                return;
+            }
+            if (current.target === result.attempted.target || result.next.target === current.target)
+                savePublicationQueue(path, result.next, current);
+        }).catch(() => {
+            // Queue/CAS truth remains durable; status and a later activation expose retry.
+        }).finally(() => {
+            this.active.delete(path);
+            try {
+                lease.release();
+                if (!this.stopped && loadPublicationQueue(path)?.status === "pending")
+                    this.launch();
+            }
+            catch {
+                // Failed lease cleanup or malformed persistence stays inert until retry or repair.
+            }
+        });
+        this.active.set(path, { controller, done });
+    }
+    shutdown(waitMs) {
+        this.stopped = true;
+        return this.shutdownPromise ??= (async () => {
+            const workers = [...this.active.values()];
+            for (const { controller } of workers)
+                controller.abort();
+            if (workers.length === 0)
+                return true;
+            let timeout;
+            try {
+                return await Promise.race([
+                    Promise.all(workers.map(({ done }) => done)).then(() => true),
+                    new Promise((resolve) => { timeout = setTimeout(() => resolve(false), waitMs); }),
+                ]);
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        })();
+    }
+}

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

@@ -1,3 +1,4 @@
+import { type JsonValue } from "./json.ts";
 import { type MaterializedState, type ScopePatch, type StateScope } from "./state.ts";
 import { type TemporalState, type TransitionBoundary } from "./temporal.ts";
 export type StateReadQuery = {
@@ -22,6 +23,47 @@ export type StateReadResult = {
         response?: string;
     };
 };
-/** Resolve the compact model-facing path grammar without treating aliases as literal JSON containers. */
+export type StateReadProjection = "value" | "keys" | "patch";
+type StateReadMeta = {
+    type: "object";
+    size: number;
+} | {
+    type: "array";
+    length: number;
+} | {
+    type: "string";
+    length: number;
+} | {
+    type: "number" | "boolean";
+};
+type StateReadKeys = Record<string, string> | [];
+export interface StateReadHint {
+    type: "dangling-reference";
+    message: string;
+    paths: string[];
+}
+export type ProjectedStateRead = {
+    value: JsonValue | JsonValue[];
+    hint?: StateReadHint[];
+} | {
+    meta: StateReadMeta | StateReadMeta[];
+    keys: StateReadKeys | StateReadKeys[];
+} | {
+    patch: JsonValue | JsonValue[];
+};
+export interface StateReferenceSource {
+    scope: StateScope;
+    path: string;
+    form: "structured" | "text";
+}
+/** Resolve a projection root without repeating the tool name in every path. */
 export declare function parseStateReadPath(path: string): StateReadQuery;
 export declare function readStatePath(view: TemporalState, path: string): StateReadResult;
+/** Reactively locate exact durable sources for one failed state-path resolution. */
+export declare function findStateReferenceSources(view: TemporalState, path: string): {
+    sources: StateReferenceSource[];
+    truncated: boolean;
+};
+/** Project exact current/historical state paths without exposing temporal metadata. */
+export declare function readProjectedState(view: TemporalState, paths: readonly string[], projection?: StateReadProjection): ProjectedStateRead;
+export {};

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

@@ -1,24 +1,26 @@
+import { isObject, sameJson } from "./json.js";
 import { projectStateForModel } from "./state.js";
 import { readTemporalState } from "./temporal.js";
-const PATH_PATTERN = /^state(?:\[(\d+)\])?(?:\.(global|cwd|session)(?:\[(\d+)\])?(?:\.patches(?:\[(\d+)\])?)?)?$/;
-/** Resolve the compact model-facing path grammar without treating aliases as literal JSON containers. */
+const MAX_REFERENCE_SOURCES = 3;
+const MAX_REFERENCE_SCAN_NODES = 10_000;
+const PATH_PATTERN = /^(effective|global|cwd|session)(?:\[(\d+)\])?(?:\.patches(?:\[(\d+)\])?)?$/;
+/** Resolve a projection root without repeating the tool name in every path. */
 export function parseStateReadPath(path) {
     const match = PATH_PATTERN.exec(path);
     if (!match)
         throw new Error("Invalid State Flow read path");
-    const [, effectiveOffset, scope, scopeOffset, patchOffset] = match;
-    if (effectiveOffset !== undefined && scope !== undefined)
-        throw new Error("State Flow read path cannot index both state and a scope");
-    if (path.includes(".patches") && scopeOffset !== undefined)
+    const [, root, rootOffset, patchOffset] = match;
+    if (path.includes(".patches") && rootOffset !== undefined)
         throw new Error("Index patches after .patches, not after the scope");
-    const rawOffset = patchOffset ?? scopeOffset ?? effectiveOffset ?? "0";
-    const offset = Number(rawOffset);
+    if (path.includes(".patches") && root === "effective")
+        throw new Error("Patch history requires an explicit scope");
+    const offset = Number(patchOffset ?? rootOffset ?? "0");
     if (!Number.isSafeInteger(offset) || offset < 0 || offset > 7)
         throw new Error("State Flow read path index must be an integer from 0 to 7");
     if (patchOffset !== undefined || path.endsWith(".patches")) {
-        return { kind: "patch", path, offset, scope: scope };
+        return { kind: "patch", path, offset, scope: root };
     }
-    return { kind: "state", path, offset, ...(scope === undefined ? {} : { scope: scope }) };
+    return { kind: "state", path, offset, ...(root === "effective" ? {} : { scope: root }) };
 }
 export function readStatePath(view, path) {
     const query = parseStateReadPath(path);
@@ -33,3 +35,259 @@ export function readStatePath(view, path) {
         throw new Error(`Requested ${query.scope} patch predates retained hot history`);
     return { path, boundary: structuredClone(record.transition), patch: structuredClone(record.patch) };
 }
+function parseValuePath(path) {
+    const explicitRoot = /^(?:effective|global|cwd|session)(?:\[\d+\])?(?=\.|$)/.exec(path)?.[0];
+    const implicitRoot = /^(?:artifacts|contract|working|intents|response|lazy)(?=\.|\[|$)/.exec(path)?.[0];
+    if (explicitRoot === undefined && implicitRoot === undefined) {
+        throw new Error("State Flow read path requires a semantic path or an effective, global, cwd, or session root");
+    }
+    const root = explicitRoot ?? "effective";
+    const selectors = implicitRoot === undefined ? [] : [{ kind: "key", key: implicitRoot }];
+    let rest = path.slice((explicitRoot ?? implicitRoot).length);
+    while (rest.length > 0) {
+        const key = /^\.([A-Za-z_$][A-Za-z0-9_$-]*)/.exec(rest);
+        if (key) {
+            selectors.push({ kind: "key", key: key[1] });
+            rest = rest.slice(key[0].length);
+            continue;
+        }
+        const range = /^\[(\d+)(?::|\.\.)(\d+)\]/.exec(rest);
+        if (range) {
+            selectors.push({ kind: "range", start: Number(range[1]), end: Number(range[2]) });
+            rest = rest.slice(range[0].length);
+            continue;
+        }
+        const index = /^\[(\d+)\]/.exec(rest);
+        if (index) {
+            selectors.push({ kind: "index", index: Number(index[1]) });
+            rest = rest.slice(index[0].length);
+            continue;
+        }
+        throw new Error("Invalid State Flow read path selector");
+    }
+    return { root, selectors };
+}
+function selectValue(root, selectors, path) {
+    let value = root;
+    for (const selector of selectors) {
+        if (selector.kind === "key") {
+            if (!isObject(value) || !Object.hasOwn(value, selector.key))
+                throw new Error(`State Flow read path does not exist: ${path}`);
+            value = value[selector.key];
+            continue;
+        }
+        if (!Array.isArray(value))
+            throw new Error(`State Flow array selector requires an array: ${path}`);
+        if (selector.kind === "index") {
+            if (selector.index >= value.length)
+                throw new Error(`Index ${selector.index} is outside ${path} with length ${value.length}`);
+            value = value[selector.index];
+            continue;
+        }
+        if (selector.start > selector.end || selector.end > value.length)
+            throw new Error(`Range [${selector.start}:${selector.end}] is outside ${path} with length ${value.length}`);
+        value = value.slice(selector.start, selector.end);
+    }
+    return structuredClone(value);
+}
+function valueKind(value) {
+    if (Array.isArray(value))
+        return "array";
+    if (isObject(value))
+        return "object";
+    return typeof value;
+}
+function referenceCandidates(path) {
+    if (/^(?:artifacts|contract|working|intents|response|lazy)(?=\.|\[|$)/.test(path))
+        return [path, `effective.${path}`];
+    return [path];
+}
+function inlineReferencePattern(path) {
+    const escaped = path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?:^|[^A-Za-z0-9_$.[\\]:-])\\$${escaped}(?=$|[^A-Za-z0-9_$.[\\]:-])`, "u");
+}
+/** Reactively locate exact durable sources for one failed state-path resolution. */
+export function findStateReferenceSources(view, path) {
+    const candidates = referenceCandidates(path);
+    const patterns = candidates.map(inlineReferencePattern);
+    const sources = [];
+    let visited = 0;
+    let truncated = false;
+    const visit = (value, owner, ownerPath) => {
+        if (sources.length >= MAX_REFERENCE_SOURCES || visited >= MAX_REFERENCE_SCAN_NODES) {
+            truncated = true;
+            return;
+        }
+        visited += 1;
+        if (typeof value === "string") {
+            if (patterns.some((pattern) => pattern.test(value)))
+                sources.push({ scope: owner, path: ownerPath, form: "text" });
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (let index = 0; index < value.length && !truncated; index++)
+                visit(value[index], owner, `${ownerPath}[${index}]`);
+            return;
+        }
+        if (!isObject(value))
+            return;
+        if (typeof value.$ref === "string" && candidates.includes(value.$ref)) {
+            sources.push({ scope: owner, path: ownerPath, form: "structured" });
+            if (sources.length >= MAX_REFERENCE_SOURCES) {
+                truncated = true;
+                return;
+            }
+        }
+        for (const key of Object.keys(value).sort()) {
+            if (key === "response" || (key === "$ref" && typeof value[key] === "string"))
+                continue;
+            visit(value[key], owner, ownerPath ? `${ownerPath}.${key}` : `${owner}.${key}`);
+            if (truncated)
+                return;
+        }
+    };
+    for (const scope of ["global", "cwd", "session"]) {
+        const state = readTemporalState(view, 0, scope);
+        for (const plane of ["artifacts", "contract", "working", "intents", "lazy"]) {
+            const value = state[plane];
+            if (value !== undefined)
+                visit(value, scope, `${scope}.${plane}`);
+            if (truncated)
+                break;
+        }
+        if (truncated)
+            break;
+    }
+    sources.sort((left, right) => (left.form === right.form ? left.path.localeCompare(right.path) : left.form === "structured" ? -1 : 1));
+    return { sources, truncated };
+}
+function missingReferenceHint(view, path) {
+    const { sources, truncated } = findStateReferenceSources(view, path);
+    if (sources.length === 0)
+        return undefined;
+    return [{
+            type: "dangling-reference",
+            message: `Reconcile the verified current values that reference this path${truncated ? "; additional sources may exist beyond the bounded scan" : ""}.`,
+            paths: sources.map(({ path: sourcePath }) => sourcePath),
+        }];
+}
+function projectValue(value, projection) {
+    if (projection === "value")
+        return { value: structuredClone(value) };
+    if (isObject(value)) {
+        return {
+            meta: { type: "object", size: Object.keys(value).length },
+            keys: Object.fromEntries(Object.entries(value).map(([key, child]) => [key, valueKind(child)])),
+        };
+    }
+    if (Array.isArray(value))
+        return { meta: { type: "array", length: value.length }, keys: [] };
+    if (typeof value === "string")
+        return { meta: { type: "string", length: value.length }, keys: [] };
+    if (value === null)
+        throw new Error("State Flow semantic state cannot contain null");
+    return { meta: { type: typeof value }, keys: [] };
+}
+function patchAtPath(view, root, selectors, path) {
+    const rootQuery = parseStateReadPath(root);
+    if (rootQuery.kind !== "state")
+        throw new Error("Patch projection requires a state path");
+    const boundary = view.lineage.at(-1 - rootQuery.offset);
+    if (!boundary)
+        throw new Error("Requested history predates the proven temporal origin");
+    let patch = {};
+    if (rootQuery.scope) {
+        patch = structuredClone(view.scopes[rootQuery.scope].patches.find((record) => record.transition.id === boundary.id)?.patch ?? {});
+    }
+    else {
+        const before = view.lineage.at(-2 - rootQuery.offset);
+        if (before) {
+            const current = readTemporalState(view, rootQuery.offset);
+            const previous = readTemporalState(view, rootQuery.offset + 1);
+            patch = diffObjects(previous, current);
+        }
+    }
+    for (let index = 0; index < selectors.length; index++) {
+        const selector = selectors[index];
+        if (patch === null)
+            return null;
+        if (selector.kind === "key" && isObject(patch) && Object.hasOwn(patch, selector.key)) {
+            patch = patch[selector.key];
+            continue;
+        }
+        if (selector.kind !== "key" && isObject(patch)) {
+            const key = selector.kind === "index" ? `[${selector.index}]` : undefined;
+            if (key && Object.hasOwn(patch, key)) {
+                patch = patch[key];
+                continue;
+            }
+        }
+        if (Array.isArray(patch))
+            return selectValue(patch, selectors.slice(index), path);
+        if (!isObject(patch)) {
+            const result = readStatePath(view, root);
+            if (!("state" in result))
+                throw new Error("Patch projection requires a state path");
+            return selectValue(result.state, selectors, path);
+        }
+        return {};
+    }
+    return structuredClone(patch);
+}
+function diffObjects(previous, current) {
+    if (!isObject(previous) || !isObject(current))
+        return structuredClone(current);
+    const patch = {};
+    for (const key of new Set([...Object.keys(previous), ...Object.keys(current)])) {
+        if (!Object.hasOwn(current, key))
+            patch[key] = null;
+        else if (!Object.hasOwn(previous, key))
+            patch[key] = structuredClone(current[key]);
+        else if (!sameJson(previous[key], current[key]))
+            patch[key] = diffObjects(previous[key], current[key]);
+    }
+    return patch;
+}
+/** Project exact current/historical state paths without exposing temporal metadata. */
+export function readProjectedState(view, paths, projection = "value") {
+    if (paths.length === 0)
+        throw new Error("read_state requires at least one path");
+    if (projection === "patch") {
+        const patches = paths.map((path) => {
+            const { root, selectors } = parseValuePath(path);
+            return patchAtPath(view, root, selectors, path);
+        });
+        return { patch: patches.length === 1 ? patches[0] : patches };
+    }
+    const projected = paths.map((path) => {
+        try {
+            const { root, selectors } = parseValuePath(path);
+            const query = parseStateReadPath(root);
+            if (query.kind !== "state")
+                throw new Error("Value and keys projections require a state path");
+            const readsLazy = selectors[0]?.kind === "key" && selectors[0].key === "lazy";
+            const state = readsLazy
+                ? readTemporalState(view, query.offset, query.scope)
+                : projectStateForModel(readTemporalState(view, query.offset, query.scope));
+            if (readsLazy && !Object.hasOwn(state, "lazy"))
+                state.lazy = {};
+            return projectValue(selectValue(state, selectors, path), projection);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const missing = /does not exist| is outside /.test(message);
+            const hint = missing && projection === "value" && paths.length === 1 ? missingReferenceHint(view, path) : undefined;
+            if (hint)
+                return { value: null, hint };
+            throw new Error(message, error instanceof Error ? { cause: error } : undefined);
+        }
+    });
+    if (projected.length === 1)
+        return projected[0];
+    if (projection === "value")
+        return { value: projected.map((result) => result.value) };
+    return {
+        meta: projected.map((result) => result.meta),
+        keys: projected.map((result) => result.keys),
+    };
+}

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

@@ -97,6 +97,8 @@ export declare class TemporalRuntime {
     get sessionKey(): string;
     /** Runtime-owned artifact freshness evidence for one scope; never model-visible state. */
     artifactProvenance(scope: StateScope): ArtifactProvenanceRegistry;
+    /** Read canonical shared memory without creating, migrating, or publishing storage. */
+    loadPassive(): boolean;
     /** Explicit start owns directory/repository creation; reads never call this. */
     prepare(): void;
     /** Explicit start migrates a predecessor envelope even when passive restore already populated the cache. */

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

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { lstatSync } from "node:fs";
 import { join } from "node:path";
 import { classifyScopeStream, parseScopeProvenance, parseScopeStream, sessionRuntimePaths, temporalScopePaths } from "./durable.js";
-import { parseArtifactProvenanceRegistry, pruneArtifactProvenance } from "./artifact.js";
+import { pruneArtifactProvenance } from "./artifact.js";
 import { adoptFileStateToGit, initializeGitRepository, isLocalGitRepository, captureTemporalGitBase, loadTemporalRevision, migrateLegacyStorageToGit, publishTemporalStateToGit } from "./git.js";
 import { captureTemporalFileBase, detectGitCapability, initializeFileStore, loadTemporalFileRevision, migrateLegacyStorageToFiles, publishTemporalStateToFiles } from "./storage.js";
 import { hashJson, sameJson } from "./json.js";
@@ -95,6 +95,35 @@ export class TemporalRuntime {
     artifactProvenance(scope) {
         return structuredClone(this.provenanceByScope[scope]);
     }
+    /** Read canonical shared memory without creating, migrating, or publishing storage. */
+    loadPassive() {
+        if (!lstatSync(this.root, { throwIfNoEntry: false }))
+            return false;
+        const backend = detectGitCapability() === "git" && lstatSync(join(this.root, ".git"), { throwIfNoEntry: false }) ? "git" : "files";
+        const base = backend === "git"
+            ? captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey)
+            : captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey);
+        const files = new Map(base.files.map((file) => [file.path, file.content]));
+        const shared = Object.fromEntries(SHARED_SCOPES.map((scope) => {
+            const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
+            return [scope, parseScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope, scope === "cwd" ? this.cwd : undefined, files.get(paths.meta))];
+        }));
+        if (!shared.global && !shared.cwd)
+            return false;
+        if (!shared.global || !shared.cwd)
+            throw new Error("Incomplete passive State Flow shared storage");
+        const fresh = createTemporalState({ global: emptyState(), cwd: emptyState(), session: emptyState() }, randomUUID());
+        const basis = backend === "git" ? base.head ?? "unborn" : "files";
+        this.view = adoptTemporalStreams({ global: shared.global, cwd: shared.cwd, session: fresh.scopes.session }, `passive:${basis}:${randomUUID()}`);
+        this.base = base;
+        this.backend = backend;
+        this.provenanceByScope = {
+            global: parseScopeProvenance(files.get(temporalScopePaths(this.cwd, this.sessionId, "global", this.root, this.sessionKey).meta), "State Flow global metadata"),
+            cwd: parseScopeProvenance(files.get(temporalScopePaths(this.cwd, this.sessionId, "cwd", this.root, this.sessionKey).meta), "State Flow CWD metadata"),
+            session: {},
+        };
+        return true;
+    }
     /** Explicit start owns directory/repository creation; reads never call this. */
     prepare() {
         const backend = detectGitCapability();
@@ -309,7 +338,7 @@ export class TemporalRuntime {
         const files = new Map(base.files.map((file) => [file.path, file.content]));
         if (copy) {
             const session = temporalScopePaths(this.cwd, this.sessionId, "session", this.root, this.sessionKey);
-            const owned = [session.checkpoint, session.patches, session.meta, join(session.directory, "config.json"), join(session.directory, "state.json")];
+            const owned = [session.checkpoint, session.patches, session.meta, join(session.directory, "config.json"), join(session.directory, "runtime.json"), join(session.directory, "state.json")];
             const occupied = owned.some((path) => files.get(path) !== undefined);
             const historical = !occupied && backend === "git" && base.head ? loadTemporalRevision(this.cwd, this.sessionId, this.root, base.head, this.sessionKey) : undefined;
             if (occupied || historical?.runtime || historical?.scopes.session) {
@@ -330,7 +359,7 @@ export class TemporalRuntime {
         if (copy && !streams.global)
             throw new Error("State Flow fork requires existing shared scope storage");
         const paths = sessionRuntimePaths(this.cwd, this.sessionId, this.root, this.sessionKey);
-        const existingRuntime = parseSessionRuntime(files.get(paths.config), files.get(paths.meta), this.cwd, this.sessionId);
+        const existingRuntime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), this.cwd, this.sessionId, files.get(paths.meta));
         if (existingRuntime && !newSessionOrigin)
             throw new Error("Existing session runtime requires a branch revision pointer");
         // Explicit start before any branch runtime is a new origin, never inheritance of a later session layer.
@@ -348,7 +377,7 @@ export class TemporalRuntime {
         candidate.provenanceByScope = {
             global: parseScopeProvenance(files.get(globalMeta), globalMeta),
             cwd: parseScopeProvenance(files.get(cwdMeta), cwdMeta),
-            session: copy ? structuredClone(copy.provenance) : streams.session === undefined ? {} : parseArtifactProvenanceRegistry(existingRuntime?.meta.artifacts, "State Flow session artifact provenance"),
+            session: copy ? structuredClone(copy.provenance) : streams.session === undefined ? {} : parseScopeProvenance(files.get(paths.meta), paths.meta),
         };
         if (expectedShared && ["global", "cwd"].some((scope) => !sameJson(candidate.read(0, scope), expectedShared[scope]))) {
             throw new Error("Legacy branch shared scopes diverged from the selected revision; migration cannot overwrite them");
@@ -507,7 +536,7 @@ export class TemporalRuntime {
         if (!scopedWrite) {
             const current = captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey);
             const paths = sessionRuntimePaths(this.cwd, this.sessionId, this.root, this.sessionKey);
-            for (const path of [paths.config, paths.meta]) {
+            for (const path of [paths.config, paths.runtime]) {
                 if (current.files.find((file) => file.path === path)?.identity !== base.files.find((file) => file.path === path)?.identity) {
                     throw new Error("Temporal State Flow runtime changed concurrently");
                 }

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

@@ -7,6 +7,20 @@ interface BranchEntry {
         role?: unknown;
     };
 }
+export interface SessionEntryLookup {
+    getLeafEntry(): (BranchEntry & {
+        id?: string;
+        parentId?: string | null;
+    }) | undefined;
+    getEntry(id: string): (BranchEntry & {
+        id?: string;
+        parentId?: string | null;
+    }) | undefined;
+}
+export interface PassiveStopBoundary {
+    at: number;
+    from?: number;
+}
 export interface SnapshotDiscovery {
     candidates: unknown[];
     errors: string[];
@@ -18,4 +32,7 @@ export declare function latestSnapshotData(branch: readonly BranchEntry[]): unkn
 export declare function hasPriorConversation(branch: readonly BranchEntry[]): boolean;
 /** Auto-start eligibility is session identity/lifecycle, not the presence of CWD materialization. */
 export declare function isNewSession(reason: unknown, branch: readonly BranchEntry[]): boolean;
+export declare function findAssistantToolBatch(session: SessionEntryLookup, toolCallId: string): string[] | undefined;
+export declare function findPassiveStopBoundary(branch: readonly BranchEntry[], sessionId: string, entryType: string): PassiveStopBoundary | undefined;
+export declare function retainsPhysicalSessionProjection(reason: unknown): boolean;
 export {};

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

@@ -42,3 +42,41 @@ export function isNewSession(reason, branch) {
         return true;
     return reason === "startup" && !hasPriorConversation(branch);
 }
+export function findAssistantToolBatch(session, toolCallId) {
+    for (let cursor = session.getLeafEntry(); cursor; cursor = cursor.parentId ? session.getEntry(cursor.parentId) : undefined) {
+        if (cursor.type !== "message" || cursor.message?.role !== "assistant" || !Array.isArray(cursor.message.content))
+            continue;
+        const calls = cursor.message.content.filter((block) => {
+            return typeof block === "object" && block !== null
+                && block.type === "toolCall"
+                && typeof block.id === "string"
+                && typeof block.name === "string";
+        });
+        if (calls.some(({ id }) => id === toolCallId))
+            return calls.map(({ name }) => name);
+    }
+    return undefined;
+}
+export function findPassiveStopBoundary(branch, sessionId, entryType) {
+    for (const entry of [...branch].reverse()) {
+        try {
+            if (entry?.type !== "custom" || entry.customType !== entryType)
+                continue;
+            const { at, from, reset, owner } = entry.data ?? {};
+            if (reset === true && owner === sessionId)
+                return undefined;
+            if (typeof at === "number" && Number.isSafeInteger(at) && at >= 0)
+                return {
+                    at,
+                    ...(typeof from === "number" && Number.isSafeInteger(from) && from >= 0 ? { from } : {}),
+                };
+        }
+        catch {
+            // A hostile unrelated branch entry cannot manufacture or suppress a valid marker.
+        }
+    }
+    return undefined;
+}
+export function retainsPhysicalSessionProjection(reason) {
+    return reason === undefined || reason === "startup" || reason === "reload" || reason === "resume";
+}

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

@@ -1,7 +1,7 @@
 import { type ArtifactProvenanceRegistry } from "./artifact.ts";
 import { type RemotePublicationPolicyDocument } from "./publication.ts";
 import { type JsonObject } from "./json.ts";
-import { type ScopeStream, type TransitionBoundary } from "./temporal.ts";
+import { type TransitionBoundary } from "./temporal.ts";
 /** Missing operational capability is not evidence that a checkpoint target is invalid. */
 export declare class RevisionUnavailableError extends Error {
 }
@@ -57,12 +57,12 @@ export interface SessionRuntime {
     };
 }
 export declare function validateSessionRuntime(value: unknown, cwd: string, sessionId: string): asserts value is SessionRuntime;
-export declare function createSessionRuntime(snapshot: Snapshot, cwd: string, sessionId: string, lineage: readonly TransitionBoundary[], publication?: SessionRuntime["meta"]["publication"], artifacts?: ArtifactProvenanceRegistry): SessionRuntime;
-export declare function serializeSessionRuntime(runtime: SessionRuntime, cwd: string, sessionId: string, stream?: ScopeStream, existingSource?: string): {
+export declare function createSessionRuntime(snapshot: Snapshot, cwd: string, sessionId: string, lineage: readonly TransitionBoundary[], publication?: SessionRuntime["meta"]["publication"], _artifacts?: ArtifactProvenanceRegistry): SessionRuntime;
+export declare function serializeSessionRuntime(runtime: SessionRuntime, cwd: string, sessionId: string): {
     config: string;
-    meta: string;
+    runtime: string;
 };
-export declare function parseSessionRuntime(config: string | undefined, meta: string | undefined, cwd: string, sessionId: string): SessionRuntime | undefined;
+export declare function parseSessionRuntime(config: string | undefined, runtimeSource: string | undefined, cwd: string, sessionId: string, legacyMetaSource?: string): SessionRuntime | undefined;
 export declare function resolveSessionRuntime(runtime: SessionRuntime, revision: string): {
     snapshot: Snapshot;
     lineage: TransitionBoundary[];