@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

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 {

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

@@ -7,38 +7,40 @@ import { countTenantFieldDefinitions } from "../lib/quota.ts";
 import { type DefineFieldPayload, defineFieldPayloadSchema } from "../schemas.ts";
 import { DEFAULT_FIELD_DEFINITION_WRITE_ROLES } from "../web/constants.ts";
 
-// define-tenant-field — TenantAdmin definiert eine Custom-Field-Definition
-// für seinen eigenen Tenant. tenantId wird automatisch aus event.user.tenantId
-// abgeleitet (NICHT vom Caller setzbar — verhindert Cross-Tenant-Mutation).
+// define-tenant-field — TenantAdmin defines a custom-field definition
+// for its own tenant. tenantId is derived automatically from
+// event.user.tenantId (NOT settable by the caller — prevents cross-tenant
+// mutation).
 //
-// **Same-scope-conflict** wird natürlich durch aggregate-version-conflict
-// enforced: deterministische aggregate-id aus uuidv5(tenant, entity, fieldKey)
-// macht einen zweiten Create auf dieselbe Definition ein version_conflict.
-// Dispatcher returnt 409. Saubere Idempotency-Garantie ohne extra DB-roundtrip.
+// **Same-scope-conflict** is naturally enforced by the
+// aggregate-version-conflict: the deterministic aggregate-id from
+// uuidv5(tenant, entity, fieldKey) makes a second Create for the same
+// definition a version_conflict. The dispatcher returns 409, providing a
+// clean idempotency guarantee without an extra DB round trip.
 //
-// **Cross-scope-conflict** (tenant versucht fieldKey zu definieren der bereits
-// system-scope existiert) wird in B1 NICHT enforced — aggregate-ids
-// unterscheiden sich (verschiedene tenantIds in uuidv5), beide writes gehen
-// durch. Resolution beim Read (B2) zeigt dann den system-scope-Wert. v2
-// kann r.systemScope-Sub-Handler einführen um cross-scope-conflict am Write
-// abzulehnen.
+// **Cross-scope-conflict** (a tenant attempts to define a fieldKey that
+// already exists in the system scope) is NOT enforced here — the aggregate
+// IDs differ (different tenantIds in uuidv5), so both writes proceed.
+// Resolution at read time shows the system-scope value. A future version
+// could introduce an r.systemScope sub-handler to reject cross-scope-conflict
+// at write time.
 //
-// **Quota (T1.5e)**: optional `fieldDefinitionLimitPerTenant` gate. When the
-// tenant already has ≥ limit definitions, the handler rejects with
-// `unprocessable` + reason `cap_exceeded` BEFORE attempting the insert.
-// The factory below closes over the limit; the legacy const-export keeps
-// behavior unchanged for callers who didn't opt into a limit.
+// **Quota**: optional `fieldDefinitionLimitPerTenant` gate. When the tenant
+// already has ≥ limit definitions, the handler rejects with `unprocessable`
+// and reason `cap_exceeded` BEFORE attempting the insert. The factory below
+// closes over the limit; the legacy const-export preserves behavior for
+// callers that did not opt into a limit.
 //
-// Soft cap, not a hard guarantee: the count-then-insert is not serialized, so
+// Soft cap, not a hard guarantee: count-then-insert is not serialized, so
 // N concurrent defines with distinct fieldKeys can each read `current < limit`
-// and overshoot by up to N. Acceptable here — defining fields is an admin-only,
-// low-frequency action and the limit is not wired to billing/tier enforcement.
-// If an exact cap is ever needed, serialize via advisory lock or a count
-// constraint at the insert.
+// and overshoot by up to N. This is acceptable because defining fields is an
+// admin-only, low-frequency action and the limit is not wired to
+// billing/tier enforcement. If an exact cap is ever needed, serialize via
+// advisory lock or add a count constraint at the insert.
 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). */
