@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

package/packages/bundled-features/src/config/handlers/set.write.ts

@@ -74,7 +74,8 @@ export const setWrite = defineWriteHandler({
     // rejected), but an admin override write can still target scope=
     // "system" for a tenant/user-scoped key (validateScope allows any
     // requestedScope <= definedScope) — system-row has no subject.
-    if (keyDef.piiEncrypted && scope === ConfigScopes.system) {
+    const piiScope = keyDef.piiEncrypted && scope !== ConfigScopes.system ? scope : undefined;
+    if (keyDef.piiEncrypted && piiScope === undefined) {
       return writeFailure(
         new UnprocessableError("invalid_scope", {
           i18nKey: "config.errors.invalidScope",
@@ -153,7 +154,7 @@ export const setWrite = defineWriteHandler({
     if (keyDef.encrypted) {
       const cipher = requireConfigEncryption(ctx, "config:write:set");
       serialized = await cipher.encrypt(serialized, { tenantId });
-    } else if (keyDef.piiEncrypted) {
+    } else if (piiScope !== undefined) {
       const kms = configuredPiiSubjectKms();
       if (!kms) {
         throw new InternalError({
@@ -163,8 +164,7 @@ export const setWrite = defineWriteHandler({
             `configurePiiSubjectKms(adapter) at boot.`,
         });
       }
-      // scope="system" was already rejected above — narrow accordingly.
-      const subject = resolvePiiSubject(scope as Exclude<typeof scope, "system">, tenantId, userId);
+      const subject = resolvePiiSubject(piiScope, tenantId, userId);
       const kmsCtx: KmsContext = {
         requestId: requestContext.get()?.requestId ?? "config:write:set",
         tenantId,

package/packages/bundled-features/src/config/handlers/values.query.ts

@@ -1,6 +1,7 @@
 import {
   type ConfigKeyDefinition,
   type ConfigScope,
+  ConfigScopes,
   type ConfigValueSource,
   defineQueryHandler,
   isEncryptedAtRest,
@@ -8,7 +9,7 @@ import {
 import * as z from "zod";
 import { requireConfigResolver, requireSystemDb } from "../feature.ts";
 import { MASKED, redactInheritedCascade, shouldRedactInherited } from "../read-redaction.ts";
-import { hasConfigAccess } from "../write-helpers.ts";
+import { hasConfigAccess, keyDefAtScope } from "../write-helpers.ts";
 
 export const valuesQuery = defineQueryHandler({
   name: "values",
@@ -16,6 +17,7 @@ export const valuesQuery = defineQueryHandler({
     "Returns the effective value, scope and winning source for every config key the caller may read (optionally narrowed to `keys`), with encrypted and secret-backed values masked; use it to inspect the current settings.",
   schema: z.object({
     keys: z.array(z.string()).optional(),
+    scope: z.enum([ConfigScopes.system, ConfigScopes.tenant, ConfigScopes.user]).optional(),
   }),
   // Per-key read access enforced via hasConfigAccess inside the handler.
   access: {
@@ -44,7 +46,7 @@ export const valuesQuery = defineQueryHandler({
     for (const [qualifiedKey, keyDef] of allKeys) {
       if (requestedKeys !== undefined && !requestedKeys.has(qualifiedKey)) continue;
       if (!hasConfigAccess(keyDef.access.read, query.user.roles)) continue;
-      keyDefs.set(qualifiedKey, keyDef);
+      keyDefs.set(qualifiedKey, keyDefAtScope(keyDef, query.payload.scope, query.user.roles));
       filteredKeys.push(qualifiedKey);
     }
 

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

@@ -583,10 +583,10 @@ export function validateAppOverrides(
       );
     }
 
-    // Per keyDef.type narrow value inline — TS narrowt nicht durch
-    // `typeof value !== typeForKey(...)` (typeForKey returnt string,
-    // kein discriminator). Das vermeidet `value as string|number` casts
-    // unten, weil value innerhalb des Branches schon typed ist.
+    // Narrow by keyDef.type inline because TypeScript cannot narrow through
+    // `typeof value !== typeForKey(...)`, whose return type is string rather
+    // than a discriminator. This avoids `value as string|number` casts below;
+    // value is correctly typed within each branch.
     if (keyDef.type === "number") {
       if (typeof value !== "number") {
         throw new Error(`App-Boot-Override for "${key}": expected number, got ${typeof value}`);

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

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

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

@@ -75,8 +75,9 @@ export async function configRowHoldsValue(
   serializedValue: string,
 ): Promise<boolean> {
   if (row?.value === null || row?.value === undefined) return false;
-  if (!keyDef?.encrypted && !keyDef?.piiEncrypted) return row.value === serializedValue;
-  if (!keyDef) return false;
+  if (keyDef === undefined || (!keyDef.encrypted && !keyDef.piiEncrypted)) {
+    return row.value === serializedValue;
+  }
   try {
     return (await decryptStoredValue(row.value, keyDef, cipher, qualifiedKey)) === serializedValue;
   } catch {
@@ -194,12 +195,7 @@ export function validateScope(
   definedScope: ConfigScope,
   key: string,
 ): KumikoError | null {
-  const levels: Record<ConfigScope, number> = {
-    [ConfigScopes.system]: 0,
-    [ConfigScopes.tenant]: 1,
-    [ConfigScopes.user]: 2,
-  };
-  if (levels[requestedScope] > levels[definedScope]) {
+  if (SCOPE_LEVEL[requestedScope] > SCOPE_LEVEL[definedScope]) {
     return new UnprocessableError("invalid_scope", {
       i18nKey: "config.errors.invalidScope",
       details: { key, definedScope, requestedScope },
@@ -208,6 +204,29 @@ export function validateScope(
   return null;
 }
 
+const SCOPE_LEVEL: Record<ConfigScope, number> = {
+  [ConfigScopes.system]: 0,
+  [ConfigScopes.tenant]: 1,
+  [ConfigScopes.user]: 2,
+};
+
+// Reads a tenant/user key at a narrower scope, e.g. system for a system-level screen.
+// Only a SystemAdmin may widen the read to the platform level; everyone else keeps the normal cascade.
+export function keyDefAtScope(
+  keyDef: ConfigKeyDefinition,
+  readScope: ConfigScope | undefined,
+  roles: readonly string[],
+): ConfigKeyDefinition {
+  if (
+    readScope === undefined ||
+    !roles.includes("SystemAdmin") ||
+    SCOPE_LEVEL[readScope] >= SCOPE_LEVEL[keyDef.scope]
+  ) {
+    return keyDef;
+  }
+  return { ...keyDef, scope: readScope };
+}
+
 export function resolveScopeIds(
   scope: ConfigScope,
   tenantId: TenantId,
@@ -226,7 +245,7 @@ export function resolveScopeIds(
 }
 
 // The subject a piiEncrypted config value is encrypted under, for the scope
-// actually written to (kumiko-platform#231/#459). Pure — no I/O — so a bug
+// actually written to. Pure — no I/O — so a bug
 // here (e.g. picking the writer's identity instead of the row's target,
 // see entity fields' explicit userOwned.ownerField for why that
 // distinction matters) is caught by a fast unit test, not only the DB-

package/packages/bundled-features/src/crypto-shredding/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "forget-subject audit event survives a failing record owner lookup",
+    "detail": "The lookup of the record row's owning tenant now runs inside the file purge step, so a database error there is reported as cleanupError on the subject-forgotten event instead of aborting the handler after the key was erased."
+  },
   {
     "version": "0.377.0",
     "type": "fix",

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

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

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

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

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

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

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

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