@cosmicdrift/kumiko-framework 0.306.0 → 0.307.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.306.0",
+  "version": "0.307.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.306.0",
-    "@cosmicdrift/kumiko-types": "0.306.0",
+    "@cosmicdrift/kumiko-http": "0.307.0",
+    "@cosmicdrift/kumiko-types": "0.307.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.306.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.307.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/redis-sse-broker.integration.test.ts

@@ -127,6 +127,72 @@ describe("createRedisSseBroker", () => {
     expect(invalidatedA).toBe(false);
   });
 
+  test("publishAccessInvalidation with a keptSessionId spares only the listener whose own sid matches exactly", async () => {
+    const podA = trackedBroker();
+    const podB = trackedBroker();
+    const userId = `user-${generateId()}`;
+    const sidKept = `sid-kept-${generateId()}`;
+    const sidAlreadyRevoked = `sid-already-revoked-${generateId()}`;
+    let invalidatedKept = false;
+    let invalidatedSidless = false;
+    let invalidatedAlreadyRevoked = false;
+
+    podA.subscribeAccessInvalidation(
+      userId,
+      () => {
+        invalidatedKept = true;
+      },
+      sidKept,
+    );
+    // No ownSid — mirrors a PAT/bearer stream, always invalidated (fail-closed).
+    podA.subscribeAccessInvalidation(userId, () => {
+      invalidatedSidless = true;
+    });
+    // Not the kept sid — mirrors a session already revoked through an
+    // eventless path (plain logout): the keep-list must still close it.
+    podA.subscribeAccessInvalidation(
+      userId,
+      () => {
+        invalidatedAlreadyRevoked = true;
+      },
+      sidAlreadyRevoked,
+    );
+
+    await waitFor(() => {
+      podB.publishAccessInvalidation(userId, sidKept);
+      return invalidatedSidless && invalidatedAlreadyRevoked;
+    });
+    // Asserted only after the control listeners above already fired for the
+    // same publish — proves the pipe delivered the message at all, so a
+    // false here means the sid really was spared, not that delivery is slow.
+    expect(invalidatedKept).toBe(false);
+  });
+
+  test("a legacy unscoped invalidation message (bare `1`, pre-scoping pod) still invalidates every listener, sid or not", async () => {
+    const podA = trackedBroker();
+    const publisherRaw = new (await import("ioredis")).default(testRedis.redisUrl);
+    const userId = `user-${generateId()}`;
+    let invalidatedWithSid = false;
+
+    podA.subscribeAccessInvalidation(
+      userId,
+      () => {
+        invalidatedWithSid = true;
+      },
+      `sid-${generateId()}`,
+    );
+
+    try {
+      await waitFor(async () => {
+        await publisherRaw.publish(`kumiko:sse:inval:${userId}`, JSON.stringify(1));
+        return invalidatedWithSid;
+      });
+      expect(invalidatedWithSid).toBe(true);
+    } finally {
+      publisherRaw.disconnect();
+    }
+  });
+
   test("a malformed message on the channel namespace is dropped, not thrown, and does not kill delivery", async () => {
     const podA = trackedBroker();
     const publisherRaw = new (await import("ioredis")).default(testRedis.redisUrl);

package/src/api/__tests__/sse-broker.test.ts

@@ -121,4 +121,53 @@ describe("SSE broker", () => {
     const { publish } = requireAccessInvalidation(createSseBroker());
     expect(() => publish("nobody-listening")).not.toThrow();
   });
+
+  test("publishAccessInvalidation with a keptSessionId spares only the listener whose own sid matches exactly", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const spared = mock();
+    const unrelated = mock();
+
+    subscribe("user-a", spared, "sid-kept");
+    subscribe("user-a", unrelated, "sid-other");
+    publish("user-a", "sid-kept");
+
+    expect(spared).not.toHaveBeenCalled();
+    expect(unrelated).toHaveBeenCalledTimes(1);
+  });
+
+  test("publishAccessInvalidation with a keptSessionId still closes a listener whose sid was already revoked through an eventless path (keep-list, not a kill-list)", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const alreadyRevoked = mock();
+
+    // Simulates a stream from a session logged out earlier via a path that
+    // never appended session-revoked — the keep-list must not accidentally
+    // exempt it just because its sid isn't the freshly-kept one.
+    subscribe("user-a", alreadyRevoked, "sid-logged-out-earlier");
+    publish("user-a", "sid-kept");
+
+    expect(alreadyRevoked).toHaveBeenCalledTimes(1);
+  });
+
+  test("publishAccessInvalidation with a keptSessionId still fires a listener with no sid of its own (fail-closed, e.g. a PAT/bearer stream)", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const sidless = mock();
+
+    subscribe("user-a", sidless);
+    publish("user-a", "sid-kept");
+
+    expect(sidless).toHaveBeenCalledTimes(1);
+  });
+
+  test("publishAccessInvalidation with no keptSessionId (unscoped) still invalidates every listener, matching pre-scoping behavior", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const first = mock();
+    const second = mock();
+
+    subscribe("user-a", first, "sid-1");
+    subscribe("user-a", second, "sid-2");
+    publish("user-a");
+
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).toHaveBeenCalledTimes(1);
+  });
 });

