@llblab/pi-kit 0.15.0 → 0.16.0

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,31 @@ 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 type ProjectedStateRead = {
+    value: JsonValue | JsonValue[];
+} | {
+    meta: StateReadMeta | StateReadMeta[];
+    keys: StateReadKeys | StateReadKeys[];
+} | {
+    patch: JsonValue | JsonValue[];
+};
+/** 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;
+/** 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,24 @@
+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 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 +33,175 @@ 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|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 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) => {
+        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);
+    });
+    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/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[];

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

@@ -42,7 +42,7 @@ export function validateSessionRuntime(value, cwd, sessionId) {
         throw new Error("Invalid State Flow runtime configuration or counters");
     }
 }
-export function createSessionRuntime(snapshot, cwd, sessionId, lineage, publication = "unconfirmed", artifacts = {}) {
+export function createSessionRuntime(snapshot, cwd, sessionId, lineage, publication = "unconfirmed", _artifacts = {}) {
     const { durableBase: _base, pendingPublication: _publication, ...fields } = snapshot.meta;
     const runtime = {
         config: structuredClone(snapshot.config),
@@ -51,7 +51,6 @@ export function createSessionRuntime(snapshot, cwd, sessionId, lineage, publicat
             version: 1,
             identity: { cwd: resolve(cwd), sessionId },
             lineage: structuredClone([...lineage]),
-            ...(Object.keys(artifacts).length === 0 ? {} : { artifacts: structuredClone(artifacts) }),
             revision: "self",
             publication,
         },
@@ -59,51 +58,48 @@ export function createSessionRuntime(snapshot, cwd, sessionId, lineage, publicat
     validateSessionRuntime(runtime, cwd, sessionId);
     return runtime;
 }
-export function serializeSessionRuntime(runtime, cwd, sessionId, stream, existingSource) {
+export function serializeSessionRuntime(runtime, cwd, sessionId) {
     validateSessionRuntime(runtime, cwd, sessionId);
-    let existing = {};
-    if (existingSource !== undefined) {
+    const { temporal: _retiredTemporal, artifacts: _legacyArtifacts, ...runtimeMeta } = runtime.meta;
+    return { config: `${canonicalJson(runtime.config)}\n`, runtime: `${canonicalJson(runtimeMeta)}\n` };
+}
+export function parseSessionRuntime(config, runtimeSource, cwd, sessionId, legacyMetaSource) {
+    let selected = runtimeSource;
+    if (selected === undefined && legacyMetaSource !== undefined) {
+        let legacy;
         try {
-            existing = JSON.parse(existingSource);
+            legacy = JSON.parse(legacyMetaSource);
         }
         catch {
             throw new Error("State Flow session runtime contains invalid JSON");
         }
-        if (!isObject(existing) || !isJsonValue(existing))
-            throw new Error("Invalid State Flow session runtime metadata");
+        if (isObject(legacy) && (Object.hasOwn(legacy, "identity") || Object.hasOwn(legacy, "lineage")))
+            selected = legacyMetaSource;
     }
-    const temporal = stream === undefined ? runtime.meta.temporal : {
-        checkpoint: structuredClone(stream.checkpoint.through),
-        patches: stream.patches.map((record) => structuredClone(record.transition)),
-    };
-    return { config: `${canonicalJson(runtime.config)}\n`, meta: `${canonicalJson({ ...existing, ...runtime.meta, ...(temporal ? { temporal } : {}) })}\n` };
-}
-export function parseSessionRuntime(config, meta, cwd, sessionId) {
-    if (config === undefined && meta === undefined)
+    if (config === undefined && selected === undefined)
         return undefined;
-    if (config === undefined && meta !== undefined) {
+    if (config === undefined && selected !== undefined) {
         let document;
         try {
-            document = JSON.parse(meta);
+            document = JSON.parse(selected);
         }
         catch {
             throw new Error("State Flow session runtime contains invalid JSON");
         }
-        if (isObject(document) && !Object.hasOwn(document, "identity") && !Object.hasOwn(document, "lineage")
-            && Object.keys(document).every((key) => ["version", "artifacts", "temporal", "owner"].includes(key)))
+        if (isObject(document) && !Object.hasOwn(document, "identity") && !Object.hasOwn(document, "lineage"))
             return undefined;
     }
-    if (config === undefined || meta === undefined)
-        throw new Error("Incomplete State Flow config/meta pair");
+    if (config === undefined || selected === undefined)
+        throw new Error("Incomplete State Flow config/runtime pair");
     let runtime;
     try {
-        runtime = { config: JSON.parse(config), meta: JSON.parse(meta) };
+        runtime = { config: JSON.parse(config), meta: JSON.parse(selected) };
     }
     catch {
         throw new Error("State Flow session runtime contains invalid JSON");
     }
     validateSessionRuntime(runtime, cwd, sessionId);
-    const { temporal: _temporal, ...runtimeMeta } = runtime.meta;
+    const { temporal: _legacyTemporal, ...runtimeMeta } = runtime.meta;
     return { config: { enabled: runtime.config.enabled }, meta: runtimeMeta };
 }
 export function resolveSessionRuntime(runtime, revision) {

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

@@ -1,12 +1,14 @@
 import { type ArtifactCompilationUpdate, type ArtifactRegistry } from "./artifact.ts";
-import { type JsonObject } from "./json.ts";
+import { type JsonObject, type JsonValue } from "./json.ts";
 /** The canonical semantic state shape shared by global, CWD, and session scopes. */