@@ -66,7 +68,7 @@ export function createDefineTenantFieldHandler(
       const payload = event.payload as DefineFieldPayload; // @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",
@@ -101,5 +103,5 @@ export function createDefineTenantFieldHandler(
 }
 
 // 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: WriteHandlerDef = createDefineTenantFieldHandler();

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

@@ -6,11 +6,10 @@ import { createCustomFieldsFeature } from "../feature.ts";
 import { type DeleteFieldPayload, deleteFieldPayloadSchema } from "../schemas.ts";
 import { FIELD_DEFINITION_AGGREGATE_TYPE } from "../web/constants.ts";
 
-// 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: WriteHandlerDef = {
   name: "delete-system-field",
   schema: deleteFieldPayloadSchema,
@@ -32,8 +31,8 @@ export const deleteSystemFieldHandler: WriteHandlerDef = {
       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/packages/bundled-features/src/custom-fields/handlers/delete-tenant-field.write.ts

@@ -8,18 +8,17 @@ import {
   FIELD_DEFINITION_AGGREGATE_TYPE,
 } from "../web/constants.ts";
 
-// delete-tenant-field — TenantAdmin löscht eigene Field-Definition.
-// Spec-Promise (Plan-Doc v2 "wie Entity-Delete"): Events bleiben im event-
-// store für Audit-Trail. Read-Projection-Row wird entfernt. B2 wird die
-// Cleanup-Pipeline (`customFieldDefinition.deleted`-Event → MSP entfernt
-// values aus read_<entity>.customFields jsonb) wirklich wiren — in B1
-// kümmern wir uns nur um die Definition selbst.
+// delete-tenant-field — TenantAdmin deletes their own field definition.
+// Events remain in the event store for the audit trail, while the read-projection
+// row is removed. The cleanup pipeline (`customFieldDefinition.deleted`-Event → MSP
+// removes values from read_<entity>.customFields jsonb) is wired separately; this
+// handler only manages the definition itself.
 //
-// **Idempotency:** Delete auf nicht-existente Definition → version_conflict
-// (executor.delete returns failure, dispatcher 404/422). Caller sieht "not
-// found" — kein Crash.
+// **Idempotency:** Deleting a non-existent definition results in version_conflict
+// (executor.delete returns failure, dispatcher 404/422). The caller sees "not
+// found" rather than an exception.
 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[];
 }
@@ -52,9 +51,9 @@ export function createDeleteTenantFieldHandler(
 
       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/packages/bundled-features/src/custom-fields/handlers/set-custom-field.write.ts

@@ -25,30 +25,27 @@ export type SetCustomFieldPayload = z.infer<typeof setCustomFieldPayloadSchema>;
 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: WriteHandlerDef = {
   name: "set-custom-field",
   schema: setCustomFieldPayloadSchema,
@@ -95,11 +92,11 @@ export const setCustomFieldHandler: WriteHandlerDef = {
       }
     }
 
-    // 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,
@@ -114,9 +111,9 @@ export 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 function createSetCustomFieldHandler(
   roles: readonly string[] = DEFAULT_VALUE_WRITE_ROLES,
 ): WriteHandlerDef {

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

@@ -15,10 +15,10 @@ import { DEFAULT_FIELD_DEFINITION_WRITE_ROLES } from "../web/constants.ts";
 //
 // **type is immutable**; an omitted type keeps the stored one. A type change
 // would orphan existing values in the host entities' customFields jsonb (a
-// text value under a number field), so delete + re-define is the honest path
-// (Bug-Bash D2: deliberately no delete+redefine inside update, since that
-// destroys event history and field ids, which is exactly the break a type
-// change needs to make visible).
+// text value under a number field), so delete + re-define is the honest path.
+// There is deliberately no delete+redefine inside update, since that destroys
+// event history and field ids, which is exactly the break a type change needs
+// to make visible.
 //
 // **Known MVP limit (deliberate):** the edit does NOT reconcile existing host
 // values against the new definition. Narrowed constraints (enum value removed,
@@ -32,7 +32,7 @@ import { DEFAULT_FIELD_DEFINITION_WRITE_ROLES } from "../web/constants.ts";
 // (same trade-off as the quota soft cap in define), so last write wins instead
 // of a version round trip through the edit screen.
 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[];
 }
@@ -87,7 +87,7 @@ export function createUpdateTenantFieldHandler(
         });
       }
 
-      // 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,

package/packages/bundled-features/src/custom-fields/lib/field-access.ts

@@ -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).
 
@@ -31,7 +31,7 @@ export async function loadFieldDefinition(
 ): Promise<LoadedFieldDefinition> {
   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/packages/bundled-features/src/custom-fields/lib/parse-serialized-field.ts

@@ -42,7 +42,7 @@ export function parseSerializedField(raw: unknown): SerializedFieldShape | null
   const parsed = typeof raw === "string" ? parseJsonSafe<unknown>(raw, null) : 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(

package/packages/bundled-features/src/custom-fields/lib/quota.ts

@@ -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.
 

package/packages/bundled-features/src/custom-fields/lib/value-schema.ts

@@ -8,23 +8,21 @@ import type * as z from "zod";
 import { SUPPORTED_FIELD_TYPES } from "../web/constants.ts";
 
 // 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: ReadonlySet<string> = new Set(SUPPORTED_FIELD_TYPES);
 const SUPPORTED_EMBEDDED_SUB_TYPES: ReadonlySet<string> = new Set([

package/packages/bundled-features/src/custom-fields/run-retention.ts

@@ -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
@@ -158,7 +158,7 @@ async function loadRetentionPolicies(
   for (const raw of rows) {
     // 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: ReturnType<typeof parseSerializedField>;
@@ -178,7 +178,7 @@ interface InstantLike {
   readonly epochMilliseconds: number;
 }
 
-// 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: unknown): value is InstantLike {
   if (!value || typeof value !== "object") return false;
   if (!("epochMilliseconds" in value)) return false;