@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/data-retention/feature.js

@@ -10,25 +10,18 @@ export { resolveTenantRetentionPreset, } from "./resolve-tenant-preset.js";
 export { resolveRetentionPolicy, } from "./resolver.js";
 export { runRetentionCleanup, } from "./run-retention-cleanup.js";
 export { tenantRetentionOverrideEntity, tenantRetentionOverrideTable, } from "./schema/tenant-retention-override.js";
-// data-retention — automatisierte Aufbewahrung + Löschung pro Entity.
+// data-retention — automated retention and deletion per entity.
 //
-// Sprint 2.D1 (this commit):
-//   - 3-Schicht-Resolver (Entity-Default → Tenant-Preset → Tenant-Override)
-//   - Retention-Presets (dsgvo-basic, dsgvo-hgb, swiss-dsg, default)
-//   - tenantRetentionOverride-Entity für per-Tenant Edge-Cases
+// Retention is resolved through three layers: entity default → tenant preset →
+// tenant override stored in `tenantRetentionOverride`.
 //
-// Sprint 2.D2b (this commit):
-//   - retention-cleanup-Cron (perTenant) — hardDelete (batched) + softDelete
-//   - Layer-2-Preset aus dem Compliance-Profile abgeleitet (soft-dep)
-//   - anonymize deferred (Idempotenz-Marker, siehe run-retention-cleanup.ts)
+// The retention-cleanup cron performs batched hard deletes and soft deletes per
+// tenant. The tenant preset can be derived from the compliance profile, while
+// anonymization is deferred and uses an idempotency marker; see
+// `run-retention-cleanup.ts`.
 //
