@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.387.0

package/dist/data-retention/presets.js

@@ -1,32 +1,28 @@
-// 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.
 /**
- * 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 = {
-    // 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" },
@@ -36,7 +32,7 @@ export const RETENTION_PRESETS = {
         contract: { keepFor: "6y", strategy: "blockDelete", reference: "createdAt" },
         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" },
@@ -44,9 +40,8 @@ export const RETENTION_PRESETS = {
     },
 };
 /**
- * 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 = [
     "dsgvo-basic",

package/dist/data-retention/resolve-tenant-preset.js

@@ -1,18 +1,19 @@
-// 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 { resolveProfileForTenant } from "../compliance-profiles/index.js";
-// 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 = {
     "eu-dsgvo": "dsgvo-basic",
@@ -24,11 +25,11 @@ export async function resolveTenantRetentionPreset(args) {
     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/dist/data-retention/resolver.d.ts

@@ -1,9 +1,9 @@
 import type { EntityDefinition, RetentionDef } from "@cosmicdrift/kumiko-framework/engine";
 import { 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;
@@ -11,13 +11,13 @@ export interface RetentionOverride {
     readonly reference?: string;
 }
 /**
- * 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;
@@ -31,8 +31,8 @@ export interface ResolveRetentionPolicyArgs {
     readonly tenantOverride: RetentionOverride | null;
 }
 /**
- * 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 declare function resolveRetentionPolicy(args: ResolveRetentionPolicyArgs): EffectiveRetentionPolicy;

package/dist/data-retention/resolver.js

@@ -1,42 +1,43 @@
-// 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 { RETENTION_PRESETS } from "./presets.js";
 /**
- * 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) {
     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;
         const baseFromEntity = entityDef?.retention ?? null;
         const base = baseFromPreset ?? baseFromEntity;
         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" };
         }
@@ -58,6 +59,6 @@ export function resolveRetentionPolicy(args) {
     if (entityDef?.retention) {
         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/dist/data-retention/run-retention-cleanup.d.ts

@@ -11,14 +11,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. */
@@ -33,7 +35,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[];
 }
 export declare function runRetentionCleanup(args: RunRetentionCleanupArgs): Promise<RunRetentionCleanupResult>;

package/dist/data-retention/run-retention-cleanup.js

@@ -1,46 +1,46 @@
-// 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, configuredPiiSubjectKms, isRecordKeyedField, isSelfPiiField, resolveSubjectForField, subjectIdToKey, } from "@cosmicdrift/kumiko-framework/crypto";
 import { createEventStoreExecutor, createTenantDb, nullBlindIndexesForSubject, selectMany, WritePurposes, } from "@cosmicdrift/kumiko-framework/db";
 import { deleteFileRefBytes } from "@cosmicdrift/kumiko-framework/derivatives";
 import { createSystemUser, entityHasAnonymizableSubjectField, } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { fileRefEntity, fileRefsTable, } from "@cosmicdrift/kumiko-framework/files";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { collectSingleFileHolders, planFileFields, purgeRowFileRefs, runInSubTransaction, } from "../shared/index.js";
