@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/custom-fields/db/queries/projection.ts

@@ -0,0 +1,84 @@
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+function quoteTable(tableName: string): string {
+  return `"${tableName.replace(/"/g, '""')}"`;
+}
+
+function bindJsonbParam(value: unknown): { sql: string; bound: unknown } {
+  // Scalar JSON primitives can't bind directly to ::jsonb — Postgres rejects a
+  // bound boolean/number with "cannot cast type boolean/integer to jsonb" (and
+  // Bun.SQL infers boolean[] candidates). Route them through ::text::jsonb with
+  // a JSON-encoded literal. Objects/arrays/strings already bind as ::jsonb.
+  if (typeof value === "boolean" || typeof value === "number") {
+    return { sql: "$1::text::jsonb", bound: JSON.stringify(value) };
+  }
+  // JSON.stringify throws on bigint; its decimal string is a valid JSON number literal.
+  if (typeof value === "bigint") {
+    return { sql: "$1::text::jsonb", bound: value.toString() };
+  }
+  return { sql: "$1::jsonb", bound: value };
+}
+
+// Security invariant: aggregateId is a global row UUID, so without the tenant_id
+// filter tenant A could mutate tenant B's row by its UUID (cf. removeCustomFieldKeyForTenant).
+export async function setCustomFieldValue(
+  db: DbRunner,
+  tableName: string,
+  fieldKey: string,
+  value: unknown,
+  aggregateId: string,
+  tenantId: TenantId,
+): Promise<void> {
+  const tbl = quoteTable(tableName);
+  const escapedKey = fieldKey.replace(/'/g, "''");
+  const jsonb = bindJsonbParam(value);
+  await asRawClient(db).unsafe(
+    `UPDATE ${tbl} SET custom_fields = jsonb_set(custom_fields, '{${escapedKey}}', ${jsonb.sql}, true) WHERE id = $2 AND tenant_id = $3`,
+    [jsonb.bound, aggregateId, tenantId],
+  );
+}
+
+export async function clearCustomFieldKey(
+  db: DbRunner,
+  tableName: string,
+  fieldKey: string,
+  aggregateId: string,
+  tenantId: TenantId,
+): Promise<void> {
+  const tbl = quoteTable(tableName);
+  await asRawClient(db).unsafe(
+    `UPDATE ${tbl} SET custom_fields = custom_fields - $1 WHERE id = $2 AND tenant_id = $3`,
+    [fieldKey, aggregateId, tenantId],
+  );
+}
+
+// Tenant-scoped orphan-cleanup: removes the jsonb key only from the deleting
+// tenant's rows. This is the default path for tenant-field deletions — without
+// the tenant_id filter, deleting tenant A's field strips the same kebab key
+// from every tenant's rows (cross-tenant data loss).
+export async function removeCustomFieldKeyForTenant(
+  db: DbRunner,
+  tableName: string,
+  fieldKey: string,
+  tenantId: TenantId,
+): Promise<void> {
+  const tbl = quoteTable(tableName);
+  await asRawClient(db).unsafe(
+    `UPDATE ${tbl} SET custom_fields = custom_fields - $1 WHERE tenant_id = $2`,
+    [fieldKey, tenantId],
+  );
+}
+
+// Cross-tenant cleanup: strips the key from EVERY tenant's rows. Only valid for
+// system-scope field-definition deletions (the field applied to all tenants).
+// Never call this for a tenant-scoped deletion — use removeCustomFieldKeyForTenant.
+export async function removeCustomFieldKeyFromAllTenants(
+  db: DbRunner,
+  tableName: string,
+  fieldKey: string,
+): Promise<void> {
+  const tbl = quoteTable(tableName);
+  await asRawClient(db).unsafe(`UPDATE ${tbl} SET custom_fields = custom_fields - $1`, [fieldKey]);
+}

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

@@ -0,0 +1,20 @@
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+
+export async function countTenantFieldDefinitions(
+  runner: DbRunner,
+  tenantId: string,
+): Promise<number> {
+  // Active definitions only — delete soft-deletes (the deterministic stream is
+  // kept so a re-define can restore it), so isDeleted rows must not consume quota.
+  const rowsResult = await unsafeReadRetrying(
+    runner,
+    "SELECT COUNT(*)::int AS n FROM read_custom_field_definitions WHERE tenant_id = $1 AND is_deleted = FALSE",
+    [tenantId],
+  );
+  const rows = rowsResult as ReadonlyArray<Record<string, unknown>>; // @cast-boundary db-row
+  const first = rows[0];
+  if (!first) return 0;
+  const n = first["n"];
+  return typeof n === "number" ? n : Number.parseInt(String(n ?? 0), 10);
+}

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

@@ -0,0 +1,43 @@
+import { asRawClient, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+
+export async function selectHostRowsWithCustomFields(
+  db: DbRunner,
+  tableName: string,
+  tenantId: string,
+): Promise<readonly unknown[]> {
+  const quoted = `"${tableName.replace(/"/g, '""')}"`;
+  const rowsResult = await unsafeReadRetrying(
+    db,
+    `SELECT id, modified_at, custom_fields FROM ${quoted} WHERE tenant_id = $1 AND custom_fields IS NOT NULL`,
+    [tenantId],
+  );
+  return Array.isArray(rowsResult) ? rowsResult : [];
+}
+
+export async function applyRetentionRemovals(
+  db: DbRunner,
+  tableName: string,
+  deleteKeys: readonly string[],
+  anonymizeKeys: readonly string[],
+  rowId: string,
+): Promise<void> {
+  const quoted = `"${tableName.replace(/"/g, '""')}"`;
+  // Atomic per-row jsonb edit instead of read-modify-write of the whole
+  // object: delete-keys are dropped (`- $1::text[]`), anonymize-keys are set
+  // to JSON null via a merge patch. Operating on the live row value preserves
+  // a concurrent set-custom-field on any *other* key — no lost update.
+  await asRawClient(db).unsafe(
+    `UPDATE ${quoted} SET custom_fields = CASE
+       WHEN jsonb_typeof(custom_fields) = 'object' THEN
+         (custom_fields - $1::text[])
+         || COALESCE(
+              (SELECT jsonb_object_agg(k, 'null'::jsonb) FROM unnest($2::text[]) AS k),
+              '{}'::jsonb
+            )
+       ELSE custom_fields
+     END
+     WHERE id = $3`,
+    [deleteKeys, anonymizeKeys, rowId],
+  );
+}

package/packages/bundled-features/src/custom-fields/db/queries/user-data-rights.ts

@@ -0,0 +1,39 @@
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+
+function quoteTable(tableName: string): string {
+  return `"${tableName.replace(/"/g, '""')}"`;
+}
+
+function quoteColumn(columnName: string): string {
+  return `"${columnName.replace(/"/g, '""')}"`;
+}
+
+export async function selectCustomFieldsHostRows(
+  db: DbRunner,
+  tableName: string,
+  userIdColumn: string,
+  userId: string,
+  tenantId: string,
+): Promise<readonly unknown[]> {
+  const tbl = quoteTable(tableName);
+  const userCol = quoteColumn(userIdColumn);
+  const rowsResult = await unsafeReadRetrying(
+    db,
+    `SELECT id, custom_fields FROM ${tbl} WHERE ${userCol} = $1 AND tenant_id = $2`,
+    [userId, tenantId],
+  );
+  return Array.isArray(rowsResult) ? rowsResult : [];
+}
+
+export async function selectFieldDefinitionsForEntity(
+  db: DbRunner,
+  entityName: string,
+  tenantId: string,
+): Promise<readonly { field_key: string; serialized_field: unknown }[]> {
+  return unsafeReadRetrying(
+    db,
+    "SELECT field_key, serialized_field FROM read_custom_field_definitions WHERE entity_name = $1 AND tenant_id = $2",
+    [entityName, tenantId],
+  ) as Promise<readonly { field_key: string; serialized_field: unknown }[]>;
+}

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

@@ -0,0 +1,112 @@
+import {
+  createBooleanField,
+  createEntity,
+  createNumberField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// fieldDefinition — Tenant- oder 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).
+//
+// **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).
+//
+// **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).
+//
+// **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.
+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.",
+  // softDelete is required, NOT cosmetic: the aggregate-id is deterministic
+  // (uuidv5(tenantId|entityName|fieldKey)), so deleting a definition leaves a
+  // (created+deleted) event stream under that id. A hard delete would force the
+  // next define to create() at version 0 onto that stream → version_conflict —
+  // a deleted (entity, fieldKey) could never be re-defined. With softDelete the
+  // define handlers resurrect via restore()+update() (see define-or-resurrect).
+  // 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).
+  //
+  // 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).
+  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.
+    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.
+    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.
+    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: createBooleanField({ required: true }),
+
+    // Searchable-Flag — wenn true, contribuiert das Field zum Search-Doc
+    // via F3 search-payload-extension.
+    searchable: createBooleanField({ required: true }),
+
+    // UI-Display-Order. Tenant kann seine Felder via UI sortieren.
+    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.
+    serializedField: createTextField({
+      required: true,
+      maxLength: 65536,
+      personal: false,
+      reason: "technical_reference",
+    }),
+  },
+});

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

