@cosmicdrift/kumiko-bundled-features 0.231.0 → 0.232.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.231.0",
+  "version": "0.232.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -130,12 +130,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.231.0",
-    "@cosmicdrift/kumiko-framework": "0.231.0",
-    "@cosmicdrift/kumiko-headless": "0.231.0",
-    "@cosmicdrift/kumiko-renderer": "0.231.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.231.0",
-    "@cosmicdrift/kumiko-types": "0.231.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.232.0",
+    "@cosmicdrift/kumiko-framework": "0.232.0",
+    "@cosmicdrift/kumiko-headless": "0.232.0",
+    "@cosmicdrift/kumiko-renderer": "0.232.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.232.0",
+    "@cosmicdrift/kumiko-types": "0.232.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -164,7 +164,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.231.0",
-    "@cosmicdrift/kumiko-locale-es": "0.231.0"
+    "@cosmicdrift/kumiko-locale-de": "0.232.0",
+    "@cosmicdrift/kumiko-locale-es": "0.232.0"
   }
 }

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

@@ -0,0 +1,328 @@
+// event-wakeup — the event-based resume path (framework#2513 Phase 3b)
+// against real Postgres.
+//
+// Fires the AWAITED domain event (not the workflow's own trigger event)
+// through a real event-dispatcher pass so event-subscriber.ts's MSP
+// observes it, then drives `resume-due-runs` directly via
+// stack.registry.getJob(...) — same style as resume-loop.integration.test.ts
+// — to exercise the full resume-run handler off the row the subscriber
+// marked due.
+//
+// The workflow under test reads the matched event's payload back via a
+// resolver (`ctx.steps[awaits.replied]`) in the step right after
+// waitForEvent and asserts it inline, throwing on a mismatch. Steps that
+// resume a suspended run always execute inside resume-run's own
+// workflow-runner write-handler context, which only owns workflow-runner's
+// own event types (see resume-run.write.ts's module doc) — a custom
+// business event appended from a resumed step would need the owning
+// feature's write-handler context instead, unrelated to what Phase 3b
+// threads through, so throw-on-mismatch is the direct probe: the run
+// reaching workflow.run-completed instead of workflow.run-failed IS the
+// assertion that ctx.steps[awaits.replied] held the expected payload.
+// r.step.return's own `data` is discarded for workflow-triggered runs (see
+// workflow-runner.integration.test.ts) — this sidesteps that too.
+
+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 {
+  type AwaitedEventType,
+  createSystemUser,
+  defineFeature,
+  defineWorkflow,
+  type JobContext,
+  stepsPipeline,
+  WORKFLOW_RESUMED_TYPE,
+  WORKFLOW_RUN_COMPLETED_TYPE,
+  WORKFLOW_RUN_STARTED_TYPE,
+  WORKFLOW_WAITING_FOR_EVENT_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 { 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();
+
+// "wk-" prefix — the workflow-registry + event-subscriber MSP registration
+// are process-global; other test files in this suite use their own prefix
+// (wr-, rl-) for the same reason (see resume-loop.integration.test.ts).
+const waitForEventWorkflow = defineWorkflow({
+  name: "wk-wait-for-event",
+  trigger: { kind: "event", eventType: "wk-test.start" },
+  awaits: { replied: "wk-test.replied" },
+  idempotencyKey: ({ payload }) => (payload as { runKey: string }).runKey,
+  steps: stepsPipeline<unknown, unknown, { readonly replied: AwaitedEventType }>(
+    ({ r, awaits }) => [
+      r.step.waitForEvent({
+        event: awaits.replied,
+        match: {
+          version: 1,
+          expr: { kind: "atom", path: ["from"], op: { kind: "eq", value: "match@example.com" } },
+        },
+        timeout: "P7D",
+      }),
+      r.step.compute("seen", (ctx) => {
+        const payload = ctx.steps[awaits.replied] as { from: string; body: string } | undefined;
+        if (payload?.from !== "match@example.com" || payload.body !== "hi") {
+          throw new Error(`triggerPayload not threaded: got ${JSON.stringify(payload)}`);
+        }
+        return payload;
+      }),
+      r.step.return({ isSuccess: true, data: undefined }),
+    ],
+  ),
+});
+
+const timeoutWorkflow = defineWorkflow({
+  name: "wk-wait-for-event-timeout",
+  trigger: { kind: "event", eventType: "wk-test.timeout-start" },
+  awaits: { replied: "wk-test.timeout-replied" },
+  idempotencyKey: ({ payload }) => (payload as { runKey: string }).runKey,
+  steps: stepsPipeline<unknown, unknown, { readonly replied: AwaitedEventType }>(
+    ({ r, awaits }) => [
+      r.step.waitForEvent({
+        event: awaits.replied,
+        // Absolute ISO timestamp (not a "P..."/"PT..." duration) — resolves
+        // straight to timeoutAt, already in the past, no wakeAt-tampering
+        // needed (same trick rl-wait's `forIso` uses).
+        timeout: (ctx) => (ctx.event.payload as { timeoutIso: string }).timeoutIso,
+      }),
+      r.step.compute("seen", (ctx) => {
+        const payload = ctx.steps[awaits.replied];
+        // pending.triggerPayload round-trips through jsonb as null, not
+        // undefined, when the row was never matched (timeout path).
+        if (payload != null) {
+          throw new Error(
+            `expected no triggerPayload on a timeout, got ${JSON.stringify(payload)}`,
+          );
+        }
+        return payload;
+      }),
+      r.step.return({ isSuccess: true, data: undefined }),
+    ],
+  ),
+});
+
+// The two casts below only erase TAwaits's literal key type (`{replied: ...}`
+// -> the default `Record<string, string>`) — registerEventTrigger itself
+// stays generic-free (it never reads the pipeline's branded awaits map, only
+// workflow.awaits's plain string values), so this is the narrow-to-wide
+// widening cast the `const TAwaits` inference on defineWorkflow forces at
+// every call site, not a loss of type safety over real behavior.
+const testTriggersFeature = defineFeature("workflow-runner-event-wakeup-test-triggers", (r) => {
+  registerEventTrigger(r, waitForEventWorkflow as unknown as WorkflowDefinition);
+  registerEventTrigger(r, timeoutWorkflow as unknown as WorkflowDefinition);
+});
+
+const noopLogger: JobContext["log"] = {
+  info() {},
+  warn() {},
+  error() {},
+  debug() {},
+  child() {
+    return noopLogger;
+  },
+};
+
+async function insertEvent(
+  type: string,
+  payload: Record<string, unknown>,
+  user: { readonly id: string; readonly tenantId: string } = admin,
+): Promise<void> {
+  await insertOne(stack.db, eventsTable, {
+    aggregateId: crypto.randomUUID(),
+    aggregateType: "wk-test-source",
+    tenantId: user.tenantId,
+    version: 1,
+    type,
+    eventVersion: 1,
+    payload,
+    metadata: { userId: user.id },
+    createdBy: user.id,
+  });
+}
+
+async function fireTrigger(
+  type: string,
+  payload: Record<string, unknown>,
+  user: { readonly id: string; readonly tenantId: string } = admin,
+): Promise<void> {
+  await insertEvent(type, payload, user);
+  // Two passes: event-trigger's MSP writes run-started + the suspension on
+  // the first pass; pending-projection only observes that newly-written
+  // suspension event on a pass after it exists.
+  await stack.eventDispatcher?.runOnce();
+  await stack.eventDispatcher?.runOnce();
+}
+
+async function fireAwaitedEvent(
+  type: string,
+  payload: Record<string, unknown>,
+  user: { readonly id: string; readonly tenantId: string } = admin,
+): Promise<void> {
+  await insertEvent(type, payload, user);
+  await stack.eventDispatcher?.runOnce();
+}
+
+async function loadRunEvents(runId: string) {
+  return selectMany(
+    stack.db,
+    eventsTable,
+    { aggregateId: runId },
+    { orderBy: { col: "version", direction: "asc" } },
+  );
+}
+
+async function pendingRow(
+  runId: string,
+  stepIndex: number,
+): Promise<
+  { triggerEventType: string | null; triggerPayload: unknown; wakeAt: string } | undefined
+> {
+  const rows = (await asRawClient(stack.db).unsafe(
+    `SELECT trigger_event_type AS "triggerEventType", trigger_payload AS "triggerPayload", wake_at AS "wakeAt" FROM workflow_run_pending WHERE run_id = $1 AND step_index = $2`,
+    [runId, stepIndex],
+  )) as ReadonlyArray<{ triggerEventType: string | null; triggerPayload: unknown; wakeAt: string }>;
+  return rows[0];
+}
+
+async function runResumeDueRunsJob(tenantId: string): Promise<void> {
+  const job = stack.registry.getJob("workflow-runner:job:resume-due-runs");
+  expect(job).toBeDefined();
+  if (!job) return;
+
+  const systemUser = createSystemUser(tenantId);
+  const ctx: JobContext = {
+    db: stack.db,
+    registry: stack.registry,
+    systemUser,
+    log: noopLogger,
+    triggeredBy: null,
+    _tenantId: tenantId,
+    write: (qn, payload) => stack.dispatcher.write(qn, payload, systemUser),
+  } as JobContext;
+  await job.handler({}, ctx);
+}
+
+describe("workflow-runner event-wakeup", () => {
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [workflowRunnerFeature, testTriggersFeature] });
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("matching awaited event marks the row due; resume-due-runs completes the run and a later step sees the payload", async () => {
+    const runKey = crypto.randomUUID();
+    const runId = workflowRunAggregateId(waitForEventWorkflow.name, runKey);
+
+    await fireTrigger("wk-test.start", { runKey });
+    expect((await pendingRow(runId, 0))?.triggerEventType).toBeNull();
+
+    await fireAwaitedEvent("wk-test.replied", { from: "match@example.com", body: "hi" });
+
+    const marked = await pendingRow(runId, 0);
+    expect(marked?.triggerEventType).toBe("wk-test.replied");
+    expect(marked?.triggerPayload).toEqual({ from: "match@example.com", body: "hi" });
+
+    await runResumeDueRunsJob(admin.tenantId);
+
+    // The "seen" compute step throws if ctx.steps[awaits.replied] doesn't
+    // hold the exact triggerPayload — reaching run-completed (not
+    // run-failed) IS the proof resume-run threaded it through correctly.
+    const rows = await loadRunEvents(runId);
+    expect(rows.map((row) => row["type"])).toEqual([
+      WORKFLOW_RUN_STARTED_TYPE,
+      WORKFLOW_WAITING_FOR_EVENT_TYPE,
+      WORKFLOW_RESUMED_TYPE,
+      WORKFLOW_RUN_COMPLETED_TYPE,
+    ]);
+  });
+
+  test("awaited event that fails matchExpr leaves the row untouched, no resume", async () => {
+    const runKey = crypto.randomUUID();
+    const runId = workflowRunAggregateId(waitForEventWorkflow.name, runKey);
+
+    await fireTrigger("wk-test.start", { runKey });
+    const before = await pendingRow(runId, 0);
+    expect(before?.triggerEventType).toBeNull();
+
+    await fireAwaitedEvent("wk-test.replied", { from: "someone-else@example.com", body: "hi" });
+
+    const after = await pendingRow(runId, 0);
+    expect(after?.triggerEventType).toBeNull();
+    expect(after?.wakeAt).toEqual(before?.wakeAt);
+
+    await runResumeDueRunsJob(admin.tenantId);
+    const rows = await loadRunEvents(runId);
+    expect(rows.map((row) => row["type"])).toEqual([
+      WORKFLOW_RUN_STARTED_TYPE,
+      WORKFLOW_WAITING_FOR_EVENT_TYPE,
+    ]);
+  });
+
+  test("an event no workflow awaits leaves every pending row untouched", async () => {
+    const runKey = crypto.randomUUID();
+    const runId = workflowRunAggregateId(waitForEventWorkflow.name, runKey);
+
+    await fireTrigger("wk-test.start", { runKey });
+    const before = await pendingRow(runId, 0);
+
+    await fireAwaitedEvent("wk-test.nobody-awaits-this", { anything: true });
+
+    const after = await pendingRow(runId, 0);
+    expect(after).toEqual(before);
+  });
+
+  test("tenant isolation: another tenant's matching event does not wake this tenant's run", async () => {
+    const runKey = crypto.randomUUID();
+    const runId = workflowRunAggregateId(waitForEventWorkflow.name, runKey);
+
+    await fireTrigger("wk-test.start", { runKey });
+    expect((await pendingRow(runId, 0))?.triggerEventType).toBeNull();
+
+    await fireAwaitedEvent(
+      "wk-test.replied",
+      { from: "match@example.com", body: "hi" },
+      TestUsers.otherTenant,
+    );
+
+    expect((await pendingRow(runId, 0))?.triggerEventType).toBeNull();
+
+    const rows = await loadRunEvents(runId);
+    expect(rows.map((row) => row["type"])).toEqual([
+      WORKFLOW_RUN_STARTED_TYPE,
+      WORKFLOW_WAITING_FOR_EVENT_TYPE,
+    ]);
+  });
+
+  test("timeout path: no matching event ever arrives, wakeAt (from timeoutAt) elapses, resume-due-runs still wakes the run", async () => {
+    const runKey = crypto.randomUUID();
+    const runId = workflowRunAggregateId(timeoutWorkflow.name, runKey);
+    const pastIso = T.Now.instant().subtract({ hours: 1 }).toString();
+
+    await fireTrigger("wk-test.timeout-start", { runKey, timeoutIso: pastIso });
+    expect((await pendingRow(runId, 0))?.triggerEventType).toBeNull();
+
+    await runResumeDueRunsJob(admin.tenantId);
+
+    // The "seen" compute step throws if ctx.steps[awaits.replied] is
+    // anything other than undefined on a timeout resume — reaching
+    // run-completed proves resume-run left it unset (pending.triggerPayload
+    // stayed NULL, never matched).
+    const rows = await loadRunEvents(runId);
+    expect(rows.map((row) => row["type"])).toEqual([
+      WORKFLOW_RUN_STARTED_TYPE,
+      WORKFLOW_WAITING_FOR_EVENT_TYPE,
+      WORKFLOW_RESUMED_TYPE,
+      WORKFLOW_RUN_COMPLETED_TYPE,
+    ]);
+  });
+});

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

