@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/custom-fields/entity.js

@@ -1,33 +1,34 @@
 import { createBooleanField, createEntity, createNumberField, 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: "One custom-field definition: the host entity it extends, the field key, its type and required/searchable flags, a display order, and the serialized field builder that carries the type options, default value and labels. Rows owned by the system tenant apply to every tenant; all others belong to the tenant that defined them.",
@@ -40,55 +41,56 @@ 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,
             personal: false,
             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,
             personal: false,
             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,
             personal: false,
             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/dist/custom-fields/events.js

@@ -1,15 +1,14 @@
 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/dist/custom-fields/feature.d.ts

@@ -15,24 +15,24 @@ declare const defaultCustomFieldsFeature: import("@cosmicdrift/kumiko-types/feat
     };
 };
 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/dist/custom-fields/feature.js

@@ -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, defineFeature, } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { fieldDefinitionEntity } from "./entity.js";
@@ -76,9 +75,9 @@ function registerCustomFields(r, variant) {
         recommended: false,
     });
     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.
@@ -89,28 +88,28 @@ function registerCustomFields(r, variant) {
         piiFields: "none",
     });
     const fieldDefinitionDeletedEvent = r.defineEvent(FIELD_DEFINITION_DELETED_EVENT, fieldDefinitionDeletedSchema, { 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 },
         description: "Lists the custom-field definitions of the caller's own tenant; use it to discover which extra fields an entity accepts before setting or clearing a value on it.",

package/dist/custom-fields/handlers/clear-custom-field.write.d.ts

@@ -7,6 +7,7 @@ export declare const clearCustomFieldPayloadSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ClearCustomFieldPayload = z.infer<typeof clearCustomFieldPayloadSchema>;
 export declare 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 declare function createClearCustomFieldHandler(roles?: readonly string[]): WriteHandlerDef;

package/dist/custom-fields/handlers/clear-custom-field.write.js

@@ -13,13 +13,13 @@ export const clearCustomFieldPayloadSchema = z.object({
         .regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/),
 });
 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 = {
     name: "clear-custom-field",
     schema: clearCustomFieldPayloadSchema,
@@ -56,8 +56,9 @@ export const clearCustomFieldHandler = {
         };
     },
 };
-/** 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 = DEFAULT_VALUE_WRITE_ROLES) {
     return { ...clearCustomFieldHandler, access: { roles } };
 }

package/dist/custom-fields/handlers/define-tenant-field.write.d.ts

@@ -2,7 +2,7 @@ import { type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 export interface DefineTenantFieldOptions {
     /** Soft cap — `>= limit` definitions per tenant rejects further defines (see header: concurrent defines may overshoot). */
     readonly fieldDefinitionLimitPerTenant?: number;
-    /** Access roles for this handler. Default ["TenantAdmin"] (#2296) — apps with
+    /** Access roles for this handler. Default ["TenantAdmin"] — apps with
      *  their own role vocabulary pass this via createCustomFieldsFeature({
      *  fieldDefinitionWriteRoles }), which threads the same roles into
      *  update-/delete-tenant-field too (the definition-CRUD triad shares one gate). */

package/dist/custom-fields/handlers/define-tenant-field.write.js

