@cosmicdrift/kumiko-framework 0.269.2 → 0.273.0

package/src/engine/feature-ast/patcher.ts

@@ -31,7 +31,12 @@ import type {
 } from "../types/config";
 import type { MetricOptions, SecretOptions } from "../types/feature";
 import type { EntityDefinition } from "../types/fields";
-import type { AccessRule, ClaimKeyType, RateLimitOption } from "../types/handlers";
+import type {
+  AccessRule,
+  ClaimKeyType,
+  EscapeHatchDeclaration,
+  RateLimitOption,
+} from "../types/handlers";
 import type { HookPhase } from "../types/hooks";
 import type { HttpRouteMethod } from "../types/http-route";
 import type { NavDefinition } from "../types/nav";
@@ -94,6 +99,7 @@ export type AddWriteHandlerArgs = {
   readonly access?: AccessRule;
   readonly rateLimit?: RateLimitOption;
   readonly unsafeSkipTransitionGuard?: boolean;
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };
 
 export type AddQueryHandlerArgs = {
@@ -102,6 +108,7 @@ export type AddQueryHandlerArgs = {
   readonly handlerSource: string;
   readonly access?: AccessRule;
   readonly rateLimit?: RateLimitOption;
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };
 
 export type AddStreamHandlerArgs = {
@@ -121,6 +128,7 @@ export type AddHookArgs = {
   /** Source text of the closure, e.g. `"async (event, ctx) => { ... }"`. */
   readonly handlerSource: string;
   readonly phase?: HookPhase;
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };
 
 export type AddJobArgs = {
@@ -380,6 +388,7 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
       access,
       rateLimit,
       unsafeSkipTransitionGuard,
+      escapeHatch,
     }) {
       add({
         kind: "writeHandler",
@@ -390,10 +399,11 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
         ...(access !== undefined && { access }),
         ...(rateLimit !== undefined && { rateLimit }),
         ...(unsafeSkipTransitionGuard === true && { unsafeSkipTransitionGuard: true }),
+        ...(escapeHatch !== undefined && { escapeHatch }),
       });
     },
 
-    addQueryHandler({ name, schemaSource, handlerSource, access, rateLimit }) {
+    addQueryHandler({ name, schemaSource, handlerSource, access, rateLimit, escapeHatch }) {
       add({
         kind: "queryHandler",
         source: SYNTHETIC_LOC,
@@ -402,6 +412,7 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
         handlerBody: rawLoc(handlerSource),
         ...(access !== undefined && { access }),
         ...(rateLimit !== undefined && { rateLimit }),
+        ...(escapeHatch !== undefined && { escapeHatch }),
       });
     },
 
@@ -417,7 +428,7 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
       });
     },
 
