@llblab/pi-kit 0.13.0 → 0.14.0

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

@@ -0,0 +1,79 @@
+import { randomUUID } from "node:crypto";
+import { isJsonValue, isObject, sameJson, validatePatch } from "./json.js";
+export const RECENT_TRANSITION_LIMIT = 7;
+const SCOPES = new Set(["global", "cwd", "session"]);
+const PATCH_KEYS = new Set(["artifacts", "contract", "working", "response"]);
+/** Normalize accepted replacements into recursive-merge replay, including removals. */
+function replayPatch(before, after) {
+    const entries = [];
+    for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+        if (!Object.hasOwn(after, key)) {
+            entries.push([key, null]);
+            continue;
+        }
+        if (Object.hasOwn(before, key) && sameJson(before[key], after[key]))
+            continue;
+        const previous = before[key];
+        const next = after[key];
+        entries.push([key, isObject(previous) && isObject(next) ? replayPatch(previous, next) : structuredClone(next)]);
+    }
+    return Object.fromEntries(entries);
+}
+function validateScopedPatch(value) {
+    if (!isObject(value) || Object.keys(value).sort().join(",") !== "patch,scope") {
+        throw new Error('Recent State Flow transition entries must contain exactly "scope" and "patch"');
+    }
+    if (typeof value.scope !== "string" || !SCOPES.has(value.scope)) {
+        throw new Error(`Recent State Flow transition has an unknown scope: ${String(value.scope)}`);
+    }
+    validatePatch(value.patch);
+    for (const [key, field] of Object.entries(value.patch)) {
+        if (!PATCH_KEYS.has(key) || (key === "response"
+            ? value.scope !== "session" || typeof field !== "string" : !isObject(field))) {
+            throw new Error("Recent State Flow patches may contain object-valued artifacts, contract, and working plus a session response string");
+        }
+    }
+}
+export function validateRecentTransition(value) {
+    if (!isObject(value) || Object.keys(value).sort().join(",") !== "at,id,transitions")
+        throw new Error("Recent State Flow transition has an invalid envelope");
+    if (typeof value.id !== "string" || value.id.length === 0)
+        throw new Error("Recent State Flow transition must have a non-empty id");
+    if (!Number.isSafeInteger(value.at) || value.at < 0)
+        throw new Error("Recent State Flow transition must have a safe non-negative position");
+    if (!Array.isArray(value.transitions) || value.transitions.length === 0 || !isJsonValue(value.transitions))
+        throw new Error("Recent State Flow transition must contain semantic patches");
+    const seen = new Set();
+    for (const transition of value.transitions) {
+        validateScopedPatch(transition);
+        if (seen.has(transition.scope))
+            throw new Error(`Duplicate recent State Flow transition scope: ${transition.scope}`);
+        seen.add(transition.scope);
+    }
+}
+export function createAcceptedTransition(currentStates, nextStates, id) {
+    const transitions = [];
+    for (const scope of SCOPES) {
+        const patch = replayPatch(currentStates[scope], nextStates[scope]);
+        if (Object.keys(patch).length > 0)
+            transitions.push({ scope, patch });
+    }
+    if (transitions.length === 0)
+        return undefined;
+    return { id: id ?? randomUUID(), transitions };
+}
+/** Preserve the configured per-scope budget, filtering in selected-lineage order. */
+export function projectRecentTransitionsWithLimit(limit, lineage) {
+    if (!Number.isSafeInteger(limit) || limit < 0 || limit > RECENT_TRANSITION_LIMIT) {
+        throw new Error(`Recent State Flow transition limit must be an integer from 0 to ${RECENT_TRANSITION_LIMIT}`);
+    }
+    const remaining = { global: limit, cwd: limit, session: limit };
+    const result = [];
+    for (let index = lineage.length - 1; index >= 0; index--) {
+        const record = lineage[index];
+        const transitions = record.transitions.filter(({ scope }) => remaining[scope]-- > 0);
+        if (transitions.length)
+            result.push({ ...record, transitions });
+    }
+    return structuredClone(result.reverse());
+}

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

