@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

package/packages/bundled-features/src/custom-fields/schemas.ts

@@ -1,7 +1,6 @@
 import * as z from "zod";
 import { SUPPORTED_FIELD_TYPES } from "./web/constants.ts";
 
-// Field-Type-Validator — pinnt valid type-Werte für fieldDefinition.
 export const fieldTypeSchema = z.enum(SUPPORTED_FIELD_TYPES);
 
 // Per-field access-control. When set, `set/clear-custom-field` handlers
@@ -9,8 +8,8 @@ export const fieldTypeSchema = z.enum(SUPPORTED_FIELD_TYPES);
 // in addition to the handler-level RBAC. Absent or empty `write` means
 // the handler-level RBAC is the only gate.
 //
-// `read` is reserved for the postQuery-flatten pipeline (T1.5c+); not
-// enforced in T1.5b.
+// `read` is reserved for the postQuery-flatten pipeline and is not
+// currently enforced.
 export const customFieldAccessSchema = z
   .object({
     read: z.array(z.string()).optional(),
@@ -19,11 +18,12 @@ export const customFieldAccessSchema = z
   .optional();
 export type CustomFieldAccess = z.infer<typeof customFieldAccessSchema>;
 
-// Serialized-field-jsonb — was als `serializedField`-Spalte gespeichert wird.
-// In v1 noch nicht strict-typed pro field-type (das kommt in B2 wenn die
-// Stammfeld-Builder-Schemas exposed sind). Hier nur die Struktur-Garantie.
+// Serialized-field JSONB: the value stored in the `serializedField` column.
+// In v1, it is not strictly typed per field type because the base-field
+// builder schemas are not yet exposed. This schema only guarantees the
+// overall structure.
 //
-// Schema-shape (Beispiel-Inputs für die unterschiedlichen Field-Types):
+// Schema shape (example inputs for the different field types):
 //
 //   text:     { type: "text", required: true, maxLength: 50 }
 //   number:   { type: "number", required: false, min: 0, max: 100 }
@@ -33,13 +33,13 @@ export type CustomFieldAccess = z.infer<typeof customFieldAccessSchema>;
 //   money:    { type: "money", required: false, currency: "EUR" }
 //   embedded: { type: "embedded", required: false, schema: { ... } }
 //
-// `fieldAccess` (T1.5b) is the structured key recognised by the handlers.
-// Everything else stays loose pending B2's per-type discriminated-union —
+// `fieldAccess` is the structured key recognised by the handlers.
+// Everything else remains loose pending per-type discriminated unions —
 // EXCEPT `sensitive`, which is explicitly rejected below: custom fields
-// carry supplemental business data only, PII support was removed (#972).
+// carry supplemental business data only, and PII support was removed.
 const serializedFieldBaseShape = {
   fieldAccess: customFieldAccessSchema,
-  // `retention` (T1.5d): per-field expiry. The retention-cron strips
+  // `retention`: per-field expiry. The retention-cron strips
   // values whose host-row `modified_at` is older than `keepFor`. Strategy
   // `delete` removes the key from the customFields jsonb; `anonymize`
   // sets it to `null` (key stays, value gone — preserves the schema
@@ -69,10 +69,10 @@ const updateSerializedFieldSchema = z
   .looseObject({ type: fieldTypeSchema.optional(), ...serializedFieldBaseShape })
   .refine(...rejectSensitive);
 
-// i18n-labels — `{ de: "...", en: "...", ... }`. Mindestens ein Eintrag.
+// i18n labels — `{ de: "...", en: "...", ... }`. At least one entry.
 const labelSchema = z.record(z.string().min(2).max(8), z.string().min(1));
 
-// Payload für `define-tenant-field` und `define-system-field` write-handler.
+// Payload for the `define-tenant-field` and `define-system-field` write handlers.
 export const defineFieldPayloadSchema = z.object({
   entityName: z.string().min(1).max(64),
   fieldKey: z
@@ -100,7 +100,7 @@ export const updateFieldPayloadSchema = defineFieldPayloadSchema.extend({
 });
 export type UpdateFieldPayload = z.infer<typeof updateFieldPayloadSchema>;
 
-// Payload für `delete-tenant-field` / `delete-system-field`.
+// Payload for `delete-tenant-field` / `delete-system-field`.
 export const deleteFieldPayloadSchema = z.object({
   entityName: z.string().min(1).max(64),
   fieldKey: z.string().min(1).max(64),

package/packages/bundled-features/src/custom-fields/web/client-plugin.tsx

@@ -1,8 +1,5 @@
-// Client-Feature-Factory für custom-fields. Wird vom App-Code in
-// createKumikoApp({ clientFeatures: [customFieldsClient()] }) eingehängt
-// und registriert die CustomFieldsFormSection unter dem Namen
-// CUSTOM_FIELDS_FORM_EXTENSION_NAME im ExtensionSectionsProvider. Apps
-// referenzieren den Namen im Screen-Schema:
+// Registers the custom-fields form section under
+// CUSTOM_FIELDS_FORM_EXTENSION_NAME so apps can reference it in their screen schema:
 //
 //   layout: { sections: [
 //     { kind: "extension", title: "...", contributesToFormSubmit: true, component: {

package/packages/bundled-features/src/custom-fields/web/constants.ts

@@ -56,8 +56,8 @@ export const CUSTOM_FIELDS_EXTENSION = "customFields";
 // every app user.
 export const DEFAULT_VALUE_WRITE_ROLES = ["TenantAdmin", "TenantMember"] as const;
 export const DEFAULT_FIELD_DEFINITION_LIST_ROLES = ["TenantAdmin"] as const;
-// Default-RBAC of the definition-CRUD triad (define-/update-/delete-tenant-field,
-// #2296). Apps with their own role vocabulary override via
+// Default-RBAC of the definition-CRUD triad (define-/update-/delete-tenant-field).
+// Apps with their own role vocabulary override via
 // createCustomFieldsFeature({ fieldDefinitionWriteRoles }) — otherwise those three
 // hard-wired handler QNs are access_denied for every app-user without a
 // "TenantAdmin" role (same Role-Naming-Drift as DEFAULT_VALUE_WRITE_ROLES above).

package/packages/bundled-features/src/custom-fields/web/custom-fields-form-section.tsx

@@ -1,13 +1,12 @@
-// CustomFieldsFormSection — extension-section component für entityEdit-
-// Screens. Lädt die fieldDefinition-Liste des Tenants, filtert auf die
-// host-Entity, rendert pro Definition einen typed Input, dispatched
-// `custom-fields:write:set-custom-field` pro non-empty Value beim Save.
+// CustomFieldsFormSection — extension-section component for entityEdit-
+// screens. Loads the tenant's fieldDefinition list, filters it to the
+// host entity, renders a typed input per definition, and dispatches
+// `custom-fields:write:set-custom-field` for each non-empty value on save.
 //
 // Mount via createKumikoApp({ clientFeatures: [customFieldsClient()] })
-// — der clientFeature-Factory registriert diese Component unter dem
-// Namen `CustomFieldsFormSection`, den die App im Screen-Schema via
-// `component: { react: { __component: CUSTOM_FIELDS_FORM_EXTENSION_NAME } }`
-// referenziert.
+// — the clientFeature factory registers this component under the name
+// `CustomFieldsFormSection`, which the app references in the screen schema
+// via `component: { react: { __component: CUSTOM_FIELDS_FORM_EXTENSION_NAME } }`.
 
 import {
   type ExtensionSubmitResult,
@@ -40,10 +39,10 @@ export function CustomFieldsFormSection({
 }: {
   readonly entityName: string;
   readonly entityId: string | null;
-  /** Bereits gespeicherte customField-Werte der Entity (aus der detail-
-   *  row durchgereicht). Ohne sie wäre die Section write-only — die Inputs
-   *  zeigen den Bestand beim Edit. `pending` trackt nur Änderungen, also
-   *  bleibt der Save-Button bis zur ersten Eingabe disabled. */
+  /** The entity's previously saved customField values, passed through from the
+   * detail row. Without them, the section would be write-only: the inputs
+   * would not show existing values while editing. `pending` tracks only
+   * changes, so the Save button remains disabled until the first edit. */
   readonly initialValues?: Readonly<Record<string, unknown>>;
 }): ReactNode {
   const { Banner, Button, Field, Input, Text } = usePrimitives();
@@ -58,11 +57,11 @@ export function CustomFieldsFormSection({
   const [saving, setSaving] = useState(false);
   const [errorKey, setErrorKey] = useState<string | null>(null);
 
-  // Vor den early-returns berechnet, weil useExtensionFormSubmit (Hook) davor
-  // laufen muss. matchingFields ist während des Loadings []; dirty bleibt dann
-  // false. Dirty = weicht vom GESPEICHERTEN Wert ab (nicht von ""), sonst ist
-  // das Leeren eines Bestandswerts unsichtbar und würde übersprungen statt
-  // gecleart.
+  // Computed before the early returns because useExtensionFormSubmit (a Hook)
+  // must run before them. matchingFields is [] while loading, so dirty remains
+  // false. Dirty means differing from the SAVED value (not from ""); otherwise
+  // clearing an existing value would be invisible and skipped instead of
+  // cleared.
   const matchingFields = (query.data?.rows ?? [])
     .filter((f) => f.entityName === entityName)
     .slice()
@@ -75,9 +74,10 @@ export function CustomFieldsFormSection({
   });
   const dirty = changedFields.length > 0;
 
-  // Schreibt alle geänderten Felder via set/clear. Genutzt vom composed-Submit
-  // (Haupt-Form ruft den Handler nach dem Entity-Write) UND vom standalone-
-  // Button (wenn die Section ohne umgebende composed-Form gemountet ist).
+  // Writes all changed fields via set/clear. Used by the composed submit
+  // (the main form calls the handler after the entity write) and by the
+  // standalone button when the section is mounted without a surrounding
+  // composed form.
   const flushChanges = async (targetEntityId: string): Promise<ExtensionSubmitResult> => {
     for (const field of changedFields) {
       const raw = pending[field.fieldKey] ?? "";
@@ -105,9 +105,9 @@ export function CustomFieldsFormSection({
     return { isSuccess: true };
   };
 
-  // composed = innerhalb eines entityEdit-Forms → kein eigener Save-Button,
-  // die Section schreibt beim Haupt-Save mit (Bug-Bash 3 #1). Außerhalb einer
-  // composed-Form (composed === false) bleibt der standalone-Button.
+  // composed = inside an entityEdit form, so there is no separate Save button;
+  // the section writes along with the main save. Outside a composed form
+  // (composed === false), the standalone button remains available.
   const composed = useExtensionFormSubmit({
     dirty,
     onSubmit: (ctx) => flushChanges(ctx.entityId),
@@ -236,9 +236,9 @@ function coerceValue(type: string, raw: string): unknown {
   return raw;
 }
 
-// Umkehrung von coerceValue: gespeicherter jsonb-Wert → string-Form für den
-// Input. number/boolean/date/text werden so dargestellt, wie der Input sie
-// erwartet; fehlende Werte werden zu "".
+// Inverse of coerceValue: converts a stored jsonb value to the string form
+// expected by the input. number/boolean/date/text are represented as their
+// inputs expect; missing values become "".
 function displayValue(type: string, value: unknown): string {
   if (value === undefined || value === null) return "";
   if (type === "boolean") return value === true ? "true" : "false";

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;