@llblab/pi-kit 0.37.1 → 0.38.0

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

@@ -1,5 +1,5 @@
 import { type JsonObject, type JsonValue } from "./json.ts";
-import type { ScopedSemanticStates, StateScope } from "./state.ts";
+import type { ScopeStateValues, StateScope } from "./state.ts";
 export declare const DEFAULT_HISTORY_LIMIT = 7;
 export declare const MAX_HISTORY_LIMIT = 100;
 export interface RecentScopePatch {
@@ -7,8 +7,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;
@@ -25,6 +25,6 @@ export interface RecentTransition extends AcceptedTransition {
 }
 export type RecentTransitionWindow = RecentTransition[];
 export declare function validateRecentTransition(value: unknown): asserts value is RecentTransition;
-export declare function createAcceptedTransition(currentStates: ScopedSemanticStates, nextStates: ScopedSemanticStates, id?: string): AcceptedTransition | undefined;
+export declare function createAcceptedTransition(currentStates: ScopeStateValues, nextStates: ScopeStateValues, id?: string): AcceptedTransition | undefined;
 /** Preserve the configured per-scope budget, filtering in selected-lineage order. */
 export declare function projectRecentTransitionsWithLimit(limit: number, lineage: readonly RecentTransition[]): RecentTransitionWindow;

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

@@ -3,7 +3,7 @@ import { isJsonValue, isObject, sameJson, validatePatch } from "./json.js";
 export const DEFAULT_HISTORY_LIMIT = 7;
 export const MAX_HISTORY_LIMIT = 100;
 const SCOPES = new Set(["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, after) {
     const entries = [];
@@ -28,6 +28,8 @@ function validateScopedPatch(value) {
         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")
@@ -54,10 +56,20 @@ export function validateRecentTransition(value) {
     }
 }
 export function createAcceptedTransition(currentStates, nextStates, id) {
+    const owners = Object.keys(currentStates);
+    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 = [];
     for (const scope of SCOPES) {
-        const patch = replayPatch(currentStates[scope], nextStates[scope]);
-        if ((currentStates[scope].response ?? "") === (nextStates[scope].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 });

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

@@ -7,6 +7,8 @@ export interface MissingDeletion {
     path: string;
     unavailablePath: string;
 }
+/** Internal path-copying step; callers must own the detached draft and collect failures privately. */
+export declare function applyOwnedPatch(state: JsonObject, patch: JsonObject, missingDeletions?: MissingDeletion[], path?: string, unavailablePath?: string): JsonObject;
 /** Remove empty object fields without removing array slots or mutating the input. */
 export declare function pruneEmptyObjects(value: JsonObject): JsonObject;
 export declare function pruneEmptyObjects(value: JsonValue): JsonValue;

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

@@ -34,7 +34,8 @@ function applyOwnedArrayPatch(state, patch, missingDeletions, path, unavailableP
     }
     return next;
 }
-function applyOwnedPatch(state, patch, missingDeletions, path = "", unavailablePath) {
+/** Internal path-copying step; callers must own the detached draft and collect failures privately. */
+export function applyOwnedPatch(state, patch, missingDeletions, path = "", unavailablePath) {
     let next = state;
     for (const [key, value] of Object.entries(patch)) {
         const owns = Object.hasOwn(next, key);

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

@@ -1,2 +1,4 @@
-import type { ScopedStates, StateScope } from "./state.ts";
+import { type ScopeStateValues, type ScopedStates, type StateScope } from "./state.ts";
+import { type ScopeSelection } from "./selection.ts";
 export declare function retainedMemoryScopes(states: ScopedStates): Record<StateScope, boolean>;
+export declare function retainedMemoryScopes(states: ScopeStateValues, selection: ScopeSelection): Partial<Record<StateScope, boolean>>;

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

@@ -1,10 +1,10 @@
+import { assertScopeStateValues } from "./state.js";
+import { captureScopeSelection, DEFAULT_SCOPE_SELECTION } from "./selection.js";
 function hasSemanticMemory(state) {
-    return Object.keys(state.contract).length > 0 || Object.keys(state.working).length > 0;
+    return Object.keys(state.strategy ?? {}).length > 0 || Object.keys(state.tactics ?? {}).length > 0;
 }
-export function retainedMemoryScopes(states) {
-    return {
-        global: hasSemanticMemory(states.global),
-        cwd: hasSemanticMemory(states.cwd),
-        session: hasSemanticMemory(states.session),
-    };
+export function retainedMemoryScopes(states, selection = DEFAULT_SCOPE_SELECTION) {
+    const selected = captureScopeSelection(selection);
+    assertScopeStateValues(states, selected);
+    return Object.fromEntries(selected.map(scope => [scope, hasSemanticMemory(states[scope])]));
 }

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

@@ -0,0 +1,29 @@
+import { type JsonObject } from "./json.ts";
+import { type RetainedModules } from "./semantic-module.ts";
+import { type StateScope } from "./state.ts";
+import { 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>;
+}
+/** Translate a raw legacy checkpoint or replay patch before any known-field filtering. */
+export declare function translateLegacySemanticObject(value: unknown): JsonObject;
+/** Build a detached target candidate; publication still belongs to the guarded storage transaction. */
+export declare function prepareSemanticMigration(value: unknown, scope: StateScope, sourceVersion: number, historyLimit?: number, targetModules?: RetainedModules): SemanticMigrationCandidate;
+/** Decode a complete raw owner cohort before filtering; never load files, normalize authority or publish. */
+export declare function prepareSerializedScopeMigration(sources: ScopeMigrationSources, scope: StateScope, expectedCwd?: string, targetModules?: RetainedModules): SerializedSemanticMigrationCandidate;

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

@@ -0,0 +1,186 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { parseArtifactProvenanceRegistry } from "./artifact.js";
+import { MAX_HISTORY_LIMIT } from "./history.js";
+import { canonicalJson, isJsonValue, isObject, validatePatch } from "./json.js";
+import { parseStateReadPath, parseValuePath } from "./query.js";
+import { assertRetainedModules, validateRetainedModules } from "./semantic-module.js";
+import { assertNoRetiredSemanticPlanes } from "./state.js";
+import { validateScopeStream } from "./temporal.js";
+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) {
+    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) {
+    if (typeof value === "string")
+        return value.replace(MARKED_LOCATOR, (_token, path) => `$${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) {
+    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) {
+    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, scope, sourceVersion, historyLimit = MAX_HISTORY_LIMIT, targetModules) {
+    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) => {
+        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, label) {
+    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, label) {
+    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, label) {
+    let value;
+    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, scope, expectedCwd, targetModules) {
+    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/dist/lib/model-interface.d.ts

@@ -0,0 +1,17 @@
+import { type JsonValue, type MissingDeletion } from "./json.ts";
+import { type ScopeSelection } from "./selection.ts";
+import type { AtomicScopePatches, StateScope } from "./state.ts";
+/** Anchor eligible flat current references, never text/resource/effective/historical references. */
+export declare function canonicalizeModelReferences(value: unknown, scopes: ScopeSelection, external?: readonly string[]): JsonValue;
+/** Strip only validated same-owner current semantic reference prefixes; canonical data stays untouched. */
+export declare function projectModelReferences(value: unknown, scopes: ScopeSelection, external?: readonly string[]): JsonValue;
+/** Value normalization only; callers must validate their original request/owner before invoking it. */
+export declare function normalizeModelPatches(value: unknown, scopes: ScopeSelection, external?: readonly string[]): AtomicScopePatches;
+/** Compilation target syntax, not a query locator: preserve the exact opaque source key. */
+export declare function projectModelArtifactTarget(scope: StateScope, path: string, scopes: ScopeSelection): string;
+/** Known deletion-report JSON pointers only; do not parse source keys or rewrite diagnostics. */
+export declare function projectModelMissingDeletion(deletion: MissingDeletion, scopes: ScopeSelection): MissingDeletion;
+/** Sole-owner locators bind to that exact owner; multi-owner effective aliases keep their existing meaning. */
+export declare function normalizeModelReadPath(path: string, scopes: ScopeSelection, historyLimit?: number): string;
+/** Presentation locator only: history keeps an explicit projection root and does not become an array index. */
+export declare function projectModelReadPath(path: string, scopes: ScopeSelection, historyLimit?: number): string;

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

@@ -0,0 +1,158 @@
+// 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 } from "./json.js";
+import { DEFAULT_HISTORY_LIMIT } from "./history.js";
+import { parseStateReadPath, parseValuePath } from "./query.js";
+import { captureScopeSelection } from "./selection.js";
+import { MODEL_PLANE_NAMES } from "./planes.js";
+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) {
+    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) {
+    if (!isJsonValue(value))
+        throw new Error("Model interface requires finite acyclic JSON data");
+    let copy;
+    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, translate) {
+    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, external) {
+    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, scopes, external = []) {
+    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, scopes, external = []) {
+    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, selected, external) {
+    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))
+                throw new Error(`Multi-owner model patches require participating explicit owners; does not accept field ${key}`);
+        }
+}
+function planePatch(value, external) {
+    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, scopes, external = []) {
+    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));
+    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;
+}
+/** Compilation target syntax, not a query locator: preserve the exact opaque source key. */
+export function projectModelArtifactTarget(scope, path, scopes) {
+    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, scopes) {
+    const selected = captureScopeSelection(scopes);
+    const project = (path) => {
+        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, selected, historyLimit) {
+    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, scopes, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    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, scopes, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    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/dist/lib/module-registry.d.ts

@@ -0,0 +1,21 @@
+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>;
+export interface StateFlowModuleCatalog {
+    readonly modules: readonly Definition[];
+    readonly signal: AbortSignal;
+    assertCurrent(): void;
+}
+/** Registry metadata alone grants no content, source, private or publication authority. */
+export declare function registerStateFlowModule<Content extends JsonObject, Input extends JsonValue>(manager: SessionManager, definition: StateFlowModule<Content, Input>): () => void;
+/** One composition-root owner; catalogs are revoked independently of memory mode or storage. */
+export declare class StateFlowModuleHost {
+    #private;
+    bind(manager: SessionManager, checkOwner: () => void): void;
+    captureIfBound(): StateFlowModuleCatalog | undefined;
+    capture(): StateFlowModuleCatalog;
+    dispose(): void;
+}
+export {};

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

@@ -0,0 +1,108 @@
+const BRIDGE = Symbol.for("@llblab/pi-state-flow/modules/v1");
+function bridge(create = false) {
+    const globals = globalThis;
+    let value = globals[BRIDGE];
+    if (value === undefined && create)
+        globals[BRIDGE] = value = { version: 1, hosts: new WeakMap() };
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== "object")
+        throw new Error("Incompatible State Flow module registration bridge");
+    const candidate = value;
+    if (candidate.version !== 1 || !(candidate.hosts instanceof WeakMap))
+        throw new Error("Incompatible State Flow module registration bridge");
+    return candidate;
+}
+function captureDefinition(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) } : {}) });
+}
+/** Registry metadata alone grants no content, source, private or publication authority. */
+export function registerStateFlowModule(manager, definition) {
+    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);
+}
+/** One composition-root owner; catalogs are revoked independently of memory mode or storage. */
+export class StateFlowModuleHost {
+    #binding;
+    bind(manager, checkOwner) {
+        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 = { manager, checkOwner, modules: new Map(), controller: new AbortController(), register: definition => this.#register(binding, definition) };
+        this.#binding = binding;
+        hosts.set(manager, binding);
+    }
+    #check(binding) {
+        if (this.#binding !== binding || bridge()?.hosts.get(binding.manager) !== binding)
+            throw new Error("State Flow module host ownership changed");
+        binding.checkOwner();
+    }
+    #changed(binding) {
+        const previous = binding.controller;
+        binding.controller = new AbortController();
+        previous.abort(new Error("State Flow module catalog changed"));
+    }
+    #register(binding, definition) {
+        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() {
+        return this.#binding ? this.capture() : undefined;
+    }
+    capture() {
+        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() {
+        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"));
+    }
+}