@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

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;

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

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

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

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

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

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

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

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