@cosmicdrift/kumiko-bundled-features 0.12.2 → 0.13.0

package/src/custom-fields/__tests__/user-data-rights.integration.ts

@@ -0,0 +1,290 @@
+// T1.5c — user-data-rights wiring for custom-fields.
+//
+// Verifies the full DSGVO loop for custom-field values on a user-owned
+// host entity:
+//
+//   * Export (Art. 15+20): every row owned by the user contributes its
+//     customFields jsonb into the user's export bundle under
+//     `<entity>.customFields`.
+//
+//   * Forget strategy=anonymize (Art. 17 with retention obligation):
+//     sensitive customFields keys are stripped from the jsonb; non-
+//     sensitive keys stay so co-tenants / co-authors keep useful data.
+//
+//   * Forget strategy=delete: no-op — the host entity's own user-data-
+//     rights hook handles the row delete, jsonb travels with the row.
+
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createEntityExecutor,
+  createTextField,
+  defineFeature,
+  EXT_USER_DATA,
+  type UserDataDeleteHook,
+  type UserDataExportHook,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createComplianceProfilesFeature } from "../../compliance-profiles";
+import { createDataRetentionFeature } from "../../data-retention";
+import { createSessionsFeature } from "../../sessions";
+import { createUserFeature, userEntity } from "../../user";
+import { createUserDataRightsFeature } from "../../user-data-rights";
+import { fieldDefinitionEntity } from "../entity";
+import { createCustomFieldsFeature } from "../feature";
+import { customFieldsField, wireCustomFieldsFor } from "../wire-for-entity";
+import { wireCustomFieldsUserDataRightsFor } from "../wire-user-data-rights";
+
+const propertyEntity = createEntity({
+  table: "read_t15c_properties",
+  fields: {
+    name: createTextField({ required: true }),
+    customFields: customFieldsField(),
+  },
+});
+const propertyTable = buildDrizzleTable("property", propertyEntity);
+
+// Host entity gets its own EXT_USER_DATA-registration too — that's the
+// canonical setup (host bundle handles row-anonymize/delete, custom-fields
+// adds its strip-sensitive-jsonb layer on top). Both hooks fire in the
+// same cleanup-run.
+const hostExportHook: UserDataExportHook = async (ctx) => {
+  const rows = await ctx.db.execute(sql`
+    SELECT id, name FROM read_t15c_properties
+    WHERE inserted_by_id = ${ctx.userId} AND tenant_id = ${ctx.tenantId}
+  `);
+  const list = rows as ReadonlyArray<Record<string, unknown>>;
+  if (list.length === 0) return null;
+  return {
+    entity: "property",
+    rows: list.map((r) => ({ id: r["id"] as string, name: r["name"] as string })),
+  };
+};
+
+const hostDeleteHook: UserDataDeleteHook = async (ctx, strategy) => {
+  if (strategy === "delete") {
+    await ctx.db.execute(sql`
+      DELETE FROM read_t15c_properties
+      WHERE inserted_by_id = ${ctx.userId} AND tenant_id = ${ctx.tenantId}
+    `);
+  } else {
+    // anonymize: clear owner, keep row + non-sensitive customFields
+    await ctx.db.execute(sql`
+      UPDATE read_t15c_properties SET inserted_by_id = NULL
+      WHERE inserted_by_id = ${ctx.userId} AND tenant_id = ${ctx.tenantId}
+    `);
+  }
+};
+
+const propertyFeature = defineFeature("property-t15c", (r) => {
+  r.entity("property", propertyEntity);
+  r.requires("custom-fields");
+  wireCustomFieldsFor(r, "property", propertyTable);
+  wireCustomFieldsUserDataRightsFor(r, {
+    entityName: "property",
+    entityTable: propertyTable,
+    userIdColumn: "inserted_by_id",
+  });
+  r.useExtension(EXT_USER_DATA, "property", {
+    export: hostExportHook,
+    delete: hostDeleteHook,
+  });
+
+  const { executor } = createEntityExecutor("property", propertyEntity);
+  r.writeHandler({
+    name: "property:create",
+    schema: z.object({ id: z.string(), name: z.string() }),
+    access: { roles: ["TenantAdmin", "TenantMember"] },
+    handler: async (event, ctx) =>
+      executor.create(
+        { id: event.payload.id, name: event.payload.name, customFields: {} },
+        event.user,
+        ctx.db,
+      ),
+  });
+});
+
+const customFieldsFeature = createCustomFieldsFeature();
+const admin = createTestUser({ id: 1, roles: ["TenantAdmin"] });
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createUserFeature(),
+      createSessionsFeature(),
+      createDataRetentionFeature(),
+      createComplianceProfilesFeature(),
+      customFieldsFeature,
+      createUserDataRightsFeature(),
+      propertyFeature,
+    ],
+  });
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, fieldDefinitionEntity);
+  await unsafeCreateEntityTable(stack.db, propertyEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await resetEventStore(stack);
+  await stack.db.execute(sql`DELETE FROM read_t15c_properties`);
+  await stack.db.execute(sql`DELETE FROM read_custom_field_definitions`);
+});
+
+async function defineField(fieldKey: string, serializedField: Record<string, unknown>) {
+  return stack.http.writeOk(
+    "custom-fields:write:define-tenant-field",
+    {
+      entityName: "property",
+      fieldKey,
+      serializedField,
+      required: false,
+      searchable: false,
+      displayOrder: 0,
+    },
+    admin,
+  );
+}
+
+async function createProperty(id: string, name: string) {
+  return stack.http.writeOk("property-t15c:write:property:create", { id, name }, admin);
+}
+
+async function setField(entityId: string, fieldKey: string, value: unknown) {
+  return stack.http.writeOk(
+    "custom-fields:write:set-custom-field",
+    { entityName: "property", entityId, fieldKey, value },
+    admin,
+  );
+}
+
+async function readRow(id: string): Promise<Record<string, unknown> | undefined> {
+  const rows = await stack.db.execute(
+    sql`SELECT id, custom_fields FROM read_t15c_properties WHERE id = ${id}`,
+  );
+  const list = rows as ReadonlyArray<Record<string, unknown>>;
+  return list[0];
+}
+
+async function callExportHook(userId: string, tenantId: string) {
+  const usages = stack.registry.getExtensionUsages(EXT_USER_DATA);
+  const customFieldsUsage = usages.find(
+    (u) =>
+      u.entityName === "property" &&
+      (u.options as { export?: unknown })?.export &&
+      u.options !== undefined &&
+      (u.options as Record<string, unknown>)["export"] !== hostExportHook,
+  );
+  if (!customFieldsUsage) throw new Error("custom-fields user-data-rights export hook not found");
+  const hook = (customFieldsUsage.options as { export: UserDataExportHook }).export;
+  return hook({ db: stack.db, tenantId, userId });
+}
+
+async function callDeleteHook(userId: string, tenantId: string, strategy: "anonymize" | "delete") {
+  const usages = stack.registry.getExtensionUsages(EXT_USER_DATA);
+  const customFieldsUsage = usages.find(
+    (u) =>
+      u.entityName === "property" &&
+      (u.options as { delete?: unknown })?.delete &&
+      u.options !== undefined &&
+      (u.options as Record<string, unknown>)["delete"] !== hostDeleteHook,
+  );
+  if (!customFieldsUsage) throw new Error("custom-fields user-data-rights delete hook not found");
+  const hook = (customFieldsUsage.options as { delete: UserDataDeleteHook }).delete;
+  return hook({ db: stack.db, tenantId, userId }, strategy);
+}
+
+describe("T1.5c: user-data-rights wiring for custom-fields", () => {
+  test("export: customFields jsonb travels into the user's export snippet", async () => {
+    const propertyId = "11111111-1111-4000-8000-000000000001";
+    await defineField("email", { type: "text", sensitive: true });
+    await defineField("vipFlag", { type: "boolean" });
+    await createProperty(propertyId, "Hofgarten 12");
+    await setField(propertyId, "email", "alice@example.com");
+    await setField(propertyId, "vipFlag", true);
+    await stack.eventDispatcher?.runOnce();
+
+    const snippet = await callExportHook(String(admin.id), admin.tenantId);
+    expect(snippet).not.toBeNull();
+    expect(snippet?.entity).toBe("property.customFields");
+    expect(snippet?.rows).toHaveLength(1);
+    expect(snippet?.rows[0]?.["customFields"]).toMatchObject({
+      email: "alice@example.com",
+      vipFlag: true,
+    });
+  });
+
+  test("forget anonymize: sensitive keys stripped, non-sensitive keys kept", async () => {
+    const propertyId = "22222222-2222-4000-8000-000000000002";
+    await defineField("email", { type: "text", sensitive: true });
+    await defineField("vipFlag", { type: "boolean" });
+    await createProperty(propertyId, "Anonymize-Me");
+    await setField(propertyId, "email", "alice@example.com");
+    await setField(propertyId, "vipFlag", true);
+    await stack.eventDispatcher?.runOnce();
+
+    await callDeleteHook(String(admin.id), admin.tenantId, "anonymize");
+
+    const row = await readRow(propertyId);
+    const customFields = row?.["custom_fields"] as Record<string, unknown> | undefined;
+    expect(customFields).toBeDefined();
+    expect(customFields).not.toHaveProperty("email");
+    expect(customFields).toMatchObject({ vipFlag: true });
+  });
+
+  test("forget delete: no-op on customFields (host hook removes the row)", async () => {
+    const propertyId = "33333333-3333-4000-8000-000000000003";
+    await defineField("email", { type: "text", sensitive: true });
+    await createProperty(propertyId, "Delete-Me");
+    await setField(propertyId, "email", "alice@example.com");
+    await stack.eventDispatcher?.runOnce();
+
+    // call only the custom-fields delete hook (strategy=delete) — verify
+    // it doesn't mutate the row (the host hook would handle the actual
+    // row delete; we're proving custom-fields stays out of the way).
+    await callDeleteHook(String(admin.id), admin.tenantId, "delete");
+
+    const row = await readRow(propertyId);
+    const customFields = row?.["custom_fields"] as Record<string, unknown> | undefined;
+    expect(customFields).toMatchObject({ email: "alice@example.com" });
+  });
+
+  test("export: rows without customFields are not included in the snippet", async () => {
+    const propertyId = "44444444-4444-4000-8000-000000000004";
+    await createProperty(propertyId, "NoCustomFields");
+
+    const snippet = await callExportHook(String(admin.id), admin.tenantId);
+    expect(snippet).toBeNull();
+  });
+
+  test("anonymize without sensitive fields defined is a no-op (everything kept)", async () => {
+    const propertyId = "55555555-5555-4000-8000-000000000005";
+    await defineField("nonSensitive", { type: "text" });
+    await createProperty(propertyId, "AllStay");
+    await setField(propertyId, "nonSensitive", "still-here");
+    await stack.eventDispatcher?.runOnce();
+
+    await callDeleteHook(String(admin.id), admin.tenantId, "anonymize");
+
+    const row = await readRow(propertyId);
+    expect((row?.["custom_fields"] as Record<string, unknown>)?.["nonSensitive"]).toBe(
+      "still-here",
+    );
+  });
+});

