@cosmicdrift/kumiko-bundled-features 0.231.0 → 0.232.0

package/src/workflow-runner/__tests__/resume-loop.integration.test.ts

@@ -0,0 +1,277 @@
+// resume-loop — the time-based resume path (framework#2513 Phase 2)
+// against real Postgres.
+//
+// Drives `resume-due-runs` directly via stack.registry.getJob(...) (same
+// style as data-retention/__tests__/retention-cleanup.integration.test.ts)
+// with `write` wired to the real dispatcher — this exercises the full
+// resume-run handler (access gate, Q7 check, claim, pipeline re-entry), not
+// just runResumeDueRunsJob's own SELECT.
+//
+// wait's `for` is a resolver reading the trigger payload, so both the due
+// and not-yet-due cases share one workflow fixture — no need to fake the
+// clock or sleep past a real backoff. The retry fixture's backoff can't be
+// steered the same way (only `wait`'s wait-length step-arg is resolver-
+// controlled), so its due-case tampers `wake_at` directly, same as the Q7
+// mismatch test tampers `definition_fingerprint` directly — neither touches
+// the workflow-registry, keeping "registry overwrite" out of the test
+// contract.
+//
+// pending-projection.ts and the event-trigger MSP both run off
+// stack.eventDispatcher.runOnce() — this file's own tests are unaffected by
+// (and must not touch) whatever separately-named test file exercises the
+// projection itself.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  defineFeature,
+  defineWorkflow,
+  type JobContext,
+  stepsPipeline,
+  WORKFLOW_RESUMED_TYPE,
+  WORKFLOW_RETRY_SCHEDULED_TYPE,
+  WORKFLOW_RUN_COMPLETED_TYPE,
+  WORKFLOW_RUN_FAILED_TYPE,
+  WORKFLOW_RUN_STARTED_TYPE,
+  WORKFLOW_WAITING_TYPE,
+  type WorkflowDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { setupTestStack, type TestStack, TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { bridgeStub } from "@cosmicdrift/kumiko-framework/testing";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { workflowRunAggregateId } from "../aggregate-id";
+import { registerEventTrigger } from "../event-trigger";
+import { workflowRunnerFeature } from "../feature";
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+const T = getTemporal();
+
+// Uniquely prefixed ("rl-") — the workflow-registry is a process-global
+// module singleton, and workflow-runner.integration.test.ts's own fixtures
+// ("wr-integration-*") already live in the same test process.
+const waitWorkflow: WorkflowDefinition = defineWorkflow({
+  name: "rl-wait",
+  trigger: { kind: "event", eventType: "rl-test.wait" },
+  idempotencyKey: ({ payload }) => (payload as { runKey: string }).runKey,
+  steps: stepsPipeline(({ r }) => [
+    r.step.wait({ for: (ctx) => (ctx.event.payload as { forIso: string }).forIso }),
+    r.step.return({ isSuccess: true, data: undefined }),
+  ]),
+});
+
+const retryWorkflow: WorkflowDefinition = defineWorkflow({
+  name: "rl-retry",
+  trigger: { kind: "event", eventType: "rl-test.retry" },
+  idempotencyKey: ({ payload }) => (payload as { runKey: string }).runKey,
+  steps: stepsPipeline(({ r }) => [
+    r.step.retry({
+      times: 2,
+      backoff: "linear",
+      do: [
+        r.step.compute("gate", (ctx) => {
+          const attempt = ctx.workflow?.retryAttempt ?? 1;
+          if (attempt === 1) throw new Error("first-attempt-fails");
+          return attempt;
+        }),
+      ],
+    }),
+    r.step.return({ isSuccess: true, data: undefined }),
+  ]),
+});
+
+const testTriggersFeature = defineFeature("workflow-runner-resume-loop-test-triggers", (r) => {
+  registerEventTrigger(r, waitWorkflow);
+  registerEventTrigger(r, retryWorkflow);
+});
+
+const noopLogger: JobContext["log"] = {
+  info() {},
+  warn() {},
+  error() {},
+  debug() {},
+  child() {
+    return noopLogger;
+  },
+};
+
+async function fireTrigger(eventType: string, payload: Record<string, unknown>): Promise<void> {
+  await insertOne(stack.db, eventsTable, {
+    aggregateId: crypto.randomUUID(),
+    aggregateType: "rl-test-source",
+    tenantId: admin.tenantId,
+    version: 1,
+    type: eventType,
+    eventVersion: 1,
+    payload,
+    metadata: { userId: admin.id },
+    createdBy: admin.id,
+  });
+  // Two passes: event-trigger's MSP consumes this event and writes the
+  // run-started/suspension events on the first pass; pending-projection is a
+  // separate MSP consumer that only observes those newly-written events
+  // (and materialises the pending row) on a pass after they exist.
+  await stack.eventDispatcher?.runOnce();
+  await stack.eventDispatcher?.runOnce();
+}
+
+async function loadRunEvents(runId: string) {
+  return selectMany(
+    stack.db,
+    eventsTable,
+    { aggregateId: runId },
+    { orderBy: { col: "version", direction: "asc" } },
+  );
+}
+
+async function pendingRowExists(runId: string, stepIndex: number): Promise<boolean> {
+  const rows = (await asRawClient(stack.db).unsafe(
+    `SELECT 1 FROM workflow_run_pending WHERE run_id = $1 AND step_index = $2`,
+    [runId, stepIndex],
+  )) as ReadonlyArray<unknown>;
+  return rows.length > 0;
+}
+
+async function tamperWakeAtToPast(runId: string, stepIndex: number): Promise<void> {
+  await asRawClient(stack.db).unsafe(
+    `UPDATE workflow_run_pending SET wake_at = now() - interval '1 hour' WHERE run_id = $1 AND step_index = $2`,
+    [runId, stepIndex],
+  );
+}
+
+async function tamperFingerprint(runId: string, stepIndex: number, value: string): Promise<void> {
+  await asRawClient(stack.db).unsafe(
+    `UPDATE workflow_run_pending SET definition_fingerprint = $1 WHERE run_id = $2 AND step_index = $3`,
+    [value, runId, stepIndex],
+  );
+}
+
+async function runResumeDueRunsJob(): Promise<void> {
+  const job = stack.registry.getJob("workflow-runner:job:resume-due-runs");
+  expect(job).toBeDefined();
+  if (!job) return;
+
+  const systemUser = createSystemUser(admin.tenantId);
+  const ctx: JobContext = {
+    db: stack.db,
+    registry: stack.registry,
+    systemUser,
+    log: noopLogger,
+    triggeredBy: null,
+    ...bridgeStub({ user: systemUser }),
+    write: (qn, payload) => stack.dispatcher.write(qn, payload, systemUser),
+  };
+  await job.handler({}, ctx);
+}
+
+describe("workflow-runner resume loop", () => {
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [workflowRunnerFeature, testTriggersFeature] });
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("due wait: resume-due-runs resumes it to completion, pending row deleted", async () => {
+    const runKey = crypto.randomUUID();
+    const runId = workflowRunAggregateId(waitWorkflow.name, runKey);
+    const pastIso = T.Now.instant().subtract({ hours: 1 }).toString();
+
+    await fireTrigger("rl-test.wait", { runKey, forIso: pastIso });
+    expect(await pendingRowExists(runId, 0)).toBe(true);
+
+    await runResumeDueRunsJob();
+
+    const rows = await loadRunEvents(runId);
+    expect(rows.map((row) => row["type"])).toEqual([
+      WORKFLOW_RUN_STARTED_TYPE,
+      WORKFLOW_WAITING_TYPE,
+      WORKFLOW_RESUMED_TYPE,
+      WORKFLOW_RUN_COMPLETED_TYPE,
+    ]);
+    expect(rows[3]!["payload"]).toEqual({ workflowName: waitWorkflow.name, stepIndex: 2 });
+
+    // pending-projection deletes on WORKFLOW_RESUMED via a separate MSP pass.
+    await stack.eventDispatcher?.runOnce();
+    expect(await pendingRowExists(runId, 0)).toBe(false);
+  });
+
+  test("not-yet-due wait: resume-due-runs leaves the row and run untouched", async () => {
+    const runKey = crypto.randomUUID();
+    const runId = workflowRunAggregateId(waitWorkflow.name, runKey);
+    const futureIso = T.Now.instant().add({ hours: 1 }).toString();
+
+    await fireTrigger("rl-test.wait", { runKey, forIso: futureIso });
+    expect(await pendingRowExists(runId, 0)).toBe(true);
+
+    await runResumeDueRunsJob();
+
+    const rows = await loadRunEvents(runId);
+    expect(rows.map((row) => row["type"])).toEqual([
+      WORKFLOW_RUN_STARTED_TYPE,
+      WORKFLOW_WAITING_TYPE,
+    ]);
+    expect(await pendingRowExists(runId, 0)).toBe(true);
+  });
+
+  test("changed workflow definition: resume-run fails loud with reason workflow_definition_changed, no resume", async () => {
+    const runKey = crypto.randomUUID();
+    const runId = workflowRunAggregateId(waitWorkflow.name, runKey);
+    const pastIso = T.Now.instant().subtract({ hours: 1 }).toString();
+
+    await fireTrigger("rl-test.wait", { runKey, forIso: pastIso });
+    await tamperFingerprint(runId, 0, "tampered-fingerprint-value");
+
+    await runResumeDueRunsJob();
+
+    const rows = await loadRunEvents(runId);
+    expect(rows.map((row) => row["type"])).toEqual([
+      WORKFLOW_RUN_STARTED_TYPE,
+      WORKFLOW_WAITING_TYPE,
+      WORKFLOW_RUN_FAILED_TYPE,
+    ]);
+    expect(rows[2]!["payload"]).toMatchObject({
+      workflowName: waitWorkflow.name,
+      stepIndex: 0,
+      reason: "workflow_definition_changed",
+    });
+
+    await stack.eventDispatcher?.runOnce();
+    expect(await pendingRowExists(runId, 0)).toBe(false);
+  });
+
+  test("retry suspension: resumeFrom is the same stepIndex — the step repeats with retryAttempt threaded, then completes", async () => {
+    const runKey = crypto.randomUUID();
+    const runId = workflowRunAggregateId(retryWorkflow.name, runKey);
+
+    await fireTrigger("rl-test.retry", { runKey });
+
+    const rowsAfterSuspend = await loadRunEvents(runId);
+    expect(rowsAfterSuspend.map((row) => row["type"])).toEqual([
+      WORKFLOW_RUN_STARTED_TYPE,
+      WORKFLOW_RETRY_SCHEDULED_TYPE,
+    ]);
+    expect(rowsAfterSuspend[1]!["payload"]).toMatchObject({ stepIndex: 0, attempt: 1 });
+
+    await tamperWakeAtToPast(runId, 0);
+    await runResumeDueRunsJob();
+
+    const rowsAfterResume = await loadRunEvents(runId);
+    expect(rowsAfterResume.map((row) => row["type"])).toEqual([
+      WORKFLOW_RUN_STARTED_TYPE,
+      WORKFLOW_RETRY_SCHEDULED_TYPE,
+      WORKFLOW_RESUMED_TYPE,
+      WORKFLOW_RUN_COMPLETED_TYPE,
+    ]);
+    // Only one retry-scheduled ever: proves retryAttempt was threaded into
+    // the resumed pass (attempt=2 clears the gate) instead of the gate
+    // throwing again and scheduling a second retry at attempt=1.
+    expect(
+      rowsAfterResume.filter((row) => row["type"] === WORKFLOW_RETRY_SCHEDULED_TYPE),
+    ).toHaveLength(1);
+  });
+});

