@cosmicdrift/kumiko-framework 0.270.0 → 0.274.0

package/src/engine/entity-handlers.ts

@@ -8,7 +8,8 @@ import {
 } from "../db/eagerload";
 import { createEventStoreExecutor, type EventStoreExecutor } from "../db/event-store-executor";
 import { buildEntityTable, type EntityTable } from "../db/table-builder";
-import { createTenantDb, type TenantDb } from "../db/tenant-db";
+import { acknowledgeConventionCrossTenant, type TenantDb } from "../db/tenant-db";
+import { isSystemIdentity } from "../pipeline/system-identity-switch";
 import { assertUnreachable } from "../utils";
 import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
@@ -16,6 +17,7 @@ import type {
   AccessRule,
   DeriveContext,
   EntityDefinition,
+  EscapeHatchDeclaration,
   HandlerContext,
   QueryHandlerDef,
   SessionUser,
@@ -100,13 +102,40 @@ type ListPayload = {
   // den gleichen Query-Handler.
   filter?: {
     readonly field: string;
-    readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+    readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
     readonly value: unknown;
   };
 };
 
 const idSchema = z.object({ id: z.uuid() });
 
+// Keyed by handler function: the registrar rebuilds the def object but keeps the function reference.
+const deprecatedCrossTenantHandlers = new WeakSet<object>();
+
+export function isDeprecatedCrossTenantHandler(handler: object): boolean {
+  return deprecatedCrossTenantHandlers.has(handler);
+}
+
+export const DEPRECATED_CROSS_TENANT_SIGNAL = "deprecation:entity-handler-cross-tenant";
+
+function resolveCrossTenantReason(name: string, options: EntityHandlerOptions): string | undefined {
+  if (options.escapeHatch !== undefined && options.crossTenant === true) {
+    throw new Error(
+      `"${name}": declare either escapeHatch or the deprecated crossTenant, not both.`,
+    );
+  }
+  if (options.escapeHatch !== undefined) {
+    if (options.escapeHatch.reason.trim().length === 0) {
+      throw new Error(`"${name}": escapeHatch requires a non-empty reason.`);
+    }
+    return options.escapeHatch.reason;
+  }
+  if (options.crossTenant === true) {
+    return `deprecated crossTenant: true on entity convention handler ${name}`;
+  }
+  return undefined;
+}
+
 // Upper bound on entity-list `limit`: unbounded/fractional values ran
 // straight into the raw `LIMIT ${limit}` SQL string (event-store-executor-
 // read.ts), letting a client demand a full-table materialisation or trip a
@@ -128,7 +157,7 @@ export const entityListSchema = z.object({
   filter: z
     .object({
       field: z.string(),
-      op: z.enum(["eq", "ne", "lt", "gt", "in"]),
+      op: z.enum(["eq", "ne", "lt", "gt", "lte", "gte", "in"]),
       // Value ist `unknown` zur Compile-Zeit; Server-Side prüft beim
       // Build der WHERE-Clause ob der Type zum Field passt. z.unknown()
       // lässt alles durch; Type-Check kommt im executor.list.
@@ -141,7 +170,7 @@ export const entityListSchema = z.object({
     .array(
       z.object({
         field: z.string(),
-        op: z.enum(["eq", "ne", "lt", "gt", "in"]),
+        op: z.enum(["eq", "ne", "lt", "gt", "lte", "gte", "in"]),
         value: z.unknown(),
       }),
     )
@@ -194,10 +223,10 @@ export function defineEntityWriteHandler(
   // behavior-preserving: ctx.db was already an unfiltered "system"-mode
   // TenantDb for these handlers before the ctx.db cutover.
   //
-  // options.crossTenant mirrors the query-handler branch below: this ONE
-  // write handler reads/writes across every tenant without making the
-  // whole feature r.systemScope().
-  const crossTenant = options?.crossTenant === true;
+  // crossTenantReason (escapeHatch or the deprecated crossTenant) mirrors the
+  // query-handler branch below: this ONE write handler reads/writes across
+  // every tenant without making the whole feature r.systemScope().
+  const crossTenantReason = resolveCrossTenantReason(name, options);
 
   const dbFor = (ctx: HandlerContext): TenantDb => {
     if (ctx.systemDb) {
@@ -205,7 +234,9 @@ export function defineEntityWriteHandler(
         `entity convention handler for r.systemScope() feature (${name})`,
       );
     }
-    return crossTenant ? createTenantDb(ctx.db.raw, ctx.db.tenantId, "system") : ctx.db;
+    return crossTenantReason !== undefined
+      ? acknowledgeConventionCrossTenant(ctx.db, crossTenantReason)
+      : ctx.db;
   };
 
   // The event stream is keyed by the acting user's tenantId (streamTenantFor in
@@ -219,7 +250,7 @@ export function defineEntityWriteHandler(
     id: unknown,
     db: TenantDb,
   ): Promise<SessionUser> => {
-    if (!crossTenant || entity.systemStream) return user;
+    if (crossTenantReason === undefined || entity.systemStream) return user;
     const row = await db.fetchOne<Record<string, unknown>>(table, { id });
     const rowTenantId = row?.["tenantId"];
     if (typeof rowTenantId !== "string" || rowTenantId === user.tenantId) return user;
@@ -234,7 +265,14 @@ export function defineEntityWriteHandler(
       schema = buildInsertSchema(entity);
       handler = async (event, ctx) => {
         const { runPreSave } = ctx;
-        return executor.create(event.payload as DbRow, event.user, dbFor(ctx), {
+        // A caller-chosen id (deterministic-id idempotent creates) is only
+        // honored for a system-identity caller (jobs/hooks via
+        // createSystemUser) — an HTTP-authenticated end user can never
+        // present that identity, so their payload.id is dropped exactly as
+        // before this field became part of the schema.
+        const { id: _callerId, ...payloadWithoutId } = event.payload as DbRow;
+        const payload = isSystemIdentity(event.user) ? (event.payload as DbRow) : payloadWithoutId;
+        return executor.create(payload, event.user, dbFor(ctx), {
           preSave:
             runPreSave &&
             ((changes, previous, isNew) => runPreSave(event.type, changes, previous, isNew)),
@@ -288,6 +326,9 @@ export function defineEntityWriteHandler(
       assertUnreachable(verb, "write verb");
   }
 
+  if (options.crossTenant === true) deprecatedCrossTenantHandlers.add(handler);
+
+  // escapeHatch stays off the def: WriteHandlerDef.escapeHatch also grants unsafeRaw, global writes, identity switches.
   return {
     name,
     schema,
@@ -340,21 +381,22 @@ export function defineEntityQueryHandler(
   // useReferenceLookup stays as a fallback (for apps that write custom
   // handlers by hand without this wrapper).
   const hasRefFields = collectReferenceFields(entity).length > 0;
+  const crossTenantReason = resolveCrossTenantReason(name, options);
 
   // Preference order:
   //  1. ctx.systemDb — the feature declared r.systemScope() (whole-feature
   //     cutover, dispatch-shared.ts), so ctx.db is fail-closed. This is
   //     behavior-preserving: ctx.db was already an unfiltered "system"-mode
   //     TenantDb for these handlers before that cutover.
-  //  2. options.crossTenant — this ONE handler reads across every tenant
-  //     (e.g. a SystemAdmin-only operator inspector) without making the
-  //     whole feature r.systemScope() — that would drop tenant isolation
-  //     from every OTHER handler the feature registers too. The executor's
-  //     list()/detail() only add a tenant filter when db.mode === "tenant"
-  //     (see event-store-executor.ts), so handing them a "system"-mode
-  //     TenantDb built from the same raw connection is enough to skip it —
-  //     access-control (who may call this handler at all) is unaffected,
-  //     still gated by `options.access`.
+  //  2. crossTenantReason (escapeHatch or the deprecated crossTenant) — this
+  //     ONE handler reads across every tenant (e.g. a SystemAdmin-only
+  //     operator inspector) without making the whole feature r.systemScope()
+  //     — that would drop tenant isolation from every OTHER handler the
+  //     feature registers too. The executor's list()/detail() only add a
+  //     tenant filter when db.mode === "tenant" (see event-store-executor.ts),
+  //     so handing them a "system"-mode TenantDb built from the same raw
+  //     connection is enough to skip it — access-control (who may call this
+  //     handler at all) is unaffected, still gated by `options.access`.
   //  3. plain ctx.db — the common case, tenant-filtered.
   const dbFor = (ctx: HandlerContext): TenantDb => {
     if (ctx.systemDb) {
@@ -362,7 +404,9 @@ export function defineEntityQueryHandler(
         `entity convention handler for r.systemScope() feature (${entityName}:${verb})`,
       );
     }
-    return options?.crossTenant ? createTenantDb(ctx.db.raw, ctx.db.tenantId, "system") : ctx.db;
+    return crossTenantReason !== undefined
+      ? acknowledgeConventionCrossTenant(ctx.db, crossTenantReason)
+      : ctx.db;
   };
 
   switch (verb) {
@@ -418,6 +462,9 @@ export function defineEntityQueryHandler(
       assertUnreachable(verb, "query verb");
   }
 
+  if (options.crossTenant === true) deprecatedCrossTenantHandlers.add(handler);
+
+  // escapeHatch stays off the def: QueryHandlerDef.escapeHatch also grants unsafeRaw and identity switches.
   return {
     name,
     schema,
@@ -543,7 +590,11 @@ export function createEntityExecutor(
 export function defineProjectionQueryHandler(
   name: string,
   projectionQualifiedName: string,
-  options: { access: AccessRule; unsafeAllTenants?: boolean },
+  options: {
+    access: AccessRule;
+    unsafeAllTenants?: boolean;
+    escapeHatch?: EscapeHatchDeclaration;
+  },
 ): QueryHandlerDef {
   return {
     name,
@@ -558,6 +609,7 @@ export function defineProjectionQueryHandler(
         options.unsafeAllTenants ? { unsafeAllTenants: true } : undefined,
       ), // @wrapper-known semantic-alias
     access: options.access,
+    ...(options.escapeHatch && { escapeHatch: options.escapeHatch }),
   };
 }
 

package/src/engine/feature-entity-handlers.ts

@@ -23,7 +23,7 @@ import type {
   HandlerRef,
   NameOrRef,
   QueryHandlerFn,
-  RateLimitOption,
+  RateLimitDeclaration,
   RelationDefinition,
   StreamHandlerFn,
   WriteHandlerFn,
@@ -124,7 +124,7 @@ export function buildEntityHandlerMethods<TName extends string>(
       handler?: WriteHandlerFn<z.infer<TSchema>>,
       options?: {
         access: AccessRule;
-        rateLimit?: RateLimitOption;
+        rateLimit?: RateLimitDeclaration;
         description?: string;
         agent?: AgentHandlerHints;
         escapeHatch?: EscapeHatchDeclaration;
@@ -181,7 +181,7 @@ export function buildEntityHandlerMethods<TName extends string>(
       handler?: QueryHandlerFn<z.infer<TSchema>>,
       options?: {
         access: AccessRule;
-        rateLimit?: RateLimitOption;
+        rateLimit?: RateLimitDeclaration;
         outputSchema?: ZodType;
         description?: string;
         agent?: AgentHandlerHints;
@@ -230,7 +230,7 @@ export function buildEntityHandlerMethods<TName extends string>(
       handler?: StreamHandlerFn<z.infer<TSchema>>,
       options?: {
         access: AccessRule;
-        rateLimit?: RateLimitOption;
+        rateLimit?: RateLimitDeclaration;
         escapeHatch?: EscapeHatchDeclaration;
       },
     ): HandlerRef {

package/src/engine/index.ts

@@ -374,7 +374,12 @@ export type {
   EntityListScreenDefinition,
   EntityRef,
   EntityRelations,
+  EscapeHatchAuditSink,
   EscapeHatchDeclaration,
+  EscapeHatchKind,
+  EscapeHatchReporter,
+  EscapeHatchTarget,
+  EscapeHatchUseEvent,
   EventDef,
   FeatureDefinition,
   FeatureRegistrar,

package/src/engine/registry-validate.ts

@@ -1,4 +1,5 @@
 import { configureEventPiiCatalog } from "../crypto/event-pii";
+import { hasSearchablePlaintext, isSensitiveLabelField } from "../db/entity-field-encryption";
 import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch";
 import { resolveName } from "./handler-helpers";
 import type {
@@ -16,6 +17,7 @@ import {
   softDeleteGraceDaysConfig,
 } from "./soft-delete-cleanup";
 import type {
+  EntityDefinition,
   EventPiiFields,
   EventUpcastFn,
   FeatureDefinition,
@@ -25,7 +27,7 @@ import type {
   PreSaveHookFn,
   ReferenceFieldDef,
 } from "./types";
-import { HookPhases } from "./types";
+import { HookPhases, isRateLimitDisabled } from "./types";
 
 function allHandlerQns(state: RegistryState): ReadonlySet<string> {
   return new Set([...state.writeHandlerMap.keys(), ...state.queryHandlerMap.keys()]);
@@ -206,6 +208,7 @@ function buildSearchableReferenceField(
   entityName: string,
   fieldName: string,
   field: ReferenceFieldDef,
+  entityMap: ReadonlyMap<string, EntityDefinition>,
 ): SearchableReferenceField {
   if (field.labelField === undefined || field.labelField === "id") {
     throw new Error(
@@ -220,9 +223,26 @@ function buildSearchableReferenceField(
         `(array) reference fields — remove "multiple" or "searchable".`,
     );
   }
+  const targetEntityName = parseReferenceTargetEntityName(field.entity);
+  const targetEntity = entityMap.get(targetEntityName);
+  if (targetEntity !== undefined) {
+    if (
+      isSensitiveLabelField(targetEntity, field.labelField) &&
+      !hasSearchablePlaintext(targetEntity, field.labelField)
+    ) {
+      throw new Error(
+        `[Entity ${entityName}] field "${fieldName}": searchable reference targets ` +
+          `"${targetEntityName}.${field.labelField}", which is encrypted/PII and not itself ` +
+          `searchable — there is no plaintext anywhere to match a search term against. Mark ` +
+          `"${targetEntityName}.${field.labelField}" searchable: true (add find: "fuzzy" if it ` +
+          `also carries a personal annotation, so it lands in the derived search index) or ` +
+          `remove searchable from "${fieldName}".`,
+      );
+    }
+  }
   return {
     fieldName,
-    targetEntityName: parseReferenceTargetEntityName(field.entity),
+    targetEntityName,
     labelField: field.labelField,
   };
 }
@@ -273,7 +293,9 @@ export function buildSearchableSortableCaches(state: RegistryState): void {
         }
       }
       if (field.type === "reference" && field.searchable === true) {
-        searchableReferences.push(buildSearchableReferenceField(name, fieldName, field));
+        searchableReferences.push(
+          buildSearchableReferenceField(name, fieldName, field, state.entityMap),
+        );
       }
       if (field.type === "reference" && field.sortable === true) {
         sortableReferences.push(buildSortableReferenceField(name, fieldName, field));
@@ -721,10 +743,18 @@ export function validateExtensionUsageTargets(state: RegistryState): void {
 export function computeHasRateLimitedHandler(state: RegistryState): void {
   // Pre-compute: any handler with a rateLimit option? Keeps the boot
   // path able to short-circuit the RateLimitResolver wiring (and its
-  // Lua-script registration on Redis) when nobody opted in.
+  // Lua-script registration on Redis) when nobody opted in. Deliberately
+  // stays limited to explicit, non-disabled `rateLimit` declarations —
+  // `{ disabled: true }` must not auto-wire a resolver for an app that only
+  // opted OUT, and fw#2861's systemScope default only fires once a resolver
+  // already exists, so it must not force wantsL3 either.
   state.hasRateLimitedHandlerCached = (() => {
-    for (const h of state.writeHandlerMap.values()) if (h.rateLimit !== undefined) return true;
-    for (const h of state.queryHandlerMap.values()) if (h.rateLimit !== undefined) return true;
+    for (const h of state.writeHandlerMap.values()) {
+      if (h.rateLimit !== undefined && !isRateLimitDisabled(h.rateLimit)) return true;
+    }
+    for (const h of state.queryHandlerMap.values()) {
+      if (h.rateLimit !== undefined && !isRateLimitDisabled(h.rateLimit)) return true;
+    }
     return false;
   })();
 }

package/src/engine/schema-builder.ts

@@ -380,6 +380,12 @@ export function buildInsertSchema(
     shape[name] = isRequired || hasDefault ? zodField : zodField.optional();
   }
 
+  // Caller-chosen aggregate id for idempotent creates (deterministic-id
+  // patterns). Accepting it here only lets it survive parsing — the create
+  // handler still honors it only for a system-identity caller (jobs/hooks
+  // via createSystemUser), never for an ordinary HTTP-authenticated user.
+  shape["id"] = z.uuid().optional();
+
   return applyTotalsMatchRefinements(entity, z.object(shape));
 }
 

package/src/engine/screen-filter-ops.ts

@@ -6,7 +6,7 @@
 //     compare nutzt der Author selten bewusst); Author kann den
 //     Filter dann einfach nicht setzen.
 //   - boolean: eq, ne (in/lt/gt sinnlos für 2-Werte-Type).
-//   - number/money/decimal/date/timestamp/locatedTimestamp: alle 5
+//   - number/money/decimal/date/timestamp/locatedTimestamp: alle 7
 //     Ops — die Felder sind natürlich vergleichbar.
 //
 // Boot-Validator nutzt diese Map um Author-Fehler früh zu fangen
@@ -17,7 +17,15 @@
 import type { FieldDefinition, ScreenFilterOp } from "./types";
 
 const EQUALITY_ONLY = ["eq", "ne", "in"] as const satisfies readonly ScreenFilterOp[];
-const COMPARABLE = ["eq", "ne", "lt", "gt", "in"] as const satisfies readonly ScreenFilterOp[];
+const COMPARABLE = [
+  "eq",
+  "ne",
+  "lt",
+  "gt",
+  "lte",
+  "gte",
+  "in",
+] as const satisfies readonly ScreenFilterOp[];
 const BOOL_OPS = ["eq", "ne"] as const satisfies readonly ScreenFilterOp[];
 
 export function getAllowedFilterOps(field: FieldDefinition): readonly ScreenFilterOp[] {

package/src/engine/screen-helpers.ts

@@ -11,10 +11,62 @@ import type {
   FormatSpec,
   ListColumnSpec,
   ProjectionDetailScreenDefinition,
+  RowAction,
   ScreenDefinition,
   SecretMintScreenDefinition,
+  ToolbarAction,
 } from "./types/screen";
 
+// Every screen type carrying `listScreenId` declares it identically; centralizing
+// here keeps the switch the only place that grows for a new screen type.
+export function explicitListScreenId(screen: ScreenDefinition): string | undefined {
+  switch (screen.type) {
+    case "custom":
+    case "projectionDetail":
+    case "entityEdit":
+    case "actionForm":
+    case "secretMint":
+      return screen.listScreenId;
+    default:
+      return undefined;
+  }
+}
+
+// Shared by the renderer breadcrumb and the boot-validator so both resolve
+// parents the same way; `getId` lets each caller normalize `screen.id`.
+export function resolveNavParentScreen(
+  screens: readonly ScreenDefinition[],
+  detail: ScreenDefinition,
+  getId: (screen: ScreenDefinition) => string,
+): ScreenDefinition | undefined {
+  const detailScreenId = getId(detail);
+
+  const listFromExplicit = ((): ScreenDefinition | undefined => {
+    const explicitId = explicitListScreenId(detail);
+    return explicitId !== undefined ? screens.find((s) => getId(s) === explicitId) : undefined;
+  })();
+
+  // rowActions, toolbarActions, and drawer-kind actions (which mount inline
+  // and have no page of their own) all count as "reached from" this list.
+  const navigatesToDetail = (
+    actions: readonly (RowAction | ToolbarAction)[] | undefined,
+  ): boolean =>
+    (actions ?? []).some(
+      (a) => (a.kind === "navigate" || a.kind === "drawer") && a.screen === detailScreenId,
+    );
+  const listFromRowAction = screens.find((s) => {
+    if (s.type !== "entityList" && s.type !== "projectionList") return false;
+    return navigatesToDetail(s.rowActions) || navigatesToDetail(s.toolbarActions);
+  });
+
+  const listFromEntity =
+    detail.type === "entityEdit"
+      ? screens.find((s) => s.type === "entityList" && s.entity === detail.entity)
+      : undefined;
+
+  return listFromExplicit ?? listFromRowAction ?? listFromEntity;
+}
+
 export type EditLayoutScreen =
   | ProjectionDetailScreenDefinition
   | EntityEditScreenDefinition

package/src/engine/steps/_read-source.ts

@@ -0,0 +1,12 @@
+import type { DbRunner } from "../../db/connection";
+import { type TenantDb, unsafeRawForDeclaredStep } from "../../db/tenant-db";
+import type { PipelineCtx } from "../types/step";
+
+// unsafeRaw fails closed without the handler's escapeHatch (or systemScope) and reports the use.
+export function readSourceFor(
+  ctx: PipelineCtx,
+  unsafeAllTenants: { readonly reason: string } | undefined,
+): TenantDb | DbRunner {
+  if (!unsafeAllTenants) return ctx.db;
+  return unsafeRawForDeclaredStep(ctx.systemDb ?? ctx.db, unsafeAllTenants.reason);
+}

package/src/engine/steps/read-find-many.ts

@@ -1,6 +1,8 @@
 // r.step.read.findMany — load multiple rows from a projection table.
 //
-// Sibling to read.findOne — same tenant-filter caveat (caller-owned).
+// Sibling to read.findOne — same tenant-filtering: own tenant +
+// SYSTEM_TENANT_ID reference rows by default, `unsafeAllTenants: { reason }`
+// plus `escapeHatch: { reason }` on the handler to read across tenants.
 // Resolves to a row-array (possibly empty), landed under steps.<name>.
 //
 // Optional `limit` — defaults to no-limit (caller-chosen, NOT a
@@ -11,6 +13,7 @@
 import { selectMany, type WhereObject } from "../../db/query";
 import { defineStep } from "../define-step";
 import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { readSourceFor } from "./_read-source";
 import { resolveOptional } from "./_resolver-utils";
 
 type ReadFindManyArgs = {
@@ -18,6 +21,7 @@ type ReadFindManyArgs = {
   readonly table: unknown;
   readonly where?: StepResolver<WhereObject | undefined>;
   readonly limit?: number;
+  readonly unsafeAllTenants?: { readonly reason: string };
 };
 
 defineStep<ReadFindManyArgs, readonly Record<string, unknown>[]>({
@@ -26,8 +30,9 @@ defineStep<ReadFindManyArgs, readonly Record<string, unknown>[]>({
   resultKey: (args) => args.name,
   run: async (args, ctx: PipelineCtx) => {
     const where = resolveOptional(args.where, ctx);
+    const source = readSourceFor(ctx, args.unsafeAllTenants);
     const rows = await selectMany(
-      ctx.db.raw,
+      source,
       args.table,
       where,
       args.limit !== undefined ? { limit: args.limit } : undefined,
@@ -42,6 +47,7 @@ export function buildReadFindManyStep(
     readonly table: unknown;
     readonly where?: StepResolver<WhereObject | undefined>;
     readonly limit?: number;
+    readonly unsafeAllTenants?: { readonly reason: string };
   },
 ): StepInstance {
   return {

package/src/engine/steps/read-find-one.ts

@@ -1,13 +1,12 @@
 // r.step.read.findOne — load a single row from a projection table.
 //
 // Thin wrapper on selectMany(db, table, where, { limit: 1 }) (bun-db).
-// Resolves to the first row or null. Tenant-isolation: the caller's
-// `where` clause is responsible for any tenantId filter — read.findOne
-// does NOT auto-inject one (different from ctx.queryProjection which
-// does). That's deliberate: most read-step uses are aggregate-lookups
-// where the where-clause already pins a uuid that's globally unique;
-// auto-tenant-filtering would be redundant and would surprise users
-// who pass an explicit tenantId.
+// Resolves to the first row or null. Tenant-filtered like ctx.db
+// method-form reads (own tenant + SYSTEM_TENANT_ID reference rows); a
+// foreign `where.tenantId` is narrowed to the caller's own scope.
+// Cross-tenant reads require `unsafeAllTenants: { reason }` here AND
+// `escapeHatch: { reason }` on the handler — reported as an "unsafe-raw"
+// escape-hatch audit event.
 //
 // Use when a subsequent step needs a row from the read-side. For
 // cross-feature reads, prefer `r.step.callFeature(...)` (M.2) so the
@@ -23,12 +22,14 @@
 import { selectMany, type WhereObject } from "../../db/query";
 import { defineStep } from "../define-step";
 import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import { readSourceFor } from "./_read-source";
 import { resolveRequired } from "./_resolver-utils";
 
 type ReadFindOneArgs = {
   readonly name: string;
   readonly table: unknown;
   readonly where: StepResolver<WhereObject | undefined>;
+  readonly unsafeAllTenants?: { readonly reason: string };
 };
 
 defineStep<ReadFindOneArgs, Record<string, unknown> | null>({
@@ -37,7 +38,8 @@ defineStep<ReadFindOneArgs, Record<string, unknown> | null>({
   resultKey: (args) => args.name,
   run: async (args, ctx: PipelineCtx) => {
     const where = resolveRequired(args.where, ctx);
-    const rows = await selectMany(ctx.db.raw, args.table, where, { limit: 1 });
+    const source = readSourceFor(ctx, args.unsafeAllTenants);
+    const rows = await selectMany(source, args.table, where, { limit: 1 });
     return (rows[0] as Record<string, unknown> | undefined) ?? null;
   },
 });
@@ -47,6 +49,7 @@ export function buildReadFindOneStep(
   opts: {
     readonly table: unknown;
     readonly where: StepResolver<WhereObject | undefined>;
+    readonly unsafeAllTenants?: { readonly reason: string };
   },
 ): StepInstance {
   return {

package/src/engine/steps/unsafe-projection-delete.ts

@@ -18,6 +18,7 @@
 
 import type { EntityTableMeta } from "../../db/entity-table-meta";
 import { deleteMany, type WhereObject } from "../../db/query";
+import { tenantDbRunner } from "../../db/tenant-db-runner";
 import { defineStep } from "../define-step";
 import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
 import { resolveRequired } from "./_resolver-utils";
@@ -40,7 +41,7 @@ defineStep<UnsafeProjectionDeleteArgs, void>({
     // The `unsafe*`-step IS the sanctioned direct projection write — it exists
     // to bypass the executor deliberately (boot-validated allowlist + reviewer
     // gate). The brand-strip cast makes that explicit at the one blessed seam.
-    await deleteMany(ctx.db.raw, args.table as EntityTableMeta, where);
+    await deleteMany(tenantDbRunner(ctx.db), args.table as EntityTableMeta, where);
   },
 });
 

package/src/engine/steps/unsafe-projection-upsert.ts

@@ -14,6 +14,7 @@
 import { KUMIKO_COLUMNS_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { extractTableName } from "../../db";
 import { executeRawQuery } from "../../db/queries/raw-sql";
+import { tenantDbRunner } from "../../db/tenant-db-runner";
 import { defineStep } from "../define-step";
 import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
 import { resolveRequired } from "./_resolver-utils";
@@ -78,7 +79,7 @@ defineStep<UnsafeProjectionUpsertArgs, void>({
       `INSERT INTO ${quoteIdent(tableName)} (${colNames.join(", ")}) VALUES (${placeholders.join(", ")}) ` +
       `ON CONFLICT (${conflictCols}) DO UPDATE SET ${setClauses.join(", ")}`;
 
-    await executeRawQuery(ctx.db.raw, sqlText, params);
+    await executeRawQuery(tenantDbRunner(ctx.db), sqlText, params);
   },
 });
 

package/src/engine/types/index.ts

@@ -159,7 +159,12 @@ export type {
   DeclarativeEventMigration,
   DispatchWriteRef,
   EntityRef,
+  EscapeHatchAuditSink,
   EscapeHatchDeclaration,
+  EscapeHatchKind,
+  EscapeHatchReporter,
+  EscapeHatchTarget,
+  EscapeHatchUseEvent,
   EventDef,
   EventMigrationDef,
   EventPiiFields,
@@ -184,6 +189,8 @@ export type {
   QueryEvent,
   QueryHandlerDef,
   QueryHandlerFn,
+  RateLimitDeclaration,
+  RateLimitDisabled,
   RateLimitOption,
   RateLimitPer,
   SessionUser,
@@ -198,7 +205,7 @@ export type {
   WriteHandlerFn,
   WriteResult,
 } from "@cosmicdrift/kumiko-types/handlers";
-export { isOpenToAllGranted } from "@cosmicdrift/kumiko-types/handlers";
+export { isOpenToAllGranted, isRateLimitDisabled } from "@cosmicdrift/kumiko-types/handlers";
 export type {
   DeleteContext,
   EntityHookMap,

package/src/errors/i18n/de.yaml

@@ -113,6 +113,20 @@ identity_switch_denied:
     (oder am `r.hook(...)`-Aufruf, wenn der Wechsel in einem Hook passiert),
     oder verlagere die Logik in ein `r.systemScope()`-Feature oder einen Job.
 
+unsafe_all_tenants_denied:
+  endUser: |
+    Diese Aktion ist nicht erlaubt.
+    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
+  developer: |
+    `AccessDeniedError`: ein Handler oder Hook hat
+    `ctx.queryProjection(qualifiedName, { unsafeAllTenants: true })`
+    aufgerufen, ohne `r.systemScope()`-Handler zu sein oder
+    `escapeHatch: { reason }` zu deklarieren.
+
+    Deklariere `escapeHatch: { reason: "..." }` am Write-, Query- oder
+    Stream-Handler (oder am `r.hook(...)`-Aufruf, wenn der Read in einem Hook
+    passiert), oder verlagere die Logik in ein `r.systemScope()`-Feature.
+
 member_resolution_denied:
   endUser: |
     Diese Aktion ist nicht erlaubt.