@cosmicdrift/kumiko-bundled-features 0.24.1 → 0.25.0

package/src/custom-fields/wire-user-data-rights.ts

@@ -40,6 +40,14 @@ function asCustomFieldsHostRow(value: unknown): CustomFieldsHostRow | null {
   return { id: value.id, customFields: Object.fromEntries(Object.entries(cf)) };
 }
 
+// The anonymize strip filters rows by `WHERE userIdColumn = userId`. A host
+// anonymize hook on the SAME entity that nulls that column (e.g. inserted_by_id
+// = NULL) would, if it ran first, leave the strip matching 0 rows → sensitive
+// jsonb PII silently retained (DSGVO Art. 17 violation). A negative order makes
+// runForgetCleanup run this strip before any default-order (0) owner-nulling
+// hook, independent of feature registration order.
+const ORDER_REDACT_BEFORE_OWNER_MUTATION = -100;
+
 export function wireCustomFieldsUserDataRightsFor<TReg extends FeatureRegistrar<string>>(
   r: TReg,
   opts: WireCustomFieldsUserDataRightsOptions,
@@ -88,6 +96,7 @@ export function wireCustomFieldsUserDataRightsFor<TReg extends FeatureRegistrar<
   r.useExtension(EXT_USER_DATA, opts.entityName, {
     export: exportHook,
     delete: deleteHook,
+    order: ORDER_REDACT_BEFORE_OWNER_MUTATION,
   });
 }
 

package/src/feature-toggles/handlers/set.write.ts