-export interface MaterializedState extends JsonObject {
+export type MaterializedState = JsonObject & {
     artifacts: ArtifactRegistry;
     contract: JsonObject;
     working: JsonObject;
     response: string;
-}
+    /** Absent is the canonical empty lazy plane and preserves predecessor-store compatibility. */
+    lazy?: JsonValue;
+};
 /** Compatibility name for callers that still treat materialized state as a document. */
 export type StateDocument = MaterializedState;
 /** Model patch shape; artifact entries may be compiler outputs before trusted metadata is attached. */
@@ -22,6 +24,7 @@ export interface ScopePatch {
     artifacts?: JsonObject;
     contract?: JsonObject;
     working?: JsonObject;
+    lazy?: JsonValue;
 }
 export interface ScopedPatch {
     scope: StateScope;

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

@@ -1,5 +1,5 @@
 import { isArtifactRegistry, projectArtifactsForModel, updateArtifactRegistry, } from "./artifact.js";
-import { applyPatch, isObject } from "./json.js";
+import { applyPatch, isJsonValue, isObject } from "./json.js";
 export function emptyState() {
     return { artifacts: {}, contract: {}, working: {}, response: "" };
 }
@@ -9,7 +9,8 @@ export function isMaterializedState(value) {
         && isObject(value.contract)
         && isObject(value.working)
         && typeof value.response === "string"
-        && Object.keys(value).every((key) => key === "artifacts" || key === "contract" || key === "working" || key === "response");
+        && (!Object.hasOwn(value, "lazy") || (isJsonValue(value.lazy) && value.lazy !== null))
+        && Object.keys(value).every((key) => key === "artifacts" || key === "contract" || key === "working" || key === "response" || key === "lazy");
 }
 export const isStateDocument = isMaterializedState;
 /** Atomically replace compiled and removed artifacts inside one materialized scope. */
@@ -27,5 +28,6 @@ export function overlayStates(...scopes) {
 }
 /** Model-visible projection: runtime artifact bookkeeping never reaches ordinary context. */
 export function projectStateForModel(state) {
-    return { ...structuredClone(state), artifacts: projectArtifactsForModel(state.artifacts) };
+    const { lazy: _lazy, ...hot } = structuredClone(state);
+    return { ...hot, artifacts: projectArtifactsForModel(state.artifacts) };
 }

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

@@ -54,7 +54,7 @@ export function detailedStatus(snapshot, diagnostics) {
         `State Flow diagnostics — config.enabled=${snapshot.config.enabled}; branch mode=${snapshot.config.enabled ? "active" : "inactive"}`,
         `Repository: ${diagnostics.repositoryRoot}`,
         `Scope keys: CWD ${diagnostics.cwdScopeKey}; session ${diagnostics.sessionScopeKey}`,
-        "Session files: config.json owns behavior; meta.json owns lineage and provenance",
+        "Session files: config.json owns behavior; runtime.json owns branch recovery; meta.json owns scope provenance",
         `Runtime metadata: step #${snapshot.meta.step}; active revision ${snapshot.meta.durableBase ?? "none"}; bootstrap ${snapshot.meta.bootstrap === true}`,
         `Remote publication policy: ${snapshot.meta.remotePublication?.mode ?? "legacy-transition"}`,
         diagnostics.publicationQueueError !== undefined

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

@@ -12,6 +12,8 @@ export declare function detectGitCapability(): "git" | "files";
 export declare function assertStorageDirectory(path: string): void;
 /** Explicit creation only; existing bytes and unrelated files are never adopted or rewritten here. */
 export declare function initializeFileStore(root: string): void;
+/** Wait only for a cooperating live owner; interrupted or malformed locks remain explicit recovery errors. */
+export declare function acquirePublicationLock(path: string, unavailable: (cause: unknown) => Error): number;
 /** Git writers also acquire this lock before their common-Git-directory lock. */
 export declare function withStoragePublicationLock<T>(repositoryRoot: string, action: (root: string) => T): T;
 export declare function assertTemporalFileBase(expected: TemporalFileBase, current: TemporalFileBase): void;