package/src/custom-fields/__tests__/wire-for-entity.test.ts

@@ -0,0 +1,123 @@
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { describe, expect, test } from "vitest";
+import { customFieldsField, wireCustomFieldsFor } from "../wire-for-entity";
+
+// B2 wireCustomFieldsFor: einziger Aufruf registriert MSP + postQuery-hook +
+// search-payload-extension + useExtension-Marker. Tests pinnen die Surface
+// — Integration via setupTestStack kommt im T1 sprint.
+
+const propertyEntity = createEntity({
+  table: "read_test_properties",
+  fields: {
+    name: createTextField({ required: true }),
+    customFields: customFieldsField(),
+  },
+});
+
+const propertyTable = buildDrizzleTable("property", propertyEntity);
+
+describe("wireCustomFieldsFor", () => {
+  test("registers useExtension + MSP + postQuery-entity-hook + search-payload-extension", () => {
+    const feature = defineFeature("test-property", (r) => {
+      r.entity("property", propertyEntity);
+      wireCustomFieldsFor(r, "property", propertyTable);
+    });
+
+    // 1. useExtension registered
+    expect(feature.extensionUsages).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          extensionName: "customFields",
+          entityName: "property",
+        }),
+      ]),
+    );
+
+    // 2. MSP registered with the right name
+    expect(Object.keys(feature.multiStreamProjections)).toEqual(
+      expect.arrayContaining(["custom-fields-property-projection"]),
+    );
+
+    // 3. postQuery entity-hook on "property"
+    expect(feature.entityHooks.postQuery["property"]).toHaveLength(1);
+
+    // 4. search-payload-extension on "property"
+    expect(feature.searchPayloadExtensions["property"]).toHaveLength(1);
+  });
+
+  test("postQuery-hook flattens row.customFields onto root", async () => {
+    const feature = defineFeature("test-property", (r) => {
+      r.entity("property", propertyEntity);
+      wireCustomFieldsFor(r, "property", propertyTable);
+    });
+
+    const hook = feature.entityHooks.postQuery["property"]?.[0]?.fn;
+    expect(hook).toBeDefined();
+    const result = await hook?.(
+      {
+        entityName: "property",
+        rows: [
+          {
+            id: "p1",
+            name: "Hofgarten",
+            customFields: { internalNumber: "X-42", vipFlag: true },
+          },
+        ],
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      {} as never,
+    );
+    expect(result?.rows[0]).toMatchObject({
+      id: "p1",
+      name: "Hofgarten",
+      internalNumber: "X-42",
+      vipFlag: true,
+    });
+  });
+
+  test("postQuery-hook handles missing/invalid customFields gracefully", async () => {
+    const feature = defineFeature("test-property", (r) => {
+      r.entity("property", propertyEntity);
+      wireCustomFieldsFor(r, "property", propertyTable);
+    });
+
+    const hook = feature.entityHooks.postQuery["property"]?.[0]?.fn;
+    const result = await hook?.(
+      {
+        entityName: "property",
+        rows: [
+          { id: "p1", name: "NoCustomFields" }, // missing customFields
+          { id: "p2", name: "WithEmpty", customFields: {} },
+          { id: "p3", name: "WithNull", customFields: null },
+        ],
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      {} as never,
+    );
+    expect(result?.rows).toHaveLength(3);
+    expect(result?.rows[0]).toMatchObject({ id: "p1", name: "NoCustomFields" });
+    expect(result?.rows[1]).toMatchObject({ id: "p2", name: "WithEmpty" });
+    expect(result?.rows[2]).toMatchObject({ id: "p3", name: "WithNull" });
+  });
+
+  test("search-payload-extension returns customFields keys flat", async () => {
+    const feature = defineFeature("test-property", (r) => {
+      r.entity("property", propertyEntity);
+      wireCustomFieldsFor(r, "property", propertyTable);
+    });
+
+    const contributor = feature.searchPayloadExtensions["property"]?.[0]?.fn;
+    expect(contributor).toBeDefined();
+    const result = await contributor?.({
+      entityName: "property",
+      entityId: "p1",
+      state: {
+        id: "p1",
+        name: "Hofgarten",
+        customFields: { internalNumber: "X-42", vipFlag: true },
+      },
+    });
+    expect(result).toEqual({ internalNumber: "X-42", vipFlag: true });
+  });
+});

