@cosmicdrift/kumiko-framework 0.307.0 → 0.309.0

package/src/pipeline/__tests__/msp-rebuild.integration.test.ts

@@ -17,7 +17,8 @@
 
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
 import { sql } from "@cosmicdrift/kumiko-framework/db";
-import { z } from "zod";
+import * as z from "zod";
+import type { DbConnection, DbTx } from "../../db/connection";
 import { integer as pgInteger, table as pgTable, uuid as pgUuid } from "../../db/dialect";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { asRawClient, selectMany, updateMany } from "../../db/query";
@@ -35,6 +36,8 @@ import {
   TestUsers,
   unsafeCreateEntityTable,
 } from "../../stack";
+import { waitFor } from "../../testing";
+import { SHARED_INSTANCE_SENTINEL } from "../event-consumer-state";
 
 // --- Fixtures: two aggregates feeding one MSP + two cornered MSPs ---
 
@@ -69,6 +72,10 @@ const sagaStateTable = pgTable("read_mspreb_saga_state", {
   id: pgUuid("id").primaryKey(),
 });
 
+// Captured for the raw-SQL out-of-order-commit test below, which appends
+// events directly (bypassing the write handler) to control commit timing.
+let invoiceBilledEventName = "";
+
 const feature = defineFeature("mspreb", (r) => {
   r.entity("msp-reb-invoice", invoiceEntity);
   r.entity("msp-reb-payment", paymentEntity);
@@ -78,6 +85,7 @@ const feature = defineFeature("mspreb", (r) => {
     z.object({ customer: z.uuid(), cents: z.number().int() }),
     { piiFields: "none" },
   );
+  invoiceBilledEventName = invoiceBilled.name;
   const paymentReceived = r.defineEvent(
     "payment-received",
     z.object({ customer: z.uuid(), cents: z.number().int() }),
@@ -231,6 +239,47 @@ async function runFullDispatcher(): Promise<void> {
   await stack.eventDispatcher?.runOnce();
 }
 
+// Appends an invoice-billed event directly (not via the write handler) so
+// the caller controls exactly when its id is committed and visible. `version`
+// must be distinct per call for the SAME aggregateId — a repeated version on
+// an uncommitted row makes Postgres block the second INSERT until the first
+// transaction resolves (unique-constraint ambiguity), which would deadlock
+// against a caller still holding that first transaction open.
+async function insertInvoiceBilledEvent(
+  db: DbConnection | DbTx,
+  customer: string,
+  cents: number,
+  version: number,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `INSERT INTO "kumiko_events"
+       (aggregate_id, aggregate_type, tenant_id, version, type, payload, metadata, created_by)
+     VALUES ($1::uuid, 'msp-reb-invoice', $2::uuid, $3, $4, $5::jsonb, '{}'::jsonb, 'test')`,
+    [
+      customer,
+      admin.tenantId,
+      version,
+      invoiceBilledEventName,
+      JSON.stringify({ customer, cents }),
+    ],
+  );
+}
+
+async function readPendingGaps(
+  consumerName: string,
+): Promise<ReadonlyArray<{ from: string; to: string; xmax: string }>> {
+  const rows = (await asRawClient(stack.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 ?? [];
+}
+
 // --- Tests ---
 
 describe("rebuildMultiStreamProjection — rebuildable read-model", () => {
@@ -310,6 +359,72 @@ describe("rebuildMultiStreamProjection — rebuildable read-model", () => {
     const [row] = await selectMany(stack.db, balanceTable, { customer: carol });
     expect(row).toMatchObject({ invoicesCents: 42_00, paymentsCents: 0 });
   });
+
+  test("rebuild handoff seeds a pending gap for a lower-id write still open during replay, and the live dispatcher delivers it exactly once (#3231)", async () => {
+    const frank = "00000000-0000-4000-8000-00000000f106";
+    await updateMany(
+      stack.db,
+      eventConsumerStateTable,
+      { status: "disabled", updatedAt: sql`now()` },
+      { name: SAGA_MSP },
+    );
+
+    // Tx A grabs the LOW id first but holds its transaction open —
+    // uncommitted, so it's invisible to the rebuild's horizon read below.
+    let releaseA!: () => void;
+    const aGate = new Promise<void>((resolve) => {
+      releaseA = resolve;
+    });
+    let markAInserted!: () => void;
+    const aInserted = new Promise<void>((resolve) => {
+      markAInserted = resolve;
+    });
+    const aDone = stack.db
+      .begin(async (tx: DbTx) => {
+        await insertInvoiceBilledEvent(tx, frank, 1_00, 1);
+        markAInserted();
+        await aGate;
+      })
+      .catch(() => {});
+    await aInserted;
+
+    // Commits AFTER A grabbed its id, so it's the higher, only-visible id
+    // when the rebuild reads its horizon.
+    await insertInvoiceBilledEvent(stack.db, frank, 100_00, 2);
+
+    try {
+      const result = await rebuildMultiStreamProjection(BALANCE_MSP, {
+        db: stack.db,
+        registry: stack.registry,
+      });
+      // Only the visible (higher-id) event was replayed — A's row is still
+      // invisible, so it must not be double-counted once it does arrive.
+      const [afterRebuild] = await selectMany(stack.db, balanceTable, { customer: frank });
+      expect(afterRebuild).toMatchObject({ invoicesCents: 100_00 });
+      expect(result.lastProcessedEventId).toBeGreaterThan(0n);
+
+      const gapsAfterRebuild = await readPendingGaps(BALANCE_MSP);
+      expect(gapsAfterRebuild).not.toEqual([]);
+    } finally {
+      releaseA();
+      await aDone;
+    }
+
+    // A commits now — the live dispatcher must deliver it exactly once via
+    // the seeded pending gap, landing at 1_00 + 100_00, not double-applied.
+    await waitFor(
+      async () => {
+        await runFullDispatcher();
+        const [row] = await selectMany(stack.db, balanceTable, { customer: frank });
+        expect(row).toMatchObject({ invoicesCents: 101_00 });
+        expect(await readPendingGaps(BALANCE_MSP)).toEqual([]);
+      },
+      { delays: [20, 100, 500, 1000, 3000] },
+    );
+
+    const [finalRow] = await selectMany(stack.db, balanceTable, { customer: frank });
+    expect(finalRow).toMatchObject({ invoicesCents: 101_00 });
+  });
 });
 
 describe("rebuildMultiStreamProjection — guard rails", () => {

package/src/pipeline/__tests__/multi-stream-projection.integration.test.ts

@@ -7,7 +7,7 @@
 // per MSP consumer, dead-letters on repeated handler failures.
 
 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, uuid as pgUuid } from "../../db/dialect";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { asRawClient, selectMany } from "../../db/query";

package/src/pipeline/__tests__/pending-gap-ranges.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import type { PendingGapEntry } from "../event-consumer-state";
+import { capPendingGapsBelowCursor, subtractSortedIdsFromRanges } from "../pending-gap-ranges";
+
+function gap(from: string, to: string, xmax = "100"): PendingGapEntry {
+  return { from, to, xmax };
+}
+
+describe("subtractSortedIdsFromRanges", () => {
+  test("no ids leaves ranges unchanged", () => {
+    const ranges = [gap("10", "20")];
+    expect(subtractSortedIdsFromRanges(ranges, [])).toEqual([gap("10", "20")]);
+  });
+
+  test("id in the middle of a range splits it in two", () => {
+    const ranges = [gap("10", "20")];
+    expect(subtractSortedIdsFromRanges(ranges, [15n])).toEqual([gap("10", "14"), gap("16", "20")]);
+  });
+
+  test("ids at from- and to-boundary shrink the range from inside", () => {
+    const ranges = [gap("10", "20")];
+    expect(subtractSortedIdsFromRanges(ranges, [10n, 20n])).toEqual([gap("11", "19")]);
+  });
+
+  test("all ids of a range make it disappear", () => {
+    const ranges = [gap("10", "12")];
+    expect(subtractSortedIdsFromRanges(ranges, [10n, 11n, 12n])).toEqual([]);
+  });
+
+  test("ids between, before and after ranges affect nothing", () => {
+    const ranges = [gap("10", "20"), gap("30", "40")];
+    expect(subtractSortedIdsFromRanges(ranges, [5n, 25n, 45n])).toEqual([
+      gap("10", "20"),
+      gap("30", "40"),
+    ]);
+  });
+
+  test("multiple ranges with ids spread across them use a single pointer pass", () => {
+    const ranges = [gap("10", "20"), gap("30", "40"), gap("50", "60")];
+    const ids = [15n, 30n, 40n, 55n];
+    expect(subtractSortedIdsFromRanges(ranges, ids)).toEqual([
+      gap("10", "14"),
+      gap("16", "20"),
+      gap("31", "39"),
+      gap("50", "54"),
+      gap("56", "60"),
+    ]);
+  });
+
+  test("xmax is preserved on every surviving part", () => {
+    const ranges = [gap("10", "20", "999")];
+    expect(subtractSortedIdsFromRanges(ranges, [15n])).toEqual([
+      gap("10", "14", "999"),
+      gap("16", "20", "999"),
+    ]);
+  });
+});
+
+describe("capPendingGapsBelowCursor", () => {
+  test("cursor 0n caps everything away", () => {
+    const ranges = [gap("10", "20")];
+    expect(capPendingGapsBelowCursor(ranges, 0n)).toEqual([]);
+  });
+
+  test("range fully below cursor is unchanged", () => {
+    const ranges = [gap("10", "20")];
+    expect(capPendingGapsBelowCursor(ranges, 100n)).toEqual([gap("10", "20")]);
+  });
+
+  test("range straddling the cursor is truncated to cursor - 1", () => {
+    const ranges = [gap("10", "20")];
+    expect(capPendingGapsBelowCursor(ranges, 15n)).toEqual([gap("10", "14")]);
+  });
+
+  test("range with to == cursor is truncated to cursor - 1", () => {
+    const ranges = [gap("10", "20")];
+    expect(capPendingGapsBelowCursor(ranges, 20n)).toEqual([gap("10", "19")]);
+  });
+
+  test("range with from == cursor is dropped entirely", () => {
+    const ranges = [gap("20", "30")];
+    expect(capPendingGapsBelowCursor(ranges, 20n)).toEqual([]);
+  });
+
+  test("range with from > cursor is dropped entirely", () => {
+    const ranges = [gap("25", "30")];
+    expect(capPendingGapsBelowCursor(ranges, 20n)).toEqual([]);
+  });
+
+  test("xmax is preserved on surviving ranges", () => {
+    const ranges = [gap("10", "20", "777")];
+    expect(capPendingGapsBelowCursor(ranges, 15n)).toEqual([gap("10", "14", "777")]);
+  });
+});

package/src/pipeline/__tests__/post-query-hook.integration.test.ts

@@ -10,7 +10,7 @@
 // nicht createTestDispatcher.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { createEntity, createTextField, defineFeature } from "../../engine";
 import type { PostQueryHookFn } from "../../engine/types";
 import { setupTestStack, type TestStack, TestUsers } from "../../stack";

package/src/pipeline/__tests__/public-intake-runtime-gate.integration.test.ts

@@ -2,7 +2,7 @@
 // so the static boot check passes and only the runtime gate can stop the write.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import type { SchemaTable } from "../../db";
 import type { DbRunner } from "../../db/connection";
 import { createEventStoreExecutor } from "../../db/event-store-executor";

package/src/pipeline/__tests__/query-projection.integration.test.ts

@@ -5,7 +5,7 @@
 // grant — r.systemScope() or a declared escapeHatch on the handler.
 
 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__/rate-limit-default.integration.test.ts

@@ -4,7 +4,7 @@
 // rate-limit/__tests__/dispatcher-l3.integration.test.ts.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { createSystemUser, defineFeature } from "../../engine";
 import type { RateLimitConfig, RateLimitDecision, RateLimitResolver } from "../../rate-limit";
 import { createTestUser, setupTestStack, type TestStack, testTenantId } from "../../stack";

package/src/pipeline/__tests__/rebuild-poison-quarantine.integration.test.ts

@@ -15,7 +15,7 @@
 //   - SQL error (aborts the tx → proves the savepoint is load-bearing)
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { integer as pgInteger, table as pgTable, uuid as pgUuid } from "../../db/dialect";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { asRawClient } from "../../db/query";

package/src/pipeline/__tests__/search-consumer-named-events.integration.test.ts

@@ -3,7 +3,7 @@
 // the search index. The event payload only carries the named event's own
 // field slice, so the consumer reads the live projection row instead.
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { asRawClient, buildEntityTable, createEventStoreExecutor, createTenantDb } from "../../db";
 import { createEntity, createTextField, defineFeature } from "../../engine";
 import {

package/src/pipeline/__tests__/system-identity-switch.integration.test.ts

@@ -2,7 +2,7 @@
 // r.systemScope() or { escapeHatch }. 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 { createEventStoreExecutor } from "../../db/event-store-executor";
 import { buildEntityTable } from "../../db/table-builder";
 import {

package/src/pipeline/__tests__/try-append-event.integration.test.ts

@@ -21,7 +21,7 @@
 // may pick either writer as the winner.
 
 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__/unsafe-raw-escape-hatch.integration.test.ts

@@ -4,7 +4,7 @@
 // escape-hatch.integration.test.ts (fw#2855).
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { executeRawQuery } from "../../db/queries/raw-sql";
 import { defineFeature } from "../../engine";
 import { createTestUser, setupTestStack, type TestStack } from "../../stack";

package/src/pipeline/dispatch-stream.ts

@@ -1,3 +1,4 @@
+import type { AccessInvalidationCredential } from "../api/sse-broker";
 import { hasAccess } from "../engine/access";
 import type { SessionUser } from "../engine/types";
 import {
@@ -74,12 +75,16 @@ async function* executeStreamInner(
   const invalidated = new Promise<void>((resolve) => {
     resolveInvalidated = resolve;
   });
+  const streamCredential: AccessInvalidationCredential = {
+    ...(user.sid !== undefined && { sid: user.sid }),
+    ...(user.pat?.tokenId !== undefined && { patTokenId: user.pat.tokenId }),
+  };
   const unsubscribeAccessInvalidation = ctx.sseBroker?.subscribeAccessInvalidation(
     user.id,
     () => {
       resolveInvalidated?.();
     },
-    user.sid,
+    streamCredential,
   );
 
   let iterator: AsyncIterator<unknown> | undefined;

package/src/pipeline/event-dispatcher-delivery.ts

@@ -2,7 +2,7 @@
 // `Temporal` TYPE that ConsumerStateRow.updatedAt/StoredEventRow.createdAt
 // resolve against (same #1438 dual-package-hazard pattern as event-store.ts).
 import { Temporal as TemporalPolyfill } from "temporal-polyfill";
-import { requestContext } from "../api/request-context";
+import { type RequestContextData, requestContext } from "../api/request-context";
 import type { DbConnection, DbTx } from "../db/connection";
 import {
   insertConsumerIfAbsent,
@@ -10,6 +10,7 @@ import {
   rearmDeadConsumer,
   recordConsumerPassFailure,
   selectConsumerForUpdateSkipLocked,
+  selectProvablyIdleConsumerPairs,
   updateConsumerDeliveryOutcome,
 } from "../db/queries/event-consumer";
 import {
@@ -20,7 +21,7 @@ import {
 import { coerceRow, extractTableInfo } from "../db/query";
 import { qnScope } from "../engine/qualified-name";
 import type { AppContext } from "../engine/types";
-import { eventsTable, toStoredEvent as rowToStoredEvent } from "../event-store";
+import { eventsTable, toStoredEvent as rowToStoredEvent, type StoredEvent } from "../event-store";
 import {
   emitDispatcherError,
   emitEventConsumerLag,
@@ -159,6 +160,39 @@ export async function acquireConsumerState(
   return { state, skip: null };
 }
 
+// Read-only pre-check run once per doPass, before any consumer's turn opens
+// a transaction (event-dispatcher.ts's doPass/runConsumerTurn). Keyed like
+// consumerBackoff/inFlightTurns: `${name}:${instanceId}`. Consumers not
+// provably idle (missing row, dead, pending gaps, or an event past cursor)
+// simply don't appear in the result — the caller falls through to the
+// existing acquireConsumerState/FOR UPDATE SKIP LOCKED path unchanged.
+//
+// Race: an event that commits between this query and the next tick CAN
+// make this snapshot stale — that's expected, not a bug. What it can't do
+// is get silently lost: the append fires NOTIFY (or the next poll tick
+// fires regardless), triggering a fresh doPass. That pass's own pre-check
+// sees the new head id and excludes the consumer from "idle"; a new
+// pending_gap only ever gets created when a later turn's fetch (id > the
+// old cursor) walks past the row that committed late, and this same
+// pre-check reads pending_gaps live on every pass, so it observes that gap
+// too. In short: this can under-report idleness for one tick, never
+// over-report it.
+export async function selectIdleConsumerKeys(
+  db: DbConnection,
+  pairs: ReadonlyArray<{ readonly name: string; readonly instanceId: string }>,
+): Promise<ReadonlySet<string>> {
+  if (pairs.length === 0) return new Set();
+  const names = pairs.map((p) => p.name);
+  const instanceIds = pairs.map((p) => p.instanceId);
+  const idlePairs = await selectProvablyIdleConsumerPairs(
+    db,
+    names,
+    instanceIds,
+    ConsumerStatuses.dead,
+  );
+  return new Set(idlePairs.map((p) => `${p.name}:${p.instanceId}`));
+}
+
 // Shared pre-registration: one row per (consumer, shard), cursor = 0,
 // status = idle. Shared-delivery consumers use SHARED_INSTANCE_SENTINEL;
 // per-instance consumers use the dispatcher's instanceId. Idempotent
@@ -230,12 +264,15 @@ export type DeliveryOutcome = {
   readonly resolvedPendingIds: readonly bigint[];
 };
 
-// Deliver events to the consumer's handler in events.id order. Halt-on-
-// poison: a throw breaks the loop, the cursor stays at the last successful
-// event, and attempts climb. At the consumer's effectiveMaxAttempts
-// (errorPolicy.maxAttempts ?? maxAttempts) the caller persists status=
-// "dead" and the consumer is parked until ops intervenes (see
-// restartConsumer / skipPoisonEvent).
+// Deliver events to the consumer's handler in events.id order, or — when
+// the consumer wires a batchHandler — through it in one call first. Halt-
+// on-poison: a throw breaks the per-event loop, the cursor stays at the
+// last successful event, and attempts climb. At the consumer's
+// effectiveMaxAttempts (errorPolicy.maxAttempts ?? maxAttempts) the caller
+// persists status="dead" and the consumer is parked until ops intervenes
+// (see restartConsumer / skipPoisonEvent). A batch that throws falls back
+// to the same per-event loop for the same events — the batch failure
+// itself does not bump attempts, only a per-event failure does.
 export async function deliverEvents(
   consumer: EventConsumer,
   events: ReadonlyArray<StoredEventRow>,
@@ -262,6 +299,17 @@ export async function deliverEvents(
     lastError = null;
   };
 
+  if (consumer.batchHandler && events.length > 0) {
+    const batchSucceeded = await tryApplyBatch(consumer, events, context);
+    if (batchSucceeded) {
+      for (const row of events) resolve(row.id);
+      processed = events.length;
+      return { cursor, attempts, lastError, deadLettered, processed, failed, resolvedPendingIds };
+    }
+    // fall through to the per-event loop below; the batch failure itself
+    // does NOT bump attempts — only a per-event failure does.
+  }
+
   for (const row of events) {
     try {
       await applyEvent(consumer, row, context);
@@ -285,42 +333,89 @@ export async function deliverEvents(
   return { cursor, attempts, lastError, deadLettered, processed, failed, resolvedPendingIds };
 }
 
-async function applyEvent(
+// Shared requestContext scope for one apply — event-derived fields
+// (correlationId, causationId, writeOrigin) come from `causationSource`;
+// applyEvent uses the event itself, applyBatch uses the LAST event of the
+// turn (see applyBatch for why). requestId falls back to a fresh id
+// because the dispatcher runs outside any HTTP request (background poll),
+// and a stable log-correlation handle is still useful for debugging.
+// #3043 — an event this apply writes is attributed to the consumer, not
+// to whatever wrote the triggering event; causationId already links back.
+function buildConsumerRequestScope(
   consumer: EventConsumer,
-  row: StoredEventRow,
-  context: AppContext,
-): Promise<void> {
-  // Propagate causation: if the handler calls ctx.appendEvent, the new
-  // event should record THIS event as its cause. correlationId is
-  // inherited unchanged — it survives the hop across streams by design.
-  // requestId falls back to a fresh id because the dispatcher runs
-  // outside any HTTP request (background poll), and a stable log-
-  // correlation handle is still useful for debugging.
-  const stored = rowToStoredEvent(row);
-  const correlationId = stored.metadata.correlationId ?? requestContext.generateId();
-  const causationId = String(stored.id);
+  causationSource: StoredEvent,
+): RequestContextData {
+  const correlationId = causationSource.metadata.correlationId ?? requestContext.generateId();
+  const causationId = String(causationSource.id);
   const requestId = requestContext.generateId();
   // The job-trigger consumer's handleEvent stamps event-triggered jobs from this.
-  const rawStoredWriteOrigin = stored.metadata.writeOrigin;
+  const rawStoredWriteOrigin = causationSource.metadata.writeOrigin;
   const writeOrigin =
     rawStoredWriteOrigin === undefined
       ? undefined
       : (parseWriteOrigin(rawStoredWriteOrigin) ?? UNPARSEABLE_STORED_WRITE_ORIGIN);
-  // #3043 — an event this apply writes is attributed to the consumer, not
-  // to whatever wrote the triggering event; causationId already links back.
-  await requestContext.run(
-    {
-      requestId,
-      correlationId,
-      causationId,
-      handler: consumer.name,
-      feature: consumer.featureName ?? qnScope(consumer.name),
-      writeOrigin,
-    },
-    async () => {
-      await consumer.handler(stored, context);
-    },
-  );
+  return {
+    requestId,
+    correlationId,
+    causationId,
+    handler: consumer.name,
+    feature: consumer.featureName ?? qnScope(consumer.name),
+    writeOrigin,
+  };
+}
+
+async function applyEvent(
+  consumer: EventConsumer,
+  row: StoredEventRow,
+  context: AppContext,
+): Promise<void> {
+  const stored = rowToStoredEvent(row);
+  await requestContext.run(buildConsumerRequestScope(consumer, stored), async () => {
+    await consumer.handler(stored, context);
+  });
+}
+
+// Runs the consumer's batchHandler for the whole turn under one
+// requestContext scope, attempted before the per-event loop. Returns
+// false on failure instead of rethrowing — the caller falls back to
+// per-event delivery for the exact same events, so a batch failure must
+// not itself count as an applyEvent failure or bump attempts.
+async function tryApplyBatch(
+  consumer: EventConsumer,
+  events: ReadonlyArray<StoredEventRow>,
+  context: AppContext,
+): Promise<boolean> {
+  try {
+    await applyBatch(consumer, events, context);
+    return true;
+  } catch (e) {
+    const errMessage = e instanceof Error ? e.message : String(e);
+    context.log?.warn(
+      `event-dispatcher: ${consumer.name} batch of ${events.length} failed, falling back to per-event delivery: ${errMessage}`,
+    );
+    return false;
+  }
+}
+
+async function applyBatch(
+  consumer: EventConsumer,
+  events: ReadonlyArray<StoredEventRow>,
+  context: AppContext,
+): Promise<void> {
+  const batchHandler = consumer.batchHandler;
+  // skip: deliverEvents only calls this for consumers that wire a batchHandler.
+  if (!batchHandler) return;
+  const stored = events.map((row) => rowToStoredEvent(row));
+  // correlationId/causationId/writeOrigin come from the LAST row — a
+  // batch-appended event's causation is attributed to the turn's most
+  // recent input, same as chaining N applyEvent calls would leave the
+  // requestContext at after the final one.
+  const lastStored = stored.at(-1);
+  // skip: deliverEvents never calls this with an empty turn.
+  if (!lastStored) return;
+  await requestContext.run(buildConsumerRequestScope(consumer, lastStored), async () => {
+    await batchHandler(stored, context);
+  });
 }
 
 // Best-effort mode: record the error on the skip counter so ops can alert on