@@ -0,0 +1,12 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export declare function applyPatch(state: JsonObject, patch: JsonObject): JsonObject;
+export declare function isObject(value: JsonValue | unknown): value is JsonObject;
+export declare function validatePatch(value: unknown): asserts value is JsonObject;
+export declare function canonicalJson(value: JsonValue | unknown): string;
+export declare function sameJson(left: JsonValue | unknown, right: JsonValue | unknown): boolean;
+export declare function hashJson(value: JsonValue | unknown): string;
+export declare function containsNull(value: unknown): boolean;
+export declare function isJsonValue(value: unknown, ancestors?: WeakSet<object>): value is JsonValue;

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

@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+export function applyPatch(state, patch) {
+    const next = structuredClone(state);
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null) {
+            delete next[key];
+            continue;
+        }
+        const current = next[key];
+        const materialized = isObject(current) && isObject(value)
+            ? applyPatch(current, value)
+            : structuredClone(value);
+        Object.defineProperty(next, key, {
+            value: materialized,
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return next;
+}
+export function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function validatePatch(value) {
+    if (!isObject(value))
+        throw new Error("State patch must be a JSON object");
+    if (!isJsonValue(value))
+        throw new Error("State patch must contain finite, acyclic JSON data");
+}
+export function canonicalJson(value) {
+    if (!isJsonValue(value))
+        throw new Error("Value must be finite, acyclic JSON data");
+    return JSON.stringify(orderValue(value));
+}
+export function sameJson(left, right) {
+    if (left === right) {
+        if (!isJsonValue(left))
+            throw new Error("Values must be finite, acyclic JSON data");
+        return true;
+    }
+    if (!isJsonValue(left) || !isJsonValue(right))
+        throw new Error("Values must be finite, acyclic JSON data");
+    return equalJsonValues(left, right);
+}
+function equalJsonValues(left, right) {
+    if (left === right)
+        return true;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return Array.isArray(left) && Array.isArray(right) && left.length === right.length
+            && left.every((value, index) => equalJsonValues(value, right[index]));
+    }
+    if (isObject(left) || isObject(right)) {
+        if (!isObject(left) || !isObject(right))
+            return false;
+        const keys = Object.keys(left);
+        return keys.length === Object.keys(right).length
+            && keys.every((key) => Object.hasOwn(right, key) && equalJsonValues(left[key], right[key]));
+    }
+    return false;
+}
+export function hashJson(value) {
+    return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+function orderValue(value) {
+    if (Array.isArray(value))
+        return value.map((item) => orderValue(item));
+    if (!isObject(value))
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, orderValue(value[key])]));
+}
+export function containsNull(value) {
+    if (value === null)
+        return true;
+    if (Array.isArray(value))
+        return value.some((item) => containsNull(item));
+    if (!isObject(value))
+        return false;
+    return Object.values(value).some((item) => containsNull(item));
+}
+export function isJsonValue(value, ancestors = new WeakSet()) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (typeof value !== "object")
+        return false;
+    if (ancestors.has(value))
+        return false;
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value))
+            return value.every((item) => isJsonValue(item, ancestors));
+        if (!isObject(value))
+            return false;
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            return false;
+        if (Reflect.ownKeys(value).some((key) => typeof key === "symbol"))
+            return false;
+        return Object.values(value).every((item) => isJsonValue(item, ancestors));
+    }
+    catch {
+        return false;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}

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

