@llblab/pi-kit 0.24.0 → 0.25.0

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

@@ -1,13 +1,21 @@
 import { randomUUID } from "node:crypto";
-import { isJsonValue, isObject, sameJson, validatePatch, type JsonObject } from "./json.ts";
-import type { ScopePatch, ScopedStates, StateScope } from "./state.ts";
+import { isJsonValue, isObject, sameJson, validatePatch, type JsonObject, type JsonValue } from "./json.ts";
+import type { ScopedSemanticStates, StateScope } from "./state.ts";
 
 export const DEFAULT_HISTORY_LIMIT = 7;
 export const MAX_HISTORY_LIMIT = 100;
 
 export interface RecentScopePatch {
 	scope: StateScope;
-	patch: ScopePatch & { response?: string };
+	patch: {
+		[key: string]: JsonValue | undefined;
+		intents?: JsonObject | null;
+		contract?: JsonObject | null;
+		working?: JsonObject | null;
+		artifacts?: JsonObject | null;
+		lazy?: JsonObject | null;
+		response?: string | null;
+	};
 }
 
 /** Exact accepted replay cohort; temporal runtime owns its causal boundary. */
@@ -51,13 +59,9 @@ function validateScopedPatch(value: unknown): asserts value is RecentScopePatch
 	validatePatch(value.patch);
 	for (const [key, field] of Object.entries(value.patch)) {
 		const valid = key === "response"
-			? value.scope === "session" && typeof field === "string"
-			: key === "lazy"
-				? field !== null
-				: PATCH_KEYS.has(key) && isObject(field);
-		if (!PATCH_KEYS.has(key) || !valid) {
-			throw new Error("Recent State Flow patches may contain hot object planes, ordinary-JSON lazy state, and a session response string");
-		}
+			? value.scope === "session" && (field === null || typeof field === "string")
+			: !PATCH_KEYS.has(key) || field === null || isObject(field);
+		if (!valid) throw new Error("Recent State Flow patches require object planes or deletion, and a session response string or deletion");
 	}
 }
 
@@ -74,10 +78,11 @@ export function validateRecentTransition(value: unknown): asserts value is Recen
 	}
 }
 
