@cosmicdrift/kumiko-bundled-features 0.274.0 → 0.276.0

package/src/files-tenant-data/__tests__/hooks.integration.test.ts

@@ -57,7 +57,6 @@ import {
   TENANT_DESTRUCTION_STARTED_EVENT_QN,
 } from "../../tenant-lifecycle/constants";
 import { runTenantDestructionSweep } from "../../tenant-lifecycle/run-tenant-destroy";
-import { sweepOrphanedDerivativesJob } from "../handlers/sweep-orphaned-derivatives.job";
 import { createFilesTenantDataFeature } from "../index";
 
 const SET_PROFILE = "compliance-profiles:write:set-profile";
@@ -181,7 +180,10 @@ describe("files-tenant-data :: job registration", () => {
   test("registers sweepOrphanedDerivativesJob as files-tenant-data:job:sweep-orphaned-derivatives — the name jobs:write:trigger dispatches by", () => {
     const job = stack.registry.getJob(SWEEP_JOB);
     expect(job).toBeDefined();
-    expect(job?.handler).toBe(sweepOrphanedDerivativesJob);
+    expect(typeof job?.handler).toBe("function");
+    expect(job?.escapeHatch?.reason).toBe(
+      "iterates every tenant and checks fileRef owners per tenant",
+    );
     expect(job?.trigger).toEqual({ manual: true });
   });
 });

package/src/files-tenant-data/__tests__/sweep-orphaned-derivatives.job.integration.test.ts