-// Sprint 2.D3 (done):
-//   - r.exposesApi("retention.policyFor") für user-data-rights
-//
-// Cross-Feature-Hinweis: Plan-Roadmap docs/plans/datenschutz/
-// core-data-retention.md — Forget-Flow konsultiert blockDelete via
-// retention.policyFor → anonymize statt hardDelete bei Aufbewahrungs-
-// pflicht. Das Wiring kommt in Sprint 2.U5.
+// The forget flow consults `retention.policyFor` and anonymizes records instead
+// of hard-deleting them while a mandatory retention period applies.
 export function createDataRetentionFeature() {
     return defineFeature("data-retention", (r) => {
         r.describe("Resolves the effective retention policy for any entity using a 3-layer stack: entity-level default \u2192 tenant preset (`dsgvo-basic`, `dsgvo-hgb`, `swiss-dsg`) \u2192 per-tenant override stored in `tenantRetentionOverride`. Other features query the resolved policy via the `retention.policyFor` cross-feature API \u2014 most notably `user-data-rights`, which uses it to decide whether to anonymize instead of hard-delete a record that is still within a mandatory retention window.");
@@ -38,10 +31,10 @@ export function createDataRetentionFeature() {
             recommended: false,
         });
         r.entity({ name: "tenant-retention-override", ...tenantRetentionOverrideEntity });
-        // S2.D3: Cross-Feature-API fuer Forget-Flow + Cleanup-Job
+        // Cross-feature API for the forget flow and cleanup job
         r.exposesApi("retention.policyFor");
         r.queryHandler(policyForQuery);
-        // S2.D2b — autonomous retention cleanup. perTenant fan-out (one run per
+        // Autonomous retention cleanup. perTenant fan-out (one run per
         // active tenant, like soft-delete-cleanup): runRetentionCleanup's raw
         // query helpers need the unfiltered runner, so the handler declares
         // escapeHatch and reaches for ctx.db.unsafeRaw(). Without this cron,

package/dist/data-retention/handlers/policy-for.query.js

@@ -1,18 +1,18 @@
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { resolveRetentionPolicyForTenant } from "../resolve-for-tenant.js";
-// retention:query:policy-for — Cross-Feature-API fuer den Forget-Flow.
+// retention:query:policy-for — Cross-feature API for the forget flow.
 //
-// user-data-rights-Sprint-2.U5 ruft das pro Entity um zu wissen ob ein
-// Forget mit "delete" oder "anonymize" oder "blockDelete-bis-Frist"
-// laufen soll. Plus Cleanup-Job-Sprint-2.D2b fuer das gleiche.
+// The forget flow calls this for each entity to determine whether it should
+// use "delete", "anonymize", or "blockDelete-bis-Frist". The cleanup job uses
+// it for the same purpose.
 //
 // Delegates to resolveRetentionPolicyForTenant so forget, the cleanup cron and
 // this query can never disagree about the tenant preset. Letting the resolver
 // load the preset itself costs one read per call, fine for a single lookup.
 //
-// access: openToAll — andere Features im selben Tenant duerfen das
-// abrufen. Keine PII im Result, nur Policy-Metadata.
+// access: openToAll — other features in the same tenant may retrieve this.
+// The result contains no PII, only policy metadata.
 export const policyForQuery = defineQueryHandler({
     name: "policy-for",
     schema: z.object({

package/dist/data-retention/keep-for.d.ts

@@ -4,17 +4,17 @@ export declare class InvalidKeepForError extends Error {
 }
 export type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 /**
- * Berechnet den Cutoff-Instant — Rows mit reference < cutoff sind
- * abgelaufen und werden vom Cleanup-Job geraeumt.
+ * Computes the cutoff instant — rows with reference < cutoff are expired
+ * and removed by the cleanup job.
  *
- * @param spec keepFor-String wie "30d", "10y", "6m", "1w", "24h"
- * @param now Aktueller Zeitpunkt (advisor-Pattern: injection-Parameter
- *            fuer Time-Travel-Tests, kein global Temporal.Now)
+ * @param spec keepFor string such as "30d", "10y", "6m", "1w", "24h"
+ * @param now Current point in time (injection parameter for time-travel tests;
+ *            not global Temporal.Now)
  */
 export declare function computeCutoff(spec: string, now: Instant): Instant;
 /**
- * Ist referenceTimestamp aelter als der keepFor-Cutoff bei now?
- * Cleanup-Job nutzt das pro Row.
+ * Determines whether referenceTimestamp is older than the keepFor cutoff at now.
+ * The cleanup job uses this for each row.
  */
 export declare function isPastCutoff(args: {
     readonly referenceTimestamp: Instant;

package/dist/data-retention/keep-for.js

@@ -1,14 +1,14 @@
-// keepFor-Format-Parser: "30d" / "10y" / "6m" / "1w" / "24h" → Cutoff-Instant.
+// keepFor format parser: "30d" / "10y" / "6m" / "1w" / "24h" → cutoff instant.
 //
-// Nicht millisekunden-praezise — DSGVO-Aufbewahrungspflichten haben
-// Tag-/Monat-Granularitaet. "6m" = 6×30d, "10y" = 10×365d. Cleanup-Job
-// laeuft taeglich, ein paar Tage Differenz beim Cutoff sind akzeptabel.
+// Not millisecond-precise — GDPR retention requirements use day/month
+// granularity. "6m" = 6×30d, "10y" = 10×365d. The cleanup job runs daily,
+// so a difference of a few days at the cutoff is acceptable.
 //
-// Boot-Validator (S0.2) hat das Format schon gegen /^\d+[hdwmy]$/
-// gecheckt — hier defensiv nochmal validiert fuer Migration-Edge-Cases.
+// The boot validator already checked the format against /^\d+[hdwmy]$/
+// — validate defensively again here for migration edge cases.
 //
-// Temporal kommt via globalThis (Polyfill in framework-Boot installiert).
-// `getTemporal()` aus framework/time gibt typed Zugriff.
+// Temporal is provided via globalThis (the polyfill is installed during framework boot).
+// `getTemporal()` from framework/time provides typed access.
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 const KEEP_FOR_PATTERN = /^(\d+)([hdwmy])$/;
 const UNIT_TO_DAYS = {
@@ -23,12 +23,12 @@ export class InvalidKeepForError extends Error {
     }
 }
 /**
- * Berechnet den Cutoff-Instant — Rows mit reference < cutoff sind
- * abgelaufen und werden vom Cleanup-Job geraeumt.
+ * Computes the cutoff instant — rows with reference < cutoff are expired
+ * and removed by the cleanup job.
  *
- * @param spec keepFor-String wie "30d", "10y", "6m", "1w", "24h"
- * @param now Aktueller Zeitpunkt (advisor-Pattern: injection-Parameter
- *            fuer Time-Travel-Tests, kein global Temporal.Now)
+ * @param spec keepFor string such as "30d", "10y", "6m", "1w", "24h"
+ * @param now Current point in time (injection parameter for time-travel tests;
+ *            not global Temporal.Now)
  */
 export function computeCutoff(spec, now) {
     const match = KEEP_FOR_PATTERN.exec(spec);
@@ -47,8 +47,8 @@ export function computeCutoff(spec, now) {
     return now.subtract({ hours: amount * daysFactor * 24 });
 }
 /**
- * Ist referenceTimestamp aelter als der keepFor-Cutoff bei now?
- * Cleanup-Job nutzt das pro Row.
+ * Determines whether referenceTimestamp is older than the keepFor cutoff at now.
+ * The cleanup job uses this for each row.
  */
 export function isPastCutoff(args) {
     const T = getTemporal();

package/dist/data-retention/override-schema.d.ts

@@ -1,9 +1,8 @@
 import * as z from "zod";
 /**
- * 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 declare const retentionOverrideSchema: z.ZodObject<{
     keepFor: z.ZodOptional<z.ZodString>;

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

@@ -1,25 +1,23 @@
-// 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";
 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/dist/data-retention/presets.d.ts

@@ -8,13 +8,12 @@ import type { RetentionDef } from "@cosmicdrift/kumiko-framework/engine";
 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 declare const RETENTION_PRESETS: 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 declare const SELECTABLE_RETENTION_PRESETS: readonly RetentionPresetKey[];

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>;