@llblab/pi-kit 0.37.1 → 0.38.0

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

@@ -2,7 +2,8 @@ import { resolve } from "node:path";
 import { parseArtifactProvenanceRegistry } from "./artifact.js";
 import { MAX_HISTORY_LIMIT } from "./history.js";
 import { canonicalJson, isJsonValue, isObject } from "./json.js";
-import { validateTemporalLineage } from "./temporal.js";
+import { captureTemporalWitnesses, validateTemporalLineage } from "./temporal.js";
+import { captureScopeSelection } from "./selection.js";
 const MAX_RESTORED_STEP = Number.MAX_SAFE_INTEGER - 1;
 const MAX_LEGACY_VALIDATION_ATTEMPT = 7;
 /** Missing operational capability is not evidence that a checkpoint target is invalid. */
@@ -23,26 +24,70 @@ export function readCheckpointMode(value, inactiveMode = "passive") {
         return Object.hasOwn(value, "enabled") || !isStateFlowMode(value.mode) ? undefined : value.mode;
     return typeof value.enabled === "boolean" ? value.enabled ? "active" : inactiveMode : undefined;
 }
+/** Capture closed caller-owned run fields, omitting only undefined optional in-memory fields. */
+export function captureLifecycleSnapshot(value) {
+    if (!isObject(value) || Object.keys(value).sort().join(",") !== "config,meta" || !isObject(value.config)
+        || Object.keys(value.config).join(",") !== "mode" || !isObject(value.meta)
+        || Object.keys(value.meta).some((key) => !["step", "specification", "bootstrap", "validation"].includes(key))) {
+        throw new Error("Selected State Flow lifecycle update contains non-owned fields");
+    }
+    const meta = Object.fromEntries(Object.entries(value.meta).filter(([, field]) => field !== undefined));
+    const supplied = { config: value.config, meta };
+    if (!isJsonValue(supplied))
+        throw new Error("Invalid State Flow lifecycle snapshot");
+    const normalized = { config: { mode: isStateFlowMode(value.config.mode) ? value.config.mode : "off" }, meta: restoredMeta(meta) };
+    if (meta.bootstrap === false)
+        normalized.meta.bootstrap = false;
+    if (meta.step === Number.MAX_SAFE_INTEGER)
+        normalized.meta.step = Number.MAX_SAFE_INTEGER;
+    if (canonicalJson(normalized) !== canonicalJson(supplied))
+        throw new Error("Invalid State Flow lifecycle snapshot");
+    return structuredClone(normalized);
+}
 /** Failed Active selection retains its policy and fences inference until explicit recovery or an inactive choice. */
 export function isActiveRestorationBlocked(snapshot) {
     return snapshot.config.mode === "active" && snapshot.meta.validation?.attempt === 0;
 }
+/** Retained private identity proof, never private values or acquisition permission. */
+export function capturePrivateCausalBasis(value) {
+    if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "causalWitnesses,lineage")
+        throw new Error("Invalid State Flow private causal basis");
+    const lineage = value.lineage;
+    validateTemporalLineage(lineage, MAX_HISTORY_LIMIT);
+    const causalWitnesses = captureTemporalWitnesses(lineage, value.causalWitnesses, MAX_HISTORY_LIMIT);
+    const witnessed = new Set(causalWitnesses.map(witness => witness.transition.id));
+    if (lineage.slice(1).some(boundary => !witnessed.has(boundary.id)))
+        throw new Error("Insufficient State Flow private causal basis witnesses");
+    return structuredClone({ lineage, causalWitnesses });
+}
 export function validateSessionRuntime(value, cwd, sessionId) {
+    validateRuntimeVersion(value, cwd, sessionId, 1);
+}
+/** Shared syntax checks do not widen native admission or prove private-stream acquisition. */
+function validateRuntimeVersion(value, cwd, sessionId, expectedVersion) {
     if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "config,meta"
         || !isObject(value.config) || !isObject(value.meta))
         throw new Error("Invalid State Flow session runtime envelope");
     const { version, identity, lineage, artifacts, temporal: _temporalScope, ...fields } = value.meta;
