@cosmicdrift/kumiko-framework 0.307.0 → 0.308.0

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.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"));
+  });
+});

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

@@ -0,0 +1,94 @@
+// A provably-idle consumer's doPass turn must not take the state row's
+// FOR UPDATE SKIP LOCKED lock: that lock sets xmax on the row, requires an
+// xid, writes WAL, and forces a commit fsync — on every poll tick, forever,
+// even with zero events in the system. The pre-check in
+// selectIdleConsumerKeys (event-dispatcher-delivery.ts) must keep an idle
+// consumer's row untouched entirely, verified here via the row's own
+// system column `xmax`: unchanged across an idle runOnce() means no lock
+// was ever taken on it.
+
+import { afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { asRawClient } from "../../db/query";
+import { createTenantDb, type TenantDb } from "../../db/tenant-db";
+import { defineFeature } from "../../engine";
+import {
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "../../stack";
+import { sharedWidgetEntity, sharedWidgetTable } from "../../testing";
+import { SHARED_INSTANCE_SENTINEL } from "../event-consumer-state";
+
+const executor = createEventStoreExecutor(sharedWidgetTable, sharedWidgetEntity, {
+  entityName: "widget",
+});
+
+let observed: Array<{ name: string }> = [];
+
+const idleFeature = defineFeature("idletest", (r) => {
+  r.entity("widget", sharedWidgetEntity);
+
+  r.multiStreamProjection({
+    name: "observer",
+    apply: {
+      "widget.created": async (event) => {
+        observed.push({ name: event.payload["name"] as string });
+      },
+    },
+  });
+});
+
+const admin = TestUsers.admin;
+const qn = "idletest:projection:observer";
+let stack: TestStack;
+let tdb: TenantDb;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [idleFeature],
+    systemHooks: [],
+  });
+  await unsafeCreateEntityTable(stack.db, sharedWidgetEntity, "widget");
+  tdb = createTenantDb(stack.db, admin.tenantId);
+});
+
+afterEach(async () => {
+  observed = [];
+  await resetEventStore(stack, ["read_widgets"]);
+});
+
+async function appendWidget(name: string): Promise<void> {
+  await executor.create({ name }, admin, tdb);
+}
+
+async function readConsumerRowXmax(): Promise<string> {
+  const rows = (await asRawClient(stack.db).unsafe(
+    `SELECT xmax::text FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2`,
+    [qn, SHARED_INSTANCE_SENTINEL],
+  )) as ReadonlyArray<{ xmax: string }>;
+  const xmax = rows[0]?.xmax;
+  if (xmax === undefined) throw new Error("consumer state row missing");
+  return xmax;
+}
+
+describe("idle event-dispatcher passes take no row lock", () => {
+  test("xmax is unchanged across an idle runOnce() after draining, then a new event is still delivered", async () => {
+    await appendWidget("drain-me");
+    await stack.eventDispatcher?.runOnce();
+    expect(observed).toEqual([{ name: "drain-me" }]);
+
+    const xmaxBeforeIdlePass = await readConsumerRowXmax();
+
+    await stack.eventDispatcher?.runOnce();
+    const xmaxAfterIdlePass = await readConsumerRowXmax();
+    expect(xmaxAfterIdlePass).toBe(xmaxBeforeIdlePass);
+
+    await appendWidget("wake-me");
+    const result = await stack.eventDispatcher?.runOnce();
+    expect(result?.processed).toBeGreaterThan(0);
+    expect(observed).toEqual([{ name: "drain-me" }, { name: "wake-me" }]);
+  });
+});

package/src/pipeline/__tests__/event-dispatcher-start-from.integration.test.ts

@@ -13,12 +13,12 @@
 // event-triggered workflow hits in production.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import type { DbTx } from "../../db/connection";
-import { insertOne } from "../../db/query";
+import type { DbConnection, DbTx } from "../../db/connection";
+import { asRawClient, insertOne } from "../../db/query";
 import type { AppContext } from "../../engine/types";
 import { eventsTable } from "../../event-store";
 import { createTestDb, type TestDb, TestUsers } from "../../stack";
-import { createEventConsumerStateTable } from "../event-consumer-state";
+import { createEventConsumerStateTable, SHARED_INSTANCE_SENTINEL } from "../event-consumer-state";
 import { createEventDispatcher, type EventConsumer, getConsumerState } from "../event-dispatcher";
 import { fetchPendingEvents } from "../event-dispatcher-delivery";
 
@@ -49,6 +49,40 @@ async function appendHistoricalEvent(type: string): Promise<void> {
   historicalEventCount += 1;
 }
 