package/src/custom-fields/constants.ts

@@ -6,10 +6,25 @@
 export const CUSTOM_FIELDS_FEATURE_NAME = "custom-fields";
 
 // Event-Type-Names (qualified at registration via r.defineEvent — final
-// names are `custom-fields:event:field-definition.created` etc.).
-export const FIELD_DEFINITION_CREATED_EVENT = "field-definition.created";
-export const FIELD_DEFINITION_UPDATED_EVENT = "field-definition.updated";
-export const FIELD_DEFINITION_DELETED_EVENT = "field-definition.deleted";
+// names are `custom-fields:event:field-definition-created` etc.).
+// Short-names MUST be in kebab-case (no dots): qualifyEntityName runs toKebab
+// which collapses dots to dashes, so a dotted short-name diverges from the
+// registry key when handlers hand-build the qualified string.
+export const FIELD_DEFINITION_CREATED_EVENT = "field-definition-created";
+export const FIELD_DEFINITION_UPDATED_EVENT = "field-definition-updated";
+export const FIELD_DEFINITION_DELETED_EVENT = "field-definition-deleted";
+
+// Custom-field-VALUE events. Live auf host-aggregate stream (ES-Option-B).
+// Short-names werden via r.defineEvent qualified zu `custom-fields:event:
+// custom-field-set` etc. (qualifyEntityName runs toKebab which collapses dots
+// to dashes — so the short-name MUST already be in dash form, otherwise
+// handler-built strings won't match the registry key).
+export const CUSTOM_FIELD_SET_EVENT = "custom-field-set";
+export const CUSTOM_FIELD_CLEARED_EVENT = "custom-field-cleared";
+
+// Extension-name für r.useExtension("customFields", "<entity>") — registriert
+// dass eine host-entity Custom-Fields haben darf.
+export const CUSTOM_FIELDS_EXTENSION = "customFields";
 
 // Field-type union — identisch zu Stammfeld-Field-Type-System (Spec Z.59-73:
 // `Identisch zu Entity-Feld-Typen`). Builder-Reuse-Promise: was `r.field.X()`

