@cosmicdrift/kumiko-bundled-features 0.231.0 → 0.232.0

package/src/workflow-runner/handlers/resume-run.write.ts

@@ -0,0 +1,277 @@
+// resume-run — wakes one suspended workflow step. Dispatched by the
+// resume-due-runs job (framework#2513 Phase 2), never called directly by a
+// user — r.systemScope() + access: { roles: [SYSTEM_ROLE] } enforce that.
+//
+// The job does nothing but SELECT + dispatch; all resume logic lives here,
+// adapted from samples/recipes/workflow-engine/src/resume-loop.ts:
+//   1. Q7 fingerprint check FIRST — before claiming, before any pipeline
+//      work. A changed workflow definition fails loud (WORKFLOW_RUN_FAILED,
+//      reason "workflow_definition_changed"), never a silent skip.
+//   2. Claim via a savepoint-scoped WORKFLOW_RESUMED append (ctx.tryAppendEvent,
+//      not unsafeAppendEvent — a losing VersionConflict must not poison this
+//      handler's own transaction). A losing claim means another worker beat
+//      us to this row; silent no-op.
+//   3. Re-run the pipeline via runStepList with resumeFrom: the suspended
+//      step's own index for a retry (re-enters the step), stepIndex + 1
+//      otherwise (wait already wrote its effect; resume past it).
+//
+// The run's ORIGINAL trigger event (the one that started the whole run) is
+// always recovered from the run's own WORKFLOW_RUN_STARTED_TYPE event,
+// never from the pending row — that event always carries it (see
+// WorkflowRunStartedPayload in ./runner). The pending row's own
+// triggerEventType/triggerPayload columns are a DIFFERENT thing: for a
+// waitForEvent suspension they hold the AWAITED event the Phase 3b
+// event-subscriber matched (NULL until then, and NULL forever on a
+// timeout-without-a-match). That payload becomes the resumed pipeline's
+// result for the skipped waitForEvent step itself (see resultKey on
+// steps/wait-for-event.ts) — pre-seeded into stepsAcc below so a
+// subsequent step's resolver can read `ctx.steps[awaits.someKey]`.
+
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  buildPipelineSteps,
+  computeDefinitionFingerprint,
+  getStep,
+  type HandlerContext,
+  runStepList,
+  type StepInstance,
+  SYSTEM_ROLE,
+  WORKFLOW_AGGREGATE_TYPE,
+  WORKFLOW_RESUMED_TYPE,
+  WORKFLOW_RETRY_SCHEDULED_TYPE,
+  WORKFLOW_RUN_COMPLETED_TYPE,
+  WORKFLOW_RUN_FAILED_TYPE,
+  WORKFLOW_RUN_STARTED_TYPE,
+  WORKFLOW_WAITING_FOR_EVENT_TYPE,
+  type WorkflowDefinition,
+  type WriteEvent,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import {
+  isResumableSuspension,
+  type WorkflowRunCompletedPayload,
+  type WorkflowRunFailedPayload,
+  type WorkflowRunStartedPayload,
+  WorkflowSuspensionUnsupportedError,
+} from "../runner";
+import { workflowRunPendingTable } from "../tables";
+import { getWorkflow } from "../workflow-registry";
+
+const resumeRunSchema = z.object({
+  runId: z.string().min(1),
+  stepIndex: z.number().int().nonnegative(),
+});
+
+async function appendRunFailed(
+  ctx: HandlerContext,
+  runId: string,
+  failedPayload: WorkflowRunFailedPayload,
+): Promise<void> {
+  await ctx.unsafeAppendEvent({
+    aggregateId: runId,
+    aggregateType: WORKFLOW_AGGREGATE_TYPE,
+    type: WORKFLOW_RUN_FAILED_TYPE,
+    payload: failedPayload,
+  });
+}
+
+function checkQ7Fingerprint(
+  workflow: WorkflowDefinition,
+  workflowName: string,
+  runId: string,
+  stepIndex: number,
+  storedFingerprint: string | null,
+): WorkflowRunFailedPayload | null {
+  const currentFingerprint = computeDefinitionFingerprint(workflow);
+  const fingerprintChanged = storedFingerprint !== null && currentFingerprint !== storedFingerprint;
+  if (!fingerprintChanged) {
+    return null;
+  }
+  return {
+    workflowName,
+    stepIndex,
+    error:
+      `Workflow "${workflowName}" definition changed since run ${runId} started ` +
+      `(expected ${storedFingerprint?.slice(0, 12)}…, current ${currentFingerprint?.slice(0, 12)}…).`,
+    reason: "workflow_definition_changed",
+  };
+}
+
+async function recoverTriggerEvent(
+  ctx: HandlerContext,
+  runId: string,
+  user: WriteEvent["user"],
+): Promise<WriteEvent> {
+  const startedEvents = await ctx.loadAggregate(runId);
+  const started = startedEvents.find((e) => e.type === WORKFLOW_RUN_STARTED_TYPE);
+  if (!started) {
+    throw new InternalError({
+      message: `workflow-runner:write:resume-run: run ${runId} has no ${WORKFLOW_RUN_STARTED_TYPE} event — cannot recover its trigger event.`,
+    });
+  }
+  const startedPayload = started.payload as WorkflowRunStartedPayload; // @cast-boundary event-store-payload
+  const triggerEvent: WriteEvent = {
+    type: startedPayload.triggerEventType,
+    payload: startedPayload.triggerPayload,
+    user,
+  };
+  return triggerEvent;
+}
+
+// The suspended waitForEvent step itself is skipped on resume
+// (resumeFrom = stepIndex + 1) — its run() never re-executes, so its
+// resultKey (args.event, see steps/wait-for-event.ts) never gets
+// populated by the normal runStepList loop. Seed it here from the
+// pending row's own triggerPayload so a subsequent step's resolver
+// sees the matched event via `ctx.steps[awaits.someKey]`, same as any
+// other step result. NULL on a timeout-without-a-match — a later
+// resolver reading it just sees `undefined`, no special-casing needed.
+function seedResumedStepResults(
+  pending: { suspensionEventType: string; triggerPayload: unknown | null },
+  steps: readonly StepInstance[],
+  stepIndex: number,
+): Record<string, unknown> {
+  const stepsAcc: Record<string, unknown> = {};
+  if (pending.suspensionEventType === WORKFLOW_WAITING_FOR_EVENT_TYPE) {
+    const suspendedStep = steps[stepIndex];
+    const key = suspendedStep && getStep(suspendedStep.kind)?.resultKey?.(suspendedStep.args);
+    if (key !== undefined) {
+      stepsAcc[key] = pending.triggerPayload;
+    }
+  }
+  return stepsAcc;
+}
+
+export const resumeRunHandler: WriteHandlerDef = {
+  name: "resume-run",
+  schema: resumeRunSchema,
+  access: { roles: [SYSTEM_ROLE] },
+  handler: async (event, ctx) => {
+    const { runId, stepIndex } = event.payload as z.infer<typeof resumeRunSchema>;
+    const tenantId = event.user.tenantId;
+
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "workflow-runner:write:resume-run requires ctx.systemDb — is r.systemScope() still set on the workflow-runner feature?",
+      });
+    }
+    const db = ctx.systemDb.assertTenantMatch(tenantId);
+
+    const pending = await fetchOne<{
+      workflowName: string;
+      suspensionEventType: string;
+      retryAttempt: number | null;
+      definitionFingerprint: string | null;
+      triggerPayload: unknown | null;
+    }>(db, workflowRunPendingTable, { runId, stepIndex, tenantId });
+
+    if (!pending) {
+      // skip: no pending row for (runId, stepIndex, tenantId) — another
+      // worker already resumed it (or the run reached a terminal state)
+      // between the job's SELECT and this dispatch; pending-projection.ts
+      // already deleted it.
+      return { isSuccess: true, data: { outcome: "already-resumed" as const } };
+    }
+
+    const { workflowName } = pending;
+    const workflow = getWorkflow(workflowName);
+    if (!workflow) {
+      const failedPayload: WorkflowRunFailedPayload = {
+        workflowName,
+        stepIndex,
+        error: `Workflow "${workflowName}" is not registered — cannot resume run ${runId}.`,
+        reason: "workflow_definition_changed",
+      };
+      await appendRunFailed(ctx, runId, failedPayload);
+      return { isSuccess: true, data: { outcome: "failed" as const } };
+    }
+
+    const fingerprintFailure = checkQ7Fingerprint(
+      workflow,
+      workflowName,
+      runId,
+      stepIndex,
+      pending.definitionFingerprint,
+    );
+    if (fingerprintFailure) {
+      await appendRunFailed(ctx, runId, fingerprintFailure);
+      return { isSuccess: true, data: { outcome: "failed" as const } };
+    }
+
+    const claim = await ctx.tryAppendEvent({
+      aggregateId: runId,
+      aggregateType: WORKFLOW_AGGREGATE_TYPE,
+      type: WORKFLOW_RESUMED_TYPE,
+      payload: {
+        stepIndex,
+        retryAttempt: pending.retryAttempt ?? undefined,
+      },
+    });
+    if (!claim.ok) {
+      // skip: lost the claim race against a concurrent resume-run dispatch
+      // for the same (runId, stepIndex) — the winner already re-runs the
+      // pipeline; nothing left for this call to do.
+      return { isSuccess: true, data: { outcome: "already-resumed" as const } };
+    }
+
+    const triggerEvent = await recoverTriggerEvent(ctx, runId, event.user);
+
+    const resumeFrom =
+      pending.suspensionEventType === WORKFLOW_RETRY_SCHEDULED_TYPE ? stepIndex : stepIndex + 1;
+
+    try {
+      const steps = buildPipelineSteps(workflow.pipelineDef, triggerEvent);
+      const workflowCtx = {
+        runId,
+        workflowName,
+        stepIndex,
+        definitionFingerprint: pending.definitionFingerprint ?? undefined,
+        ...(pending.retryAttempt !== null && { retryAttempt: pending.retryAttempt + 1 }),
+      };
+
+      const stepsAcc = seedResumedStepResults(pending, steps, stepIndex);
+
+      const outcome = await runStepList(
+        steps,
+        triggerEvent,
+        ctx,
+        stepsAcc,
+        {},
+        workflowCtx,
+        resumeFrom,
+      );
+
+      if (outcome.kind === "suspended") {
+        if (!isResumableSuspension(steps, outcome.stepIndex)) {
+          throw new WorkflowSuspensionUnsupportedError(workflowName, outcome.stepIndex);
+        }
+        // Another suspension further down the pipeline — pending-projection.ts
+        // already materialised the new row; nothing more to do this pass.
+        return { isSuccess: true, data: { outcome: "suspended" as const } };
+      }
+
+      const completedPayload: WorkflowRunCompletedPayload = {
+        workflowName,
+        stepIndex: steps.length,
+      };
+      await ctx.unsafeAppendEvent({
+        aggregateId: runId,
+        aggregateType: WORKFLOW_AGGREGATE_TYPE,
+        type: WORKFLOW_RUN_COMPLETED_TYPE,
+        payload: completedPayload,
+      });
+      return { isSuccess: true, data: { outcome: "completed" as const } };
+    } catch (error) {
+      const failedPayload: WorkflowRunFailedPayload = {
+        workflowName,
+        stepIndex,
+        error: String(error),
+      };
+      await appendRunFailed(ctx, runId, failedPayload);
+      return { isSuccess: true, data: { outcome: "failed" as const } };
+    }
+  },
+};