@@ -0,0 +1,25 @@
+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).
+//
+// 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).
+
+export const customFieldSetSchema = z.object({
+  fieldKey: z.string().min(1).max(64),
+  // Every set carries its value (custom fields hold no PII, #972) — 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.
+  value: z.unknown().optional(),
+});
+export type CustomFieldSetPayload = z.infer<typeof customFieldSetSchema>;
+
+export const customFieldClearedSchema = z.object({
+  fieldKey: z.string().min(1).max(64),
+});
+export type CustomFieldClearedPayload = z.infer<typeof customFieldClearedSchema>;

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

@@ -0,0 +1,10 @@
+import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
+import { fieldDefinitionEntity } from "./entity.js";
+
+// Single field-definition executor shared by the four define/delete handlers.
+// createEntityExecutor is side-effect-free; instantiating it once keeps the
+// table+executor pair in one place instead of rebuilding it per handler module.
+export const { executor: fieldDefinitionExecutor } = createEntityExecutor(
+  "field-definition",
+  fieldDefinitionEntity,
+);

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

@@ -0,0 +1,289 @@
+// custom-fields — Tenant- + System-scoped Custom-Field-Definitions +
+// generische Custom-Field-VALUE write-handler (host-stream-events).
+//
+// **Scope: supplemental business data, NO PII (#972).** Custom fields sind
+// für tenant-spezifische Zusatzinfos (Referenznummern, Flags, Kategorien) —
+// nicht für personenbezogene Daten. Das frühere `sensitive`-Flag wurde
+// entfernt; das Schema rejected es und `parseSerializedField` wirft auf
+// Alt-Definitionen. Werte stehen vollständig im Event-Log (rebuild-safe).
+// PII belongs in schema-entity fields with a `personal` annotation
+// (crypto-shredding, event ciphertext, forget pipeline).
+//
+// **Was diese Feature liefert (B1 + B2, 2026-05-23):**
+//   1. r.entity("field-definition") — Definition-Storage (event-sourced).
+//   2. define-tenant-field / define-system-field — RBAC write-handlers für
+//      Definition-CRUD.
+//   3. delete-tenant-field / delete-system-field — RBAC write-handlers.
+//   3b. update-tenant-field — Vollersatz-Edit (Bug-Bash D2); type immutable.
+//   4. set-custom-field / clear-custom-field — write-handlers für VALUES.
+//      Emittieren customField.set/.cleared-Events auf host-aggregate-stream.
+//   5. r.defineEvent für customField.set/.cleared + fieldDefinition.deleted.
+//   6. r.extendsRegistrar("customFields") — registriert die extension-name
+//      damit consumer via r.useExtension("customFields", "<entity>") opt-in.
+//   7. defineEntityListHandler — read fieldDefinitions (B1-limit: nur tenant-
+//      scope; B2-todo: system+tenant UNION als custom query).
+//
+// **Consumer-side-Wiring** (siehe wire-for-entity.ts):
+//   Consumer ruft `wireCustomFieldsFor(r, entityName, entityTable)` auf —
+//   das registriert pro host-entity: useExtension + MSP (jsonb-projection)
+//   + postQuery-hook (flatten) + search-payload-extension.
+//
+// **Host-Entity-Requirement**:
+//   Consumer MUSS in der entity-definition eine `customFields`-Spalte als
+//   `customFieldsField()` (jsonb) deklarieren.
+//
+// **Exports-Pattern (2026-05-23 refactor)**:
+//   `customFieldsFeature.exports.{setEvent,clearedEvent,fieldDefinitionDeletedEvent}`
+//   liefern typed EventDef-handles. Handler + wire-for-entity nutzen
+//   `<event>.name` als compile-time-literal-typed qualified-string — keine
+//   hand-gebauten Template-Literals mehr (T1 hat den toKebab-collapse-drift
+//   aufgedeckt, siehe Memory feedback_event_def_exports_pattern).
+//
+// **Noch offen (future iterations)**:
+//   - Cross-scope-conflict-Detection (Tenant überschreibt system fieldKey)
+//   - Cross-Scope-Read-UNION (system + tenant fieldDefinitions in einem List)
+//   (cap-counter-quota → T1.5e, user-data-rights-anonymization → T1.5c,
+//    Value-Validation gegen serializedField → set-custom-field via fieldToZod —
+//    alle erledigt.)
+
+import {
+  defineEntityListHandler,
+  defineFeature,
+  type FeatureRegistrar,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import {
+  CUSTOM_FIELD_CLEARED_EVENT,
+  CUSTOM_FIELD_SET_EVENT,
+  CUSTOM_FIELDS_EXTENSION,
+  CUSTOM_FIELDS_FEATURE_NAME,
+  DEFAULT_FIELD_DEFINITION_LIST_ROLES,
+  FIELD_DEFINITION_DELETED_EVENT,
+} from "./constants.js";
+import { fieldDefinitionEntity } from "./entity.js";
+import { customFieldClearedSchema, customFieldSetSchema } from "./events.js";
+import {
+  clearCustomFieldHandler,
+  createClearCustomFieldHandler,
+} from "./handlers/clear-custom-field.write.js";
+import { defineSystemFieldHandler } from "./handlers/define-system-field.write.js";
+import {
+  createDefineTenantFieldHandler,
+  defineTenantFieldHandler,
+} from "./handlers/define-tenant-field.write.js";
+import { deleteSystemFieldHandler } from "./handlers/delete-system-field.write.js";
+import {
+  createDeleteTenantFieldHandler,
+  deleteTenantFieldHandler,
+} from "./handlers/delete-tenant-field.write.js";
+import {
+  createSetCustomFieldHandler,
+  setCustomFieldHandler,
+} from "./handlers/set-custom-field.write.js";
+import {
+  createUpdateTenantFieldHandler,
+  updateTenantFieldHandler,
+} from "./handlers/update-tenant-field.write.js";
+
+const fieldDefinitionDeletedSchema = z.object({
+  entityName: z.string(),
+  fieldKey: z.string(),
+  // Owning tenant of the deleted definition: a specific tenant for tenant-scope
+  // deletions, SYSTEM_TENANT_ID for system-scope. The cascade-MSP scopes its
+  // orphan-cleanup by this so a tenant deletion never touches other tenants'
+  // rows. Optional for backward-compat with events appended before this field
+  // existed — the MSP falls back to the event's stream tenantId.
+  tenantId: z.string().optional(),
+});
+
+// Handler-/Access-Varianten die zwischen Singleton und Options-Variante
+// differieren können. Alles andere registriert registerCustomFields für
+// beide identisch, damit ein neues Event/Handler nie still die
+// Options-Variante verfehlt.
+type RegisterVariant = {
+  readonly defineTenantHandler: WriteHandlerDef;
+  readonly updateTenantHandler: WriteHandlerDef;
+  readonly deleteTenantHandler: WriteHandlerDef;
+  readonly setHandler: WriteHandlerDef;
+  readonly clearHandler: WriteHandlerDef;
+  readonly fieldDefinitionListRoles: readonly string[];
+};
+
+// Shared registration body for both the singleton and the options-variant.
+function registerCustomFields(
+  r: FeatureRegistrar<typeof CUSTOM_FIELDS_FEATURE_NAME>,
+  variant: RegisterVariant,
+) {
+  r.describe(
+    "Tenant- and system-scoped custom field definitions with generic value storage on any host entity. Registers the `field-definition` entity (event-sourced CRUD via `define-tenant-field`, `define-system-field`, `update-tenant-field`, `delete-tenant-field`, `delete-system-field`) and two value write-handlers (`set-custom-field`, `clear-custom-field`) that emit `custom-fields:event:custom-field-set` / `custom-fields:event:custom-field-cleared` events on the host aggregate's stream. To attach custom fields to your own entity, call `wireCustomFieldsFor(r, entityName, entityTable)` in the host feature — this wires the JSONB projection, `postQuery` flattening hook, and search-payload extension. The host entity must declare a `customFieldsField()` JSONB column.",
+  );
+  r.uiHints({
+    displayLabel: "Custom Fields",
+    category: "data",
+    recommended: false,
+  });
+  r.entity("field-definition", fieldDefinitionEntity);
+
+  // Event-types — qualified als "custom-fields:event:<short-name>".
+  // Returned EventDefs liefern .name als compile-time literal-typed string,
+  // den Handler + MSP-keys konsumieren statt Template-Literal-Konstruktion.
+  // `value: z.unknown()` has no field-level schema to catalog under piiFields
+  // (event PII covers string fields only), so "no PII" is a convention here,
+  // not an enforced guarantee.
+  const setEvent = r.defineEvent(CUSTOM_FIELD_SET_EVENT, customFieldSetSchema, {
+    piiFields: "none",
+  });
+  const clearedEvent = r.defineEvent(CUSTOM_FIELD_CLEARED_EVENT, customFieldClearedSchema, {
+    piiFields: "none",
+  });
+  const fieldDefinitionDeletedEvent = r.defineEvent(
+    FIELD_DEFINITION_DELETED_EVENT,
+    fieldDefinitionDeletedSchema,
+    { piiFields: "none" },
+  );
+
+  // Extension-Registrar — registriert dass diese Extension existiert.
+  // Consumer-side: r.useExtension("customFields", "<entity>") MARKIERT
+  // opt-in, aber wired NICHTS automatisch. Consumer MUSS zusätzlich
+  // `wireCustomFieldsFor(r, entity, table)` aufrufen damit MSP +
+  // postQuery-hook + search-extension tatsächlich registriert werden.
+  // Empty-options-Pattern (`{}`) ist absichtlich — boot-time-onRegister-
+  // wiring würde Closure über Drizzle-Table benötigen, die der Consumer
+  // bei extendsRegistrar-Registration nicht kennt. Daher consumer-side
+  // explicit-wiring statt magic-auto-wiring.
+  r.extendsRegistrar(CUSTOM_FIELDS_EXTENSION, {});
+
+  // Definition-CRUD handlers (B1; update kam mit Bug-Bash D2 2026-06-08).
+  r.writeHandler(variant.defineTenantHandler);
+  r.writeHandler(defineSystemFieldHandler);
+  r.writeHandler(variant.updateTenantHandler);
+  r.writeHandler(variant.deleteTenantHandler);
+  r.writeHandler(deleteSystemFieldHandler);
+
+  // Value-write handlers (B2). Emittieren events auf host-aggregate-stream.
+  r.writeHandler(variant.setHandler);
+  r.writeHandler(variant.clearHandler);
+
+  // List-Query — tenant-scoped (B1-limit). Die CustomFieldsFormSection
+  // dispatcht diesen QN hart — Apps mit eigenem Rollen-Vokabular
+  // überschreiben die Rollen via fieldDefinitionListRoles.
+  r.queryHandler(
+    defineEntityListHandler("field-definition", fieldDefinitionEntity, {
+      access: { roles: variant.fieldDefinitionListRoles },
+      description:
+        "Lists the custom-field definitions of the caller's own tenant; use it to discover which extra fields an entity accepts before setting or clearing a value on it.",
+    }),
+  );
+
+  return { setEvent, clearedEvent, fieldDefinitionDeletedEvent };
+}
+
+// Singleton feature-definition mit typed exports. Handler + wire-for-entity
+// importieren diesen `customFieldsFeature` und greifen lazy in ihrer
+// runtime-arrow-fn auf `.exports.<event>.name` zu — der module-cycle
+// (feature.ts -> handlers/*.write.ts -> feature.ts) löst sich auf weil
+// kein top-level-access stattfindet.
+export const customFieldsFeature = defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r) =>
+  registerCustomFields(r, {
+    defineTenantHandler: defineTenantFieldHandler,
+    updateTenantHandler: updateTenantFieldHandler,
+    deleteTenantHandler: deleteTenantFieldHandler,
+    setHandler: setCustomFieldHandler,
+    clearHandler: clearCustomFieldHandler,
+    fieldDefinitionListRoles: DEFAULT_FIELD_DEFINITION_LIST_ROLES,
+  }),
+);
+
+export type CustomFieldsFeatureOptions = {
+  /** T1.5e: Quota für 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). */
+  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). */
+  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"])
+   *  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
+   *  system-scope is a separate trust boundary that must not become reachable
+   *  through a tenant role vocabulary. Also feeds into
+   *  resolveFieldDefinitionListRoles (below) so a definer without an explicit
+   *  fieldDefinitionListRoles override can still load the definitions they can
+   *  write — mirrors the valueWriteRoles → list-default inheritance. */
+  readonly fieldDefinitionWriteRoles?: readonly string[];
+};
+
+export function resolveFieldDefinitionListRoles(
+  opts: Pick<
+    CustomFieldsFeatureOptions,
+    "valueWriteRoles" | "fieldDefinitionListRoles" | "fieldDefinitionWriteRoles"
+  >,
+): readonly string[] {
+  if (opts.fieldDefinitionListRoles !== undefined) return opts.fieldDefinitionListRoles;
+  if (opts.valueWriteRoles === undefined && opts.fieldDefinitionWriteRoles === undefined) {
+    return DEFAULT_FIELD_DEFINITION_LIST_ROLES;
+  }
+  // The default stays in the union: with valueWriteRoles unset, TenantAdmin still
+  // saves values and must be able to load the FormSection.
+  return [
+    ...new Set([
+      ...(opts.valueWriteRoles ?? []),
+      ...(opts.fieldDefinitionWriteRoles ?? []),
+      ...DEFAULT_FIELD_DEFINITION_LIST_ROLES,
+    ]),
+  ];
+}
+
+// Backwards-compat-wrapper. Bestehende Caller (z.B. integration-tests,
+// host-apps) nutzen weiterhin `createCustomFieldsFeature()`. Returnt den
+// module-level-Singleton — kein neuer build pro Aufruf, was für consumer
+// nicht erkennbar ist (read-only inspection). Jede gesetzte Option baut
+// eine frische Feature-Definition mit den Varianten-Handlern.
+export function createCustomFieldsFeature(
+  opts: CustomFieldsFeatureOptions = {},
+): typeof customFieldsFeature {
+  const hasOptions =
+    opts.fieldDefinitionLimitPerTenant !== undefined ||
+    opts.valueWriteRoles !== undefined ||
+    opts.fieldDefinitionListRoles !== undefined ||
+    opts.fieldDefinitionWriteRoles !== undefined;
+  if (!hasOptions) {
+    return customFieldsFeature;
+  }
+  const limit = opts.fieldDefinitionLimitPerTenant;
+  const definitionWriteRoles = opts.fieldDefinitionWriteRoles;
+  return defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r) =>
+    registerCustomFields(r, {
+      defineTenantHandler:
+        limit !== undefined || definitionWriteRoles !== undefined
+          ? createDefineTenantFieldHandler({
+              fieldDefinitionLimitPerTenant: limit,
+              roles: definitionWriteRoles,
+            })
+          : defineTenantFieldHandler,
+      updateTenantHandler:
+        definitionWriteRoles !== undefined
+          ? createUpdateTenantFieldHandler({ roles: definitionWriteRoles })
+          : updateTenantFieldHandler,
+      deleteTenantHandler:
+        definitionWriteRoles !== undefined
+          ? createDeleteTenantFieldHandler({ roles: definitionWriteRoles })
+          : deleteTenantFieldHandler,
+      setHandler: createSetCustomFieldHandler(opts.valueWriteRoles),
+      clearHandler: createClearCustomFieldHandler(opts.valueWriteRoles),
+      fieldDefinitionListRoles: resolveFieldDefinitionListRoles(opts),
+    }),
+  );
+}