@@ -0,0 +1,25 @@
+export type StateFlowDiagnosticCategory = "invalid-patch" | "publication-conflict" | "terminal-pending" | "finalization";
+/** Minimal structural block; only ordinary text keeps its exact content. */
+export interface StateFlowDiagnosticBlock {
+    type: string;
+    text?: string;
+}
+export interface StateFlowDiagnosticRecord {
+    at: string;
+    sessionId: string;
+    cwd: string;
+    category: StateFlowDiagnosticCategory;
+    error: string;
+    content?: StateFlowDiagnosticBlock[];
+    /** Rejected tool arguments, captured for reproducible diagnosis. Never reasoning bodies. */
+    input?: unknown;
+    tool?: string;
+    toolCallId?: string;
+    resolutionAttempt?: number;
+    terminalEligible?: boolean;
+}
+/** Preserve exact text blocks and block boundaries; reasoning bodies are never duplicated. */
+export declare function projectDiagnosticContent(content: unknown): StateFlowDiagnosticBlock[];
+/** Diagnostic JSONL lives beneath the active Pi agent directory, never inside the state repository. */
+export declare function stateFlowLogPath(agentDir: string): string;
+export declare function appendStateFlowDiagnostic(path: string, record: StateFlowDiagnosticRecord): void;

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

@@ -0,0 +1,24 @@
+// Domain: opt-in diagnostic capture for rejected State Flow resolutions.
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isObject } from "./json.js";
+/** Preserve exact text blocks and block boundaries; reasoning bodies are never duplicated. */
+export function projectDiagnosticContent(content) {
+    if (!Array.isArray(content))
+        return [];
+    return content.map((block) => {
+        if (!isObject(block) || typeof block.type !== "string")
+            return { type: "unknown" };
+        if (block.type === "text" && typeof block.text === "string")
+            return { type: "text", text: block.text };
+        return { type: block.type };
+    });
+}
+/** Diagnostic JSONL lives beneath the active Pi agent directory, never inside the state repository. */
+export function stateFlowLogPath(agentDir) {
+    return join(agentDir, "tmp", "state-flow", "logs.jsonl");
+}
+export function appendStateFlowDiagnostic(path, record) {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
+}

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

@@ -0,0 +1,36 @@
+import { type ArtifactProvenance, type ArtifactSourceIdentity } from "./artifact.ts";
+import type { ArtifactSourceCandidate } from "./discovery.ts";
+export declare const DEFAULT_ARTIFACT_MAINTENANCE_MAX_READS = 1;
+export declare const DEFAULT_ARTIFACT_MAINTENANCE_MAX_SOURCE_BYTES: number;
+export declare const DEFAULT_ARTIFACT_MAINTENANCE_MINIMUM_AGE_MS: number;
+export interface ArtifactMaintenanceOptions {
+    /** Stable cycle time supplied by the caller. */
+    now?: Date | number | string;
+    /** A source must be at least this old. Missing/unparseable timestamps rank as oldest. */
+    minimumAgeMs?: number;
+    /** Strict source-read count ceiling for this cycle. */
+    maxReads?: number;
+    /** Strict source-byte ceiling; bytes conservatively upper-bound source tokenizer input. */
+    maxSourceBytes?: number;
+}
+export interface ArtifactMaintenanceRequest extends ArtifactSourceIdentity {
+    reason: "maintenance";
+    sourceBytes: number;
+}
+export interface ArtifactMaintenancePlan {
+    requiresCompilation: ArtifactMaintenanceRequest[];
+    deferred: ArtifactMaintenanceRequest[];
+    budget: {
+        maxReads: number;
+        maxSourceBytes: number;
+        usedReads: number;
+        usedSourceBytes: number;
+    };
+}
+/**
+ * Select a bounded, oldest-first maintenance cohort from otherwise fresh artifacts.
+ *
+ * This planner is opt-in and side-effect free. Correctness invalidations remain the
+ * responsibility of planArtifactInvalidation; they are never displaced by maintenance.
+ */
+export declare function planArtifactMaintenance(sources: readonly ArtifactSourceCandidate[], registry: Readonly<Record<string, unknown>>, compiler: string, options?: ArtifactMaintenanceOptions, provenance?: Readonly<Record<string, ArtifactProvenance>>): ArtifactMaintenancePlan;

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

