@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

package/packages/bundled-features/src/custom-fields/wire-for-entity.ts

@@ -17,8 +17,7 @@ import type { CustomFieldClearedPayload, CustomFieldSetPayload } from "./events.
 import { createCustomFieldsFeature } from "./feature.ts";
 import { CUSTOM_FIELDS_EXTENSION, FIELD_DEFINITION_AGGREGATE_TYPE } from "./web/constants.ts";
 
-// Helper für entity-definitions — fügt eine `customFields jsonb`-Spalte
-// hinzu. Consumer:
+// Adds a `customFields jsonb` column to an entity definition.
 //
 //   const propertyEntity = createEntity({
 //     fields: {
@@ -27,57 +26,58 @@ import { CUSTOM_FIELDS_EXTENSION, FIELD_DEFINITION_AGGREGATE_TYPE } from "./web/
 //     },
 //   });
 //
-// Spec-Promise: customFields verhält sich wie Stammfelder. Default `{}`,
-// NOT NULL — analog zu embedded-Spalten.
+// `customFields` follows the same contract as regular fields: default `{}` and
+// NOT NULL, like embedded columns.
 // @wrapper-known semantic-alias
 export function customFieldsField(): JsonbFieldDef {
   return createJsonbField();
 }
 
-// Vollständige integration der custom-fields-Bundle für eine spezifische
-// host-entity. Eine einzige Aufruf-Stelle pro consumer registriert ALLE
-// wiring-Aspekte: extension-tracking, MSP für value-projection, rebuild-
-// replay via extendEntityProjection, postQuery-hook für API-flatten,
-// search-payload-extension für indexable customFields.
+// Complete integration of the custom-fields bundle for a specific host
+// entity. One call site per consumer registers all wiring aspects:
+// extension tracking, the value-projection MSP, rebuild replay via
+// extendEntityProjection, the postQuery hook for API flattening, and the
+// search-payload extension for indexable customFields.
 //
 // Consumer-side:
 //
 //   defineFeature("property-mgmt", (r) => {
-//     r.entity({ name: "property", ...propertyEntity });  // muss customFieldsField() haben
+//     r.entity({ name: "property", ...propertyEntity });  // must have customFieldsField()
 //     r.requires({ features: [CUSTOM_FIELDS_FEATURE_NAME] });
 //     wireCustomFieldsFor(r, "property", propertyTable);
 //   });
 //
-// Der `entityTable`-Parameter ist die Drizzle-Table-Instance (typically
-// `buildEntityTable(name, entity)`-Output). Die Closure über `entityTable`
-// erspart der MSP-apply-fn einen runtime-table-lookup über die Registry.
+// The `entityTable` parameter is the Drizzle table instance (typically the
+// output of `buildEntityTable(name, entity)`). Closing over `entityTable`
+// avoids a runtime table lookup through the registry in the MSP apply
+// function.
 //
-// **Was registriert wird**:
+// **What is registered**:
 //
-//   1. r.useExtension("customFields", entityName) — opt-in marker,
-//      ermöglicht boot-validation und usage-tracking via Registry.
+//   1. r.useExtension("customFields", entityName) — opt-in marker enabling
+//      boot validation and usage tracking through the registry.
 //
 //   2. r.multiStreamProjection — consumes customField.set/.cleared events
-//      die customer's set-custom-field / clear-custom-field write-handlers
-//      emittiert haben. Updated entityTable.customFields jsonb über
+//      emitted by the customer's set-custom-field / clear-custom-field write
+//      handlers. Updates entityTable.customFields jsonb through
 //      jsonb_set / jsonb-key-removal.
 //
-//   3. r.extendEntityProjection — hängt dieselben apply-Handler in die
-//      implicit projection der host-entity, damit rebuildProjection die
-//      customField-Events mit-replayt. Ohne das fällt customFields bei
-//      jedem Entity-Rebuild (Schema-Migration!) auf `{}` zurück (#759).
+//   3. r.extendEntityProjection — adds the same apply handlers to the host
+//      entity's implicit projection so rebuildProjection replays the
+//      customField events. Without this, customFields would reset to `{}` on
+//      every entity rebuild (for example, after a schema migration).
 //
