@cosmicdrift/kumiko-framework 0.270.0 → 0.273.0

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

@@ -2,18 +2,39 @@ import { describe, expect, mock, test } from "bun:test";
 import type { DbRunner } from "../../db/connection";
 import { createTenantDb, type TenantDb } from "../../db/tenant-db";
 import { createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID } from "../../engine";
-import type { SessionUser } from "../../engine/types";
+import type {
+  EscapeHatchReporter,
+  EscapeHatchTarget,
+  MemberReader,
+  SessionUser,
+} from "../../engine/types";
 import type { TenantId } from "../../engine/types/identifiers";
 import { AccessDeniedError, FrameworkReasons } from "../../errors";
 import {
   createGatedIdentitySwitch,
+  createGatedMemberReader,
+  createGatedProjectionReader,
   type IdentitySwitch,
   isIdentitySwitchAllowed,
   isSystemIdentity,
+  type ProjectionReader,
   type WriteAsFn,
   withHookEscapeHatchGrant,
 } from "../system-identity-switch";
 
+function recordingReporter(): {
+  readonly report: EscapeHatchReporter;
+  readonly calls: Array<{ kind: string; reason: string; target: EscapeHatchTarget | undefined }>;
+} {
+  const calls: Array<{ kind: string; reason: string; target: EscapeHatchTarget | undefined }> = [];
+  return {
+    report: (kind, reason, target) => {
+      calls.push({ kind, reason, target });
+    },
+    calls,
+  };
+}
+
 const TENANT = "00000000-0000-4000-8000-00000000ab01" as TenantId;
 
 const normalUser: SessionUser = { id: crypto.randomUUID(), tenantId: TENANT, roles: ["User"] };
@@ -224,6 +245,69 @@ describe("createGatedIdentitySwitch", () => {
   });
 });
 