package/src/custom-fields/events.ts

@@ -0,0 +1,21 @@
+import { 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),
+  value: z.unknown(),
+});
+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/src/custom-fields/feature.ts

@@ -1,54 +1,160 @@
-// custom-fields — Tenant- + System-scoped Custom-Field-Definitions.
+// custom-fields — Tenant- + System-scoped Custom-Field-Definitions +
+// generische Custom-Field-VALUE write-handler (host-stream-events).
 //
-// **Was diese Feature liefert (B1, 2026-05-22):**
+// **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 — write-handlers (RBAC).
-//   3. delete-tenant-field / delete-system-field — write-handlers (RBAC).
-//   4. defineEntityListHandler — read alle Definitionen des current-tenants
-//      (B1 limitation: nur tenant-scope; B2 wird system+tenant UNION
-//      ergänzen).
+//   2. define-tenant-field / define-system-field — RBAC write-handlers für
+//      Definition-CRUD.
+//   3. delete-tenant-field / delete-system-field — RBAC write-handlers.
+//   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).
 //
-// **Was B2 ergänzen wird:**
-//   - customField.set / customField.cleared Event-Types
-//   - MSP für value-projection in read_<entity>.customFields jsonb
-//   - r.extendsRegistrar("customFields", ...) + onRegister-Wiring
-//   - F1 postQuery / F3 search-payload-extension contributors
-//   - Cross-scope-conflict-Detection (tenant darf system-fieldKey nicht
-//     überschreiben)
-//   - user-data-rights anonymization-Wiring für sensitive customFields
-//   - cap-counter wiring im fieldDefinition-create-Handler
+// **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).
 //