@@ -0,0 +1,98 @@
+import { classifyArtifactFreshness, } from "./artifact.js";
+import { isObject } from "./json.js";
+export const DEFAULT_ARTIFACT_MAINTENANCE_MAX_READS = 1;
+export const DEFAULT_ARTIFACT_MAINTENANCE_MAX_SOURCE_BYTES = 16 * 1024;
+export const DEFAULT_ARTIFACT_MAINTENANCE_MINIMUM_AGE_MS = 30 * 24 * 60 * 60 * 1_000;
+function nonNegativeSafeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error(`${name} must be a non-negative safe integer`);
+    return value;
+}
+function cycleTime(value) {
+    const timestamp = value === undefined
+        ? Date.now()
+        : value instanceof Date
+            ? value.getTime()
+            : typeof value === "number"
+                ? value
+                : Date.parse(value);
+    if (!Number.isFinite(timestamp))
+        throw new Error("Artifact maintenance cycle time must be valid");
+    return timestamp;
+}
+function compiledTime(entry, legacy) {
+    const timestamp = entry?.malformed === true ? undefined
+        : entry !== undefined && Object.hasOwn(entry, "compiledAt") ? entry.compiledAt
+            : legacy;
+    if (typeof timestamp !== "string")
+        return Number.NEGATIVE_INFINITY;
+    const parsed = Date.parse(timestamp);
+    return Number.isFinite(parsed) ? parsed : Number.NEGATIVE_INFINITY;
+}
+function request(source) {
+    return {
+        path: source.path,
+        hash: source.hash,
+        reason: "maintenance",
+        sourceBytes: source.bytes,
+    };
+}
+/**
+ * Select a bounded, oldest-first maintenance cohort from otherwise fresh artifacts.
+ *
+ * This planner is opt-in and side-effect free. Correctness invalidations remain the
+ * responsibility of planArtifactInvalidation; they are never displaced by maintenance.
+ */
+export function planArtifactMaintenance(sources, registry, compiler, options = {}, provenance = {}) {
+    if (!isObject(registry))
+        throw new Error("Artifacts must be a path-keyed JSON object");
+    const now = cycleTime(options.now);
+    const minimumAgeMs = nonNegativeSafeInteger(options.minimumAgeMs ?? DEFAULT_ARTIFACT_MAINTENANCE_MINIMUM_AGE_MS, "Artifact maintenance minimum age");
+    const maxReads = nonNegativeSafeInteger(options.maxReads ?? DEFAULT_ARTIFACT_MAINTENANCE_MAX_READS, "Artifact maintenance read budget");
+    const maxSourceBytes = nonNegativeSafeInteger(options.maxSourceBytes ?? DEFAULT_ARTIFACT_MAINTENANCE_MAX_SOURCE_BYTES, "Artifact maintenance source-byte budget");
+    const seen = new Set();
+    const eligible = [];
+    for (const source of sources) {
+        if (seen.has(source.path))
+            throw new Error(`Duplicate artifact source path: ${source.path}`);
+        seen.add(source.path);
+        nonNegativeSafeInteger(source.bytes, `Artifact source bytes at ${source.path}`);
+        const metadata = Object.hasOwn(registry, source.path) ? registry[source.path] : undefined;
+        const entry = Object.hasOwn(provenance, source.path) ? provenance[source.path] : undefined;
+        const freshness = classifyArtifactFreshness(source, metadata, compiler, false, entry);
+        if (freshness.kind !== "fresh")
+            continue;
+        const compiledAt = compiledTime(entry, isObject(metadata) ? metadata.compiled_at : undefined);
+        if (compiledAt !== Number.NEGATIVE_INFINITY && now - compiledAt < minimumAgeMs)
+            continue;
+        eligible.push({ source, compiledAt });
+    }
+    eligible.sort((left, right) => {
+        if (left.compiledAt !== right.compiledAt)
+            return left.compiledAt - right.compiledAt;
+        return left.source.path < right.source.path ? -1 : left.source.path > right.source.path ? 1 : 0;
+    });
+    const requiresCompilation = [];
+    const deferred = [];
+    let usedSourceBytes = 0;
+    for (const candidate of eligible) {
+        const next = request(candidate.source);
+        if (requiresCompilation.length >= maxReads
+            || candidate.source.bytes > maxSourceBytes - usedSourceBytes) {
+            deferred.push(next);
+            continue;
+        }
+        requiresCompilation.push(next);
+        usedSourceBytes += candidate.source.bytes;
+    }
+    return {
+        requiresCompilation,
+        deferred,
+        budget: {
+            maxReads,
+            maxSourceBytes,
+            usedReads: requiresCompilation.length,
+            usedSourceBytes,
+        },
+    };
+}

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

