@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

package/packages/bundled-features/src/user-data-rights/web/public-deletion-gate.tsx

@@ -1,25 +1,26 @@
-// Public-Gate für die anonyme Account-Löschung. Matcht window.location.pathname:
+// Public gate for anonymous account deletion. Matches window.location.pathname:
 // requestPath → RequestAccountDeletionScreen, confirmPath →
-// ConfirmAccountDeletionScreen, sonst durch zur App. Spiegelt makeAuthGate
-// (auth-email-password) — userDataRightsClient hängt es als Gate ein, die App
-// listet den Client VOR dem Auth-Client, damit ein anonymer Besucher die Lösch-
-// Maske statt der Login-Maske sieht. Path-Match beim Render: Apex-Übergänge
-// (der Verify-Link) sind Full-Page-Loads, kein Client-Router.
+// ConfirmAccountDeletionScreen, otherwise passes through to the app. Mirrors
+// makeAuthGate (auth-email-password) — userDataRightsClient adds it as a gate,
+// and the app lists this client BEFORE the auth client so an anonymous visitor
+// sees the deletion screen instead of the login screen. Matching during render:
+// Apex transitions (the verification link) are full-page loads, not client-router
+// transitions.
 //
-// confirmPath MUSS dem Pfad der server-seitigen deletionVerifyUrl entsprechen —
-// der ConfirmScreen liest das ?token aus eben dieser URL.
+// confirmPath MUST match the path of the server-side deletionVerifyUrl —
+// ConfirmScreen reads the ?token from that URL.
 
 import type { ComponentType, ReactNode } from "react";
 import { ConfirmAccountDeletionScreen } from "./confirm-deletion-screen.tsx";
 import { RequestAccountDeletionScreen } from "./request-deletion-screen.tsx";
 
 export type PublicDeletionRoutes = {
-  /** Login-freie Route für die Email-Antrags-Maske (z.B. "/account/delete"). */
+  /** Login-free route for the email request screen (e.g. "/account/delete"). */
   readonly requestPath: string;
-  /** Login-freie Route für die Token-Bestätigung; = Pfad der deletionVerifyUrl. */
+  /** Login-free route for token confirmation; path of deletionVerifyUrl. */
   readonly confirmPath: string;
-  /** Chrome um die Screen-Card. Default: vollflächig zentriert (wie der Auth-
-   *  defaultShell). Apps reichen ihre eigene Shell (z.B. Marketing-Header). */
+  /** Shell around the screen card. Default: full-screen centered (like the auth-
+   *  defaultShell). Apps can provide their own shell (e.g. a marketing header). */
   readonly shell?: (screen: ReactNode) => ReactNode;
 };
 

package/packages/bundled-features/src/user-data-rights/web/request-deletion-screen.tsx

@@ -1,10 +1,10 @@
-// RequestAccountDeletionScreen — anonymer Apex-Screen Schritt 1. Email-Form
-// → user-data-rights:write:request-deletion-by-email. Enumeration-safe: zeigt
-// unconditional ein "Falls Account existiert, Mail unterwegs"-Confirm, auch
-// wenn der Server intern erkannt hat dass die Email nicht existiert.
+// RequestAccountDeletionScreen — anonymous Apex screen, step 1: email form
+// → user-data-rights:write:request-deletion-by-email. Enumeration-safe: always
+// shows a "If an account exists, the email is on its way" confirmation, even
+// when the server has determined internally that the email does not exist.
 //
-// App mountet den Screen unter einer Apex-Route (z.B. /delete-account) via
-// createPublicSurface; die Page-Shell liefert die Chrome.
+// The app mounts this screen at an Apex route (e.g. /delete-account) via
+// createPublicSurface; the page shell provides the surrounding chrome.
 
 import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type FormEvent, type ReactNode, useState } from "react";

package/packages/bundled-features/src/user-data-rights/zip-path.ts

@@ -1,52 +1,52 @@
-// Shared helper fuer ZIP-Path-Berechnung von fileRefs (S2.U3 Atom 3c).
+// Shared helper for computing ZIP paths from fileRefs.
 //
-// Das Bundle hat zwei Sichten auf die selben fileRefs:
-//   1. bundle.json: Eine flat-Liste mit `zipPath` pro fileRef. Reader-
-//      Tools koennen so JSON ↔ files/-Pfade verlinken.
-//   2. ZIP-Entries: Bytes liegen unter genau diesen `zipPath`-Schluesseln.
+// The bundle has two views of the same fileRefs:
+//   1. bundle.json: A flat list with `zipPath` for each fileRef. Reader
+//      tools can use this to link JSON to files/-paths.
+//   2. ZIP entries: Bytes are stored under exactly these `zipPath` keys.
 //