+// Grabs an id (like appendHistoricalEvent) but never commits — the row
+// stays invisible until the caller releases and awaits the enclosing tx.
+async function appendEventRawHoldingTx(tx: DbTx, type: string): Promise<void> {
+  await asRawClient(tx).unsafe(
+    `INSERT INTO "kumiko_events"
+       (aggregate_id, aggregate_type, tenant_id, version, type, payload, metadata, created_by)
+     VALUES ($1::uuid, 'start-from-test-source', $2::uuid, 1, $3, '{}'::jsonb, '{}'::jsonb, 'test')`,
+    [crypto.randomUUID(), admin.tenantId, type],
+  );
+}
+
+async function selectVisibleMaxEventId(): Promise<bigint> {
+  const rows = (await asRawClient(testDb.db).unsafe(
+    `SELECT COALESCE(MAX("id"), 0)::text AS max FROM "kumiko_events"`,
+  )) as ReadonlyArray<{ max: string }>;
+  return BigInt(rows[0]?.max ?? "0");
+}
+
+async function readPendingGaps(
+  db: DbConnection,
+  consumerName: string,
+): Promise<ReadonlyArray<{ from: string; to: string; xmax: string }>> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT "pending_gaps", jsonb_typeof("pending_gaps") AS kind FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2`,
+    [consumerName, SHARED_INSTANCE_SENTINEL],
+  )) as ReadonlyArray<{
+    pending_gaps: ReadonlyArray<{ from: string; to: string; xmax: string }>;
+    kind: string;
+  }>;
+  // A double-encoded write lands as a jsonb string scalar, not an array.
+  if (rows[0] && rows[0].kind !== "array") throw new Error(`pending_gaps is jsonb ${rows[0].kind}`);
+  return rows[0]?.pending_gaps ?? [];
+}
+
 beforeAll(async () => {
   // createTestDb() already materializes kumiko_events (see stack/db.ts).
   testDb = await createTestDb();
@@ -173,4 +207,70 @@ describe("EventConsumer.startFrom", () => {
     const afterRedeploy = await getConsumerState(testDb.db, consumer.name);
     expect(afterRedeploy?.lastProcessedEventId).toBe(advanced?.lastProcessedEventId);
   });
+
+  test("'now' registered while a lower-id write is still uncommitted seeds a pending gap and later delivers it", async () => {
+    const captured: string[] = [];
+    const consumer: EventConsumer = {
+      name: "test:consumer:now-out-of-order",
+      startFrom: "now",
+      handler: async (event) => {
+        captured.push(event.type);
+      },
+    };
+
+    // Tx A grabs the LOW id first but holds its transaction open — invisible
+    // to insertConsumerIfAbsent's horizon read below, same mechanic as the
+    // live-dispatcher out-of-order case in event-dispatcher-commit-order.
+    let releaseA!: () => void;
+    const aGate = new Promise<void>((resolve) => {
+      releaseA = resolve;
+    });
+    let markAInserted!: () => void;
+    const aInserted = new Promise<void>((resolve) => {
+      markAInserted = resolve;
+    });
+    const aDone = testDb.db
+      .begin(async (tx: DbTx) => {
+        await appendEventRawHoldingTx(tx, "start-from-test.low-id");
+        markAInserted();
+        await aGate;
+      })
+      .catch(() => {});
+    await aInserted;
+
+    // Tx B commits AFTER A grabbed its id, so B's id is the higher, visible
+    // MAX(id) when the consumer is registered below. A's still-open tx
+    // already consumed a sequence value, so B's actual id is one past
+    // historicalEventCount, not equal to it — read the real MAX(id).
+    await appendHistoricalEvent("start-from-test.high-id");
+    const headAtMount = await selectVisibleMaxEventId();
+
+    const dispatcher = createEventDispatcher({
+      db: testDb.db,
+      consumers: [consumer],
+      context: stubContext(),
+    });
+
+    try {
+      await dispatcher.ensureRegistered();
+
+      const seeded = await getConsumerState(testDb.db, consumer.name);
+      expect(seeded?.lastProcessedEventId).toBe(headAtMount);
+      expect(await readPendingGaps(testDb.db, consumer.name)).not.toEqual([]);
+
+      // Nothing to deliver yet — A's transaction hasn't committed.
+      const passWhileOpen = await dispatcher.runOnce();
+      expect(passWhileOpen.byConsumer[consumer.name]).toEqual({ processed: 0, failed: 0 });
+    } finally {
+      releaseA();
+      await aDone;
+    }
+
+    // A commits now — its lower id is delivered as a resolved pending gap,
+    // even though the cursor already sits above it from registration.
+    const pass = await dispatcher.runOnce();
+    expect(pass.byConsumer[consumer.name]).toEqual({ processed: 1, failed: 0 });
+    expect(captured).toEqual(["start-from-test.low-id"]);
+    expect(await readPendingGaps(testDb.db, consumer.name)).toEqual([]);
+  });
 });

package/src/pipeline/__tests__/fetch-for-writing.integration.test.ts

@@ -8,7 +8,7 @@
 //      consecutive versions without re-reading the DB.
 
 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 { asRawClient } from "../../db/query-api";
 import { buildEntityTable } from "../../db/table-builder";

package/src/pipeline/__tests__/idempotency-transient-failure.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__/job-trigger-consumer.integration.test.ts

@@ -17,7 +17,7 @@
 // produce, not something exercised end-to-end by any test today.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { entityEventName } from "../../db";
 import { defineFeature } from "../../engine";
 import { createInMemoryFileProvider, type InMemoryFileProvider } from "../../files";

package/src/pipeline/__tests__/lifecycle-pipeline.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, spyOn, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import {
   createEntity,
   createRegistry,