@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/workflow-engine.md

@@ -0,0 +1,1731 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/workflow-engine. Do not edit. -->
+
+# workflow-engine
+
+M.4 Tier-3 step-vocabulary showcase: defineWorkflow with wait/waitForEvent/retry steps
+
+## README
+
+# Workflow Engine
+
+Tier-3 `defineWorkflow` vocabulary: wait, branch, mail, webhook.
+
+## What it shows
+
+- Real runnable pipelines (no empty `build: () => []` stubs)
+- Workflow-run lifecycle across wait / waitForEvent
+- `webhook.send` is delivered once by the step-dispatcher; a failed delivery ends as `step.dispatch-failed`. Wrapping it in `r.step.retry` would not repeat it, because the step only enqueues the request and never throws on a delivery error
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/workflow-engine
+bun test
+```
+
+## Source files
+
+### src/__tests__/workflow-integration.integration.test.ts
+
+```ts
+// Workflow-engine event-store integration test.
+//
+// Verifies the Postgres-backed fetcher against real rows:
+//   - finds expired WAITING events
+//   - hydrates SuspendableRun with the trigger-event snapshot + Q7
+//     definitionFingerprint from the event payload
+//   - returns a no-op for fingerprint-less legacy rows
+//
+// End-to-end MSP-trigger → workflow execution is a separate followup
+// (requires wiring a dispatcher-fire-able event-shape into the test
+// stack); the unit-test file covers the Pipeline/resume-loop logic
+// against the in-memory fetcher.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
+import type { WorkflowDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  computeDefinitionFingerprint,
+  defineWorkflow,
+  stepsPipeline,
+  WORKFLOW_AGGREGATE_TYPE,
+  WORKFLOW_RESUMED_TYPE,
+  WORKFLOW_RUN_STARTED_TYPE,
+  WORKFLOW_WAITING_TYPE,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { append, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { setupTestStack, type TestStack, TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { createSuspendedRunFetcher } from "../postgres-resume-loop";
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+function buildTestWorkflow(name: string): WorkflowDefinition {
+  return defineWorkflow({
+    name,
+    trigger: { kind: "event", eventType: "demo.fired" },
+    steps: stepsPipeline(({ r }) => [
+      r.step.wait({ for: "PT1H" }),
+      r.step.return({ isSuccess: true, data: undefined }),
+    ]),
+  });
+}
+
+describe("workflow-engine event-store roundtrip", () => {
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [] });
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("write and read WORKFLOW_WAITING_TYPE via event store", async () => {
+    const runId = crypto.randomUUID();
+
+    await insertOne(stack.db, eventsTable, {
+      aggregateId: runId,
+      aggregateType: WORKFLOW_AGGREGATE_TYPE,
+      tenantId: admin.tenantId,
+      version: 1,
+      type: WORKFLOW_RUN_STARTED_TYPE,
+      eventVersion: 1,
+      payload: { workflowName: "test-workflow", triggerEventType: "demo.fired" },
+      metadata: { userId: admin.id },
+      createdBy: admin.id,
+    });
+
+    await insertOne(stack.db, eventsTable, {
+      aggregateId: runId,
+      aggregateType: WORKFLOW_AGGREGATE_TYPE,
+      tenantId: admin.tenantId,
+      version: 2,
+      type: WORKFLOW_WAITING_TYPE,
+      eventVersion: 1,
+      payload: {
+        workflowName: "test-workflow",
+        stepIndex: 2,
+        wakeAt: new Date(Date.now() - 5000).toISOString(),
+      },
+      metadata: { userId: admin.id },
+      createdBy: admin.id,
+    });
+
+    const rows = await selectMany(
+      stack.db,
+      eventsTable,
+      { aggregateId: runId },
+      { orderBy: { col: "version", direction: "asc" } },
+    );
+
+    expect(rows).toHaveLength(2);
+    expect(rows[0]!["type"]).toBe(WORKFLOW_RUN_STARTED_TYPE);
+    expect(rows[1]!["type"]).toBe(WORKFLOW_WAITING_TYPE);
+    expect(rows[1]!["payload"]["workflowName"]).toBe("test-workflow");
+    expect(rows[1]!["payload"]["stepIndex"]).toBe(2);
+  });
+
+  test("fetcher hydrates SuspendableRun with workflow + trigger snapshot + Q7 fingerprint", async () => {
+    const runId = crypto.randomUUID();
+    const workflow = buildTestWorkflow("test-workflow-hydration");
+    const fingerprint = computeDefinitionFingerprint(workflow);
+
+    const sourceAggregateId = crypto.randomUUID();
+    const source = await append(stack.db, {
+      aggregateId: sourceAggregateId,
+      aggregateType: "demo-source",
+      tenantId: admin.tenantId,
+      expectedVersion: 0,
+      type: "demo.fired",
+      payload: { signal: "abc" },
+      metadata: { userId: admin.id },
+    });
+    await append(stack.db, {
+      aggregateId: runId,
+      aggregateType: WORKFLOW_AGGREGATE_TYPE,
+      tenantId: admin.tenantId,
+      expectedVersion: 0,
+      type: WORKFLOW_RUN_STARTED_TYPE,
+      payload: {
+        workflowName: "test-workflow-hydration",
+        triggerEventType: "demo.fired",
+        triggerEventRef: { eventId: source.id, aggregateId: sourceAggregateId, version: 1 },
+        definitionFingerprint: fingerprint,
+      },
+      metadata: { userId: admin.id },
+    });
+    await append(stack.db, {
+      aggregateId: runId,
+      aggregateType: WORKFLOW_AGGREGATE_TYPE,
+      tenantId: admin.tenantId,
+      expectedVersion: 1,
+      type: WORKFLOW_WAITING_TYPE,
+      payload: {
+        workflowName: "test-workflow-hydration",
+        stepIndex: 1,
+        wakeAt: new Date(Date.now() - 5000).toISOString(),
+        definitionFingerprint: fingerprint,
+      },
+      metadata: { userId: admin.id },
+    });
+
+    const registry = new Map([["test-workflow-hydration", workflow]]);
+    const fetchRuns = createSuspendedRunFetcher(stack.db, registry);
+    const suspended = await fetchRuns();
+
+    const match = suspended.find((r) => r.runId === runId);
+    expect(match).toBeDefined();
+    expect(match!.workflowName).toBe("test-workflow-hydration");
+    expect(match!.stepIndex).toBe(1);
+    expect(match!.workflow).toBe(workflow);
+    expect(match!.definitionFingerprint).toBe(fingerprint);
+    expect(match!.triggerEvent).toMatchObject({
+      type: "demo.fired",
+      aggregateId: sourceAggregateId,
+      payload: { signal: "abc" },
+    });
+  });
+
+  test("fetcher skips workflows that are not in the registry", async () => {
+    const runId = crypto.randomUUID();
+
+    await insertOne(stack.db, eventsTable, {
+      aggregateId: runId,
+      aggregateType: WORKFLOW_AGGREGATE_TYPE,
+      tenantId: admin.tenantId,
+      version: 1,
+      type: WORKFLOW_WAITING_TYPE,
+      eventVersion: 1,
+      payload: {
+        workflowName: "unregistered-workflow",
+        stepIndex: 0,
+        wakeAt: new Date(Date.now() - 5000).toISOString(),
+      },
+      metadata: { userId: admin.id },
+      createdBy: admin.id,
+    });
+
+    const fetchRuns = createSuspendedRunFetcher(stack.db, new Map());
+    const suspended = await fetchRuns();
+
+    expect(suspended.find((r) => r.runId === runId)).toBeUndefined();
+  });
+
+  test("WORKFLOW_RESUMED_TYPE appends after WAITING on the same stream", async () => {
+    const runId = crypto.randomUUID();
+
+    await insertOne(stack.db, eventsTable, {
+      aggregateId: runId,
+      aggregateType: WORKFLOW_AGGREGATE_TYPE,
+      tenantId: admin.tenantId,
+      version: 1,
+      type: WORKFLOW_WAITING_TYPE,
+      eventVersion: 1,
+      payload: {
+        workflowName: "test-workflow",
+        stepIndex: 2,
+        wakeAt: new Date(Date.now() - 5000).toISOString(),
+      },
+      metadata: { userId: admin.id },
+      createdBy: admin.id,
+    });
+
+    await insertOne(stack.db, eventsTable, {
+      aggregateId: runId,
+      aggregateType: WORKFLOW_AGGREGATE_TYPE,
+      tenantId: admin.tenantId,
+      version: 2,
+      type: WORKFLOW_RESUMED_TYPE,
+      eventVersion: 1,
+      payload: { stepIndex: 2 },
+      metadata: { userId: admin.id },
+      createdBy: admin.id,
+    });
+
+    const rows = await selectMany(
+      stack.db,
+      eventsTable,
+      { aggregateId: runId },
+      { orderBy: { col: "version", direction: "asc" } },
+    );
+
+    expect(rows).toHaveLength(2);
+    expect(rows[0]!["type"]).toBe(WORKFLOW_WAITING_TYPE);
+    expect(rows[1]!["type"]).toBe(WORKFLOW_RESUMED_TYPE);
+  });
+});
+```
+
+### src/__tests__/workflow-integration.test.ts
+
+```ts
+import { describe, expect, it, mock } from "bun:test";
+import {
+  computeDefinitionFingerprint,
+  defineWorkflow,
+  STEP_DISPATCH_REQUESTED_TYPE,
+  stepsPipeline,
+  type WorkflowDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { VersionConflictError } from "@cosmicdrift/kumiko-framework/event-store";
+import { type CronWorkflow, nextCronDate, runDueCronWorkflows } from "../cron-scheduler";
+import { registerEventTrigger } from "../event-trigger";
+import {
+  dailyReportWorkflow,
+  userOnboardingSteps,
+  userOnboardingWorkflow,
+  webhookDeliveryWorkflow,
+} from "../feature";
+import { createInMemorySuspendedRunFetcher } from "../postgres-resume-loop";
+import { runResumeLoop, type SuspendableRun } from "../resume-loop";
+import { startAndRunWorkflow } from "../workflow-runner";
+
+function makeWaitWorkflow(name: string) {
+  return defineWorkflow({
+    name,
+    trigger: { kind: "event", eventType: "demo.fired" },
+    steps: stepsPipeline(({ r }) => [
+      r.step.wait({ for: "PT1H" }),
+      r.step.return({ isSuccess: true, data: { result: "resumed" } }),
+    ]),
+  });
+}
+
+function makeReturnOnlyWorkflow(name: string) {
+  return defineWorkflow({
+    name,
+    trigger: { kind: "event", eventType: "demo.fired" },
+    steps: stepsPipeline(({ r }) => [r.step.return({ isSuccess: true, data: undefined })]),
+  });
+}
+
+describe("workflow-engine", () => {
+  it("defineWorkflow returns a valid WorkflowDefinition", () => {
+    expect(userOnboardingWorkflow.__kind).toBe("workflow");
+    expect(userOnboardingWorkflow.name).toBe("user-onboarding");
+    const trigger = userOnboardingWorkflow.trigger;
+    if (trigger.kind !== "event") throw new Error("expected event trigger");
+    expect(trigger.eventType).toBe("user.signed-up");
+    expect(typeof userOnboardingWorkflow.idempotencyKey).toBe("function");
+  });
+
+  it("defines a webhook-delivery workflow with event trigger", () => {
+    expect(webhookDeliveryWorkflow.__kind).toBe("workflow");
+    expect(webhookDeliveryWorkflow.name).toBe("webhook-delivery");
+    const trigger = webhookDeliveryWorkflow.trigger;
+    if (trigger.kind !== "event") throw new Error("expected event trigger");
+    expect(trigger.eventType).toBe("data.processed");
+  });
+
+  it("webhook-delivery completes with exactly one dispatch request", async () => {
+    const ctx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+
+    const result = await startAndRunWorkflow({
+      runId: "wf-webhook-delivery-1",
+      workflow: webhookDeliveryWorkflow as unknown as WorkflowDefinition,
+      triggerEvent: {
+        aggregateId: "agg_1",
+        type: "data.processed",
+        payload: { data: { id: 7 }, webhookUrl: "https://hooks.example.com/in" },
+      } as never,
+      handlerCtx: ctx as never,
+    });
+
+    expect(result.outcome).toBe("completed");
+    const dispatchRequests = ctx.unsafeAppendEvent.mock.calls
+      .map(([event]) => event as { type: string; payload: Record<string, unknown> })
+      .filter((event) => event.type === STEP_DISPATCH_REQUESTED_TYPE);
+    expect(dispatchRequests).toHaveLength(1);
+    expect(dispatchRequests[0]?.payload["url"]).toBe("https://hooks.example.com/in");
+    expect(dispatchRequests[0]?.payload["bodyJson"]).toBe(JSON.stringify({ id: 7 }));
+  });
+
+  it("defines a daily-report workflow with cron trigger", () => {
+    expect(dailyReportWorkflow.__kind).toBe("workflow");
+    expect(dailyReportWorkflow.name).toBe("daily-report");
+    const trigger = dailyReportWorkflow.trigger;
+    if (trigger.kind !== "cron") throw new Error("expected cron trigger");
+    expect(trigger.schedule).toBe("0 9 * * *");
+  });
+
+  it("workflow stores an idempotency key resolver for event-triggered workflows", () => {
+    const key = (
+      userOnboardingWorkflow.idempotencyKey as (e: { payload: { userId: string } }) => string
+    )({
+      payload: { userId: "user_123" },
+    });
+    expect(key).toBe("onboarding:user_123");
+  });
+});
+
+describe("workflow-runner", () => {
+  function makeAppendOnlyCtx() {
+    return { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+  }
+
+  it("startAndRunWorkflow writes run.started with Q7 snapshot fingerprint, then runs the pipeline to completion when no suspension", async () => {
+    const workflow = defineWorkflow({
+      name: "demo-sync",
+      trigger: { kind: "event", eventType: "demo.fired" },
+      steps: stepsPipeline(({ r }) => [r.step.return({ isSuccess: true, data: undefined })]),
+    });
+    const ctx = makeAppendOnlyCtx();
+
+    const result = await startAndRunWorkflow({
+      runId: "wf-demo-sync-1",
+      workflow,
+      triggerEvent: { aggregateId: "agg_1", type: "demo.fired", payload: {} } as never,
+      handlerCtx: ctx as never,
+    });
+
+    expect(result.outcome).toBe("completed");
+    expect(ctx.unsafeAppendEvent).toHaveBeenCalledTimes(2);
+    const started = ctx.unsafeAppendEvent.mock.calls[0]![0] as {
+      type: string;
+      payload: Record<string, unknown>;
+    };
+    expect(started.type).toBe("kumiko:system:workflow.run-started");
+    expect(started.payload["definitionFingerprint"]).toBe(computeDefinitionFingerprint(workflow));
+    expect(started.payload["triggerEventType"]).toBe("demo.fired");
+    const completed = ctx.unsafeAppendEvent.mock.calls[1]![0] as { type: string };
+    expect(completed.type).toBe("kumiko:system:workflow.run-completed");
+  });
+
+  it("startAndRunWorkflow returns outcome=suspended and stamps fingerprint into the waiting event", async () => {
+    const workflow = defineWorkflow({
+      name: "demo-wait",
+      trigger: { kind: "event", eventType: "demo.fired" },
+      steps: stepsPipeline(({ r }) => [
+        r.step.wait({ for: "PT1H" }),
+        r.step.return({ isSuccess: true, data: undefined }),
+      ]),
+    });
+    const ctx = makeAppendOnlyCtx();
+
+    const result = await startAndRunWorkflow({
+      runId: "wf-demo-wait-1",
+      workflow,
+      triggerEvent: { aggregateId: "agg_1", type: "demo.fired", payload: {} } as never,
+      handlerCtx: ctx as never,
+    });
+
+    expect(result.outcome).toBe("suspended");
+    // run.started + workflow.step.waiting — no run-completed yet
+    expect(ctx.unsafeAppendEvent).toHaveBeenCalledTimes(2);
+    const waiting = ctx.unsafeAppendEvent.mock.calls[1]![0] as {
+      type: string;
+      payload: Record<string, unknown>;
+    };
+    expect(waiting.type).toBe("kumiko:system:workflow.step.waiting");
+    expect(waiting.payload["definitionFingerprint"]).toBe(computeDefinitionFingerprint(workflow));
+  });
+
+  it("idempotencyKey ends up in the run.started payload when provided", async () => {
+    const workflow = defineWorkflow({
+      name: "demo-idem",
+      trigger: { kind: "event", eventType: "demo.fired" },
+      idempotencyKey: ({ payload }) => `id:${(payload as { x: string }).x}`,
+      steps: stepsPipeline(({ r }) => [r.step.return({ isSuccess: true, data: undefined })]),
+    });
+    const ctx = makeAppendOnlyCtx();
+
+    await startAndRunWorkflow({
+      runId: "wf-demo-idem-1",
+      workflow,
+      triggerEvent: { aggregateId: "agg_1", type: "demo.fired", payload: { x: "abc" } } as never,
+      idempotencyKey: "id:abc",
+      handlerCtx: ctx as never,
+    });
+
+    const started = ctx.unsafeAppendEvent.mock.calls[0]![0] as { payload: Record<string, unknown> };
+    expect(started.payload["idempotencyKey"]).toBe("id:abc");
+  });
+});
+
+describe("userOnboardingWorkflow (end-to-end, in-memory)", () => {
+  it("suspends on the first wait, then resume-loop runs it through to completion", async () => {
+    const ctx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+    const trigger = {
+      aggregateId: "agg_user_42",
+      type: "user.signed-up",
+      payload: { email: "x@example.com", userId: "active-42" },
+    };
+
+    const result = await startAndRunWorkflow({
+      runId: "wf-onboarding-active-42",
+      workflow: userOnboardingWorkflow as unknown as WorkflowDefinition,
+      triggerEvent: trigger as never,
+      triggerEventRef: { eventId: "1", aggregateId: trigger.aggregateId, version: 1 },
+      idempotencyKey: "onboarding:active-42",
+      handlerCtx: ctx as never,
+    });
+
+    expect(result.outcome).toBe("suspended");
+    // Calls: run.started, mail.send dispatch-requested, workflow.step.waiting
+    expect(ctx.unsafeAppendEvent).toHaveBeenCalledTimes(3);
+    const startedCall = ctx.unsafeAppendEvent.mock.calls[0]![0] as {
+      type: string;
+      payload: Record<string, unknown>;
+    };
+    const mailCall = ctx.unsafeAppendEvent.mock.calls[1]![0] as {
+      type: string;
+      payload: Record<string, unknown>;
+    };
+    const waitingCall = ctx.unsafeAppendEvent.mock.calls[2]![0] as {
+      type: string;
+      payload: Record<string, unknown>;
+    };
+    expect(startedCall.type).toBe("kumiko:system:workflow.run-started");
+    expect(mailCall.type).toBe("kumiko:system:step.dispatch-requested");
+    expect((mailCall.payload as { stepKind: string }).stepKind).toBe("mail.send");
+    expect(waitingCall.type).toBe("kumiko:system:workflow.step.waiting");
+    expect(waitingCall.payload["definitionFingerprint"]).toBe(
+      computeDefinitionFingerprint(userOnboardingWorkflow as unknown as WorkflowDefinition),
+    );
+
+    // The run stream holds a reference, never a copy of the trigger payload.
+    expect(startedCall.payload["triggerEventRef"]).toEqual({
+      eventId: "1",
+      aggregateId: "agg_user_42",
+      version: 1,
+    });
+    expect(startedCall.payload).not.toHaveProperty("triggerPayload");
+    expect(waitingCall.payload).not.toHaveProperty("triggerPayload");
+
+    // Re-feed the run through the resume-loop using the fingerprint the
+    // waiting event carries — the loop runs the rest of the pipeline. The
+    // trigger event is what the event store returns for the reference.
+    const triggerSnapshot = trigger;
+    const suspendedRun: SuspendableRun = {
+      runId: "wf-onboarding-active-42",
+      workflowName: "user-onboarding",
+      stepIndex: waitingCall.payload["stepIndex"] as number,
+      wakeAt: Temporal.Now.instant().subtract({ seconds: 1 }).toString(),
+      suspensionEventType: "kumiko:system:workflow.step.waiting",
+      workflow: userOnboardingWorkflow as unknown as WorkflowDefinition,
+      triggerEvent: triggerSnapshot as never,
+      definitionFingerprint: waitingCall.payload["definitionFingerprint"] as string,
+    };
+
+    const resumeCtx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+    const count = await runResumeLoop(
+      createInMemorySuspendedRunFetcher([suspendedRun]),
+      resumeCtx as never,
+    );
+
+    expect(count).toBe(1);
+    // Resume sequence: RESUMED, branch fires the tips-mail (engaged=true
+    // because userId starts with "active-"), second WAITING for P7D.
+    // The run is suspended again before the webhook, so no RUN_COMPLETED
+    // yet — this is one resume-cycle, not the whole workflow.
+    const resumeTypes = resumeCtx.unsafeAppendEvent.mock.calls.map(
+      (c) => (c[0] as { type: string }).type,
+    );
+    expect(resumeTypes).toEqual([
+      "kumiko:system:workflow.step.resumed",
+      "kumiko:system:step.dispatch-requested",
+      "kumiko:system:workflow.step.waiting",
+    ]);
+    const tipsMail = resumeCtx.unsafeAppendEvent.mock.calls[1]![0] as {
+      payload: { subject: string };
+    };
+    expect(tipsMail.payload.subject).toBe("Engagement tips");
+  });
+
+  it("not-engaged path picks the reminder branch", async () => {
+    const ctx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+    const trigger = {
+      aggregateId: "agg_user_cold",
+      type: "user.signed-up",
+      payload: { email: "cold@example.com", userId: "cold-1" },
+    };
+    await startAndRunWorkflow({
+      runId: "wf-onboarding-cold-1",
+      workflow: userOnboardingWorkflow as unknown as WorkflowDefinition,
+      triggerEvent: trigger as never,
+      triggerEventRef: { eventId: "2", aggregateId: trigger.aggregateId, version: 1 },
+      handlerCtx: ctx as never,
+    });
+    const waiting = ctx.unsafeAppendEvent.mock.calls[2]![0] as { payload: Record<string, unknown> };
+    const suspendedRun: SuspendableRun = {
+      runId: "wf-onboarding-cold-1",
+      workflowName: "user-onboarding",
+      stepIndex: waiting.payload["stepIndex"] as number,
+      wakeAt: Temporal.Now.instant().subtract({ seconds: 1 }).toString(),
+      suspensionEventType: "kumiko:system:workflow.step.waiting",
+      workflow: userOnboardingWorkflow as unknown as WorkflowDefinition,
+      triggerEvent: trigger as never,
+      definitionFingerprint: waiting.payload["definitionFingerprint"] as string,
+    };
+    const resumeCtx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+    await runResumeLoop(createInMemorySuspendedRunFetcher([suspendedRun]), resumeCtx as never);
+
+    const reminderMail = resumeCtx.unsafeAppendEvent.mock.calls[1]![0] as {
+      payload: { subject: string };
+    };
+    expect(reminderMail.payload.subject).toBe("Getting started");
+  });
+});
+
+describe("computeDefinitionFingerprint", () => {
+  it("returns the same fingerprint for the same definition", () => {
+    const a = defineWorkflow({
+      name: "wf",
+      trigger: { kind: "event", eventType: "x" },
+      steps: stepsPipeline(({ r }) => [r.step.return({ isSuccess: true, data: undefined })]),
+    });
+    const b = defineWorkflow({
+      name: "wf",
+      trigger: { kind: "event", eventType: "x" },
+      steps: stepsPipeline(({ r }) => [r.step.return({ isSuccess: true, data: undefined })]),
+    });
+    expect(computeDefinitionFingerprint(a)).toBe(computeDefinitionFingerprint(b));
+  });
+
+  it("returns a different fingerprint when the pipeline source changes", () => {
+    const a = defineWorkflow({
+      name: "wf",
+      trigger: { kind: "event", eventType: "x" },
+      steps: stepsPipeline(({ r }) => [r.step.return({ isSuccess: true, data: undefined })]),
+    });
+    const b = defineWorkflow({
+      name: "wf",
+      trigger: { kind: "event", eventType: "x" },
+      steps: stepsPipeline(({ r }) => [
+        r.step.compute("noop", () => 1),
+        r.step.return({ isSuccess: true, data: undefined }),
+      ]),
+    });
+    expect(computeDefinitionFingerprint(a)).not.toBe(computeDefinitionFingerprint(b));
+  });
+
+  it("returns a different fingerprint when the trigger changes", () => {
+    const a = defineWorkflow({
+      name: "wf",
+      trigger: { kind: "event", eventType: "x" },
+      steps: stepsPipeline(({ r }) => [r.step.return({ isSuccess: true, data: undefined })]),
+    });
+    const b = defineWorkflow({
+      name: "wf",
+      trigger: { kind: "event", eventType: "y" },
+      steps: stepsPipeline(({ r }) => [r.step.return({ isSuccess: true, data: undefined })]),
+    });
+    expect(computeDefinitionFingerprint(a)).not.toBe(computeDefinitionFingerprint(b));
+  });
+});
+
+describe("event-trigger", () => {
+  it("registerEventTrigger creates MSP for event-kind workflows", () => {
+    const registrations: unknown[] = [];
+    const mockRegistrar = {
+      multiStreamProjection: (def: unknown) => {
+        registrations.push(def);
+      },
+    };
+
+    registerEventTrigger(
+      mockRegistrar as never,
+      userOnboardingWorkflow as unknown as WorkflowDefinition,
+    );
+
+    expect(registrations).toHaveLength(1);
+    const msp = registrations[0] as Record<string, unknown>;
+    expect(msp["name"]).toBe("workflow-user-onboarding");
+    expect(typeof (msp["apply"] as Record<string, unknown>)["user.signed-up"]).toBe("function");
+  });
+
+  it("registerEventTrigger skips non-event workflows", () => {
+    const registrations: unknown[] = [];
+    const mockRegistrar = {
+      multiStreamProjection: (def: unknown) => {
+        registrations.push(def);
+      },
+    };
+
+    registerEventTrigger(
+      mockRegistrar as never,
+      dailyReportWorkflow as unknown as WorkflowDefinition,
+    );
+
+    expect(registrations).toHaveLength(0);
+  });
+
+  it("userOnboardingSteps is a valid pipeline", () => {
+    expect(userOnboardingSteps.__kind).toBe("pipeline");
+    expect(typeof userOnboardingSteps.build).toBe("function");
+  });
+});
+
+describe("cron-scheduler", () => {
+  it("nextCronDate computes the next run time", () => {
+    const base = Temporal.Instant.from("2025-06-01T00:00:00Z");
+    const next = nextCronDate("30 9 * * *", base);
+    expect(next).not.toBeNull();
+    const zdt = next!.toZonedDateTimeISO("UTC");
+    expect(zdt.hour).toBe(9);
+    expect(zdt.minute).toBe(30);
+    expect(zdt.day).toBe(1);
+  });
+
+  it("nextCronDate returns null for invalid cron expressions", () => {
+    expect(nextCronDate("invalid", Temporal.Now.instant())).toBeNull();
+    expect(nextCronDate("", Temporal.Now.instant())).toBeNull();
+  });
+
+  it("nextCronDate advances to next day if time already passed", () => {
+    const base = Temporal.Instant.from("2025-06-01T10:00:00Z");
+    const next = nextCronDate("30 9 * * *", base);
+    const zdt = next!.toZonedDateTimeISO("UTC");
+    // 09:30 already passed on June 1 → next is June 2 at 09:30
+    expect(zdt.day).toBe(2);
+    expect(zdt.hour).toBe(9);
+    expect(zdt.minute).toBe(30);
+  });
+
+  it("runDueCronWorkflows skips not-yet-due workflows", async () => {
+    const wf = defineWorkflow({
+      name: "test-daily",
+      trigger: { kind: "cron", schedule: "0 9 * * *" },
+      steps: stepsPipeline(({ r }) => [r.step.return({ isSuccess: true, data: undefined })]),
+    });
+
+    const handlerCtx = { unsafeAppendEvent: mock() };
+    const lastRuns = new Map<string, Temporal.Instant>();
+    const now = Temporal.Instant.from("2025-06-01T08:00:00Z");
+
+    const count = await runDueCronWorkflows(
+      [wf as CronWorkflow],
+      lastRuns,
+      now,
+      handlerCtx as never,
+    );
+
+    expect(count).toBe(0);
+    expect(handlerCtx.unsafeAppendEvent).not.toHaveBeenCalled();
+  });
+
+  it("runDueCronWorkflows runs due workflows through the full start path", async () => {
+    const wf = defineWorkflow({
+      name: "test-daily",
+      trigger: { kind: "cron", schedule: "0 9 * * *" },
+      steps: stepsPipeline(({ r }) => [r.step.return({ isSuccess: true, data: undefined })]),
+    });
+
+    const handlerCtx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+    const lastRuns = new Map<string, Temporal.Instant>();
+    const lastRun = Temporal.Instant.from("2025-05-31T08:00:00Z");
+    lastRuns.set("test-daily", lastRun);
+    const now = Temporal.Instant.from("2025-06-01T09:01:00Z");
+
+    const count = await runDueCronWorkflows(
+      [wf as CronWorkflow],
+      lastRuns,
+      now,
+      handlerCtx as never,
+    );
+
+    expect(count).toBe(1);
+    // run.started + run-completed (no suspension, pipeline returns immediately).
+    expect(handlerCtx.unsafeAppendEvent).toHaveBeenCalledTimes(2);
+    const started = handlerCtx.unsafeAppendEvent.mock.calls[0]![0] as Record<string, unknown>;
+    expect(started["type"]).toBe("kumiko:system:workflow.run-started");
+    const completed = handlerCtx.unsafeAppendEvent.mock.calls[1]![0] as Record<string, unknown>;
+    expect(completed["type"]).toBe("kumiko:system:workflow.run-completed");
+  });
+});
+
+describe("resume-loop", () => {
+  it("returns 0 when no suspended runs exist", async () => {
+    const fetchRuns = createInMemorySuspendedRunFetcher([]);
+    const handlerCtx = { unsafeAppendEvent: mock() };
+
+    const count = await runResumeLoop(fetchRuns, handlerCtx as never);
+
+    expect(count).toBe(0);
+    expect(handlerCtx.unsafeAppendEvent).not.toHaveBeenCalled();
+  });
+
+  it("resumes a suspended run", async () => {
+    const workflow = makeWaitWorkflow("test-workflow");
+    const suspendedRun: SuspendableRun = {
+      runId: "wf-test-run_123",
+      workflowName: "test-workflow",
+      stepIndex: 0,
+      wakeAt: Temporal.Now.instant().subtract({ seconds: 1 }).toString(),
+      suspensionEventType: "kumiko:system:workflow.step.waiting",
+      workflow,
+      triggerEvent: { aggregateId: "agg_1", type: "demo.fired", payload: {} } as never,
+      definitionFingerprint: computeDefinitionFingerprint(workflow),
+    };
+
+    const fetchRuns = createInMemorySuspendedRunFetcher([suspendedRun]);
+    const handlerCtx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+
+    const count = await runResumeLoop(fetchRuns, handlerCtx as never);
+
+    expect(count).toBe(1);
+    expect(handlerCtx.unsafeAppendEvent).toHaveBeenCalledTimes(2);
+    expect(handlerCtx.unsafeAppendEvent).toHaveBeenNthCalledWith(1, {
+      aggregateId: "wf-test-run_123",
+      aggregateType: "workflow-run",
+      type: "kumiko:system:workflow.step.resumed",
+      payload: { stepIndex: 0, retryAttempt: undefined },
+    });
+    expect(handlerCtx.unsafeAppendEvent).toHaveBeenNthCalledWith(2, {
+      aggregateId: "wf-test-run_123",
+      aggregateType: "workflow-run",
+      type: "kumiko:system:workflow.run-completed",
+      payload: { stepIndex: 0 },
+    });
+  });
+
+  it("fails loud (RUN_FAILED + reason workflow_definition_changed) when the fingerprint diverges", async () => {
+    const workflow = makeWaitWorkflow("test-workflow-drift");
+    const suspendedRun: SuspendableRun = {
+      runId: "wf-drift-run",
+      workflowName: "test-workflow-drift",
+      stepIndex: 0,
+      wakeAt: Temporal.Now.instant().subtract({ seconds: 1 }).toString(),
+      suspensionEventType: "kumiko:system:workflow.step.waiting",
+      workflow,
+      triggerEvent: { aggregateId: "agg_y", type: "demo.fired", payload: {} } as never,
+      definitionFingerprint: "stale-fingerprint-from-an-older-deploy",
+    };
+
+    const fetchRuns = createInMemorySuspendedRunFetcher([suspendedRun]);
+    const handlerCtx = { unsafeAppendEvent: mock().mockResolvedValue(undefined) };
+
+    const count = await runResumeLoop(fetchRuns, handlerCtx as never);
+
+    expect(count).toBe(0);
+    expect(handlerCtx.unsafeAppendEvent).toHaveBeenCalledTimes(1);
+    const failed = handlerCtx.unsafeAppendEvent.mock.calls[0]![0] as {
+      type: string;
+      payload: Record<string, unknown>;
+    };
+    expect(failed.type).toBe("kumiko:system:workflow.run-failed");
+    expect(failed.payload["reason"]).toBe("workflow_definition_changed");
+    expect(failed.payload["error"]).toContain("definition changed");
+  });
+
+  it("skips a run silently when the resume-claim hits VersionConflictError", async () => {
+    const workflow = makeWaitWorkflow("test-workflow-conflict");
+    const suspendedRun: SuspendableRun = {
+      runId: "wf-conflict-run",
+      workflowName: "test-workflow-conflict",
+      stepIndex: 0,
+      wakeAt: Temporal.Now.instant().subtract({ seconds: 1 }).toString(),
+      suspensionEventType: "kumiko:system:workflow.step.waiting",
+      workflow,
+      triggerEvent: { aggregateId: "agg_x", type: "demo.fired", payload: {} } as never,
+      definitionFingerprint: computeDefinitionFingerprint(workflow),
+    };
+
+    const fetchRuns = createInMemorySuspendedRunFetcher([suspendedRun]);
+    const handlerCtx = {
+      unsafeAppendEvent: mock()
+        .mockRejectedValueOnce(new VersionConflictError("wf-conflict-run", 1))
+        .mockResolvedValue(undefined),
+    };
+
+    const count = await runResumeLoop(fetchRuns, handlerCtx as never);
+
+    expect(count).toBe(0);
+    expect(handlerCtx.unsafeAppendEvent).toHaveBeenCalledTimes(1);
+    expect((handlerCtx.unsafeAppendEvent.mock.calls[0]![0] as { type: string }).type).toBe(
+      "kumiko:system:workflow.step.resumed",
+    );
+  });
+
+  it("createInMemorySuspendedRunFetcher returns runs with workflow intact", async () => {
+    const workflow = makeReturnOnlyWorkflow("test-fetcher");
+    const run: SuspendableRun = {
+      runId: "wf-test-pipeline",
+      workflowName: "test-fetcher",
+      stepIndex: 0,
+      wakeAt: "2025-06-01T00:00:00Z",
+      workflow,
+      triggerEvent: { aggregateId: "a", type: "demo.fired", payload: {} } as never,
+      suspensionEventType: "kumiko:system:workflow.step.waiting",
+    };
+
+    const fetchRuns = createInMemorySuspendedRunFetcher([run]);
+    const result = await fetchRuns();
+
+    expect(result).toHaveLength(1);
+    expect(typeof result[0]!.workflow.pipelineDef.build).toBe("function");
+  });
+});
+```
+
+### src/cron-scheduler.ts
+
+```ts
+// cron-scheduler — schedules and triggers cron-based workflows.
+//
+// Each tick (default 60s) checks whether a cron workflow is due and runs it
+// through the same `startAndRunWorkflow` path the event-trigger uses.
+// Production setups should swap the tick-loop for a persistent scheduler
+// (pg_cron, BullMQ) — the sample provides Bun.Timer + a manual entrypoint.
+
+import type { HandlerContext, WorkflowDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { v4 as uuid } from "uuid";
+import { startAndRunWorkflow } from "./workflow-runner";
+
+export type CronWorkflow = WorkflowDefinition & {
+  readonly trigger: { readonly kind: "cron"; readonly schedule: string };
+};
+
+// Parse a cron expression in the format "minute hour * * *" and return
+// the next scheduled Instant (UTC), or null if invalid. Wildcards for
+// day/month/weekday are accepted; numeric minute+hour required.
+export function nextCronDate(schedule: string, since: Temporal.Instant): Temporal.Instant | null {
+  const parts = schedule.trim().split(/\s+/);
+  if (parts.length < 5) return null;
+  const [minStr, hourStr] = parts;
+  if (minStr === undefined || hourStr === undefined) return null;
+
+  const cronMin = parseInt(minStr, 10);
+  const cronHour = parseInt(hourStr, 10);
+  if (Number.isNaN(cronMin) || Number.isNaN(cronHour)) return null;
+
+  // Move to the same-day candidate at cronHour:cronMin (UTC), then bump
+  // by one day until strictly after `since`.
+  let candidate = since.toZonedDateTimeISO("UTC").with({
+    hour: cronHour,
+    minute: cronMin,
+    second: 0,
+    millisecond: 0,
+    microsecond: 0,
+    nanosecond: 0,
+  });
+  while (Temporal.Instant.compare(candidate.toInstant(), since) <= 0) {
+    candidate = candidate.add({ days: 1 });
+  }
+  return candidate.toInstant();
+}
+
+/**
+ * Check if a cron workflow is due to run and execute it via the shared
+ * start-and-run path. Returns the number of workflow runs started.
+ */
+export async function runDueCronWorkflows(
+  workflows: readonly CronWorkflow[],
+  lastRuns: Map<string, Temporal.Instant>,
+  now: Temporal.Instant,
+  handlerCtx: HandlerContext,
+): Promise<number> {
+  let count = 0;
+
+  for (const wf of workflows) {
+    const lastRun = lastRuns.get(wf.name) ?? now;
+    const next = nextCronDate(wf.trigger.schedule, lastRun);
+
+    if (next && Temporal.Instant.compare(next, now) <= 0) {
+      const runId = `wf-${wf.name}-cron-${uuid()}`;
+      await startAndRunWorkflow({
+        runId,
+        workflow: wf,
+        triggerEvent: { aggregateId: runId, type: "cron", payload: {} } as never,
+        handlerCtx,
+      });
+      lastRuns.set(wf.name, now);
+      count++;
+    }
+  }
+
+  return count;
+}
+
+/**
+ * Create a Bun.Timer-based cron scheduler that periodically checks for
+ * due workflows and runs them.
+ */
+export function startCronScheduler(
+  workflows: readonly CronWorkflow[],
+  handlerCtx: HandlerContext,
+  intervalMs = 60_000,
+): { stop: () => void } {
+  const lastRuns = new Map<string, Temporal.Instant>();
+  let running = false;
+  let timer: ReturnType<typeof setInterval> | null = null;
+
+  async function tick() {
+    if (running) return;
+    running = true;
+    try {
+      await runDueCronWorkflows(workflows, lastRuns, Temporal.Now.instant(), handlerCtx);
+    } catch {
+      // Logged by the caller
+    } finally {
+      running = false;
+    }
+  }
+
+  timer = setInterval(tick, intervalMs);
+  void tick();
+
+  return {
+    stop: () => {
+      if (timer) clearInterval(timer);
+    },
+  };
+}
+```
+
+### src/db/queries/suspended-runs.ts
+
+```ts
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+
+export async function selectExpiredSuspensionEvents(
+  db: DbRunner,
+  eventTypes: readonly string[],
+): Promise<readonly Record<string, unknown>[]> {
+  return (await asRawClient(db).unsafe(
+    `SELECT * FROM "kumiko_events"
+       WHERE "type" = ANY($1::text[])
+       AND (("payload"->>'wakeAt')::timestamptz < now() OR ("payload"->>'timeoutAt')::timestamptz < now())`,
+    [eventTypes as unknown as string[]],
+  )) as Record<string, unknown>[];
+}
+```
+
+### src/event-trigger.ts
+
+```ts
+// event-trigger — MultiStreamProjection that listens for domain events and
+// starts + runs a workflow when the event matches a trigger.
+//
+// Registration pattern:
+//   registerEventTrigger(r, userOnboardingWorkflow)
+//
+// The MSP apply-fn runs in the dispatcher's tx, so the run.started event
+// plus the synchronous portion of the pipeline land atomically. If the
+// pipeline hits a Tier-3 suspension (wait/waitForEvent/retry), the apply
+// commits with the WAITING event written; the resume-loop wakes it later.
+
+import type {
+  FeatureRegistrar,
+  MultiStreamProjectionDefinition,
+  WorkflowDefinition,
+  WriteEvent,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  describeWorkflowStepError,
+  WORKFLOW_AGGREGATE_TYPE,
+  WORKFLOW_RUN_FAILED_TYPE,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { v4 as uuid } from "uuid";
+import { startAndRunWorkflow } from "./workflow-runner";
+
+export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefinition): void {
+  if (workflow.trigger.kind !== "event") return;
+
+  const eventType = workflow.trigger.eventType;
+
+  r.multiStreamProjection({
+    name: `workflow-${workflow.name}`,
+    apply: {
+      [eventType]: async (event, _tx, ctx) => {
+        if (workflow.trigger.kind !== "event") return;
+        if (workflow.trigger.filter) {
+          const matches = workflow.trigger.filter(event as never);
+          if (!matches) return;
+        }
+
+        // @cast-boundary msp-to-write-event — MSP receives StoredEvent
+        // (event-store shape), workflow runner expects WriteEvent (handler
+        // shape). The fields workflow steps read (type, payload) overlap
+        // exactly; the missing `.user` field on StoredEvent is acceptable
+        // because workflow triggers run system-level, not user-scoped.
+        const triggerEvent = event as unknown as WriteEvent;
+        let idempotencyKey: string | undefined;
+        if (typeof workflow.idempotencyKey === "function") {
+          idempotencyKey = workflow.idempotencyKey(triggerEvent);
+        } else if (typeof workflow.idempotencyKey === "string") {
+          idempotencyKey = workflow.idempotencyKey;
+        }
+
+        const runId = idempotencyKey
+          ? `wf-${workflow.name}-${idempotencyKey}`
+          : `wf-${workflow.name}-${uuid()}`;
+
+        try {
+          await startAndRunWorkflow({
+            runId,
+            workflow,
+            triggerEvent,
+            triggerEventRef: {
+              eventId: event.id,
+              aggregateId: event.aggregateId,
+              version: event.version,
+            },
+            ...(idempotencyKey && { idempotencyKey }),
+            handlerCtx: ctx as never,
+          });
+        } catch (error) {
+          await (
+            ctx as never as { unsafeAppendEvent: (a: unknown) => Promise<void> }
+          ).unsafeAppendEvent({
+            aggregateId: runId,
+            aggregateType: WORKFLOW_AGGREGATE_TYPE,
+            type: WORKFLOW_RUN_FAILED_TYPE,
+            payload: {
+              workflowName: workflow.name,
+              stepIndex: 0,
+              error: describeWorkflowStepError(error),
+            },
+          });
+          throw error;
+        }
+      },
+    },
+  } satisfies MultiStreamProjectionDefinition);
+}
+```
+
+### src/feature.ts
+
+```ts
+// workflow-engine Sample — M.4 Tier-3 step-vocabulary showcase.
+//
+// Demonstrates defineWorkflow with wait, branch, mail.send, webhook.send
+// and the workflow-run lifecycle. Each workflow below is a real,
+// runnable pipeline — no empty `build: () => []` stubs. The
+// integration-tests in __tests__/ exercise the suspension/resume cycle
+// against the in-memory fetcher and (separately) the postgres event-store.
+//
+// Mounting:
+//   - Event-triggered workflows register an MSP via `registerEventTrigger`
+//     (see feature() below). The MSP starts + runs the pipeline up to the
+//     first suspension; the resume-loop wakes it later.
+//   - Cron-triggered workflows are started by the `cron-scheduler` tick.
+//
+// M.4 Limitations (Followups, will land with M.5 / future slices):
+//   - The MSP apply-ctx exposes `unsafeAppendEvent` + `db` but not the
+//     full HandlerContext surface. `r.step.read.findOne` works (db is
+//     present), `r.step.callFeature` does NOT yet (no `write`/`writeAs`
+//     on apply-ctx). Pipelines should stick to compute / branch / wait /
+//     mail.send / webhook.send for now.
+//   - The fetcher reads every suspension row whose wakeAt has expired
+//     (no `workflow_run_pending` read-side projection yet). Concurrency
+//     is safe via the event-store version-conflict path; performance is
+//     adequate for the demo, not for high-volume production.
+
+import type { PipelineCtx, WorkflowDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature, defineWorkflow, stepsPipeline } from "@cosmicdrift/kumiko-framework/engine";
+import { registerEventTrigger } from "./event-trigger";
+
+/**
+ * User-onboarding workflow: welcome-mail → wait 1 day → branch on a
+ * computed engagement flag → either tips or reminder → wait 7 days →
+ * webhook to the CRM. Triggered by `user.signed-up`, deduped per userId.
+ *
+ * The engagement-flag is computed inline (no read.findOne in M.4 yet —
+ * see Limitations above). A real app would resolve the flag from the
+ * user-store via a Tier-1 read step once the apply-ctx → HandlerContext
+ * bridge lands.
+ */
+export const userOnboardingWorkflow: WorkflowDefinition<{ email: string; userId: string }, void> =
+  defineWorkflow({
+    name: "user-onboarding",
+    trigger: { kind: "event", eventType: "user.signed-up" },
+    idempotencyKey: ({ payload }) => `onboarding:${payload.userId}`,
+
+    steps: stepsPipeline<{ email: string; userId: string }, void>(({ r }) => [
+      r.step.mail.send({
+        to: (ctx) => (ctx.event.payload as { email: string }).email,
+        subject: "Welcome!",
+        body: "Thanks for signing up — we'll check in soon.",
+        mode: "deferred",
+      }),
+
+      r.step.wait({ for: "P1D" }),
+
+      // Engagement gate: demo-only inline flag. In a production sample this
+      // would be `r.step.read.findOne("user", { ... })` followed by a
+      // branch on `lastSeenAt`; deferred to the M.5 read-bridge.
+      r.step.compute("engaged", (ctx) => {
+        const userId = (ctx.event.payload as { userId: string }).userId;
+        return userId.startsWith("active-");
+      }),
+
+      r.step.branch({
+        if: (ctx) => (ctx.steps["engaged"] as boolean) === true,
+        onTrue: [
+          r.step.mail.send({
+            to: (ctx) => (ctx.event.payload as { email: string }).email,
+            subject: "Engagement tips",
+            body: "You're off to a great start — try these next.",
+            mode: "deferred",
+          }),
+        ],
+        onFalse: [
+          r.step.mail.send({
+            to: (ctx) => (ctx.event.payload as { email: string }).email,
+            subject: "Getting started",
+            body: "Need a hand? Here's how to begin.",
+            mode: "deferred",
+          }),
+        ],
+      }),
+
+      r.step.wait({ for: "P7D" }),
+
+      r.step.webhook.send({
+        url: "https://hooks.example.com/crm-onboarding",
+        method: "POST",
+        body: (ctx: PipelineCtx) => ({
+          userId: (ctx.event.payload as { userId: string }).userId,
+          stage: "day8",
+        }),
+        mode: "deferred",
+      }),
+
+      r.step.return({ isSuccess: true, data: undefined }),
+    ]),
+  });
+
+/**
+ * Webhook-delivery workflow: one deferred webhook per `data.processed` event.
+ * `webhook.send` only enqueues a dispatch request; the step-dispatcher
+ * delivers it once and a failed delivery ends as `step.dispatch-failed`. A
+ * `retry` around it would never fire, because the step itself cannot throw
+ * on a delivery error.
+ */
+export const webhookDeliveryWorkflow: WorkflowDefinition<
+  { data: unknown; webhookUrl: string },
+  void
+> = defineWorkflow({
+  name: "webhook-delivery",
+  trigger: { kind: "event", eventType: "data.processed" },
+
+  steps: stepsPipeline<{ data: unknown; webhookUrl: string }, void>(({ r }) => [
+    r.step.webhook.send({
+      url: (ctx: PipelineCtx) => (ctx.event.payload as { webhookUrl: string }).webhookUrl,
+      body: (ctx: PipelineCtx) => (ctx.event.payload as { data: unknown }).data,
+      mode: "deferred",
+    }),
+    r.step.return({ isSuccess: true, data: undefined }),
+  ]),
+});
+
+/**
+ * Daily-report workflow: cron-triggered, single deferred webhook.
+ */
+export const dailyReportWorkflow: WorkflowDefinition<void, void> = defineWorkflow({
+  name: "daily-report",
+  trigger: { kind: "cron", schedule: "0 9 * * *" },
+
+  steps: stepsPipeline<void, void>(({ r }) => [
+    r.step.webhook.send({
+      url: "https://hooks.example.com/daily-report",
+      body: () => ({ ts: Temporal.Now.instant().toString() }),
+      mode: "deferred",
+    }),
+    r.step.return({ isSuccess: true, data: undefined }),
+  ]),
+});
+
+/**
+ * Workflow-engine feature registers MSP subscriptions for every event-
+ * triggered workflow. Cron-triggered workflows are picked up by the
+ * cron-scheduler.tick() in production wiring; the feature itself doesn't
+ * own them.
+ */
+export const workflowEngineFeature = defineFeature("workflowEngine", (r) => {
+  // @cast-boundary workflow-payload-variance — registerEventTrigger's
+  // WorkflowDefinition<unknown> can't directly accept WorkflowDefinition<{...}>
+  // because the embedded pipeline closure is contravariant in TPayload.
+  // The runtime only touches trigger/name/idempotencyKey + executes
+  // the closure with the real event payload — payload-agnostic.
+  registerEventTrigger(r, userOnboardingWorkflow as unknown as WorkflowDefinition);
+  registerEventTrigger(r, webhookDeliveryWorkflow as unknown as WorkflowDefinition);
+  // dailyReportWorkflow is cron-triggered — skip MSP registration
+});
+
+/**
+ * Compat-Export — the unit-test file references this. It's just the
+ * onboarding workflow's pipelineDef pulled out so the test can assert
+ * its shape independently from the workflow definition.
+ */
+export const userOnboardingSteps = userOnboardingWorkflow.pipelineDef;
+```
+
+### src/postgres-resume-loop.ts
+
+```ts
+// postgres-resume-loop — fetchSuspendedRuns implementations.
+//
+// Two flavours:
+//   1. createSuspendedRunFetcher(db, workflowRegistry) — Postgres-backed
+//   2. createInMemorySuspendedRunFetcher(runs) — for unit tests
+//
+// The fetcher reads the Q7 fingerprint from the suspension event payload and
+// re-loads the trigger event from the event store through the
+// triggerEventRef on the run's own run.started event (no payload copy lives
+// on the run stream).
+
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId, WorkflowDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  WORKFLOW_RETRY_SCHEDULED_TYPE,
+  WORKFLOW_RUN_STARTED_TYPE,
+  WORKFLOW_WAITING_FOR_EVENT_TYPE,
+  WORKFLOW_WAITING_TYPE,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { loadAggregate } from "@cosmicdrift/kumiko-framework/event-store";
+import { selectExpiredSuspensionEvents } from "./db/queries/suspended-runs";
+import type { SuspendableRun } from "./resume-loop";
+import type { TriggerEventRef } from "./workflow-runner";
+
+export type WorkflowRegistry = ReadonlyMap<string, WorkflowDefinition>;
+
+const SUSPEND_EVENT_TYPES = [
+  WORKFLOW_WAITING_TYPE,
+  WORKFLOW_WAITING_FOR_EVENT_TYPE,
+  WORKFLOW_RETRY_SCHEDULED_TYPE,
+] as const;
+
+function isTriggerEventRef(value: unknown): value is TriggerEventRef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "eventId" in value &&
+    typeof value.eventId === "string" &&
+    "aggregateId" in value &&
+    typeof value.aggregateId === "string" &&
+    "version" in value &&
+    typeof value.version === "number"
+  );
+}
+
+// undefined when the run has no usable reference or the trigger event can no
+// longer be loaded (archived stream): the run is skipped, never resumed on
+// made-up data.
+async function loadTriggerEvent(
+  db: DbRunner,
+  tenantId: TenantId,
+  runId: string,
+): Promise<{ aggregateId: string; type: string; payload: unknown } | undefined> {
+  const runEvents = await loadAggregate(db, runId, tenantId);
+  const started = runEvents.find((e) => e.type === WORKFLOW_RUN_STARTED_TYPE);
+  if (!started) return undefined;
+  const ref = started.payload["triggerEventRef"];
+  if (ref === undefined) {
+    // Cron run: the synthetic trigger event was never stored.
+    return { aggregateId: runId, type: String(started.payload["triggerEventType"]), payload: {} };
+  }
+  if (!isTriggerEventRef(ref)) return undefined;
+  const source = (await loadAggregate(db, ref.aggregateId, tenantId)).find(
+    (e) => e.id === ref.eventId,
+  );
+  return source && { aggregateId: source.aggregateId, type: source.type, payload: source.payload };
+}
+
+/**
+ * Postgres-backed fetcher. Queries kumiko_events for suspension events with
+ * expired wakeAt/timeoutAt timestamps. The resume-loop applies the Q7
+ * fingerprint check + concurrency-claim per row.
+ *
+ * Known limitation (M.4 followup): the WHERE clause currently picks up
+ * every WAITING-row whose wakeAt has expired, including those that have
+ * already been resumed. The resume-loop silently skips them via the
+ * VersionConflictError path on the RESUMED-claim. A future optimisation
+ * is the workflow_run_pending read-side projection (Plan-Doc Sample 2,
+ * "Resume-Loop" section).
+ */
+export function createSuspendedRunFetcher(
+  db: DbRunner,
+  workflowRegistry: WorkflowRegistry,
+): () => Promise<SuspendableRun[]> {
+  return async () => {
+    const rows = await selectExpiredSuspensionEvents(db, SUSPEND_EVENT_TYPES);
+
+    const results: SuspendableRun[] = [];
+
+    for (const row of rows) {
+      const aggregateId = (row["aggregateId"] ?? row["aggregate_id"]) as string;
+      const type = row["type"] as string;
+      const payload = row["payload"] as Record<string, unknown>;
+
+      const workflowName = payload["workflowName"] as string | undefined;
+      if (!workflowName) continue;
+
+      const workflow = workflowRegistry.get(workflowName);
+      if (!workflow) continue;
+
+      const stepIndex = payload["stepIndex"] as number | undefined;
+      if (stepIndex === undefined) continue;
+
+      const wakeAt = (payload["wakeAt"] ?? payload["timeoutAt"]) as string | undefined;
+      if (!wakeAt) continue;
+
+      const triggerEvent = await loadTriggerEvent(
+        db,
+        (row["tenantId"] ?? row["tenant_id"]) as TenantId, // @cast-boundary raw-sql-row
+        aggregateId,
+      );
+      if (!triggerEvent) continue;
+
+      results.push({
+        runId: aggregateId,
+        workflowName,
+        stepIndex,
+        wakeAt,
+        retryAttempt: payload["attempt"] as number | undefined,
+        suspensionEventType: type,
+        workflow,
+        triggerEvent,
+        definitionFingerprint: payload["definitionFingerprint"] as string | undefined,
+      });
+    }
+
+    return results;
+  };
+}
+
+/**
+ * In-memory fetchSuspendedRuns for unit testing. Returns a fresh copy of
+ * runs on each call.
+ */
+export function createInMemorySuspendedRunFetcher(
+  runs: readonly SuspendableRun[],
+): () => Promise<SuspendableRun[]> {
+  return async () => runs.map((r) => ({ ...r }));
+}
+```
+
+### src/resume-loop.ts
+
+```ts
+// resume-loop — polls for suspended workflow runs with expired wake times
+// and re-enters the pipeline at the appropriate step.
+//
+// The Resume-Loop is the runtime that makes Tier-3 steps work:
+//   1. Reads the event store for WORKFLOW_WAITING_TYPE events
+//   2. Filters on `wakeAt < now()` — runs whose wait period has expired
+//   3. Writes a WORKFLOW_RESUMED_TYPE event to the run's stream
+//   4. Re-executes the pipeline from the suspended step + 1
+//
+// For WORKFLOW_RETRY_SCHEDULED_TYPE events:
+//   1. Matches step with expired backoff
+//   2. Writes a resumed event with retryAttempt = previous + 1
+//   3. Re-executes the pipeline at the same step index
+//
+// The loop is designed to run as a Bun worker / cron job (e.g. every 30s).
+
+import type { HandlerContext, WorkflowDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  buildPipelineSteps,
+  computeDefinitionFingerprint,
+  describeWorkflowStepError,
+  runStepList,
+  WORKFLOW_AGGREGATE_TYPE,
+  WORKFLOW_RESUMED_TYPE,
+  WORKFLOW_RETRY_SCHEDULED_TYPE,
+  WORKFLOW_RUN_COMPLETED_TYPE,
+  WORKFLOW_RUN_FAILED_TYPE,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { VersionConflictError } from "@cosmicdrift/kumiko-framework/event-store";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+
+const log = createFallbackLogger("workflow-runner");
+
+export type SuspendableRun = {
+  runId: string;
+  workflowName: string;
+  stepIndex: number;
+  wakeAt: string;
+  /** Previous retry attempt count — set by the retry step's suspension event. */
+  retryAttempt?: number;
+  /** The event type that caused the suspension — used by the resume-loop
+   *  to decide whether to skip or re-execute the suspended step. */
+  suspensionEventType: string;
+  /** The workflow the suspension belongs to — resolved by the fetcher from
+   *  the registry. The resume-loop validates its current fingerprint
+   *  against `definitionFingerprint` below before resuming. */
+  workflow: WorkflowDefinition;
+  /** The original trigger event payload captured at run.started time
+   *  (Q7 Snapshot-at-Start). Re-fed into the pipeline on resume so
+   *  resolvers that read `event.payload` see what they saw originally. */
+  triggerEvent: unknown;
+  /** Fingerprint stamped on the suspension event when the run started.
+   *  Resume-loop compares this against the current workflow definition's
+   *  fingerprint; a mismatch surfaces as RUN_FAILED with the reason
+   *  `workflow_definition_changed`. */
+  definitionFingerprint?: string;
+};
+
+export class WorkflowDefinitionChangedError extends Error {
+  constructor(
+    readonly runId: string,
+    readonly workflowName: string,
+    readonly expectedFingerprint: string,
+    readonly currentFingerprint: string,
+  ) {
+    super(
+      `Workflow "${workflowName}" definition changed since run ${runId} started ` +
+        `(expected ${expectedFingerprint.slice(0, 12)}…, current ${currentFingerprint.slice(0, 12)}…). ` +
+        `Cancel the run or wait for it to complete before deploying definition changes.`,
+    );
+    this.name = "WorkflowDefinitionChangedError";
+  }
+}
+
+/**
+ * Poll for suspended runs with expired wake times and resume them.
+ * Called periodically (e.g. every 30s) by a scheduler or Bun.Timer.
+ *
+ * @param fetchSuspendedRuns - async function that reads the event store
+ *   for WORKFLOW_WAITING_TYPE events where wakeAt < now()
+ * @param handlerCtx - the HandlerContext to pass to the pipeline
+ * @returns the number of runs resumed
+ */
+export async function runResumeLoop(
+  fetchSuspendedRuns: () => Promise<SuspendableRun[]>,
+  handlerCtx: HandlerContext,
+): Promise<number> {
+  const suspended = await fetchSuspendedRuns();
+  let resumed = 0;
+
+  for (const run of suspended) {
+    // Q7 fingerprint check FIRST — before we claim the run, before any
+    // expensive work, before we burn a stream-version. If the workflow
+    // definition changed since the run started, fail loud (do NOT silent-
+    // skip — a stale stuck run is worse than an explicit failure).
+    if (run.definitionFingerprint !== undefined) {
+      const currentFingerprint = computeDefinitionFingerprint(run.workflow);
+      if (currentFingerprint !== run.definitionFingerprint) {
+        await handlerCtx.unsafeAppendEvent({
+          aggregateId: run.runId,
+          aggregateType: WORKFLOW_AGGREGATE_TYPE,
+          type: WORKFLOW_RUN_FAILED_TYPE,
+          payload: {
+            workflowName: run.workflowName,
+            stepIndex: run.stepIndex,
+            error: new WorkflowDefinitionChangedError(
+              run.runId,
+              run.workflowName,
+              run.definitionFingerprint,
+              currentFingerprint,
+            ).message,
+            reason: "workflow_definition_changed",
+          },
+        });
+        continue;
+      }
+    }
+
+    // Resume-claim: append WORKFLOW_RESUMED first. The event-store appends
+    // against expectedVersion = current stream-version; a competing
+    // resume-loop instance racing the same run loses the UNIQUE
+    // (tenant_id, aggregate_id, version) check and gets a
+    // VersionConflictError. That's the concurrency-guard — silent skip,
+    // no FAILED-event. Stale WAITING-rows in the fetcher result also
+    // hit this branch on the second poll-tick.
+    try {
+      await handlerCtx.unsafeAppendEvent({
+        aggregateId: run.runId,
+        aggregateType: WORKFLOW_AGGREGATE_TYPE,
+        type: WORKFLOW_RESUMED_TYPE,
+        payload: {
+          stepIndex: run.stepIndex,
+          retryAttempt: run.retryAttempt,
+        },
+      });
+    } catch (error) {
+      if (error instanceof VersionConflictError) {
+        continue;
+      }
+      throw error;
+    }
+
+    try {
+      const workflowCtx = {
+        runId: run.runId,
+        workflowName: run.workflowName,
+        stepIndex: run.stepIndex,
+        ...(run.retryAttempt ? { retryAttempt: run.retryAttempt + 1 } : {}),
+        ...(run.definitionFingerprint && {
+          definitionFingerprint: run.definitionFingerprint,
+        }),
+      };
+
+      // runStepList skip semantics: indices `i < resumeFrom` are skipped,
+      // `i >= resumeFrom` execute. Wait/waitForEvent already wrote their
+      // suspension event in the original run → resume past them (stepIndex + 1).
+      // Retry re-enters at the same index because the retry step itself
+      // wraps the sub-pipeline that must run again.
+      const resumeFrom =
+        run.suspensionEventType === WORKFLOW_RETRY_SCHEDULED_TYPE
+          ? run.stepIndex
+          : run.stepIndex + 1;
+
+      const steps = buildPipelineSteps(run.workflow.pipelineDef, run.triggerEvent as never);
+      const outcome = await runStepList(
+        steps,
+        run.triggerEvent as never,
+        handlerCtx,
+        {},
+        {},
+        workflowCtx,
+        resumeFrom,
+      );
+
+      // Only write run-completed when the pipeline actually completed or
+      // returned. A second suspension (e.g. `wait` further down the
+      // pipeline) leaves the run pending for the next resume-loop tick.
+      if (outcome.kind !== "suspended") {
+        await handlerCtx.unsafeAppendEvent({
+          aggregateId: run.runId,
+          aggregateType: WORKFLOW_AGGREGATE_TYPE,
+          type: WORKFLOW_RUN_COMPLETED_TYPE,
+          payload: { stepIndex: run.stepIndex },
+        });
+      }
+
+      resumed++;
+    } catch (error) {
+      // The failed event keeps only a short description; log the raw error so
+      // the cause stays diagnosable.
+      log.warn("workflow run failed", {
+        runId: run.runId,
+        stepIndex: run.stepIndex,
+        error: String(error),
+      });
+      await handlerCtx.unsafeAppendEvent({
+        aggregateId: run.runId,
+        aggregateType: WORKFLOW_AGGREGATE_TYPE,
+        type: WORKFLOW_RUN_FAILED_TYPE,
+        payload: {
+          stepIndex: run.stepIndex,
+          error: describeWorkflowStepError(error),
+        },
+      });
+    }
+  }
+
+  return resumed;
+}
+```
+
+### src/workflow-runner.ts
+
+```ts
+// workflow-runner — starts a workflow-run by writing run.started and
+// executing the pipeline until first suspension or completion.
+//
+// Q7 (Snapshot-at-Start): the run.started payload carries
+// `definitionFingerprint` plus the trigger fields the resume-loop needs
+// to re-hydrate state. The fingerprint travels on into every suspension
+// event (wait/waitForEvent/retry payloads) so the resume-loop validates
+// it without a separate per-run lookup.
+//
+// On first suspension: just return — the resume-loop wakes the run later.
+// On full completion (pipeline ran to r.step.return): we write
+// WORKFLOW_RUN_COMPLETED here. Throws bubble up to the caller (event-
+// trigger / cron-scheduler) which translates them into RUN_FAILED.
+
+import type {
+  HandlerContext,
+  WorkflowDefinition,
+  WriteEvent,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  buildPipelineSteps,
+  computeDefinitionFingerprint,
+  runStepList,
+  WORKFLOW_AGGREGATE_TYPE,
+  WORKFLOW_RUN_COMPLETED_TYPE,
+  WORKFLOW_RUN_STARTED_TYPE,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// Reference into the event store; the run stream never copies a foreign
+// payload, so erasing the source event also covers the workflow.
+export type TriggerEventRef = {
+  readonly eventId: string;
+  readonly aggregateId: string;
+  readonly version: number;
+};
+
+export type WorkflowRunStartedPayload = {
+  readonly workflowName: string;
+  readonly triggerEventType: string;
+  // Absent for cron runs: their synthetic trigger event has no stored source.
+  readonly triggerEventRef?: TriggerEventRef;
+  readonly definitionFingerprint: string;
+  readonly idempotencyKey?: string;
+};
+
+/**
+ * Start + execute a workflow run.
+ *
+ * 1. Append `workflow.run.started` with the snapshot fingerprint.
+ * 2. Run the pipeline. Tier-3 steps may suspend it via SUSPEND_SENTINEL.
+ * 3. If the pipeline completes without suspension → write
+ *    `workflow.run-completed`. If it suspends → leave the resume-loop
+ *    to wake it. If it throws → bubble up; the caller writes FAILED.
+ */
+export async function startAndRunWorkflow(args: {
+  readonly runId: string;
+  readonly workflow: WorkflowDefinition;
+  readonly triggerEvent: WriteEvent;
+  readonly triggerEventRef?: TriggerEventRef;
+  readonly idempotencyKey?: string;
+  readonly handlerCtx: HandlerContext;
+}): Promise<{ readonly outcome: "completed" | "suspended" }> {
+  const fingerprint = computeDefinitionFingerprint(args.workflow);
+
+  const startedPayload: WorkflowRunStartedPayload = {
+    workflowName: args.workflow.name,
+    triggerEventType: args.triggerEvent.type,
+    ...(args.triggerEventRef && { triggerEventRef: args.triggerEventRef }),
+    definitionFingerprint: fingerprint,
+    ...(args.idempotencyKey && { idempotencyKey: args.idempotencyKey }),
+  };
+
+  await args.handlerCtx.unsafeAppendEvent({
+    aggregateId: args.runId,
+    aggregateType: WORKFLOW_AGGREGATE_TYPE,
+    type: WORKFLOW_RUN_STARTED_TYPE,
+    payload: startedPayload as unknown as Record<string, unknown>,
+  });
+
+  const steps = buildPipelineSteps(args.workflow.pipelineDef, args.triggerEvent);
+
+  const outcome = await runStepList(
+    steps,
+    args.triggerEvent,
+    args.handlerCtx,
+    {},
+    {},
+    {
+      runId: args.runId,
+      workflowName: args.workflow.name,
+      stepIndex: 0,
+      definitionFingerprint: fingerprint,
+    },
+  );
+
+  if (outcome.kind === "suspended") {
+    return { outcome: "suspended" };
+  }
+
+  await args.handlerCtx.unsafeAppendEvent({
+    aggregateId: args.runId,
+    aggregateType: WORKFLOW_AGGREGATE_TYPE,
+    type: WORKFLOW_RUN_COMPLETED_TYPE,
+    payload: { workflowName: args.workflow.name },
+  });
+  return { outcome: "completed" };
+}
+```