@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

package/packages/bundled-features/src/user-data-rights/handlers/download-by-token.query.ts

@@ -1,30 +1,29 @@
-// GET /api/query → user-data-rights:query:download-by-token (S2.U3 Atom 4b).
+// GET /api/query → user-data-rights:query:download-by-token.
 //
-// **Magic-Link-Pfad** (anonymous): User klickt Email-Link mit
-// `#token=<plain>` (URL fragment, issue #1271). Worker hat beim done-flip Token-Hash in DB
-// persistiert (Atom 4a). Verify-Pipeline:
+// **Magic-link path** (anonymous): The user clicks an email link with
+// `#token=<plain>` (URL fragment). The worker persisted the token hash in the database
+// when marking the job done. Verification:
 //
 //   1. hashDownloadToken(plain) → fetchOne in download-tokens
-//   2. expiresAt > now (Multi-use within TTL — Plan-Decision)
+//   2. expiresAt > now (multiple uses within the TTL)
 //   3. job.status === "done"
-//   4. job.downloadStorageKey != null (storage nicht gecleared)
-//   5. provider.getSignedUrl pflicht (501 wenn Provider local-fs ist)
-//   6. Audit-Update: useCount + 1, lastUsedAt, IP, UA (best-effort, race-tolerant)
+//   4. job.downloadStorageKey != null (storage was not cleared)
+//   5. provider.getSignedUrl is required (501 when the provider is local-fs)
+//   6. Audit update: useCount + 1, lastUsedAt, IP, UA (best-effort, race-tolerant)
 //   7. Return {url, expiresAt}
 //
-// **Sicherheit:**
-//   - Token-Hash-Compare via DB-fetchOne (nicht constant-time, aber
-//     timing-attacks auf SHA256-bytes brauchen >>10k requests + stable
-//     latenz — in Web-App-Kontext nicht ausnutzbar). Plan-Decision: harden
-//     wenn Pen-Test es flaggt.
-//   - 404 bei invalidem Token (kein Existenz-Leak) — gleicher Code-Pfad
-//     wie nicht-gefundenes Token.
-//   - tenant-agnostic: Token ist global eindeutig (UUID + SHA256), kein
-//     Tenant-Filter nötig.
+// **Security:**
+//   - Token-hash comparison via DB-fetchOne is not constant-time, but timing attacks
+//     against SHA256 bytes require >>10k requests plus stable latency and are not
+//     exploitable in a web-app context.
+//   - Invalid tokens return 404 without leaking existence, using the same code path
+//     as a token that was not found.
+//   - The token is tenant-agnostic: UUID + SHA256 makes it globally unique, so no
+//     tenant filter is needed.
 //