@@ -42,6 +42,17 @@ export function createSetWriteHandler(getRuntime: (() => GlobalFeatureToggleRunt
     handler: async (event, ctx) => {
       const { featureName, enabled } = event.payload;
 
+      // Guard 0: fail fast on a misconfigured app BEFORE any DB write or event
+      // append — otherwise the row + toggle-set event commit and the operator
+      // only sees the error, leaving the in-memory snapshot stale until reboot.
+      if (!getRuntime) {
+        throw new Error(
+          "[feature-toggles] set-handler called but createFeatureTogglesFeature " +
+            "was wired up without `getRuntime`. Wire the accessor in your app-config " +
+            "(production: `() => runtime` after buildServer; tests: createLateBoundHolder.get).",
+        );
+      }
+
       // Guard 1: featureName must be a registered feature. Otherwise we'd
       // pile up orphan rows from typos that the gate would silently apply
       // (if someone ever added a feature with that name later).
@@ -153,14 +164,8 @@ export function createSetWriteHandler(getRuntime: (() => GlobalFeatureToggleRunt
       // for a dispatcher tick. Other instances learn the change through
       // the `toggle-cache-sync` MSP (see feature-toggles-feature.ts). Both
       // paths are idempotent — Map.set is last-write-wins and the DB is
-      // the source of truth after boot-time initialize().
-      if (!getRuntime) {
-        throw new Error(
-          "[feature-toggles] set-handler called but createFeatureTogglesFeature " +
-            "was wired up without `getRuntime`. Wire the accessor in your app-config " +
-            "(production: `() => runtime` after buildServer; tests: createLateBoundHolder.get).",
-        );
-      }
+      // the source of truth after boot-time initialize(). getRuntime presence
+      // is enforced at Guard 0, so it is non-undefined here.
       getRuntime().apply(featureName, enabled);
 
       return {

package/src/secrets/feature.ts

@@ -23,21 +23,14 @@ import { tenantSecretEntity } from "./table";
 export const secretsEnvSchema = z.object({
   KUMIKO_SECRETS_MASTER_KEY_V1: z
     .string()
-    .refine(
-      (v) => {
-        try {
-          return Buffer.from(v, "base64").length === 32;
-        } catch {
-          return false;
-        }
-      },
-      { message: "must be base64-encoded 32 bytes (AES-256 KEK)" },
-    )
+    .refine((v) => Buffer.from(v, "base64").length === 32, {
+      message: "must be base64-encoded 32 bytes (AES-256 KEK)",
+    })
     .describe("AES-256 master-key (KEK) for tenant-secrets encryption.")
     .meta({ kumiko: { pulumi: { generator: "openssl rand -base64 32", secret: true } } }),
   KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: z
     .string()
-    .regex(/^\d+$/, "must be a positive integer (V<n> selector)")
+    .regex(/^[1-9]\d*$/, "must be a positive integer (V<n> selector)")
     .default("1")
     .describe(
       "Pins the active KEK version. Default '1'. Bump after writing a higher KUMIKO_SECRETS_MASTER_KEY_V<n>.",

package/src/subscription-stripe/feature.ts

@@ -60,12 +60,12 @@ import { verifyAndParseStripeWebhook } from "./verify-webhook";
 export const subscriptionStripeEnvSchema = z.object({
   STRIPE_WEBHOOK_SECRET: z
     .string()
-    .min(1, "STRIPE_WEBHOOK_SECRET must not be empty")
+    .regex(/^whsec_/, "STRIPE_WEBHOOK_SECRET must start with 'whsec_'")
     .describe("Stripe webhook-signing secret (`whsec_...` from the Stripe dashboard).")
     .meta({ kumiko: { pulumi: { secret: true } } }),
   STRIPE_API_KEY: z
     .string()
-    .min(1, "STRIPE_API_KEY must not be empty")
+    .regex(/^sk_(test|live)_/, "STRIPE_API_KEY must start with 'sk_test_' or 'sk_live_'")
     .describe("Stripe API key (`sk_live_...` / `sk_test_...`).")
     .meta({ kumiko: { pulumi: { secret: true } } }),
 });

package/src/template-resolver/handlers/list.query.ts

@@ -20,15 +20,11 @@ export const listQuery = defineQueryHandler({
     const isSystemAdmin = query.user.roles.includes("SystemAdmin");
     const where: Record<string, unknown> = {};
 
-    // Tenant-Scope: SystemAdmin sieht alles, andere nur eigener Tenant + System
-    if (!isSystemAdmin) {
-      if (query.payload.includeSystem) {
-        where["tenantId"] = [query.user.tenantId, SYSTEM_TENANT_ID];
-      } else {
-        where["tenantId"] = query.user.tenantId;
-      }
-    } else if (!query.payload.includeSystem) {
-      // SystemAdmin mit includeSystem=false → nur eigener Tenant
+    // TenantDb scopes non-SystemAdmin reads to [own tenant, SYSTEM reference] and
+    // refuses a caller-narrowed where.tenantId (enforced isolation). SystemAdmin
+    // uses a system-scoped db that sees every tenant, so narrow to own explicitly
+    // when they don't want the cross-tenant view.
+    if (isSystemAdmin && !query.payload.includeSystem) {
       where["tenantId"] = query.user.tenantId;
     }
 
@@ -48,7 +44,13 @@ export const listQuery = defineQueryHandler({
       limit: 500,
     })) as TemplateResourceRow[];
 
-    return rows.map((row) => ({
+    // TenantDb always surfaces SYSTEM reference rows alongside the tenant's own;
+    // includeSystem=false drops them here since they can't be excluded at the DB.
+    const visible = query.payload.includeSystem
+      ? rows
+      : rows.filter((row) => row.tenantId !== SYSTEM_TENANT_ID);
+
+    return visible.map((row) => ({
       id: String(row.id),
       tenantId: row.tenantId,
       slug: row.slug,

package/src/tenant/__tests__/seed-testing.integration.test.ts

@@ -173,6 +173,32 @@ describe("seedTenantMembership", () => {
     expect(events.filter((e) => e.type === "tenant-membership.created")).toHaveLength(1);
   });
 
+  test("returns the membership-row id — identical across create + no-op re-seed", async () => {
+    // Both return paths (create via extractMembershipId, no-op via fetched row)
+    // must yield the same valid uuid string that the projection actually holds.
+    // Previously the return was never asserted; a no-op returning the wrong /
+    // undefined id would have gone unnoticed.
+    const created = await seedTenantMembership(stack.db, {
+      userId: ALICE_ID,
+      tenantId: TENANT_A,
+      roles: ["User"],
+    });
+    const reSeeded = await seedTenantMembership(stack.db, {
+      userId: ALICE_ID,
+      tenantId: TENANT_A,
+      roles: ["User"],
+    });
+
+    expect(created.id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+    expect(reSeeded.id).toBe(created.id);
+
+    const [row] = await selectMany(stack.db, tenantMembershipsTable, {
+      userId: ALICE_ID,
+      tenantId: TENANT_A,
+    });
+    expect(row?.["id"]).toBe(created.id);
+  });
+
   test("records the `by` user as insertedById on the projection", async () => {
     // Audit-queries that join events → users need a stable actor. Default
     // `by` is TestUsers.systemAdmin; override to a custom test user and

package/src/tenant/seeding.ts

@@ -141,9 +141,9 @@ export async function seedTenantMembership(
     tenantId: options.tenantId,
   });
   if (existing) {
-    // @cast-boundary db-row: membership-row id is uuid (string) per
-    // entity definition; fetchOne returns the raw projection row.
-    return { id: existing["id"] as string };
+    // Same validation as the create-path — a missing/non-string id throws
+    // instead of silently returning `undefined as string`.
+    return { id: extractMembershipId(existing) };
   }
 
   const result = await executor.create(

package/src/user-data-rights/__tests__/file-binary-forget-cleanup.integration.test.ts

@@ -6,7 +6,7 @@
 // Datei ihre Bytes dauerhaft auf Disk (Issue gefunden im Review zu #177).
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { asRawClient, insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import {
   createInMemoryFileProvider,
@@ -20,31 +20,32 @@ import {
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
-import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { createComplianceProfilesFeature } from "../../compliance-profiles";
 import { createDataRetentionFeature, tenantRetentionOverrideEntity } from "../../data-retention";
 import { createFilesFeature } from "../../files";
 import { createSessionsFeature } from "../../sessions";
-import { createUserFeature, USER_STATUS, userEntity, userTable } from "../../user";
+import { createUserFeature, userEntity, userTable } from "../../user";
 import { createUserDataRightsDefaultsFeature } from "../../user-data-rights-defaults";
 import { createUserDataRightsFeature } from "../feature";
 import { runForgetCleanup } from "../run-forget-cleanup";
+import {
+  createForgetSeeders,
+  type ForgetSeeders,
+  nowInstant,
+  READ_TENANT_MEMBERSHIPS_DDL,
+} from "./forget-test-helpers";
 
 let stack: TestStack;
 let db: DbConnection;
 let provider: InMemoryFileProvider;
+let seed: ForgetSeeders;
 
 const TENANT = "00000000-0000-4000-8000-00000000000c";
-const TENANT_SYSTEM = "00000000-0000-4000-8000-000000000001";
 
 function uuid(suffix: number): string {
   return `bbbbbbbb-bbbb-4bbb-8bbb-${suffix.toString(16).padStart(12, "0")}`;
 }
 
-type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
-const NOW = (): Instant => getTemporal().Now.instant();
-const pastInstant = (): Instant => getTemporal().Instant.fromEpochMilliseconds(Date.now() - 60_000);
-
 beforeAll(async () => {
   provider = createInMemoryFileProvider();
   stack = await setupTestStack({
@@ -60,27 +61,12 @@ beforeAll(async () => {
     files: { storageProvider: provider },
   });
   db = stack.db;
+  seed = createForgetSeeders(db, provider);
 
   await unsafeCreateEntityTable(db, userEntity);
   await unsafeCreateEntityTable(db, tenantRetentionOverrideEntity);
   await unsafePushTables(db, { fileRefsTable });
-  await asRawClient(db).unsafe(`
-    CREATE TABLE IF NOT EXISTS read_tenant_memberships (
-      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-      tenant_id UUID NOT NULL,
-      user_id TEXT NOT NULL,
-      version INTEGER NOT NULL DEFAULT 0,
-      inserted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-      modified_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-      inserted_by_id TEXT,
-      modified_by_id TEXT,
-      is_deleted BOOLEAN NOT NULL DEFAULT false,
-      deleted_at TIMESTAMPTZ,
-      deleted_by_id TEXT,
-      roles TEXT NOT NULL DEFAULT '[]',
-      UNIQUE(user_id, tenant_id)
-    )
-  `);
+  await asRawClient(db).unsafe(READ_TENANT_MEMBERSHIPS_DDL);
 });
 
 afterAll(async () => {
@@ -92,49 +78,15 @@ beforeEach(async () => {
   await resetTestTables(db, [userTable, "read_tenant_memberships", fileRefsTable]);
 });
 
-async function seedForgetUser(id: string): Promise<void> {
-  await insertOne(db, userTable, {
-    id,
-    tenantId: TENANT_SYSTEM,
-    email: `user-${id}@example.com`,
-    passwordHash: "hashed",
-    displayName: `User ${id}`,
-    locale: "de",
-    emailVerified: true,
-    roles: '["Member"]',
-    status: USER_STATUS.DeletionRequested,
-    gracePeriodEnd: pastInstant(),
-  });
-}
-
-async function seedMembership(userId: string, tenantId: string): Promise<void> {
-  await asRawClient(db).unsafe(
-    `INSERT INTO read_tenant_memberships (tenant_id, user_id, roles)
-     VALUES ($1, $2, '["Member"]') ON CONFLICT (user_id, tenant_id) DO NOTHING`,
-    [tenantId, userId],
-  );
-}
-
-async function seedFile(id: string, tenantId: string, insertedById: string): Promise<string> {
-  const storageKey = `storage/${id}`;
-  await provider.write(storageKey, new Uint8Array([1, 2, 3, 4]), "application/pdf");
-  await asRawClient(db).unsafe(
-    `INSERT INTO file_refs (id, tenant_id, storage_key, file_name, mime_type, size, inserted_by_id)
-     VALUES ($1, $2, $3, $4, 'application/pdf', 4, $5) ON CONFLICT (id) DO NOTHING`,
-    [id, tenantId, storageKey, `${id}.pdf`, insertedById],
-  );
-  return storageKey;
-}
-
 describe("forget-binary-cleanup :: storage.delete fires before row hard-delete", () => {
   test("Forget deletes the binary from the storage provider", async () => {
     const userId = uuid(1);
-    await seedForgetUser(userId);
-    await seedMembership(userId, TENANT);
-    const key = await seedFile(uuid(101), TENANT, userId);
+    await seed.seedForgetUser(userId);
+    await seed.seedMembership(userId, TENANT);
+    const key = await seed.seedFile(uuid(101), TENANT, userId);
     expect(await provider.exists(key)).toBe(true);
 
-    const result = await runForgetCleanup({ db, registry: stack.registry, now: NOW() });
+    const result = await runForgetCleanup({ db, registry: stack.registry, now: nowInstant() });
 
     expect(result.processedUserIds).toContain(userId);
     expect(await provider.exists(key)).toBe(false);
@@ -143,16 +95,16 @@ describe("forget-binary-cleanup :: storage.delete fires before row hard-delete",
 
   test("Multiple files from the same user — all binaries cleaned up", async () => {
     const userId = uuid(2);
-    await seedForgetUser(userId);
-    await seedMembership(userId, TENANT);
+    await seed.seedForgetUser(userId);
+    await seed.seedMembership(userId, TENANT);
     const keys = await Promise.all([
-      seedFile(uuid(201), TENANT, userId),
-      seedFile(uuid(202), TENANT, userId),
-      seedFile(uuid(203), TENANT, userId),
+      seed.seedFile(uuid(201), TENANT, userId),
+      seed.seedFile(uuid(202), TENANT, userId),
+      seed.seedFile(uuid(203), TENANT, userId),
     ]);
     expect(provider.keys()).toHaveLength(3);
 
-    await runForgetCleanup({ db, registry: stack.registry, now: NOW() });
+    await runForgetCleanup({ db, registry: stack.registry, now: nowInstant() });
 
     for (const key of keys) {
       expect(await provider.exists(key)).toBe(false);
@@ -163,14 +115,14 @@ describe("forget-binary-cleanup :: storage.delete fires before row hard-delete",
   test("Other tenants' files stay untouched", async () => {
     const userId = uuid(3);
     const otherTenant = "00000000-0000-4000-8000-00000000000d";
-    await seedForgetUser(userId);
-    await seedMembership(userId, TENANT);
-    const myKey = await seedFile(uuid(301), TENANT, userId);
-    const otherKey = await seedFile(uuid(302), otherTenant, "another-user");
+    await seed.seedForgetUser(userId);
+    await seed.seedMembership(userId, TENANT);
+    const myKey = await seed.seedFile(uuid(301), TENANT, userId);
+    const otherKey = await seed.seedFile(uuid(302), otherTenant, "another-user");
     // The other-tenant file is owned by a different user; the forget run for
     // userId must NOT touch it.
 
-    await runForgetCleanup({ db, registry: stack.registry, now: NOW() });
+    await runForgetCleanup({ db, registry: stack.registry, now: nowInstant() });
 
     expect(await provider.exists(myKey)).toBe(false);
     expect(await provider.exists(otherKey)).toBe(true);

package/src/user-data-rights/__tests__/file-binary-forget-failure.integration.test.ts

@@ -0,0 +1,211 @@
+// Forget-Hook fail-closed Integration-Test.
+//
+// Beweist den Vertrag von runForgetCleanup für den fileRef-delete-Hook: wenn
+// `storageProvider.delete()` fehlschlägt, wirft der Hook → die per-User-Sub-Tx
+// rollt zurück → der User bleibt `DeletionRequested`, die Row + Binary bleiben,
+// der Fehler landet im `errors`-Array. Der nächste Run (Storage wieder ok)
+// konvergiert sauber, weil `delete` idempotent ist. Ohne den Throw würde ein
+// transienter Storage-Fehler die Row permanent hard-löschen, den User auf
+// `Deleted` flippen und die Binary dauerhaft verwaisen lassen (Art.-17-Erasure
+// still unvollständig).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient, fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createInMemoryFileProvider,
+  fileRefsTable,
+  type InMemoryFileProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
+import { createComplianceProfilesFeature } from "../../compliance-profiles";
+import { createDataRetentionFeature, tenantRetentionOverrideEntity } from "../../data-retention";
+import { createFilesFeature } from "../../files";
+import { createSessionsFeature } from "../../sessions";
+import { createUserFeature, USER_STATUS, userEntity, userTable } from "../../user";
+import { createUserDataRightsDefaultsFeature } from "../../user-data-rights-defaults";
+import { createUserDataRightsFeature } from "../feature";
+import { runForgetCleanup } from "../run-forget-cleanup";
+import {
+  createForgetSeeders,
+  type ForgetSeeders,
+  nowInstant,
+  READ_TENANT_MEMBERSHIPS_DDL,
+} from "./forget-test-helpers";
+
+let stack: TestStack;
+let db: DbConnection;
+let base: InMemoryFileProvider;
+let seed: ForgetSeeders;
+// `delete` throws while set; flip off to simulate storage recovery on retry.
+let failDeletes = true;
+
+const TENANT = "00000000-0000-4000-8000-00000000000e";
+
+beforeAll(async () => {
+  base = createInMemoryFileProvider();
+  // Spread the real provider (all methods bound to its store) and override
+  // only `delete` to fail on demand — lets one test prove abort + retry-convergence.
+  const flakyProvider: InMemoryFileProvider = {
+    ...base,
+    async delete(key) {
+      if (failDeletes) throw new Error("storage unavailable (test)");
+      return base.delete(key);
+    },
+  };
+  stack = await setupTestStack({
+    features: [
+      createUserFeature(),
+      createFilesFeature(),
+      createDataRetentionFeature(),
+      createComplianceProfilesFeature(),
+      createSessionsFeature(),
+      createUserDataRightsFeature(),
+      createUserDataRightsDefaultsFeature({ storageProvider: flakyProvider }),
+    ],
+    files: { storageProvider: flakyProvider },
+  });
+  db = stack.db;
+  // Seeders write binaries through the real store (`base`), not the flaky
+  // wrapper — the wrapper's `delete` failure is what the test exercises.
+  seed = createForgetSeeders(db, base);
+
+  await unsafeCreateEntityTable(db, userEntity);
+  await unsafeCreateEntityTable(db, tenantRetentionOverrideEntity);
+  await unsafePushTables(db, { fileRefsTable });
+  await asRawClient(db).unsafe(READ_TENANT_MEMBERSHIPS_DDL);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  failDeletes = true;
+  base.clear();
+  await resetTestTables(db, [userTable, "read_tenant_memberships", fileRefsTable]);
+});
+
+async function fileRowCount(tenantId: string, insertedById: string): Promise<number> {
+  const rows = await asRawClient(db).unsafe(
+    `SELECT 1 FROM file_refs WHERE tenant_id = $1 AND inserted_by_id = $2`,
+    [tenantId, insertedById],
+  );
+  return (rows as ReadonlyArray<unknown>).length;
+}
+
+describe("forget fail-closed :: storage.delete failure aborts the row hard-delete", () => {
+  test("storage delete fails → user stays DeletionRequested, row + binary remain, error surfaced", async () => {
+    const userId = "cccccccc-cccc-4ccc-8ccc-000000000001";
+    await seed.seedForgetUser(userId);
+    await seed.seedMembership(userId, TENANT);
+    const key = await seed.seedFile("dddddddd-dddd-4ddd-8ddd-000000000001", TENANT, userId);
+
+    const result = await runForgetCleanup({ db, registry: stack.registry, now: nowInstant() });
+
+    // NOT flipped to Deleted — the sub-tx rolled back.
+    expect(result.processedUserIds).not.toContain(userId);
+    // Failure surfaced for operator visibility.
+    expect(result.errors.some((e) => e.userId === userId && e.entityName === "fileRef")).toBe(true);
+    // Row NOT hard-deleted; binary NOT orphaned.
+    expect(await fileRowCount(TENANT, userId)).toBe(1);
+    expect(await base.exists(key)).toBe(true);
+    // User still pending deletion in the DB.
+    const row = await fetchOne<{ status: string }>(db, userTable, { id: userId });
+    expect(row?.status).toBe(USER_STATUS.DeletionRequested);
+  });
+
+  test("next run with storage healthy converges (idempotent delete) — user deleted, binary gone", async () => {
+    const userId = "cccccccc-cccc-4ccc-8ccc-000000000002";
+    await seed.seedForgetUser(userId);
+    await seed.seedMembership(userId, TENANT);
+    const key = await seed.seedFile("dddddddd-dddd-4ddd-8ddd-000000000002", TENANT, userId);
+
+    // First run: storage down → abort.
+    const first = await runForgetCleanup({ db, registry: stack.registry, now: nowInstant() });
+    expect(first.processedUserIds).not.toContain(userId);
+    expect(await base.exists(key)).toBe(true);
+
+    // Storage recovers; retry converges.
+    failDeletes = false;
+    const second = await runForgetCleanup({ db, registry: stack.registry, now: nowInstant() });
+
+    expect(second.processedUserIds).toContain(userId);
+    expect(await base.exists(key)).toBe(false);
+    expect(await fileRowCount(TENANT, userId)).toBe(0);
+    const row = await fetchOne<{ status: string }>(db, userTable, { id: userId });
+    expect(row?.status).toBe(USER_STATUS.Deleted);
+  });
+});
+
+// Same contract, but driven through the REAL dispatcher (POST run-forget-cleanup)
+// rather than calling runForgetCleanup with a top-level connection. The
+// dispatcher wraps the handler in an outer transaction, so ctx.db.raw is a
+// TransactionSql — which has `.savepoint`, not `.begin`. The per-user sub-tx
+// must open as a SAVEPOINT here; the previous `.begin`-only path threw on every
+// user when invoked this way (the cron path), so production deleted nobody while
+// these direct-connection tests stayed green. #214.
+describe("forget-cleanup through the real dispatcher :: per-user savepoint nests under the handler tx", () => {
+  const systemUser = {
+    id: "00000000-0000-4000-8000-0000000000ff",
+    tenantId: TENANT,
+    roles: ["SystemAdmin"],
+  };
+  type CleanupResult = {
+    readonly processedUserIds: readonly string[];
+    readonly hookCallsAttempted: number;
+    readonly errorCount: number;
+    readonly errors: ReadonlyArray<{ readonly userId: string; readonly entityName: string }>;
+  };
+  const RUN_FORGET = "user-data-rights:write:run-forget-cleanup";
+
+  test("dispatcher POST flips a due user to Deleted (SAVEPOINT inside the outer handler tx)", async () => {
+    failDeletes = false;
+    const userId = "cccccccc-cccc-4ccc-8ccc-000000000003";
+    await seed.seedForgetUser(userId);
+    await seed.seedMembership(userId, TENANT);
+    const key = await seed.seedFile("dddddddd-dddd-4ddd-8ddd-000000000003", TENANT, userId);
+
+    const result = await stack.http.writeOk<CleanupResult>(RUN_FORGET, {}, systemUser);
+
+    // Pre-fix this list was always empty — `.begin` is absent on the
+    // dispatcher's TransactionSql, so the per-user sub-tx threw for every user.
+    expect(result.processedUserIds).toContain(userId);
+    expect(result.errorCount).toBe(0);
+    expect(await base.exists(key)).toBe(false);
+    expect(await fileRowCount(TENANT, userId)).toBe(0);
+    const row = await fetchOne<{ status: string }>(db, userTable, { id: userId });
+    expect(row?.status).toBe(USER_STATUS.Deleted);
+  });
+
+  test("fail-closed + retry-convergence through the dispatcher (savepoint rolls back one user)", async () => {
+    const userId = "cccccccc-cccc-4ccc-8ccc-000000000004";
+    await seed.seedForgetUser(userId);
+    await seed.seedMembership(userId, TENANT);
+    const key = await seed.seedFile("dddddddd-dddd-4ddd-8ddd-000000000004", TENANT, userId);
+
+    // Storage down → fileRef hook throws → ROLLBACK TO SAVEPOINT undoes just
+    // this user; the outer handler tx still commits the run. User stays pending.
+    failDeletes = true;
+    const failed = await stack.http.writeOk<CleanupResult>(RUN_FORGET, {}, systemUser);
+    expect(failed.processedUserIds).not.toContain(userId);
+    expect(failed.errors.some((e) => e.userId === userId && e.entityName === "fileRef")).toBe(true);
+    expect(await base.exists(key)).toBe(true);
+    let row = await fetchOne<{ status: string }>(db, userTable, { id: userId });
+    expect(row?.status).toBe(USER_STATUS.DeletionRequested);
+
+    // Storage recovers → retry converges (idempotent delete).
+    failDeletes = false;
+    const ok = await stack.http.writeOk<CleanupResult>(RUN_FORGET, {}, systemUser);
+    expect(ok.processedUserIds).toContain(userId);
+    expect(await base.exists(key)).toBe(false);
+    row = await fetchOne<{ status: string }>(db, userTable, { id: userId });
+    expect(row?.status).toBe(USER_STATUS.Deleted);
+  });
+});