+    if (!Object.hasOwn(value.meta, "version") || version !== expectedVersion)
+        throw new Error("Unsupported State Flow runtime provenance format");
     if (artifacts !== undefined)
         parseArtifactProvenanceRegistry(artifacts, "State Flow session artifact provenance");
-    if (version !== 1)
-        throw new Error("Unsupported State Flow runtime provenance format");
+    if (expectedVersion === 2 && (!Object.hasOwn(value.meta, "privateAcquisition") || !["unacquired", "deferred", "acquired"].includes(value.meta.privateAcquisition))) {
+        throw new Error("Invalid State Flow private acquisition provenance");
+    }
+    if (Object.hasOwn(value.meta, "privateCausalBasis")) {
+        if (expectedVersion !== 2 || value.meta.privateAcquisition !== "acquired")
+            throw new Error("Invalid State Flow private causal basis provenance");
+        capturePrivateCausalBasis(value.meta.privateCausalBasis);
+    }
     if (!isObject(identity) || Object.keys(identity).sort().join(",") !== "cwd,sessionId"
         || identity.cwd !== resolve(cwd) || identity.sessionId !== sessionId || sessionId.trim().length === 0 || sessionId !== sessionId.trim()) {
         throw new Error("State Flow runtime scope identity mismatch");
     }
     validateTemporalLineage(lineage, MAX_HISTORY_LIMIT);
     const known = new Set(["step", "specification", "validation", "bootstrap"]);
