@cosmicdrift/kumiko-framework 0.270.0 → 0.273.0

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

@@ -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/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/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-systemdb.integration.test.ts

@@ -1,5 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { tenantDbRunner } from "../../db/tenant-db-runner";
 import { createRegistry, defineFeature, type Registry } from "../../engine";
 import { createTestRedis, type TestRedis, testTenantId } from "../../stack";
 import { waitFor } from "../../testing";
@@ -12,9 +13,9 @@ import { createJobRunner, type JobRunner } from "../job-runner";
 type JobRunResult = {
   readonly name: "system" | "tenant" | "system-per-tenant";
   readonly present: boolean;
-  // assertTenantMatch() must return a TenantDb whose `.raw` is the SAME
-  // underlying DbConnection ctx.db carries — proves systemDb is bound to
-  // the job's own tenant-scoped db, not a separate instance.
+  // assertTenantMatch() must return a TenantDb bound (via tenantDbRunner) to
+  // the SAME underlying DbConnection ctx.db carries — proves systemDb is
+  // bound to the job's own tenant-scoped db, not a separate instance.
   readonly boundToRawDb: boolean | undefined;
   // A foreign tenantId must throw fail-closed (AccessDeniedError), same as
   // the HandlerContext.systemDb self-check.
@@ -48,7 +49,7 @@ const systemScopedFeature = defineFeature("jobsystemdb-system", (r) => {
     results.push({
       name: "system",
       present: true,
-      boundToRawDb: checked.raw === ctx.db,
+      boundToRawDb: tenantDbRunner(checked) === ctx.db,
       foreignTenantThrew,
     });
   });

package/src/jobs/__tests__/jobs.integration.test.ts

@@ -31,6 +31,10 @@ let redisUrl: string;
 // Track which jobs ran and when
 const jobLog: Array<{ name: string; payload: Record<string, unknown>; timestamp: number }> = [];
 
+// Counts eventRetrySucceeds' own attempts — throws once on attempt 1, then
+// succeeds, so a real retry must have happened for the job to ever reach 2.
+let eventRetryAttemptCount = 0;
+
 function clearLog() {
   jobLog.length = 0;
 }
@@ -140,6 +144,25 @@ const testFeature = defineFeature("test", (r) => {
     },
   );
 
+  r.writeHandler(
+    "retry-event-trigger",
+    z.object({ n: z.number() }),
+    async (event) => ({ isSuccess: true, data: { n: event.payload.n } }),
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+  );
+  // Event-triggered job with retries — proves handleEvent passes
+  // retries/backoff to the queue the same way dispatch() does (fw
+  // job-runner retries regression, solon).
+  r.job(
+    "eventRetrySucceeds",
+    { trigger: { on: "test:write:retry-event-trigger" }, retries: 2 },
+    async (payload) => {
+      eventRetryAttemptCount += 1;
+      jobLog.push({ name: "test:job:event-retry-succeeds", payload, timestamp: Date.now() });
+      if (eventRetryAttemptCount === 1) throw new Error("fails on first attempt");
+    },
+  );
+
   // Job that fails
   r.job("failingJob", { trigger: { manual: true }, retries: 1 }, async () => {
     throw new Error("intentional failure");
@@ -1197,6 +1220,24 @@ describe("handleEvent maxPerTenant", () => {
   });
 });
 
+describe("handleEvent retries", () => {
+  test("an event-triggered job with retries retries on failure and eventually succeeds", async () => {
+    clearLog();
+    eventRetryAttemptCount = 0;
+    await withRunner(async (runner) => {
+      const user = { ...TestUsers.admin, tenantId: "retry-tenant-evt" };
+      await runner.handleEvent("test:write:retry-event-trigger", { n: 1 }, user);
+      // Without retries/backoff reaching the queue, the job fails on
+      // attempt 1 and BullMQ never retries — this would time out.
+      await waitFor(() => {
+        const entries = jobLog.filter((e) => e.name === "test:job:event-retry-succeeds");
+        expect(entries.length).toBe(2);
+      });
+    });
+    expect(eventRetryAttemptCount).toBe(2);
+  });
+});
+
 // --- Registry ---
 
 describe("job registry", () => {

package/src/jobs/job-runner.ts

@@ -9,6 +9,7 @@ import {
   type AppContext,
   type DispatchWriteRef,
   type JobContext,
+  type JobDefinition,
   type JobRunIn,
   type MemberReader,
   type Registry,
@@ -27,6 +28,7 @@ import {
   type Tracer,
 } from "../observability";
 import { createDistributedLock, type DistributedLock } from "../pipeline/distributed-lock";
+import { createEscapeHatchReporter } from "../pipeline/escape-hatch-report";
 import { RedisKeys } from "../pipeline/redis-keys";
 import { bridgeStub } from "../testing/handler-context";
 
@@ -251,6 +253,16 @@ function timeoutReject(
   };
 }
 
+// Shared by dispatch() and handleEvent() — an event-triggered job must retry
+// on failure the same way a directly-dispatched one does; a duplicated
+// inline computation in handleEvent previously dropped both options.
+function buildRetryBullOpts(jobDef: JobDefinition): Record<string, unknown> {
+  const opts: Record<string, unknown> = {};
+  if (jobDef.retries !== undefined) opts["attempts"] = jobDef.retries + 1;
+  if (jobDef.backoff) opts["backoff"] = { type: jobDef.backoff };
+  return opts;
+}
+
 export function createJobRunner(options: JobRunnerOptions): JobRunner {
   const { registry, context, redisUrl, consumerLane } = options;
   const queueNamePrefix = options.queueNamePrefix ?? DEFAULT_QUEUE_NAME_PREFIX;
@@ -282,12 +294,19 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     return async () => {
       const systemUser = createSystemUser(SYSTEM_TENANT_ID);
       const systemModeDb = createTenantDb(db, SYSTEM_TENANT_ID, "system");
+      const reportEscapeHatch = createEscapeHatchReporter({
+        handler: ACTIVE_TENANT_IDS_QUERY_NAME,
+        tenantId: SYSTEM_TENANT_ID,
+        actor: systemUser.id,
+        sink: context._escapeHatchAuditSink,
+        log: context.log,
+      });
       const result = await handler.handler(
         { type: ACTIVE_TENANT_IDS_QUERY_NAME, payload: {}, user: systemUser },
         {
           db: systemModeDb,
           dbOutsideTransaction: systemModeDb,
-          systemDb: createUncheckedSystemDb(systemModeDb),
+          systemDb: createUncheckedSystemDb(systemModeDb, undefined, reportEscapeHatch),
           registry,
           ...bridgeStub(),
         },
@@ -533,7 +552,19 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     const tenantScopedDb = configDb ? createTenantDb(configDb, tenantId, "system") : undefined;
     const isSystemJob = registry.isJobSystemScoped(jobName);
     const systemDb =
-      isSystemJob && tenantScopedDb ? createUncheckedSystemDb(tenantScopedDb) : undefined;
+      isSystemJob && tenantScopedDb
+        ? createUncheckedSystemDb(
+            tenantScopedDb,
+            undefined,
+            createEscapeHatchReporter({
+              handler: jobName,
+              tenantId,
+              actor: jobSystemUser.id,
+              sink: context._escapeHatchAuditSink,
+              log: context.log,
+            }),
+          )
+        : undefined;
     const config =
       context._configAccessorFactory && tenantScopedDb
         ? context._configAccessorFactory({
@@ -883,8 +914,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
           break;
       }
 
-      if (jobDef.retries !== undefined) bullOpts["attempts"] = jobDef.retries + 1;
-      if (jobDef.backoff) bullOpts["backoff"] = { type: jobDef.backoff };
+      Object.assign(bullOpts, buildRetryBullOpts(jobDef));
       if (jobDef.timeout) bullOpts["timeout"] = jobDef.timeout;
       if (meta?.priority !== undefined) bullOpts["priority"] = meta.priority;
 
@@ -948,7 +978,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
         }
         // Route to the job's declared lane, not a fixed queue — that's
         // the whole reason both queues are held.
-        await queues[laneForJob(jobDef)].add(name, data);
+        await queues[laneForJob(jobDef)].add(name, data, buildRetryBullOpts(jobDef));
       }
     },
     attachDispatcher(ref: DispatchWriteRef): void {