cloving 0.3.20 → 1.1.0

package/dist/src/effect-authorization.d.ts

@@ -0,0 +1,21 @@
+export interface EffectBudget {
+    readonly limit: number;
+    readonly spent: number;
+}
+export interface EffectRequest {
+    readonly capability: string;
+    readonly units: number;
+}
+export type EffectAuthorization = {
+    readonly kind: "authorized";
+    readonly spent: number;
+} | {
+    readonly kind: "rejected";
+    readonly reason: string;
+};
+export declare function authorizeEffect(manifest: {
+    readonly capabilities: readonly string[];
+}, effect: {
+    readonly budget: EffectBudget;
+    readonly request: EffectRequest;
+}): EffectAuthorization;

package/dist/src/effect-authorization.js

@@ -0,0 +1,14 @@
+export function authorizeEffect(manifest, effect) {
+    const { budget, request } = effect;
+    if (![budget.limit, budget.spent].every((value) => Number.isSafeInteger(value) && value >= 0) ||
+        !Number.isSafeInteger(request.units) ||
+        request.units < 1 ||
+        budget.spent > budget.limit)
+        return { kind: "rejected", reason: "invalid-effect-request" };
+    if (!manifest.capabilities.includes(request.capability))
+        return { kind: "rejected", reason: "unadmitted-capability" };
+    const spent = budget.spent + request.units;
+    if (spent > budget.limit)
+        return { kind: "rejected", reason: "budget-exhausted" };
+    return { kind: "authorized", spent };
+}

package/dist/src/execution-pin.d.ts

@@ -0,0 +1,4 @@
+import type { AdmissionResult, ExecutionManifest } from "./workflow-admission.ts";
+export declare function pinnedIdentity(manifest: ExecutionManifest): string;
+export declare function resumePinned(pinned: ExecutionManifest, available: ExecutionManifest): AdmissionResult;
+export declare function readExecutionManifest(value: unknown): ExecutionManifest;

package/dist/src/execution-pin.js

@@ -0,0 +1,68 @@
+const canonical = {
+    name: (manifest) => JSON.stringify(manifest.name),
+    workflowId: (manifest) => JSON.stringify(manifest.workflowId),
+    steps: (manifest) => JSON.stringify([...manifest.steps].sort()),
+    capabilities: (manifest) => JSON.stringify([...manifest.capabilities].sort()),
+    artifacts: (manifest) => JSON.stringify(Object.keys(manifest.artifacts)
+        .sort()
+        .map((name) => [name, manifest.artifacts[name]])),
+    resources: (manifest) => JSON.stringify(Object.keys(manifest.resources)
+        .sort()
+        .map((name) => [name, manifest.resources[name]])),
+    toolchain: (manifest) => JSON.stringify(["sdk", "world", "builder", "node", "dependencies"].map((key) => manifest.toolchain[key])),
+};
+const fields = [
+    "name",
+    "workflowId",
+    "steps",
+    "capabilities",
+    "artifacts",
+    "resources",
+    "toolchain",
+];
+export function pinnedIdentity(manifest) {
+    return JSON.stringify(fields.map((field) => canonical[field](manifest)));
+}
+export function resumePinned(pinned, available) {
+    const changed = fields.find((field) => canonical[field](pinned) !== canonical[field](available));
+    if (changed !== undefined)
+        return {
+            kind: "rejected",
+            reason: "pinned-manifest-mismatch",
+            detail: changed,
+        };
+    return { kind: "admitted", manifest: pinned };
+}
+export function readExecutionManifest(value) {
+    const fields = record(value);
+    const toolchain = record(fields["toolchain"]);
+    return {
+        name: text(fields["name"]),
+        workflowId: text(fields["workflowId"]),
+        steps: texts(fields["steps"]),
+        capabilities: texts(fields["capabilities"]),
+        artifacts: textRecord(fields["artifacts"]),
+        resources: textRecord(fields["resources"]),
+        toolchain: {
+            sdk: text(toolchain["sdk"]),
+            world: text(toolchain["world"]),
+            builder: text(toolchain["builder"]),
+            node: text(toolchain["node"]),
+            dependencies: text(toolchain["dependencies"]),
+        },
+    };
+}
+function record(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return {};
+    return Object.fromEntries(Object.entries(value));
+}
+function text(value) {
+    return typeof value === "string" ? value : "";
+}
+function texts(value) {
+    return Array.isArray(value) ? value.map(text) : [];
+}
+function textRecord(value) {
+    return Object.fromEntries(Object.entries(record(value)).map(([key, item]) => [key, text(item)]));
+}

