@llblab/pi-kit 0.18.1 → 0.19.0

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

@@ -1,5 +1,5 @@
-import { projectRecentTransitionsWithLimit, RECENT_TRANSITION_LIMIT } from "./history.js";
-import { inspectMemoryPromotions, retainedMemoryScopes } from "./memory.js";
+import { projectRecentTransitionsWithLimit } from "./history.js";
+import { retainedMemoryScopes } from "./memory.js";
 import { overlayStates } from "./state.js";
 export const STATUS_KEY = "state-flow";
 export function compactStatus(snapshot, colorize) {
@@ -10,68 +10,40 @@ export function compactStatus(snapshot, colorize) {
 function countArtifacts(states, scope) {
     return Object.keys(states[scope].artifacts).length;
 }
-function abbreviatedCommit(commit) {
-    return commit.length > 12 ? commit.slice(0, 12) : commit;
-}
 export function detailedStatus(snapshot, diagnostics) {
-    const projectedRecent = projectRecentTransitionsWithLimit(RECENT_TRANSITION_LIMIT, diagnostics.recent);
+    const projectedRecent = projectRecentTransitionsWithLimit(diagnostics.historyLimit, diagnostics.recent);
     const available = diagnostics.temporal !== undefined && diagnostics.durableStateError === undefined;
     const materialized = !available ? undefined : overlayStates(diagnostics.scopeStates.global, diagnostics.scopeStates.cwd, diagnostics.scopeStates.session);
     const stateJson = materialized === undefined ? undefined : JSON.stringify(materialized, null, 2);
-    const freshnessError = diagnostics.artifactFreshnessError ?? (available ? undefined : "temporal global artifact registry is unavailable");
-    const stale = freshnessError === undefined
-        ? String(diagnostics.staleArtifacts.length)
-        : "unknown";
-    const publication = diagnostics.pendingPublication === undefined
-        ? "idle"
-        : `pending ${abbreviatedCommit(diagnostics.pendingPublication.commit)} — ${diagnostics.pendingPublication.error}`;
-    const staleLines = freshnessError !== undefined
-        ? [`Artifact freshness unavailable: ${freshnessError}`]
-        : diagnostics.staleArtifacts.length === 0
-            ? ["Stale artifacts: none"]
-            : [
-                "Stale artifacts:",
-                ...diagnostics.staleArtifacts.map(({ scope, path, reason }) => `- [${scope}] ${path} — ${reason}`),
-            ];
+    const invalidated = available ? String(diagnostics.staleArtifacts.length) : "unavailable";
+    const invalidationLines = diagnostics.staleArtifacts.length === 0
+        ? ["Pending artifact invalidations: none"]
+        : [
+            "Pending artifact invalidations:",
+            ...diagnostics.staleArtifacts.map(({ scope, path, reason }) => `- [${scope}] ${path} — ${reason}`),
+        ];
     const temporal = available ? diagnostics.temporal : undefined;
     const temporalLines = temporal === undefined
         ? [`Temporal materialization unavailable: ${diagnostics.durableStateError ?? "no selected branch runtime"}`,
-            "Hot history: unavailable; offsets beyond 7 require explicit cold Git inspection",
+            `Hot history: unavailable; configured maximum depth ${diagnostics.historyLimit}`,
             "Retained patch tails: unavailable"]
         : [`Temporal head: ${JSON.stringify(temporal.head.id)}; branch-local position ${temporal.head.position}`,
-            `Hot history: offsets 0..${temporal.historyDepth}; maximum depth 7`,
+            `Hot history: offsets 0..${temporal.historyDepth}; maximum depth ${diagnostics.historyLimit}`,
             `Retained patch tails: global ${temporal.tailCounts.global}; CWD ${temporal.tailCounts.cwd}; session ${temporal.tailCounts.session}`];
     const artifacts = (scope) => available ? countArtifacts(diagnostics.scopeStates, scope) : "unknown";
-    const promotions = available ? inspectMemoryPromotions(diagnostics.scopeStates.global) : [];
-    const promotionCounts = Object.fromEntries(["pending", "accepted", "failed", "unknown", "invalid"].map((status) => [status, promotions.filter((entry) => entry.status === status).length]));
     const memoryScopes = available ? retainedMemoryScopes(diagnostics.scopeStates) : undefined;
-    const oneLine = (value) => value.replace(/\s+/g, " ").slice(0, 240);
-    const promotionLines = !available || promotions.length === 0 ? [] : [
-        "Memory promotions:",
-        ...promotions.map((entry) => `- ${oneLine(entry.id)} — ${entry.status}; owner ${oneLine(entry.owner ?? "unavailable")}${entry.pointer ? `; pointer ${oneLine(entry.pointer)}` : ""}${entry.revision ? `; revision ${oneLine(entry.revision)}` : ""}${entry.error ? `; error ${oneLine(entry.error)}` : ""}`),
-    ];
     return [
         `State Flow diagnostics — config.enabled=${snapshot.config.enabled}; branch mode=${snapshot.config.enabled ? "active" : "inactive"}`,
         `Repository: ${diagnostics.repositoryRoot}`,
         `Scope keys: CWD ${diagnostics.cwdScopeKey}; session ${diagnostics.sessionScopeKey}`,
         "Session files: config.json owns behavior; runtime.json owns branch recovery; meta.json owns scope provenance",
-        `Runtime metadata: step #${snapshot.meta.step}; active revision ${snapshot.meta.durableBase ?? "none"}; bootstrap ${snapshot.meta.bootstrap === true}`,
-        `Remote publication policy: ${snapshot.meta.remotePublication?.mode ?? "legacy-transition"}`,
-        diagnostics.publicationQueueError !== undefined
-            ? `Remote queue: unavailable; error ${diagnostics.publicationQueueError}`
-            : diagnostics.publicationQueue === undefined
-                ? "Remote queue: idle"
-                : `Remote queue: ${diagnostics.publicationQueue.status}; target ${abbreviatedCommit(diagnostics.publicationQueue.target)}; confirmed ${diagnostics.publicationQueue.confirmed ? abbreviatedCommit(diagnostics.publicationQueue.confirmed) : "none"}; attempt ${diagnostics.publicationQueue.attempt}${diagnostics.publicationQueue.error ? `; error ${diagnostics.publicationQueue.error}` : ""}`,
+        `Runtime metadata: step #${snapshot.meta.step}; bootstrap ${snapshot.meta.bootstrap === true}`,
         "Memory: owner state-flow; global retention enabled; global fallback active",
         `Memory-bearing scopes: global ${memoryScopes?.global ?? "unknown"}; CWD ${memoryScopes?.cwd ?? "unknown"}; session ${memoryScopes?.session ?? "unknown"}`,
-        `Promotion status: pending ${promotionCounts.pending}; accepted ${promotionCounts.accepted}; failed ${promotionCounts.failed}; unknown ${promotionCounts.unknown}; invalid ${promotionCounts.invalid}`,
-        ...promotionLines,
         ...temporalLines,
-        `Artifacts: global ${artifacts("global")}; CWD ${artifacts("cwd")}; session ${artifacts("session")}; stale ${stale}`,
+        `Artifacts: global ${artifacts("global")}; CWD ${artifacts("cwd")}; session ${artifacts("session")}; pending invalidations ${invalidated}`,
         available ? `Recent transitions: global ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "global")).length}; CWD ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "cwd")).length}; session ${diagnostics.recent.filter(({ transitions }) => transitions.some(({ scope }) => scope === "session")).length}; active ${projectedRecent.length}` : "Recent transitions: unavailable",
-        `Publication policy: ${snapshot.meta.remotePublication?.mode ?? "legacy-unresolved"}`,
-        `Publication: ${publication}`,
-        ...staleLines,
+        ...invalidationLines,
         ...(stateJson === undefined
             ? ["Effective memory: unavailable"]
             : [`Effective memory (${Buffer.byteLength(stateJson, "utf8")} JSON bytes; global → CWD → session overlay):`, "", stateJson]),

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

@@ -1,5 +1,5 @@
 import { type DurableFileBase, type OwnedFileUpdate } from "./durable.ts";
-import { type ArtifactProvenanceRegistry } from "./artifact.ts";
+import type { ArtifactProvenanceRegistry } from "./artifact.ts";
 import { type FileRevision, type SessionRuntime } from "./snapshot.ts";
 export { isFileRevision, type FileRevision } from "./snapshot.ts";
 import type { StateScope } from "./state.ts";
@@ -7,17 +7,15 @@ import { type TemporalState } from "./temporal.ts";
 export interface TemporalFileBase {
     files: DurableFileBase[];
 }
-/** Probe once at a lifecycle boundary, never on cached state reads. Only spawn ENOENT is absence. */
-export declare function detectGitCapability(): "git" | "files";
 export declare function assertStorageDirectory(path: string): void;
 /** Explicit creation only; existing bytes and unrelated files are never adopted or rewritten here. */
 export declare function initializeFileStore(root: string): void;
 /** Wait only for a cooperating live owner; interrupted or malformed locks remain explicit recovery errors. */
 export declare function acquirePublicationLock(path: string, unavailable: (cause: unknown) => Error): number;
-/** Git writers also acquire this lock before their common-Git-directory lock. */
+/** Canonical writers and bounded backup capture share exclusion; no Git work runs under this lock. */
 export declare function withStoragePublicationLock<T>(repositoryRoot: string, action: (root: string) => T): T;
 export declare function assertTemporalFileBase(expected: TemporalFileBase, current: TemporalFileBase): void;
-/** One shared publication plan for Git and files; neither backend invents semantic changes. */
+/** Plan exact canonical updates; lifecycle-only writes exclude semantic files and provenance. */
 export declare function planTemporalPublication(cwd: string, sessionId: string, view: TemporalState, scopes: readonly StateScope[], current: TemporalFileBase, root: string, runtime?: SessionRuntime, runtimeOnly?: boolean, sessionKey?: string, provenance?: Readonly<Record<StateScope, ArtifactProvenanceRegistry>>): {
     updates: OwnedFileUpdate[];
     changedScopes: StateScope[];
@@ -38,11 +36,9 @@ export declare function loadTemporalFileRevision(cwd: string, sessionId: string,
     };
     revision: `file:${string}`;
 };
-/** Publish a validated full runtime/scoped cohort; no Git commands, success receipts, or pending pushes. */
-export declare function publishTemporalStateToFiles(cwd: string, sessionId: string, view: TemporalState, scopes: readonly StateScope[], base: TemporalFileBase, root: string, runtime: SessionRuntime, sessionKey?: string, provenance?: Readonly<Record<StateScope, ArtifactProvenanceRegistry>>): {
+/** Publish a validated canonical cohort; runtimeOnly owns only session config/runtime files. */
+export declare function publishTemporalStateToFiles(cwd: string, sessionId: string, view: TemporalState, scopes: readonly StateScope[], base: TemporalFileBase, root: string, runtime: SessionRuntime, sessionKey?: string, provenance?: Readonly<Record<StateScope, ArtifactProvenanceRegistry>>, runtimeOnly?: boolean): {
     base: TemporalFileBase;
     revision: FileRevision;
     changed: boolean;
 };
-/** In-store format conversion only; no Git history or cross-repository import. */
-export declare function migrateLegacyStorageToFiles(cwd: string, sessionId: string, root: string, sessionKey?: string): void;

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

@@ -1,27 +1,15 @@
 // Domain: exact file-cohort publication, current-only recovery, and cooperating worktree exclusion.
 // Excludes: temporal algebra, Pi lifecycle, Git objects/remotes, and backend fallback policy.
-import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import { assertOwnedFileUpdates, captureTemporalFileBases, parseScopeProvenance, parseScopeStream, restoreDurableFileBases, serializeScopeMetadata, sessionRuntimePaths, temporalScopePaths, temporalStateFileUpdates, writeOwnedFileUpdates, } from "./durable.js";
-import { parseArtifactProvenanceRegistry } from "./artifact.js";
+import { MAX_HISTORY_LIMIT } from "./history.js";
 import { hashJson, sameJson } from "./json.js";
 import { RevisionUnavailableError, isFileRevision, parseSessionRuntime, serializeSessionRuntime } from "./snapshot.js";
-import { planLegacyStorageMigration } from "./migration.js";
 export { isFileRevision } from "./snapshot.js";
 import { validateTemporalState } from "./temporal.js";
 const SCOPES = ["global", "cwd", "session"];
-/** Probe once at a lifecycle boundary, never on cached state reads. Only spawn ENOENT is absence. */
-export function detectGitCapability() {
-    const result = spawnSync("git", ["--version"], { encoding: "utf8", timeout: 15_000 });
-    if (result.error && result.error.code === "ENOENT")
-        return "files";
-    if (result.error || result.status !== 0) {
-        throw new RevisionUnavailableError(`Cannot resolve Git capability: ${result.error?.message ?? result.stderr ?? `exit ${result.status}`}`);
-    }
-    return "git";
-}
 export function assertStorageDirectory(path) {
     const root = resolve(path);
     const parent = dirname(root);
@@ -76,7 +64,7 @@ export function acquirePublicationLock(path, unavailable) {
         }
     }
 }
-/** Git writers also acquire this lock before their common-Git-directory lock. */
+/** Canonical writers and bounded backup capture share exclusion; no Git work runs under this lock. */
 export function withStoragePublicationLock(repositoryRoot, action) {
     const root = resolve(repositoryRoot);
     assertStorageDirectory(root);
@@ -98,17 +86,15 @@ export function assertTemporalFileBase(expected, current) {
     }))
         throw new Error("Temporal State Flow base or scope identity changed concurrently");
 }
-/** One shared publication plan for Git and files; neither backend invents semantic changes. */
+/** Plan exact canonical updates; lifecycle-only writes exclude semantic files and provenance. */
 export function planTemporalPublication(cwd, sessionId, view, scopes, current, root, runtime, runtimeOnly = false, sessionKey = sessionId, provenance) {
     const candidates = temporalStateFileUpdates(cwd, sessionId, view, scopes, root, sessionKey);
     const files = new Map(current.files.map((file) => [file.path, file]));
-    if (runtimeOnly && scopes.length !== 0)
-        throw new Error("Runtime-only publication cannot write semantic scopes");
+    if (runtimeOnly && (scopes.length !== 0 || provenance !== undefined))
+        throw new Error("Runtime-only publication cannot write semantic scopes or artifact provenance");
     const changedScopes = [];
     for (const scope of SCOPES) {
         const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
-        if (files.get(resolve(paths.directory, "state.json")).identity !== "missing")
-            throw new Error("Legacy State Flow storage requires explicit migration");
         const previous = parseScopeStream(files.get(paths.checkpoint).content, files.get(paths.patches).content, scope, scope === "cwd" ? cwd : undefined, files.get(paths.meta).content);
         if (runtimeOnly || (previous !== undefined && sameJson(previous, view.scopes[scope])))
             continue;
@@ -132,7 +118,7 @@ export function planTemporalPublication(cwd, sessionId, view, scopes, current, r
         }
     }
     const runtimePaths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
-    const previousRuntime = parseSessionRuntime(files.get(runtimePaths.config).content, files.get(runtimePaths.runtime).content, cwd, sessionId, files.get(runtimePaths.meta).content);
+    const previousRuntime = parseSessionRuntime(files.get(runtimePaths.config).content, files.get(runtimePaths.runtime).content, cwd, sessionId);
     if (previousRuntime !== undefined && changedScopes.length > 0 && runtime === undefined)
         throw new Error("Temporal semantic publication requires its session runtime cohort");
     const runtimeUpdates = [];
@@ -143,12 +129,6 @@ export function planTemporalPublication(cwd, sessionId, view, scopes, current, r
         if (files.get(runtimePaths.config).content !== sources.config || files.get(runtimePaths.runtime).content !== sources.runtime) {
             runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.runtime, content: sources.runtime });
         }
-        if (files.get(runtimePaths.runtime).identity === "missing" && files.get(runtimePaths.meta).content !== undefined
-            && previousRuntime !== undefined && !provenanceUpdates.some(({ path }) => path === runtimePaths.meta)) {
-            const registry = provenance?.session ?? parseArtifactProvenanceRegistry(previousRuntime.meta.artifacts, "State Flow session artifact provenance");
-            const content = serializeScopeMetadata(registry, view.scopes.session, "session", undefined, files.get(runtimePaths.meta).content);
-            runtimeUpdates.push({ path: runtimePaths.meta, content });
-        }
     }
     const changedPaths = new Set(changedScopes.flatMap((scope) => {
         const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
@@ -177,19 +157,17 @@ function decodeFileCohort(cwd, sessionId, root, base, sessionKey = sessionId) {
     const scopes = {};
     for (const scope of SCOPES) {
         const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
-        if (files.get(resolve(paths.directory, "state.json")) !== undefined)
-            throw new Error("Legacy State Flow storage requires explicit migration");
         const stream = parseScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope, scope === "cwd" ? cwd : undefined, files.get(paths.meta));
         if (!stream)
             throw new Error("Incomplete file-only temporal scope cohort");
         scopes[scope] = stream;
     }
     const paths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
-    const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), cwd, sessionId, files.get(paths.meta));
-    if (!runtime || runtime.meta.publication !== "files")
-        throw new Error("File-only recovery requires file publication provenance, not a Git self reference");
+    const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), cwd, sessionId);
+    if (!runtime)
+        throw new Error("Canonical recovery requires a complete session runtime");
     const view = { scopes, lineage: runtime.meta.lineage };
