@llblab/pi-kit 0.24.1 → 0.26.0

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;
 }

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. */