@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/custom-fields/handlers/clear-custom-field.write.ts

@@ -0,0 +1,82 @@
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { DEFAULT_VALUE_WRITE_ROLES } from "../constants.js";
+import { customFieldsFeature } from "../feature.js";
+import { checkFieldAccessForWrite } from "../lib/field-access.js";
+
+export const clearCustomFieldPayloadSchema = z.object({
+  entityName: z.string().min(1).max(64),
+  entityId: z.string().min(1),
+  fieldKey: z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/),
+});
+export type ClearCustomFieldPayload = z.infer<typeof clearCustomFieldPayloadSchema>;
+
+const CLEAR_CUSTOM_FIELD_REASON =
+  "reads custom field definitions with an explicit tenant_id = caller tenant via raw SQL with read retry";
+
+// clear-custom-field — entfernt einen Custom-Field-Wert von einer host-
+// entity. Emittiert customField.cleared-Event; MSP entfernt key aus
+// jsonb-column (key-removal, nicht null-set).
+//
+// T1.5b: per-field fieldAccess.write gate — caller muss eine der definierten
+// Rollen halten falls fieldDefinition.serializedField.fieldAccess.write
+// gesetzt ist. Handler-level RBAC (TenantAdmin/Member) bleibt zusätzlich.
+export const clearCustomFieldHandler: WriteHandlerDef = {
+  name: "clear-custom-field",
+  schema: clearCustomFieldPayloadSchema,
+  access: { roles: DEFAULT_VALUE_WRITE_ROLES },
+  description:
+    "Removes the stored value of one custom field from a single host entity row after re-checking that field's per-field write roles; use it to blank a field the user emptied instead of writing a null value.",
+  escapeHatch: {
+    grants: ["unsafeRaw"],
+    reason: CLEAR_CUSTOM_FIELD_REASON,
+  },
+  handler: async (event, ctx) => {
+    const payload = event.payload as ClearCustomFieldPayload; // @cast-boundary engine-payload
+
+    const accessCheck = await checkFieldAccessForWrite(
+      ctx.db.unsafeRaw(CLEAR_CUSTOM_FIELD_REASON),
+      event.user.tenantId,
+      payload.entityName,
+      payload.fieldKey,
+      event.user.roles,
+    );
+    if (!accessCheck.ok) {
+      if (accessCheck.reason === "field_definition_not_found") {
+        return failNotFound("fieldDefinition", payload.fieldKey);
+      }
+      if (accessCheck.reason === "field_definition_corrupt") {
+        return failUnprocessable("field_definition_corrupt", { fieldKey: payload.fieldKey });
+      }
+      return failUnprocessable("field_access_denied", {
+        fieldKey: payload.fieldKey,
+        requiredRoles: accessCheck.requiredRoles ?? [],
+      });
+    }
+
+    await ctx.unsafeAppendEvent({
+      aggregateId: payload.entityId,
+      aggregateType: payload.entityName,
+      type: customFieldsFeature.exports.clearedEvent.name,
+      payload: { fieldKey: payload.fieldKey },
+    });
+
+    return {
+      isSuccess: true as const,
+      data: { entityName: payload.entityName, entityId: payload.entityId },
+    };
+  },
+};
+
+/** Pendant zu createSetCustomFieldHandler — gleiche Rollen für set + clear,
+ *  ein Wert ohne Clear-Recht wäre nur halb beherrschbar. */
+export function createClearCustomFieldHandler(
+  roles: readonly string[] = DEFAULT_VALUE_WRITE_ROLES,
+): WriteHandlerDef {
+  return { ...clearCustomFieldHandler, access: { roles } };
+}

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

@@ -0,0 +1,45 @@
+import { SYSTEM_TENANT_ID, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { fieldDefinitionAggregateId } from "../aggregate-id.js";
+import { defineOrResurrectFieldDefinition } from "../lib/define-or-resurrect.js";
+import { buildFieldDefinitionColumns } from "../lib/field-definition-row.js";
+import { type DefineFieldPayload, defineFieldPayloadSchema } from "../schemas.js";
+
+// 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"] },
+  description:
+    "Creates a custom-field definition under the system tenant so every tenant inherits the field on the named entity; use it for platform-mandated fields that individual tenants may fill in but never edit or delete.",
+  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 defineOrResurrectFieldDefinition(
+      aggregateId,
+      buildFieldDefinitionColumns(payload),
+      systemUser,
+      ctx.db,
+    );
+  },
+};

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

