@llblab/pi-kit 0.24.1 → 0.25.0

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

@@ -1,6 +1,6 @@
 import { type ArtifactCompilationUpdate, type ArtifactModelHints, type ArtifactRegistry } from "./artifact.ts";
 import { 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;
@@ -9,6 +9,16 @@ export type MaterializedState = JsonObject & {
     response: string;
     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;
 /** Model patch shape; artifact entries may be compiler outputs before trusted metadata is attached. */
@@ -52,11 +62,14 @@ export interface ScopedStates {
 }
 export declare function emptyState(): MaterializedState;
 export declare function isMaterializedState(value: unknown): value is MaterializedState;
+/** Missing planes are valid storage, not missing authority. Present values retain their type checks. */
+export declare function isSemanticState(value: unknown): value is SemanticState;
 export declare const isStateDocument: typeof isMaterializedState;
 /** Atomically replace compiled and removed artifacts inside one materialized scope. */
 export declare function updateMaterializedArtifacts(state: MaterializedState, updates: readonly ArtifactCompilationUpdate[], removed?: readonly string[]): MaterializedState;
 /** Overlay lower-to-higher scopes without mutating any scope document. */
-export declare function overlayStates(...scopes: readonly MaterializedState[]): MaterializedState;
+export declare function overlayStates(...scopes: readonly JsonObject[]): MaterializedState;
+/** Default-bearing SDK compatibility view; model transport uses sparse SemanticState instead. */
 export type ModelState = JsonObject & {
     intents: JsonObject;
     contract: JsonObject;
@@ -64,5 +77,11 @@ export type ModelState = JsonObject & {
     artifacts: ArtifactRegistry;
     response: string;
 };
+/** Select only owned top-level fields, preserving nested data and replay deletion markers. */
+export declare function selectSemanticFields(value: JsonObject): JsonObject;
+/** Read only documented, present planes; empty responses carry no semantic value. */
+export declare function projectSemanticState(state: JsonObject): SemanticState;
+/** Preserve deletion meaning in visible history without exposing ignored fields or empty responses. */
+export declare function projectSemanticPatch(patch: JsonObject): JsonObject;
 /** Model-visible projection: lazy bodies and runtime artifact bookkeeping stay out of ordinary context. */
-export declare function projectStateForModel(state: MaterializedState, artifactHints?: ArtifactModelHints): ModelState;
+export declare function projectStateForModel(state: SemanticState, artifactHints?: ArtifactModelHints): SemanticState;

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

@@ -10,8 +10,11 @@ export function isMaterializedState(value) {
         && 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) {
+    return isObject(value) && isMaterializedState({ ...emptyState(), ...value });
 }
 export const isStateDocument = isMaterializedState;
 /** Atomically replace compiled and removed artifacts inside one materialized scope. */
@@ -27,14 +30,31 @@ export function overlayStates(...scopes) {
         return applyPatch(effective, scope);
     }, emptyState());
 }
+/** Select only owned top-level fields, preserving nested data and replay deletion markers. */
+export function selectSemanticFields(value) {
+    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) {
+    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) {
+    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, artifactHints = {}) {
-    const cloned = structuredClone(state);
-    return {
-        intents: cloned.intents,
-        contract: cloned.contract,
-        working: cloned.working,
-        artifacts: projectArtifactsForModel(cloned.artifacts, artifactHints),
-        response: cloned.response,
-    };
+    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/dist/lib/status.d.ts

@@ -1,7 +1,7 @@
 import type { ArtifactInvalidationReason } from "./artifact.ts";
-import { type RecentTransitionWindow } from "./history.ts";
+import type { RecentTransitionWindow } from "./history.ts";
 import type { Snapshot } from "./snapshot.ts";
-import { type ScopedStates, type StateScope } from "./state.ts";
+import { type SemanticState, type ScopedStates, type StateScope } from "./state.ts";
 import type { ScopeRevisions, TransitionBoundary } from "./temporal.ts";
 export declare const STATUS_KEY = "state-flow";
 export type Colorize = (color: "accent" | "dim", text: string) => string;
@@ -16,6 +16,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?: {
@@ -29,5 +31,5 @@ export interface StatusDiagnostics {
     publicationError?: string;
 }
 export declare function formatScopeRevisionVector(revisions: ScopeRevisions): string;
-export declare function compactStatus(snapshot: Snapshot, revisions: ScopeRevisions, colorize: Colorize): string | undefined;
+export declare function compactStatus(snapshot: Snapshot, _revisions: ScopeRevisions, colorize: Colorize): string | undefined;
 export declare function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostics): string;

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

@@ -1,27 +1,26 @@
-import { projectRecentTransitionsWithLimit } from "./history.js";
-import { retainedMemoryScopes } from "./memory.js";
 import { conciseDiagnostic } from "./protocol.js";
-import { overlayStates } from "./state.js";
+import { overlayStates, projectSemanticState } from "./state.js";
 export const STATUS_KEY = "state-flow";
 export function formatScopeRevisionVector(revisions) {
-    return `G${revisions.global}/C${revisions.cwd}/S${revisions.session}`;
+    return `g${revisions.global}c${revisions.cwd}s${revisions.session}`;
 }
-export function compactStatus(snapshot, revisions, colorize) {
-    if (!snapshot.config.enabled)
+export function compactStatus(snapshot, _revisions, colorize) {
+    const { mode } = snapshot.config;
+    if (mode === "off")
         return undefined;
-    return `${colorize("accent", "state-flow")} ${colorize("dim", formatScopeRevisionVector(revisions))}`;
+    return `${colorize("accent", "state-flow")} ${colorize("dim", mode)}`;
 }
 function countArtifacts(states, scope) {
     return Object.keys(states[scope].artifacts).length;
 }
 export function detailedStatus(snapshot, diagnostics) {
-    const projectedRecent = projectRecentTransitionsWithLimit(diagnostics.historyLimit, diagnostics.recent);
     const available = diagnostics.temporal !== undefined && diagnostics.durableStateError === undefined;
-    const materialized = !available ? undefined : overlayStates(diagnostics.scopeStates.global, diagnostics.scopeStates.cwd, diagnostics.scopeStates.session);
-    const stateJson = materialized === undefined ? undefined : JSON.stringify(materialized, null, 2);
+    const materialized = !available ? undefined : diagnostics.effectiveState ?? projectSemanticState(overlayStates(diagnostics.scopeStates.global, diagnostics.scopeStates.cwd, diagnostics.scopeStates.session));
+    // 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}`),
@@ -29,29 +28,21 @@ export function detailedStatus(snapshot, diagnostics) {
     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) => 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) => countArtifacts(diagnostics.scopeStates, scope);
+    const hasArtifacts = available && ["global", "cwd", "session"].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/dist/lib/telegram.d.ts

@@ -1,9 +1,11 @@
+import type { StateFlowMode } from "./snapshot.ts";
 import type { ScopeRevisions } from "./temporal.ts";
 export declare const STATE_FLOW_TELEGRAM_ID = "@llblab/pi-state-flow";
 /** Resolve the package export or the compiled sibling-extension layout used in local development. */
 export declare function stateFlowTelegramSectionSpecifiers(moduleUrl?: string): string[];
 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;
@@ -12,11 +14,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;
 }
 export type StateFlowTelegramRichText = string | StateFlowTelegramRichText[] | {
@@ -92,26 +94,26 @@ 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 {
     ensure(): Promise<boolean>;
     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 declare function formatStateFlowSectionLabel(snapshot: StateFlowTelegramSnapshot): string;
-/** The submenu header repeats the button's state line; the single action matches the current state. */
-export declare function buildStateFlowSectionView(snapshot: StateFlowTelegramSnapshot, callbackData: (action: string) => string): StateFlowTelegramView;
-export declare function buildStateFlowScopeChooser(callbackData: (action: string, payload?: string) => string): StateFlowTelegramView;
+export declare const STATE_FLOW_MODES: readonly ["off", "passive", "active"];
+/** One radio-style mode row followed directly by read-only scope actions. */
+export declare function buildStateFlowSectionView(snapshot: StateFlowTelegramSnapshot, callbackData: (action: string, payload?: string) => string): StateFlowTelegramView;
 export declare function renderStateFlowRichState(scope: StateFlowTelegramScope, revisions: ScopeRevisions, state: StateFlowTelegramState): StateFlowTelegramRichMessage;
 /** Default loader; injectable so tests and embedded hosts can control transport presence. */
 export declare function loadStateFlowTelegramModules(): Promise<StateFlowTelegramModules>;

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

@@ -20,35 +20,50 @@ export function stateFlowTelegramSectionSpecifiers(moduleUrl = import.meta.url)
         new URL("../../../pi-telegram/dist/api/sections.js", moduleUrl).href,
     ];
 }
-/** 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) {
-    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) {
-    if (!snapshot.enabled)
-        return "off";
-    return snapshot.revisions ? formatScopeRevisionVector(snapshot.revisions) : `#${snapshot.step}`;
+export const STATE_FLOW_MODES = ["off", "passive", "active"];
+const STATE_FLOW_MODE_LABELS = { off: "Off", passive: "Passive", active: "Active" };
+const STATE_FLOW_SELECTED_MARKERS = { off: "🟡", passive: "🟣", active: "🟢" };
+function isStateFlowModeAction(value) {
+    return STATE_FLOW_MODES.includes(value);
 }
-/** Submenu state line: the same identity as the button label, with the live value in monospace. */
-function formatStateFlowSectionHeader(snapshot) {
-    return `<b>🌀 State Flow: <code>${stateFlowLabelValue(snapshot)}</code></b>`;
+function modeReceiptNotice(mode, result) {
+    if (result.ok && (result.message === `State Flow ${mode}` || result.message === `State Flow is already ${mode}`))
+        return undefined;
+    return result.message;
 }
-/** 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.";
-/** 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, callbackData) {
-    const action = snapshot.enabled
-        ? { text: "⏹ Stop", callback_data: callbackData("stop") }
-        : { text: "▶️ Start", callback_data: callbackData("start") };
+    const modes = 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"]].map((row) => row.map((scope) => ({
+                    text: STATE_FLOW_SCOPE_LABELS[scope], callback_data: callbackData("inspect", scope),
+                }))),
             ] },
     };
 }
@@ -58,17 +73,6 @@ const STATE_FLOW_SCOPE_LABELS = {
     session: "💬 Session",
     effective: "🧬 Effective",
 };
-export function buildStateFlowScopeChooser(callbackData) {
-    return {
-        text: "<b>👁 Show state:</b>",
-        parseMode: "html",
-        replyMarkup: { inline_keyboard: [
-                ...["global", "cwd", "session", "effective"].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;
@@ -113,10 +117,10 @@ export function renderStateFlowRichState(scope, revisions, state) {
                 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",
                 summary: { type: "code", text: field },
-                blocks: [{ type: "pre", language: "json", text: renderStateFlowTelegramField(state[field] ?? {}) }],
+                blocks: [{ type: "pre", language: "json", text: renderStateFlowTelegramField(state[field]) }],
             })),
         ],
         skip_entity_detection: true,
@@ -131,20 +135,16 @@ function buildStateFlowTelegramSection(port, isActive) {
         id: STATE_FLOW_TELEGRAM_ID,
         label: "🌀 State Flow",
         getLabel: () => formatStateFlowSectionLabel(port.snapshot()),
-        render: (ctx) => buildStateFlowSectionView(port.snapshot(), (action) => ctx.callbackData(action)),
+        render: (ctx) => buildStateFlowSectionView(port.snapshot(), (action, payload) => ctx.callbackData(action, payload)),
         handleCallback: async (ctx) => {
-            // 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")
+            // 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";
             const request = ++interaction;
             let notice;
             let acknowledged = false;
             try {
-                if (ctx.action === "show-state") {
-                    await ctx.answerCallback();
-                    await ctx.edit(buildStateFlowScopeChooser((action, payload) => ctx.callbackData(action, payload)));
-                    return "handled";
-                }
                 if (ctx.action === "inspect") {
                     if (!isStateFlowTelegramScope(ctx.payload))
                         throw new Error("Unknown State Flow scope");
@@ -167,25 +167,25 @@ function buildStateFlowTelegramSection(port, isActive) {
                         await ctx.answerCallback();
                     return "handled";
                 }
-                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";
-                        notice = result.message;
+                        notice = modeReceiptNotice(mode, result);
                     }
                     else
-                        notice = port[action]().message;
+                        notice = modeReceiptNotice(mode, port.select(mode));
                 }
-                else if (ctx.action === "start") {
+                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();
@@ -198,7 +198,7 @@ function buildStateFlowTelegramSection(port, isActive) {
             if (request !== interaction || !isActive())
                 return "handled";
             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/dist/lib/temporal.d.ts

@@ -1,5 +1,5 @@
 import { type RecentScopePatch } from "./history.ts";
-import { type MaterializedState, type ScopedStates, type StateScope } from "./state.ts";
+import { 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 {
     id: string;
@@ -9,7 +9,7 @@ export interface TransitionBoundary {
 }
 export interface ScopeCheckpoint {
     through: TransitionBoundary;
-    state: MaterializedState;
+    state: SemanticState;
 }
 export interface TemporalPatch {
     transition: TransitionBoundary;
@@ -37,7 +37,7 @@ export declare function validateTemporalState(view: TemporalState, historyLimit?
 /** Adopt revision-proven inherited streams without rewriting their checkpoints or tails. */
 export declare function adoptTemporalStreams(scopes: Record<StateScope, ScopeStream>, id: string, historyLimit?: number): TemporalState;
 /** New or migrated state starts at a proven current boundary, with no invented past. */
-export declare function createTemporalState(states: ScopedStates, id: string, historyLimit?: number): TemporalState;
+export declare function createTemporalState(states: ScopedSemanticStates, id: string, historyLimit?: number): TemporalState;
 /** Fold retained tails to a lower configured limit without inventing history. */
 export declare function constrainTemporalState(view: TemporalState, historyLimit: number): TemporalState;
 /** Select one scope at a proven retained boundary from its owning runtime lineage. */
@@ -46,7 +46,11 @@ export declare function selectScopeStreamAtBoundary(stream: ScopeStream, scope:
 export declare function selectTemporalStateBoundary(view: TemporalState, boundaryId: string, historyLimit?: number): TemporalState;
 /** Current independent scope revisions; Effective uses this vector rather than inventing a scalar owner. */
 export declare function temporalScopeRevisions(view: TemporalState): ScopeRevisions;
-/** Lazy scope/effective read at one shared transition boundary, never by local patch count. */
+/** Exact scope semantics for authored staging; defaults must never become implicit writes. */
+export declare function readTemporalScopes(view: TemporalState, offset?: number, historyLimit?: number): ScopedSemanticStates;
+/** Sparse current/historical view: unknown planes and absent values never become effective data. */
+export declare function readTemporalView(view: TemporalState, offset?: number, scope?: StateScope, historyLimit?: number): SemanticState;
+/** Internal defaulted materialization for consumers that require object registries. */
 export declare function readTemporalState(view: TemporalState, offset?: number, scope?: StateScope, historyLimit?: number): MaterializedState;
 /** Allocate the identity outside this algebra; only materially effective patches accept it. */
 export declare function advanceTemporalState(view: TemporalState, transitions: readonly RecentScopePatch[], id: string, historyLimit?: number): TemporalState;

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

@@ -1,6 +1,6 @@
 import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT, validateRecentTransition } from "./history.js";
 import { applyPatch, containsNull, isJsonValue, isObject, sameJson } from "./json.js";
-import { isMaterializedState, overlayStates } from "./state.js";
+import { emptyState, isSemanticState, overlayStates, projectSemanticState } from "./state.js";
 const SCOPES = ["global", "cwd", "session"];
 function validateHistoryLimit(limit) {
     if (!Number.isSafeInteger(limit) || limit < 0 || limit > MAX_HISTORY_LIMIT) {
@@ -16,14 +16,20 @@ function validateBoundary(boundary) {
         throw new Error("Invalid State Flow temporal boundary");
     }
 }
-function validateState(state) {
-    if (!isJsonValue(state) || !isMaterializedState(state) || containsNull(state)) {
-        throw new Error("Invalid temporal materialized semantic state");
-    }
+function validateState(state, location) {
+    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, patch) {
+function apply(state, patch, location) {
     const next = applyPatch(state, patch);
-    validateState(next);
+    validateState(next, location);
     return next;
 }
 function sameBoundary(left, right) {
@@ -42,7 +48,7 @@ export function validateScopeStream(value, scope, historyLimit = DEFAULT_HISTORY
     }
     const stream = value;
     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)
@@ -62,9 +68,7 @@ export function validateScopeStream(value, scope, historyLimit = DEFAULT_HISTORY
             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);
@@ -244,21 +248,33 @@ export function temporalScopeRevisions(view) {
     }
     return revisions;
 }
-/** Lazy scope/effective read at one shared transition boundary, never by local patch count. */
-export function readTemporalState(view, offset = 0, scope, historyLimit = DEFAULT_HISTORY_LIMIT) {
+function readBoundary(view, offset, historyLimit) {
     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, offset = 0, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    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, offset = 0, scope, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    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((state, owner) => applyPatch(state, projectSemanticState(scopeAt(view.scopes[owner], boundary))), {});
+}
+/** Internal defaulted materialization for consumers that require object registries. */
+export function readTemporalState(view, offset = 0, scope, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    return overlayStates(readTemporalView(view, offset, scope, historyLimit));
 }
 /** Allocate the identity outside this algebra; only materially effective patches accept it. */
 export function advanceTemporalState(view, transitions, id, historyLimit = DEFAULT_HISTORY_LIMIT) {

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

@@ -3,9 +3,9 @@ import type { SuccessfulArtifactRead } from "./acquisition.ts";
 import { type AcceptedTransition } from "./history.ts";
 import { type SuccessfulSkillRead } from "./skills.ts";
 import type { Snapshot } from "./snapshot.ts";
-import type { AtomicScopePatches, ScopedStates, StateScope, TerminalTransition } from "./state.ts";
+import type { AtomicScopePatches, ScopedSemanticStates, StateScope, TerminalTransition } 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>>;
@@ -13,11 +13,11 @@ export interface StagedScopedTransition {
     committed: boolean;
 }
 /** Stage one canonical atomic scope cohort without changing the finalized response. */
-export declare function stageAtomicScopePatches(currentStates: ScopedStates, patches: AtomicScopePatches, successfulSkillReads: Iterable<SuccessfulSkillRead>, causalBasis: string, successfulArtifactReads?: Iterable<SuccessfulArtifactRead>): StagedScopedTransition;
-export declare function stageScopedTransition(currentStates: ScopedStates, transition: TerminalTransition, successfulSkillReads: Iterable<SuccessfulSkillRead>, causalBasis: string, successfulArtifactReads?: Iterable<SuccessfulArtifactRead>): StagedScopedTransition;
+export declare function stageAtomicScopePatches(currentStates: ScopedSemanticStates, patches: AtomicScopePatches, successfulSkillReads: Iterable<SuccessfulSkillRead>, causalBasis: string, successfulArtifactReads?: Iterable<SuccessfulArtifactRead>): StagedScopedTransition;
+export declare function stageScopedTransition(currentStates: ScopedSemanticStates, transition: TerminalTransition, successfulSkillReads: Iterable<SuccessfulSkillRead>, causalBasis: string, successfulArtifactReads?: Iterable<SuccessfulArtifactRead>): StagedScopedTransition;
 /** Commit one accepted transition; durable publication receives all changed scopes as one cohort. */
 export interface CommitScopedTransitionOptions {
     /** Runtime response reconciliation finalizes bootstrap lifecycle state. */
     finalizeRun?: boolean;
 }
-export declare function commitScopedTransition(snapshot: Snapshot, states: ScopedStates, stage: StagedScopedTransition, publishDurable: (accepted: AcceptedTransition | undefined, nextSnapshot: Snapshot) => void, causalBasis: string, options?: CommitScopedTransitionOptions): boolean;
+export declare function commitScopedTransition(snapshot: Snapshot, states: ScopedSemanticStates, stage: StagedScopedTransition, publishDurable: (accepted: AcceptedTransition | undefined, nextSnapshot: Snapshot) => void, causalBasis: string, options?: CommitScopedTransitionOptions): boolean;