@@ -0,0 +1,15 @@
+import type { MaterializedState, ScopedStates, StateScope } from "./state.ts";
+export declare const MEMORY_PROMOTIONS_KEY = "memory_promotions";
+export declare const MEMORY_PROMOTION_STATUSES: readonly ["pending", "accepted", "failed", "unknown"];
+export type MemoryPromotionStatus = typeof MEMORY_PROMOTION_STATUSES[number];
+export interface MemoryPromotionDiagnostic {
+    id: string;
+    status: MemoryPromotionStatus | "invalid";
+    owner?: string;
+    pointer?: string;
+    revision?: string;
+    error?: string;
+}
+/** Inspect the generic State Flow promotion convention without importing an external owner's schema. */
+export declare function inspectMemoryPromotions(globalState: MaterializedState): MemoryPromotionDiagnostic[];
+export declare function retainedMemoryScopes(states: ScopedStates): Record<StateScope, boolean>;

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

@@ -0,0 +1,42 @@
+import { isObject } from "./json.js";
+export const MEMORY_PROMOTIONS_KEY = "memory_promotions";
+export const MEMORY_PROMOTION_STATUSES = ["pending", "accepted", "failed", "unknown"];
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+/** Inspect the generic State Flow promotion convention without importing an external owner's schema. */
+export function inspectMemoryPromotions(globalState) {
+    const records = globalState.working[MEMORY_PROMOTIONS_KEY];
+    if (records === undefined)
+        return [];
+    if (!isObject(records))
+        return [{ id: MEMORY_PROMOTIONS_KEY, status: "invalid", error: "promotion registry is not an object" }];
+    return Object.entries(records).sort(([left], [right]) => left.localeCompare(right)).map(([id, value]) => {
+        if (!isObject(value))
+            return { id, status: "invalid", error: "promotion record is not an object" };
+        const owner = nonEmpty(value.owner);
+        const pointer = nonEmpty(value.pointer);
+        const revision = nonEmpty(value.revision);
+        const error = nonEmpty(value.error);
+        const status = typeof value.status === "string" && MEMORY_PROMOTION_STATUSES.includes(value.status)
+            ? value.status
+            : undefined;
+        if (!status || !owner)
+            return { id, status: "invalid", ...(owner ? { owner } : {}), ...(pointer ? { pointer } : {}), ...(revision ? { revision } : {}), error: error ?? "promotion status/owner is invalid" };
+        if (status === "accepted" && (!pointer || !revision))
+            return { id, status: "invalid", owner, ...(pointer ? { pointer } : {}), ...(revision ? { revision } : {}), error: "accepted promotion requires pointer and revision" };
+        return { id, status, owner, ...(pointer ? { pointer } : {}), ...(revision ? { revision } : {}), ...(error ? { error } : {}) };
+    });
+}
+function hasSemanticMemory(state, ignorePromotions) {
+    if (Object.keys(state.contract).length > 0)
+        return true;
+    return Object.keys(state.working).some((key) => !ignorePromotions || key !== MEMORY_PROMOTIONS_KEY);
+}
+export function retainedMemoryScopes(states) {
+    return {
+        global: hasSemanticMemory(states.global, true),
+        cwd: hasSemanticMemory(states.cwd, false),
+        session: hasSemanticMemory(states.session, false),
+    };
+}

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