@@ -0,0 +1,108 @@
+import { isSystemTenant, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import { fieldDefinitionAggregateId } from "../aggregate-id.js";
+import { DEFAULT_FIELD_DEFINITION_WRITE_ROLES } from "../constants.js";
+import { defineOrResurrectFieldDefinition } from "../lib/define-or-resurrect.js";
+import { buildFieldDefinitionColumns } from "../lib/field-definition-row.js";
+import { countTenantFieldDefinitions } from "../lib/quota.js";
+import { type DefineFieldPayload, defineFieldPayloadSchema } from "../schemas.js";
+
+// 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.
+//
+// **Quota (T1.5e)**: optional `fieldDefinitionLimitPerTenant` gate. When the
+// tenant already has ≥ limit definitions, the handler rejects with
+// `unprocessable` + reason `cap_exceeded` BEFORE attempting the insert.
+// The factory below closes over the limit; the legacy const-export keeps
+// behavior unchanged for callers who didn't opt into a limit.
+//
+// Soft cap, not a hard guarantee: the count-then-insert is not serialized, so
+// N concurrent defines with distinct fieldKeys can each read `current < limit`
+// and overshoot by up to N. Acceptable here — defining fields is an admin-only,
+// low-frequency action and the limit is not wired to billing/tier enforcement.
+// If an exact cap is ever needed, serialize via advisory lock or a count
+// constraint at the insert.
+export interface DefineTenantFieldOptions {
+  /** Soft cap — `>= limit` definitions per tenant rejects further defines (see header: concurrent defines may overshoot). */
+  readonly fieldDefinitionLimitPerTenant?: number;
+  /** Access roles for this handler. Default ["TenantAdmin"] (#2296) — apps with
+   *  their own role vocabulary pass this via createCustomFieldsFeature({
+   *  fieldDefinitionWriteRoles }), which threads the same roles into
+   *  update-/delete-tenant-field too (the definition-CRUD triad shares one gate). */
+  readonly roles?: readonly string[];
+}
+
+const DEFINE_TENANT_FIELD_REASON =
+  "counts custom field definitions with an explicit tenant_id = caller tenant via raw SQL with read retry";
+
+export function createDefineTenantFieldHandler(
+  opts: DefineTenantFieldOptions = {},
+): WriteHandlerDef {
+  const limit = opts.fieldDefinitionLimitPerTenant;
+  return {
+    name: "define-tenant-field",
+    schema: defineFieldPayloadSchema,
+    access: { roles: opts.roles ?? DEFAULT_FIELD_DEFINITION_WRITE_ROLES },
+    description:
+      "Creates a custom-field definition owned by the caller's own tenant on the named entity, rejecting the write once the tenant's definition quota is reached; use it when one tenant needs an extra field the other tenants must not see.",
+    escapeHatch: {
+      grants: ["unsafeRaw"],
+      reason: DEFINE_TENANT_FIELD_REASON,
+    },
+    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",
+        );
+      }
+
+      if (limit !== undefined) {
+        const current = await countTenantFieldDefinitions(
+          ctx.db.unsafeRaw(DEFINE_TENANT_FIELD_REASON),
+          tenantId,
+        );
+        if (current >= limit) {
+          return failUnprocessable("cap_exceeded", {
+            capName: "customFields.fieldDefinition.count",
+            limit,
+            current,
+          });
+        }
+      }
+
+      const aggregateId = fieldDefinitionAggregateId(
+        tenantId,
+        payload.entityName,
+        payload.fieldKey,
+      );
+
+      return defineOrResurrectFieldDefinition(
+        aggregateId,
+        buildFieldDefinitionColumns(payload),
+        event.user,
+        ctx.db,
+      );
+    },
+  };
+}
+
+// Backwards-compat: existing imports of `defineTenantFieldHandler` keep
+// working — the handler has no quota, identical to pre-T1.5e behavior.
+export const defineTenantFieldHandler: WriteHandlerDef = createDefineTenantFieldHandler();

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

