@llblab/pi-kit 0.13.0 → 0.14.0

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

@@ -0,0 +1,21 @@
+export declare const SNAPSHOT_ENTRY_TYPE = "state-flow-snapshot";
+interface BranchEntry {
+    type?: unknown;
+    customType?: unknown;
+    data?: unknown;
+    message?: {
+        role?: unknown;
+    };
+}
+export interface SnapshotDiscovery {
+    candidates: unknown[];
+    errors: string[];
+}
+/** Enumerate active-branch snapshots newest-first while containing hostile entries. */
+export declare function discoverSnapshotData(branch: readonly BranchEntry[]): SnapshotDiscovery;
+export declare function snapshotDataNewestFirst(branch: readonly BranchEntry[]): unknown[];
+export declare function latestSnapshotData(branch: readonly BranchEntry[]): unknown;
+export declare function hasPriorConversation(branch: readonly BranchEntry[]): boolean;
+/** Auto-start eligibility is session identity/lifecycle, not the presence of CWD materialization. */
+export declare function isNewSession(reason: unknown, branch: readonly BranchEntry[]): boolean;
+export {};

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

@@ -0,0 +1,44 @@
+export const SNAPSHOT_ENTRY_TYPE = "state-flow-snapshot";
+/** Enumerate active-branch snapshots newest-first while containing hostile entries. */
+export function discoverSnapshotData(branch) {
+    const candidates = [];
+    const errors = [];
+    for (let index = branch.length - 1; index >= 0; index--) {
+        try {
+            const entry = branch[index];
+            if (entry?.type === "custom" && entry.customType === SNAPSHOT_ENTRY_TYPE)
+                candidates.push(entry.data);
+        }
+        catch (error) {
+            errors.push(error instanceof Error ? error.message : String(error));
+        }
+    }
+    return { candidates, errors };
+}
+export function snapshotDataNewestFirst(branch) {
+    return discoverSnapshotData(branch).candidates;
+}
+export function latestSnapshotData(branch) {
+    return snapshotDataNewestFirst(branch)[0];
+}
+export function hasPriorConversation(branch) {
+    for (const entry of branch) {
+        try {
+            if (entry.type !== "message")
+                continue;
+            const role = entry.message?.role;
+            if (role === "user" || role === "assistant" || role === "toolResult")
+                return true;
+        }
+        catch {
+            // A hostile unrelated entry must not prevent explicit episode startup.
+        }
+    }
+    return false;
+}
+/** Auto-start eligibility is session identity/lifecycle, not the presence of CWD materialization. */
+export function isNewSession(reason, branch) {
+    if (reason === "new")
+        return true;
+    return reason === "startup" && !hasPriorConversation(branch);
+}

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

@@ -0,0 +1,25 @@
+import { type ArtifactProvenance, type ArtifactRegistry } from "./artifact.ts";
+import type { MaterializedState } from "./state.ts";
+export declare const SKILL_ARTIFACT_COMPILER = "skill-artifact-v1";
+export declare function hasCompiledSkillArtifact(artifacts: ArtifactRegistry, provenance: ArtifactProvenance | undefined, source: string, expectedHash?: string): boolean;
+export type SkillSourceHasher = (source: string) => string;
+export declare function hashSkillSource(source: string): string;
+/** Move the retired contract store into source-addressed Skill artifacts. */
+export declare function migrateLegacySkillCompilations(state: MaterializedState, hasher?: SkillSourceHasher): MaterializedState;
+export declare function skillPathFromRead(toolName: unknown, args: unknown): string | undefined;
+export interface SuccessfulSkillRead {
+    path: string;
+    hash?: string;
+    error?: string;
+}
+/** Correlates Pi's mutable tool lifecycle and captures trusted source identity. */
+export declare class SkillReadTracker {
+    #private;
+    readonly successful: Map<string, SuccessfulSkillRead>;
+    readonly hashSource: SkillSourceHasher;
+    constructor(hashSource?: SkillSourceHasher);
+    clear(): void;
+    recordStart(toolCallId: string, toolName: string, args: unknown): void;
+    recordCall(toolCallId: string, toolName: string, input: unknown): void;
+    recordEnd(toolCallId: string, toolName: string, isError: boolean): void;
+}

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

