@cosmicdrift/kumiko-framework 0.274.0 → 0.275.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.274.0",
+  "version": "0.275.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.274.0",
+    "@cosmicdrift/kumiko-types": "0.275.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.274.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.275.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.275.0",
+    "type": "breaking",
+    "title": "JobContext.db is a tenant-filtered TenantDb; unfiltered job access needs r.job({ escapeHatch }) or r.systemScope() (fw#2914).",
+    "detail": "Job handlers no longer receive the unfiltered boot `DbConnection` as `ctx.db`. `JobContext.db` is now a `TenantDb` in \"tenant\" mode, bound to the job's resolved tenant (`_tenantId`, `payload.tenantId`, or `SYSTEM_TENANT_ID` for tenant-less cron jobs). Reads see that tenant plus `SYSTEM_TENANT_ID` reference rows, and writes are scoped to it. `JobDefinition` gains `escapeHatch?: { reason }`: it grants `ctx.db.unsafeRaw(reason)` for that job and reports an `\"unsafe-raw\"` escape-hatch audit event through `_escapeHatchAuditSink` (deduplicated like handler grants). Without it, `ctx.db.unsafeRaw` throws `AccessDeniedError`. `r.systemScope()` features keep `ctx.systemDb` unchanged. `r.job` throws at registration for an `escapeHatch` with an empty reason. Framework `soft-delete` cleanup jobs run on the tenant-filtered `TenantDb` without a grant. Bundled cross-tenant jobs now declare `escapeHatch`: auth-mfa reencrypt, sessions cleanup, form-draft cleanup, secrets rotate, files-tenant-data sweep-orphaned-derivatives, data-retention retention-cleanup, inbound-mail-retention, tenant-lifecycle run-tenant-destruction, and user-data-rights run-export-jobs/run-forget-cleanup. The systemScope features config, jobs and workflow-runner use `ctx.systemDb.unsafeRaw`. The exported `rotateJob` (secrets) and `sweepOrphanedDerivativesJob` (files-tenant-data) take the raw `DbConnection` as a third argument.",
+    "migration": "Jobs that only read and write their own tenant through `ctx.db` method calls or `selectMany/fetchOne/insertOne/updateMany/deleteMany(ctx.db, ...)` need no change. A job that treated `ctx.db` as a `DbConnection` (casts, `asRawClient`, `countWhere`, `upsert*`, `incrementCounter`, `createTenantDb(ctx.db, ...)`, `runProjectionsForEvent(..., ctx.db)`, or `\"raw\" in db ? db.raw : db`) must declare the grant and fetch the runner explicitly. Use `r.job({ name, trigger, escapeHatch: { reason: \"<why>\" }, handler: async (payload, ctx) => work(ctx.db.unsafeRaw(\"<why>\")) })`; keep the `unsafeRaw` call inside the inline `handler` next to `escapeHatch` so `guard-escape-hatch-declared` recognizes the declaration. `r.systemScope()` features use `ctx.systemDb.unsafeRaw(reason)` instead. WARNING: a job that is not migrated but passes a foreign `where.tenantId` through `ctx.db` does not fail; the filter silently narrows it to the job's own tenant (`SYSTEM_TENANT_ID` for tenant-less cron jobs), so cross-tenant sweeps silently read nothing. Audit every cross-tenant job. Hand-built `JobContext` objects in tests need `db: createTenantDb(conn, tenantId)` (plus `systemDb` for systemScope jobs). Direct callers of `rotateJob`/`sweepOrphanedDerivativesJob` pass the raw connection as the third argument."
+  },
   {
     "version": "0.274.0",
     "type": "breaking",

package/src/engine/__tests__/dedupe-features.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+import { createApp, createRegistry, dedupeFeatures, defineFeature } from "../index";
+
+describe("dedupeFeatures", () => {
+  test("same reference mounted twice collapses to one entry, order preserved", () => {
+    const shared = defineFeature("shared", () => {});
+    const other = defineFeature("other", () => {});
+
+    const result = dedupeFeatures([shared, other, shared]);
+
+    expect(result).toEqual([shared, other]);
+    expect(result[0]).toBe(shared);
+  });
+
+  test("registry builds when the same reference is mounted twice", () => {
+    const shared = defineFeature("shared", () => {});
+
+    expect(() => createRegistry([shared, shared])).not.toThrow();
+  });
+
+  test("two instances with shallow-equal dedupeOptions collapse — first instance kept", () => {
+    const a = defineFeature("x", () => {}, { dedupeOptions: { limit: 3 } });
+    const b = defineFeature("x", () => {}, { dedupeOptions: { limit: 3 } });
+    const other = defineFeature("y", () => {});
+
+    const result = dedupeFeatures([a, other, b]);
+
+    expect(result).toEqual([a, other]);
+    expect(result[0]).toBe(a);
+  });
+
+  test("differing primitive dedupeOptions throws with a 'different options' message", () => {
+    const a = defineFeature("x", () => {}, { dedupeOptions: { limit: 3 } });
+    const b = defineFeature("x", () => {}, { dedupeOptions: { limit: 5 } });
+
+    expect(() => dedupeFeatures([a, b])).toThrow(/Duplicate feature: "x".*different options/);
+  });
+
+  test("same function reference in dedupeOptions collapses", () => {
+    const onTrigger = () => {};
+    const a = defineFeature("x", () => {}, { dedupeOptions: { onTrigger } });
+    const b = defineFeature("x", () => {}, { dedupeOptions: { onTrigger } });
+
+    const result = dedupeFeatures([a, b]);
+
+    expect(result).toEqual([a]);
+  });
+
+  test("different function reference in dedupeOptions throws", () => {
+    const a = defineFeature("x", () => {}, { dedupeOptions: { onTrigger: () => {} } });
+    const b = defineFeature("x", () => {}, { dedupeOptions: { onTrigger: () => {} } });
+
+    expect(() => dedupeFeatures([a, b])).toThrow(/Duplicate feature: "x".*different options/);
+  });
+
+  test("{ a: undefined } and {} are treated as shallow-equal (missing key == undefined)", () => {
+    const a = defineFeature("x", () => {}, { dedupeOptions: { a: undefined } });
+    const b = defineFeature("x", () => {}, { dedupeOptions: {} });
+
+    const result = dedupeFeatures([a, b]);
+
+    expect(result).toEqual([a]);
+  });
+
+  test("two distinct instances with no dedupeOptions throw with a 'distinct instances' message", () => {
+    const a = defineFeature("x", () => {});
+    const b = defineFeature("x", () => {});
+
+    expect(() => dedupeFeatures([a, b])).toThrow(
+      /Duplicate feature: "x" mounted twice as distinct instances/,
+    );
+  });
+
+  test("createApp boots end-to-end with a feature mounted twice via dedupeOptions", () => {
+    const a = defineFeature("x", () => {}, { dedupeOptions: {} });
+    const b = defineFeature("x", () => {}, { dedupeOptions: {} });
+
+    expect(() =>
+      createApp({
+        roles: ["Admin"],
+        features: [a, b],
+      }),
+    ).not.toThrow();
+  });
+});

package/src/engine/__tests__/soft-delete-cleanup-job-tenant-db.integration.test.ts

@@ -0,0 +1,82 @@
+// fw#2914 — soft-delete cleanup runs through the real job runner with ctx.db as a
+// tenant-filtered TenantDb: a run purges only its own tenant's expired rows.
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { asRawClient } from "../../bun-db/query";
+import { selectMany } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { waitFor } from "../../testing";
+import {
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityDeleteHandler,
+  defineFeature,
+} from "../index";
+import { SOFT_DELETE_CLEANUP_JOB } from "../soft-delete-cleanup";
+
+const itemEntity = createEntity({
+  table: "fw2914_sdc_items",
+  softDelete: true,
+  fields: {
+    label: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+  },
+});
+const itemTable = buildEntityTable("item", itemEntity);
+
+const feature = defineFeature("sdcjob", (r) => {
+  r.entity("item", itemEntity);
+  r.writeHandler(defineEntityCreateHandler("item", itemEntity, { access: { roles: ["Admin"] } }));
+  r.writeHandler(defineEntityDeleteHandler("item", itemEntity, { access: { roles: ["Admin"] } }));
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [feature],
+    jobs: {
+      consumerLane: "worker",
+      getActiveTenantIds: async () => [TestUsers.admin.tenantId],
+    },
+  });
+  await unsafeCreateEntityTable(stack.db, itemEntity, "item");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function createExpiredDeletedItem(user: typeof TestUsers.admin): Promise<string> {
+  const created = await stack.http.writeOk<{ id: string }>(
+    "sdcjob:write:item:create",
+    { label: `expired-${user.tenantId}` },
+    user,
+  );
+  await stack.http.writeOk("sdcjob:write:item:delete", { id: created.id }, user);
+  // kumiko-lint-ignore raw-sql test fixture ages deletedAt past the default grace period
+  await asRawClient(stack.db).unsafe(
+    `UPDATE fw2914_sdc_items SET deleted_at = now() - interval '400 days' WHERE id = $1`,
+    [created.id],
+  );
+  return created.id;
+}
+
+describe("soft-delete cleanup job smoke run on a tenant-filtered JobContext.db (fw#2914)", () => {
+  test("a per-tenant fan-out run purges only the active tenant's expired soft-deleted rows", async () => {
+    const ownId = await createExpiredDeletedItem(TestUsers.admin);
+    const foreignId = await createExpiredDeletedItem(TestUsers.otherTenant);
+    const jobRunner = stack.jobRunner;
+    if (!jobRunner) throw new Error("setupTestStack({ jobs }) did not wire a jobRunner");
+
+    await jobRunner.dispatch(SOFT_DELETE_CLEANUP_JOB, {});
+
+    await waitFor(async () => {
+      const own = await selectMany(stack.db, itemTable, { id: ownId });
+      expect(own).toHaveLength(0);
+    });
+    const foreign = await selectMany(stack.db, itemTable, { id: foreignId });
+    expect(foreign).toHaveLength(1);
+    expect(foreign[0]?.["isDeleted"]).toBe(true);
+  });
+});

package/src/engine/boot-validator/index.ts

@@ -1,4 +1,5 @@
 import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-encryption";
+import { dedupeFeatures } from "../dedupe-features";
 import { QnTypes, qualifyEntityName } from "../qualified-name";
 import type { FeatureDefinition } from "../types";
 import { validateAccessDeclarations } from "./access-declarations";
@@ -91,9 +92,10 @@ export type ValidateBootOptions = {
  * Throws on the first error found — fail fast.
  */
 export function validateBoot(
-  features: readonly FeatureDefinition[],
+  rawFeatures: readonly FeatureDefinition[],
   options?: ValidateBootOptions,
 ): void {
+  const features = dedupeFeatures(rawFeatures);
   const featureMap = new Map<string, FeatureDefinition>();
   for (const f of features) {
     featureMap.set(f.name, f);

package/src/engine/create-app.ts

@@ -1,4 +1,5 @@
 import { type ValidateBootOptions, validateBoot } from "./boot-validator";
+import { dedupeFeatures } from "./dedupe-features";
 import { createRegistry } from "./registry";
 import type { FeatureDefinition, Registry } from "./types";
 import { DEFAULT_CURRENCIES } from "./types";
@@ -20,6 +21,7 @@ export type App = {
 };
 
 export function createApp(config: AppConfig): App {
+  const features = dedupeFeatures(config.features);
   const validRoles = new Set(config.roles);
 
   // "system" is reserved for SYSTEM_USER — cannot be used as an app role
@@ -32,7 +34,7 @@ export function createApp(config: AppConfig): App {
 
   // Validate all roles referenced by features exist in app-defined roles.
   // openToAll access has no role list — nothing to validate there.
-  for (const feature of config.features) {
+  for (const feature of features) {
     for (const handler of Object.values(feature.writeHandlers)) {
       if (handler.access && "roles" in handler.access) {
         for (const role of handler.access.roles) {
@@ -83,7 +85,7 @@ export function createApp(config: AppConfig): App {
   const currencies = [...new Set([...DEFAULT_CURRENCIES, ...(config.currencies ?? [])])];
 
   // Validate defaultCurrency on entities that have money fields
-  for (const feature of config.features) {
+  for (const feature of features) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
       // A top-level money field isn't the only way an entity can hold money —
       // an embedded-list's sub-schema (e.g. invoice lines) can carry a money
@@ -110,10 +112,10 @@ export function createApp(config: AppConfig): App {
   }
 
   // Run boot-time validation before creating registry
-  validateBoot(config.features, config.validateBootOptions);
+  validateBoot(features, config.validateBootOptions);
 
   return {
-    registry: createRegistry(config.features),
+    registry: createRegistry(features),
     roles: config.roles,
     softDeleteDefault,
     currencies,

package/src/engine/dedupe-features.ts

@@ -0,0 +1,46 @@
+import type { FeatureDefinition } from "./types";
+
+function dedupeOptionsShallowEqual(
+  a: Readonly<Record<string, unknown>>,
+  b: Readonly<Record<string, unknown>>,
+): boolean {
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const key of keys) {
+    if (!Object.is(a[key], b[key])) return false;
+  }
+  return true;
+}
+
+function isInterchangeable(existing: FeatureDefinition, next: FeatureDefinition): boolean {
+  if (existing === next) return true;
+  if (existing.dedupeOptions !== undefined && next.dedupeOptions !== undefined) {
+    return dedupeOptionsShallowEqual(existing.dedupeOptions, next.dedupeOptions);
+  }
+  return false;
+}
+
+// First occurrence wins: runtimes late-bind closure state (sessions' autoRevoke) on the kept instance.
+export function dedupeFeatures(features: readonly FeatureDefinition[]): FeatureDefinition[] {
+  const byName = new Map<string, FeatureDefinition>();
+  const result: FeatureDefinition[] = [];
+
+  for (const feature of features) {
+    const existing = byName.get(feature.name);
+    if (existing === undefined) {
+      byName.set(feature.name, feature);
+      result.push(feature);
+      continue;
+    }
+    if (isInterchangeable(existing, feature)) continue;
+    if (existing.dedupeOptions !== undefined && feature.dedupeOptions !== undefined) {
+      throw new Error(
+        `Duplicate feature: "${feature.name}" mounted twice with different options — mount it once or pass identical options`,
+      );
+    }
+    throw new Error(
+      `Duplicate feature: "${feature.name}" mounted twice as distinct instances — mount it once`,
+    );
+  }
+
+  return result;
+}

package/src/engine/define-feature.ts

@@ -29,9 +29,14 @@ function resolveFeatureNamesArgs(
   return unwrapArrayForm(args, "features");
 }
 
+export type DefineFeatureSettings = {
+  readonly dedupeOptions?: Readonly<Record<string, unknown>>;
+};
+
 export function defineFeature<const TName extends string, TExports = undefined>(
   name: TName,
   setup: (r: FeatureRegistrar<TName>) => TExports,
+  settings?: DefineFeatureSettings,
 ): FeatureDefinition & { readonly exports: TExports } {
   const state = createInitialFeatureBuilderState();
 
@@ -158,5 +163,6 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     storeTables: state.storeTables,
     ...(state.treeActions !== undefined && { treeActions: state.treeActions }),
     ...(state.envSchema !== undefined && { envSchema: state.envSchema }),
+    ...(settings?.dedupeOptions !== undefined && { dedupeOptions: settings.dedupeOptions }),
   };
 }

package/src/engine/feature-ast/__tests__/parse-real-features.test.ts

@@ -68,8 +68,8 @@ const FEATURES: readonly RealFeature[] = [
   {
     path: "packages/bundled-features/src/sessions/feature.ts",
     expectedFeatureName: "sessions",
-    recognisedKinds: ["hook", "writeHandler", "queryHandler"],
-    errorMethodNames: ["storeTable", "job"],
+    recognisedKinds: ["hook", "writeHandler", "queryHandler", "job"],
+    errorMethodNames: ["storeTable"],
   },
   {
     path: "packages/bundled-features/src/auth-email-password/feature.ts",

package/src/engine/feature-config-events-jobs.ts

@@ -181,9 +181,18 @@ export function buildConfigEventsJobsMethods<TName extends string>(
               handler as JobHandlerFn,
             ]
           : (() => {
-              const { name, handler: h, ...rest } = jobNameOrDefinition;
-              return [name, rest, h] as const;
+              const { name: definedJobName, handler: h, ...rest } = jobNameOrDefinition;
+              return [definedJobName, rest, h] as const;
             })();
+      if (
+        jobOptions.escapeHatch !== undefined &&
+        jobOptions.escapeHatch.reason.trim().length === 0
+      ) {
+        throw new Error(
+          `[Feature ${name}] r.job("${jobName}") declares { escapeHatch: { reason: "" } } — ` +
+            "the reason must be a non-empty string explaining why this job needs unfiltered database access.",
+        );
+      }
       // Resolve NameOrRef(s) in trigger.on. Multi-Trigger-Form: Array
       // wird zu Array von resolved strings, Single bleibt single string —
       // job-runner unterscheidet anhand Array.isArray.

package/src/engine/index.ts

@@ -49,6 +49,7 @@ export {
 export type { App, AppConfig } from "./create-app";
 export { createApp } from "./create-app";
 export { crossTenantOverrideDenied } from "./cross-tenant";
+export { dedupeFeatures } from "./dedupe-features";
 export { defineFeature } from "./define-feature";
 export type {
   PagedQueryHandlerDefinition,

package/src/engine/registry.ts

@@ -1,4 +1,5 @@
 import { validateExtensionPreSaveWiring } from "./boot-validator/entity-handler";
+import { dedupeFeatures } from "./dedupe-features";
 import { buildRegistryFacade } from "./registry-facade";
 import {
   populateClaimsAndAuth,
@@ -44,7 +45,8 @@ import type { FeatureDefinition, Registry } from "./types";
 // This is where the magic happens. By "magic" I mean: precomputed maps.
 // I build everything once at boot (hooks, relations, searchable fields, ...)
 // so nothing has to iterate over objects at runtime. O(1) instead of O(n*m).
-export function createRegistry(features: readonly FeatureDefinition[]): Registry {
+export function createRegistry(rawFeatures: readonly FeatureDefinition[]): Registry {
+  const features = dedupeFeatures(rawFeatures);
   const state = createInitialState();
 
   for (const feature of features) {

package/src/engine/soft-delete-cleanup.ts

@@ -42,9 +42,10 @@ export const softDeleteCleanupJob: JobHandlerFn = async (_payload, ctx) => {
     throw new Error("soft-delete cleanup: ctx.db + ctx.registry required (JobContext incomplete)");
   }
   // perTenant fan-out → one run per active tenant, systemUser scoped to it.
-  // The job's db is the boot DbConnection (NOT tenant-scoped), so every delete
-  // is explicitly tenant-filtered below — otherwise a tenant with a short grace
-  // would purge another tenant's still-within-grace rows.
+  // The job's db is a tenant-filtered TenantDb, but every delete is still
+  // explicitly tenant-filtered below as defense-in-depth — otherwise a
+  // tenant with a short grace would purge another tenant's still-within-grace
+  // rows.
   const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
   if (tenantId === undefined) {
     // skip: cron fired without a perTenant fan-out tenant — nothing scoped to purge

package/src/jobs/__tests__/job-systemdb.integration.test.ts

@@ -49,7 +49,7 @@ const systemScopedFeature = defineFeature("jobsystemdb-system", (r) => {
     results.push({
       name: "system",
       present: true,
-      boundToRawDb: tenantDbRunner(checked) === ctx.db,
+      boundToRawDb: tenantDbRunner(checked) === tenantDbRunner(ctx.db),
       foreignTenantThrew,
     });
   });

package/src/jobs/__tests__/job-tenant-db.integration.test.ts

@@ -0,0 +1,162 @@
+// fw#2914 — JobContext.db is a tenant-filtered TenantDb; unfiltered access needs r.job({ escapeHatch }).
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import type { DbRunner } from "../../db/connection";
+import { table, text, uuid } from "../../db/dialect";
+import { insertOne, selectMany } from "../../db/query";
+import { createRegistry, defineFeature, type Registry } from "../../engine";
+import type { EscapeHatchUseEvent, JobContext } from "../../engine/types";
+import { AccessDeniedError } from "../../errors";
+import { createTestRedis, type TestRedis, testTenantId, unsafePushTables } from "../../stack";
+import { waitFor } from "../../testing";
+import { createJobRunner, type JobRunner } from "../job-runner";
+
+const itemsTable = table("fw2914_job_items", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  tenantId: uuid("tenant_id").notNull(),
+  label: text("label").notNull(),
+});
+
+const ownTenant = testTenantId(1);
+const foreignTenant = testTenantId(2);
+const DECLARED_REASON = "fw#2914 integration test — job counts items of every tenant";
+
+type Outcome = {
+  readonly job: "undeclared" | "declared";
+  readonly mode?: string;
+  readonly tenantId?: string;
+  readonly labels?: readonly string[];
+  readonly foreignWhereLabels?: readonly string[];
+  readonly unsafeRawDenied?: boolean;
+  readonly rawLabels?: readonly string[];
+};
+
+const outcomes: Outcome[] = [];
+const auditEvents: EscapeHatchUseEvent[] = [];
+
+function labelsOf(rows: readonly { label: string }[]): string[] {
+  return rows.map((row) => row.label).sort();
+}
+
+const jobsFeature = defineFeature("jobtenantdb", (r) => {
+  r.job("undeclared", { trigger: { manual: true } }, async (_payload, ctx) => {
+    const own = await selectMany<{ label: string }>(ctx.db, itemsTable);
+    const foreignWhere = await selectMany<{ label: string }>(ctx.db, itemsTable, {
+      tenantId: foreignTenant,
+    });
+    let unsafeRawDenied = false;
+    try {
+      ctx.db.unsafeRaw("fw#2914 integration test — undeclared job reaching for raw");
+    } catch (err) {
+      unsafeRawDenied = err instanceof AccessDeniedError;
+    }
+    outcomes.push({
+      job: "undeclared",
+      mode: ctx.db.mode,
+      tenantId: ctx.db.tenantId,
+      labels: labelsOf(own),
+      foreignWhereLabels: labelsOf(foreignWhere),
+      unsafeRawDenied,
+    });
+  });
+
+  r.job({
+    name: "declared",
+    trigger: { manual: true },
+    escapeHatch: { reason: DECLARED_REASON },
+    handler: async (_payload, ctx) => {
+      const raw = ctx.db.unsafeRaw(DECLARED_REASON);
+      const rows = await selectMany<{ label: string }>(raw, itemsTable);
+      outcomes.push({ job: "declared", rawLabels: labelsOf(rows) });
+    },
+  });
+});
+
+let testDb: BunTestDb;
+let testRedis: TestRedis;
+let registry: Registry;
+let jobRunner: JobRunner;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  testRedis = await createTestRedis();
+  await unsafePushTables(testDb.db, { fw2914_job_items: itemsTable });
+  await insertOne(testDb.db, itemsTable, { tenantId: ownTenant, label: "own" });
+  await insertOne(testDb.db, itemsTable, { tenantId: foreignTenant, label: "foreign" });
+
+  registry = createRegistry([jobsFeature]);
+  const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+  jobRunner = createJobRunner({
+    registry,
+    context: {
+      db: testDb.db,
+      _escapeHatchAuditSink: async (event) => {
+        auditEvents.push(event);
+      },
+    },
+    redisUrl,
+    consumerLane: "worker",
+    queueNamePrefix: `kumiko-job-tenant-db-test-${Date.now()}`,
+    getActiveTenantIds: async () => [ownTenant],
+  });
+  await jobRunner.start();
+});
+
+afterAll(async () => {
+  await jobRunner.stop();
+  await testDb.cleanup();
+  await testRedis.cleanup();
+});
+
+describe("JobContext.db (fw#2914)", () => {
+  test("is tenant-filtered to the job's tenant and unsafeRaw is denied without escapeHatch", async () => {
+    outcomes.length = 0;
+    auditEvents.length = 0;
+    await jobRunner.dispatch("jobtenantdb:job:undeclared", { tenantId: ownTenant });
+
+    await waitFor(() => {
+      const outcome = outcomes.find((o) => o.job === "undeclared");
+      expect(outcome).toBeDefined();
+      expect(outcome?.mode).toBe("tenant");
+      expect(outcome?.tenantId).toBe(ownTenant);
+      expect(outcome?.labels).toEqual(["own"]);
+      expect(outcome?.foreignWhereLabels).toEqual(["own"]);
+      expect(outcome?.unsafeRawDenied).toBe(true);
+    });
+    expect(auditEvents).toHaveLength(0);
+  });
+
+  test("escapeHatch on r.job grants unfiltered access and reports one unsafe-raw audit event", async () => {
+    outcomes.length = 0;
+    auditEvents.length = 0;
+    await jobRunner.dispatch("jobtenantdb:job:declared", { tenantId: ownTenant });
+
+    await waitFor(() => {
+      const outcome = outcomes.find((o) => o.job === "declared");
+      expect(outcome?.rawLabels).toEqual(["foreign", "own"]);
+      expect(auditEvents).toHaveLength(1);
+    });
+    expect(auditEvents[0]).toMatchObject({
+      handler: "jobtenantdb:job:declared",
+      kind: "unsafe-raw",
+      reason: DECLARED_REASON,
+      tenantId: ownTenant,
+    });
+  });
+
+  test("r.job rejects an escapeHatch with an empty reason at registration", () => {
+    const register = () =>
+      defineFeature("jobtenantdb-empty", (r) => {
+        r.job("bad", { trigger: { manual: true }, escapeHatch: { reason: "   " } }, async () => {});
+      });
+    expect(register).toThrow(/r\.job\("bad"\) declares \{ escapeHatch: \{ reason: "" \} \}/);
+  });
+
+  test("JobContext.db is not assignable to a raw DbRunner", () => {
+    const acceptsRunner = (runner: DbRunner): DbRunner => runner;
+    const ctx = { db: undefined } as unknown as JobContext;
+    // @ts-expect-error — JobContext.db is a TenantDb, not a raw DbRunner (fw#2914)
+    const leaked = () => acceptsRunner(ctx.db);
+    expect(typeof leaked).toBe("function");
+  });
+});

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

@@ -2,6 +2,7 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { Queue } from "bullmq";
 import { z } from "zod";
 import { requestContext } from "../../api/request-context";
+import { tenantDbRunner } from "../../db/tenant-db-runner";
 import { createRegistry, defineFeature } from "../../engine";
 import type {
   AppContext,
@@ -910,7 +911,7 @@ describe("perTenant across multiple runner instances", () => {
         async (_payload, ctx) => {
           log.push({
             tenantId: String(ctx.systemUser.tenantId),
-            runnerTag: ctx.db as unknown as string, // @cast-boundary test fixture
+            runnerTag: tenantDbRunner(ctx.db) as unknown as string, // @cast-boundary test fixture — runner context db is a tag string
           });
         },
       );
@@ -1012,7 +1013,7 @@ describe("perTenant across multiple runner instances", () => {
         await sleep(80);
         log.push({
           tenantId: String(ctx.systemUser.tenantId),
-          runnerTag: ctx.db as unknown as string, // @cast-boundary test fixture
+          runnerTag: tenantDbRunner(ctx.db) as unknown as string, // @cast-boundary test fixture — runner context db is a tag string
         });
       });
     });

package/src/jobs/job-runner.ts

@@ -2,7 +2,7 @@ import { Queue, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context";
 import type { DbConnection, DbRow } from "../db/connection";
-import { createTenantDb, createUncheckedSystemDb } from "../db/tenant-db";
+import { createTenantDb, createUncheckedSystemDb, type TenantDb } from "../db/tenant-db";
 import { createDerivativesContext } from "../derivatives/derivatives-context";
 import { createSystemUser } from "../engine/system-user";
 import {
@@ -551,20 +551,24 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     // unchecked cross-tenant escape hatch for such a job.
     const tenantScopedDb = configDb ? createTenantDb(configDb, tenantId, "system") : undefined;
     const isSystemJob = registry.isJobSystemScoped(jobName);
+    // One reporter for ctx.systemDb and ctx.db.unsafeRaw() so both dedupe in the same window.
+    const reportEscapeHatch = createEscapeHatchReporter({
+      handler: jobName,
+      tenantId,
+      actor: jobSystemUser.id,
+      sink: context._escapeHatchAuditSink,
+      log: context.log,
+    });
     const systemDb =
       isSystemJob && tenantScopedDb
-        ? createUncheckedSystemDb(
-            tenantScopedDb,
-            undefined,
-            createEscapeHatchReporter({
-              handler: jobName,
-              tenantId,
-              actor: jobSystemUser.id,
-              sink: context._escapeHatchAuditSink,
-              log: context.log,
-            }),
-          )
+        ? createUncheckedSystemDb(tenantScopedDb, undefined, reportEscapeHatch)
         : undefined;
+    const jobDb = configDb
+      ? createTenantDb(configDb, tenantId, "tenant", context.tracer, context.meter, undefined, {
+          unsafeRaw: jobDef.escapeHatch,
+          report: reportEscapeHatch,
+        })
+      : undefined;
     const config =
       context._configAccessorFactory && tenantScopedDb
         ? context._configAccessorFactory({
@@ -589,9 +593,8 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     let memberReader: MemberReader | undefined;
     const jobContext: JobContext = {
       ...context,
-      // Same union as configDb above — job runners are always constructed
-      // with a real DbConnection; JobContext requires it non-optional.
-      db: configDb as DbConnection, // @cast-boundary db-operator
+      // Undefined only for a runner built without a db; JobContext requires db non-optional.
+      db: jobDb as TenantDb, // @cast-boundary db-operator
       files,
       derivatives,
       ...(notify !== undefined && { notify }),