@llblab/pi-kit 0.13.0 → 0.14.0

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

@@ -0,0 +1,38 @@
+import type { ArtifactInvalidationReason } from "./artifact.ts";
+import { type RecentTransitionWindow } from "./history.ts";
+import type { PublicationQueueState } from "./publication.ts";
+import type { Snapshot } from "./snapshot.ts";
+import { type ScopedStates, type StateScope } from "./state.ts";
+import type { TransitionBoundary } from "./temporal.ts";
+export declare const STATUS_KEY = "state-flow";
+export type Colorize = (color: "accent" | "dim", text: string) => string;
+export type StaleArtifactReason = ArtifactInvalidationReason | "source-removed";
+export interface StaleArtifactDiagnostic {
+    scope: StateScope;
+    path: string;
+    reason: StaleArtifactReason;
+}
+export interface PendingPublicationDiagnostic {
+    commit: string;
+    error: string;
+}
+export interface StatusDiagnostics {
+    repositoryRoot: string;
+    cwdScopeKey: string;
+    sessionScopeKey: string;
+    scopeStates: ScopedStates;
+    recent: RecentTransitionWindow;
+    temporal?: {
+        head: TransitionBoundary;
+        historyDepth: number;
+        tailCounts: Record<StateScope, number>;
+    };
+    staleArtifacts: readonly StaleArtifactDiagnostic[];
+    artifactFreshnessError?: string;
+    durableStateError?: string;
+    pendingPublication?: PendingPublicationDiagnostic;
+    publicationQueue?: PublicationQueueState;
+    publicationQueueError?: string;
+}
+export declare function compactStatus(snapshot: Snapshot, colorize: Colorize): string | undefined;
+export declare function detailedStatus(snapshot: Snapshot, diagnostics: StatusDiagnostics): string;

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

@@ -0,0 +1,79 @@
+import { projectRecentTransitionsWithLimit, RECENT_TRANSITION_LIMIT } from "./history.js";
+import { inspectMemoryPromotions, retainedMemoryScopes } from "./memory.js";
+import { overlayStates } from "./state.js";
+export const STATUS_KEY = "state-flow";
+export function compactStatus(snapshot, colorize) {
+    if (!snapshot.config.enabled)
+        return undefined;
+    return `${colorize("accent", "state-flow")} ${colorize("dim", `#${snapshot.meta.step}`)}`;
+}
+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 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 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",
+            "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`,
+            `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; meta.json owns lineage and 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}` : ""}`,
+        "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}`,
+        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,
+        ...(stateJson === undefined
+            ? ["Effective memory: unavailable"]
+            : [`Effective memory (${Buffer.byteLength(stateJson, "utf8")} JSON bytes; global → CWD → session overlay):`, "", stateJson]),
+    ].join("\n");
+}

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

