cloving 0.3.20 → 1.0.1

package/dist/src/host/step-bridge-host.d.ts

@@ -0,0 +1,79 @@
+import { type ProtectedRequest, type StepBridge } from "../step-bridge.ts";
+export interface StepCall {
+    readonly worldRunId: string;
+    readonly stepId: string;
+    readonly attempt: number;
+}
+export declare function sdkStepCall(): StepCall;
+export interface OperationRead {
+    readonly operationId: string;
+    readonly status: string;
+    readonly reason: string | null;
+    readonly receipt: string | null;
+    readonly result: string | null;
+}
+export interface BridgeReply {
+    readonly receipt: {
+        readonly kind: string;
+        readonly reason?: string;
+    };
+    readonly disposition: {
+        readonly disposition: string;
+        readonly reason: string | null;
+    } | null;
+    readonly operation: OperationRead | null;
+}
+interface BridgeIdentity {
+    readonly commandId: string;
+    readonly transport: string;
+}
+export interface BridgeRequest extends ProtectedRequest, BridgeIdentity {
+    readonly runId: string;
+}
+export interface GateReceipt {
+    readonly kind: string;
+    readonly reason?: string;
+}
+export interface GateOpening {
+    readonly runId: string;
+    readonly commandId: string;
+    readonly expectedRevision: number;
+    readonly gateId: string;
+    readonly kind: "question" | "approval";
+    readonly prompt: string;
+    readonly subject: string;
+}
+export interface WaitRegistration {
+    readonly runId: string;
+    readonly commandId: string;
+    readonly gateId: string;
+}
+export interface BridgeTiming {
+    readonly lookupTries: number;
+    readonly pollMilliseconds: number;
+    readonly retryMilliseconds: number;
+}
+export declare const bridgeTiming: BridgeTiming;
+export interface BridgePorts {
+    readonly call: () => StepCall;
+    readonly run: (worldRunId: string) => Promise<{
+        readonly runId: string;
+    } | undefined>;
+    readonly timing?: BridgeTiming;
+    readonly stopped: AbortSignal;
+    readonly state: () => Promise<{
+        readonly runs: Readonly<Record<string, {
+            readonly status: string;
+            readonly revision: number;
+        } | undefined>>;
+        readonly gates: Readonly<Record<string, unknown>>;
+    }>;
+    readonly openGate: (opening: GateOpening) => Promise<GateReceipt>;
+    readonly registerWait: (wait: WaitRegistration) => Promise<GateReceipt>;
+    readonly requestEffect: (request: BridgeRequest) => Promise<BridgeReply>;
+    readonly operation: (operationId: string) => Promise<OperationRead | undefined>;
+    readonly document: (digest: string) => Promise<string | undefined>;
+}
+export declare function stepBridge(ports: BridgePorts): StepBridge;
+export declare function registerStepBridge(bridge: StepBridge): () => void;
+export {};

package/dist/src/host/step-bridge-host.js