package/src/api/redis-sse-broker.ts

@@ -60,6 +60,17 @@ function isSseEvent(value: unknown): value is SseEvent {
   );
 }
 
+// Invalidation payload: `1` means userwide, `{ keptSessionId }` spares that one
+// session. Anything else falls back to userwide. Older pods never read the
+// payload and invalidate userwide, which keeps a mixed rolling deploy safe.
+function extractInvalidationKeptSessionId(payload: unknown): string | undefined {
+  if (typeof payload !== "object" || payload === null || !("keptSessionId" in payload)) {
+    return undefined;
+  }
+  const { keptSessionId } = payload;
+  return typeof keptSessionId === "string" && keptSessionId.length > 0 ? keptSessionId : undefined;
+}
+
 // Transport layer around a local `createSseBroker()` — all client/listener
 // state lives in `inner`, this only moves events across the Redis wire via
 // the shared PubSubSignal. `pushToChannel`/`publishAccessInvalidation` never
@@ -89,7 +100,10 @@ export function createRedisSseBroker(opts: RedisSseBrokerOptions): RedisSseBroke
     }
 
     if (channel.startsWith(INVALIDATION_PREFIX)) {
-      inner.publishAccessInvalidation(channel.slice(INVALIDATION_PREFIX.length));
+      inner.publishAccessInvalidation(
+        channel.slice(INVALIDATION_PREFIX.length),
+        extractInvalidationKeptSessionId(payload),
+      );
     }
   });
 
@@ -108,8 +122,8 @@ export function createRedisSseBroker(opts: RedisSseBrokerOptions): RedisSseBroke
     // stream must close on every replica, not just the one that observed
     // the revocation event. Publishing (rather than calling inner directly,
     // like the in-memory broker does) is what makes that true here.