+function makeUngatedProjectionReader(): {
+  readonly ungated: ProjectionReader;
+  readonly mockFn: ReturnType<typeof mock>;
+} {
+  const mockFn = mock(async (_qn: string, _options?: { readonly unsafeAllTenants?: boolean }) => [
+    { ok: true },
+  ]);
+  return { ungated: mockFn as unknown as ProjectionReader, mockFn };
+}
+
+describe("createGatedProjectionReader", () => {
+  test("without a grant, unsafeAllTenants: true throws AccessDeniedError and never calls ungated", async () => {
+    const { ungated, mockFn } = makeUngatedProjectionReader();
+    const gated = createGatedProjectionReader('handler "x"', false, ungated);
+
+    let caught: unknown;
+    try {
+      await gated("qp:projection:widgets", { unsafeAllTenants: true });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(AccessDeniedError);
+    const error = caught as AccessDeniedError;
+    expect(error.details).toEqual({ reason: FrameworkReasons.unsafeAllTenantsDenied });
+    expect(mockFn).not.toHaveBeenCalled();
+  });
+
+  test("without the unsafeAllTenants option, calls ungated directly with no report", async () => {
+    const { ungated, mockFn } = makeUngatedProjectionReader();
+    const { report, calls } = recordingReporter();
+    const gated = createGatedProjectionReader('handler "x"', false, ungated, {
+      reason: "escapeHatch reason",
+      report,
+    });
+
+    await gated("qp:projection:widgets");
+
+    expect(mockFn).toHaveBeenCalledWith("qp:projection:widgets", undefined);
+    expect(calls).toEqual([]);
+  });
+
+  test("with a grant, unsafeAllTenants: true calls ungated and reports exactly once", async () => {
+    const { ungated, mockFn } = makeUngatedProjectionReader();
+    const { report, calls } = recordingReporter();
+    const gated = createGatedProjectionReader('handler "x"', true, ungated, {
+      reason: 'r.systemScope() feature "widgets"',
+      report,
+    });
+
+    await gated("qp:projection:widgets", { unsafeAllTenants: true });
+
+    expect(mockFn).toHaveBeenCalledWith("qp:projection:widgets", { unsafeAllTenants: true });
+    expect(calls).toEqual([
+      {
+        kind: "unsafe-all-tenants",
+        reason: 'r.systemScope() feature "widgets"',
+        target: undefined,
+      },
+    ]);
+  });
+});
+
 describe("withHookEscapeHatchGrant", () => {
   test("hook without escapeHatch does NOT inherit the handler's SYSTEM grant", async () => {
     const { ungated } = makeUngated();
@@ -403,4 +487,159 @@ describe("withHookEscapeHatchGrant", () => {
     }) as { db: TenantDb };
     expect(hookCtxWithEscapeHatch.db.unsafeRaw("test reason")).toBe(rawDb);
   });
+
+  test("handler-granted queryProjection reader: hook without escapeHatch loses the grant for unsafeAllTenants", async () => {
+    const { ungated, mockFn } = makeUngatedProjectionReader();
+    const handlerCtx = {
+      queryProjection: createGatedProjectionReader('handler "outer"', true, ungated),
+    };
+
+    const hookCtx = withHookEscapeHatchGrant(handlerCtx, "hook", undefined) as {
+      queryProjection: ProjectionReader;
+    };
+
+    await expect(
+      hookCtx.queryProjection("qp:projection:widgets", { unsafeAllTenants: true }),
+    ).rejects.toBeInstanceOf(AccessDeniedError);
+    expect(mockFn).not.toHaveBeenCalled();
+  });
+
+  test("hook's own escapeHatch grants queryProjection's unsafeAllTenants and reports with the hook's reason", async () => {
+    const { ungated, mockFn } = makeUngatedProjectionReader();
+    const { report, calls } = recordingReporter();
+    const handlerCtx = {
+      queryProjection: createGatedProjectionReader('handler "outer"', false, ungated, {
+        reason: undefined,
+        report,
+      }),
+    };
+
+    const hookCtx = withHookEscapeHatchGrant(handlerCtx, "hook", {
+      reason: "hook's own grant",
+    }) as { queryProjection: ProjectionReader };
+
+    await hookCtx.queryProjection("qp:projection:widgets", { unsafeAllTenants: true });
+
+    expect(mockFn).toHaveBeenCalledWith("qp:projection:widgets", { unsafeAllTenants: true });
+    expect(calls).toEqual([
+      { kind: "unsafe-all-tenants", reason: "hook's own grant", target: undefined },
+    ]);
+  });
+});
+
+describe("createGatedIdentitySwitch — escape-hatch reporting", () => {
+  test("granted switch to SYSTEM reports identity-switch once with the target", async () => {
+    const { ungated } = makeUngated();
+    const { report, calls } = recordingReporter();
+    const gated = createGatedIdentitySwitch('handler "x"', normalUser, true, ungated, {
+      reason: 'r.systemScope() feature "widgets"',
+      report,
+    });
+
+    await gated.queryAs(systemUserById, "q", {});
+
+    expect(calls).toEqual([
+      {
+        kind: "identity-switch",
+        reason: 'r.systemScope() feature "widgets"',
+        target: { id: systemUserById.id, tenantId: systemUserById.tenantId },
+      },
+    ]);
+  });
+
+  test("self-delegation with a grant reports nothing", async () => {
+    const { ungated } = makeUngated();
+    const { report, calls } = recordingReporter();
+    const gated = createGatedIdentitySwitch('handler "x"', normalUser, true, ungated, {
+      reason: "escapeHatch reason",
+      report,
+    });
+
+    await gated.queryAs(normalUser, "q", {});
+
+    expect(calls).toEqual([]);
+  });
+
+  test("a denied switch reports nothing", async () => {
+    const { ungated } = makeUngated();
+    const { report, calls } = recordingReporter();
+    const gated = createGatedIdentitySwitch('handler "x"', normalUser, false, ungated, {
+      reason: "escapeHatch reason",
+      report,
+    });
+
+    await expect(gated.queryAs(systemUserById, "q", {})).rejects.toBeInstanceOf(AccessDeniedError);
+
+    expect(calls).toEqual([]);
+  });
+
+  test("hook re-gating via withHookEscapeHatchGrant reports with the HOOK's reason", async () => {
+    const { ungated } = makeUngated();
+    const { report, calls } = recordingReporter();
+    const handlerCtx = {
+      ...createGatedIdentitySwitch('handler "outer"', normalUser, true, ungated, {
+        reason: "handler's own grant",
+        report,
+      }),
+    };
+
+    const hookCtx = withHookEscapeHatchGrant(handlerCtx, "hook", { reason: "hook's own grant" });
+    await hookCtx.queryAs(systemUserById, "q", {});
+
+    expect(calls).toEqual([
+      {
+        kind: "identity-switch",
+        reason: "hook's own grant",
+        target: { id: systemUserById.id, tenantId: systemUserById.tenantId },
+      },
+    ]);
+  });
+
+  test("hook re-gates and reports even when the handler itself has no grant (reason: undefined)", async () => {
+    const { ungated } = makeUngated();
+    const { report, calls } = recordingReporter();
+    // Handler has NO grant (hasGrant=false, reason: undefined) — the report fn
+    // must still be attached so a hook's own escapeHatch can use it.
+    const handlerCtx = {
+      ...createGatedIdentitySwitch('handler "outer"', normalUser, false, ungated, {
+        reason: undefined,
+        report,
+      }),
+    };
+
+    const hookCtx = withHookEscapeHatchGrant(handlerCtx, "hook", { reason: "hook reason" });
+    await hookCtx.queryAs(systemUserById, "q", {});
+
+    expect(calls).toEqual([
+      {
+        kind: "identity-switch",
+        reason: "hook reason",
+        target: { id: systemUserById.id, tenantId: systemUserById.tenantId },
+      },
+    ]);
+  });
+
+  test("queryAsMember hook re-gates and reports even when the handler itself has no grant", async () => {
+    const ungatedReader: MemberReader = mock(async () => ({ ok: true }));
+    const { report, calls } = recordingReporter();
+    const gatedReader = createGatedMemberReader('handler "outer"', false, ungatedReader, {
+      reason: undefined,
+      report,
+      tenantId: TENANT,
+    });
+    const handlerCtx = { queryAsMember: gatedReader };
+
+    const hookCtx = withHookEscapeHatchGrant(handlerCtx, "hook", { reason: "hook reason" }) as {
+      queryAsMember: MemberReader;
+    };
+    await hookCtx.queryAsMember(systemUserById.id, "q", {});
+
+    expect(calls).toEqual([
+      {
+        kind: "identity-switch",
+        reason: "hook reason",
+        target: { id: systemUserById.id, tenantId: TENANT },
+      },
+    ]);
+  });
 });

package/src/pipeline/dispatch-query.ts

@@ -1,7 +1,7 @@
 import type { DbRow, DbTx } from "../db/connection";
 import { hasAccess } from "../engine/access";
 import { filterReadFields } from "../engine/field-access";
-import type { SessionUser } from "../engine/types";
+import type { QueryHandlerDef, SessionUser } from "../engine/types";
 import { AccessDeniedError, NotFoundError, validationErrorFromZod } from "../errors";
 import { assertNoSecretLeak } from "../secrets";
 import type { DispatchContext } from "./dispatch-shared";
@@ -11,6 +11,7 @@ import {
   ensureFeatureEnabled,
   runHandlerInstrumented,
 } from "./dispatch-shared";
+import { runInMemberReadOnlyTransaction } from "./member-read-only-transaction";
 
 // Standalone query execution — used by the public dispatcher.query() and
 // by ctx.query/ctx.queryAs inside handlers. Runs the handler, applies
@@ -48,12 +49,11 @@ async function executeQueryInner(
   // unauthorized callers must hit the cap too (otherwise the limit
   // would be a free probe-detector for valid credentials). The
   // resolver throws RateLimitError which the dispatcher's outer
-  // wrapper turns into a 429 response. Inline-skip when the handler
-  // didn't opt in — keeps the hot path zero-cost (no await on a
-  // no-op promise).
-  if (handler.rateLimit !== undefined) {
-    await enforceRateLimit(ctx, handler.rateLimit, type, user);
-  }
+  // wrapper turns into a 429 response. Apps that don't use L3 pay zero
+  // cost for non-systemScope handlers with no rateLimit declared;
+  // systemScope handlers pay one isHandlerSystemScoped lookup to check
+  // whether the default per-tenant limit applies.
+  await enforceRateLimit(ctx, handler.rateLimit, type, user, registry.isHandlerSystemScoped(type));
 
   // Default-deny: missing access rule is treated as "no one has access".
   // The registry boot-validator refuses to register handlers without one,
@@ -79,8 +79,27 @@ async function executeQueryInner(
     typeof parsed.data === "object" &&
     parsed.data !== null &&
     (parsed.data as Record<string, unknown>)["includeDeleted"] === true; // @cast-boundary validated-payload
+
+  // A resolved member (ctx.queryAsMember) runs in a Postgres READ ONLY transaction, not just the ctx surface below.
+  return user.origin === "member-resolution"
+    ? runInMemberReadOnlyTransaction(ctx, tx, (readOnlyTx) =>
+        runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, readOnlyTx),
+      )
+    : runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, tx);
+}
+
+async function runQueryHandler(
+  ctx: DispatchContext,
+  type: string,
+  handler: QueryHandlerDef,
+  payload: unknown,
+  includeDeleted: boolean,
+  user: SessionUser,
+  tx: DbTx | undefined,
+): Promise<unknown> {
+  const { registry } = ctx;
   const handlerContext = await buildHandlerContext(ctx, type, user, tx, undefined, includeDeleted);
-  let result = await handler.handler({ type, payload: parsed.data, user }, handlerContext);
+  let result = await handler.handler({ type, payload, user }, handlerContext);
 
   // postQuery-Hooks: fire BEFORE field-access-filter so hooks see raw data
   // and can merge custom-fields/computed-counts/tags/etc. Each hook is

package/src/pipeline/dispatch-shared.ts

@@ -3,7 +3,12 @@ import type { SseBroker } from "../api/sse-broker";
 import type { DbConnection, DbRunner, DbTx } from "../db/connection";
 import { runInSavepoint, selectMany } from "../db/query";
 import type { buildEntityTable } from "../db/table-builder";
-import { createTenantDb, createUncheckedSystemDb, type TenantDb } from "../db/tenant-db";
+import {
+  createTenantDb,
+  createUncheckedSystemDb,
+  hasTenantColumn,
+  type TenantDb,
+} from "../db/tenant-db";
 import { createDerivativesContext } from "../derivatives/derivatives-context";
 import type { defineTransitions } from "../engine/state-machine";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension";
@@ -17,10 +22,13 @@ import type {
   HandlerContext,
   JobRunnerRef,
   MemberReader,
+  RateLimitDeclaration,
+  RateLimitOption,
   Registry,
   SessionUser,
   WriteResult,
 } from "../engine/types";
+import { isRateLimitDisabled } from "../engine/types";
 import type { TenantId } from "../engine/types/identifiers";
 import {
   AccessDeniedError,
@@ -77,12 +85,16 @@ import {
   dispatcherSpanAttributes,
   isFailedWriteResult,
 } from "./dispatcher-utils";
+import { createEscapeHatchReporter, type EscapeHatchReportWindow } from "./escape-hatch-report";
 import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
 import { createMemberReaderFn } from "./member-reader";
 import {
   createGatedIdentitySwitch,
   createGatedMemberReader,
+  createGatedProjectionReader,
+  isSystemIdentity,
+  type ProjectionReader,
   systemIdentitySwitchDenied,
 } from "./system-identity-switch";
 import type { TenantTimezoneCache } from "./tenant-timezone-cache";
@@ -130,6 +142,7 @@ export type DispatchContext = {
   tableCache: Map<string, ReturnType<typeof buildEntityTable>>;
   transitionCache: Map<string, ReturnType<typeof defineTransitions>>;
   tenantTimezoneCache: TenantTimezoneCache;
+  escapeHatchReportWindow: EscapeHatchReportWindow;
   tracer: ReturnType<typeof getFallbackTracer>;
   meter: ReturnType<typeof getFallbackMeter>;
   // Qualified name of the membership-list query handler consulted by
@@ -206,10 +219,11 @@ function createSystemScopedDbGuard(
   });
 }
 
-export function memberResolutionReadOnlyDenied(): AccessDeniedError {
+export function memberResolutionReadOnlyDenied(cause?: unknown): AccessDeniedError {
   return new AccessDeniedError({
     message: "a resolved member principal (ctx.queryAsMember) cannot write — read-only",
     details: { reason: FrameworkReasons.memberResolutionReadOnly },
+    ...(cause instanceof Error && { cause }),
   });
 }
 
@@ -232,11 +246,12 @@ function denyingJobRunnerProxy(): JobRunnerRef {
 function applyMemberResolutionReadOnly(handlerContext: HandlerContext): HandlerContext {
   return {
     ...handlerContext,
-    // `db` itself stays open — same access the member's own HTTP request has;
-    // raw ctx.db writes inside a queried handler are not blocked by this.
+    // `db` stays open — executeQuery runs the whole handler in a Postgres READ ONLY transaction.
     dbOutsideTransaction: undefined,
     write: denyMemberResolutionWrite,
     writeAs: denyMemberResolutionWrite,
+    // A resolved member cannot switch identity either — the target would get a normal, writable context.
+    queryAs: denyMemberResolutionWrite,
     appendEvent: denyMemberResolutionWrite as AppendEventFn, // @cast-boundary engine-bridge
     unsafeAppendEvent: denyMemberResolutionWrite,
     tryAppendEvent: denyMemberResolutionWrite,
@@ -281,6 +296,18 @@ export async function buildHandlerContext(
     registry.getQueryHandler(type)?.escapeHatch ??
     registry.getStreamHandler(type)?.escapeHatch;
   const hasIdentitySwitchGrant = isSystem || handlerEscapeHatch !== undefined;
+  const featureName = registry.getHandlerFeature(type);
+  const reportEscapeHatch = createEscapeHatchReporter({
+    handler: type,
+    tenantId: user.tenantId,
+    actor: user.id,
+    sink: context._escapeHatchAuditSink,
+    log: context.log,
+    window: ctx.escapeHatchReportWindow,
+  });
+  const identitySwitchGrantReason =
+    handlerEscapeHatch?.reason ??
+    (isSystem ? `r.systemScope() feature "${featureName ?? "unknown"}"` : undefined);
   const buildTenantScopedDb = (source: DbConnection | DbTx, signal: AbortSignal | undefined) =>
     createTenantDb(
       source,
@@ -289,7 +316,7 @@ export async function buildHandlerContext(
       context.tracer,
       context.meter,
       signal,
-      { globalWrites: writeEscapeHatch, unsafeRaw: handlerEscapeHatch },
+      { globalWrites: writeEscapeHatch, unsafeRaw: handlerEscapeHatch, report: reportEscapeHatch },
     );
   // Propagate the request's AbortSignal so every TenantDb query throws when
   // the client has disconnected — handlers with many sequential queries skip
@@ -306,7 +333,9 @@ export async function buildHandlerContext(
     ? buildTenantScopedDb(outsideTxSource, undefined)
     : undefined;
   const systemDb =
-    isSystem && db ? createUncheckedSystemDb(db, rawDbOutsideTransaction) : undefined;
+    isSystem && db
+      ? createUncheckedSystemDb(db, rawDbOutsideTransaction, reportEscapeHatch)
+      : undefined;
   // Exposed as ctx.db below — the internal `db` above stays the real,
   // working TenantDb for this function's own use (config/derivatives
   // accessors, systemDb construction).
@@ -366,7 +395,6 @@ export async function buildHandlerContext(
   // so legacy internal handlers don't crash.
   const tracer = context.tracer ?? getFallbackTracer();
   const meter = context.meter;
-  const featureName = registry.getHandlerFeature(type);
   const metrics =
     meter && featureName ? createMetricsHandle(meter, featureName) : createNoopMetricsHandle();
   // ctx.metricsFor(featureName) — shared/library code binds to a feature
@@ -383,6 +411,7 @@ export async function buildHandlerContext(
   const scheduleAfterCommit = (hook: AfterCommitHook): void => {
     bridgeSink.push(hook);
   };
+  const identitySwitchAudit = { reason: identitySwitchGrantReason, report: reportEscapeHatch };
   const identitySwitch = createGatedIdentitySwitch(
     `handler "${type}"`,
     user,
@@ -393,6 +422,7 @@ export async function buildHandlerContext(
       writeAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
         executeWrite(ctx, targetType, payload, asUser, tx, bridgeSink),
     },
+    identitySwitchAudit,
   );
   // Lazy — creates the reader (which fails closed on SYSTEM_TENANT_ID) only
   // on first actual use, not on every HandlerContext build.
@@ -404,6 +434,48 @@ export async function buildHandlerContext(
       ungatedMemberReader ??= createMemberReaderFn(ctx, user.tenantId, tx);
       return ungatedMemberReader(userId, qn, payload);
     },
+    { ...identitySwitchAudit, tenantId: user.tenantId },
+  );
+  const ungatedQueryProjection: ProjectionReader = async <T = Record<string, unknown>>(
+    qualifiedName: string,
+    queryOptions?: { readonly unsafeAllTenants?: boolean },
+  ): Promise<readonly T[]> => {
+    // queryProjection works against both single-stream and multi-stream
+    // projections. MSPs without a table cannot be queried — those are
+    // side-effect-only consumers (no state to read back).
+    const singleProj = registry.getAllProjections().get(qualifiedName);
+    const mspProj = registry.getAllMultiStreamProjections().get(qualifiedName);
+    const projTable = singleProj?.table ?? mspProj?.table;
+    if (!projTable) {
+      const singleNames = [...registry.getAllProjections().keys()];
+      const mspNames = [...registry.getAllMultiStreamProjections().keys()].filter(
+        (n) => registry.getAllMultiStreamProjections().get(n)?.table,
+      );
+      const all = [...singleNames, ...mspNames];
+      throw new InternalError({
+        message:
+          `ctx.queryProjection("${qualifiedName}") — projection not registered, or it is a ` +
+          `table-less MSP (side-effect-only). Known queryable projections: ${all.join(", ") || "(none)"}`,
+      });
+    }
+    const dbSource = resolveDbSource(ctx, tx);
+    if (!dbSource) {
+      throw new InternalError({
+        message: `ctx.queryProjection("${qualifiedName}") requires a database connection — none is configured.`,
+      });
+    }
+    const where =
+      hasTenantColumn(projTable) && queryOptions?.unsafeAllTenants !== true
+        ? { tenantId: user.tenantId }
+        : undefined;
+    const rows = await selectMany<Record<string, unknown>>(dbSource, projTable, where);
+    return rows as readonly T[]; // @cast-boundary engine-payload
+  };
+  const queryProjection = createGatedProjectionReader(
+    `handler "${type}"`,
+    hasIdentitySwitchGrant,
+    ungatedQueryProjection,
+    identitySwitchAudit,
   );
   const bridge = {
     query: (targetType: string, payload: unknown) =>
@@ -630,44 +702,7 @@ export async function buildHandlerContext(
         },
       );
     },
-    queryProjection: async <T = Record<string, unknown>>(
-      qualifiedName: string,
-      queryOptions?: { readonly unsafeAllTenants?: boolean },
-    ): Promise<readonly T[]> => {
-      // queryProjection works against both single-stream and multi-stream
-      // projections. MSPs without a table cannot be queried — those are
-      // side-effect-only consumers (no state to read back).
-      const singleProj = registry.getAllProjections().get(qualifiedName);
-      const mspProj = registry.getAllMultiStreamProjections().get(qualifiedName);
-      const projTable = singleProj?.table ?? mspProj?.table;
-      if (!projTable) {
-        const singleNames = [...registry.getAllProjections().keys()];
-        const mspNames = [...registry.getAllMultiStreamProjections().keys()].filter(
-          (n) => registry.getAllMultiStreamProjections().get(n)?.table,
-        );
-        const all = [...singleNames, ...mspNames];
-        throw new InternalError({
-          message:
-            `ctx.queryProjection("${qualifiedName}") — projection not registered, or it is a ` +
-            `table-less MSP (side-effect-only). Known queryable projections: ${all.join(", ") || "(none)"}`,
-        });
-      }
-      const dbSource = resolveDbSource(ctx, tx);
-      if (!dbSource) {
-        throw new InternalError({
-          message: `ctx.queryProjection("${qualifiedName}") requires a database connection — none is configured.`,
-        });
-      }
-      // Introspect for a tenant_id column on the projection table. Auto-
-      // 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.
-      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
-    },
+    queryProjection,
     // Thin pass-through: one resolve impl lives on the dispatcher, the
     // handler surface just forwards the call so both entry points (login
     // handler via ctx.resolveAuthClaims, switch-tenant route via
@@ -1009,28 +1044,60 @@ export async function ensureFeatureEnabled(
   if (err) throw err;
 }
 
+// systemScope handlers get a default per-tenant limit unless the app declared its own or
+// opted out — but ONLY when a resolver is actually configured (an app without the
+// rate-limiting feature must not start throwing InternalError on every systemScope call
+// just because it never opted into L3), and never for a SYSTEM-identity caller (jobs,
+// replay, internal queryAs(SYSTEM,...) — those are not the tenant-facing traffic this
+// default protects against).
+// per: "tenant+handler" (not "tenant") — a per-handler bucket so one hot systemScope
+// handler cannot starve every other systemScope handler's shared tenant quota.
+const DEFAULT_SYSTEM_SCOPE_RATE_LIMIT: RateLimitOption = {
+  per: "tenant+handler",
+  limit: 600,
+  windowSeconds: 60,
+};
+
+function resolveEffectiveRateLimit(
+  rateLimit: RateLimitOption | undefined,
+  isSystemScope: boolean,
+  user: SessionUser,
+  resolver: AppContext["rateLimit"],
+): RateLimitOption | undefined {
+  if (rateLimit) return rateLimit;
+  if (!isSystemScope) return undefined;
+  if (!resolver) return undefined;
+  if (isSystemIdentity(user)) return undefined;
+  return DEFAULT_SYSTEM_SCOPE_RATE_LIMIT;
+}
+
 // L3 rate limit gate. Called by both query and write paths before
 // access-check. Reasoning:
-//   - handler without rateLimit → no-op
+//   - handler without rateLimit and not systemScope → no-op
+//   - systemScope handler without rateLimit → DEFAULT_SYSTEM_SCOPE_RATE_LIMIT
+//     applies, unless no resolver is configured or the caller is SYSTEM
 //   - app booted without rateLimit resolver → InternalError so the
-//     misconfig surfaces immediately, not on first 429
+//     misconfig surfaces immediately, not on first 429 (only reachable once
+//     an effective rate limit was actually resolved above)
 //   - bucket builder returns "skip" (e.g. ip-based but no client IP):
 //     pass through. ip-modes are commonly used at L1/L2 middleware
 //     where the IP comes from Hono directly; falling back to "skip"
 //     here keeps non-HTTP entry-points (jobs, MSPs) functional.
 export async function enforceRateLimit(
   ctx: DispatchContext,
-  rateLimit: import("../engine/types").RateLimitOption | undefined,
+  rateLimit: RateLimitDeclaration | undefined,
   handlerName: string,
   user: SessionUser,
+  isSystemScope: boolean,
 ): Promise<void> {
   const { appContext: context } = ctx;
-  // skip: defence-in-depth — both call-sites already gate on
-  //       handler.rateLimit !== undefined, so this branch only fires
-  //       if a future caller forgets the inline check.
-  if (!rateLimit) return;
+  // skip: handler explicitly opts out via rateLimit: { disabled: true }
+  if (isRateLimitDisabled(rateLimit)) return;
+  const effective = resolveEffectiveRateLimit(rateLimit, isSystemScope, user, context.rateLimit);
+  // skip: no rateLimit declared and not systemScope (or resolved to no-op) — nothing to enforce
+  if (!effective) return;
   const reqCtx = requestContext.get();
-  const bucket = buildBucketKey(rateLimit, {
+  const bucket = buildBucketKey(effective, {
     handlerName,
     user,
     ip: reqCtx?.ip,
@@ -1044,9 +1111,9 @@ export async function enforceRateLimit(
     });
   }
   await context.rateLimit.enforce(bucket.key, {
-    limit: rateLimit.limit,
-    windowSeconds: rateLimit.windowSeconds,
-    cost: rateLimit.cost,
+    limit: effective.limit,
+    windowSeconds: effective.windowSeconds,
+    cost: effective.cost,
   });
 }
 
@@ -1063,7 +1130,24 @@ function buildAuthClaimsContext(ctx: DispatchContext, user: SessionUser): AuthCl
       message: "dispatcher.resolveAuthClaims requires a database connection — none is configured.",
     });
   }
-  const db = createTenantDb(dbSource, user.tenantId, "tenant", context.tracer, context.meter);
+  const db = createTenantDb(
+    dbSource,
+    user.tenantId,
+    "tenant",
+    context.tracer,
+    context.meter,
+    undefined,
+    {
+      report: createEscapeHatchReporter({
+        handler: "r.authClaims hook",
+        tenantId: user.tenantId,
+        actor: user.id,
+        sink: context._escapeHatchAuditSink,
+        log: context.log,
+        window: ctx.escapeHatchReportWindow,
+      }),
+    },
+  );
   const configAccessor = context._configAccessorFactory
     ? context._configAccessorFactory({
         user: { id: user.id, tenantId: user.tenantId },