-    if (Object.keys(fields).some((key) => ["state", "contract", "working", "response"].includes(key))) {
+    if (Object.keys(fields).some((key) => ["state", "strategy", "tactics", "contract", "working", "response"].includes(key))) {
         throw new Error("Semantic state does not belong in State Flow runtime metadata");
     }
     const runtimeFields = Object.fromEntries(Object.entries(fields).filter(([key]) => known.has(key)));
@@ -54,7 +99,12 @@ export function validateSessionRuntime(value, cwd, sessionId) {
         normalized.meta.bootstrap = false;
     if (runtimeFields.step === Number.MAX_SAFE_INTEGER)
         normalized.meta.step = Number.MAX_SAFE_INTEGER;
-    if (canonicalJson({ config: normalized.config, meta: normalized.meta }) !== canonicalJson({ config: value.config, meta: runtimeFields })) {
+    if (expectedVersion === 2 && !Object.hasOwn(value.config, "scopes"))
+        throw new Error("State Flow lifecycle v2 requires explicit scopes");
+    const scopes = expectedVersion === 2 ? captureScopeSelection(value.config.scopes) : undefined;
+    const normalizedConfig = scopes === undefined ? normalized.config : { ...normalized.config, scopes };
+    const suppliedConfig = scopes === undefined ? value.config : { ...value.config, scopes };
+    if (canonicalJson({ config: normalizedConfig, meta: normalized.meta }) !== canonicalJson({ config: suppliedConfig, meta: runtimeFields })) {
         throw new Error("Invalid State Flow runtime configuration or counters");
     }
 }
@@ -86,10 +136,7 @@ export function parseSessionRuntime(config, runtimeSource, cwd, sessionId) {
     let runtime;
     try {
         const settings = JSON.parse(config);
-        const mode = isObject(settings) && Object.keys(settings).length === 1 ? readCheckpointMode(settings, "passive") : undefined;
-        if (mode === undefined)
-            throw new Error("Invalid State Flow runtime configuration or counters");
-        runtime = { config: { mode }, meta: JSON.parse(runtimeSource) };
+        runtime = { config: legacySessionConfig(settings), meta: JSON.parse(runtimeSource) };
     }
     catch (error) {
         if (error instanceof SyntaxError)
@@ -100,6 +147,48 @@ export function parseSessionRuntime(config, runtimeSource, cwd, sessionId) {
     const { temporal: _legacyTemporal, ...runtimeMeta } = runtime.meta;
     return { config: { mode: runtime.config.mode }, meta: runtimeMeta };
 }
+function legacySessionConfig(settings) {
+    const mode = isObject(settings) && Object.keys(settings).length === 1 ? readCheckpointMode(settings, "passive") : undefined;
+    if (mode === undefined)
+        throw new Error("Invalid State Flow runtime configuration or counters");
+    return { mode };
+}
+/** Detached lifecycle preflight only; current native readers/writers still admit version 1 exclusively. */
+export function prepareSessionPolicyMigration(config, runtimeSource, cwd, sessionId, legacySelection) {
+    if (config === undefined && runtimeSource === undefined)
+        return undefined;
+    if (config === undefined || runtimeSource === undefined)
+        throw new Error("Incomplete State Flow config/runtime pair");
+    const metadata = parsePolicyDocument(runtimeSource);
+    if (!isObject(metadata) || !Object.hasOwn(metadata, "version") || (metadata.version !== 1 && metadata.version !== 2))
+        throw new Error("Unsupported State Flow runtime provenance format");
+    const sourceVersion = metadata.version;
+    const settings = parsePolicyDocument(config);
+    if (sourceVersion === 1 && (Object.hasOwn(metadata, "privateAcquisition") || Object.hasOwn(metadata, "causalWitnesses") || Object.hasOwn(metadata, "privateCausalBasis") || (isObject(settings) && Object.hasOwn(settings, "scopes")))) {
+        throw new Error("Target State Flow policy fields in legacy lifecycle format");
+    }
+    const sourceValue = { config: sourceVersion === 1 ? legacySessionConfig(settings) : settings, meta: metadata };
+    validateRuntimeVersion(sourceValue, cwd, sessionId, sourceVersion);
+    const scopes = captureScopeSelection(sourceVersion === 1 ? legacySelection : settings.scopes);
+    const runtime = {
+        config: { ...sourceValue.config, scopes },
+        meta: { ...metadata, version: 2, ...(sourceVersion === 1 ? { privateAcquisition: "acquired" } : {}) },
+    };
+    validateRuntimeVersion(runtime, cwd, sessionId, 2);
+    return {
+        sourceVersion, targetVersion: 2, requiresConversion: sourceVersion === 1,
+        source: { config, runtime: runtimeSource }, runtime,
+        target: { config: `${canonicalJson(runtime.config)}\n`, runtime: `${canonicalJson(runtime.meta)}\n` },
+    };
+}
+function parsePolicyDocument(source) {
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        throw new Error("State Flow session policy contains invalid JSON");
+    }
+}
 function restoredStep(value) {
     return typeof value === "number"
         && Number.isSafeInteger(value)
@@ -187,6 +276,37 @@ export function parseRetainedPiCheckpoint(value, inactiveMode = "passive") {
         ...(typeof value.specification === "string" ? { specification: value.specification } : {}),
     };
 }
+/** Native policy value preflight; no retained boundary, fork or acquisition authority is created. */
+export function prepareRetainedPolicyMigration(value, legacySelection, inactiveMode = "passive") {
+    if (!isObject(value))
+        throw new Error("Invalid State Flow policy checkpoint");
+    const legacy = !Object.hasOwn(value, "version");
+    let declaredVersion;
+    try {
+        if (!legacy)
+            declaredVersion = value.version;
+    }
+    catch {
+        throw new Error("Invalid State Flow policy checkpoint");
+    }
+    if (!legacy && declaredVersion !== 2)
+        throw new Error("Unsupported State Flow native policy version");
+    const sourceVersion = legacy ? "legacy" : 2;
+    if (sourceVersion === "legacy" && Object.hasOwn(value, "scopes"))
+        throw new Error("Target State Flow policy fields in legacy native checkpoint");
+    if (!isJsonValue(value))
+        throw new Error("Invalid State Flow policy checkpoint");
+    const { version: _version, scopes, ...lifecycle } = value;
+    if (sourceVersion === 2 && (!Object.hasOwn(value, "scopes") || !isStateFlowMode(lifecycle.mode)
+        || Object.hasOwn(lifecycle, "enabled") || Object.hasOwn(lifecycle, "disabled"))) {
+        throw new Error("Invalid State Flow lifecycle v2 policy");
+    }
+    const checkpoint = parseRetainedPiCheckpoint(lifecycle, inactiveMode);
+    return {
+        sourceVersion, targetVersion: 2, requiresConversion: sourceVersion === "legacy",
+        checkpoint: { ...checkpoint, version: 2, scopes: captureScopeSelection(sourceVersion === "legacy" ? legacySelection : scopes) },
+    };
+}
 export function migrationFailure(data, error, mode = "passive") {
     const meta = restoredMeta(data.meta, data);
     meta.validation = {

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

@@ -1,10 +1,11 @@
 import { type ArtifactCompilationUpdate, type ArtifactModelHints, type ArtifactRegistry } from "./artifact.ts";
 import { type JsonObject } from "./json.ts";
+import { type RetainedModules } from "./semantic-module.ts";
 /** Runtime defaults for documented semantic planes; stored objects may omit them or retain other fields. */
 export type MaterializedState = JsonObject & {
     intents: JsonObject;
-    contract: JsonObject;
-    working: JsonObject;
+    strategy: JsonObject;
+    tactics: JsonObject;
     artifacts: ArtifactRegistry;
     response: string;
     lazy: JsonObject;
@@ -12,20 +13,24 @@ export type MaterializedState = 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;
+    strategy: JsonObject;
+    tactics: JsonObject;
     artifacts: ArtifactRegistry;
     response: string;
     lazy: JsonObject;
 }>;
 export type ScopedSemanticStates = Record<StateScope, SemanticState>;
+/** Present owners only; a selection-aware caller must validate the exact acquired key set. */
+export type ScopeStateValues = Partial<Record<StateScope, SemanticState>>;
+/** Value admission only: owners must already be a captured policy, never inferred from missing data. */
+export declare function assertScopeStateValues(states: ScopeStateValues, owners: readonly StateScope[]): void;
 /** 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. */
 export interface StatePatch extends JsonObject {
     artifacts: JsonObject;
-    contract: JsonObject;
-    working: JsonObject;
+    strategy: JsonObject;
+    tactics: JsonObject;
     intents: JsonObject;
     response: string;
     lazy: JsonObject;
@@ -33,9 +38,10 @@ export interface StatePatch extends JsonObject {
 export type StateScope = "global" | "cwd" | "session";
 /** A model-authored patch for one scope. Response is captured by the runtime in session state. */
 export interface ScopePatch {
+    [module: `x_${string}`]: JsonObject | undefined;
     artifacts?: JsonObject;
-    contract?: JsonObject;
-    working?: JsonObject;
+    strategy?: JsonObject;
+    tactics?: JsonObject;
     intents?: JsonObject;
     lazy?: JsonObject;
 }
@@ -60,6 +66,8 @@ export interface ScopedStates {
     cwd: MaterializedState;
     session: MaterializedState;
 }
+/** Temporary root-plane reservation; nested domain data is not an alternate semantic namespace. */
+export declare function assertNoRetiredSemanticPlanes(value: JsonObject): void;
 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. */
@@ -72,18 +80,22 @@ export declare function overlayStates(...scopes: readonly JsonObject[]): Materia
 /** Default-bearing SDK compatibility view; model transport uses sparse SemanticState instead. */
 export type ModelState = JsonObject & {
     intents: JsonObject;
-    contract: JsonObject;
-    working: JsonObject;
+    strategy: JsonObject;
+    tactics: 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;
+export declare function selectSemanticFields(value: JsonObject, modules?: RetainedModules): JsonObject;
+/** v4 admits only declared object planes; null is a replay deletion, never stored content. */
+export declare function validateExternalPlanes(value: JsonObject, modules: RetainedModules, patch?: boolean): void;
+/** Normalize only core planes: opaque external bodies are not empty-branch policy subjects. */
+export declare function pruneSemanticState(value: JsonObject): JsonObject;
 /** Read only documented, present planes; empty responses carry no semantic value. */
-export declare function projectSemanticState(state: JsonObject): SemanticState;
+export declare function projectSemanticState(state: JsonObject, modules?: RetainedModules): SemanticState;
 /** Preserve deletion meaning in visible history without exposing ignored fields or empty responses. */
-export declare function projectSemanticPatch(patch: JsonObject): JsonObject;
+export declare function projectSemanticPatch(patch: JsonObject, modules?: RetainedModules): JsonObject;
 /** Explicit hot reads filter hidden bodies/bookkeeping without normalizing legacy semantic data. */
-export declare function projectStateForRead(state: SemanticState, artifactHints?: ArtifactModelHints): SemanticState;
+export declare function projectStateForRead(state: SemanticState, artifactHints?: ArtifactModelHints, modules?: RetainedModules): SemanticState;
 /** Ordinary model context omits empty object fields; exact reads and replay remain observational. */
 export declare function projectStateForModel(state: SemanticState, artifactHints?: ArtifactModelHints): SemanticState;

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

@@ -1,16 +1,32 @@
-import { isArtifactRegistry, projectArtifactsForModel, updateArtifactRegistry, } from "./artifact.js";
-import { applyPatch, isObject, pruneEmptyObjects } from "./json.js";
+import { isArtifactRegistry, updateArtifactRegistry, } from "./artifact.js";
+import { applyPatch, isJsonValue, isObject, pruneEmptyObjects } from "./json.js";
+import { projectPlaneContext, SEMANTIC_PLANES } from "./planes.js";
+import { validateModuleObject, validateRetainedModules } from "./semantic-module.js";
+/** Value admission only: owners must already be a captured policy, never inferred from missing data. */
+export function assertScopeStateValues(states, owners) {
+    if (!isObject(states) || Object.keys(states).length !== owners.length
+        || Object.keys(states).some((scope) => !owners.includes(scope))
+        || owners.some((scope) => !Object.hasOwn(states, scope)))
+        throw new Error("Selected State Flow values must match their owners exactly");
+    for (const scope of owners)
+        if (!isJsonValue(states[scope]) || !isSemanticState(states[scope]))
+            throw new Error(`Invalid selected State Flow ${scope} value`);
+}
+/** Temporary root-plane reservation; nested domain data is not an alternate semantic namespace. */
+export function assertNoRetiredSemanticPlanes(value) {
+    for (const plane of ["contract", "working"]) {
+        if (Object.hasOwn(value, plane))
+            throw new Error(`Retired State Flow semantic plane: ${plane}`);
+    }
+}
 export function emptyState() {
-    return { intents: {}, contract: {}, working: {}, artifacts: {}, response: "", lazy: {} };
+    return { intents: {}, strategy: {}, tactics: {}, artifacts: {}, response: "", lazy: {} };
 }
 export function isMaterializedState(value) {
     return isObject(value)
+        && !Object.hasOwn(value, "contract") && !Object.hasOwn(value, "working")
         && isArtifactRegistry(value.artifacts)
-        && isObject(value.contract)
-        && isObject(value.working)
-        && isObject(value.intents)
-        && typeof value.response === "string"
-        && isObject(value.lazy);
+        && SEMANTIC_PLANES.every(({ module }) => module.validate(value[module.id]));
 }
 /** Missing planes are valid storage, not missing authority. Present values retain their type checks. */
 export function isSemanticState(value) {
@@ -27,36 +43,62 @@ export function updateMaterializedArtifacts(state, updates, removed = []) {
 /** Overlay lower-to-higher scopes without mutating any scope document. */
 export function overlayStates(...scopes) {
     return scopes.reduce((effective, scope) => {
+        assertNoRetiredSemanticPlanes(scope);
         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())
+export function selectSemanticFields(value, modules) {
+    assertNoRetiredSemanticPlanes(value);
+    if (modules !== undefined)
+        validateExternalPlanes(value, modules, true);
+    return structuredClone(Object.fromEntries([...Object.keys(emptyState()), ...Object.keys(modules ?? {})]
         .filter((key) => Object.hasOwn(value, key))
         .map((key) => [key, value[key]])));
 }
+/** v4 admits only declared object planes; null is a replay deletion, never stored content. */
+export function validateExternalPlanes(value, modules, patch = false) {
+    validateRetainedModules(modules);
+    const core = emptyState();
+    for (const [key, field] of Object.entries(value)) {
+        if (Object.hasOwn(core, key))
+            continue;
+        if (!Object.hasOwn(modules, key) || !(patch && field === null || isObject(field))) {
+            throw new Error(`Undeclared or invalid State Flow external plane: ${key}`);
+        }
+        if (field !== null)
+            validateModuleObject(field);
+    }
+}
+/** Normalize only core planes: opaque external bodies are not empty-branch policy subjects. */
+export function pruneSemanticState(value) {
+    return Object.fromEntries(Object.entries(value).flatMap(([key, field]) => {
+        if (key.startsWith("x_"))
+            return [[key, field]];
+        const pruned = pruneEmptyObjects({ [key]: field });
+        return Object.entries(pruned);
+    }));
+}
 /** Read only documented, present planes; empty responses carry no semantic value. */
-export function projectSemanticState(state) {
-    const projected = selectSemanticFields(state);
+export function projectSemanticState(state, modules) {
+    const projected = selectSemanticFields(state, modules);
     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);
+export function projectSemanticPatch(patch, modules) {
+    const projected = selectSemanticFields(patch, modules);
     if (projected.response === "")
         projected.response = null;
     return projected;
 }
 /** Explicit hot reads filter hidden bodies/bookkeeping without normalizing legacy semantic data. */
-export function projectStateForRead(state, artifactHints = {}) {
+export function projectStateForRead(state, artifactHints = {}, modules) {
     const { lazy: _hidden, ...visible } = state;
-    const projected = projectSemanticState(visible);
-    if (projected.artifacts)
-        projected.artifacts = projectArtifactsForModel(projected.artifacts, artifactHints);
-    return projected;
+    const selected = projectSemanticState(visible, modules);
+    const core = projectPlaneContext(selected, artifactHints).state;
+    return { ...core, ...Object.fromEntries(Object.keys(modules ?? {}).filter(id => Object.hasOwn(selected, id)).map(id => [id, structuredClone(selected[id])])) };
 }
 /** Ordinary model context omits empty object fields; exact reads and replay remain observational. */
 export function projectStateForModel(state, artifactHints = {}) {

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

@@ -1,7 +1,8 @@
 import type { ArtifactInvalidationReason } from "./artifact.ts";
 import type { RecentTransitionWindow } from "./history.ts";
 import { type Snapshot } from "./snapshot.ts";
-import { type SemanticState, type ScopedStates, type StateScope } from "./state.ts";
+import { type SemanticState, type ScopeStateValues, type StateScope } from "./state.ts";
+import { type ScopeSelection } from "./selection.ts";
 import type { ScopeRevisions, TransitionBoundary } from "./temporal.ts";
 export declare const STATUS_KEY = "state-flow";
 export type Colorize = (color: "accent" | "dim", text: string) => string;
@@ -15,23 +16,27 @@ export interface StatusDiagnostics {
     repositoryRoot: string;
     cwdScopeKey: string;
     sessionScopeKey: string;
-    scopeStates: ScopedStates;
-    /** Overlay raw scopes before defaults so absent scalar planes cannot mask lower scopes. */
+    /** Omission retains all-three compatibility; a subset must be explicit, never inferred from missing data. */
+    selection?: ScopeSelection;
+    /** Captured policy may request Session while only shared owners are observable. Never a materialization grant. */
+    requestedSelection?: ScopeSelection;
+    scopeStates: ScopeStateValues;
+    /** Legacy overlay override. Explicit selected observations derive only from scopeStates. */
     effectiveState?: SemanticState;
     recent: RecentTransitionWindow;
     historyLimit: number;
     temporal?: {
         head: TransitionBoundary;
         historyDepth: number;
-        tailCounts: Record<StateScope, number>;
-        revisions: ScopeRevisions;
+        tailCounts: Partial<Record<StateScope, number>>;
+        revisions: Partial<ScopeRevisions>;
     };
     staleArtifacts: readonly StaleArtifactDiagnostic[];
     durableStateError?: string;
     publicationError?: string;
 }
-export declare function formatScopeRevisionVector(revisions: ScopeRevisions): string;
-export declare function compactStatus(snapshot: Snapshot, _revisions: ScopeRevisions, colorize: Colorize): string | undefined;
-/** Operator-only footprint: serialized plane sizes and intent-owned share of top-level working/lazy entries. */
-export declare function scopeMemoryLines(states: ScopedStates): string[];
+export declare function formatScopeRevisionVector(revisions: Partial<ScopeRevisions>, selection?: ScopeSelection): string;
+export declare function compactStatus(snapshot: Snapshot, _revisions: Partial<ScopeRevisions>, colorize: Colorize): string | undefined;
+/** Operator-only footprint: serialized plane sizes and intent-owned share of top-level tactics/lazy entries. */
+export declare function scopeMemoryLines(states: ScopeStateValues, selection?: ScopeSelection): string[];
 export declare function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostics): string;

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

@@ -1,10 +1,24 @@
 import { ownedTopLevelKeys } from "./ownership.js";
 import { conciseDiagnostic } from "./protocol.js";
 import { isActiveRestorationBlocked } from "./snapshot.js";
-import { overlayStates, projectSemanticState } from "./state.js";
+import { assertScopeStateValues, overlayStates, projectSemanticState } from "./state.js";
+import { applyPatch, isObject } from "./json.js";
+import { captureScopeSelection, DEFAULT_SCOPE_SELECTION } from "./selection.js";
 export const STATUS_KEY = "state-flow";
-export function formatScopeRevisionVector(revisions) {
-    return `g${revisions.global}c${revisions.cwd}s${revisions.session}`;
+function assertScopeNumbers(values, selection, label) {
+    if (!isObject(values) || Object.keys(values).length !== selection.length
+        || Object.keys(values).some(scope => !selection.includes(scope))
+        || selection.some(scope => !Object.hasOwn(values, scope)))
+        throw new Error(`Invalid State Flow selected ${label}`);
+    for (const scope of selection)
+        if (!Number.isSafeInteger(values[scope]) || values[scope] < 0)
+            throw new Error(`Invalid State Flow selected ${label}`);
+}
+export function formatScopeRevisionVector(revisions, selection = DEFAULT_SCOPE_SELECTION) {
+    const selected = captureScopeSelection(selection);
+    assertScopeNumbers(revisions, selected, "revision vector");
+    const prefix = { global: "g", cwd: "c", session: "s" };
+    return selected.map(scope => `${prefix[scope]}${revisions[scope]}`).join("");
 }
 export function compactStatus(snapshot, _revisions, colorize) {
     const { mode } = snapshot.config;
@@ -13,26 +27,28 @@ export function compactStatus(snapshot, _revisions, colorize) {
     return `${colorize("accent", "state-flow")} ${colorize("dim", isActiveRestorationBlocked(snapshot) ? "active (blocked)" : mode)}`;
 }
 function countArtifacts(states, scope) {
-    return Object.keys(states[scope].artifacts).length;
+    return Object.keys(states[scope].artifacts ?? {}).length;
 }
-const STATUS_PLANES = ["intents", "contract", "working", "artifacts", "response", "lazy"];
+const STATUS_PLANES = ["intents", "strategy", "tactics", "artifacts", "response", "lazy"];
 const encoder = new TextEncoder();
 function isPresentPlane(value) {
     if (value === undefined || value === "")
         return false;
     return typeof value !== "object" || value === null || Object.keys(value).length > 0;
 }
-/** Operator-only footprint: serialized plane sizes and intent-owned share of top-level working/lazy entries. */
-export function scopeMemoryLines(states) {
+/** Operator-only footprint: serialized plane sizes and intent-owned share of top-level tactics/lazy entries. */
+export function scopeMemoryLines(states, selection = DEFAULT_SCOPE_SELECTION) {
+    const selected = captureScopeSelection(selection);
+    assertScopeStateValues(states, selected);
     const lines = [];
-    for (const scope of ["global", "cwd", "session"]) {
+    for (const scope of selected) {
         const state = states[scope];
         const sizes = STATUS_PLANES.filter((plane) => isPresentPlane(state[plane]))
             .map((plane) => `${plane} ${encoder.encode(JSON.stringify(state[plane])).length} B`);
         if (sizes.length === 0)
             continue;
         const owned = ownedTopLevelKeys(scope, state);
-        const shares = ["working", "lazy"].flatMap((plane) => {
+        const shares = ["tactics", "lazy"].flatMap((plane) => {
             const value = state[plane];
             const keys = value !== null && typeof value === "object" && !Array.isArray(value) ? Object.keys(value) : [];
             return keys.length === 0 ? [] : [`${plane} ${keys.filter((key) => owned[plane].has(key)).length}/${keys.length}`];
@@ -42,36 +58,57 @@ export function scopeMemoryLines(states) {
     return lines.length ? ["Scope memory:", ...lines] : [];
 }
 export function detailedStatus(snapshot, diagnostics) {
+    const selection = diagnostics.selection;
+    const explicit = selection !== undefined;
+    const selected = captureScopeSelection(explicit ? selection : DEFAULT_SCOPE_SELECTION);
+    const requested = diagnostics.requestedSelection === undefined ? selected : captureScopeSelection(diagnostics.requestedSelection);
     const available = diagnostics.temporal !== undefined && diagnostics.durableStateError === undefined;
-    const materialized = !available ? undefined : diagnostics.effectiveState ?? projectSemanticState(overlayStates(diagnostics.scopeStates.global, diagnostics.scopeStates.cwd, diagnostics.scopeStates.session));
+    if (available) {
+        if (selected.some(scope => !requested.includes(scope)))
+            throw new Error("State Flow materialization exceeds requested scopes");
+        assertScopeStateValues(diagnostics.scopeStates, selected);
+        assertScopeNumbers(diagnostics.temporal.revisions, selected, "revision vector");
+        assertScopeNumbers(diagnostics.temporal.tailCounts, selected, "tail counts");
+    }
+    // A selected observation derives its overlay from exact owners, never a stale all-owner override.
+    const materialized = !available ? undefined : explicit
+        ? selected.reduce((state, scope) => applyPatch(state, projectSemanticState(diagnostics.scopeStates[scope])), {})
+        : diagnostics.effectiveState ?? projectSemanticState(overlayStates(...selected.map(scope => diagnostics.scopeStates[scope])));
     // 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:",
-            ...diagnostics.staleArtifacts.map(({ scope, path, reason }) => `- [${scope}] ${path} — ${reason}`),
-        ];
+    const stale = explicit ? !available ? [] : diagnostics.staleArtifacts.flatMap(notice => {
+        const scope = notice.scope;
+        return selected.includes(scope) ? [{ scope, path: notice.path, reason: notice.reason }] : [];
+    }) : diagnostics.staleArtifacts;
+    const invalidated = available ? String(stale.length) : "unavailable";
+    const invalidationLines = stale.length === 0 ? []
+        : ["Pending artifact invalidations:", ...stale.map(({ scope, path, reason }) => `- [${scope}] ${path} — ${reason}`)];
     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}`]
-        : [`Scope revisions: ${formatScopeRevisionVector(temporal.revisions)}`,
+        : [`Scope revisions: ${formatScopeRevisionVector(temporal.revisions, selected)}`,
             `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);
+    const hasArtifacts = available && selected.some((scope) => artifacts(scope) > 0);
+    const scopeKeys = [
+        ...(selected.includes("cwd") ? [`CWD ${diagnostics.cwdScopeKey}`] : []),
+        ...(selected.includes("session") ? [`session ${diagnostics.sessionScopeKey}`] : []),
+    ];
+    const artifactLabels = { global: "global", cwd: "CWD", session: "session" };
     return [
         `Mode: ${snapshot.config.mode}`,
+        ...(explicit ? [`Selected scopes: ${requested.join(", ")}`] : []),
+        ...(available && selected.length !== requested.length ? [`Materialized scopes: ${selected.join(", ")}`] : []),
         ...(isActiveRestorationBlocked(snapshot) ? ["Inference blocked: Active memory restoration failed. Use /state-flow-active for current memory or select Passive/Off for native context."] : []),
         `Repository: ${diagnostics.repositoryRoot}`,
-        `Scope keys: CWD ${diagnostics.cwdScopeKey}; session ${diagnostics.sessionScopeKey}`,
+        ...(scopeKeys.length ? [`Scope keys: ${scopeKeys.join("; ")}`] : []),
         ...temporalLines,
         ...(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}`] : []),
+        ...(hasArtifacts ? [`Artifacts: ${selected.map(scope => `${artifactLabels[scope]} ${artifacts(scope)}`).join("; ")}; pending invalidations ${invalidated}`] : []),
         ...invalidationLines,
-        ...(available ? scopeMemoryLines(diagnostics.scopeStates) : []),
+        ...(available ? scopeMemoryLines(diagnostics.scopeStates, selected) : []),
         ...(stateJson === undefined
             ? ["Effective memory: unavailable"]
             : ["Effective memory:", "", stateJson]),