package/src/workflow-runner/pending-projection.ts

@@ -0,0 +1,148 @@
+// pending-projection — MultiStreamProjection that keeps workflow_run_pending
+// in sync with suspension/resume/terminal events on workflow-run streams.
+//
+// Insert (upsert, for idempotent at-least-once redelivery) on every
+// suspension: wait, waitForEvent, retry. Delete on WORKFLOW_RESUMED or a
+// terminal run outcome (completed/failed) — a run only ever has one row
+// pending at a time (D1: a later suspension always targets a fresh
+// stepIndex, since the prior one was resumed away first), so deleting by
+// (tenantId, runId) alone is exact.
+//
+// No resume logic here — framework#2513 Phase 2 owns the job that reads
+// this table and dispatches the actual resume. This projection only writes
+// the rows.
+
+import { deleteMany, upsertOnConflict } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type {
+  FeatureRegistrar,
+  MultiStreamProjectionDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  WORKFLOW_RESUMED_TYPE,
+  WORKFLOW_RETRY_SCHEDULED_TYPE,
+  WORKFLOW_RUN_COMPLETED_TYPE,
+  WORKFLOW_RUN_FAILED_TYPE,
+  WORKFLOW_WAITING_FOR_EVENT_TYPE,
+  WORKFLOW_WAITING_TYPE,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { workflowRunPendingTable } from "./tables";
+
+type WaitPayload = {
+  readonly wakeAt: string;
+  readonly stepIndex: number;
+  readonly workflowName: string;
+  readonly definitionFingerprint?: string;
+};
+
+type WaitForEventPayload = {
+  readonly eventType: string;
+  readonly match?: unknown;
+  readonly timeoutAt: string;
+  readonly stepIndex: number;
+  readonly workflowName: string;
+  readonly definitionFingerprint?: string;
+};
+
+type RetryScheduledPayload = {
+  readonly stepIndex: number;
+  readonly attempt: number;
+  readonly wakeAt: string;
+  readonly workflowName: string;
+  readonly definitionFingerprint?: string;
+};
+
+type PendingRow = {
+  readonly runId: string;
+  readonly tenantId: string;
+  readonly workflowName: string;
+  readonly stepIndex: number;
+  readonly suspensionEventType: string;
+  readonly wakeAt: string;
+  readonly retryAttempt: number | null;
+  readonly definitionFingerprint: string | null;
+  readonly waitEventType: string | null;
+  readonly matchExpr: unknown | null;
+};
+
+async function upsertPending(tx: DbRunner, row: PendingRow): Promise<void> {
+  await upsertOnConflict(
+    tx,
+    workflowRunPendingTable,
+    {
+      ...row,
+      // Phase 3's event-subscriber writes these when the awaited event
+      // arrives — Phase 1 never touches them, insert or update.
+      triggerEventType: null,
+      triggerPayload: null,
+    },
+    { conflictKeys: ["tenantId", "runId", "stepIndex"] },
+  );
+}
+
+async function deleteRunPending(tx: DbRunner, tenantId: string, runId: string): Promise<void> {
+  await deleteMany(tx, workflowRunPendingTable, { tenantId, runId });
+}
+
+export function registerWorkflowRunPendingProjection(r: FeatureRegistrar): void {
+  r.multiStreamProjection({
+    name: "workflow-run-pending",
+    table: workflowRunPendingTable,
+    apply: {
+      [WORKFLOW_WAITING_TYPE]: async (event, tx) => {
+        const p = event.payload as WaitPayload; // @cast-boundary engine-payload
+        await upsertPending(tx, {
+          runId: event.aggregateId,
+          tenantId: event.tenantId,
+          workflowName: p.workflowName,
+          stepIndex: p.stepIndex,
+          suspensionEventType: WORKFLOW_WAITING_TYPE,
+          wakeAt: p.wakeAt,
+          retryAttempt: null,
+          definitionFingerprint: p.definitionFingerprint ?? null,
+          waitEventType: null,
+          matchExpr: null,
+        });
+      },
+      [WORKFLOW_WAITING_FOR_EVENT_TYPE]: async (event, tx) => {
+        const p = event.payload as WaitForEventPayload; // @cast-boundary engine-payload
+        await upsertPending(tx, {
+          runId: event.aggregateId,
+          tenantId: event.tenantId,
+          workflowName: p.workflowName,
+          stepIndex: p.stepIndex,
+          suspensionEventType: WORKFLOW_WAITING_FOR_EVENT_TYPE,
+          wakeAt: p.timeoutAt,
+          retryAttempt: null,
+          definitionFingerprint: p.definitionFingerprint ?? null,
+          waitEventType: p.eventType,
+          matchExpr: p.match ?? null,
+        });
+      },
+      [WORKFLOW_RETRY_SCHEDULED_TYPE]: async (event, tx) => {
+        const p = event.payload as RetryScheduledPayload; // @cast-boundary engine-payload
+        await upsertPending(tx, {
+          runId: event.aggregateId,
+          tenantId: event.tenantId,
+          workflowName: p.workflowName,
+          stepIndex: p.stepIndex,
+          suspensionEventType: WORKFLOW_RETRY_SCHEDULED_TYPE,
+          wakeAt: p.wakeAt,
+          retryAttempt: p.attempt,
+          definitionFingerprint: p.definitionFingerprint ?? null,
+          waitEventType: null,
+          matchExpr: null,
+        });
+      },
+      [WORKFLOW_RESUMED_TYPE]: async (event, tx) => {
+        await deleteRunPending(tx, event.tenantId, event.aggregateId);
+      },
+      [WORKFLOW_RUN_COMPLETED_TYPE]: async (event, tx) => {
+        await deleteRunPending(tx, event.tenantId, event.aggregateId);
+      },
+      [WORKFLOW_RUN_FAILED_TYPE]: async (event, tx) => {
+        await deleteRunPending(tx, event.tenantId, event.aggregateId);
+      },
+    },
+  } satisfies MultiStreamProjectionDefinition);
+}

package/src/workflow-runner/runner.ts

@@ -1,15 +1,17 @@
 // runner — starts a workflow-run by writing run-started, executing the
 // pipeline until first suspension or completion, and writing run-completed.
 //
-// No resume-loop is mounted yet (framework#2480): a suspending step
-// (wait / waitForEvent / retry) would leave the run stuck forever with
-// nothing to wake it. startAndRunWorkflow surfaces that case as a loud
-// WorkflowSuspensionUnsupportedError instead of returning a silent
-// "suspended" outcome — callers (registerEventTrigger) treat it like any
-// other pipeline failure and record it as a failed run.
+// wait / retry / waitForEvent suspensions are all resumable — the
+// resume-due-runs job + resume-run handler (framework#2513 Phase 2) wake
+// wait/retry via a plain wakeAt timeout; waitForEvent additionally gets
+// woken early by the event-subscriber (Phase 3b, event-subscriber.ts) when
+// its awaited event arrives, and by the same wakeAt timeout otherwise
+// (D1's `wakeAt ?? timeoutAt`). startAndRunWorkflow returns a silent
+// "suspended" outcome for all three instead of throwing.
 
 import type {
   HandlerContext,
+  StepInstance,
   WorkflowDefinition,
   WriteEvent,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -22,6 +24,17 @@ import {
   WORKFLOW_RUN_STARTED_TYPE,
 } from "@cosmicdrift/kumiko-framework/engine";
 
+// Suspensions the resume loop knows how to wake — every Tier-3 step that
+// can return SUSPEND_SENTINEL. Kept as an explicit allowlist (not "every
+// registered Tier-3 step") so a future suspending step that forgets to
+// wire up its own wake path fails loud via WorkflowSuspensionUnsupportedError
+// instead of hanging a run forever.
+const RESUMABLE_STEP_KINDS = new Set(["workflow.wait", "workflow.retry", "workflow.waitForEvent"]);
+
+export function isResumableSuspension(steps: readonly StepInstance[], stepIndex: number): boolean {
+  return RESUMABLE_STEP_KINDS.has(steps[stepIndex]?.kind ?? "");
+}
+
 export type WorkflowRunStartedPayload = {
   readonly workflowName: string;
   readonly triggerEventType: string;
@@ -31,11 +44,11 @@ export type WorkflowRunStartedPayload = {
 };
 
 // Canonical run-completed shape — the sample this was hoisted from had two
-// writers disagree (`{workflowName}` here, `{stepIndex}` in the not-yet-
-// mounted resume-loop). `stepIndex` is the pipeline's top-level step count
-// (sub-lists inside branch/forEach aren't counted); every run that reaches
-// this event ran to completion in one pass (suspension throws instead of
-// returning here).
+// writers disagree (`{workflowName}` here, `{stepIndex}` in the resume-loop
+// sample). `stepIndex` is the pipeline's top-level step count (sub-lists
+// inside branch/forEach aren't counted). A run reaches this event either in
+// one pass, or across multiple passes when a wait/retry suspension resumed
+// it (resume-run writes this same event on the pass that finally completes).
 export type WorkflowRunCompletedPayload = {
   readonly workflowName: string;
   readonly stepIndex: number;
@@ -45,6 +58,10 @@ export type WorkflowRunFailedPayload = {
   readonly workflowName: string;
   readonly stepIndex: number;
   readonly error: string;
+  // Machine-readable failure category — set by resume-run for a Q7
+  // fingerprint mismatch ("workflow_definition_changed"); absent for a
+  // plain pipeline-step failure (the `error` string is human-readable only).
+  readonly reason?: string;
 };
 
 export class WorkflowSuspensionUnsupportedError extends Error {
@@ -74,7 +91,7 @@ export async function startAndRunWorkflow(args: {
   readonly triggerEvent: WriteEvent;
   readonly idempotencyKey?: string;
   readonly handlerCtx: HandlerContext;
-}): Promise<{ readonly outcome: "completed" }> {
+}): Promise<{ readonly outcome: "completed" | "suspended" }> {
   const fingerprint = computeDefinitionFingerprint(args.workflow);
 
   const startedPayload: WorkflowRunStartedPayload = {
@@ -109,7 +126,13 @@ export async function startAndRunWorkflow(args: {
   );
 
   if (outcome.kind === "suspended") {
-    throw new WorkflowSuspensionUnsupportedError(args.workflow.name, outcome.stepIndex);
+    if (!isResumableSuspension(steps, outcome.stepIndex)) {
+      throw new WorkflowSuspensionUnsupportedError(args.workflow.name, outcome.stepIndex);
+    }
+    // pending-projection.ts already materialised the row that
+    // resume-due-runs will pick up (or the event-subscriber will wake
+    // early, for waitForEvent) — nothing more to do on this pass.
+    return { outcome: "suspended" };
   }
 
   const completedPayload: WorkflowRunCompletedPayload = {

package/src/workflow-runner/tables.ts

@@ -0,0 +1,95 @@
+import {
+  defineUnmanagedTable,
+  type EntityTableMeta,
+  index,
+  instant,
+  integer,
+  jsonb,
+  table as pgTable,
+  primaryKey,
+  text,
+  uuid,
+} from "@cosmicdrift/kumiko-framework/db";
+
+// workflow_run_pending — one row per currently-suspended workflow step.
+// Read-side of the resume loop (framework#2513 Phase 1): the wait /
+// waitForEvent / retry steps already write their suspension onto the
+// workflow-run event stream, but scanning kumiko_events for due runs
+// doesn't scale (see samples/recipes/workflow-engine/postgres-resume-loop.ts,
+// which does exactly that). This table is kept in sync by
+// pending-projection.ts's MultiStreamProjection so Phase 2's resume job can
+// do an indexed `wakeAt < now()` scan instead.
+//
+// **Unmanaged table** — same reasoning as delivery/tables.ts'
+// deliveryAttemptsTable: rows are keyed by the workflow-run's own
+// (runId, stepIndex), not by an ES-aggregate id of their own, and rows are
+// deleted outright on resume/terminal rather than soft-state-transitioned —
+// no audit trail needed for a purely operational pending-set.
+//
+// PK = (tenant_id, run_id, step_index): workflowRunAggregateId() is
+// intentionally tenant-agnostic (uuidv5 over workflowName + idempotency
+// key only, see aggregate-id.ts), so two tenants triggering the same
+// workflow with the same idempotencyKey get the SAME run_id. Without
+// tenant_id in the key, a same-stepIndex suspension from tenant B would
+// upsert onto tenant A's row and silently steal it (framework#2513).
+export const workflowRunPendingTable = pgTable(
+  "workflow_run_pending",
+  {
+    runId: uuid("run_id").notNull(),
+    tenantId: uuid("tenant_id").notNull(),
+    workflowName: text("workflow_name").notNull(),
+    stepIndex: integer("step_index").notNull(),
+    suspensionEventType: text("suspension_event_type").notNull(),
+    // Unified `wakeAt ?? timeoutAt` from the suspension payload — one
+    // column, one index, one predicate for the resume job regardless of
+    // which step suspended.
+    wakeAt: instant("wake_at").notNull(),
+    retryAttempt: integer("retry_attempt"),
+    // Q7 snapshot fingerprint — Phase 2 compares this against the current
+    // workflow definition's fingerprint before resuming.
+    definitionFingerprint: text("definition_fingerprint"),
+    // Set only for waitForEvent suspensions; NULL for wait/retry.
+    waitEventType: text("wait_event_type"),
+    matchExpr: jsonb("match_expr"),
+    // Written by the Phase 3 event-subscriber when the awaited event
+    // arrives — always NULL in Phase 1/2.
+    triggerEventType: text("trigger_event_type"),
+    triggerPayload: jsonb("trigger_payload"),
+  },
+  (t) => [
+    primaryKey({
+      columns: [t.tenantId, t.runId, t.stepIndex],
+      name: "workflow_run_pending_pkey",
+    }),
+    // Composite, not wake_at-alone: the resume job's due-scan
+    // (feature.ts) always filters `tenant_id = $1 AND wake_at < now()`.
+    index("workflow_run_pending_tenant_wake_at_idx").on(t.tenantId, t.wakeAt),
+    index("workflow_run_pending_wait_event_type_idx").on(t.waitEventType),
+  ],
+);
+
+export const workflowRunPendingTableMeta: EntityTableMeta = defineUnmanagedTable({
+  tableName: "workflow_run_pending",
+  columns: [
+    { name: "run_id", pgType: "uuid", notNull: true },
+    { name: "tenant_id", pgType: "uuid", notNull: true },
+    { name: "workflow_name", pgType: "text", notNull: true },
+    { name: "step_index", pgType: "integer", notNull: true },
+    { name: "suspension_event_type", pgType: "text", notNull: true },
+    { name: "wake_at", pgType: "timestamptz", notNull: true },
+    { name: "retry_attempt", pgType: "integer", notNull: false },
+    { name: "definition_fingerprint", pgType: "text", notNull: false },
+    { name: "wait_event_type", pgType: "text", notNull: false },
+    { name: "match_expr", pgType: "jsonb", notNull: false },
+    { name: "trigger_event_type", pgType: "text", notNull: false },
+    { name: "trigger_payload", pgType: "jsonb", notNull: false },
+  ],
+  indexes: [
+    { name: "workflow_run_pending_tenant_wake_at_idx", columns: ["tenant_id", "wake_at"] },
+    { name: "workflow_run_pending_wait_event_type_idx", columns: ["wait_event_type"] },
+  ],
+  compositePrimaryKey: {
+    name: "workflow_run_pending_pkey",
+    columns: ["tenant_id", "run_id", "step_index"],
+  },
+});

package/src/workflow-runner/workflow-registry.ts

@@ -0,0 +1,23 @@
+// workflow-registry — process-local lookup from workflow name to its
+// WorkflowDefinition. registerEventTrigger populates it at feature-
+// registration time; resume-run (Phase 2) is the only reader — it has
+// nothing but a workflow name on the pending row and needs the live
+// definition to rebuild the pipeline + recompute the Q7 fingerprint.
+//
+// Overwrite-on-same-name, no throw: unlike defineStep's registry (which
+// throws on a duplicate kind — a real programming error), redefining a
+// workflow under the same name is a legitimate deploy-time occurrence
+// (the whole point of Q7 is detecting exactly that changed-definition case
+// downstream, not preventing the registration).
+
+import type { WorkflowDefinition } from "@cosmicdrift/kumiko-framework/engine";
+
+const registry = new Map<string, WorkflowDefinition>();
+
+export function registerWorkflow(workflow: WorkflowDefinition): void {
+  registry.set(workflow.name, workflow);
+}
+
+export function getWorkflow(name: string): WorkflowDefinition | undefined {
+  return registry.get(name);
+}