@@ -0,0 +1,205 @@
+import { createHash } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { getStepMetadata, getWorkflowMetadata } from "workflow";
+import { gateKey } from "../authority/gates.js";
+import { stepBridgeKey, } from "../step-bridge.js";
+export function sdkStepCall() {
+    const { stepId, attempt } = getStepMetadata();
+    return { worldRunId: getWorkflowMetadata().workflowRunId, stepId, attempt };
+}
+export const bridgeTiming = {
+    lookupTries: 250,
+    pollMilliseconds: 20,
+    retryMilliseconds: 1000,
+};
+const committed = ["accepted", "duplicate"];
+const ended = ["failed", "stopped", "blocked", "cancelled"];
+async function paused(hold, milliseconds) {
+    const { stopped } = hold.ports;
+    await delay(milliseconds, undefined, { signal: stopped }).catch(() => undefined);
+    if (stopped.aborted)
+        await new Promise(() => undefined);
+}
+function answered(reply) {
+    const { receipt, disposition, operation } = reply;
+    const busy = receipt.kind === "rejected" && receipt.reason === "service-busy";
+    if (receipt.kind === "failed" || busy)
+        return undefined;
+    if (!committed.includes(receipt.kind))
+        return { kind: "refused", reason: receipt.reason ?? receipt.kind };
+    if (disposition?.disposition === "refused")
+        return { kind: "refused", reason: disposition.reason ?? "refused" };
+    if (operation === null)
+        return undefined;
+    return { kind: "admitted", operationId: operation.operationId };
+}
+async function requested(hold, request) {
+    for (;;) {
+        await paused(hold, 0);
+        const answer = await hold.ports
+            .requestEffect(request)
+            .then(answered, () => undefined);
+        if (answer !== undefined)
+            return answer;
+        await paused(hold, hold.timing.retryMilliseconds);
+    }
+}
+async function text(hold, digest) {
+    if (digest === null)
+        return null;
+    for (;;) {
+        const read = await hold.ports.document(digest).then((value) => ({ value: value ?? null }), () => undefined);
+        if (read !== undefined)
+            return read.value;
+        await paused(hold, hold.timing.retryMilliseconds);
+    }
+}
+async function outcome(hold, operation) {
+    const { operationId, status, reason, receipt, result } = operation;
+    if (status === "refused")
+        return { kind: "refused", reason: reason ?? "refused" };
+    const end = ended.find((kind) => kind === status);
+    if (end !== undefined)
+        return { kind: end, operationId, reason };
+    if (status !== "completed")
+        return undefined;
+    return {
+        kind: "completed",
+        operationId,
+        receipt,
+        result: await text(hold, result),
+    };
+}
+async function settled(hold, operationId) {
+    for (;;) {
+        const operation = await hold.ports
+            .operation(operationId)
+            .catch(() => undefined);
+        const result = operation === undefined ? undefined : await outcome(hold, operation);
+        if (result !== undefined)
+            return result;
+        await paused(hold, operation === undefined
+            ? hold.timing.retryMilliseconds
+            : hold.timing.pollMilliseconds);
+    }
+}
+async function located(hold, worldRunId) {
+    const tries = hold.timing.lookupTries;
+    for (let attempt = 1; attempt <= tries; attempt += 1) {
+        const world = await hold.ports.run(worldRunId);
+        if (world !== undefined || attempt === tries)
+            return world;
+        await paused(hold, hold.timing.pollMilliseconds);
+    }
+    return undefined;
+}
+async function inWork(hold, runId) {
+    for (;;) {
+        const state = await hold.ports.state().catch(() => undefined);
+        if (state !== undefined && state.runs[runId]?.status !== "queued")
+            return;
+        await paused(hold, state === undefined
+            ? hold.timing.retryMilliseconds
+            : hold.timing.pollMilliseconds);
+    }
+}
+function transportOf(call) {
+    return `sdk:${call.stepId}`.replace(/[^A-Za-z0-9._:/-]/g, "-");
+}
+function identity(call, request) {
+    const transport = transportOf(call);
+    const scope = createHash("sha256")
+        .update(JSON.stringify(request.scope))
+        .digest("hex")
+        .slice(0, 16);
+    return { transport, commandId: `${transport}:${scope}` };
+}
+async function effect(hold, request) {
+    const call = hold.ports.call();
+    const world = await located(hold, call.worldRunId);
+    if (world === undefined)
+        return { kind: "unavailable", reason: "unknown-world-run" };
+    await inWork(hold, world.runId);
+    const answer = await requested(hold, {
+        ...request,
+        ...identity(call, request),
+        runId: world.runId,
+    });
+    if (answer.kind !== "admitted")
+        return answer;
+    return await settled(hold, answer.operationId);
+}
+function verdict(hold, receipt) {
+    if (receipt === undefined || receipt.kind === "failed")
+        return hold.timing.retryMilliseconds;
+    if (committed.includes(receipt.kind))
+        return "committed";
+    if (receipt.reason === "service-busy")
+        return hold.timing.retryMilliseconds;
+    if (receipt.reason === "stale-revision")
+        return hold.timing.pollMilliseconds;
+    return { kind: "refused", reason: receipt.reason ?? receipt.kind };
+}
+async function gateCommand(hold, send) {
+    for (;;) {
+        await paused(hold, 0);
+        const result = verdict(hold, await send().catch(() => undefined));
+        if (result === "committed")
+            return undefined;
+        if (typeof result !== "number")
+            return result;
+        await paused(hold, result);
+    }
+}
+async function opening(hold, subject) {
+    const { runId, transport, request } = subject;
+    const { gateId, kind, prompt } = request;
+    const state = await hold.ports.state();
+    const run = state.runs[runId];
+    if (run === undefined)
+        return { kind: "rejected", reason: "unknown-run" };
+    if (Object.hasOwn(state.gates, gateKey(runId, gateId)))
+        return { kind: "duplicate" };
+    return await hold.ports.openGate({
+        runId,
+        commandId: `${transport}:open:${gateId}`,
+        expectedRevision: run.revision,
+        gateId,
+        kind,
+        prompt,
+        subject: `sha256:${createHash("sha256").update(prompt).digest("hex")}`,
+    });
+}
+async function gate(hold, request) {
+    const call = hold.ports.call();
+    const world = await located(hold, call.worldRunId);
+    if (world === undefined)
+        return { kind: "unavailable", reason: "unknown-world-run" };
+    await inWork(hold, world.runId);
+    const subject = {
+        runId: world.runId,
+        transport: transportOf(call),
+        request,
+    };
+    const refusal = (await gateCommand(hold, () => opening(hold, subject))) ??
+        (await gateCommand(hold, () => hold.ports.registerWait({
+            runId: subject.runId,
+            commandId: `${subject.transport}:wait:${request.gateId}`,
+            gateId: request.gateId,
+        })));
+    return refusal ?? { kind: "opened", decisionId: request.gateId };
+}
+export function stepBridge(ports) {
+    const hold = { ports, timing: ports.timing ?? bridgeTiming };
+    return {
+        effect: (request) => effect(hold, request),
+        gate: (request) => gate(hold, request),
+    };
+}
+export function registerStepBridge(bridge) {
+    const key = Symbol.for(stepBridgeKey);
+    Reflect.set(globalThis, key, bridge);
+    return () => {
+        Reflect.deleteProperty(globalThis, key);
+    };
+}

