@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

package/packages/bundled-features/src/config/table.ts

@@ -3,19 +3,19 @@ import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/eng
 
 // Config values are event-sourced. Each (key, scope) is its own aggregate
 // stream — lifecycle events `configValue.created / .updated / .deleted`
-// flow through createEventStoreExecutor, which writes the stream + this
-// projection in one TX. Reads stay O(1) against the projection.
+// flow through createEventStoreExecutor, which writes the stream and this
+// projection in one TX. Reads remain O(1) against the projection.
 //
 // System-scope rows use SYSTEM_TENANT_ID (not null) — buildBaseColumns
-// (via buildEntityTable) forces tenant_id NOT NULL, so die pre-ES "NULL
-// means system" convention is replaced with a fixed sentinel. Der unique
-// index über (key, tenant_id, user_id) prevent duplicate writes at the DB
-// level — deklariert via entity.indexes.
+// (via buildEntityTable) forces tenant_id NOT NULL, so the pre-ES "NULL
+// means system" convention is replaced with a fixed sentinel. The unique
+// index on (key, tenant_id, user_id) prevents duplicate writes at the DB
+// level — declared via entity.indexes.
 //
-// Single-Source-of-Truth: `configValueEntity`. Die DB-Tabelle wird über
-// buildEntityTable aus der EntityDefinition abgeleitet, der unique-Index
-// ist via entity.indexes deklariert. Plural-Re-Export `configValuesTable`
-// dient handlers (`reset.write.ts` etc.) als typisierte Drizzle-Table-Ref.
+// Single source of truth: `configValueEntity`. The DB table is derived from
+// the EntityDefinition through buildEntityTable, and the unique index is
+// declared via entity.indexes. The plural re-export `configValuesTable`
+// provides handlers (`reset.write.ts` etc.) with a typed Drizzle table ref.
 export const configValueEntity = createEntity({
   table: "read_config_values",
   fields: {

package/packages/bundled-features/src/config/write-helpers.ts

@@ -226,7 +226,7 @@ export function resolveScopeIds(
 }
 
 // The subject a piiEncrypted config value is encrypted under, for the scope
-// actually written to (kumiko-platform#231/#459). Pure — no I/O — so a bug
+// actually written to. Pure — no I/O — so a bug
 // here (e.g. picking the writer's identity instead of the row's target,
 // see entity fields' explicit userOwned.ownerField for why that
 // distinction matters) is caught by a fast unit test, not only the DB-

package/packages/bundled-features/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -112,7 +112,7 @@ function subjectAggregateId(raw: SubjectIdInput): string {
 }
 
 // The record subject names its own entity — resolve it against the registry
-// instead of trusting the payload straight into resolveTableName/SQL (#2786).
+// instead of trusting the payload straight into resolveTableName/SQL.
 function findRegisteredEntity(
   features: ReadonlyMap<string, FeatureDefinition>,
   entityName: string,
@@ -124,7 +124,7 @@ function findRegisteredEntity(
   return undefined;
 }
 
-// Tenant-scope guard (mh#349): DataProtectionOfficer is a tenant-scoped role,
+// Tenant-scope guard: DataProtectionOfficer is a tenant-scoped role,
 // but the handler otherwise erases ANY subject cross-tenant on a raw
 // (un-scoped) client — a Tenant-A DPO who learns a Tenant-B subject id
 // (export, support ticket, log line) could destroy it. SystemAdmin
@@ -182,7 +182,7 @@ async function resolveTenantScopeDenial(
   return ownedInTenant ? undefined : memberDenied;
 }
 
-// fw#2789/#2805: blockDelete (legally mandated physical retention, e.g.
+// blockDelete (legally mandated physical retention, e.g.
 // ledger/invoice text) means this command must refuse, not silently
 // anonymize or proceed. Refused when the host entity itself declares
 // blockDelete OR the owning tenant's effective data-retention policy
@@ -213,7 +213,7 @@ async function resolveRetentionDenial(
   const effective = await resolveRetentionPolicyForTenant({
     db: runner,
     registry: ctx.registry,
-    tenantId: owningTenantId as TenantId,
+    tenantId: owningTenantId,
     entityName: raw.entity,
   });
   return effective.policy?.strategy === "blockDelete" ? deny() : undefined;
@@ -241,8 +241,8 @@ function denialReasonOf(failure: WriteFailure): string {
   return failure.error.code;
 }
 
-// Denied cross-tenant probes must still leave an audit trail (fw#2348).
-// Appended outside the handler tx (fw#2592): the caller's
+// Denied cross-tenant probes must still leave an audit trail.
+// Appended outside the handler tx: the caller's
 // `return tenantScopeDenial` rolls that tx back.
 async function appendDenialAuditEvent(
   ctx: HandlerContext,
@@ -285,7 +285,7 @@ async function appendDenialAuditEvent(
       registry: ctx.registry,
       db: denialAuditRunner,
       // MUST be event.user.tenantId, never SYSTEM_TENANT_ID — unsafeRaw
-      // bypasses TenantDb's scoping, so this is the only guard against a cross-tenant denial event (fw#2452).
+      // bypasses TenantDb's scoping, so this is the only guard against a cross-tenant denial event.
       tenantId: event.user.tenantId,
       userId: String(event.user.id),
       callSiteLabel: "forget-subject denial audit",
@@ -339,11 +339,11 @@ async function sweepDerivedSubjectData(
   };
 
   await runStep(async (crossTenantSubjectRunner) => {
-    // Blind-index sweep (#818): nulls bidx columns now so the deterministic
+    // Blind-index sweep: nulls bidx columns now so the deterministic
     // HMAC doesn't stay equality-matchable; raw because the ciphertext prefix addresses the subject across tenants.
     await nullBlindIndexesForSubject(crossTenantSubjectRunner, ctx.registry.features, subjectKey);
 
-    // Derived search index still holds plaintext (#1610) — purge next to the
+    // Derived search index still holds plaintext — purge next to the
     // blind-index sweep. No adapter → no-op (apps without search).
     if (ctx.searchAdapter) {
       await purgeSearchDocumentsForSubject(
@@ -442,7 +442,8 @@ async function appendSubjectForgotten(
       {
         registry: ctx.registry,
         db: outsideRunner,
-        // MUST be event.user.tenantId, never SYSTEM_TENANT_ID — unsafeRaw bypasses TenantDb's scoping (fw#2452).
+        // MUST be event.user.tenantId, never SYSTEM_TENANT_ID — unsafeRaw bypasses TenantDb's
+        // scoping.
         tenantId: event.user.tenantId,
         userId: String(event.user.id),
         callSiteLabel: "forget-subject audit",
@@ -466,7 +467,7 @@ async function appendSubjectForgotten(
 // The automated Art.-17 path (user-data-rights forget-cleanup) calls
 // kms.eraseKey directly inside its per-user sub-tx; this command is the
 // standalone trigger for cases outside that pipeline (authority requests,
-// tenant-destroy in Sprint 5, operator recovery).
+// tenant-destroy, operator recovery).
 export const forgetSubjectWrite = defineWriteHandler({
   name: "forget-subject",
   schema: forgetSubjectSchema,
@@ -558,7 +559,7 @@ export const forgetSubjectWrite = defineWriteHandler({
     // callable. Mirror of the automated Art.-17 path (userDeleteHook:
     // status=Deleted; apiTokenDeleteHook: revoke):
     //   - user.updated as lifecycle event (updateUserLifecycle), so a
-    //     read_users rebuild doesn't wipe the flip (#494)
+    //     read_users rebuild doesn't wipe the flip
     //   - sessions don't need active revocation — session-callbacks
     //     re-validate user.status on every request (isPrincipalBlocked
     //     blocks Deleted).

package/packages/bundled-features/src/custom-fields/aggregate-id.ts

@@ -1,28 +1,27 @@
 import { v5 as uuidv5 } from "uuid";
 
-// Fixed UUID-namespace für custom-field-definition aggregate-id-Ableitung.
-// Generiert einmalig (2026-05-22), in Stein gemeißelt: ein Wechsel würde
-// jeden existing fieldDefinition-Stream re-keyen → kaputter event-replay,
-// kaputte definition-history. Drift-Pin in __tests__/drift.test.ts.
+// Fixed UUID namespace for deriving custom-field definition aggregate IDs.
+// Generated once; changing it would re-key every existing fieldDefinition stream,
+// breaking event replay and definition history. Drift is pinned in
+// __tests__/drift.test.ts.
 const FIELD_DEFINITION_NAMESPACE = "f1d3b2c7-4e5a-4b9c-8d1f-2a3b4c5d6e7f";
 
 /**
- * Deterministic aggregate-id für ein fieldDefinition-Aggregate aus dem
- * Tripel (tenantId, entityName, fieldKey). Pro (Tenant|System, Entity,
- * FieldKey) existiert genau ein Aggregate.
+ * Deterministic aggregate ID for a fieldDefinition aggregate from the tuple
+ * (tenantId, entityName, fieldKey). Exactly one aggregate exists per
+ * (Tenant|System, Entity, FieldKey).
  *
- * **Scope-Semantik:**
- *   - System-Scope: `tenantId = SYSTEM_TENANT_ID` → die fieldDefinition
- *     gilt für alle Tenants (vendor-defined).
- *   - Tenant-Scope: `tenantId = <tenant-uuid>` → pro Tenant eigene
+ * **Scope semantics:**
+ *   - System scope: `tenantId = SYSTEM_TENANT_ID` → the fieldDefinition applies
+ *     to all tenants (vendor-defined).
+ *   - Tenant scope: `tenantId = <tenant-uuid>` → each tenant has its own
  *     fieldDefinition.
  *
- * **Conflict-Rule** (durchgesetzt im write-handler, NICHT via DB-constraint):
- *   Pro (entityName, fieldKey) darf nur EINE Definition existieren — entweder
- *   system oder tenant, nicht beide. Wenn system `customer.internalNumber`
- *   definiert, kann Tenant kein eigenes `customer.internalNumber` mehr
- *   definieren (422 `fieldKey_conflict`). Verhindert Resolution-Ambiguität
- *   beim Read.
+ * **Conflict rule** (enforced in the write handler, NOT via a DB constraint):
+ *   Only ONE definition may exist per (entityName, fieldKey)—system or tenant,
+ *   but not both. If system defines `customer.internalNumber`, a tenant cannot
+ *   define its own `customer.internalNumber` (422 `fieldKey_conflict`). This
+ *   prevents ambiguity when resolving the field during reads.
  */
 // @wrapper-known uuid-domain
 export function fieldDefinitionAggregateId(

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

@@ -5,35 +5,36 @@ import {
   createTextField,
 } from "@cosmicdrift/kumiko-framework/engine";
 
-// fieldDefinition — Tenant- oder System-scoped Custom-Field-Definition.
+// fieldDefinition — Tenant- or system-scoped custom-field definition.
 //
-// **Tenant-Scope:** `tenantId`-Base-Column wird vom Framework automatisch
-// gesetzt. Bei system-scope-Definitionen ist `tenantId = SYSTEM_TENANT_ID`;
-// bei tenant-scope der current-tenant. Beide leben in derselben Tabelle,
-// Scope ergibt sich aus dem tenantId-Wert (no separate `scope`-column).
+// **Tenant scope:** The `tenantId` base column is set automatically by the
+// framework. For system-scope definitions, `tenantId = SYSTEM_TENANT_ID`;
+// for tenant-scope definitions, it is the current tenant. Both use the same
+// table; the scope is determined by the tenantId value (no separate `scope`
+// column).
 //
-// **Conflict-Rule:** pro (entityName, fieldKey) darf nur eine Definition
-// existieren — entweder system oder tenant, nicht beide. Resolution beim
-// Read = `WHERE tenantId IN (SYSTEM_TENANT_ID, <current-tenant>)`.
-// Conflict-Check ist write-handler-side, NICHT DB-constraint (DB hat
-// natürliche UNIQUE auf (tenantId, entityName, fieldKey) durch Aggregate-
-// ID-Konstruktion).
+// **Conflict rule:** only one definition may exist per (entityName, fieldKey)
+// — either system or tenant, not both. Resolution on read = `WHERE tenantId IN
+// (SYSTEM_TENANT_ID, <current-tenant>)`. The conflict check is performed by
+// the write handler, NOT enforced by a DB constraint (the DB has a natural
+// UNIQUE constraint on (tenantId, entityName, fieldKey) through aggregate-ID
+// construction).
 //
-// **Spec-Drift**: Spec Z.40-54 hat eine separate `custom_field_value`-
-// Tabelle. Plan-Doc v2 hat das durch jsonb-on-host-entity ersetzt
-// (D2-pur-Storage). Hier definieren wir NUR die definition-Entity; values
-// landen in `read_<entity>.customFields` jsonb via MSP (B2).
+// **Spec drift**: Spec Z.40-54 defines a separate `custom_field_value` table.
+// Plan-Doc v2 replaced it with jsonb on the host entity (pure jsonb storage).
+// This defines ONLY the definition entity; values land in
+// `read_<entity>.customFields` jsonb via MSP.
 //
-// **Was hier NICHT als Stammfeld-Spalte landet**:
-//   - `defaultValue`, `options`, `fieldAccess`, `label` — alles in
-//     `serializedField` jsonb gepackt (Builder-Reuse: dehydrierter
-//     r.field.X()-Output). Spec Z.18-38 listet sie als separate Spalten,
-//     aber Builder-Reuse macht das redundant — der serialized Builder
-//     enthält alle diese Aspekte type-safe.
-//   - `version` (optimistic-lock) — ES-redundant, wir nutzen aggregate-
-//     stream-version (Sprint E-Pattern).
-//   - `createdAt/updatedAt/createdBy/updatedBy` — automatic via base-
-//     columns + events.
+// **What is NOT stored as a base-field column here**:
+//   - `defaultValue`, `options`, `fieldAccess`, `label` — all packed into
+//     `serializedField` jsonb (builder reuse: dehydrated
+//     r.field.X()-output). Spec Z.18-38 lists them as separate columns, but
+//     builder reuse makes that redundant — the serialized builder contains all
+//     these aspects in a type-safe form.
+//   - `version` (optimistic lock) — redundant with event sourcing; we use the
+//     aggregate stream version.
+//   - `createdAt/updatedAt/createdBy/updatedBy` — automatic through base
+//     columns and events.
 export const fieldDefinitionEntity = createEntity({
   table: "read_custom_field_definitions",
   description:
@@ -47,20 +48,21 @@ export const fieldDefinitionEntity = createEntity({
   // NB: `retention.strategy` below is the data-retention purge policy, a
   // SEPARATE knob from this executor flag — it does not drive executor.delete.
   softDelete: true,
-  // B1.5 retention-policy — fieldDefinitions sind tenant-Schema-Metadaten,
-  // keine PII-Daten. Lange Retention für Audit (Compliance kann "wann hat
-  // Tenant das Feld definiert / geändert / gelöscht" fragen).
+  // Retention policy — field definitions are tenant-schema metadata, not PII.
+  // Long retention supports audits (compliance can ask when a tenant defined,
+  // changed, or deleted the field).
   //
-  // 10-Jahre keepFor ist konservativer Default; per-Tenant kann via
-  // tenantRetentionOverride für eigene Edge-Cases gesetzt werden
-  // (z.B. shorter für test-tenants).
+  // The 10-year keepFor is a conservative default; tenants can override it
+  // through tenantRetentionOverride for their own edge cases
+  // (e.g. shorter retention for test tenants).
   retention: {
     keepFor: "10y",
     strategy: "softDelete",
   },
   fields: {
-    // Ziel-Entity-Name, für die dieses Field definiert wird (z.B. "property",
-    // "customer"). Max 64 char passt zu Kumiko's entity-name-Convention.
+    // The entity name for which this field is defined (e.g. "property",
+    // "customer"). The 64-character maximum follows Kumiko's entity-name
+    // convention.
     entityName: createTextField({
       required: true,
       maxLength: 64,
@@ -68,8 +70,8 @@ export const fieldDefinitionEntity = createEntity({
       reason: "technical_reference",
     }),
 
-    // Field-Key (z.B. "internalNumber", "vipFlag") — kebab-case oder camelCase
-    // erlaubt; UI-rendering nutzt label statt fieldKey.
+    // Field key (e.g. "internalNumber", "vipFlag") — kebab-case and camelCase
+    // are allowed; UI rendering uses label instead of fieldKey.
     fieldKey: createTextField({
       required: true,
       maxLength: 64,
@@ -77,8 +79,8 @@ export const fieldDefinitionEntity = createEntity({
       reason: "technical_reference",
     }),
 
-    // Field-Type aus dem SUPPORTED_FIELD_TYPES-Set. Validiert via Zod im
-    // write-handler.
+    // Field type from the SUPPORTED_FIELD_TYPES set. Validated with Zod in the
+    // write handler.
     type: createTextField({
       required: true,
       maxLength: 16,
@@ -86,22 +88,22 @@ export const fieldDefinitionEntity = createEntity({
       reason: "technical_reference",
     }),
 
-    // Required-Flag — wird beim Entity-Write gegen den value gecheckt
-    // (Stammfeld-identische Semantik, Spec-Promise Z.4).
+    // Required flag — checked against the value during entity writes
+    // (the same semantics as a base field).
     required: createBooleanField({ required: true }),
 
-    // Searchable-Flag — wenn true, contribuiert das Field zum Search-Doc
-    // via F3 search-payload-extension.
+    // Searchable flag — when true, the field contributes to the search document
+    // through the search-payload extension.
     searchable: createBooleanField({ required: true }),
 
-    // UI-Display-Order. Tenant kann seine Felder via UI sortieren.
+    // UI display order, allowing tenants to sort their fields in the UI.
     displayOrder: createNumberField({ required: true, integer: true }),
 
-    // Builder-Reuse: serialisierter r.field.X(opts)-Output als jsonb.
-    // Beinhaltet type-options (enum-values, money-currency, embedded-schema),
-    // defaultValue, fieldAccess, i18n-labels. Beim Write-Validation
-    // dehydriert der handler dies zurück zu einer r.field.X()-Instanz und
-    // nutzt deren .schema für value-Validation.
+    // Builder reuse: serialized r.field.X(opts) output stored as jsonb.
+    // It includes type options (enum values, money currency, embedded schema),
+    // defaultValue, fieldAccess, and i18n labels. During write validation, the
+    // handler dehydrates this back into an r.field.X() instance and uses its
+    // .schema for value validation.
     serializedField: createTextField({
       required: true,
       maxLength: 65536,

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

@@ -1,17 +1,16 @@
 import * as z from "zod";
 
-// Domain-Events für custom-field-VALUES. customField.set + .cleared leben
-// auf der host-aggregate stream (Plan-Doc v2 ES-Option-B: customField-Events
-// auf demselben Stream wie die host-entity's eigene Events).
+// Domain events for custom-field values. customField.set and .cleared live
+// on the host aggregate stream, alongside the host entity's own events.
 //
-// Aggregate-Type im Event ist der host-entity-name (z.B. "property"),
-// aggregate-id ist die host-entity-row-id (z.B. property-uuid). So konsumieren
-// die customFields-MSPs nur die Events ihrer wired-entities (filtered via
-// aggregate-type-match an der jeweiligen consumer-side-MSP-Registration).
+// The event's aggregate type is the host entity name (for example, "property"),
+// and its aggregate ID is the host entity row ID (for example, property-uuid).
+// This ensures customFields-MSPs consume only events for their wired entities,
+// filtered by aggregate-type match in each consumer-side-MSP registration.
 
 export const customFieldSetSchema = z.object({
   fieldKey: z.string().min(1).max(64),
-  // Every set carries its value (custom fields hold no PII, #972) — replay
+  // Every set carries its value (custom fields hold no PII) — replay
   // reproduces the projection fully. Stays optional at the type layer only
   // because z.unknown() is inherently optional; the apply side treats
   // `value === undefined` as an anomaly and warns.

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

@@ -1,50 +1,49 @@
-// custom-fields — Tenant- + System-scoped Custom-Field-Definitions +
-// generische Custom-Field-VALUE write-handler (host-stream-events).
+// custom-fields — tenant- and system-scoped custom-field definitions plus
+// generic custom-field value write-handlers (host-stream events).
 //
-// **Scope: supplemental business data, NO PII (#972).** Custom fields sind
-// für tenant-spezifische Zusatzinfos (Referenznummern, Flags, Kategorien) —
-// nicht für personenbezogene Daten. Das frühere `sensitive`-Flag wurde
-// entfernt; das Schema rejected es und `parseSerializedField` wirft auf
-// Alt-Definitionen. Werte stehen vollständig im Event-Log (rebuild-safe).
+// **Scope: supplemental business data, NO PII.** Custom fields are for
+// tenant-specific additional data (reference numbers, flags, categories),
+// not personally identifiable information. The former `sensitive` flag was
+// removed; the schema rejects it and `parseSerializedField` throws for legacy
+// definitions. Values are stored entirely in the event log (rebuild-safe).
 // PII belongs in schema-entity fields with a `personal` annotation
 // (crypto-shredding, event ciphertext, forget pipeline).
 //
-// **Was diese Feature liefert (B1 + B2, 2026-05-23):**
-//   1. r.entity({ name: "field-definition" }) — Definition-Storage (event-sourced).
-//   2. define-tenant-field / define-system-field — RBAC write-handlers für
-//      Definition-CRUD.
+// **This feature provides:**
+//   1. r.entity({ name: "field-definition" }) — event-sourced definition storage.
+//   2. define-tenant-field / define-system-field — RBAC write-handlers for
+//      definition CRUD.
 //   3. delete-tenant-field / delete-system-field — RBAC write-handlers.
-//   3b. update-tenant-field — Vollersatz-Edit (Bug-Bash D2); type immutable.
-//   4. set-custom-field / clear-custom-field — write-handlers für VALUES.
-//      Emittieren customField.set/.cleared-Events auf host-aggregate-stream.
-//   5. r.defineEvent für customField.set/.cleared + fieldDefinition.deleted.
-//   6. r.extendsRegistrar("customFields") — registriert die extension-name
-//      damit consumer via r.useExtension("customFields", "<entity>") opt-in.
-//   7. defineEntityListHandler — read fieldDefinitions (B1-limit: nur tenant-
-//      scope; B2-todo: system+tenant UNION als custom query).
+//   3b. update-tenant-field — full-replacement edit; type is immutable.
+//   4. set-custom-field / clear-custom-field — write-handlers for VALUES.
+//      They emit customField.set/.cleared events on the host aggregate stream.
+//   5. r.defineEvent for customField.set/.cleared + fieldDefinition.deleted.
+//   6. r.extendsRegistrar("customFields") — registers the extension name so
+//      consumers can opt in via r.useExtension("customFields", "<entity>").
+//   7. defineEntityListHandler — reads fieldDefinitions (currently tenant-
+//      scoped; a system+tenant UNION requires a custom query).
 //
-// **Consumer-side-Wiring** (siehe wire-for-entity.ts):
-//   Consumer ruft `wireCustomFieldsFor(r, entityName, entityTable)` auf —
-//   das registriert pro host-entity: useExtension + MSP (jsonb-projection)
-//   + postQuery-hook (flatten) + search-payload-extension.
+// **Consumer-side wiring** (see wire-for-entity.ts):
+//   The consumer calls `wireCustomFieldsFor(r, entityName, entityTable)`,
+//   which registers per host entity: useExtension + MSP (JSONB projection)
+//   + postQuery hook (flattening) + search-payload extension.
 //
-// **Host-Entity-Requirement**:
-//   Consumer MUSS in der entity-definition eine `customFields`-Spalte als
-//   `customFieldsField()` (jsonb) deklarieren.
+// **Host-entity requirement**:
+//   The consumer MUST declare a `customFields` column as
+//   `customFieldsField()` (JSONB) in the entity definition.
 //
-// **Exports-Pattern (2026-05-23 refactor)**:
+// **Exports pattern**:
 //   `createCustomFieldsFeature().exports.{setEvent,clearedEvent,fieldDefinitionDeletedEvent}`
-//   liefern typed EventDef-handles. Handler + wire-for-entity nutzen
-//   `<event>.name` als compile-time-literal-typed qualified-string — keine
-//   hand-gebauten Template-Literals mehr (T1 hat den toKebab-collapse-drift
-//   aufgedeckt, siehe Memory feedback_event_def_exports_pattern).
+//   provides typed EventDef handles. Handlers and wire-for-entity use
+//   `<event>.name` as a compile-time literal-typed qualified string instead of
+//   hand-built template literals, which drifted from the real names once
+//   toKebab collapsed them.
 //
-// **Noch offen (future iterations)**:
-//   - Cross-scope-conflict-Detection (Tenant überschreibt system fieldKey)
-//   - Cross-Scope-Read-UNION (system + tenant fieldDefinitions in einem List)
-//   (cap-counter-quota → T1.5e, user-data-rights-anonymization → T1.5c,
-//    Value-Validation gegen serializedField → set-custom-field via fieldToZod —
-//    alle erledigt.)
+// **Still open:**
+//   - Cross-scope conflict detection (a tenant overriding a system fieldKey)
+//   - Cross-scope read UNION (system + tenant fieldDefinitions in one list)
+//   (cap-counter quota, user-data-rights anonymization, and value validation
+//   against serializedField via fieldToZod in set-custom-field are complete.)
 
 import {
   defineEntityListHandler,
@@ -97,10 +96,9 @@ const fieldDefinitionDeletedSchema = z.object({
   tenantId: z.string().optional(),
 });
 
-// Handler-/Access-Varianten die zwischen Singleton und Options-Variante
-// differieren können. Alles andere registriert registerCustomFields für
-// beide identisch, damit ein neues Event/Handler nie still die
-// Options-Variante verfehlt.
+// Handler and access variants can differ between the singleton and options
+// variant. Everything else registers identically through registerCustomFields
+// so a new event or handler cannot silently be omitted from the options variant.
 type RegisterVariant = {
   readonly defineTenantHandler: WriteHandlerDef;
   readonly updateTenantHandler: WriteHandlerDef;
@@ -125,9 +123,9 @@ function registerCustomFields(
   });
   r.entity({ name: "field-definition", ...fieldDefinitionEntity });
 
-  // Event-types — qualified als "custom-fields:event:<short-name>".
-  // Returned EventDefs liefern .name als compile-time literal-typed string,
-  // den Handler + MSP-keys konsumieren statt Template-Literal-Konstruktion.
+  // Event types — qualified as "custom-fields:event:<short-name>".
+  // Returned EventDefs expose .name as a compile-time literal-typed string,
+  // which handlers and MSP keys consume instead of constructing template literals.
   // `value: z.unknown()` has no field-level schema to catalog under piiFields
   // (event PII covers string fields only), so "no PII" is a convention here,
   // not an enforced guarantee.
@@ -143,31 +141,31 @@ function registerCustomFields(
     { piiFields: "none" },
   );
 
-  // Extension-Registrar — registriert dass diese Extension existiert.
-  // Consumer-side: r.useExtension("customFields", "<entity>") MARKIERT
-  // opt-in, aber wired NICHTS automatisch. Consumer MUSS zusätzlich
-  // `wireCustomFieldsFor(r, entity, table)` aufrufen damit MSP +
-  // postQuery-hook + search-extension tatsächlich registriert werden.
-  // Empty-options-Pattern (`{}`) ist absichtlich — boot-time-onRegister-
-  // wiring würde Closure über Drizzle-Table benötigen, die der Consumer
-  // bei extendsRegistrar-Registration nicht kennt. Daher consumer-side
-  // explicit-wiring statt magic-auto-wiring.
+  // Registers that this extension exists.
+  // Consumer-side: r.useExtension("customFields", "<entity>") marks opt-in,
+  // but does not wire anything automatically. The consumer MUST also call
+  // `wireCustomFieldsFor(r, entity, table)` to register the MSP, postQuery hook,
+  // and search extension.
+  // The empty-options pattern (`{}`) is intentional: boot-time onRegister
+  // wiring would require a closure over the Drizzle table, which the consumer
+  // does not provide during extendsRegistrar registration. Explicit consumer-
+  // side wiring therefore avoids implicit magic.
   r.extendsRegistrar(CUSTOM_FIELDS_EXTENSION, {});
 
-  // Definition-CRUD handlers (B1; update kam mit Bug-Bash D2 2026-06-08).
+  // Definition CRUD handlers.
   r.writeHandler(variant.defineTenantHandler);
   r.writeHandler(defineSystemFieldHandler);
   r.writeHandler(variant.updateTenantHandler);
   r.writeHandler(variant.deleteTenantHandler);
   r.writeHandler(deleteSystemFieldHandler);
 
-  // Value-write handlers (B2). Emittieren events auf host-aggregate-stream.
+  // Value write handlers. They emit events on the host aggregate stream.
   r.writeHandler(variant.setHandler);
   r.writeHandler(variant.clearHandler);
 
-  // List-Query — tenant-scoped (B1-limit). Die CustomFieldsFormSection
-  // dispatcht diesen QN hart — Apps mit eigenem Rollen-Vokabular
-  // überschreiben die Rollen via fieldDefinitionListRoles.
+  // The list query is tenant-scoped. CustomFieldsFormSection dispatches this
+  // query name directly, so apps with their own role vocabulary must override
+  // the roles through fieldDefinitionListRoles.
   r.queryHandler(
     defineEntityListHandler("field-definition", fieldDefinitionEntity, {
       access: { roles: variant.fieldDefinitionListRoles },
@@ -193,24 +191,24 @@ const defaultCustomFieldsFeature = defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r)
 );
 
 export type CustomFieldsFeatureOptions = {
-  /** T1.5e: Quota für define-tenant-field. */
+  /** Quota for define-tenant-field. */
   readonly fieldDefinitionLimitPerTenant?: number;
-  /** Rollen für set-/clear-custom-field — die Save-Pfade der
-   *  CustomFieldsFormSection. Default ["TenantAdmin","TenantMember"];
-   *  Apps mit eigenem Rollen-Vokabular (z.B. ["Admin","Editor"]) MÜSSEN
-   *  das setzen, sonst ist der Value-Save für jeden App-User
-   *  access_denied (Role-Naming-Drift). */
+  /** Roles for set-/clear-custom-field, used by the save paths in
+   * CustomFieldsFormSection. Default ["TenantAdmin","TenantMember"];
+   * apps with their own role vocabulary (for example ["Admin","Editor"])
+   * MUST set this, otherwise value saving is access_denied for every app user
+   * (role-naming drift). */
   readonly valueWriteRoles?: readonly string[];
-  /** Rollen für custom-fields:query:field-definition:list — der Lade-Pfad
-   *  der CustomFieldsFormSection. Default ["TenantAdmin"]. Wird valueWriteRoles
-   *  gesetzt, dies aber NICHT, erben die Value-Rollen hier hinein (Union mit
-   *  dem Default, damit Admins den List-Zugriff behalten) — sonst lädt die
-   *  FormSection für Value-Writer nie (access_denied), während der Save-Pfad
-   *  offen wäre (asymmetrischer Bruch). */
+  /** Roles for custom-fields:query:field-definition:list, used by the loading
+   * path in CustomFieldsFormSection. Default ["TenantAdmin"]. If
+   * valueWriteRoles is set but this is not, the value roles are inherited here
+   * (unioned with the default so admins retain list access); otherwise the
+   * FormSection cannot load for value writers (access_denied) while the save
+   * path remains open (an asymmetric break). */
   readonly fieldDefinitionListRoles?: readonly string[];
   /** Access roles for the definition-CRUD triad (`define-tenant-field`,
-   *  `update-tenant-field`, `delete-tenant-field`) — hard-wired to ["TenantAdmin"]
-   *  before #2296. Apps with their own role vocabulary (e.g. ["Admin","Editor"])
+   *  `update-tenant-field`, `delete-tenant-field`) — hard-wired to ["TenantAdmin"].
+   *  Apps with their own role vocabulary (e.g. ["Admin","Editor"])
    *  MUST set this, else field-definition management is access_denied for every
    *  app-user without a "TenantAdmin" role. Only covers the tenant-scope triad —
    *  define-/delete-system-field stay hard-wired to ["SystemAdmin"], since

package/packages/bundled-features/src/custom-fields/handlers/clear-custom-field.write.ts

@@ -19,13 +19,13 @@ export type ClearCustomFieldPayload = z.infer<typeof clearCustomFieldPayloadSche
 const CLEAR_CUSTOM_FIELD_REASON =
   "reads custom field definitions with an explicit tenant_id = caller tenant via raw SQL with read retry";
 
-// clear-custom-field — entfernt einen Custom-Field-Wert von einer host-
-// entity. Emittiert customField.cleared-Event; MSP entfernt key aus
-// jsonb-column (key-removal, nicht null-set).
+// clear-custom-field — removes a custom-field value from a host entity.
+// Emits the customField.cleared event; MSP removes the key from the
+// jsonb column (key removal, not setting it to null).
 //
-// T1.5b: per-field fieldAccess.write gate — caller muss eine der definierten
-// Rollen halten falls fieldDefinition.serializedField.fieldAccess.write
-// gesetzt ist. Handler-level RBAC (TenantAdmin/Member) bleibt zusätzlich.
+// Per-field fieldAccess.write gate: the caller must hold one of the defined
+// roles when fieldDefinition.serializedField.fieldAccess.write is set.
+// Handler-level RBAC (TenantAdmin/Member) still applies as well.
 export const clearCustomFieldHandler: WriteHandlerDef = {
   name: "clear-custom-field",
   schema: clearCustomFieldPayloadSchema,
@@ -73,8 +73,9 @@ export const clearCustomFieldHandler: WriteHandlerDef = {
   },
 };
 
-/** Pendant zu createSetCustomFieldHandler — gleiche Rollen für set + clear,
- *  ein Wert ohne Clear-Recht wäre nur halb beherrschbar. */
+/** Companion to createSetCustomFieldHandler: set and clear use the same roles;
+ *  allowing a value to be set without allowing it to be cleared would leave
+ *  access control incomplete. */
 export function createClearCustomFieldHandler(
   roles: readonly string[] = DEFAULT_VALUE_WRITE_ROLES,
 ): WriteHandlerDef {