@@ -0,0 +1,46 @@
+import { type DurableFileBase, type OwnedFileUpdate } from "./durable.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";
+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;
+/** Git writers also acquire this lock before their common-Git-directory 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. */
+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[];
+};
+/** The accepted basis comes from prepared outputs, never a post-publication worktree reread. */
+export declare function temporalFileReceipts(current: TemporalFileBase, updates: readonly OwnedFileUpdate[]): DurableFileBase[];
+export declare function captureTemporalFileBase(cwd: string, sessionId: string, root: string, sessionKey?: string): TemporalFileBase;
+/** Current-only reference: exact bytes, complete identities and lineage, no aliases or history store. */
+export declare function loadTemporalFileRevision(cwd: string, sessionId: string, root: string, revision: string, sessionKey?: string): {
+    runtime: SessionRuntime;
+    view: {
+        scopes: Record<StateScope, import("./temporal.ts").ScopeStream>;
+        lineage: import("./temporal.ts").TransitionBoundary[];
+    };
+    provenance: Record<StateScope, ArtifactProvenanceRegistry>;
+    base: {
+        files: DurableFileBase[];
+    };
+    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>>): {
+    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

@@ -0,0 +1,217 @@
+// 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, 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 { 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);
+    if (parent !== root)
+        assertStorageDirectory(parent);
+    const stat = lstatSync(root, { throwIfNoEntry: false });
+    if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
+        throw new Error(`State Flow repository path is not a regular directory: ${root}`);
+}
+/** Explicit creation only; existing bytes and unrelated files are never adopted or rewritten here. */
+export function initializeFileStore(root) {
+    assertStorageDirectory(root);
+    mkdirSync(resolve(root), { recursive: true });
+}
+/** Git writers also acquire this lock before their common-Git-directory lock. */
+export function withStoragePublicationLock(repositoryRoot, action) {
+    const root = resolve(repositoryRoot);
+    assertStorageDirectory(root);
+    const path = resolve(root, ".state-flow-publication.lock");
+    let descriptor;
+    try {
+        descriptor = openSync(path, "wx", 0o600);
+    }
+    catch (error) {
+        throw new RevisionUnavailableError(`State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause: error });
+    }
+    try {
+        writeFileSync(descriptor, `${process.pid}\n`);
+        return action(root);
+    }
+    finally {
+        closeSync(descriptor);
+        rmSync(path);
+    }
+}
+export function assertTemporalFileBase(expected, current) {
+    if (expected.files.length !== current.files.length || current.files.some((file, index) => {
+        const previous = expected.files[index];
+        return file.path !== previous.path || file.identity !== previous.identity;
+    }))
+        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. */
+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");
+    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;
+        if (!scopes.includes(scope))
+            throw new Error(`Temporal scope update omitted a changed stream: ${scope}`);
+        changedScopes.push(scope);
+    }
+    const provenanceUpdates = [];
+    // Shared metadata owns provenance, temporal boundaries, and CWD identity beside semantic files.
+    if (!runtimeOnly) {
+        for (const scope of ["global", "cwd"]) {
+            const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
+            const registry = provenance?.[scope] ?? parseScopeProvenance(files.get(paths.meta).content, paths.meta);
+            const currentFile = files.get(paths.meta);
+            if (!changedScopes.includes(scope)
+                && (provenance === undefined || sameJson(parseScopeProvenance(currentFile.content, paths.meta), registry)))
+                continue;
+            const content = serializeScopeMetadata(registry, view.scopes[scope], scope, scope === "cwd" ? cwd : undefined, currentFile.content);
+            if (currentFile.content !== content)
+                provenanceUpdates.push({ path: paths.meta, content });
+        }
+    }
+    const runtimePaths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
+    const previousRuntime = parseSessionRuntime(files.get(runtimePaths.config).content, files.get(runtimePaths.meta).content, cwd, sessionId);
+    if (previousRuntime !== undefined && changedScopes.length > 0 && runtime === undefined)
+        throw new Error("Temporal semantic publication requires its session runtime cohort");
+    const runtimeUpdates = [];
+    if (runtime !== undefined) {
+        const sources = serializeSessionRuntime(runtime, cwd, sessionId, runtimeOnly ? undefined : view.scopes.session, files.get(runtimePaths.meta).content);
+        if (!sameJson(runtime.meta.lineage, view.lineage))
+            throw new Error("Runtime lineage does not match the temporal cohort");
+        if (files.get(runtimePaths.config).content !== sources.config || files.get(runtimePaths.meta).content !== sources.meta) {
+            runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.meta, content: sources.meta });
+        }
+    }
+    else if (!runtimeOnly && changedScopes.includes("session")) {
+        const content = serializeScopeMetadata(undefined, view.scopes.session, "session", undefined, files.get(runtimePaths.meta).content);
+        if (files.get(runtimePaths.meta).content !== content)
+            runtimeUpdates.push({ path: runtimePaths.meta, content });
+    }
+    const changedPaths = new Set(changedScopes.flatMap((scope) => {
+        const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
+        return [paths.checkpoint, paths.patches];
+    }));
+    return { updates: [...candidates.filter(({ path }) => changedPaths.has(path)), ...provenanceUpdates, ...runtimeUpdates], changedScopes };
+}
+/** The accepted basis comes from prepared outputs, never a post-publication worktree reread. */
+export function temporalFileReceipts(current, updates) {
+    const receipts = new Map(updates.map((update) => [update.path, update.content]));
+    return current.files.map((file) => {
+        if (!receipts.has(file.path))
+            return file;
+        const content = receipts.get(file.path);
+        return content === undefined ? { path: file.path, identity: "missing" } : {
+            path: file.path, content, bytes: Buffer.from(content),
+            identity: `sha256:${createHash("sha256").update(content).digest("hex")}`,
+        };
+    });
+}
+function fileRevision(base, root) {
+    return `file:${hashJson({ root: resolve(root), files: base.files.map(({ path, identity }) => [relative(root, path), identity]) })}`;
+}
+function decodeFileCohort(cwd, sessionId, root, base, sessionKey = sessionId) {
+    const files = new Map(base.files.map((file) => [file.path, file.content]));
+    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.meta), cwd, sessionId);
+    if (!runtime || runtime.meta.publication !== "files")
+        throw new Error("File-only recovery requires file publication provenance, not a Git self reference");
+    const view = { scopes, lineage: runtime.meta.lineage };
+    validateTemporalState(view);
+    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),
+        session: parseArtifactProvenanceRegistry(runtime.meta.artifacts, "State Flow session artifact provenance"),
+    };
+    return { runtime, view, provenance };
+}
+export function captureTemporalFileBase(cwd, sessionId, root, sessionKey = sessionId) {
+    return withStoragePublicationLock(root, (locked) => ({ files: captureTemporalFileBases(cwd, sessionId, locked, sessionKey) }));
+}
+/** Current-only reference: exact bytes, complete identities and lineage, no aliases or history store. */
+export function loadTemporalFileRevision(cwd, sessionId, root, revision, sessionKey = sessionId) {
+    if (!isFileRevision(revision))
+        throw new Error("File recovery requires an exact file revision");
+    return withStoragePublicationLock(root, (locked) => {
+        const base = { files: captureTemporalFileBases(cwd, sessionId, locked, sessionKey) };
+        if (fileRevision(base, locked) !== revision)
+            throw new RevisionUnavailableError(`State Flow file revision is unavailable: ${revision}`);
+        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) {
+    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 next = { files: temporalFileReceipts(current, updates) };
+        decodeFileCohort(cwd, sessionId, locked, next, sessionKey);
+        const revision = fileRevision(next, locked);
+        publishFileUpdates(current.files, updates, locked);
+        return { base: next, revision, changed: updates.length > 0 };
+    });
+}
+function publishFileUpdates(bases, updates, root) {
+    writeOwnedFileUpdates(updates, bases, root);
+    try {
+        assertOwnedFileUpdates(updates, root);
+    }
+    catch (error) {
+        try {
+            const touched = new Set(updates.map(({ path }) => path));
+            restoreDurableFileBases(bases.filter(({ path }) => touched.has(path)), root, updates);
+        }
+        catch (rollbackError) {
+            throw new AggregateError([error, rollbackError], "State Flow file publication and rollback failed");
+        }
+        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.d.ts

@@ -0,0 +1,98 @@
+export declare const STATE_FLOW_TELEGRAM_ID = "@llblab/pi-state-flow";
+export interface StateFlowTelegramSnapshot {
+    enabled: boolean;
+    step: number;
+    bootstrap: boolean;
+    startPending: boolean;
+}
+export type StateFlowTelegramScope = "global" | "cwd" | "session" | "effective";
+export interface StateFlowTelegramState {
+    artifacts: Record<string, unknown>;
+    contract: Record<string, unknown>;
+    working: Record<string, unknown>;
+    response: string;
+}
+export type StateFlowTelegramRichBlock = {
+    type: "heading";
+    text: string;
+    size: 3;
+} | {
+    type: "pre";
+    text: string;
+    language?: string;
+} | {
+    type: "details";
+    summary: string | {
+        type: "bold" | "code";
+        text: string;
+    };
+    blocks: StateFlowTelegramRichBlock[];
+    is_open?: true;
+};
+export interface StateFlowTelegramRichMessage {
+    blocks: StateFlowTelegramRichBlock[];
+    skip_entity_detection?: boolean;
+}
+export interface StateFlowTelegramButton {
+    text: string;
+    callback_data: string;
+}
+export interface StateFlowTelegramView {
+    text: string;
+    parseMode?: "markdown" | "html" | "plain";
+    replyMarkup?: {
+        inline_keyboard: StateFlowTelegramButton[][];
+    };
+}
+export interface StateFlowTelegramSectionContext {
+    callbackData(action: string, payload?: string): string;
+    edit(view: StateFlowTelegramView): Promise<void>;
+    openRich(message: StateFlowTelegramRichMessage): Promise<void>;
+    answerCallback(text?: string): Promise<void>;
+}
+export interface StateFlowTelegramCallbackContext extends StateFlowTelegramSectionContext {
+    action: string;
+    payload: string;
+}
+export interface StateFlowTelegramSectionModule {
+    registerTelegramSection(section: {
+        id: string;
+        label: string;
+        getLabel?: () => string;
+        render: (ctx: StateFlowTelegramSectionContext) => StateFlowTelegramView | Promise<StateFlowTelegramView>;
+        handleCallback?: (ctx: StateFlowTelegramCallbackContext) => "handled" | "pass" | Promise<"handled" | "pass">;
+    }): () => void;
+}
+export interface StateFlowTelegramModules {
+    sections?: StateFlowTelegramSectionModule;
+}
+export type StateFlowTelegramLoader = () => Promise<StateFlowTelegramModules>;
+export interface StateFlowTelegramControlResult {
+    ok: boolean;
+    message: string;
+}
+export interface StateFlowTelegramPort {
+    snapshot(): StateFlowTelegramSnapshot;
+    state(scope: StateFlowTelegramScope): StateFlowTelegramState;
+    canStartNow(): boolean;
+    start(): StateFlowTelegramControlResult;
+    stop(): StateFlowTelegramControlResult;
+    deferStart(): void;
+    cancelStart(): void;
+}
+export interface StateFlowTelegramAdapter {
+    ensure(): Promise<boolean>;
+    dispose(): void;
+}
+/** Main-menu section label doubles as the live status value: the spiral identity is constant, the value is not. */
+export declare function formatStateFlowSectionLabel(snapshot: StateFlowTelegramSnapshot): string;
+/** The submenu header repeats the button's state line; the single action matches the current state. */
+export declare function buildStateFlowSectionView(snapshot: StateFlowTelegramSnapshot, callbackData: (action: string) => string): StateFlowTelegramView;
+export declare function buildStateFlowScopeChooser(callbackData: (action: string, payload?: string) => string): StateFlowTelegramView;
+export declare function renderStateFlowRichState(scope: StateFlowTelegramScope, step: number, state: StateFlowTelegramState): StateFlowTelegramRichMessage;
+/** Default loader; injectable so tests and embedded hosts can control transport presence. */
+export declare function loadStateFlowTelegramModules(): Promise<StateFlowTelegramModules>;
+export declare function createStateFlowTelegramAdapter(options: {
+    port: StateFlowTelegramPort;
+    load?: StateFlowTelegramLoader;
+}): StateFlowTelegramAdapter;