@cosmicdrift/kumiko-framework 0.306.0 → 0.308.0

package/src/pipeline/event-dispatcher.ts

@@ -1,4 +1,5 @@
 import type { DbTx, PgClient } from "../db/connection";
+import { selectSnapshotXmax, selectSnapshotXmin } from "../db/queries/event-consumer";
 import type { AppContext } from "../engine/types";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
 import { EVENTS_PUBSUB_CHANNEL, type StoredEvent } from "../event-store";
@@ -11,18 +12,22 @@ import {
   type Meter,
   type Tracer,
 } from "../observability";
-import { SHARED_INSTANCE_SENTINEL } from "./event-consumer-state";
+import { type PendingGapEntry, SHARED_INSTANCE_SENTINEL } from "./event-consumer-state";
 import {
   acquireConsumerState,
   consumerInstanceId,
+  type DeliveryOutcome,
   deliverEvents,
   emitLagFromTx,
   fetchPendingEvents,
   markProcessing,
+  type PersistedConsumerOutcome,
   persistConsumerOutcome,
   persistConsumerPassFailure,
   preRegisterConsumers,
+  selectIdleConsumerKeys,
 } from "./event-dispatcher-delivery";
+import { partitionBurntGaps, splitRangeExcludingIds, toIdRanges } from "./pending-gap-ranges";
 
 // Async event-dispatcher — the "AsyncDaemon"-pendant for Kumiko.
 //
