@llblab/pi-kit 0.15.0 → 0.17.0

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

@@ -1,3 +1,4 @@
+import { isObject, sameJson, type JsonValue } from "./json.ts";
 import { projectStateForModel, type MaterializedState, type ScopePatch, type StateScope } from "./state.ts";
 import { readTemporalState, type TemporalState, type TransitionBoundary } from "./temporal.ts";
 
@@ -9,22 +10,46 @@ export type StateReadResult =
 	| { path: string; boundary: TransitionBoundary; state: MaterializedState }
 	| { path: string; boundary: TransitionBoundary; patch: ScopePatch & { response?: string } };
 
-const PATH_PATTERN = /^state(?:\[(\d+)\])?(?:\.(global|cwd|session)(?:\[(\d+)\])?(?:\.patches(?:\[(\d+)\])?)?)?$/;
+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";
+}
+
+const MAX_REFERENCE_SOURCES = 3;
+const MAX_REFERENCE_SCAN_NODES = 10_000;
 
-/** Resolve the compact model-facing path grammar without treating aliases as literal JSON containers. */
+type ValueSelector = { kind: "key"; key: string } | { kind: "index"; index: number } | { kind: "range"; start: number; end: number };
+
+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: string): StateReadQuery {
 	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) throw new Error("Index patches after .patches, not after the scope");
-	const rawOffset = patchOffset ?? scopeOffset ?? effectiveOffset ?? "0";
-	const offset = Number(rawOffset);
+	const [, root, rootOffset, patchOffset] = match;
+	if (path.includes(".patches") && rootOffset !== undefined) throw new Error("Index patches after .patches, not after the scope");
+	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 as StateScope };
+		return { kind: "patch", path, offset, scope: root as StateScope };
 	}
-	return { kind: "state", path, offset, ...(scope === undefined ? {} : { scope: scope as StateScope }) };
+	return { kind: "state", path, offset, ...(root === "effective" ? {} : { scope: root as StateScope }) };
 }
 
 export function readStatePath(view: TemporalState, path: string): StateReadResult {
@@ -38,3 +63,230 @@ export function readStatePath(view: TemporalState, path: string): StateReadResul
 	if (!record) throw new Error(`Requested ${query.scope} patch predates retained hot history`);
 	return { path, boundary: structuredClone(record.transition), patch: structuredClone(record.patch) };
 }
+
+function parseValuePath(path: string): { root: string; selectors: ValueSelector[] } {
+	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: ValueSelector[] = 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: JsonValue, selectors: readonly ValueSelector[], path: string): JsonValue {
+	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: JsonValue): string {
+	if (Array.isArray(value)) return "array";
+	if (isObject(value)) return "object";
+	return typeof value;
+}
+
+function referenceCandidates(path: string): string[] {
+	if (/^(?:artifacts|contract|working|intents|response|lazy)(?=\.|\[|$)/.test(path)) return [path, `effective.${path}`];
+	return [path];
+}
+
+function inlineReferencePattern(path: string): RegExp {
+	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: TemporalState, path: string): { sources: StateReferenceSource[]; truncated: boolean } {
+	const candidates = referenceCandidates(path);
+	const patterns = candidates.map(inlineReferencePattern);
+	const sources: StateReferenceSource[] = [];
+	let visited = 0;
+	let truncated = false;
+	const visit = (value: JsonValue, owner: StateScope, ownerPath: string): void => {
+		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"] as const) {
+		const state = readTemporalState(view, 0, scope);
+		for (const plane of ["artifacts", "contract", "working", "intents", "lazy"] as const) {
+			const value = state[plane];
+			if (value !== undefined) visit(value as JsonValue, 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: TemporalState, path: string): StateReadHint[] | undefined {
+	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: JsonValue, projection: StateReadProjection): ProjectedStateRead {
+	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 as "number" | "boolean" }, keys: [] };
+}
+
+function patchAtPath(view: TemporalState, root: string, selectors: readonly ValueSelector[], path: string): JsonValue {
+	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: JsonValue = {};
+	if (rootQuery.scope) {
+		patch = structuredClone(view.scopes[rootQuery.scope].patches.find((record) => record.transition.id === boundary.id)?.patch ?? {}) as JsonValue;
+	} 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: JsonValue, current: JsonValue): JsonValue {
+	if (!isObject(previous) || !isObject(current)) return structuredClone(current);
+	const patch: Record<string, JsonValue> = {};
+	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: TemporalState, paths: readonly string[], projection: StateReadProjection = "value"): ProjectedStateRead {
+	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 as { value: JsonValue }).value) };
+	return {
+		meta: projected.map((result) => (result as Extract<ProjectedStateRead, { meta: unknown }>).meta),
+		keys: projected.map((result) => (result as Extract<ProjectedStateRead, { meta: unknown }>).keys),
+	} as unknown as ProjectedStateRead;
+}

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