@@ -0,0 +1,13 @@
+import { type DurableFileBase, type OwnedFileUpdate } from "./durable.ts";
+import type { StateScope } from "./state.ts";
+export interface LegacyStorageMigration {
+    bases: DurableFileBase[];
+    updates: OwnedFileUpdate[];
+    scopes: StateScope[];
+}
+/** Read-only activation eligibility, before global migration or any repository publication. */
+export declare function hasCwdMaterialization(cwd: string, repositoryRoot: string): boolean;
+/** Detect predecessor snapshots or temporal envelopes without mutating the store. */
+export declare function hasLegacyStateSources(cwd: string, sessionId: string, repositoryRoot: string, sessionKey?: string): boolean;
+/** Plan from current scope snapshots only; old explanatory journals are never replay input. */
+export declare function planLegacyStorageMigration(cwd: string, sessionId: string, repositoryRoot: string, _origin?: string, sessionKey?: string): LegacyStorageMigration;

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

@@ -0,0 +1,133 @@
+// Domain: predecessor temporal-envelope migration planning; Git/files backends own publication and rollback.
+import { lstatSync, readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { captureOwnedFileBases, cwdScopePaths, parseScopeStream, serializeScopeMetadata, serializeScopeStream, sessionScopeKey, sessionScopePaths, } from "./durable.js";
+import { canonicalJson } from "./json.js";
+/** Discover every owner-proven CWD and session cohort beneath the configured store. */
+function migrationDirectories(cwd, sessionId, root, sessionKey) {
+    const selectedCwd = cwdScopePaths(cwd, root).directory;
+    const selectedSession = sessionScopePaths(cwd, sessionId, root, sessionKey).directory;
+    const directories = [{ directory: root, scope: "global" }];
+    const cwdOwners = new Map([[selectedCwd, resolve(cwd)]]);
+    if (lstatSync(root, { throwIfNoEntry: false }) !== undefined) {
+        for (const entry of readdirSync(root, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const directory = join(root, entry.name);
+            let checkpoint;
+            let meta;
+            try {
+                checkpoint = JSON.parse(readFileSync(join(directory, "checkpoint.json"), "utf8"));
+            }
+            catch {
+                continue;
+            }
+            try {
+                meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8"));
+            }
+            catch { /* predecessor metadata may be absent */ }
+            const owner = checkpoint && typeof checkpoint === "object" && !Array.isArray(checkpoint) && checkpoint.owner
+                ? checkpoint.owner
+                : meta && typeof meta === "object" && !Array.isArray(meta) ? meta.owner : undefined;
+            if (owner && typeof owner.cwd === "string" && resolve(owner.cwd) === owner.cwd)
+                cwdOwners.set(directory, owner.cwd);
+        }
+    }
+    for (const [cwdDirectory, cwdOwner] of cwdOwners) {
+        directories.push({ directory: cwdDirectory, scope: "cwd", cwdIdentity: cwdOwner });
+        if (lstatSync(cwdDirectory, { throwIfNoEntry: false }) === undefined)
+            continue;
+        for (const entry of readdirSync(cwdDirectory, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            try {
+                sessionScopeKey(entry.name);
+            }
+            catch {
+                continue;
+            }
+            const directory = join(cwdDirectory, entry.name);
+            let meta;
+            try {
+                meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8"));
+            }
+            catch {
+                continue;
+            }
+            const identity = meta && typeof meta === "object" && !Array.isArray(meta) ? meta.identity : undefined;
+            if (!identity || typeof identity !== "object" || Array.isArray(identity))
+                continue;
+            const owner = identity;
+            if (owner.cwd === cwdOwner && typeof owner.sessionId === "string" && owner.sessionId.length > 0)
+                directories.push({ directory, scope: "session" });
+        }
+    }
+    if (!directories.some(({ directory }) => directory === selectedSession))
+        directories.push({ directory: selectedSession, scope: "session" });
+    return directories;
+}
+/** Read-only activation eligibility, before global migration or any repository publication. */
+export function hasCwdMaterialization(cwd, repositoryRoot) {
+    const root = resolve(repositoryRoot);
+    const directory = cwdScopePaths(cwd, root).directory;
+    const [checkpoint, patches, meta] = captureOwnedFileBases([
+        join(directory, "checkpoint.json"), join(directory, "patches.jsonl"), join(directory, "meta.json"),
+    ], root);
+    if (checkpoint.content !== undefined)
+        return parseScopeStream(checkpoint.content, patches.content, "cwd", cwd, meta.content) !== undefined;
+    if (patches.content !== undefined)
+        throw new Error(`State Flow tail has no provable checkpoint: ${directory}`);
+    return false;
+}
+/** Detect predecessor snapshots or temporal envelopes without mutating the store. */
+export function hasLegacyStateSources(cwd, sessionId, repositoryRoot, sessionKey = sessionId) {
+    const root = resolve(repositoryRoot);
+    return migrationDirectories(cwd, sessionId, root, sessionKey).some(({ directory }) => {
+        if (lstatSync(join(directory, "checkpoint.json"), { throwIfNoEntry: false }) === undefined)
+            return false;
+        try {
+            const meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8"));
+            return meta === null || typeof meta !== "object" || !("temporal" in meta);
+        }
+        catch {
+            return true;
+        }
+    });
+}
+/** Plan from current scope snapshots only; old explanatory journals are never replay input. */
+export function planLegacyStorageMigration(cwd, sessionId, repositoryRoot, _origin, sessionKey = sessionId) {
+    const root = resolve(repositoryRoot);
+    const directories = migrationDirectories(cwd, sessionId, root, sessionKey);
+    const paths = directories.flatMap(({ directory }) => [
+        join(directory, "checkpoint.json"), join(directory, "patches.jsonl"), join(directory, "meta.json"),
+    ]);
+    const bases = captureOwnedFileBases(paths, root);
+    const byPath = new Map(bases.map((base) => [base.path, base]));
+    const updates = [];
+    const scopes = [];
+    for (const { scope, directory, cwdIdentity } of directories) {
+        const checkpoint = byPath.get(join(directory, "checkpoint.json"));
+        const patches = byPath.get(join(directory, "patches.jsonl"));
+        const meta = byPath.get(join(directory, "meta.json"));
+        if (checkpoint.content !== undefined) {
+            const stream = parseScopeStream(checkpoint.content, patches.content, scope, cwdIdentity, meta.content);
+            const source = serializeScopeStream(stream, scope, cwdIdentity);
+            let metadata = serializeScopeMetadata(undefined, stream, scope, cwdIdentity, meta.content);
+            if (scope === "session") {
+                const runtime = JSON.parse(metadata);
+                runtime.revision = "self";
+                runtime.temporalRevision = "self";
+                metadata = `${canonicalJson(runtime)}\n`;
+            }
+            if (checkpoint.content !== source.checkpoint || patches.content !== source.patches || meta.content !== metadata) {
+                if (!scopes.includes(scope))
+                    scopes.push(scope);
+                updates.push({ path: checkpoint.path, content: source.checkpoint }, { path: patches.path, content: source.patches }, { path: meta.path, content: metadata });
+            }
+            continue;
+        }
+        if (patches.content !== undefined)
+            throw new Error(`State Flow tail has no provable checkpoint: ${directory}`);
+    }
+    return { bases, updates, scopes };
+}

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

@@ -0,0 +1,7 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+export type { StateDocument } from "./state.ts";
+/** The compact model-facing contract. Semantic writes never travel through terminal prose. */
+export declare function stateFlowProtocol(bootstrap: boolean): string;
+export declare function assistantToolCallCount(content: unknown): number;
+/** The post-handler assistant message is authoritative; State Flow does not parse service comments. */
+export declare function finalizedAssistantResponse(message: AgentMessage): string;