package/dist/src/host/step-claims.d.ts

@@ -0,0 +1,31 @@
+interface ClaimEvent {
+    readonly eventType: string;
+    readonly correlationId?: string | undefined;
+}
+interface EventPage {
+    readonly data: readonly ClaimEvent[];
+    readonly cursor: string | null;
+    readonly hasMore: boolean;
+}
+export interface ClaimWorld {
+    readonly runs: {
+        readonly get: (runId: string, parameters: {
+            readonly resolveData: "none";
+        }) => Promise<{
+            readonly status: string;
+        }>;
+    };
+    readonly events: {
+        readonly list: (parameters: {
+            readonly runId: string;
+            readonly resolveData: "none";
+            readonly pagination: {
+                readonly limit: number;
+                readonly sortOrder: "asc";
+                readonly cursor?: string;
+            };
+        }) => Promise<EventPage>;
+    };
+}
+export declare function releaseStepClaims(dataDirectory: string, world: ClaimWorld): Promise<readonly string[]>;
+export {};

package/dist/src/host/step-claims.js

@@ -0,0 +1,85 @@
+import { readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+const claimName = /^(wrun_[0-9A-Z]+)-(step_[0-9A-Z]+)\.(created|terminal)$/;
+const runEnds = ["completed", "failed", "cancelled"];
+const stepEnds = ["step_completed", "step_failed"];
+const endFields = ["output", "error", "completedAt"];
+function claimOf(name) {
+    const [, runId, stepId, kind] = claimName.exec(name) ?? [];
+    if (runId === undefined || stepId === undefined)
+        return [];
+    return [
+        { name, runId, stepId, kind: kind === "terminal" ? kind : "created" },
+    ];
+}
+async function recorded(world, page) {
+    const { runId, cursor } = page;
+    const listed = await world.events.list({
+        runId,
+        resolveData: "none",
+        pagination: {
+            limit: 1000,
+            sortOrder: "asc",
+            ...(cursor === null ? {} : { cursor }),
+        },
+    });
+    if (!listed.hasMore || listed.cursor === null)
+        return listed.data;
+    return [
+        ...listed.data,
+        ...(await recorded(world, { runId, cursor: listed.cursor })),
+    ];
+}
+function proven(claim, events) {
+    const own = events
+        .filter((event) => event.correlationId === claim.stepId)
+        .map((event) => event.eventType);
+    if (claim.kind === "created")
+        return own.length > 0;
+    return own.some((type) => stepEnds.includes(type));
+}
+async function orphans(world, held) {
+    const run = await world.runs
+        .get(held.runId, { resolveData: "none" })
+        .catch(() => undefined);
+    if (run === undefined || runEnds.includes(run.status))
+        return [];
+    const events = await recorded(world, { runId: held.runId, cursor: null });
+    return held.claims.filter((claim) => !proven(claim, events));
+}
+function records(value) {
+    return typeof value === "object" && value !== null ? { ...value } : {};
+}
+async function reopened(path) {
+    const text = await readFile(path, "utf8").catch(() => undefined);
+    if (text === undefined)
+        return;
+    const parsed = JSON.parse(text);
+    const step = records(parsed);
+    if (step["status"] !== "completed" && step["status"] !== "failed")
+        return;
+    const kept = Object.entries(step).filter(([field]) => !endFields.includes(field));
+    const staged = `${path}.reopened`;
+    await writeFile(staged, JSON.stringify({ ...Object.fromEntries(kept), status: "running" }, null, 2));
+    await rename(staged, path);
+}
+async function reverted(dataDirectory, claim) {
+    const path = join(dataDirectory, "steps", `${claim.runId}-${claim.stepId}.json`);
+    if (claim.kind === "created")
+        await rm(path, { force: true });
+    if (claim.kind === "terminal")
+        await reopened(path);
+}
+export async function releaseStepClaims(dataDirectory, world) {
+    const folder = join(dataDirectory, ".locks", "steps");
+    const names = await readdir(folder).catch(() => []);
+    const held = Map.groupBy(names.flatMap(claimOf), (claim) => claim.runId);
+    const released = [];
+    for (const [runId, claims] of held)
+        for (const claim of await orphans(world, { runId, claims })) {
+            await reverted(dataDirectory, claim);
+            await rm(join(folder, claim.name), { force: true });
+            released.push(claim.name);
+        }
+    return released;
+}

package/dist/src/host/world-host.d.ts

@@ -0,0 +1,21 @@
+export type WorkflowHandler = (request: Request) => Promise<Response>;
+export interface HostSettings {
+    readonly dataDirectory: string;
+    readonly concurrency: number;
+    readonly handler: WorkflowHandler;
+}
+export interface WorkflowHost {
+    readonly released: readonly string[];
+    readonly close: () => Promise<void>;
+}
+export interface HostRefusal {
+    readonly kind: "refused";
+    readonly reason: string;
+    readonly detail: string;
+}
+export type HostOpening = {
+    readonly kind: "started";
+    readonly host: WorkflowHost;
+} | HostRefusal;
+export declare const hostBoundLimit = 64;
+export declare function startHost(settings: HostSettings): Promise<HostOpening>;

package/dist/src/host/world-host.js

@@ -0,0 +1,51 @@
+import { getWorld } from "workflow/runtime";
+import { releaseStepClaims } from "./step-claims.js";
+const workflowQueue = "__wkf_workflow_";
+export const hostBoundLimit = 64;
+function direct(world) {
+    return ("registerHandler" in world && typeof world.registerHandler === "function");
+}
+function refused(reason, detail) {
+    return { kind: "refused", reason, detail };
+}
+function unsuitable(settings) {
+    const { concurrency, dataDirectory } = settings;
+    const bounded = Number.isSafeInteger(concurrency) &&
+        concurrency >= 1 &&
+        concurrency <= hostBoundLimit;
+    if (!bounded)
+        return refused("invalid-host-bound", String(concurrency));
+    if (process.env["WORKFLOW_TARGET_WORLD"] !== "local")
+        return refused("host-world", "WORKFLOW_TARGET_WORLD is not local");
+    if (process.env["WORKFLOW_LOCAL_DATA_DIR"] !== dataDirectory)
+        return refused("host-world", "WORKFLOW_LOCAL_DATA_DIR is not the setting");
+    if (process.env["WORKFLOW_LOCAL_QUEUE_CONCURRENCY"] !== String(concurrency))
+        return refused("host-bound", "WORKFLOW_LOCAL_QUEUE_CONCURRENCY is not the setting");
+    return undefined;
+}
+export async function startHost(settings) {
+    const refusal = unsuitable(settings);
+    if (refusal)
+        return refusal;
+    const world = await getWorld();
+    if (!direct(world))
+        return refused("host-world", "the World takes no handler in its process");
+    const released = await releaseStepClaims(settings.dataDirectory, world);
+    world.registerHandler(workflowQueue, settings.handler);
+    try {
+        await world.start?.();
+    }
+    catch (error) {
+        await world.close?.();
+        return refused("host-start-failed", String(Reflect.get(Object(error), "message")));
+    }
+    return {
+        kind: "started",
+        host: {
+            released,
+            close: async () => {
+                await world.close?.();
+            },
+        },
+    };
+}

package/dist/src/host/world-reconciliation.d.ts

@@ -0,0 +1,37 @@
+import { type WorldReport, type WorldRun } from "../authority/reconciliation.ts";
+import type { AuthorityState } from "../authority/transitions.ts";
+export type ReconciledState = Pick<AuthorityState, "runs" | "intents" | "details" | "gates" | "commands">;
+export interface WorkflowOutcome {
+    readonly kind: string;
+    readonly reason?: string;
+}
+export interface ReconciliationPorts {
+    readonly state: () => Promise<ReconciledState>;
+    readonly submit: (command: Readonly<Record<string, unknown>>) => Promise<{
+        readonly kind: "accepted" | "duplicate" | "rejected" | "failed";
+    }>;
+    readonly runs: () => Promise<readonly WorldRun[]>;
+    readonly outcome: (receipt: string) => Promise<WorkflowOutcome | undefined>;
+}
+export interface Pass {
+    readonly sent: readonly string[];
+    readonly interrupted: boolean;
+    readonly reports: readonly WorldReport[];
+    readonly conflicts: readonly string[];
+}
+export declare function reconcileWorld(ports: ReconciliationPorts): Promise<Pass>;
+export type LoopReport = WorldReport | {
+    readonly kind: "world-run-conflict";
+    readonly runId: string;
+} | {
+    readonly kind: "world-reconciliation-failed";
+    readonly passes: number;
+};
+export declare const passFailureLimit = 3;
+export interface WorldLoop {
+    readonly stop: () => Promise<void>;
+    readonly reports: () => readonly LoopReport[];
+}
+export declare function worldLoop(parts: ReconciliationPorts & {
+    readonly intervalMilliseconds: number;
+}): WorldLoop;

package/dist/src/host/world-reconciliation.js

@@ -0,0 +1,75 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { reconcile, } from "../authority/reconciliation.js";
+async function withOutcome(ports, observed) {
+    const { state, world } = observed;
+    const ended = world.status === "completed" &&
+        state.runs[world.runId]?.status === "running";
+    if (!ended)
+        return world;
+    const read = await ports.outcome(world.receipt).then((outcome) => ({ outcome }), () => undefined);
+    if (read === undefined)
+        return { ...world, status: "unreadable" };
+    return read.outcome === undefined
+        ? world
+        : {
+            ...world,
+            outcome: read.outcome.kind,
+            ...(read.outcome.reason === undefined
+                ? {}
+                : { outcomeReason: read.outcome.reason }),
+        };
+}
+export async function reconcileWorld(ports) {
+    const listed = await ports.runs();
+    const state = await ports.state();
+    const runs = [];
+    for (const world of listed)
+        runs.push(await withOutcome(ports, { state, world }));
+    const { commands, reports, conflicts } = reconcile(state, runs);
+    const sent = [];
+    for (const command of commands) {
+        const receipt = await ports.submit(command);
+        sent.push(`${String(command["commandId"])} ${receipt.kind}`);
+        if (receipt.kind === "failed")
+            return { sent, interrupted: true, reports, conflicts };
+    }
+    return { sent, interrupted: false, reports, conflicts };
+}
+export const passFailureLimit = 3;
+function reported(pass) {
+    return [
+        ...pass.reports,
+        ...pass.conflicts.map((runId) => ({
+            kind: "world-run-conflict",
+            runId,
+        })),
+    ];
+}
+export function worldLoop(parts) {
+    const stopping = new AbortController();
+    let reports = [];
+    let failures = 0;
+    const cycle = async () => {
+        while (!stopping.signal.aborted) {
+            const pass = await reconcileWorld(parts).catch(() => undefined);
+            reports = pass === undefined ? reports : reported(pass);
+            failures = pass?.interrupted === false ? 0 : failures + 1;
+            await delay(parts.intervalMilliseconds, undefined, {
+                signal: stopping.signal,
+            }).catch(() => undefined);
+        }
+    };
+    const running = cycle();
+    return {
+        stop: async () => {
+            stopping.abort();
+            await running;
+        },
+        reports: () => failures < passFailureLimit
+            ? reports
+            : [
+                ...reports,
+                { kind: "world-reconciliation-failed", passes: failures },
+            ],
+    };
+}

package/dist/src/host/world-runs.d.ts

@@ -0,0 +1,14 @@
+import type { WorldRun } from "../authority/reconciliation.ts";
+import type { WorkflowOutcome } from "./world-reconciliation.ts";
+export declare const runTag = "cloving.run";
+export declare const operationTag = "cloving.operation";
+export interface TaggedRun extends WorldRun {
+    readonly operationId: string | null;
+    readonly createdAt: string;
+}
+export declare function taggedRuns(pageSize?: number): Promise<TaggedRun[]>;
+export declare function workflowOutcome(receipt: string): Promise<WorkflowOutcome | undefined>;
+export declare function cancelled(receipt: string): Promise<string>;
+export declare function taggedRun(receipt: string): Promise<{
+    readonly runId: string;
+} | undefined>;

package/dist/src/host/world-runs.js

@@ -0,0 +1,61 @@
+import { getRun } from "workflow/api";
+import { getWorld } from "workflow/runtime";
+export const runTag = "cloving.run";
+export const operationTag = "cloving.operation";
+function tag(attributes, name) {
+    const value = Reflect.get(Object(attributes), name);
+    return typeof value === "string" ? value : null;
+}
+async function collected(world, page) {
+    const listed = await world.runs.list({
+        resolveData: "none",
+        pagination: {
+            limit: page.limit,
+            ...(page.cursor === null ? {} : { cursor: page.cursor }),
+        },
+    });
+    const found = listed.data.flatMap((item) => {
+        const runId = tag(item.attributes, runTag);
+        if (runId === null)
+            return [];
+        return [
+            {
+                runId,
+                operationId: tag(item.attributes, operationTag),
+                receipt: item.runId,
+                status: item.status,
+                createdAt: item.createdAt.toISOString(),
+            },
+        ];
+    });
+    if (!listed.hasMore || listed.cursor === null)
+        return found;
+    return [
+        ...found,
+        ...(await collected(world, { limit: page.limit, cursor: listed.cursor })),
+    ];
+}
+export async function taggedRuns(pageSize = 200) {
+    return await collected(await getWorld(), { limit: pageSize, cursor: null });
+}
+export async function workflowOutcome(receipt) {
+    const value = await getRun(receipt).returnValue;
+    const kind = Reflect.get(Object(value), "kind");
+    if (typeof kind !== "string")
+        return undefined;
+    const reason = Reflect.get(Object(value), "reason");
+    return { kind, ...(typeof reason === "string" ? { reason } : {}) };
+}
+export async function cancelled(receipt) {
+    const run = getRun(receipt);
+    await run.cancel().catch(() => undefined);
+    return await run.status;
+}
+export async function taggedRun(receipt) {
+    const world = await getWorld();
+    const run = await world.runs
+        .get(receipt, { resolveData: "none" })
+        .catch(() => undefined);
+    const runId = tag(run?.attributes, runTag);
+    return runId === null ? undefined : { runId };
+}

package/dist/src/operation-identity.d.ts

@@ -0,0 +1,7 @@
+import type { Validation } from "./workflow-contracts.ts";
+export declare function operationIdentity(value: unknown): Validation<string>;
+export interface OperationScope {
+    readonly run: string;
+    readonly operation: string;
+}
+export declare function operationScope(operationId: string): OperationScope | null;