@cosmicdrift/kumiko-framework 0.270.0 → 0.274.0

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 },

package/src/pipeline/dispatch-stream.ts

@@ -44,9 +44,7 @@ async function* executeStreamInner(
 
   await ensureFeatureEnabled(ctx, type, user.tenantId);
 
-  if (handler.rateLimit !== undefined) {
-    await enforceRateLimit(ctx, handler.rateLimit, type, user);
-  }
+  await enforceRateLimit(ctx, handler.rateLimit, type, user, registry.isHandlerSystemScoped(type));
 
   if (!hasAccess(user, handler.access)) {
     throw new AccessDeniedError({

package/src/pipeline/dispatch-write.ts

@@ -1,10 +1,11 @@
-import type { DbRow, DbTx } from "../db/connection";
+import type { DbRow, DbRunner, DbTx } from "../db/connection";
 import { selectRowForUpdateById } from "../db/queries/entity-read";
 import { asEntityTableMeta, selectMany } from "../db/query";
 import { buildEntityTable, toSnakeCase } from "../db/table-builder";
+import { tenantDbRunner } from "../db/tenant-db-runner";
 import { hasAccess } from "../engine/access";
 import { ConfigScopes } from "../engine/constants";
-import { checkWriteFieldRoles } from "../engine/field-access";
+import { checkWriteFieldOwnership, checkWriteFieldRoles } from "../engine/field-access";
 import { defineTransitions, guardTransition } from "../engine/state-machine";
 import type { HandlerContext, SessionUser, WriteResult } from "../engine/types";
 import { HookPhases } from "../engine/types";
@@ -28,6 +29,7 @@ import {
   checkFeatureEnabled,
   enforceRateLimit,
   memberResolutionReadOnlyDenied,
+  resolveDbSource,
   runHandlerInstrumented,
   TENANT_TIMEZONE_CONFIG_KEY,
 } from "./dispatch-shared";
@@ -127,6 +129,7 @@ async function runLifecycle(
   handlerContext: HandlerContext,
   user: SessionUser,
   afterCommitHooks: AfterCommitHook[],
+  runner: DbRunner | undefined,
 ): Promise<void> {
   const { lifecycle } = ctx;
   if (!lifecycle) {
@@ -143,7 +146,7 @@ async function runLifecycle(
   // hooks. If a projection apply() throws, the whole tx rolls back — the
   // event and the auto-projection row go with it. Running before the hooks
   // keeps projection state consistent with what the hooks observe.
-  await runProjections(result, handlerContext);
+  await runProjections(result, handlerContext.registry, runner);
 
   if (result.kind === "save") {
     await lifecycle.runPostSave(type, result, handlerContext, HookPhases.inTransaction);
@@ -196,6 +199,14 @@ export async function executeWrite(
   );
 }
 
+function isForeignTenantParentRow(
+  parentRow: Readonly<Record<string, unknown>>,
+  user: SessionUser,
+): boolean {
+  const rowTenantId = parentRow["tenantId"];
+  return typeof rowTenantId === "string" && rowTenantId !== user.tenantId;
+}
+
 // Nested-write orchestration (v1: depth=1, create-only, hasMany-only).
 //
 // When a parent `:create` handler's payload carries values under keys
@@ -286,6 +297,36 @@ export async function executeNestedWrite(
     );
   }
 
+  // A custom create handler may return an existing foreign row; verify it before attaching children.
+  if (!registry.isHandlerSystemScoped(type) && isForeignTenantParentRow(parentRow, user)) {
+    return writeFailure(
+      new AccessDeniedError({
+        message: `nested-write: parent row belongs to another tenant — refusing to attach children to "${type}"`,
+        details: { reason: FrameworkReasons.fieldAccessDenied, handler: type },
+      }),
+    );
+  }
+  const parentEntityName = registry.getHandlerEntity(type);
+  if (parentEntityName) {
+    const parentEntity = registry.getEntity(parentEntityName);
+    if (parentEntity) {
+      const deniedField = checkWriteFieldOwnership(parentEntity, parentRow, user);
+      if (deniedField) {
+        return writeFailure(
+          new AccessDeniedError({
+            message: `nested-write: parent row ownership check failed on field "${deniedField}" of "${type}" — refusing to attach children to a parent row the caller does not own`,
+            i18nKey: "errors.access.fieldDenied",
+            details: {
+              reason: FrameworkReasons.fieldAccessDenied,
+              field: deniedField,
+              handler: type,
+            },
+          }),
+        );
+      }
+    }
+  }
+
   for (const spec of nested.specs) {
     const subRows: Record<string, unknown>[] = [];
     for (let i = 0; i < spec.items.length; i++) {
@@ -341,15 +382,21 @@ async function executeWriteInner(
 
   // Rate-limit gate before access (same reasoning as in executeQueryInner).
   // Throws RateLimitError; the outer wrapper turns it into a 429
-  // WriteFailure via toWriteErrorInfo. Inline-skip when no opt-in —
-  // hot path stays zero-cost.
-  if (handler.rateLimit !== undefined) {
-    try {
-      await enforceRateLimit(ctx, handler.rateLimit, type, user);
-    } catch (e) {
-      if (isKumikoError(e)) return writeFailure(e);
-      throw e;
-    }
+  // WriteFailure via toWriteErrorInfo. 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.
+  try {
+    await enforceRateLimit(
+      ctx,
+      handler.rateLimit,
+      type,
+      user,
+      registry.isHandlerSystemScoped(type),
+    );
+  } catch (e) {
+    if (isKumikoError(e)) return writeFailure(e);
+    throw e;
   }
 
   // Default-deny: missing access rule is treated as "no one has access".
@@ -447,7 +494,7 @@ async function executeWriteInner(
         // active (tests without a DB connection).
         const tableName = asEntityTableMeta(table)?.tableName ?? "";
         const rows = tx
-          ? await selectRowForUpdateById(transitionGuardDb, tableName, id)
+          ? await selectRowForUpdateById(tenantDbRunner(transitionGuardDb), tableName, id)
           : await selectMany(transitionGuardDb, table, { id });
         const row = rows[0];
 
@@ -504,7 +551,8 @@ async function executeWriteInner(
 
   if (result.isSuccess) {
     try {
-      await runLifecycle(ctx, type, result.data, handlerContext, user, afterCommitHooks);
+      const runner = resolveDbSource(ctx, tx);
+      await runLifecycle(ctx, type, result.data, handlerContext, user, afterCommitHooks, runner);
     } catch (e) {
       return writeFailure(wrapToKumiko(e));
     }

package/src/pipeline/dispatcher.ts

@@ -1,5 +1,9 @@
 import type { SseBroker } from "../api/sse-broker";
 import type { buildEntityTable } from "../db/table-builder";
+import {
+  DEPRECATED_CROSS_TENANT_SIGNAL,
+  isDeprecatedCrossTenantHandler,
+} from "../engine/entity-handlers";
 import { TENANT_MEMBERSHIPS_QUERY } from "../engine/extension-names";
 import type { defineTransitions } from "../engine/state-machine";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension";
@@ -23,6 +27,7 @@ import type { BatchCommand, BatchResult, DispatchContext } from "./dispatch-shar
 import { resolveAuthClaimsFn } from "./dispatch-shared";
 import { executeStream } from "./dispatch-stream";
 import { type HandlerType, resolveType } from "./dispatcher-utils";
+import { createEscapeHatchReportWindow } from "./escape-hatch-report";
 import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
 import { createMemberReaderFn } from "./member-reader";
@@ -129,6 +134,7 @@ export function createDispatcher(
   // One per dispatcher instance (not a module-level singleton) so caches
   // never leak across separately-booted apps or test stacks.
   const tenantTimezoneCache = createTenantTimezoneCache();
+  const escapeHatchReportWindow = createEscapeHatchReportWindow();
 
   const dispatcherTracer = context.tracer ?? getFallbackTracer();
   const dispatcherMeter = context.meter ?? getFallbackMeter();
@@ -136,6 +142,19 @@ export function createDispatcher(
   // Idempotent: buildServer may have registered them already.
   registerStandardMetrics(dispatcherMeter);
 
+  for (const def of [
+    ...registry.getAllWriteHandlers().values(),
+    ...registry.getAllQueryHandlers().values(),
+  ]) {
+    if (isDeprecatedCrossTenantHandler(def.handler)) {
+      context.log?.warn(DEPRECATED_CROSS_TENANT_SIGNAL, {
+        handler: def.name,
+        migration:
+          'replace crossTenant: true with escapeHatch: { reason: "<why this operator handler reads/writes every tenant>" } (bun scripts/codemod/migrate-cross-tenant.ts)',
+      });
+    }
+  }
+
   const ctx: DispatchContext = {
     registry,
     appContext: context,
@@ -147,6 +166,7 @@ export function createDispatcher(
     tableCache,
     transitionCache,
     tenantTimezoneCache,
+    escapeHatchReportWindow,
     tracer: dispatcherTracer,
     meter: dispatcherMeter,
     membershipQuery,

package/src/pipeline/escape-hatch-report.ts

@@ -0,0 +1,127 @@
+import type {
+  EscapeHatchAuditSink,
+  EscapeHatchKind,
+  EscapeHatchReporter,
+  EscapeHatchTarget,
+  EscapeHatchUseEvent,
+  TenantId,
+} from "../engine/types";
+import type { Logger } from "../logging/types";
+
+export const ESCAPE_HATCH_USED_SIGNAL = "security:escape-hatch-used";
+
+const DEFAULT_WINDOW_MS = 60_000;
+const DEFAULT_MAX_ENTRIES = 1_000;
+
+export type EscapeHatchReportWindow = {
+  shouldReport(key: string, nowMs: number): boolean;
+};
+
+// Dedups identical (handler,kind,reason,tenant,actor,target) reports within the window so hot systemScope queries don't write one row per request.
+export function createEscapeHatchReportWindow(opts?: {
+  readonly windowMs?: number;
+  readonly maxEntries?: number;
+}): EscapeHatchReportWindow {
+  const windowMs = opts?.windowMs ?? DEFAULT_WINDOW_MS;
+  const maxEntries = opts?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  // Map insertion order doubles as recency order: a re-set moves the key to the end.
+  const entries = new Map<string, number>();
+
+  return {
+    shouldReport(key, nowMs) {
+      const expiresAt = entries.get(key);
+      if (expiresAt !== undefined && expiresAt > nowMs) return false;
+      entries.delete(key);
+      entries.set(key, nowMs + windowMs);
+      while (entries.size > maxEntries) {
+        const oldestKey = entries.keys().next().value;
+        if (oldestKey === undefined) break;
+        entries.delete(oldestKey);
+      }
+      return true;
+    },
+  };
+}
+
+// Default window for createEscapeHatchReporter callers that don't pass their own.
+const fallbackReportWindow = createEscapeHatchReportWindow();
+
+const consoleLogger: Logger = {
+  info() {},
+  warn(msg, data) {
+    console.warn(msg, data);
+  },
+  error(msg, data) {
+    console.error(msg, data);
+  },
+  debug() {},
+  child() {
+    return consoleLogger;
+  },
+};
+
+function eventFields(event: EscapeHatchUseEvent): Record<string, unknown> {
+  return {
+    handler: event.handler,
+    kind: event.kind,
+    reason: event.reason,
+    tenantId: event.tenantId,
+    actor: event.actor,
+    ...(event.target && { targetId: event.target.id, targetTenantId: event.target.tenantId }),
+  };
+}
+
+export function reportEscapeHatchUse(
+  event: EscapeHatchUseEvent,
+  deps: { readonly sink?: EscapeHatchAuditSink; readonly log?: Logger },
+): void {
+  const logger = deps.log ?? consoleLogger;
+  const fields = eventFields(event);
+  if (deps.sink) {
+    void deps.sink(event).catch((err: unknown) => {
+      logger.error(`${ESCAPE_HATCH_USED_SIGNAL}: audit sink failed`, {
+        ...fields,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    });
+    return;
+  }
+  logger.warn(ESCAPE_HATCH_USED_SIGNAL, fields);
+}
+
+export function createEscapeHatchReporter(opts: {
+  readonly handler: string;
+  readonly tenantId: TenantId;
+  readonly actor: string;
+  readonly sink?: EscapeHatchAuditSink;
+  readonly log?: Logger;
+  readonly window?: EscapeHatchReportWindow;
+}): EscapeHatchReporter {
+  const window = opts.window ?? fallbackReportWindow;
+
+  return (kind: EscapeHatchKind, reason: string, target?: EscapeHatchTarget) => {
+    const key = JSON.stringify([
+      opts.handler,
+      kind,
+      reason,
+      opts.tenantId,
+      opts.actor,
+      target?.id ?? null,
+      target?.tenantId ?? null,
+    ]);
+    // skip: same (handler, kind, reason, target) already reported within the window — dedup
+    if (!window.shouldReport(key, Date.now())) return;
+    reportEscapeHatchUse(
+      { handler: opts.handler, kind, reason, tenantId: opts.tenantId, actor: opts.actor, target },
+      { sink: opts.sink, log: opts.log },
+    );
+  };
+}
+
+export function fallbackEscapeHatchReporter(tenantId: TenantId): EscapeHatchReporter {
+  return createEscapeHatchReporter({
+    handler: "<unattributed>",
+    tenantId,
+    actor: "<unattributed>",
+  });
+}