@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

package/packages/bundled-features/src/data-retention/override-schema.ts

@@ -1,17 +1,16 @@
-// Zod-Schema fuer RetentionOverride mit .strict() — Sprint 2.D2.5 (M2+M3).
+// Strict Zod schema for RetentionOverride.
 //
-// Symmetrisch zu compliance-profiles override-schema.ts (S1.9 Z3).
-// Sub-Sprint-Pattern (advisor-pinned): bei jedem User-konfigurierbarem
-// JSON-Override → strict-Zod + enum-validated.
+// Symmetric with compliance-profiles override-schema.ts.
+// Every user-configurable JSON override uses strict Zod validation
+// with enum validation.
 //
-// Schuetzt vor:
-//   - Top-Level-Tippfehler ("keepfor" statt "keepFor") — strict()-Reject
-//   - Strategy-Enum-Drift ("delete" statt "hardDelete") — z.enum-Reject
-//   - keepFor-Format-Drift ("30days" statt "30d") — regex-Reject
+// Protects against:
+//   - Top-level typos ("keepfor" instead of "keepFor") — strict() rejects them
+//   - Strategy enum drift ("delete" instead of "hardDelete") — z.enum rejects it
+//   - keepFor format drift ("30days" instead of "30d") — regex rejects it
 //
-// Tenant-Override darf alle drei Properties weglassen (Resolver
-// fallback auf Preset/Entity-Default), aber WAS gesetzt ist muss
-// gueltig sein.
+// A tenant override may omit all three properties (the resolver falls back
+// to the preset/entity default), but every property that is set must be valid.
 
 import * as z from "zod";
 
