@cosmicdrift/kumiko-bundled-features 0.385.0 → 0.387.0

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

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

@@ -35,7 +35,7 @@ export function createUpdateTenantFieldHandler(opts = {}) {
                     requestedType,
                 });
             }
-            // entityName/fieldKey sind die Identität — nicht Teil der changes.
+            // entityName/fieldKey define the identity and must not be included in changes.
             const { entityName: _entityName, fieldKey: _fieldKey, ...changes } = buildFieldDefinitionColumns({
                 ...payload,
                 serializedField: { ...payload.serializedField, type: storedType.data },

package/dist/custom-fields/lib/field-access.js

@@ -1,4 +1,4 @@
-// T1.5b — per-field write access-check for the set/clear handlers.
+// Per-field write access-check for the set/clear handlers.
 // Plus single-fetch loader so set-custom-field can run access-check AND
 // value-validation off one DB read (no double fetch).
 import { selectSerializedFieldDefinition } from "../db/queries/field-access.js";
@@ -8,7 +8,7 @@ export async function loadFieldDefinition(runner, tenantId, entityName, fieldKey
     const serialized = await selectSerializedFieldDefinition(runner, tenantId, entityName, fieldKey);
     if (serialized === null)
         return { found: false };
-    // parseSerializedField throws on a #972 legacy `sensitive` definition —
+    // parseSerializedField throws on a legacy `sensitive` definition —
     // that's a corrupt/unprocessable row from this write-gate's perspective,
     // same fail-closed treatment as a shape that fails isShape().
     try {

package/dist/custom-fields/lib/parse-serialized-field.js

@@ -30,7 +30,7 @@ export function parseSerializedField(raw) {
     if (!isShape(parsed))
         return null;
     // Fail loud instead of silently dropping the key: a stored definition with
-    // `sensitive` predates #972 and its PII expectations (event-log exclusion,
+    // `sensitive` predates and its PII expectations (event-log exclusion,
     // forget-strip) no longer hold — the field must be recreated.
     if ("sensitive" in parsed) {
         throw new Error("custom-field definition contains the removed `sensitive` key (#972) — custom fields don't support PII. Recreate the field without it; model personal data as a schema entity field with a pii annotation.");

package/dist/custom-fields/lib/quota.js

@@ -1,4 +1,4 @@
-// T1.5e — per-tenant fieldDefinition quota.
+// Per-tenant fieldDefinition quota.
 //
 // Re-exports from db/queries/quota.ts for backward-compatible import paths.
 export { countTenantFieldDefinitions } from "../db/queries/quota.js";

package/dist/custom-fields/lib/value-schema.js

@@ -2,23 +2,21 @@ import { DEFAULT_CURRENCIES, fieldToZod, } from "@cosmicdrift/kumiko-framework/e
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { SUPPORTED_FIELD_TYPES } from "../web/constants.js";
 // Builds a Zod schema that validates a custom-field VALUE against its
-// fieldDefinition. Reuses the framework's `fieldToZod` (Builder-Reuse /
-// Stammfeld-Identität, Plan-Doc) — one field-type-schema source, no drift
-// between Stammfeld- and Custom-Field-validation.
+// fieldDefinition. Reuses the framework's `fieldToZod` so built-in and
+// custom-field validation share one field-type schema source.
 //
-// Scope: type-shape only. fieldToZod also folds `required`, `maxLength`,
-// `format`, and `default` into Zod refinements; we strip those before the
-// call so set-custom-field rejects type-mismatches and only type-mismatches.
-// Required-on-set, default-application, and length/format-enforcement remain
-// out-of-scope per the Plan-Doc ("Stammfeld-Identität" lists them as
-// separate concerns).
+// Scope: type-shape only. `fieldToZod` also folds `required`, `maxLength`,
+// `format`, and `default` into Zod refinements; stripping them before the
+// call ensures that setting a custom field rejects only type mismatches.
+// Required-on-set, default application, and length/format enforcement remain
+// separate concerns.
 //
-// Vocabulary bridge: custom-fields expose `enum` (Plan + `r.field.enum([...])`)
-// where the framework's FieldDefinition calls the equivalent type `select`
+// Vocabulary bridge: custom fields expose `enum` through `r.field.enum([...])`,
+// while the framework's FieldDefinition calls the equivalent type `select`
 // with an `options` array.
 //
 // Returns `null` when the serialized field is unparseable or names a type
-// outside the custom-fields-supported set — callers then skip value-validation.
+// outside the custom-fields-supported set, allowing callers to skip validation.
 const SUPPORTED_TYPES_SET = new Set(SUPPORTED_FIELD_TYPES);
 const SUPPORTED_EMBEDDED_SUB_TYPES = new Set([
     "text",

package/dist/custom-fields/run-retention.js

@@ -1,4 +1,4 @@
-// T1.5d — per-field retention sweep for the customFields jsonb.
+// Per-field retention sweep for the customFields jsonb.
 //
 // Iterates one host entity's rows, looks up every fieldDefinition with a
 // `retention` policy, and strips/nulls customField values whose host-row
@@ -113,7 +113,7 @@ async function loadRetentionPolicies(db, tenantId, entityName) {
         // skip: see asHostRow rationale.
         if (!isFieldDefinitionRow(raw))
             continue;
-        // parseSerializedField throws on a #972 legacy `sensitive` definition —
+        // parseSerializedField throws on a legacy `sensitive` definition —
         // one unmigrated field must not abort the whole tenant's retention sweep
         // for every other field; skip it (no retention policy to apply anyway).
         let parsed;
@@ -129,7 +129,7 @@ async function loadRetentionPolicies(db, tenantId, entityName) {
     }
     return out;
 }
-// guard:dup-ok — false positive: gleiche TypeGuard-Struktur wie isFieldDefinitionRow, völlig andere Semantik
+// guard:dup-ok — false positive: same type-guard structure as isFieldDefinitionRow, but completely different semantics
 function isInstantLike(value) {
     if (!value || typeof value !== "object")
         return false;

package/dist/custom-fields/schemas.js

@@ -1,25 +1,25 @@
 import * as z from "zod";
 import { SUPPORTED_FIELD_TYPES } from "./web/constants.js";
-// 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
 // require the calling user to hold at least one of the listed roles —
 // 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(),
     write: z.array(z.string()).optional(),
 })
     .optional();
-// 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 }
@@ -29,13 +29,13 @@ export const customFieldAccessSchema = z
 //   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
@@ -61,9 +61,9 @@ const serializedFieldSchema = z
 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
@@ -84,7 +84,7 @@ export const defineFieldPayloadSchema = z.object({
 export const updateFieldPayloadSchema = defineFieldPayloadSchema.extend({
     serializedField: updateSerializedFieldSchema,
 });
-// 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/dist/custom-fields/web/client-plugin.js

@@ -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/dist/custom-fields/web/constants.js

@@ -48,8 +48,8 @@ export const CUSTOM_FIELDS_EXTENSION = "customFields";
 // every app user.
 export const DEFAULT_VALUE_WRITE_ROLES = ["TenantAdmin", "TenantMember"];
 export const DEFAULT_FIELD_DEFINITION_LIST_ROLES = ["TenantAdmin"];
-// 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/dist/custom-fields/web/custom-fields-form-section.d.ts

@@ -2,9 +2,9 @@ import { type ReactNode } from "react";
 export declare function CustomFieldsFormSection({ entityName, entityId, initialValues, }: {
     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;