@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/user-data-rights/run-forget-cleanup.ts

@@ -0,0 +1,665 @@
+// Forget-Cleanup-Runner (S2.U5b) — pure-Function Pipeline.
+//
+// After the grace period (S2.U5a sets gracePeriodEnd) this runner iterates
+// over all users in DeletionRequested state and triggers the EXT_USER_DATA
+// delete hooks in every tenant the user is or was a member of (membership
+// history from kumiko_events).
+//
+// **Cross-tenant iteration:** a forget request in tenant A must remove the
+// user's data in ALL of their tenants, including tenants they left before
+// the request — see
+// docs/plans/architecture/user-data-rights.md "Cross-Tenant-Semantik".
+//
+// **Strategy-Dispatch:** Pro Entity entscheidet die data-retention-
+// policy (per-Tenant Override moeglich), ob "delete" oder "anonymize"
+// gefahren wird. blockDelete (Aufbewahrungs-Pflicht) ergibt zwingend
+// "anonymize" — Daten-Objekt bleibt physisch da, Personen-Bezug raus.
+//
+// **Per-User-Atomicity (advisor-pinned):** Jeder User wird in einer
+// eigenen Sub-Transaction abgewickelt (db.transaction → SAVEPOINT wenn
+// Outer-Tx aktiv, BEGIN sonst). Folge: ein failing Hook bei User A
+// rollt nur dessen Sub-Tx zurueck, User B + bisherige User-Status-Flips
+// bleiben commit-able. Ohne diese Sub-Tx wuerde der Outer-Dispatcher-Tx
+// (alle writeHandler laufen in `db.begin(...)`) den ganzen
+// Cleanup-Run beim ersten Hook-Throw zurueckrollen.
+//
+// **Idempotenz:** Hooks sind idempotent designed (siehe
+// engine/extensions/user-data.ts). Doppellauf nach Crash-Recovery muss
+// safe sein. Status-Flip auf "Deleted" am Ende sorgt dafuer, dass next
+// Lauf den User nicht mehr findet.
+//
+// **Error-Handling:** Ein hook der wirft soll den Lauf NICHT stoppen —
+// andere User sollen weiter abgearbeitet werden. Errors werden
+// gesammelt + zurueckgegeben fuer Operator-Visibility. Ein User mit
+// gefailten Hooks bleibt im DeletionRequested-Status (next Lauf
+// retried automatisch).
+
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configuredPiiSubjectKms,
+  type KmsAdapter,
+  subjectIdToKey,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import {
+  createTenantDb,
+  type DbRunner,
+  entityEventName,
+  executeRawQuery,
+  nullBlindIndexesForSubject,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  type EscapeHatchAuditSink,
+  EXT_USER_DATA,
+  EXT_USER_DATA_ORDER,
+  extensionUsageEscapeHatchReason,
+  type Registry,
+  type TenantId,
+  type TenantUserModel,
+  type UserDataDeleteHook,
+  type UserDataDeleteStrategy,
+  type UserDataStorageProvider,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEscapeHatchReporter,
+  UNATTRIBUTED_ACTOR,
+} from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  purgeSearchDocumentsForSubject,
+  type SearchAdapter,
+} from "@cosmicdrift/kumiko-framework/search";
+import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import {
+  resolveRetentionPolicyForTenant,
+  resolveTenantRetentionPreset,
+} from "../data-retention/index.js";
+import { decryptStoredPii, runInSubTransaction } from "../shared/index.js";
+import { tenantMembershipsTable } from "../tenant/index.js";
+import { USER_STATUS, userTable } from "../user/index.js";
+import { selectUsersDueForForgetCleanup } from "./db/queries/forget-cleanup.js";
+import { updateUserLifecycle } from "./lib/update-user-lifecycle.js";
+
+type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+
+/**
+ * Notification-Callback fuer den Forget-Cleanup-Pfad (Atom 5b). Pattern
+ * matched Atom 5 (Export). Throw bubbelt zum r.job-Wrap; jobs-feature
+ * persistiert den failed-Run in jobRunsTable (siehe
+ * jobs/__tests__/jobs-feature.integration.ts Scenario 2 — der throw-
+ * Pfad eines r.job-handlers wird dort gepinnt).
+ *
+ * **executedAt:** Zeitpunkt des delete-Flips. Wird als ISO-String
+ * uebergeben damit App-Author den frei in Email-Template einbauen kann.
+ *
+ * **tenantIds:** alle Memberships die der User vor dem Delete hatte.
+ * Email-Template kann das nutzen ("dein Account in Tenant X+Y wurde
+ * geloescht"). Bei orphan-User (0 Memberships) ist die Liste leer.
+ */
+export type SendDeletionExecutedEmailFn = (args: {
+  readonly userId: string;
+  readonly userEmail: string;
+  /** Stored user.locale (free-form, cached PRE-tx alongside the email) — lets
+   *  the default mailer render in the recipient's language. */
+  readonly userLocale: string | null;
+  readonly tenantIds: readonly TenantId[];
+  readonly executedAt: string;
+}) => Promise<void>;
+
+export interface RunForgetCleanupArgs {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  /**
+   * Now-Injection — Tests koennen den Wert pinnen ohne Date-Mock.
+   * Pattern aus data-retention/keep-for.ts (advisor-pinned).
+   */
+  readonly now: Instant;
+
+  /** Atom 5b — Email-Notification beim delete-flip. Optional;
+   *  ohne Callback laeuft Worker still (User hatte schon
+   *  request-deletion-Email + grace-period-Erinnerung). */
+  readonly sendDeletionExecutedEmail?: SendDeletionExecutedEmailFn;
+
+  /**
+   * Per-tenant file-storage-provider resolver (the forget cron builds it from
+   * the mounted file-foundation, mirroring the export cron). Threaded into
+   * every delete-hook's ctx so file-aware hooks erase binaries from the same
+   * store the upload/export path uses. Omitted → hooks skip binary cleanup.
+   */
+  readonly buildStorageProvider?: (
+    tenantId: TenantId,
+  ) => Promise<UserDataStorageProvider | undefined>;
+
+  /**
+   * KMS for crypto-shredding: erases the per-user subject key after the
+   * delete-hooks, inside the per-user sub-tx, right before the status flip.
+   * Defaults to the boot-configured adapter (configurePiiSubjectKms);
+   * explicit arg is the test seam. Omitted + none configured → plaintext
+   * deployment, nothing to shred.
+   */
+  readonly kms?: KmsAdapter;
+
+  /**
+   * Search adapter for purging derived Meili docs of searchable subject-PII
+   * (#1610). Same seam as forget-subject. Omitted → no search purge (apps
+   * without Meili).
+   */
+  readonly searchAdapter?: SearchAdapter;
+
+  /**
+   * App-level tenant-occupancy model (resolved from the `tenantModel` config by
+   * the cron/handler). The pipeline refines it PER TENANT with a sole-member
+   * check before handing `tenantModel` to each delete-hook, so tenant-scoped
+   * erasure only happens where it's actually safe. Omitted → `"multi-user"`
+   * (no tenant-scoped erasure).
+   */
+  readonly tenantModel?: TenantUserModel;
+
+  // fw#2914 — sourced from the owning job's ctx (_escapeHatchAuditSink,
+  // systemUser.id); attributes+audits any EXT_USER_DATA usage's declared
+  // escapeHatch when its delete hook calls ctx.db.unsafeRaw(reason).
+  readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
+  readonly actor?: string;
+}
+
+export interface ForgetCleanupError {
+  readonly userId: string;
+  readonly tenantId: TenantId;
+  readonly entityName: string;
+  readonly message: string;
+}
+
+/** A hook reporting `{status:"incomplete", reason}` — no throw, no
+ *  rollback, the user still gets flipped to Deleted (see Header
+ *  "incomplete is not a hard failure"). Collected for operator
+ *  visibility, NOT in `errors` (those stand for hook throws + rollback). */
+export interface ForgetCleanupIncomplete {
+  readonly userId: string;
+  readonly tenantId: TenantId;
+  readonly entityName: string;
+  readonly reason: string;
+  /** True when a LATER hook in the same user's sub-tx threw, rolling back
+   *  the DB rows (including the status flip) — but this hook's own
+   *  non-transactional side effect (e.g. an already-issued S3 delete,
+   *  a provider API call) already ran and does NOT get undone by that
+   *  rollback. The user is still DeletionRequested and will retry, but
+   *  this partial external effect needs its own operator follow-up. */
+  readonly rolledBack: boolean;
+}
+
+export interface RunForgetCleanupResult {
+  /** User die in diesem Lauf von DeletionRequested → Deleted geflippt wurden. */
+  readonly processedUserIds: readonly string[];
+  /** Anzahl entity-hook-calls die wirklich gelaufen sind (success oder fail). */
+  readonly hookCallsAttempted: number;
+  /** Hook-Errors fuer Operator-Visibility. Lauf bricht nicht ab — siehe Header. */
+  readonly errors: readonly ForgetCleanupError[];
+  /** Hooks that reported `{status:"incomplete"}` — partial success, user still Deleted. */
+  readonly incomplete: readonly ForgetCleanupIncomplete[];
+}
+
+interface HookEntry {
+  readonly entityName: string;
+  readonly deleteHook: UserDataDeleteHook;
+  /** Lower runs first. Owner-column-preserving redaction declares a negative
+   * order so it precedes owner-nulling hooks on the same entity (see sort below). */
+  readonly order: number;
+  readonly escapeHatchReason: string | undefined;
+}
+
+function buildHookDb(
+  db: DbRunner,
+  tenantId: TenantId,
+  entry: HookEntry,
+  args: { readonly escapeHatchAuditSink?: EscapeHatchAuditSink; readonly actor?: string },
+) {
+  const report = createEscapeHatchReporter({
+    handler: `${EXT_USER_DATA}:${entry.entityName}`,
+    tenantId,
+    actor: args.actor ?? UNATTRIBUTED_ACTOR,
+    sink: args.escapeHatchAuditSink,
+  });
+  return createTenantDb(db, tenantId, "tenant", undefined, undefined, undefined, {
+    unsafeRaw:
+      entry.escapeHatchReason !== undefined ? { reason: entry.escapeHatchReason } : undefined,
+    report,
+  });
+}
+
+// EXT_USER_DATA delete-hooks default here; a hook that redacts data keyed on an
+// owner column it doesn't own must register a lower order so it runs BEFORE any
+// hook that nulls that column. See custom-fields wire-user-data-rights.ts.
+const HOOK_ORDER_DEFAULT = EXT_USER_DATA_ORDER.DEFAULT;
+
+// Hook-reported reasons are external input (provider error messages can embed
+// user-controlled filenames/emails) — strip newlines before a single-line
+// console.warn so a crafted reason can't forge extra log lines, and cap the
+// length against a log-flood. The unsanitized reason still lands in the
+// returned `incomplete` entry untouched.
+export function sanitizeReasonForLog(reason: string): string {
+  return reason.replace(/[\r\n]+/g, " ").slice(0, 500);
+}
+
+export async function runForgetCleanup(
+  args: RunForgetCleanupArgs,
+): Promise<RunForgetCleanupResult> {
+  const { db, registry, now, sendDeletionExecutedEmail, buildStorageProvider } = args;
+  const kms = args.kms ?? configuredPiiSubjectKms();
+  const appTenantModel: TenantUserModel = args.tenantModel ?? "multi-user";
+
+  // Step 1: Find users with expired grace period.
+  const dueUsers = await selectUsersDueForForgetCleanup(
+    db as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
+    USER_STATUS.DeletionRequested,
+    now.toString(),
+  );
+
+  if (dueUsers.length === 0) {
+    return { processedUserIds: [], hookCallsAttempted: 0, errors: [], incomplete: [] };
+  }
+
+  // Step 2: Sammle alle EXT_USER_DATA-Usages einmalig — Liste der
+  // (entityName, deleteHook)-Pairs aller registrierten Provider-Features.
+  const usages = registry.getExtensionUsages(EXT_USER_DATA);
+  const hookEntries: HookEntry[] = usages
+    .map((u): HookEntry | null => {
+      const opts = (u.options ?? {}) as { delete?: UserDataDeleteHook; order?: number }; // @cast-boundary engine-payload
+      if (!opts.delete) return null;
+      const order = typeof opts.order === "number" ? opts.order : HOOK_ORDER_DEFAULT;
+      return {
+        entityName: u.entityName,
+        deleteHook: opts.delete,
+        order,
+        escapeHatchReason: extensionUsageEscapeHatchReason(u),
+      };
+    })
+    .filter((x): x is HookEntry => x !== null)
+    // Order ascending. Array.sort is ES2019-stable, so equal orders keep
+    // registration order; correctness here needs only distinct orders, not
+    // stability. Guarantees owner-preserving redaction (negative order) runs
+    // before owner-nulling hooks on the same entity, independent of feature
+    // registration order.
+    .sort((a, b) => a.order - b.order);
+
+  const errors: ForgetCleanupError[] = [];
+  const incomplete: ForgetCleanupIncomplete[] = [];
+  const processedUserIds: string[] = [];
+  let hookCallsAttempted = 0;
+
+  // Step 3: Pro User iterieren — eigene Sub-Tx pro User (siehe Header).
+  for (const user of dueUsers) {
+    const userResult = await processUser({
+      db,
+      registry,
+      userId: user.id,
+      hookEntries,
+      buildStorageProvider,
+      appTenantModel,
+      kms,
+      searchAdapter: args.searchAdapter,
+      escapeHatchAuditSink: args.escapeHatchAuditSink,
+      actor: args.actor,
+    });
+    hookCallsAttempted += userResult.hookCallsAttempted;
+    errors.push(...userResult.errors);
+    incomplete.push(...userResult.incomplete);
+    if (userResult.success) {
+      processedUserIds.push(user.id);
+
+      // Atom 5b — Email-Notification nach success-flip. userEmail wurde
+      // VOR der Tx gecacht (user-Hook anonymisiert in der Tx).
+      //
+      // Best-effort: ein Email-Throw fuer User A darf nicht den Batch
+      // killen — User A ist bereits geloescht (Sub-Tx committed), und
+      // die Users B, C, ... muessen noch verarbeitet werden. Throw waere
+      // hier ein Bug: r.job-Wrap markiert den Run failed, retry findet
+      // keine User mehr im DeletionRequested+grace-expired-Status (alle
+      // schon Deleted) → silent miss. console.warn ist die einzige
+      // Operator-Sichtbarkeit — runForgetCleanup-args fuehren AppContext.
+      // log aktuell nicht durch (pure-function-Pattern).
+      if (sendDeletionExecutedEmail && userResult.userEmailBeforeDelete) {
+        try {
+          await sendDeletionExecutedEmail({
+            userId: user.id,
+            userEmail: userResult.userEmailBeforeDelete,
+            userLocale: userResult.userLocaleBeforeDelete,
+            tenantIds: userResult.tenantIdsBeforeDelete,
+            executedAt: now.toString(),
+          });
+        } catch (err) {
+          // biome-ignore lint/suspicious/noConsole: operator-visibility for email-send-failure
+          console.warn(
+            `[user-data-rights:run-forget-cleanup] sendDeletionExecutedEmail failed userId=${user.id} err=${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      }
+    }
+  }
+
+  return { processedUserIds, hookCallsAttempted, errors, incomplete };
+}
+
+interface ProcessUserResult {
+  readonly success: boolean;
+  readonly hookCallsAttempted: number;
+  readonly errors: readonly ForgetCleanupError[];
+  readonly incomplete: readonly ForgetCleanupIncomplete[];
+  /** Atom 5b: userEmail VOR Tx gecacht (user-Hook anonymisiert in Tx).
+   *  null wenn user-Row beim Pre-Tx-Lookup nicht (mehr) existiert oder
+   *  email leer ist. */
+  readonly userEmailBeforeDelete: string | null;
+  /** user.locale VOR Tx gecacht — Default-Mailer rendert in Empfaenger-Sprache. */
+  readonly userLocaleBeforeDelete: string | null;
+  /** Tenant-Memberships VOR Tx — Email-Template kann das nutzen. */
+  readonly tenantIdsBeforeDelete: readonly TenantId[];
+}
+
+async function processUser(args: {
+  db: DbRunner;
+  registry: Registry;
+  userId: string;
+  hookEntries: readonly HookEntry[];
+  buildStorageProvider?: (tenantId: TenantId) => Promise<UserDataStorageProvider | undefined>;
+  appTenantModel: TenantUserModel;
+  kms?: KmsAdapter;
+  searchAdapter?: SearchAdapter;
+  escapeHatchAuditSink?: EscapeHatchAuditSink;
+  actor?: string;
+}): Promise<ProcessUserResult> {
+  const { db, registry, userId, hookEntries, buildStorageProvider, appTenantModel, kms } = args;
+  const errors: ForgetCleanupError[] = [];
+  const incomplete: Omit<ForgetCleanupIncomplete, "rolledBack">[] = [];
+  let hookCallsAttempted = 0;
+
+  // Atom 5b — userEmail VOR der Tx cachen. user-Hook (user-data-rights-
+  // defaults) anonymisiert email/displayName/passwordHash IN der Tx.
+  // Nach der Tx ist email = "deleted-{id}@{tenant}.example" oder NULL.
+  // Memory-cache laesst Atom-5b-Callback nach success-flip den
+  // ORIGINAL-email an App-Author-Callback geben.
+  const userPreTx = await fetchOne<{ email: string | null; locale: string | null }>(db, userTable, {
+    id: userId,
+  });
+  const userEmailBeforeDelete =
+    userPreTx?.email && userPreTx.email.length > 0
+      ? await decryptStoredPii(userPreTx.email, "email", "user-data-rights:forget-cleanup")
+      : null;
+  const userLocaleBeforeDelete = userPreTx?.locale ?? null;
+
+  // Memberships fuer diesen User holen — alle Tenants in denen er Mitglied ist.
+  const memberships = await selectMany<{ tenantId: TenantId }>(db, tenantMembershipsTable, {
+    userId,
+  });
+  // tenant-Liste fuer Atom 5b Email — Memberships VOR Tx, weil hooks
+  // memberships in der Tx loeschen. Orphan-User (0 memberships) liefert
+  // [] in Email-args; App-Author-Template kann das case-handlen.
+  const tenantIdsBeforeDelete: readonly TenantId[] = memberships.map((m) => m.tenantId);
+
+  // Departed tenants: removeMember deletes only the projection row, so data
+  // the user left behind there (e.g. note mentions) must still be reached.
+  const historicalTenantIds = await readHistoricalMembershipTenantIds(db, userId);
+  const hookTenantIds = [...new Set([...tenantIdsBeforeDelete, ...historicalTenantIds])];
+
+  // Edge case "0 tenants" (neither membership nor history): the hook loop still
+  // runs with a pseudo tenant. The user hook is tenant-agnostic and MUST run so
+  // email/displayName/passwordHash get anonymized; tenant-scoped hooks find
+  // nothing there and no-op. Without this path status=Deleted would be set
+  // while the original PII stays — compliant-looking, but not compliant.
+  const tenantList: TenantId[] =
+    hookTenantIds.length > 0 ? hookTenantIds : [SYSTEM_TENANT_ID_FOR_ORPHANS];
+
+  // Per-User-Sub-Tx: hooks + status-flip atomar. Bei Hook-Throw rollt
+  // nur dieser User zurueck, andere User bleiben commit-fest. Die Sub-Tx
+  // nestet korrekt: eine Top-Level-Connection oeffnet sie via `.begin`
+  // (BEGIN), eine TransactionSql — der Fall im Dispatcher, wo jeder
+  // writeHandler bereits IN der Outer-Tx laeuft — via `.savepoint`
+  // (SAVEPOINT). Siehe runInSubTransaction.
+  let txSucceeded = false;
+  let currentTenantId: TenantId | null = null;
+  let currentEntityName: string | null = null;
+  try {
+    await runInSubTransaction(db, async (tx) => {
+      // Discover + purge search docs for this subject BEFORE any delete
+      // hook runs (fw#1611). purgeSearchDocumentsForSubject finds candidate
+      // rows via a live SELECT on each entity's read-table — a hook that
+      // hard-deletes a row (UserDataDeleteStrategy "delete") makes that row
+      // invisible to a purge running afterward, permanently stranding its
+      // plaintext PII in the search index. Running the purge first means it
+      // sees every row a hook is about to touch, delete or not.
+      if (args.searchAdapter) {
+        const subject = { kind: "user" as const, userId };
+        await purgeSearchDocumentsForSubject(
+          tx,
+          registry.features,
+          args.searchAdapter,
+          subjectIdToKey(subject),
+          subject,
+        );
+      }
+
+      for (const tenantId of tenantList) {
+        currentTenantId = tenantId;
+        // Refine the app-level model to THIS tenant: "single-user" only if the
+        // tenant truly has one member, so a stray invite can't let a per-user
+        // forget erase a co-member's tenant-scoped data (money-path safety).
+        const tenantModel = await resolveEffectiveTenantModel(tx, tenantId, appTenantModel);
+        // Resolved ONCE per tenant (not per hookEntry below) — the compliance-
+        // profile lookup it does internally is a single indexed read; N entities
+        // re-deriving it per tenant would be N reads for the same answer.
+        const tenantPreset = await resolveTenantRetentionPreset({ db: tx, registry, tenantId });
+        for (const entry of hookEntries) {
+          currentEntityName = entry.entityName;
+          const policy = await resolveRetentionPolicyForTenant({
+            db: tx,
+            registry,
+            tenantId,
+            entityName: entry.entityName,
+            preloadedTenantPreset: tenantPreset,
+          });
+          const strategy = policyToStrategy(policy.policy?.strategy ?? null);
+
+          hookCallsAttempted++;
+          const hookResult = await entry.deleteHook(
+            {
+              db: buildHookDb(tx, tenantId, entry, {
+                escapeHatchAuditSink: args.escapeHatchAuditSink,
+                actor: args.actor,
+              }),
+              registry,
+              tenantId,
+              userId,
+              buildStorageProvider,
+              tenantModel,
+              userEmailBeforeDelete,
+            },
+            strategy,
+          );
+          // "incomplete" is not a hard failure (see Header): no throw,
+          // no rollback, eraseKey + status flip proceed unchanged.
+          // Only collected + logged for operator visibility.
+          if (hookResult?.status === "incomplete") {
+            incomplete.push({
+              userId,
+              tenantId,
+              entityName: entry.entityName,
+              reason: hookResult.reason,
+            });
+            // biome-ignore lint/suspicious/noConsole: operator-visibility for partial hook completion
+            console.warn(
+              `[user-data-rights:run-forget-cleanup] hook incomplete userId=${userId} tenantId=${tenantId} entityName=${entry.entityName} reason=${sanitizeReasonForLog(hookResult.reason)}`,
+            );
+          }
+        }
+      }
+
+      // Crypto-shredding: erase the user's subject key AFTER the hooks and
+      // BEFORE the status flip. The KMS is not a tx participant, so ordering
+      // is what makes this crash-safe: eraseKey-throw → tx rollback → user
+      // stays DeletionRequested → next run retries; flip-throw after a
+      // successful erase → retry re-runs the idempotent hooks and eraseKey
+      // (contractually a no-op on an erased/unknown subject). Erasing after
+      // the flip instead would risk a permanent silent miss: user already
+      // Deleted, no run ever picks him up again, key stays live.
+      if (kms) {
+        await kms.eraseKey(
+          { kind: "user", userId },
+          {
+            requestId: "user-data-rights:run-forget-cleanup",
+            userId,
+            eraseReason: "user-data-rights:forget",
+          },
+        );
+        // Blind-Index-Sweep (#818): bidx-Spalten des erased Subjects sofort
+        // nullen — sonst bliebe der deterministische HMAC bis zum nächsten
+        // Rebuild equality-matchbar (Linkage-Fenster). In der Sub-Tx, damit
+        // ein Rollback auch den Sweep zurücknimmt.
+        await nullBlindIndexesForSubject(
+          tx,
+          registry.features,
+          subjectIdToKey({ kind: "user", userId }),
+        );
+      }
+
+      // Status-Flip in derselben Sub-Tx. Falls einer der Hooks oben
+      // geworfen hat, kommen wir hier nicht an — die Tx rollback'd
+      // alles, der User bleibt im DeletionRequested-Status, naechster
+      // Run retried.
+      await updateUserLifecycle(tx, userId, { status: USER_STATUS.Deleted });
+      txSucceeded = true;
+    });
+  } catch (e) {
+    // currentTenantId/currentEntityName tracken den Failing-Hook —
+    // Operator sieht "Hook fileRef in Tenant A failed for user X" statt
+    // generisches "<sub-transaction>".
+    errors.push({
+      userId,
+      tenantId: currentTenantId ?? ("" as TenantId),
+      entityName: currentEntityName ?? "<unknown>",
+      message: e instanceof Error ? e.message : String(e),
+    });
+  }
+
+  return {
+    success: txSucceeded,
+    hookCallsAttempted,
+    errors,
+    // Reported either way — a rolled-back sub-tx doesn't undo an
+    // "incomplete" hook's own non-transactional side effect (S3 delete,
+    // provider call), so dropping the report entirely would hide exactly
+    // the case its own reason string describes ("would report a
+    // not-yet-deleted user as partially cleaned up" — true of the DB rows,
+    // not of that external effect). `rolledBack` lets the operator tell
+    // the two situations apart instead of losing the signal outright.
+    incomplete: incomplete.map((i) => ({ ...i, rolledBack: !txSucceeded })),
+    userEmailBeforeDelete,
+    userLocaleBeforeDelete,
+    tenantIdsBeforeDelete,
+  };
+}
+
+// Pseudo-Tenant fuer User ohne aktive Memberships. RFC4122-konforme
+// Null-UUID. Tenant-scoped Hooks finden hier nichts (no-op),
+// tenant-agnostische Hooks (z.B. user) operieren auf der globalen
+// User-Row und ignorieren tenantId.
+const SYSTEM_TENANT_ID_FOR_ORPHANS = "00000000-0000-0000-0000-000000000000" as TenantId;
+
+// "single-user" requires BOTH the app config AND a runtime sole-member check —
+// the config asserts the deployment model, the count guards against a stray
+// invite that would make a per-user forget delete a co-member's tenant-scoped
+// data. Only queried when the app opted into "single-user" (multi-user apps
+// never reach the destructive path, so no extra query for them).
+async function resolveEffectiveTenantModel(
+  db: DbRunner,
+  tenantId: TenantId,
+  appTenantModel: TenantUserModel,
+): Promise<TenantUserModel> {
+  if (appTenantModel !== "single-user") return "multi-user";
+  // Only "exactly one member vs. more than one" matters here — a LIMIT 2
+  // read answers that without pulling every historical membership row.
+  const members = await selectMany<{ userId: string }>(
+    db,
+    tenantMembershipsTable,
+    { tenantId },
+    { limit: 2 },
+  );
+  if (members.length !== 1) return "multi-user";
+  return (await everHadMultipleMembers(db, tenantId)) ? "multi-user" : "single-user";
+}
+
+// removeMemberWrite only deletes the tenant-membership PROJECTION row — the
+// event history survives forever, and a departed member's own tenant-scoped
+// data rows (contributor-style records with no per-user column) can
+// outlive their membership (ent#346). A live count of 1 is therefore not
+// enough: a tenant that ever had >1 distinct member must stay multi-user for
+// the forget path even after everyone but one is removed, or the sole
+// remaining member's forget request wipes the departed co-member's leftover
+// rows.
+//
+// Filter by payload->>'tenantId' (not the event column tenant_id): cross-
+// tenant SystemAdmin adds land under the actor's tenant_id.
+//
+// Counting created-ROWS against distinct userIds latched a tenant to
+// multi-user as soon as its sole member was removed and re-added (#2608) —
+// two created-events, one identity, no co-member ever. The fail-safe only
+// needs to cover payloads whose userId cannot be READ, so the unreadable
+// remainder is measured directly instead of inferred from the row count.
+// NULLIF folds an empty-string userId into that remainder (it names nobody).
+async function everHadMultipleMembers(db: DbRunner, tenantId: TenantId): Promise<boolean> {
+  const eventType = entityEventName("tenant-membership", "created");
+  const rows = await executeRawQuery<{
+    event_count: number;
+    readable_users: number;
+    distinct_users: number;
+  }>(
+    db,
+    `SELECT
+       COUNT(*)::int AS event_count,
+       COUNT(NULLIF(payload->>'userId', ''))::int AS readable_users,
+       COUNT(DISTINCT NULLIF(payload->>'userId', ''))::int AS distinct_users
+     FROM kumiko_events
+     WHERE aggregate_type = 'tenant-membership'
+       AND type = $1
+       AND payload->>'tenantId' = $2`,
+    [eventType, tenantId],
+  );
+  const row = rows[0];
+  if (!row) return false;
+  if (row.distinct_users > 1) return true;
+  // Unreadable / missing userId payloads: fail-safe to multi-user, each one
+  // could name a second member.
+  return row.event_count > row.readable_users;
+}
+
+// Filter by payload (not the event column tenant_id) for the same reason as
+// everHadMultipleMembers: cross-tenant SystemAdmin adds are billed to the
+// actor's tenant.
+async function readHistoricalMembershipTenantIds(
+  db: DbRunner,
+  userId: string,
+): Promise<TenantId[]> {
+  const rows = await executeRawQuery<{ tenant_id: string }>(
+    db,
+    `SELECT DISTINCT payload->>'tenantId' AS tenant_id
+     FROM kumiko_events
+     WHERE aggregate_type = 'tenant-membership'
+       AND type = $1
+       AND payload->>'userId' = $2
+       AND NULLIF(payload->>'tenantId', '') IS NOT NULL`,
+    [entityEventName("tenant-membership", "created"), userId],
+  );
+  return rows.map((row) => row.tenant_id as TenantId); // @cast-boundary db-row
+}
+
+// Mapping retention.strategy → user-data-rights.UserDataDeleteStrategy.
+//   - "anonymize" / "blockDelete" → "anonymize" (Aufbewahrungs-Pflicht
+//     blockDelete: Daten muessen physisch bleiben, nur Personen-Bezug raus)
+//   - "hardDelete" / "softDelete" / null → "delete" (Default)
+//
+// Eigene Funktion damit Strategie-Drift zwischen retention-strategies
+// und user-data-rights-Hooks an EINER Stelle dokumentiert + getestet
+// werden kann (siehe run-forget-cleanup.test.ts).
+export function policyToStrategy(
+  retentionStrategy: "hardDelete" | "softDelete" | "anonymize" | "blockDelete" | null,
+): UserDataDeleteStrategy {
+  if (retentionStrategy === "anonymize" || retentionStrategy === "blockDelete") {
+    return "anonymize";
+  }
+  return "delete";
+}