@@ -0,0 +1,292 @@
+// pending-projection — workflow_run_pending MultiStreamProjection integration test.
+//
+// Exercises registerWorkflowRunPendingProjection end to end through a real
+// event-dispatcher pass: a test-only writeHandler appends the suspension/
+// resume/terminal event onto the run's workflow-run stream via
+// ctx.unsafeAppendEvent (the same primitive runner.ts uses for
+// run-started/run-completed), stack.eventDispatcher.runOnce() delivers it to
+// the MSP, and the resulting workflow_run_pending rows are asserted against
+// real Postgres rows.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
+import {
+  defineFeature,
+  WORKFLOW_AGGREGATE_TYPE,
+  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 { setupTestStack, type TestStack, TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { z } from "zod";
+import { workflowRunAggregateId } from "../aggregate-id";
+import { workflowRunnerFeature } from "../feature";
+import { workflowRunPendingTable } from "../tables";
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+// Generic "emit any workflow-run event" writeHandler — mirrors the
+// generic sendNotification handler in delivery.integration.test.ts. Lets
+// each test pick the suspension/resume/terminal event type + payload it
+// wants to exercise instead of poking eventsTable directly, so the MSP is
+// driven through the same ctx.unsafeAppendEvent + event-dispatcher path
+// runner.ts and event-trigger.ts use in production.
+const testEventsFeature = defineFeature("wr-pending-test", (r) => {
+  r.writeHandler(
+    "emit",
+    z.object({
+      runId: z.string(),
+      type: z.string(),
+      payload: z.unknown(),
+    }),
+    async (event, ctx) => {
+      await ctx.unsafeAppendEvent({
+        aggregateId: event.payload.runId,
+        aggregateType: WORKFLOW_AGGREGATE_TYPE,
+        type: event.payload.type,
+        payload: event.payload.payload,
+      });
+      return { isSuccess: true, data: {} };
+    },
+    { access: { openToAll: true } },
+  );
+});
+
+async function emitAndDeliver(
+  runId: string,
+  type: string,
+  payload: Record<string, unknown>,
+  user = admin,
+): Promise<void> {
+  await stack.http.writeOk("wr-pending-test:write:emit", { runId, type, payload }, user);
+  await stack.eventDispatcher?.runOnce();
+}
+
+async function pendingRowsFor(runId: string) {
+  return selectMany(stack.db, workflowRunPendingTable, { runId });
+}
+
+function newRunId(workflowName: string): string {
+  return workflowRunAggregateId(workflowName, crypto.randomUUID());
+}
+
+describe("workflow-runner pending-projection", () => {
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [workflowRunnerFeature, testEventsFeature] });
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("wait-suspension writes a row with wakeAt/stepIndex/workflowName/suspensionEventType, wait-fields NULL", async () => {
+    const workflowName = "wr-pending-wait";
+    const runId = newRunId(workflowName);
+
+    await emitAndDeliver(runId, WORKFLOW_WAITING_TYPE, {
+      workflowName,
+      stepIndex: 2,
+      wakeAt: "2026-05-01T10:00:00Z",
+    });
+
+    const rows = await pendingRowsFor(runId);
+    expect(rows).toHaveLength(1);
+    const row = rows[0]!;
+    expect(row["workflowName"]).toBe(workflowName);
+    expect(row["stepIndex"]).toBe(2);
+    expect(row["suspensionEventType"]).toBe(WORKFLOW_WAITING_TYPE);
+    expect(String(row["wakeAt"])).toBe("2026-05-01T10:00:00Z");
+    expect(row["waitEventType"]).toBeNull();
+    expect(row["matchExpr"]).toBeNull();
+  });
+
+  test("waitForEvent-suspension derives wakeAt from timeoutAt and round-trips matchExpr unchanged", async () => {
+    const workflowName = "wr-pending-wfe";
+    const runId = newRunId(workflowName);
+    const matchExpr = {
+      version: 1,
+      expr: { kind: "atom", path: ["email"], op: { kind: "eq", value: "a@b.de" } },
+    };
+
+    await emitAndDeliver(runId, WORKFLOW_WAITING_FOR_EVENT_TYPE, {
+      workflowName,
+      stepIndex: 1,
+      eventType: "user.replied",
+      timeoutAt: "2026-06-01T08:30:00Z",
+      match: matchExpr,
+    });
+
+    const rows = await pendingRowsFor(runId);
+    expect(rows).toHaveLength(1);
+    const row = rows[0]!;
+    expect(row["suspensionEventType"]).toBe(WORKFLOW_WAITING_FOR_EVENT_TYPE);
+    expect(String(row["wakeAt"])).toBe("2026-06-01T08:30:00Z");
+    expect(row["waitEventType"]).toBe("user.replied");
+    expect(row["matchExpr"]).toEqual(matchExpr);
+  });
+
+  test("retry-scheduled sets retryAttempt from the payload's attempt", async () => {
+    const workflowName = "wr-pending-retry";
+    const runId = newRunId(workflowName);
+
+    await emitAndDeliver(runId, WORKFLOW_RETRY_SCHEDULED_TYPE, {
+      workflowName,
+      stepIndex: 0,
+      attempt: 3,
+      wakeAt: "2026-05-02T00:00:00Z",
+    });
+
+    const rows = await pendingRowsFor(runId);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]!["retryAttempt"]).toBe(3);
+    expect(rows[0]!["suspensionEventType"]).toBe(WORKFLOW_RETRY_SCHEDULED_TYPE);
+  });
+
+  test("WORKFLOW_RESUMED deletes the run's pending row", async () => {
+    const workflowName = "wr-pending-resumed";
+    const runId = newRunId(workflowName);
+
+    await emitAndDeliver(runId, WORKFLOW_WAITING_TYPE, {
+      workflowName,
+      stepIndex: 0,
+      wakeAt: "2026-05-03T00:00:00Z",
+    });
+    expect(await pendingRowsFor(runId)).toHaveLength(1);
+
+    await emitAndDeliver(runId, WORKFLOW_RESUMED_TYPE, {});
+    expect(await pendingRowsFor(runId)).toHaveLength(0);
+  });
+
+  test("WORKFLOW_RUN_COMPLETED deletes the run's pending row", async () => {
+    const workflowName = "wr-pending-completed";
+    const runId = newRunId(workflowName);
+
+    await emitAndDeliver(runId, WORKFLOW_WAITING_TYPE, {
+      workflowName,
+      stepIndex: 0,
+      wakeAt: "2026-05-03T00:00:00Z",
+    });
+    expect(await pendingRowsFor(runId)).toHaveLength(1);
+
+    await emitAndDeliver(runId, WORKFLOW_RUN_COMPLETED_TYPE, {});
+    expect(await pendingRowsFor(runId)).toHaveLength(0);
+  });
+
+  test("WORKFLOW_RUN_FAILED deletes the run's pending row", async () => {
+    const workflowName = "wr-pending-failed";
+    const runId = newRunId(workflowName);
+
+    await emitAndDeliver(runId, WORKFLOW_WAITING_TYPE, {
+      workflowName,
+      stepIndex: 0,
+      wakeAt: "2026-05-03T00:00:00Z",
+    });
+    expect(await pendingRowsFor(runId)).toHaveLength(1);
+
+    await emitAndDeliver(runId, WORKFLOW_RUN_FAILED_TYPE, {});
+    expect(await pendingRowsFor(runId)).toHaveLength(0);
+  });
+
+  test("sequential suspend -> resume -> suspend again: never two rows at once, new row carries the new stepIndex", async () => {
+    const workflowName = "wr-pending-lifecycle";
+    const runId = newRunId(workflowName);
+
+    await emitAndDeliver(runId, WORKFLOW_WAITING_TYPE, {
+      workflowName,
+      stepIndex: 0,
+      wakeAt: "2026-05-04T00:00:00Z",
+    });
+    let rows = await pendingRowsFor(runId);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]!["stepIndex"]).toBe(0);
+
+    await emitAndDeliver(runId, WORKFLOW_RESUMED_TYPE, {});
+    expect(await pendingRowsFor(runId)).toHaveLength(0);
+
+    await emitAndDeliver(runId, WORKFLOW_WAITING_TYPE, {
+      workflowName,
+      stepIndex: 1,
+      wakeAt: "2026-05-04T01:00:00Z",
+    });
+    rows = await pendingRowsFor(runId);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]!["stepIndex"]).toBe(1);
+  });
+
+  test("tenant isolation: another tenant's resume does not delete or leak this tenant's row", async () => {
+    const otherTenantRunId = newRunId("wr-pending-tenant-a");
+    await emitAndDeliver(
+      otherTenantRunId,
+      WORKFLOW_WAITING_TYPE,
+      { workflowName: "wr-pending-tenant-a", stepIndex: 0, wakeAt: "2026-05-05T00:00:00Z" },
+      TestUsers.otherTenant,
+    );
+
+    const adminRunId = newRunId("wr-pending-tenant-b");
+    await emitAndDeliver(adminRunId, WORKFLOW_WAITING_TYPE, {
+      workflowName: "wr-pending-tenant-b",
+      stepIndex: 0,
+      wakeAt: "2026-05-05T00:00:00Z",
+    });
+
+    // Resolving the admin-tenant run must not touch the other tenant's row.
+    await emitAndDeliver(adminRunId, WORKFLOW_RESUMED_TYPE, {});
+
+    const otherTenantRows = await pendingRowsFor(otherTenantRunId);
+    expect(otherTenantRows).toHaveLength(1);
+    expect(otherTenantRows[0]!["tenantId"]).toBe(TestUsers.otherTenant.tenantId);
+
+    expect(await pendingRowsFor(adminRunId)).toHaveLength(0);
+
+    // Tenant-scoped select proves the row is filed under its own tenant.
+    const scoped = await selectMany(stack.db, workflowRunPendingTable, {
+      tenantId: TestUsers.otherTenant.tenantId,
+      runId: otherTenantRunId,
+    });
+    expect(scoped).toHaveLength(1);
+    const crossTenant = await selectMany(stack.db, workflowRunPendingTable, {
+      tenantId: admin.tenantId,
+      runId: otherTenantRunId,
+    });
+    expect(crossTenant).toHaveLength(0);
+  });
+
+  test("same workflow + idempotencyKey across tenants share a run_id but keep separate pending rows", async () => {
+    // workflowRunAggregateId() is deliberately tenant-agnostic (aggregate-id.ts):
+    // uuidv5(workflowName|idempotencyKey) only. Two tenants triggering the
+    // same workflow with the same idempotencyKey (e.g. a scheduled monthly
+    // close) land on the SAME run_id. Before tenant_id joined the PK, the
+    // second tenant's upsert on (run_id, step_index) silently overwrote the
+    // first tenant's row instead of inserting its own.
+    const workflowName = "wr-pending-shared-runid";
+    const idempotencyKey = "monatsabschluss-2026-09";
+    const sharedRunId = workflowRunAggregateId(workflowName, idempotencyKey);
+
+    await emitAndDeliver(
+      sharedRunId,
+      WORKFLOW_WAITING_TYPE,
+      { workflowName, stepIndex: 0, wakeAt: "2026-09-01T00:00:00Z" },
+      TestUsers.otherTenant,
+    );
+    await emitAndDeliver(
+      sharedRunId,
+      WORKFLOW_WAITING_TYPE,
+      { workflowName, stepIndex: 0, wakeAt: "2026-09-02T00:00:00Z" },
+      admin,
+    );
+
+    const rows = await pendingRowsFor(sharedRunId);
+    expect(rows).toHaveLength(2);
+
+    const otherTenantRow = rows.find((r) => r["tenantId"] === TestUsers.otherTenant.tenantId);
+    const adminRow = rows.find((r) => r["tenantId"] === admin.tenantId);
+    expect(otherTenantRow).toBeDefined();
+    expect(adminRow).toBeDefined();
+    expect(String(otherTenantRow!["wakeAt"])).toBe("2026-09-01T00:00:00Z");
+    expect(String(adminRow!["wakeAt"])).toBe("2026-09-02T00:00:00Z");
+  });
+});