package/src/workflow-runner/__tests__/workflow-runner.integration.test.ts

@@ -15,6 +15,7 @@ import {
   WORKFLOW_RUN_COMPLETED_TYPE,
   WORKFLOW_RUN_FAILED_TYPE,
   WORKFLOW_RUN_STARTED_TYPE,
+  WORKFLOW_WAITING_TYPE,
   type WorkflowDefinition,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
@@ -134,22 +135,16 @@ describe("workflow-runner event-trigger", () => {
     expect(String(rows[1]!["payload"]["error"])).toContain("boom-explicit-failure");
   });
 
-  test("suspension: a wait step fails the run instead of leaving it silently pending, no run-completed", async () => {
+  test("suspension: a wait step suspends the run instead of failing it — resumable by framework#2513 Phase 2, no run-completed yet", async () => {
     const runKey = crypto.randomUUID();
     const runId = workflowRunAggregateId(suspendingWorkflow.name, runKey);
 
     await fireTrigger("wr-test.suspend", { runKey });
 
     const rows = await loadRunEvents(runId);
-    const types = rows.map((row) => row["type"]);
-    expect(types).toContain(WORKFLOW_RUN_STARTED_TYPE);
-    expect(types).not.toContain(WORKFLOW_RUN_COMPLETED_TYPE);
-    expect(types).toContain(WORKFLOW_RUN_FAILED_TYPE);
-
-    const failed = rows.find((row) => row["type"] === WORKFLOW_RUN_FAILED_TYPE)!;
-    const errorText = String(failed["payload"]["error"]);
-    expect(errorText).toContain("WorkflowSuspensionUnsupportedError");
-    expect(errorText).toContain(suspendingWorkflow.name);
-    expect(errorText).toContain("resume-loop");
+    expect(rows.map((row) => row["type"])).toEqual([
+      WORKFLOW_RUN_STARTED_TYPE,
+      WORKFLOW_WAITING_TYPE,
+    ]);
   });
 });

package/src/workflow-runner/db/queries/due-runs.ts

@@ -0,0 +1,23 @@
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+export type DueRow = { readonly run_id: string; readonly step_index: number };
+
+// Standalone statement (no db.begin) — FOR UPDATE SKIP LOCKED only
+// needs to survive this one SELECT to reduce redundant dispatches
+// under true concurrency; it auto-commits and releases the row locks
+// immediately after. The real correctness guarantee is resume-run's
+// VersionConflictError-checked claim (ctx.tryAppendEvent on
+// WORKFLOW_RESUMED) — a second dispatch for the same row just loses
+// that race and no-ops, same as the sample this was adapted from.
+export async function selectDueWorkflowRunPending(
+  db: DbConnection,
+  tenantId: TenantId,
+): Promise<readonly DueRow[]> {
+  // kumiko-lint-ignore raw-sql tenant-scoped due-row pickup with FOR UPDATE SKIP LOCKED
+  return (await asRawClient(db).unsafe(
+    `SELECT run_id, step_index FROM workflow_run_pending WHERE tenant_id = $1 AND wake_at < now() FOR UPDATE SKIP LOCKED`,
+    [tenantId],
+  )) as readonly DueRow[];
+}

package/src/workflow-runner/event-subscriber.ts

@@ -0,0 +1,93 @@
+// event-subscriber — wakes up pending waitForEvent suspensions when their
+// awaited domain event arrives (framework#2513 Phase 3b, D4 in
+// workflow-resume-loop.md).
+//
+// registerEventTrigger (event-trigger.ts) calls registerEventWakeup for
+// every workflow it registers, building ONE MultiStreamProjection PER
+// WORKFLOW from that workflow's own `awaits` declaration — not a single
+// shared MSP built by scanning the process-global workflow-registry.
+// Reason: the registrar throws synchronously if an MSP's apply-map is
+// empty at r.multiStreamProjection() call time (feature-ui-extensions.ts).
+// workflow-runner's own feature.ts is imported independently of whatever
+// app-specific feature module calls registerEventTrigger — a shared MSP
+// built by reading the registry inside feature.ts's registration would
+// depend on every awaits-declaring feature already having run
+// registerEventTrigger() first, which is an unenforced app-import-order
+// hazard. Building the map right here, from the `workflow` argument
+// already in hand, has no such hazard — same reasoning event-trigger.ts
+// already applies to the run-start MSP.
+//
+// This subscriber never resumes a run itself (D3, workflow-resume-loop.md):
+// the MultiStreamApplyContext it runs in has no callFeature/runStepList
+// access, only unsafeAppendEvent/loadAggregate. It writes triggerEventType
+// + triggerPayload + wakeAt=now() onto the matching pending row(s); the
+// existing resume-due-runs job (Phase 2) picks the row up on its next
+// cron tick — the one resume path stays exactly the one Phase 2 built.
+
+import { selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type {
+  FeatureRegistrar,
+  MultiStreamApplyFn,
+  MultiStreamProjectionDefinition,
+  WorkflowDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { evaluateEventMatch } from "@cosmicdrift/kumiko-framework/engine";
+import { workflowRunPendingTable } from "./tables";
+
+type CandidateRow = {
+  readonly runId: string;
+  readonly tenantId: string;
+  readonly stepIndex: number;
+  readonly matchExpr: unknown | null;
+};
+
+const wakeupApply: MultiStreamApplyFn = async (event, tx) => {
+  const rows = await selectMany<CandidateRow>(tx, workflowRunPendingTable, {
+    tenantId: event.tenantId,
+    waitEventType: event.type,
+  });
+
+  for (const row of rows) {
+    const matches = row.matchExpr
+      ? evaluateEventMatch(
+          // @cast-boundary engine-payload — matchExpr round-trips through
+          // jsonb as the EventMatch AST waitForEvent's `match` resolver
+          // persisted (see steps/wait-for-event.ts); never an unchecked
+          // external value.
+          row.matchExpr as Parameters<typeof evaluateEventMatch>[0],
+          event.payload,
+        )
+      : true;
+    // skip: this row's matchExpr rejected the event — not this row's
+    // resume, leave wakeAt/triggerEventType untouched.
+    if (!matches) continue;
+
+    await updateMany(
+      tx,
+      workflowRunPendingTable,
+      {
+        triggerEventType: event.type,
+        triggerPayload: event.payload,
+        wakeAt: Temporal.Now.instant().toString(),
+      },
+      { tenantId: row.tenantId, runId: row.runId, stepIndex: row.stepIndex },
+    );
+  }
+};
+
+export function registerEventWakeup(r: FeatureRegistrar, workflow: WorkflowDefinition): void {
+  const eventTypes = Object.values(workflow.awaits ?? {});
+  // skip: no `awaits` declared — nothing to subscribe to, and an empty
+  // apply-map throws at r.multiStreamProjection() registration time.
+  if (eventTypes.length === 0) return;
+
+  const apply: Record<string, MultiStreamApplyFn> = {};
+  for (const eventType of eventTypes) {
+    apply[eventType] = wakeupApply;
+  }
+
+  r.multiStreamProjection({
+    name: `workflow-${workflow.name}-wakeup`,
+    apply,
+  } satisfies MultiStreamProjectionDefinition);
+}

package/src/workflow-runner/event-trigger.ts

@@ -6,10 +6,8 @@
 //
 // The MSP apply-fn runs in the dispatcher's own tx, so `workflow.run-started`
 // plus the synchronous portion of the pipeline land atomically. Any throw
-// from startAndRunWorkflow — including WorkflowSuspensionUnsupportedError,
-// since no resume-loop is mounted yet (framework#2480) — is recorded as
-// `workflow.run-failed` and rethrown so the dispatcher's retry/dead-letter
-// handling still applies.
+// from startAndRunWorkflow is recorded as `workflow.run-failed` and
+// rethrown so the dispatcher's retry/dead-letter handling still applies.
 
 import type {
   FeatureRegistrar,
@@ -22,9 +20,21 @@ import {
   WORKFLOW_RUN_FAILED_TYPE,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { workflowRunAggregateId } from "./aggregate-id";
+import { registerEventWakeup } from "./event-subscriber";
 import { startAndRunWorkflow, type WorkflowRunFailedPayload } from "./runner";
+import { registerWorkflow } from "./workflow-registry";
 
 export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefinition): void {
+  // Populate the workflow-registry unconditionally, before the event-trigger
+  // guard below — resume-run (framework#2513 Phase 2) looks workflows up by
+  // name regardless of trigger kind, and a cron-triggered workflow that never
+  // reaches the MSP branch still needs to be resumable.
+  registerWorkflow(workflow);
+
+  // Independent of trigger.kind — a cron-triggered workflow can still have
+  // waitForEvent steps in its pipeline (framework#2513 Phase 3b, D4).
+  registerEventWakeup(r, workflow);
+
   // skip: cron-triggered workflows have no domain event to project off — they
   // need a scheduler, not an MSP, so there is nothing to register here.
   if (workflow.trigger.kind !== "event") return;

package/src/workflow-runner/feature.ts

@@ -7,13 +7,28 @@
 // WorkflowDefinition via `defineWorkflow` and wire it up with
 // `registerEventTrigger(r, myWorkflow)` inside their own feature. Mounting
 // `workflowRunnerFeature` documents that dependency and reserves the
-// picker/manifest slot; it has no MSPs or entities to register itself.
+// picker/manifest slot.
 //
-// No resume-loop is bundled yet (framework#2480) — workflows that use
-// suspending steps (wait / waitForEvent / retry) fail loud via
-// WorkflowSuspensionUnsupportedError instead of hanging silently.
+// It also registers the resume loop (framework#2513 Phase 2 + 3b):
+//   - the workflow_run_pending MSP (Phase 1) materialises suspended
+//     wait/waitForEvent/retry steps into a pending-set table
+//   - the `resume-due-runs` cron job (perTenant) scans that table for
+//     `wakeAt < now()` rows and dispatches `resume-run` per row — the job
+//     itself does no resume logic, only SELECT + dispatch
+//   - the `resume-run` write handler (r.systemScope(), SYSTEM_ROLE-only)
+//     does the actual Q7-check + claim + pipeline re-entry
+//   - `registerEventTrigger` (event-trigger.ts) additionally registers an
+//     event-wakeup MSP per workflow that declares `awaits` — it marks the
+//     matching pending row due as soon as the awaited event arrives,
+//     instead of waiting out the full timeout (event-subscriber.ts)
+//
+// wait/retry/waitForEvent suspensions all resume automatically now.
 
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { selectDueWorkflowRunPending } from "./db/queries/due-runs";
+import { resumeRunHandler } from "./handlers/resume-run.write";
+import { registerWorkflowRunPendingProjection } from "./pending-projection";
+import { workflowRunPendingTableMeta } from "./tables";
 
 // Kebab-case matching the "./workflow-runner" export subpath — every other
 // bundled feature's runtime name follows this convention, and
@@ -22,11 +37,53 @@ const FEATURE_NAME = "workflow-runner";
 
 export const workflowRunnerFeature = defineFeature(FEATURE_NAME, (r) => {
   r.describe(
-    "Writes the run-envelope (`workflow.run-started` / `workflow.run-completed` / `workflow.run-failed`) for a workflow run onto its `workflow-run` aggregate stream. Provides `startAndRunWorkflow` and `registerEventTrigger` for consumer features to wire up `defineWorkflow`-based workflows against domain events. Registers no workflows itself. No resume-loop is bundled yet (framework#2480) — suspending steps (wait/waitForEvent/retry) fail the run instead of pausing it.",
+    "Writes the run-envelope (`workflow.run-started` / `workflow.run-completed` / `workflow.run-failed`) for a workflow run onto its `workflow-run` aggregate stream. Provides `startAndRunWorkflow` and `registerEventTrigger` for consumer features to wire up `defineWorkflow`-based workflows against domain events. Registers no workflows itself. Runs the resume loop for suspended `wait`/`retry`/`waitForEvent` steps (`resume-due-runs` job + `resume-run` handler); `registerEventTrigger` wires an event-wakeup subscriber per workflow that declares `awaits` so a `waitForEvent` step resumes as soon as its awaited event arrives, not just on timeout.",
   );
   r.uiHints({
     displayLabel: "Workflow Runner",
     category: "infrastructure",
     recommended: false,
   });
+  // resume-run needs a full HandlerContext + ctx.systemDb (the pending-row
+  // scan crosses whatever tenant the row belongs to relative to the job's
+  // own tenant loop iteration) — same reasoning as tenant/feature.ts.
+  r.systemScope();
+  r.storeTable(workflowRunPendingTableMeta, {
+    reason: "resume_loop.pending_suspended_steps",
+  });
+  registerWorkflowRunPendingProjection(r);
+  r.writeHandler(resumeRunHandler);
+
+  r.job(
+    "resume-due-runs",
+    { trigger: { cron: "* * * * *" }, perTenant: true, concurrency: "skip" },
+    async (_payload, ctx) => {
+      if (!ctx.db) {
+        throw new Error("resume-due-runs: ctx.db required (JobContext incomplete)");
+      }
+      const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
+      if (tenantId === undefined) {
+        // skip: cron fired without a perTenant fan-out tenant — nothing scoped
+        return;
+      }
+
+      const dueRows = await selectDueWorkflowRunPending(ctx.db, tenantId);
+
+      for (const row of dueRows) {
+        try {
+          await ctx.write("workflow-runner:write:resume-run", {
+            runId: row.run_id,
+            stepIndex: row.step_index,
+          });
+        } catch (error) {
+          // skip: one row's dispatch failing (infra hiccup, not a business
+          // outcome — resume-run itself never throws for expected cases)
+          // must not stop the rest of this tenant's due rows from resuming.
+          ctx.log.warn(
+            `[workflow-runner:resume-due-runs] runId=${row.run_id} stepIndex=${row.step_index} dispatch failed: ${String(error)}`,
+          );
+        }
+      }
+    },
+  );
 });