@@ -20,10 +19,9 @@ const KEEP_FOR_PATTERN = /^\d+[hdwmy]$/;
 const retentionStrategySchema = z.enum(["hardDelete", "softDelete", "anonymize", "blockDelete"]);
 
 /**
- * RetentionOverride-Zod-Schema mit .strict() — fuer (a) set-override-
- * Handler-Validation (S2.D3) und (b) DB-Loader im Cleanup-Job (S2.D2b)
- * der invalides JSON aus der config-Spalte loggt + skipt statt mit
- * undefined behavior weiterzumachen.
+ * Strict Zod schema for RetentionOverride, used by the set-override handler
+ * and the cleanup job's DB loader. The loader logs invalid JSON from the
+ * config column and skips it instead of continuing with undefined behavior.
  */
 export const retentionOverrideSchema = z
   .object({

package/packages/bundled-features/src/data-retention/presets.ts

@@ -1,14 +1,10 @@
-// Retention-Presets — vorgefertigte Bündel von per-Entity-Aufbewahrungs-
-// Konfigurationen pro Compliance-Regime. Tenant-Admin wählt EINES (analog
-// zu compliance-profiles); Entity-Default + Tenant-Override liegen als
-// Schichten 1+3 darüber (siehe resolver.ts).
+// Retention presets — predefined bundles of per-entity retention
+// configurations for each compliance regime. The tenant admin selects ONE
+// (analogous to compliance profiles); the entity default and tenant override
+// are layered above it as layers 1 and 3 (see resolver.ts).
 //
-// Plan-Roadmap docs/plans/datenschutz/core-data-retention.md hat 8 Presets
-// vorgeschlagen. Sprint-2-MVP: 3 Production-Presets + 1 dev-Default,
-// rest folgt on-demand wenn Customer fragt.
-//
-// Presets sind pure Daten — keine Logik. Erweitern = Constant erweitern,
-// kein Code-Eingriff.
+// The presets are pure data with no logic. Extending them means extending the
+// constant; no code changes are required.
 
 import type { RetentionDef } from "@cosmicdrift/kumiko-framework/engine";
 
@@ -23,25 +19,25 @@ export type RetentionPreset = Readonly<Record<string, RetentionDef>>;
 export type RetentionPresetKey = "default" | "dsgvo-basic" | "dsgvo-hgb" | "swiss-dsg";
 
 /**
- * MVP-Set für Sprint 2. Erweiterungen (hipaa, ccpa, aggressive-gdpr,
- * pipeda-default, ca-quebec-l25) kommen on-demand.
+ * Available presets. Additional options (hipaa, ccpa, aggressive-gdpr,
+ * pipeda-default, ca-quebec-l25) can be added on demand.
  */
 export const RETENTION_PRESETS: Readonly<Record<RetentionPresetKey, RetentionPreset>> = {
-  // Default — keine Auto-Aktion. Nur sinnvoll für Dev/Staging.
-  // Production-Tenant der "default" stehen lässt → Cleanup-Job
-  // schreibt Audit-Eintrag "skipped: no preset selected".
+  // Default — no automatic action; intended only for Dev/Staging.
+  // A production tenant that leaves `default` selected causes the cleanup job
+  // to write the audit entry "skipped: no preset selected".
   default: {},
 
-  // DSGVO Basic — Datenminimierung ohne Buchhaltungspflichten.
+  // DSGVO Basic — data minimization without accounting retention obligations.
   "dsgvo-basic": {
     "audit-log": { keepFor: "1y", strategy: "hardDelete", reference: "createdAt" },
     session: { keepFor: "30d", strategy: "hardDelete", reference: "lastSeenAt" },
     "http-log": { keepFor: "90d", strategy: "hardDelete", reference: "createdAt" },
   },
 
-  // DSGVO + HGB — deutsche Aufbewahrungspflichten überlagert. Order
-  // wird anonymisiert (PII raus, Geschäftsdaten bleiben), Invoice +
-  // Booking sind blockDelete bis 10 Jahre, dann Anonymize.
+  // DSGVO + HGB — German statutory retention obligations take precedence.
+  // Orders are anonymized (PII removed while business data remains); invoices
+  // and bookings are blockDelete for up to 10 years, then anonymized.
   "dsgvo-hgb": {
     "audit-log": { keepFor: "1y", strategy: "hardDelete", reference: "createdAt" },
     session: { keepFor: "30d", strategy: "hardDelete", reference: "lastSeenAt" },
@@ -52,7 +48,7 @@ export const RETENTION_PRESETS: Readonly<Record<RetentionPresetKey, RetentionPre
     order: { keepFor: "6y", strategy: "anonymize", reference: "completedAt" },
   },
 
-  // Schweizer DSG — ähnlich DSGVO mit OR Art. 958f Aufbewahrung.
+  // Swiss DSG — similar to DSGVO, with retention under OR Art. 958f.
   "swiss-dsg": {
     "audit-log": { keepFor: "1y", strategy: "hardDelete", reference: "createdAt" },
     session: { keepFor: "30d", strategy: "hardDelete", reference: "lastSeenAt" },
@@ -61,9 +57,8 @@ export const RETENTION_PRESETS: Readonly<Record<RetentionPresetKey, RetentionPre
 } satisfies Readonly<Record<RetentionPresetKey, RetentionPreset>>;
 
 /**
- * Auswählbare Presets für den Onboarding-Banner. "default" ist Migration-
- * Edge-Case und wird nicht angezeigt — Production-Tenants wählen ein
- * echtes Preset.
+ * Presets available in the onboarding banner. `default` is a migration edge
+ * case and is not displayed; production tenants must choose an actual preset.
  */
 export const SELECTABLE_RETENTION_PRESETS: readonly RetentionPresetKey[] = [
   "dsgvo-basic",

package/packages/bundled-features/src/data-retention/resolve-for-tenant.ts

@@ -13,7 +13,7 @@ import { type EffectiveRetentionPolicy, resolveRetentionPolicy } from "./resolve
 import { tenantRetentionOverrideTable } from "./schema/tenant-retention-override.ts";
 
 export interface ResolveForTenantArgs {
-  // fw#2914 — a EXT_USER_DATA hook's ctx.db is a TenantDb (method-form);
+  // A EXT_USER_DATA hook's ctx.db is a TenantDb (method-form);
   // the cleanup cron's own db is still a raw DbRunner. Both are valid here —
   // this lookup is a plain tenant-scoped read either way.
   readonly db: DbRunner | TenantDb;

package/packages/bundled-features/src/data-retention/resolve-tenant-preset.ts

@@ -1,15 +1,16 @@
-// Leitet den Layer-2 Retention-Preset eines Tenants aus seinem Compliance-
-// Profile ab. Der retention-cleanup-Cron ruft das pro fan-out-Tenant.
+// Derives a tenant's Layer-2 retention preset from its compliance profile.
+// The retention-cleanup cron calls this once per fan-out tenant.
 //
-// **Soft-Dependency:** data-retention bleibt standalone-mountbar. Nur wenn
-// compliance-profiles mit-gemountet ist (seine Entity registriert), wird ein
-// Preset abgeleitet — sonst null, dann greifen ausschliesslich Entity-Defaults
-// (Layer 1) + per-Entity Tenant-Overrides (Layer 3). Kein r.requires, damit
-// eine App data-retention auch ohne Compliance-Profiles nutzen kann.
+// **Soft dependency:** data-retention remains mountable standalone. A preset is
+// derived only when compliance-profiles is mounted as well (its entity is
+// registered); otherwise this returns null, leaving only entity defaults
+// (Layer 1) and per-entity tenant overrides (Layer 3). No r.requires is used,
+// so an app can use data-retention without compliance-profiles.
 //
-// Die Map ist intentional: Compliance-Profile (Region) und Retention-Preset
-// sind beide um dieselben drei Regimes gebaut (EU/CH/DE-HGB). swiss-dsg ist
-// sogar namensgleich. minimal-no-region → "default" (No-Op-Preset).
+// The mapping is intentional: compliance profiles (regions) and retention
+// presets are both built around the same three regimes (EU/CH/DE-HGB).
+// swiss-dsg even has the same name. minimal-no-region maps to "default"
+// (a no-op preset).
 
 import type { ComplianceProfileKey } from "@cosmicdrift/kumiko-framework/compliance";
 import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
@@ -17,8 +18,8 @@ import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { resolveProfileForTenant } from "../compliance-profiles/index.ts";
 import type { RetentionPresetKey } from "./presets.ts";
 
-// r.entity-Name aus compliance-profiles/feature.ts — Probe ob das Feature
-// gemountet ist, bevor wir seine Tabelle lesen (sonst wirft fetchOne).
+// Entity name from compliance-profiles/feature.ts — check that the feature is
+// mounted before reading its table; otherwise fetchOne throws.
 const COMPLIANCE_PROFILE_ENTITY = "tenant-compliance-profile";
 
 const PROFILE_TO_PRESET: Readonly<Record<ComplianceProfileKey, RetentionPresetKey>> = {
@@ -43,12 +44,12 @@ export async function resolveTenantRetentionPreset(
   if (!args.registry.getEntity(COMPLIANCE_PROFILE_ENTITY)) {
     return null;
   }
-  // resolveProfileForTenant liest die 1:1-Profile-Row des Tenants (boot-DB,
-  // by tenantId gefiltert) und faellt auf minimal-no-region zurueck wenn der
-  // Tenant noch kein Profile gewaehlt hat.
+  // resolveProfileForTenant reads the tenant's 1:1 profile row from the boot DB,
+  // filtered by tenantId, and falls back to minimal-no-region when the tenant
+  // has not selected a profile yet.
   const effective = await resolveProfileForTenant({ db: args.db, tenantId: args.tenantId });
   return PROFILE_TO_PRESET[effective.profile.key] ?? null;
 }
 
-// Exportiert fuer den Unit-Test (Map-Vollstaendigkeit gegen ComplianceProfileKey).
+// Exported for the unit test that checks completeness against ComplianceProfileKey.
 export { PROFILE_TO_PRESET };

package/packages/bundled-features/src/data-retention/resolver.ts

@@ -1,30 +1,30 @@
-// 3-Schicht-Retention-Resolver.
+// Three-layer retention resolver.
 //
-// Layer 1: Entity-Default       — Feature-Author setzt r.entity({retention})
-// Layer 2: Tenant-Preset        — Tenant-Admin wählt Bundle (RETENTION_PRESETS)
-// Layer 3: Tenant-Override      — per (tenantId, entityName) JSON-Override
+// Layer 1: Entity default       — Feature author sets r.entity({retention})
+// Layer 2: Tenant preset        — Tenant admin selects a bundle (RETENTION_PRESETS)
+// Layer 3: Tenant override      — per (tenantId, entityName) JSON override
 //
-// Resolver-Reihenfolge:
+// Resolution order:
 //   effective = override(tenantId, entityName)
 //             ?? preset[tenant.retentionPreset][entityName]
-//             ?? entity.retention   (Code-Default aus EntityDefinition)
-//             ?? null               (keine Auto-Aktion)
+//             ?? entity.retention   (code default from EntityDefinition)
+//             ?? null               (no automatic action)
 //
-// Cleanup-Job in S2.D2 ruft das pro (tenantId, entityName) und
-// entscheidet was zu tun ist (hardDelete / softDelete / anonymize /
-// blockDelete-mit-Frist-Check).
+// The cleanup job resolves this for each (tenantId, entityName) and
+// decides what to do (hardDelete / softDelete / anonymize /
+// blockDelete with a grace-period check).
 //
-// Cross-Feature-API r.exposesApi("retention.policyFor") (S2.D3)
-// macht das aus user-data-rights heraus konsumierbar — Forget-Flow
-// fragt blockDelete-Felder ab + anonymisiert sie statt zu löschen.
+// The cross-feature API r.exposesApi("retention.policyFor")
+// makes this consumable by user-data-rights — the forget flow
+// queries blockDelete fields and anonymizes them instead of deleting them.
 
 import type { EntityDefinition, RetentionDef } from "@cosmicdrift/kumiko-framework/engine";
 import { RETENTION_PRESETS, type RetentionPresetKey } from "./presets.ts";
 
 /**
- * Roh-Override aus der DB-Tabelle (config-Spalte als JSON-String).
- * Nicht das gleiche wie RetentionDef weil hier alles optional ist —
- * Override darf einzelne Properties überschreiben.
+ * Raw override from the database table (the config column as a JSON string).
+ * Unlike RetentionDef, every property is optional because an override may
+ * replace individual properties.
  */
 export interface RetentionOverride {
   readonly keepFor?: string;
@@ -33,13 +33,13 @@ export interface RetentionOverride {
 }
 
 /**
- * Effektive Policy nach Resolver-Lauf. Source dokumentiert WELCHE
- * Schicht den Wert geliefert hat — Audit-Trail für DPO.
+ * Effective policy after the resolver ran. `source` records WHICH layer
+ * supplied the value, as an audit trail for the DPO.
  *
- * `override-incomplete` bedeutet: Tenant-Override ist gesetzt, aber
- * füllt keepFor weder selbst noch via Preset-/Entity-Fallback.
- * Cleanup-Job logt eine Warning + skippt — anstatt mit Default-"0d"
- * sofort alles zu löschen.
+ * `override-incomplete` means a tenant override is set but fills keepFor
+ * neither itself nor through the preset/entity fallback. The cleanup job
+ * logs a warning and skips instead of deleting everything at once with a
+ * default "0d".
  */
 export interface EffectiveRetentionPolicy {
   readonly entityName: string;
@@ -55,15 +55,15 @@ export interface ResolveRetentionPolicyArgs {
 }
 
 /**
- * Auswertung der drei Schichten. Pure Function — kein DB-Access, alle
- * Inputs werden vom Caller besorgt (Cleanup-Job aggregiert pro Tenant
- * vorher).
+ * Resolves the three layers. This is a pure function with no database
+ * access; the caller supplies all inputs (the cleanup job aggregates them
+ * per tenant beforehand).
  */
 export function resolveRetentionPolicy(args: ResolveRetentionPolicyArgs): EffectiveRetentionPolicy {
   const { entityName, entityDef, tenantPreset, tenantOverride } = args;
 
-  // Layer 3: Override wins, aber Override darf Felder weglassen — dann
-  // fallen die einzelnen Properties auf Layer 2/1 zurück.
+  // Layer 3: Override wins, but it may omit fields, which then
+  // fall back to the individual properties from Layer 2 or 1.
   if (tenantOverride !== null) {
     const baseFromPreset =
       tenantPreset !== null ? (RETENTION_PRESETS[tenantPreset]?.[entityName] ?? null) : null;
@@ -73,10 +73,11 @@ export function resolveRetentionPolicy(args: ResolveRetentionPolicyArgs): Effect
     const keepFor = tenantOverride.keepFor ?? base?.keepFor;
     const strategy = tenantOverride.strategy ?? base?.strategy;
 
-    // keepFor + strategy sind Pflicht für jede aktive Policy. Wenn
-    // weder Override noch Base sie liefert, ist das Override semantisch
-    // unvollständig — Cleanup-Job soll WARNEN statt mit Default-"0d"
-    // sofort alles löschen. Source-Marker dokumentiert das.
+    // keepFor + strategy are required for every active policy. If
+    // neither the override nor the base supplies them, the override is
+    // semantically incomplete — the cleanup job must warn instead of
+    // immediately deleting everything with the default "0d". The source
+    // marker documents this.
     if (keepFor === undefined || strategy === undefined) {
       return { entityName, policy: null, source: "override-incomplete" };
     }
@@ -102,6 +103,6 @@ export function resolveRetentionPolicy(args: ResolveRetentionPolicyArgs): Effect
     return { entityName, policy: entityDef.retention, source: "entity-default" };
   }
 
-  // Nichts da — Cleanup-Job überspringt diese Entity für diesen Tenant.
+  // No policy is defined, so the cleanup job skips this entity for this tenant.
   return { entityName, policy: null, source: "none" };
 }

package/packages/bundled-features/src/data-retention/run-retention-cleanup.ts

@@ -1,42 +1,41 @@
-// Retention-Cleanup-Runner (S2.D2b) — pure Function, vom retention-cleanup-Cron
-// pro fan-out-Tenant aufgerufen.
+// Retention-Cleanup-Runner — pure function, called by the retention-cleanup cron
+// for each fan-out tenant.
 //
-// Iteriert alle implicit-Entity-Projektionen, loest pro Entity die effektive
-// Retention-Policy (3-Schicht-Resolver, siehe resolver.ts) und wendet die
-// Strategy auf Rows an deren reference-Timestamp aelter als der keepFor-Cutoff
-// ist:
+// Iterates all implicit entity projections, resolves the effective retention
+// policy per entity (3-layer resolver, see resolver.ts), and applies the
+// strategy to rows whose reference timestamp is older than the keepFor cutoff:
 //
-//   - hardDelete  → executor.forget pro Row (Event → rebuild-safe hard purge).
+//   - hardDelete  → executor.forget per row (event → rebuild-safe hard purge).
 //                   Entities with file/image/files/images fields: bytes first
 //                   (incl. derivatives), then the fileRef row(s), then the row;
 //                   shared fileRefs (other owner, other row of the same table)
 //                   stay untouched.
-//   - softDelete  → executor.delete pro Row (Event → rebuild-safe soft-delete),
-//                   nur auf noch-nicht-geloeschte (isDeleted:false-Filter)
-//   - anonymize   → executor.update pro Row mit den Werten der per-Feld
-//                   anonymize-Funktionen; Row bleibt (fields.ts-Contract)
-//   - blockDelete → waehrend keepFor unangetastet (Aufbewahrungs-Pflicht;
-//                   user-forget loest anonymize aus). NACH Ablauf laufen die
-//                   anonymize-Funktionen — Geschaeftsdaten bleiben, Personen-
-//                   Bezug raus (fields.ts:44-47).
+//   - softDelete  → executor.delete per row (event → rebuild-safe soft-delete),
+//                   only on not-yet-deleted rows (isDeleted:false filter)
+//   - anonymize   → executor.update per row with the values of the per-field
+//                   anonymize functions; row remains (fields.ts contract)
+//   - blockDelete → untouched during keepFor (retention requirement;
+//                   user-forget triggers anonymize). AFTER expiration, the
+//                   anonymize functions run — business data remains, the person-
+//                   identifying link is removed (fields.ts:44-47).
 //
-// Über den Executor statt Batch-deleteMany/updateMany: ein eventloser Batch-Write
-// auf die (erased) Projektions-Tabelle wird beim Projection-Rebuild
-// gewischt/resurrektiert — das #648-Loch. Kosten: N Events pro Cleanup statt ein
-// Batch-Statement (per-Row-Ceiling, Batch-Event-Variante als Follow-up).
+// Via the executor instead of batch-deleteMany/updateMany: an eventless batch write
+// to the (erased) projection table is wiped/resurrected during a projection rebuild.
+// Cost: N events per cleanup instead of one batch statement (per-row ceiling, with
+// a batch-event variant later).
 //
-// **Schaerfer als soft-delete-cleanup:** dieser Cron hardDeleted LIVE Rows
-// (keyed auf reference, Default createdAt), nicht bereits-soft-geloeschte.
-// Darum die Spalten-Existenz-Pruefung vor jedem WHERE — eine fehlende/vertippte
-// reference-Spalte wuerde sonst ein malformed/all-matching WHERE ergeben und
-// pauschal loeschen.
+// **Stricter than soft-delete-cleanup:** this cron hard-deletes LIVE rows
+// (keyed on reference, default createdAt), not already-soft-deleted ones.
+// Therefore the column-existence check comes before every WHERE — a missing/mistyped
+// reference column would otherwise produce a malformed/all-matching WHERE and
+// delete everything.
 //
-// **anonymize-Idempotenz ohne Marker-Spalte:** die anonymize-Funktionen sind
-// row-unabhaengig (`() => unknown`) — einmal pro Entity ausgewertet ergeben
-// sie die Ziel-Werte. Eine Row die sie schon traegt wird uebersprungen, der
-// taegliche Re-Lauf appended also null Events. Der WHERE matcht anonymisierte
-// Rows weiter (reference bleibt alt), deshalb id-Cursor-Paging statt einer
-// einzelnen Page — sonst verstopfen erledigte Rows das batchLimit-Fenster.
+// **anonymize idempotence without a marker column:** the anonymize functions are
+// row-independent (`() => unknown`) — evaluated once per entity, they produce
+// the target values. A row that already carries them is skipped, so the
+// daily rerun appends zero events. The WHERE continues to match anonymized
+// rows (reference remains old), hence id-cursor paging instead of a single
+// page — otherwise completed rows clog the batchLimit window.
 
 import {
   collectPiiSubjectFields,
@@ -68,6 +67,7 @@ import {
   type SessionUser,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import {
   type FileContext,
   fileRefEntity,
@@ -89,13 +89,13 @@ import { tenantRetentionOverrideTable } from "./schema/tenant-retention-override
 const DEFAULT_BATCH_LIMIT = 1000;
 const DEFAULT_REFERENCE_FIELD = "createdAt";
 
-// Der Boot-Validator (boot-validator/pii-retention.ts FRAMEWORK_TIMESTAMP_FIELDS)
-// erlaubt diese Aliase als retention.reference, auch wenn sie nicht in
-// entity.fields deklariert sind — die physischen Spalten heissen aber anders
-// (table-builder.ts: inserted_at/modified_at). Hier zur Cleanup-Zeit auf das
-// echte Entity-Feld mappen, sonst trifft die Spalten-Existenz-Pruefung unten
-// und der Cron wuerde lautlos nichts tun. deletedAt/lastSeenAt sind echte
-// Felder (softDelete bzw. session) und brauchen keine Uebersetzung.
+// The boot validator (boot-validator/pii-retention.ts FRAMEWORK_TIMESTAMP_FIELDS)
+// permits these aliases as retention.reference even when they are not declared in
+// entity.fields, but the physical columns use different names
+// (table-builder.ts: inserted_at/modified_at). Map them to the actual entity field
+// during cleanup; otherwise the column existence check below would cause the cron
+// to do nothing silently. deletedAt/lastSeenAt are real fields (softDelete and
+// session respectively) and need no translation.
 const FRAMEWORK_REFERENCE_ALIAS: Readonly<Record<string, string>> = {
   createdAt: "insertedAt",
   updatedAt: "modifiedAt",
@@ -108,14 +108,16 @@ export interface RunRetentionCleanupArgs {
   /** Layer-2 preset from resolveTenantRetentionPreset, resolved once per tenant
    *  by the caller rather than per entity here. null = layers 1 and 3 only. */
   readonly preloadedTenantPreset: RetentionPresetKey | null;
-  /** Now-Injection — Tests pinnen den Wert ohne Date-Mock (Pattern keep-for.ts). */
+  /**
+   * Injects the current time so tests can pin it without mocking the date (pattern keep-for.ts).
+   */
   readonly now: Instant;
   readonly batchLimit?: number;
   /** Storage access for hardDelete entities with file/image/files/images fields.
    *  Missing while fileRefs are due → the row stays (skipped "missing_file_storage"),
    *  fail-closed instead of orphaning bytes. */
   readonly files?: FileContext;
-  /** KMS for erasing a hardDeleted row's own subject key (Refs #2057). Defaults
+  /** KMS for erasing a hardDeleted row's own subject key. Defaults
    *  to configuredPiiSubjectKms() (same fallback as run-forget-cleanup.ts);
    *  undefined/no-KMS-configured skips erasure entirely — the row is still
    *  hard-deleted, only crypto-shredding of its DEK is not attempted. */
@@ -137,7 +139,10 @@ export interface RunRetentionCleanupResult {
   readonly softDeleted: number;
   /** Rows deren anonymize-Feld-Funktionen angewendet wurden (anonymize + abgelaufene blockDelete). */
   readonly anonymized: number;
-  /** Anomalien: Policy referenziert eine Spalte die die Tabelle nicht hat, oder anonymize ohne anonymize-Felder. */
+  /**
+   * Anomalies where the policy references a missing table column or anonymize has no anonymize
+   * fields.
+   */
   readonly skipped: readonly RetentionCleanupSkip[];
 }
 
@@ -159,7 +164,7 @@ async function purgeMatchingRows(
   return count;
 }
 
-// --- hardDelete crypto-shredding (Refs #2057) ---
+// --- hardDelete crypto-shredding ---
 //
 // recordOwned/self-pii resolution (subject-resolver.ts) only ever reads
 // `row.id` for these two kinds — resolveRecordSubject uses opts.entityName +
@@ -243,17 +248,14 @@ async function forgetRowAndEraseKeys(args: {
   readonly entityName: string;
   readonly tenantId: TenantId;
   readonly systemUser: SessionUser;
+  readonly rowId: EntityId;
   readonly row: Record<string, unknown>;
   readonly kms: KmsAdapter | undefined;
   readonly registry: Registry;
 }): Promise<{ readonly isSuccess: boolean }> {
   return runInSubTransaction(args.db, async (sp) => {
     const tdb = createTenantDb({ db: sp, tenantId: args.tenantId, mode: "system" });
-    const result = await args.executor.forget(
-      { id: args.row["id"] as EntityId },
-      args.systemUser,
-      tdb,
-    );
+    const result = await args.executor.forget({ id: args.rowId }, args.systemUser, tdb);
     if (!result.isSuccess) return { isSuccess: false };
     await eraseHardDeletedRowKeys({
       kms: args.kms,
@@ -268,7 +270,7 @@ async function forgetRowAndEraseKeys(args: {
   });
 }
 
-// --- hardDelete + file-fields (kumiko-framework#3089) ---
+// --- hardDelete + file-fields ---
 
 // Throws (unsafe key, missing list permission) must fail this row closed,
 // not abort the whole tenant run.
@@ -298,6 +300,7 @@ async function purgeHardDeleteRowWithFiles(args: {
   readonly tenantId: TenantId;
   readonly entityName: string;
   readonly entity: EntityDefinition;
+  readonly rowId: EntityId;
   readonly row: Record<string, unknown>;
   readonly files: FileContext | undefined;
   readonly entityExecutor: ReturnType<typeof createEventStoreExecutor>;
@@ -308,8 +311,7 @@ async function purgeHardDeleteRowWithFiles(args: {
   readonly registry: Registry;
   readonly onSkip: (reason: "missing_file_storage" | "file_delete_failed") => void;
 }): Promise<boolean> {
-  const rowId = String(args.row["id"]);
-  const logContext = `tenant=${args.tenantId} entity=${args.entityName} row=${rowId}`;
+  const logContext = `tenant=${args.tenantId} entity=${args.entityName} row=${String(args.rowId)}`;
   const files = args.files;
   const outcome = await purgeRowFileRefs({
     db: args.db,
@@ -341,6 +343,7 @@ async function purgeHardDeleteRowWithFiles(args: {
       entityName: args.entityName,
       tenantId: args.tenantId,
       systemUser: args.systemUser,
+      rowId: args.rowId,
       row: args.row,
       kms: args.kms,
       registry: args.registry,
@@ -392,7 +395,14 @@ async function purgeHardDeleteRowsWithFiles(args: {
     });
     if (rows.length === 0) break;
     for (const row of rows) {
-      cursor = row["id"] as EntityId; // @cast-boundary db-row
+      const rawId = row["id"];
+      if (typeof rawId !== "string" && typeof rawId !== "number") {
+        throw new InternalError({
+          message: `data-retention: ${args.entityName} row has no usable id (got ${typeof rawId})`,
+        });
+      }
+      const rowId = rawId;
+      cursor = rowId;
       const ok = await purgeHardDeleteRowWithFiles({
         db: args.db,
         table: args.table,
@@ -400,6 +410,7 @@ async function purgeHardDeleteRowsWithFiles(args: {
         tenantId: args.tenantId,
         entityName: args.entityName,
         entity: args.entity,
+        rowId,
         row,
         files: args.files,
         entityExecutor: args.entityExecutor,
@@ -490,9 +501,9 @@ export async function runRetentionCleanup(
 
   // Retention writes go through the executor (events) so a projection rebuild
   // replays the cleanup — a batch deleteMany/updateMany on the (erased)
-  // projection table is eventless and gets wiped/resurrected on rebuild (the
-  // #648 hole this closes). The cron acts as the system actor; the WHERE already
-  // tenant-scopes, so a system-mode TenantDb (no extra filter) is correct.
+  // projection table is eventless and gets wiped/resurrected on rebuild.
+  // The cron acts as the system actor; the WHERE already tenant-scopes, so a
+  // system-mode TenantDb (no extra filter) is correct.
   // ponytail: per-row events, one batchLimit-sized page per entity per run —
   // the daily cron converges (hardDelete removes rows, softDelete's isDeleted
   // filter shrinks the set). A single batched forget/delete event is a follow-up.
@@ -511,8 +522,9 @@ export async function runRetentionCleanup(
   const overrideByEntity = new Map(overrideRows.map((r) => [r.entityName, { config: r.config }]));
 
   for (const proj of registry.getAllProjections().values()) {
-    // Nur implicit-Entity-Projektionen mit Tabelle — wie soft-delete-cleanup.
-    // Custom-Projektionen + unmanaged-Tables (z.B. sessions) sind kein Target.
+    // Only implicit entity projections with a table are targets, as in
+    // soft-delete-cleanup. Custom projections and unmanaged tables (such as
+    // sessions) are excluded.
     if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table) continue;
     const entityName = proj.source;
 
@@ -539,9 +551,9 @@ export async function runRetentionCleanup(
 
     const cutoff = computeCutoff(policy.keepFor, now);
     const where: WhereObject = { [referenceField]: { lt: cutoff } };
-    // Tenant-Scope nur wenn die Tabelle eine tenantId-Spalte hat — identisch zu
-    // soft-delete-cleanup. Ohne diesen Filter wuerde ein Tenant die Rows eines
-    // anderen treffen.
+    // Apply tenant scoping only when the table has a tenantId column, as in
+    // soft-delete-cleanup. Without this filter, one tenant could affect another
+    // tenant's rows.
     if (propertyOf(proj.table, "tenantId") !== undefined) {
       where["tenantId"] = tenantId;
     }
@@ -559,6 +571,7 @@ export async function runRetentionCleanup(
               entityName,
               tenantId,
               systemUser,
+              rowId: id,
               row: { id },
               kms,
               registry,

package/packages/bundled-features/src/data-retention/schema/tenant-retention-override.ts

@@ -5,21 +5,23 @@ import {
   createTextField,
 } from "@cosmicdrift/kumiko-framework/engine";
 
-// tenantRetentionOverride — Layer 3 im 3-Schicht-Resolver.
+// tenantRetentionOverride — Layer 3 in the three-layer resolver.
 //
-// Per (tenantId, entityName) eine optionale Override-Config die das
-// Preset (Layer 2) für genau diese eine Entity überschreibt. Use-Cases:
-//   - Anwaltskanzlei in DE: caseFile 6y blockDelete (nicht im Preset)
-//   - Pilot-Tenant der länger speichert für Test
-//   - Branchenspezifische verkürzte Fristen
+// One optional override config per (tenantId, entityName) replaces the
+// preset (Layer 2) for that entity only. Use cases:
+//   - Law firm in DE: caseFile 6y blockDelete (not in the preset)
+//   - Pilot tenant retaining data longer for testing
+//   - Industry-specific shorter retention periods
 //
-// reason ist Pflicht — Audit für DPO + Aufsichtsbehörde nachvollziehbar.
+// reason is required so the decision is auditable by the DPO and supervisory
+// authorities.
 //
-// config ist JSON-String mit `{ keepFor, strategy, reference? }`. Zod-
-// Schema validiert beim set-override-Call (S2.D2 ggf. erweitert).
+// config is a JSON string with `{ keepFor, strategy, reference? }`. The Zod
+// schema validates it when set-override is called.
 //
-// Tenant-1-zu-N: pro Tenant beliebig viele Entity-Overrides. UNIQUE-
-// Index auf (tenantId, entityName) damit pro Entity max ein Override.
+// Tenant one-to-many: each tenant can have any number of entity overrides.
+// A UNIQUE index on (tenantId, entityName) allows at most one override per
+// entity.
 export const tenantRetentionOverrideEntity = createEntity({
   table: "read_tenant_retention_overrides",
   fields: {