@cosmicdrift/kumiko-samples 0.404.0 → 0.405.0

package/packages/bundled-features/src/tenant/handlers/team-list.query.ts

@@ -14,8 +14,11 @@ import { decryptStoredPii, mapWithConcurrency } from "../../shared/index.ts";
 import { userTable } from "../../user/index.ts";
 import { INVITATION_STATUS, tenantInvitationsTable } from "../invitation-table.ts";
 import { tenantMembershipsTable } from "../membership-table.ts";
-
-const KMS_POOL_CONCURRENCY = 4;
+import {
+  decryptMemberUsers,
+  KMS_POOL_CONCURRENCY,
+  type MemberUserRow,
+} from "./decrypt-member-users.ts";
 
 type TeamStatus = "active" | "pending";
 
@@ -115,11 +118,7 @@ export const teamListQuery = definePagedQueryHandler({
     const membershipRows = await selectMany(db, tenantMembershipsTable, { tenantId });
     const userIds = [...new Set(membershipRows.map((row) => String(row["userId"])))];
     const users =
-      userIds.length > 0
-        ? await selectMany<{ id: unknown; email?: unknown; displayName?: unknown }>(db, userTable, {
-            id: userIds,
-          })
-        : [];
+      userIds.length > 0 ? await selectMany<MemberUserRow>(db, userTable, { id: userIds }) : [];
 
     const lastSeenByUserId = new Map<string, Temporal.Instant>();
     if (userIds.length > 0) {
@@ -147,21 +146,10 @@ export const teamListQuery = definePagedQueryHandler({
     }
 
     // Bounded, not Promise.all/sequential-per-item: shares the KMS
-    // adapter's small dedicated pool (max 4, see members.query.ts) with the
+    // adapter's small dedicated pool (max 4, see decrypt-member-users.ts) with the
     // invitations decrypt below — the two passes run one after the other
     // (await, not Promise.all), so combined concurrency never exceeds 4.
-    const decryptedUsers = await mapWithConcurrency(users, KMS_POOL_CONCURRENCY, async (user) => {
-      const email =
-        typeof user.email === "string"
-          ? await decryptStoredPii(user.email, "email", "tenant:team-list")
-          : null;
-      const displayName =
-        typeof user.displayName === "string"
-          ? await decryptStoredPii(user.displayName, "displayName", "tenant:team-list")
-          : null;
-      return { userId: String(user.id), email, displayName };
-    });
-    const decryptedByUserId = new Map(decryptedUsers.map((d) => [d.userId, d]));
+    const decryptedByUserId = await decryptMemberUsers(users, "tenant:team-list");
 
     const memberRows: TeamRow[] = membershipRows.map((row) => {
       const userId = String(row["userId"]);

package/packages/bundled-features/src/tenant-lifecycle/archive-and-delete-tenant-rows.ts

@@ -0,0 +1,28 @@
+import type { EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import { declareEscapeHatch, type TenantDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";
+import { archiveStream } from "@cosmicdrift/kumiko-framework/event-store";
+
+export const TENANT_DESTROY_ARCHIVED_BY = "tenant-lifecycle:destroy";
+export const TENANT_DESTROY_ARCHIVE_REASON = "tenant_destroy";
+
+// Archiving first means a later projection rebuild cannot resurrect the deleted rows.
+export async function archiveAndDeleteTenantRows(
+  ctx: TenantDataHookCtx,
+  table: EntityTableMeta,
+  aggregateType: string,
+  escapeHatchReason: string,
+): Promise<readonly string[]> {
+  declareEscapeHatch({ reason: escapeHatchReason });
+  const rows = await ctx.db.selectMany<{ id: string }>(table, { tenantId: ctx.tenantId });
+  for (const row of rows) {
+    await archiveStream(ctx.db.unsafeRaw(), {
+      tenantId: ctx.tenantId,
+      aggregateId: row.id,
+      aggregateType,
+      archivedBy: TENANT_DESTROY_ARCHIVED_BY,
+      reason: TENANT_DESTROY_ARCHIVE_REASON,
+    });
+  }
+  await ctx.db.deleteMany(table, { tenantId: ctx.tenantId });
+  return rows.map((row) => row.id);
+}

package/packages/bundled-features/src/tenant-lifecycle/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "archiveAndDeleteTenantRows for tenant-destroy hooks",
+    "detail": "@cosmicdrift/kumiko-bundled-features/tenant-lifecycle exports archiveAndDeleteTenantRows(ctx, table, aggregateType, escapeHatchReason), which archives each row's event stream and then deletes the tenant's rows, plus the TENANT_DESTROY_ARCHIVED_BY and TENANT_DESTROY_ARCHIVE_REASON constants. inbound-mail-foundation uses the helper, billing-foundation the constants."
+  },
   {
     "version": "0.389.0",
     "type": "fix",

package/packages/bundled-features/src/tenant-lifecycle/index.ts

@@ -1,3 +1,8 @@
+export {
+  archiveAndDeleteTenantRows,
+  TENANT_DESTROY_ARCHIVE_REASON,
+  TENANT_DESTROY_ARCHIVED_BY,
+} from "./archive-and-delete-tenant-rows.ts";
 export {
   TENANT_DESTRUCTION_STAGES,
   TENANT_LIFECYCLE_FEATURE,

package/packages/bundled-features/src/tenant-lifecycle/stages.ts

@@ -92,6 +92,7 @@ const tenantMembershipCrud = createEventStoreExecutor(
 // earlier hook that keeps reporting done:false can use up the budget, so later chunking
 // hooks time out with nothing processed until it finishes.
 function newOutcomeAccumulator(): {
+  // biome-ignore lint/suspicious/noConfusingVoidType: takes the awaited result of a destroy hook, whose public type allows void
   add: (result: TenantDestroyHookResult | void) => void;
   outcome: () => StageRunOutcome;
 } {

package/packages/bundled-features/src/tier-engine/feature.ts

@@ -495,7 +495,7 @@ export function createTierEngineFeature<
       // point AND registers itself as the default plugin. Other features could
       // register there later (e.g. a future toggle-only resolver), but only one
       // plugin wins — see the "single-plugin" comment on findTierResolverUsage.
-      r.extendsRegistrar(TENANT_TIER_RESOLVER_EXT, { onRegister: () => {} });
+      r.extendsRegistrar(TENANT_TIER_RESOLVER_EXT, {});
 
       // Plugin-registration: framework's runDevApp/runProdApp picks this up
       // post-stack-setup, calls build(deps), wires effectiveFeatures.

package/packages/bundled-features/src/user-data-rights/COMPLIANCE.md

@@ -16,34 +16,34 @@ Dieses Dokument bündelt die **technischen Fakten** zur DSGVO-Pipeline
 
 ## 1. Endpoint → Artikel-Mapping
 
-| Artikel | Endpoint / Runner | Wer ruft auf | Was passiert |
-|---------|-------------------|--------------|--------------|
-| **Art. 15 (Auskunft, light)** | `user-data-rights:query:my-audit-log` | User | Liest eigene Framework-Events aus `kumiko_events` (account-weit über alle Memberships). Filterbar nach `eventType`, `aggregateType`, `from`/`to`. Domain-Entities ohne `ctx.events.append` erscheinen NICHT — die kommen im Export-Bundle (Art. 20). |
-| **Art. 15 + 20 (Auskunft + Portabilität)** | `user-data-rights:write:request-export` | User | Async Job → ZIP mit user-Profil + fileRefs + alle EXT_USER_DATA-Provider-Daten (cross-tenant) + signed Magic-Link per Email. Idempotent: nur 1 active Job pro User (`ACTIVE_JOB_CONSTRAINT`). |
-| **Art. 15 + 20** | `GET /user-export/by-token` (interstitial) + `POST /user-export/by-token` (exchange) | Anonym (Magic-Link-Pfad) | Email-Link trägt den Token als URL-Fragment (`#token=`, nie an den Server gesendet, issue #1271); Interstitial-Script liest das Fragment client-seitig und tauscht es per POST-Body gegen die signed Storage-URL. Kein `?token=`-Query-Fallback (#1512) — Query-Param landet unveränderlich in Proxy-/Access-Logs. Multi-use innerhalb TTL. Audit: `lastUsedAt`, `lastUsedFromIp`, `lastUsedUserAgent`. |
-| **Art. 15 + 20** | `GET /user-export/by-job/:jobId` | User (Session-Auth) | UI-Klick-Pfad. Cross-tenant-same-user: User in Tenant B kann Job aus Tenant A laden wenn er der Owner ist. |
-| **Art. 17 (Löschung)** | `user-data-rights:write:request-deletion` | User | Soft-Delete: `status=DeletionRequested` + `gracePeriodEnd = now + profile.gracePeriod`. Cron `run-forget-cleanup` führt nach Grace die Anonymisierung durch. |
-| **Art. 17** | `user-data-rights:write:cancel-deletion` | User | Während Grace: status zurück auf `Active`. |
-| **Art. 17** | `run-forget-cleanup` (Cron) | System | Findet User mit `status=DeletionRequested AND gracePeriodEnd < now`. Pro User Sub-TX über alle EXT_USER_DATA-Provider mit Strategy aus `retention.policyFor`. user-Hook anonymisiert (PII raus, Sentinel-Email). |
-| **Art. 18 (Restriction)** | `user-data-rights:write:restrict-account` | Admin / SystemAdmin | Status-Flip → Auth-Middleware-Guard blockt Logins. `sessions.revokeAllForUser` killt aktive Sessions. |
-| **Art. 18** | `user-data-rights:write:lift-restriction` | Admin / SystemAdmin | Restriction aufheben. |
-| **Operator (DPO)** | `user-data-rights:query:list-download-attempts` | Admin / SystemAdmin | Brute-Force-Detection: zeigt invalid Download-Versuche (notFound / expired / failed / signedUrlNotSupported) gefiltert nach Result, IP, Zeitraum. |
+| Artikel                                    | Endpoint / Runner                                                                    | Wer ruft auf             | Was passiert                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------------------------------ | ------------------------------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Art. 15 (Auskunft, light)**              | `user-data-rights:query:my-audit-log`                                                | User                     | Liest eigene Framework-Events aus `kumiko_events` (account-weit über alle Memberships). Filterbar nach `eventType`, `aggregateType`, `from`/`to`. Domain-Entities ohne `ctx.events.append` erscheinen NICHT — die kommen im Export-Bundle (Art. 20).                                                                                                                                                    |
+| **Art. 15 + 20 (Auskunft + Portabilität)** | `user-data-rights:write:request-export`                                              | User                     | Async Job → ZIP mit user-Profil + fileRefs + alle EXT_USER_DATA-Provider-Daten (cross-tenant) + signed Magic-Link per Email. Idempotent: nur 1 active Job pro User (`ACTIVE_JOB_CONSTRAINT`).                                                                                                                                                                                                           |
+| **Art. 15 + 20**                           | `GET /user-export/by-token` (interstitial) + `POST /user-export/by-token` (exchange) | Anonym (Magic-Link-Pfad) | Email-Link trägt den Token als URL-Fragment (`#token=`, nie an den Server gesendet, issue #1271); Interstitial-Script liest das Fragment client-seitig und tauscht es per POST-Body gegen die signed Storage-URL. Kein `?token=`-Query-Fallback (#1512) — Query-Param landet unveränderlich in Proxy-/Access-Logs. Multi-use innerhalb TTL. Audit: `lastUsedAt`, `lastUsedFromIp`, `lastUsedUserAgent`. |
+| **Art. 15 + 20**                           | `GET /user-export/by-job/:jobId`                                                     | User (Session-Auth)      | UI-Klick-Pfad. Cross-tenant-same-user: User in Tenant B kann Job aus Tenant A laden wenn er der Owner ist.                                                                                                                                                                                                                                                                                              |
+| **Art. 17 (Löschung)**                     | `user-data-rights:write:request-deletion`                                            | User                     | Soft-Delete: `status=DeletionRequested` + `gracePeriodEnd = now + profile.gracePeriod`. Cron `run-forget-cleanup` führt nach Grace die Anonymisierung durch.                                                                                                                                                                                                                                            |
+| **Art. 17**                                | `user-data-rights:write:cancel-deletion`                                             | User                     | Während Grace: status zurück auf `Active`.                                                                                                                                                                                                                                                                                                                                                              |
+| **Art. 17**                                | `run-forget-cleanup` (Cron)                                                          | System                   | Findet User mit `status=DeletionRequested AND gracePeriodEnd < now`. Pro User Sub-TX über alle EXT_USER_DATA-Provider mit Strategy aus `retention.policyFor`. user-Hook anonymisiert (PII raus, Sentinel-Email).                                                                                                                                                                                        |
+| **Art. 18 (Restriction)**                  | `user-data-rights:write:restrict-account`                                            | Admin / SystemAdmin      | Status-Flip → Auth-Middleware-Guard blockt Logins. `sessions.revokeAllForUser` killt aktive Sessions.                                                                                                                                                                                                                                                                                                   |
+| **Art. 18**                                | `user-data-rights:write:lift-restriction`                                            | Admin / SystemAdmin      | Restriction aufheben.                                                                                                                                                                                                                                                                                                                                                                                   |
+| **Operator (DPO)**                         | `user-data-rights:query:list-download-attempts`                                      | Admin / SystemAdmin      | Brute-Force-Detection: zeigt invalid Download-Versuche (notFound / expired / failed / signedUrlNotSupported) gefiltert nach Result, IP, Zeitraum.                                                                                                                                                                                                                                                       |
 
 ---
 
 ## 2. Speicherorte (Verarbeitungsverzeichnis Art. 30)
 
-| Tabelle | Inhalt | Personenbezug | Retention | Zweck |
-|---------|--------|---------------|-----------|-------|
-| `read_users` | User-Profil (email, displayName, passwordHash, locale, status, gracePeriodEnd, roles) | direkt | per Domain (typ. blockDelete bei Aufbewahrungspflicht, sonst hardDelete via Forget-Pipeline) | Authentifizierung, Nutzer-Profil |
-| `read_tenant_memberships` | User↔Tenant-Verknüpfung + Rollen | direkt (via userId) | per Tenant-Lifecycle | Mehrmandant-Zuordnung |
-| `kumiko_events` | Event-Store (alle write-Events) | direkt (`createdBy = userId`) | per Domain-Policy via `data-retention` | Audit-Trail (Art. 15-Selbstauskunft Quelle), Event-Sourcing |
-| `read_export_jobs` | Async Export-Status (queued/running/done/failed), userId, requestedAt, doneAt, storageKey | direkt (userId) | per `compliance-profiles` Profil-Default | Idempotenz + Status-Polling |
-| `read_export_download_tokens` | Magic-Link-Hash (SHA-256), TTL, useCount, lastUsedAt, lastUsedFromIp, lastUsedUserAgent | indirekt (Token→Job→User) | `compliance-profiles.userRights.exportDownloadTtl` (default 7d) | Magic-Link-Auth + Multi-Use-Audit |
-| `read_download_attempts` | Invalid Download-Versuche: result, via, tokenHash, ip, userAgent, attemptedAt | indirekt (IP) | **90d hardDelete** (Entity-Default, Disk-Bomb-Schutz) | DPO-Brute-Force-Detection |
-| `read_tenant_compliance_profiles` | Per-Tenant Profile-Wahl + Override | nein | unbounded (Konfiguration) | Region-/Branchen-Defaults |
-| `read_tenant_retention_overrides` | Per-Tenant Retention-Override pro Entity | nein | unbounded (Konfiguration) | Aufbewahrungspflicht-Edge-Cases |
-| Storage-Provider (Local / S3) | Export-ZIPs + File-Binaries | indirekt (Inhalt) | Local: per `exportDownloadTtl` Cleanup. S3: lifecycle-Policy (App-Author-Verantwortung) | Daten-Export-Auslieferung |
+| Tabelle                           | Inhalt                                                                                    | Personenbezug                 | Retention                                                                                    | Zweck                                                       |
+| --------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `read_users`                      | User-Profil (email, displayName, passwordHash, locale, status, gracePeriodEnd, roles)     | direkt                        | per Domain (typ. blockDelete bei Aufbewahrungspflicht, sonst hardDelete via Forget-Pipeline) | Authentifizierung, Nutzer-Profil                            |
+| `read_tenant_memberships`         | User↔Tenant-Verknüpfung + Rollen                                                          | direkt (via userId)           | per Tenant-Lifecycle                                                                         | Mehrmandant-Zuordnung                                       |
+| `kumiko_events`                   | Event-Store (alle write-Events)                                                           | direkt (`createdBy = userId`) | per Domain-Policy via `data-retention`                                                       | Audit-Trail (Art. 15-Selbstauskunft Quelle), Event-Sourcing |
+| `read_export_jobs`                | Async Export-Status (queued/running/done/failed), userId, requestedAt, doneAt, storageKey | direkt (userId)               | per `compliance-profiles` Profil-Default                                                     | Idempotenz + Status-Polling                                 |
+| `read_export_download_tokens`     | Magic-Link-Hash (SHA-256), TTL, useCount, lastUsedAt, lastUsedFromIp, lastUsedUserAgent   | indirekt (Token→Job→User)     | `compliance-profiles.userRights.exportDownloadTtl` (default 7d)                              | Magic-Link-Auth + Multi-Use-Audit                           |
+| `read_download_attempts`          | Invalid Download-Versuche: result, via, tokenHash, ip, userAgent, attemptedAt             | indirekt (IP)                 | **90d hardDelete** (Entity-Default, Disk-Bomb-Schutz)                                        | DPO-Brute-Force-Detection                                   |
+| `read_tenant_compliance_profiles` | Per-Tenant Profile-Wahl + Override                                                        | nein                          | unbounded (Konfiguration)                                                                    | Region-/Branchen-Defaults                                   |
+| `read_tenant_retention_overrides` | Per-Tenant Retention-Override pro Entity                                                  | nein                          | unbounded (Konfiguration)                                                                    | Aufbewahrungspflicht-Edge-Cases                             |
+| Storage-Provider (Local / S3)     | Export-ZIPs + File-Binaries                                                               | indirekt (Inhalt)             | Local: per `exportDownloadTtl` Cleanup. S3: lifecycle-Policy (App-Author-Verantwortung)      | Daten-Export-Auslieferung                                   |
 
 ### Bekanntes Residuum: `createdBy` / `metadata.userId` in `kumiko_events`
 
@@ -69,12 +69,12 @@ Retention-Policy irgendwann das Event selbst löscht.
 
 ## 3. Compliance-Profile
 
-| Profil | gracePeriod | exportDownloadTtl | Stale-After | Sub-Processors |
-|--------|-------------|-------------------|-------------|----------------|
-| `eu-dsgvo` | 30d | 7d | 30d | per Tenant konfigurierbar |
-| `swiss-dsg` | 30d | 7d | 30d | + EDÖB-Meldepfad |
-| `de-hr-dsgvo-hgb` | 30d | 7d | 30d | + HR-Aufbewahrung 10y für HR-Entities (anonymize statt delete) |
-| `minimal-no-region` | 30d | 7d | 30d | Migration-Edge-Case ohne Region |
+| Profil              | gracePeriod | exportDownloadTtl | Stale-After | Sub-Processors                                                 |
+| ------------------- | ----------- | ----------------- | ----------- | -------------------------------------------------------------- |
+| `eu-dsgvo`          | 30d         | 7d                | 30d         | per Tenant konfigurierbar                                      |
+| `swiss-dsg`         | 30d         | 7d                | 30d         | + EDÖB-Meldepfad                                               |
+| `de-hr-dsgvo-hgb`   | 30d         | 7d                | 30d         | + HR-Aufbewahrung 10y für HR-Entities (anonymize statt delete) |
+| `minimal-no-region` | 30d         | 7d                | 30d         | Migration-Edge-Case ohne Region                                |
 
 Tenant kann via `compliance-profiles:write:set-profile` + Override (`override.userRights.gracePeriod={ days: N }` etc.) eigene Werte setzen.
 
@@ -128,13 +128,13 @@ und Organisatorische Maßnahmen" übernommen werden:
 
 ## 5. Cron-Jobs / Operationale Trigger
 
-| Job | Trigger | Was passiert | Operator-Sichtbarkeit |
-|-----|---------|--------------|------------------------|
-| `run-forget-cleanup` | Cron (per App-Author konfigurierbar, typisch täglich) | Findet User mit abgelaufener Grace, ruft `EXT_USER_DATA.delete` pro Provider, anonymisiert User, sendet `sendDeletionExecutedEmail`-Callback | `read_job_runs` (success/fail), Hook-Errors als `errors[]` im Result |
-| `run-export-jobs` | Cron + Event-getriggert | Findet pending Export-Jobs, ruft `runUserExport` → ZIP-Bau → Storage-Upload → Magic-Link-Token → `sendExportReadyEmail` | `read_job_runs`, `read_export_jobs.status` |
-| `data-retention-cleanup` | Cron (in `data-retention`) | Cleant abgelaufene Rows pro Entity per `retention.keepFor` | `read_job_runs` |
-| Token-Cleanup (implizit) | Per `compliance-profiles.userRights.exportDownloadTtl` | Worker-Job entfernt expired Magic-Link-Tokens + Storage-Binaries | `read_export_download_tokens` |
-| Download-Attempt-Cleanup | Per Entity-Default 90d | Cleant `read_download_attempts` | — |
+| Job                      | Trigger                                                | Was passiert                                                                                                                                 | Operator-Sichtbarkeit                                                |
+| ------------------------ | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `run-forget-cleanup`     | Cron (per App-Author konfigurierbar, typisch täglich)  | Findet User mit abgelaufener Grace, ruft `EXT_USER_DATA.delete` pro Provider, anonymisiert User, sendet `sendDeletionExecutedEmail`-Callback | `read_job_runs` (success/fail), Hook-Errors als `errors[]` im Result |
+| `run-export-jobs`        | Cron + Event-getriggert                                | Findet pending Export-Jobs, ruft `runUserExport` → ZIP-Bau → Storage-Upload → Magic-Link-Token → `sendExportReadyEmail`                      | `read_job_runs`, `read_export_jobs.status`                           |
+| `data-retention-cleanup` | Cron (in `data-retention`)                             | Cleant abgelaufene Rows pro Entity per `retention.keepFor`                                                                                   | `read_job_runs`                                                      |
+| Token-Cleanup (implizit) | Per `compliance-profiles.userRights.exportDownloadTtl` | Worker-Job entfernt expired Magic-Link-Tokens + Storage-Binaries                                                                             | `read_export_download_tokens`                                        |
+| Download-Attempt-Cleanup | Per Entity-Default 90d                                 | Cleant `read_download_attempts`                                                                                                              | —                                                                    |
 
 App-Author registriert die Cron-Trigger im run-config; `jobs`-Feature
 persistiert Run-Tracking + Retry-Pfad.

package/packages/bundled-features/src/user-data-rights/README.md

@@ -18,16 +18,16 @@ defineFeature("tasks", (r) => {
   r.useExtension(EXT_USER_DATA, "task", {
     export: async (ctx) => ({
       entity: "task",
-      rows: await ctx.db.select().from(tasksTable)
-        .where(eq(tasksTable.authorId, ctx.userId)),
+      rows: await ctx.db.select().from(tasksTable).where(eq(tasksTable.authorId, ctx.userId)),
     }),
     delete: async (ctx, strategy) => {
       if (strategy === "anonymize") {
-        await ctx.db.update(tasksTable).set({ authorId: null })
+        await ctx.db
+          .update(tasksTable)
+          .set({ authorId: null })
           .where(eq(tasksTable.authorId, ctx.userId));
       } else {
-        await ctx.db.delete(tasksTable)
-          .where(eq(tasksTable.authorId, ctx.userId));
+        await ctx.db.delete(tasksTable).where(eq(tasksTable.authorId, ctx.userId));
       }
     },
   });
@@ -42,15 +42,15 @@ Hook-Signaturen in `framework/src/engine/extensions/user-data.ts`:
 
 ## Endpoints
 
-| Article | Handler | Zweck |
-|---------|---------|-------|
-| Art. 15 | `user-data-rights:query:my-audit-log` | User sieht eigene Framework-Events (account-weit über alle Memberships). Domain-Entities ohne `ctx.events.append` erscheinen NICHT — nur im Export-Bundle. |
-| Art. 15+20 | `user-data-rights:write:request-export` | Async Job → ZIP mit user-Profil + fileRefs + alle EXT_USER_DATA-Provider-Daten + signed Magic-Link |
-| Art. 17 | `user-data-rights:write:request-deletion` | Soft-Delete mit Grace-Period, anschließend Cron anonymisiert User + cleant Domain-Entities |
-| Art. 17 | `user-data-rights:write:cancel-deletion` | User widerruft seinen Forget-Request während der Grace |
-| Art. 18 | `user-data-rights:write:restrict-account` | Auth-Middleware blockt Logins bis Lift |
-| Art. 18 | `user-data-rights:write:lift-restriction` | Admin/SystemAdmin hebt Restriction auf |
-| Operator | `user-data-rights:query:list-download-attempts` | DPO-Sicht auf invalid Download-Versuche (Brute-Force-Detection, Admin/SystemAdmin only) |
+| Article    | Handler                                         | Zweck                                                                                                                                                      |
+| ---------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Art. 15    | `user-data-rights:query:my-audit-log`           | User sieht eigene Framework-Events (account-weit über alle Memberships). Domain-Entities ohne `ctx.events.append` erscheinen NICHT — nur im Export-Bundle. |
+| Art. 15+20 | `user-data-rights:write:request-export`         | Async Job → ZIP mit user-Profil + fileRefs + alle EXT_USER_DATA-Provider-Daten + signed Magic-Link                                                         |
+| Art. 17    | `user-data-rights:write:request-deletion`       | Soft-Delete mit Grace-Period, anschließend Cron anonymisiert User + cleant Domain-Entities                                                                 |
+| Art. 17    | `user-data-rights:write:cancel-deletion`        | User widerruft seinen Forget-Request während der Grace                                                                                                     |
+| Art. 18    | `user-data-rights:write:restrict-account`       | Auth-Middleware blockt Logins bis Lift                                                                                                                     |
+| Art. 18    | `user-data-rights:write:lift-restriction`       | Admin/SystemAdmin hebt Restriction auf                                                                                                                     |
+| Operator   | `user-data-rights:query:list-download-attempts` | DPO-Sicht auf invalid Download-Versuche (Brute-Force-Detection, Admin/SystemAdmin only)                                                                    |
 
 Plus 2 anonyme HTTP-Routes für Export-Download (Magic-Link-Pfad +
 session-auth-Pfad), siehe `handlers/download-by-{token,job}.query.ts`.
@@ -77,30 +77,30 @@ weglassen wenn er Custom-Hooks registrieren will.
 
 ## Audit-Trail
 
-| Tabelle | Zweck | Retention |
-|---------|-------|-----------|
-| `kumiko_events` | Framework-Event-Store, Quelle für `my-audit-log` | per Domain-Policy |
-| `read_export_jobs` | Async Export-Status (queued / done / failed) | per `compliance-profiles` |
-| `read_export_download_tokens` | Magic-Link-Hash + TTL + lastUsed-Audit | per `compliance-profiles` (default `exportDownloadTtl`) |
-| `read_download_attempts` | Invalid-Download-Versuche für DPO-Brute-Force-Detection | **90d hardDelete** (Entity-Default — schützt vor Disk-Bomb bei aktiven Angriffen) |
+| Tabelle                       | Zweck                                                   | Retention                                                                         |
+| ----------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `kumiko_events`               | Framework-Event-Store, Quelle für `my-audit-log`        | per Domain-Policy                                                                 |
+| `read_export_jobs`            | Async Export-Status (queued / done / failed)            | per `compliance-profiles`                                                         |
+| `read_export_download_tokens` | Magic-Link-Hash + TTL + lastUsed-Audit                  | per `compliance-profiles` (default `exportDownloadTtl`)                           |
+| `read_download_attempts`      | Invalid-Download-Versuche für DPO-Brute-Force-Detection | **90d hardDelete** (Entity-Default — schützt vor Disk-Bomb bei aktiven Angriffen) |
 
 ## Tests
 
 18 Testdateien, 188 Tests, alle grün:
 
-| Datei | Pinst |
-|-------|-------|
-| `audit-log.integration.test.ts` | Cross-User-Isolation, Account-weite Sicht, eventType-Filter, Admin-only operator-query, download-attempt 90d-retention |
-| `cross-data-matrix.integration.test.ts` | 3-Provider-Pipeline (user + fileRef + custom-domain), Cross-Tenant Forget mit user-anonymize, Other-User-Isolation |
-| `download.integration.test.ts` | HTTP-e2e via `r.httpRoute`: Magic-Link, multi-use, expired, failed-job, storage-cleared, cross-tenant-same-user, malicious-filename |
-| `request-export.integration.test.ts` | Idempotency, active-job-constraint, cross-tenant-anyMember-userId-pattern |
-| `request-deletion-callback.integration.test.ts` + `request-cancel-deletion.integration.test.ts` | Grace + Cancel-Pfad + Email-Callback best-effort |
-| `restriction-flow.integration.test.ts` | Status-Flip + Auth-Middleware-Block + Lift |
-| `run-{export-jobs,forget-cleanup,user-export}.integration.test.ts` | Worker-Logic + Idempotency + Email-Callbacks |
-| `policy-to-strategy.test.ts` | Retention.strategy → UserDataDeleteStrategy mapping |
-| `user-data-rights.integration.test.ts` | Boot-Smoke + Feature-Meta |
-| `token-helpers.test.ts` + `zip-path.test.ts` | Token-Hashing + Path-Traversal-Schutz |
-| `export-job-{idempotency,schema}.test.ts` | Active-job-uniqueness + Schema-Constraints |
+| Datei                                                                                           | Pinst                                                                                                                               |
+| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `audit-log.integration.test.ts`                                                                 | Cross-User-Isolation, Account-weite Sicht, eventType-Filter, Admin-only operator-query, download-attempt 90d-retention              |
+| `cross-data-matrix.integration.test.ts`                                                         | 3-Provider-Pipeline (user + fileRef + custom-domain), Cross-Tenant Forget mit user-anonymize, Other-User-Isolation                  |
+| `download.integration.test.ts`                                                                  | HTTP-e2e via `r.httpRoute`: Magic-Link, multi-use, expired, failed-job, storage-cleared, cross-tenant-same-user, malicious-filename |
+| `request-export.integration.test.ts`                                                            | Idempotency, active-job-constraint, cross-tenant-anyMember-userId-pattern                                                           |
+| `request-deletion-callback.integration.test.ts` + `request-cancel-deletion.integration.test.ts` | Grace + Cancel-Pfad + Email-Callback best-effort                                                                                    |
+| `restriction-flow.integration.test.ts`                                                          | Status-Flip + Auth-Middleware-Block + Lift                                                                                          |
+| `run-{export-jobs,forget-cleanup,user-export}.integration.test.ts`                              | Worker-Logic + Idempotency + Email-Callbacks                                                                                        |
+| `policy-to-strategy.test.ts`                                                                    | Retention.strategy → UserDataDeleteStrategy mapping                                                                                 |
+| `user-data-rights.integration.test.ts`                                                          | Boot-Smoke + Feature-Meta                                                                                                           |
+| `token-helpers.test.ts` + `zip-path.test.ts`                                                    | Token-Hashing + Path-Traversal-Schutz                                                                                               |
+| `export-job-{idempotency,schema}.test.ts`                                                       | Active-job-uniqueness + Schema-Constraints                                                                                          |
 
 ## Sample
 

package/packages/bundled-features/src/user-data-rights/build-hook-db.ts

@@ -0,0 +1,40 @@
+import { createTenantDb, type DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import {
+  type EscapeHatchAuditSink,
+  EXT_USER_DATA,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger, type Logger } from "@cosmicdrift/kumiko-framework/logging";
+import {
+  createEscapeHatchReporter,
+  UNATTRIBUTED_ACTOR,
+} from "@cosmicdrift/kumiko-framework/pipeline";
+
+export function buildHookDb(
+  db: DbRunner,
+  tenantId: TenantId,
+  entry: { readonly entityName: string; readonly escapeHatchReason: string | undefined },
+  args: {
+    readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
+    readonly escapeHatchAuditLog?: Logger;
+    readonly actor?: string;
+  },
+) {
+  const report = createEscapeHatchReporter({
+    handler: `${EXT_USER_DATA}:${entry.entityName}`,
+    tenantId,
+    actor: args.actor ?? UNATTRIBUTED_ACTOR,
+    sink: args.escapeHatchAuditSink,
+    log: args.escapeHatchAuditLog ?? createFallbackLogger("user-data-rights"),
+  });
+  return createTenantDb({
+    db,
+    tenantId,
+    mode: "tenant",
+    grants: {
+      unsafeRaw:
+        entry.escapeHatchReason !== undefined ? { reason: entry.escapeHatchReason } : undefined,
+      report,
+    },
+  });
+}

package/packages/bundled-features/src/user-data-rights/handlers/request-export.write.ts

@@ -23,9 +23,9 @@
 
 import { createEventStoreExecutor, fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler, type SaveContext } from "@cosmicdrift/kumiko-framework/engine";
-import type { WriteFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import * as z from "zod";
+import { isUniqueConstraintFailure } from "../../shared/index.ts";
 import {
   ACTIVE_JOB_CONSTRAINT,
   EXPORT_JOB_STATUS,
@@ -40,23 +40,6 @@ const crud = createEventStoreExecutor(exportJobsTable, exportJobEntity, {
 const REQUEST_EXPORT_REASON =
   "export jobs are keyed by userId across all of the user's tenant memberships, not the caller's current tenant";
 
-/**
- * `createEventStoreExecutor.create` catches 23505 internally and returns
- * `WriteFailure(UniqueViolationError)` rather than throwing. Check the
- * failure code and constraintName to distinguish the app-side and race
- * paths; propagate other failures (validation, version conflicts, ...)
- * unchanged.
- */
-function isActiveJobConflict(failure: WriteFailure): boolean {
-  const error = failure.error as {
-    code?: string;
-    details?: { constraintName?: string };
-  }; // @cast-boundary error-details
-  return (
-    error.code === "unique_violation" && error.details?.constraintName === ACTIVE_JOB_CONSTRAINT
-  );
-}
-
 export const requestExportWrite = defineWriteHandler({
   name: "request-export",
   schema: z.object({}),
@@ -115,7 +98,7 @@ export const requestExportWrite = defineWriteHandler({
       // crud.create, causing UniqueViolationError for our constraint. Re-fetch
       // and return the existing job with isExisting=true. Propagate other
       // failures (validation, version conflicts, ...) unchanged.
-      if (isActiveJobConflict(result)) {
+      if (isUniqueConstraintFailure(result, ACTIVE_JOB_CONSTRAINT)) {
         const winner = await findActiveJob(exportJobRunner, userId);
         if (!winner) {
           // This should be impossible: a constraint violation without an existing

package/packages/bundled-features/src/user-data-rights/mail-notifications.ts

@@ -1,19 +1,13 @@
 import {
   type FeatureRegistrar,
-  type NotificationLocalizedTemplate,
   QnTypes,
   qn,
   type TemplateVariables,
   templateVariable,
 } from "@cosmicdrift/kumiko-framework/engine";
-import {
-  hasMailTranslationKey,
-  listMailLocales,
-  mailT,
-  resolveMailLocale,
-} from "@cosmicdrift/kumiko-framework/i18n";
+import { mailT } from "@cosmicdrift/kumiko-framework/i18n";
 import { escapeHtml } from "@cosmicdrift/kumiko-renderer/headless";
-import { mailParagraph } from "../shared/index.ts";
+import { createMailLocaleTemplates, mailParagraph } from "../shared/index.ts";
 import { USER_DATA_RIGHTS_FEATURE } from "./web/constants.ts";
 
 const ALL_GDPR_MAIL_KINDS = [
@@ -49,18 +43,14 @@ function subjectKey(kind: GdprMailKind): string {
   return `gdpr.mail.${GDPR_MAIL_KINDS[kind].translationKey}.subject`;
 }
 
-const SUBJECT_KEY_BY_TYPE: ReadonlyMap<string, string> = new Map(
-  ALL_GDPR_MAIL_KINDS.map((kind) => [GdprMailNotificationTypes[kind], subjectKey(kind)]),
-);
-
-// A registered locale whose bundle lacks the subject key has no template (see
-// gdprMailLocalizedTemplate); the renderer has no locale fallback, so the
-// sender must pick a locale that has one or the mail would not go out at all.
-export function gdprMailTemplateLocale(notificationType: string, requestedLocale: string): string {
-  const locale = resolveMailLocale(requestedLocale);
-  const key = SUBJECT_KEY_BY_TYPE.get(notificationType);
-  return key !== undefined && hasMailTranslationKey(locale, key) ? locale : "en";
-}
+const mailLocaleTemplates = createMailLocaleTemplates({
+  kinds: ALL_GDPR_MAIL_KINDS,
+  notificationTypes: GdprMailNotificationTypes,
+  subjectKey,
+  bodyFor: (kind, locale) => mailBody(kind, locale),
+});
+
+export const gdprMailTemplateLocale = mailLocaleTemplates.templateLocale;
 
 const appName = () => templateVariable.text({ required: true });
 
@@ -119,33 +109,7 @@ function mailBody(kind: GdprMailKind, locale: string): string {
   }
 }
 
-// Evaluated when the registry is built, after every locale feature has
-// registered its mail translations. English always ships; another locale only
-// gets a template when it has its own subject, so a missing translation never
-// silently becomes an English mail in that locale's slot.
-export function gdprMailLocalizedTemplate(kind: GdprMailKind): () => NotificationLocalizedTemplate {
-  const kindSubjectKey = subjectKey(kind);
-  return () => {
-    const locales = [
-      "en",
-      ...listMailLocales().filter(
-        (locale) => locale !== "en" && hasMailTranslationKey(locale, kindSubjectKey),
-      ),
-    ];
-    return Object.fromEntries(
-      locales.map((locale) => [
-        locale,
-        {
-          body: mailBody(kind, locale),
-          meta: {
-            subject: mailT(locale, kindSubjectKey, { app: "{{appName}}" }),
-            category: "transactional" as const,
-          },
-        },
-      ]),
-    );
-  };
-}
+export const gdprMailLocalizedTemplate = mailLocaleTemplates.localizedTemplate;
 
 export function registerGdprMails(r: FeatureRegistrar): void {
   for (const kind of ALL_GDPR_MAIL_KINDS) {

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

@@ -1,4 +1,4 @@
-import { createFallbackLogger, type Logger } from "@cosmicdrift/kumiko-framework/logging";
+import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
 // Forget-cleanup runner — pure-function pipeline.
 //
 // After the grace period, this runner processes users in DeletionRequested
@@ -34,7 +34,6 @@ import {
   subjectIdToKey,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import {
-  createTenantDb,
   type DbRunner,
   entityEventName,
   executeRawQuery,
@@ -57,10 +56,6 @@ import {
   type UserDataStorageProvider,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { runInSystemRowLevelSecurityScope } from "@cosmicdrift/kumiko-framework/internal/row-level-security";
-import {
-  createEscapeHatchReporter,
-  UNATTRIBUTED_ACTOR,
-} from "@cosmicdrift/kumiko-framework/pipeline";
 import {
   purgeSearchDocumentsForSubject,
   type SearchAdapter,
@@ -78,6 +73,7 @@ import {
 } from "../shared/index.ts";
 import { tenantMembershipsTable } from "../tenant/index.ts";
 import { USER_STATUS, userTable } from "../user/index.ts";
+import { buildHookDb } from "./build-hook-db.ts";
 import { selectUsersDueForForgetCleanup } from "./db/queries/forget-cleanup.ts";
 import { updateUserLifecycle } from "./lib/update-user-lifecycle.ts";
 
@@ -205,35 +201,6 @@ interface HookEntry {
   readonly escapeHatchReason: string | undefined;
 }
 
-function buildHookDb(
-  db: DbRunner,
-  tenantId: TenantId,
-  entry: HookEntry,
-  args: {
-    readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
-    readonly escapeHatchAuditLog?: Logger;
-    readonly actor?: string;
-  },
-) {
-  const report = createEscapeHatchReporter({
-    handler: `${EXT_USER_DATA}:${entry.entityName}`,
-    tenantId,
-    actor: args.actor ?? UNATTRIBUTED_ACTOR,
-    sink: args.escapeHatchAuditSink,
-    log: args.escapeHatchAuditLog ?? createFallbackLogger("user-data-rights"),
-  });
-  return createTenantDb({
-    db,
-    tenantId,
-    mode: "tenant",
-    grants: {
-      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.