-    validateTemporalState(view);
+    validateTemporalState(view, MAX_HISTORY_LIMIT);
     const provenance = {
         global: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta),
         cwd: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta),
@@ -211,14 +189,12 @@ export function loadTemporalFileRevision(cwd, sessionId, root, revision, session
         return { base, revision, ...decodeFileCohort(cwd, sessionId, locked, base, sessionKey) };
     });
 }
-/** Publish a validated full runtime/scoped cohort; no Git commands, success receipts, or pending pushes. */
-export function publishTemporalStateToFiles(cwd, sessionId, view, scopes, base, root, runtime, sessionKey = sessionId, provenance) {
+/** Publish a validated canonical cohort; runtimeOnly owns only session config/runtime files. */
+export function publishTemporalStateToFiles(cwd, sessionId, view, scopes, base, root, runtime, sessionKey = sessionId, provenance, runtimeOnly = false) {
     return withStoragePublicationLock(root, (locked) => {
-        if (runtime.meta.publication !== "files")
-            throw new Error("File publication requires explicit file provenance");
         const current = { files: captureTemporalFileBases(cwd, sessionId, locked, sessionKey) };
         assertTemporalFileBase(base, current);
-        const { updates } = planTemporalPublication(cwd, sessionId, view, scopes, current, locked, runtime, false, sessionKey, provenance);
+        const { updates } = planTemporalPublication(cwd, sessionId, view, scopes, current, locked, runtime, runtimeOnly, sessionKey, provenance);
         const next = { files: temporalFileReceipts(current, updates) };
         decodeFileCohort(cwd, sessionId, locked, next, sessionKey);
         const revision = fileRevision(next, locked);
@@ -242,11 +218,3 @@ function publishFileUpdates(bases, updates, root) {
         throw error;
     }
 }
-/** In-store format conversion only; no Git history or cross-repository import. */
-export function migrateLegacyStorageToFiles(cwd, sessionId, root, sessionKey = sessionId) {
-    withStoragePublicationLock(root, (locked) => {
-        const plan = planLegacyStorageMigration(cwd, sessionId, locked, undefined, sessionKey);
-        if (plan.updates.length)
-            publishFileUpdates(plan.bases, plan.updates, locked);
-    });
-}

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

@@ -94,7 +94,7 @@ function renderStateFlowTelegramField(value) {
     return rendered;
 }
 export function renderStateFlowRichState(scope, step, state) {
-    const fields = ["artifacts", "contract", "working", "intents", "response", "lazy"];
+    const fields = ["intents", "contract", "working", "artifacts", "response", "lazy"];
     return {
         blocks: [
             {

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

@@ -25,15 +25,23 @@ export interface TemporalState {
     scopes: Record<StateScope, ScopeStream>;
 }
 /** Replay validation is shared by disk codecs and active-lineage materialization. */
-export declare function validateScopeStream(value: unknown, scope: StateScope): asserts value is ScopeStream;
-export declare function validateTemporalLineage(value: unknown): asserts value is TransitionBoundary[];
+export declare function validateScopeStream(value: unknown, scope: StateScope, historyLimit?: number): asserts value is ScopeStream;
+export declare function validateTemporalLineage(value: unknown, historyLimit?: number): asserts value is TransitionBoundary[];
+/** Bind one owned stream to its runtime lineage without requiring patches from unrelated scopes. */
+export declare function validateScopeLineage(stream: ScopeStream, scope: StateScope, lineage: readonly TransitionBoundary[], historyLimit?: number): void;
 /** Validate one revision-selected cohort. Its older ancestry must be bound by the durable loader. */
-export declare function validateTemporalState(view: TemporalState): void;
+export declare function validateTemporalState(view: TemporalState, historyLimit?: number): void;
 /** Adopt revision-proven inherited streams without rewriting their checkpoints or tails. */
-export declare function adoptTemporalStreams(scopes: Record<StateScope, ScopeStream>, id: string): TemporalState;
+export declare function adoptTemporalStreams(scopes: Record<StateScope, ScopeStream>, id: string, historyLimit?: number): TemporalState;
 /** New or migrated state starts at a proven current boundary, with no invented past. */
-export declare function createTemporalState(states: ScopedStates, id: string): TemporalState;
+export declare function createTemporalState(states: ScopedStates, id: string, historyLimit?: number): TemporalState;
+/** Fold retained tails to a lower configured limit without inventing history. */
+export declare function constrainTemporalState(view: TemporalState, historyLimit: number): TemporalState;
+/** Select one scope at a proven retained boundary from its owning runtime lineage. */
+export declare function selectScopeStreamAtBoundary(stream: ScopeStream, scope: StateScope, boundary: TransitionBoundary, historyLimit?: number): ScopeStream;
+/** Select one still-retained causal boundary without consulting an external history store. */
+export declare function selectTemporalStateBoundary(view: TemporalState, boundaryId: string, historyLimit?: number): TemporalState;
 /** Lazy scope/effective read at one shared transition boundary, never by local patch count. */
-export declare function readTemporalState(view: TemporalState, offset?: number, scope?: StateScope): MaterializedState;
+export declare function readTemporalState(view: TemporalState, offset?: number, scope?: StateScope, historyLimit?: number): MaterializedState;
 /** Allocate the identity outside this algebra; only materially effective patches accept it. */
-export declare function advanceTemporalState(view: TemporalState, transitions: readonly RecentScopePatch[], id: string): TemporalState;
+export declare function advanceTemporalState(view: TemporalState, transitions: readonly RecentScopePatch[], id: string, historyLimit?: number): TemporalState;

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

@@ -1,7 +1,12 @@
-import { RECENT_TRANSITION_LIMIT, validateRecentTransition } from "./history.js";
+import { DEFAULT_HISTORY_LIMIT, MAX_HISTORY_LIMIT, validateRecentTransition } from "./history.js";
 import { applyPatch, containsNull, isJsonValue, isObject, sameJson } from "./json.js";
 import { isMaterializedState, overlayStates } from "./state.js";
 const SCOPES = ["global", "cwd", "session"];
+function validateHistoryLimit(limit) {
+    if (!Number.isSafeInteger(limit) || limit < 0 || limit > MAX_HISTORY_LIMIT) {
+        throw new Error(`State Flow history limit must be an integer from 0 to ${MAX_HISTORY_LIMIT}`);
+    }
+}
 function validateBoundary(boundary) {
     if (!isObject(boundary) || Object.keys(boundary).sort().join(",") !== "id,parent,position"
         || typeof boundary.id !== "string" || boundary.id.trim().length === 0
@@ -25,7 +30,8 @@ function sameBoundary(left, right) {
     return left.id === right.id && left.position === right.position && left.parent === right.parent;
 }
 /** Replay validation is shared by disk codecs and active-lineage materialization. */
-export function validateScopeStream(value, scope) {
+export function validateScopeStream(value, scope, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    validateHistoryLimit(historyLimit);
     if (!SCOPES.includes(scope))
         throw new Error("Unknown temporal scope");
     if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "checkpoint,patches"
@@ -36,8 +42,8 @@ export function validateScopeStream(value, scope) {
     const stream = value;
     validateBoundary(stream.checkpoint.through);
     validateState(stream.checkpoint.state);
-    if (stream.patches.length > RECENT_TRANSITION_LIMIT)
-        throw new Error("Temporal scope tail exceeds seven patches");
+    if (stream.patches.length > historyLimit)
+        throw new Error(`Temporal scope tail exceeds configured history limit ${historyLimit}`);
     let previous = stream.checkpoint.through;
     let state = stream.checkpoint.state;
     const identities = new Set([previous.id]);
@@ -61,9 +67,10 @@ export function validateScopeStream(value, scope) {
         identities.add(previous.id);
     }
 }
-export function validateTemporalLineage(value) {
-    if (!isJsonValue(value) || !Array.isArray(value) || value.length === 0 || value.length > RECENT_TRANSITION_LIMIT + 1) {
-        throw new Error("Temporal lineage must contain between one and eight boundaries");
+export function validateTemporalLineage(value, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    validateHistoryLimit(historyLimit);
+    if (!isJsonValue(value) || !Array.isArray(value) || value.length === 0 || value.length > historyLimit + 1) {
+        throw new Error(`Temporal lineage must contain between one and ${historyLimit + 1} boundaries`);
     }
     const seen = new Set();
     for (let index = 0; index < value.length; index++) {
@@ -78,9 +85,29 @@ export function validateTemporalLineage(value) {
         }
     }
 }
+/** Bind one owned stream to its runtime lineage without requiring patches from unrelated scopes. */
+export function validateScopeLineage(stream, scope, lineage, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    validateTemporalLineage(lineage, historyLimit);
+    validateScopeStream(stream, scope, historyLimit);
+    const oldest = lineage[0];
+    const head = lineage.at(-1);
+    if (stream.checkpoint.through.position > oldest.position)
+        throw new Error("Scope checkpoint is newer than the guaranteed hot boundary");
+    const identities = new Map(lineage.map((boundary) => [boundary.id, boundary]));
+    for (const boundary of [stream.checkpoint.through, ...stream.patches.map((record) => record.transition)]) {
+        if (boundary.position > head.position)
+            throw new Error("Temporal scope patch is beyond the active head");
+        const identity = identities.get(boundary.id);
+        const position = lineage[boundary.position - oldest.position];
+        if ((identity && !sameBoundary(identity, boundary)) || (position && !sameBoundary(position, boundary))) {
+            throw new Error("Conflicting State Flow temporal lineage");
+        }
+    }
+}
 /** Validate one revision-selected cohort. Its older ancestry must be bound by the durable loader. */
-export function validateTemporalState(view) {
-    validateTemporalLineage(view.lineage);
+export function validateTemporalState(view, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    validateHistoryLimit(historyLimit);
+    validateTemporalLineage(view.lineage, historyLimit);
     const oldest = view.lineage[0];
     const identities = new Map();
     const positions = new Map();
@@ -100,7 +127,7 @@ export function validateTemporalState(view) {
     const head = view.lineage.at(-1);
     for (const scope of SCOPES) {
         const stream = view.scopes[scope];
-        validateScopeStream(stream, scope);
+        validateScopeStream(stream, scope, historyLimit);
         remember(stream.checkpoint.through);
         if (stream.checkpoint.through.position > oldest.position) {
             throw new Error("Scope checkpoint is newer than the guaranteed hot boundary");
@@ -123,22 +150,21 @@ export function validateTemporalState(view) {
     }
 }
 /** Adopt revision-proven inherited streams without rewriting their checkpoints or tails. */
-export function adoptTemporalStreams(scopes, id) {
+export function adoptTemporalStreams(scopes, id, historyLimit = DEFAULT_HISTORY_LIMIT) {
     const boundaries = Object.values(scopes).flatMap((stream) => [stream.checkpoint.through, ...stream.patches.map((record) => record.transition)]);
     const origin = { id, position: Math.max(...boundaries.map((boundary) => boundary.position)) + 1, parent: null };
     const view = { lineage: [origin], scopes: structuredClone(scopes) };
-    validateTemporalState(view);
-    return view;
+    return constrainTemporalState(view, historyLimit);
 }
 /** New or migrated state starts at a proven current boundary, with no invented past. */
-export function createTemporalState(states, id) {
+export function createTemporalState(states, id, historyLimit = DEFAULT_HISTORY_LIMIT) {
     const through = { id, position: 0, parent: null };
     const stream = (scope) => ({
         checkpoint: { through: structuredClone(through), state: structuredClone(states[scope]) },
         patches: [],
     });
     const view = { lineage: [through], scopes: { global: stream("global"), cwd: stream("cwd"), session: stream("session") } };
-    validateTemporalState(view);
+    validateTemporalState(view, historyLimit);
     return view;
 }
 function scopeAt(stream, boundary) {
@@ -150,14 +176,62 @@ function scopeAt(stream, boundary) {
     }
     return state;
 }
+/** Fold retained tails to a lower configured limit without inventing history. */
+export function constrainTemporalState(view, historyLimit) {
+    validateHistoryLimit(historyLimit);
+    validateTemporalState(view, MAX_HISTORY_LIMIT);
+    const next = structuredClone(view);
+    for (const scope of SCOPES) {
+        const stream = next.scopes[scope];
+        while (stream.patches.length > historyLimit) {
+            const folded = stream.patches.shift();
+            stream.checkpoint = { through: folded.transition, state: apply(stream.checkpoint.state, folded.patch) };
+        }
+    }
+    next.lineage = next.lineage.slice(-(historyLimit + 1));
+    validateTemporalState(next, historyLimit);
+    return next;
+}
+/** Select one scope at a proven retained boundary from its owning runtime lineage. */
+export function selectScopeStreamAtBoundary(stream, scope, boundary, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    validateHistoryLimit(historyLimit);
+    validateBoundary(boundary);
+    validateScopeStream(stream, scope, historyLimit);
+    if (boundary.position < stream.checkpoint.through.position) {
+        throw new Error("Selected State Flow history boundary predates the retained scope checkpoint");
+    }
+    const selected = structuredClone(stream);
+    selected.patches = selected.patches.filter(({ transition }) => transition.position <= boundary.position);
+    validateScopeStream(selected, scope, historyLimit);
+    return selected;
+}
+/** Select one still-retained causal boundary without consulting an external history store. */
+export function selectTemporalStateBoundary(view, boundaryId, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    validateHistoryLimit(historyLimit);
+    validateTemporalState(view, historyLimit);
+    if (typeof boundaryId !== "string" || boundaryId.trim().length === 0)
+        throw new Error("State Flow temporal boundary identity must be non-empty");
+    const index = view.lineage.findIndex(({ id }) => id === boundaryId);
+    if (index < 0)
+        throw new Error("Selected State Flow history boundary is outside the retained temporal window");
+    const target = view.lineage[index];
+    const selected = structuredClone(view);
+    selected.lineage = selected.lineage.slice(0, index + 1);
+    for (const scope of SCOPES) {
+        selected.scopes[scope].patches = selected.scopes[scope].patches.filter(({ transition }) => transition.position <= target.position);
+    }
+    validateTemporalState(selected, historyLimit);
+    return selected;
+}
 /** Lazy scope/effective read at one shared transition boundary, never by local patch count. */
-export function readTemporalState(view, offset = 0, scope) {
-    if (!Number.isSafeInteger(offset) || offset < 0 || offset > RECENT_TRANSITION_LIMIT) {
-        throw new Error("State Flow hot-history offset must be an integer from 0 to 7");
+export function readTemporalState(view, offset = 0, scope, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    validateHistoryLimit(historyLimit);
+    if (!Number.isSafeInteger(offset) || offset < 0 || offset > historyLimit) {
+        throw new Error(`State Flow hot-history offset must be an integer from 0 to ${historyLimit}`);
     }
     if (scope !== undefined && !SCOPES.includes(scope))
         throw new Error("Unknown temporal scope");
-    validateTemporalState(view);
+    validateTemporalState(view, historyLimit);
     const boundary = view.lineage[view.lineage.length - 1 - offset];
     if (!boundary)
         throw new Error("Requested history predates the proven temporal origin");
@@ -166,8 +240,9 @@ export function readTemporalState(view, offset = 0, scope) {
     return overlayStates(...SCOPES.map((owner) => scopeAt(view.scopes[owner], boundary)));
 }
 /** Allocate the identity outside this algebra; only materially effective patches accept it. */
-export function advanceTemporalState(view, transitions, id) {
-    validateTemporalState(view);
+export function advanceTemporalState(view, transitions, id, historyLimit = DEFAULT_HISTORY_LIMIT) {
+    validateHistoryLimit(historyLimit);
+    validateTemporalState(view, historyLimit);
     if (transitions.length === 0)
         return view;
     validateRecentTransition({ id, at: 0, transitions });
@@ -191,13 +266,18 @@ export function advanceTemporalState(view, transitions, id) {
     const next = structuredClone(view);
     for (const { scope, patch } of changes) {
         const stream = next.scopes[scope];
-        if (stream.patches.length === RECENT_TRANSITION_LIMIT) {
+        if (historyLimit === 0) {
+            stream.checkpoint = { through: structuredClone(boundary), state: apply(scopeAt(stream, head), patch) };
+            stream.patches = [];
+            continue;
+        }
+        while (stream.patches.length >= historyLimit) {
             const folded = stream.patches.shift();
             stream.checkpoint = { through: folded.transition, state: apply(stream.checkpoint.state, folded.patch) };
         }
         stream.patches.push({ transition: structuredClone(boundary), patch: structuredClone(patch) });
     }
-    next.lineage = [...next.lineage, boundary].slice(-(RECENT_TRANSITION_LIMIT + 1));
-    validateTemporalState(next);
+    next.lineage = [...next.lineage, boundary].slice(-(historyLimit + 1));
+    validateTemporalState(next, historyLimit);
     return next;
 }

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

@@ -12,8 +12,6 @@ export interface StagedScopedTransition {
     causalBasis: string;
     committed: boolean;
 }
-/** Validate that final eligibility has no pending acquisition/compilation obligation. */
-export declare function validateFinalEligibility(currentStates: ScopedStates, successfulSkillReads: Iterable<SuccessfulSkillRead>, causalBasis: string, successfulArtifactReads?: Iterable<SuccessfulArtifactRead>): void;
 /** Stage one canonical atomic scope cohort without changing the finalized response. */
 export declare function stageAtomicScopePatches(currentStates: ScopedStates, patches: AtomicScopePatches, successfulSkillReads: Iterable<SuccessfulSkillRead>, causalBasis: string, successfulArtifactReads?: Iterable<SuccessfulArtifactRead>): StagedScopedTransition;
 export declare function stageScopedTransition(currentStates: ScopedStates, transition: TerminalTransition, successfulSkillReads: Iterable<SuccessfulSkillRead>, causalBasis: string, successfulArtifactReads?: Iterable<SuccessfulArtifactRead>): StagedScopedTransition;

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

@@ -3,15 +3,15 @@ import { createAcceptedTransition } from "./history.js";
 import { applyPatch, containsNull, hashJson, isObject, validatePatch } from "./json.js";
 import { hasCompiledSkillArtifact, SKILL_ARTIFACT_COMPILER } from "./skills.js";
 const SCOPES = new Set(["global", "cwd", "session"]);
-const PATCH_KEYS = new Set(["artifacts", "contract", "working", "intents", "lazy"]);
+const PATCH_KEYS = new Set(["intents", "contract", "working", "artifacts", "lazy"]);
 function compileReadArtifacts(nextState, patch, successfulArtifactReads, provenance) {
     for (const read of successfulArtifactReads) {
         const output = patch.artifacts[read.path];
         if (!isObject(output)) {
-            throw new Error(`Every successfully read invalidated artifact must have a global compiler output at artifacts[exact candidate path]; missing: ${read.path}`);
+            throw new Error(`Successfully read invalidated artifact requires compiler output at ${read.scope ?? "global"}.artifacts[${JSON.stringify(read.path)}]`);
         }
         const compiled = compileArtifact({
-            source: { path: read.path, hash: read.hash },
+            source: { path: read.path, scope: read.scope, hash: read.hash, sourceFingerprint: read.sourceFingerprint },
             compiler: ORDINARY_ARTIFACT_COMPILER,
             output: output,
         });
@@ -77,7 +77,7 @@ function validateScopePatch(scope, patch) {
     validatePatch(patch);
     for (const key of Object.keys(patch)) {
         if (!PATCH_KEYS.has(key)) {
-            throw new Error(`Scoped State Flow patches cannot modify ${key}; only artifacts, contract, working, intents, and lazy are model-owned`);
+            throw new Error(`Unknown State Flow patch key ${JSON.stringify(key)}; expected one of: ${[...PATCH_KEYS].join(", ")}`);
         }
     }
     for (const key of ["artifacts", "contract", "working", "intents"]) {
@@ -85,8 +85,8 @@ function validateScopePatch(scope, patch) {
             throw new Error(`Scoped State Flow patch field ${key} must be a JSON object`);
         }
     }
-    if (Object.hasOwn(patch, "lazy") && patch.lazy === null) {
-        throw new Error("Scoped State Flow patch field lazy cannot be null");
+    if (Object.hasOwn(patch, "lazy") && !isObject(patch.lazy)) {
+        throw new Error("Scoped State Flow patch field lazy must be a JSON object");
     }
     if (isObject(patch.artifacts))
         validateModelArtifactPatch(patch.artifacts);
@@ -98,7 +98,7 @@ function completePatch(patch, response) {
         working: patch.working ?? {},
         intents: patch.intents ?? {},
         response,
-        ...(Object.hasOwn(patch, "lazy") ? { lazy: structuredClone(patch.lazy) } : {}),
+        lazy: structuredClone(patch.lazy ?? {}),
     };
 }
 /** Stage all scope updates against one immutable basis before any state is published. */
@@ -120,7 +120,8 @@ function stageScopedSemanticTransition(currentStates, transition, successfulSkil
         patches.set(scope, item.patch);
     }
     const cwdPatch = patches.get("cwd") ?? {};
-    const nextStates = structuredClone(currentStates);
+    const artifactReads = [...successfulArtifactReads];
+    const nextStates = { ...currentStates };
     const provenanceUpdates = { global: {}, cwd: {}, session: {} };
     for (const scope of SCOPES) {
         const authored = patches.get(scope) ?? {};
@@ -128,8 +129,8 @@ function stageScopedSemanticTransition(currentStates, transition, successfulSkil
             ? acceptedResponse
             : currentStates[scope].response;
         const patch = completePatch(authored, response);
-        const nextState = applyPatch(structuredClone(currentStates[scope]), patch);
-        compileReadArtifacts(nextState, { artifacts: scope === "global" ? authored.artifacts ?? {} : {} }, scope === "global" ? successfulArtifactReads : [], provenanceUpdates.global);
+        const nextState = applyPatch(currentStates[scope], patch);
+        compileReadArtifacts(nextState, { artifacts: authored.artifacts ?? {} }, artifactReads.filter((read) => (read.scope ?? "global") === scope), provenanceUpdates[scope]);
         compileReadSkills(nextState, { artifacts: scope === "cwd" ? cwdPatch.artifacts ?? {} : {} }, scope === "cwd" ? successfulSkillReads : [], provenanceUpdates.cwd);
         validateMaterializedTransition(nextState);
         nextStates[scope] = nextState;
@@ -146,10 +147,6 @@ function stageScopedSemanticTransition(currentStates, transition, successfulSkil
         committed: false,
     };
 }
-/** Validate that final eligibility has no pending acquisition/compilation obligation. */
-export function validateFinalEligibility(currentStates, successfulSkillReads, causalBasis, successfulArtifactReads = []) {
-    stageScopedSemanticTransition(currentStates, { transitions: [] }, successfulSkillReads, causalBasis, successfulArtifactReads);
-}
 /** Stage one canonical atomic scope cohort without changing the finalized response. */
 export function stageAtomicScopePatches(currentStates, patches, successfulSkillReads, causalBasis, successfulArtifactReads = []) {
     if (!isObject(patches))