@cosmicdrift/kumiko-framework 0.306.0 → 0.308.0

package/src/jobs/job-runner.ts

@@ -1,3 +1,4 @@
+import type { WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
 import { type JobsOptions, Queue, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context";
@@ -18,6 +19,7 @@ import {
   SYSTEM_TENANT_ID,
   type TenantId,
 } from "../engine/types";
+import { InternalError } from "../errors";
 import { isKumikoError } from "../errors/kumiko-error";
 import { createFileContext } from "../files/file-handle";
 import { createFallbackLogger } from "../logging";
@@ -33,8 +35,22 @@ import {
 import { createEscapeHatchReporter } from "../observability/escape-hatch-report";
 import { createDistributedLock, type DistributedLock } from "../pipeline/distributed-lock";
 import { RedisKeys } from "../pipeline/redis-keys";
+import {
+  buildPersonalDataGate,
+  isPersonalDataGated,
+  parseWriteOrigin,
+} from "../pipeline/write-origin";
 import { bridgeStub } from "../testing/handler-context";
 
+// A payload's own `_writeOrigin` is never trusted; only the ambient gated origin is stamped.
+function stampGatedWriteOrigin(data: Record<string, unknown>): void {
+  delete data["_writeOrigin"];
+  const origin = requestContext.get()?.writeOrigin;
+  if (origin && isPersonalDataGated(origin)) {
+    data["_writeOrigin"] = origin;
+  }
+}
+
 // Queue-name convention: <prefix>-<lane>. The prefix is fixed in prod
 // ("kumiko-jobs") — it must match between enqueuers and consumers, and an
 // accidental drift would silently drop jobs. Tests override via
@@ -731,6 +747,21 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     // multi-trigger dispatch; exposed as jobContext.triggerName so handlers
     // don't dig through the raw payload themselves.
     const triggerName = rawData["_triggerName"] as string | undefined; // @cast-boundary dynamic-key
+
+    // Absent = legacy or ungated root; present but invalid fails the run closed.
+    const rawWriteOrigin = rawData["_writeOrigin"]; // @cast-boundary dynamic-key
+    let jobOrigin: WriteOrigin | undefined;
+    let writeOriginInvalid = false;
+    if (rawWriteOrigin !== undefined) {
+      const parsed = parseWriteOrigin(rawWriteOrigin);
+      if (parsed) {
+        jobOrigin = { ...parsed, viaJob: jobName };
+      } else {
+        writeOriginInvalid = true;
+      }
+    }
+    const jobPersonalDataGate = jobOrigin ? buildPersonalDataGate(registry, jobOrigin) : undefined;
+
     // Mirror dispatch-shared.ts buildHandlerContext: ctx.files must resolve
     // through the same _fileProviderResolver for jobs as for write-handlers,
     // otherwise event-triggered jobs silently get an unresolved ctx.files.
@@ -749,8 +780,19 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     // systemScope() status (pre-existing, not something this change alters)
     // — isSystemJob below is what actually keeps ctx.systemDb off a
     // non-system job; it is the only thing standing between this db and an
-    // unchecked cross-tenant escape hatch for such a job.
-    const tenantScopedDb = configDb ? createTenantDb(configDb, tenantId, "system") : undefined;
+    // unchecked cross-tenant escape hatch for such a job. Gated like jobDb so
+    // ctx.systemDb, built from it, is gated too.
+    const tenantScopedDb = configDb
+      ? createTenantDb(
+          configDb,
+          tenantId,
+          "system",
+          undefined,
+          undefined,
+          undefined,
+          jobPersonalDataGate ? { personalDataGate: jobPersonalDataGate } : undefined,
+        )
+      : undefined;
     const isSystemJob = registry.isJobSystemScoped(jobName);
     // One reporter for ctx.systemDb and ctx.db.unsafeRaw() so both dedupe in the same window.
     const reportEscapeHatch = createEscapeHatchReporter({
@@ -768,6 +810,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       ? createTenantDb(configDb, tenantId, "tenant", context.tracer, context.meter, undefined, {
           unsafeRaw: jobDef.escapeHatch,
           report: reportEscapeHatch,
+          ...(jobPersonalDataGate && { personalDataGate: jobPersonalDataGate }),
         })
       : undefined;
     const config =
@@ -818,7 +861,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
             "JobContext.write called before dispatcher attached — call attachDispatcher() first",
           );
         }
-        return dispatchWriteRef.write(jobSystemUser, qn, payload);
+        return dispatchWriteRef.write(jobSystemUser, qn, payload, jobOrigin);
       },
       writeAs: (user: SessionUser, qn: string, payload: unknown) => {
         if (!dispatchWriteRef) {
@@ -826,7 +869,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
             "JobContext.writeAs called before dispatcher attached — call attachDispatcher() first",
           );
         }
-        return dispatchWriteRef.write(user, qn, payload);
+        return dispatchWriteRef.write(user, qn, payload, jobOrigin);
       },
       queryAs: (user: SessionUser, qn: string, payload: unknown) => {
         if (!dispatchWriteRef) {
@@ -834,7 +877,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
             "JobContext.queryAs called before dispatcher attached — call attachDispatcher() first",
           );
         }
-        return dispatchWriteRef.queryAs(user, qn, payload);
+        return dispatchWriteRef.queryAs(user, qn, payload, jobOrigin);
       },
       queryAsMember: (userId: string, qn: string, payload: unknown) => {
         if (!dispatchWriteRef) {
@@ -866,6 +909,13 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
 
     const runInSpan = async (): Promise<void> => {
       try {
+        if (writeOriginInvalid) {
+          throw new InternalError({
+            message:
+              `Job "${jobName}" received an unparseable _writeOrigin — refusing to run without ` +
+              "a trustworthy anonymous-root gate.",
+          });
+        }
         await requestContext.run(
           {
             requestId: jobRequestId,
@@ -873,6 +923,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
             // #3043 — events a job writes carry the job as their origin.
             handler: jobName,
             feature: qnScope(jobName),
+            writeOrigin: jobOrigin,
           },
           () => jobDef.handler(payload, jobContext),
         );
@@ -1107,9 +1158,11 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
 
       // perTenant: dispatch the fan-out wrapper instead
       if (jobDef.perTenant) {
+        const perTenantData: Record<string, unknown> = { ...(payload ?? {}) };
+        stampGatedWriteOrigin(perTenantData);
         const job = await targetQueue.add(
           `_perTenant:${jobName}`,
-          payload ?? {},
+          perTenantData,
           buildRetryBullOpts(jobDef),
         );
         return job.id ?? "unknown";
@@ -1184,6 +1237,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       // stamp the same correlation as the HTTP request that scheduled it.
       const reqCtx = requestContext.get();
       if (reqCtx?.correlationId) data["_correlationId"] = reqCtx.correlationId;
+      stampGatedWriteOrigin(data);
 
       const job = await targetQueue.add(jobName, data, bullOpts);
       return job.id ?? "unknown";
@@ -1228,6 +1282,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
             continue;
           }
         }
+        stampGatedWriteOrigin(data);
         // Route to the job's declared lane, not a fixed queue — that's
         // the whole reason both queues are held.
         await queues[laneForJob(jobDef)].add(name, data, buildRetryBullOpts(jobDef));

package/src/observability/__tests__/metrics-wiring.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { composeEnvSchema, readKumikoMeta } from "../../env";
 import { prometheusMetricsEnvSchema, resolveObservabilityWiring } from "../metrics-wiring";
 

package/src/observability/__tests__/observability.integration.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import type { TableColumns } from "../../db/dialect";
 import { buildEntityTable } from "../../db/table-builder";
 import { createRegistry, defineFeature } from "../../engine";

package/src/observability/metrics-wiring.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import * as z from "zod";
 import { createNoopProvider } from "./noop-provider";
 import { createPrometheusMeter, type PrometheusMeter } from "./prometheus-meter";
 import type { ObservabilityProvider } from "./types";

package/src/pipeline/__tests__/archive-stream.integration.test.ts

@@ -6,7 +6,7 @@
 // streams never pay for extra metadata writes.
 
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { buildEntityTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";

package/src/pipeline/__tests__/causation-chain.integration.test.ts

@@ -16,7 +16,7 @@
 // msp-multi-hop.integration.ts.
 
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { requestContext } from "../../api/request-context";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { selectMany } from "../../db/query";

package/src/pipeline/__tests__/ctx-bridge.integration.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { asRawClient, selectMany } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";

package/src/pipeline/__tests__/ctx-systemdb.integration.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { defineFeature } from "../../engine";
 import { setupTestStack, type TestStack, TestUsers } from "../../stack";
 

package/src/pipeline/__tests__/dispatcher-utils.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { createSystemUser } from "../../engine/system-user";
 import { InternalError } from "../../errors";
+import { VersionConflictError as EventStoreVersionConflictError } from "../../event-store/errors";
 import {
   describeShape,
   dispatcherSpanAttributes,
@@ -115,6 +116,13 @@ describe("wrapToKumiko", () => {
     expect(wrapped.code).toBe("internal_error");
     expect(wrapped.cause).toBeInstanceOf(TypeError);
   });
+
+  test("maps an event-store version conflict to a 409 version_conflict", () => {
+    const wrapped = wrapToKumiko(new EventStoreVersionConflictError("agg-1", 3));
+    expect(wrapped.code).toBe("version_conflict");
+    expect(wrapped.httpStatus).toBe(409);
+    expect(wrapped.details).toMatchObject({ entityId: "agg-1", expectedVersion: 3 });
+  });
 });
 
 describe("extractNestedSpecs", () => {

package/src/pipeline/__tests__/dispatcher.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import type { SseBroker } from "../../api/sse-broker";
 import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
 import type { TenantId } from "../../engine/types/identifiers";

package/src/pipeline/__tests__/domain-events-projections.integration.test.ts

@@ -10,7 +10,7 @@
 // projections-runner fires on appendEvent, dispatcher routes appendEvent to
 // the aggregate stream), any of the assertions below go red.
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import {
   integer as pgInteger,
   table as pgTable,

package/src/pipeline/__tests__/escape-hatch-audit.integration.test.ts

@@ -4,7 +4,7 @@
 // system-identity-switch.integration.test.ts.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { defineUnmanagedTable } from "../../db/entity-table-meta";
 import { executeRawQuery } from "../../db/queries/raw-sql";
 import { createSystemUser, defineFeature } from "../../engine";

package/src/pipeline/__tests__/escape-hatch.integration.test.ts

@@ -3,7 +3,7 @@
 // Real HTTP calls + setupTestStack — never createTestDispatcher.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { defineUnmanagedTable } from "../../db/entity-table-meta";
 import { defineFeature } from "../../engine";
 import { createTestUser, setupTestStack, type TestStack } from "../../stack";

package/src/pipeline/__tests__/event-dedup.integration.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { defineFeature, type SaveContext } from "../../engine";
 import {

package/src/pipeline/__tests__/event-define-event-strict.integration.test.ts

@@ -11,7 +11,7 @@
 //   3. r.defineEvent returns `{ name: qualifiedName, schema }` — callers
 //      pass `def.name` to ctx.appendEvent without building the qn manually.
 import { afterEach, beforeAll, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { selectMany } from "../../db/query";
 import { defineFeature } from "../../engine";
 import { eventsTable } from "../../event-store";

package/src/pipeline/__tests__/event-dispatcher-batch-delivery.test.ts

@@ -0,0 +1,178 @@
+// #3227 — deliverEvents' batchHandler fast-path: batch success must land
+// the exact outcome the per-event loop would produce, a batch throw falls
+// back to per-event delivery without bumping attempts for the failed
+// batch attempt itself, and pending-gap resolution still splits pending
+// vs new ids the same way it does for the per-event path.
+
+import { beforeAll, describe, expect, test } from "bun:test";
+import type { AppContext } from "../../engine/types";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
+import type { EventConsumer } from "../event-dispatcher";
+import {
+  type ConsumerStateRow,
+  deliverEvents,
+  type StoredEventRow,
+} from "../event-dispatcher-delivery";
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+});
+
+function stubContext(): AppContext {
+  return {
+    db: {} as unknown as AppContext["db"],
+    redis: {} as unknown as AppContext["redis"],
+    registry: {} as unknown as AppContext["registry"],
+  } as AppContext;
+}
+
+function stubEvent(id: bigint): StoredEventRow {
+  return {
+    id,
+    aggregateId: "agg-1",
+    aggregateType: "widget",
+    tenantId: "tenant-1",
+    version: 1,
+    type: "widget.created",
+    eventVersion: 1,
+    payload: {},
+    metadata: { userId: "system" },
+    createdAt: Temporal.Now.instant(),
+    createdBy: "system",
+  };
+}
+
+function stubState(overrides: Partial<ConsumerStateRow> = {}): ConsumerStateRow {
+  return {
+    name: "consumer",
+    instanceId: "shared",
+    lastProcessedEventId: 0n,
+    status: "idle",
+    attempts: 0,
+    rearmCount: 0,
+    pendingGaps: [],
+    lastError: null,
+    updatedAt: Temporal.Now.instant(),
+    ...overrides,
+  };
+}
+
+describe("deliverEvents — batchHandler fast-path", () => {
+  test("batch success calls batchHandler once, never handler, and matches the per-event outcome", async () => {
+    const rows = [1n, 2n, 3n].map(stubEvent);
+    const batchCalls: string[][] = [];
+    let handlerCalls = 0;
+
+    const batchConsumer: EventConsumer = {
+      name: "search",
+      batchHandler: async (events) => {
+        batchCalls.push(events.map((e) => e.id));
+      },
+      handler: async () => {
+        handlerCalls += 1;
+      },
+    };
+    const perEventConsumer: EventConsumer = {
+      name: "search",
+      handler: async () => {
+        // no-op — succeeds for every event, same as the batch above
+      },
+    };
+
+    const batchOutcome = await deliverEvents(batchConsumer, rows, stubContext(), 10, stubState());
+    const perEventOutcome = await deliverEvents(
+      perEventConsumer,
+      rows,
+      stubContext(),
+      10,
+      stubState(),
+    );
+
+    expect(batchCalls).toEqual([["1", "2", "3"]]);
+    expect(handlerCalls).toBe(0);
+    expect(batchOutcome).toEqual(perEventOutcome);
+    expect(batchOutcome.cursor).toBe(3n);
+    expect(batchOutcome.attempts).toBe(0);
+    expect(batchOutcome.lastError).toBeNull();
+    expect(batchOutcome.processed).toBe(3);
+    expect(batchOutcome.failed).toBe(0);
+  });
+
+  test("pending-gap ids resolve the same way as per-event delivery", async () => {
+    const rows = [4n, 7n, 11n, 12n].map(stubEvent);
+    const consumer: EventConsumer = {
+      name: "search",
+      batchHandler: async () => {
+        // succeeds
+      },
+      handler: async () => {
+        throw new Error("handler must not run on batch success");
+      },
+    };
+
+    const outcome = await deliverEvents(
+      consumer,
+      rows,
+      stubContext(),
+      10,
+      stubState({ lastProcessedEventId: 10n }),
+    );
+
+    expect(outcome.resolvedPendingIds).toEqual([4n, 7n]);
+    expect(outcome.cursor).toBe(12n);
+  });
+
+  test("batch throws, one poison row: falls back to per-event delivery without bumping attempts for the batch failure itself", async () => {
+    const rows = [1n, 2n, 3n, 4n, 5n].map(stubEvent);
+    const handlerCalls: string[] = [];
+    const consumer: EventConsumer = {
+      name: "search",
+      errorPolicy: { maxAttempts: 2 },
+      batchHandler: async () => {
+        throw new Error("batch failed");
+      },
+      handler: async (event) => {
+        handlerCalls.push(event.id);
+        if (event.id === "3") throw new Error("poison event");
+      },
+    };
+
+    const first = await deliverEvents(consumer, rows, stubContext(), 10, stubState());
+    expect(first.cursor).toBe(2n);
+    expect(first.attempts).toBe(1);
+    expect(first.deadLettered).toBe(false);
+    expect(handlerCalls).toEqual(["1", "2", "3"]);
+
+    const remaining = [3n, 4n, 5n].map(stubEvent);
+    const second = await deliverEvents(
+      consumer,
+      remaining,
+      stubContext(),
+      10,
+      stubState({ lastProcessedEventId: first.cursor, attempts: first.attempts }),
+    );
+    expect(second.attempts).toBe(2);
+    expect(second.deadLettered).toBe(true);
+  });
+
+  test("batch throws with skipApplyErrors: true skips the poison row and delivers the rest via handler", async () => {
+    const rows = [1n, 2n, 3n, 4n, 5n].map(stubEvent);
+    const handlerCalls: string[] = [];
+    const consumer: EventConsumer = {
+      name: "search",
+      errorPolicy: { skipApplyErrors: true },
+      batchHandler: async () => {
+        throw new Error("batch failed");
+      },
+      handler: async (event) => {
+        handlerCalls.push(event.id);
+        if (event.id === "3") throw new Error("poison event");
+      },
+    };
+
+    const outcome = await deliverEvents(consumer, rows, stubContext(), 10, stubState());
+
+    expect(outcome.cursor).toBe(5n);
+    expect(handlerCalls).toEqual(["1", "2", "3", "4", "5"]);
+  });
+});

package/src/pipeline/__tests__/event-dispatcher-batch-handler.integration.test.ts

@@ -0,0 +1,143 @@
+// #3227 — batchHandler wired into a real dispatcher pass: a successful
+// batch is delivered in one call (handler never runs, cursor lands at the
+// last event) and a batch+handler failure still dead-letters through the
+// normal errorPolicy machinery, delivering the poisoned event via handler
+// exactly once before it does.
+
+import { afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { createTenantDb, type TenantDb } from "../../db/tenant-db";
+import { defineFeature } from "../../engine";
+import type { StoredEvent } from "../../event-store";
+import {
+  createEventDispatcher,
+  type EventConsumer,
+  type EventDispatcher,
+  getConsumerState,
+} from "../../pipeline";
+import {
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "../../stack";
+import { sharedWidgetEntity, sharedWidgetTable } from "../../testing";
+
+const executor = createEventStoreExecutor(sharedWidgetTable, sharedWidgetEntity, {
+  entityName: "widget",
+});
+
+const feature = defineFeature("batchhandlerintegration", (r) => {
+  r.entity("widget", sharedWidgetEntity);
+});
+
+const admin = TestUsers.admin;
+let stack: TestStack;
+let tdb: TenantDb;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [feature], systemHooks: [] });
+  await unsafeCreateEntityTable(stack.db, sharedWidgetEntity, "widget");
+  tdb = createTenantDb(stack.db, admin.tenantId);
+});
+
+afterEach(async () => {
+  await resetEventStore(stack, ["read_widgets"]);
+});
+
+async function appendWidget(name: string): Promise<string> {
+  const created = await executor.create({ name }, admin, tdb);
+  if (!created.isSuccess) throw new Error("create failed");
+  return String(created.data.id);
+}
+
+function buildDispatcher(consumers: readonly EventConsumer[]): EventDispatcher {
+  return createEventDispatcher({
+    db: stack.db,
+    consumers,
+    context: { db: stack.db, redis: stack.redis.redis, registry: stack.registry },
+    batchSize: 200,
+    // No timer/LISTEN involved — runOnce() below drives every pass
+    // explicitly, so pollIntervalMs never fires a competing pass.
+    pollIntervalMs: 60_000,
+  });
+}
+
+describe("event-dispatcher — batchHandler", () => {
+  test("a successful batch delivers all events in one call, handler stays unused, cursor lands on the last event", async () => {
+    const consumerName = "batchhandlerintegration:success";
+    const batchSizes: number[] = [];
+    const batchIds: bigint[] = [];
+    const handlerIds: string[] = [];
+
+    const consumer: EventConsumer = {
+      name: consumerName,
+      batchHandler: async (events) => {
+        batchSizes.push(events.length);
+        for (const event of events) batchIds.push(BigInt(event.id));
+      },
+      handler: async (event) => {
+        handlerIds.push(event.aggregateId);
+      },
+    };
+
+    const dispatcher = buildDispatcher([consumer]);
+    await dispatcher.ensureRegistered();
+
+    await appendWidget("one");
+    await appendWidget("two");
+    await appendWidget("three");
+
+    const result = await dispatcher.runOnce();
+
+    expect(batchSizes).toEqual([3]);
+    expect(handlerIds).toEqual([]);
+    expect(result.byConsumer[consumerName]).toEqual({ processed: 3, failed: 0 });
+
+    const state = await getConsumerState(stack.db, consumerName);
+    expect(state?.status).toBe("idle");
+    expect(state?.lastProcessedEventId).toBe(batchIds.at(-1));
+  });
+
+  test("batch throws, handler poisons the 2nd event: dead-letters at maxAttempts, first event delivered exactly once via handler", async () => {
+    const consumerName = "batchhandlerintegration:poison";
+    const handlerCalls: StoredEvent[] = [];
+    let poisonAggregateId: string | undefined;
+
+    const consumer: EventConsumer = {
+      name: consumerName,
+      errorPolicy: { maxAttempts: 2 },
+      batchHandler: async () => {
+        throw new Error("batch always fails in this test");
+      },
+      handler: async (event) => {
+        handlerCalls.push(event);
+        if (event.aggregateId === poisonAggregateId) {
+          throw new Error("poisoned event");
+        }
+      },
+    };
+
+    const dispatcher = buildDispatcher([consumer]);
+    await dispatcher.ensureRegistered();
+
+    await appendWidget("first");
+    poisonAggregateId = await appendWidget("second");
+
+    const firstPass = await dispatcher.runOnce();
+    expect(firstPass.byConsumer[consumerName]?.failed).toBeGreaterThan(0);
+
+    const secondPass = await dispatcher.runOnce();
+    expect(secondPass.byConsumer[consumerName]).toBeDefined();
+
+    const state = await getConsumerState(stack.db, consumerName);
+    expect(state?.status).toBe("dead");
+
+    const firstEventDeliveries = handlerCalls.filter(
+      (event) => event.aggregateId === handlerCalls[0]?.aggregateId,
+    );
+    expect(firstEventDeliveries).toHaveLength(1);
+    expect(state?.lastProcessedEventId).toBe(BigInt(handlerCalls[0]?.id ?? "0"));
+  });
+});