@llblab/pi-kit 0.37.1 → 0.38.0

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

@@ -2,7 +2,8 @@ import { resolve } from "node:path";
 import { parseArtifactProvenanceRegistry, type ArtifactProvenanceRegistry } from "./artifact.ts";
 import { MAX_HISTORY_LIMIT } from "./history.ts";
 import { canonicalJson, isJsonValue, isObject, type JsonObject } from "./json.ts";
-import { validateTemporalLineage, type TransitionBoundary } from "./temporal.ts";
+import { captureTemporalWitnesses, validateTemporalLineage, type ExcludedTransitionWitness, type TransitionBoundary } from "./temporal.ts";
+import { captureScopeSelection, type ScopeSelection } from "./selection.ts";
 const MAX_RESTORED_STEP = Number.MAX_SAFE_INTEGER - 1;
 const MAX_LEGACY_VALIDATION_ATTEMPT = 7;
 
@@ -55,37 +56,92 @@ export interface StateFlowSnapshot {
 
 export type Snapshot = StateFlowSnapshot;
 
+/** Capture closed caller-owned run fields, omitting only undefined optional in-memory fields. */
+export function captureLifecycleSnapshot(value: Snapshot): Snapshot {
+	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: Snapshot = { 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: Snapshot): boolean {
 	return snapshot.config.mode === "active" && snapshot.meta.validation?.attempt === 0;
 }
 
+interface LifecycleMetadata extends SnapshotMeta {
+	identity: { cwd: string; sessionId: string };
+	lineage: TransitionBoundary[];
+	[key: string]: unknown;
+}
+
+interface SessionRuntimeMetadata extends LifecycleMetadata {
+	/** Runtime-owned artifact compilation evidence; never projected as semantic state. */
+	artifacts?: ArtifactProvenanceRegistry;
+	temporal?: { checkpoint: TransitionBoundary; patches: TransitionBoundary[] };
+}
+
 export interface SessionRuntime {
 	config: SnapshotConfig;
-	meta: SnapshotMeta & {
-		version: 1;
-		identity: { cwd: string; sessionId: string };
-		lineage: TransitionBoundary[];
-		/** Runtime-owned artifact compilation evidence; never projected as semantic state. */
-		artifacts?: ArtifactProvenanceRegistry;
-		temporal?: { checkpoint: TransitionBoundary; patches: TransitionBoundary[] };
-		[key: string]: unknown;
-	};
+	meta: SessionRuntimeMetadata & { version: 1 };
+}
+
+export type PrivateAcquisition = "unacquired" | "deferred" | "acquired";
+export interface PrivateCausalBasis {
+	lineage: TransitionBoundary[];
+	causalWitnesses: ExcludedTransitionWitness[];
+}
+
+/** Retained private identity proof, never private values or acquisition permission. */
+export function capturePrivateCausalBasis(value: unknown): PrivateCausalBasis {
+	if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "causalWitnesses,lineage") throw new Error("Invalid State Flow private causal basis");
+	const lineage: unknown = 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 interface SelectedSessionRuntime {
+	config: SnapshotConfig & { scopes: ScopeSelection };
+	meta: LifecycleMetadata & { version: 2; privateAcquisition: PrivateAcquisition; privateCausalBasis?: PrivateCausalBasis };
 }
 
 export function validateSessionRuntime(value: unknown, cwd: string, sessionId: string): asserts value is SessionRuntime {
+	validateRuntimeVersion(value, cwd, sessionId, 1);
+}
+
+/** Shared syntax checks do not widen native admission or prove private-stream acquisition. */
+function validateRuntimeVersion(value: unknown, cwd: string, sessionId: string, expectedVersion: 1 | 2): void {
 	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 as string))) {
+		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)));
@@ -95,7 +151,11 @@ export function validateSessionRuntime(value: unknown, cwd: string, sessionId: s
 	};
 	if (runtimeFields.bootstrap === false) 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");
 	}
 }
@@ -138,9 +198,7 @@ export function parseSessionRuntime(
 	let runtime: unknown;
 	try {
 		const settings: unknown = 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) throw new Error("State Flow session runtime contains invalid JSON");
 		throw error;
@@ -150,6 +208,55 @@ export function parseSessionRuntime(
 	return { config: { mode: runtime.config.mode }, meta: runtimeMeta };
 }
 
+function legacySessionConfig(settings: unknown): SnapshotConfig {
+	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 };
+}
+
+export interface SessionPolicyMigrationCandidate {
+	sourceVersion: 1 | 2;
+	targetVersion: 2;
+	requiresConversion: boolean;
+	/** Original strings, not file observations or publication authority. */
+	source: { config: string; runtime: string };
+	runtime: SelectedSessionRuntime;
+	target: { config: string; runtime: string };
+}
+
+/** Detached lifecycle preflight only; current native readers/writers still admit version 1 exclusively. */
+export function prepareSessionPolicyMigration(
+	config: string | undefined, runtimeSource: string | undefined, cwd: string, sessionId: string, legacySelection: ScopeSelection,
+): SessionPolicyMigrationCandidate | undefined {
+	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 as JsonObject).scopes);
+	const runtime = {
+		config: { ...(sourceValue.config as SnapshotConfig), scopes },
+		meta: { ...metadata, version: 2, ...(sourceVersion === 1 ? { privateAcquisition: "acquired" } : {}) },
+	} as SelectedSessionRuntime;
+	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: string): unknown {
+	try { return JSON.parse(source); }
+	catch { throw new Error("State Flow session policy contains invalid JSON"); }
+}
+
 function restoredStep(value: unknown): number {
 	return typeof value === "number"
 		&& Number.isSafeInteger(value)
@@ -252,6 +359,39 @@ export function parseRetainedPiCheckpoint(value: unknown, inactiveMode: Inactive
 	};
 }
 