-//   4. r.entityHook("postQuery", entity, flatten-fn) — bei JEDEM Read auf
-//      diese entity wird `row.customFields` jsonb auf root-level expanded
-//      damit die API-response wie Stammfelder aussieht.
+//   4. r.entityHook("postQuery", entity, flatten-fn) — on every read of
+//      this entity, expands `row.customFields` jsonb at the root level so
+//      the API response looks like it contains regular fields.
 //
-//   5. r.searchPayloadExtension(entity, contributor) — searchable
-//      customFields-keys werden flach ins Meilisearch-Index-Doc beigetragen
-//      (F3-wiring).
+//   5. r.searchPayloadExtension(entity, contributor) — contributes
+//      searchable customFields keys as flat fields in the Meilisearch index
+//      document.
 //
-//   6. fieldDefinition.deleted-Event-Handler im selben MSP — bei delete
-//      einer fieldDefinition werden orphan values aus allen entity-rows
-//      entfernt (key-removal pro fieldKey).
+//   6. fieldDefinition.deleted event handler in the same MSP — removes
+//      orphaned values from all entity rows when a fieldDefinition is deleted
+//      (one key removal per fieldKey).
 export function wireCustomFieldsFor<TReg extends FeatureRegistrar<string>>(
   r: TReg,
   entityName: string,
@@ -87,24 +87,24 @@ export function wireCustomFieldsFor<TReg extends FeatureRegistrar<string>>(
   r.useExtension(CUSTOM_FIELDS_EXTENSION, entityName);
 
   // Qualified event-type-names — sourced from typed EventDef.name handles
-  // (compile-time literal-typed, no Template-Literal-Drift à la toKebab-
-  // collapse-bug die T1 aufgedeckt hat).
+  // (compile-time literal-typed, no Template-Literal-Drift from the toKebab-
+  // collapse bug that exposed it).
   const setEventType = createCustomFieldsFeature().exports.setEvent.name;
   const clearedEventType = createCustomFieldsFeature().exports.clearedEvent.name;
   const fieldDefDeletedType = createCustomFieldsFeature().exports.fieldDefinitionDeletedEvent.name;
 
-  // Geteilte apply-Bodies: die MSP liefert sie live (async cursor), die
-  // entity-projection-extension replayt sie in rebuildProjection — gleiche
-  // SQL-Helper, beide idempotent. 2-Param-Signatur ist die gemeinsame
-  // Teilmenge von MultiStreamApplyFn und SingleStreamApplyFn.
+  // Shared apply bodies: the MSP supplies them live through an async cursor,
+  // while the entity-projection extension replays them in rebuildProjection.
+  // Both use the same idempotent SQL helpers. The two-parameter signature is
+  // the common subset of MultiStreamApplyFn and SingleStreamApplyFn.
   const applyCustomFieldSet = async (event: StoredEvent, tx: DbRunner): Promise<void> => {
-    // skip: feuert für ALLE aggregate-types die customField.set emittieren —
-    // wir wollen nur die unserer wired host-entity. Andere consumers haben
-    // eigene Wirings für ihre Entities.
+    // skip: fires for every aggregate type that emits customField.set, but only
+    // events for the wired host entity should be processed. Other consumers
+    // have their own wiring for their entities.
     if (event.aggregateType !== entityName) return;
     const payload = event.payload as CustomFieldSetPayload; // @cast-boundary engine-payload
 
-    // skip: a value-less customField.set is an anomaly since #972 (every set
+    // skip: a value-less customField.set is an anomaly (every set
     // carries its value; the sensitive self-projection path was removed) —
     // warn and leave the row untouched instead of binding undefined.
     if (payload.value === undefined) {
@@ -116,9 +116,9 @@ export function wireCustomFieldsFor<TReg extends FeatureRegistrar<string>>(
       return;
     }
 
-    // jsonb_set: setze key auf value. Wenn key noch nicht existiert →
-    // wird angelegt (create_missing=true ist default). value muss als
-    // jsonb-literal kommen.
+    // jsonb_set: assigns value to the key. If the key does not yet exist, it is
+    // created (`create_missing=true` is the default). value must be supplied
+    // as a jsonb literal.
     const tableName = extractTableName(entityTable, "custom-fields/wire-for-entity");
     await setCustomFieldValue(
       tx,
@@ -131,28 +131,27 @@ export function wireCustomFieldsFor<TReg extends FeatureRegistrar<string>>(
   };
 
   const applyCustomFieldCleared = async (event: StoredEvent, tx: DbRunner): Promise<void> => {
-    // skip: feuert für alle aggregate-types — nur unsere host-entity
-    // verarbeiten.
+    // skip: fires for all aggregate types; process only our host entity.
     if (event.aggregateType !== entityName) return;
     const payload = event.payload as CustomFieldClearedPayload; // @cast-boundary engine-payload
 
-    // jsonb minus operator (`-`) entfernt key aus jsonb-object.
+    // The jsonb minus operator (`-`) removes a key from a jsonb object.
     const tableName = extractTableName(entityTable, "custom-fields/wire-for-entity");
     await clearCustomFieldKey(tx, tableName, payload.fieldKey, event.aggregateId, event.tenantId);
   };
 
   const applyFieldDefinitionDeleted = async (event: StoredEvent, tx: DbRunner): Promise<void> => {
-    // fieldDefinition.deleted fires nur einmal pro fieldDef-delete
-    // (NICHT per-entity). Wir entfernen den key aus ALLEN rows der host-
-    // entity falls die deleted-fieldDef für diese entity galt.
+    // fieldDefinition.deleted fires once per field-definition deletion, not once
+    // per entity. Remove the key from all rows of the host entity if the
+    // deleted field definition belonged to this entity.
     const payload = event.payload as {
       entityName: string;
       fieldKey: string;
       tenantId?: TenantId;
     }; // @cast-boundary engine-payload
-    // skip: fieldDefinition.deleted feuert für ALLE fieldDefs cross-entity;
-    // nur wenn die deleted-fieldDef diese host-entity betraf, cleanen wir
-    // ihre Rows.
+    // skip: fieldDefinition.deleted fires for field definitions across all
+    // entities; clean rows only when the deleted definition belonged to this
+    // host entity.
     if (payload.entityName !== entityName) return;
 
     const tableName = extractTableName(entityTable, "custom-fields/wire-for-entity");
@@ -179,13 +178,12 @@ export function wireCustomFieldsFor<TReg extends FeatureRegistrar<string>>(
     },
   });
 
-  // Rebuild-wiring (#759): ohne das replayt rebuildProjection nur die
-  // entity-lifecycle-Events und resettet jede customFields-jsonb auf ihr
-  // Default `{}` — die Werte existieren ausschließlich als customField.set/
-  // .cleared-Events. set/cleared reiten auf dem HOST-entity-Stream
-  // (aggregateType = entityName, von source schon abgedeckt);
-  // fieldDefinition.deleted lebt auf dem "field-definition"-Stream und
-  // kommt deshalb als extra source dazu.
+  // Rebuild wiring: without it, rebuildProjection replays only entity
+  // lifecycle events and resets each customFields jsonb value to its default
+  // `{}`. The values exist only in customField.set/.cleared events. set/
+  // cleared events use the HOST entity stream (aggregateType = entityName,
+  // already covered by the source); fieldDefinition.deleted belongs to the
+  // "field-definition" stream and is therefore added as an extra source.
   r.extendEntityProjection(entityName, {
     sources: [FIELD_DEFINITION_AGGREGATE_TYPE],
     apply: {
@@ -195,8 +193,8 @@ export function wireCustomFieldsFor<TReg extends FeatureRegistrar<string>>(
     },
   });
 
-  // postQuery-hook: flatten row.customFields jsonb auf root-level der
-  // API-response. Spec-Promise Z.4 "indistinguishable von Stammfeldern".
+  // postQuery hook: expands row.customFields jsonb at the API response's root
+  // level so it is indistinguishable from regular fields.
   r.hook({
     type: "postQuery",
     target: { allOf: entityName },
@@ -214,11 +212,11 @@ export function wireCustomFieldsFor<TReg extends FeatureRegistrar<string>>(
     }),
   });
 
-  // Search-Payload-Extension: customFields-keys flach ins Index-Doc.
-  // Anders als postQuery-hook (der ALLE keys merged) trägt der Search-
-  // Contributor nur die als searchable=true definierten fields bei. v1
-  // ist conservatively: ALLES contribuieren — B2-follow-up filtert
-  // per fieldDefinition.searchable-flag.
+  // Search-payload extension: flattens customFields keys into the index
+  // document. Unlike the postQuery hook, which merges ALL keys, the search
+  // contributor should include only fields defined with searchable=true. The
+  // current version conservatively contributes everything; a later change
+  // will filter by the fieldDefinition.searchable flag.
   r.searchPayloadExtension(entityName, ({ state }) => {
     const customFields = state["customFields"];
     if (customFields && typeof customFields === "object" && !Array.isArray(customFields)) {

package/packages/bundled-features/src/custom-fields/wire-user-data-rights.ts

@@ -1,4 +1,4 @@
-// T1.5c — user-data-rights wiring for custom-fields.
+// User-data-rights wiring for custom-fields.
 
 import { type DbRunner, extractTableName } from "@cosmicdrift/kumiko-framework/db";
 import type { UserDataExportSnippet, UserDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";
@@ -28,7 +28,7 @@ function asCustomFieldsHostRow(value: unknown): CustomFieldsHostRow | null {
   return { id, customFields: Object.fromEntries(Object.entries(cf)) };
 }
 
-// fw#2914 — selectCustomFieldsHostRows runs raw SQL against a dynamic host
+// selectCustomFieldsHostRows runs raw SQL against a dynamic host
 // table name (opts.entityTable varies per call site), so it can't go through
 // TenantDb's typed method API (table param must be a known SchemaTable). The
 // SQL text itself still filters `tenant_id = ctx.tenantId`, so this stays a
@@ -64,7 +64,7 @@ async function exportCustomFields(
 }
 
 // Export-only wiring: custom fields hold supplemental business data, not PII
-// (#972) — there is nothing to redact on user-forget, only Art. 20 export.
+// — there is nothing to redact on user-forget, only Art. 20 export.
 export function wireCustomFieldsUserDataRightsFor<TReg extends FeatureRegistrar<string>>(
   r: TReg,
   opts: WireCustomFieldsUserDataRightsOptions,

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

@@ -1,6 +1,5 @@
-// Geteilter Override-Parser fuer policy-for-Query und resolve-for-tenant-
-// Helper. War vorher 1:1 in beiden Files dupliziert (Memory
-// `feedback_bulk_patterns` — Drift-Risiko bei Schema-Aenderungen).
+// Shared override parser for policy-for-Query and the resolve-for-tenant helper. It was
+// duplicated 1:1 in both files, so schema changes could make the copies drift.
 
 import { retentionOverrideSchema } from "../override-schema.ts";
 import type { RetentionOverride } from "../resolver.ts";

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

@@ -36,25 +36,18 @@ export {
   tenantRetentionOverrideTable,
 } from "./schema/tenant-retention-override.ts";
 
-// 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(): FeatureDefinition {
   return defineFeature("data-retention", (r) => {
     r.describe(
@@ -67,11 +60,11 @@ export function createDataRetentionFeature(): FeatureDefinition {
     });
     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/packages/bundled-features/src/data-retention/handlers/policy-for.query.ts

@@ -3,18 +3,18 @@ import * as z from "zod";
 import { resolveRetentionPolicyForTenant } from "../resolve-for-tenant.ts";
 import type { EffectiveRetentionPolicy } from "../resolver.ts";
 
-// 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/packages/bundled-features/src/data-retention/keep-for.ts

@@ -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";
 
@@ -29,17 +29,17 @@ export class InvalidKeepForError extends Error {
   }
 }
 
-// Re-export von Temporal.Instant als Type-Alias damit Caller den Type
-// nicht selbst aus globalThis ziehen muessen.
+// Re-export Temporal.Instant as a type alias so callers do not have to obtain
+// the type from globalThis themselves.
 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 function computeCutoff(spec: string, now: Instant): Instant {
   const match = KEEP_FOR_PATTERN.exec(spec);
@@ -61,8 +61,8 @@ export 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 function isPastCutoff(args: {
   readonly referenceTimestamp: Instant;

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