-// **Out-of-Scope (Plan-Doc v2):**
-//   - Tenant-Admin UI (Post-Todo, Phase β)
-//   - In-place type-change auf existing fieldDefinition — caller must
-//     DELETE + CREATE (Plan-Doc v2 B1.8 "Type-Change-Lock v1")
+// **Out-of-B2 (future iterations)**:
+//   - Cross-scope-conflict-Detection (Tenant überschreibt system fieldKey)
+//   - cap-counter quota-Check beim fieldDefinition-create
+//   - user-data-rights anonymization-Wiring für sensitive customFields
+//   - Value-Validation gegen fieldDefinition.serializedField
+//   - Cross-Scope-Read-UNION (system + tenant fieldDefinitions in einem List)
 
 import { defineEntityListHandler, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
-import { CUSTOM_FIELDS_FEATURE_NAME } from "./constants";
+import { z } from "zod";
+import {
+  CUSTOM_FIELD_CLEARED_EVENT,
+  CUSTOM_FIELD_SET_EVENT,
+  CUSTOM_FIELDS_EXTENSION,
+  CUSTOM_FIELDS_FEATURE_NAME,
+  FIELD_DEFINITION_DELETED_EVENT,
+} from "./constants";
 import { fieldDefinitionEntity } from "./entity";
+import { customFieldClearedSchema, customFieldSetSchema } from "./events";
+import { clearCustomFieldHandler } from "./handlers/clear-custom-field.write";
 import { defineSystemFieldHandler } from "./handlers/define-system-field.write";
-import { defineTenantFieldHandler } from "./handlers/define-tenant-field.write";
+import {
+  createDefineTenantFieldHandler,
+  defineTenantFieldHandler,
+} from "./handlers/define-tenant-field.write";
 import { deleteSystemFieldHandler } from "./handlers/delete-system-field.write";
 import { deleteTenantFieldHandler } from "./handlers/delete-tenant-field.write";
+import { setCustomFieldHandler } from "./handlers/set-custom-field.write";
 
 const tenantAdminAccess = { access: { roles: ["TenantAdmin"] } } as const;
 
-export function createCustomFieldsFeature() {
+const fieldDefinitionDeletedSchema = z.object({
+  entityName: z.string(),
+  fieldKey: z.string(),
+});
+
+// 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) => {
+  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.
+  const setEvent = r.defineEvent(CUSTOM_FIELD_SET_EVENT, customFieldSetSchema);
+  const clearedEvent = r.defineEvent(CUSTOM_FIELD_CLEARED_EVENT, customFieldClearedSchema);
+  const fieldDefinitionDeletedEvent = r.defineEvent(
+    FIELD_DEFINITION_DELETED_EVENT,
+    fieldDefinitionDeletedSchema,
+  );
+
+  // 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).
+  r.writeHandler(defineTenantFieldHandler);
+  r.writeHandler(defineSystemFieldHandler);
+  r.writeHandler(deleteTenantFieldHandler);
+  r.writeHandler(deleteSystemFieldHandler);
+
+  // Value-write handlers (B2). Emittieren events auf host-aggregate-stream.
+  r.writeHandler(setCustomFieldHandler);
+  r.writeHandler(clearCustomFieldHandler);
+
+  // List-Query — tenant-scoped (B1-limit).
+  r.queryHandler(
+    defineEntityListHandler("field-definition", fieldDefinitionEntity, tenantAdminAccess),
+  );
+
+  return { setEvent, clearedEvent, fieldDefinitionDeletedEvent };
+});
+
+// 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).
+//
+// **T1.5e options**: when `fieldDefinitionLimitPerTenant` is set, the
+// returned feature carries a fresh `define-tenant-field` handler with the
+// quota baked in. Callers that don't pass options get the singleton — no
+// change in behavior.
+export function createCustomFieldsFeature(
+  opts: { readonly fieldDefinitionLimitPerTenant?: number } = {},
+): typeof customFieldsFeature {
+  if (opts.fieldDefinitionLimitPerTenant === undefined) {
+    return customFieldsFeature;
+  }
   return defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r) => {
     r.entity("field-definition", fieldDefinitionEntity);
 
-    // Write-Handlers — tenant + system Scope getrennt durch dedicated Handlers
-    // mit unterschiedlichen access-rules.
-    r.writeHandler(defineTenantFieldHandler);
+    const setEvent = r.defineEvent(CUSTOM_FIELD_SET_EVENT, customFieldSetSchema);
+    const clearedEvent = r.defineEvent(CUSTOM_FIELD_CLEARED_EVENT, customFieldClearedSchema);
+    const fieldDefinitionDeletedEvent = r.defineEvent(
+      FIELD_DEFINITION_DELETED_EVENT,
+      fieldDefinitionDeletedSchema,
+    );
+
+    r.extendsRegistrar(CUSTOM_FIELDS_EXTENSION, {});
+
+    r.writeHandler(
+      createDefineTenantFieldHandler({
+        fieldDefinitionLimitPerTenant: opts.fieldDefinitionLimitPerTenant,
+      }),
+    );
     r.writeHandler(defineSystemFieldHandler);
     r.writeHandler(deleteTenantFieldHandler);
     r.writeHandler(deleteSystemFieldHandler);
 
-    // List-Query — tenant kann seine eigenen Definitionen sehen. B2 wird
-    // einen Custom-Query mit UNION über (current-tenant ∪ SYSTEM_TENANT_ID)
-    // ergänzen.
+    r.writeHandler(setCustomFieldHandler);
+    r.writeHandler(clearCustomFieldHandler);
+
     r.queryHandler(
       defineEntityListHandler("field-definition", fieldDefinitionEntity, tenantAdminAccess),
     );
+
+    return { setEvent, clearedEvent, fieldDefinitionDeletedEvent };
   });
 }