@@ -0,0 +1,49 @@
+import { SYSTEM_TENANT_ID, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { fieldDefinitionAggregateId } from "../aggregate-id.js";
+import { FIELD_DEFINITION_AGGREGATE_TYPE } from "../constants.js";
+import { fieldDefinitionExecutor } from "../executor.js";
+import { customFieldsFeature } from "../feature.js";
+import { type DeleteFieldPayload, deleteFieldPayloadSchema } from "../schemas.js";
+
+// 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"] },
+  description:
+    "Deletes a system-tenant custom-field definition and cascades an event that strips the now-orphaned values out of every tenant's host rows; use it to retire a platform-wide field for all tenants at once.",
+  agent: { risk: "high" },
+  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 };
+    const result = await fieldDefinitionExecutor.delete({ id: aggregateId }, systemUser, ctx.db);
+
+    // Cascade-cleanup-Event — host-entity-MSPs entfernen orphan values aus
+    // ihrer customFields jsonb. Im selben TX = atomic.
+    if (result.isSuccess) {
+      await ctx.unsafeAppendEvent({
+        aggregateId,
+        aggregateType: FIELD_DEFINITION_AGGREGATE_TYPE,
+        type: customFieldsFeature.exports.fieldDefinitionDeletedEvent.name,
+        payload: {
+          entityName: payload.entityName,
+          fieldKey: payload.fieldKey,
+          tenantId: SYSTEM_TENANT_ID,
+        },
+      });
+    }
+
+    return result;
+  },
+};

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

@@ -0,0 +1,74 @@
+import { isSystemTenant, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { fieldDefinitionAggregateId } from "../aggregate-id.js";
+import {
+  DEFAULT_FIELD_DEFINITION_WRITE_ROLES,
+  FIELD_DEFINITION_AGGREGATE_TYPE,
+} from "../constants.js";
+import { fieldDefinitionExecutor } from "../executor.js";
+import { customFieldsFeature } from "../feature.js";
+import { type DeleteFieldPayload, deleteFieldPayloadSchema } from "../schemas.js";
+
+// 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 interface DeleteTenantFieldOptions {
+  /** Access roles for this handler. Default ["TenantAdmin"] (#2296) — see
+   *  DefineTenantFieldOptions.roles, the definition-CRUD triad shares one gate. */
+  readonly roles?: readonly string[];
+}
+
+export function createDeleteTenantFieldHandler(
+  opts: DeleteTenantFieldOptions = {},
+): WriteHandlerDef {
+  return {
+    name: "delete-tenant-field",
+    schema: deleteFieldPayloadSchema,
+    access: { roles: opts.roles ?? DEFAULT_FIELD_DEFINITION_WRITE_ROLES },
+    description:
+      "Deletes one of the caller's own tenant's custom-field definitions and cascades an event that strips its orphaned values out of that tenant's host rows; use it to retire a field this tenant defined itself.",
+    agent: { risk: "high" },
+    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,
+      );
+
+      const result = await fieldDefinitionExecutor.delete({ id: aggregateId }, event.user, ctx.db);
+
+      // Emit cascade-cleanup-Event NACH erfolgreichem Delete. host-entity-MSPs
+      // (registriert via wireCustomFieldsFor) konsumieren das + entfernen orphan
+      // values aus ihrer customFields jsonb. Im selben TX = atomic cleanup.
+      if (result.isSuccess) {
+        await ctx.unsafeAppendEvent({
+          aggregateId,
+          aggregateType: FIELD_DEFINITION_AGGREGATE_TYPE,
+          type: customFieldsFeature.exports.fieldDefinitionDeletedEvent.name,
+          payload: { entityName: payload.entityName, fieldKey: payload.fieldKey, tenantId },
+        });
+      }
+
+      return result;
+    },
+  };
+}
+
+// Backwards-compat: existing imports of `deleteTenantFieldHandler` keep
+// working — identical to createDeleteTenantFieldHandler() with default roles.
+export const deleteTenantFieldHandler: WriteHandlerDef = createDeleteTenantFieldHandler();

package/packages/bundled-features/src/custom-fields/handlers/set-custom-field.write.ts

