@cosmicdrift/kumiko-framework 0.306.0 → 0.308.0

package/src/api/server.ts

@@ -50,6 +50,7 @@ import {
   type GlobalIpRateLimitOptions,
   globalIpRateLimit,
 } from "../rate-limit";
+import { deriveSearchAdapterConfig } from "../search/derive-search-adapter-config";
 import type { SearchAdapter } from "../search/types";
 import { assertUnreachable, generateId } from "../utils";
 import { NO_ROUTE_MATCH_HEADER_NAME, PUBLIC_API_PATHS } from "./api-constants";
@@ -488,6 +489,16 @@ export function buildServer(options: ServerOptions): KumikoServer {
   // @cast-boundary engine-bridge — searchAdapter is an optional context-extension
   const searchAdapter = (contextWithObservability as { searchAdapter?: SearchAdapter })
     .searchAdapter;
+  // Adapter is built before the registry exists (app boot order) — hand it
+  // the registry-derived default config here so it can lazily configure
+  // each tenant index on first access instead of requiring per-tenant app
+  // wiring.
+  const derivedSearchConfig = searchAdapter
+    ? deriveSearchAdapterConfig(options.registry)
+    : undefined;
+  if (searchAdapter && derivedSearchConfig) {
+    searchAdapter.setDefaultConfig?.(derivedSearchConfig);
+  }
 
   const sseConsumerEnabled = options.eventDispatcher?.systemConsumers?.sse ?? true;
   const searchConsumerEnabled = options.eventDispatcher?.systemConsumers?.search ?? true;

package/src/api/sse-broker.ts

@@ -12,6 +12,26 @@ export type SseEvent = {
   data: Record<string, unknown>;
 };
 
+// What a publish invalidates. "user" is the broadest (and the historical
+// default — every scope narrower than this is an opt-in from a caller that
+// knows exactly which credential(s) it revoked).
+export type AccessInvalidationScope =
+  | { readonly kind: "user" }
+  | { readonly kind: "all-except-session"; readonly keptSessionId: string }
+  | { readonly kind: "sessions"; readonly sessionIds: readonly string[] }
+  | { readonly kind: "pat-tokens"; readonly tokenIds: readonly string[] };
+
+// What a stream's own listener is authenticated as — used to decide whether
+// a narrow scope (sessions/pat-tokens) applies to it. A listener with
+// neither field (should not normally happen — dispatch-stream.ts always
+// passes at least one) is treated as unidentifiable and closed by every
+// narrow scope, same fail-closed stance as a PAT stream facing a
+// sessions-scope.
+export type AccessInvalidationCredential = {
+  readonly sid?: string;
+  readonly patTokenId?: string;
+};
+
 export type SseBroker = {
   addClient(channel: string, send: (event: SseEvent) => void, close: () => void): string;
   removeClient(channel: string, clientId: string): void;
@@ -24,21 +44,56 @@ export type SseBroker = {
   // access-teardown security control (#1561) into a no-op — a revoked
   // session keeps receiving live SSE data with no error or log. A no-op
   // stub is one line for a broker that genuinely doesn't need it.
-  subscribeAccessInvalidation(userId: string, onInvalidate: () => void): () => void;
-  publishAccessInvalidation(userId: string): void;
+  subscribeAccessInvalidation(
+    userId: string,
+    onInvalidate: () => void,
+    credential?: AccessInvalidationCredential,
+  ): () => void;
+  // `scope` narrows which credential(s) close; omitted = userwide (every
+  // listener), the historical default and still what unrelated
+  // reasons (role change, membership removal) use.
+  publishAccessInvalidation(userId: string, scope?: AccessInvalidationScope): void;
 };
 
+// Fail-closed: a narrow scope only spares/limits a listener it can positively
+// match against its own credential. A listener with neither sid nor
+// patTokenId of its own can't be matched by "sessions"/"pat-tokens", so it
+// closes — same reasoning "all-except-session" already used for a sidless
+// (PAT/bearer) listener.
+export function shouldInvalidateListener(
+  credential: AccessInvalidationCredential,
+  scope: AccessInvalidationScope,
+): boolean {
+  switch (scope.kind) {
+    case "user":
+      return true;
+    case "all-except-session":
+      return credential.sid !== scope.keptSessionId;
+    case "sessions":
+      return credential.sid !== undefined
+        ? scope.sessionIds.includes(credential.sid)
+        : credential.patTokenId === undefined;
+    case "pat-tokens":
+      return credential.patTokenId !== undefined
+        ? scope.tokenIds.includes(credential.patTokenId)
+        : credential.sid === undefined;
+  }
+}
+
 export function createSseBroker(): SseBroker {
   // Purely local: no cross-replica fanout. buildServer wraps this in
   // createRedisSseBroker (fw#2625) whenever REDIS_URL is set, which is what
   // makes pushToChannel/publishAccessInvalidation reach every replica's
   // clients — this reference implementation stays single-process only.
   const channels = new Map<string, Map<string, SseClient>>();
-  // Set, not Map<listenerId, fn> — dedup key is callback reference. Every
-  // subscriber must pass a distinct closure (dispatch-stream.ts does, one
-  // per stream). Two subscribes with the SAME reference for the same user
-  // collapse into one listener, and the first unsubscribe kills both.
-  const accessInvalidationListeners = new Map<string, Set<() => void>>();
+  // Keyed by callback reference, value is the subscriber's own credential.
+  // Every subscriber must pass a distinct closure (dispatch-stream.ts does,
+  // one per stream). Two subscribes with the SAME reference for the same
+  // user collapse into one listener, and the first unsubscribe kills both.
+  const accessInvalidationListeners = new Map<
+    string,
+    Map<() => void, AccessInvalidationCredential>
+  >();
 
   function getOrCreateChannel(channel: string): Map<string, SseClient> {
     let clients = channels.get(channel);
@@ -86,14 +141,14 @@ export function createSseBroker(): SseBroker {
       return total;
     },
 
-    subscribeAccessInvalidation(userId, onInvalidate) {
+    subscribeAccessInvalidation(userId, onInvalidate, credential) {
       const channel = userAccessChannel(userId);
       let listeners = accessInvalidationListeners.get(channel);
       if (!listeners) {
-        listeners = new Set();
+        listeners = new Map();
         accessInvalidationListeners.set(channel, listeners);
       }
-      listeners.add(onInvalidate);
+      listeners.set(onInvalidate, credential ?? {});
       return () => {
         const current = accessInvalidationListeners.get(channel);
         // skip: already unsubscribed (e.g. stream ended after a publish already fired)
@@ -103,14 +158,16 @@ export function createSseBroker(): SseBroker {
       };
     },
 
-    publishAccessInvalidation(userId) {
+    publishAccessInvalidation(userId, scope) {
       const channel = userAccessChannel(userId);
       const listeners = accessInvalidationListeners.get(channel);
       // skip: no live stream is watching this user right now
       if (!listeners) return;
+      const resolvedScope: AccessInvalidationScope = scope ?? { kind: "user" };
       // Snapshot before iterating — a fired listener unsubscribes itself,
       // which would mutate `listeners` mid-iteration otherwise.
-      for (const onInvalidate of [...listeners]) {
+      for (const [onInvalidate, credential] of [...listeners]) {
+        if (!shouldInvalidateListener(credential, resolvedScope)) continue;
         onInvalidate();
       }
     },

package/src/changes.json

@@ -1,4 +1,67 @@
 [
+  {
+    "version": "0.308.0",
+    "type": "fix",
+    "title": "startFrom \"now\" and MSP rebuild hand-off no longer lose out-of-order commits"
+  },
+  {
+    "version": "0.308.0",
+    "type": "fix",
+    "title": "Idle event-dispatcher passes no longer lock consumer rows or write WAL"
+  },
+  {
+    "version": "0.308.0",
+    "type": "breaking",
+    "title": "Boot validator rejects a projectionDetail screen/section/emptyState action with no resolvable icon (fw#3234)",
+    "migration": "Every screen.actions / section.actions / section.emptyState.action entry on a projectionDetail screen, and every section.actions entry on an entityEdit screen, must resolve an icon: either an explicit `icon` on the action, or an id the shared action-icon map (@cosmicdrift/kumiko-types resolveActionIcon) already derives from the full id or its last/first kebab segment. entityEdit's own screen-level `actions` are not checked (unchanged, out of scope for this rule). An action that fails this now fails boot instead of rendering without an icon; give it an explicit `icon` or rename it to an id the map covers."
+  },
+  {
+    "version": "0.308.0",
+    "type": "improvement",
+    "title": "EventConsumer.batchHandler — turn-level batching with per-event fallback, used by the search consumer"
+  },
+  {
+    "version": "0.308.0",
+    "type": "fix",
+    "title": "Meilisearch tenant indexes are configured automatically on first access"
+  },
+  {
+    "version": "0.308.0",
+    "type": "breaking",
+    "title": "Session and PAT revoke now close their own credential's open SSE stream, not just other reasons' userwide invalidations",
+    "migration": "An app-injected SseBroker implementation must update its subscribeAccessInvalidation/publishAccessInvalidation signatures: the third parameter of subscribeAccessInvalidation is now an AccessInvalidationCredential object (`{ sid?, patTokenId? }`) instead of a bare sid string, and the second parameter of publishAccessInvalidation is now an AccessInvalidationScope object (`{ kind: \"user\" } | { kind: \"all-except-session\"; keptSessionId } | { kind: \"sessions\"; sessionIds } | { kind: \"pat-tokens\"; tokenIds }`) instead of a bare keptSessionId string. Example: `subscribeAccessInvalidation(userId, cb, sid)` becomes `subscribeAccessInvalidation(userId, cb, { sid })`, and `publishAccessInvalidation(userId, keptSessionId)` becomes `publishAccessInvalidation(userId, { kind: \"all-except-session\", keptSessionId })`."
+  },
+  {
+    "version": "0.308.0",
+    "type": "fix",
+    "title": "zod namespace import lets client bundles tree-shake unused locales"
+  },
+  {
+    "version": "0.307.0",
+    "type": "fix",
+    "title": "Event dispatcher no longer skips events that commit out of id order"
+  },
+  {
+    "version": "0.307.0",
+    "type": "fix",
+    "title": "A slow event consumer no longer delays every other consumer"
+  },
+  {
+    "version": "0.307.0",
+    "type": "breaking",
+    "title": "The public-intake gate now also covers jobs, event-triggered jobs, anonymous query roots and TenantDbs built from ctx.db.unsafeRaw (fw#3185)",
+    "migration": "An anonymous handler (roles include \"anonymous\") without personalData: \"public-intake\" now fails when personal data (pii / userOwned / recordOwned) is written through any of these paths: a job it enqueues (write or query root), a job triggered by its handler event or by an r.defineEvent it appends, a job chained from such a job, a job ctx.write/writeAs into another handler, or a TenantDb built with createTenantDb on a ctx.db.unsafeRaw / ctx.systemDb.unsafeRaw runner (including savepoints on it). The error is AccessDeniedError with details.reason \"public_intake_required\"; for jobs details.job names the job and the job run fails. Declare access: { roles: [..., \"anonymous\"], personalData: \"public-intake\" } on the root write handler if the anonymous intake is intended, otherwise stop writing the field from that path. A query root cannot declare public-intake: move the enqueue from an anonymous query handler into a write handler that declares it. Raw SQL through unsafeRaw stays escapeHatch plus audit. Jobs without a stamped origin (cron, boot, jobs dispatched outside a request, jobs queued before this release) run as before; a job whose _writeOrigin is present but invalid fails before its handler runs."
+  },
+  {
+    "version": "0.307.0",
+    "type": "fix",
+    "title": "Revoking all other sessions no longer closes the caller's own live stream"
+  },
+  {
+    "version": "0.307.0",
+    "type": "fix",
+    "title": "Version conflicts from custom writes return 409 instead of 500"
+  },
   {
     "version": "0.306.0",
     "type": "breaking",

package/src/compliance/override-schema.ts

@@ -17,7 +17,7 @@
 // Schema — wer die overriden will, würde die Profile-Identitaet
 // zerstören.
 
-import { z } from "zod";
+import * as z from "zod";
 
 // DurationSpec: { days } | { hours } — strict bedeutet beide Forms
 // muessen exakt 1 property haben (kein "{ days: 30, hours: 1 }").

package/src/crypto/__tests__/event-pii.test.ts

@@ -5,7 +5,7 @@
 
 import { afterEach, describe, expect, test } from "bun:test";
 import { normalizeEventPiiSubject } from "@cosmicdrift/kumiko-types/handlers";
-import { z } from "zod";
+import * as z from "zod";
 import { createRegistry, defineFeature } from "../../engine";
 import type { TenantId } from "../../engine/types/identifiers";
 import {

package/src/crypto/kms-adapter.ts

@@ -3,7 +3,7 @@ import {
   type SubjectId,
   subjectIdToKey,
 } from "@cosmicdrift/kumiko-types/kms-adapter-types";
-import { z } from "zod";
+import * as z from "zod";
 import type { TenantId } from "../engine/types/identifiers";
 
 export * from "@cosmicdrift/kumiko-types/kms-adapter-types";

package/src/db/__tests__/tenant-db-where-merge.integration.test.ts

@@ -6,7 +6,7 @@
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { updateRows } from "@cosmicdrift/kumiko-framework/testing";
-import { z } from "zod";
+import * as z from "zod";
 import { selectMany } from "../../bun-db";
 import {
   createEntity,

package/src/db/queries/event-consumer.ts

@@ -1,14 +1,89 @@
+import type { PendingGapEntry } from "../../pipeline/event-consumer-state";
 import type { AnyDb } from "../query";
 import { asRawClient } from "../query";
 
+// Per-turn snapshot bounds for pending-gap finality (event-dispatcher.ts's
+// processConsumer). pg_current_snapshot() is this transaction's MVCC view;
+// xmin is the oldest still-in-progress xact id in it, xmax the next
+// unassigned one. Both travel as strings — bigint/xid8 doesn't round-trip
+// through the driver as a JS number.
+export async function selectSnapshotXmin(db: AnyDb): Promise<string> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT pg_snapshot_xmin(pg_current_snapshot())::text AS xmin`,
+  )) as ReadonlyArray<{ xmin: string }>;
+  const xmin = rows[0]?.xmin;
+  if (xmin === undefined) throw new Error("selectSnapshotXmin: no row returned");
+  return xmin;
+}
+
+export async function selectSnapshotXmax(db: AnyDb): Promise<string> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT pg_snapshot_xmax(pg_current_snapshot())::text AS xmax`,
+  )) as ReadonlyArray<{ xmax: string }>;
+  const xmax = rows[0]?.xmax;
+  if (xmax === undefined) throw new Error("selectSnapshotXmax: no row returned");
+  return xmax;
+}
+
 /** Serialise against consumer-bootstrap INSERTs during event retention prune. */
 export async function lockEventConsumersShareMode(db: AnyDb): Promise<void> {
   await asRawClient(db).unsafe(`LOCK TABLE "kumiko_event_consumers" IN SHARE MODE`);
 }
 
+// The MAX(id) horizon plus every currently-open id gap below it, read from a
+// single snapshot (READ COMMITTED gives each statement its own). A gap can
+// only later fill in if some transaction holding a lower id was still
+// in-flight in that same snapshot — pg_snapshot_xip is empty otherwise, so
+// the gap CTEs short-circuit and the window scan over kumiko_events never
+// runs. Used both to seed startFrom "now" (#3231) and to seed an MSP
+// rebuild's handoff to the live dispatcher (msp-rebuild.ts).
+export async function selectEventIdHorizonWithMissingRanges(
+  db: AnyDb,
+): Promise<{ readonly horizon: bigint; readonly gaps: PendingGapEntry[] }> {
+  const rows = (await asRawClient(db).unsafe(
+    `WITH b AS (
+       SELECT COALESCE(MAX("id"), 0) AS horizon, MIN("id") AS min_id FROM "kumiko_events"
+     ),
+     r AS (
+       SELECT 1::bigint AS f, b.min_id - 1 AS t FROM b
+        WHERE b.min_id > 1 AND EXISTS (SELECT 1 FROM pg_snapshot_xip(pg_current_snapshot()))
+       UNION ALL
+       SELECT w."id" + 1, w.next_id - 1
+         FROM (SELECT "id", lead("id") OVER (ORDER BY "id") AS next_id FROM "kumiko_events") w
+        WHERE w.next_id > w."id" + 1 AND EXISTS (SELECT 1 FROM pg_snapshot_xip(pg_current_snapshot()))
+     )
+     SELECT b.horizon::text AS horizon,
+            pg_snapshot_xmax(pg_current_snapshot())::text AS xmax,
+            r.f::text AS gap_from,
+            r.t::text AS gap_to
+       FROM b LEFT JOIN r ON true
+      ORDER BY r.f`,
+  )) as ReadonlyArray<{
+    horizon: string;
+    xmax: string;
+    gap_from: string | null;
+    gap_to: string | null;
+  }>;
+  const first = rows[0];
+  if (first === undefined)
+    throw new Error("selectEventIdHorizonWithMissingRanges: no row returned");
+  const gaps: PendingGapEntry[] = [];
+  for (const row of rows) {
+    if (row.gap_from === null || row.gap_to === null) continue;
+    gaps.push({ from: row.gap_from, to: row.gap_to, xmax: row.xmax });
+  }
+  return { horizon: BigInt(first.horizon), gaps };
+}
+
 // startFrom "now" seeds the FIRST-registration cursor at the current
 // MAX(events.id) instead of the column default 0 — mounting a consumer into
-// an existing app then skips the historical log instead of replaying it.
+// an existing app then skips the historical log instead of replaying it. The
+// horizon and pending_gaps are read from one snapshot (selectEventIdHorizon
+// WithMissingRanges): a transaction holding a lower id can still be
+// in-flight at boot, and without seeding those gaps its event would commit
+// after the cursor already sits above it, so `id > cursor` would never
+// deliver it (#3231). The cheap existence check skips the scan entirely for
+// the (overwhelmingly common) case of an already-registered consumer.
 // ON CONFLICT DO NOTHING keeps both branches safe for an existing row: the
 // subquery only ever affects the row this statement inserts.
 export async function insertConsumerIfAbsent(
@@ -18,11 +93,18 @@ export async function insertConsumerIfAbsent(
   startFrom: "beginning" | "now" = "beginning",
 ): Promise<void> {
   if (startFrom === "now") {
+    const existing = (await asRawClient(db).unsafe(
+      `SELECT 1 FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2`,
+      [name, instanceId],
+    )) as ReadonlyArray<unknown>;
+    // skip: already registered — an existing cursor is never re-seeded.
+    if (existing.length > 0) return;
+    const { horizon, gaps } = await selectEventIdHorizonWithMissingRanges(db);
     await asRawClient(db).unsafe(
-      `INSERT INTO "kumiko_event_consumers" ("name", "instance_id", "status", "last_processed_event_id")
-       VALUES ($1, $2, 'idle', COALESCE((SELECT MAX("id") FROM "kumiko_events"), 0))
+      `INSERT INTO "kumiko_event_consumers" ("name", "instance_id", "status", "last_processed_event_id", "pending_gaps")
+       VALUES ($1, $2, 'idle', $3, $4::text::jsonb)
        ON CONFLICT ("name", "instance_id") DO NOTHING`,
-      [name, instanceId],
+      [name, instanceId, horizon, JSON.stringify(gaps)],
     );
   } else {
     await asRawClient(db).unsafe(
@@ -59,6 +141,37 @@ export async function deleteOrphanedPerInstanceConsumerRows(
   );
 }
 
+// Lock-free pre-check for doPass: which (name, instance_id) pairs are
+// provably idle — no locking, no xid, no WAL. A pair only qualifies when its
+// row exists, its status isn't dead (dead must still go through
+// acquireConsumerState for auto-rearm), it has no pending_gaps, and no event
+// exists past its cursor. Paired via unnest so the two positional arrays
+// zip element-wise into rows instead of a cartesian product.
+//
+// `deadStatus` is passed in rather than imported from event-consumer-state.ts
+// (which defines ConsumerStatuses) — that module already imports from this
+// one, so importing back would be a require cycle (same pattern as
+// deleteOrphanedPerInstanceConsumerRows above).
+export async function selectProvablyIdleConsumerPairs(
+  db: AnyDb,
+  names: readonly string[],
+  instanceIds: readonly string[],
+  deadStatus: string,
+): Promise<ReadonlyArray<{ readonly name: string; readonly instanceId: string }>> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT c."name" AS name, c."instance_id" AS instance_id
+     FROM "kumiko_event_consumers" c
+     WHERE ("name", "instance_id") = ANY (SELECT * FROM unnest($1::text[], $2::text[]))
+       AND "status" != $3
+       AND "pending_gaps" = '[]'::jsonb
+       AND NOT EXISTS (
+         SELECT 1 FROM "kumiko_events" e WHERE e."id" > c."last_processed_event_id"
+       )`,
+    [names, instanceIds, deadStatus],
+  )) as ReadonlyArray<{ name: string; instance_id: string }>;
+  return rows.map((r) => ({ name: r.name, instanceId: r.instance_id }));
+}
+
 export async function selectConsumerForUpdateSkipLocked(
   db: AnyDb,
   name: string,
@@ -116,6 +229,7 @@ export type ConsumerDeliveryOutcome = {
   readonly lastError: string | null;
   readonly deadLettered: boolean;
   readonly processed: number;
+  readonly pendingGaps: readonly PendingGapEntry[];
 };
 
 export async function updateConsumerDeliveryOutcome(
@@ -136,14 +250,17 @@ export async function updateConsumerDeliveryOutcome(
        "status" = $3,
        "last_error" = $4,
        "rearm_count" = CASE WHEN $5 THEN 0 ELSE "rearm_count" END,
+       -- text param + cast: a JS string bound straight to ::jsonb double-encodes under Bun.SQL
+       "pending_gaps" = $6::text::jsonb,
        "updated_at" = now()
-     WHERE "name" = $6 AND "instance_id" = $7`,
+     WHERE "name" = $7 AND "instance_id" = $8`,
     [
       outcome.cursor,
       outcome.attempts,
       outcome.deadLettered ? "dead" : "idle",
       outcome.lastError,
       resetRearmCount,
+      JSON.stringify(outcome.pendingGaps),
       name,
       instanceId,
     ],
@@ -192,13 +309,14 @@ export async function resetConsumerForMspRebuild(
   instanceId: string,
 ): Promise<void> {
   await asRawClient(db).unsafe(
-    `INSERT INTO "kumiko_event_consumers" ("name", "instance_id", "last_processed_event_id", "status")
-     VALUES ($1, $2, 0, 'idle')
+    `INSERT INTO "kumiko_event_consumers" ("name", "instance_id", "last_processed_event_id", "status", "pending_gaps")
+     VALUES ($1, $2, 0, 'idle', '[]'::jsonb)
      ON CONFLICT ("name", "instance_id") DO UPDATE SET
        "last_processed_event_id" = 0,
        "status" = 'idle',
        "attempts" = 0,
        "last_error" = NULL,
+       "pending_gaps" = '[]'::jsonb,
        "updated_at" = now()`,
     [name, instanceId],
   );
@@ -220,6 +338,7 @@ export async function updateConsumerRebuildCursor(
   name: string,
   instanceId: string,
   lastProcessedEventId: bigint,
+  pendingGaps: readonly PendingGapEntry[],
 ): Promise<void> {
   await asRawClient(db).unsafe(
     `UPDATE "kumiko_event_consumers" SET
@@ -227,9 +346,11 @@ export async function updateConsumerRebuildCursor(
        "status" = 'idle',
        "attempts" = 0,
        "last_error" = NULL,
+       -- text param + cast: a JS string bound straight to ::jsonb double-encodes under Bun.SQL
+       "pending_gaps" = $2::text::jsonb,
        "updated_at" = now()
-     WHERE "name" = $2 AND "instance_id" = $3`,
-    [lastProcessedEventId, name, instanceId],
+     WHERE "name" = $3 AND "instance_id" = $4`,
+    [lastProcessedEventId, JSON.stringify(pendingGaps), name, instanceId],
   );
 }
 
@@ -269,3 +390,28 @@ export async function rearmDeadConsumer(
   )) as ReadonlyArray<Record<string, unknown>>;
   return rows[0];
 }
+
+// skipPoisonEvent's pending-gap branch: the poison is a pending id below the
+// cursor, so it's removed from pending_gaps directly instead of advancing
+// last_processed_event_id (advancing it here would be a regression — the
+// cursor already sits above this id).
+export async function removePendingGapReturning(
+  db: AnyDb,
+  name: string,
+  instanceId: string,
+  newPendingGaps: readonly PendingGapEntry[],
+): Promise<Record<string, unknown> | undefined> {
+  const rows = (await asRawClient(db).unsafe(
+    `UPDATE "kumiko_event_consumers" SET
+       "pending_gaps" = $1::text::jsonb,
+       "status" = 'idle',
+       "attempts" = 0,
+       "last_error" = NULL,
+       "rearm_count" = 0,
+       "updated_at" = now()
+     WHERE "name" = $2 AND "instance_id" = $3
+     RETURNING *`,
+    [JSON.stringify(newPendingGaps), name, instanceId],
+  )) as ReadonlyArray<Record<string, unknown>>;
+  return rows[0];
+}

package/src/db/queries/event-store.ts

@@ -7,6 +7,15 @@ import {
 import type { AnyDb } from "../query";
 import { asRawClient, unsafeReadRetrying } from "../query";
 
+// Gap-finality (event-dispatcher pending_gaps) needs every holder of an
+// event id to already have a *real* xact id by the time it inserts — Postgres
+// assigns those lazily on first write, so a bare INSERT alone doesn't
+// guarantee one exists yet for comparison against a later snapshot's
+// xmin/xmax. pg_current_xact_id() forces the allocation.
+export async function claimXactId(db: AnyDb): Promise<void> {
+  await asRawClient(db).unsafe(`SELECT pg_current_xact_id()`);
+}
+
 /** NOTIFY on commit — wakes LISTEN subscribers (event-dispatcher). */
 export async function notifyPgChannel(db: AnyDb, channel: string): Promise<void> {
   await asRawClient(db).unsafe(`SELECT pg_notify($1, '')`, [channel]);
@@ -283,3 +292,63 @@ export async function upsertArchivedStream(db: AnyDb, params: ArchiveStreamParam
     [params.tenantId, params.aggregateId, params.aggregateType, params.archivedBy, params.reason],
   );
 }
+
+export type PendingIdRange = { readonly from: bigint; readonly to: bigint };
+
+// Per-consumer turn fetch: the plain `id > cursor` window plus any ranges the
+// consumer is still watching as pending gaps (ids invisible on an earlier
+// turn that may have become visible since). Raw SQL — the typed builder's
+// WhereObject is an AND of fields, it can't express this OR.
+export async function selectPendingAndNewEventRows(
+  db: AnyDb,
+  cursor: bigint,
+  pendingRanges: readonly PendingIdRange[],
+  batchSize: number,
+): Promise<ReadonlyArray<Record<string, unknown>>> {
+  if (pendingRanges.length === 0) {
+    return unsafeReadRetrying(
+      db,
+      `SELECT * FROM "kumiko_events" WHERE "id" > $1 ORDER BY "id" ASC LIMIT $2`,
+      [cursor, batchSize],
+    );
+  }
+  return unsafeReadRetrying(
+    db,
+    // UNION ALL of two primary-key range scans: an `id > $1 OR EXISTS (…)`
+    // predicate can't use the index and would seq-scan kumiko_events per turn.
+    // Ranges sit below $1, so the branches never overlap.
+    `(SELECT e.* FROM unnest($2::bigint[], $3::bigint[]) AS g(f, t)
+       CROSS JOIN LATERAL (
+         SELECT * FROM "kumiko_events" WHERE "id" BETWEEN g.f AND g.t ORDER BY "id" ASC LIMIT $4
+       ) e)
+     UNION ALL
+     (SELECT * FROM "kumiko_events" WHERE "id" > $1 ORDER BY "id" ASC LIMIT $4)
+     ORDER BY "id" ASC LIMIT $4`,
+    [
+      cursor,
+      pendingRanges.map((r) => r.from.toString()),
+      pendingRanges.map((r) => r.to.toString()),
+      batchSize,
+    ],
+  );
+}
+
+// Smallest committed-and-visible id inside any pending range — lets
+// skipPoisonEvent (event-dispatcher-admin.ts) tell a live poison apart from
+// a still-invisible gap without pulling full rows.
+export async function selectSmallestVisibleIdInRanges(
+  db: AnyDb,
+  pendingRanges: readonly PendingIdRange[],
+): Promise<bigint | null> {
+  if (pendingRanges.length === 0) return null;
+  const rows = (await unsafeReadRetrying(
+    db,
+    `SELECT MIN("id")::text AS id FROM "kumiko_events"
+     WHERE EXISTS (
+       SELECT 1 FROM unnest($1::bigint[], $2::bigint[]) AS g(f, t) WHERE "id" BETWEEN g.f AND g.t
+     )`,
+    [pendingRanges.map((r) => r.from.toString()), pendingRanges.map((r) => r.to.toString())],
+  )) as ReadonlyArray<{ id: string | null }>;
+  const id = rows[0]?.id;
+  return id === null || id === undefined ? null : BigInt(id);
+}