@cosmicdrift/kumiko-bundled-features 0.274.0 → 0.275.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.274.0",
+  "version": "0.275.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -129,12 +129,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.274.0",
-    "@cosmicdrift/kumiko-framework": "0.274.0",
-    "@cosmicdrift/kumiko-headless": "0.274.0",
-    "@cosmicdrift/kumiko-renderer": "0.274.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.274.0",
-    "@cosmicdrift/kumiko-types": "0.274.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.275.0",
+    "@cosmicdrift/kumiko-framework": "0.275.0",
+    "@cosmicdrift/kumiko-headless": "0.275.0",
+    "@cosmicdrift/kumiko-renderer": "0.275.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.275.0",
+    "@cosmicdrift/kumiko-types": "0.275.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -163,7 +163,7 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.274.0",
-    "@cosmicdrift/kumiko-locale-es": "0.274.0"
+    "@cosmicdrift/kumiko-locale-de": "0.275.0",
+    "@cosmicdrift/kumiko-locale-es": "0.275.0"
   }
 }

package/src/__tests__/cross-tenant-jobs-escape-hatch.test.ts

@@ -0,0 +1,45 @@
+// fw#2914 — JobContext.db is tenant-filtered; these bundled jobs reach every tenant
+// and only work because their registration declares escapeHatch.
+import { describe, expect, test } from "bun:test";
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createAuthMfaFeature } from "../auth-mfa/feature";
+import { createDataRetentionFeature } from "../data-retention/feature";
+import { createFilesTenantDataFeature } from "../files-tenant-data";
+import { formDraftFeature } from "../form-draft/feature";
+import { inboundMailFoundationFeature } from "../inbound-mail-foundation/feature";
+import { createSecretsFeature } from "../secrets/feature";
+import { createSessionsFeature } from "../sessions/feature";
+import { createTenantLifecycleFeature } from "../tenant-lifecycle/feature";
+import { createUserDataRightsFeature } from "../user-data-rights/feature";
+
+const TEST_SECRET = "cross-tenant-jobs-escape-hatch-test-secret-0123456789";
+
+const crossTenantJobs: ReadonlyArray<readonly [FeatureDefinition, string]> = [
+  [
+    createAuthMfaFeature({
+      setupTokenSecret: TEST_SECRET,
+      challengeTokenSecret: `${TEST_SECRET}-challenge`,
+      issuer: "Kumiko",
+    }),
+    "reencrypt",
+  ],
+  [createDataRetentionFeature(), "retention-cleanup"],
+  [createFilesTenantDataFeature(), "sweep-orphaned-derivatives"],
+  [formDraftFeature, "cleanup"],
+  [inboundMailFoundationFeature, "inbound-mail-retention"],
+  [createSecretsFeature(), "rotate"],
+  [createSessionsFeature(), "cleanup"],
+  [createTenantLifecycleFeature(), "run-tenant-destruction"],
+  [createUserDataRightsFeature(), "run-export-jobs"],
+  [createUserDataRightsFeature(), "run-forget-cleanup"],
+];
+
+describe("bundled cross-tenant jobs declare escapeHatch (fw#2914)", () => {
+  for (const [feature, jobName] of crossTenantJobs) {
+    test(`${feature.name}:${jobName}`, () => {
+      const job = feature.jobs[jobName];
+      expect(job).toBeDefined();
+      expect(job?.escapeHatch?.reason.trim().length ?? 0).toBeGreaterThan(20);
+    });
+  }
+});

package/src/audit/feature.ts