package/dist/src/host/start-delivery.d.ts

@@ -0,0 +1,41 @@
+import { type TaggedRun } from "./world-runs.ts";
+export type WorkflowFunction = (input: unknown, continuation?: Continuation) => Promise<unknown>;
+export interface Continuation {
+    readonly gateId: string;
+    readonly decision: string;
+    readonly answer: string | null;
+}
+export interface RunIntent extends Partial<Continuation> {
+    readonly kind: string;
+    readonly runId: string;
+    readonly operationId: string;
+}
+export type RunOutcome = {
+    readonly kind: "accepted";
+    readonly receipt: string;
+} | {
+    readonly kind: "stopped";
+    readonly receipt: string;
+} | {
+    readonly kind: "absent";
+} | {
+    readonly kind: "unknown";
+    readonly evidence: string;
+};
+type OperationRun = Pick<TaggedRun, "receipt" | "operationId" | "status">;
+export interface StartParts {
+    readonly runs: () => Promise<readonly OperationRun[]>;
+    readonly input: (runId: string) => Promise<string | undefined>;
+    readonly document: (digest: string) => Promise<string | undefined>;
+    readonly workflow: (runId: string) => Promise<WorkflowFunction | undefined>;
+    readonly cancel: (receipt: string) => Promise<string>;
+}
+export interface StartDelivery {
+    readonly reconcile: (intent: RunIntent) => Promise<RunOutcome>;
+    readonly deliver: (intent: RunIntent) => Promise<{
+        readonly receipt: string;
+    }>;
+    readonly stop: (intent: RunIntent) => Promise<RunOutcome>;
+}
+export declare function startDelivery(parts: StartParts): StartDelivery;
+export {};

package/dist/src/host/start-delivery.js

@@ -0,0 +1,68 @@
+import { start } from "workflow/api";
+import { operationTag, runTag } from "./world-runs.js";
+const ends = ["cancelled", "completed", "failed"];
+async function segments(parts, intent) {
+    return (await parts.runs()).filter((run) => run.operationId === intent.operationId);
+}
+async function reconciled(parts, intent) {
+    const found = await segments(parts, intent);
+    const [first, ...others] = found;
+    if (first === undefined)
+        return { kind: "absent" };
+    if (others.length === 0)
+        return { kind: "accepted", receipt: first.receipt };
+    return {
+        kind: "unknown",
+        evidence: found.map((run) => `world-run:${run.receipt}`).join(" "),
+    };
+}
+async function continuation(parts, intent) {
+    const { kind, gateId, decision, answer } = intent;
+    if (kind === "start-run")
+        return undefined;
+    if (kind !== "continue-run" || gateId === undefined || decision === undefined)
+        throw new Error(`unsupported-intent: ${kind}`);
+    if (answer === undefined || answer === null)
+        return { gateId, decision, answer: null };
+    const text = await parts.document(answer);
+    if (text === undefined)
+        throw new Error(`answer-not-available: ${gateId}`);
+    return { gateId, decision, answer: text };
+}
+async function delivered(parts, intent) {
+    const continued = await continuation(parts, intent);
+    const workflow = await parts.workflow(intent.runId);
+    const input = await parts.input(intent.runId);
+    if (workflow === undefined || input === undefined)
+        throw new Error(`start-not-available: ${intent.runId}`);
+    const argument = JSON.parse(input);
+    const started = await start(workflow, [argument, continued], {
+        attributes: {
+            [runTag]: intent.runId,
+            [operationTag]: intent.operationId,
+        },
+    });
+    return { receipt: started.runId };
+}
+async function stopped(parts, intent) {
+    const found = await segments(parts, intent);
+    const [first] = found;
+    if (first === undefined)
+        return { kind: "absent" };
+    const alive = [];
+    for (const run of found.filter((run) => !ends.includes(run.status))) {
+        const status = await parts.cancel(run.receipt);
+        if (!ends.includes(status))
+            alive.push(`world-run:${run.receipt} ${status}`);
+    }
+    if (alive.length > 0)
+        return { kind: "unknown", evidence: alive.join(" ") };
+    return { kind: "stopped", receipt: first.receipt };
+}
+export function startDelivery(parts) {
+    return {
+        reconcile: (intent) => reconciled(parts, intent),
+        deliver: (intent) => delivered(parts, intent),
+        stop: (intent) => stopped(parts, intent),
+    };
+}

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>;