-    publishAccessInvalidation(userId) {
-      signal.publish(`${INVALIDATION_PREFIX}${userId}`, 1);
+    publishAccessInvalidation(userId, keptSessionId) {
+      signal.publish(`${INVALIDATION_PREFIX}${userId}`, keptSessionId ? { keptSessionId } : 1);
     },
 
     close: signal.close,

package/src/api/request-context.ts

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { isPersonalDataGated, type WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
 import { generateId } from "../utils";
 
 // Request-scoped propagation. Populated by the HTTP middleware and by the
@@ -48,6 +49,9 @@ export type RequestContextData = {
   // performance.now() at request entry, so a failing request can report how
   // long it ran. Monotonic — a wall-clock step cannot make it negative.
   readonly startedAt?: number;
+  // Only ever a gated origin. Read by job enqueue and event-store.append();
+  // dispatch roots never narrow from it, only jobs inherit explicitly.
+  readonly writeOrigin?: WriteOrigin;
 };
 
 const storage = new AsyncLocalStorage<RequestContextData>();
@@ -87,3 +91,23 @@ export function runWithOrigin<T>(
     fn,
   );
 }
+
+// An ungated origin never mints a scope: seeds and boot writes keep their missing context.
+export function runWithWriteOrigin<T>(origin: WriteOrigin, fn: () => T): T {
+  const current = requestContext.get();
+  if (!isPersonalDataGated(origin)) {
+    if (!current?.writeOrigin) return fn();
+    const { writeOrigin: _writeOrigin, ...rest } = current;
+    return requestContext.run(rest, fn);
+  }
+  const requestId = current?.requestId ?? requestContext.generateId();
+  return requestContext.run(
+    {
+      ...current,
+      requestId,
+      correlationId: current?.correlationId ?? requestId,
+      writeOrigin: origin,
+    },
+    fn,
+  );
+}

package/src/api/sse-broker.ts

@@ -24,21 +24,38 @@ 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,
+    ownSid?: string,
+  ): () => void;
+  // `keptSessionId` spares exactly one stream: the caller's own session on a
+  // "revoke all others" write. It is a keep-list, not a list of revoked
+  // sessions, so a stream of a session already revoked without an event
+  // (plain logout) still closes. Every other reason stays userwide.
+  publishAccessInvalidation(userId: string, keptSessionId?: string): void;
 };
 
+// Fail-closed: without a kept sid, or for a listener without its own sid
+// (PAT/bearer), nothing is spared.
+function isSparedByKeptSessionId(
+  ownSid: string | undefined,
+  keptSessionId: string | undefined,
+): boolean {
+  return keptSessionId !== undefined && ownSid === keptSessionId;
+}
+
 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