@@ -37,7 +42,9 @@ import {
 //   2. SELECT state row FOR UPDATE SKIP LOCKED
 //      — multi-instance-safe: if another poller holds the lock, this pass
 //        skips this consumer and tries the next. No duplicate delivery.
-//   3. SELECT events WHERE id > lastProcessedEventId ORDER BY id ASC LIMIT batchSize
+//   3. SELECT events WHERE id > lastProcessedEventId, PLUS any ranges still
+//      tracked in pending_gaps (ids invisible on an earlier turn that may
+//      have committed since) — ORDER BY id ASC LIMIT batchSize
 //   4. For each event: call the consumer's handler
 //        - handler throws → increment attempts, mark status="dead" at
 //          maxAttempts, surface lastError, STOP this consumer's pass
@@ -61,6 +68,21 @@ import {
 
 export type EventConsumerHandler = (event: StoredEvent, ctx: AppContext) => Promise<void>;
 
+// Batch variant of EventConsumerHandler — receives all events of one
+// delivery turn in id order, meant for side-effect sinks (search index,
+// bulk fan-out) that can collapse a turn into one round-trip. `handler`
+// stays mandatory and is the fallback: if the batch throws, the dispatcher
+// re-delivers the same events one by one through `handler`, so errorPolicy
+// (maxAttempts, skipApplyErrors, dead-lettering) applies per event exactly
+// as before. The batch handler must therefore be replay-safe — a partially
+// applied batch gets re-applied event by event under the same idempotency
+// rule as `handler`. Events appended from inside a batch handler carry the
+// LAST event's causation id only.
+export type EventConsumerBatchHandler = (
+  events: readonly StoredEvent[],
+  ctx: AppContext,
+) => Promise<void>;
+
 // Per-consumer error policy. When skipApplyErrors is true and handler throws,
 // the dispatcher logs the error, advances the cursor past the offending event,
 // and keeps delivering — instead of the default retry + dead-letter flow.
@@ -78,6 +100,9 @@ export type EventConsumerErrorPolicy = {
 export type EventConsumer = {
   readonly name: string;
   readonly handler: EventConsumerHandler;
+  // Optional batch fast-path for this turn's events — see
+  // EventConsumerBatchHandler for the fallback and replay-safety contract.
+  readonly batchHandler?: EventConsumerBatchHandler;
   readonly errorPolicy?: EventConsumerErrorPolicy;
   // Owning feature — when present, the dispatcher skips this consumer's
   // pass while the feature is globally disabled. Events remain in the store
@@ -240,6 +265,15 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
   // entry — the next failure (if any) starts a fresh backoff from scratch.
   const consumerBackoff = new Map<string, { consecutiveFailures: number; retryAtMs: number }>();
 
+  // Dedup flag for the idle pre-check's error log (doPass) — a broken
+  // pre-check falls back to the expensive-but-correct path silently on
+  // every tick (see doPass), which must not mean silently in the logs too:
+  // ops needs to see it degrade once, not have every poll tick spam the
+  // same line. Cleared the moment the pre-check succeeds again, so a later,
+  // unrelated outage gets its own fresh log line instead of staying
+  // permanently suppressed by this process's flag.
+  let idlePreCheckErrorLogged = false;
+
   let running = false;
   // Separate from `running` on purpose: pre-registration of consumer state
   // rows is a one-time boot action, while running/timer/LISTEN is a
@@ -255,17 +289,100 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
   // NOTIFYs (subscription drop, crash mid-commit).
   let pgUnlisten: (() => Promise<void>) | null = null;
 
-  // Serialises concurrent runOnce() calls from both wake-up sources (timer
-  // + any future explicit nudge). Mirrors outbox-poller's passInFlight
-  // pattern so behaviour under races stays predictable.
-  let passInFlight: Promise<DispatcherPassResult> | null = null;
+  // Bounds how many consumer turns hold a DB transaction at once. Each turn's
+  // db.begin() checks out one pool connection, plus any writes the handler
+  // itself makes via context.db — the app db pool defaults to postgres-js's
+  // max=10 (db/connection.ts, no DATABASE_POOL_MAX override) and is shared
+  // with HTTP request handlers, so turns can't be allowed to claim it all.
+  // A pool no larger than this limit can deadlock: every connection held by
+  // an open turn TX while each handler waits for one more.
+  const MAX_CONCURRENT_CONSUMER_TURNS = 4;
+  let activeConsumerTurns = 0;
+  const consumerTurnWaiters: Array<() => void> = [];
+
+  async function acquireConsumerTurnSlot(): Promise<() => void> {
+    if (activeConsumerTurns >= MAX_CONCURRENT_CONSUMER_TURNS) {
+      // The releasing turn hands its slot over directly (count unchanged),
+      // so a synchronous acquire in between cannot overshoot the limit.
+      await new Promise<void>((resolve) => consumerTurnWaiters.push(resolve));
+    } else {
+      activeConsumerTurns++;
+    }
+    let released = false;
+    return () => {
+      // skip: already released — finally-blocks calling this twice must not
+      // free the same slot twice
+      if (released) return;
+      released = true;
+      const nextWaiter = consumerTurnWaiters.shift();
+      if (nextWaiter) nextWaiter();
+      else activeConsumerTurns--;
+    };
+  }
 
-  async function drainPassInFlight(): Promise<void> {
-    if (passInFlight) {
-      await passInFlight.catch(() => {
-        // skip: errors already recorded per-consumer inside the pass
-      });
+  // Per-(consumer, instanceId) turn guard, so one slow consumer never holds
+  // back the others. Keyed like consumerBackoff: a consumer already running
+  // its turn hands back that same promise instead of starting a second one.
+  const inFlightTurns = new Map<string, Promise<{ processed: number; failed: number }>>();
+
+  async function runConsumerTurn(
+    consumer: EventConsumer,
+    effective: ReadonlySet<string> | undefined,
+    idleKeys: ReadonlySet<string>,
+  ): Promise<{ processed: number; failed: number }> {
+    const key = `${consumer.name}:${consumerInstanceId(consumer, options.instanceId)}`;
+    const existing = inFlightTurns.get(key);
+    if (existing) return existing;
+
+    // Feature-gate, backoff-gate and idle-gate are resolved synchronously,
+    // before any promise is registered — a gated consumer must resolve
+    // without ever occupying inFlightTurns, or it would look "still
+    // running" forever.
+    if (effective && consumer.featureName && !effective.has(consumer.featureName)) {
+      return { processed: 0, failed: 0 };
+    }
+    const backoff = consumerBackoff.get(key);
+    if (backoff && backoff.retryAtMs > Date.now()) {
+      return { processed: 0, failed: 0 };
+    }
+    // Idle-gate: doPass already proved this consumer has nothing to do
+    // (see selectIdleConsumerKeys) — skip the turn without ever opening a
+    // db.begin/FOR UPDATE SKIP LOCKED (see doPass for why that matters).
+    // Clear any prior backoff same as a successful pass would: the
+    // backoff-gate above already confirmed retryAtMs has elapsed, and
+    // "provably nothing to deliver" is itself proof the consumer isn't
+    // presently failing.
+    if (idleKeys.has(key)) {
+      consumerBackoff.delete(key);
+      return { processed: 0, failed: 0 };
     }
+
+    // Registered before awaiting the slot — a turn queued behind the
+    // concurrency limit still counts as in-flight, so it isn't started twice.
+    const turn = (async () => {
+      const releaseSlot = await acquireConsumerTurnSlot();
+      try {
+        return await processConsumer(consumer);
+      } finally {
+        releaseSlot();
+      }
+    })();
+    inFlightTurns.set(key, turn);
+    try {
+      return await turn;
+    } finally {
+      if (inFlightTurns.get(key) === turn) inFlightTurns.delete(key);
+    }
+  }
+
+  async function drainInFlightTurns(): Promise<void> {
+    await Promise.all(
+      [...inFlightTurns.values()].map((turn) =>
+        turn.catch(() => {
+          // skip: errors already recorded per-consumer inside the pass
+        }),
+      ),
+    );
   }
 
   async function runOnce(): Promise<DispatcherPassResult> {
@@ -274,13 +391,7 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
         "EventDispatcher.runOnce() called before start() — consumer state rows are not registered. Call start() first (production) or ensureRegistered() (tests after truncating kumiko_event_consumers).",
       );
     }
-    if (passInFlight) return passInFlight;
-    passInFlight = doPass();
-    try {
-      return await passInFlight;
-    } finally {
-      passInFlight = null;
-    }
+    return doPass();
   }
 
   async function doPass(): Promise<DispatcherPassResult> {
@@ -301,30 +412,58 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
     // SYSTEM_TENANT_ID returnt (typisch: union-of-all-tier-features).
     const effective = context.effectiveFeatures?.(SYSTEM_TENANT_ID);
 
-    // Seriell pro consumer. Parallelisierung wäre möglich (je eigene TX), aber
-    // das einfache Modell reicht für v1 — jeder consumer hat geringe
-    // per-event-Arbeit (network call at worst). Bei hunderten Events pro
-    // Batch lohnt sich Parallelisierung — Optimierung für später.
-    for (const consumer of consumers) {
-      // Feature-gate: consumers tagged with a featureName get paused while
-      // that feature is globally disabled. Cursor stays put — events accumulate
-      // and are re-delivered in order when the feature is re-enabled.
-      if (effective && consumer.featureName && !effective.has(consumer.featureName)) {
-        byConsumer[consumer.name] = { processed: 0, failed: 0 };
-        continue;
-      }
-      // Backoff-gate: a consumer whose last pass threw waits out its
-      // exponential delay before being tried again — see the catch in
-      // processConsumer. Other consumers are unaffected; only this one's
-      // turn is skipped this tick.
-      const backoffKey = `${consumer.name}:${consumerInstanceId(consumer, options.instanceId)}`;
-      const backoff = consumerBackoff.get(backoffKey);
-      if (backoff && backoff.retryAtMs > Date.now()) {
-        byConsumer[consumer.name] = { processed: 0, failed: 0 };
-        continue;
+    // Lock-free pre-check, once per pass: which consumers are provably idle
+    // (no locking, no xid, no WAL — see selectIdleConsumerKeys). Read
+    // outside any transaction, before a single db.begin/FOR UPDATE SKIP
+    // LOCKED opens — an idle deployment (most consumers, most ticks)
+    // otherwise pays a row lock + WAL record + commit fsync per consumer
+    // per tick for nothing.
+    //
+    // A failure here (e.g. a transient DB blip) must not abort the whole
+    // pass — timer/LISTEN callers swallow doPass()'s rejection silently
+    // (see start()), which would mean no log, no persistConsumerPassFailure,
+    // and no backoff for every consumer this tick. Falling back to "nothing
+    // proven idle" instead routes every consumer through its normal
+    // acquireConsumerState path, whose own try/catch already covers this.
+    let idleKeys: ReadonlySet<string>;
+    try {
+      idleKeys = await selectIdleConsumerKeys(
+        db,
+        consumers.map((consumer) => ({
+          name: consumer.name,
+          instanceId: consumerInstanceId(consumer, options.instanceId),
+        })),
+      );
+      idlePreCheckErrorLogged = false;
+    } catch (e) {
+      idleKeys = new Set();
+      // Log once per outage, not once per poll tick — see
+      // idlePreCheckErrorLogged above. Every consumer still gets delivered
+      // correctly this tick (fallback above), so this is a degradation
+      // signal for ops, not a delivery failure.
+      if (!idlePreCheckErrorLogged) {
+        idlePreCheckErrorLogged = true;
+        const msg = e instanceof Error ? e.message : String(e);
+        const logMsg = `[event-dispatcher] idle pre-check failed, falling back to per-consumer locking every tick until it recovers: ${msg}`;
+        if (context.log) {
+          context.log.error(logMsg);
+        } else {
+          console.error(logMsg);
+        }
       }
-      const perConsumer = await processConsumer(consumer);
-      byConsumer[consumer.name] = perConsumer;
+    }
+
+    // Every consumer runs its own turn concurrently (own TX, own cursor,
+    // own backoff/feature-gate/idle-gate) — a slow consumer no longer
+    // blocks the others' delivery until it commits, see runConsumerTurn.
+    const results = await Promise.all(
+      consumers.map(async (consumer) => {
+        const perConsumer = await runConsumerTurn(consumer, effective, idleKeys);
+        return [consumer.name, perConsumer] as const;
+      }),
+    );
+    for (const [name, perConsumer] of results) {
+      byConsumer[name] = perConsumer;
       totalProcessed += perConsumer.processed;
       totalFailed += perConsumer.failed;
     }
@@ -376,20 +515,85 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
         // staying permanently suppressed by this process's Set.
         reportedDeadConsumers.delete(`${consumer.name}:${instanceId}`);
 
-        const events = await fetchPendingEvents(tx, acquired.state.lastProcessedEventId, batchSize);
-        // skip: nothing to deliver — no markProcessing/persistConsumerOutcome write,
-        // so an idle consumer doesn't burn a WAL record on every poll tick.
-        if (events.length === 0) {
+        const oldCursor = acquired.state.lastProcessedEventId;
+        const pendingGaps = acquired.state.pendingGaps;
+        // xmin BEFORE the fetch: a range is provably burnt only once this has
+        // passed the xmax recorded with it. Only needed when ranges exist.
+        const xminNow = pendingGaps.length > 0 ? await selectSnapshotXmin(tx) : "0";
+        const events = await fetchPendingEvents(tx, oldCursor, batchSize, toIdRanges(pendingGaps));
+        const fetchedIds = events.map((e) => e.id);
+        const truncated = events.length === batchSize;
+
+        // Burnt: no visible id this turn, the fetch is proven to have
+        // covered the range (LIMIT can otherwise cut it off early), and
+        // xmin passed its recorded xmax — every xact that could still
+        // produce a row has finished without one ever appearing.
+        const { burnt: burntGaps, surviving: survivingGaps } = partitionBurntGaps(
+          pendingGaps,
+          fetchedIds,
+          truncated,
+          xminNow,
+        );
+
+        // skip: nothing to deliver and no burnt gap to clean up. The
+        // doPass idle pre-check (selectIdleConsumerKeys) already keeps the
+        // common idle case out of this transaction entirely — reaching
+        // here with an empty fetch means the pre-check couldn't prove
+        // idleness (pending gaps forced a fetch, or a race window). By this
+        // point acquireConsumerState's FOR UPDATE has already taken the
+        // lock, so skipping markProcessing/persistConsumerOutcome only
+        // avoids extra writes, not that lock's own WAL record.
+        if (events.length === 0 && burntGaps.length === 0) {
           span.setAttribute("consumer.skip_reason", "no_pending_events");
           return;
         }
         await markProcessing(tx, consumer.name, instanceId);
 
-        const outcome = await deliverEvents(consumer, events, context, maxAttempts, acquired.state);
+        const outcome: DeliveryOutcome =
+          events.length > 0
+            ? await deliverEvents(consumer, events, context, maxAttempts, acquired.state)
+            : {
+                cursor: oldCursor,
+                attempts: acquired.state.attempts,
+                lastError: acquired.state.lastError,
+                deadLettered: false,
+                processed: 0,
+                failed: 0,
+                resolvedPendingIds: [],
+              };
         processed = outcome.processed;
         failed = outcome.failed;
 
-        await persistConsumerOutcome(tx, consumer.name, instanceId, outcome);
+        // Carve delivered/skip-applied ids out of the surviving ranges —
+        // an id still fetched-but-unresolved (halt-on-poison stopped before
+        // it) stays put, since it's below the cursor and only pending_gaps
+        // will ever retry it.
+        const keptGaps = survivingGaps.flatMap((gap) =>
+          splitRangeExcludingIds(gap, outcome.resolvedPendingIds),
+        );
+        // New gaps as ranges between consecutive fetched ids, so a huge id
+        // jump (retention prune) costs one entry, not one per missing id.
+        // Their xmax is read after the fetch; any later read is only more
+        // conservative, so it is fetched lazily.
+        const newWindowIds = fetchedIds.filter((id) => id > oldCursor && id <= outcome.cursor);
+        const newGapBounds: Array<readonly [bigint, bigint]> = [];
+        let prev = oldCursor;
+        for (const id of newWindowIds) {
+          if (id > prev + 1n) newGapBounds.push([prev + 1n, id - 1n]);
+          prev = id;
+        }
+        const xmaxNow = newGapBounds.length > 0 ? await selectSnapshotXmax(tx) : "";
+        const newGaps: PendingGapEntry[] = newGapBounds.map(([from, to]) => ({
+          from: from.toString(),
+          to: to.toString(),
+          xmax: xmaxNow,
+        }));
+        const persistedOutcome: PersistedConsumerOutcome = {
+          ...outcome,
+          pendingGaps: [...keptGaps, ...newGaps],
+        };
+
+        await persistConsumerOutcome(tx, consumer.name, instanceId, persistedOutcome);
         await emitLagFromTx(tx, consumer.name, instanceId, outcome.cursor, meter);
       });
 
@@ -544,7 +748,7 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
       }
 
       // Drain any in-flight pass so shutdown observes consistent state.
-      await drainPassInFlight();
+      await drainInFlightTurns();
       // preRegistered stays true — the rows survive stop(). runOnce()
       // after a stop() still works (tests stop the timer and then drain
       // deterministically).
@@ -555,7 +759,7 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
       preRegistered = true;
     },
 
-    drain: drainPassInFlight,
+    drain: drainInFlightTurns,
 
     runOnce,
   };

package/src/pipeline/index.ts

@@ -28,6 +28,7 @@ export type {
   ConsumerRecoveryState,
   DispatcherPassResult,
   EventConsumer,
+  EventConsumerBatchHandler,
   EventConsumerHandler,
   EventDispatcher,
   EventDispatcherOptions,

package/src/pipeline/msp-rebuild.ts

@@ -3,6 +3,8 @@ import {
   markConsumerRebuildFailed,
   resetConsumerForMspRebuild,
   selectConsumerForUpdate,
+  selectEventIdHorizonWithMissingRanges,
+  selectSnapshotXmax,
   updateConsumerRebuildCursor,
 } from "../db/queries/event-consumer";
 import {
@@ -28,6 +30,7 @@ import { emitProjectionRebuild } from "../observability/standard-metrics";
 import type { Meter } from "../observability/types/metric";
 import { SHARED_INSTANCE_SENTINEL } from "./event-consumer-state";
 import type { MultiStreamApplyContext } from "./multi-stream-apply-context";
+import { capPendingGapsBelowCursor, subtractSortedIdsFromRanges } from "./pending-gap-ranges";
 import type { RebuildResult } from "./projection-rebuild";
 
 // Rebuild a multi-stream projection (MSP) from the event log. Symmetric to
@@ -61,6 +64,20 @@ import type { RebuildResult } from "./projection-rebuild";
 //   - Advance cursor to last processed event id, status=idle.
 //   - Swap the shadow into public (brief ACCESS EXCLUSIVE, not the replay).
 //
+// Handoff to the live dispatcher (#3231): the replay horizon (MAX(id) at the
+// time selectEventIdHorizonWithMissingRanges ran) plus the id gaps open below
+// it in that same snapshot are read up front and the replay is bounded to
+// `id <= horizon`. A transaction holding a lower id can still be in-flight
+// during replay — its row is invisible here and, once committed, would sit
+// below the cursor with no live-dispatcher gap tracking to ever revisit it.
+// Seeding pending_gaps closes that: ids actually read during replay are
+// carved out (delivered here, so a live pass must never redeliver them), and
+// whatever survives is capped below the written cursor — the live dispatcher
+// owns everything from `id > cursor` onward on its own. Those surviving
+// ranges are the shape of the snapshot taken before the replay, but their
+// xmax is read after the replay — a later xmax can only delay when the live
+// dispatcher burns the gap, never make it burn a still-in-flight range early.
+//
 // Failure: outer catch writes status="dead" + lastError so ops sees the
 // failure after the TX rolled back. Use restartConsumer to clear dead.
 //
@@ -145,10 +162,13 @@ export async function rebuildMultiStreamProjection(
     // Outside the rebuild tx, like the schema: idempotent DDL colliding
     // inside the tx would roll the whole replay back.
     if (skipApplyErrors) await createRebuildDeadLetterTable(db);
+    const replayedIds: bigint[] = [];
     await db.begin(async (tx: DbTx) => {
       await resetConsumerForMspRebuild(tx, mspName, SHARED_INSTANCE_SENTINEL);
       await selectConsumerForUpdate(tx, mspName, SHARED_INSTANCE_SENTINEL);
 
+      const { horizon, gaps: seededGaps } = await selectEventIdHorizonWithMissingRanges(tx);
+
       await assertLiveColumnsMatchMeta(tx, meta, mspName);
       await assertLiveTableHasNoRowLevelSecurity(tx, meta.tableName, mspName);
       await buildShadowTable(tx, meta);
@@ -168,10 +188,13 @@ export async function rebuildMultiStreamProjection(
           createdAt: Temporal.Instant;
           createdBy: string;
         };
+        // Events past `horizon` are the live dispatcher's to deliver via
+        // `id > cursor` — bounding the replay here is what keeps the two
+        // paths from ever double-applying the same event.
         const events = await selectMany<EventRow>(
           tx,
           eventsTable,
-          { type: [...subscribedTypes] },
+          { type: [...subscribedTypes], id: { lte: horizon } },
           { orderBy: { col: "id", direction: "asc" } },
         );
 
@@ -194,6 +217,7 @@ export async function rebuildMultiStreamProjection(
             db: tx,
             tenantId: row.tenantId,
           });
+          replayedIds.push(row.id);
           const applyFn = msp.apply[row.type];
           if (!applyFn) continue;
           if (skipApplyErrors) {
@@ -221,11 +245,25 @@ export async function rebuildMultiStreamProjection(
       if (skipped.length > 0) {
         await recordRebuildDeadLetters(tx, mspName, skipped);
       }
+      // Every id actually read this replay (applied or skip-applied) is
+      // resolved — a live pass must never redeliver it. Anything surviving
+      // that subtraction is capped below the written cursor: a gap at or
+      // above it is the live dispatcher's own `id > cursor` territory, not
+      // pending_gaps'. No events replayed (cursor stays 0) means no gap can
+      // sit below it either.
+      const survivingGaps = subtractSortedIdsFromRanges(seededGaps, replayedIds);
+      const cappedGaps = capPendingGapsBelowCursor(survivingGaps, lastProcessedEventId);
+      const postReplayXmax = cappedGaps.length > 0 ? await selectSnapshotXmax(tx) : null;
+      const pendingGaps =
+        postReplayXmax === null
+          ? cappedGaps
+          : cappedGaps.map((gap) => ({ ...gap, xmax: postReplayXmax }));
       await updateConsumerRebuildCursor(
         tx,
         mspName,
         SHARED_INSTANCE_SENTINEL,
         lastProcessedEventId,
+        pendingGaps,
       );
       await swapShadowIntoLive(tx, meta.tableName);
     });

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

@@ -0,0 +1,120 @@
+import type { PendingIdRange } from "../db/queries/event-store";
+import type { PendingGapEntry } from "./event-consumer-state";
+
+export function toIdRanges(gaps: readonly PendingGapEntry[]): PendingIdRange[] {
+  return gaps.map((g) => ({ from: BigInt(g.from), to: BigInt(g.to) }));
+}
+
+export function rangeContainsId(range: PendingGapEntry, id: bigint): boolean {
+  return id >= BigInt(range.from) && id <= BigInt(range.to);
+}
+
+// A range is only provably burnt (rolled back, not just slow) once it's
+// certain the fetch would have surfaced any of its ids had they been
+// visible. LIMIT can cut a fetch off before reaching the range's ids —
+// `to < maxFetchedId` proves the scan passed the range regardless of the
+// cutoff, since ORDER BY id ASC LIMIT N always includes every matching id
+// below the largest one it did return.
+export function isRangeFullyCoveredByFetch(
+  range: PendingGapEntry,
+  truncated: boolean,
+  maxFetchedId: bigint | null,
+): boolean {
+  if (!truncated) return true;
+  if (maxFetchedId === null) return false;
+  return BigInt(range.to) < maxFetchedId;
+}
+
+// A gap is burnt when none of its ids showed up in this turn's fetch, the
+// fetch is proven to have covered it, and its recorded xmax is behind this
+// turn's xmin (every xact that could still produce a row has finished).
+export function partitionBurntGaps(
+  gaps: readonly PendingGapEntry[],
+  fetchedIds: readonly bigint[],
+  truncated: boolean,
+  xminNow: string,
+): { readonly burnt: PendingGapEntry[]; readonly surviving: PendingGapEntry[] } {
+  const maxFetchedId = fetchedIds.at(-1) ?? null;
+  const burnt: PendingGapEntry[] = [];
+  const surviving: PendingGapEntry[] = [];
+  for (const gap of gaps) {
+    const hasVisibleId = fetchedIds.some((id) => rangeContainsId(gap, id));
+    const isBurnt =
+      !hasVisibleId &&
+      isRangeFullyCoveredByFetch(gap, truncated, maxFetchedId) &&
+      BigInt(gap.xmax) <= BigInt(xminNow);
+    (isBurnt ? burnt : surviving).push(gap);
+  }
+  return { burnt, surviving };
+}
+
+// Carves `excludeIds` (delivered or skip-applied this turn) out of `range`,
+// yielding 0-2 sub-ranges. xmax is preserved on every surviving piece.
+export function splitRangeExcludingIds(
+  range: PendingGapEntry,
+  excludeIds: readonly bigint[],
+): PendingGapEntry[] {
+  const from = BigInt(range.from);
+  const to = BigInt(range.to);
+  const inRange = excludeIds
+    .filter((id) => id >= from && id <= to)
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  if (inRange.length === 0) return [range];
+  const parts: PendingGapEntry[] = [];
+  let cursor = from;
+  for (const id of inRange) {
+    if (id > cursor)
+      parts.push({ from: cursor.toString(), to: (id - 1n).toString(), xmax: range.xmax });
+    cursor = id + 1n;
+  }
+  if (cursor <= to) parts.push({ from: cursor.toString(), to: to.toString(), xmax: range.xmax });
+  return parts;
+}
+
+// Same carve-out as splitRangeExcludingIds, but for many ranges against many
+// ids at once — an MSP rebuild's replay reads events in ascending id order,
+// so a single forward pointer over `sortedIds` (both inputs already sorted,
+// ranges non-overlapping) avoids scanning the full id list per range.
+export function subtractSortedIdsFromRanges(
+  ranges: readonly PendingGapEntry[],
+  sortedIds: readonly bigint[],
+): PendingGapEntry[] {
+  if (sortedIds.length === 0) return [...ranges];
+  const result: PendingGapEntry[] = [];
+  let cursor = 0;
+  for (const range of ranges) {
+    const from = BigInt(range.from);
+    const to = BigInt(range.to);
+    let id = sortedIds[cursor];
+    while (id !== undefined && id < from) {
+      cursor++;
+      id = sortedIds[cursor];
+    }
+    const idsInRange: bigint[] = [];
+    while (id !== undefined && id <= to) {
+      idsInRange.push(id);
+      cursor++;
+      id = sortedIds[cursor];
+    }
+    result.push(...splitRangeExcludingIds(range, idsInRange));
+  }
+  return result;
+}
+
+// Ranges above the written cursor belong to the live dispatcher's own
+// `id > cursor` territory; a range straddling it is truncated at cursor - 1.
+export function capPendingGapsBelowCursor(
+  gaps: readonly PendingGapEntry[],
+  cursor: bigint,
+): PendingGapEntry[] {
+  if (cursor <= 0n) return [];
+  const capped: PendingGapEntry[] = [];
+  for (const gap of gaps) {
+    const from = BigInt(gap.from);
+    if (from >= cursor) continue;
+    const to = BigInt(gap.to);
+    const cappedTo = to >= cursor ? cursor - 1n : to;
+    capped.push({ ...gap, to: cappedTo.toString() });
+  }
+  return capped;
+}