@@ -64,7 +64,7 @@ function makeCtx(
   log: JobContext["log"] = noopLogger,
 ): JobContext {
   return {
-    db: stack.db,
+    db: createTenantDb(stack.db, tenantA.tenantId, "tenant"),
     registry: stack.registry,
     systemUser: tenantA,
     log,
@@ -151,6 +151,7 @@ describe("sweepOrphanedDerivativesJob", () => {
     await sweepOrphanedDerivativesJob(
       {},
       makeCtx(async () => provider),
+      stack.db,
     );
 
     expect(await provider.exists(orphan)).toBe(false);
@@ -167,6 +168,7 @@ describe("sweepOrphanedDerivativesJob", () => {
     await sweepOrphanedDerivativesJob(
       {},
       makeCtx(async () => provider),
+      stack.db,
     );
 
     expect(await provider.exists(derivative)).toBe(true);
@@ -197,6 +199,7 @@ describe("sweepOrphanedDerivativesJob", () => {
     await sweepOrphanedDerivativesJob(
       {},
       makeCtx(async () => provider),
+      stack.db,
     );
 
     // A trashed (soft-deleted) row still legitimately backs its derivatives —
@@ -214,6 +217,7 @@ describe("sweepOrphanedDerivativesJob", () => {
     await sweepOrphanedDerivativesJob(
       { dryRun: true },
       makeCtx(async () => provider, log),
+      stack.db,
     );
 
     // Existence alone can't distinguish "correctly found and would delete the
@@ -240,6 +244,7 @@ describe("sweepOrphanedDerivativesJob", () => {
     await sweepOrphanedDerivativesJob(
       {},
       makeCtx(async () => provider),
+      stack.db,
     );
 
     expect(await provider.exists(orphanA)).toBe(false);
@@ -253,7 +258,7 @@ describe("sweepOrphanedDerivativesJob", () => {
     const orphan = derivativeOf(original);
     await provider.write(orphan, new Uint8Array([1]));
 
-    await expect(sweepOrphanedDerivativesJob({}, makeCtx())).resolves.toBeUndefined();
+    await expect(sweepOrphanedDerivativesJob({}, makeCtx(), stack.db)).resolves.toBeUndefined();
 
     expect(await provider.exists(orphan)).toBe(true);
   });
@@ -268,6 +273,7 @@ describe("sweepOrphanedDerivativesJob", () => {
     await sweepOrphanedDerivativesJob(
       {},
       makeCtx(async () => provider),
+      stack.db,
     );
 
     expect(await provider.exists(original)).toBe(true);

package/src/files-tenant-data/changes.json

@@ -1 +1,9 @@
-[]
+[
+  {
+    "version": "0.275.0",
+    "type": "breaking",
+    "title": "sweepOrphanedDerivativesJob takes the raw DbConnection as a third argument; the job declares escapeHatch (fw#2914).",
+    "detail": "JobContext.db is now a tenant-filtered TenantDb. The sweep checks fileRef owners of every tenant, so its registration declares `escapeHatch` and passes `ctx.db.unsafeRaw(reason)` to `sweepOrphanedDerivativesJob(payload, ctx, db)`. Without the raw runner, the foreign-tenant owner lookup would be narrowed away and every derivative would look orphaned.",
+    "migration": "Direct callers of the exported `sweepOrphanedDerivativesJob` pass the raw `DbConnection` as the third argument. Apps that only mount the feature need no change."
+  }
+]

package/src/files-tenant-data/handlers/sweep-orphaned-derivatives.job.ts

@@ -19,9 +19,9 @@
 // handling still applies per-key.
 
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { parseDerivativeKey } from "@cosmicdrift/kumiko-framework/derivatives";
-import type { JobHandlerFn, TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import type { JobContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   assertSafeStorageKey,
   type FileProviderResolver,
@@ -50,17 +50,12 @@ type DerivativeCandidate = {
   readonly provider: FileStorageProvider;
 };
 
-export const sweepOrphanedDerivativesJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
+export async function sweepOrphanedDerivativesJob(
+  rawPayload: Record<string, unknown>,
+  ctx: JobContext,
+  db: DbConnection,
+): Promise<void> {
   const payload = sweepOrphanedDerivativesPayloadSchema.parse(rawPayload ?? {});
-  if (!ctx.db) {
-    throw new InternalError({
-      message:
-        "[files-tenant-data:sweep] ctx.db missing — job context requires a database connection.",
-    });
-  }
-  const db = ctx.db;
-  // Re-bound to a definitely-assigned const: TS control-flow narrowing from
-  // the guard above doesn't cross into fillQueue's nested closure below.
   const maybeResolver = ctx._fileProviderResolver;
   if (!maybeResolver) {
     ctx.log?.warn(
@@ -170,4 +165,4 @@ export const sweepOrphanedDerivativesJob: JobHandlerFn = async (rawPayload, ctx)
   ctx.log?.info?.(
     `[files-tenant-data:sweep] complete dryRun=${dryRun} deleted=${outcome.migrated} wouldDelete=${dryRunWouldDelete} skipped=${outcome.skipped} failed=${outcome.failed} batches=${outcome.batchesProcessed} stoppedReason=${outcome.stoppedReason}`,
   );
-};
+}

package/src/files-tenant-data/index.ts

@@ -11,6 +11,7 @@
 // fileRef entity exists and the hooks work fine — same reasoning as
 // folders-user-data's optionalRequires("folders").
 
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import {
   defineFeature,
   EXT_STORAGE_PROVIDER,
@@ -39,15 +40,23 @@ export function createFilesTenantDataFeature(): FeatureDefinition {
     r.useExtension(EXT_TENANT_DATA, "fileRef", { destroy: fileRefTenantDestroyHook });
     r.useExtension(EXT_STORAGE_PROVIDER, "fileRef", { destroyTenant: fileRefStorageDestroyHook });
 
-    r.job(
-      "sweep-orphaned-derivatives",
-      {
-        trigger: { manual: true },
-        concurrency: "skip",
-        schema: sweepOrphanedDerivativesPayloadSchema,
+    r.job({
+      name: "sweep-orphaned-derivatives",
+      trigger: { manual: true },
+      concurrency: "skip",
+      schema: sweepOrphanedDerivativesPayloadSchema,
+      escapeHatch: {
+        reason: "iterates every tenant and checks fileRef owners per tenant",
       },
-      sweepOrphanedDerivativesJob,
-    );
+      handler: (payload, ctx) =>
+        sweepOrphanedDerivativesJob(
+          payload,
+          ctx,
+          ctx.db.unsafeRaw(
+            "iterates every tenant and checks fileRef owners per tenant",
+          ) as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+        ),
+    });
   });
 }
 

package/src/form-draft/feature.ts

@@ -5,6 +5,7 @@
 // savedAt } through save/discard/get. See entity.ts for the ownership +
 // uniqueness model.
 
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature, type FeatureRegistrar } from "@cosmicdrift/kumiko-framework/engine";
 import { FORM_DRAFT_FEATURE_NAME } from "./constants";
 import { formDraftEntity } from "./entity";
@@ -39,7 +40,18 @@ function registerFormDraft(r: FeatureRegistrar<typeof FORM_DRAFT_FEATURE_NAME>):
   r.queryHandler(listDraftsQuery);
 
   r.config({ keys: { retentionDays: formDraftRetentionDaysConfig } });
-  r.job("cleanup", { trigger: { cron: "0 3 * * *" }, concurrency: "skip" }, cleanupDraftsJob);
+  r.job({
+    name: "cleanup",
+    trigger: { cron: "0 3 * * *" },
+    concurrency: "skip",
+    escapeHatch: { reason: "purges stale drafts of every tenant" },
+    handler: (payload, ctx) =>
+      cleanupDraftsJob(
+        payload,
+        ctx,
+        ctx.db.unsafeRaw("purges stale drafts of every tenant") as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+      ),
+  });
 }
 
 export const formDraftFeature = defineFeature(FORM_DRAFT_FEATURE_NAME, registerFormDraft);

package/src/form-draft/handlers/cleanup.job.ts

@@ -17,12 +17,11 @@ import {
   type ConfigKeyDefinition,
   createSystemConfig,
   createSystemUser,
-  type JobHandlerFn,
+  type JobContext,
   SYSTEM_TENANT_ID,
   SYSTEM_USER_ID,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { fileRefEntity, fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 import {
   isDraftStillStale,
@@ -150,14 +149,11 @@ async function deleteStaleDraftsBatch(
   return deletedRows;
 }
 
-export const cleanupDraftsJob: JobHandlerFn = async (_payload, ctx) => {
-  if (!ctx.db) {
-    throw new InternalError({
-      message: "[form-draft:cleanup] ctx.db required (JobContext incomplete)",
-    });
-  }
-  const db = ctx.db as DbConnection;
-
+export async function cleanupDraftsJob(
+  _payload: Record<string, unknown>,
+  ctx: JobContext,
+  db: DbConnection,
+): Promise<void> {
   const resolved = ctx.configResolver
     ? await ctx.configResolver.get(
         FORM_DRAFT_RETENTION_DAYS_CONFIG_KEY,
@@ -201,4 +197,4 @@ export const cleanupDraftsJob: JobHandlerFn = async (_payload, ctx) => {
     if (deletedRows.length === 0 || batch.length < DEFAULT_BATCH_SIZE) break;
   }
   ctx.log?.info?.(`[form-draft:cleanup] deleted=${deleted} retentionDays=${retentionDays}`);
-};
+}

package/src/inbound-mail-foundation/feature.ts

@@ -203,18 +203,22 @@ export const inboundMailFoundationFeature = defineFeature(INBOUND_MAIL_FOUNDATIO
     destroy: mailThreadTenantDestroyHook,
   });
 
-  // Data-Retention (#957) — perTenant-Fan-out (ein Run pro Tenant, wie
-  // data-retention:retention-cleanup): die job-DB ist NICHT tenant-scoped,
-  // der Sweep scoped jeden Delete explizit per tenantId. Ohne diesen Cron
-  // wachsen read_inbound_messages + die Bodies unbegrenzt (DSGVO Art. 5).
-  r.job(
-    "inbound-mail-retention",
-    { trigger: { cron: "0 3 * * *" }, perTenant: true, concurrency: "skip" },
-    async (_payload, ctx) => {
-      if (!ctx.db || !ctx.registry) {
-        throw new Error(
-          "inbound-mail-retention: ctx.db + ctx.registry required (JobContext incomplete)",
-        );
+  // Data-Retention (#957) — perTenant fan-out (one run per tenant, like
+  // data-retention:retention-cleanup): runInboundMailRetention's raw query
+  // helpers need the unfiltered runner, so the handler declares escapeHatch
+  // and reaches for ctx.db.unsafeRaw(). Without this cron, read_inbound_messages
+  // + the bodies grow unbounded (GDPR Art. 5).
+  const INBOUND_MAIL_RETENTION_REASON =
+    "inbound-mail retention runs raw deletes; every statement filters by this run's tenantId";
+  r.job({
+    name: "inbound-mail-retention",
+    trigger: { cron: "0 3 * * *" },
+    perTenant: true,
+    concurrency: "skip",
+    escapeHatch: { reason: INBOUND_MAIL_RETENTION_REASON },
+    handler: async (_payload, ctx) => {
+      if (!ctx.registry) {
+        throw new Error("inbound-mail-retention: ctx.registry required (JobContext incomplete)");
       }
       const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
       if (tenantId === undefined) {
@@ -222,7 +226,7 @@ export const inboundMailFoundationFeature = defineFeature(INBOUND_MAIL_FOUNDATIO
         return;
       }
       const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
-      const retentionDb = ctx.db as DbConnection; // @cast-boundary db-operator
+      const retentionDb = ctx.db.unsafeRaw(INBOUND_MAIL_RETENTION_REASON) as DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
 
       // Body-Objekte liegen in file-foundation. Provider lazy + memoized —
       // heute schreibt der Ingest kein bodyRef (storeBody-Hook ungebunden),
@@ -253,5 +257,5 @@ export const inboundMailFoundationFeature = defineFeature(INBOUND_MAIL_FOUNDATIO
         );
       }
     },
-  );
+  });
 });

package/src/jobs/__tests__/job-system-user.integration.test.ts

@@ -62,36 +62,45 @@ const billingFeature = defineFeature("billing", (r) => {
   // resolver.set escape hatch is gone. checkWriteAccess grants a
   // SYSTEM_ROLE caller the right to write system-only keys that Admin
   // cannot touch, so the security invariant (see Admin test below) holds.
-  r.job("calculateTotal", { trigger: { manual: true } }, async (_payload, ctx) => {
-    const systemUser = ctx["systemUser"] as SessionUser;
-    const jobDb = ctx["db"] as DbConnection;
-    const reg = ctx["registry"] as Registry;
-
-    ctx.log?.info("Calculating monthly total...");
-    const total = 42000;
-
-    const handler = reg.getWriteHandler("config:write:set");
-    if (handler) {
-      const parsed = handler.schema.parse({
-        key: "billing:config:monthly-total",
-        value: total,
-      });
-      const tenantDb = createTenantDb(jobDb, systemUser.tenantId, "system");
-      await handler.handler(
-        { type: "config:write:set", payload: parsed, user: systemUser },
-        {
-          db: tenantDb,
-          dbOutsideTransaction: tenantDb,
-          systemDb: createUncheckedSystemDb(tenantDb),
-          registry: reg,
-          configResolver: ctx["configResolver"] as ConfigResolver,
-          ...bridgeStub(),
-        },
-      );
-    }
-
-    ctx.log?.info(`Set monthlyTotal to ${total}`);
-  });
+  r.job(
+    "calculateTotal",
+    {
+      trigger: { manual: true },
+      escapeHatch: { reason: "test job builds a system-mode handler context for config:write:set" },
+    },
+    async (_payload, ctx) => {
+      const systemUser = ctx["systemUser"] as SessionUser;
+      const jobDb = ctx.db.unsafeRaw(
+        "test job builds a system-mode handler context for config:write:set",
+      ) as DbConnection;
+      const reg = ctx["registry"] as Registry;
+
+      ctx.log?.info("Calculating monthly total...");
+      const total = 42000;
+
+      const handler = reg.getWriteHandler("config:write:set");
+      if (handler) {
+        const parsed = handler.schema.parse({
+          key: "billing:config:monthly-total",
+          value: total,
+        });
+        const tenantDb = createTenantDb(jobDb, systemUser.tenantId, "system");
+        await handler.handler(
+          { type: "config:write:set", payload: parsed, user: systemUser },
+          {
+            db: tenantDb,
+            dbOutsideTransaction: tenantDb,
+            systemDb: createUncheckedSystemDb(tenantDb),
+            registry: reg,
+            configResolver: ctx["configResolver"] as ConfigResolver,
+            ...bridgeStub(),
+          },
+        );
+      }
+
+      ctx.log?.info(`Set monthlyTotal to ${total}`);
+    },
+  );
 });
 
 const configFeature = createConfigFeature();

package/src/jobs/__tests__/reindex-entity-job.integration.test.ts

@@ -100,7 +100,7 @@ describe("reindexEntityJob", () => {
     expect(preResults).toHaveLength(0);
 
     const ctx: JobContext = {
-      db: stack.db,
+      db: createTenantDb(stack.db, admin.tenantId),
       registry: stack.registry,
       searchAdapter: stack.search,
       systemUser: admin,
@@ -141,7 +141,7 @@ describe("reindexEntityJob", () => {
     if (!job) return;
 
     const ctx: JobContext = {
-      db: stack.db,
+      db: createTenantDb(stack.db, admin.tenantId),
       registry: stack.registry,
       searchAdapter: stack.search,
       systemUser: admin,
@@ -205,7 +205,7 @@ describe("reindexEntityJob", () => {
   test("fails closed when ctx.systemDb is scoped to a different tenant than ctx.systemUser", async () => {
     const otherTenantId = TestUsers.otherTenant.tenantId;
     const ctx: JobContext = {
-      db: stack.db,
+      db: createTenantDb(stack.db, admin.tenantId),
       registry: stack.registry,
       searchAdapter: stack.search,
       systemUser: admin,

package/src/jobs/handlers/retention-cleanup.job.ts

@@ -8,13 +8,15 @@ export const DEFAULT_JOB_RUN_RETENTION_DAYS = 30;
 
 export function createRetentionCleanupJob(retentionDays: number): JobHandlerFn {
   return async (_payload, ctx) => {
-    if (!ctx.db) {
+    if (!ctx.systemDb) {
       throw new InternalError({
         message:
-          "[jobs:retention-cleanup] ctx.db missing — job context requires a database connection.",
+          "[jobs:retention-cleanup] ctx.systemDb missing — is r.systemScope() still set on the jobs feature?",
       });
     }
-    const db = ctx.db as DbConnection; // @cast-boundary db-operator (matches sibling cron jobs)
+    const db = ctx.systemDb.unsafeRaw(
+      "store_job_runs retention purges finished runs of every tenant",
+    ) as DbConnection; // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
     const result = await deleteStaleJobRuns(db, retentionDays);
     ctx.log?.info?.(`[jobs:retention-cleanup] complete: ${JSON.stringify(result)}`);
   };

package/src/jobs/handlers/stale-run-sweep.job.ts

@@ -15,13 +15,15 @@ export const DEFAULT_JOB_RUN_STALE_TIMEOUT_HOURS = 24;
 
 export function createStaleRunSweepJob(timeoutHours: number): JobHandlerFn {
   return async (_payload, ctx) => {
-    if (!ctx.db) {
+    if (!ctx.systemDb) {
       throw new InternalError({
         message:
-          "[jobs:stale-run-sweep] ctx.db missing — job context requires a database connection.",
+          "[jobs:stale-run-sweep] ctx.systemDb missing — is r.systemScope() still set on the jobs feature?",
       });
     }
-    const db = ctx.db as DbConnection; // @cast-boundary db-operator (matches sibling cron jobs)
+    const db = ctx.systemDb.unsafeRaw(
+      "stale-run sweep marks stuck runs of every tenant as failed",
+    ) as DbConnection; // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
     const result = await markStaleJobRunsFailed(db, timeoutHours);
     ctx.log?.info?.(`[jobs:stale-run-sweep] complete: ${JSON.stringify(result)}`);
   };

package/src/presets/__tests__/security-baseline.test.ts

@@ -1,8 +1,29 @@
 import { describe, expect, test } from "bun:test";
-import { SECURITY_BASELINE_FEATURE_NAMES } from "@cosmicdrift/kumiko-framework/engine";
+import { createAuthEmailPasswordFeature } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { createCryptoShreddingFeature } from "@cosmicdrift/kumiko-bundled-features/crypto-shredding";
+import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
+import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
+import { createUserDataRightsDefaultsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights-defaults";
+import {
+  createRegistry,
+  defineFeature,
+  SECURITY_BASELINE_FEATURE_NAMES,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { dsgvoSelfServiceFeatures } from "../dsgvo-self-service";
 import { securityBaselineFeatures } from "../security-baseline";
 
+// Minimal host every combo below needs: sessions requires user +
+// auth-foundation, audit requires tenant, tenant requires config.
+const HOST_FEATURES = [
+  createConfigFeature(),
+  createUserFeature(),
+  createTenantFeature(),
+  authFoundationFeature,
+];
+
 describe("securityBaselineFeatures", () => {
   test("returns exactly the SECURITY_BASELINE_FEATURE_NAMES feature names", () => {
     const names = securityBaselineFeatures().map((f) => f.name);
@@ -32,4 +53,42 @@ describe("securityBaselineFeatures", () => {
     const b = securityBaselineFeatures();
     expect(a[0]).not.toBe(b[0]);
   });
+
+  test("dsgvoSelfServiceFeatures() + securityBaselineFeatures() boots with exactly one sessions", () => {
+    // user-data-rights-defaults additionally requires "files" — a bare stub
+    // is enough here, its own domain logic isn't exercised by this test.
+    const filesStub = defineFeature("files", () => {});
+    const registry = createRegistry([
+      ...HOST_FEATURES,
+      createAuthEmailPasswordFeature({}),
+      filesStub,
+      createUserDataRightsDefaultsFeature(),
+      ...dsgvoSelfServiceFeatures(),
+      ...securityBaselineFeatures(),
+    ]);
+
+    expect(registry.getFeature("sessions")).toBeDefined();
+  });
+
+  test("standalone sessions + crypto-shredding mounted alongside the preset boots (offlot case)", () => {
+    const registry = createRegistry([
+      ...HOST_FEATURES,
+      createSessionsFeature(),
+      createCryptoShreddingFeature(),
+      ...securityBaselineFeatures(),
+    ]);
+
+    expect(registry.getFeature("sessions")).toBeDefined();
+    expect(registry.getFeature("crypto-shredding")).toBeDefined();
+  });
+
+  test("sessions mounted with different options than the preset's throws a clear boot error", () => {
+    expect(() =>
+      createRegistry([
+        ...HOST_FEATURES,
+        createSessionsFeature({ expiresInMs: 1000 }),
+        ...securityBaselineFeatures(),
+      ]),
+    ).toThrow(/Duplicate feature: "sessions".*different options/);
+  });
 });

package/src/presets/security-baseline.ts

@@ -8,8 +8,7 @@ export type SecurityBaselineOptions = {
   readonly includeSessions?: boolean;
 };
 
-// includeSessions: false when dsgvoSelfServiceFeatures() already mounts sessions (duplicate
-// feature names throw); host app must mount user, tenant, auth-foundation (sessions/audit requires).
+// Host app must mount user, tenant, auth-foundation (sessions/audit requires).
 export function securityBaselineFeatures(opts: SecurityBaselineOptions = {}): FeatureDefinition[] {
   return [
     ...(opts.includeSessions !== false ? [createSessionsFeature()] : []),

package/src/rate-limiting/feature.ts

@@ -10,15 +10,19 @@ import { rateLimitStatus } from "./handlers/status.query";
 // only use L3 (handler-opt-in) and don't need ops introspection can
 // skip this feature entirely — the resolver still runs.
 export function createRateLimitingFeature() {
-  return defineFeature("rate-limiting", (r) => {
-    r.describe(
-      "Adds an ops-side `rate-limiting:query:status` query handler for inspecting current bucket state; the actual request throttling is wired automatically by the dispatcher when any handler declares a `rateLimit` option (e.g. `{ per: 'user', limit: 3, windowSeconds: 60 }`) or when you pass `context.rateLimit` to `buildServer`. Loading this feature is optional if you only need L3 per-handler rate limits and have no need for ops introspection.",
-    );
-    r.uiHints({
-      displayLabel: "Rate Limiting · Ops Query",
-      category: "operations",
-      recommended: false,
-    });
-    r.queryHandler(rateLimitStatus);
-  });
+  return defineFeature(
+    "rate-limiting",
+    (r) => {
+      r.describe(
+        "Adds an ops-side `rate-limiting:query:status` query handler for inspecting current bucket state; the actual request throttling is wired automatically by the dispatcher when any handler declares a `rateLimit` option (e.g. `{ per: 'user', limit: 3, windowSeconds: 60 }`) or when you pass `context.rateLimit` to `buildServer`. Loading this feature is optional if you only need L3 per-handler rate limits and have no need for ops introspection.",
+      );
+      r.uiHints({
+        displayLabel: "Rate Limiting · Ops Query",
+        category: "operations",
+        recommended: false,
+      });
+      r.queryHandler(rateLimitStatus);
+    },
+    { dedupeOptions: {} },
+  );
 }

package/src/secrets/__tests__/rotate.integration.test.ts

@@ -140,7 +140,7 @@ describe("rotate-job circuit-breaker", () => {
 
     // maxFailures: 3 means the job gives up after 3 failed rows. Without
     // the breaker it would attempt all 20 and log 20 warns.
-    await rotateJob({ batchSize: 10, maxFailures: 3 }, jobCtx(broken));
+    await rotateJob({ batchSize: 10, maxFailures: 3 }, jobCtx(broken), stack.db);
 
     // All 20 rows still at V1 — the broken provider never let any rewrap
     // succeed. Plus: the breaker tripped at ≤3 attempts, not 20.
@@ -151,7 +151,7 @@ describe("rotate-job circuit-breaker", () => {
   test("maxFailures=1 trips on the very first failure — single attempt then stop", async () => {
     const broken = createBrokenUnwrapProvider();
 
-    await rotateJob({ batchSize: 10, maxFailures: 1 }, jobCtx(broken));
+    await rotateJob({ batchSize: 10, maxFailures: 1 }, jobCtx(broken), stack.db);
 
     // Same end-state (all rows on V1) but the internal counter proves the
     // breaker fired after exactly one failure instead of draining the batch.
@@ -167,7 +167,7 @@ describe("rotate-job circuit-breaker", () => {
     // honours its parameter rather than silently capping.
     const broken = createBrokenUnwrapProvider();
 
-    await rotateJob({ batchSize: 10, maxFailures: 25 }, jobCtx(broken));
+    await rotateJob({ batchSize: 10, maxFailures: 25 }, jobCtx(broken), stack.db);
 
     expect(await countV1Rows()).toBe(20);
     expect(broken.calls()).toBe(25);
@@ -205,7 +205,7 @@ describe("rotate-job circuit-breaker", () => {
     );
     const ciphertextByKey = new Map(preRotation.map((row) => [row.key, row.envelope.ciphertext]));
 
-    await rotateJob({ batchSize: 10, maxFailures: 5 }, jobCtx(rotator));
+    await rotateJob({ batchSize: 10, maxFailures: 5 }, jobCtx(rotator), stack.db);
 
     expect(await countV1Rows()).toBe(0);
 

package/src/secrets/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.275.0",
+    "type": "breaking",
+    "title": "rotateJob takes the raw DbConnection as a third argument; the rotate job declares escapeHatch (fw#2914).",
+    "detail": "JobContext.db is now a tenant-filtered TenantDb. Rotation re-encrypts every tenant's secrets, so the `rotate` registration declares `escapeHatch` and passes `ctx.db.unsafeRaw(reason)` to `rotateJob(payload, ctx, db)`.",
+    "migration": "Direct callers of the exported `rotateJob` pass the raw `DbConnection` as the third argument. Apps that only mount the feature need no change."
+  },
   {
     "version": "0.166.0",
     "type": "improvement",

package/src/secrets/feature.ts

@@ -1,3 +1,4 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import {
   type AccessRule,
   defineFeature,
@@ -157,16 +158,30 @@ export function createSecretsFeature(opts: SecretsFeatureOptions = {}): FeatureD
 
     // Per-tenant handlers (set/delete/list) run in the default tenant-scope,
     // giving them the automatic ctx.db tenant-filter as extra defense.
-    // The rotation job deliberately reaches for ctx.db as DbConnection
-    // (raw, cross-tenant) because rotation is a deployment-wide operation —
-    // no feature-wide r.systemScope() needed.
+    // The rotation job deliberately reaches for ctx.db.unsafeRaw() (raw,
+    // cross-tenant) because rotation is a deployment-wide operation — no
+    // feature-wide r.systemScope() needed.
     r.writeHandler(createSetHandler(access));
     r.writeHandler(createDeleteHandler(access));
     r.queryHandler(createListHandler(access));
     // Manual-only by design: ops triggers rotation after a KEK version flip.
     // BullMQ delivers to exactly one worker, so running it against a busy
     // table on multiple instances is still safe.
-    r.job("rotate", { trigger: { manual: true } }, rotateJob);
+    r.job({
+      name: "rotate",
+      trigger: { manual: true },
+      escapeHatch: {
+        reason: "re-encrypts every tenant's secrets with the new master key",
+      },
+      handler: (payload, ctx) =>
+        rotateJob(
+          payload,
+          ctx,
+          ctx.db.unsafeRaw(
+            "re-encrypts every tenant's secrets with the new master key",
+          ) as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+        ),
+    });
 
     // Pre-ES had a separate `retention-cleanup` job scrubbing the audit
     // table on a compliance-driven schedule (90d default). Post-ES the