+  // Keyed by callback reference, value is the subscriber's own sid. 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>>();
+  const accessInvalidationListeners = new Map<string, Map<() => void, string | undefined>>();
 
   function getOrCreateChannel(channel: string): Map<string, SseClient> {
     let clients = channels.get(channel);
@@ -86,14 +103,14 @@ export function createSseBroker(): SseBroker {
       return total;
     },
 
-    subscribeAccessInvalidation(userId, onInvalidate) {
+    subscribeAccessInvalidation(userId, onInvalidate, ownSid) {
       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, ownSid);
       return () => {
         const current = accessInvalidationListeners.get(channel);
         // skip: already unsubscribed (e.g. stream ended after a publish already fired)
@@ -103,14 +120,15 @@ export function createSseBroker(): SseBroker {
       };
     },
 
-    publishAccessInvalidation(userId) {
+    publishAccessInvalidation(userId, keptSessionId) {
       const channel = userAccessChannel(userId);
       const listeners = accessInvalidationListeners.get(channel);
       // skip: no live stream is watching this user right now
       if (!listeners) return;
       // Snapshot before iterating — a fired listener unsubscribes itself,
       // which would mutate `listeners` mid-iteration otherwise.
-      for (const onInvalidate of [...listeners]) {
+      for (const [onInvalidate, ownSid] of [...listeners]) {
+        if (isSparedByKeptSessionId(ownSid, keptSessionId)) continue;
         onInvalidate();
       }
     },

package/src/changes.json

@@ -1,4 +1,30 @@
 [
+  {
+    "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/db/queries/event-consumer.ts

@@ -1,6 +1,30 @@
+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`);
@@ -116,6 +140,7 @@ export type ConsumerDeliveryOutcome = {
   readonly lastError: string | null;
   readonly deadLettered: boolean;
   readonly processed: number;
+  readonly pendingGaps: readonly PendingGapEntry[];
 };
 
 export async function updateConsumerDeliveryOutcome(
@@ -136,14 +161,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 +220,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],
   );
@@ -269,3 +298,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);
+}

package/src/db/tenant-db.ts

@@ -51,6 +51,41 @@ const declaredUnsafeRawRunners = new WeakMap<
 // (withUnsafeRawGrant, acknowledgeConventionCrossTenant) carry it too.
 const personalDataGates = new WeakMap<TenantDb, PersonalDataGate>();
 
+// Lets createTenantDb(ctx.db.unsafeRaw(reason), ...) inherit the gate. Keyed by a
+// per-grant proxy, never the shared pool/tx: tagging that would gate every sibling TenantDb.
+const runnerPersonalDataGates = new WeakMap<DbRunner, PersonalDataGate>();
+
+function gatedRunner(runner: DbRunner, gate: PersonalDataGate): DbRunner {
+  const proxy = new Proxy(runner as object, {
+    // Tagged-template calls need the real driver object as `this`.
+    apply(target, _thisArg, args) {
+      return Reflect.apply(target as (...callArgs: unknown[]) => unknown, target, args);
+    },
+    get(target, prop, _receiver) {
+      const value = Reflect.get(target, prop, target);
+      if (typeof value !== "function") return value;
+      if (prop === "begin" || prop === "savepoint") {
+        // createTenantDb(tx, ...) inside the callback must inherit the gate too.
+        return (...args: unknown[]) => {
+          const callback = args[args.length - 1];
+          if (typeof callback !== "function") {
+            return Reflect.apply(value, target, args);
+          }
+          const gatedArgs = [
+            ...args.slice(0, -1),
+            (tx: unknown) => callback(gatedRunner(tx as DbRunner, gate)),
+          ];
+          return Reflect.apply(value, target, gatedArgs);
+        };
+      }
+      return value.bind(target);
+    },
+    // @cast-boundary proxy-erasure — Proxy<object> re-tags as the wrapped DbRunner shape.
+  }) as DbRunner;
+  runnerPersonalDataGates.set(proxy, gate);
+  return proxy;
+}
+
 // The executor passes its entity so the check does not depend on the table-name lookup.
 export function assertPersonalDataWrite(
   db: TenantDb,
@@ -151,7 +186,9 @@ function buildUncheckedSystemDb(
       });
     }
     report("unsafe-raw", reason);
-    return tenantDbRunner(db);
+    const runner = tenantDbRunner(db);
+    const personalDataGate = personalDataGates.get(db);
+    return personalDataGate ? gatedRunner(runner, personalDataGate) : runner;
   }
 
   const uncheckedSystemDb: UncheckedSystemDb = {
@@ -352,6 +389,7 @@ export function createTenantDb(
 ): TenantDb {
   if (meter) registerStandardMetrics(meter);
   const report = grants?.report ?? fallbackEscapeHatchReporter(tenantId);
+  const personalDataGate = grants?.personalDataGate ?? runnerPersonalDataGates.get(db);
 
   function withDbSpan<T>(
     operation: "select" | "insert" | "update" | "delete",
@@ -452,9 +490,9 @@ export function createTenantDb(
     table: Table | EntityTableMeta,
     keys: readonly string[],
   ): AccessDeniedError | undefined {
-    if (!grants?.personalDataGate) return undefined;
+    if (!personalDataGate) return undefined;
     try {
-      grants.personalDataGate(tableNameOf(table), keys);
+      personalDataGate(tableNameOf(table), keys);
       return undefined;
     } catch (e) {
       if (e instanceof AccessDeniedError) return e;
@@ -553,7 +591,7 @@ export function createTenantDb(
       });
     }
     report("unsafe-raw", reason);
-    return db;
+    return personalDataGate ? gatedRunner(db, personalDataGate) : db;
   }
 
   const tenantDb: TenantDb = {
@@ -648,7 +686,7 @@ export function createTenantDb(
     return createTenantDb(db, tenantId, "system", tracer, meter, signal, grants);
   });
   bindTenantDbRunner(tenantDb, db);
-  if (grants?.personalDataGate) personalDataGates.set(tenantDb, grants.personalDataGate);
+  if (personalDataGate) personalDataGates.set(tenantDb, personalDataGate);
   return tenantDb;
 }