clinkx 1.1.1 → 1.2.0

package/clinkx-workflows/dist/verified-repair/runtime.js

@@ -0,0 +1,186 @@
+import { SchemaValidationError, OutputSizeError } from "../artifacts.js";
+import { relative } from "node:path";
+import { readContainedRelativeFile } from "../contained-file.js";
+import { FixProposalSchema, InvestigationSchema, MAX_REPAIR_PACKET_BYTES, MAX_REPAIR_PROPOSAL_BYTES, RepairPacketSchema, RepairRecordSchema, RepairReviewSchema, REPAIR_REFS, assertRepairBounded, } from "./contract.js";
+import { bytesDigest } from "../architecture-comparison/contract.js";
+import { publishRepairRecord } from "./result.js";
+import { hasCredentialTokenShape } from "../dashboard/session-log-redaction.js";
+import { WorkflowCancellationError } from "../errors.js";
+const PROVIDER_PHASES = {
+    [REPAIR_REFS.investigate]: { phase: "investigate", packet: "capture" },
+    [REPAIR_REFS.repair]: { phase: "repair", packet: "reproduce" },
+    [REPAIR_REFS.review]: { phase: "review", packet: "fixed" },
+};
+/** Fixed phase policy; the existing engine remains the only dispatcher. */
+export class VerifiedRepairRuntime {
+    host;
+    runId;
+    runDir;
+    packet;
+    providerPackets = new Map();
+    retained = new Map();
+    finalization;
+    invalidArtifact;
+    constructor(host, runId, runDir) {
+        this.host = host;
+        this.runId = runId;
+        this.runDir = runDir;
+    }
+    async prepareProvider(reference, signal) {
+        if (this.invalidArtifact !== undefined)
+            throw new Error(`invalid repair provider artifact: ${this.invalidArtifact.phase}`);
+        const binding = PROVIDER_PHASES[reference];
+        if (binding === undefined)
+            throw new Error("unexpected repair provider call");
+        if (this.packet?.phase !== binding.packet)
+            throw new Error(`repair prerequisite unavailable for ${binding.phase}`);
+        await this.verifyRetained();
+        await this.host.assertProviderPhase(binding.phase, signal);
+        assertRepairBounded(this.packet, MAX_REPAIR_PACKET_BYTES);
+        this.providerPackets.set(reference, JSON.stringify(this.packet));
+    }
+    providerPacket(reference) {
+        const packet = this.providerPackets.get(reference);
+        if (packet === undefined)
+            throw new Error("repair provider packet was not prepared");
+        return packet;
+    }
+    async beforeDispatch(reference, input, signal) {
+        const binding = PROVIDER_PHASES[reference];
+        if (binding === undefined || input["continuation_id"] !== undefined ||
+            typeof input["prompt"] !== "string" || !input["prompt"].endsWith(`\n\nFROZEN REPAIR PACKET\n${this.providerPacket(reference)}`)) {
+            throw new Error("repair dispatch is not the fresh frozen packet");
+        }
+        await this.verifyRetained();
+        await this.host.assertProviderPhase(binding.phase, signal);
+    }
+    validateOutput(reference, value) {
+        const schema = reference === REPAIR_REFS.investigate ? InvestigationSchema
+            : reference === REPAIR_REFS.repair ? FixProposalSchema
+                : reference === REPAIR_REFS.review ? RepairReviewSchema
+                    : reference === REPAIR_REFS.record ? RepairRecordSchema : RepairPacketSchema;
+        const parsed = schema.parse(value);
+        assertRepairBounded(parsed, MAX_REPAIR_PROPOSAL_BYTES);
+        if (hasCredentialTokenShape(JSON.stringify(parsed)))
+            throw new Error("repair artifact contains credential-like material; publication is rejected");
+        this.host.validateProviderOutput?.(parsed);
+        if (this.packet !== undefined && parsed.frozen_digest !== this.packet.frozen_digest)
+            throw new Error("repair artifact frozen identity mismatch");
+    }
+    noteInvalidArtifact(reference, error) {
+        if (!(reference in PROVIDER_PHASES))
+            return;
+        // JSON parser errors can include excerpts of untrusted provider text.
+        // Preserve the phase and failure class without copying those excerpts.
+        const message = error instanceof SchemaValidationError ? "provider artifact failed strict JSON/schema validation"
+            : error instanceof OutputSizeError ? "provider artifact exceeded repair byte limits"
+                : "provider artifact identity or semantic contract is invalid";
+        this.invalidArtifact ??= { kind: "invalid_artifact", phase: reference, message };
+    }
+    recordWritten(artifact) {
+        this.retained.set(artifact.reference, {
+            path: relative(this.runDir, artifact.filePath),
+            sha256: bytesDigest(`${JSON.stringify(artifact.parsed, null, 2)}\n`),
+        });
+    }
+    async reduce(operation, artifacts, signal) {
+        if (operation !== "record" && this.invalidArtifact !== undefined)
+            throw new Error(`invalid repair provider artifact: ${this.invalidArtifact.phase}`);
+        await this.verifyRetained();
+        const proposal = (reference) => {
+            const artifact = artifacts.find((entry) => entry.reference === reference);
+            if (artifact === undefined || !this.retained.has(reference))
+                throw new Error(`repair prerequisite unavailable: ${reference}`);
+            this.validateOutput(reference, artifact.parsed);
+            return artifact.parsed;
+        };
+        if (operation === "record") {
+            // The run owner publishes again after cleanup with actual terminal state.
+            // A final reducer is never the interruption publication boundary.
+            return JSON.stringify(RepairRecordSchema.parse(await this.host.record("completed")));
+        }
+        const packet = operation === "capture" ? await this.host.capture(signal)
+            : operation === "reproduce" ? await this.host.reproduce(proposal(REPAIR_REFS.investigate), signal)
+                : operation === "fixed" ? await this.host.fixed(proposal(REPAIR_REFS.repair), signal)
+                    : await this.host.independently(proposal(REPAIR_REFS.review), signal);
+        const parsed = RepairPacketSchema.parse(packet);
+        if (parsed.phase !== operation || (this.packet !== undefined && parsed.frozen_digest !== this.packet.frozen_digest))
+            throw new Error("repair host packet phase or frozen identity mismatch");
+        assertRepairBounded(parsed, MAX_REPAIR_PACKET_BYTES);
+        this.packet = parsed;
+        return JSON.stringify(this.packet);
+    }
+    /** Await all owned cleanup before publication, even with an aborted run signal. */
+    finalize(status, reason, signal) {
+        this.finalization ??= this.finalizeOnce(status, reason, signal);
+        return this.finalization;
+    }
+    async cleanupUnadmitted(reason) {
+        try {
+            await this.host.abort(reason);
+        }
+        finally {
+            await this.host.cleanup();
+        }
+    }
+    async finalizeOnce(status, reason, signal) {
+        const requestedCompletion = status === "completed";
+        const finalizationErrors = [];
+        const abort = async (error) => {
+            try {
+                await this.host.abort(error);
+            }
+            catch (abortError) {
+                finalizationErrors.push(abortError);
+            }
+        };
+        if (this.invalidArtifact !== undefined)
+            await abort(this.invalidArtifact);
+        if (status !== "completed")
+            await abort(reason ?? status);
+        try {
+            await this.host.cleanup();
+        }
+        catch (error) {
+            finalizationErrors.push(error);
+            status = status === "completed" ? "failed" : status;
+            await abort(error);
+        }
+        if (status === "completed" && finalizationErrors.length > 0)
+            status = "failed";
+        if (requestedCompletion && signal?.aborted) {
+            status = "cancelled";
+            await abort(signal.reason ?? "cancelled during finalization");
+        }
+        let record = RepairRecordSchema.parse(await this.host.record(status));
+        if (record.run_id !== this.runId || record.execution_status !== status)
+            throw new Error("repair terminal record identity mismatch");
+        await publishRepairRecord(this.runDir, record);
+        // Cancellation can arrive while the host projection or atomic publication
+        // awaits I/O. Reproject partial facts before the owner commits terminal state.
+        if (requestedCompletion && signal?.aborted && status !== "cancelled") {
+            await abort(signal.reason ?? "cancelled during publication");
+            status = "cancelled";
+            record = RepairRecordSchema.parse(await this.host.record(status));
+            if (record.run_id !== this.runId || record.execution_status !== status)
+                throw new Error("repair terminal record identity mismatch");
+            await publishRepairRecord(this.runDir, record);
+        }
+        if (requestedCompletion && status === "cancelled")
+            throw new WorkflowCancellationError();
+        if (finalizationErrors.length > 0)
+            throw new AggregateError(finalizationErrors, "repair finalization failed after retaining terminal facts");
+        return JSON.stringify(record);
+    }
+    async verifyRetained() {
+        for (const [reference, fact] of this.retained) {
+            const read = await readContainedRelativeFile(this.runDir, fact.path, {
+                wantContent: true, requireRegular: true, requireExactRequestedPath: true,
+                maxBytes: MAX_REPAIR_PROPOSAL_BYTES,
+            });
+            if (bytesDigest(read.content) !== fact.sha256)
+                throw new Error(`retained repair artifact changed: ${reference}`);
+        }
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/clinkx-workflows/dist/verified-repair/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/verified-repair/runtime.ts"],"names":[],"mappings":"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"}

package/clinkx-workflows/dist/workflow-completion.d.ts

@@ -0,0 +1,83 @@
+export declare const WORKFLOW_WAIT_BUDGET_MS = 30000;
+export declare const SETTLED_LIMIT = 128;
+export type IdentityFailure = "identity_changed" | "identity_unavailable";
+export interface PublicationIdentity {
+    readonly generation: string;
+    readonly fingerprint: string;
+    readonly terminal: boolean;
+}
+/** Read-only view; every transition goes through WorkflowCompletionRegistry. */
+export interface WorkflowCompletion {
+    readonly executionId: string;
+    readonly runId: string;
+    readonly runDir: string;
+    readonly settled: boolean;
+    /** state.json carries executionId; set once the owner's stamp write lands. */
+    readonly stamped: boolean;
+    readonly observers: number;
+    readonly listenerCount: number;
+}
+/** One run owner's lazy binding to the store it created or resumed. */
+export interface CompletionOwner {
+    readonly entry: WorkflowCompletion | undefined;
+    /** Idempotent for the same store; a different store is a programming error. */
+    bind(store: {
+        readonly sessionLogGeneration: string | undefined;
+    }): WorkflowCompletion;
+}
+/**
+ * Provenance only: result bodies and unfinished promise callbacks are never cached.
+ * An execution exists here only once its owner has bound a created/resumed
+ * store, so a request rejected during admission can never displace one.
+ */
+export declare class WorkflowCompletionRegistry {
+    private readonly latest;
+    private readonly byId;
+    private readonly minted;
+    private readonly settledIds;
+    bind(runId: string, runDir: string, generation: string | undefined): WorkflowCompletion;
+    owner(runId: string, runDir: string): CompletionOwner;
+    /**
+     * A pin yields `identity_unavailable` only when this registry retains no
+     * record for it (bound by another process, or evicted); callers may then
+     * consult the identity persisted in state.json.
+     */
+    select(runDir: string): WorkflowCompletion | undefined;
+    select(runDir: string, expected?: string): WorkflowCompletion | IdentityFailure | undefined;
+    /**
+     * Capture the terminal publication while ownership still prevents local
+     * re-admission. Only a terminal state of the bound directory incarnation counts.
+     */
+    recordPublication(entry: WorkflowCompletion): Promise<void>;
+    markStamped(entry: WorkflowCompletion): void;
+    settle(entry: WorkflowCompletion): void;
+    /** Protect provenance through the handler's final filesystem rereads. */
+    retain(entry: WorkflowCompletion): () => void;
+    /**
+     * Execution fence around a projection. `observedDigest` is the fingerprint of
+     * the state bytes the projection actually parsed (null: unreadable); pass it
+     * only when the entry was already settled before that projection began.
+     * Without it, only provenance and directory incarnation are checked, which
+     * is correct for an active execution that legitimately republishes state.
+     */
+    check(entry: WorkflowCompletion, observedDigest?: string | null): Promise<IdentityFailure | undefined>;
+    wait(entry: WorkflowCompletion, signal: AbortSignal): Promise<"settled" | "budget_elapsed">;
+    private selectionFailure;
+    private own;
+    private prune;
+}
+/**
+ * Persisted provenance for a pin this process retains no record for. Only a
+ * terminal state stamped with exactly that id, whose run.lock is released
+ * (`stale_or_absent`), counts as its settlement: a live or unknown lock means
+ * an owner may still be inside its cleanup fence, and a non-terminal match has
+ * no local owner whose fence could be witnessed.
+ */
+export declare function persistedIdentityFailure(state: {
+    readonly runId?: unknown;
+    readonly status?: unknown;
+    readonly executionId?: unknown;
+    readonly completedAt?: unknown;
+    readonly executionCompletedAt?: unknown;
+}, lock: "held" | "stale_or_absent" | "unknown", runId: string, expected: string): IdentityFailure | undefined;
+export declare function inspectPublication(runDir: string): Promise<PublicationIdentity | undefined>;

package/clinkx-workflows/dist/workflow-completion.js

@@ -0,0 +1,250 @@
+import { createHash, randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { readContainedRelativeFile } from "./contained-file.js";
+import { DEFAULT_DASHBOARD_MAX_STATE_BYTES } from "./config.js";
+import { readSessionLogGeneration } from "./dashboard/session-log-identity.js";
+import { WorkflowCancellationError } from "./errors.js";
+import { logger } from "./logger.js";
+export const WORKFLOW_WAIT_BUDGET_MS = 30_000;
+export const SETTLED_LIMIT = 128;
+/** sha256 over the exact bytes read from state.json (never a decoded string). */
+function fingerprintStateBytes(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Provenance only: result bodies and unfinished promise callbacks are never cached.
+ * An execution exists here only once its owner has bound a created/resumed
+ * store, so a request rejected during admission can never displace one.
+ */
+export class WorkflowCompletionRegistry {
+    latest = new Map();
+    byId = new Map();
+    minted = new WeakSet();
+    settledIds = [];
+    bind(runId, runDir, generation) {
+        const listeners = new Set();
+        const record = {
+            executionId: randomUUID(),
+            runId,
+            runDir: resolve(runDir),
+            generation,
+            publication: undefined,
+            settled: false,
+            stamped: false,
+            observers: 0,
+            listeners,
+            get listenerCount() { return listeners.size; },
+        };
+        this.minted.add(record);
+        this.byId.set(record.executionId, record);
+        this.latest.set(record.runDir, record);
+        return record;
+    }
+    owner(runId, runDir) {
+        let entry;
+        let boundStore;
+        return {
+            get entry() { return entry; },
+            bind: (store) => {
+                if (entry !== undefined) {
+                    if (boundStore !== store)
+                        throw new Error(`workflow run ${runId} is already bound to a different state store`);
+                    return entry;
+                }
+                entry = this.bind(runId, runDir, store.sessionLogGeneration);
+                boundStore = store;
+                return entry;
+            },
+        };
+    }
+    select(runDir, expected) {
+        const latest = this.latest.get(resolve(runDir));
+        if (expected === undefined)
+            return latest;
+        const entry = this.byId.get(expected);
+        if (entry === undefined)
+            return "identity_unavailable";
+        if (entry.runDir !== resolve(runDir) || latest !== entry)
+            return "identity_changed";
+        return entry;
+    }
+    /**
+     * Capture the terminal publication while ownership still prevents local
+     * re-admission. Only a terminal state of the bound directory incarnation counts.
+     */
+    async recordPublication(entry) {
+        const record = this.own(entry);
+        if (record.settled || record.generation === undefined)
+            return;
+        const publication = await inspectPublication(record.runDir);
+        if (publication?.generation === record.generation && publication.terminal) {
+            record.publication = publication;
+        }
+    }
+    markStamped(entry) {
+        this.own(entry).stamped = true;
+    }
+    settle(entry) {
+        const record = this.own(entry);
+        if (record.settled)
+            return;
+        record.settled = true;
+        this.settledIds.push(record.executionId);
+        this.prune();
+        for (const listener of [...record.listeners])
+            listener();
+    }
+    /** Protect provenance through the handler's final filesystem rereads. */
+    retain(entry) {
+        const record = this.own(entry);
+        record.observers += 1;
+        return () => {
+            record.observers -= 1;
+            this.prune();
+        };
+    }
+    /**
+     * Execution fence around a projection. `observedDigest` is the fingerprint of
+     * the state bytes the projection actually parsed (null: unreadable); pass it
+     * only when the entry was already settled before that projection began.
+     * Without it, only provenance and directory incarnation are checked, which
+     * is correct for an active execution that legitimately republishes state.
+     */
+    async check(entry, observedDigest) {
+        const record = this.own(entry);
+        const before = this.selectionFailure(record);
+        if (before !== undefined)
+            return before;
+        if (record.generation === undefined)
+            return "identity_unavailable";
+        const generation = await readSessionLogGeneration(record.runDir);
+        // Recheck after the I/O: a replacement may bind while the read is pending.
+        const after = this.selectionFailure(record);
+        if (after !== undefined)
+            return after;
+        if (generation.kind !== "available")
+            return "identity_unavailable";
+        if (generation.sessionLogGeneration !== record.generation)
+            return "identity_changed";
+        if (record.settled && record.publication === undefined)
+            return "identity_unavailable";
+        if (observedDigest !== undefined) {
+            if (record.publication === undefined || observedDigest === null)
+                return "identity_unavailable";
+            if (observedDigest !== record.publication.fingerprint)
+                return "identity_changed";
+        }
+        return undefined;
+    }
+    wait(entry, signal) {
+        const record = this.own(entry);
+        if (signal.aborted)
+            return Promise.reject(new WorkflowCancellationError());
+        if (record.settled)
+            return Promise.resolve("settled");
+        return new Promise((resolveWait, reject) => {
+            let timer;
+            const cleanup = () => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                record.listeners.delete(onComplete);
+                signal.removeEventListener("abort", onAbort);
+            };
+            const onComplete = () => {
+                cleanup();
+                resolveWait("settled");
+            };
+            const onAbort = () => {
+                cleanup();
+                reject(new WorkflowCancellationError());
+            };
+            record.listeners.add(onComplete);
+            signal.addEventListener("abort", onAbort, { once: true });
+            timer = setTimeout(() => {
+                cleanup();
+                resolveWait("budget_elapsed");
+            }, WORKFLOW_WAIT_BUDGET_MS);
+            // A pending observation must not keep an otherwise idle process alive.
+            timer.unref?.();
+            // Inspect after registration, so a fast completion cannot strand a waiter.
+            if (record.settled)
+                onComplete();
+            else if (signal.aborted)
+                onAbort();
+        });
+    }
+    selectionFailure(record) {
+        const selected = this.select(record.runDir, record.executionId);
+        if (typeof selected === "string")
+            return selected;
+        return selected === record ? undefined : "identity_unavailable";
+    }
+    own(entry) {
+        if (!this.minted.has(entry))
+            throw new Error("workflow completion was not bound by this registry");
+        return entry;
+    }
+    prune() {
+        while (this.settledIds.length > SETTLED_LIMIT) {
+            const index = this.settledIds.findIndex((id) => this.byId.get(id)?.observers === 0);
+            if (index === -1)
+                return;
+            const id = this.settledIds.splice(index, 1)[0];
+            const retired = this.byId.get(id);
+            this.byId.delete(id);
+            if (retired !== undefined && this.latest.get(retired.runDir) === retired) {
+                this.latest.delete(retired.runDir);
+            }
+        }
+    }
+}
+function isTerminalStatus(status) {
+    return status === "succeeded" || status === "failed" || status === "cancelled";
+}
+/**
+ * Persisted provenance for a pin this process retains no record for. Only a
+ * terminal state stamped with exactly that id, whose run.lock is released
+ * (`stale_or_absent`), counts as its settlement: a live or unknown lock means
+ * an owner may still be inside its cleanup fence, and a non-terminal match has
+ * no local owner whose fence could be witnessed.
+ */
+export function persistedIdentityFailure(state, lock, runId, expected) {
+    if (typeof state.executionId !== "string" || state.runId !== runId)
+        return "identity_unavailable";
+    if (state.executionId !== expected)
+        return "identity_changed";
+    if (!isTerminalStatus(state.status) || lock !== "stale_or_absent")
+        return "identity_unavailable";
+    return typeof state.completedAt === "string" && state.executionCompletedAt === state.completedAt
+        ? undefined
+        : "identity_unavailable";
+}
+export async function inspectPublication(runDir) {
+    try {
+        const before = await readSessionLogGeneration(runDir);
+        if (before.kind !== "available")
+            return undefined;
+        const file = await readContainedRelativeFile(runDir, "state.json", {
+            wantBytes: true,
+            requireRegular: true,
+            requireExactRequestedPath: true,
+            maxBytes: DEFAULT_DASHBOARD_MAX_STATE_BYTES,
+        });
+        const state = JSON.parse(file.bytes.toString("utf-8"));
+        const after = await readSessionLogGeneration(runDir);
+        if (after.kind !== "available" || after.sessionLogGeneration !== before.sessionLogGeneration) {
+            return undefined;
+        }
+        return {
+            generation: before.sessionLogGeneration,
+            fingerprint: fingerprintStateBytes(file.bytes),
+            terminal: isTerminalStatus(state.status),
+        };
+    }
+    catch (error) {
+        // Class only: messages can carry paths or state values.
+        logger.debug({ errClass: error instanceof Error ? error.constructor.name : typeof error, runDir }, "workflow publication identity unavailable");
+        return undefined;
+    }
+}
+//# sourceMappingURL=workflow-completion.js.map

package/clinkx-workflows/dist/workflow-completion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-completion.js","sourceRoot":"","sources":["../src/workflow-completion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,iCAAiC,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAC9C,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAsCjC,iFAAiF;AACjF,SAAS,qBAAqB,CAAC,KAAiB;IAC9C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,0BAA0B;IACpB,MAAM,GAAG,IAAI,GAAG,EAA4B,CAAC;IAC7C,IAAI,GAAG,IAAI,GAAG,EAA4B,CAAC;IAC3C,MAAM,GAAG,IAAI,OAAO,EAAsB,CAAC;IAC3C,UAAU,GAAa,EAAE,CAAC;IAE3C,IAAI,CAAC,KAAa,EAAE,MAAc,EAAE,UAA8B;QAChE,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;QACxC,MAAM,MAAM,GAAqB;YAC/B,WAAW,EAAE,UAAU,EAAE;YACzB,KAAK;YACL,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC;YACvB,UAAU;YACV,WAAW,EAAE,SAAS;YACtB,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,KAAK;YACd,SAAS,EAAE,CAAC;YACZ,SAAS;YACT,IAAI,aAAa,KAAK,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;SAC/C,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACvC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,KAAa,EAAE,MAAc;QACjC,IAAI,KAAqC,CAAC;QAC1C,IAAI,UAA8B,CAAC;QACnC,OAAO;YACL,IAAI,KAAK,KAAK,OAAO,KAAK,CAAC,CAAC,CAAC;YAC7B,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE;gBACd,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;oBACxB,IAAI,UAAU,KAAK,KAAK;wBAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,KAAK,8CAA8C,CAAC,CAAC;oBAC/G,OAAO,KAAK,CAAC;gBACf,CAAC;gBACD,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,oBAAoB,CAAC,CAAC;gBAC7D,UAAU,GAAG,KAAK,CAAC;gBACnB,OAAO,KAAK,CAAC;YACf,CAAC;SACF,CAAC;IACJ,CAAC;IASD,MAAM,CAAC,MAAc,EAAE,QAAiB;QACtC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAChD,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;QAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,sBAAsB,CAAC;QACvD,IAAI,KAAK,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,KAAK,KAAK;YAAE,OAAO,kBAAkB,CAAC;QACpF,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,iBAAiB,CAAC,KAAyB;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS;YAAE,OAAO;QAC9D,MAAM,WAAW,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5D,IAAI,WAAW,EAAE,UAAU,KAAK,MAAM,CAAC,UAAU,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;YAC1E,MAAM,CAAC,WAAW,GAAG,WAAW,CAAC;QACnC,CAAC;IACH,CAAC;IAED,WAAW,CAAC,KAAyB;QACnC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC;IACjC,CAAC;IAED,MAAM,CAAC,KAAyB;QAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO;QAC3B,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC;YAAE,QAAQ,EAAE,CAAC;IAC3D,CAAC;IAED,yEAAyE;IACzE,MAAM,CAAC,KAAyB;QAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC/B,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC;QACtB,OAAO,GAAG,EAAE;YACV,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC;YACtB,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,CAAC,KAAyB,EAAE,cAA8B;QACnE,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC7C,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;QACxC,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS;YAAE,OAAO,sBAAsB,CAAC;QACnE,MAAM,UAAU,GAAG,MAAM,wBAAwB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACjE,2EAA2E;QAC3E,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC5C,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACtC,IAAI,UAAU,CAAC,IAAI,KAAK,WAAW;YAAE,OAAO,sBAAsB,CAAC;QACnE,IAAI,UAAU,CAAC,oBAAoB,KAAK,MAAM,CAAC,UAAU;YAAE,OAAO,kBAAkB,CAAC;QACrF,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,WAAW,KAAK,SAAS;YAAE,OAAO,sBAAsB,CAAC;QACtF,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;YACjC,IAAI,MAAM,CAAC,WAAW,KAAK,SAAS,IAAI,cAAc,KAAK,IAAI;gBAAE,OAAO,sBAAsB,CAAC;YAC/F,IAAI,cAAc,KAAK,MAAM,CAAC,WAAW,CAAC,WAAW;gBAAE,OAAO,kBAAkB,CAAC;QACnF,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC,KAAyB,EAAE,MAAmB;QACjD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,yBAAyB,EAAE,CAAC,CAAC;QAC3E,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACtD,OAAO,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE;YACzC,IAAI,KAAgD,CAAC;YACrD,MAAM,OAAO,GAAG,GAAS,EAAE;gBACzB,IAAI,KAAK,KAAK,SAAS;oBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;gBAC7C,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;gBACpC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC/C,CAAC,CAAC;YACF,MAAM,UAAU,GAAG,GAAS,EAAE;gBAC5B,OAAO,EAAE,CAAC;gBACV,WAAW,CAAC,SAAS,CAAC,CAAC;YACzB,CAAC,CAAC;YACF,MAAM,OAAO,GAAG,GAAS,EAAE;gBACzB,OAAO,EAAE,CAAC;gBACV,MAAM,CAAC,IAAI,yBAAyB,EAAE,CAAC,CAAC;YAC1C,CAAC,CAAC;YACF,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACjC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1D,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBACtB,OAAO,EAAE,CAAC;gBACV,WAAW,CAAC,gBAAgB,CAAC,CAAC;YAChC,CAAC,EAAE,uBAAuB,CAAC,CAAC;YAC5B,uEAAuE;YACvE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;YAChB,2EAA2E;YAC3E,IAAI,MAAM,CAAC,OAAO;gBAAE,UAAU,EAAE,CAAC;iBAC5B,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAO,EAAE,CAAC;QACrC,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,gBAAgB,CAAC,MAAwB;QAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;QAChE,IAAI,OAAO,QAAQ,KAAK,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAClD,OAAO,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,sBAAsB,CAAC;IAClE,CAAC;IAEO,GAAG,CAAC,KAAyB;QACnC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACnG,OAAO,KAAyB,CAAC;IACnC,CAAC;IAEO,KAAK;QACX,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,aAAa,EAAE,CAAC;YAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,SAAS,KAAK,CAAC,CAAC,CAAC;YACpF,IAAI,KAAK,KAAK,CAAC,CAAC;gBAAE,OAAO;YACzB,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC;YAChD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAClC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACrB,IAAI,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,OAAO,EAAE,CAAC;gBACzE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACrC,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,SAAS,gBAAgB,CAAC,MAAe;IACvC,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,WAAW,CAAC;AACjF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAMC,EACD,IAA4C,EAC5C,KAAa,EACb,QAAgB;IAEhB,IAAI,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK;QAAE,OAAO,sBAAsB,CAAC;IAClG,IAAI,KAAK,CAAC,WAAW,KAAK,QAAQ;QAAE,OAAO,kBAAkB,CAAC;IAC9D,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,IAAI,KAAK,iBAAiB;QAAE,OAAO,sBAAsB,CAAC;IACjG,OAAO,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,IAAI,KAAK,CAAC,oBAAoB,KAAK,KAAK,CAAC,WAAW;QAC9F,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,sBAAsB,CAAC;AAC7B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAc;IACrD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,wBAAwB,CAAC,MAAM,CAAC,CAAC;QACtD,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW;YAAE,OAAO,SAAS,CAAC;QAClD,MAAM,IAAI,GAAG,MAAM,yBAAyB,CAAC,MAAM,EAAE,YAAY,EAAE;YACjE,SAAS,EAAE,IAAI;YACf,cAAc,EAAE,IAAI;YACpB,yBAAyB,EAAE,IAAI;YAC/B,QAAQ,EAAE,iCAAiC;SAC5C,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAyB,CAAC;QAChF,MAAM,KAAK,GAAG,MAAM,wBAAwB,CAAC,MAAM,CAAC,CAAC;QACrD,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,IAAI,KAAK,CAAC,oBAAoB,KAAK,MAAM,CAAC,oBAAoB,EAAE,CAAC;YAC7F,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO;YACL,UAAU,EAAE,MAAM,CAAC,oBAAoB;YACvC,WAAW,EAAE,qBAAqB,CAAC,IAAI,CAAC,KAAM,CAAC;YAC/C,QAAQ,EAAE,gBAAgB,CAAC,KAAK,CAAC,MAAM,CAAC;SACzC,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,wDAAwD;QACxD,MAAM,CAAC,KAAK,CACV,EAAE,QAAQ,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,KAAK,EAAE,MAAM,EAAE,EACpF,2CAA2C,CAC5C,CAAC;QACF,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/clinkx-workflows/dist/workflow-tools.d.ts

@@ -5,11 +5,12 @@
  * - Standalone STDIO server (ClinkSession child process backend)
  * - In-process integration (LocalClinkBackend via root ClinkX)
  *
- * The `registerWorkflowTools()` function registers five tools on a Server:
+ * The `registerWorkflowTools()` function registers six tools on a Server:
  * - run_workflow: start a new workflow execution
  * - resume_workflow: resume a failed/cancelled run
  * - list_workflows: list available workflow definitions
  * - workflow_run_status: read workflow run progress/result
+ * - workflow_run_wait: observe local execution settlement
  * - cancel_workflow: cancel a live or orphaned workflow run
  *
  * The caller provides a `createBackend` factory that determines how clink
@@ -26,7 +27,10 @@ import type { Variable } from "./schema.js";
 import { type WorkflowContextRequestedMode, type WorkflowContextPolicy } from "./context-mode-resolver.js";
 import { type AvailableCliCapability, type ResolvedRoster } from "./roster-contract.js";
 import type { RosterLoader } from "./rosters.js";
+import type { VerifiedRepairHost } from "./verified-repair/host.js";
 export interface WorkflowToolsOptions {
+    /** Root-owned contract capture, scoped edits, and native verification. */
+    readonly verifiedRepairHost?: VerifiedRepairHost | undefined;
     /**
      * Factory that creates a ClinkBackend for a given run.
      * For standalone server: `(runId) => new ClinkSession({ runId })`
@@ -191,8 +195,8 @@ export declare function handleWorkflowToolCall(server: Server, options: Workflow
  * Register workflow tools on an MCP Server instance.
  *
  * This is the reusable core extracted from createWorkflowServer().
- * It registers five tools: run_workflow, resume_workflow, list_workflows,
- * workflow_run_status, cancel_workflow.
+ * It registers six tools: run_workflow, resume_workflow, list_workflows,
+ * workflow_run_status, workflow_run_wait, cancel_workflow.
  *
  * The `options.createBackend` factory determines how clink calls are
  * dispatched — callers provide either a child-process or in-process backend.