@cosmicdrift/kumiko-framework 0.305.0 → 0.307.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,21 @@ 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,
 } from "./event-dispatcher-delivery";
+import { partitionBurntGaps, splitRangeExcludingIds, toIdRanges } from "./pending-gap-ranges";
 
 // Async event-dispatcher — the "AsyncDaemon"-pendant for Kumiko.
 //
@@ -37,7 +41,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
@@ -255,32 +261,96 @@ 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,
+  ): Promise<{ processed: number; failed: number }> {
+    const key = `${consumer.name}:${consumerInstanceId(consumer, options.instanceId)}`;
+    const existing = inFlightTurns.get(key);
+    if (existing) return existing;
+
+    // Feature-gate and backoff-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 };
+    }
+
+    // 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> {
     if (!preRegistered) {
       throw new Error(
         "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 +371,17 @@ 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;
-      }
-      const perConsumer = await processConsumer(consumer);
-      byConsumer[consumer.name] = perConsumer;
+    // Every consumer runs its own turn concurrently (own TX, own cursor,
+    // own backoff/feature-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);
+        return [consumer.name, perConsumer] as const;
+      }),
+    );
+    for (const [name, perConsumer] of results) {
+      byConsumer[name] = perConsumer;
       totalProcessed += perConsumer.processed;
       totalFailed += perConsumer.failed;
     }
@@ -376,20 +433,80 @@ 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 — no
+        // markProcessing/persistConsumerOutcome write, so an idle consumer
+        // doesn't burn a WAL record on every poll tick.
+        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 +661,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 +672,7 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
       preRegistered = true;
     },
 
-    drain: drainPassInFlight,
+    drain: drainInFlightTurns,
 
     runOnce,
   };

package/src/pipeline/idempotency.ts

@@ -19,6 +19,7 @@ export type IdempotencyGuard = {
     token: string,
     result: unknown,
   ): Promise<void>;
+  release(tenantId: string, userId: string, requestId: string, token: string): Promise<void>;
 };
 
 // Sentinel prefix stored under the key while the handler is running. Each