-// Damit beide Sichten NICHT auseinander driften, lebt die Pfad-Berechnung
-// EXAKT EINMAL hier. run-user-export befuellt zipPath im fileRef-Item,
-// run-export-jobs's bundleToZipEntries nutzt dieselben Pfade als Entry-
-// Keys.
+// To keep both views synchronized, path computation lives EXACTLY ONCE here.
+// run-user-export fills zipPath in the fileRef item, and
+// run-export-jobs's bundleToZipEntries uses the same paths as entry keys.
 
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 
 /**
- * Maximale Laenge des sanitized fileName (ohne Extension). Realistic
- * Filenames sind <50, 100 ist eine sichere Grenze fuer ZIP-Kompatibilitaet
- * (PKWARE-spec keine harte limit, aber viele Reader haengen bei extrem
- * langen Namen).
+ * Maximum length of the sanitized fileName without its extension. Realistic
+ * filenames are <50; 100 is a safe limit for ZIP compatibility
+ * (the PKWARE spec has no hard limit, but many readers struggle with
+ * extremely long names).
  */
 const MAX_SANITIZED_BASENAME_LENGTH = 100;
 
 /**
- * Erlaubte Filename-Chars: alphanumerisch, dot, dash, underscore. Alles
- * andere wird zu underscore replaced. Path-Separator (`/`, `\`),
- * relative-traversal (`..`), und null-bytes sind insbesondere ausgeschlossen.
+ * Allowed filename chars: alphanumerics, dot, dash, underscore. Everything
+ * else is replaced with an underscore. This excludes path separators (`/`,
+ * `\`) and null bytes in particular; relative traversal (`..`) is handled
+ * by the basename and leading-dot rules below.
  */
 const FILENAME_SAFE_CHARS = /[^a-zA-Z0-9._-]/g;
 
 /**
- * Sanitize einen vom User-Input stammenden fileName fuer Verwendung als
- * ZIP-internal-path-Suffix. Defense gegen:
- *   - Path-Traversal:  "../../etc/passwd" → "file.etc_passwd"
- *   - Null-Bytes:      "report\x00.pdf"   → "report_.pdf"
- *   - Path-Separator:  "sub/dir/file.txt" → "sub_dir_file.txt"
- *   - Reserved-Names:  "." / ".." / "..."  → "file"
+ * Sanitizes a user-provided fileName for use as a ZIP-internal-path suffix.
+ *   - Path traversal:  "../../etc/passwd" → "file.etc_passwd"
+ *   - Null bytes:      "report\x00.pdf"   → "report_.pdf"
+ *   - Path separators: "sub/dir/file.txt" → "sub_dir_file.txt"
+ *   - Reserved names:  "." / ".." / "..."  → "file"
  *   - Empty input:     "" / null / undef   → "unnamed"
- *   - Ueberlange:      lange Strings auf MAX_SANITIZED_BASENAME_LENGTH gekappt
- *                      (Extension bleibt erhalten falls vorhanden)
- *   - Unicode:         non-ASCII → underscore. Leading-strip kann auch dazu
- *                      fuehren dass alle-Unicode-Names zu "file" werden.
+ *   - Excessive length: long strings are truncated to
+ *                       MAX_SANITIZED_BASENAME_LENGTH
+ *                       (the extension is preserved when present)
+ *   - Unicode:         non-ASCII characters → underscores. Leading stripping
+ *                       can also cause all-Unicode names to become "file".
  *
- * Output ist garantiert: nicht leer, kein Path-Separator, max-len enforced,
- * keine `..`-Sequenz im finalen String.
+ * The output is guaranteed to be non-empty, contain no path separators, obey
+ * the maximum length, and contain no `..` sequence.
  */
 export function sanitizeZipFilename(raw: string): string {
   if (raw === undefined || raw === null || raw === "") return "unnamed";
 
-  // Extension extrahieren (letzte ".X" wo X kein "." enthaelt).
+  // Extract the extension (the last ".X" where X contains no ".").
   const lastDot = raw.lastIndexOf(".");
   const hasExt = lastDot > 0 && lastDot < raw.length - 1;
   const baseName = hasExt ? raw.slice(0, lastDot) : raw;
@@ -55,20 +55,21 @@ export function sanitizeZipFilename(raw: string): string {
   const safeBase = collapseUnsafe(baseName).slice(0, MAX_SANITIZED_BASENAME_LENGTH);
   const safeExt = collapseUnsafe(extension).slice(0, 20);
 
-  // Empty oder all-underscores → "file" als reproduzierbarer Fallback.
+  // Empty or all-underscore input → "file" as a reproducible fallback.
   const finalBase = safeBase.length === 0 ? "file" : safeBase;
 
   return safeExt.length > 0 ? `${finalBase}.${safeExt}` : finalBase;
 }
 
 /**
- * 3-step Sanitize:
- *   1. Replace alles ausser [a-zA-Z0-9._-] mit "_"
- *   2. Collapse `..` (oder mehr) → "_" — verhindert dass `..` nach
- *      Sanitize uebrig bleibt (z.B. wenn input nur dots+slashes ist).
- *   3. Strip leading [._-]+ — verhindert hidden-file-Patterns + leere
- *      Basenames + leading-segments die nach den ersten zwei Steps
- *      lauter underscores haetten.
+ * Three-step sanitization:
+ *   1. Replace everything except [a-zA-Z0-9._-] with "_".
+ *   2. Collapse `..` (or more) to "_"—this prevents `..` from surviving
+ *      sanitization (for example, when the input contains only dots and
+ *      slashes).
+ *   3. Strip leading [._-]+—this prevents hidden-file patterns, empty
+ *      basenames, and leading segments that would consist entirely of
+ *      underscores after the first two steps.
  */
 function collapseUnsafe(s: string): string {
   let out = s.replace(FILENAME_SAFE_CHARS, "_");
@@ -78,11 +79,11 @@ function collapseUnsafe(s: string): string {
 }
 
 /**
- * Berechnet den ZIP-internal-Pfad fuer einen fileRef. Layout:
+ * Computes the ZIP-internal path for a fileRef. Layout:
  *   files/<tenantId>/<fileRefId>-<sanitized-fileName>
  *
- * tenantId + fileRefId sind UUID-shape (sicher); fileName geht durch
- * sanitizeZipFilename. Garantiert kein path-traversal.
+ * tenantId and fileRefId have UUID shapes and are safe; fileName is passed
+ * through sanitizeZipFilename. Path traversal is guaranteed to be excluded.
  */
 export function buildFileRefZipPath(args: {
   readonly tenantId: TenantId;

package/packages/bundled-features/src/user-data-rights-defaults/feature.ts

@@ -36,23 +36,23 @@ import {
   userSessionExportHook,
 } from "./hooks/user-session.userdata-hook.ts";
 
-// user-data-rights-defaults — Default-Hooks für die Core-Entities
-// `user` (S2.H1) und `fileRef` (S2.H2).
+// user-data-rights-defaults — Default hooks for the core entities
+// `user` and `fileRef`.
 //
-// Architektur-Entscheidung (S2.H1+H2): user-data-rights selbst kann
-// nicht r.requires({ features: ["user", "files"] }) + r.useExtension(EXT_USER_DATA, ...)
-// machen weil es selbst Provider von EXT_USER_DATA ist (Boot-Validator
-// lehnt self-extension ab). Lösung: drittes optional-mountbares Feature
-// das requires beide Sources + die useExtension-Calls macht.
+// Architectural decision: user-data-rights itself cannot call
+// r.requires({ features: ["user", "files"] }) + r.useExtension(EXT_USER_DATA, ...)
+// because it provides EXT_USER_DATA itself (the boot validator rejects
+// self-extension). The solution is a third, optionally mountable feature
+// that requires both sources and makes the useExtension calls.
 //
-// App-Author kann dieses Feature weglassen wenn er Custom-Hooks
-// stattdessen registrieren will (z.B. "anonymize sollte den User-Row
-// hard-delete" — App-spezifische Compliance-Entscheidung). Default-
-// Implementierung deckt 95% der Apps ab.
+// App authors can omit this feature if they want to register custom hooks
+// instead (for example, "anonymize should hard-delete the user row" — an
+// app-specific compliance decision). The default implementation covers 95%
+// of apps.
 //
-// Pattern matched file-foundation + file-provider-s3 (separate Plugin-
-// Feature), nicht user/files schreiben ihre eigenen Hooks selbst weil
-// das circular-requires waere.
+// This follows the file-foundation + file-provider-s3 pattern (separate
+// plugin features): user/files do not define their own hooks because that
+// would create circular requires.
 // Binary storage for the fileRef delete-hook is resolved at run time from the
 // mounted file-foundation via ctx.buildStorageProvider (injected by the forget
 // orchestrator) — no provider is captured here, so a single app-wide store and
@@ -123,7 +123,7 @@ export function createUserDataRightsDefaultsFeature(): FeatureDefinition {
       delete: configValueDeleteHook,
     });
 
-    // Events-only aggregates (#799): export reads the projected rows, the
+    // Events-only aggregates: export reads the projected rows, the
     // delete hooks are deliberate no-ops — erasure happens via crypto-
     // shredding (forget erases the user's DEK; recipientAddress / job
     // payload become unreadable in events AND rows).

package/packages/bundled-features/src/user-data-rights-defaults/hooks/delivery-attempt.userdata-hook.ts

@@ -9,11 +9,9 @@ import {
 } from "../../delivery/index.ts";
 import { featureMounted } from "./feature-mounted.ts";
 
-// userData-Hooks for delivery's attempt log (deferred from #797, closed by
-// #799). deliveryAttempt is an events-only aggregate — the export reads the
-// projected rows; recipientAddress may be ciphertext (kumiko-pii:), which
-// the export runner's central decrypt sweep resolves to plaintext (or
-// [[erased]] after a forget).
+// userData-Hooks for delivery's attempt log. deliveryAttempt is an events-only aggregate — the
+// export reads the projected rows; recipientAddress may be ciphertext (kumiko-pii:), which the
+// export runner's central decrypt sweep resolves to plaintext (or [[erased]] after a forget).
 
 export const deliveryAttemptExportHook: UserDataExportHook = async (ctx) => {
   if (!featureMounted(ctx, "delivery")) return null;

package/packages/bundled-features/src/user-data-rights-defaults/hooks/file-ref.userdata-hook.ts

@@ -30,68 +30,64 @@ const ERROR_CONTEXT = "user-data-rights-defaults:fileRef";
 // per-user forget flows are rare, so per-row events are acceptable.
 const crud = createEventStoreExecutor(fileRefsTable, fileRefEntity, { entityName: "fileRef" });
 
-// userData-Hook fuer fileRef-entity (S2.H2).
+// User-data hook for the fileRef entity.
 //
-// Export-Hook liefert Metadata aller FileRefs des Users mit Subject-
-// Resolver via insertedById. Storage-Provider-binary-Streams kommen
-// NICHT direkt — sie werden via signed-Download-URLs separat ins ZIP
-// gepackt (S2.U3 Export-Job-Pipeline orchestriert das).
+// The export hook returns metadata for all of the user's FileRefs, with the
+// subject resolved through insertedById. Storage-provider binary streams are
+// not included directly; signed download URLs package them into the ZIP
+// separately.
 //
-// Delete-hook removes the fileRef row + binary:
+// The delete hook removes the fileRef row and binary:
 //   "delete":    storageProvider.delete() per file + row hard-delete — but
 //                ONLY for rows whose field is marked as PII of the person
-//                (isPersonalFileRow, #3005). All other rows (business/
-//                tenant data, no resolvable field, no annotation) go
-//                through severPersonLink instead, even when the entity
-//                strategy is "delete" — the uploader axis (insertedById) is
-//                not the subject axis.
-//   "anonymize": insertedById=null, row + binary survive (FK refs can still
-//                point at it; person-link removed) — applies to ALL rows
+//                (isPersonalFileRow). All other rows (business/tenant data,
+//                no resolvable field, no annotation) go through
+//                severPersonLink instead, even when the entity strategy is
+//                "delete" — the uploader axis (insertedById) is not the
+//                subject axis.
+//   "anonymize": insertedById=null; row and binary survive (FK refs can still
+//                point at it; person-link removed). This applies to ALL rows
 //                when a retention override on fileRef (anonymize or
 //                blockDelete, e.g. a statutory retention duty) sets the
 //                strategy, regardless of the field.
 //
-// **Provider-Resolution:** der Provider kommt zur Lauf-Zeit aus
-// `ctx.buildStorageProvider(ctx.tenantId)` — der Forget-Orchestrator
-// (run-forget-cleanup) baut ihn aus dem gemounteten file-foundation, also aus
-// DEMSELBEN Store den Upload + Export nutzen (delete-target == upload-target by
-// construction). Kein bei-Mount captured Provider mehr.
+// **Provider resolution:** the provider is obtained at runtime from
+// `ctx.buildStorageProvider(ctx.tenantId)`. The forget orchestrator builds it
+// from the mounted file-foundation, using the SAME store as upload and export
+// (delete-target == upload-target by construction). No provider is captured at
+// mount time.
 //
-// **Zwei Fehlerklassen, bewusst verschieden behandelt:**
-//   1. Resolution schlaegt fehl (kein Provider konfiguriert / configResolver
-//      fehlt) → NICHT fail-closed: Warn pro Aufruf + row-only-delete. Ein
-//      fehlkonfigurierter Store darf die Art.-17-Loeschung nicht DAUERHAFT
-//      blockieren (sonst haengt jeder User fuer immer in DeletionRequested);
-//      der Boot-Guard macht die Fehlkonfiguration sichtbar, Binaries werden
-//      nachgeholt sobald ein Provider existiert.
-//   2. Binary-DELETE schlaegt fehl, OBWOHL ein Provider da ist → FAIL-CLOSED:
-//      der Hook wirft NACH dem Loop, die per-User-Sub-Tx von runForgetCleanup
-//      rollt zurueck, der User bleibt DeletionRequested, der naechste Run
-//      retried (delete ist idempotent → konvergiert). Den Fehler zu schlucken +
-//      die Row trotzdem zu loeschen wuerde Erasure als "done" markieren waehrend
-//      die Bytes liegen bleiben — falsche Compliance-Aussage. Das "KEIN globaler
-//      Rollback" der Sprint-2-Atomicity bleibt gewahrt: nur DIESE Sub-Tx rollt
-//      zurueck. Der anonymize-Pfad behaelt Row+binary, hat nichts zu schlucken.
+// **Two error classes are handled differently:**
+//   1. Resolution fails (no provider configured / configResolver missing) →
+//      NOT fail-closed: warn per invocation and perform a row-only delete. A
+//      misconfigured store must not permanently block the Art. 17 deletion;
+//      the boot guard exposes the misconfiguration, and binaries are removed
+//      once a provider exists.
+//   2. Binary DELETE fails even though a provider exists → FAIL-CLOSED: the
+//      hook throws after the loop, the per-user sub-transaction rolls back,
+//      the user remains DeletionRequested, and the next run retries (delete is
+//      idempotent → converges). Swallowing the error and deleting the row would
+//      mark erasure as "done" while leaving the bytes behind. Only this
+//      sub-transaction rolls back; there is no global rollback. The anonymize
+//      path retains the row and binary, so it has no error to swallow.
 //
-// Caveat: hard-delete via deleteMany emittiert KEIN fileRef.deleted —
-// die storage-tracking-MSP dekrementiert nicht. Wenn die zu loeschenden
-// Files vorher nicht soft-deleted waren, bleibt `tenant_storage_usage`
-// inflated. Forget-Flows sind selten (per-User-Art.-17) und damit
-// bounded; ein executor.purge-API folgt mit dem trashed-files-GC.
+// Caveat: hard-delete via deleteMany emits no fileRef.deleted event, so
+// storage-tracking does not decrement. If the files being deleted were not
+// soft-deleted first, `tenant_storage_usage` remains inflated. Forget flows are
+// rare and bounded; an executor.purge API will follow with trashed-files GC.
 
 export const fileRefExportHook: UserDataExportHook = async (ctx) => {
-  // isDeleted:false — soft-deleted (trashed) Files gehören nicht ins
-  // Auskunfts-Bundle. Forget (delete-Hook unten) erfasst sie trotzdem.
+  // isDeleted:false — soft-deleted (trashed) files are excluded from the
+  // export bundle. The forget hook below still processes them.
   const rawRows = await ctx.db.selectMany(fileRefsTable, {
     tenantId: ctx.tenantId,
     insertedById: ctx.userId,
     isDeleted: false,
   });
 
-  // @cast-boundary db-row: drizzle liefert insertedAt als Instant
-  // (framework-customType). Fuer JSON-Export brauchen wir String —
-  // .toString() funktioniert sowohl auf Temporal.Instant als auch
-  // Date.
+  // @cast-boundary db-row: drizzle returns insertedAt as an Instant
+  // (framework-customType). JSON export requires a string —
+  // .toString() works for both Temporal.Instant and Date.
   const rows = rawRows.map((r) => {
     const row = r as Record<string, unknown>; // @cast-boundary recursive-walk
     return {
@@ -115,9 +111,8 @@ export const fileRefExportHook: UserDataExportHook = async (ctx) => {
       size: r.size,
       insertedAt: r.insertedAt,
     })),
-    // Plus die fileRefs-Liste die Sprint-2-U3 dann zum Storage-Provider
-    // bringt + signed-URLs erzeugt + ins ZIP packt (siehe S1.9-Z1
-    // UserDataExportSnippet.fileRefs).
+    // The fileRefs list is passed to the storage provider, which generates
+    // signed URLs and adds the files to the ZIP.
     fileRefs: rows.map((r) => ({
       fileRefId: r.id,
       storageKey: r.storageKey,
@@ -142,7 +137,7 @@ async function resolveProvider(ctx: UserDataHookCtx): Promise<UserDataStoragePro
   }
 }
 
-// Per-row Art.17 decision (kumiko-framework#3005): whether THIS file's field
+// Per-row Art.17 decision: whether THIS file's field
 // carries personal data of the forgotten person, or is business/tenant data
 // that merely loses its uploader-attribution. insertedById names who
 // UPLOADED the file, not whose data it is — a dealer's vehicle photo
@@ -163,8 +158,7 @@ function isPersonalPiiField(field: FieldDefinition | undefined): boolean {
   );
 }
 
-// Three cases the field-lookup itself can't resolve (issue #3005's rule for
-// the non-resolvable cases):
+// Three cases the field-lookup itself can't resolve:
 //   1. Unattached upload (entityType/fieldName both null) → hard-delete: a
 //      file with no entity binding belongs to nobody but its uploader.
 //   2. Field exists but carries no PII annotation → anonymize (the
@@ -244,7 +238,7 @@ export const fileRefDeleteHook: UserDataDeleteHook = async (ctx, strategy) => {
   }
 
   // strategy="delete" decides PER ROW based on the field, not uniformly
-  // (#3005): only rows whose field is marked as PII of the person (or
+  // only rows whose field is marked as PII of the person (or
   // unattached, see isPersonalFileRow) take the hard path. Everything else
   // only loses the uploader link.
   const personalRows: Record<string, unknown>[] = [];

package/packages/bundled-features/src/user-data-rights-defaults/hooks/job-run.userdata-hook.ts

@@ -2,7 +2,7 @@ import type { UserDataDeleteHook, UserDataExportHook } from "@cosmicdrift/kumiko
 import { jobRunsTable } from "../../jobs/index.ts";
 import { featureMounted } from "./feature-mounted.ts";
 
-// userData-Hooks for the jobs run log (deferred from #797, closed by #799).
+// userData-Hooks for the jobs run log.
 // Job runs live on the SYSTEM tenant regardless of who triggered them, so
 // the export filters by triggeredById only — Art. 15 covers everything the
 // user caused, across tenants. payload may be ciphertext (kumiko-pii:); the
@@ -29,6 +29,6 @@ export const jobRunExportHook: UserDataExportHook = async (ctx) => {
 export const jobRunDeleteHook: UserDataDeleteHook = async () => {
   // Deliberate no-op: erasure runs via crypto-shredding — the forget pipeline
   // erases the triggering user's DEK, which makes the payload unreadable in
-  // BOTH the append-only events and the projected rows (#799). triggeredById
+  // BOTH the append-only events and the projected rows. triggeredById
   // itself is a pseudonymous fk (plaintext by design, like config.userId).
 };

package/packages/bundled-features/src/user-data-rights-defaults/hooks/notification-preference.userdata-hook.ts

@@ -17,7 +17,7 @@ import { featureMounted } from "./feature-mounted.ts";
 // the forget verb.
 //
 // The delivery ATTEMPTS log is covered separately: export via
-// delivery-attempt.userdata-hook.ts, erasure via crypto-shredding (#799).
+// delivery-attempt.userdata-hook.ts, erasure via crypto-shredding.
 
 const crud = createEventStoreExecutor(notificationPreferencesTable, notificationPreferenceEntity, {
   entityName: "notification-preference",

package/packages/bundled-features/src/user-data-rights-defaults/hooks/user-session.userdata-hook.ts

@@ -5,9 +5,9 @@ import { featureMounted } from "./feature-mounted.ts";
 // userData-Hooks for the sessions feature's user-session rows (ip, userAgent).
 //
 // user-session is an unmanaged direct-write store (no event stream, excluded
-// from projection rebuilds — see sessions/feature.ts #494/#498), so a direct
-// DELETE is legal here and survives rebuilds; the executor path the ES
-// entities use does not apply.
+// from projection rebuilds, see sessions/feature.ts), so a direct DELETE is
+// legal here and survives rebuilds; the executor path the ES entities use does
+// not apply.
 //
 // Both forget strategies hard-delete: a session row without its user is
 // worthless (revocation audit trail loses its subject), and ip/userAgent are

package/packages/bundled-features/src/user-data-rights-defaults/hooks/user.userdata-hook.ts

@@ -20,25 +20,25 @@ import {
 // A direct write would be wiped on rebuild — the Art.17 hole this fixes.
 const crud = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
 
-// userData-Hook fuer user-entity (S2.H1).
+// The user-data hook for the user entity.
 //
-// Export-Hook liefert Profil-Daten ohne security-sensitive Felder
-// (passwordHash, roles, status — DSGVO Art. 20 ist Datenportabilitaet
-// fuer das was der User selbst zur Verfuegung gestellt hat, nicht
-// Lifecycle-Metadata oder Authorization-State).
+// The export hook returns profile data without security-sensitive fields
+// (passwordHash, roles, status — GDPR Art. 20 covers portability of data
+// the user provided themselves, not lifecycle metadata or authorization
+// state).
 //
-// Delete-Hook anonymisiert PII + setzt status=deleted. Der eigentliche
-// softDelete-Flag wird ueber drizzle's deletedAt-Column gesetzt; die
-// Row bleibt fuer Audit-Trail erhalten (alle FK-Refs auf user.id
-// bleiben gueltig). DSGVO-konform via PII-Anonymisierung.
+// The delete hook anonymizes PII and sets status=deleted. The actual
+// softDelete flag is set through Drizzle's deletedAt column; the row remains
+// for the audit trail (all foreign-key references to user.id remain valid).
+// This complies with GDPR through PII anonymization.
 //
 // Strategy:
-//   "delete":    softDelete + email/displayName/passwordHash leeren,
-//                status=deleted (Login geblockt)
-//   "anonymize": email/displayName auf Pseudonym, Row bleibt active
-//                — fuer Cases wo User-Row als FK noch relevant ist
-//                aber PII raus muss (z.B. anonymize mit blockDelete-
-//                Frist auf einer FK-target-Entity)
+//   "delete":    softDelete + clear email/displayName/passwordHash,
+//                status=deleted (login blocked)
+//   "anonymize": replace email/displayName with pseudonyms; the row remains
+//                active when the user row is still needed as a foreign-key
+//                target but PII must be removed (for example, anonymization
+//                with a blockDelete deadline on a foreign-key target entity)
 
 export const userExportHook: UserDataExportHook = async (ctx) => {
   const row = await ctx.db.fetchOne<{
@@ -66,11 +66,11 @@ export const userExportHook: UserDataExportHook = async (ctx) => {
 };
 
 export const userDeleteHook: UserDataDeleteHook = async (ctx, strategy) => {
-  // Idempotent: zweiter Call findet die Row schon anonymized + skipt
-  // implicit (UPDATE mit gleichen Werten). Memory feedback_event_store_
-  // tenant_consistency: ctx.tenantId muss in der user-table-Zeile
-  // korrelieren — user.id ist tenant-agnostic (User kann in mehreren
-  // Tenants Member sein), kein tenantId-Filter noetig.
+  // Idempotent: a second call finds the row already anonymized and skips
+  // implicitly (UPDATE with the same values). Event-store tenant
+  // consistency requires ctx.tenantId to correlate with the row in
+  // the user table — user.id is tenant-agnostic (a user can be a member in
+  // multiple tenants), so no tenantId filter is needed.
 
   // System actor + skipOptimisticLock: the forget pipeline has no read
   // version and writes privileged identity columns ("system" is privileged).
@@ -81,12 +81,13 @@ export const userDeleteHook: UserDataDeleteHook = async (ctx, strategy) => {
   const systemUser = createSystemUser(ctx.tenantId);
 
   if (strategy === "delete") {
-    // PII raus + status=deleted (Login geblockt) via Event → Rebuild spielt den
-    // Forget mit. KEIN softDelete: user ist systemStream (eine tenant-agnostische
-    // Row), der Forget laeuft pro Tenant — wuerde isDeleted gesetzt, faende der
-    // loadById (isDeleted:false) die Row beim zweiten Tenant nicht mehr
-    // (not_found). status=Deleted blockt Login; die Row bleibt findbar +
-    // idempotent ueber mehrere Tenant-Durchlaeufe (wie der alte raw UPDATE).
+    // Remove PII and set status=deleted via an event, so a rebuild replays
+    // the forget operation. Do NOT use softDelete: user is systemStream (a
+    // tenant-agnostic row), and forgetting runs once per tenant. Setting
+    // isDeleted would cause loadById (isDeleted:false) to miss the row for
+    // the second tenant (not_found). status=Deleted blocks login; the row
+    // remains findable and idempotent across tenant passes, as with the old
+    // raw UPDATE.
     await crud.update(
       {
         id: ctx.userId,
@@ -105,11 +106,11 @@ export const userDeleteHook: UserDataDeleteHook = async (ctx, strategy) => {
       { skipOptimisticLock: true, writePurpose: WritePurposes.erasure },
     );
   } else {
-    // anonymize: PII raus, aber Row bleibt active (damit FK-References
-    // weiter aufloesbar sind). Account ist effektiv weiter nutzbar
-    // wenn der User sich neu authentifiziert — pragmatisch akzeptabel
-    // weil "anonymize" auf user-entity ein seltener Edge-Case ist
-    // (typisch hard-delete fuer User).
+    // Anonymize PII, but keep the row active so foreign-key references
+    // remain resolvable. The account can still be used if the user
+    // authenticates again — pragmatically acceptable because "anonymize"
+    // on the user entity is a rare edge case (hard deletion is typical for
+    // users).
     await crud.update(
       {
         id: ctx.userId,

package/packages/bundled-features/src/user-profile/handlers/change-email.write.ts

@@ -10,9 +10,9 @@ import { decryptStoredPii, verifyPassword } from "../../shared/index.ts";
 import { UserErrors, UserHandlers, UserQueries } from "../../user/index.ts";
 import { UserProfileErrors } from "../web/constants.ts";
 
-// Gleiche Failure-Shape wie auth-email-password (anti-enumeration):
-// dessen errors.ts ist nicht Teil des Feature-Barrels, der Reason-Code
-// + i18nKey sind aber stabile Public-API.
+// Same failure shape as auth-email-password (anti-enumeration):
+// its errors.ts is not part of the feature barrel, but the reason code
+// and i18nKey are stable public API.
 // @wrapper-known error-helper
 function invalidCredentials() {
   return writeFailure(
@@ -22,13 +22,13 @@ function invalidCredentials() {
   );
 }
 
-// Change-email — authenticated, self-only. Der User bestätigt mit seinem
-// aktuellen Passwort (Re-Auth wie change-password); die neue Adresse wird
-// via ctx.writeAs(system) gegen den user-update-Handler geschrieben, weil
-// `email` field-level privileged ist und bei Self-Updates sonst silent
-// gestrippt würde. emailVerified flippt auf false — die App triggert
-// anschließend den Verification-Flow (request-email-verification ist
-// public; der ProfileScreen ruft ihn nach Erfolg auf).
+// Change-email — authenticated, self-only. The user confirms with their
+// current password (re-authentication as with change-password); the new
+// address is written through the user-update handler via ctx.writeAs(system)
+// because `email` is field-level privileged and would otherwise be silently
+// stripped during self-updates. emailVerified is set to false — the app then
+// triggers the verification flow (request-email-verification is public; the
+// ProfileScreen calls it after success).
 export const changeEmailWrite = defineWriteHandler({
   name: "change-email",
   schema: z.object({
@@ -88,9 +88,9 @@ export const changeEmailWrite = defineWriteHandler({
       );
     }
 
-    // user ist systemStream (#497): der Event-Stream liegt deterministisch
-    // auf SYSTEM_TENANT_ID. Pre-#497-Streams brauchen einmalig
-    // backfillUserStreamTenants (#762).
+    // user is systemStream: the event stream is deterministically located
+    // on SYSTEM_TENANT_ID. Older streams require a one-time
+    // backfillUserStreamTenants.
     const writer = createSystemUser(SYSTEM_TENANT_ID);
 
     const writeRes = await ctx.writeAs(writer, UserHandlers.update, {