@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/service/workflows.js

@@ -0,0 +1,1549 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { Cause, Context, Effect, Exit, Layer, Redacted, Schema } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { decodeProtectedHeader } from "jose";
+import { deploymentFromEnv, requireDeploymentCapability, } from "../deployment.js";
+import { NO_INPUT } from "../analyze.js";
+import { ONTOLOGY_QUEUE_NAMESPACE } from "../workflow-topics.js";
+import { actionInputToWire } from "../authoring-input.js";
+import { nameToWire } from "../authoring-names.js";
+import { connectionContext } from "../connection.js";
+import { Files } from "../files.js";
+import { canonicalJson } from "../manifest.js";
+import { unavailableFiles } from "../storage/file-access.js";
+import { ActionRejected, PermissionDenied, } from "../errors.js";
+import { isActionTrigger, isCronTrigger, isWebhookTrigger, } from "../manifest.js";
+import { webhookTokenMatches } from "../webhook-token.js";
+import { MAX_WEBHOOK_BODY_BYTES, MAX_META_WEBHOOK_BODY_BYTES, MAX_WEBHOOK_VERIFICATION_CHARS, WEBHOOK_BASE_PATH, webhookPath, } from "../webhooks.js";
+import { readWebhookBody, SIGNATURE_SCHEMES, signatureRefusals, utf8Text, } from "./webhooks.js";
+import { clientAddress } from "./rate-limit.js";
+import { isAllowed, workflowPermission } from "../permissions.js";
+import { OntologyActions, OntologyReads, OntologyWrites, } from "../runtime.js";
+import { writesOnlyThroughActions } from "../runtime/generated-actions.js";
+import { validate } from "../runtime/validation.js";
+import { triggerContext, WorkflowStartFailed, } from "../runtime/workflow-starts.js";
+import { RECOVERY_CONFIRM_MS, RECOVERY_COVERAGE_MARGIN_MS, RECOVERY_FIRST_SWEEP_MS, } from "../start-recovery-contract.js";
+import { nextCronTime, } from "../workflow.js";
+import { platformWorkflows, setWorkflowBinding, WORKFLOW_BASE_PATH, workflowSdk, } from "../workflow-runtime.js";
+import { callbackIdentityToken } from "./workflow-callback.js";
+import { expireAgentTask, startAgentTask, } from "./agent/task-start.js";
+import { CurrentPrincipal, WORKLOAD_TOKEN_TYPE, withPrincipal, workloadKind, } from "./authentication.js";
+import { CurrentCaller } from "./caller-context.js";
+import { InvalidActionInput, InvalidRequestBody, RequestId, failureResponse, forbidden, internalError, notFound, toServerResponse, unauthorized, unavailable, } from "./errors.js";
+import { identityToken as requestIdentityToken, makeOperations, } from "./operations.js";
+import { OntologyBackend } from "./runtime-contract.js";
+import { stepFailure, WorkflowStepFailed, workflowErrorView } from "./workflow-errors.js";
+export { WorkflowStepFailed } from "./workflow-errors.js";
+import { runtimeCredential } from "./runtime-identity.js";
+import { deploymentWorkflowEngine } from "./workflow-deployment.js";
+import { decodeWorkflowArguments, encodeWorkflowArguments } from "../runtime/workflow-arguments.js";
+import { WorkflowRecoveryUnavailable } from "../runtime/errors.js";
+import { hasWorkflowError, hydrateWorkflowStepPage, readWorkflowDiagnostics, WORLD_PAGE_SIZE, } from "./workflow-diagnostics.js";
+export { MAX_LISTED_WORKFLOW_EVENTS, WORLD_PAGE_SIZE } from "./workflow-diagnostics.js";
+/**
+ * The world has no such run: the Workflow SDK's `WorkflowRunNotFoundError`, told apart by its name
+ * as its own `is` guard does (this module imports none of the SDK), or a world's bare 404.
+ */
+function isRunNotFound(error) {
+    const candidate = error;
+    return candidate?.name === "WorkflowRunNotFoundError" || candidate?.status === 404;
+}
+/**
+ * No run waits on the hook any longer: the SDK's `HookNotFoundError`, or `RunExpiredError` for a
+ * run that ended, told apart by name as their own `is` guards do.
+ */
+function isHookGone(error) {
+    const name = error?.name;
+    return name === "HookNotFoundError" || name === "RunExpiredError";
+}
+/**
+ * The Workflow SDK's engine over a world: `start` from `workflow/api` on the ontology's queue, and
+ * the world's `runs.list`, `runs.get` and `steps.list`, paged within what the Vercel world accepts.
+ */
+export function worldWorkflowEngine(world, begin = (workflow, args, options) => installedWorkflowSdk().start(workflow, args, options), hydrate = (value, run, kind) => installedWorkflowSdk().hydrateError?.(value, run, kind) ?? Promise.resolve(value), resume = (token, payload) => installedWorkflowSdk().resumeHook(token, payload)) {
+    const engine = {
+        allocateRun: () => {
+            const allocate = installedWorkflowSdk().allocateRun;
+            if (!allocate) {
+                throw new Error("The Workflow runtime cannot reserve durable provider run identities.");
+            }
+            return allocate();
+        },
+        getHookRunId: async (token) => {
+            try {
+                const current = await world();
+                if (!current.hooks) {
+                    throw new Error("WorkflowHookLookupUnavailable");
+                }
+                return (await current.hooks.getByToken(token)).runId;
+            }
+            catch (error) {
+                if (isHookGone(error) || isRunNotFound(error)) {
+                    return undefined;
+                }
+                throw error;
+            }
+        },
+        resumeHook: async (token, payload) => {
+            requireDeploymentCapability(deploymentFromEnv(), "workflows");
+            try {
+                await resume(token, payload);
+                return "resumed";
+            }
+            catch (error) {
+                if (isHookGone(error)) {
+                    return "not_found";
+                }
+                throw error;
+            }
+        },
+        // The ontology's queue, which only the ontology service's flow function consumes.
+        start: async (workflow, args, options) => {
+            requireDeploymentCapability(deploymentFromEnv(), "workflows");
+            return begin(workflow, [...args], { ...options, namespace: ONTOLOGY_QUEUE_NAMESPACE });
+        },
+        listRuns: async ({ workflowName, limit, cursor }) => (await world()).runs.list({
+            workflowName,
+            pagination: {
+                limit: Math.min(limit, WORLD_PAGE_SIZE),
+                ...(cursor === undefined ? {} : { cursor }),
+                sortOrder: "desc",
+            },
+            resolveData: "none",
+        }),
+        getRun: async (runId) => {
+            try {
+                return await (await world()).runs.get(runId, { resolveData: "none" });
+            }
+            catch (error) {
+                if (isRunNotFound(error)) {
+                    return undefined;
+                }
+                throw error;
+            }
+        },
+        listSteps: async (runId, options = {}) => {
+            const current = await world();
+            const page = await current.steps.list({
+                runId,
+                pagination: {
+                    limit: Math.min(Math.max(options.limit ?? WORLD_PAGE_SIZE, 1), WORLD_PAGE_SIZE),
+                    sortOrder: "desc",
+                    ...(options.cursor === undefined ? {} : { cursor: options.cursor }),
+                },
+                resolveData: "none",
+            });
+            return hydrateWorkflowStepPage(current, runId, page, hydrate);
+        },
+        diagnostics: async (run, steps) => readWorkflowDiagnostics(await world(), run, steps, hydrate),
+    };
+    return deploymentWorkflowEngine(engine, deploymentFromEnv);
+}
+/**
+ * The Vercel Workflow SDK as `installWorkflowRuntime()` registered it. The service imports none of
+ * the SDK itself: a process that bundles the service without serving workflows, such as the
+ * platform's backend on another SDK major, carries none of it.
+ */
+export const vercelWorkflowEngine = worldWorkflowEngine(async () => (await installedWorkflowSdk().world()));
+/** A workflow route was served in a process that never called `installWorkflowRuntime()`. */
+export class WorkflowRuntimeNotInstalled extends Error {
+    constructor() {
+        super("The ontology's workflow routes need installWorkflowRuntime() from " +
+            '"@segmentstream/ontology/server", which the starter\'s server/plugin.ts calls ' +
+            "at startup, before they serve a run.");
+        this.name = "WorkflowRuntimeNotInstalled";
+    }
+}
+function installedWorkflowSdk() {
+    const sdk = workflowSdk();
+    if (sdk === undefined) {
+        throw new WorkflowRuntimeNotInstalled();
+    }
+    return sdk;
+}
+/** The Workflow SDK's id of a compiled `"use workflow"` function; `undefined` before compilation. */
+export function compiledWorkflowId(run) {
+    const id = run?.workflowId;
+    return typeof id === "string" && id !== "" ? id : undefined;
+}
+function declaredWorkflows(ontology) {
+    const declarations = ontology.config.workflows ?? [];
+    return ontology.workflows.flatMap((manifest) => {
+        const declaration = declarations.find((candidate) => nameToWire(candidate.name) === manifest.name);
+        return declaration === undefined
+            ? []
+            : [
+                {
+                    manifest,
+                    declaration,
+                    input: declaration.input === undefined ? NO_INPUT : actionInputToWire(declaration.input),
+                },
+            ];
+    });
+}
+/** How long the recovery run's start may take; the arming request waits for it. */
+const RECOVERY_START_TIMEOUT_MS = 15_000;
+/** The platform's recovery workflow, compiled, or why it cannot be started. */
+function recoveryWorkflow() {
+    const run = platformWorkflows()?.recoverStarts;
+    if (run === undefined) {
+        return new WorkflowStartFailed({
+            reason: "no_recovery_workflow",
+            message: "The platform's start recovery workflow is not registered: build the ontology service " +
+                "with ontologyWorkflows() in nitro.config.ts, which compiles and registers it.",
+        });
+    }
+    if (compiledWorkflowId(run) === undefined) {
+        return new WorkflowStartFailed({
+            reason: "not_compiled",
+            message: "The platform's start recovery workflow was not compiled by the Workflow SDK.",
+        });
+    }
+    return run;
+}
+/**
+ * Starts the runs action triggers decide, through the engine on the ontology's queue: the row's
+ * wire input decoded with the workflow's input, and `startedBy` naming the trigger, the action and,
+ * when it was evaluated per edited record, the record. The ontology service hands it to the runtime.
+ *
+ * `ensureRecovery` arms the platform's recovery run, one per process at a time: a run started at
+ * `A` first sweeps at `A + RECOVERY_FIRST_SWEEP_MS` and looks once more RECOVERY_CONFIRM_MS later,
+ * so it covers every request whose transaction deadline falls before that horizon, less a margin.
+ * Requests that arrive while a start is in flight wait for it instead of starting their own.
+ */
+export function workflowStarter(ontology, engine, clock = Date.now) {
+    const workflows = declaredWorkflows(ontology);
+    const capture = (pending) => {
+        if (pending.arguments && pending.workflowId) {
+            return {
+                ...pending,
+                workflowId: pending.workflowId,
+                arguments: decodeWorkflowArguments(encodeWorkflowArguments(pending.arguments)),
+                attributes: pending.attributes ?? {},
+            };
+        }
+        const workflow = workflows.find((candidate) => candidate.manifest.name === pending.workflow);
+        const id = pending.workflowId ?? (workflow && compiledWorkflowId(workflow.declaration.run));
+        if (!workflow || !id) {
+            throw new WorkflowStartFailed({
+                reason: "not_compiled",
+                message: "Workflow input capture requires a compiled declaration.",
+            });
+        }
+        const decoded = validate(workflow.input, pending.input ?? {});
+        if (!decoded.ok) {
+            throw new WorkflowStartFailed({
+                reason: "invalid_input",
+                message: "The workflow admission input is invalid.",
+            });
+        }
+        return {
+            ...pending,
+            workflowId: id,
+            arguments: decodeWorkflowArguments(encodeWorkflowArguments([decoded.value, triggerContext(pending)])),
+            attributes: pending.attributes ?? startAttributes(triggerContext(pending).startedBy),
+        };
+    };
+    // The horizon of the latest armed recovery run, as this process may rely on it.
+    let coveredUntil = 0;
+    let arming;
+    const arm = (submit) => (arming ??= (async () => {
+        const run = recoveryWorkflow();
+        if (run instanceof WorkflowStartFailed) {
+            throw run;
+        }
+        const armedAt = clock();
+        let timer;
+        try {
+            await Promise.race([
+                submit
+                    ? submit({
+                        workflowId: compiledWorkflowId(run),
+                        arguments: [],
+                        attributes: { "startedBy.kind": "platform" },
+                    })
+                    : engine.start(run, [], { attributes: { "startedBy.kind": "platform" } }),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new WorkflowStartFailed({
+                        reason: "timeout",
+                        message: "The Workflow SDK did not accept the recovery run in time.",
+                    })), RECOVERY_START_TIMEOUT_MS);
+                }),
+            ]);
+        }
+        catch (cause) {
+            throw cause instanceof WorkflowStartFailed
+                ? cause
+                : new WorkflowStartFailed({
+                    reason: "engine",
+                    message: "The Workflow SDK did not start the recovery run.",
+                    cause,
+                });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        coveredUntil =
+            armedAt + RECOVERY_FIRST_SWEEP_MS + RECOVERY_CONFIRM_MS - RECOVERY_COVERAGE_MARGIN_MS;
+    })().finally(() => {
+        arming = undefined;
+    }));
+    return {
+        ...(engine.allocateRun ? { allocateRun: engine.allocateRun } : {}),
+        recoveryHorizon: () => coveredUntil,
+        capture,
+        prepare: (pending) => Effect.gen(function* () {
+            if (pending.reservation && pending.arguments && pending.workflowId) {
+                return {
+                    ...pending,
+                    reservation: pending.reservation,
+                    arguments: pending.arguments,
+                    workflowId: pending.workflowId,
+                    attributes: pending.attributes ?? {},
+                };
+            }
+            if (!engine.allocateRun) {
+                return yield* new WorkflowStartFailed({
+                    reason: "engine",
+                    message: "Workflow reservation is unavailable.",
+                });
+            }
+            const captured = yield* Effect.try({
+                try: () => capture(pending),
+                catch: (cause) => cause instanceof WorkflowStartFailed
+                    ? cause
+                    : new WorkflowStartFailed({
+                        reason: "invalid_input",
+                        message: "Workflow input capture failed.",
+                        cause,
+                    }),
+            });
+            const reservation = yield* Effect.tryPromise({
+                try: engine.allocateRun,
+                catch: (cause) => new WorkflowStartFailed({
+                    reason: "engine",
+                    message: "Workflow run identity allocation failed.",
+                    cause,
+                }),
+            });
+            return {
+                ...captured,
+                reservation: {
+                    ...reservation,
+                    ...(pending.deploymentId ? { deploymentId: pending.deploymentId } : {}),
+                },
+            };
+        }),
+        ensureRecovery: ({ commitBy, submit }) => Effect.gen(function* () {
+            // At most twice: the first start may be one in flight for an earlier request; the second
+            // is this request's own, and covers it unless its deadline is beyond one run's horizon.
+            for (let attempt = 0; commitBy >= coveredUntil; attempt += 1) {
+                if (attempt === 2) {
+                    return yield* new WorkflowStartFailed({
+                        reason: "engine",
+                        message: "The action's transaction deadline is beyond what one recovery run covers " +
+                            `(${RECOVERY_FIRST_SWEEP_MS + RECOVERY_CONFIRM_MS - RECOVERY_COVERAGE_MARGIN_MS} ms).`,
+                    });
+                }
+                yield* Effect.tryPromise({
+                    try: () => arm(submit),
+                    catch: (cause) => cause instanceof WorkflowStartFailed
+                        ? cause
+                        : new WorkflowStartFailed({
+                            reason: "engine",
+                            message: "The Workflow SDK did not start the recovery run.",
+                            cause,
+                        }),
+                });
+            }
+        }),
+        start: (start) => Effect.gen(function* () {
+            if (start.reservation && start.arguments && start.workflowId) {
+                const begun = yield* Effect.tryPromise({
+                    try: () => engine.start({ workflowId: start.workflowId }, start.arguments, {
+                        reservation: start.reservation,
+                        attributes: start.attributes ?? {},
+                    }),
+                    catch: (cause) => new WorkflowStartFailed({
+                        reason: "engine",
+                        message: "The reserved workflow submission failed.",
+                        cause,
+                    }),
+                });
+                return begun.runId;
+            }
+            const workflow = workflows.find((candidate) => candidate.manifest.name === start.workflow);
+            if (workflow === undefined) {
+                return yield* new WorkflowStartFailed({
+                    reason: "unknown_workflow",
+                    message: `The serving ontology declares no workflow ${start.workflow}.`,
+                });
+            }
+            if (compiledWorkflowId(workflow.declaration.run) === undefined) {
+                return yield* new WorkflowStartFailed({
+                    reason: "not_compiled",
+                    message: `The run function of ${start.workflow} was not compiled by the Workflow SDK.`,
+                });
+            }
+            const decoded = validate(workflow.input, start.input ?? {});
+            if (!decoded.ok) {
+                return yield* new WorkflowStartFailed({
+                    reason: "invalid_input",
+                    message: `The stored input of ${start.trigger} does not decode: ${decoded.issues
+                        .map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`)
+                        .join("; ")}`,
+                });
+            }
+            const context = triggerContext(start);
+            const started = yield* Effect.tryPromise({
+                try: () => engine.start(workflow.declaration.run, [decoded.value, context], { attributes: startAttributes(context.startedBy) }),
+                catch: (cause) => new WorkflowStartFailed({
+                    reason: "engine",
+                    message: "The Workflow SDK did not start the run.",
+                    cause,
+                }),
+            });
+            return started.runId;
+        }),
+    };
+}
+const json = (body, status = 200) => HttpServerResponse.jsonUnsafe(body, {
+    status,
+    headers: { "cache-control": "private, no-store" },
+});
+function iso(value) {
+    if (value === undefined) {
+        return null;
+    }
+    return value instanceof Date ? value.toISOString() : value;
+}
+/** Workflow SDK 5 attributes are flat strings; `$` keys belong to the SDK. */
+function startAttributes(startedBy) {
+    return Object.fromEntries(Object.entries(startedBy)
+        .filter((entry) => typeof entry[1] === "string")
+        .map(([key, value]) => [`startedBy.${key}`, value]));
+}
+/** Older runs and attributes from other uses carry no ontology start context. */
+function runStartedBy(attributes) {
+    const kind = attributes?.["startedBy.kind"];
+    const userId = attributes?.["startedBy.userId"];
+    if (kind === "member" && userId !== undefined) {
+        return { kind, userId };
+    }
+    if (kind === "platform") {
+        return { kind, userId: userId ?? null };
+    }
+    const trigger = attributes?.["startedBy.trigger"];
+    if (kind === "trigger" && trigger !== undefined) {
+        const actionId = attributes?.["startedBy.actionId"];
+        const recordId = attributes?.["startedBy.recordId"];
+        const triggerKind = attributes?.["startedBy.triggerKind"];
+        return {
+            kind,
+            ...(triggerKind === "cron" || triggerKind === "action" || triggerKind === "webhook"
+                ? { triggerKind }
+                : {}),
+            trigger,
+            ...(actionId === undefined ? {} : { actionId }),
+            ...(recordId === undefined ? {} : { recordId }),
+        };
+    }
+    return undefined;
+}
+function runView(workflow, record) {
+    const startedBy = runStartedBy(record.attributes);
+    return {
+        runId: record.runId,
+        workflow,
+        status: record.status,
+        ...(record.deploymentId === undefined ? {} : { deploymentId: record.deploymentId }),
+        createdAt: iso(record.createdAt),
+        startedAt: iso(record.startedAt),
+        completedAt: iso(record.completedAt),
+        ...(startedBy === undefined ? {} : { startedBy }),
+        error: workflowErrorView(record.error),
+    };
+}
+function stepView(record) {
+    return {
+        stepId: record.stepId,
+        stepName: record.stepName,
+        status: record.status,
+        attempt: record.attempt ?? null,
+        startedAt: iso(record.startedAt),
+        completedAt: iso(record.completedAt),
+        error: workflowErrorView(record.error),
+        ...(record.attempts === undefined
+            ? {}
+            : {
+                attempts: record.attempts.map((attempt) => ({
+                    attempt: attempt.attempt,
+                    status: attempt.status,
+                    startedAt: iso(attempt.startedAt),
+                    completedAt: iso(attempt.completedAt),
+                    error: workflowErrorView(attempt.error),
+                })),
+            }),
+    };
+}
+/** The route Vercel calls for a cron trigger: `/api/ontology/workflows/<workflow>/triggers/<trigger>`. */
+export function triggerPath(workflow, trigger) {
+    return `${WORKFLOW_BASE_PATH}/workflows/${workflow}/triggers/${trigger}`;
+}
+/** The route Vercel calls every five minutes when the manifest declares an action trigger. */
+export const SWEEP_PATH = `${WORKFLOW_BASE_PATH}/workflows/sweep`;
+function workflowView(workflow, now) {
+    return {
+        ...workflow,
+        // Triggers of kinds this SDK does not run are not presented.
+        triggers: workflow.triggers.flatMap((trigger) => isCronTrigger(trigger)
+            ? [
+                {
+                    ...trigger,
+                    path: triggerPath(workflow.name, trigger.name),
+                    nextAt: nextCronTime(trigger.cron, now)?.toISOString() ?? null,
+                },
+            ]
+            : isActionTrigger(trigger)
+                ? [
+                    {
+                        kind: trigger.kind,
+                        name: trigger.name,
+                        description: trigger.description,
+                        entity: trigger.entity,
+                        // `null` for a trigger on any action of the entity.
+                        action: trigger.action ?? null,
+                    },
+                ]
+                : isWebhookTrigger(trigger)
+                    ? [
+                        {
+                            kind: trigger.kind,
+                            name: trigger.name,
+                            description: trigger.description,
+                            // Never the token: whoever reads the declarations does not get the URL.
+                            path: webhookPath(trigger.name),
+                            signature: trigger.signature ?? null,
+                            headers: trigger.headers ?? [],
+                        },
+                    ]
+                    : []),
+    };
+}
+function bearerEquals(header, secret) {
+    if (Redacted.value(secret) === "") {
+        return false;
+    }
+    const expected = Buffer.from(`Bearer ${Redacted.value(secret)}`);
+    const received = Buffer.from(header ?? "");
+    return received.length === expected.length && timingSafeEqual(received, expected);
+}
+function isWorkloadToken(token) {
+    try {
+        return decodeProtectedHeader(token).typ === WORKLOAD_TOKEN_TYPE;
+    }
+    catch {
+        return false;
+    }
+}
+/** Refusals that are typed on the entity handles pass through; the others end the step. */
+function expected(effect, tags) {
+    return effect.pipe(Effect.catchCause((cause) => {
+        const failure = Cause.squash(cause);
+        return typeof failure?._tag === "string" && tags.includes(failure._tag)
+            ? Effect.fail(failure)
+            : Effect.failCause(cause);
+    }));
+}
+/**
+ * The workflow routes and the in-process binding of workflow runs:
+ *
+ * - `GET /api/ontology/workflows/:workflow/triggers/:trigger`, Vercel's cron call, verified with the
+ *   project's cron secret, starts the workflow with the trigger's input;
+ * - `POST /api/ontology/workflows/:workflow/start` starts it for a member holding
+ *   `workflow:<workflow>:start`, or for the platform;
+ * - `GET /api/ontology/workflows`, `…/:workflow/runs` and `…/runs/:runId` read the declarations
+ *   and the SDK's run records for callers holding `workflow:<workflow>:read` and the platform;
+ * - `GET /api/ontology/workflows/:workflow/starts` lists the starts its action triggers decided,
+ *   pending and started, for the same callers;
+ * - `GET` and `POST /api/ontology/workflows/sweep`, verified with the cron secret, start the
+ *   starts that stayed pending.
+ *
+ * Building it installs the binding `run(effect)` uses inside steps; the flow callback, which
+ * `ontologyWorkflows()` mounts outside these routes, runs them.
+ */
+export function workflowsLayer(options) {
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        const engine = options.engine ?? deploymentWorkflowEngine(vercelWorkflowEngine, options.deployment);
+        const { plan } = options;
+        const operations = makeOperations(backend, plan, options.hooks, options.connections, options.replicate, options.chatDelivery);
+        const workflows = declaredWorkflows(plan.ontology);
+        // Either spelling names a workflow: `remindStaleLeads` or its wire name `remind_stale_leads`.
+        const byName = (name) => name === undefined
+            ? undefined
+            : workflows.find((candidate) => candidate.manifest.name === nameToWire(name));
+        const planned = (entity) => {
+            const found = plan.entities.find((candidate) => candidate.name === entity);
+            if (found === undefined) {
+                throw new ActionRejected({ message: `The ontology has no entity ${entity}.` });
+            }
+            return found;
+        };
+        const plannedAction = (entity, action) => {
+            const found = entity.actions.find((candidate) => candidate.name === action);
+            if (found === undefined) {
+                throw new ActionRejected({
+                    message: writesOnlyThroughActions(plan.ontology, entity.name, action) ??
+                        `${entity.name} has no action ${action}.`,
+                });
+            }
+            return found;
+        };
+        // The services the layer was built with, so every step runs as the routes do.
+        const layerServices = yield* Effect.context();
+        for (const workflow of workflows) {
+            if (compiledWorkflowId(workflow.declaration.run) === undefined) {
+                yield* Effect.logError("ontology.workflow.not_compiled").pipe(Effect.annotateLogs({
+                    workflow: workflow.manifest.name,
+                    detail: "Its run function was not compiled by the Workflow SDK: keep the workflow's file " +
+                        "in a directory ontologyWorkflows({ dirs }) compiles.",
+                }));
+            }
+        }
+        /** The workflow each run records, by run id, read from the world once per found run. */
+        const runWorkflows = new Map();
+        const recordedWorkflow = async (runId) => {
+            requireDeploymentCapability(options.deployment, "workflows");
+            const cached = runWorkflows.get(runId);
+            if (cached !== undefined) {
+                return cached;
+            }
+            const run = await engine.getRun(runId);
+            if (run === undefined) {
+                return undefined;
+            }
+            if (runWorkflows.size >= 1_000) {
+                runWorkflows.delete(runWorkflows.keys().next().value);
+            }
+            runWorkflows.set(runId, run.workflowName);
+            return run.workflowName;
+        };
+        /** The declared workflow a step's run runs, after checking the run's own record agrees. */
+        const boundWorkflow = async (step) => {
+            const workflow = workflows.find((candidate) => compiledWorkflowId(candidate.declaration.run) === step.workflowName);
+            if (workflow === undefined) {
+                throw new WorkflowStepFailed("WorkflowNotDeclared", `The run's workflow ${step.workflowName} is not one the serving ontology declares ` +
+                    "in defineOntology({ workflows }).", true);
+            }
+            // The step's queue message names the workflow; the run's own record must agree.
+            const recorded = await recordedWorkflow(step.workflowRunId);
+            if (recorded === undefined) {
+                // The world may not show a fresh run yet: the step is retried.
+                throw new WorkflowStepFailed("WorkflowRunUnknown", `The world has no record of run ${step.workflowRunId} yet.`);
+            }
+            if (recorded !== step.workflowName) {
+                throw new WorkflowStepFailed("WorkflowMismatch", `The step names workflow ${step.workflowName}, which is not its run's.`, true);
+            }
+            return workflow;
+        };
+        /** The platform's recovery workflow's compiled id, when the generated plugin registered it. */
+        const recoveryWorkflowId = () => {
+            const run = platformWorkflows()?.recoverStarts;
+            return run === undefined ? undefined : compiledWorkflowId(run);
+        };
+        setWorkflowBinding({
+            admitWorkflow: (workflowName) => {
+                if (!workflows.some((candidate) => compiledWorkflowId(candidate.declaration.run) === workflowName) &&
+                    workflowName !== recoveryWorkflowId()) {
+                    throw new WorkflowStepFailed("WorkflowNotDeclared", "The deployment declares no such workflow.", true);
+                }
+            },
+            run: async (step, effect) => runStep(await boundWorkflow(step), step, effect),
+            recoverStarts: async (step, input) => {
+                const expected = recoveryWorkflowId();
+                if (expected === undefined || step.workflowName !== expected) {
+                    throw new WorkflowStepFailed("WorkflowNotDeclared", `The run's workflow ${step.workflowName} is not the platform's start recovery workflow.`, true);
+                }
+                const recorded = await recordedWorkflow(step.workflowRunId);
+                if (recorded === undefined) {
+                    throw new WorkflowStepFailed("WorkflowRunUnknown", `The world has no record of run ${step.workflowRunId} yet.`);
+                }
+                if (recorded !== expected) {
+                    throw new WorkflowStepFailed("WorkflowMismatch", `The step names workflow ${step.workflowName}, which is not its run's.`, true);
+                }
+                const requestId = crypto.randomUUID();
+                const result = backend.workflowStarts === undefined
+                    ? { started: 0, failed: 0, abandoned: 0, waiting: 0, at: new Date().toISOString() }
+                    : await Effect.runPromise(backend.workflowStarts.sweep({
+                        retryAbandoned: false,
+                        requestId,
+                        ...(input.before === undefined ? {} : { before: input.before }),
+                    }));
+                console.log(JSON.stringify({
+                    event: "ontology.workflow.recovery_sweep",
+                    requestId,
+                    workflowRunId: step.workflowRunId,
+                    stepId: step.stepId,
+                    attempt: step.attempt,
+                    ...result,
+                }));
+                return result;
+            },
+            startAgentTask: async (step, input) => {
+                const workflow = await boundWorkflow(step);
+                if (options.deployment.target === "preview") {
+                    return { status: "decided", result: { status: "failed", reason: "agent_unavailable" } };
+                }
+                return runAgentTaskStep(workflow, step, true, (identityToken) => backend.agentTasks === undefined
+                    ? Effect.succeed({
+                        status: "decided",
+                        result: { status: "failed", reason: "agent_unavailable" },
+                    })
+                    : startAgentTask({
+                        store: backend.agentTasks,
+                        origin: options.agentOrigin,
+                        identityToken,
+                        runtimeIdentity: options.verifyRuntime !== undefined,
+                        transport: options.agentTransport ?? fetch,
+                        workflow: workflow.manifest.name,
+                        runId: step.workflowRunId,
+                    }, input));
+            },
+            expireAgentTask: async (step, taskId) => {
+                const workflow = await boundWorkflow(step);
+                if (options.deployment.target === "preview") {
+                    return { status: "timed_out" };
+                }
+                return runAgentTaskStep(workflow, step, false, () => backend.agentTasks === undefined
+                    ? Effect.succeed({ status: "timed_out" })
+                    : expireAgentTask(backend.agentTasks, taskId));
+            },
+        });
+        /**
+         * Runs one of `agentTask`'s steps for the run's workflow, with the invocation's Vercel OIDC
+         * token. The start refuses a workflow user that is missing or inactive, as every step does; the
+         * expiry only records the timeout. Failures are logged and thrown as the SDK retries them.
+         */
+        function runAgentTaskStep(workflow, step, requireUser, program) {
+            const requestId = crypto.randomUUID();
+            const identityToken = callbackIdentityToken() ?? process.env.VERCEL_OIDC_TOKEN;
+            const checked = Effect.gen(function* () {
+                if (requireUser) {
+                    const principal = yield* backend.resolveWorkflowUser?.({
+                        workspaceId: options.workspaceId,
+                        workflow: workflow.manifest.name,
+                    }) ?? Effect.succeed(undefined);
+                    if (principal === undefined) {
+                        return yield* new PermissionDenied({
+                            message: `The workflow user of ${workflow.manifest.name} is missing or inactive.`,
+                        });
+                    }
+                }
+                return yield* program(identityToken);
+            }).pipe(Effect.annotateLogs({ requestId }));
+            return Effect.runPromiseExitWith(layerServices)(checked).then((exit) => {
+                if (Exit.isSuccess(exit)) {
+                    return exit.value;
+                }
+                const failure = stepFailure(exit.cause, requestId, step, workflow.manifest.name, [
+                    identityToken,
+                ]);
+                console.error(JSON.stringify({
+                    event: "ontology.workflow.step.failed",
+                    workflow: workflow.manifest.name,
+                    workflowRunId: step.workflowRunId,
+                    stepId: step.stepId,
+                    attempt: step.attempt,
+                    error: workflowErrorView(failure),
+                }));
+                throw failure;
+            });
+        }
+        /** Runs one step's effect as the workflow's user. */
+        function runStep(workflow, step, effect) {
+            const requestId = crypto.randomUUID();
+            // Capture this invocation's identity before Effect resumes from a shared database socket,
+            // whose async context may not carry the callback token. Each invocation reads it anew.
+            const identityToken = callbackIdentityToken() ?? process.env.VERCEL_OIDC_TOKEN;
+            const program = Effect.gen(function* () {
+                const principal = yield* backend.resolveWorkflowUser?.({
+                    workspaceId: options.workspaceId,
+                    workflow: workflow.manifest.name,
+                }) ?? Effect.succeed(undefined);
+                if (principal === undefined) {
+                    return yield* new PermissionDenied({
+                        message: `The workflow user of ${workflow.manifest.name} is missing or inactive.`,
+                    });
+                }
+                const caller = Context.make(CurrentPrincipal, {
+                    ...principal,
+                    authenticatedVia: "workflow",
+                }).pipe(Context.add(CurrentCaller, { kind: "service", subjectId: principal.id }), Context.add(RequestId, requestId));
+                const as = (operation) => operation.pipe(Effect.provideContext(caller));
+                const answer = (entity, action, input, supplied) => Effect.suspend(() => {
+                    const target = planned(entity);
+                    const definition = plannedAction(target, action);
+                    const hasUpload = (value) => value !== null &&
+                        typeof value === "object" &&
+                        ("uploadId" in value ||
+                            "upload_id" in value ||
+                            Object.values(value).some(hasUpload));
+                    const fileAction = (definition.action.files?.length ?? 0) > 0 || hasUpload(input);
+                    const actionOptions = fileAction
+                        ? {
+                            ...supplied,
+                            idempotencyKey: supplied?.idempotencyKey ??
+                                createHash("sha256")
+                                    .update(canonicalJson({
+                                    run: step.workflowRunId,
+                                    step: step.stepId,
+                                    entity,
+                                    action,
+                                    input,
+                                    createIntent: supplied?.createIntent ?? null,
+                                }))
+                                    .digest("hex"),
+                        }
+                        : supplied;
+                    return as(operations.runAction(target, definition, {
+                        input,
+                        validateOnly: false,
+                        identityToken,
+                        ...(actionOptions ? { options: actionOptions } : {}),
+                    }));
+                });
+                const result = (outcome) => Effect.map(outcome, (answered) => answered.result);
+                const reads = OntologyReads.of({
+                    get: ({ entity, id }) => expected(Effect.suspend(() => as(operations.get(planned(entity), id))), ["NotFound"]),
+                    find: ({ entity, options: query }) => expected(Effect.suspend(() => {
+                        // Outside a transaction there is nothing to lock: the lock is dropped.
+                        const rest = { ...query };
+                        delete rest.forUpdate;
+                        return as(operations.find(planned(entity), rest));
+                    }), []).pipe(Effect.map((page) => page.items)),
+                    // A step reads as its user, through the API, where metric queries are the warehouse's.
+                    queryMetrics: () => Effect.die(new Error("Fresh metric queries run in action handlers and prepare; a workflow step runs " +
+                        "an action that queries metrics.")),
+                });
+                const refusedBatch = () => Effect.fail(new ActionRejected({
+                    message: "Batch writes are not available in workflow steps; run an action that writes " +
+                        "the batch.",
+                }));
+                const writes = OntologyWrites.of({
+                    createMany: refusedBatch,
+                    updateMany: refusedBatch,
+                    upsertMany: refusedBatch,
+                    create: ({ entity, values }) => expected(result(answer(entity, "create", values)), [
+                        "Conflict",
+                        "NotFound",
+                        "ScopeViolated",
+                    ]),
+                    update: ({ entity, id, values }) => expected(result(answer(entity, "update", { ...values, id })), [
+                        "Conflict",
+                        "NotFound",
+                        "ScopeViolated",
+                    ]),
+                    upsertBy: ({ entity, property, values }) => expected(result(answer(entity, `upsert_by_${property}`, values)), [
+                        "Conflict",
+                        "NotFound",
+                        "ScopeViolated",
+                    ]),
+                    delete: ({ entity, id }) => expected(Effect.asVoid(answer(entity, "delete", { id })), [
+                        "Conflict",
+                        "NotFound",
+                        "ScopeViolated",
+                    ]),
+                    link: ({ entity, relationship, id, targetId }) => expected(Effect.asVoid(answer(entity, "link", { relationship, id, target: targetId })), ["NotFound", "ScopeViolated"]),
+                    unlink: ({ entity, relationship, id, targetId }) => expected(Effect.asVoid(answer(entity, "unlink", { relationship, id, target: targetId })), ["NotFound", "ScopeViolated"]),
+                    // A step's member writes are the generated `user` actions, with their permissions.
+                    grantUserRoles: ({ id, roles }) => expected(result(answer("user", "grant_roles", { id, roles })), [
+                        "ActionRejected",
+                        "NotFound",
+                    ]),
+                    revokeUserRoles: ({ id, roles }) => expected(result(answer("user", "revoke_roles", roles === "all" ? { id, all: true } : { id, roles })), ["ActionRejected", "NotFound"]),
+                    inviteUser: ({ email, name, roles }) => expected(result(answer("user", "invite", {
+                        email,
+                        ...(name === undefined ? {} : { name }),
+                        ...(roles === undefined ? {} : { roles }),
+                    })), ["ActionRejected", "Conflict"]),
+                    setUserActive: ({ id, active }) => expected(result(answer("user", active ? "reactivate" : "deactivate", { id })), ["NotFound"]),
+                    sendUserSignInLink: () => Effect.fail(new ActionRejected({
+                        message: "Sign-in links are sent from action handlers; a workflow step runs an action " +
+                            "that sends one.",
+                    })),
+                });
+                const actions = OntologyActions.of({
+                    run: ({ entity, action, input, options: actionOptions }) => Effect.gen(function* () {
+                        const target = planned(entity);
+                        const definition = plannedAction(target, action);
+                        // The handle takes the input in TypeScript names; the route takes its wire form.
+                        const wire = yield* Schema.encodeUnknownEffect(definition.action.input)(input).pipe(Effect.mapError((issue) => new ActionRejected({
+                            cause: issue,
+                            message: `The input of ${entity}.${action} does not encode: ${issue.message}`,
+                        })));
+                        return yield* result(answer(entity, action, wire, actionOptions));
+                    }).pipe(Effect.catchIf((error) => error._tag === "InvalidActionInput", (error) => Effect.fail(new ActionRejected({
+                        message: `The input of ${entity}.${action} is invalid: ` +
+                            error.issues
+                                .map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`)
+                                .join("; "),
+                    }))), (operation) => expected(operation, [
+                        "ActionRejected",
+                        "PermissionDenied",
+                        "ScopeViolated",
+                        "Conflict",
+                        "NotFound",
+                        "ConnectionError",
+                    ])),
+                });
+                const services = Context.make(OntologyReads, reads).pipe(Context.add(Files, backend.blobs?.files?.({
+                    principal,
+                    idempotencyKey: createHash("sha256")
+                        .update(`${step.workflowRunId}:${step.stepId}`)
+                        .digest("hex"),
+                }) ?? unavailableFiles), Context.add(OntologyWrites, writes), Context.add(OntologyActions, actions), Context.merge(connectionContext(workflow.declaration.connections, options.connections({
+                    identityToken,
+                    audit: {
+                        action: `workflow.${workflow.manifest.name}`,
+                        principalId: principal.id,
+                        requestId,
+                    },
+                }))));
+                console.info(JSON.stringify({
+                    event: "ontology.workflow.step.started",
+                    workflow: workflow.manifest.name,
+                    workflowRunId: step.workflowRunId,
+                    stepId: step.stepId,
+                    attempt: step.attempt,
+                }));
+                return yield* Effect.provideContext(effect, services);
+            });
+            return Effect.runPromiseExitWith(layerServices)(program).then(async (exit) => {
+                if (Exit.isSuccess(exit)) {
+                    return exit.value;
+                }
+                const failure = stepFailure(exit.cause, requestId, step, workflow.manifest.name, [
+                    identityToken,
+                    options.cronSecret === undefined ? undefined : Redacted.value(options.cronSecret),
+                    options.webhookSecret === undefined ? undefined : Redacted.value(options.webhookSecret),
+                ]);
+                console.error(JSON.stringify({
+                    event: "ontology.workflow.step.failed",
+                    workflow: workflow.manifest.name,
+                    workflowRunId: step.workflowRunId,
+                    stepId: step.stepId,
+                    attempt: step.attempt,
+                    error: workflowErrorView(failure),
+                }));
+                throw failure;
+            });
+        }
+        /**
+         * Starts a run with input in its wire form, as the cron, start and webhook routes receive
+         * it: the run id, or the response that refuses it.
+         */
+        const beginRun = (workflow, input, context) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const refused = (response) => ({ ok: false, response });
+            // A workflow's input is an object of its fields, whatever its schema accepts.
+            const shape = validate(Schema.Record(Schema.String, Schema.Unknown), input ?? {});
+            const decoded = shape.ok ? validate(workflow.input, input ?? {}) : shape;
+            if (!decoded.ok) {
+                return refused(yield* failureResponse(Cause.fail(new InvalidActionInput({ issues: decoded.issues })), requestId));
+            }
+            if (compiledWorkflowId(workflow.declaration.run) === undefined) {
+                return refused(toServerResponse({
+                    status: 503,
+                    body: {
+                        error: "workflow_not_compiled",
+                        detail: "The workflow's run function was not compiled by the Workflow SDK; its file " +
+                            "must be in a directory the build compiles.",
+                        requestId,
+                    },
+                }));
+            }
+            let admitted;
+            if (backend.workflowAdmissions && !engine.allocateRun) {
+                return refused(toServerResponse(unavailable(requestId)));
+            }
+            if (backend.workflowAdmissions) {
+                const argumentsCheck = yield* Effect.try({
+                    try: () => encodeWorkflowArguments([decoded.value, context]),
+                    catch: () => new InvalidActionInput({
+                        issues: [{ path: [], message: "workflow_arguments_unsupported" }],
+                    }),
+                }).pipe(Effect.result);
+                if (argumentsCheck._tag === "Failure") {
+                    return refused(yield* failureResponse(Cause.fail(argumentsCheck.failure), requestId));
+                }
+            }
+            if (backend.workflowAdmissions && engine.allocateRun) {
+                const requestedCommitBy = Date.now() + 5_000;
+                const recovery = yield* backend.workflowAdmissions
+                    .ensureRecovery(requestedCommitBy)
+                    .pipe(Effect.result);
+                if (recovery._tag === "Failure") {
+                    return refused(yield* failureResponse(Cause.fail(recovery.failure), requestId));
+                }
+                const commitBy = Math.min(requestedCommitBy, recovery.success);
+                if (!Number.isFinite(commitBy) || Date.now() >= commitBy) {
+                    return refused(yield* failureResponse(Cause.fail(new WorkflowRecoveryUnavailable({
+                        message: "The workflow recovery coverage expired before reservation could commit.",
+                    })), requestId));
+                }
+                const allocated = yield* Effect.tryPromise(() => engine.allocateRun()).pipe(Effect.result);
+                if (allocated._tag === "Failure") {
+                    return refused(toServerResponse(unavailable(requestId)));
+                }
+                const identity = context.startedBy.kind === "trigger" && context.startedBy.triggerKind === "cron"
+                    ? `${workflow.manifest.name}:${context.startedBy.trigger}:${Math.floor(Date.now() / 60_000)}`
+                    : `${requestId}:${canonicalJson(context.startedBy)}`;
+                const hash = createHash("sha256").update(identity).digest("hex");
+                const actionId = [
+                    hash.slice(0, 8),
+                    hash.slice(8, 12),
+                    hash.slice(12, 16),
+                    hash.slice(16, 20),
+                    hash.slice(20, 32),
+                ].join("-");
+                const admission = yield* backend.workflowAdmissions
+                    .reserve({
+                    trigger: context.startedBy.kind === "trigger"
+                        ? context.startedBy.trigger
+                        : `_manual.${workflow.manifest.name}`,
+                    workflow: workflow.manifest.name,
+                    workflowId: compiledWorkflowId(workflow.declaration.run),
+                    actionId,
+                    recordId: null,
+                    input: input ?? {},
+                    arguments: [decoded.value, context],
+                    reservation: allocated.success,
+                    attributes: startAttributes(context.startedBy),
+                    commitBy,
+                })
+                    .pipe(Effect.result);
+                if (admission._tag === "Failure") {
+                    return refused(yield* failureResponse(Cause.fail(admission.failure), requestId));
+                }
+                admitted = admission.success;
+            }
+            const started = yield* Effect.tryPromise(() => engine.start(admitted
+                ? { workflowId: admitted.workflowId }
+                : workflow.declaration.run, admitted?.arguments ?? [decoded.value, context], {
+                attributes: admitted?.attributes ?? startAttributes(context.startedBy),
+                ...(admitted ? { reservation: admitted.reservation } : {}),
+            })).pipe(Effect.timeoutOrElse({
+                duration: "15 seconds",
+                orElse: () => Effect.fail(new Error("Workflow submission acknowledgement timed out.")),
+            }), Effect.result);
+            if (started._tag === "Failure") {
+                yield* Effect.logError("ontology.workflow.start.failed", started.failure).pipe(Effect.annotateLogs({ requestId, workflow: workflow.manifest.name }));
+                if (admitted) {
+                    // Recovery was durably armed before this journal commit. A failed acknowledgement
+                    // is accepted pending, never both a retriable ingress failure and an independent run.
+                    return { ok: true, runId: admitted.reservation.runId };
+                }
+                return refused(toServerResponse({
+                    status: 503,
+                    body: {
+                        error: "workflow_unavailable",
+                        detail: "The workflow could not be started. Quote the request id when you report it.",
+                        requestId,
+                    },
+                }));
+            }
+            if (admitted) {
+                if (started.success.runId !== admitted.reservation.runId) {
+                    return refused(toServerResponse(unavailable(requestId)));
+                }
+                yield* backend
+                    .workflowAdmissions.submitted(admitted)
+                    .pipe(Effect.catchCause((cause) => Effect.logError("ontology.workflow.submission_journal_ack_failed", cause)));
+            }
+            yield* Effect.logInfo("ontology.workflow.started").pipe(Effect.annotateLogs({
+                requestId,
+                workflow: workflow.manifest.name,
+                runId: started.success.runId,
+                startedBy: context.startedBy,
+            }));
+            return { ok: true, runId: started.success.runId };
+        });
+        /** Starts a run and answers 202 with its id, as the cron and start routes do. */
+        const startRun = (workflow, input, context) => Effect.map(beginRun(workflow, input, context), (begun) => begun.ok
+            ? json({ runId: begun.runId, workflow: workflow.manifest.name }, 202)
+            : begun.response);
+        /** Authenticates a workflow route's caller: the platform's workload token, or a principal. */
+        const authorized = (handle) => (request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const bearer = yield* HttpApiBuilder.securityDecode(HttpApiSecurity.bearer).pipe(Effect.provideService(HttpServerRequest.HttpServerRequest, request));
+            const token = Redacted.value(bearer);
+            if (token !== "" && isWorkloadToken(token)) {
+                const verification = yield* Effect.promise(() => options.verifyToken(token));
+                if (verification.status === "unavailable") {
+                    return toServerResponse(unavailable(requestId));
+                }
+                if (verification.status !== "workload") {
+                    return toServerResponse(unauthorized(requestId, "The token is not valid."));
+                }
+                // Only the platform's subject reaches the workflow routes with a workload token.
+                if (workloadKind({ sub: verification.execution.subject }, verification.execution.workspaceId) !== "platform" ||
+                    (options.deployment.target === "preview" &&
+                        verification.execution.ontologyOrigin !==
+                            new URL(request.source instanceof Request ? request.source.url : request.url, `https://${request.headers.host ?? "ontology.invalid"}`).origin)) {
+                    return toServerResponse(forbidden(requestId, "This workload may not use the workflow routes."));
+                }
+                return yield* handle({ kind: "platform", execution: verification.execution }, request);
+            }
+            const runtime = runtimeCredential(options.verifyRuntime, request);
+            return yield* withPrincipal(bearer, options.verifyToken, backend, Effect.gen(function* () {
+                const principal = yield* CurrentPrincipal;
+                const caller = yield* CurrentCaller;
+                // A pipeline worker never uses the workflow routes.
+                if (caller.kind === "workload") {
+                    return toServerResponse(forbidden(requestId, "This workload may not use the workflow routes."));
+                }
+                return yield* handle({ kind: "principal", principal, caller }, request);
+            }), {
+                session: { request, exchange: options.exchangeSession },
+                ...(runtime === undefined ? {} : { runtime }),
+            });
+        });
+        const mayRead = (caller, workflow) => caller.kind === "platform" ||
+            isAllowed(workflowPermission(workflow, "read"), caller.principal);
+        const unknownWorkflow = (requestId) => toServerResponse(notFound(requestId, "The ontology declares no such workflow."));
+        const readable = (caller, name) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const workflow = byName(name);
+            if (workflow === undefined) {
+                return { ok: false, refused: unknownWorkflow(requestId) };
+            }
+            if (!mayRead(caller, workflow.manifest.name)) {
+                return {
+                    ok: false,
+                    refused: toServerResponse(forbidden(requestId, `Reading this workflow's runs requires ${workflowPermission(workflow.manifest.name, "read")}.`)),
+                };
+            }
+            return { ok: true, workflow };
+        });
+        const recorded = (read) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const outcome = yield* Effect.tryPromise(read).pipe(Effect.result);
+            if (outcome._tag === "Failure") {
+                yield* Effect.logError("ontology.workflow.runs.failed", outcome.failure).pipe(Effect.annotateLogs({ requestId }));
+                return { ok: false, refused: toServerResponse(internalError(requestId)) };
+            }
+            return { ok: true, value: outcome.success };
+        });
+        yield* router.add("GET", `${WORKFLOW_BASE_PATH}/workflows/:workflow/triggers/:trigger`, (request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            if (options.deployment.target === "preview") {
+                return json({ error: "preview_capability_unavailable", capability: "workflows" }, 403);
+            }
+            if (options.cronSecret === undefined ||
+                !bearerEquals(request.headers.authorization, options.cronSecret)) {
+                return toServerResponse(unauthorized(requestId, "The cron secret is required."));
+            }
+            const params = yield* HttpRouter.params;
+            const workflow = byName(params.workflow);
+            const trigger = workflow?.manifest.triggers
+                .filter(isCronTrigger)
+                .find((candidate) => params.trigger !== undefined && candidate.name === nameToWire(params.trigger));
+            if (workflow === undefined || trigger === undefined) {
+                return toServerResponse(notFound(requestId, "The ontology declares no such workflow trigger."));
+            }
+            return yield* startRun(workflow, trigger.input, {
+                startedBy: {
+                    kind: "trigger",
+                    triggerKind: "cron",
+                    trigger: `${workflow.manifest.name}.${trigger.name}`,
+                },
+            });
+        }));
+        // Webhooks, by the wire name that is their URL: one delivery starts one run.
+        const webhooks = new Map();
+        for (const workflow of workflows) {
+            for (const trigger of workflow.manifest.triggers.filter(isWebhookTrigger)) {
+                webhooks.set(trigger.name, { workflow, trigger });
+            }
+        }
+        const refusals = signatureRefusals();
+        const webhook = (request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const params = yield* HttpRouter.params;
+            const began = Date.now();
+            const declared = params.name === undefined ? undefined : webhooks.get(params.name);
+            // Only declared names enter the logs: an arbitrary path segment may be private.
+            const name = declared?.trigger.name;
+            const refuse = (reason, status, headers = {}) => Effect.as(Effect.logWarning("ontology.webhook.refused").pipe(Effect.annotateLogs({
+                requestId,
+                reason,
+                status,
+                ...(name === undefined ? {} : { webhook: name }),
+            })), HttpServerResponse.empty({
+                status,
+                headers: { "cache-control": "no-store", ...headers },
+            }));
+            if (request.method !== "POST" && request.method !== "GET") {
+                return yield* refuse("method", 405, {
+                    allow: declared?.trigger.verification === undefined ? "POST" : "GET, POST",
+                });
+            }
+            if (request.method === "GET" && declared?.trigger.verification === undefined) {
+                return yield* refuse("method", 405, { allow: "POST" });
+            }
+            const secret = options.webhookSecret === undefined ? "" : Redacted.value(options.webhookSecret);
+            if (secret === "") {
+                return yield* refuse("webhook_secret_missing", 404);
+            }
+            if (declared === undefined) {
+                return yield* refuse("unknown_webhook", 404);
+            }
+            const { trigger, workflow } = declared;
+            const signature = trigger.signature;
+            if (signature === undefined) {
+                if (params.token === undefined ||
+                    !webhookTokenMatches(secret, trigger.name, params.token)) {
+                    return yield* refuse("token", 404);
+                }
+            }
+            else if (params.token !== undefined) {
+                return yield* refuse("unexpected_token", 404);
+            }
+            if (request.method === "GET") {
+                const verification = trigger.verification;
+                const verifier = options.webhookTokenVerifier;
+                if (verification?.scheme !== "meta" ||
+                    signature?.scheme !== "meta" ||
+                    verifier === undefined) {
+                    return yield* refuse("verification_unavailable", 503);
+                }
+                const client = `${trigger.name}:${clientAddress(request)}`;
+                const wait = refusals.blocked(client);
+                if (wait !== undefined) {
+                    return yield* refuse("verification_throttled", 429, { "retry-after": String(wait) });
+                }
+                const query = new URL(request.url, "https://ontology.invalid").searchParams;
+                const token = query.get("hub.verify_token");
+                const challenge = query.get("hub.challenge");
+                if (query.getAll("hub.mode").length !== 1 ||
+                    query.get("hub.mode") !== "subscribe" ||
+                    query.getAll("hub.verify_token").length !== 1 ||
+                    token === null ||
+                    token.length === 0 ||
+                    token.length > MAX_WEBHOOK_VERIFICATION_CHARS ||
+                    query.getAll("hub.challenge").length !== 1 ||
+                    challenge === null ||
+                    challenge.length === 0 ||
+                    challenge.length > MAX_WEBHOOK_VERIFICATION_CHARS) {
+                    refusals.refused(client);
+                    return yield* refuse("verification_query", 403);
+                }
+                const verified = yield* Effect.promise(() => verifier({
+                    secret: verification.verifyToken,
+                    token,
+                    identityToken: requestIdentityToken(request),
+                    requestId,
+                }));
+                if (verified.outcome === "unavailable") {
+                    yield* Effect.logError("ontology.webhook.verification_unavailable", verified.cause).pipe(Effect.annotateLogs({ requestId, webhook: trigger.name, status: verified.status }));
+                    return yield* refuse("verification_unavailable", 503);
+                }
+                if (verified.outcome !== "valid") {
+                    refusals.refused(client);
+                    return yield* refuse("verification_token", 403);
+                }
+                return HttpServerResponse.text(challenge, {
+                    status: 200,
+                    headers: { "cache-control": "no-store", "content-type": "text/plain; charset=utf-8" },
+                });
+            }
+            const receivedAt = new Date();
+            const body = yield* readWebhookBody(request, signature?.scheme === "meta" ? MAX_META_WEBHOOK_BODY_BYTES : MAX_WEBHOOK_BODY_BYTES);
+            if (body === "too_large") {
+                return yield* refuse("too_large", 413);
+            }
+            if (body === "unreadable") {
+                return yield* refuse("unreadable", 400);
+            }
+            if (signature !== undefined) {
+                const client = `${trigger.name}:${clientAddress(request)}`;
+                const wait = refusals.blocked(client);
+                if (wait !== undefined) {
+                    return yield* refuse("signature_throttled", 429, { "retry-after": String(wait) });
+                }
+                const scheme = SIGNATURE_SCHEMES[signature.scheme];
+                if (scheme === undefined || options.webhookVerifier === undefined) {
+                    return yield* refuse("scheme_unavailable", 503);
+                }
+                const content = scheme(request.headers, body, receivedAt);
+                if (!content.ok) {
+                    refusals.refused(client);
+                    return yield* refuse(content.reason, 401);
+                }
+                const verifier = options.webhookVerifier;
+                const verified = yield* Effect.promise(() => verifier({
+                    secret: signature.secret,
+                    algorithm: "sha256",
+                    encoding: "hex",
+                    message: content.message,
+                    signatures: content.signatures,
+                    identityToken: requestIdentityToken(request),
+                    requestId,
+                }));
+                if (verified.outcome === "unavailable") {
+                    yield* Effect.logError("ontology.webhook.verification_unavailable", verified.cause).pipe(Effect.annotateLogs({ requestId, webhook: trigger.name, status: verified.status }));
+                    return yield* refuse("verification_unavailable", 503);
+                }
+                if (verified.outcome !== "valid") {
+                    refusals.refused(client);
+                    return yield* refuse(verified.outcome === "secret_missing"
+                        ? "signature_secret_missing"
+                        : "signature_invalid", 401);
+                }
+            }
+            const text = utf8Text(body);
+            if (text === undefined) {
+                return yield* refuse("encoding", 415);
+            }
+            const headers = {};
+            for (const header of trigger.headers ?? []) {
+                const value = request.headers[header];
+                if (typeof value === "string") {
+                    headers[header] = value;
+                }
+            }
+            const begun = yield* beginRun(workflow, {
+                body: text,
+                content_type: request.headers["content-type"] ?? "",
+                query: new URL(request.url, "https://ontology.invalid").search.replace(/^\?/, ""),
+                headers,
+                received_at: receivedAt.toISOString(),
+            }, {
+                startedBy: {
+                    kind: "trigger",
+                    triggerKind: "webhook",
+                    trigger: `${workflow.manifest.name}.${trigger.name}`,
+                },
+            });
+            if (!begun.ok) {
+                return yield* refuse("start_failed", 503);
+            }
+            yield* Effect.logInfo("ontology.webhook.received").pipe(Effect.annotateLogs({
+                requestId,
+                webhook: trigger.name,
+                workflow: workflow.manifest.name,
+                runId: begun.runId,
+                bytes: body.byteLength,
+                durationMs: Date.now() - began,
+            }));
+            return HttpServerResponse.empty({
+                status: 200,
+                headers: { "cache-control": "no-store" },
+            });
+        });
+        yield* router.add("*", `${WEBHOOK_BASE_PATH}/:name`, webhook);
+        yield* router.add("*", `${WEBHOOK_BASE_PATH}/:name/:token`, webhook);
+        // The sweep: Vercel's cron calls it with GET; an operator may POST, with
+        // `?retryAbandoned=true` to retry the starts the automatic sweep gave up on.
+        const sweep = (request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            if (options.deployment.target === "preview") {
+                if (request.method !== "POST") {
+                    return json({ error: "preview_capability_unavailable", capability: "workflows" }, 403);
+                }
+                return yield* authorized((caller) => caller.kind === "platform"
+                    ? performSweep(request)
+                    : Effect.succeed(toServerResponse(forbidden(requestId, "The platform token is required."))))(request);
+            }
+            if (options.cronSecret === undefined ||
+                !bearerEquals(request.headers.authorization, options.cronSecret)) {
+                return toServerResponse(unauthorized(requestId, "The cron secret is required."));
+            }
+            return yield* performSweep(request);
+        });
+        const performSweep = (request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            if (backend.workflowStarts === undefined) {
+                return json({ started: 0, failed: 0, abandoned: 0 });
+            }
+            const query = new URL(request.url, "https://ontology.invalid").searchParams;
+            const { started, failed, abandoned, waiting } = yield* backend.workflowStarts.sweep({
+                retryAbandoned: query.get("retryAbandoned") === "true",
+                requestId,
+            });
+            yield* Effect.logInfo("ontology.workflow.sweep").pipe(Effect.annotateLogs({ requestId, started, failed, abandoned, waiting }));
+            return json({ started, failed, abandoned });
+        });
+        yield* router.add("GET", SWEEP_PATH, sweep);
+        yield* router.add("POST", SWEEP_PATH, sweep);
+        yield* router.add("GET", `${WORKFLOW_BASE_PATH}/workflows/:workflow/starts`, authorized((caller, request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const params = yield* HttpRouter.params;
+            const found = yield* readable(caller, params.workflow);
+            if (!found.ok) {
+                return found.refused;
+            }
+            const query = new URL(request.url, "https://ontology.invalid").searchParams;
+            const pending = query.get("pending");
+            if (pending !== null && pending !== "true" && pending !== "false") {
+                return toServerResponse({
+                    status: 400,
+                    body: {
+                        error: "invalid_request",
+                        detail: "The query parameters are invalid.",
+                        requestId,
+                        issues: [{ path: ["pending"], message: "Expected true or false" }],
+                    },
+                });
+            }
+            const limit = Math.min(Math.max(Number(query.get("limit") ?? 20) || 20, 1), 100);
+            const after = query.get("after") ?? undefined;
+            if (backend.workflowStarts === undefined) {
+                return json({ items: [], nextCursor: null });
+            }
+            const page = yield* backend.workflowStarts
+                .list({
+                workflow: found.workflow.manifest.name,
+                pending: pending === null ? undefined : pending === "true",
+                limit,
+                after,
+            })
+                .pipe(Effect.result);
+            if (page._tag === "Failure") {
+                return toServerResponse({
+                    status: 400,
+                    body: {
+                        error: "invalid_request",
+                        detail: "The query parameters are invalid.",
+                        requestId,
+                        issues: [{ path: ["after"], message: page.failure.message }],
+                    },
+                });
+            }
+            return json(page.success);
+        })));
+        yield* router.add("POST", `${WORKFLOW_BASE_PATH}/workflows/:workflow/start`, authorized((caller, request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const params = yield* HttpRouter.params;
+            const workflow = byName(params.workflow);
+            if (workflow === undefined) {
+                return unknownWorkflow(requestId);
+            }
+            const required = workflowPermission(workflow.manifest.name, "start");
+            if (caller.kind === "principal" &&
+                (caller.caller.kind === "runtime" || !isAllowed(required, caller.principal))) {
+                return toServerResponse(forbidden(requestId, `Starting this workflow requires ${required}.`));
+            }
+            const text = yield* request.text.pipe(Effect.orElseSucceed(() => ""));
+            let body;
+            try {
+                body = text.trim() === "" ? {} : JSON.parse(text);
+            }
+            catch {
+                return yield* failureResponse(Cause.fail(new InvalidRequestBody({ reason: "invalid_json", issues: [] })), requestId);
+            }
+            const fields = typeof body === "object" && body !== null && !Array.isArray(body)
+                ? body
+                : {};
+            const startedBy = caller.kind === "platform"
+                ? {
+                    kind: "platform",
+                    userId: typeof fields.startedBy === "string" ? fields.startedBy : null,
+                }
+                : { kind: "member", userId: caller.principal.id };
+            return yield* startRun(workflow, fields.input, { startedBy });
+        })));
+        yield* router.add("GET", `${WORKFLOW_BASE_PATH}/workflows`, authorized((caller) => Effect.sync(() => {
+            const now = new Date();
+            return json({
+                items: plan.ontology.workflows
+                    .filter((workflow) => mayRead(caller, workflow.name))
+                    .map((workflow) => workflowView(workflow, now)),
+            });
+        })));
+        yield* router.add("GET", `${WORKFLOW_BASE_PATH}/workflows/:workflow/runs`, authorized((caller, request) => Effect.gen(function* () {
+            const params = yield* HttpRouter.params;
+            const found = yield* readable(caller, params.workflow);
+            if (!found.ok) {
+                return found.refused;
+            }
+            const workflowName = compiledWorkflowId(found.workflow.declaration.run);
+            if (workflowName === undefined) {
+                return json({ items: [], nextCursor: null });
+            }
+            const query = new URL(request.url, "https://ontology.invalid").searchParams;
+            const limit = Math.min(Math.max(Number(query.get("limit") ?? 20) || 20, 1), 100);
+            const cursor = query.get("after") ?? undefined;
+            const page = yield* recorded(() => engine.listRuns({ workflowName, limit, ...(cursor ? { cursor } : {}) }));
+            if (!page.ok) {
+                return page.refused;
+            }
+            return json({
+                items: page.value.data.map((record) => runView(found.workflow.manifest.name, record)),
+                nextCursor: page.value.hasMore ? page.value.cursor : null,
+            });
+        })));
+        yield* router.add("GET", `${WORKFLOW_BASE_PATH}/workflows/:workflow/runs/:runId`, authorized((caller, request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const params = yield* HttpRouter.params;
+            const found = yield* readable(caller, params.workflow);
+            if (!found.ok) {
+                return found.refused;
+            }
+            const workflowName = compiledWorkflowId(found.workflow.declaration.run);
+            const runId = params.runId ?? "";
+            const run = yield* recorded(() => engine.getRun(runId));
+            if (!run.ok) {
+                return run.refused;
+            }
+            // A run of another workflow, or of the agent, is not this workflow's.
+            if (run.value === undefined ||
+                workflowName === undefined ||
+                run.value.workflowName !== workflowName) {
+                return toServerResponse(notFound(requestId, "This workflow has no such run."));
+            }
+            // The run is answered without its steps when the world cannot list them.
+            const query = new URL(request.url, "https://ontology.invalid").searchParams;
+            const limit = Math.min(Math.max(Math.trunc(Number(query.get("limit")) || WORLD_PAGE_SIZE), 1), WORLD_PAGE_SIZE);
+            const cursor = query.get("after") ?? undefined;
+            const steps = yield* Effect.tryPromise(() => engine.listSteps(runId, { limit, ...(cursor ? { cursor } : {}) })).pipe(Effect.result);
+            if (steps._tag === "Failure") {
+                yield* Effect.logError("ontology.workflow.steps.failed", steps.failure).pipe(Effect.annotateLogs({ requestId, workflow: found.workflow.manifest.name, runId }));
+            }
+            const diagnostics = engine.diagnostics === undefined
+                ? undefined
+                : yield* Effect.tryPromise(() => engine.diagnostics(run.value, steps._tag === "Success" ? steps.success.data : [])).pipe(Effect.result);
+            const observed = diagnostics?._tag === "Success" ? diagnostics.success : undefined;
+            if (diagnostics?._tag === "Failure") {
+                yield* Effect.logError("ontology.workflow.diagnostics.failed", diagnostics.failure).pipe(Effect.annotateLogs({ requestId, runId }));
+            }
+            return json({
+                ...runView(found.workflow.manifest.name, {
+                    ...run.value,
+                    error: observed?.error ?? run.value.error,
+                }),
+                steps: steps._tag === "Success"
+                    ? steps.success.data.map((step) => {
+                        const attempts = observed?.attempts.get(step.stepId);
+                        const failure = attempts?.at(-1)?.error;
+                        return stepView({
+                            ...step,
+                            error: hasWorkflowError(step.error) ? step.error : (failure ?? step.error),
+                            attempts,
+                        });
+                    })
+                    : null,
+                stepsTruncated: steps._tag === "Success" ? steps.success.hasMore : true,
+                stepsNextCursor: steps._tag === "Success" && steps.success.hasMore ? steps.success.cursor : null,
+                ...(diagnostics === undefined
+                    ? {}
+                    : {
+                        attemptsTruncated: steps._tag === "Failure" || (observed?.truncated ?? true),
+                    }),
+            });
+        })));
+    }));
+}