@@ -114,6 +114,34 @@ export class TemporalRuntime {
 		return structuredClone(this.provenanceByScope[scope]);
 	}
 
+	/** Read canonical shared memory without creating, migrating, or publishing storage. */
+	loadPassive(): boolean {
+		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))];
+		})) as Record<(typeof SHARED_SCOPES)[number], ScopeStream | undefined>;
+		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 as TemporalGitBase).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(): void {
 		const backend = detectGitCapability();
@@ -325,7 +353,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) {
@@ -344,7 +372,7 @@ export class TemporalRuntime {
 		if (!streams.cwd && !allowCreateCwd) return undefined;
 		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.
 		if (newSessionOrigin) streams.session = undefined;
@@ -359,7 +387,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"] as const).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");
@@ -520,7 +548,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/lib/session.ts

@@ -7,6 +7,16 @@ interface BranchEntry {
 	message?: { 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[];
@@ -53,3 +63,38 @@ export function isNewSession(reason: unknown, branch: readonly BranchEntry[]): b
 	if (reason === "new") return true;
 	return reason === "startup" && !hasPriorConversation(branch);
 }
+
+export function findAssistantToolBatch(session: SessionEntryLookup, toolCallId: string): string[] | undefined {
+	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 as { content?: unknown }).content)) continue;
+		const calls = (cursor.message as { content: unknown[] }).content.filter((block): block is { type: "toolCall"; id: string; name: string } => {
+			return typeof block === "object" && block !== null
+				&& (block as { type?: unknown }).type === "toolCall"
+				&& typeof (block as { id?: unknown }).id === "string"
+				&& typeof (block as { name?: unknown }).name === "string";
+		});
+		if (calls.some(({ id }) => id === toolCallId)) return calls.map(({ name }) => name);
+	}
+	return undefined;
+}
+
+export function findPassiveStopBoundary(branch: readonly BranchEntry[], sessionId: string, entryType: string): PassiveStopBoundary | undefined {
+	for (const entry of [...branch].reverse()) {
+		try {
+			if (entry?.type !== "custom" || entry.customType !== entryType) continue;
+			const { at, from, reset, owner } = (entry.data as { at?: unknown; from?: unknown; reset?: unknown; owner?: unknown } | undefined) ?? {};
+			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: unknown): boolean {
+	return reason === undefined || reason === "startup" || reason === "reload" || reason === "resume";
+}

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

@@ -2,7 +2,7 @@ import { resolve } from "node:path";
 import { parseArtifactProvenanceRegistry, type ArtifactProvenanceRegistry } from "./artifact.ts";
 import { parseRemotePublicationPolicyDocument, serializeRemotePublicationPolicyDocument, type RemotePublicationPolicyDocument } from "./publication.ts";
 import { applyPatch, canonicalJson, containsNull, isJsonValue, isObject, type JsonObject } from "./json.ts";
-import { validateTemporalLineage, type ScopeStream, type TransitionBoundary } from "./temporal.ts";
+import { validateTemporalLineage, type TransitionBoundary } from "./temporal.ts";
 import { migrateLegacySkillCompilations } from "./skills.ts";
 import { isMaterializedState, type MaterializedState } from "./state.ts";
 const MAX_RESTORED_STEP = Number.MAX_SAFE_INTEGER - 1;
@@ -97,7 +97,7 @@ export function createSessionRuntime(
 	sessionId: string,
 	lineage: readonly TransitionBoundary[],
 	publication: SessionRuntime["meta"]["publication"] = "unconfirmed",
-	artifacts: ArtifactProvenanceRegistry = {},
+	_artifacts: ArtifactProvenanceRegistry = {},
 ): SessionRuntime {
 	const { durableBase: _base, pendingPublication: _publication, ...fields } = snapshot.meta;
 	const runtime: SessionRuntime = {
@@ -107,7 +107,6 @@ export function createSessionRuntime(
 			version: 1,
 			identity: { cwd: resolve(cwd), sessionId },
 			lineage: structuredClone([...lineage]),
-			...(Object.keys(artifacts).length === 0 ? {} : { artifacts: structuredClone(artifacts) }),
 			revision: "self",
 			publication,
 		},
@@ -117,39 +116,37 @@ export function createSessionRuntime(
 }
 
 export function serializeSessionRuntime(
-	runtime: SessionRuntime, cwd: string, sessionId: string, stream?: ScopeStream, existingSource?: string,
-): { config: string; meta: string } {
+	runtime: SessionRuntime, cwd: string, sessionId: string,
+): { config: string; runtime: string } {
 	validateSessionRuntime(runtime, cwd, sessionId);
-	let existing: Record<string, unknown> = {};
-	if (existingSource !== undefined) {
-		try { existing = JSON.parse(existingSource) as Record<string, unknown>; }
-		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");
-	}
-	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` };
+	const { temporal: _retiredTemporal, artifacts: _legacyArtifacts, ...runtimeMeta } = runtime.meta;
+	return { config: `${canonicalJson(runtime.config)}\n`, runtime: `${canonicalJson(runtimeMeta)}\n` };
 }
 
-export function parseSessionRuntime(config: string | undefined, meta: string | undefined, cwd: string, sessionId: string): SessionRuntime | undefined {
-	if (config === undefined && meta === undefined) return undefined;
-	if (config === undefined && meta !== undefined) {
+export function parseSessionRuntime(
+	config: string | undefined, runtimeSource: string | undefined, cwd: string, sessionId: string, legacyMetaSource?: string,
+): SessionRuntime | undefined {
+	let selected = runtimeSource;
+	if (selected === undefined && legacyMetaSource !== undefined) {
+		let legacy: unknown;
+		try { legacy = JSON.parse(legacyMetaSource); } catch { throw new Error("State Flow session runtime contains invalid JSON"); }
+		if (isObject(legacy) && (Object.hasOwn(legacy, "identity") || Object.hasOwn(legacy, "lineage"))) selected = legacyMetaSource;
+	}
+	if (config === undefined && selected === undefined) return undefined;
+	if (config === undefined && selected !== undefined) {
 		let document: unknown;
-		try { document = JSON.parse(meta); } 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))) return undefined;
+		try { 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")) 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: unknown;
 	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 };
 }
 

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

@@ -5,15 +5,18 @@ import {
 	type ArtifactCompilationUpdate,
 	type ArtifactRegistry,
 } from "./artifact.ts";
-import { applyPatch, isObject, type JsonObject } from "./json.ts";
+import { applyPatch, isJsonValue, isObject, 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;
+	intents: 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;
@@ -23,6 +26,7 @@ export interface StatePatch extends JsonObject {
 	artifacts: JsonObject;
 	contract: JsonObject;
 	working: JsonObject;
+	intents: JsonObject;
 	response: string;
 }
 
@@ -33,6 +37,8 @@ export interface ScopePatch {
 	artifacts?: JsonObject;
 	contract?: JsonObject;
 	working?: JsonObject;
+	intents?: JsonObject;
+	lazy?: JsonValue;
 }
 
 export interface ScopedPatch {
@@ -62,7 +68,7 @@ export interface ScopedStates {
 }
 
 export function emptyState(): MaterializedState {
-	return { artifacts: {}, contract: {}, working: {}, response: "" };
+	return { artifacts: {}, contract: {}, working: {}, intents: {}, response: "" } as MaterializedState;
 }
 
 export function isMaterializedState(value: unknown): value is MaterializedState {
@@ -70,12 +76,21 @@ export function isMaterializedState(value: unknown): value is MaterializedState
 		&& isArtifactRegistry(value.artifacts)
 		&& isObject(value.contract)
 		&& isObject(value.working)
+		&& isObject(value.intents)
 		&& 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 === "intents" || key === "response" || key === "lazy");
 }
 
 export const isStateDocument = isMaterializedState;
 
+/** Upgrade one exact pre-intents materialized state without inferring commitments. */
+export function migratePreIntentState(value: unknown): MaterializedState | undefined {
+	if (!isObject(value) || Object.hasOwn(value, "intents")) return undefined;
+	const candidate = { ...structuredClone(value), intents: {} };
+	return isMaterializedState(candidate) ? candidate : undefined;
+}
+
 /** Atomically replace compiled and removed artifacts inside one materialized scope. */
 export function updateMaterializedArtifacts(
 	state: MaterializedState,
@@ -96,5 +111,6 @@ export function overlayStates(...scopes: readonly MaterializedState[]): Material
 
 /** Model-visible projection: runtime artifact bookkeeping never reaches ordinary context. */
 export function projectStateForModel(state: MaterializedState): MaterializedState {
-	return { ...structuredClone(state), artifacts: projectArtifactsForModel(state.artifacts) };
+	const { lazy: _lazy, ...hot } = structuredClone(state);
+	return { ...hot, artifacts: projectArtifactsForModel(state.artifacts) } as MaterializedState;
 }

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

@@ -100,7 +100,7 @@ export function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostic
 		`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