@@ -23,108 +23,112 @@ import { AUDIT_I18N } from "./i18n";
 // (tracked with the snapshot/archive infrastructure that already exists in
 // the framework).
 export function createAuditFeature(): FeatureDefinition {
-  return defineFeature("audit", (r) => {
-    r.describe(
-      "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
-    );
-    r.uiHints({
-      displayLabel: "Audit Log",
-      category: "compliance",
-      recommended: false,
-    });
-    r.translations({ keys: AUDIT_I18N });
-    // Screens resolve actor names via tenant:query:members.
-    r.requires("tenant");
+  return defineFeature(
+    "audit",
+    (r) => {
+      r.describe(
+        "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
+      );
+      r.uiHints({
+        displayLabel: "Audit Log",
+        category: "compliance",
+        recommended: false,
+      });
+      r.translations({ keys: AUDIT_I18N });
+      // Screens resolve actor names via tenant:query:members.
+      r.requires("tenant");
 
-    // Registered so ops tools/MSPs can discover the type — escape-hatch-audit-sink.ts appends it via the low-level event-store API.
-    r.defineEvent("escape-hatch-used", escapeHatchUsedSchema, { piiFields: "none" });
+      // Registered so ops tools/MSPs can discover the type — escape-hatch-audit-sink.ts appends it via the low-level event-store API.
+      r.defineEvent("escape-hatch-used", escapeHatchUsedSchema, { piiFields: "none" });
 
-    const queries = {
-      list: r.queryHandler(listQuery),
-      details: r.queryHandler(detailsQuery),
-    };
+      const queries = {
+        list: r.queryHandler(listQuery),
+        details: r.queryHandler(detailsQuery),
+      };
 
-    r.screen({
-      id: AUDIT_LOG_SCREEN_ID,
-      type: "projectionList",
-      query: AuditQueries.list,
-      columns: [
-        {
-          field: "createdAt",
-          label: i18nKey("audit.log.col.when"),
-          renderer: { format: "timestamp" },
-        },
-        { field: "type", label: i18nKey("audit.log.col.type") },
-        { field: "createdBy", label: i18nKey("audit.log.col.actor") },
-      ],
-      searchable: true,
-      defaultSort: { field: "createdAt", dir: "desc" },
-      rowActions: [
-        {
-          kind: "navigate",
-          id: "details",
-          label: i18nKey("audit.log.details"),
-          screen: AUDIT_LOG_DETAIL_SCREEN_ID,
-          entityId: "id",
-          rowClick: true,
-        },
-      ],
-      pagination: "infinite",
-      description:
-        "Admin table of the tenant's audit-trail events with actor names and event-type/date filters; open it to browse recent changes and drill into a single event.",
-      access: { roles: access.admin },
-    });
-    r.screen({
-      id: AUDIT_LOG_DETAIL_SCREEN_ID,
-      type: "projectionDetail",
-      query: AuditQueries.details,
-      idParam: "id",
-      fieldLabels: {
-        type: i18nKey("audit.log.col.type"),
-        createdAt: i18nKey("audit.log.col.when"),
-        aggregateType: i18nKey("audit.log.col.aggregateType"),
-        aggregateId: i18nKey("audit.log.col.aggregateId"),
-        createdBy: i18nKey("audit.log.col.actor"),
-        id: i18nKey("audit.log.detail.field.id"),
-        payload: i18nKey("audit.log.detail.payload"),
-        metadata: i18nKey("audit.log.detail.metadata"),
-      },
-      layout: {
-        sections: [
-          {
-            fields: [
-              "type",
-              { field: "createdAt", renderer: { format: "timestamp" } },
-              "aggregateType",
-              "aggregateId",
-              "createdBy",
-              "id",
-            ],
-          },
-          // No section `title` here (fw#2312 label-dedup fix): each section
-          // holds exactly one field, so a title would repeat the field's own
-          // label (rendered by RenderField as the Field's heading) verbatim.
+      r.screen({
+        id: AUDIT_LOG_SCREEN_ID,
+        type: "projectionList",
+        query: AuditQueries.list,
+        columns: [
           {
-            fields: [{ field: "payload", renderer: { format: "json" } }],
+            field: "createdAt",
+            label: i18nKey("audit.log.col.when"),
+            renderer: { format: "timestamp" },
           },
+          { field: "type", label: i18nKey("audit.log.col.type") },
+          { field: "createdBy", label: i18nKey("audit.log.col.actor") },
+        ],
+        searchable: true,
+        defaultSort: { field: "createdAt", dir: "desc" },
+        rowActions: [
           {
-            fields: [{ field: "metadata", renderer: { format: "json" } }],
+            kind: "navigate",
+            id: "details",
+            label: i18nKey("audit.log.details"),
+            screen: AUDIT_LOG_DETAIL_SCREEN_ID,
+            entityId: "id",
+            rowClick: true,
           },
         ],
-      },
-      description:
-        "Read-only detail view of one audit event showing actor, timestamp, aggregate and the raw event payload and metadata; reached from a row of the audit log.",
-      listScreenId: AUDIT_LOG_SCREEN_ID,
-      access: { roles: access.admin },
-    });
-    r.nav({
-      id: "audit-log",
-      label: "audit:nav.auditLog",
-      icon: "file",
-      screen: "audit:screen:audit-log",
-      order: 30,
-    });
+        pagination: "infinite",
+        description:
+          "Admin table of the tenant's audit-trail events with actor names and event-type/date filters; open it to browse recent changes and drill into a single event.",
+        access: { roles: access.admin },
+      });
+      r.screen({
+        id: AUDIT_LOG_DETAIL_SCREEN_ID,
+        type: "projectionDetail",
+        query: AuditQueries.details,
+        idParam: "id",
+        fieldLabels: {
+          type: i18nKey("audit.log.col.type"),
+          createdAt: i18nKey("audit.log.col.when"),
+          aggregateType: i18nKey("audit.log.col.aggregateType"),
+          aggregateId: i18nKey("audit.log.col.aggregateId"),
+          createdBy: i18nKey("audit.log.col.actor"),
+          id: i18nKey("audit.log.detail.field.id"),
+          payload: i18nKey("audit.log.detail.payload"),
+          metadata: i18nKey("audit.log.detail.metadata"),
+        },
+        layout: {
+          sections: [
+            {
+              fields: [
+                "type",
+                { field: "createdAt", renderer: { format: "timestamp" } },
+                "aggregateType",
+                "aggregateId",
+                "createdBy",
+                "id",
+              ],
+            },
+            // No section `title` here (fw#2312 label-dedup fix): each section
+            // holds exactly one field, so a title would repeat the field's own
+            // label (rendered by RenderField as the Field's heading) verbatim.
+            {
+              fields: [{ field: "payload", renderer: { format: "json" } }],
+            },
+            {
+              fields: [{ field: "metadata", renderer: { format: "json" } }],
+            },
+          ],
+        },
+        description:
+          "Read-only detail view of one audit event showing actor, timestamp, aggregate and the raw event payload and metadata; reached from a row of the audit log.",
+        listScreenId: AUDIT_LOG_SCREEN_ID,
+        access: { roles: access.admin },
+      });
+      r.nav({
+        id: "audit-log",
+        label: "audit:nav.auditLog",
+        icon: "file",
+        screen: "audit:screen:audit-log",
+        order: 30,
+      });
 
-    return { queries };
-  });
+      return { queries };
+    },
+    { dedupeOptions: {} },
+  );
 }

package/src/auth-mfa/__tests__/reencrypt-job.integration.test.ts

@@ -147,7 +147,7 @@ describe("auth-mfa KEK-rotation job — kumiko-framework#266 Step 8", () => {
       }),
     );
 
