@llblab/pi-kit 0.37.0 → 0.38.0

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

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { isJsonValue, isObject, sameJson, validatePatch, type JsonObject, type JsonValue } from "./json.ts";
-import type { ScopedSemanticStates, StateScope } from "./state.ts";
+import type { ScopeStateValues, StateScope } from "./state.ts";
 
 export const DEFAULT_HISTORY_LIMIT = 7;
 export const MAX_HISTORY_LIMIT = 100;
@@ -10,8 +10,8 @@ export interface RecentScopePatch {
 	patch: {
 		[key: string]: JsonValue | undefined;
 		intents?: JsonObject | null;
-		contract?: JsonObject | null;
-		working?: JsonObject | null;
+		strategy?: JsonObject | null;
+		tactics?: JsonObject | null;
 		artifacts?: JsonObject | null;
 		lazy?: JsonObject | null;
 		response?: string | null;
@@ -31,7 +31,7 @@ export interface RecentTransition extends AcceptedTransition {
 
 export type RecentTransitionWindow = RecentTransition[];
 const SCOPES = new Set<StateScope>(["global", "cwd", "session"]);
-const PATCH_KEYS = new Set(["artifacts", "contract", "working", "intents", "response", "lazy"]);
+const PATCH_KEYS = new Set(["artifacts", "strategy", "tactics", "intents", "response", "lazy"]);
 
 /** Normalize accepted replacements into recursive-merge replay, including removals. */
 function replayPatch(before: JsonObject, after: JsonObject): JsonObject {
@@ -57,6 +57,7 @@ function validateScopedPatch(value: unknown): asserts value is RecentScopePatch
 		throw new Error(`Recent State Flow transition has an unknown scope: ${String(value.scope)}`);
 	}
 	validatePatch(value.patch);
+	if (Object.hasOwn(value.patch, "contract") || Object.hasOwn(value.patch, "working")) throw new Error("Retired State Flow semantic plane in target patch");
 	for (const [key, field] of Object.entries(value.patch)) {
 		const valid = key === "response"
 			? value.scope === "session" && (field === null || typeof field === "string")
@@ -78,11 +79,19 @@ export function validateRecentTransition(value: unknown): asserts value is Recen
 	}
 }
 
-export function createAcceptedTransition(currentStates: ScopedSemanticStates, nextStates: ScopedSemanticStates, id?: string): AcceptedTransition | undefined {
+export function createAcceptedTransition(currentStates: ScopeStateValues, nextStates: ScopeStateValues, id?: string): AcceptedTransition | undefined {
+	const owners = Object.keys(currentStates) as StateScope[];
+	if (owners.length === 0 || owners.some((scope) => !SCOPES.has(scope))
+		|| Object.keys(nextStates).length !== owners.length || owners.some((scope) => !Object.hasOwn(nextStates, scope))) {
+		throw new Error("Accepted State Flow replay requires matching nonempty owner sets");
+	}
 	const transitions: RecentScopePatch[] = [];
 	for (const scope of SCOPES) {
-		const patch = replayPatch(currentStates[scope], nextStates[scope]);
-		if ((currentStates[scope].response ?? "") === (nextStates[scope].response ?? "")) delete patch.response;
+		if (!Object.hasOwn(currentStates, scope)) continue;
+		const before = currentStates[scope], after = nextStates[scope];
+		if (!isObject(before) || !isObject(after)) throw new Error("Accepted State Flow replay requires present owner values");
+		const patch = replayPatch(before, after);
+		if ((before.response ?? "") === (after.response ?? "")) delete patch.response;
 		if (Object.keys(patch).length > 0) transitions.push({ scope, patch });
 	}
 	if (transitions.length === 0) return undefined;

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

@@ -49,7 +49,8 @@ function applyOwnedArrayPatch(
 	return next;
 }
 
-function applyOwnedPatch(
+/** Internal path-copying step; callers must own the detached draft and collect failures privately. */
+export function applyOwnedPatch(
 	state: JsonObject, patch: JsonObject, missingDeletions?: MissingDeletion[], path = "", unavailablePath?: string,
 ): JsonObject {
 	let next = state;

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

@@ -1,13 +1,14 @@
-import type { MaterializedState, ScopedStates, StateScope } from "./state.ts";
+import { assertScopeStateValues, type SemanticState, type ScopeStateValues, type ScopedStates, type StateScope } from "./state.ts";
+import { captureScopeSelection, DEFAULT_SCOPE_SELECTION, type ScopeSelection } from "./selection.ts";
 
-function hasSemanticMemory(state: MaterializedState): boolean {
-	return Object.keys(state.contract).length > 0 || Object.keys(state.working).length > 0;
+function hasSemanticMemory(state: SemanticState): boolean {
+	return Object.keys(state.strategy ?? {}).length > 0 || Object.keys(state.tactics ?? {}).length > 0;
 }
 
-export function retainedMemoryScopes(states: ScopedStates): Record<StateScope, boolean> {
-	return {
-		global: hasSemanticMemory(states.global),
-		cwd: hasSemanticMemory(states.cwd),
-		session: hasSemanticMemory(states.session),
-	};
+export function retainedMemoryScopes(states: ScopedStates): Record<StateScope, boolean>;
+export function retainedMemoryScopes(states: ScopeStateValues, selection: ScopeSelection): Partial<Record<StateScope, boolean>>;
+export function retainedMemoryScopes(states: ScopeStateValues, selection: ScopeSelection = DEFAULT_SCOPE_SELECTION): Partial<Record<StateScope, boolean>> {
+	const selected = captureScopeSelection(selection);
+	assertScopeStateValues(states, selected);
+	return Object.fromEntries(selected.map(scope => [scope, hasSemanticMemory(states[scope]!)]));
 }

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

@@ -0,0 +1,189 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { parseArtifactProvenanceRegistry } from "./artifact.ts";
+import { MAX_HISTORY_LIMIT } from "./history.ts";
+import { canonicalJson, isJsonValue, isObject, validatePatch, type JsonObject, type JsonValue } from "./json.ts";
+import { parseStateReadPath, parseValuePath } from "./query.ts";
+import { assertRetainedModules, validateRetainedModules, type RetainedModules } from "./semantic-module.ts";
+import { assertNoRetiredSemanticPlanes, type StateScope } from "./state.ts";
+import { validateScopeStream, type ScopeStream } from "./temporal.ts";
+
+/** Owns temporary pure semantic-dialect conversion; excludes I/O, publication, backup and lifecycle authority. */
+export interface SemanticMigrationCandidate {
+	sourceVersion: 1 | 2 | 3 | 4;
+	targetVersion: 3 | 4;
+	/** A format conversion is not an authored semantic transition or revision. */
+	requiresConversion: boolean;
+	stream: ScopeStream;
+}
+
+export type ScopeMigrationFile = "checkpoint" | "patches" | "meta";
+export type ScopeMigrationSources = Partial<Record<ScopeMigrationFile, Uint8Array>>;
+
+/** Detached evidence for later backup/CAS, not a publication capability or a filesystem observation. */
+export interface MigrationByteReceipt {
+	bytes: Uint8Array;
+	identity: `sha256:${string}`;
+}
+
+export interface SerializedSemanticMigrationCandidate extends SemanticMigrationCandidate {
+	basis: Record<ScopeMigrationFile, MigrationByteReceipt>;
+	target: Record<ScopeMigrationFile, string>;
+}
+
+const LEGACY_PLANES = new Map([["contract", "strategy"], ["working", "tactics"]]);
+const LEGACY_SEMANTIC_PLANES = new Set(["intents", "contract", "working", "artifacts", "response", "lazy"]);
+const LEGACY_LOCATOR = /^(?:((?:effective|global|cwd|session)(?:\[\d+\])?(?:\.patches(?:\[\d+\])?)?)\.)?(contract|working)(?=$|\.|\[)/;
+const MARKED_LOCATOR = /(?<![\p{L}\p{N}_$.[\]:/\\-])\$([\p{L}\p{N}_$.[\]:-]+)(?![\p{L}\p{N}_$.[\]:/\\-])/gu;
+
+function translateLocator(path: string): string {
+	const match = LEGACY_LOCATOR.exec(path);
+	if (!match) return path;
+	const [, prefix, plane] = match;
+	const suffix = path.slice(match[0].length);
+	try {
+		if (prefix) parseStateReadPath(prefix, MAX_HISTORY_LIMIT);
+		// The unchanged lazy root lets the shared parser validate selectors after legacy names retire.
+		parseValuePath(`lazy${suffix}`);
+	} catch {
+		return path;
+	}
+	return `${prefix ? `${prefix}.` : ""}${LEGACY_PLANES.get(plane!)!}${suffix}`;
+}
+
+function translateReferences(value: JsonValue): JsonValue {
+	if (typeof value === "string") return value.replace(MARKED_LOCATOR, (_token, path: string) => `$${translateLocator(path)}`);
+	if (Array.isArray(value)) return value.map(translateReferences);
+	if (!isObject(value)) return value;
+	return Object.fromEntries(Object.entries(value).map(([key, child]) => [key,
+		key === "$ref" && typeof child === "string" ? translateLocator(child) : translateReferences(child)]));
+}
+
+function translateArtifacts(value: JsonValue): JsonValue {
+	if (!isObject(value)) return translateReferences(value);
+	return Object.fromEntries(Object.entries(value).map(([path, card]) => [path, !isObject(card) ? translateReferences(card)
+		: Object.fromEntries(Object.entries(card).map(([key, child]) => [key,
+			// Retired embedded provenance is evidence, never a semantic reference namespace.
+			["hash", "compiler", "compiled_at"].includes(key) ? structuredClone(child) : translateReferences(child)]))]));
+}
+
+/** Translate a raw legacy checkpoint or replay patch before any known-field filtering. */
+export function translateLegacySemanticObject(value: unknown): JsonObject {
+	validatePatch(value);
+	for (const plane of LEGACY_PLANES.values()) {
+		if (Object.hasOwn(value, plane)) throw new Error(`Target State Flow semantic plane in legacy format: ${plane}`);
+	}
+	return Object.fromEntries(Object.entries(value).map(([key, child]) => [LEGACY_PLANES.get(key) ?? key,
+		key === "artifacts" ? translateArtifacts(child) : LEGACY_SEMANTIC_PLANES.has(key) ? translateReferences(child) : structuredClone(child)]));
+}
+
+/** Build a detached target candidate; publication still belongs to the guarded storage transaction. */
+export function prepareSemanticMigration(
+	value: unknown, scope: StateScope, sourceVersion: number, historyLimit = MAX_HISTORY_LIMIT, targetModules?: RetainedModules,
+): SemanticMigrationCandidate {
+	if (sourceVersion !== 1 && sourceVersion !== 2 && sourceVersion !== 3 && sourceVersion !== 4) throw new Error("Unsupported State Flow migration source version");
+	validatePatch(value);
+	if (!isObject(value.checkpoint) || !Array.isArray(value.patches)) throw new Error("Invalid temporal checkpoint/tail envelope");
+	if (targetModules !== undefined) validateRetainedModules(targetModules);
+	if (sourceVersion === 4) {
+		validateRetainedModules(value.modules);
+		if (targetModules !== undefined) assertRetainedModules(value.modules, targetModules);
+	}
+	else if (Object.hasOwn(value, "modules")) throw new Error("Legacy State Flow stream cannot declare modules");
+	const translate = (state: unknown): JsonObject => {
+		if (sourceVersion !== 4 && targetModules !== undefined && isObject(state)
+			&& Object.keys(state).some(key => key.startsWith("x_"))) throw new Error("Legacy State Flow external namespace collision");
+		if (sourceVersion < 3) return translateLegacySemanticObject(state);
+		validatePatch(state);
+		assertNoRetiredSemanticPlanes(state);
+		return structuredClone(state);
+	};
+	// Preserve envelope fields until strict target validation; malformed input must not be sanitized into acceptance.
+	const stream = {
+		...structuredClone(value),
+		...(targetModules === undefined ? {} : { modules: structuredClone(targetModules) }),
+		checkpoint: { ...structuredClone(value.checkpoint), state: translate(value.checkpoint.state) },
+		patches: value.patches.map((record) => {
+			if (!isObject(record)) throw new Error("Invalid temporal patch envelope");
+			return { ...structuredClone(record), patch: translate(record.patch) };
+		}),
+	};
+	validateScopeStream(stream, scope, historyLimit);
+	const targetVersion = sourceVersion === 4 || targetModules !== undefined ? 4 : 3;
+	return { sourceVersion, targetVersion, requiresConversion: sourceVersion !== targetVersion, stream };
+}
+
+function captureMigrationBytes(value: Uint8Array | undefined, label: string): MigrationByteReceipt {
+	if (!(value instanceof Uint8Array)) throw new Error(`Incomplete State Flow migration cohort: ${label} bytes are required`);
+	const bytes = new Uint8Array(value);
+	return { bytes, identity: `sha256:${createHash("sha256").update(bytes).digest("hex")}` };
+}
+
+function decodeMigrationText(bytes: Uint8Array, label: string): string {
+	try {
+		// Do not silently repair invalid UTF-8 or strip a BOM that ordinary JSON decoding would reject.
+		return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+	} catch {
+		throw new Error(`State Flow migration ${label} is not valid UTF-8`);
+	}
+}
+
+function parseMigrationJson(source: string, label: string): JsonValue {
+	let value: unknown;
+	try { value = JSON.parse(source); }
+	catch { throw new Error(`State Flow migration ${label} contains invalid JSON`); }
+	if (!isJsonValue(value)) throw new Error(`State Flow migration ${label} must contain finite JSON data`);
+	return value;
+}
+
+/** Decode a complete raw owner cohort before filtering; never load files, normalize authority or publish. */
+export function prepareSerializedScopeMigration(
+	sources: ScopeMigrationSources, scope: StateScope, expectedCwd?: string, targetModules?: RetainedModules,
+): SerializedSemanticMigrationCandidate {
+	const basis = {
+		checkpoint: captureMigrationBytes(sources.checkpoint, "checkpoint"),
+		patches: captureMigrationBytes(sources.patches, "patches"),
+		meta: captureMigrationBytes(sources.meta, "metadata"),
+	};
+	const metaText = decodeMigrationText(basis.meta.bytes, "metadata");
+	const metadata = parseMigrationJson(metaText, "metadata");
+	if (!isObject(metadata)) throw new Error("Invalid State Flow migration metadata");
+	const version = metadata.version;
+	if (version !== 1 && version !== 2 && version !== 3 && version !== 4) throw new Error("Unsupported State Flow migration source version");
+	if (version === 4) validateRetainedModules(metadata.modules);
+	else if (targetModules !== undefined && Object.hasOwn(metadata, "modules")) throw new Error("Legacy State Flow modules metadata collision");
+	if (scope === "cwd") {
+		if (expectedCwd === undefined) throw new Error("State Flow CWD migration requires its canonical identity");
+		if (metadata.owner === undefined) throw new Error("State Flow CWD scope identity is missing");
+		if (!isObject(metadata.owner) || Object.keys(metadata.owner).join(",") !== "cwd" || metadata.owner.cwd !== resolve(expectedCwd)) {
+			throw new Error("State Flow CWD migration identity mismatch");
+		}
+	} else if (expectedCwd !== undefined) throw new Error("Only State Flow CWD migration accepts a CWD identity");
+	if (Object.hasOwn(metadata, "artifacts")) parseArtifactProvenanceRegistry(metadata.artifacts, "State Flow migration provenance");
+	const temporal = metadata.temporal;
+	if (!isObject(temporal) || !Object.hasOwn(temporal, "checkpoint") || !Array.isArray(temporal.patches)) {
+		throw new Error("Invalid State Flow migration temporal metadata");
+	}
+	if (version >= 3 && !Object.hasOwn(temporal, "revision")) throw new Error("State Flow target migration metadata requires a revision");
+	const checkpointText = decodeMigrationText(basis.checkpoint.bytes, "checkpoint");
+	const patchesText = decodeMigrationText(basis.patches.bytes, "tail");
+	const checkpoint = parseMigrationJson(checkpointText, "checkpoint");
+	const patches = patchesText.split(/\r?\n/).flatMap((line, index) => line.trim().length === 0 ? []
+		: [parseMigrationJson(line, `tail line ${index + 1}`)]);
+	const boundaries = temporal.patches;
+	if (boundaries.length !== patches.length) throw new Error("State Flow migration metadata does not match its semantic tail");
+	const candidate = prepareSemanticMigration({
+		...(version === 4 ? { modules: metadata.modules } : {}),
+		revision: temporal.revision === undefined ? patches.length : temporal.revision,
+		checkpoint: { through: temporal.checkpoint, state: checkpoint },
+		patches: patches.map((patch, index) => ({ transition: boundaries[index], patch })),
+	}, scope, version, MAX_HISTORY_LIMIT, targetModules);
+	const target = !candidate.requiresConversion && targetModules === undefined ? { checkpoint: checkpointText, patches: patchesText, meta: metaText } : {
+		checkpoint: `${canonicalJson(candidate.stream.checkpoint.state)}\n`,
+		patches: candidate.stream.patches.map((record) => `${canonicalJson(record.patch)}\n`).join(""),
+		meta: `${canonicalJson({ ...metadata, version: candidate.targetVersion,
+			...(candidate.stream.modules === undefined ? {} : { modules: candidate.stream.modules }),
+			temporal: { ...temporal, revision: candidate.stream.revision } })}\n`,
+	};
+	return { ...candidate, basis, target };
+}

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

@@ -0,0 +1,136 @@
+// Domain: detached model/canonical patch, locator and structured-reference translation.
+// Excludes: SDK schemas, mode, acquisition, existence checks, storage and request/publication authority.
+import { isJsonValue, isObject, type JsonObject, type JsonValue, type MissingDeletion } from "./json.ts";
+import { DEFAULT_HISTORY_LIMIT } from "./history.ts";
+import { parseStateReadPath, parseValuePath } from "./query.ts";
+import { captureScopeSelection, type ScopeSelection } from "./selection.ts";
+import type { AtomicScopePatches, StateScope } from "./state.ts";
+
+import { MODEL_PLANE_NAMES } from "./planes.ts";
+
+const PATCH_PLANES = MODEL_PLANE_NAMES;
+const SEMANTIC_ROOT = /^(?:intents|strategy|tactics|artifacts|response|lazy|x_[a-z][a-z0-9_]*)(?=\.|\[|$)/;
+const PATCH_PATH = /^(?:effective|global|cwd|session)\.patches(?:\[\d+\])?$/;
+
+function dense(value: JsonValue): boolean {
+	if (Array.isArray(value)) {
+		for (let i = 0; i < value.length; i++) if (!Object.hasOwn(value, i) || !dense(value[i]!)) return false;
+		return true;
+	}
+	return !isObject(value) || Object.values(value).every(dense);
+}
+
+function capture(value: unknown): JsonValue {
+	if (!isJsonValue(value)) throw new Error("Model interface requires finite acyclic JSON data");
+	let copy: unknown;
+	try { copy = structuredClone(value); } catch { throw new Error("Model interface requires detached JSON data"); }
+	if (!isJsonValue(copy) || !dense(copy)) throw new Error("Model interface requires finite dense JSON data");
+	return copy;
+}
+
+function translateReferences(value: JsonValue, translate: (ref: string) => string): JsonValue {
+	if (Array.isArray(value)) return value.map(child => translateReferences(child, translate));
+	if (!isObject(value)) return value;
+	return Object.fromEntries(Object.entries(value).map(([key, child]) => [key,
+		key === "$ref" && typeof child === "string" ? translate(child) : translateReferences(child, translate)]));
+}
+
+function semanticReference(path: string, external?: readonly string[]): boolean {
+	const root = SEMANTIC_ROOT.exec(path)?.[0];
+	if (!root || root.startsWith("x_") && external !== undefined && !external.includes(root)) return false;
+	try { parseValuePath(path); return true; } catch { return false; }
+}
+
+/** Anchor eligible flat current references, never text/resource/effective/historical references. */
+export function canonicalizeModelReferences(value: unknown, scopes: ScopeSelection, external: readonly string[] = []): JsonValue {
+	const selected = captureScopeSelection(scopes), copy = capture(value);
+	return selected.length !== 1 ? copy : translateReferences(copy, ref => semanticReference(ref, external) ? `${selected[0]}.${ref}` : ref);
+}
+
+/** Strip only validated same-owner current semantic reference prefixes; canonical data stays untouched. */
+export function projectModelReferences(value: unknown, scopes: ScopeSelection, external: readonly string[] = []): JsonValue {
+	const selected = captureScopeSelection(scopes), copy = capture(value), prefix = `${selected[0]}.`;
+	return selected.length !== 1 ? copy : translateReferences(copy, ref => ref.startsWith(prefix) && semanticReference(ref.slice(prefix.length), external) ? ref.slice(prefix.length) : ref);
+}
+
+function admitKeys(value: JsonObject, selected: ScopeSelection, external: readonly string[]): void {
+	const keys = Object.keys(value);
+	if (!keys.length) throw new Error("Model patch requires at least one supplied branch");
+	if (selected.length === 1) {
+		if (keys.some(key => !PATCH_PLANES.includes(key) && !external.includes(key))) throw new Error("Single-owner model patches require flat semantic planes");
+	} else for (const key of keys) {
+		if (!selected.includes(key as StateScope)) throw new Error(`Multi-owner model patches require participating explicit owners; does not accept field ${key}`);
+	}
+}
+
+function planePatch(value: unknown, external: readonly string[]): asserts value is JsonObject {
+	if (!isObject(value) || !Object.keys(value).length) throw new Error("Model scope patch must be a nonempty object");
+	for (const key of Object.keys(value)) {
+		if (!PATCH_PLANES.includes(key) && !external.includes(key)) throw new Error(`Model patch does not accept semantic plane ${key}`);
+		if (!isObject(value[key])) throw new Error(`Model patch plane ${key} must be a JSON object`);
+	}
+}
+
+/** Value normalization only; callers must validate their original request/owner before invoking it. */
+export function normalizeModelPatches(value: unknown, scopes: ScopeSelection, external: readonly string[] = []): AtomicScopePatches {
+	const selected = captureScopeSelection(scopes);
+	if (!isObject(value)) throw new Error("Model patch must be an object");
+	// Reject shape/excluded owners before touching a supplied owner's payload or cloning it.
+	admitKeys(value, selected, external);
+	const copy = (selected.length === 1 ? canonicalizeModelReferences(value, selected, external) : capture(value)) as JsonObject;
+	admitKeys(copy, selected, external);
+	if (selected.length === 1) {
+		planePatch(copy, external);
+		return { [selected[0]]: copy };
+	}
+	for (const key of Object.keys(copy)) planePatch(copy[key], external);
+	return copy as AtomicScopePatches;
+}
+
+/** Compilation target syntax, not a query locator: preserve the exact opaque source key. */
+export function projectModelArtifactTarget(scope: StateScope, path: string, scopes: ScopeSelection): string {
+	const selected = captureScopeSelection(scopes);
+	if (!selected.includes(scope)) throw new Error("Model artifact target scope is excluded");
+	if (typeof path !== "string") throw new Error("Model artifact target path must be a string");
+	return `${selected.length === 1 ? "" : scope + "."}artifacts[${JSON.stringify(path)}]`;
+}
+
+/** Known deletion-report JSON pointers only; do not parse source keys or rewrite diagnostics. */
+export function projectModelMissingDeletion(deletion: MissingDeletion, scopes: ScopeSelection): MissingDeletion {
+	const selected = captureScopeSelection(scopes);
+	const project = (path: string) => {
+		if (typeof path !== "string") throw new Error("Model deletion locator must be a string");
+		const prefix = `/${selected[0]}`;
+		return selected.length === 1 && (path === prefix || path.startsWith(prefix + "/")) ? path.slice(prefix.length) : path;
+	};
+	return { path: project(deletion.path), unavailablePath: project(deletion.unavailablePath) };
+}
+
+function validateReadPath(path: string, selected: ScopeSelection, historyLimit: number): void {
+	const query = PATCH_PATH.test(path) ? parseStateReadPath(path, historyLimit) : parseStateReadPath(parseValuePath(path).root, historyLimit);
+	if (query.scope !== undefined && !selected.includes(query.scope)) throw new Error("Model read scope is excluded");
+}
+
+/** Sole-owner locators bind to that exact owner; multi-owner effective aliases keep their existing meaning. */
+export function normalizeModelReadPath(path: string, scopes: ScopeSelection, historyLimit = DEFAULT_HISTORY_LIMIT): string {
+	const selected = captureScopeSelection(scopes);
+	if (typeof path !== "string") throw new Error("Model read path must be a string");
+	let canonical = path;
+	if (selected.length === 1) {
+		if (/^patches(?:\[\d+\])?$/.test(path)) canonical = `${selected[0]}.${path}`;
+		else if (SEMANTIC_ROOT.test(path)) canonical = `${selected[0]}.${path}`;
+		else if (/^effective(?=\.|\[|$)/.test(path)) canonical = selected[0] + path.slice("effective".length);
+	}
+	validateReadPath(canonical, selected, historyLimit);
+	return canonical;
+}
+
+/** Presentation locator only: history keeps an explicit projection root and does not become an array index. */
+export function projectModelReadPath(path: string, scopes: ScopeSelection, historyLimit = DEFAULT_HISTORY_LIMIT): string {
+	const selected = captureScopeSelection(scopes), canonical = normalizeModelReadPath(path, selected, historyLimit);
+	if (selected.length !== 1) return canonical;
+	const prefix = `${selected[0]}.`;
+	if (canonical.startsWith(prefix) && /^patches(?:\[\d+\])?$/.test(canonical.slice(prefix.length))) return canonical.slice(prefix.length);
+	if (canonical.startsWith(prefix) && semanticReference(canonical.slice(prefix.length))) return canonical.slice(prefix.length);
+	return "effective" + canonical.slice(selected[0].length);
+}

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

@@ -0,0 +1,119 @@
+// Domain: public module registration, native-host ownership and revocable catalog snapshots.
+// Excludes: storage, callback evaluation, inference and semantic publication.
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { JsonObject, JsonValue } from "./json.ts";
+import type { StateFlowModule } from "./semantic-module.ts";
+
+type SessionManager = ExtensionContext["sessionManager"];
+type Definition = StateFlowModule<JsonObject, JsonValue>;
+interface Binding {
+	readonly manager: SessionManager;
+	readonly checkOwner: () => void;
+	readonly register: (definition: Definition) => () => void;
+	readonly modules: Map<string, Definition>;
+	controller: AbortController;
+}
+interface Bridge { readonly version: 1; readonly hosts: WeakMap<SessionManager, Binding> }
+const BRIDGE = Symbol.for("@llblab/pi-state-flow/modules/v1");
+
+function bridge(create = false): Bridge | undefined {
+	const globals = globalThis as unknown as Record<symbol, unknown>;
+	let value = globals[BRIDGE];
+	if (value === undefined && create) globals[BRIDGE] = value = { version: 1, hosts: new WeakMap() } satisfies Bridge;
+	if (value === undefined) return undefined;
+	if (!value || typeof value !== "object") throw new Error("Incompatible State Flow module registration bridge");
+	const candidate = value as Partial<Bridge>;
+	if (candidate.version !== 1 || !(candidate.hosts instanceof WeakMap)) throw new Error("Incompatible State Flow module registration bridge");
+	return candidate as Bridge;
+}
+
+function captureDefinition(definition: Definition): Definition {
+	if (!definition || typeof definition !== "object") throw new Error("Invalid State Flow module registration");
+	const { apiVersion, id, schemaVersion, immutable, validate, context, captureInput, produce } = definition;
+	if (apiVersion !== 1) throw new Error("Unsupported State Flow module API version");
+	if (typeof id !== "string" || !/^x_[a-z][a-z0-9_]*$/.test(id)) throw new Error("External State Flow module id must match x_[a-z][a-z0-9_]*");
+	if (!Number.isSafeInteger(schemaVersion) || schemaVersion < 1) throw new Error("Invalid State Flow module schema version");
+	if (typeof immutable !== "boolean" || typeof validate !== "function" || typeof context !== "function"
+		|| (captureInput !== undefined && typeof captureInput !== "function") || (produce !== undefined && typeof produce !== "function")) {
+		throw new Error("Invalid State Flow module callbacks or authoring policy");
+	}
+	// Preserve class/constructor-injected services while capturing policy and callback identities.
+	return Object.freeze({ apiVersion, id, schemaVersion, immutable, validate: validate.bind(definition), context: context.bind(definition),
+		...(captureInput ? { captureInput: captureInput.bind(definition) } : {}), ...(produce ? { produce: produce.bind(definition) } : {}) });
+}
+
+export interface StateFlowModuleCatalog {
+	readonly modules: readonly Definition[];
+	readonly signal: AbortSignal;
+	assertCurrent(): void;
+}
+
+/** Registry metadata alone grants no content, source, private or publication authority. */
+export function registerStateFlowModule<Content extends JsonObject, Input extends JsonValue>(
+	manager: SessionManager, definition: StateFlowModule<Content, Input>,
+): () => void {
+	const host = bridge()?.hosts.get(manager);
+	if (!host) throw new Error("State Flow module host unavailable; load State Flow first and register at session_start");
+	return host.register(definition as unknown as Definition);
+}
+
+/** One composition-root owner; catalogs are revoked independently of memory mode or storage. */
+export class StateFlowModuleHost {
+	#binding: Binding | undefined;
+	bind(manager: SessionManager, checkOwner: () => void): void {
+		checkOwner();
+		const hosts = bridge(true)!.hosts;
+		const existing = hosts.get(manager);
+		if (existing && existing !== this.#binding) throw new Error("State Flow module host already bound to this native session manager");
+		this.dispose();
+		if (this.#binding || hosts.has(manager)) throw new Error("State Flow module host changed during rebind");
+		checkOwner();
+		const binding: Binding = { manager, checkOwner, modules: new Map(), controller: new AbortController(), register: definition => this.#register(binding, definition) };
+		this.#binding = binding;
+		hosts.set(manager, binding);
+	}
+	#check(binding: Binding): void {
+		if (this.#binding !== binding || bridge()?.hosts.get(binding.manager) !== binding) throw new Error("State Flow module host ownership changed");
+		binding.checkOwner();
+	}
+	#changed(binding: Binding): void {
+		const previous = binding.controller;
+		binding.controller = new AbortController();
+		previous.abort(new Error("State Flow module catalog changed"));
+	}
+	#register(binding: Binding, definition: Definition): () => void {
+		this.#check(binding);
+		const captured = captureDefinition(definition);
+		this.#check(binding);
+		if (binding.modules.has(captured.id)) throw new Error(`State Flow module id already registered: ${captured.id}`);
+		binding.modules.set(captured.id, captured);
+		this.#changed(binding);
+		return () => {
+			if (this.#binding !== binding || binding.modules.get(captured.id) !== captured) return;
+			binding.modules.delete(captured.id);
+			this.#changed(binding);
+		};
+	}
+	captureIfBound(): StateFlowModuleCatalog | undefined {
+		return this.#binding ? this.capture() : undefined;
+	}
+	capture(): StateFlowModuleCatalog {
+		const binding = this.#binding;
+		if (!binding) throw new Error("State Flow module host unavailable");
+		this.#check(binding);
+		const signal = binding.controller.signal;
+		return Object.freeze({ modules: Object.freeze([...binding.modules.values()]), signal, assertCurrent: () => {
+			this.#check(binding);
+			signal.throwIfAborted();
+		} });
+	}
+	dispose(): void {
+		const binding = this.#binding;
+		if (!binding) return;
+		this.#binding = undefined;
+		const hosts = bridge()?.hosts;
+		if (hosts?.get(binding.manager) === binding) hosts.delete(binding.manager);
+		binding.modules.clear();
+		binding.controller.abort(new Error("State Flow module host retired"));
+	}
+}

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

@@ -31,8 +31,8 @@ export class OwnedOperationSlot<E extends OwnedOperation> {
 	/** Abort and forget the current owner; returns its operation for optional awaiting. */
 	cancel(): E["operation"] | undefined {
 		const entry = this.#current;
-		entry?.controller.abort();
 		this.#current = undefined;
+		entry?.controller.abort();
 		return entry?.operation;
 	}
 
@@ -66,8 +66,9 @@ export class RenewableLifetime {
 
 	/** Abort current holders and open a fresh lifetime. */
 	renew(reason?: unknown): void {
-		this.#controller.abort(reason);
+		const previous = this.#controller;
 		this.#controller = new AbortController();
+		previous.abort(reason);
 	}
 
 	/** Abort current holders without opening a new lifetime (shutdown). */

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

@@ -2,7 +2,7 @@ import { isObject, type JsonObject, type JsonValue } from "./json.ts";
 import type { SemanticState, StateScope } from "./state.ts";
 
 /** Planes whose object keys an intent may own by structured reference. */
-export type OwnedPlane = "working" | "lazy";
+export type OwnedPlane = "strategy" | "tactics" | "lazy";
 
 /** One same-scope object-key target of an intent ownership reference. */
 export interface OwnedPath {
@@ -10,14 +10,14 @@ export interface OwnedPath {
 	keys: string[];
 }
 
-const OWNED_PLANES = new Set<string>(["working", "lazy"]);
+const OWNED_PLANES = new Set<string>(["strategy", "tactics", "lazy"]);
 // Same key grammar as read_state value paths; array selectors never parse.
 const OBJECT_KEY = /^[A-Za-z_$][A-Za-z0-9_$-]*$/;
 
 /**
  * Parse one structured `$ref` target as an ownership path of `scope`.
  * Cross-scope, unscoped, `effective`, historical, plane-root, array-element
- * and non-`working`/`lazy` targets are not ownership targets.
+ * and non-`strategy`/`tactics`/`lazy` targets are not ownership targets.
  */
 export function parseOwnedPath(scope: StateScope, ref: string): OwnedPath | undefined {
 	const parts = ref.split(".");
@@ -68,7 +68,7 @@ function exists(state: SemanticState, path: OwnedPath): boolean {
 
 /**
  * Compute the same-scope ownership cascade for intent keys removed between
- * `before` and `after` (the state after authored operations). A target is
+ * `before` and `after` (the normalized intent-phase view, before other writes). A target is
  * kept while any remaining intent references it, an ancestor or a descendant;
  * missing targets are skipped. The result is minimal (no target below
  * another) and deterministically ordered.
@@ -111,9 +111,9 @@ export function formatOwnedPath(scope: StateScope, path: OwnedPath): string {
 	return [scope, path.plane, ...path.keys].join(".");
 }
 
-/** Top-level `working`/`lazy` keys that at least one current intent of `scope` owns. */
+/** Top-level ownership-eligible keys referenced by current intents of `scope`. */
 export function ownedTopLevelKeys(scope: StateScope, state: SemanticState): Record<OwnedPlane, Set<string>> {
-	const owned: Record<OwnedPlane, Set<string>> = { working: new Set(), lazy: new Set() };
+	const owned: Record<OwnedPlane, Set<string>> = { strategy: new Set(), tactics: new Set(), lazy: new Set() };
 	const intents = isObject(state.intents) ? state.intents : {};
 	for (const value of Object.values(intents)) for (const path of extractOwnedPaths(scope, value)) owned[path.plane].add(path.keys[0]!);
 	return owned;