@@ -0,0 +1,124 @@
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { DEFAULT_VALUE_WRITE_ROLES } from "../constants.js";
+import { customFieldsFeature } from "../feature.js";
+import { fieldWriteAccessDeniedRoles, loadFieldDefinition } from "../lib/field-access.js";
+import { buildCustomFieldValueSchema } from "../lib/value-schema.js";
+
+export const setCustomFieldPayloadSchema = z.object({
+  entityName: z.string().min(1).max(64),
+  entityId: z.string().min(1),
+  fieldKey: z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/),
+  // z.unknown() is implicitly optional; reject a missing value here (clearing is
+  // clear-custom-field's job) so the projection never binds JSON.stringify(undefined).
+  value: z
+    .unknown()
+    .refine((v) => v !== undefined, "value is required (use clear-custom-field to remove a value)"),
+});
+export type SetCustomFieldPayload = z.infer<typeof setCustomFieldPayloadSchema>;
+
+const SET_CUSTOM_FIELD_REASON =
+  "reads custom field definitions with an explicit tenant_id = caller tenant via raw SQL with read retry";
+
+// set-custom-field — schreibt einen Custom-Field-Wert auf eine host-entity.
+//
+// **ES-Option-B**: emittiert customField.set-Event auf dem host-aggregate
+// stream (aggregateType = host-entity-name, aggregateId = host-entity-id).
+// Last-Wins-Semantik: customField.set wird OHNE expectedVersion appended,
+// concurrent writes auf gleiches Field gehen beide durch (Plan-Doc v2
+// Concurrency-Tabelle).
+//
+// **Write-Pfad (Single-Fetch)** — eine fieldDefinition-Ladung, drei Gates:
+//   1. Definition fehlt → 404.
+//   2. field-access (T1.5b): fieldAccess.write-Rollen müssen intersecten, sonst
+//      403/422. Handler-level RBAC (TenantAdmin/Member) bleibt zusätzlich.
+//   3. Value-Validation (Builder-Reuse): der Wert wird gegen das aus
+//      serializedField rehydrierte fieldToZod-Schema geparst. Type-Mismatch →
+//      422, KEIN Event entsteht (Projection bleibt typed — Plan-Doc
+//      Stammfeld-Identität). `value: null` ODER `value: undefined` auf einem
+//      typisierten Feld sind Type-Mismatches → 422; zum Entfernen eines Werts
+//      dient clear-custom-field.
+//
+// Scope: ECHTE type-only Validation. value-schema.ts strippt `required`,
+// `maxLength`, `format` und `default` aus dem serializedField bevor fieldToZod
+// daraus ein Schema baut — wir prüfen nur die Type-Shape. Required-on-set,
+// Default-Application und Length-/Format-Enforcement bleiben out-of-scope
+// (Plan-Doc "Stammfeld-Identität" listet sie als eigene Zeilen).
+export const setCustomFieldHandler: WriteHandlerDef = {
+  name: "set-custom-field",
+  schema: setCustomFieldPayloadSchema,
+  access: { roles: DEFAULT_VALUE_WRITE_ROLES },
+  description:
+    "Stores one custom-field value on a single host entity row after validating it against the field definition's declared type and per-field write roles; use it to save what a user entered into a custom field.",
+  escapeHatch: {
+    grants: ["unsafeRaw"],
+    reason: SET_CUSTOM_FIELD_REASON,
+  },
+  handler: async (event, ctx) => {
+    const payload = event.payload as SetCustomFieldPayload; // @cast-boundary engine-payload
+
+    const loaded = await loadFieldDefinition(
+      ctx.db.unsafeRaw(SET_CUSTOM_FIELD_REASON),
+      event.user.tenantId,
+      payload.entityName,
+      payload.fieldKey,
+    );
+    if (!loaded.found) {
+      return failNotFound("fieldDefinition", payload.fieldKey);
+    }
+    if (loaded.field === null) {
+      return failUnprocessable("field_definition_corrupt", { fieldKey: payload.fieldKey });
+    }
+
+    const deniedRoles = fieldWriteAccessDeniedRoles(loaded.field, event.user.roles);
+    if (deniedRoles) {
+      return failUnprocessable("field_access_denied", {
+        fieldKey: payload.fieldKey,
+        requiredRoles: deniedRoles,
+      });
+    }
+
+    const valueSchema = buildCustomFieldValueSchema(loaded.field);
+    if (valueSchema) {
+      const parsed = valueSchema.safeParse(payload.value);
+      if (!parsed.success) {
+        return failUnprocessable("custom_field_value_invalid", {
+          fieldKey: payload.fieldKey,
+          fieldType: loaded.field?.type,
+          issues: parsed.error.issues.map((i) => i.message),
+        });
+      }
+    }
+
+    // Emit customField.set on host-aggregate stream. unsafeAppendEvent
+    // (statt strict appendEvent) weil event-type-map keine cross-feature-
+    // augmentation für diesen event-typ hat — wir nutzen den qualified
+    // string-namen direkt. Der Wert steht IMMER im Event (custom fields
+    // tragen keine PII, #972) — Replay reproduziert die Projection voll.
+    await ctx.unsafeAppendEvent({
+      aggregateId: payload.entityId,
+      aggregateType: payload.entityName,
+      type: customFieldsFeature.exports.setEvent.name,
+      payload: { fieldKey: payload.fieldKey, value: payload.value },
+    });
+
+    return {
+      isSuccess: true as const,
+      data: { entityName: payload.entityName, entityId: payload.entityId },
+    };
+  },
+};
+
+/** Value-Write mit App-Rollen statt der Bundle-Defaults — Apps mit eigenem
+ *  Rollen-Vokabular (z.B. "Admin"/"Editor") reichen ihre Rollen über
+ *  createCustomFieldsFeature({ valueWriteRoles }) hierher durch. */
+export function createSetCustomFieldHandler(
+  roles: readonly string[] = DEFAULT_VALUE_WRITE_ROLES,
+): WriteHandlerDef {
+  return { ...setCustomFieldHandler, access: { roles } };
+}

