@llblab/pi-kit 0.24.1 → 0.25.0

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

@@ -1,9 +1,8 @@
 import type { ArtifactInvalidationReason } from "./artifact.ts";
-import { projectRecentTransitionsWithLimit, type RecentTransitionWindow } from "./history.ts";
-import { retainedMemoryScopes } from "./memory.ts";
+import type { RecentTransitionWindow } from "./history.ts";
 import { conciseDiagnostic } from "./protocol.ts";
 import type { Snapshot } from "./snapshot.ts";
-import { overlayStates, type ScopedStates, type StateScope } from "./state.ts";
+import { overlayStates, projectSemanticState, type SemanticState, type ScopedStates, type StateScope } from "./state.ts";
 import type { ScopeRevisions, TransitionBoundary } from "./temporal.ts";
 
 export const STATUS_KEY = "state-flow";
@@ -23,6 +22,8 @@ export interface StatusDiagnostics {
 	cwdScopeKey: string;
 	sessionScopeKey: string;
 	scopeStates: ScopedStates;
+	/** Overlay raw scopes before defaults so absent scalar planes cannot mask lower scopes. */
+	effectiveState?: SemanticState;
 	recent: RecentTransitionWindow;
 	historyLimit: number;
 	temporal?: { head: TransitionBoundary; historyDepth: number; tailCounts: Record<StateScope, number>; revisions: ScopeRevisions };
@@ -32,12 +33,13 @@ export interface StatusDiagnostics {
 }
 
 export function formatScopeRevisionVector(revisions: ScopeRevisions): string {
-	return `G${revisions.global}/C${revisions.cwd}/S${revisions.session}`;
+	return `g${revisions.global}c${revisions.cwd}s${revisions.session}`;
 }
 
-export function compactStatus(snapshot: Snapshot, revisions: ScopeRevisions, colorize: Colorize): string | undefined {
-	if (!snapshot.config.enabled) return undefined;
-	return `${colorize("accent", "state-flow")} ${colorize("dim", formatScopeRevisionVector(revisions))}`;
+export function compactStatus(snapshot: Snapshot, _revisions: ScopeRevisions, colorize: Colorize): string | undefined {
+	const { mode } = snapshot.config;
+	if (mode === "off") return undefined;
+	return `${colorize("accent", "state-flow")} ${colorize("dim", mode)}`;
 }
 
 function countArtifacts(states: ScopedStates, scope: StateScope): number {
@@ -45,20 +47,17 @@ function countArtifacts(states: ScopedStates, scope: StateScope): number {
 }
 
 export function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostics): string {
-	const projectedRecent = projectRecentTransitionsWithLimit(
-		diagnostics.historyLimit,
-		diagnostics.recent,
-	);
 	const available = diagnostics.temporal !== undefined && diagnostics.durableStateError === undefined;
-	const materialized = !available ? undefined : overlayStates(
+	const materialized = !available ? undefined : diagnostics.effectiveState ?? projectSemanticState(overlayStates(
 		diagnostics.scopeStates.global,
 		diagnostics.scopeStates.cwd,
 		diagnostics.scopeStates.session,
-	);
-	const stateJson = materialized === undefined ? undefined : JSON.stringify(materialized, null, 2);
+	));
+	// Only top-level plane boundaries gain whitespace; nested user JSON stays unchanged.
+	const stateJson = materialized === undefined ? undefined : JSON.stringify(materialized, null, 2).replace(/,\n(?=  ")/g, ",\n\n");
 	const invalidated = available ? String(diagnostics.staleArtifacts.length) : "unavailable";
 	const invalidationLines = diagnostics.staleArtifacts.length === 0
-		? ["Pending artifact invalidations: none"]
+		? []
 		: [
 			"Pending artifact invalidations:",
 			...diagnostics.staleArtifacts.map(({ scope, path, reason }) => `- [${scope}] ${path} — ${reason}`),
@@ -66,30 +65,22 @@ export function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostic
 	const temporal = available ? diagnostics.temporal : undefined;
 	const temporalLines = temporal === undefined
 		? [`Temporal materialization unavailable: ${conciseDiagnostic(diagnostics.durableStateError ?? "no selected branch runtime")}`,
-			`Hot history: unavailable; configured maximum depth ${diagnostics.historyLimit}`,
-			"Retained patch tails: unavailable"]
-		: [`Temporal head: ${JSON.stringify(temporal.head.id)}; branch-local position ${temporal.head.position}`,
-			`Scope revisions: global #${temporal.revisions.global}; CWD #${temporal.revisions.cwd}; session #${temporal.revisions.session}; effective ${formatScopeRevisionVector(temporal.revisions)}`,
-			`Hot history: offsets 0..${temporal.historyDepth}; maximum depth ${diagnostics.historyLimit}`,
-			`Retained patch tails: global ${temporal.tailCounts.global}; CWD ${temporal.tailCounts.cwd}; session ${temporal.tailCounts.session}`];
-	const artifacts = (scope: StateScope) => available ? countArtifacts(diagnostics.scopeStates, scope) : "unknown";
-	const memoryScopes = available ? retainedMemoryScopes(diagnostics.scopeStates) : undefined;
+			`Hot history: unavailable; configured maximum depth ${diagnostics.historyLimit}`]
+		: [`Scope revisions: ${formatScopeRevisionVector(temporal.revisions)}`,
+			`Runtime metadata: step #${snapshot.meta.step}${snapshot.meta.bootstrap ? "; bootstrap" : ""}`,
+			`Hot history: offsets 0..${temporal.historyDepth}; maximum depth ${diagnostics.historyLimit}`];
+	const artifacts = (scope: StateScope) => countArtifacts(diagnostics.scopeStates, scope);
+	const hasArtifacts = available && (["global", "cwd", "session"] as const).some((scope) => artifacts(scope) > 0);
 
 	return [
-		`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; runtime.json owns branch recovery; meta.json owns scope provenance",
-		`Runtime metadata: step #${snapshot.meta.step}; bootstrap ${snapshot.meta.bootstrap === true}`,
-		"Memory: owner state-flow; global retention enabled; global fallback active",
-		`Memory-bearing scopes: global ${memoryScopes?.global ?? "unknown"}; CWD ${memoryScopes?.cwd ?? "unknown"}; session ${memoryScopes?.session ?? "unknown"}`,
 		...temporalLines,
-		...(diagnostics.publicationError === undefined ? [] : [`Memory writes paused after Stop: ${conciseDiagnostic(diagnostics.publicationError)}`]),
-		`Artifacts: global ${artifacts("global")}; CWD ${artifacts("cwd")}; session ${artifacts("session")}; pending invalidations ${invalidated}`,
-		available ? `Recent transitions: global ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "global")).length}; CWD ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "cwd")).length}; session ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "session")).length}; active ${projectedRecent.length}` : "Recent transitions: unavailable",
+		...(diagnostics.publicationError === undefined ? [] : [`Memory writes paused after mode change: ${conciseDiagnostic(diagnostics.publicationError)}`]),
+		...(hasArtifacts ? [`Artifacts: global ${artifacts("global")}; CWD ${artifacts("cwd")}; session ${artifacts("session")}; pending invalidations ${invalidated}`] : []),
 		...invalidationLines,
 		...(stateJson === undefined
 			? ["Effective memory: unavailable"]
-			: [`Effective memory (${Buffer.byteLength(stateJson, "utf8")} JSON bytes; global → CWD → session overlay):`, "", stateJson]),
+			: ["Effective memory:", "", stateJson]),
 	].join("\n");
 }

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

@@ -4,6 +4,7 @@
 // pi-telegram is absent or its registry is not ready, registration fails open and retries.
 
 import { conciseDiagnostic, diagnosticText } from "./protocol.ts";
+import type { StateFlowMode } from "./snapshot.ts";
 import { formatScopeRevisionVector } from "./status.ts";
 import type { ScopeRevisions } from "./temporal.ts";
 
@@ -18,7 +19,8 @@ export function stateFlowTelegramSectionSpecifiers(moduleUrl = import.meta.url):
 }
 
 export interface StateFlowTelegramSnapshot {
-	enabled: boolean;
+	/** The current session's selected mode. */
+	mode: StateFlowMode;
 	/** Legacy branch step retained for existing adapter ports; current runtime ports also supply owner revisions. */
 	step: number;
 	revisions?: ScopeRevisions;
@@ -29,11 +31,11 @@ export interface StateFlowTelegramSnapshot {
 export type StateFlowTelegramScope = "global" | "cwd" | "session" | "effective";
 
 export interface StateFlowTelegramState {
-	artifacts: Record<string, unknown>;
-	contract: Record<string, unknown>;
-	working: Record<string, unknown>;
-	intents: Record<string, unknown>;
-	response: string;
+	artifacts?: Record<string, unknown>;
+	contract?: Record<string, unknown>;
+	working?: Record<string, unknown>;
+	intents?: Record<string, unknown>;
+	response?: string;
 	lazy?: unknown;
 }
 
@@ -110,17 +112,17 @@ export interface StateFlowTelegramPort {
 	state(scope: StateFlowTelegramScope): StateFlowTelegramState;
 	/** Optional additive capability; absent legacy ports retain their branch-step presentation. */
 	revisions?(): ScopeRevisions;
+	/** Active may need a settled native boundary; inactive modes apply immediately. */
 	canStartNow(): boolean;
-	start(): StateFlowTelegramControlResult;
-	stop(): StateFlowTelegramControlResult;
+	/** Select the current session's mode through the same lifecycle owners as the terminal commands. */
+	select(mode: StateFlowMode): StateFlowTelegramControlResult;
 	deferStart(): void;
 	cancelStart(): void;
 }
 
-export interface StateFlowTelegramInspectionPort extends Omit<StateFlowTelegramPort, "state" | "revisions" | "start" | "stop"> {
+export interface StateFlowTelegramInspectionPort extends Omit<StateFlowTelegramPort, "state" | "revisions" | "select"> {
 	inspect(scope: StateFlowTelegramScope): StateFlowTelegramInspection | Promise<StateFlowTelegramInspection>;
-	start(): StateFlowTelegramControlResult | Promise<StateFlowTelegramControlResult>;
-	stop(): StateFlowTelegramControlResult | Promise<StateFlowTelegramControlResult>;
+	select(mode: StateFlowMode): StateFlowTelegramControlResult | Promise<StateFlowTelegramControlResult>;
 }
 
 export interface StateFlowTelegramAdapter {
@@ -128,41 +130,56 @@ export interface StateFlowTelegramAdapter {
 	dispose(): void;
 }
 
-/** Main-menu section label doubles as the live status value: the spiral identity is constant, the value is not. */
+/** Main-menu section label shows only the current session mode. */
 export function formatStateFlowSectionLabel(snapshot: StateFlowTelegramSnapshot): string {
-	if (!snapshot.enabled) return "🌀 State Flow: off";
-	return `🌀 State Flow: ${snapshot.revisions ? formatScopeRevisionVector(snapshot.revisions) : `#${snapshot.step}`}`;
+	return `🌀 State Flow: ${snapshot.mode}`;
 }
 
-/** Shared live value: plain in the button label, monospaced in the submenu state line. */
-function stateFlowLabelValue(snapshot: StateFlowTelegramSnapshot): string {
-	if (!snapshot.enabled) return "off";
-	return snapshot.revisions ? formatScopeRevisionVector(snapshot.revisions) : `#${snapshot.step}`;
-}
+export const STATE_FLOW_MODES = ["off", "passive", "active"] as const satisfies readonly StateFlowMode[];
+const STATE_FLOW_MODE_LABELS: Record<StateFlowMode, string> = { off: "Off", passive: "Passive", active: "Active" };
+const STATE_FLOW_SELECTED_MARKERS: Record<StateFlowMode, string> = { off: "🟡", passive: "🟣", active: "🟢" };
 
-/** Submenu state line: the same identity as the button label, with the live value in monospace. */
-function formatStateFlowSectionHeader(snapshot: StateFlowTelegramSnapshot): string {
-	return `<b>🌀 State Flow: <code>${stateFlowLabelValue(snapshot)}</code></b>`;
+function isStateFlowModeAction(value: string): value is StateFlowMode {
+	return (STATE_FLOW_MODES as readonly string[]).includes(value);
 }
 
-/** Short help under the state line: what State Flow is and why its action button exists. */
-const STATE_FLOW_SECTION_HELP =
-	"Accepted memory remains visible in active and passive modes. Start or Stop changes episode behavior, not state access.";
+function modeReceiptNotice(mode: StateFlowMode, result: StateFlowTelegramControlResult): string | undefined {
+	if (result.ok && (result.message === `State Flow ${mode}` || result.message === `State Flow is already ${mode}`)) return undefined;
+	return result.message;
+}
 
-/** The submenu header repeats the button's state line; the single action matches the current state. */
+/** One radio-style mode row followed directly by read-only scope actions. */
 export function buildStateFlowSectionView(
 	snapshot: StateFlowTelegramSnapshot,
-	callbackData: (action: string) => string,
+	callbackData: (action: string, payload?: string) => string,
 ): StateFlowTelegramView {
-	const action: StateFlowTelegramButton = snapshot.enabled
-		? { text: "⏹ Stop", callback_data: callbackData("stop") }
-		: { text: "▶️ Start", callback_data: callbackData("start") };
+	const modes: StateFlowTelegramButton[] = STATE_FLOW_MODES.map((mode) => ({
+		text: `${mode === snapshot.mode ? STATE_FLOW_SELECTED_MARKERS[mode] : "⚫️"} ${STATE_FLOW_MODE_LABELS[mode]}`,
+		callback_data: callbackData(mode),
+	}));
 	return {
-		text: [formatStateFlowSectionHeader(snapshot), "", STATE_FLOW_SECTION_HELP].join("\n"),
+		text: [
+			`<b>🌀 State Flow:</b> <code>${snapshot.mode}</code>`,
+			"",
+			"<b>Mode</b> — choose a workflow (switching modes never erases stored memory):",
+			"",
+			"<code>-</code> <code>off</code> (default): regular chat without State Flow memory tools or context.",
+			"<code>-</code> <code>passive</code>: regular chat with memory tools; available combined memory enters the agent's context.",
+			"<code>-</code> <code>active</code>: same memory access; each completed answer closes a cycle, and the next request starts from saved state, not the full chat.",
+			"",
+			"<b>Inspect memory</b> — view stored state even in Off:",
+			"",
+			"<code>-</code> <code>global</code>: memory shared across projects and sessions.",
+			"<code>-</code> <code>cwd</code>: memory shared by sessions in this directory.",
+			"<code>-</code> <code>session</code>: private memory for this session, kept on resume.",
+			"<code>-</code> <code>effective</code>: merged Global, CWD and Session state; the agent can use it when memory is enabled and available.",
+		].join("\n"),
 		parseMode: "html",
 		replyMarkup: { inline_keyboard: [
-			[action],
-			[{ text: "👁 Show state", callback_data: callbackData("show-state") }],
+			modes,
+			...([["global", "cwd"], ["session", "effective"]] as const).map((row) => row.map((scope) => ({
+				text: STATE_FLOW_SCOPE_LABELS[scope], callback_data: callbackData("inspect", scope),
+			}))),
 		] },
 	};
 }
@@ -174,18 +191,6 @@ const STATE_FLOW_SCOPE_LABELS: Record<StateFlowTelegramScope, string> = {
 	effective: "🧬 Effective",
 };
 
-export function buildStateFlowScopeChooser(callbackData: (action: string, payload?: string) => string): StateFlowTelegramView {
-	return {
-		text: "<b>👁 Show state:</b>",
-		parseMode: "html",
-		replyMarkup: { inline_keyboard: [
-			...(["global", "cwd", "session", "effective"] as const).map((scope) => [
-				{ text: STATE_FLOW_SCOPE_LABELS[scope], callback_data: callbackData("inspect", scope) },
-			]),
-		] },
-	};
-}
-
 // The complete message serializes each preformatted field one additional time;
 // 3,000 leaves safe headroom for worst-case JSON escaping across all four fields.
 const STATE_FLOW_TELEGRAM_FIELD_MAX_CHARS = 3_000;
@@ -230,10 +235,10 @@ export function renderStateFlowRichState(scope: StateFlowTelegramScope, revision
 				text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text: revision }],
 				size: 3,
 			},
-			...fields.map((field) => ({
+			...fields.filter((field) => state[field] !== undefined && state[field] !== "").map((field) => ({
 				type: "details" as const,
 				summary: { type: "code" as const, text: field },
-				blocks: [{ type: "pre" as const, language: "json", text: renderStateFlowTelegramField(state[field] ?? {}) }],
+				blocks: [{ type: "pre" as const, language: "json", text: renderStateFlowTelegramField(state[field]) }],
 			})),
 		],
 		skip_entity_detection: true,
@@ -251,19 +256,15 @@ function buildStateFlowTelegramSection(port: StateFlowTelegramPort | StateFlowTe
 		label: "🌀 State Flow",
 		getLabel: () => formatStateFlowSectionLabel(port.snapshot()),
 		render: (ctx: StateFlowTelegramSectionContext) =>
-			buildStateFlowSectionView(port.snapshot(), (action) => ctx.callbackData(action)),
+			buildStateFlowSectionView(port.snapshot(), (action, payload) => ctx.callbackData(action, payload)),
 		handleCallback: async (ctx: StateFlowTelegramCallbackContext) => {
-			// cancel/refresh remain routable for keyboards sent by earlier versions.
-			if (ctx.action !== "start" && ctx.action !== "stop" && ctx.action !== "cancel" && ctx.action !== "refresh" && ctx.action !== "show-state" && ctx.action !== "inspect" && ctx.action !== "back") return "pass" as const;
+			// Keyboards sent by earlier versions re-render (start/stop/refresh) or withdraw deferral (cancel); they change no mode.
+			const legacy = ctx.action === "start" || ctx.action === "stop" || ctx.action === "cancel" || ctx.action === "refresh";
+			if (!isStateFlowModeAction(ctx.action) && !legacy && ctx.action !== "show-state" && ctx.action !== "inspect" && ctx.action !== "back") return "pass" as const;
 			const request = ++interaction;
 			let notice: string | undefined;
 			let acknowledged = false;
 			try {
-				if (ctx.action === "show-state") {
-					await ctx.answerCallback();
-					await ctx.edit(buildStateFlowScopeChooser((action, payload) => ctx.callbackData(action, payload)));
-					return "handled" as const;
-				}
 				if (ctx.action === "inspect") {
 					if (!isStateFlowTelegramScope(ctx.payload)) throw new Error("Unknown State Flow scope");
 					let observation: StateFlowTelegramInspection;
@@ -282,21 +283,21 @@ function buildStateFlowTelegramSection(port: StateFlowTelegramPort | StateFlowTe
 					if (!acknowledged) await ctx.answerCallback();
 					return "handled" as const;
 				}
-				const action = ctx.action === "stop" || (ctx.action === "start" && port.canStartNow()) ? ctx.action : undefined;
-				if (action) {
+				const mode = isStateFlowModeAction(ctx.action) && (ctx.action !== "active" || port.canStartNow()) ? ctx.action : undefined;
+				if (mode) {
 					if ("inspect" in port) {
 						acknowledged = true;
-						// Start the control immediately and acknowledge in parallel; neither promise can reject unobserved.
+						// Apply the control immediately and acknowledge in parallel; neither promise can reject unobserved.
 						const [, result] = await Promise.all([
-							ctx.answerCallback(action === "stop" ? "Stopping State Flow" : "Starting State Flow"),
-							Promise.resolve().then(() => port[action]()),
+							ctx.answerCallback(`Switching State Flow to ${mode}`),
+							Promise.resolve().then(() => port.select(mode)),
 						]);
 						if (result.signal?.aborted) return "handled" as const;
-						notice = result.message;
-					} else notice = port[action]().message;
-				} else if (ctx.action === "start") {
+						notice = modeReceiptNotice(mode, result);
+					} else notice = modeReceiptNotice(mode, port.select(mode));
+				} else if (ctx.action === "active") {
 					port.deferStart();
-					notice = "State Flow will start after the current turn";
+					notice = "State Flow will become active after the current turn";
 				} else if (ctx.action === "cancel") {
 					port.cancelStart();
 					notice = "Pending start cancelled";
@@ -306,7 +307,7 @@ function buildStateFlowTelegramSection(port: StateFlowTelegramPort | StateFlowTe
 			}
 			if (request !== interaction || !isActive()) return "handled" as const;
 			const summary = notice === undefined ? undefined : conciseDiagnostic(notice, 200);
-			const view = buildStateFlowSectionView(port.snapshot(), (action) => ctx.callbackData(action));
+			const view = buildStateFlowSectionView(port.snapshot(), (action, payload) => ctx.callbackData(action, payload));
 			if (acknowledged && summary !== undefined) {
 				// Callback queries can expire during storage waits; retain errors in the existing menu instead.
 				view.text += `\n\n${summary.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")}`;

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

@@ -1,6 +1,6 @@
 import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT, validateRecentTransition, type RecentScopePatch } from "./history.ts";
 import { applyPatch, containsNull, isJsonValue, isObject, sameJson, type JsonObject } from "./json.ts";
-import { isMaterializedState, overlayStates, type MaterializedState, type ScopedStates, type StateScope } from "./state.ts";
+import { emptyState, isSemanticState, overlayStates, projectSemanticState, type MaterializedState, type SemanticState, type ScopedSemanticStates, type StateScope } from "./state.ts";
 
 /** Owns hot temporal algebra; excludes filesystem, Git, identity allocation, and Pi lifecycle. */
 export interface TransitionBoundary {
@@ -12,7 +12,7 @@ export interface TransitionBoundary {
 
 export interface ScopeCheckpoint {
 	through: TransitionBoundary;
-	state: MaterializedState;
+	state: SemanticState;
 }
 
 export interface TemporalPatch {
@@ -52,15 +52,20 @@ function validateBoundary(boundary: TransitionBoundary): void {
 	}
 }
 
-function validateState(state: MaterializedState): void {
-	if (!isJsonValue(state) || !isMaterializedState(state) || containsNull(state)) {
-		throw new Error("Invalid temporal materialized semantic state");
-	}
+function validateState(state: JsonObject, location?: string): asserts state is SemanticState {
+	const json = isJsonValue(state);
+	const hasNull = json && isObject(state) && Object.keys(emptyState()).some((key) => containsNull(state[key]));
+	if (json && isSemanticState(state) && !hasNull) return;
+	const reason = !json ? "expected finite, acyclic JSON data"
+		: !isObject(state) ? "expected a semantic object"
+			: hasNull ? "null is not allowed"
+				: "invalid semantic fields or artifact metadata";
+	throw new Error(`Invalid temporal materialized semantic state${location ? ` in ${location}` : ""}: ${reason}`);
 }
 
-function apply(state: MaterializedState, patch: TemporalPatch["patch"]): MaterializedState {
-	const next = applyPatch(state, patch as JsonObject) as MaterializedState;
-	validateState(next);
+function apply(state: SemanticState, patch: TemporalPatch["patch"], location?: string): SemanticState {
+	const next = applyPatch(state, patch as JsonObject);
+	validateState(next, location);
 	return next;
 }
 
@@ -80,7 +85,7 @@ export function validateScopeStream(value: unknown, scope: StateScope, historyLi
 	}
 	const stream = value as unknown as ScopeStream;
 	validateBoundary(stream.checkpoint.through);
-	validateState(stream.checkpoint.state);
+	validateState(stream.checkpoint.state, `${scope} checkpoint`);
 	if (stream.patches.length > historyLimit) throw new Error(`Temporal scope tail exceeds configured history limit ${historyLimit}`);
 	if (stream.revision < stream.patches.length) throw new Error("Temporal scope revision predates its retained patch tail");
 	let previous = stream.checkpoint.through;
@@ -98,8 +103,7 @@ export function validateScopeStream(value: unknown, scope: StateScope, historyLi
 			throw new Error("Disconnected State Flow temporal ancestry");
 		}
 		validateRecentTransition({ id: record.transition.id, at: 0, transitions: [{ scope, patch: record.patch }] });
-		const next = apply(state, record.patch);
-		if (sameJson(next, state)) throw new Error("Temporal scope tail contains a semantic no-op");
+		const next = apply(state, record.patch, `${scope} tail`);
 		state = next;
 		previous = record.transition;
 		identities.add(previous.id);
@@ -193,7 +197,7 @@ export function adoptTemporalStreams(scopes: Record<StateScope, ScopeStream>, id
 }
 
 /** New or migrated state starts at a proven current boundary, with no invented past. */
-export function createTemporalState(states: ScopedStates, id: string, historyLimit = DEFAULT_HISTORY_LIMIT): TemporalState {
+export function createTemporalState(states: ScopedSemanticStates, id: string, historyLimit = DEFAULT_HISTORY_LIMIT): TemporalState {
 	const through: TransitionBoundary = { id, position: 0, parent: null };
 	const stream = (scope: StateScope): ScopeStream => ({
 		revision: 0,
@@ -205,7 +209,7 @@ export function createTemporalState(states: ScopedStates, id: string, historyLim
 	return view;
 }
 
-function scopeAt(stream: ScopeStream, boundary: TransitionBoundary): MaterializedState {
+function scopeAt(stream: ScopeStream, boundary: TransitionBoundary): SemanticState {
 	let state = structuredClone(stream.checkpoint.state);
 	for (const record of stream.patches) {
 		if (record.transition.position > boundary.position) break;
@@ -280,18 +284,34 @@ export function temporalScopeRevisions(view: TemporalState): ScopeRevisions {
 	return revisions;
 }
 
-/** Lazy scope/effective read at one shared transition boundary, never by local patch count. */
-export function readTemporalState(view: TemporalState, offset = 0, scope?: StateScope, historyLimit = DEFAULT_HISTORY_LIMIT): MaterializedState {
+function readBoundary(view: TemporalState, offset: number, historyLimit: number): TransitionBoundary {
 	validateHistoryLimit(historyLimit);
 	if (!Number.isSafeInteger(offset) || offset < 0 || offset > historyLimit) {
 		throw new Error(`State Flow hot-history offset must be an integer from 0 to ${historyLimit}`);
 	}
-	if (scope !== undefined && !SCOPES.includes(scope)) throw new Error("Unknown temporal scope");
 	validateTemporalState(view, historyLimit);
 	const boundary = view.lineage[view.lineage.length - 1 - offset];
 	if (!boundary) throw new Error("Requested history predates the proven temporal origin");
-	if (scope !== undefined) return scopeAt(view.scopes[scope], boundary);
-	return overlayStates(...SCOPES.map((owner) => scopeAt(view.scopes[owner], boundary)));
+	return boundary;
+}
+
+/** Exact scope semantics for authored staging; defaults must never become implicit writes. */
+export function readTemporalScopes(view: TemporalState, offset = 0, historyLimit = DEFAULT_HISTORY_LIMIT): ScopedSemanticStates {
+	const boundary = readBoundary(view, offset, historyLimit);
+	return { global: scopeAt(view.scopes.global, boundary), cwd: scopeAt(view.scopes.cwd, boundary), session: scopeAt(view.scopes.session, boundary) };
+}
+
+/** Sparse current/historical view: unknown planes and absent values never become effective data. */
+export function readTemporalView(view: TemporalState, offset = 0, scope?: StateScope, historyLimit = DEFAULT_HISTORY_LIMIT): SemanticState {
+	if (scope !== undefined && !SCOPES.includes(scope)) throw new Error("Unknown temporal scope");
+	const boundary = readBoundary(view, offset, historyLimit);
+	const owners = scope === undefined ? SCOPES : [scope];
+	return owners.reduce<SemanticState>((state, owner) => applyPatch(state, projectSemanticState(scopeAt(view.scopes[owner], boundary))), {});
+}
+
+/** Internal defaulted materialization for consumers that require object registries. */
+export function readTemporalState(view: TemporalState, offset = 0, scope?: StateScope, historyLimit = DEFAULT_HISTORY_LIMIT): MaterializedState {
+	return overlayStates(readTemporalView(view, offset, scope, historyLimit));
 }
 
 /** Allocate the identity outside this algebra; only materially effective patches accept it. */

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

@@ -12,12 +12,13 @@ import { createAcceptedTransition, type AcceptedTransition } from "./history.ts"
 import { applyPatch, containsNull, hashJson, isObject, validatePatch, type JsonObject } from "./json.ts";
 import { hasCompiledSkillArtifact, SKILL_ARTIFACT_COMPILER, type SuccessfulSkillRead } from "./skills.ts";
 import type { Snapshot } from "./snapshot.ts";
+import { emptyState } from "./state.ts";
 import type {
 	AtomicScopePatches,
-	MaterializedState,
+	SemanticState,
 	ScopePatch,
 	ScopedPatch,
-	ScopedStates,
+	ScopedSemanticStates,
 	SemanticTransition,
 	StateDocument,
 	StatePatch,
@@ -26,7 +27,7 @@ import type {
 } from "./state.ts";
 
 export interface StagedScopedTransition {
-	nextStates: ScopedStates;
+	nextStates: ScopedSemanticStates;
 	stateHashes: Record<StateScope, string>;
 	/** Fresh runtime-owned provenance for artifacts compiled in this transition. */
 	provenanceUpdates: Record<StateScope, Record<string, ArtifactProvenance>>;
@@ -126,7 +127,7 @@ function compileReadSkills(
 }
 
 function validateMaterializedTransition(nextState: StateDocument, scope: StateScope): void {
-	if (containsNull(nextState)) {
+	if (Object.keys(emptyState()).some((key) => containsNull(nextState[key]))) {
 		throw new Error("Materialized state cannot contain null; use null only as an object-key deletion marker");
 	}
 	validateArtifactRegistry(nextState.artifacts, `${scope}.artifacts`);
@@ -156,20 +157,9 @@ function validateScopePatch(scope: unknown, patch: unknown): asserts patch is Sc
 	if (isObject(patch.artifacts)) validateModelArtifactPatch(patch.artifacts, `${scope}.artifacts`);
 }
 
-function completePatch(patch: ScopePatch, response: string): StatePatch {
-	return {
-		artifacts: patch.artifacts ?? {},
-		contract: patch.contract ?? {},
-		working: patch.working ?? {},
-		intents: patch.intents ?? {},
-		response,
-		lazy: structuredClone(patch.lazy ?? {}),
-	};
-}
-
 /** Stage all scope updates against one immutable basis before any state is published. */
 function stageScopedSemanticTransition(
-	currentStates: ScopedStates,
+	currentStates: ScopedSemanticStates,
 	transition: SemanticTransition,
 	successfulSkillReads: Iterable<SuccessfulSkillRead>,
 	causalBasis: string,
@@ -197,19 +187,21 @@ function stageScopedSemanticTransition(
 	const provenanceUpdates: Record<StateScope, Record<string, ArtifactProvenance>> = { global: {}, cwd: {}, session: {} };
 	for (const scope of SCOPES) {
 		const authored = patches.get(scope) ?? {};
-		const response = scope === "session" && acceptedResponse !== undefined
-			? acceptedResponse
-			: currentStates[scope].response;
-		const patch = completePatch(authored, response);
-		const nextState = applyPatch(currentStates[scope], patch) as MaterializedState;
+		const patch = { ...authored, ...(scope === "session" && acceptedResponse !== undefined ? { response: acceptedResponse } : {}) };
+		const materialized = applyPatch({ ...emptyState(), ...currentStates[scope] }, patch) as StateDocument;
 		compileReadArtifacts(
-			nextState,
+			materialized,
 			{ artifacts: authored.artifacts ?? {} },
 			artifactReads.filter((read) => (read.scope ?? "global") === scope),
 			provenanceUpdates[scope],
 		);
-		compileReadSkills(scope, nextState, { artifacts: authored.artifacts ?? {} }, skillReads.filter((read) => read.scope === scope), provenanceUpdates[scope]);
-		validateMaterializedTransition(nextState, scope);
+		compileReadSkills(scope, materialized, { artifacts: authored.artifacts ?? {} }, skillReads.filter((read) => read.scope === scope), provenanceUpdates[scope]);
+		validateMaterializedTransition(materialized, scope);
+		const nextState: SemanticState = materialized;
+		for (const key of Object.keys(emptyState())) {
+			if (!Object.hasOwn(currentStates[scope], key) && !Object.hasOwn(patch, key)
+				&& !(key === "artifacts" && Object.keys(provenanceUpdates[scope]).length > 0)) delete nextState[key];
+		}
 		nextStates[scope] = nextState;
 	}
 	return {
@@ -227,7 +219,7 @@ function stageScopedSemanticTransition(
 
 /** Stage one canonical atomic scope cohort without changing the finalized response. */
 export function stageAtomicScopePatches(
-	currentStates: ScopedStates,
+	currentStates: ScopedSemanticStates,
 	patches: AtomicScopePatches,
 	successfulSkillReads: Iterable<SuccessfulSkillRead>,
 	causalBasis: string,
@@ -251,7 +243,7 @@ export function stageAtomicScopePatches(
 }
 
 export function stageScopedTransition(
-	currentStates: ScopedStates,
+	currentStates: ScopedSemanticStates,
 	transition: TerminalTransition,
 	successfulSkillReads: Iterable<SuccessfulSkillRead>,
 	causalBasis: string,
@@ -278,7 +270,7 @@ export interface CommitScopedTransitionOptions {
 
 export function commitScopedTransition(
 	snapshot: Snapshot,
-	states: ScopedStates,
+	states: ScopedSemanticStates,
 	stage: StagedScopedTransition,
 	publishDurable: (accepted: AcceptedTransition | undefined, nextSnapshot: Snapshot) => void,
 	causalBasis: string,

package/node_modules/@llblab/pi-state-flow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "private": false,
   "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
   "keywords": [
@@ -76,7 +76,7 @@
     "@earendil-works/pi-ai": "0.87.0",
     "@earendil-works/pi-coding-agent": "0.87.0",
     "@earendil-works/pi-tui": "0.87.0",
-    "@types/node": "latest",
-    "typescript": "latest"
+    "@types/node": "^26.4.0",
+    "typescript": "^7.0.2"
   }
 }

package/node_modules/@llblab/pi-state-flow/skills/state-flow-guide/SKILL.md

@@ -15,7 +15,7 @@ State Flow's on-demand operational reference. Resolve the usage question or iden
 
 Passive tools access memory without starting an episode. Missing tools or storage are blockers, not permission to enable an episode or bypass storage; explanation alone remains possible.
 
-Operator commands: `/state-flow-status` inspects; `/state-flow-start` enables the current branch; `/state-flow-stop` ends active semantics without erasing memory or necessarily disabling passive tools.
+Operator commands: `/state-flow-status` inspects; `/state-flow-active` selects state-driven episodes; `/state-flow-passive` selects ordinary conversation with both memory tools and existing-state projection; `/state-flow-off` removes both tools and all State Flow context, including frozen handoffs, without deleting memory. Commands and Telegram change only the current session's `mode`. Global `mode` defaults to Off for new sessions and never overrides retained choices. Do not change mode without operator authorization.
 
 ## Map
 
@@ -56,7 +56,7 @@ Call `patch_state` alone per assistant response; await acceptance before depende
 
 The runtime waits cancelably for publication ownership, then applies authored Global/CWD operations to current canonical values. Untouched fields survive; overlapping targets follow successful acceptance order. Correct repeats succeed as `State already current.` without another semantic revision. Do not repeat external actions during a memory wait, or rebuild an entire scope from an older snapshot. Session ownership/history fences remain private, not a universal merge.
 
-Semantic planes `intents`, `contract`, `working`, `artifacts`, and the required `lazy` root are objects; nested lazy values may contain ordinary JSON without stored nulls. Objects merge, arrays/scalars replace, omitted fields persist. Nested `null` removes an owned object key; inherited content may reappear. Canonical `"[N]"` keys patch array elements; indexed deletion is forbidden.
+When present, semantic planes `intents`, `contract`, `working`, `artifacts`, and `lazy` are objects; nested lazy values may contain ordinary JSON without stored nulls. Stored checkpoints and patches may omit any documented plane. Current and historical views assemble only known fields present in the selected scopes. Absent fields and empty responses are omitted from views. Checkpoint/tail readers ignore unknown top-level fields, and writers emit only known fields. Nested data within known planes remains intact. Explicit value reads of an absent documented top-level field return `null`. Authored `patch_state` keeps its documented field grammar. Objects merge, arrays/scalars replace, omitted fields persist. Nested `null` removes an owned object key; inherited content may reappear. Canonical `"[N]"` keys patch array elements; indexed deletion is forbidden.
 
 Illustrative deletion, only for an actually completed intent and after satisfying pending acquisitions: