@cosmicdrift/kumiko-bundled-features 0.11.1 → 0.12.1

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @cosmicdrift/kumiko-bundled-features
 
+## 0.12.1
+
+### Patch Changes
+
+- Updated dependencies [f2ad7c4]
+  - @cosmicdrift/kumiko-framework@0.12.1
+  - @cosmicdrift/kumiko-renderer@0.12.1
+  - @cosmicdrift/kumiko-dispatcher-live@0.12.1
+  - @cosmicdrift/kumiko-renderer-web@0.12.1
+
+## 0.12.0
+
+### Minor Changes
+
+- 0c1ebe5: Add `@cosmicdrift/kumiko-bundled-features/custom-fields` — B1 phase of the custom-fields-bundle Sprint.
+
+  **Contents:**
+
+  - `fieldDefinition` entity (event-sourced) — stores tenant-scoped and system-scoped (`tenantId = SYSTEM_TENANT_ID`) custom-field definitions side-by-side
+  - 4 write-handlers: `define-tenant-field` (TenantAdmin), `define-system-field` (SystemAdmin), `delete-tenant-field`, `delete-system-field`
+  - 1 query-handler: list (tenant-scoped; B2 will add system+tenant UNION resolution)
+  - Deterministic aggregate-id from `(tenantId, entityName, fieldKey)` — same-scope conflicts surface naturally as `version_conflict`
+  - Builder-Reuse-ready: `serializedField` jsonb stores the dehydrated field-builder-options; B2 will rehydrate for value-validation against `customField.set` events
+
+  **Not in B1 (deferred to B2):**
+
+  - Event-types `customField.set` / `customField.cleared`
+  - MSP for value-projection in `read_<entity>.customFields` jsonb
+  - Schema-Migration trigger for jsonb-column on host-entities
+  - `r.extendsRegistrar("customFields", ...)` + onRegister wiring
+  - F1 postQuery + F3 search-payload-extension integration
+  - Cross-scope-conflict (tenant trying to override system fieldKey)
+  - user-data-rights anonymization wiring
+  - cap-counter quota wiring on define
+  - In-place type-change-lock (DELETE+CREATE workaround for v1)
+
+  Part of custom-fields-bundle Sprint Phase B1.
+
+### Patch Changes
+
+- @cosmicdrift/kumiko-framework@0.12.0
+- @cosmicdrift/kumiko-dispatcher-live@0.12.0
+- @cosmicdrift/kumiko-renderer@0.12.0
+- @cosmicdrift/kumiko-renderer-web@0.12.0
+
+## 0.11.2
+
+### Patch Changes
+
+- Updated dependencies [92a84f0]
+  - @cosmicdrift/kumiko-framework@0.11.2
+  - @cosmicdrift/kumiko-renderer@0.11.2
+  - @cosmicdrift/kumiko-dispatcher-live@0.11.2
+  - @cosmicdrift/kumiko-renderer-web@0.11.2
+
 ## 0.11.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.11.1",
+  "version": "0.12.1",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -25,6 +25,7 @@
     "./jobs": "./src/jobs/index.ts",
     "./tier-engine": "./src/tier-engine/index.ts",
     "./cap-counter": "./src/cap-counter/index.ts",
+    "./custom-fields": "./src/custom-fields/index.ts",
     "./billing-foundation": "./src/billing-foundation/index.ts",
     "./subscription-stripe": "./src/subscription-stripe/index.ts",
     "./subscription-mollie": "./src/subscription-mollie/index.ts",
@@ -74,10 +75,10 @@
     "@aws-sdk/client-s3": "^3.1045.0",
     "@aws-sdk/lib-storage": "^3.1045.0",
     "@aws-sdk/s3-request-presigner": "^3.1045.0",
-    "@cosmicdrift/kumiko-dispatcher-live": "0.11.1",
-    "@cosmicdrift/kumiko-framework": "0.11.1",
-    "@cosmicdrift/kumiko-renderer": "0.11.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.11.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.12.1",
+    "@cosmicdrift/kumiko-framework": "0.12.1",
+    "@cosmicdrift/kumiko-renderer": "0.12.1",
+    "@cosmicdrift/kumiko-renderer-web": "0.12.1",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

package/src/custom-fields/__tests__/feature.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, test } from "vitest";
+import { fieldDefinitionAggregateId } from "../aggregate-id";
+import { SUPPORTED_FIELD_TYPES } from "../constants";
+import { createCustomFieldsFeature } from "../feature";
+import { defineFieldPayloadSchema, deleteFieldPayloadSchema } from "../schemas";
+
+// B1 unit-tests: feature-shape, schema-validation, aggregate-id determinism.
+// Integration tests (full-stack via setupTestStack) kommen in B2 wenn der
+// MSP + Read-Pipeline da ist — die testen ES-Loop end-to-end.
+
+describe("createCustomFieldsFeature shape", () => {
+  test("registers field-definition entity + 4 write-handlers + 1 query-handler", () => {
+    const feature = createCustomFieldsFeature();
+
+    expect(Object.keys(feature.entities)).toContain("field-definition");
+
+    const writeHandlerNames = Object.keys(feature.writeHandlers);
+    expect(writeHandlerNames).toEqual(
+      expect.arrayContaining([
+        expect.stringMatching(/define-tenant-field/),
+        expect.stringMatching(/define-system-field/),
+        expect.stringMatching(/delete-tenant-field/),
+        expect.stringMatching(/delete-system-field/),
+      ]),
+    );
+
+    expect(Object.keys(feature.queryHandlers)).toHaveLength(1);
+  });
+});
+
+describe("defineFieldPayloadSchema", () => {
+  test("accepts minimal payload with text field", () => {
+    const result = defineFieldPayloadSchema.safeParse({
+      entityName: "customer",
+      fieldKey: "internalNumber",
+      serializedField: { type: "text", required: true, maxLength: 50 },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("rejects fieldKey with invalid chars", () => {
+    const result = defineFieldPayloadSchema.safeParse({
+      entityName: "customer",
+      fieldKey: "9starts-with-digit",
+      serializedField: { type: "text" },
+    });
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects unknown field-type", () => {
+    const result = defineFieldPayloadSchema.safeParse({
+      entityName: "customer",
+      fieldKey: "weird",
+      serializedField: { type: "unknown-type" },
+    });
+    expect(result.success).toBe(false);
+  });
+
+  test("accepts all SUPPORTED_FIELD_TYPES", () => {
+    for (const type of SUPPORTED_FIELD_TYPES) {
+      const result = defineFieldPayloadSchema.safeParse({
+        entityName: "thing",
+        fieldKey: "f",
+        serializedField: { type },
+      });
+      expect(result.success).toBe(true);
+    }
+  });
+
+  test("accepts i18n-label", () => {
+    const result = defineFieldPayloadSchema.safeParse({
+      entityName: "customer",
+      fieldKey: "vipLevel",
+      serializedField: { type: "enum", values: ["bronze", "silver", "gold"] },
+      label: { de: "VIP-Stufe", en: "VIP Level" },
+    });
+    expect(result.success).toBe(true);
+  });
+});
+
+describe("deleteFieldPayloadSchema", () => {
+  test("accepts minimal payload", () => {
+    const result = deleteFieldPayloadSchema.safeParse({
+      entityName: "customer",
+      fieldKey: "internalNumber",
+    });
+    expect(result.success).toBe(true);
+  });
+});
+
+describe("fieldDefinitionAggregateId determinism", () => {
+  test("same inputs produce same uuid", () => {
+    const id1 = fieldDefinitionAggregateId("t1", "customer", "internalNumber");
+    const id2 = fieldDefinitionAggregateId("t1", "customer", "internalNumber");
+    expect(id1).toBe(id2);
+  });
+
+  test("different tenants produce different uuids (scope-separation)", () => {
+    const idTenant = fieldDefinitionAggregateId("t1", "customer", "internalNumber");
+    const idSystem = fieldDefinitionAggregateId(
+      "00000000-0000-0000-0000-000000000000",
+      "customer",
+      "internalNumber",
+    );
+    expect(idTenant).not.toBe(idSystem);
+  });
+
+  test("different fieldKey on same entity produces different uuids", () => {
+    const idA = fieldDefinitionAggregateId("t1", "customer", "internalNumber");
+    const idB = fieldDefinitionAggregateId("t1", "customer", "vipFlag");
+    expect(idA).not.toBe(idB);
+  });
+
+  test("aggregate-id format is a valid uuid", () => {
+    const id = fieldDefinitionAggregateId("t1", "customer", "internalNumber");
+    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  });
+});

package/src/custom-fields/aggregate-id.ts

@@ -0,0 +1,33 @@
+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.
+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.
+ *
+ * **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
+ *     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.
+ */
+export function fieldDefinitionAggregateId(
+  tenantId: string,
+  entityName: string,
+  fieldKey: string,
+): string {
+  return uuidv5(`${tenantId}|${entityName}|${fieldKey}`, FIELD_DEFINITION_NAMESPACE);
+}

package/src/custom-fields/constants.ts

@@ -0,0 +1,26 @@
+// custom-fields bundle constants — feature-name + event-names.
+//
+// Spec: kumiko-platform/docs/plans/features/custom-fields.md
+// Sprint plan: kumiko-platform/docs/plans/custom-fields-sprint.md
+
+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";
+
+// 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()`
+// kann, kann eine Custom-Field-Definition auch.
+export const SUPPORTED_FIELD_TYPES = [
+  "text",
+  "number",
+  "boolean",
+  "date",
+  "enum",
+  "money",
+  "embedded",
+] as const;
+export type SupportedFieldType = (typeof SUPPORTED_FIELD_TYPES)[number];

package/src/custom-fields/entity.ts

@@ -0,0 +1,83 @@
+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",
+  // 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). Strategy
+  // softDelete: row bleibt als marker, value-cleanup (in B2's MSP) macht
+  // die eigentliche Anonymisierung wenn customFields PII enthielten.
+  //
+  // 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 }),
+
+    // Field-Key (z.B. "internalNumber", "vipFlag") — kebab-case oder camelCase
+    // erlaubt; UI-rendering nutzt label statt fieldKey.
+    fieldKey: createTextField({ required: true, maxLength: 64 }),
+
+    // Field-Type aus dem SUPPORTED_FIELD_TYPES-Set. Validiert via Zod im
+    // write-handler.
+    type: createTextField({ required: true, maxLength: 16 }),
+
+    // 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 }),
+
+    // 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 }),
+  },
+});

package/src/custom-fields/feature.ts

@@ -0,0 +1,54 @@
+// custom-fields — Tenant- + System-scoped Custom-Field-Definitions.
+//
+// **Was diese Feature liefert (B1, 2026-05-22):**
+//   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).
+//
+// **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
+//
+// **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")
+
+import { defineEntityListHandler, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { CUSTOM_FIELDS_FEATURE_NAME } from "./constants";
+import { fieldDefinitionEntity } from "./entity";
+import { defineSystemFieldHandler } from "./handlers/define-system-field.write";
+import { defineTenantFieldHandler } from "./handlers/define-tenant-field.write";
+import { deleteSystemFieldHandler } from "./handlers/delete-system-field.write";
+import { deleteTenantFieldHandler } from "./handlers/delete-tenant-field.write";
+
+const tenantAdminAccess = { access: { roles: ["TenantAdmin"] } } as const;
+
+export function createCustomFieldsFeature() {
+  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);
+    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.queryHandler(
+      defineEntityListHandler("field-definition", fieldDefinitionEntity, tenantAdminAccess),
+    );
+  });
+}

package/src/custom-fields/handlers/define-system-field.write.ts

@@ -0,0 +1,59 @@
+import {
+  createEntityExecutor,
+  SYSTEM_TENANT_ID,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { fieldDefinitionAggregateId } from "../aggregate-id";
+import { fieldDefinitionEntity } from "../entity";
+import { type DefineFieldPayload, defineFieldPayloadSchema } from "../schemas";
+
+const { executor } = createEntityExecutor("field-definition", fieldDefinitionEntity);
+
+// define-system-field — SystemAdmin definiert eine system-weite Custom-Field-
+// Definition die für ALLE Tenants gilt. tenantId wird auf SYSTEM_TENANT_ID
+// gesetzt (NICHT vom Caller — SystemAdmin's event.user.tenantId würde sonst
+// auf den admin's eigenen platform-tenant zeigen).
+//
+// **Use-Case:** Vendor (cdgs) sagt "alle Hausverwaltungs-customers haben ab
+// heute ein `internalNumber`-Field". Tenant kann den Wert pro customer
+// setzen, aber die Definition nicht ändern oder löschen.
+//
+// **Same-scope-conflict** wie bei define-tenant-field via aggregate-version-
+// conflict (deterministische ID mit tenantId=SYSTEM_TENANT_ID).
+export const defineSystemFieldHandler: WriteHandlerDef = {
+  name: "define-system-field",
+  schema: defineFieldPayloadSchema,
+  access: { roles: ["SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const payload = event.payload as DefineFieldPayload; // @cast-boundary engine-payload
+
+    const aggregateId = fieldDefinitionAggregateId(
+      SYSTEM_TENANT_ID,
+      payload.entityName,
+      payload.fieldKey,
+    );
+
+    // Override event.user.tenantId to SYSTEM_TENANT_ID for the system-scope
+    // write. The framework's CrudExecutor writes the row with this tenantId
+    // — the row lives in the system-scope-stream.
+    const systemUser = { ...event.user, tenantId: SYSTEM_TENANT_ID };
+
+    return executor.create(
+      {
+        id: aggregateId,
+        entityName: payload.entityName,
+        fieldKey: payload.fieldKey,
+        type: payload.serializedField.type,
+        required: payload.required,
+        searchable: payload.searchable,
+        displayOrder: payload.displayOrder,
+        serializedField: JSON.stringify({
+          ...payload.serializedField,
+          label: payload.label,
+        }),
+      },
+      systemUser,
+      ctx.db,
+    );
+  },
+};

package/src/custom-fields/handlers/define-tenant-field.write.ts

@@ -0,0 +1,62 @@
+import {
+  createEntityExecutor,
+  isSystemTenant,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { fieldDefinitionAggregateId } from "../aggregate-id";
+import { fieldDefinitionEntity } from "../entity";
+import { type DefineFieldPayload, defineFieldPayloadSchema } from "../schemas";
+
+const { executor } = createEntityExecutor("field-definition", fieldDefinitionEntity);
+
+// define-tenant-field — TenantAdmin definiert eine Custom-Field-Definition
+// für seinen eigenen Tenant. tenantId wird automatisch aus event.user.tenantId
+// abgeleitet (NICHT vom Caller setzbar — verhindert Cross-Tenant-Mutation).
+//
+// **Same-scope-conflict** wird natürlich durch aggregate-version-conflict
+// enforced: deterministische aggregate-id aus uuidv5(tenant, entity, fieldKey)
+// macht einen zweiten Create auf dieselbe Definition ein version_conflict.
+// Dispatcher returnt 409. Saubere Idempotency-Garantie ohne extra DB-roundtrip.
+//
+// **Cross-scope-conflict** (tenant versucht fieldKey zu definieren der bereits
+// system-scope existiert) wird in B1 NICHT enforced — aggregate-ids
+// unterscheiden sich (verschiedene tenantIds in uuidv5), beide writes gehen
+// durch. Resolution beim Read (B2) zeigt dann den system-scope-Wert. v2
+// kann r.systemScope-Sub-Handler einführen um cross-scope-conflict am Write
+// abzulehnen.
+export const defineTenantFieldHandler: WriteHandlerDef = {
+  name: "define-tenant-field",
+  schema: defineFieldPayloadSchema,
+  access: { roles: ["TenantAdmin"] },
+  handler: async (event, ctx) => {
+    const payload = event.payload as DefineFieldPayload; // @cast-boundary engine-payload
+    const tenantId = event.user.tenantId;
+
+    // TenantAdmin darf NICHT system-scope schreiben — strict-guard.
+    if (isSystemTenant(tenantId)) {
+      throw new Error(
+        "define-tenant-field: tenantId is SYSTEM_TENANT_ID — use define-system-field for system-scope definitions",
+      );
+    }
+
+    const aggregateId = fieldDefinitionAggregateId(tenantId, payload.entityName, payload.fieldKey);
+
+    return executor.create(
+      {
+        id: aggregateId,
+        entityName: payload.entityName,
+        fieldKey: payload.fieldKey,
+        type: payload.serializedField.type,
+        required: payload.required,
+        searchable: payload.searchable,
+        displayOrder: payload.displayOrder,
+        serializedField: JSON.stringify({
+          ...payload.serializedField,
+          label: payload.label,
+        }),
+      },
+      event.user,
+      ctx.db,
+    );
+  },
+};

package/src/custom-fields/handlers/delete-system-field.write.ts

@@ -0,0 +1,33 @@
+import {
+  createEntityExecutor,
+  SYSTEM_TENANT_ID,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { fieldDefinitionAggregateId } from "../aggregate-id";
+import { fieldDefinitionEntity } from "../entity";
+import { type DeleteFieldPayload, deleteFieldPayloadSchema } from "../schemas";
+
+const { executor } = createEntityExecutor("field-definition", fieldDefinitionEntity);
+
+// delete-system-field — SystemAdmin entfernt eine system-weite Field-
+// Definition. Konsequenz: KEIN Tenant kann mehr neue Werte dafür setzen,
+// existing Werte in read_<entity>.customFields jsonb bleiben aber bestehen
+// (B2's MSP wird sie via customFieldDefinition.deleted-Event aufräumen).
+// Events bleiben für Audit.
+export const deleteSystemFieldHandler: WriteHandlerDef = {
+  name: "delete-system-field",
+  schema: deleteFieldPayloadSchema,
+  access: { roles: ["SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const payload = event.payload as DeleteFieldPayload; // @cast-boundary engine-payload
+
+    const aggregateId = fieldDefinitionAggregateId(
+      SYSTEM_TENANT_ID,
+      payload.entityName,
+      payload.fieldKey,
+    );
+
+    const systemUser = { ...event.user, tenantId: SYSTEM_TENANT_ID };
+    return executor.delete({ id: aggregateId }, systemUser, ctx.db);
+  },
+};

package/src/custom-fields/handlers/delete-tenant-field.write.ts

@@ -0,0 +1,40 @@
+import {
+  createEntityExecutor,
+  isSystemTenant,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { fieldDefinitionAggregateId } from "../aggregate-id";
+import { fieldDefinitionEntity } from "../entity";
+import { type DeleteFieldPayload, deleteFieldPayloadSchema } from "../schemas";
+
+const { executor } = createEntityExecutor("field-definition", fieldDefinitionEntity);
+
+// delete-tenant-field — TenantAdmin löscht eigene Field-Definition.
+// Spec-Promise (Plan-Doc v2 "wie Entity-Delete"): Events bleiben im event-
+// store für Audit-Trail. Read-Projection-Row wird entfernt. B2 wird die
+// Cleanup-Pipeline (`customFieldDefinition.deleted`-Event → MSP entfernt
+// values aus read_<entity>.customFields jsonb) wirklich wiren — in B1
+// kümmern wir uns nur um die Definition selbst.
+//
+// **Idempotency:** Delete auf nicht-existente Definition → version_conflict
+// (executor.delete returns failure, dispatcher 404/422). Caller sieht "not
+// found" — kein Crash.
+export const deleteTenantFieldHandler: WriteHandlerDef = {
+  name: "delete-tenant-field",
+  schema: deleteFieldPayloadSchema,
+  access: { roles: ["TenantAdmin"] },
+  handler: async (event, ctx) => {
+    const payload = event.payload as DeleteFieldPayload; // @cast-boundary engine-payload
+    const tenantId = event.user.tenantId;
+
+    if (isSystemTenant(tenantId)) {
+      throw new Error(
+        "delete-tenant-field: tenantId is SYSTEM_TENANT_ID — use delete-system-field for system-scope deletions",
+      );
+    }
+
+    const aggregateId = fieldDefinitionAggregateId(tenantId, payload.entityName, payload.fieldKey);
+
+    return executor.delete({ id: aggregateId }, event.user, ctx.db);
+  },
+};

package/src/custom-fields/index.ts

@@ -0,0 +1,17 @@
+export { fieldDefinitionAggregateId } from "./aggregate-id";
+export {
+  CUSTOM_FIELDS_FEATURE_NAME,
+  FIELD_DEFINITION_CREATED_EVENT,
+  FIELD_DEFINITION_DELETED_EVENT,
+  FIELD_DEFINITION_UPDATED_EVENT,
+  SUPPORTED_FIELD_TYPES,
+  type SupportedFieldType,
+} from "./constants";
+export { fieldDefinitionEntity } from "./entity";
+export { createCustomFieldsFeature } from "./feature";
+export {
+  type DefineFieldPayload,
+  type DeleteFieldPayload,
+  defineFieldPayloadSchema,
+  deleteFieldPayloadSchema,
+} from "./schemas";

package/src/custom-fields/schemas.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { SUPPORTED_FIELD_TYPES } from "./constants";
+
+// Field-Type-Validator — pinnt valid type-Werte für fieldDefinition.
+const fieldTypeSchema = z.enum(SUPPORTED_FIELD_TYPES);
+
+// Serialized-field-jsonb — was als `serializedField`-Spalte gespeichert wird.
+// In v1 noch nicht strict-typed pro field-type (das kommt in B2 wenn die
+// Stammfeld-Builder-Schemas exposed sind). Hier nur die Struktur-Garantie.
+//
+// Schema-shape (Beispiel-Inputs für die unterschiedlichen Field-Types):
+//
+//   text:     { type: "text", required: true, maxLength: 50 }
+//   number:   { type: "number", required: false, min: 0, max: 100 }
+//   boolean:  { type: "boolean", required: false }
+//   date:     { type: "date", required: false }
+//   enum:     { type: "enum", required: true, values: ["bronze", "silver", "gold"] }
+//   money:    { type: "money", required: false, currency: "EUR" }
+//   embedded: { type: "embedded", required: false, schema: { ... } }
+//
+// In B1 akzeptieren wir alle Variants als Generic-jsonb-Payload mit nur dem
+// `type`-Pflichtfeld validiert. B2 wird die volle discriminated-union mit
+// per-type-options anschließen — sobald die Stammfeld-Field-Builder-Schemas
+// exportiert sind.
+const serializedFieldSchema = z
+  .looseObject({
+    type: fieldTypeSchema,
+  })
+  .refine((v) => typeof v["type"] === "string", "serializedField must have a string `type`");
+
+// i18n-labels — `{ de: "...", en: "...", ... }`. Mindestens ein Eintrag.
+const labelSchema = z.record(z.string().min(2).max(8), z.string().min(1));
+
+// Payload für `define-tenant-field` und `define-system-field` write-handler.
+export const defineFieldPayloadSchema = z.object({
+  entityName: z.string().min(1).max(64),
+  fieldKey: z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(
+      /^[a-zA-Z][a-zA-Z0-9_-]*$/,
+      "fieldKey must start with a letter, only letters/digits/_/- allowed",
+    ),
+  serializedField: serializedFieldSchema,
+  required: z.boolean().default(false),
+  searchable: z.boolean().default(false),
+  displayOrder: z.number().int().min(0).default(0),
+  label: labelSchema.optional(),
+});
+export type DefineFieldPayload = z.infer<typeof defineFieldPayloadSchema>;
+
+// Payload für `delete-tenant-field` / `delete-system-field`.
+export const deleteFieldPayloadSchema = z.object({
+  entityName: z.string().min(1).max(64),
+  fieldKey: z.string().min(1).max(64),
+});
+export type DeleteFieldPayload = z.infer<typeof deleteFieldPayloadSchema>;