@@ -0,0 +1,131 @@
+import { readFileSync } from "node:fs";
+import { hashArtifactSource, isArtifactHash, } from "./artifact.js";
+import { canonicalJson, isObject } from "./json.js";
+export const SKILL_ARTIFACT_COMPILER = "skill-artifact-v1";
+function hasContent(value) {
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (isObject(value))
+        return Object.keys(value).length > 0;
+    return value !== undefined && value !== null;
+}
+export function hasCompiledSkillArtifact(artifacts, provenance, source, expectedHash) {
+    const metadata = artifacts[source];
+    if (!isObject(metadata)
+        || metadata.kind !== "skill"
+        || !isObject(metadata.compilation)
+        || !hasContent(metadata.compilation)
+        || provenance?.malformed === true)
+        return false;
+    const compilerRevision = provenance !== undefined && Object.hasOwn(provenance, "compilerRevision")
+        ? provenance.compilerRevision
+        : metadata.compiler;
+    const sourceHash = provenance !== undefined && Object.hasOwn(provenance, "sourceHash")
+        ? provenance.sourceHash
+        : metadata.hash;
+    return compilerRevision === SKILL_ARTIFACT_COMPILER
+        && (expectedHash === undefined || sourceHash === expectedHash);
+}
+export function hashSkillSource(source) {
+    return hashArtifactSource(readFileSync(source));
+}
+function legacyCompilation(value) {
+    if (!hasContent(value))
+        return undefined;
+    return isObject(value) ? structuredClone(value) : { value: structuredClone(value) };
+}
+/** Move the retired contract store into source-addressed Skill artifacts. */
+export function migrateLegacySkillCompilations(state, hasher = hashSkillSource) {
+    if (!isObject(state.contract.compiled_skills))
+        return structuredClone(state);
+    const legacy = state.contract.compiled_skills;
+    const next = structuredClone(state);
+    delete next.contract.compiled_skills;
+    for (const [source, value] of Object.entries(legacy)) {
+        const compilation = legacyCompilation(value);
+        if (!compilation)
+            continue;
+        let hash;
+        let verified = true;
+        try {
+            hash = hasher(source);
+            if (!isArtifactHash(hash))
+                throw new Error("invalid source hash");
+        }
+        catch {
+            // Preserve useful legacy behavior while ensuring a later observable source
+            // identity normally invalidates this explicitly unverified fallback.
+            hash = hashArtifactSource(canonicalJson({ source, compilation }));
+            verified = false;
+        }
+        const metadata = {
+            description: `Compiled operational guidance for the Skill at ${source}`,
+            hash,
+            compiler: SKILL_ARTIFACT_COMPILER,
+            kind: "skill",
+            compilation,
+            ...(verified ? {} : { source_hash_verified: false }),
+        };
+        Object.defineProperty(next.artifacts, source, {
+            value: metadata,
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return next;
+}
+export function skillPathFromRead(toolName, args) {
+    if (toolName !== "read" || !isObject(args) || typeof args.path !== "string")
+        return undefined;
+    return /(^|[\\/])SKILL\.md$/.test(args.path) ? args.path : undefined;
+}
+/** Correlates Pi's mutable tool lifecycle and captures trusted source identity. */
+export class SkillReadTracker {
+    successful = new Map();
+    #pending = new Map();
+    hashSource;
+    constructor(hashSource = hashSkillSource) {
+        this.hashSource = hashSource;
+    }
+    clear() {
+        this.successful.clear();
+        this.#pending.clear();
+    }
+    recordStart(toolCallId, toolName, args) {
+        this.#record(toolCallId, toolName, args);
+    }
+    recordCall(toolCallId, toolName, input) {
+        this.#record(toolCallId, toolName, input);
+    }
+    recordEnd(toolCallId, toolName, isError) {
+        const pending = this.#pending.get(toolCallId);
+        this.#pending.delete(toolCallId);
+        if (isError || !pending || toolName !== pending.toolName)
+            return;
+        const source = skillPathFromRead(pending.toolName, pending.args);
+        if (!source)
+            return;
+        try {
+            const hash = this.hashSource(source);
+            if (!isArtifactHash(hash))
+                throw new Error("hasher returned a non-canonical SHA-256 identity");
+            this.successful.set(source, { path: source, hash });
+        }
+        catch (error) {
+            this.successful.set(source, {
+                path: source,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    #record(toolCallId, toolName, args) {
+        if (toolName !== "read") {
+            this.#pending.delete(toolCallId);
+            return;
+        }
+        this.#pending.set(toolCallId, { toolName, args });
+    }
+}

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

@@ -0,0 +1,88 @@
+import { type ArtifactProvenanceRegistry } from "./artifact.ts";
+import { type RemotePublicationPolicyDocument } from "./publication.ts";
+import { type JsonObject } from "./json.ts";
+import { type ScopeStream, type TransitionBoundary } from "./temporal.ts";
+/** Missing operational capability is not evidence that a checkpoint target is invalid. */
+export declare class RevisionUnavailableError extends Error {
+}
+export interface SnapshotConfig {
+    enabled: boolean;
+}
+export interface PendingPublicationState {
+    commit: string;
+    error: string;
+}
+interface LegacyValidationFeedback {
+    attempt: number;
+    error: string;
+    instruction: string;
+}
+export interface SnapshotMeta {
+    durableBase?: string;
+    pendingPublication?: PendingPublicationState;
+    step: number;
+    specification?: string;
+    /** Read-only compatibility/recovery diagnostic; 0.7 never schedules terminal-envelope retries. */
+    validation?: LegacyValidationFeedback;
+    bootstrap?: boolean;
+    remotePublication?: RemotePublicationPolicyDocument;
+}
+/** In-memory runtime config/provenance; durable config/meta and scope files own restoration. */
+export interface StateFlowSnapshot {
+    config: SnapshotConfig;
+    meta: SnapshotMeta;
+}
+export type Snapshot = StateFlowSnapshot;
+export interface SessionRuntime {
+    config: SnapshotConfig;
+    meta: Omit<SnapshotMeta, "durableBase" | "pendingPublication"> & {
+        version: 1;
+        identity: {
+            cwd: string;
+            sessionId: string;
+        };
+        lineage: TransitionBoundary[];
+        /** Runtime-owned artifact freshness evidence; never projected as semantic state. */
+        artifacts?: ArtifactProvenanceRegistry;
+        /** Resolved against the commit that last wrote this runtime record, not arbitrary HEAD. */
+        revision: "self";
+        temporalRevision?: "self" | string;
+        /** Durable intent survives a crash before the push result can be observed. */
+        publication: "unconfirmed" | "files";
+        temporal?: {
+            checkpoint: TransitionBoundary;
+            patches: TransitionBoundary[];
+        };
+        [key: string]: unknown;
+    };
+}
+export declare function validateSessionRuntime(value: unknown, cwd: string, sessionId: string): asserts value is SessionRuntime;
+export declare function createSessionRuntime(snapshot: Snapshot, cwd: string, sessionId: string, lineage: readonly TransitionBoundary[], publication?: SessionRuntime["meta"]["publication"], artifacts?: ArtifactProvenanceRegistry): SessionRuntime;
+export declare function serializeSessionRuntime(runtime: SessionRuntime, cwd: string, sessionId: string, stream?: ScopeStream, existingSource?: string): {
+    config: string;
+    meta: string;
+};
+export declare function parseSessionRuntime(config: string | undefined, meta: string | undefined, cwd: string, sessionId: string): SessionRuntime | undefined;
+export declare function resolveSessionRuntime(runtime: SessionRuntime, revision: string): {
+    snapshot: Snapshot;
+    lineage: TransitionBoundary[];
+    publicationTarget: string;
+    artifacts: ArtifactProvenanceRegistry;
+};
+export declare function resolveFileSessionRuntime(runtime: SessionRuntime, revision: string): Snapshot;
+export declare function emptySnapshot(enabled?: boolean): Snapshot;
+export type PiCheckpoint = {
+    revision: string;
+} | {
+    disabled: true;
+};
+export type FileRevision = `file:${string}`;
+export declare function isFileRevision(value: unknown): value is FileRevision;
+export declare function isDurableRevision(value: unknown): value is string;
+export declare function isExactRevision(value: unknown): value is string;
+export declare function persistableSnapshot(snapshot: Snapshot): PiCheckpoint;
+/** Pi checkpoints admit only strict revision pointers or the disabled marker. */
+export declare function parsePiCheckpoint(value: unknown): PiCheckpoint;
+export declare function migrationFailure(data: JsonObject, error: string): Snapshot;
+export declare function migrateSnapshot(value: unknown): Snapshot;
+export {};

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

@@ -0,0 +1,255 @@
+import { resolve } from "node:path";
+import { parseArtifactProvenanceRegistry } from "./artifact.js";
+import { parseRemotePublicationPolicyDocument, serializeRemotePublicationPolicyDocument } from "./publication.js";
+import { canonicalJson, isJsonValue, isObject } from "./json.js";
+import { validateTemporalLineage } from "./temporal.js";
+const MAX_RESTORED_STEP = Number.MAX_SAFE_INTEGER - 1;
+const MAX_LEGACY_VALIDATION_ATTEMPT = 7;
+/** Missing operational capability is not evidence that a checkpoint target is invalid. */
+export class RevisionUnavailableError extends Error {
+}
+export function validateSessionRuntime(value, cwd, sessionId) {
+    if (!isJsonValue(value) || !isObject(value) || Object.keys(value).sort().join(",") !== "config,meta"
+        || !isObject(value.config) || !isObject(value.meta))
+        throw new Error("Invalid State Flow session runtime envelope");
+    const { version, identity, lineage, revision, temporalRevision, publication, artifacts, temporal: _temporalScope, ...fields } = value.meta;
+    if (artifacts !== undefined)
+        parseArtifactProvenanceRegistry(artifacts, "State Flow session artifact provenance");
+    if (temporalRevision !== undefined && temporalRevision !== "self"
+        && !isExactRevision(temporalRevision))
+        throw new Error("Invalid temporal revision reference");
+    if (version !== 1 || revision !== "self" || (publication !== "unconfirmed" && publication !== "files"))
+        throw new Error("Unsupported State Flow runtime provenance format");
+    if (publication === "files" && temporalRevision !== undefined && temporalRevision !== "self")
+        throw new Error("File runtime cannot select a historical temporal revision");
+    if (!isObject(identity) || Object.keys(identity).sort().join(",") !== "cwd,sessionId"
+        || identity.cwd !== resolve(cwd) || identity.sessionId !== sessionId || sessionId.trim().length === 0 || sessionId !== sessionId.trim()) {
+        throw new Error("State Flow runtime scope identity mismatch");
+    }
+    validateTemporalLineage(lineage);
+    const known = new Set(["step", "specification", "validation", "bootstrap", "remotePublication"]);
+    if (Object.keys(fields).some((key) => ["state", "contract", "working", "response"].includes(key))) {
+        throw new Error("Semantic state does not belong in State Flow runtime metadata");
+    }
+    const runtimeFields = Object.fromEntries(Object.entries(fields).filter(([key]) => known.has(key)));
+    const { transitionWindow: _retiredWindow, ...supportedConfig } = value.config;
+    const normalized = migrateSnapshot({ config: supportedConfig, meta: runtimeFields });
+    if (runtimeFields.bootstrap === false)
+        normalized.meta.bootstrap = false;
+    if (runtimeFields.step === Number.MAX_SAFE_INTEGER)
+        normalized.meta.step = Number.MAX_SAFE_INTEGER;
+    if (canonicalJson({ config: normalized.config, meta: normalized.meta }) !== canonicalJson({ config: supportedConfig, meta: runtimeFields })) {
+        throw new Error("Invalid State Flow runtime configuration or counters");
+    }
+}
+export function createSessionRuntime(snapshot, cwd, sessionId, lineage, publication = "unconfirmed", artifacts = {}) {
+    const { durableBase: _base, pendingPublication: _publication, ...fields } = snapshot.meta;
+    const runtime = {
+        config: structuredClone(snapshot.config),
+        meta: {
+            ...Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined)),
+            version: 1,
+            identity: { cwd: resolve(cwd), sessionId },
+            lineage: structuredClone([...lineage]),
+            ...(Object.keys(artifacts).length === 0 ? {} : { artifacts: structuredClone(artifacts) }),
+            revision: "self",
+            publication,
+        },
+    };
+    validateSessionRuntime(runtime, cwd, sessionId);
+    return runtime;
+}
+export function serializeSessionRuntime(runtime, cwd, sessionId, stream, existingSource) {
+    validateSessionRuntime(runtime, cwd, sessionId);
+    let existing = {};
+    if (existingSource !== undefined) {
+        try {
+            existing = JSON.parse(existingSource);
+        }
+        catch {
+            throw new Error("State Flow session runtime contains invalid JSON");
+        }
+        if (!isObject(existing) || !isJsonValue(existing))
+            throw new Error("Invalid State Flow session runtime metadata");
+    }
+    const temporal = stream === undefined ? runtime.meta.temporal : {
+        checkpoint: structuredClone(stream.checkpoint.through),
+        patches: stream.patches.map((record) => structuredClone(record.transition)),
+    };
+    return { config: `${canonicalJson(runtime.config)}\n`, meta: `${canonicalJson({ ...existing, ...runtime.meta, ...(temporal ? { temporal } : {}) })}\n` };
+}
+export function parseSessionRuntime(config, meta, cwd, sessionId) {
+    if (config === undefined && meta === undefined)
+        return undefined;
+    if (config === undefined && meta !== undefined) {
+        let document;
+        try {
+            document = JSON.parse(meta);
+        }
+        catch {
+            throw new Error("State Flow session runtime contains invalid JSON");
+        }
+        if (isObject(document) && !Object.hasOwn(document, "identity") && !Object.hasOwn(document, "lineage")
+            && Object.keys(document).every((key) => ["version", "artifacts", "temporal", "owner"].includes(key)))
+            return undefined;
+    }
+    if (config === undefined || meta === undefined)
+        throw new Error("Incomplete State Flow config/meta pair");
+    let runtime;
+    try {
+        runtime = { config: JSON.parse(config), meta: JSON.parse(meta) };
+    }
+    catch {
+        throw new Error("State Flow session runtime contains invalid JSON");
+    }
+    validateSessionRuntime(runtime, cwd, sessionId);
+    const { temporal: _temporal, ...runtimeMeta } = runtime.meta;
+    return { config: { enabled: runtime.config.enabled }, meta: runtimeMeta };
+}
+export function resolveSessionRuntime(runtime, revision) {
+    validateSessionRuntime(runtime, runtime.meta.identity.cwd, runtime.meta.identity.sessionId);
+    if (!isExactRevision(revision) || runtime.meta.publication !== "unconfirmed")
+        throw new Error("Runtime self reference requires its exact Git revision and Git publication provenance");
+    const { version: _version, identity: _identity, lineage, revision: _self, temporalRevision: _temporal, publication: _intent, artifacts, ...fields } = runtime.meta;
+    return {
+        snapshot: { config: structuredClone(runtime.config), meta: { ...structuredClone(fields), durableBase: revision } },
+        lineage: structuredClone(lineage),
+        publicationTarget: revision,
+        artifacts: structuredClone(artifacts ?? {}),
+    };
+}
+export function resolveFileSessionRuntime(runtime, revision) {
+    validateSessionRuntime(runtime, runtime.meta.identity.cwd, runtime.meta.identity.sessionId);
+    if (!isFileRevision(revision) || runtime.meta.publication !== "files")
+        throw new Error("File runtime requires its exact file revision and file publication provenance");
+    const { version: _version, identity: _identity, lineage: _lineage, revision: _self, temporalRevision: _temporal, publication: _intent, ...fields } = runtime.meta;
+    return { config: structuredClone(runtime.config), meta: { ...structuredClone(fields), durableBase: revision } };
+}
+function isLegacyTwoPartState(value) {
+    return isObject(value)
+        && isObject(value.contract)
+        && isObject(value.working)
+        && Object.keys(value).every((key) => key === "contract" || key === "working");
+}
+function isLegacyThreePartState(value) {
+    return isObject(value)
+        && isObject(value.contract)
+        && isObject(value.working)
+        && typeof value.response === "string"
+        && Object.keys(value).every((key) => key === "contract" || key === "working" || key === "response");
+}
+function restoredStep(value) {
+    return typeof value === "number"
+        && Number.isSafeInteger(value)
+        && value >= 0
+        && value <= MAX_RESTORED_STEP
+        ? value
+        : 0;
+}
+function restoredValidation(value) {
+    if (!isObject(value)
+        || !Number.isSafeInteger(value.attempt)
+        || value.attempt < 0
+        || value.attempt > MAX_LEGACY_VALIDATION_ATTEMPT
+        || typeof value.error !== "string"
+        || typeof value.instruction !== "string")
+        return undefined;
+    return {
+        attempt: value.attempt,
+        error: value.error,
+        instruction: value.instruction,
+    };
+}
+function restoredPendingPublication(value) {
+    if (!isObject(value)
+        || typeof value.commit !== "string"
+        || !/^[0-9a-f]{40,64}$/.test(value.commit)
+        || typeof value.error !== "string"
+        || value.error.trim().length === 0)
+        return undefined;
+    return { commit: value.commit, error: value.error };
+}
+function restoredMeta(value, legacy = {}) {
+    const meta = isObject(value) ? value : legacy;
+    const pendingPublication = restoredPendingPublication(meta.pendingPublication);
+    const validation = restoredValidation(meta.validation);
+    let remotePublication;
+    try {
+        if (meta.remotePublication !== undefined)
+            remotePublication = serializeRemotePublicationPolicyDocument(parseRemotePublicationPolicyDocument(meta.remotePublication, { legacyRuntime: false }));
+    }
+    catch {
+        remotePublication = undefined;
+    }
+    return {
+        ...(isDurableRevision(meta.durableBase)
+            ? { durableBase: meta.durableBase }
+            : {}),
+        ...(pendingPublication === undefined ? {} : { pendingPublication }),
+        step: restoredStep(meta.step),
+        ...(typeof meta.specification === "string" ? { specification: meta.specification } : {}),
+        ...(validation === undefined ? {} : { validation }),
+        ...(meta.bootstrap === true ? { bootstrap: true } : {}),
+        ...(remotePublication === undefined ? {} : { remotePublication }),
+    };
+}
+function envelope(enabled, meta) {
+    return { config: { enabled }, meta };
+}
+export function emptySnapshot(enabled = false) {
+    return envelope(enabled, { step: 0 });
+}
+export function isFileRevision(value) {
+    return typeof value === "string" && /^file:[0-9a-f]{64}$/.test(value);
+}
+export function isDurableRevision(value) {
+    return isExactRevision(value) || isFileRevision(value);
+}
+export function isExactRevision(value) {
+    return typeof value === "string" && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(value);
+}
+export function persistableSnapshot(snapshot) {
+    if (snapshot.meta.durableBase !== undefined) {
+        if (!isDurableRevision(snapshot.meta.durableBase))
+            throw new Error("Checkpoint requires an exact Git revision or file reference");
+        return { revision: snapshot.meta.durableBase };
+    }
+    if (snapshot.config.enabled)
+        throw new Error("Enabled checkpoint requires a durable runtime revision");
+    return { disabled: true };
+}
+/** Pi checkpoints admit only strict revision pointers or the disabled marker. */
+export function parsePiCheckpoint(value) {
+    if (!isObject(value))
+        throw new Error("Invalid State Flow checkpoint");
+    if (Object.hasOwn(value, "revision") || Object.hasOwn(value, "disabled")) {
+        if (Object.keys(value).length === 1) {
+            if (isDurableRevision(value.revision))
+                return { revision: value.revision };
+            if (value.disabled === true)
+                return { disabled: true };
+        }
+        throw new Error("Invalid State Flow checkpoint pointer or disabled marker");
+    }
+    throw new Error("Unrecognized State Flow checkpoint");
+}
+export function migrationFailure(data, error) {
+    const meta = restoredMeta(data.meta, data);
+    meta.validation = {
+        attempt: 0,
+        error,
+        instruction: "Start a fresh State Flow episode; null is reserved for patch deletion.",
+    };
+    return envelope(false, meta);
+}
+export function migrateSnapshot(value) {
+    if (!isObject(value))
+        return emptySnapshot();
+    const isEnvelope = Object.hasOwn(value, "config") || Object.hasOwn(value, "meta");
+    const config = isEnvelope && isObject(value.config) ? value.config : value;
+    const meta = restoredMeta(isEnvelope ? value.meta : undefined, value);
+    const enabled = config.enabled === true;
+    if (Object.hasOwn(value, "state") || Object.hasOwn(value, "stateBasis") || Object.hasOwn(value, "previousStatePatch"))
+        return envelope(false, meta);
+    return envelope(enabled, meta);
+}

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

@@ -0,0 +1,55 @@
+import { type ArtifactCompilationUpdate, type ArtifactRegistry } from "./artifact.ts";
+import { type JsonObject } from "./json.ts";
+/** The canonical semantic state shape shared by global, CWD, and session scopes. */
+export interface MaterializedState extends JsonObject {
+    artifacts: ArtifactRegistry;
+    contract: JsonObject;
+    working: JsonObject;
+    response: string;
+}
+/** Compatibility name for callers that still treat materialized state as a document. */
+export type StateDocument = MaterializedState;
+/** Model patch shape; artifact entries may be compiler outputs before trusted metadata is attached. */
+export interface StatePatch extends JsonObject {
+    artifacts: JsonObject;
+    contract: JsonObject;
+    working: JsonObject;
+    response: string;
+}
+export type StateScope = "global" | "cwd" | "session";
+/** A model-authored patch for one scope. Response is captured by the runtime in session state. */
+export interface ScopePatch {
+    artifacts?: JsonObject;
+    contract?: JsonObject;
+    working?: JsonObject;
+}
+export interface ScopedPatch {
+    scope: StateScope;
+    patch: ScopePatch;
+}
+/** Canonical model-authored scope cohort before runtime final-eligibility handling. */
+export interface AtomicScopePatches {
+    global?: ScopePatch;
+    cwd?: ScopePatch;
+    session?: ScopePatch;
+}
+export interface SemanticTransition {
+    transitions: ScopedPatch[];
+}
+export interface TerminalTransition extends SemanticTransition {
+    response: string;
+}
+export interface ScopedStates {
+    global: MaterializedState;
+    cwd: MaterializedState;
+    session: MaterializedState;
+}
+export declare function emptyState(): MaterializedState;
+export declare function isMaterializedState(value: unknown): value is MaterializedState;
+export declare const isStateDocument: typeof isMaterializedState;
+/** Atomically replace compiled and removed artifacts inside one materialized scope. */
+export declare function updateMaterializedArtifacts(state: MaterializedState, updates: readonly ArtifactCompilationUpdate[], removed?: readonly string[]): MaterializedState;
+/** Overlay lower-to-higher scopes without mutating any scope document. */
+export declare function overlayStates(...scopes: readonly MaterializedState[]): MaterializedState;
+/** Model-visible projection: runtime artifact bookkeeping never reaches ordinary context. */
+export declare function projectStateForModel(state: MaterializedState): MaterializedState;

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

@@ -0,0 +1,31 @@
+import { isArtifactRegistry, projectArtifactsForModel, updateArtifactRegistry, } from "./artifact.js";
+import { applyPatch, isObject } from "./json.js";
+export function emptyState() {
+    return { artifacts: {}, contract: {}, working: {}, response: "" };
+}
+export function isMaterializedState(value) {
+    return isObject(value)
+        && isArtifactRegistry(value.artifacts)
+        && isObject(value.contract)
+        && isObject(value.working)
+        && typeof value.response === "string"
+        && Object.keys(value).every((key) => key === "artifacts" || key === "contract" || key === "working" || key === "response");
+}
+export const isStateDocument = isMaterializedState;
+/** Atomically replace compiled and removed artifacts inside one materialized scope. */
+export function updateMaterializedArtifacts(state, updates, removed = []) {
+    if (!isMaterializedState(state))
+        throw new Error("Cannot update artifacts in an invalid materialized state");
+    const artifacts = updateArtifactRegistry(state.artifacts, updates, removed);
+    return { ...structuredClone(state), artifacts };
+}
+/** Overlay lower-to-higher scopes without mutating any scope document. */
+export function overlayStates(...scopes) {
+    return scopes.reduce((effective, scope) => {
+        return applyPatch(effective, scope);
+    }, emptyState());
+}
+/** Model-visible projection: runtime artifact bookkeeping never reaches ordinary context. */
+export function projectStateForModel(state) {
+    return { ...structuredClone(state), artifacts: projectArtifactsForModel(state.artifacts) };
+}