@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.387.0

package/dist/compliance-profiles-ops/index.js

@@ -1,8 +1,8 @@
 // compliance-profiles-ops — platform-wide SystemAdmin visibility into
-// tenants missing a compliance-profile selection (#2089).
+// tenants missing a compliance-profile selection.
 //
 // needs-profile (compliance-profiles) tells a TenantAdmin they must pick a
-// profile, but stays TenantAdmin-only by design (#2084) — a SystemAdmin who
+// profile, but stays TenantAdmin-only by design — a SystemAdmin who
 // owns a picker narrowed to access.systemAdmin has no query at all. Kept as
 // a separate feature (mirrors folders-user-data/notes-history-user-data)
 // rather than folded into compliance-profiles: this is the one genuinely

package/dist/config/handlers/readiness.query.d.ts

@@ -9,10 +9,10 @@ export type ReadinessMissingKey = {
 export type RequiredKeyGate = (qualifiedName: string) => boolean;
 export declare function buildProviderSelectionGate(ctx: HandlerContext, callerQn: string, user: SessionUser, db: TenantDb): Promise<RequiredKeyGate>;
 export declare function collectMissingRequiredConfig(ctx: HandlerContext, callerQn: string, user: SessionUser, db: TenantDb, gate?: RequiredKeyGate, options?: {
-    /** Verdict-Pfade (Rollup, selbst role-gated) MÜSSEN ungefiltert zählen:
-     *  der Per-Key-read-Filter ist Info-Disclosure-Schutz für den
-     *  openToAll-Handler — im Verdict droppte er SystemAdmin-gated
-     *  required-Keys still und meldete ready:true trotz Lücke. */
+    /** Verdict paths (rollup, themselves role-gated) MUST count without filtering:
+     *  the per-key read filter protects the openToAll handler from information
+     *  disclosure, but in the verdict it dropped SystemAdmin-gated required keys
+     *  and incorrectly reported ready:true despite the gap. */
     readonly skipAccessFilter?: boolean;
 }): Promise<ReadinessMissingKey[]>;
 export declare const readinessQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"readiness", z.ZodObject<{}, z.core.$strip>, {

package/dist/config/handlers/readiness.query.js

@@ -95,7 +95,7 @@ export const readinessQuery = defineQueryHandler({
         const db = requireSystemDb(ctx, "config:query:readiness", query.user.tenantId);
         const missing = await collectMissingRequiredConfig(ctx, "config:query:readiness", query.user, db);
         // Additive, display-ready fields for the admin-shell dashboard stat
-        // panel (fw#2312) — `missing` itself stays untouched for existing
+        // panel — `missing` itself stays untouched for existing
         // consumers that read the array directly.
         return {
             missing,

package/dist/config/handlers/reencrypt.job.js

@@ -16,8 +16,8 @@
 // the NEW envelope: after a full run even a from-scratch rebuild only
 // ever sees the current-KEK envelope.
 //
-// systemScope() fail-closed pattern (framework#2056): the initial scan is
-// intentionally cross-tenant (system-wide key rotation), acknowledged via
+// systemScope() fail-closed pattern: the initial scan is intentionally
+// cross-tenant (system-wide key rotation), acknowledged via
 // UncheckedSystemDb.acknowledgeCrossTenant(). Rows are bucketed by tenant,
 // and assertRowsTenant() re-verifies each row against its bucket's tenant
 // right before the write — both checks are built locally from the exported
@@ -163,9 +163,8 @@ export const reencryptJob = async (rawPayload, ctx) => {
             return "failed";
         }
         // Re-verify the row's own tenantId against the bucket it was scanned
-        // into, right before the write (framework#2072) — a mismatch here
-        // fails this row only (via onRowError below), it does not abort the
-        // whole job.
+        // into, right before the write — a mismatch here fails this row only
+        // (via onRowError below), it does not abort the whole job.
         sdbFor(tenantId).assertRowsTenant([row], "tenantId");
         const plaintext = await cipher.decrypt(row.value, { tenantId });
         const reencrypted = await cipher.encrypt(plaintext, { tenantId });

package/dist/config/handlers/set.write.js

@@ -45,7 +45,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",
                 details: { key: event.payload.key, definedScope: keyDef.scope, requestedScope: scope },
@@ -110,7 +111,7 @@ export const setWrite = defineWriteHandler({
             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({
@@ -119,8 +120,7 @@ export const setWrite = defineWriteHandler({
                         `configurePiiSubjectKms(adapter) at boot.`,
                 });
             }
-            // scope="system" was already rejected above — narrow accordingly.
-            const subject = resolvePiiSubject(scope, tenantId, userId);
+            const subject = resolvePiiSubject(piiScope, tenantId, userId);
             const kmsCtx = {
                 requestId: requestContext.get()?.requestId ?? "config:write:set",
                 tenantId,

package/dist/config/resolver.js

@@ -402,10 +402,10 @@ export function validateAppOverrides(registry, overrides) {
         if (keyDef.computed) {
             throw new Error(`App-Boot-Override for "${key}": this key has a computed resolver (plan-based / derived). App-overrides would silently bypass that logic — remove the override, or remove the computed resolver if a flat deploy-default is intended.`);
         }
-        // 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/dist/config/table.js

@@ -2,19 +2,19 @@ import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import { createEntity, createTextField } from "@cosmicdrift/kumiko-framework/engine";
 // 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/dist/config/write-helpers.js

@@ -138,7 +138,7 @@ export function resolveScopeIds(scope, tenantId, userId) {
     }
 }
 // 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/dist/crypto-shredding/handlers/forget-subject.write.d.ts

@@ -7,7 +7,7 @@ export declare const forgetSubjectSchema: z.ZodObject<{
         userId: z.ZodUUID;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"tenant">;
-        tenantId: z.ZodPipe<z.ZodUUID, z.ZodTransform<string, string>>;
+        tenantId: z.ZodUUID;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"record">;
         entity: z.ZodString;
@@ -39,7 +39,7 @@ export declare const forgetSubjectWrite: import("@cosmicdrift/kumiko-types/defin
         userId: z.ZodUUID;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"tenant">;
-        tenantId: z.ZodPipe<z.ZodUUID, z.ZodTransform<string, string>>;
+        tenantId: z.ZodUUID;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"record">;
         entity: z.ZodString;

package/dist/crypto-shredding/handlers/forget-subject.write.js

@@ -54,7 +54,7 @@ function subjectAggregateId(raw) {
     }
 }
 // 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, entityName) {
     for (const feature of features.values()) {
         const entity = feature.entities?.[entityName];
@@ -63,7 +63,7 @@ function findRegisteredEntity(features, entityName) {
     }
     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
@@ -111,7 +111,7 @@ async function resolveTenantScopeDenial(db, features, user, raw) {
     const ownedInTenant = await subjectRowExistsInTenant(db, features, raw.userId, user.tenantId);
     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
@@ -162,8 +162,8 @@ function denialReasonOf(failure) {
     }
     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, event, subjectKey, subjectKind, denialCode, denialAuditRunner) {
     if (!denialAuditRunner) {
@@ -195,7 +195,7 @@ async function appendDenialAuditEvent(ctx, event, subjectKey, subjectKind, denia
         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",
@@ -235,10 +235,10 @@ async function sweepDerivedSubjectData(ctx, subject, subjectKey, crossTenantRunn
         }
     };
     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(crossTenantSubjectRunner, ctx.registry.features, ctx.searchAdapter, subjectKey, subject);
@@ -310,7 +310,8 @@ async function appendSubjectForgotten(ctx, event, aggregateId, payload, outsideR
         await appendDomainEventCore({
             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",
@@ -331,7 +332,7 @@ async function appendSubjectForgotten(ctx, event, aggregateId, payload, outsideR
 // 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,
@@ -393,7 +394,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/dist/custom-fields/aggregate-id.d.ts

@@ -1,19 +1,18 @@
 /**
- * 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.
  */
 export declare function fieldDefinitionAggregateId(tenantId: string, entityName: string, fieldKey: string): string;

package/dist/custom-fields/aggregate-id.js

@@ -1,26 +1,25 @@
 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(tenantId, entityName, fieldKey) {

package/dist/custom-fields/entity.js

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

package/dist/custom-fields/events.js

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

package/dist/custom-fields/feature.d.ts

@@ -15,24 +15,24 @@ declare const defaultCustomFieldsFeature: import("@cosmicdrift/kumiko-types/feat
     };
 };
 export type CustomFieldsFeatureOptions = {
-    /** T1.5e: Quota für define-tenant-field. */
+    /** Quota for define-tenant-field. */
     readonly fieldDefinitionLimitPerTenant?: number;
-    /** Rollen für set-/clear-custom-field — die Save-Pfade der
-     *  CustomFieldsFormSection. Default ["TenantAdmin","TenantMember"];
-     *  Apps mit eigenem Rollen-Vokabular (z.B. ["Admin","Editor"]) MÜSSEN
-     *  das setzen, sonst ist der Value-Save für jeden App-User
-     *  access_denied (Role-Naming-Drift). */
+    /** Roles for set-/clear-custom-field, used by the save paths in
+     * CustomFieldsFormSection. Default ["TenantAdmin","TenantMember"];
+     * apps with their own role vocabulary (for example ["Admin","Editor"])
+     * MUST set this, otherwise value saving is access_denied for every app user
+     * (role-naming drift). */
     readonly valueWriteRoles?: readonly string[];
-    /** Rollen für custom-fields:query:field-definition:list — der Lade-Pfad
-     *  der CustomFieldsFormSection. Default ["TenantAdmin"]. Wird valueWriteRoles
-     *  gesetzt, dies aber NICHT, erben die Value-Rollen hier hinein (Union mit
-     *  dem Default, damit Admins den List-Zugriff behalten) — sonst lädt die
-     *  FormSection für Value-Writer nie (access_denied), während der Save-Pfad
-     *  offen wäre (asymmetrischer Bruch). */
+    /** Roles for custom-fields:query:field-definition:list, used by the loading
+     * path in CustomFieldsFormSection. Default ["TenantAdmin"]. If
+     * valueWriteRoles is set but this is not, the value roles are inherited here
+     * (unioned with the default so admins retain list access); otherwise the
+     * FormSection cannot load for value writers (access_denied) while the save
+     * path remains open (an asymmetric break). */
     readonly fieldDefinitionListRoles?: readonly string[];
     /** Access roles for the definition-CRUD triad (`define-tenant-field`,
-     *  `update-tenant-field`, `delete-tenant-field`) — hard-wired to ["TenantAdmin"]
-     *  before #2296. Apps with their own role vocabulary (e.g. ["Admin","Editor"])
+     *  `update-tenant-field`, `delete-tenant-field`) — hard-wired to ["TenantAdmin"].
+     *  Apps with their own role vocabulary (e.g. ["Admin","Editor"])
      *  MUST set this, else field-definition management is access_denied for every
      *  app-user without a "TenantAdmin" role. Only covers the tenant-scope triad —
      *  define-/delete-system-field stay hard-wired to ["SystemAdmin"], since