+export type SelectedRetainedPiCheckpoint = RetainedPiCheckpoint & { version: 2; scopes: ScopeSelection };
+export interface RetainedPolicyMigrationCandidate {
+	sourceVersion: "legacy" | 2;
+	targetVersion: 2;
+	requiresConversion: boolean;
+	checkpoint: SelectedRetainedPiCheckpoint;
+}
+
+/** Native policy value preflight; no retained boundary, fork or acquisition authority is created. */
+export function prepareRetainedPolicyMigration(
+	value: unknown, legacySelection: ScopeSelection, inactiveMode: InactiveMode = "passive",
+): RetainedPolicyMigrationCandidate {
+	if (!isObject(value)) throw new Error("Invalid State Flow policy checkpoint");
+	const legacy = !Object.hasOwn(value, "version");
+	let declaredVersion: unknown;
+	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: JsonObject, error: string, mode: StateFlowMode = "passive"): Snapshot {
 	const meta = restoredMeta(data.meta, data);
 	meta.validation = {

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

@@ -1,18 +1,19 @@
 import {
 	isArtifactRegistry,
-	projectArtifactsForModel,
 	updateArtifactRegistry,
 	type ArtifactCompilationUpdate,
 	type ArtifactModelHints,
 	type ArtifactRegistry,
 } from "./artifact.ts";
-import { applyPatch, isObject, pruneEmptyObjects, type JsonObject } from "./json.ts";
+import { applyPatch, isJsonValue, isObject, pruneEmptyObjects, type JsonObject } from "./json.ts";
+import { projectPlaneContext, SEMANTIC_PLANES } from "./planes.ts";
+import { validateModuleObject, validateRetainedModules, 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;
@@ -21,13 +22,23 @@ 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 function assertScopeStateValues(states: ScopeStateValues, owners: readonly StateScope[]): void {
+	if (!isObject(states) || Object.keys(states).length !== owners.length
+		|| Object.keys(states).some((scope) => !owners.includes(scope as StateScope))
+		|| 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`);
+}
 
 /** Compatibility name for callers that still treat materialized state as a document. */
 export type StateDocument = MaterializedState;
@@ -35,8 +46,8 @@ 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;
@@ -46,9 +57,10 @@ 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;
 }
@@ -79,18 +91,22 @@ export interface ScopedStates {
 	session: MaterializedState;
 }
 
+/** Temporary root-plane reservation; nested domain data is not an alternate semantic namespace. */
+export function assertNoRetiredSemanticPlanes(value: JsonObject): void {
+	for (const plane of ["contract", "working"]) {
+		if (Object.hasOwn(value, plane)) throw new Error(`Retired State Flow semantic plane: ${plane}`);
+	}
+}
+
 export function emptyState(): MaterializedState {
-	return { intents: {}, contract: {}, working: {}, artifacts: {}, response: "", lazy: {} };
+	return { intents: {}, strategy: {}, tactics: {}, artifacts: {}, response: "", lazy: {} };
 }
 
 export function isMaterializedState(value: unknown): value is MaterializedState {
 	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. */
@@ -114,6 +130,7 @@ export function updateMaterializedArtifacts(
 /** Overlay lower-to-higher scopes without mutating any scope document. */
 export function overlayStates(...scopes: readonly JsonObject[]): MaterializedState {
 	return scopes.reduce<MaterializedState>((effective, scope) => {
+		assertNoRetiredSemanticPlanes(scope);
 		return applyPatch(effective, scope) as MaterializedState;
 	}, emptyState());
 }
@@ -121,39 +138,63 @@ export function overlayStates(...scopes: readonly JsonObject[]): MaterializedSta
 /** 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 function selectSemanticFields(value: JsonObject): JsonObject {
-	return structuredClone(Object.fromEntries(Object.keys(emptyState())
+export function selectSemanticFields(value: JsonObject, modules?: RetainedModules): JsonObject {
+	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: JsonObject, modules: RetainedModules, patch = false): void {
+	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: JsonObject): JsonObject {
+	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: JsonObject): SemanticState {
-	const projected = selectSemanticFields(state);
+export function projectSemanticState(state: JsonObject, modules?: RetainedModules): SemanticState {
+	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: JsonObject): JsonObject {
-	const projected = selectSemanticFields(patch);
+export function projectSemanticPatch(patch: JsonObject, modules?: RetainedModules): JsonObject {
+	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: SemanticState, artifactHints: ArtifactModelHints = {}): SemanticState {
+export function projectStateForRead(state: SemanticState, artifactHints: ArtifactModelHints = {}, modules?: RetainedModules): SemanticState {
 	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])])) } as SemanticState;
 }
 
 /** Ordinary model context omits empty object fields; exact reads and replay remain observational. */

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

@@ -3,7 +3,9 @@ import type { RecentTransitionWindow } from "./history.ts";
 import { ownedTopLevelKeys } from "./ownership.ts";
 import { conciseDiagnostic } from "./protocol.ts";
 import { isActiveRestorationBlocked, type Snapshot } from "./snapshot.ts";
-import { overlayStates, projectSemanticState, type SemanticState, type ScopedStates, type StateScope } from "./state.ts";
+import { assertScopeStateValues, overlayStates, projectSemanticState, type SemanticState, type ScopeStateValues, type StateScope } from "./state.ts";
+import { applyPatch, isObject } from "./json.ts";
+import { captureScopeSelection, DEFAULT_SCOPE_SELECTION, type ScopeSelection } from "./selection.ts";
 import type { ScopeRevisions, TransitionBoundary } from "./temporal.ts";
 
 export const STATUS_KEY = "state-flow";
@@ -22,32 +24,46 @@ 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 };
+	temporal?: { head: TransitionBoundary; historyDepth: number; tailCounts: Partial<Record<StateScope, number>>; revisions: Partial<ScopeRevisions> };
 	staleArtifacts: readonly StaleArtifactDiagnostic[];
 	durableStateError?: string;
 	publicationError?: string;
 }
 
-export function formatScopeRevisionVector(revisions: ScopeRevisions): string {
-	return `g${revisions.global}c${revisions.cwd}s${revisions.session}`;
+function assertScopeNumbers(values: Partial<ScopeRevisions>, selection: ScopeSelection, label: string): void {
+	if (!isObject(values) || Object.keys(values).length !== selection.length
+		|| Object.keys(values).some(scope => !selection.includes(scope as StateScope))
+		|| 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 compactStatus(snapshot: Snapshot, _revisions: ScopeRevisions, colorize: Colorize): string | undefined {
+export function formatScopeRevisionVector(revisions: Partial<ScopeRevisions>, selection: ScopeSelection = DEFAULT_SCOPE_SELECTION): string {
+	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: Snapshot, _revisions: Partial<ScopeRevisions>, colorize: Colorize): string | undefined {
 	const { mode } = snapshot.config;
 	if (mode === "off") return undefined;
 	return `${colorize("accent", "state-flow")} ${colorize("dim", isActiveRestorationBlocked(snapshot) ? "active (blocked)" : mode)}`;
 }
 
-function countArtifacts(states: ScopedStates, scope: StateScope): number {
-	return Object.keys(states[scope].artifacts).length;
+function countArtifacts(states: ScopeStateValues, scope: StateScope): number {
+	return Object.keys(states[scope]!.artifacts ?? {}).length;
 }
 
-const STATUS_PLANES = ["intents", "contract", "working", "artifacts", "response", "lazy"] as const;
+const STATUS_PLANES = ["intents", "strategy", "tactics", "artifacts", "response", "lazy"] as const;
 const encoder = new TextEncoder();
 
 function isPresentPlane(value: unknown): boolean {
@@ -55,16 +71,18 @@ function isPresentPlane(value: unknown): boolean {
 	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: ScopedStates): string[] {
+/** Operator-only footprint: serialized plane sizes and intent-owned share of top-level tactics/lazy entries. */
+export function scopeMemoryLines(states: ScopeStateValues, selection: ScopeSelection = DEFAULT_SCOPE_SELECTION): string[] {
+	const selected = captureScopeSelection(selection);
+	assertScopeStateValues(states, selected);
 	const lines: string[] = [];
-	for (const scope of ["global", "cwd", "session"] as const) {
+	for (const scope of selected) {
 		const state = states[scope] as SemanticState;
 		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"] as const).flatMap((plane) => {
+		const shares = (["tactics", "lazy"] as const).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}`];
@@ -75,41 +93,57 @@ export function scopeMemoryLines(states: ScopedStates): string[] {
 }
 
 export function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostics): string {
+	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<SemanticState>((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: StateScope) => countArtifacts(diagnostics.scopeStates, scope);
-	const hasArtifacts = available && (["global", "cwd", "session"] as const).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]),