-// **r.httpRoute-Wrapper** (siehe feature.ts) macht 302-Redirect zu
-// signedUrl — User klickt 1× Email-Link, Browser folgt redirect, Download
-// startet. Dieser query-handler liefert nur das JSON.
+// **r.httpRoute wrapper** (see feature.ts) redirects to signedUrl with a 302. The user
+// clicks the email link once, the browser follows the redirect, and the download
+// starts. This query handler returns only the JSON.
 
 import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import {
@@ -43,7 +42,7 @@ import { hashDownloadToken } from "../token-helpers.ts";
 
 type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 
-const SIGNED_URL_TTL_SECONDS = 300; // 5 min — kurz genug fuer Replay-Schutz, lang genug fuer slow connections
+const SIGNED_URL_TTL_SECONDS = 300; // 5 min — short enough to limit replay, long enough for slow connections
 
 const DOWNLOAD_BY_TOKEN_REASON =
   "the download token, its job and audit rows are keyed by token hash / job id, not the caller's tenant — the anonymous magic-link path has no tenant context at all";
@@ -82,12 +81,11 @@ export const downloadByTokenQuery = defineQueryHandler({
     personalData: "public-intake",
   },
   agent: { expose: false },
-  // Brute-Force-Schutz fuer Token-Hash-Probing. Anonymous-Endpoint mit
-  // 32-byte-Random-Token = 256 Bit Search-Space, aber rate-limit als
-  // defense-in-depth + Schutz gegen Storm-Patterns die DB-Last erzeugen.
-  // 30 attempts/min/IP reicht fuer legitime User (mehrere Klicks bei
-  // Connection-Abbruch); blockiert automatisierte Probing-Loops.
-  // Memory `feedback_security_default_on`.
+  // Brute-force protection for token-hash probing. This anonymous endpoint uses a
+  // 32-byte random token with a 256-bit search space, but rate limiting provides
+  // defense in depth and protects against storm patterns that generate database load.
+  // 30 attempts/min/IP allows legitimate users several retries after connection
+  // failures while blocking automated probing loops.
   rateLimit: { per: "ip+handler", limit: 30, windowSeconds: 60 },
   escapeHatch: {
     grants: ["unsafeRaw"],
@@ -105,9 +103,9 @@ export const downloadByTokenQuery = defineQueryHandler({
     });
 
     if (!tokenRow) {
-      // Invalid token — 404 ohne Existenz-Leak. Generic NotFoundError
-      // damit alle Failure-Pfade die gleiche externe Shape haben (kein
-      // Probing zwischen "Token existiert nicht" vs "Job ist failed").
+      // Invalid token — 404 without leaking existence. Use a generic NotFoundError
+      // so all failure paths have the same external shape, preventing probing that
+      // distinguishes "Token does not exist" from "Job has failed".
       throw new NotFoundError("export-download", undefined, {
         i18nKey: "userDataRights.errors.download.notFound",
       });
@@ -116,17 +114,17 @@ export const downloadByTokenQuery = defineQueryHandler({
     const auditIp = query.payload.auditMeta?.ip ?? null;
     const auditUa = query.payload.auditMeta?.userAgent ?? null;
 
-    // Step 2: TTL-check.
+    // Step 2: TTL check.
     //
-    // **Pragma:** semantisch waere 410 Gone richtig (war mal da, jetzt
-    // nicht mehr). Framework hat keine GoneError-Class; wir nutzen
-    // NotFoundError + i18nKey "expired" als Kompromiss. UI rendert
-    // anhand des i18nKeys, nicht des HTTP-Status — also User sieht
-    // "Dein Download ist abgelaufen", nicht generic "not found".
+    // 410 Gone would be semantically right (the download existed and is now
+    // gone), but the framework has no GoneError class. NotFoundError with
+    // i18nKey "expired" is the compromise: the UI renders by i18nKey, not by
+    // HTTP status, so the user sees "Your download has expired" instead of a
+    // generic "not found".
     if (tokenRow.expiresAt.epochMilliseconds <= now.epochMilliseconds) {
-      // Audit-Skip noch nicht moeglich — jobRow noch nicht geladen,
-      // tenantId unbekannt. Wir laden den Job hier noch fuer Audit-Context
-      // (best-effort — wenn Job auch fehlt, audit-skip ist akzeptabel).
+      // Auditing cannot be skipped yet because jobRow has not been loaded and the
+      // tenantId is unknown. Load the job to obtain audit context; if it is also
+      // missing, skipping the audit is acceptable (best-effort).
       const jobForAudit = await fetchOne<{ requestedFromTenantId: string }>(
         runner,
         exportJobsTable,
@@ -240,9 +238,9 @@ export const downloadByTokenQuery = defineQueryHandler({
       now.epochMilliseconds + SIGNED_URL_TTL_SECONDS * 1000,
     );
 
-    // Step 6: Audit-Update best-effort. auditMeta kommt vom httpRoute-
-    // Wrapper (trusted-source). Direct-API-caller koennen luegen, aber
-    // Audit ist nicht security-relevant.
+    // Step 6: Best-effort audit update. auditMeta comes from the httpRoute wrapper
+    // (trusted source). Direct API callers can falsify it, but the audit data is not
+    // security-sensitive.
     await recordDownloadUse({
       db: runner,
       tokenId: tokenRow.id,

package/packages/bundled-features/src/user-data-rights/handlers/export-status.query.ts

@@ -1,15 +1,14 @@
-// GET /api/user/export-status (S2.U3 Atom 2) — User-Polling.
+// GET /api/user/export-status — user polling.
 //
-// Liefert den meist-aktuellen ExportJob des aufrufenden Users (in
-// Reihenfolge: aktiver Job zuerst, sonst neuester done/failed).
+// Returns the calling user's most recent ExportJob (active jobs first,
+// otherwise the newest done/failed job).
 //
-// **Cross-User-Isolation:** Filter ist `userId === query.user.id` — kein
-// User kann fremde Job-Status sehen, auch nicht via ID-Guess. Pre-Check
-// uses ctx.db.unsafeRaw — ExportJob is tenant-agnostic (see plan doc,
-// "Cross-Tenant-Semantik").
+// **Cross-User-Isolation:** The filter is `userId === query.user.id`, so no
+// user can view another user's job status, even by guessing an ID. The
+// pre-check uses ctx.db.unsafeRaw because ExportJob is tenant-agnostic.
 //
-// **Read-Only-Endpoint:** Pollt nur, kein State-Flip. Idempotent + cache-
-// fest. UI poll-Intervall typisch 2-5s waehrend running.
+// **Read-Only-Endpoint:** Polling only; it does not change state. The endpoint
+// is idempotent and cacheable. The UI typically polls every 2-5s while running.
 
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";

package/packages/bundled-features/src/user-data-rights/handlers/lift-restriction.write.ts

@@ -8,7 +8,7 @@ import { updateUserLifecycle } from "../lib/update-user-lifecycle.ts";
 const LIFT_RESTRICTION_ESCAPE_HATCH_REASON =
   "checks the target user's membership in the admin's tenant and appends the user lifecycle status change on the SYSTEM_TENANT_ID user stream, both via DbRunner helpers outside the admin's own tenant scope.";
 
-// POST /api/user/lift-restriction (S2.U6) — DSGVO Art. 18 Reverse.
+// POST /api/user/lift-restriction — GDPR Art. 18 Reverse.
 //
 // Operator-only. A Restricted user's own session is unconditionally
 // rejected by sessionChecker (BLOCKED_STATUSES) the moment their status
@@ -16,16 +16,15 @@ const LIFT_RESTRICTION_ESCAPE_HATCH_REASON =
 // endpoint. There is no self-service path today, so lifting a restriction
 // always targets someone else's account by id.
 //
-// Tenant scope: `access.admin` includes TenantAdmin (tenant-scoped) even
-// though the User-entity is global — see user-data-rights.md "Cross-Tenant-Semantik". Without a membership check, a TenantAdmin
-// from tenant A could unrestrict/reactivate a user who has never been a
-// member of tenant A. Only SystemAdmin (platform-wide) skips the check;
-// the target must have a membership row in the acting admin's
-// `event.user.tenantId` (row existence only — no active-status field).
+// Tenant scope: `access.admin` includes TenantAdmin (tenant-scoped) even though the User-entity is
+// global — see user-data-rights.md "Cross-Tenant Semantics". Without a membership check, a
+// TenantAdmin from tenant A could unrestrict/reactivate a user who has never been a member of
+// tenant A. Only SystemAdmin (platform-wide) skips the check; the target must have a membership row
+// in the acting admin's `event.user.tenantId` (row existence only — no active-status field).
 //
 // State-Transitions:
 //   Restricted → Active        ✓
-//   Active → ...               ✗ 422 not_restricted (Idempotenz-Guard)
+//   Active → ...               ✗ 422 not_restricted (Idempotency Guard)
 //   DeletionRequested → ...    ✗ 422 not_restricted
 //   Deleted → ...              ✗ 422 not_restricted
 export const liftRestrictionWrite = defineWriteHandler({

package/packages/bundled-features/src/user-data-rights/handlers/list-download-attempts.query.ts

@@ -5,8 +5,8 @@ import * as z from "zod";
 import { decryptStoredPii } from "../../shared/index.ts";
 import { downloadAttemptsTable } from "../schema/download-attempt.ts";
 
-// Operator-Query: invalid Download-Attempts (S2.U7).
-// DPO-Sicht fuer Brute-Force-Detection. Tenant-isolated via WHERE.
+// Operator query for invalid download attempts. Provides tenant-isolated visibility for data
+// protection officers investigating brute-force probing.
 
 const MAX_LIMIT = 100;
 const REQUEST_ID = "user-data-rights:list-download-attempts";

package/packages/bundled-features/src/user-data-rights/handlers/my-audit-log.query.ts

@@ -5,10 +5,10 @@ import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { redactPiiCiphertext } from "../../shared/index.ts";
 
-// DSGVO Art. 15 Selbstauskunft — User reads HIS OWN audit-log.
-// WHERE createdBy = ctx.user.id ist hard-coded (kein userId-Param,
-// anti-cross-user-Snooping). KEIN tenantId-Filter: User hat Anspruch
-// auf account-weite Sicht ueber alle Memberships — analog Forget-Pfad.
+// GDPR Art. 15 self-disclosure: users may read only their own audit log.
+// `createdBy = ctx.user.id` is hard-coded to prevent cross-user snooping;
+// no `tenantId` filter is applied because the user is entitled to an
+// account-wide view across all memberships, as in the forget path.
 const MAX_LIMIT = 100;
 
 const MY_AUDIT_LOG_REASON =

package/packages/bundled-features/src/user-data-rights/handlers/request-deletion-by-email.write.ts

@@ -4,20 +4,20 @@ import { USER_STATUS, userTable } from "../../user/index.ts";
 import { signDeletionToken } from "../deletion-token.ts";
 import { updateUserLifecycle } from "../lib/update-user-lifecycle.ts";
 
-// TTL des Verify-Links. 60 min — lang genug für einen Mail-Roundtrip,
-// kurz genug dass ein abgefangener Link nicht ewig gültig ist.
+// Verification-link TTL: 60 minutes — long enough for an email round trip,
+// but short enough that an intercepted link does not remain valid indefinitely.
 const DELETION_VERIFY_TTL_MINUTES = 60;
 
-// Apex-Magic-Link-Versand für den anonymen Deletion-Request. Der Handler
-// gibt den Link NICHT zurück (content-Enumeration-Safety) — er ruft den
-// Callback direkt, analog sendDeletionRequestedEmail.
+// Sends the Apex magic link for an anonymous deletion request. The handler
+// does NOT return the link (content-enumeration safety); it invokes the
+// callback directly, analogous to sendDeletionRequestedEmail.
 //
-// WICHTIG (Timing-Oracle): Der Callback MUSS non-blocking sein (enqueue, z.B.
-// delivery.notify / Job), NICHT synchron senden. Er läuft nur im
-// existierenden-aktiven-User-Pfad; ein synchroner Send macht die
-// Response-Latenz für reale Accounts messbar länger als für nicht-existente
-// → Enumeration über Timing. Ein schnelles enqueue gleicht das praktisch aus.
-// Vollständige Timing-Angleichung (immer äquivalente Arbeit) ist v1-Follow-up.
+// IMPORTANT (timing oracle): The callback MUST be non-blocking (enqueue, e.g.
+// delivery.notify / Job), not send synchronously. It runs only for an
+// existing active user; a synchronous send makes response latency measurably
+// longer for real accounts than for nonexistent ones, enabling enumeration by
+// timing. A fast enqueue effectively equalizes this.
+// Complete timing equalization (always performing equivalent work) is deferred.
 export type SendDeletionVerificationEmailFn = (args: {
   readonly email: string;
   readonly verifyUrl: string;
@@ -25,12 +25,12 @@ export type SendDeletionVerificationEmailFn = (args: {
 }) => Promise<void>;
 
 export type RequestDeletionByEmailOptions = {
-  /** HMAC-Secret zum Signieren des Verify-Tokens. Ohne Secret ist der Flow
-   *  deaktiviert (Handler antwortet still mit success, kein Link). */
+  /** HMAC secret used to sign the verification token. Without a secret, the flow
+   *  is disabled (the handler silently responds with success and no link). */
   readonly deletionTokenSecret?: string;
-  /** Basis-URL des Apex-Confirm-Screens, z.B.
-   *  "https://app.example.com/delete-account/confirm". Der Handler hängt das
-   *  Token als URL-Fragment an (`#token=<token>`, fw#1554). Ohne URL kein Link. */
+  /** Base URL of the Apex confirmation screen, e.g.
+   *  "https://app.example.com/delete-account/confirm". The handler appends the
+   *  token as a URL fragment (`#token=<token>`). Without a URL, no link is sent. */
   readonly deletionVerifyUrl?: string;
   readonly sendDeletionVerificationEmail?: SendDeletionVerificationEmailFn;
 };
@@ -38,7 +38,7 @@ export type RequestDeletionByEmailOptions = {
 // Token goes in the URL fragment, not a query param — fragments never leave
 // the browser (not sent to the server, so they never land in proxy/access
 // logs, unlike `?token=`). Same convention as the export-download link
-// (feature.ts, issue #1271). Preserves any existing query params on `base`
+// (feature.ts). Preserves any existing query params on `base`
 // (`?lang=de` stays a query param; only the token is a fragment).
 const APPEND_LIFECYCLE_EVENT_REASON =
   "appends the user lifecycle event on the SYSTEM_TENANT_ID user stream";
@@ -49,14 +49,14 @@ export function buildDeletionVerifyUrl(base: string, token: string): string {
   return url.toString();
 }
 
-// Anonymer Apex-Flow Schritt 1: "Account-Löschung beantragen" per Email.
-// DSGVO-relevant gerade wenn der User sich NICHT mehr einloggen kann
-// (Lockout). Email → Magic-Link → confirm-deletion-by-token.
+// Anonymous Apex flow step 1: request account deletion by email.
+// This is especially relevant for GDPR when the user can no longer log in
+// (lockout). Email → magic link → confirm-deletion-by-token.
 //
-// Enumeration-safe (content): antwortet IMMER mit derselben success-Shape,
-// egal ob die Email existiert, der User aktiv ist oder der Flow konfiguriert
-// ist. Ein Link wird nur für einen existierenden, aktiven User generiert.
-// Timing-Safety hängt am non-blocking Callback (siehe Type-Doc oben).
+// Enumeration-safe (content): always returns the same success shape,
+// regardless of whether the email exists, the user is active, or the flow is
+// configured. A link is generated only for an existing, active user.
+// Timing safety depends on the non-blocking callback (see the type doc above).
 export function createRequestDeletionByEmailHandler(opts: RequestDeletionByEmailOptions = {}) {
   return defineWriteHandler({
     name: "request-deletion-by-email",
@@ -66,7 +66,7 @@ export function createRequestDeletionByEmailHandler(opts: RequestDeletionByEmail
       "Mails an account-deletion verification link to the given address, for a user who wants to be erased but can no longer log in; it answers identically whether or not the address belongs to an active account and never returns the link.",
     // Mails a deletion link to any address the caller names.
     agent: { risk: "high" },
-    // Defense-in-depth gegen Email-Probing auf dem anonymen Endpoint.
+    // Defense in depth against email probing on the anonymous endpoint.
     rateLimit: { per: "ip+handler", limit: 10, windowSeconds: 60 },
     escapeHatch: {
       grants: ["unsafeRaw", "globalWrites"],
@@ -75,7 +75,8 @@ export function createRequestDeletionByEmailHandler(opts: RequestDeletionByEmail
     handler: async (event, ctx) => {
       const success = { isSuccess: true as const, data: { kind: "requested" as const } };
 
-      // not-configured-safe: ohne Secret/URL kein Link, aber gleiche Antwort.
+      // Safe when not configured: without a secret or URL, no link is sent, but the response is
+      // unchanged.
       if (!opts.deletionTokenSecret || !opts.deletionVerifyUrl) return success;
 
       const userRow = await ctx.db
@@ -88,9 +89,9 @@ export function createRequestDeletionByEmailHandler(opts: RequestDeletionByEmail
         return success;
       }
 
-      // Replay-Schutz (#354/1): pro Antrag eine frische requestId, die auf der
-      // user-Row landet und in die Token-HMAC-Purpose gefaltet wird. cancel
-      // nullt sie → ein nach Cancel nachgespieltes Token verifiziert nicht mehr.
+      // Replay protection: each request gets a fresh requestId, which is stored on
+      // the user row and incorporated into the token HMAC purpose. cancel
+      // nulls it, so a token replayed after cancellation no longer verifies.
       const requestId = crypto.randomUUID();
       await updateUserLifecycle(ctx.db.unsafeRaw(), userRow["id"], {
         pendingDeletionRequestId: requestId,

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

@@ -9,13 +9,12 @@ import {
 } from "../lib/default-mailers.ts";
 import { resolveGracePeriod, startDeletionGracePeriod } from "./deletion-grace-period.ts";
 
-// Atom 5b — Email-Notification beim deletion-requested-flip. Pattern:
-// password-reset-Callback aus auth-routes.ts. Best-effort — Throw beim
-// Send wird gefangen + per console.warn geloggt, der Status-Flip selbst
-// bleibt erfolgreich. Reasoning: user-Aktion ist abgeschlossen sobald
-// die DB-Row geflipt ist; Email-Versand ist Beleg, keine Vorbedingung.
-// Wenn Email broken ist soll der User nicht erneut "Account löschen"
-// klicken muessen.
+// Sends a best-effort email after the deletion-requested status flip, following the
+// password-reset callback pattern in auth-routes.ts. Send failures are caught and logged
+// with console.warn so the status change remains successful: the user's action is complete
+// once the database row is updated, while email delivery is confirmation rather than a
+// prerequisite. This prevents users from having to click "Delete account" again when
+// email delivery fails.
 export type SendDeletionRequestedEmailFn = (args: {
   readonly userId: string;
   readonly userEmail: string;
@@ -28,16 +27,15 @@ export type SendDeletionRequestedEmailFn = (args: {
 
 export type RequestDeletionOptions = {
   readonly sendDeletionRequestedEmail?: SendDeletionRequestedEmailFn;
-  /** Branding fuer die Default-Mail wenn kein sendDeletionRequestedEmail
-   *  gesetzt ist + mail-foundation gemountet ist. */
+  /** Branding for the default email when sendDeletionRequestedEmail is not set
+   *  and mail-foundation is mounted. */
   readonly mailDefaults?: GdprMailDefaults;
 };
 
-// POST /api/user/request-deletion (S2.U5a) — DSGVO Art. 17 Forget-Antrag.
-// Flippt status=Active → deletionRequested, setzt gracePeriodEnd aus dem
-// Compliance-Profile (geteilte Logik: startDeletionGracePeriod). Account-
-// weite Semantik (1 User-Row global), siehe docs/plans/architecture/
-// user-data-rights.md "Cross-Tenant-Semantik".
+// POST /api/user/request-deletion — GDPR Art. 17 erasure request.
+// Changes status=Active → deletionRequested and sets gracePeriodEnd from the compliance
+// profile using the shared startDeletionGracePeriod logic. The operation applies to the
+// account-wide user row, so the user identity is global across tenants.
 export function createRequestDeletionHandler(opts: RequestDeletionOptions = {}) {
   return defineWriteHandler({
     name: "request-deletion",
@@ -78,8 +76,7 @@ export function createRequestDeletionHandler(opts: RequestDeletionOptions = {})
           ? makeDefaultDeletionRequestedEmail(ctx.notify, opts.mailDefaults)
           : undefined);
 
-      // Best-effort Email-Notification. Send-Failure darf das Write nicht
-      // killen — siehe Type-Doc oben.
+      // Best-effort email notification: a send failure must not abort the write.
       if (send && userEmail.length > 0) {
         try {
           await send({
@@ -97,8 +94,8 @@ export function createRequestDeletionHandler(opts: RequestDeletionOptions = {})
         }
       }
 
-      // Response liefert den absoluten gracePeriodEnd-Timestamp damit
-      // Frontend/Audit/Cleanup-Runner alle denselben Wert lesen.
+      // Returns the absolute gracePeriodEnd timestamp so the frontend, audit, and cleanup
+      // runner all use the same value.
       return {
         isSuccess: true as const,
         data: {

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

@@ -1,24 +1,25 @@
-// POST /api/user/request-export (S2.U3 Atom 2) — DSGVO Art. 15 + 20 Trigger.
+// POST /api/user/request-export — GDPR Art. 15 and 20 trigger.
 //
-// User triggert Export-Job. Persistenz via createEventStoreExecutor
-// (ES-Pattern, Memory: ES kein CRUD). Idempotency-Strategie zweistufig:
+// The user triggers an export job, persisted through
+// createEventStoreExecutor (event-sourced pattern; ES has no CRUD).
+// Idempotency uses two stages:
 //
-//   1) **App-side-Pre-Check (primaerer Pfad):** fetchOne aktive Jobs
-//      (status pending|running) fuer den userId. Wenn existing,
-//      return `{jobId, isExisting: true}` — KEIN neues Event,
-//      sauberer Audit-Trail (1 Klick-Storm = 1 Event, nicht N).
+//   1) **App-side pre-check (primary path):** fetch active jobs with
+//      (status pending|running) for the userId. If one exists, return
+//      `{jobId, isExisting: true}` without creating an event, so a click
+//      storm produces one audit event rather than N.
 //
-//   2) **DB-Constraint als Race-Schutz (Sekundaerpfad):** Bei parallelem
-//      Klick zwischen fetchOne + crud.create wirft die Tx 23505 mit
-//      constraint_name === "read_export_jobs_one_active_per_user".
-//      Catch + re-fetch + return existing als isExisting=true. Race-
-//      Window <1ms, in Production extrem selten.
+//   2) **DB constraint as race protection (secondary path):** if a parallel
+//      click occurs between fetchOne and crud.create, the transaction raises
+//      23505 with constraint_name === "read_export_jobs_one_active_per_user".
+//      Catch, re-fetch, and return the existing job with isExisting=true.
 //
-// **Cross-Tenant-Semantik:** ExportJob is tenant-agnostic (1 job per userId
-// across all memberships) — the pre-check uses ctx.db.unsafeRaw (no TenantDb filter) so a click from tenant B still finds the job from tenant A.
-// `requestedFromTenantId` persistiert den Initial-Tenant aus dem
-// 1. Klick — Worker liest sein Compliance-Profile aus DIESEM Tenant
-// fuer Job-TTL/Stale/Cleanup.
+// **Cross-tenant semantics:** ExportJob is tenant-agnostic (one job per
+// userId across all memberships), so the pre-check uses ctx.db.unsafeRaw
+// (no TenantDb filter) and a click from tenant B can find the job from tenant
+// A. `requestedFromTenantId` persists the tenant from the first click; the
+// worker reads its compliance profile from this tenant for job TTL, stale
+// handling, and cleanup.
 
 import { createEventStoreExecutor, fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler, type SaveContext } from "@cosmicdrift/kumiko-framework/engine";
@@ -40,11 +41,11 @@ const REQUEST_EXPORT_REASON =
   "export jobs are keyed by userId across all of the user's tenant memberships, not the caller's current tenant";
 
 /**
- * Race-Loss-Detection: createEventStoreExecutor.create catched 23505
- * intern + returnt `WriteFailure(UniqueViolationError)`, **kein throw**.
- * Wir checken den Failure-Code + constraintName um den App-side-vs-Race-
- * Pfad zu unterscheiden. Andere Failures (validation, version-conflict,
- * ...) propagieren unveraendert.
+ * `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 {
@@ -82,9 +83,9 @@ export const requestExportWrite = defineWriteHandler({
     // TenantDb-Wrapper would hide cross-tenant jobs.
     const existing = await findActiveJob(exportJobRunner, userId);
     if (existing) {
-      // Snapshot-Status (kann zwischen fetchOne + Response stale werden
-      // wenn Worker parallel den State flippt; window minimal). User
-      // pollt fuer Live-Wahrheit ueber export-status.query.
+      // The returned status is a snapshot and can become stale between fetchOne
+      // and the response if the worker changes the state concurrently. The
+      // window is minimal; clients poll export-status.query for live status.
       return {
         isSuccess: true as const,
         data: {
@@ -95,9 +96,9 @@ export const requestExportWrite = defineWriteHandler({
       };
     }
 
-    // Kein active Job — neuen anlegen via crud.create. requestedFromTenantId
-    // = aktueller Tenant des Users; Worker liest sein Compliance-Profile
-    // aus diesem Tenant.
+    // No active job exists, so create one through crud.create. Persist the
+    // user's current tenant in requestedFromTenantId so the worker reads the
+    // compliance profile from that tenant.
     const result = await crud.create(
       {
         userId,
@@ -110,16 +111,16 @@ export const requestExportWrite = defineWriteHandler({
     );
 
     if (!result.isSuccess) {
-      // Race-Pfad: paralleler Klick hat zwischen findActiveJob + crud.create
-      // einen aktiven Job angelegt → UniqueViolationError mit unserem
-      // Constraint. Re-fetch + return existing als isExisting=true.
-      // Andere Failures (validation, version-conflict, ...) propagieren.
+      // A parallel click may create an active job between findActiveJob and
+      // 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)) {
         const winner = await findActiveJob(exportJobRunner, userId);
         if (!winner) {
-          // Sollte nie passieren — Constraint-Violation ohne existing
-          // active Job hiesse der Constraint matcht etwas anderes.
-          // Original-Failure zurueckgeben damit das auffaellt.
+          // This should be impossible: a constraint violation without an existing
+          // active job would mean the constraint matched something else.
+          // Return the original failure so the inconsistency is visible.
           return result;
         }
         return {
@@ -134,17 +135,17 @@ export const requestExportWrite = defineWriteHandler({
       return result;
     }
 
-    // Happy path: neuer Job. SaveContext.id ist EntityId (number | string);
-    // exportJobEntity hat idType:"uuid" → garantiert string, String()
-    // schuetzt vor Drift falls jemand die Entity auf serial migriert.
+    // SaveContext.id is EntityId (number | string), while exportJobEntity has
+    // idType:"uuid" and therefore guarantees a string. String() protects
+    // against drift if the entity is migrated to serial.
     const created = result.data as SaveContext; // @cast-boundary engine-payload
     return {
       isSuccess: true as const,
       data: {
         jobId: String(created.id),
-        // Snapshot: just-created → pending. Live-Wahrheit kommt ueber
-        // export-status.query, status hier ist nice-to-have fuer das
-        // initial UI-Render ("Anfrage angenommen, currently pending").
+        // This is a snapshot: a just-created job is pending. Live status comes
+        // from export-status.query; this value is only a convenience for the
+        // initial UI render ("Anfrage angenommen, currently pending").
         status: EXPORT_JOB_STATUS.Pending,
         isExisting: false,
       },