@cosmicdrift/kumiko-bundled-features 0.278.0 → 0.280.0

package/src/personal-access-tokens/handlers/create.write.ts

@@ -30,6 +30,7 @@ export type CreatePatOptions = {
   ) => Promise<PatMfaVerifyResult>;
 };
 
+// @wrapper-known error-helper
 function reauthFailed() {
   return writeFailure(
     new UnprocessableError(PatErrors.reauthRequired, {

package/src/template-resolver-user-data/hooks.ts

@@ -3,7 +3,6 @@
 // so apps without the user-data-rights pipeline don't pull a hard dependency.
 // Mirrors notes-history-user-data: export-only, erasure via crypto-shredding.
 
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { UserDataDeleteHook, UserDataExportHook } from "@cosmicdrift/kumiko-framework/engine";
 import { userContentEntriesTable } from "../template-resolver";
 
@@ -11,7 +10,7 @@ import { userContentEntriesTable } from "../template-resolver";
 // scoping comes from the tenant-scoped ctx.db; a user who belongs to two
 // tenants gets each tenant's entries from that tenant's forget run.
 export const userContentExportHook: UserDataExportHook = async (ctx) => {
-  const rows = await selectMany<Record<string, unknown>>(ctx.db, userContentEntriesTable, {
+  const rows = await ctx.db.selectMany(userContentEntriesTable, {
     ownerId: ctx.userId,
   });
   if (rows.length === 0) return null;

package/src/tenant-lifecycle/feature.ts

@@ -132,6 +132,8 @@ export function createTenantLifecycleFeature(): FeatureDefinition {
           now: T.Now.instant(),
           log: (message) => ctx.log?.warn(message),
           fileProviderResolver: ctx._fileProviderResolver,
+          escapeHatchAuditSink: ctx._escapeHatchAuditSink,
+          actor: ctx.systemUser.id,
         });
       },
     });

package/src/tenant-lifecycle/run-tenant-destroy.ts

@@ -3,6 +3,7 @@ import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
+  type EscapeHatchAuditSink,
   type Registry,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -216,6 +217,8 @@ export async function runNextDestructionStage(args: {
   readonly tenantId: TenantId;
   readonly log?: (message: string) => void;
   readonly fileProviderResolver?: FileProviderResolver;
+  readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
+  readonly actor?: string;
 }): Promise<{ readonly done: boolean; readonly error?: string; readonly halted?: boolean }> {
   const events = await loadAggregate(args.db, args.tenantId, args.tenantId);
   const { completed, abandoned, attemptsByStage } = replayStageState(events);
@@ -238,6 +241,8 @@ export async function runNextDestructionStage(args: {
     tenantId: args.tenantId,
     log: args.log,
     fileProviderResolver: args.fileProviderResolver,
+    escapeHatchAuditSink: args.escapeHatchAuditSink,
+    actor: args.actor,
   };
 
   let version = lastEventVersion(events);
@@ -304,6 +309,8 @@ export async function runTenantDestructionSweep(args: {
   readonly now?: Temporal.Instant;
   readonly log?: (message: string) => void;
   readonly fileProviderResolver?: FileProviderResolver;
+  readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
+  readonly actor?: string;
 }): Promise<{ readonly triggered: number; readonly advanced: number }> {
   const T = getTemporal();
   const now = args.now ?? T.Now.instant();
@@ -353,6 +360,8 @@ export async function runTenantDestructionSweep(args: {
         tenantId: row.id as TenantId,
         log: args.log,
         fileProviderResolver: args.fileProviderResolver,
+        escapeHatchAuditSink: args.escapeHatchAuditSink,
+        actor: args.actor,
       });
       if (!result.error && !result.halted) advanced++;
     } catch (err) {

package/src/tenant-lifecycle/stages.ts

@@ -7,15 +7,19 @@ import {
 } from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
+  type EscapeHatchAuditSink,
   EXT_EXTERNAL_RESOURCE,
   EXT_INFRA_RESOURCE,
   EXT_SEARCH_ADAPTER,
   EXT_STORAGE_PROVIDER,
   EXT_TENANT_DATA,
+  extensionUsageEscapeHatchReason,
   type Registry,
+  type TenantDataHookCtx,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-framework/files";
+import { createEscapeHatchReporter } from "@cosmicdrift/kumiko-framework/pipeline";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import {
   tenantEntity,
@@ -35,6 +39,11 @@ export type DestructionStageCtx = {
   // "destroyTenant" hooks) — undefined when no file-provider is wired,
   // which those hooks must treat as "nothing to clean up", not an error.
   readonly fileProviderResolver?: FileProviderResolver;
+  // fw#2914 — sourced from the owning job's ctx (_escapeHatchAuditSink,
+  // systemUser.id); runTenantDataHooks uses them to attribute+audit any
+  // EXT_TENANT_DATA usage's declared escapeHatch.
+  readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
+  readonly actor?: string;
 };
 
 export type DestructionStage = {
@@ -73,10 +82,25 @@ async function runTenantDataHooks(ctx: DestructionStageCtx): Promise<void> {
   const usages = ctx.registry.getExtensionUsages(EXT_TENANT_DATA);
   for (const usage of usages) {
     const destroy = usage.options?.["destroy"] as
-      | ((ctx: DestructionStageCtx) => Promise<void>)
+      | ((hookCtx: TenantDataHookCtx) => Promise<void>)
       | undefined;
     if (!destroy) continue;
-    await destroy(ctx);
+    const reason = extensionUsageEscapeHatchReason(usage);
+    const report = createEscapeHatchReporter({
+      handler: `${EXT_TENANT_DATA}:${usage.entityName}`,
+      tenantId: ctx.tenantId,
+      actor: ctx.actor ?? "system",
+      sink: ctx.escapeHatchAuditSink,
+    });
+    const hookCtx: TenantDataHookCtx = {
+      db: createTenantDb(ctx.db, ctx.tenantId, "tenant", undefined, undefined, undefined, {
+        unsafeRaw: reason !== undefined ? { reason } : undefined,
+        report,
+      }),
+      registry: ctx.registry,
+      tenantId: ctx.tenantId,
+    };
+    await destroy(hookCtx);
   }
 }
 

package/src/user-data-rights/__tests__/cross-data-matrix.integration.test.ts

@@ -19,6 +19,7 @@ import { defineUnmanagedTable } from "@cosmicdrift/kumiko-framework/db";
 import {
   defineFeature,
   EXT_USER_DATA,
+  SYSTEM_TENANT_ID,
   type UserDataDeleteHook,
   type UserDataExportHook,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -49,7 +50,7 @@ let stack: TestStack;
 
 const TENANT_A = "00000000-0000-4000-8000-00000000000a";
 const TENANT_B = "00000000-0000-4000-8000-00000000000b";
-const TENANT_SYSTEM = "00000000-0000-4000-8000-000000000001";
+const TENANT_SYSTEM = SYSTEM_TENANT_ID;
 
 function uuid(suffix: number): string {
   return `cccccccc-cccc-4ccc-8ccc-${suffix.toString(16).padStart(12, "0")}`;
@@ -77,20 +78,10 @@ const testNotesTable = defineUnmanagedTable({
 // Stellvertretend fuer App-spezifische Entities (Chat-Message, Blog-Post
 // etc.), die ueber EXT_USER_DATA sauber in die Pipeline integrieren.
 const exportNotes: UserDataExportHook = async (ctx) => {
-  const result = await asRawClient(ctx.db).unsafe(
-    `
-    SELECT id, title, body
-    FROM test_notes
-    WHERE tenant_id = $1 AND author_id = $2
-  `,
-    [ctx.tenantId, ctx.userId],
+  const rows = await ctx.db.selectMany<{ id: string; title: string; body: string }>(
+    testNotesTable,
+    { tenantId: ctx.tenantId, authorId: ctx.userId },
   );
-  // biome-ignore lint/suspicious/noExplicitAny: drizzle execute typing
-  const rows = ((result as any).rows ?? result) as Array<{
-    id: string;
-    title: string;
-    body: string;
-  }>;
   if (rows.length === 0) return null;
   return {
     entity: "note",

package/src/user-data-rights/__tests__/escape-hatch-audit.integration.test.ts

@@ -0,0 +1,133 @@
+// fw#2914 — proves the escape-hatch audit trail is wired end-to-end on the
+// REAL production path: the registered "run-forget-cleanup" cron job (not
+// runForgetCleanup called directly, not a hand-fed sink) forwards its
+// JobContext's `_escapeHatchAuditSink` + `systemUser.id` down through
+// runForgetCleanup → the per-entity `createEscapeHatchReporter` →
+// ctx.db.unsafeRaw(reason) inside a declared-escapeHatch hook, so a
+// declared raw-SQL use is actually attributed and audited instead of
+// landing on the anonymous "<unattributed>" fallback.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  defineFeature,
+  type EscapeHatchUseEvent,
+  EXT_USER_DATA,
+  type JobContext,
+  type UserDataDeleteHook,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createComplianceProfilesFeature } from "../../compliance-profiles";
+import { createDataRetentionFeature, tenantRetentionOverrideEntity } from "../../data-retention";
+import { createSessionsFeature } from "../../sessions";
+import { createUserFeature, userEntity } from "../../user";
+import { createUserDataRightsFeature } from "../feature";
+import { createForgetSeeders, READ_TENANT_MEMBERSHIPS_DDL } from "./forget-test-helpers";
+
+const FORGET_USER = "ffffffff-ffff-4fff-8fff-000000000001";
+const TENANT_A = "00000000-0000-4000-8000-0000000000f9";
+
+const AUDITED_REASON =
+  "fw#2914 test: declared escapeHatch on the real run-forget-cleanup job path — must be audited, not <unattributed>";
+
+const auditedHook: UserDataDeleteHook = async (ctx) => {
+  await asRawClient(ctx.db.unsafeRaw(AUDITED_REASON)).unsafe(
+    `DELETE FROM test_audited_entity WHERE tenant_id = $1`,
+    [ctx.tenantId],
+  );
+};
+
+const auditedFeature = defineFeature("test-audited-entity", (r) => {
+  r.useExtension(EXT_USER_DATA, "audited-entity", {
+    export: async () => null,
+    delete: auditedHook,
+    escapeHatch: { reason: AUDITED_REASON },
+  });
+});
+
+const seed = (db: unknown) =>
+  // biome-ignore lint/suspicious/noExplicitAny: dummy file-writer; these seeders never write binaries.
+  createForgetSeeders(db as any, { write: async () => {} });
+
+describe("escape-hatch audit :: real run-forget-cleanup job forwards _escapeHatchAuditSink + systemUser.id", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({
+      features: [
+        createUserFeature(),
+        createDataRetentionFeature(),
+        createComplianceProfilesFeature(),
+        authFoundationFeature,
+        createSessionsFeature(),
+        createUserDataRightsFeature(),
+        auditedFeature,
+      ],
+    });
+    await unsafeCreateEntityTable(stack.db, userEntity);
+    await unsafeCreateEntityTable(stack.db, tenantRetentionOverrideEntity);
+    await createEventsTable(stack.db);
+    await asRawClient(stack.db).unsafe(READ_TENANT_MEMBERSHIPS_DDL);
+    await asRawClient(stack.db).unsafe(`
+      CREATE TABLE IF NOT EXISTS test_audited_entity (
+        id UUID PRIMARY KEY,
+        tenant_id UUID NOT NULL
+      )
+    `);
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("declared hook's unsafeRaw use is reported with a qualified handler + the job's systemUser as actor", async () => {
+    const job = stack.registry.getJob("user-data-rights:job:run-forget-cleanup");
+    expect(job).toBeTruthy();
+
+    await seed(stack.db).seedForgetUser(FORGET_USER);
+    await seed(stack.db).seedMembership(FORGET_USER, TENANT_A);
+
+    const events: EscapeHatchUseEvent[] = [];
+    const systemUser = createSystemUser(TENANT_A);
+    const noopLog: JobContext["log"] = {
+      info() {},
+      warn() {},
+      error() {},
+      debug() {},
+      child(): JobContext["log"] {
+        return this;
+      },
+    };
+
+    await job?.handler({}, {
+      db: createTenantDb(stack.db, TENANT_A, "tenant", undefined, undefined, undefined, {
+        unsafeRaw: { reason: "executes overdue Art.17 forget requests across every tenant" },
+      }),
+      registry: stack.registry,
+      systemUser,
+      log: noopLog,
+      _escapeHatchAuditSink: async (event: EscapeHatchUseEvent) => {
+        events.push(event);
+      },
+    } as unknown as JobContext);
+
+    const hit = events.find((e) => e.reason === AUDITED_REASON);
+    expect(hit).toBeDefined();
+    expect(hit?.handler).toBe("userData:audited-entity");
+    expect(hit?.kind).toBe("unsafe-raw");
+    expect(hit?.tenantId).toBe(TENANT_A);
+    // The job's OWN systemUser.id, not "system"/"<unattributed>" — proves
+    // ctx.systemUser.id really travels from the JobContext down to the
+    // per-hook reporter instead of a hardcoded/default actor.
+    expect(hit?.actor).toBe(systemUser.id);
+    expect(hit?.actor).not.toBe("<unattributed>");
+  });
+});

package/src/user-data-rights/__tests__/escape-hatch-declaration.integration.test.ts

@@ -0,0 +1,198 @@
+// fw#2914 — proves the escapeHatch declaration gate, not just its type.
+//
+// TenantDataHookCtx/UserDataHookCtx.db is a tenant-filtered TenantDb. A hook
+// that declares `escapeHatch: { reason }` on its `r.useExtension(...)`
+// registration can call `ctx.db.unsafeRaw(reason)` to get a REAL unfiltered
+// DbRunner — the two tests below use it with a deliberately filter-less
+// `DELETE FROM <table>` (no WHERE at all) to prove the grant is genuinely
+// unfiltered, not merely present. A sibling hook that forgot to declare
+// escapeHatch gets `AccessDeniedError` from that same call instead, which
+// `runForgetCleanup` catches into `result.errors` — the row is left
+// untouched rather than silently wiped/leaked across tenants.
+//
+// Pre-fix (TenantDataHookCtx/UserDataHookCtx.db was a raw, unfiltered
+// DbRunner) BOTH hooks below — declared or not — could run this exact
+// unfiltered DELETE with no gate at all. That's the regression this test
+// pins shut.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  defineFeature,
+  EXT_USER_DATA,
+  type UserDataDeleteHook,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createComplianceProfilesFeature } from "../../compliance-profiles";
+import { createDataRetentionFeature, tenantRetentionOverrideEntity } from "../../data-retention";
+import { createSessionsFeature } from "../../sessions";
+import { createUserFeature, userEntity } from "../../user";
+import { createUserDataRightsFeature } from "../feature";
+import { runForgetCleanup } from "../run-forget-cleanup";
+import {
+  createForgetSeeders,
+  nowInstant,
+  READ_TENANT_MEMBERSHIPS_DDL,
+} from "./forget-test-helpers";
+
+const FORGET_USER = "eeeeeeee-eeee-4eee-8eee-000000000001";
+const TENANT_A = "00000000-0000-4000-8000-0000000000e1";
+const TENANT_B_FOREIGN = "00000000-0000-4000-8000-0000000000e2";
+
+const seed = (db: unknown) =>
+  // biome-ignore lint/suspicious/noExplicitAny: dummy file-writer; these seeders never write binaries.
+  createForgetSeeders(db as any, { write: async () => {} });
+
+function baseFeatures(): NonNullable<Parameters<typeof setupTestStack>[0]["features"]> {
+  return [
+    createUserFeature(),
+    createDataRetentionFeature(),
+    createComplianceProfilesFeature(),
+    authFoundationFeature,
+    createSessionsFeature(),
+    createUserDataRightsFeature(),
+  ];
+}
+
+async function bootBaseTables(stack: TestStack): Promise<void> {
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantRetentionOverrideEntity);
+  await createEventsTable(stack.db);
+  await asRawClient(stack.db).unsafe(READ_TENANT_MEMBERSHIPS_DDL);
+}
+
+describe("escape-hatch declaration :: declared hook gets a real unfiltered DbRunner", () => {
+  const DECLARED_REASON =
+    "fw#2914 test: escape-hatch declared on r.useExtension — ctx.db.unsafeRaw(reason) must grant a real unfiltered DbRunner";
+
+  const declaredLeakHook: UserDataDeleteHook = async (ctx) => {
+    // No WHERE clause at all — only possible with a genuinely unfiltered runner.
+    await asRawClient(ctx.db.unsafeRaw(DECLARED_REASON)).unsafe(`DELETE FROM test_leaky_declared`);
+  };
+
+  const declaredFeature = defineFeature("test-leaky-declared", (r) => {
+    r.useExtension(EXT_USER_DATA, "leaky-declared", {
+      export: async () => null,
+      delete: declaredLeakHook,
+      escapeHatch: { reason: DECLARED_REASON },
+    });
+  });
+
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [...baseFeatures(), declaredFeature] });
+    await bootBaseTables(stack);
+    await asRawClient(stack.db).unsafe(`
+      CREATE TABLE IF NOT EXISTS test_leaky_declared (
+        id UUID PRIMARY KEY,
+        tenant_id UUID NOT NULL,
+        secret TEXT NOT NULL
+      )
+    `);
+    await asRawClient(stack.db).unsafe(
+      `INSERT INTO test_leaky_declared (id, tenant_id, secret) VALUES
+        ('11111111-1111-4111-8111-000000000001', $1, 'tenant-a-secret'),
+        ('11111111-1111-4111-8111-000000000002', $2, 'tenant-b-secret')`,
+      [TENANT_A, TENANT_B_FOREIGN],
+    );
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("declared unsafeRaw wipes rows across every tenant, not just the forgotten user's own", async () => {
+    await seed(stack.db).seedForgetUser(FORGET_USER);
+    await seed(stack.db).seedMembership(FORGET_USER, TENANT_A);
+
+    const result = await runForgetCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      now: nowInstant(),
+    });
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.processedUserIds).toContain(FORGET_USER);
+
+    const remaining = await asRawClient(stack.db).unsafe(`SELECT id FROM test_leaky_declared`);
+    // Both Tenant A's own row AND the foreign Tenant B's row are gone —
+    // proves ctx.db.unsafeRaw(reason) really is unfiltered, not just granted.
+    expect(remaining).toHaveLength(0);
+  });
+});
+
+describe("escape-hatch declaration :: undeclared hook is denied, not silently unfiltered", () => {
+  const UNDECLARED_REASON =
+    "fw#2914 test: escape-hatch NOT declared on r.useExtension — ctx.db.unsafeRaw(reason) must be denied";
+
+  const undeclaredLeakHook: UserDataDeleteHook = async (ctx) => {
+    await asRawClient(ctx.db.unsafeRaw(UNDECLARED_REASON)).unsafe(
+      `DELETE FROM test_leaky_undeclared`,
+    );
+  };
+
+  const undeclaredFeature = defineFeature("test-leaky-undeclared", (r) => {
+    r.useExtension(EXT_USER_DATA, "leaky-undeclared", {
+      export: async () => null,
+      delete: undeclaredLeakHook,
+      // fw#2914 — deliberately NOT declared: this is the case under test.
+    });
+  });
+
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [...baseFeatures(), undeclaredFeature] });
+    await bootBaseTables(stack);
+    await asRawClient(stack.db).unsafe(`
+      CREATE TABLE IF NOT EXISTS test_leaky_undeclared (
+        id UUID PRIMARY KEY,
+        tenant_id UUID NOT NULL,
+        secret TEXT NOT NULL
+      )
+    `);
+    await asRawClient(stack.db).unsafe(
+      `INSERT INTO test_leaky_undeclared (id, tenant_id, secret) VALUES
+        ('22222222-2222-4222-8222-000000000001', $1, 'tenant-a-secret'),
+        ('22222222-2222-4222-8222-000000000002', $2, 'tenant-b-secret')`,
+      [TENANT_A, TENANT_B_FOREIGN],
+    );
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("undeclared unsafeRaw is denied and surfaces via result.errors, rows untouched", async () => {
+    await seed(stack.db).seedForgetUser(FORGET_USER);
+    await seed(stack.db).seedMembership(FORGET_USER, TENANT_A);
+
+    const result = await runForgetCleanup({
+      db: stack.db,
+      registry: stack.registry,
+      now: nowInstant(),
+    });
+
+    // The hook throws AccessDeniedError inside processUser's sub-tx — that
+    // rolls the sub-tx back, so this user is NOT flipped to Deleted.
+    expect(result.processedUserIds).not.toContain(FORGET_USER);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0]?.entityName).toBe("leaky-undeclared");
+    expect(result.errors[0]?.userId).toBe(FORGET_USER);
+    expect(result.errors[0]?.message).toContain("escapeHatch");
+
+    const remaining = await asRawClient(stack.db).unsafe(
+      `SELECT tenant_id FROM test_leaky_undeclared ORDER BY tenant_id`,
+    );
+    // Both rows survive — the denial happened before any SQL executed, no
+    // cross-tenant leak (pre-fix, this exact hook body would have wiped both).
+    expect(remaining).toHaveLength(2);
+  });
+});

package/src/user-data-rights/__tests__/forget-cleanup-hook-ordering.integration.test.ts

@@ -48,18 +48,26 @@ import {
 
 const TENANT = "00000000-0000-4000-8000-0000000000aa";
 
+// fw#2914 — both host entities are managed r.entity tables (EXECUTOR_ONLY-
+// branded), so TenantDb's typed write methods reject them; these hooks need
+// raw SQL, still filtered by inserted_by_id + tenant_id.
+const HOST_DELETE_REASON =
+  "fw#2914 test fixture: owner-nulling delete/anonymize against a managed entity table needs raw SQL (TenantDb's typed write API rejects EXECUTOR_ONLY tables); filtered by inserted_by_id + tenant_id";
+const REDACT_REASON =
+  "fw#2914 test fixture: jsonb key removal (custom_fields - 'ssn') is a raw SQL expression TenantDb's typed updateMany can't express; filtered by inserted_by_id + tenant_id";
+
 // Owner-nulling host anonymize hook (the canonical "anonymize keeps the row,
 // clears the owner" pattern — same shape as file-ref/user host hooks).
 function makeHostDeleteHook(tableName: string): UserDataDeleteHook {
   return async (ctx, strategy) => {
     if (strategy === "delete") {
-      await asRawClient(ctx.db).unsafe(
+      await asRawClient(ctx.db.unsafeRaw(HOST_DELETE_REASON)).unsafe(
         `DELETE FROM ${tableName} WHERE inserted_by_id = $1 AND tenant_id = $2`,
         [ctx.userId, ctx.tenantId],
       );
       return;
     }
-    await asRawClient(ctx.db).unsafe(
+    await asRawClient(ctx.db.unsafeRaw(HOST_DELETE_REASON)).unsafe(
       `UPDATE ${tableName} SET inserted_by_id = NULL WHERE inserted_by_id = $1 AND tenant_id = $2`,
       [ctx.userId, ctx.tenantId],
     );
@@ -72,7 +80,7 @@ function makeRedactHook(tableName: string): UserDataDeleteHook {
   return async (ctx, strategy) => {
     // skip: delete strategy removes rows wholesale — redaction N/A.
     if (strategy === "delete") return;
-    await asRawClient(ctx.db).unsafe(
+    await asRawClient(ctx.db.unsafeRaw(REDACT_REASON)).unsafe(
       `UPDATE ${tableName} SET custom_fields = custom_fields - 'ssn'
        WHERE inserted_by_id = $1 AND tenant_id = $2`,
       [ctx.userId, ctx.tenantId],
@@ -119,10 +127,12 @@ const cfFirstFeature = defineFeature(CF_FIRST.featureName, (r) => {
     export: async () => null,
     delete: makeRedactHook(CF_FIRST.tableName),
     order: EXT_USER_DATA_ORDER.REDACT_BEFORE_OWNER,
+    escapeHatch: { reason: REDACT_REASON },
   });
   r.useExtension(EXT_USER_DATA, CF_FIRST.entityName, {
     export: async () => null,
     delete: makeHostDeleteHook(CF_FIRST.tableName),
+    escapeHatch: { reason: HOST_DELETE_REASON },
   });
 });
 
@@ -131,11 +141,13 @@ const hostFirstFeature = defineFeature(HOST_FIRST.featureName, (r) => {
   r.useExtension(EXT_USER_DATA, HOST_FIRST.entityName, {
     export: async () => null,
     delete: makeHostDeleteHook(HOST_FIRST.tableName),
+    escapeHatch: { reason: HOST_DELETE_REASON },
   });
   r.useExtension(EXT_USER_DATA, HOST_FIRST.entityName, {
     export: async () => null,
     delete: makeRedactHook(HOST_FIRST.tableName),
     order: EXT_USER_DATA_ORDER.REDACT_BEFORE_OWNER,
+    escapeHatch: { reason: REDACT_REASON },
   });
 });
 

package/src/user-data-rights/__tests__/forget-cleanup-search-purge-ordering.integration.test.ts

@@ -15,6 +15,7 @@ import {
   createTextField,
   defineFeature,
   EXT_USER_DATA,
+  SYSTEM_TENANT_ID,
   type UserDataDeleteHook,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
@@ -32,7 +33,7 @@ import { createUserFeature, USER_STATUS, userEntity, userTable } from "../../use
 import { createUserDataRightsFeature } from "../feature";
 import { runForgetCleanup } from "../run-forget-cleanup";
 
-const TENANT_SYSTEM = "00000000-0000-4000-8000-000000000001";
+const TENANT_SYSTEM = SYSTEM_TENANT_ID;
 const TENANT_A = "00000000-0000-4000-8000-0000000000f1";
 const ALICE_ID = "aaaaaaaa-aaaa-4aaa-8aaa-0000000000f1";
 const NOTE_ID = "bbbbbbbb-bbbb-4bbb-8bbb-0000000000f1";
@@ -53,9 +54,15 @@ const noteEntity = createEntity({
 });
 const noteTable = buildEntityTable("note", noteEntity);
 
+// fw#2914 — "note" is a managed r.entity table (EXECUTOR_ONLY-branded), so
+// TenantDb's typed write methods reject it; this delete is raw SQL, still
+// filtered by author_id + tenant_id.
+const HARD_DELETE_NOTE_REASON =
+  "fw#2914 test fixture: hard delete against a managed entity table needs raw SQL (TenantDb's typed write API rejects EXECUTOR_ONLY tables); filtered by author_id + tenant_id";
+
 const hardDeleteNoteHook: UserDataDeleteHook = async (ctx, strategy) => {
   if (strategy !== "delete") return;
-  await asRawClient(ctx.db).unsafe(
+  await asRawClient(ctx.db.unsafeRaw(HARD_DELETE_NOTE_REASON)).unsafe(
     `DELETE FROM read_forget_purge_notes WHERE author_id = $1 AND tenant_id = $2`,
     [ctx.userId, ctx.tenantId],
   );
@@ -66,6 +73,7 @@ const noteFeature = defineFeature("forget-purge-notes", (r) => {
   r.useExtension(EXT_USER_DATA, "note", {
     export: async () => null,
     delete: hardDeleteNoteHook,
+    escapeHatch: { reason: HARD_DELETE_NOTE_REASON },
   });
 });
 

package/src/user-data-rights/__tests__/mail-default-bridge.integration.test.ts

@@ -13,6 +13,7 @@ import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:tes
 import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { createSystemUser, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 import {
   setupTestStack,
@@ -35,7 +36,7 @@ import { createUserDataRightsDefaultsFeature } from "../../user-data-rights-defa
 import { createUserDataRightsFeature } from "../feature";
 
 const TENANT_A = "00000000-0000-4000-8000-0000000006a1";
-const TENANT_SYSTEM = "00000000-0000-4000-8000-000000000001";
+const TENANT_SYSTEM = SYSTEM_TENANT_ID;
 const USER_ID = "00000000-0000-4000-8000-0000000006b1";
 const ORIGINAL_EMAIL = "bridge-delete@example.test";
 const FORGET_JOB = "user-data-rights:job:run-forget-cleanup";
@@ -133,6 +134,7 @@ describe("C6 default mail bridge :: forget cron sends deletion-executed without
       }),
       registry: stack.registry,
       configResolver,
+      systemUser: createSystemUser(TENANT_A),
       log: {
         info() {},
         warn() {},

package/src/user-data-rights/__tests__/run-export-jobs-cron-context.integration.test.ts

@@ -13,7 +13,11 @@ import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:tes
 import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
-import { type JobContext, SYSTEM_USER_ID } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createSystemUser,
+  type JobContext,
+  SYSTEM_USER_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { registerMailTranslations } from "@cosmicdrift/kumiko-framework/i18n";
 import {
@@ -153,12 +157,13 @@ describe("run-export-jobs cron-context", () => {
       registry: stack.registry,
       configResolver,
       _userId: SYSTEM_USER_ID,
+      systemUser: createSystemUser(TENANT),
       now: getTemporal().Now.instant(),
     };
     // Vor dem Fix wirft der Wrapper hier "ctx.config is missing".
     // jobCtx is a deliberately minimal prod-context replica (missing
-    // systemUser/log/triggeredBy) — double-cast at this test boundary since
-    // the handler under test never touches those fields.
+    // log/triggeredBy) — double-cast at this test boundary since the
+    // handler under test never touches those fields.
     await job?.handler({}, jobCtx as unknown as JobContext);
 
     const [row] = (await selectMany(stack.db, exportJobsTable, { id: jobId })) as Array<{