package/packages/bundled-features/src/custom-fields/handlers/update-tenant-field.write.ts

@@ -0,0 +1,98 @@
+import { isSystemTenant, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
+import { fieldDefinitionAggregateId } from "../aggregate-id.js";
+import { DEFAULT_FIELD_DEFINITION_WRITE_ROLES } from "../constants.js";
+import { fieldDefinitionExecutor } from "../executor.js";
+import { buildFieldDefinitionColumns } from "../lib/field-definition-row.js";
+import { type UpdateFieldPayload, updateFieldPayloadSchema } from "../schemas.js";
+
+// update-tenant-field — TenantAdmin ersetzt den Stand einer bestehenden
+// Field-Definition (Vollersatz: Payload-Shape = define, der Edit-Screen
+// schickt den kompletten neuen Stand). Identität ist (entityName, fieldKey)
+// → deterministische aggregate-id wie bei define/delete; tenantId kommt
+// aus event.user (Cross-Tenant-Mutation unmöglich, fremde Definitionen
+// derivieren auf eine andere aggregate-id → 404).
+//
+// **type ist immutable.** Ein Type-Wechsel würde bestehende Values in den
+// host-entity customFields-jsonbs verwaisen (text-Wert unter number-Feld);
+// dafür ist delete + re-define der ehrliche Weg (Bug-Bash D2: bewusst KEIN
+// delete+redefine im update — das würde Event-Historie + Field-Ids
+// zerstören, aber ein Type-Wechsel will genau diese Zäsur).
+//
+// **Bekannte MVP-Grenze (bewusst):** der Edit reconciled bestehende
+// Host-Werte NICHT gegen die neue Definition — Constraint-Narrowing
+// (enum-Wert weg, min/max enger) lässt alte Werte still non-conformant,
+// required false→true macht Bestands-Rows unvollständig, searchable-Toggle
+// re-indexed nicht. Werte werden beim NÄCHSTEN Write der Host-Row gegen
+// die aktuelle Def validiert; eine Reject-mit-Konflikt-Liste-Variante
+// wäre der Ausbau, wenn der Bedarf real wird.
+//
+// **skipOptimisticLock:** Definition-Edits sind admin-only + low-frequency
+// (gleiche Abwägung wie der Quota-soft-cap in define). Last-write-wins
+// statt version-Roundtrip durch den Edit-Screen.
+export interface UpdateTenantFieldOptions {
+  /** Access roles for this handler. Default ["TenantAdmin"] (#2296) — see
+   *  DefineTenantFieldOptions.roles, the definition-CRUD triad shares one gate. */
+  readonly roles?: readonly string[];
+}
+
+export function createUpdateTenantFieldHandler(
+  opts: UpdateTenantFieldOptions = {},
+): WriteHandlerDef {
+  return {
+    name: "update-tenant-field",
+    schema: updateFieldPayloadSchema,
+    access: { roles: opts.roles ?? DEFAULT_FIELD_DEFINITION_WRITE_ROLES },
+    description:
+      "Replaces a tenant-owned custom-field definition with a complete new spec while refusing any change to the field's type; use it to relabel or re-constrain an existing field rather than to create or remove one.",
+    handler: async (event, ctx) => {
+      const payload = event.payload as UpdateFieldPayload; // @cast-boundary engine-payload
+      const tenantId = event.user.tenantId;
+
+      if (isSystemTenant(tenantId)) {
+        throw new Error(
+          "update-tenant-field: tenantId is SYSTEM_TENANT_ID — system-scope definitions have no update handler (delete + re-define via the system-field handlers)",
+        );
+      }
+
+      const aggregateId = fieldDefinitionAggregateId(
+        tenantId,
+        payload.entityName,
+        payload.fieldKey,
+      );
+
+      const existing = await fieldDefinitionExecutor.detail(
+        { id: aggregateId },
+        event.user,
+        ctx.db,
+      );
+      if (!existing) {
+        return failNotFound("field-definition", aggregateId);
+      }
+
+      if (existing["type"] !== payload.serializedField.type) {
+        return failUnprocessable("field_type_immutable", {
+          entityName: payload.entityName,
+          fieldKey: payload.fieldKey,
+          currentType: existing["type"],
+          requestedType: payload.serializedField.type,
+        });
+      }
+
+      // entityName/fieldKey sind die Identität — nicht Teil der changes.
+      const {
+        entityName: _entityName,
+        fieldKey: _fieldKey,
+        ...changes
+      } = buildFieldDefinitionColumns(payload);
+
+      return fieldDefinitionExecutor.update({ id: aggregateId, changes }, event.user, ctx.db, {
+        skipOptimisticLock: true,
+      });
+    },
+  };
+}
+
+// Backwards-compat: existing imports of `updateTenantFieldHandler` keep
+// working — identical to createUpdateTenantFieldHandler() with default roles.
+export const updateTenantFieldHandler: WriteHandlerDef = createUpdateTenantFieldHandler();

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

@@ -0,0 +1,40 @@
+export { fieldDefinitionAggregateId } from "./aggregate-id.js";
+export {
+  CUSTOM_FIELDS_EXTENSION,
+  CUSTOM_FIELDS_FEATURE_NAME,
+  FIELD_DEFINITION_CREATED_EVENT,
+  FIELD_DEFINITION_UPDATED_EVENT,
+  SUPPORTED_FIELD_TYPES,
+  type SupportedFieldType,
+} from "./constants.js";
+export { fieldDefinitionEntity } from "./entity.js";
+export {
+  type CustomFieldClearedPayload,
+  type CustomFieldSetPayload,
+  customFieldClearedSchema,
+  customFieldSetSchema,
+} from "./events.js";
+export {
+  type CustomFieldsFeatureOptions,
+  createCustomFieldsFeature,
+  customFieldsFeature,
+} from "./feature.js";
+export {
+  type ClearCustomFieldPayload,
+  clearCustomFieldPayloadSchema,
+} from "./handlers/clear-custom-field.write.js";
+export {
+  type SetCustomFieldPayload,
+  setCustomFieldPayloadSchema,
+} from "./handlers/set-custom-field.write.js";
+export {
+  isFieldDefinitionRow,
+  parseSerializedField,
+} from "./lib/parse-serialized-field.js";
+export {
+  type DefineFieldPayload,
+  type DeleteFieldPayload,
+  defineFieldPayloadSchema,
+  deleteFieldPayloadSchema,
+} from "./schemas.js";
+export { customFieldsField, wireCustomFieldsFor } from "./wire-for-entity.js";