-    await mfaReencryptJob({}, jobCtx());
+    await mfaReencryptJob({}, jobCtx(), stack.db);
 
     const afterJobRow = await readRawRow(user.id);
     expect(JSON.parse(afterJobRow.totpSecret).kekVersion).toBe(2);
@@ -222,12 +222,16 @@ describe("auth-mfa KEK-rotation job — unrecognized values are not silently ski
       child: () => capturingLog,
     };
 
-    await mfaReencryptJob({}, {
-      db: stack.db,
-      registry: stack.registry,
-      masterKeyProvider: mutableProvider,
-      log: capturingLog,
-    } as unknown as JobContext);
+    await mfaReencryptJob(
+      {},
+      {
+        db: stack.db,
+        registry: stack.registry,
+        masterKeyProvider: mutableProvider,
+        log: capturingLog,
+      } as unknown as JobContext,
+      stack.db,
+    );
 
     const completeLine = captured.info.find((line) =>
       line.includes("[auth-mfa:reencrypt] complete:"),
@@ -296,12 +300,16 @@ describe("auth-mfa KEK-rotation job — unrecognized values are not silently ski
       child: () => capturingLog,
     };
 
-    await mfaReencryptJob({}, {
-      db: stack.db,
-      registry: stack.registry,
-      masterKeyProvider: mutableProvider,
-      log: capturingLog,
-    } as unknown as JobContext);
+    await mfaReencryptJob(
+      {},
+      {
+        db: stack.db,
+        registry: stack.registry,
+        masterKeyProvider: mutableProvider,
+        log: capturingLog,
+      } as unknown as JobContext,
+      stack.db,
+    );
 
     const completeLine = captured.info.find((line) =>
       line.includes("[auth-mfa:reencrypt] complete:"),

package/src/auth-mfa/feature.ts

@@ -1,3 +1,4 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { mfaRequiredConfigKey } from "./config";
 import { createDisableHandler } from "./handlers/disable.write";
@@ -137,7 +138,21 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
     // KEK-rotation for totpSecret (entity-field encryption). Manual
     // trigger — ops runs it once after adding a new master key version,
     // same operator workflow as config's own reencrypt job.
-    r.job("reencrypt", { trigger: { manual: true } }, mfaReencryptJob);
+    r.job({
+      name: "reencrypt",
+      trigger: { manual: true },
+      escapeHatch: {
+        reason: "re-encrypts MFA secrets of every tenant's users with the new master key",
+      },
+      handler: (payload, ctx) =>
+        mfaReencryptJob(
+          payload,
+          ctx,
+          ctx.db.unsafeRaw(
+            "re-encrypts MFA secrets of every tenant's users with the new master key",
+          ) as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+        ),
+    });
 
     r.entity("user-mfa", userMfaEntity);
 

package/src/auth-mfa/handlers/reencrypt.job.ts

@@ -36,7 +36,7 @@ import {
   type DbConnection,
   type TenantDb,
 } from "@cosmicdrift/kumiko-framework/db";
-import type { JobHandlerFn, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { JobContext, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
 import {
@@ -70,7 +70,11 @@ export type MfaReencryptJobResult = {
   readonly stoppedReason: ChunkedMigrationStopReason;
 };
 
-export const mfaReencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
+export async function mfaReencryptJob(
+  rawPayload: Record<string, unknown>,
+  ctx: JobContext,
+  db: DbConnection,
+): Promise<void> {
   const payload = rawPayload as MfaReencryptJobPayload; // @cast-boundary engine-payload
   const maybeCipher = configuredEntityFieldEncryption();
   if (!maybeCipher) {
@@ -91,12 +95,6 @@ export const mfaReencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<vo
     });
   }
   const provider = ctx.masterKeyProvider;
-  if (!ctx.db) {
-    throw new InternalError({
-      message: "[auth-mfa:reencrypt] ctx.db missing — job context requires a database connection.",
-    });
-  }
-  const db = ctx.db as DbConnection; // @cast-boundary db-operator
   // Undefined = per-subject crypto-shredding isn't configured for this app —
   // both fields are then plain envelope strings, no PII layer to peel.
   const piiKms = configuredPiiSubjectKms();
@@ -222,4 +220,4 @@ export const mfaReencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<vo
     stoppedReason: outcome.stoppedReason,
   };
   ctx.log?.info?.(`[auth-mfa:reencrypt] complete: ${JSON.stringify(result)}`);
-};
+}

package/src/config/__tests__/reencrypt-job-concurrent-write-race.integration.test.ts

@@ -17,7 +17,11 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  createUncheckedSystemDb,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
   createSystemConfig,
@@ -152,7 +156,8 @@ function racyJobCtx(
     },
   };
   return {
-    db: stack.db,
+    db: createTenantDb(stack.db, SYSTEM_TENANT_ID),
+    systemDb: createUncheckedSystemDb(createTenantDb(stack.db, SYSTEM_TENANT_ID, "system")),
     registry: stack.registry,
     masterKeyProvider: mutableProvider,
     configEncryption: racyCipher,

package/src/config/__tests__/reencrypt-job-kek-rotation.integration.test.ts

@@ -10,7 +10,11 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  createUncheckedSystemDb,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
   createSystemConfig,
@@ -134,13 +138,15 @@ function capturingLog(captured: CapturedLog): TestJobLog {
 
 function jobCtx(captured?: CapturedLog): Parameters<typeof reencryptJob>[1] {
   const log = captured ? capturingLog(captured) : noopLog;
+  const systemModeDb = createTenantDb(stack.db, SYSTEM_TENANT_ID, "system");
   return {
-    db: stack.db,
+    db: systemModeDb,
+    systemDb: createUncheckedSystemDb(systemModeDb),
     registry: stack.registry,
     masterKeyProvider: mutableProvider,
     configEncryption: cipher,
     log,
-  } as unknown as Parameters<typeof reencryptJob>[1]; // @cast-boundary test-seam — job only reads db/registry/masterKeyProvider/configEncryption/log
+  } as unknown as Parameters<typeof reencryptJob>[1]; // @cast-boundary test-seam — job only reads db/systemDb/registry/masterKeyProvider/configEncryption/log
 }
 
 beforeAll(async () => {

package/src/config/__tests__/reencrypt-job-tenant-checks.integration.test.ts

@@ -12,12 +12,17 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  createUncheckedSystemDb,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
   createSystemUser,
   createTenantConfig,
   defineFeature,
+  SYSTEM_TENANT_ID,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { ESCAPE_HATCH_USED_SIGNAL } from "@cosmicdrift/kumiko-framework/pipeline";
 import {
@@ -111,7 +116,8 @@ function capturingLog(captured: CapturedLog): TestJobLog {
 
 function jobCtx(captured: CapturedLog): Parameters<typeof reencryptJob>[1] {
   return {
-    db: stack.db,
+    db: createTenantDb(stack.db, SYSTEM_TENANT_ID),
+    systemDb: createUncheckedSystemDb(createTenantDb(stack.db, SYSTEM_TENANT_ID, "system")),
     registry: stack.registry,
     masterKeyProvider: mutableProvider,
     configEncryption: cipher,

package/src/config/handlers/reencrypt.job.ts

@@ -87,17 +87,20 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
         "[config:reencrypt] ctx.masterKeyProvider missing — wire it via extraContext.masterKeyProvider at boot.",
     });
   }
-  if (!ctx.db) {
+  if (!ctx.registry) {
     throw new InternalError({
-      message: "[config:reencrypt] ctx.db missing — job context requires a database connection.",
+      message: "[config:reencrypt] ctx.registry missing — job context requires the registry.",
     });
   }
-  if (!ctx.registry) {
+  // config is r.systemScope(), so ctx.systemDb is always present on its jobs.
+  if (!ctx.systemDb) {
     throw new InternalError({
-      message: "[config:reencrypt] ctx.registry missing — job context requires the registry.",
+      message: "[config:reencrypt] ctx.systemDb missing on a system-scoped job",
     });
   }
-  const db = ctx.db as DbConnection; // @cast-boundary db-operator
+  const db = ctx.systemDb.unsafeRaw(
+    "system-wide KEK rotation scans every tenant's encrypted config values",
+  ) as DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
 
   const encryptedKeys = [...ctx.registry.getAllConfigKeys()]
     .filter(([, def]) => def.encrypted === true)

package/src/crypto-shredding/feature.ts

@@ -7,19 +7,23 @@ import {
 } from "./handlers/forget-subject.write";
 
 export function createCryptoShreddingFeature(): FeatureDefinition {
-  return defineFeature(CRYPTO_SHREDDING_FEATURE_NAME, (r) => {
-    r.describe(
-      "Operator-level crypto-shredding trigger. `forget-subject` erases a user or tenant subject key in the configured KMS adapter, making every PII field encrypted under it permanently unreadable (reads render the `[[erased]]` sentinel), and appends a `subject-forgotten` audit event. Requires a KMS adapter (`runProdApp({ kms })`). The automated Art.-17 deletion pipeline in `user-data-rights` erases keys itself; this command covers manual forgets (authority requests, operator recovery, tenant destroy).",
-    );
-    r.uiHints({
-      displayLabel: "Crypto-Shredding",
-      category: "compliance",
-    });
+  return defineFeature(
+    CRYPTO_SHREDDING_FEATURE_NAME,
+    (r) => {
+      r.describe(
+        "Operator-level crypto-shredding trigger. `forget-subject` erases a user or tenant subject key in the configured KMS adapter, making every PII field encrypted under it permanently unreadable (reads render the `[[erased]]` sentinel), and appends a `subject-forgotten` audit event. Requires a KMS adapter (`runProdApp({ kms })`). The automated Art.-17 deletion pipeline in `user-data-rights` erases keys itself; this command covers manual forgets (authority requests, operator recovery, tenant destroy).",
+      );
+      r.uiHints({
+        displayLabel: "Crypto-Shredding",
+        category: "compliance",
+      });
 
-    // `reason` is operator free text and may name the subject; encrypting it under
-    // the subject key is pointless (that key is being erased) — see #2776.
-    r.defineEvent("subject-forgotten", subjectForgottenSchema, { piiFields: "none" });
-    r.defineEvent("forget-denied", subjectForgetDeniedSchema, { piiFields: "none" });
-    r.writeHandler(forgetSubjectWrite);
-  });
+      // `reason` is operator free text and may name the subject; encrypting it under
+      // the subject key is pointless (that key is being erased) — see #2776.
+      r.defineEvent("subject-forgotten", subjectForgottenSchema, { piiFields: "none" });
+      r.defineEvent("forget-denied", subjectForgetDeniedSchema, { piiFields: "none" });
+      r.writeHandler(forgetSubjectWrite);
+    },
+    { dedupeOptions: {} },
+  );
 }

package/src/data-retention/__tests__/retention-cleanup.integration.test.ts

@@ -13,6 +13,7 @@
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { JobContext } from "@cosmicdrift/kumiko-framework/engine";
 import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -278,7 +279,9 @@ describe("runRetentionCleanup :: real postgres", () => {
     if (!job) return;
 
     const ctx: JobContext = {
-      db: stack.db,
+      db: createTenantDb(stack.db, T1, "tenant", undefined, undefined, undefined, {
+        unsafeRaw: { reason: "per-tenant fan-out cleanup using raw helpers" },
+      }),
       registry: stack.registry,
       systemUser: { id: "system", tenantId: T1, roles: ["all"] },
       log: noopLogger,

package/src/data-retention/feature.ts

@@ -71,19 +71,23 @@ export function createDataRetentionFeature(): FeatureDefinition {
     r.exposesApi("retention.policyFor");
     r.queryHandler(policyForQuery);
 
-    // S2.D2b — autonomer Retention-Cleanup. perTenant-Fan-out (ein Run pro
-    // aktivem Tenant, wie soft-delete-cleanup): die job-DB ist NICHT
-    // tenant-scoped, deshalb scoped der Runner jeden Delete explizit per
-    // tenantId. Ohne diesen Cron werden Retention-Regeln zwar konfiguriert,
-    // aber nie ausgefuehrt.
-    r.job(
-      "retention-cleanup",
-      { trigger: { cron: "0 3 * * *" }, perTenant: true, concurrency: "skip" },
-      async (_payload, ctx) => {
-        if (!ctx.db || !ctx.registry) {
-          throw new Error(
-            "retention-cleanup: ctx.db + ctx.registry required (JobContext incomplete)",
-          );
+    // S2.D2b — autonomous retention cleanup. perTenant fan-out (one run per
+    // active tenant, like soft-delete-cleanup): runRetentionCleanup's raw
+    // query helpers need the unfiltered runner, so the handler declares
+    // escapeHatch and reaches for ctx.db.unsafeRaw(). Without this cron,
+    // retention rules are configured but never enforced.
+    r.job({
+      name: "retention-cleanup",
+      trigger: { cron: "0 3 * * *" },
+      perTenant: true,
+      concurrency: "skip",
+      escapeHatch: {
+        reason:
+          "retention cleanup runs raw deletes and preset lookups; every statement filters by this run's tenantId",
+      },
+      handler: async (_payload, ctx) => {
+        if (!ctx.registry) {
+          throw new Error("retention-cleanup: ctx.registry required (JobContext incomplete)");
         }
         const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
         if (tenantId === undefined) {
@@ -91,7 +95,9 @@ export function createDataRetentionFeature(): FeatureDefinition {
           return;
         }
         const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
-        const cleanupDb = ctx.db as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator
+        const cleanupDb = ctx.db.unsafeRaw(
+          "retention cleanup runs raw deletes and preset lookups; every statement filters by this run's tenantId",
+        ) as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
         const tenantPreset = await resolveTenantRetentionPreset({
           db: cleanupDb,
           registry: ctx.registry,
@@ -111,6 +117,6 @@ export function createDataRetentionFeature(): FeatureDefinition {
           );
         }
       },
-    );
+    });
   });
 }