@@ -21,7 +21,7 @@ export function createDefineTenantFieldHandler(opts = {}) {
         handler: async (event, ctx) => {
             const payload = event.payload; // @cast-boundary engine-payload
             const tenantId = event.user.tenantId;
-            // TenantAdmin darf NICHT system-scope schreiben — strict-guard.
+            // TenantAdmin MUST NOT write to the system scope — strict guard.
             if (isSystemTenant(tenantId)) {
                 throw new Error("define-tenant-field: tenantId is SYSTEM_TENANT_ID — use define-system-field for system-scope definitions");
             }
@@ -41,5 +41,5 @@ export function createDefineTenantFieldHandler(opts = {}) {
     };
 }
 // Backwards-compat: existing imports of `defineTenantFieldHandler` keep
-// working — the handler has no quota, identical to pre-T1.5e behavior.
+// working — the handler has no quota, identical to behavior before the quota.
 export const defineTenantFieldHandler = createDefineTenantFieldHandler();

package/dist/custom-fields/handlers/delete-system-field.write.js

@@ -5,11 +5,10 @@ import { fieldDefinitionExecutor } from "../executor.js";
 import { createCustomFieldsFeature } from "../feature.js";
 import { deleteFieldPayloadSchema } from "../schemas.js";
 import { FIELD_DEFINITION_AGGREGATE_TYPE } from "../web/constants.js";
-// delete-system-field — SystemAdmin entfernt eine system-weite Field-
-// Definition. Konsequenz: KEIN Tenant kann mehr neue Werte dafür setzen,
-// existing Werte in read_<entity>.customFields jsonb bleiben aber bestehen
-// (B2's MSP wird sie via customFieldDefinition.deleted-Event aufräumen).
-// Events bleiben für Audit.
+// delete-system-field — SystemAdmin deletes a system-wide field definition.
+// Tenants can no longer set new values for it, but existing values remain in
+// read_<entity>.customFields jsonb until host-entity MSPs remove them in
+// response to the customFieldDefinition.deleted event. Events remain for audit.
 export const deleteSystemFieldHandler = {
     name: "delete-system-field",
     schema: deleteFieldPayloadSchema,
@@ -23,8 +22,8 @@ export const deleteSystemFieldHandler = {
         const result = await fieldDefinitionExecutor.delete({ id: aggregateId }, event.user, db, {
             streamTenantId,
         });
-        // Cascade-cleanup-Event — host-entity-MSPs entfernen orphan values aus
-        // ihrer customFields jsonb. Im selben TX = atomic.
+        // Cascade-cleanup event — host-entity MSPs remove orphaned values from their
+        // customFields jsonb in the same transaction for atomicity.
         if (result.isSuccess) {
             await ctx.unsafeAppendEvent({
                 aggregateId,

package/dist/custom-fields/handlers/delete-tenant-field.write.d.ts

@@ -1,6 +1,6 @@
 import { type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 export interface DeleteTenantFieldOptions {
-    /** Access roles for this handler. Default ["TenantAdmin"] (#2296) — see
+    /** Access roles for this handler. Default ["TenantAdmin"] — see
      *  DefineTenantFieldOptions.roles, the definition-CRUD triad shares one gate. */
     readonly roles?: readonly string[];
 }

package/dist/custom-fields/handlers/delete-tenant-field.write.js

@@ -19,9 +19,9 @@ export function createDeleteTenantFieldHandler(opts = {}) {
             }
             const aggregateId = fieldDefinitionAggregateId(tenantId, payload.entityName, payload.fieldKey);
             const result = await fieldDefinitionExecutor.delete({ id: aggregateId }, event.user, ctx.db);
-            // Emit cascade-cleanup-Event NACH erfolgreichem Delete. host-entity-MSPs
-            // (registriert via wireCustomFieldsFor) konsumieren das + entfernen orphan
-            // values aus ihrer customFields jsonb. Im selben TX = atomic cleanup.
+            // Emit the cascade-cleanup event after a successful delete. Host-entity MSPs
+            // registered via wireCustomFieldsFor consume it and remove orphaned values
+            // from their customFields jsonb. The same transaction makes cleanup atomic.
             if (result.isSuccess) {
                 await ctx.unsafeAppendEvent({
                     aggregateId,

package/dist/custom-fields/handlers/set-custom-field.write.d.ts

@@ -8,7 +8,7 @@ export declare const setCustomFieldPayloadSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type SetCustomFieldPayload = z.infer<typeof setCustomFieldPayloadSchema>;
 export declare const setCustomFieldHandler: WriteHandlerDef;
-/** Value-Write mit App-Rollen statt der Bundle-Defaults — Apps mit eigenem
- *  Rollen-Vokabular (z.B. "Admin"/"Editor") reichen ihre Rollen über
- *  createCustomFieldsFeature({ valueWriteRoles }) hierher durch. */
+/** Value writes use app roles instead of the bundle defaults — apps with a
+ *  custom role vocabulary (e.g. "Admin"/"Editor") pass their roles here via
+ *  createCustomFieldsFeature({ valueWriteRoles }). */
 export declare function createSetCustomFieldHandler(roles?: readonly string[]): WriteHandlerDef;

package/dist/custom-fields/handlers/set-custom-field.write.js

@@ -19,30 +19,27 @@ export const setCustomFieldPayloadSchema = z.object({
         .refine((v) => v !== undefined, "value is required (use clear-custom-field to remove a value)"),
 });
 const SET_CUSTOM_FIELD_REASON = "reads custom field definitions with an explicit tenant_id = caller tenant via raw SQL with read retry";
-// set-custom-field — schreibt einen Custom-Field-Wert auf eine host-entity.
+// set-custom-field — writes a custom-field value to a host entity.
 //
-// **ES-Option-B**: emittiert customField.set-Event auf dem host-aggregate
+// Emits a customField.set event on the host-aggregate
 // stream (aggregateType = host-entity-name, aggregateId = host-entity-id).
-// Last-Wins-Semantik: customField.set wird OHNE expectedVersion appended,
-// concurrent writes auf gleiches Field gehen beide durch (Plan-Doc v2
-// Concurrency-Tabelle).
+// Last-wins semantics: customField.set is appended WITHOUT expectedVersion,
+// so concurrent writes to the same field both succeed.
 //
-// **Write-Pfad (Single-Fetch)** — eine fieldDefinition-Ladung, drei Gates:
-//   1. Definition fehlt → 404.
-//   2. field-access (T1.5b): fieldAccess.write-Rollen müssen intersecten, sonst
-//      403/422. Handler-level RBAC (TenantAdmin/Member) bleibt zusätzlich.
-//   3. Value-Validation (Builder-Reuse): der Wert wird gegen das aus
-//      serializedField rehydrierte fieldToZod-Schema geparst. Type-Mismatch →
-//      422, KEIN Event entsteht (Projection bleibt typed — Plan-Doc
-//      Stammfeld-Identität). `value: null` ODER `value: undefined` auf einem
-//      typisierten Feld sind Type-Mismatches → 422; zum Entfernen eines Werts
-//      dient clear-custom-field.
+// **Write path (single fetch)** — one fieldDefinition load, three gates:
+//   1. Definition missing → 404.
+//   2. field-access: fieldAccess.write roles must intersect, otherwise
+//      403/422. Handler-level RBAC (TenantAdmin/Member) also applies.
+//   3. Value validation (builder reuse): the value is parsed against the
+//      fieldToZod schema rehydrated from serializedField. Type mismatch →
+//      422, NO event is created (the projection remains typed). `value: null`
+//      OR `value: undefined` on a typed field are type mismatches → 422; use
+//      clear-custom-field to remove a value.
 //
-// Scope: ECHTE type-only Validation. value-schema.ts strippt `required`,
-// `maxLength`, `format` und `default` aus dem serializedField bevor fieldToZod
-// daraus ein Schema baut — wir prüfen nur die Type-Shape. Required-on-set,
-// Default-Application und Length-/Format-Enforcement bleiben out-of-scope
-// (Plan-Doc "Stammfeld-Identität" listet sie als eigene Zeilen).
+// Scope: TRUE type-only validation. value-schema.ts strips `required`,
+// `maxLength`, `format`, and `default` from serializedField before building
+// a schema from fieldToZod — we check only the type shape. Required-on-set,
+// default application, and length/format enforcement remain out of scope.
 export const setCustomFieldHandler = {
     name: "set-custom-field",
     schema: setCustomFieldPayloadSchema,
@@ -79,11 +76,11 @@ export const setCustomFieldHandler = {
                 });
             }
         }
-        // Emit customField.set on host-aggregate stream. unsafeAppendEvent
-        // (statt strict appendEvent) weil event-type-map keine cross-feature-
-        // augmentation für diesen event-typ hat — wir nutzen den qualified
-        // string-namen direkt. Der Wert steht IMMER im Event (custom fields
-        // tragen keine PII, #972) — Replay reproduziert die Projection voll.
+        // Emit customField.set on the host-aggregate stream. unsafeAppendEvent
+        // is used instead of strict appendEvent because event-type-map has no
+        // cross-feature augmentation for this event type; the qualified string
+        // name is used directly. The value is ALWAYS included in the event
+        // (custom fields carry no PII), so replay fully reproduces the projection.
         await ctx.unsafeAppendEvent({
             aggregateId: payload.entityId,
             aggregateType: payload.entityName,
@@ -96,9 +93,9 @@ export const setCustomFieldHandler = {
         };
     },
 };
-/** Value-Write mit App-Rollen statt der Bundle-Defaults — Apps mit eigenem
- *  Rollen-Vokabular (z.B. "Admin"/"Editor") reichen ihre Rollen über
- *  createCustomFieldsFeature({ valueWriteRoles }) hierher durch. */
+/** Value writes use app roles instead of the bundle defaults — apps with a
+ *  custom role vocabulary (e.g. "Admin"/"Editor") pass their roles here via
+ *  createCustomFieldsFeature({ valueWriteRoles }). */
 export function createSetCustomFieldHandler(roles = DEFAULT_VALUE_WRITE_ROLES) {
     return { ...setCustomFieldHandler, access: { roles } };
 }

package/dist/custom-fields/handlers/update-tenant-field.write.d.ts

@@ -1,6 +1,6 @@
 import { type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 export interface UpdateTenantFieldOptions {
-    /** Access roles for this handler. Default ["TenantAdmin"] (#2296) — see
+    /** Access roles for this handler. Default ["TenantAdmin"] — see
      *  DefineTenantFieldOptions.roles, the definition-CRUD triad shares one gate. */
     readonly roles?: readonly string[];
 }