@cosmicdrift/kumiko-framework 0.14.0 → 0.16.0

package/src/pipeline/dispatcher.ts

@@ -1,7 +1,8 @@
-import { type AnyColumn, eq } from "drizzle-orm";
 import { requestContext } from "../api/request-context";
 import type { DbConnection, DbRow, DbTx } from "../db/connection";
-import { buildDrizzleTable } from "../db/table-builder";
+import { selectRowForUpdateById } from "../db/queries/entity-read";
+import { selectMany, transaction } from "../db/query";
+import { buildEntityTable, toSnakeCase } from "../db/table-builder";
 import { createTenantDb } from "../db/tenant-db";
 import { hasAccess } from "../engine/access";
 import { checkWriteFieldRoles, filterReadFields } from "../engine/field-access";
@@ -173,15 +174,22 @@ export function createDispatcher(
 ): Dispatcher {
   const { idempotency, lifecycle, jobRunner, effectiveFeatures } = options;
 
+  // Narrowing-helper: AppContext.db ist DbConnection|TenantDb|undefined. Die
+  // dispatch-Pfade brauchen DbConnection (oder DbTx aus Caller-Scope) für
+  // appendEvent/projection-writes; TenantDb-Branch wird hier ausgeschlossen.
+  function resolveDbSource(tx: DbTx | undefined): DbConnection | DbTx | undefined {
+    return tx ?? (context.db as DbConnection | undefined); // @cast-boundary db-operator
+  }
+
   // Pre-build tables and transition maps for auto-guard (avoid per-request allocation)
-  const tableCache = new Map<string, ReturnType<typeof buildDrizzleTable>>();
+  const tableCache = new Map<string, ReturnType<typeof buildEntityTable>>();
   const transitionCache = new Map<string, ReturnType<typeof defineTransitions>>();
 
-  function getTable(entityName: string): ReturnType<typeof buildDrizzleTable> | undefined {
+  function getTable(entityName: string): ReturnType<typeof buildEntityTable> | undefined {
     if (tableCache.has(entityName)) return tableCache.get(entityName);
     const entity = registry.getEntity(entityName);
     if (!entity) return undefined;
-    const table = buildDrizzleTable(entityName, entity, {
+    const table = buildEntityTable(entityName, entity, {
       relations: registry.getRelations(entityName),
     });
     tableCache.set(entityName, table);
@@ -215,8 +223,7 @@ export function createDispatcher(
     tx: DbTx | undefined,
     callerFeature: string | undefined,
   ): Promise<void> {
-    const dbSource: DbConnection | DbTx | undefined =
-      tx ?? (context.db as DbConnection | undefined); // @cast-boundary db-operator
+    const dbSource = resolveDbSource(tx);
     if (!dbSource) {
       throw new InternalError({
         message: `ctx.appendEvent("${args.type}") requires a database connection — none is configured.`,
@@ -245,8 +252,7 @@ export function createDispatcher(
     // The outer dispatcher receives a DbConnection from the server/stack;
     // AppContext's `db` union also allows TenantDb (for downstream hook calls),
     // but at this point we're the root of the pipeline — cast is safe.
-    const dbSource: DbConnection | DbTx | undefined =
-      tx ?? (context.db as DbConnection | undefined); // @cast-boundary db-operator
+    const dbSource = resolveDbSource(tx);
     const reqCtx = requestContext.get();
     const db = dbSource
       ? createTenantDb(
@@ -313,8 +319,7 @@ export function createDispatcher(
         await appendDomainEvent(args, user, tx, registry.getHandlerFeature(type));
       },
       fetchForWriting: async (args: FetchForWritingArgs): Promise<AggregateStreamHandle> => {
-        const dbSource: DbConnection | DbTx | undefined =
-          tx ?? (context.db as DbConnection | undefined); // @cast-boundary db-operator
+        const dbSource = resolveDbSource(tx);
         if (!dbSource) {
           throw new InternalError({
             message: `ctx.fetchForWriting("${args.aggregateId}") requires a database connection — none is configured.`,
@@ -377,8 +382,7 @@ export function createDispatcher(
         aggregateId: string,
         loadOptions?: { readonly asOf?: Temporal.Instant },
       ): Promise<readonly StoredEvent[]> => {
-        const dbSource: DbConnection | DbTx | undefined =
-          tx ?? (context.db as DbConnection | undefined); // @cast-boundary db-operator
+        const dbSource = resolveDbSource(tx);
         if (!dbSource) {
           throw new InternalError({
             message: `ctx.loadAggregate("${aggregateId}") requires a database connection — none is configured.`,
@@ -396,8 +400,7 @@ export function createDispatcher(
         aggregateId: string,
         archiveArgs: { readonly aggregateType: string; readonly reason?: string },
       ): Promise<void> => {
-        const dbSource: DbConnection | DbTx | undefined =
-          tx ?? (context.db as DbConnection | undefined); // @cast-boundary db-operator
+        const dbSource = resolveDbSource(tx);
         if (!dbSource) {
           throw new InternalError({
             message: `ctx.archiveStream("${aggregateId}") requires a database connection — none is configured.`,
@@ -412,8 +415,7 @@ export function createDispatcher(
         });
       },
       restoreStream: async (aggregateId: string): Promise<void> => {
-        const dbSource: DbConnection | DbTx | undefined =
-          tx ?? (context.db as DbConnection | undefined); // @cast-boundary db-operator
+        const dbSource = resolveDbSource(tx);
         if (!dbSource) {
           throw new InternalError({
             message: `ctx.restoreStream("${aggregateId}") requires a database connection — none is configured.`,
@@ -422,8 +424,7 @@ export function createDispatcher(
         await restoreStreamHelper(dbSource, user.tenantId, aggregateId);
       },
       isStreamArchived: async (aggregateId: string): Promise<boolean> => {
-        const dbSource: DbConnection | DbTx | undefined =
-          tx ?? (context.db as DbConnection | undefined); // @cast-boundary db-operator
+        const dbSource = resolveDbSource(tx);
         if (!dbSource) {
           throw new InternalError({
             message: `ctx.isStreamArchived("${aggregateId}") requires a database connection — none is configured.`,
@@ -437,8 +438,7 @@ export function createDispatcher(
         readonly version: number;
         readonly state: Record<string, unknown>;
       }): Promise<void> => {
-        const dbSource: DbConnection | DbTx | undefined =
-          tx ?? (context.db as DbConnection | undefined); // @cast-boundary db-operator
+        const dbSource = resolveDbSource(tx);
         if (!dbSource) {
           throw new InternalError({
             message: `ctx.snapshotAggregate("${snapshotArgs.aggregateId}") requires a database connection — none is configured.`,
@@ -457,8 +457,7 @@ export function createDispatcher(
         reducer: SnapshotReducer<TState>,
         initial: TState,
       ): Promise<LoadAggregateWithSnapshotResult<TState>> => {
-        const dbSource: DbConnection | DbTx | undefined =
-          tx ?? (context.db as DbConnection | undefined); // @cast-boundary db-operator
+        const dbSource = resolveDbSource(tx);
         if (!dbSource) {
           throw new InternalError({
             message: `ctx.loadAggregateWithSnapshot("${aggregateId}") requires a database connection — none is configured.`,
@@ -502,8 +501,7 @@ export function createDispatcher(
               `table-less MSP (side-effect-only). Known queryable projections: ${all.join(", ") || "(none)"}`,
           });
         }
-        const dbSource: DbConnection | DbTx | undefined =
-          tx ?? (context.db as DbConnection | undefined); // @cast-boundary db-operator
+        const dbSource = resolveDbSource(tx);
         if (!dbSource) {
           throw new InternalError({
             message: `ctx.queryProjection("${qualifiedName}") requires a database connection — none is configured.`,
@@ -513,17 +511,10 @@ export function createDispatcher(
         // filter keeps cross-tenant leaks out unless the handler explicitly
         // opts in. Works with any drizzle-table whose tenant column is named
         // tenantId on the JS side.
-        // @cast-boundary dynamic-key — drizzle's PgTable columns are schema-dependent
-        const tenantCol = (projTable as Record<string, AnyColumn | undefined>)["tenantId"]; // @cast-boundary dynamic-key
-        let rows: readonly Record<string, unknown>[];
-        if (tenantCol && !queryOptions?.unsafeAllTenants) {
-          rows = (await dbSource
-            .select()
-            .from(projTable)
-            .where(eq(tenantCol, user.tenantId))) as readonly Record<string, unknown>[]; // @cast-boundary db-row
-        } else {
-          rows = (await dbSource.select().from(projTable)) as readonly Record<string, unknown>[]; // @cast-boundary db-row
-        }
+        const tenantCol = (projTable as Record<string, unknown>)["tenantId"];
+        const where =
+          tenantCol && !queryOptions?.unsafeAllTenants ? { tenantId: user.tenantId } : undefined;
+        const rows = await selectMany<Record<string, unknown>>(dbSource, projTable, where);
         return rows as readonly T[]; // @cast-boundary engine-payload
       },
       // Thin pass-through: one resolve impl lives on the dispatcher, the
@@ -1123,9 +1114,12 @@ export function createDispatcher(
           // can false-pass; optimistic locking would catch it later, but with
           // a less specific error. Falls back to a plain SELECT if no tx is
           // active (tests without a DB connection).
-          const selectQuery = handlerContext.db.select().from(table);
-          const filtered = selectQuery.where(eq(table["id"], id));
-          const rows = tx ? await filtered.for("update") : await filtered;
+          const tableName = String(
+            (table as { [key: symbol]: unknown })[Symbol.for("kumiko:schema:Name")],
+          );
+          const rows = tx
+            ? await selectRowForUpdateById(handlerContext.db, tableName, id)
+            : await selectMany(handlerContext.db, table, { id });
           const row = rows[0];
 
           if (!row) continue;
@@ -1133,10 +1127,13 @@ export function createDispatcher(
           // at all; a handler that wants to move a deleted row should use
           // unsafeSkipTransitionGuard or restore first.
           const rowAsRow = row as DbRow; // @cast-boundary engine-payload
-          if (entity.softDelete && rowAsRow["isDeleted"] === true) {
+          const isDeleted = rowAsRow["isDeleted"] ?? rowAsRow["is_deleted"];
+          if (entity.softDelete && isDeleted === true) {
             continue;
           }
-          const currentValue = (row as DbRow)[fieldName] as string; // @cast-boundary engine-bridge
+          const currentValue =
+            ((row as DbRow)[fieldName] as string | undefined) ??
+            ((row as DbRow)[toSnakeCase(fieldName)] as string); // @cast-boundary engine-bridge
           guardTransition(
             getTransitions({ entityName, fieldName, map: transitionMap }),
             currentValue,
@@ -1278,7 +1275,9 @@ export function createDispatcher(
       }
     };
 
-    const db = context.db as DbConnection | undefined; // @cast-boundary db-operator
+    // batch() opens its own outer transaction — needs the top-level
+    // connection's `.begin()` (TransactionSql exposes only `.savepoint()`).
+    const db = resolveDbSource(undefined) as DbConnection | undefined;
     if (!db) {
       // Without a DB connection there is no transaction to open. Fall back to
       // sequential execution — useful for unit tests that don't touch the DB.
@@ -1306,7 +1305,7 @@ export function createDispatcher(
     }
 
     try {
-      await db.transaction(async (tx) => {
+      await transaction(db, async (tx) => {
         for (let i = 0; i < commands.length; i++) {
           const cmd = commands[i];
           if (!cmd) continue;
@@ -1326,10 +1325,6 @@ export function createDispatcher(
           results,
         });
       }
-      // Unexpected throw — typically a DB driver error from commit/rollback.
-      // executeWrite already traps handler + lifecycle throws into WriteResult,
-      // so anything reaching here is infrastructure-level. Wrap as InternalError
-      // so the contract ("non-Kumiko → InternalError") holds uniformly.
       return finalize({
         isSuccess: false,
         error: toWriteErrorInfo(wrapToKumiko(e)),
@@ -1368,7 +1363,7 @@ export function createDispatcher(
   // scoped as "tenant" and no tx is threaded through. Hooks that need
   // cross-tenant lookups opt in explicitly via queryAs(systemUser, ...).
   function buildAuthClaimsContext(user: SessionUser): AuthClaimsContext {
-    const dbSource: DbConnection | undefined = context.db as DbConnection | undefined; // @cast-boundary db-operator
+    const dbSource = resolveDbSource(undefined);
     if (!dbSource) {
       throw new InternalError({
         message:

package/src/pipeline/event-consumer-state.ts

@@ -1,6 +1,15 @@
-import { sql } from "drizzle-orm";
+// sql now comes from native dialect
 import type { DbConnection } from "../db/connection";
-import { bigint, index, instant, integer, table as pgTable, primaryKey, text } from "../db/dialect";
+import {
+  bigint,
+  index,
+  instant,
+  integer,
+  table as pgTable,
+  primaryKey,
+  sql,
+  text,
+} from "../db/dialect";
 import { tableExists } from "../db/schema-inspection";
 import { unsafePushTables } from "../stack";
 

package/src/pipeline/event-dispatcher.ts

@@ -1,6 +1,15 @@
-import { and, asc, eq, gt, sql } from "drizzle-orm";
 import { requestContext } from "../api/request-context";
 import type { DbConnection, DbTx, PgClient } from "../db/connection";
+import {
+  advanceConsumerPastEventReturning,
+  insertConsumerIfAbsent,
+  markConsumerProcessing,
+  selectConsumerForUpdateSkipLocked,
+  updateConsumerDeliveryOutcome,
+  updateConsumerStatusReturning,
+} from "../db/queries/event-consumer";
+import { selectEventsHeadId, selectNextEventIdAfter } from "../db/queries/event-store";
+import { coerceRow, extractTableInfo, selectMany } from "../db/query";
 import type { AppContext } from "../engine/types";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
 import {
@@ -154,7 +163,30 @@ const DEFAULT_MAX_ATTEMPTS = 10;
 // dispatcher's main pass logic stays under ~50 LOC. Every helper takes an
 // explicit `tx` — none of them use the outer dispatcher's closure state.
 
-type ConsumerStateRow = typeof eventConsumerStateTable.$inferSelect;
+type ConsumerStateRowShape = {
+  readonly name: string;
+  readonly instanceId: string;
+  readonly lastProcessedEventId: bigint;
+  readonly status: string;
+  readonly attempts: number;
+  readonly lastError: string | null;
+  readonly updatedAt: Temporal.Instant;
+};
+type ConsumerStateRow = ConsumerStateRowShape;
+
+type StoredEventRow = {
+  readonly id: bigint;
+  readonly aggregateId: string;
+  readonly aggregateType: string;
+  readonly tenantId: string;
+  readonly version: number;
+  readonly type: string;
+  readonly eventVersion: number;
+  readonly payload: Record<string, unknown>;
+  readonly metadata: import("../event-store/event-store").EventMetadata;
+  readonly createdAt: Temporal.Instant;
+  readonly createdBy: string;
+};
 
 type AcquireOutcome =
   | { readonly state: ConsumerStateRow; readonly skip: null }
@@ -180,16 +212,13 @@ async function acquireConsumerState(
   name: string,
   instanceId: string,
 ): Promise<AcquireOutcome> {
-  const [state] = (await tx
-    .select()
-    .from(eventConsumerStateTable)
-    .where(
-      and(
-        eq(eventConsumerStateTable.name, name),
-        eq(eventConsumerStateTable.instanceId, instanceId),
-      ),
-    )
-    .for("update", { skipLocked: true })) as [ConsumerStateRow | undefined]; // @cast-boundary db-row
+  const rawState = await selectConsumerForUpdateSkipLocked(tx, name, instanceId);
+
+  if (!rawState) {
+    return { state: null, skip: "not_registered" };
+  }
+
+  const state = coerceRow(rawState, extractTableInfo(eventConsumerStateTable)) as ConsumerStateRow;
 
   if (!state) {
     // Either the row never existed (no pre-reg, no ensureRegistered) or
@@ -218,12 +247,7 @@ async function preRegisterConsumers(
 ): Promise<void> {
   for (const consumer of consumers) {
     const instanceId = consumerInstanceId(consumer, dispatcherInstanceId);
-    await db
-      .insert(eventConsumerStateTable)
-      .values({ name: consumer.name, instanceId, status: "idle" })
-      .onConflictDoNothing({
-        target: [eventConsumerStateTable.name, eventConsumerStateTable.instanceId],
-      });
+    await insertConsumerIfAbsent(db, consumer.name, instanceId);
   }
 }
 
@@ -249,28 +273,20 @@ function consumerInstanceId(
 // lock already guarantees single-writer semantics; this is purely
 // informational (and resets on commit to idle/dead via persistConsumerOutcome).
 async function markProcessing(tx: DbTx, name: string, instanceId: string): Promise<void> {
-  await tx
-    .update(eventConsumerStateTable)
-    .set({ status: "processing", updatedAt: sql`now()` })
-    .where(
-      and(
-        eq(eventConsumerStateTable.name, name),
-        eq(eventConsumerStateTable.instanceId, instanceId),
-      ),
-    );
+  await markConsumerProcessing(tx, name, instanceId);
 }
 
 async function fetchPendingEvents(
   tx: DbTx,
   cursor: bigint,
   batchSize: number,
-): Promise<ReadonlyArray<typeof eventsTable.$inferSelect>> {
-  return (await tx
-    .select()
-    .from(eventsTable)
-    .where(gt(eventsTable.id, cursor))
-    .orderBy(asc(eventsTable.id))
-    .limit(batchSize)) as ReadonlyArray<typeof eventsTable.$inferSelect>; // @cast-boundary db-row
+): Promise<ReadonlyArray<StoredEventRow>> {
+  return (await selectMany(
+    tx,
+    eventsTable,
+    { id: { gt: cursor } },
+    { orderBy: { col: "id", direction: "asc" }, limit: batchSize },
+  )) as ReadonlyArray<StoredEventRow>; // @cast-boundary db-row
 }
 
 type DeliveryOutcome = {
@@ -282,7 +298,7 @@ type DeliveryOutcome = {
   readonly failed: number;
 };
 
-function rowToStoredEvent(row: typeof eventsTable.$inferSelect): StoredEvent {
+function rowToStoredEvent(row: StoredEventRow): StoredEvent {
   return {
     id: String(row.id),
     aggregateId: row.aggregateId,
@@ -305,7 +321,7 @@ function rowToStoredEvent(row: typeof eventsTable.$inferSelect): StoredEvent {
 // restartConsumer / skipPoisonEvent).
 async function deliverEvents(
   consumer: EventConsumer,
-  events: ReadonlyArray<typeof eventsTable.$inferSelect>,
+  events: ReadonlyArray<StoredEventRow>,
   context: AppContext,
   maxAttempts: number,
   state: ConsumerStateRow,
@@ -376,21 +392,7 @@ async function persistConsumerOutcome(
   instanceId: string,
   outcome: DeliveryOutcome,
 ): Promise<void> {
-  await tx
-    .update(eventConsumerStateTable)
-    .set({
-      lastProcessedEventId: outcome.cursor,
-      attempts: outcome.attempts,
-      status: outcome.deadLettered ? "dead" : "idle",
-      lastError: outcome.lastError,
-      updatedAt: sql`now()`,
-    })
-    .where(
-      and(
-        eq(eventConsumerStateTable.name, name),
-        eq(eventConsumerStateTable.instanceId, instanceId),
-      ),
-    );
+  await updateConsumerDeliveryOutcome(tx, name, instanceId, outcome);
 }
 
 // Emit the lag gauge inside the consumer pass's tx so ops sees a snapshot
@@ -403,13 +405,7 @@ async function emitLagFromTx(
   cursor: bigint,
   meter: Meter,
 ): Promise<void> {
-  const result = await tx.execute(
-    sql`SELECT COALESCE(MAX(id), 0)::bigint AS head FROM kumiko_events`,
-  );
-  // @cast-boundary db-row — raw drizzle.execute() COALESCE-aggregate row
-  const rows = Array.isArray(result) ? (result as Array<{ head?: bigint | string | null }>) : []; // @cast-boundary db-row
-  const raw = rows[0]?.head;
-  const head = typeof raw === "bigint" ? raw : BigInt(raw ?? 0);
+  const head = await selectEventsHeadId(tx);
   const lag = head > cursor ? Number(head - cursor) : 0;
   emitEventConsumerLag(meter, { consumer: consumerName, instanceId }, lag);
 }
@@ -535,7 +531,7 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
     });
 
     try {
-      await db.transaction(async (tx) => {
+      await db.begin(async (tx: DbTx) => {
         const acquired = await acquireConsumerState(tx, consumer.name, instanceId);
         // skip: another instance holds the lock, or the consumer is
         // disabled/dead. Nothing to deliver this pass.
@@ -701,9 +697,7 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
 //                     lastError=null, status="idle". For events that will
 //                     never succeed (broken payload, removed feature code).
 
-function normalizeConsumerState(
-  row: typeof eventConsumerStateTable.$inferSelect,
-): ConsumerRecoveryState {
+function normalizeConsumerState(row: ConsumerStateRowShape): ConsumerRecoveryState {
   return {
     name: row.name,
     instanceId: row.instanceId,
@@ -735,16 +729,11 @@ async function requireConsumerRow(
   db: DbConnection,
   name: string,
   instanceId: string,
-): Promise<typeof eventConsumerStateTable.$inferSelect> {
-  const [row] = await db
-    .select()
-    .from(eventConsumerStateTable)
-    .where(
-      and(
-        eq(eventConsumerStateTable.name, name),
-        eq(eventConsumerStateTable.instanceId, instanceId),
-      ),
-    );
+): Promise<ConsumerStateRowShape> {
+  const [row] = await selectMany<ConsumerStateRow>(db, eventConsumerStateTable, {
+    name,
+    instanceId,
+  });
   if (!row) {
     throw new Error(
       `Consumer "${name}" (instance_id="${instanceId}") has no state row — it hasn't run yet, the name is misspelled, or the instance is misspelled. ` +
@@ -765,16 +754,9 @@ export async function restartConsumer(
       `Consumer "${name}" (instance_id="${instanceId}") is not dead (status="${before.status}"). Restart only applies to dead consumers; use "enable" for a disabled one.`,
     );
   }
-  const [updated] = await db
-    .update(eventConsumerStateTable)
-    .set({ status: "idle", attempts: 0, lastError: null, updatedAt: sql`now()` })
-    .where(
-      and(
-        eq(eventConsumerStateTable.name, name),
-        eq(eventConsumerStateTable.instanceId, instanceId),
-      ),
-    )
-    .returning();
+  const raw = await updateConsumerStatusReturning(db, name, instanceId, "idle");
+  const updated =
+    raw && (coerceRow(raw, extractTableInfo(eventConsumerStateTable)) as ConsumerStateRow);
   if (!updated) {
     throw new Error(
       `Consumer "${name}" (instance_id="${instanceId}") vanished between read and write — retry.`,
@@ -789,16 +771,9 @@ export async function disableConsumer(
   instanceId: string = SHARED_INSTANCE_SENTINEL,
 ): Promise<ConsumerRecoveryState> {
   await requireConsumerRow(db, name, instanceId);
-  const [updated] = await db
-    .update(eventConsumerStateTable)
-    .set({ status: "disabled", updatedAt: sql`now()` })
-    .where(
-      and(
-        eq(eventConsumerStateTable.name, name),
-        eq(eventConsumerStateTable.instanceId, instanceId),
-      ),
-    )
-    .returning();
+  const raw = await updateConsumerStatusReturning(db, name, instanceId, "disabled");
+  const updated =
+    raw && (coerceRow(raw, extractTableInfo(eventConsumerStateTable)) as ConsumerStateRow);
   if (!updated) {
     throw new Error(
       `Consumer "${name}" (instance_id="${instanceId}") vanished between read and write — retry.`,
@@ -818,16 +793,9 @@ export async function enableConsumer(
       `Consumer "${name}" (instance_id="${instanceId}") is not disabled (status="${before.status}"). Enable only flips disabled → idle; use "restart" for a dead consumer.`,
     );
   }
-  const [updated] = await db
-    .update(eventConsumerStateTable)
-    .set({ status: "idle", attempts: 0, lastError: null, updatedAt: sql`now()` })
-    .where(
-      and(
-        eq(eventConsumerStateTable.name, name),
-        eq(eventConsumerStateTable.instanceId, instanceId),
-      ),
-    )
-    .returning();
+  const raw = await updateConsumerStatusReturning(db, name, instanceId, "idle");
+  const updated =
+    raw && (coerceRow(raw, extractTableInfo(eventConsumerStateTable)) as ConsumerStateRow);
   if (!updated) {
     throw new Error(
       `Consumer "${name}" (instance_id="${instanceId}") vanished between read and write — retry.`,
@@ -846,48 +814,25 @@ export async function skipPoisonEvent(
   instanceId: string = SHARED_INSTANCE_SENTINEL,
 ): Promise<ConsumerRecoveryState & { readonly skippedEventId: bigint | null }> {
   const before = await requireConsumerRow(db, name, instanceId);
-  return db.transaction(async (tx) => {
-    const [poison] = (await tx
-      .select({ id: eventsTable.id })
-      .from(eventsTable)
-      .where(gt(eventsTable.id, before.lastProcessedEventId))
-      .orderBy(asc(eventsTable.id))
-      .limit(1)) as ReadonlyArray<{ id: bigint }>; // @cast-boundary db-row
-    if (!poison) {
-      const [unchanged] = await tx
-        .select()
-        .from(eventConsumerStateTable)
-        .where(
-          and(
-            eq(eventConsumerStateTable.name, name),
-            eq(eventConsumerStateTable.instanceId, instanceId),
-          ),
-        );
+  return db.begin(async (tx: DbTx) => {
+    const poisonId = await selectNextEventIdAfter(tx, before.lastProcessedEventId);
+    if (poisonId === null) {
+      const [unchanged] = await selectMany<ConsumerStateRow>(tx, eventConsumerStateTable, {
+        name,
+        instanceId,
+      });
       if (!unchanged)
         throw new Error(`Consumer "${name}" (instance_id="${instanceId}") vanished — retry.`);
       return { ...normalizeConsumerState(unchanged), skippedEventId: null };
     }
-    const [updated] = await tx
-      .update(eventConsumerStateTable)
-      .set({
-        lastProcessedEventId: poison.id,
-        status: "idle",
-        attempts: 0,
-        lastError: null,
-        updatedAt: sql`now()`,
-      })
-      .where(
-        and(
-          eq(eventConsumerStateTable.name, name),
-          eq(eventConsumerStateTable.instanceId, instanceId),
-        ),
-      )
-      .returning();
+    const raw = await advanceConsumerPastEventReturning(tx, name, instanceId, poisonId);
+    const updated =
+      raw && (coerceRow(raw, extractTableInfo(eventConsumerStateTable)) as ConsumerStateRow);
     if (!updated)
       throw new Error(
         `Consumer "${name}" (instance_id="${instanceId}") vanished mid-skip — retry.`,
       );
-    return { ...normalizeConsumerState(updated), skippedEventId: poison.id };
+    return { ...normalizeConsumerState(updated), skippedEventId: poisonId };
   });
 }
 
@@ -905,15 +850,10 @@ export async function getConsumerState(
   readonly lastError: string | null;
   readonly updatedAt: Temporal.Instant;
 } | null> {
-  const [row] = await db
-    .select()
-    .from(eventConsumerStateTable)
-    .where(
-      and(
-        eq(eventConsumerStateTable.name, name),
-        eq(eventConsumerStateTable.instanceId, instanceId),
-      ),
-    );
+  const [row] = await selectMany<ConsumerStateRow>(db, eventConsumerStateTable, {
+    name,
+    instanceId,
+  });
   if (!row) return null;
   return {
     name: row.name,
@@ -947,7 +887,7 @@ export async function listConsumersWithState(
     readonly lastError: string | null;
   }>
 > {
-  const stateRows = await db.select().from(eventConsumerStateTable);
+  const stateRows = await selectMany<ConsumerStateRow>(db, eventConsumerStateTable);
   const registered = new Set(registeredNames);
 
   // Materialize one output row per (name, instance_id). Registered names