-    addHook({ type, target, handlerSource, phase }) {
+    addHook({ type, target, handlerSource, phase, escapeHatch }) {
       add({
         kind: "hook",
         source: SYNTHETIC_LOC,
@@ -425,6 +436,7 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
         target,
         fnBody: rawLoc(handlerSource),
         ...(phase !== undefined && { phase }),
+        ...(escapeHatch !== undefined && { escapeHatch }),
       });
     },
 

package/src/engine/feature-ast/patterns.ts

@@ -70,6 +70,7 @@ import type {
   AccessRule,
   AgentHandlerHints,
   ClaimKeyType,
+  EscapeHatchDeclaration,
   RateLimitOption,
 } from "../types/handlers";
 import type { HookPhase } from "../types/hooks";
@@ -388,6 +389,7 @@ export type WriteHandlerPattern = {
   readonly agent?: AgentHandlerHints;
   readonly rateLimit?: RateLimitOption;
   readonly unsafeSkipTransitionGuard?: boolean;
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };
 
 // `r.queryHandler(...)` — registers a read handler: name, Zod input schema,
@@ -410,6 +412,7 @@ export type QueryHandlerPattern = {
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
   readonly rateLimit?: RateLimitOption;
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };
 
 // `r.streamHandler(...)` — registers a streaming read handler: name, Zod
@@ -444,6 +447,7 @@ export type HookPattern = {
   readonly target: string | readonly string[] | { readonly allOf: string };
   readonly fnBody: SourceLocation;
   readonly phase?: HookPhase;
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };
 
 // `r.job(name, options, handler)` — registers a background job, qualified

package/src/engine/feature-ast/render.ts

@@ -408,6 +408,7 @@ function renderWriteHandler(p: WriteHandlerPattern): string {
   if (p.agent !== undefined) lines.push(`  agent: ${renderValue(p.agent)},`);
   if (p.rateLimit !== undefined) lines.push(`  rateLimit: ${renderValue(p.rateLimit)},`);
   if (p.unsafeSkipTransitionGuard === true) lines.push("  unsafeSkipTransitionGuard: true,");
+  if (p.escapeHatch !== undefined) lines.push(`  escapeHatch: ${renderValue(p.escapeHatch)},`);
   lines.push("});");
   return lines.join("\n");
 }
@@ -422,6 +423,7 @@ function renderQueryHandler(p: QueryHandlerPattern): string {
   if (p.description !== undefined) lines.push(`  description: ${JSON.stringify(p.description)},`);
   if (p.agent !== undefined) lines.push(`  agent: ${renderValue(p.agent)},`);
   if (p.rateLimit !== undefined) lines.push(`  rateLimit: ${renderValue(p.rateLimit)},`);
+  if (p.escapeHatch !== undefined) lines.push(`  escapeHatch: ${renderValue(p.escapeHatch)},`);
   lines.push("});");
   return lines.join("\n");
 }
@@ -450,6 +452,7 @@ function renderHook(p: HookPattern): string {
   lines.push(`  target: ${renderHookTarget(p.target)},`);
   lines.push(`  handler: ${reindentBody(p.fnBody.raw, PATTERN_INDENT)},`);
   if (p.phase !== undefined) lines.push(`  phase: ${JSON.stringify(p.phase)},`);
+  if (p.escapeHatch !== undefined) lines.push(`  escapeHatch: ${renderValue(p.escapeHatch)},`);
   lines.push("});");
   return lines.join("\n");
 }

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/pattern-library/shared-fields.ts

@@ -61,9 +61,13 @@ export const accessRuleField: FormFieldSpec = {
       label: { en: "Open to all (auth still required)", de: "Für alle (Auth nötig)" },
       fields: [
         {
-          path: "access.openToAll",
-          label: { en: "Open to all", de: "Offen für alle" },
-          input: "boolean",
+          path: "access.openToAll.reason",
+          label: { en: "Reason", de: "Begründung" },
+          hint: {
+            en: "Who may call this, and why that is safe without a role — required, `true` alone no longer grants access.",
+          },
+          input: "text",
+          required: true,
         },
       ],
     },

package/src/engine/registry-validate.ts

@@ -25,7 +25,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()]);
@@ -721,10 +721,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-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/entrypoint/__tests__/entrypoint-attach-dispatcher.integration.test.ts

