@voyantjs/workflow-runs 0.21.0

package/README.md

@@ -0,0 +1,44 @@
+# @voyantjs/workflow-runs
+
+Workflow run recording, admin routes, and rerun/resume dispatch primitives for Voyant operator apps.
+
+## Install
+
+```sh
+pnpm add @voyantjs/workflow-runs
+```
+
+The package is published with the same release-train version as the other installable Voyant packages.
+
+## Mount the admin routes
+
+`mountWorkflowRunsAdminRoutes` adds the workflow-run list, detail, rerun, and resume endpoints under `/v1/admin/workflow-runs`.
+
+```ts
+import { mountWorkflowRunsAdminRoutes, WorkflowRunnerRegistry } from "@voyantjs/workflow-runs"
+
+const workflowRunnerRegistry = new WorkflowRunnerRegistry()
+
+workflowRunnerRegistry.register({
+  name: "checkout-finalize",
+  rerun: async ({ run, input }) => {
+    await workflowServer.dispatch("checkout-finalize", {
+      idempotencyKey: run.idempotencyKey ?? run.id,
+      input,
+    })
+  },
+  resume: async ({ run, input, failedStep }) => {
+    await workflowServer.dispatch("checkout-finalize", {
+      resumeFromStep: failedStep?.stepName ?? null,
+      originalRunId: run.id,
+      input,
+    })
+  },
+})
+
+mountWorkflowRunsAdminRoutes(hono, {
+  runners: workflowRunnerRegistry,
+})
+```
+
+For self-hosted workflow services, keep runner registration close to the code that mounts the workflow service. The registry should dispatch to your external workflow server instead of importing worker-only runtime code into the admin API process.

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@voyantjs/workflow-runs` — passive observability for in-process
+ * workflows.
+ *
+ * The package gives templates two things:
+ *
+ *   1. A `recordWorkflowRun` / recorder API that writes lifecycle
+ *      rows into `workflow_runs` + `workflow_run_steps` as a
+ *      workflow runs. Edge-compatible — postgres-js or neon-http.
+ *   2. A read-only Hono router (`createWorkflowRunsAdminRoutes`)
+ *      that serves `/v1/admin/workflow-runs[/:id]` for the standalone
+ *      dashboard SPA in `apps/workflow-runs-dashboard/` to consume.
+ *
+ * Distinct from the durable `@voyantjs/workflows` SDK — that one is
+ * the Cloud-orchestrated runtime; this one is the lightweight
+ * "what just happened?" log every template can ship without a
+ * separate worker process.
+ */
+export { type BeginWorkflowRunInput, beginWorkflowRun, type WorkflowRunRecorder, } from "./recorder.js";
+export { mountWorkflowRunsAdminRoutes } from "./routes.js";
+export { type WorkflowIdempotency, type WorkflowRerunContext, type WorkflowResumeContext, type WorkflowRunner, WorkflowRunnerRegistry, } from "./runner.js";
+export { type NewWorkflowRun, type NewWorkflowRunStep, type WorkflowRun, type WorkflowRunErrorPayload, type WorkflowRunStep, workflowRunStatusEnum, workflowRunStepStatusEnum, workflowRunSteps, workflowRuns, } from "./schema.js";
+export { type ListWorkflowRunsQuery, type ListWorkflowRunsResult, workflowRunsService, } from "./service.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,KAAK,qBAAqB,EAC1B,gBAAgB,EAChB,KAAK,mBAAmB,GACzB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAA;AAC1D,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,sBAAsB,GACvB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,gBAAgB,EAChB,YAAY,GACb,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,mBAAmB,GACpB,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * `@voyantjs/workflow-runs` — passive observability for in-process
+ * workflows.
+ *
+ * The package gives templates two things:
+ *
+ *   1. A `recordWorkflowRun` / recorder API that writes lifecycle
+ *      rows into `workflow_runs` + `workflow_run_steps` as a
+ *      workflow runs. Edge-compatible — postgres-js or neon-http.
+ *   2. A read-only Hono router (`createWorkflowRunsAdminRoutes`)
+ *      that serves `/v1/admin/workflow-runs[/:id]` for the standalone
+ *      dashboard SPA in `apps/workflow-runs-dashboard/` to consume.
+ *
+ * Distinct from the durable `@voyantjs/workflows` SDK — that one is
+ * the Cloud-orchestrated runtime; this one is the lightweight
+ * "what just happened?" log every template can ship without a
+ * separate worker process.
+ */
+export { beginWorkflowRun, } from "./recorder.js";
+export { mountWorkflowRunsAdminRoutes } from "./routes.js";
+export { WorkflowRunnerRegistry, } from "./runner.js";
+export { workflowRunStatusEnum, workflowRunStepStatusEnum, workflowRunSteps, workflowRuns, } from "./schema.js";
+export { workflowRunsService, } from "./service.js";

package/dist/recorder.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Recorder API — wraps an in-process workflow run with start / step
+ * lifecycle / finish writes against the `workflow_runs` +
+ * `workflow_run_steps` tables.
+ *
+ * Designed for the `@voyantjs/core/workflows` saga primitive:
+ * callers do
+ *
+ *   const recorder = await beginWorkflowRun(db, { workflowName, ... })
+ *   try {
+ *     const result = await runFn(recorder)
+ *     await recorder.complete(result)
+ *   } catch (err) {
+ *     await recorder.fail(err)
+ *     throw err
+ *   }
+ *
+ * — and inside `runFn` the caller (or, more naturally, an
+ * instrumented version of `runCheckoutFinalize`) calls
+ * `recorder.startStep(name)` / `recorder.completeStep(name, output)` /
+ * `recorder.failStep(name, error)` per step.
+ *
+ * The recorder is fire-and-forget around the actual run — it logs
+ * persistence failures rather than rethrowing, so observability
+ * outages never break the underlying business operation.
+ */
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+export interface BeginWorkflowRunInput {
+    workflowName: string;
+    trigger?: string;
+    correlationId?: string | null;
+    tags?: ReadonlyArray<string>;
+    input?: Record<string, unknown> | null;
+    /** Set when this run is a rerun/resume of a prior run. */
+    parentRunId?: string | null;
+    /** User who triggered this run via the dashboard. */
+    triggeredByUserId?: string | null;
+    /**
+     * For resume runs — the step name from which to resume. The
+     * executor seeds ctx.results with prior step outputs and skips
+     * everything before this step.
+     */
+    resumeFromStep?: string | null;
+}
+export interface WorkflowRunRecorder {
+    readonly runId: string;
+    startStep(name: string): Promise<{
+        stepId: string | null;
+    }>;
+    completeStep(name: string, output?: Record<string, unknown> | null): Promise<void>;
+    failStep(name: string, error: unknown): Promise<void>;
+    /**
+     * Record a step that was skipped by a resume run. Writes a row
+     * with `status: "skipped"` and the supplied output (the value the
+     * parent run produced). Used by the resume orchestrator so the UI
+     * shows the full step list with the source of each output.
+     */
+    recordSkippedStep(name: string, output?: Record<string, unknown> | null): Promise<void>;
+    complete(result?: Record<string, unknown> | null): Promise<void>;
+    fail(error: unknown, opts?: {
+        stepName?: string;
+    }): Promise<void>;
+    cancel(reason?: string): Promise<void>;
+}
+/**
+ * Start a run and return a recorder bound to its id. The row is
+ * inserted with `status: "running"` and a `startedAt` of "now".
+ *
+ * Persistence errors are caught — if the table doesn't exist or the
+ * DB is unreachable, returns a no-op recorder so the caller's
+ * workflow keeps running. The whole point of this layer is
+ * observability, not durability.
+ */
+export declare function beginWorkflowRun(db: PostgresJsDatabase, input: BeginWorkflowRunInput): Promise<WorkflowRunRecorder>;
+//# sourceMappingURL=recorder.d.ts.map

package/dist/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAUjE,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACtC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAA;IAC3D,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD;;;;;OAKG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjE,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACvC;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CAwH9B"}

package/dist/recorder.js

@@ -0,0 +1,217 @@
+/**
+ * Recorder API — wraps an in-process workflow run with start / step
+ * lifecycle / finish writes against the `workflow_runs` +
+ * `workflow_run_steps` tables.
+ *
+ * Designed for the `@voyantjs/core/workflows` saga primitive:
+ * callers do
+ *
+ *   const recorder = await beginWorkflowRun(db, { workflowName, ... })
+ *   try {
+ *     const result = await runFn(recorder)
+ *     await recorder.complete(result)
+ *   } catch (err) {
+ *     await recorder.fail(err)
+ *     throw err
+ *   }
+ *
+ * — and inside `runFn` the caller (or, more naturally, an
+ * instrumented version of `runCheckoutFinalize`) calls
+ * `recorder.startStep(name)` / `recorder.completeStep(name, output)` /
+ * `recorder.failStep(name, error)` per step.
+ *
+ * The recorder is fire-and-forget around the actual run — it logs
+ * persistence failures rather than rethrowing, so observability
+ * outages never break the underlying business operation.
+ */
+import { eq } from "drizzle-orm";
+import { workflowRunSteps, workflowRuns, } from "./schema.js";
+/**
+ * Start a run and return a recorder bound to its id. The row is
+ * inserted with `status: "running"` and a `startedAt` of "now".
+ *
+ * Persistence errors are caught — if the table doesn't exist or the
+ * DB is unreachable, returns a no-op recorder so the caller's
+ * workflow keeps running. The whole point of this layer is
+ * observability, not durability.
+ */
+export async function beginWorkflowRun(db, input) {
+    const insert = {
+        workflowName: input.workflowName,
+        trigger: input.trigger ?? "manual",
+        correlationId: input.correlationId ?? null,
+        tags: [...(input.tags ?? [])],
+        input: input.input ?? null,
+        status: "running",
+        parentRunId: input.parentRunId ?? null,
+        triggeredByUserId: input.triggeredByUserId ?? null,
+        resumeFromStep: input.resumeFromStep ?? null,
+    };
+    let runId = null;
+    try {
+        const [row] = await db.insert(workflowRuns).values(insert).returning({ id: workflowRuns.id });
+        runId = row?.id ?? null;
+    }
+    catch (err) {
+        console.warn(`[workflow-runs] could not record run start for "${input.workflowName}":`, err instanceof Error ? err.message : err);
+    }
+    if (!runId)
+        return noopRecorder();
+    const stepStarts = new Map();
+    let nextSequence = 1;
+    return {
+        runId,
+        async startStep(name) {
+            const sequence = nextSequence++;
+            const insertStep = {
+                runId,
+                stepName: name,
+                sequence,
+                status: "running",
+            };
+            try {
+                const [row] = await db
+                    .insert(workflowRunSteps)
+                    .values(insertStep)
+                    .returning({ id: workflowRunSteps.id });
+                if (row?.id) {
+                    stepStarts.set(name, { stepId: row.id, sequence, startedAt: Date.now() });
+                    return { stepId: row.id };
+                }
+            }
+            catch (err) {
+                console.warn(`[workflow-runs] step start "${name}" insert failed:`, err);
+            }
+            return { stepId: null };
+        },
+        async completeStep(name, output) {
+            const tracking = stepStarts.get(name);
+            if (!tracking)
+                return;
+            const completedAt = new Date();
+            try {
+                await db
+                    .update(workflowRunSteps)
+                    .set({
+                    status: "succeeded",
+                    output: output ?? null,
+                    completedAt,
+                    durationMs: completedAt.getTime() - tracking.startedAt,
+                })
+                    .where(eq(workflowRunSteps.id, tracking.stepId));
+            }
+            catch (err) {
+                console.warn(`[workflow-runs] step complete "${name}" update failed:`, err);
+            }
+        },
+        async failStep(name, error) {
+            const tracking = stepStarts.get(name);
+            if (!tracking)
+                return;
+            const completedAt = new Date();
+            try {
+                await db
+                    .update(workflowRunSteps)
+                    .set({
+                    status: "failed",
+                    error: serializeError(error, name),
+                    completedAt,
+                    durationMs: completedAt.getTime() - tracking.startedAt,
+                })
+                    .where(eq(workflowRunSteps.id, tracking.stepId));
+            }
+            catch (err) {
+                console.warn(`[workflow-runs] step fail "${name}" update failed:`, err);
+            }
+        },
+        async recordSkippedStep(name, output) {
+            const sequence = nextSequence++;
+            const now = new Date();
+            const insertStep = {
+                runId,
+                stepName: name,
+                sequence,
+                status: "skipped",
+                output: output ?? null,
+                startedAt: now,
+                completedAt: now,
+                durationMs: 0,
+            };
+            try {
+                await db.insert(workflowRunSteps).values(insertStep);
+            }
+            catch (err) {
+                console.warn(`[workflow-runs] step skipped "${name}" insert failed:`, err);
+            }
+        },
+        complete: (result) => finalize(db, runId, "succeeded", result, null),
+        fail: (error, opts) => finalize(db, runId, "failed", null, serializeError(error, opts?.stepName)),
+        cancel: (reason) => finalize(db, runId, "cancelled", null, {
+            message: reason ?? "Cancelled",
+        }),
+    };
+}
+async function finalize(db, runId, status, result, error) {
+    const completedAt = new Date();
+    try {
+        const [existing] = await db
+            .select({ startedAt: workflowRuns.startedAt })
+            .from(workflowRuns)
+            .where(eq(workflowRuns.id, runId))
+            .limit(1);
+        const durationMs = existing ? completedAt.getTime() - existing.startedAt.getTime() : null;
+        await db
+            .update(workflowRuns)
+            .set({
+            status,
+            result: result ?? null,
+            error: error ?? null,
+            completedAt,
+            durationMs,
+            updatedAt: completedAt,
+        })
+            .where(eq(workflowRuns.id, runId));
+    }
+    catch (err) {
+        console.warn(`[workflow-runs] finalize ${status} failed for ${runId}:`, err);
+    }
+}
+function serializeError(error, stepName) {
+    if (error instanceof Error) {
+        return {
+            message: error.message,
+            ...(stepName ? { stepName } : {}),
+            ...(error.stack ? { stack: error.stack } : {}),
+        };
+    }
+    return {
+        message: typeof error === "string" ? error : JSON.stringify(error),
+        ...(stepName ? { stepName } : {}),
+    };
+}
+function noopRecorder() {
+    return {
+        runId: "",
+        async startStep() {
+            return { stepId: null };
+        },
+        async completeStep() {
+            // no-op
+        },
+        async failStep() {
+            // no-op
+        },
+        async recordSkippedStep() {
+            // no-op
+        },
+        async complete() {
+            // no-op
+        },
+        async fail() {
+            // no-op
+        },
+        async cancel() {
+            // no-op
+        },
+    };
+}

package/dist/routes.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Hono routes for the workflow-runs admin surface.
+ *
+ *   GET  /v1/admin/workflow-runs          → list (filter by workflow / status / tag)
+ *   GET  /v1/admin/workflow-runs/:id      → run + ordered steps
+ *   POST /v1/admin/workflow-runs/:id/rerun  → fresh run with the recorded input
+ *   POST /v1/admin/workflow-runs/:id/resume → re-run starting at the failed step
+ *
+ * Templates mount via `mountWorkflowRunsAdminRoutes(hono, opts)` —
+ * the routes are attached directly to the supplied Hono instance so
+ * they inherit the parent's middleware (auth + db). The optional
+ * `runners` registry is consulted for rerun/resume; if it's not
+ * provided (or doesn't have a runner for the workflow), those
+ * endpoints return 501 with a clear error.
+ */
+import type { Hono } from "hono";
+import type { WorkflowRunnerRegistry } from "./runner.js";
+export interface MountWorkflowRunsAdminRoutesOptions {
+    /**
+     * Registry of executable runners keyed by workflow name. Required
+     * for the rerun/resume endpoints; bundles register their runners
+     * on bootstrap.
+     */
+    runners?: WorkflowRunnerRegistry;
+    /**
+     * Resolves the acting user id from the request context — used to
+     * stamp `triggered_by_user_id` on rerun runs. When omitted, runs
+     * are recorded without an actor.
+     */
+    resolveUserId?: (c: unknown) => string | null;
+}
+export declare function mountWorkflowRunsAdminRoutes(hono: Hono, opts?: MountWorkflowRunsAdminRoutesOptions): void;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAGhC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAiBzD,MAAM,WAAW,mCAAmC;IAClD;;;;OAIG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAA;IAChC;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,CAAA;CAC9C;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,mCAAwC,GAC7C,IAAI,CA0NN"}

package/dist/routes.js

@@ -0,0 +1,205 @@
+/**
+ * Hono routes for the workflow-runs admin surface.
+ *
+ *   GET  /v1/admin/workflow-runs          → list (filter by workflow / status / tag)
+ *   GET  /v1/admin/workflow-runs/:id      → run + ordered steps
+ *   POST /v1/admin/workflow-runs/:id/rerun  → fresh run with the recorded input
+ *   POST /v1/admin/workflow-runs/:id/resume → re-run starting at the failed step
+ *
+ * Templates mount via `mountWorkflowRunsAdminRoutes(hono, opts)` —
+ * the routes are attached directly to the supplied Hono instance so
+ * they inherit the parent's middleware (auth + db). The optional
+ * `runners` registry is consulted for rerun/resume; if it's not
+ * provided (or doesn't have a runner for the workflow), those
+ * endpoints return 501 with a clear error.
+ */
+import { z } from "zod";
+import { workflowRunsService } from "./service.js";
+const listQuerySchema = z.object({
+    workflowName: z.string().min(1).optional(),
+    status: z.enum(["running", "succeeded", "failed", "cancelled"]).optional(),
+    tag: z.string().min(1).optional(),
+    parentRunId: z.string().min(1).optional(),
+    limit: z.coerce.number().int().min(1).max(200).optional(),
+    offset: z.coerce.number().int().min(0).optional(),
+});
+const rerunBodySchema = z.object({
+    /** Required when runner.idempotency === "unsafe". */
+    confirm: z.boolean().optional(),
+});
+export function mountWorkflowRunsAdminRoutes(hono, opts = {}) {
+    hono.get("/v1/admin/workflow-runs", async (c) => {
+        const params = Object.fromEntries(new URL(c.req.url).searchParams);
+        const parsed = listQuerySchema.safeParse(params);
+        if (!parsed.success) {
+            return c.json({ error: "invalid_query", detail: parsed.error.issues }, 400);
+        }
+        // biome-ignore lint/suspicious/noExplicitAny: Hono's c.var.db is loosely typed
+        const db = c.var.db;
+        if (!db) {
+            console.error("[workflow-runs] c.var.db is undefined — middleware ordering issue?");
+            return c.json({ error: "db_unavailable" }, 500);
+        }
+        try {
+            const result = await workflowRunsService.listRuns(db, parsed.data);
+            return c.json(result);
+        }
+        catch (err) {
+            console.error("[workflow-runs] listRuns failed", err);
+            return c.json({
+                error: "list_failed",
+                detail: err instanceof Error ? err.message : String(err),
+            }, 500);
+        }
+    });
+    hono.get("/v1/admin/workflow-runs/:id", async (c) => {
+        // biome-ignore lint/suspicious/noExplicitAny: Hono's c.var.db is loosely typed
+        const db = c.var.db;
+        if (!db)
+            return c.json({ error: "db_unavailable" }, 500);
+        try {
+            const result = await workflowRunsService.getRunById(db, c.req.param("id"));
+            if (!result)
+                return c.json({ error: "not_found" }, 404);
+            return c.json({ data: result });
+        }
+        catch (err) {
+            console.error("[workflow-runs] getRunById failed", err);
+            return c.json({
+                error: "get_failed",
+                detail: err instanceof Error ? err.message : String(err),
+            }, 500);
+        }
+    });
+    hono.post("/v1/admin/workflow-runs/:id/rerun", async (c) => {
+        // biome-ignore lint/suspicious/noExplicitAny: Hono's c.var.db is loosely typed
+        const db = c.var.db;
+        if (!db)
+            return c.json({ error: "db_unavailable" }, 500);
+        if (!opts.runners) {
+            return c.json({ error: "rerun_not_configured", detail: "no WorkflowRunnerRegistry mounted" }, 501);
+        }
+        const parentId = c.req.param("id");
+        const detail = await workflowRunsService.getRunById(db, parentId);
+        if (!detail)
+            return c.json({ error: "not_found" }, 404);
+        const runner = opts.runners.get(detail.run.workflowName);
+        if (!runner) {
+            return c.json({
+                error: "runner_not_registered",
+                detail: `No runner registered for workflow "${detail.run.workflowName}"`,
+            }, 501);
+        }
+        if (runner.idempotency === "resume-only") {
+            return c.json({
+                error: "rerun_not_allowed",
+                detail: `Workflow "${runner.name}" is resume-only; use POST /:id/resume instead.`,
+            }, 409);
+        }
+        let body = {};
+        try {
+            body = rerunBodySchema.parse(await c.req.json().catch(() => ({})));
+        }
+        catch (err) {
+            return c.json({ error: "invalid_body", detail: err instanceof Error ? err.message : String(err) }, 400);
+        }
+        if (runner.idempotency === "unsafe" && !body.confirm) {
+            return c.json({
+                error: "confirmation_required",
+                detail: `Workflow "${runner.name}" has side effects; pass { confirm: true } to rerun.`,
+                idempotency: runner.idempotency,
+            }, 409);
+        }
+        if (runner.canRerun) {
+            const guard = await runner.canRerun(detail.run.input);
+            if (!guard.ok) {
+                return c.json({ error: "rerun_blocked", detail: guard.reason }, 409);
+            }
+        }
+        const userId = opts.resolveUserId?.(c) ?? null;
+        try {
+            const { runId } = await runner.rerun(detail.run.input, {
+                parentRunId: detail.run.id,
+                triggeredByUserId: userId,
+                correlationId: detail.run.correlationId,
+                tags: detail.run.tags,
+            });
+            return c.json({ data: { runId, parentRunId: detail.run.id } }, 202);
+        }
+        catch (err) {
+            console.error("[workflow-runs] rerun failed", err);
+            return c.json({ error: "rerun_failed", detail: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    hono.post("/v1/admin/workflow-runs/:id/resume", async (c) => {
+        // biome-ignore lint/suspicious/noExplicitAny: Hono's c.var.db is loosely typed
+        const db = c.var.db;
+        if (!db)
+            return c.json({ error: "db_unavailable" }, 500);
+        if (!opts.runners) {
+            return c.json({ error: "resume_not_configured", detail: "no WorkflowRunnerRegistry mounted" }, 501);
+        }
+        const parentId = c.req.param("id");
+        const detail = await workflowRunsService.getRunById(db, parentId);
+        if (!detail)
+            return c.json({ error: "not_found" }, 404);
+        if (detail.run.status !== "failed") {
+            return c.json({
+                error: "resume_not_allowed",
+                detail: `Cannot resume a run with status "${detail.run.status}"; only failed runs are resumable.`,
+            }, 409);
+        }
+        const runner = opts.runners.get(detail.run.workflowName);
+        if (!runner) {
+            return c.json({
+                error: "runner_not_registered",
+                detail: `No runner registered for workflow "${detail.run.workflowName}"`,
+            }, 501);
+        }
+        // Find the failed step and seed prior step outputs.
+        const failedStep = detail.steps.find((s) => s.status === "failed");
+        if (!failedStep) {
+            return c.json({
+                error: "no_failed_step",
+                detail: "Run is marked failed but has no failed step row to resume from.",
+            }, 409);
+        }
+        const seedResults = {};
+        for (const s of detail.steps) {
+            if (s.sequence >= failedStep.sequence)
+                break;
+            if (s.status === "succeeded" || s.status === "skipped") {
+                if (s.output && typeof s.output === "object") {
+                    seedResults[s.stepName] = s.output;
+                }
+                else {
+                    // Preserve null/primitive outputs explicitly so downstream
+                    // steps that read them don't see undefined.
+                    seedResults[s.stepName] = s.output ?? null;
+                }
+            }
+            else {
+                return c.json({
+                    error: "incomplete_prior_step",
+                    detail: `Step "${s.stepName}" (sequence ${s.sequence}) is not complete; cannot resume past it.`,
+                }, 409);
+            }
+        }
+        const userId = opts.resolveUserId?.(c) ?? null;
+        try {
+            const { runId } = await runner.resume(detail.run.input, {
+                parentRunId: detail.run.id,
+                triggeredByUserId: userId,
+                correlationId: detail.run.correlationId,
+                tags: detail.run.tags,
+                resumeFromStep: failedStep.stepName,
+                seedResults,
+            });
+            return c.json({ data: { runId, parentRunId: detail.run.id, resumeFromStep: failedStep.stepName } }, 202);
+        }
+        catch (err) {
+            console.error("[workflow-runs] resume failed", err);
+            return c.json({ error: "resume_failed", detail: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+}