-export function createAcceptedTransition(currentStates: ScopedStates, nextStates: ScopedStates, id?: string): AcceptedTransition | undefined {
+export function createAcceptedTransition(currentStates: ScopedSemanticStates, nextStates: ScopedSemanticStates, id?: string): AcceptedTransition | undefined {
 	const transitions: RecentScopePatch[] = [];
 	for (const scope of SCOPES) {
 		const patch = replayPatch(currentStates[scope], nextStates[scope]);
+		if ((currentStates[scope].response ?? "") === (nextStates[scope].response ?? "")) delete patch.response;
 		if (Object.keys(patch).length > 0) transitions.push({ scope, patch });
 	}
 	if (transitions.length === 0) return undefined;

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

@@ -3,7 +3,7 @@ import { appendFileSync, closeSync, constants, fstatSync, lstatSync, mkdirSync,
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { isObject } from "./json.ts";
 
-export type StateFlowDiagnosticCategory = "invalid-patch" | "publication-conflict" | "finalization";
+export type StateFlowDiagnosticCategory = "invalid-patch" | "publication-conflict" | "finalization" | "barrier-block";
 
 /** Minimal structural block; only ordinary text keeps its exact content. */
 export interface StateFlowDiagnosticBlock {
@@ -22,6 +22,8 @@ export interface StateFlowDiagnosticRecord {
 	input?: unknown;
 	tool?: string;
 	toolCallId?: string;
+	/** Names only, in native assistant-batch order; never sibling arguments. */
+	batchToolNames?: string[];
 }
 
 /** Preserve exact text blocks and block boundaries; reasoning bodies are never duplicated. */
@@ -62,6 +64,7 @@ export interface DiagnosticExtras {
 	input?: unknown;
 	tool?: string;
 	toolCallId?: string;
+	batchToolNames?: readonly string[];
 }
 
 /** Own diagnostic path safety, projection, persistence, and one-shot failure reporting. */
@@ -105,6 +108,7 @@ export class StateFlowDiagnosticWriter {
 				...(extras.input === undefined ? {} : { input: extras.input }),
 				...(extras.tool === undefined ? {} : { tool: extras.tool }),
 				...(extras.toolCallId === undefined ? {} : { toolCallId: extras.toolCallId }),
+				...(extras.batchToolNames === undefined ? {} : { batchToolNames: [...extras.batchToolNames] }),
 			});
 			return true;
 		} catch (failure) {

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

@@ -1,15 +1,15 @@
-import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT } from "./history.ts";
-import { isObject, sameJson, type JsonValue } from "./json.ts";
-import { projectStateForModel, type ModelState, type ScopePatch, type StateScope } from "./state.ts";
-import { readTemporalState, type TemporalState, type TransitionBoundary } from "./temporal.ts";
+import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT, type RecentScopePatch } from "./history.ts";
+import { isObject, sameJson, type JsonObject, type JsonValue } from "./json.ts";
+import { emptyState, projectSemanticPatch, projectStateForModel, type SemanticState, type StateScope } from "./state.ts";
+import { readTemporalView, type TemporalState, type TransitionBoundary } from "./temporal.ts";
 
 export type StateReadQuery =
 	| { kind: "state"; path: string; offset: number; scope?: StateScope }
 	| { kind: "patch"; path: string; offset: number; scope: StateScope };
 
 export type StateReadResult =
-	| { path: string; boundary: TransitionBoundary; state: ModelState }
-	| { path: string; boundary: TransitionBoundary; patch: ScopePatch & { response?: string } };
+	| { path: string; boundary: TransitionBoundary; state: SemanticState }
+	| { path: string; boundary: TransitionBoundary; patch: RecentScopePatch["patch"] };
 
 export type StateReadProjection = "value" | "keys" | "patch";
 type StateReadMeta = { type: "object"; size: number } | { type: "array"; length: number } | { type: "string"; length: number } | { type: "number" | "boolean" };
@@ -61,11 +61,11 @@ export function readStatePath(view: TemporalState, path: string, historyLimit =
 	if (query.kind === "state") {
 		const boundary = view.lineage[view.lineage.length - 1 - query.offset];
 		if (!boundary) throw new Error("Requested history predates the proven temporal origin");
-		return { path, boundary: structuredClone(boundary), state: projectStateForModel(readTemporalState(view, query.offset, query.scope, historyLimit)) };
+		return { path, boundary: structuredClone(boundary), state: projectStateForModel(readTemporalView(view, query.offset, query.scope, historyLimit)) };
 	}
 	const record = view.scopes[query.scope].patches.at(-1 - query.offset);
 	if (!record) throw new Error(`Requested ${query.scope} patch predates retained hot history`);
-	return { path, boundary: structuredClone(record.transition), patch: structuredClone(record.patch) };
+	return { path, boundary: structuredClone(record.transition), patch: projectSemanticPatch(record.patch as JsonObject) };
 }
 
 function parseValuePath(path: string): { root: string; selectors: ValueSelector[] } {
@@ -170,7 +170,7 @@ export function findStateReferenceSources(view: TemporalState, path: string, his
 		}
 	};
 	for (const scope of ["global", "cwd", "session"] as const) {
-		const state = readTemporalState(view, 0, scope, historyLimit);
+		const state = readTemporalView(view, 0, scope, historyLimit);
 		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}`);
@@ -213,12 +213,12 @@ function patchAtPath(view: TemporalState, root: string, selectors: readonly Valu
 	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;
+		patch = projectSemanticPatch((view.scopes[rootQuery.scope].patches.find((record) => record.transition.id === boundary.id)?.patch ?? {}) as JsonObject);
 	} else {
 		const before = view.lineage.at(-2 - rootQuery.offset);
 		if (before) {
-			const current = readTemporalState(view, rootQuery.offset, undefined, historyLimit);
-			const previous = readTemporalState(view, rootQuery.offset + 1, undefined, historyLimit);
+			const current = readTemporalView(view, rootQuery.offset, undefined, historyLimit);
+			const previous = readTemporalView(view, rootQuery.offset + 1, undefined, historyLimit);
 			patch = diffObjects(previous, current);
 		}
 	}
@@ -274,10 +274,10 @@ export function readProjectedState(view: TemporalState, paths: readonly string[]
 			const query = parseStateReadPath(root, historyLimit);
 			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, historyLimit)
-				: projectStateForModel(readTemporalState(view, query.offset, query.scope, historyLimit));
-			if (readsLazy && !Object.hasOwn(state, "lazy")) state.lazy = {};
+			const raw = readTemporalView(view, query.offset, query.scope, historyLimit);
+			const state = readsLazy ? raw : projectStateForModel(raw);
+			const field = selectors.length === 1 && selectors[0]?.kind === "key" ? selectors[0].key : undefined;
+			if (projection === "value" && field !== undefined && Object.hasOwn(emptyState(), field) && !Object.hasOwn(state, field)) return { value: null };
 			return projectValue(selectValue(state, selectors, path), projection);
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);

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

@@ -1,34 +1,34 @@
-import { parseRetainedPiCheckpoint, migrationFailure, type RetainedBoundaryCheckpoint, type RetainedPiCheckpoint, type Snapshot } from "./snapshot.ts";
+import { parseRetainedPiCheckpoint, migrationFailure, type InactiveMode, type RetainedBoundaryCheckpoint, type RetainedPiCheckpoint, type Snapshot } from "./snapshot.ts";
 
 export type RetainedCheckpointSelection =
 	| { kind: "boundary"; checkpoint: RetainedBoundaryCheckpoint; skipped: string[] }
-	| { kind: "disabled"; skipped: string[] }
+	| { kind: "pre-runtime"; mode: InactiveMode; skipped: string[] }
 	| { kind: "unavailable"; snapshot: Snapshot; skipped: string[] };
 
-/** Select the newest supported retained-boundary checkpoint or disabled marker; unsupported pointers fail closed. */
-export function selectRetainedCheckpoint(candidates: readonly unknown[]): RetainedCheckpointSelection {
+/** Select the newest supported retained-boundary checkpoint or pre-runtime mode; unsupported pointers fail closed. */
+export function selectRetainedCheckpoint(candidates: readonly unknown[], inactiveMode: InactiveMode = "passive"): RetainedCheckpointSelection {
 	const skipped: string[] = [];
 	for (const candidate of candidates) {
 		let retained: RetainedPiCheckpoint;
 		try {
 			if (typeof candidate === "object" && candidate !== null && Object.hasOwn(candidate, "revision")) {
-				return { kind: "unavailable", snapshot: migrationFailure({}, "Snapshot restoration failed: revision-pointer checkpoints are unsupported"), skipped };
+				return { kind: "unavailable", snapshot: migrationFailure({}, "Snapshot restoration failed: revision-pointer checkpoints are unsupported", inactiveMode), skipped };
 			}
-			retained = parseRetainedPiCheckpoint(candidate);
+			retained = parseRetainedPiCheckpoint(candidate, inactiveMode);
 		} catch (error) {
 			skipped.push(`Snapshot restoration failed: ${error instanceof Error ? error.message : String(error)}`);
 			continue;
 		}
-		return "disabled" in retained ? { kind: "disabled", skipped } : { kind: "boundary", checkpoint: retained, skipped };
+		return "boundary" in retained ? { kind: "boundary", checkpoint: retained, skipped } : { kind: "pre-runtime", mode: retained.mode, skipped };
 	}
 	return {
 		kind: "unavailable",
-		snapshot: migrationFailure({}, skipped[0] ?? "Snapshot restoration failed: no supported checkpoint"),
+		snapshot: migrationFailure({}, skipped[0] ?? "Snapshot restoration failed: no supported checkpoint", inactiveMode),
 		skipped,
 	};
 }
 
-/** Withdraw a caller's join without cancelling independently owned recovery or Stop persistence. */
+/** Withdraw a caller's join without cancelling independently owned recovery or mode persistence. */
 export function waitForRecovery<T>(operation: Promise<T>, signal: AbortSignal): Promise<T> {
 	return new Promise<T>((resolve, reject) => {
 		const aborted = () => reject(signal.reason);
@@ -45,6 +45,6 @@ export function waitForRecovery<T>(operation: Promise<T>, signal: AbortSignal):
 }
 
 /** A selected boundary that cannot be resolved stays unavailable; callers never fall through to older evidence. */
-export function selectedBoundaryFailure(cause: string): Snapshot {
-	return migrationFailure({}, `Snapshot restoration failed: ${cause}`);
+export function selectedBoundaryFailure(cause: string, mode: InactiveMode = "passive"): Snapshot {
+	return migrationFailure({}, `Snapshot restoration failed: ${cause}`, mode);
 }

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

@@ -6,16 +6,16 @@ import { parseArtifactProvenanceRegistry, pruneArtifactProvenance, type Artifact
 import { assertTemporalFileBase, captureTemporalFileBase, initializeFileStore, publishTemporalStateToFiles, withStorageTransaction, type StorageTransaction, type TemporalFileBase } from "./storage.ts";
 import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT, type AcceptedTransition, type RecentTransitionWindow } from "./history.ts";
 import { hashJson, sameJson } from "./json.ts";
-import { HistoryBoundaryExpiredError, RevisionUnavailableError, createSessionRuntime, parseSessionRuntime, retainedBoundaryCheckpoint, type RetainedBoundaryCheckpoint, type RetainedPiCheckpoint, type Snapshot } from "./snapshot.ts";
-import { emptyState, type MaterializedState, type ScopedStates, type StateScope } from "./state.ts";
-import { adoptTemporalStreams, advanceTemporalState, constrainTemporalState, createTemporalState, readTemporalState, selectScopeStreamAtBoundary, validateScopeLineage, type ScopeStream, type TemporalState } from "./temporal.ts";
+import { HistoryBoundaryExpiredError, RevisionUnavailableError, createSessionRuntime, parseSessionRuntime, preRuntimeCheckpoint, retainedBoundaryCheckpoint, type RetainedBoundaryCheckpoint, type RetainedPiCheckpoint, type Snapshot } from "./snapshot.ts";
+import { type MaterializedState, type SemanticState, type ScopedSemanticStates, type ScopedStates, type StateScope } from "./state.ts";
+import { adoptTemporalStreams, advanceTemporalState, constrainTemporalState, createTemporalState, readTemporalScopes, readTemporalState, readTemporalView, selectScopeStreamAtBoundary, validateScopeLineage, type ScopeStream, type TemporalState } from "./temporal.ts";
 
 const SCOPES = ["global", "cwd", "session"] as const;
 const SHARED_SCOPES = ["global", "cwd"] as const;
 export type RuntimePublication = ReturnType<typeof publishTemporalStateToFiles>;
 
 export interface RuntimePatchTransaction {
-	readonly states: ScopedStates;
+	readonly states: ScopedSemanticStates;
 	readonly causalBasis: string;
 	readonly provenance: Record<StateScope, ArtifactProvenanceRegistry>;
 	publish(snapshot: Snapshot, accepted?: AcceptedTransition, provenance?: Partial<Record<StateScope, Record<string, ArtifactProvenance>>>): RuntimePublication;
@@ -68,7 +68,7 @@ function removedTargetScopeConflict(scopes: readonly StateScope[]): Error {
 }
 
 function freshEmptyScopeStream(scope: StateScope, origin: string, historyLimit: number): ScopeStream {
-	return createTemporalState({ global: emptyState(), cwd: emptyState(), session: emptyState() }, origin, historyLimit).scopes[scope];
+	return createTemporalState({ global: {}, cwd: {}, session: {} }, origin, historyLimit).scopes[scope];
 }
 
 /** Cached branch-selected temporal state and publication basis; excludes Pi event policy. */
@@ -117,7 +117,7 @@ export class TemporalRuntime {
 		})) as Record<(typeof SHARED_SCOPES)[number], ScopeStream | undefined>;
 		if (!shared.global && !shared.cwd) return false;
 		if (!shared.global) throw new Error("Incomplete passive State Flow shared storage: CWD state exists without global state");
-		const fresh = createTemporalState({ global: emptyState(), cwd: emptyState(), session: emptyState() }, randomUUID(), this.historyLimit);
+		const fresh = createTemporalState({ global: {}, cwd: {}, session: {} }, randomUUID(), this.historyLimit);
 		// Global memory is valid before this CWD has ever materialized its own scope.
 		const view = adoptTemporalStreams({ global: shared.global, cwd: shared.cwd ?? fresh.scopes.cwd, session: fresh.scopes.session }, `passive:files:${randomUUID()}`, this.historyLimit);
 		const provenance = {
@@ -151,6 +151,11 @@ export class TemporalRuntime {
 		return readTemporalState(this.view, offset, scope, this.historyLimit);
 	}
 
+	readView(offset = 0, scope?: StateScope): SemanticState {
+		if (!this.view) throw new Error("State Flow temporal runtime is unavailable");
+		return readTemporalView(this.view, offset, scope, this.historyLimit);
+	}
+
 	states(): ScopedStates {
 		return { global: this.read(0, "global"), cwd: this.read(0, "cwd"), session: this.read(0, "session") };
 	}
@@ -162,7 +167,7 @@ export class TemporalRuntime {
 
 	/** Encode Pi lifecycle state against the current retained semantic boundary. */
 	retainedCheckpoint(snapshot: Snapshot): RetainedPiCheckpoint {
-		if (!this.view) return { disabled: true };
+		if (!this.view) return preRuntimeCheckpoint(snapshot.config.mode);
 		return retainedBoundaryCheckpoint(snapshot, this.causalBasis());
 	}
 
@@ -211,7 +216,7 @@ export class TemporalRuntime {
 			session: selectedSession,
 		}, `restore:${checkpoint.boundary}:${randomUUID()}`, this.historyLimit);
 		const snapshot: Snapshot = {
-			config: { enabled: checkpoint.enabled },
+			config: { mode: checkpoint.mode },
 			meta: {
 				step: checkpoint.step,
 				...(checkpoint.bootstrap === true ? { bootstrap: true } : {}),
@@ -226,7 +231,7 @@ export class TemporalRuntime {
 				// Live evidence cannot prove an earlier artifact version, even after a change-away-and-back.
 				for (const record of scopes.session.patches) {
 					if (record.transition.position <= boundary.position) continue;
-					for (const path of Object.keys(record.patch.artifacts ?? {})) delete retained[path];
+					for (const path of Object.keys(record.patch.artifacts === null ? retained : record.patch.artifacts ?? {})) delete retained[path];
 				}
 			}
 			return [scope, retained];
@@ -294,8 +299,9 @@ export class TemporalRuntime {
 			const meta = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey).meta;
 			return [scope, parseScopeProvenance(files.get(meta), meta)];
 		})) as Record<StateScope, ArtifactProvenanceRegistry>;
+		// Read-only recovery grants no active policy; callers select the inactive mode.
 		const snapshot: Snapshot = {
-			config: { enabled: false },
+			config: { mode: "passive" },
 			meta: { step: document.meta.step, ...(document.meta.bootstrap === true ? { bootstrap: true } : {}) },
 		};
 		this.view = view;
@@ -380,7 +386,7 @@ export class TemporalRuntime {
 		// A pre-runtime branch may establish an empty origin, never import a later session layer.
 		if (newSessionOrigin) streams.session = undefined;
 		if (copy) streams.session = copy.stream;
-		const fresh = createTemporalState({ global: emptyState(), cwd: emptyState(), session: emptyState() }, randomUUID(), this.historyLimit);
+		const fresh = createTemporalState({ global: {}, cwd: {}, session: {} }, randomUUID(), this.historyLimit);
 		const candidate = new TemporalRuntime(this.cwd, this.session, this.root, undefined, this.historyLimit);
 		candidate.base = base;
 		candidate.view = adoptTemporalStreams({ global: streams.global ?? fresh.scopes.global, cwd: streams.cwd ?? fresh.scopes.cwd, session: streams.session ?? fresh.scopes.session }, `files:${randomUUID()}`, this.historyLimit);
@@ -534,7 +540,7 @@ export class TemporalRuntime {
 			const stream = parseScopeStream(files.get(session.checkpoint), files.get(session.patches), "session", undefined, files.get(session.meta));
 			if (!document || !stream) throw new RevisionUnavailableError("Current State Flow session memory is incomplete");
 			validateScopeLineage(stream, "session", document.meta.lineage, MAX_HISTORY_LIMIT);
-			throw new RevisionUnavailableError("Existing State Flow session memory is not selected; select an accepted boundary or use /state-flow-start");
+			throw new RevisionUnavailableError("Existing State Flow session memory is not selected; select an accepted boundary or use /state-flow-active");
 		}
 		const origin = `patch:${randomUUID()}`;
 		const streams = Object.fromEntries(SCOPES.map((scope) => {
@@ -555,7 +561,7 @@ export class TemporalRuntime {
 	/** Stage and accept synchronously inside an awaited lock; expose neither selection nor raw storage operations. */
 	async withPatchTransaction<T>(action: (transaction: RuntimePatchTransaction) => T, signal?: AbortSignal): Promise<T> {
 		return this.withPublicationTransaction((candidate, publish) => action({
-			states: candidate.states(),
+			states: readTemporalScopes(candidate.view!, 0, this.historyLimit),
 			causalBasis: candidate.causalBasis(),
 			provenance: structuredClone(candidate.provenanceByScope),
 			publish,

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

@@ -1,4 +1,4 @@
-import { parseRetainedPiCheckpoint } from "./snapshot.ts";
+import { parseRetainedPiCheckpoint, type InactiveMode } from "./snapshot.ts";
 
 export const SNAPSHOT_ENTRY_TYPE = "state-flow-snapshot";
 
@@ -18,8 +18,10 @@ export interface PassiveStopBoundary {
 	at: number;
 	from?: number;
 	preserveContext?: true;
-	/** A same-owner failed Stop remains a write fence until a later accepted checkpoint. */
+	/** A same-owner failed mode change remains a write fence until a later accepted checkpoint. */
 	persistenceError?: string;
+	/** The inactive mode selected by that failed change; legacy markers omit it. */
+	mode?: InactiveMode;
 }
 
 export interface SnapshotDiscovery {
@@ -114,7 +116,7 @@ export function findPassiveStopBoundary(branch: readonly BranchEntry[], sessionI
 				continue;
 			}
 			if (entry.customType !== entryType) continue;
-			const { at, from, reset, owner, preserveContext, persistenceError } = (entry.data as { at?: unknown; from?: unknown; reset?: unknown; owner?: unknown; preserveContext?: unknown; persistenceError?: unknown } | undefined) ?? {};
+			const { at, from, reset, owner, preserveContext, persistenceError, mode } = (entry.data as { at?: unknown; from?: unknown; reset?: unknown; owner?: unknown; preserveContext?: unknown; persistenceError?: unknown; mode?: unknown } | undefined) ?? {};
 			if (reset === true && owner === sessionId) return undefined;
 			if (owner !== undefined && owner !== sessionId) continue;
 			if (typeof at === "number" && Number.isSafeInteger(at) && at >= 0) return {
@@ -122,6 +124,7 @@ export function findPassiveStopBoundary(branch: readonly BranchEntry[], sessionI
 				...(typeof from === "number" && Number.isSafeInteger(from) && from >= 0 ? { from } : {}),
 				...(preserveContext === true ? { preserveContext: true } : {}),
 				...(!checkpointSeen && owner === sessionId && typeof persistenceError === "string" && persistenceError.trim().length > 0 ? { persistenceError } : {}),
+				...(mode === "passive" || mode === "off" ? { mode } : {}),
 			};
 		} catch {
 			// A hostile unrelated branch entry cannot manufacture or suppress a valid marker.

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

@@ -13,8 +13,25 @@ export class RevisionUnavailableError extends Error {}
 /** Expired history cannot be restored, but explicit activation may use validated current memory. */
 export class HistoryBoundaryExpiredError extends RevisionUnavailableError {}
 
+export type StateFlowMode = "active" | "passive" | "off";
+export type InactiveMode = Exclude<StateFlowMode, "active">;
+
+export function isStateFlowMode(value: unknown): value is StateFlowMode {
+	return value === "active" || value === "passive" || value === "off";
+}
+
+/** The session's selected mode is the only serialized behavior switch. */
 export interface SnapshotConfig {
-	enabled: boolean;
+	mode: StateFlowMode;
+}
+
+/**
+ * Read-only compatibility for session config and native checkpoints written before `mode`:
+ * `enabled:true` stays active; `enabled:false` stays the caller's inactive policy.
+ */
+function decodeLegacyMode(value: JsonObject, inactiveMode: InactiveMode): StateFlowMode | undefined {
+	if (Object.hasOwn(value, "mode")) return Object.hasOwn(value, "enabled") || !isStateFlowMode(value.mode) ? undefined : value.mode;
+	return typeof value.enabled === "boolean" ? value.enabled ? "active" : inactiveMode : undefined;
 }
 
 interface LegacyValidationFeedback {
@@ -69,7 +86,7 @@ export function validateSessionRuntime(value: unknown, cwd: string, sessionId: s
 	}
 	const runtimeFields = Object.fromEntries(Object.entries(fields).filter(([key]) => known.has(key)));
 	const normalized: Snapshot = {
-		config: { enabled: value.config.enabled === true },
+		config: { mode: isStateFlowMode(value.config.mode) ? value.config.mode : "off" },
 		meta: restoredMeta(runtimeFields),
 	};
 	if (runtimeFields.bootstrap === false) normalized.meta.bootstrap = false;
@@ -108,6 +125,7 @@ export function serializeSessionRuntime(
 	return { config: `${canonicalJson(runtime.config)}\n`, runtime: `${canonicalJson(runtimeMeta)}\n` };
 }
 
+/** Legacy `enabled:false` decodes as non-active; native checkpoints, not this file, select branch policy. */
 export function parseSessionRuntime(
 	config: string | undefined, runtimeSource: string | undefined, cwd: string, sessionId: string,
 ): SessionRuntime | undefined {
@@ -115,13 +133,17 @@ export function parseSessionRuntime(
 	if (config === undefined || runtimeSource === undefined) throw new Error("Incomplete State Flow config/runtime pair");
 	let runtime: unknown;
 	try {
-		runtime = { config: JSON.parse(config), meta: JSON.parse(runtimeSource) };
-	} catch {
-		throw new Error("State Flow session runtime contains invalid JSON");
+		const settings: unknown = JSON.parse(config);
+		const mode = isObject(settings) && Object.keys(settings).length === 1 ? decodeLegacyMode(settings, "passive") : undefined;
+		if (mode === undefined) throw new Error("Invalid State Flow runtime configuration or counters");
+		runtime = { config: { mode }, meta: JSON.parse(runtimeSource) };
+	} catch (error) {
+		if (error instanceof SyntaxError) throw new Error("State Flow session runtime contains invalid JSON");
+		throw error;
 	}
 	validateSessionRuntime(runtime, cwd, sessionId);
 	const { temporal: _legacyTemporal, ...runtimeMeta } = runtime.meta;
-	return { config: { enabled: runtime.config.enabled }, meta: runtimeMeta };
+	return { config: { mode: runtime.config.mode }, meta: runtimeMeta };
 }
 
 function restoredStep(value: unknown): number {
@@ -158,22 +180,24 @@ function restoredMeta(value: unknown, legacy: JsonObject = {}): SnapshotMeta {
 	};
 }
 
-function envelope(enabled: boolean, meta: SnapshotMeta): Snapshot {
-	return { config: { enabled }, meta };
+function envelope(mode: StateFlowMode, meta: SnapshotMeta): Snapshot {
+	return { config: { mode }, meta };
 }
 
-export function emptySnapshot(enabled = false): Snapshot {
-	return envelope(enabled, { step: 0 });
+export function emptySnapshot(mode: StateFlowMode = "passive"): Snapshot {
+	return envelope(mode, { step: 0 });
 }
 
 export type RetainedBoundaryCheckpoint = {
 	boundary: string;
-	enabled: boolean;
+	mode: StateFlowMode;
 	step: number;
 	bootstrap?: true;
 	specification?: string;
 };
-export type RetainedPiCheckpoint = RetainedBoundaryCheckpoint | { disabled: true };
+/** A proven pre-runtime branch retains only its explicit inactive choice, never semantic storage. */
+export type PreRuntimeCheckpoint = { mode: InactiveMode };
+export type RetainedPiCheckpoint = RetainedBoundaryCheckpoint | PreRuntimeCheckpoint;
 export type FileRevision = `file:${string}`;
 
 export function isFileRevision(value: unknown): value is FileRevision {
@@ -185,7 +209,7 @@ export function retainedBoundaryCheckpoint(snapshot: Snapshot, boundary: string)
 	if (typeof boundary !== "string" || boundary.trim().length === 0) throw new Error("Checkpoint requires a retained temporal boundary identity");
 	const checkpoint: RetainedBoundaryCheckpoint = {
 		boundary,
-		enabled: snapshot.config.enabled,
+		mode: snapshot.config.mode,
 		step: snapshot.meta.step,
 		...(snapshot.meta.bootstrap === true ? { bootstrap: true as const } : {}),
 		...(snapshot.meta.specification === undefined ? {} : { specification: snapshot.meta.specification }),
@@ -193,14 +217,23 @@ export function retainedBoundaryCheckpoint(snapshot: Snapshot, boundary: string)
 	return parseRetainedPiCheckpoint(checkpoint) as RetainedBoundaryCheckpoint;
 }
 
-/** Decode the 0.17 retained-window checkpoint contract. */
-export function parseRetainedPiCheckpoint(value: unknown): RetainedPiCheckpoint {
+/** Encode an explicit inactive choice on a branch that has no accepted runtime. */
+export function preRuntimeCheckpoint(mode: StateFlowMode): PreRuntimeCheckpoint {
+	if (mode === "active") throw new Error("An active State Flow branch requires a retained semantic boundary");
+	return { mode };
+}
+
+/** Decode the retained-window checkpoint contract; legacy `enabled`/`{disabled:true}` markers map through `inactiveMode`. */
+export function parseRetainedPiCheckpoint(value: unknown, inactiveMode: InactiveMode = "passive"): RetainedPiCheckpoint {
 	if (!isObject(value)) throw new Error("Invalid State Flow retained-boundary checkpoint");
-	if (Object.keys(value).length === 1 && value.disabled === true) return { disabled: true };
-	const allowed = new Set(["boundary", "enabled", "step", "bootstrap", "specification"]);
-	if (Object.keys(value).some((key) => !allowed.has(key))
+	const keys = Object.keys(value);
+	if (keys.length === 1 && value.disabled === true) return { mode: inactiveMode };
+	if (keys.length === 1 && (value.mode === "passive" || value.mode === "off")) return { mode: value.mode };
+	const allowed = new Set(["boundary", "mode", "enabled", "step", "bootstrap", "specification"]);
+	const mode = decodeLegacyMode(value, inactiveMode);
+	if (keys.some((key) => !allowed.has(key))
 		|| typeof value.boundary !== "string" || value.boundary.trim().length === 0
-		|| typeof value.enabled !== "boolean"
+		|| mode === undefined
 		|| !Number.isSafeInteger(value.step) || (value.step as number) < 0 || (value.step as number) > MAX_RESTORED_STEP
 		|| (value.bootstrap !== undefined && value.bootstrap !== true)
 		|| (value.specification !== undefined && typeof value.specification !== "string")) {
@@ -208,19 +241,19 @@ export function parseRetainedPiCheckpoint(value: unknown): RetainedPiCheckpoint
 	}
 	return {
 		boundary: value.boundary,
-		enabled: value.enabled,
+		mode,
 		step: value.step as number,
 		...(value.bootstrap === true ? { bootstrap: true } : {}),
 		...(typeof value.specification === "string" ? { specification: value.specification } : {}),
 	};
 }
 
-export function migrationFailure(data: JsonObject, error: string): Snapshot {
+export function migrationFailure(data: JsonObject, error: string, mode: InactiveMode = "passive"): Snapshot {
 	const meta = restoredMeta(data.meta, data);
 	meta.validation = {
 		attempt: 0,
 		error,
 		instruction: "Start a fresh State Flow episode; null is reserved for patch deletion.",
 	};
-	return envelope(false, meta);
+	return envelope(mode, meta);
 }

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

@@ -8,7 +8,7 @@ import {
 } from "./artifact.ts";
 import { applyPatch, isObject, type JsonObject } from "./json.ts";
 
-/** The canonical semantic state shape shared by global, CWD, and session scopes. */
+/** Runtime defaults for documented semantic planes; stored objects may omit them or retain other fields. */
 export type MaterializedState = JsonObject & {
 	intents: JsonObject;
 	contract: JsonObject;
@@ -18,6 +18,17 @@ export type MaterializedState = JsonObject & {
 	lazy: JsonObject;
 };
 
+/** Sparse semantic state: documented planes may be absent. Disk codecs select only known fields. */
+export type SemanticState = JsonObject & Partial<{
+	intents: JsonObject;
+	contract: JsonObject;
+	working: JsonObject;
+	artifacts: ArtifactRegistry;
+	response: string;
+	lazy: JsonObject;
+}>;
+export type ScopedSemanticStates = Record<StateScope, SemanticState>;
+
 /** Compatibility name for callers that still treat materialized state as a document. */
 export type StateDocument = MaterializedState;
 
@@ -79,8 +90,12 @@ export function isMaterializedState(value: unknown): value is MaterializedState
 		&& isObject(value.working)
 		&& isObject(value.intents)
 		&& typeof value.response === "string"
-		&& isObject(value.lazy)
-		&& Object.keys(value).every((key) => key === "artifacts" || key === "contract" || key === "working" || key === "intents" || key === "response" || key === "lazy");
+		&& isObject(value.lazy);
+}
+
+/** Missing planes are valid storage, not missing authority. Present values retain their type checks. */
+export function isSemanticState(value: unknown): value is SemanticState {
+	return isObject(value) && isMaterializedState({ ...emptyState(), ...value });
 }
 
 export const isStateDocument = isMaterializedState;
@@ -97,12 +112,13 @@ export function updateMaterializedArtifacts(
 }
 
 /** Overlay lower-to-higher scopes without mutating any scope document. */
-export function overlayStates(...scopes: readonly MaterializedState[]): MaterializedState {
+export function overlayStates(...scopes: readonly JsonObject[]): MaterializedState {
 	return scopes.reduce<MaterializedState>((effective, scope) => {
 		return applyPatch(effective, scope) as MaterializedState;
 	}, emptyState());
 }
 
+/** Default-bearing SDK compatibility view; model transport uses sparse SemanticState instead. */
 export type ModelState = JsonObject & {
 	intents: JsonObject;
 	contract: JsonObject;
@@ -111,14 +127,31 @@ export type ModelState = JsonObject & {
 	response: string;
 };
 
+/** Select only owned top-level fields, preserving nested data and replay deletion markers. */
+export function selectSemanticFields(value: JsonObject): JsonObject {
+	return structuredClone(Object.fromEntries(Object.keys(emptyState())
+		.filter((key) => Object.hasOwn(value, key))
+		.map((key) => [key, value[key]])));
+}
+
+/** Read only documented, present planes; empty responses carry no semantic value. */
+export function projectSemanticState(state: JsonObject): SemanticState {
+	const projected = selectSemanticFields(state);
+	if (projected.response === "") delete projected.response;
+	return projected;
+}
+
+/** Preserve deletion meaning in visible history without exposing ignored fields or empty responses. */
+export function projectSemanticPatch(patch: JsonObject): JsonObject {
+	const projected = selectSemanticFields(patch);
+	if (projected.response === "") projected.response = null;
+	return projected;
+}
+
 /** Model-visible projection: lazy bodies and runtime artifact bookkeeping stay out of ordinary context. */
-export function projectStateForModel(state: MaterializedState, artifactHints: ArtifactModelHints = {}): ModelState {
-	const cloned = structuredClone(state);
-	return {
-		intents: cloned.intents,
-		contract: cloned.contract,
-		working: cloned.working,
-		artifacts: projectArtifactsForModel(cloned.artifacts, artifactHints),
-		response: cloned.response,
-	};
+export function projectStateForModel(state: SemanticState, artifactHints: ArtifactModelHints = {}): SemanticState {
+	const { lazy: _hidden, ...visible } = state;
+	const projected = projectSemanticState(visible);
+	if (projected.artifacts) projected.artifacts = projectArtifactsForModel(projected.artifacts, artifactHints);
+	return projected;
 }