@@ -41,7 +41,7 @@ const writeProbeFeature = defineFeature("writeProbe", (r) => {
       });
       return { isSuccess: true as const, data: { note: event.payload.note } };
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
   r.job("write-via-job", { trigger: { manual: true }, retries: 0 }, async (payload, ctx) => {
     try {

package/src/entrypoint/__tests__/entrypoint-job-wiring.integration.test.ts

@@ -33,7 +33,7 @@ const wiringFeature = defineFeature("wiring", (r) => {
       isSuccess: true as const,
       data: { id: 1, sku: event.payload.sku },
     }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
   r.job(
     "record-order",
@@ -57,7 +57,7 @@ const mixedLaneFeature = defineFeature("mixed", (r) => {
       isSuccess: true as const,
       data: { id: 1, msg: event.payload.msg },
     }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
   r.job(
     "handle-on-worker",
@@ -240,7 +240,7 @@ const featureGateJobFeature = defineFeature("featuregate", (r) => {
       isSuccess: true as const,
       data: { id: 1, msg: event.payload.msg },
     }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
   r.job(
     "record-features",

package/src/entrypoint/__tests__/split-deploy.integration.test.ts

@@ -57,7 +57,7 @@ const workerWriteFeature = defineFeature("workerWrite", (r) => {
       });
       return { isSuccess: true as const, data: { note: event.payload.note } };
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
   r.multiStreamProjection({
     name: "consume-notes",

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.

package/src/errors/i18n/en.yaml

@@ -109,6 +109,19 @@ identity_switch_denied:
     (or on the `r.hook(...)` call, if the switch happens inside a hook), or
     move the logic into an `r.systemScope()` feature or a job.
 
+unsafe_all_tenants_denied:
+  endUser: |
+    This action isn't allowed.
+    Please contact an administrator if you believe this is a mistake.
+  developer: |
+    `AccessDeniedError`: a handler or hook called
+    `ctx.queryProjection(qualifiedName, { unsafeAllTenants: true })` without
+    being an `r.systemScope()` handler or declaring `escapeHatch: { reason }`.
+
+    Declare `escapeHatch: { reason: "..." }` on the write, query or stream
+    handler (or on the `r.hook(...)` call, if the read happens inside a
+    hook), or move the logic into an `r.systemScope()` feature.
+
 member_resolution_denied:
   endUser: |
     This action isn't allowed.

package/src/errors/reasons.ts

@@ -48,6 +48,10 @@ export const FrameworkReasons = {
   // claims, origin or extra roles) without r.systemScope() or escapeHatch.
   identitySwitchDenied: "identity_switch_denied",
 
+  // AccessDeniedError: a handler/hook called ctx.queryProjection(..., { unsafeAllTenants: true })
+  // without an r.systemScope() feature or a declared escapeHatch.
+  unsafeAllTenantsDenied: "unsafe_all_tenants_denied",
+
   // AccessDeniedError: ctx.queryAsMember's userId is not an active member of
   // ctx's tenant. Deliberately generic — a caller can't probe which check failed.
   memberResolutionDenied: "member_resolution_denied",

package/src/es-ops/__tests__/runner.integration.test.ts

@@ -58,7 +58,7 @@ const seedTestFeature = defineFeature("esopstest", (r) => {
     "probe:create",
     z.object({ label: z.string().min(1) }),
     async (event, ctx) => probeExecutor.create(event.payload, event.user, ctx.db),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
   r.writeHandler(
     "probe:fail",
@@ -70,7 +70,7 @@ const seedTestFeature = defineFeature("esopstest", (r) => {
         currentVersion: 2,
       });
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
   // Role-gated handler (no openToAll): the bare system actor has no bypass
   // for explicit role gates — only systemWriteAs' extraRoles reaches it.

package/src/i18n/required-surface-keys.ts

@@ -196,7 +196,9 @@ export function requiredKeysFromScreen(
       const form = screen as ActionFormScreenDefinition;
       pushKey(out, form.submitLabel);
       for (const fieldName of Object.keys(form.fields)) {
-        out.add(fieldLabelKey(featureName, ACTION_FORM_ENTITY, fieldName));
+        const override = form.fieldLabels?.[fieldName];
+        if (override !== undefined) pushKey(out, override);
+        else out.add(fieldLabelKey(featureName, ACTION_FORM_ENTITY, fieldName));
       }
       for (const section of form.layout.sections) {
         if (isExtensionEditSection(section)) {
@@ -207,7 +209,9 @@ export function requiredKeysFromScreen(
         pushKey(out, section.title);
         for (const f of section.fields) {
           const fieldName = editFieldName(f);
-          out.add(fieldLabelKey(featureName, ACTION_FORM_ENTITY, fieldName));
+          const override = form.fieldLabels?.[fieldName];
+          if (override !== undefined) pushKey(out, override);
+          else out.add(fieldLabelKey(featureName, ACTION_FORM_ENTITY, fieldName));
         }
       }
       break;

package/src/jobs/__tests__/job-event-trigger.integration.test.ts

@@ -26,7 +26,7 @@ const ordersFeature = defineFeature("orders", (r) => {
         data: { id: 1, product: event.payload.product, amount: event.payload.amount },
       };
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 
@@ -51,7 +51,7 @@ const analyticsFeature = defineFeature("analytics", (r) => {
       isSuccess: true as const,
       data: null,
     }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.job("trackOrder", { trigger: { on: "orders:write:orders:create" } }, async (payload) => {