@@ -49,13 +49,13 @@ import { resolveRetentionPolicyForTenant } from "./resolve-for-tenant.js";
 import { tenantRetentionOverrideTable } from "./schema/tenant-retention-override.js";
 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 = {
     createdAt: "insertedAt",
     updatedAt: "modifiedAt",
@@ -72,7 +72,7 @@ async function purgeMatchingRows(db, table, where, batchLimit, op) {
     }
     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 +
@@ -137,7 +137,7 @@ async function eraseHardDeletedRowKeys(args) {
 async function forgetRowAndEraseKeys(args) {
     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"] }, args.systemUser, tdb);
+        const result = await args.executor.forget({ id: args.rowId }, args.systemUser, tdb);
         if (!result.isSuccess)
             return { isSuccess: false };
         await eraseHardDeletedRowKeys({
@@ -152,7 +152,7 @@ async function forgetRowAndEraseKeys(args) {
         return { isSuccess: true };
     });
 }
-// --- 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.
 async function deleteFileFailingClosed(key, files, logContext) {
@@ -169,8 +169,7 @@ async function deleteFileFailingClosed(key, files, logContext) {
 // fields: purge the un-shared fileRefs (bytes + derivatives, then the fileRef
 // rows), then the entity row itself.
 async function purgeHardDeleteRowWithFiles(args) {
-    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,
@@ -198,6 +197,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,
@@ -230,7 +230,14 @@ async function purgeHardDeleteRowsWithFiles(args) {
         if (rows.length === 0)
             break;
         for (const row of rows) {
-            cursor = row["id"]; // @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,
@@ -238,6 +245,7 @@ async function purgeHardDeleteRowsWithFiles(args) {
                 tenantId: args.tenantId,
                 entityName: args.entityName,
                 entity: args.entity,
+                rowId,
                 row,
                 files: args.files,
                 entityExecutor: args.entityExecutor,
@@ -311,9 +319,9 @@ export async function runRetentionCleanup(args) {
     const skipped = [];
     // 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.
@@ -326,8 +334,9 @@ export async function runRetentionCleanup(args) {
     const overrideRows = await selectMany(db, tenantRetentionOverrideTable, { tenantId });
     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;
@@ -353,9 +362,9 @@ export async function runRetentionCleanup(args) {
         }
         const cutoff = computeCutoff(policy.keepFor, now);
         const where = { [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;
         }
@@ -371,6 +380,7 @@ export async function runRetentionCleanup(args) {
                         entityName,
                         tenantId,
                         systemUser,
+                        rowId: id,
                         row: { id },
                         kms,
                         registry,

package/dist/data-retention/schema/tenant-retention-override.js

@@ -1,20 +1,22 @@
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import { createEntity, createLongTextField, 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: {

package/dist/delivery/feature.js

@@ -55,10 +55,10 @@ export function createDeliveryFeature(options) {
         // boot-validator accepts the projection below because at least one
         // apply-key is a registered domain-event (DELIVERY_ATTEMPT_EVENT).
         // recipientAddress is the real PII (email address); recipientId stays
-        // plaintext — pseudonymous fk, same line as config.userId (#821).
+        // plaintext — pseudonymous fk, same line as config.userId.
         // recipientId is nullable (system-triggered sends to non-users), so the
         // address falls back to the tenant key instead of the plaintext it used
-        // to be — still shreddable, one tenant wide (fw#2776).
+        // to be — still shreddable, one tenant wide.
         r.defineEvent("attempt", deliveryAttemptSchema, {
             piiFields: {
                 recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } },

package/dist/delivery/handlers/log.query.js

@@ -135,7 +135,7 @@ export const logQuery = definePagedQueryHandler({
         const rows = [...tiedRows, ...beyondRows];
         const lastRow = rows[rows.length - 1];
         const nextCursor = rows.length === limit && lastRow ? encodeSortCursor(sortColumn, lastRow) : null;
-        // recipientAddress is stored encrypted under the recipient's DEK (#799)
+        // recipientAddress is stored encrypted under the recipient's DEK
         // — decrypt for the admin log view; forgotten subjects show [[erased]].
         // The notificationType/recipientAddress → type/recipient rename happens
         // here, not in the client: a projectionList screen has no entity to

package/dist/delivery/tables.js

@@ -30,14 +30,15 @@ export const deliveryAttemptsTable = pgTable("store_delivery_attempts", {
     priority: text("priority").notNull().default("normal").$type(),
     createdAt: instant("created_at").default(sql `now()`).notNull(),
 }, (t) => [index(DELIVERY_ATTEMPTS_TENANT_CREATED_INDEX).on(t.tenantId, t.createdAt)]);
-// **Unmanaged table** — bewusst KEIN createEntity. Begründung:
-//   - id kommt aus dem Aggregate-Stream (kein gen_random_uuid()-DEFAULT)
-//   - kein version/inserted_by/modified_by/modified_at — keine in-place-
-//     Edits, keine Audit-Spalten nötig (idempotent-on-replay via PK-Konflikt)
-//   - created_at statt inserted_at — historischer Naming-Drift, kein Bug
-// App trägt Verantwortung für tenant-scoping in Queries + replay-idempotency.
-// pgTable bleibt source-of-truth für Query-API; Phase 4 leitet das pgTable
-// aus dieser Meta ab.
+// **Unmanaged table** — deliberately has no createEntity because:
+//   - id comes from the aggregate stream (no gen_random_uuid()-DEFAULT)
+//   - no version/inserted_by/modified_by/modified_at: no in-place edits or
+//     audit columns are needed (idempotent-on-replay via PK conflict)
+//   - created_at rather than inserted_at reflects historical naming drift, not
+//     a bug
+// The app is responsible for tenant scoping in queries and replay idempotency.
+// pgTable remains the source of truth for the query API; the pgTable is derived
+// from this metadata.
 export const deliveryAttemptsTableMeta = defineUnmanagedTable({
     tableName: "store_delivery_attempts",
     indexes: [{ name: DELIVERY_ATTEMPTS_TENANT_CREATED_INDEX, columns: ["tenant_id", "created_at"] }],

package/dist/delivery/unsubscribe.js

@@ -13,13 +13,13 @@ const localeClaimSchema = z
     .string()
     .regex(/^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$/)
     .optional();
-// Shape des verified-JWT-payloads. tenantId kommt als string aus jose und
-// wird NACH erfolgreichem parse() zur Branded TenantId — kein blind-cast.
+// Shape of verified JWT payloads. `tenantId` arrives from jose as a string and
+// becomes a branded `TenantId` only after successful `parse()`—never via a blind cast.
 //
 // `kind` is explicitly typed as "absent or undefined, nothing else" here
 // (not bare `.optional()`, which would also accept any other value on an
-// unrelated key) so an address-token payload — which always carries
-// `kind: "address"` — fails this schema instead of silently parsing with
+// unrelated key) so an address-token payload—which always carries
+// `kind: "address"`—fails this schema instead of silently parsing with
 // `addressHash` mistaken for a userId.
 const unsubscribeJwtPayloadSchema = z.object({
     kind: z.undefined().optional(),