@@ -64,6 +65,16 @@ export function createIdempotencyGuard(
     end
   `;
 
+  // Same CAS guard as storeScript: only clear the lock if we still own it.
+  // A stale token (lock already reclaimed by a new owner) is a no-op.
+  const releaseScript = `
+    if redis.call("get", KEYS[1]) == ARGV[1] then
+      return redis.call("del", KEYS[1])
+    else
+      return 0
+    end
+  `;
+
   async function tryAcquire(key: string): Promise<string | null> {
     const token = `${PENDING_PREFIX}${generateId()}`;
     const acquired = await redis.set(key, token, "EX", pendingTtl, "NX");
@@ -138,5 +149,10 @@ export function createIdempotencyGuard(
       // SET and could stomp that fresher result with our stale one.
       void written;
     },
+
+    async release(tenantId, userId, requestId, token) {
+      const key = `${prefix}${tenantId}:${userId}:${requestId}`;
+      await redis.eval(releaseScript, 1, key, token);
+    },
   };
 }

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

@@ -0,0 +1,72 @@
+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;
+}

package/src/pipeline/system-hooks.ts

@@ -490,6 +490,13 @@ function readUserIdFromPreviousSnapshot(payload: Record<string, unknown>): strin
   return typeof userId === "string" && userId.length > 0 ? userId : undefined;
 }
 
+// A "revoke all others" write must not cut the caller's own live stream, so
+// session-revoked carries the spared sid. Missing or malformed → userwide.
+function readSessionRevokedKeptSessionId(payload: Record<string, unknown>): string | undefined {
+  const keptSessionId = payload["keptSessionId"];
+  return typeof keptSessionId === "string" && keptSessionId.length > 0 ? keptSessionId : undefined;
+}
+
 export function createAccessInvalidationEventConsumer(sseBroker: SseBroker): EventConsumer {
   return {
     name: ACCESS_INVALIDATION_CONSUMER_NAME,
@@ -511,7 +518,7 @@ export function createAccessInvalidationEventConsumer(sseBroker: SseBroker): Eve
         // poison would otherwise permanently stop access-invalidation for
         // every user behind one bad row).
         if (typeof userId !== "string" || userId.length === 0) return;
-        sseBroker.publishAccessInvalidation(userId);
+        sseBroker.publishAccessInvalidation(userId, readSessionRevokedKeptSessionId(event.payload));
       }
 
       if (

package/src/pipeline/system-identity-switch.ts

@@ -1,4 +1,9 @@
-import { type TenantDb, withUnsafeRawGrant } from "../db/tenant-db";
+import {
+  type TenantDb,
+  type UncheckedSystemDb,
+  withSystemDbUnsafeRawGrant,
+  withUnsafeRawGrant,
+} from "../db/tenant-db";
 import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user";
 import type {
   ActiveMembershipResult,
@@ -214,7 +219,10 @@ function readIdentitySwitchFn<
 }
 
 // context's own keys only — never touch a property of the resolved value, which may be a Proxy that throws on any get.
-function readDbLikeValue(context: object, key: "db" | "dbOutsideTransaction"): object | undefined {
+function readDbLikeValue(
+  context: object,
+  key: "db" | "dbOutsideTransaction" | "systemDb",
+): object | undefined {
   if (!(key in context)) return undefined;
   const value = (context as Record<string, unknown>)[key];
   return typeof value === "object" && value !== null ? value : undefined;
@@ -340,6 +348,7 @@ export function withHookEscapeHatchGrant<TContext extends object>(
   const ctxQueryProjection = readIdentitySwitchFn<ProjectionReader>(context, "queryProjection");
   const ctxDb = readDbLikeValue(context, "db");
   const ctxDbOutsideTransaction = readDbLikeValue(context, "dbOutsideTransaction");
+  const ctxSystemDb = readDbLikeValue(context, "systemDb");
   if (
     !ctxQueryAs &&
     !ctxWriteAs &&
@@ -347,7 +356,8 @@ export function withHookEscapeHatchGrant<TContext extends object>(
     !ctxQueryAsMember &&
     !ctxQueryProjection &&
     !ctxDb &&
-    !ctxDbOutsideTransaction
+    !ctxDbOutsideTransaction &&
+    !ctxSystemDb
   ) {
     return context;
   }
@@ -366,10 +376,18 @@ export function withHookEscapeHatchGrant<TContext extends object>(
     ...(ctxDbOutsideTransaction && {
       dbOutsideTransaction: withUnsafeRawGrant(ctxDbOutsideTransaction as TenantDb, escapeHatch),
     }),
+    // @cast-boundary engine-bridge — withSystemDbUnsafeRawGrant passes non-UncheckedSystemDb values through unchanged.
+    ...(ctxSystemDb && {
+      systemDb: withSystemDbUnsafeRawGrant(
+        ctxSystemDb as UncheckedSystemDb,
+        escapeHatch,
+        callerLabel,
+      ),
+    }),
   };
 }
 
-// Re-gates a hook's own ctx.queryAs/ctx.writeAs/ctx.queryProjection/ctx.db/ctx.dbOutsideTransaction instead of inheriting the handler's grant.
+// Re-gates a hook's own ctx.queryAs/ctx.writeAs/ctx.queryProjection/ctx.db/ctx.dbOutsideTransaction/ctx.systemDb instead of inheriting the handler's grant.
 export function bindHookEscapeHatchGrant(
   fn: LifecycleHookFn,
   label: string,

package/src/pipeline/write-origin.ts

@@ -1,6 +1,8 @@
 // The static check in boot-validator/access-declarations.ts only sees a handler's own
 // input schema; writes reached via ctx.write/writeAs/queryAs, hooks or foreign-feature
 // tables are only visible at the actual write, so the gate runs there at runtime.
+import { isPersonalDataGated, type WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
+import { z } from "zod";
 import { buildEntityTable } from "../db/table-builder";
 import { type PersonalDataGate, tableNameOf } from "../db/tenant-db";
 import {
@@ -15,12 +17,29 @@ import { AccessDeniedError } from "../errors";
 import { FrameworkReasons } from "../errors/reasons";
 import { toSnakeCase } from "../utils/case";
 
-export type WriteOrigin = {
-  readonly rootHandler: string;
-  readonly anonymousRoot: boolean;
-  // Only a write-handler root can declare public-intake; a query/stream root never does.
-  readonly publicIntake: boolean;
-};
+export { isPersonalDataGated, type WriteOrigin };
+
+// Only narrows: an inherited origin can add a gate, never lift the root's.
+export function effectiveWriteOrigin(root: WriteOrigin, inherited?: WriteOrigin): WriteOrigin {
+  if (!inherited) return root;
+  if (isPersonalDataGated(root)) return root;
+  if (isPersonalDataGated(inherited)) return inherited;
+  return root;
+}
+
+const writeOriginSchema = z
+  .object({
+    rootHandler: z.string(),
+    anonymousRoot: z.boolean(),
+    publicIntake: z.boolean(),
+    viaJob: z.string().optional(),
+  })
+  .strict();
+
+export function parseWriteOrigin(value: unknown): WriteOrigin | undefined {
+  const parsed = writeOriginSchema.safeParse(value);
+  return parsed.success ? parsed.data : undefined;
+}
 
 function declaresPublicIntake(access: AccessRule): boolean {
   return accessAllowsAnonymous(access) && declaredPersonalData(access) === "public-intake";
@@ -67,7 +86,7 @@ function personalDataTableMap(registry: Registry): ReadonlyMap<string, ReadonlyS
 }
 
 // Names fields only, never values: the error reaches the anonymous HTTP caller.
-function publicIntakeRequiredError(
+export function publicIntakeRequiredError(
   origin: WriteOrigin,
   target: string,
   fields: readonly string[],
@@ -75,14 +94,16 @@ function publicIntakeRequiredError(
   return new AccessDeniedError({
     message:
       `Anonymous root handler "${origin.rootHandler}" wrote personal-data field(s) ` +
-      `${fields.map((f) => `"${f}"`).join(", ")} on "${target}". Declare ` +
-      'access: { roles: [..., "anonymous"], personalData: "public-intake" } on ' +
+      `${fields.map((f) => `"${f}"`).join(", ")} on "${target}"` +
+      (origin.viaJob ? ` via job "${origin.viaJob}"` : "") +
+      '. Declare access: { roles: [..., "anonymous"], personalData: "public-intake" } on ' +
       `"${origin.rootHandler}" to allow anonymous callers to write personal data.`,
     details: {
       reason: FrameworkReasons.publicIntakeRequired,
       rootHandler: origin.rootHandler,
       target,
       fields,
+      ...(origin.viaJob !== undefined && { job: origin.viaJob }),
     },
   });
 }
@@ -93,7 +114,7 @@ export function buildPersonalDataGate(
   registry: Registry,
   origin: WriteOrigin,
 ): PersonalDataGate | undefined {
-  if (!origin.anonymousRoot || origin.publicIntake) return undefined;
+  if (!isPersonalDataGated(origin)) return undefined;
   const map = personalDataTableMap(registry);
   return (tableName, keys, entity) => {
     const personalFields = entity ? personalColumnNames(entity) : map.get(tableName);

package/src/stack/test-stack.ts

@@ -470,7 +470,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
 
     // Pre-register consumer state rows so tests can call runOnce() directly
     // without a preceding explicit start(). Timer fires at pollIntervalMs=50
-    // but passInFlight serialises concurrent passes — tests that drain via
+    // but each consumer runs at most one turn at a time — tests that drain via
     // runOnce() remain deterministic. Tests that specifically exercise the
     // timer loop call start() again (idempotent) after setup.
     if (eventDispatcher) await eventDispatcher.ensureRegistered();

package/src/testing/closed-connection-error.ts

@@ -0,0 +1,62 @@
+// Captures a real closed-connection error instead of a hand-built fake —
+// the production matcher checks driver-specific codes a fake can't reproduce.
+
+import postgres from "postgres";
+import { isClosedConnectionError } from "../bun-db/query";
+
+export function testDatabaseUrl(): string {
+  return (
+    process.env["TEST_DATABASE_URL"] ??
+    process.env["DATABASE_URL"] ??
+    "postgresql://kumiko:kumiko@localhost:15432/kumiko_test"
+  );
+}
+
+const MAX_WARMUP_ROUNDS = 10;
+const READS_PER_ROUND = 5;
+
+type AdminClient = { unsafe(sql: string, params?: readonly unknown[]): Promise<unknown> };
+
+// A per-round admin client hits a postgres-js reconnect timing bug (the first
+// retry after terminate hangs); a single long-lived admin client avoids it.
+export async function terminateBackendsByApplicationName(
+  admin: AdminClient,
+  applicationName: string,
+): Promise<void> {
+  await admin.unsafe(
+    "select pg_terminate_backend(pid) from pg_stat_activity where application_name = $1",
+    [applicationName],
+  );
+}
+
+// Terminates a throwaway pool's backends and races reads right after — the
+// dead-connection window is only a few ms wide, so this retries rounds until one lands.
+export async function captureClosedConnectionError(
+  url: string = testDatabaseUrl(),
+): Promise<unknown> {
+  const admin = postgres(url, { max: 1 });
+  try {
+    for (let round = 0; round < MAX_WARMUP_ROUNDS; round++) {
+      const applicationName = `kumiko-closed-conn-test-${crypto.randomUUID()}`;
+      const pool = postgres(url, { max: 1, connection: { application_name: applicationName } });
+      try {
+        await pool.unsafe("select 1");
+        await terminateBackendsByApplicationName(admin, applicationName);
+        for (let read = 0; read < READS_PER_ROUND; read++) {
+          try {
+            await pool.unsafe("select 1");
+          } catch (err) {
+            if (isClosedConnectionError(err)) return err;
+          }
+        }
+      } finally {
+        await pool.end({ timeout: 0 });
+      }
+    }
+    throw new Error(
+      `captureClosedConnectionError: no closed-connection error observed after ${MAX_WARMUP_ROUNDS} rounds.`,
+    );
+  } finally {
+    await admin.end({ timeout: 0 });
+  }
+}

package/src/testing/index.ts

@@ -15,6 +15,7 @@ export { resetEntityFieldEncryptionCacheForTests } from "../db/entity-field-encr
 export { rolesOf } from "./access-assertions";
 export { expectError, expectSuccess } from "./assertions";
 export { withBootValidatorFixture } from "./boot-validator-fixture";
+export { captureClosedConnectionError } from "./closed-connection-error";
 export { type ClearableTable, clearTables, resetTestTables } from "./db-cleanup";
 export {
   type E2EGeneratorOptions,