@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/custom-fields/lib/define-or-resurrect.ts

@@ -0,0 +1,52 @@
+import { fieldDefinitionExecutor } from "../executor.js";
+import type { FieldDefinitionColumns } from "./field-definition-row.js";
+
+type DefineUser = Parameters<typeof fieldDefinitionExecutor.create>[1];
+type DefineDb = Parameters<typeof fieldDefinitionExecutor.create>[2];
+type WriteResult = Awaited<ReturnType<typeof fieldDefinitionExecutor.create>>;
+
+// Resurrection-aware define for the deterministic fieldDefinition aggregate-id.
+//
+// A definition's id is uuidv5(tenant|entity|fieldKey), so deleting it leaves a
+// (created+deleted) event stream under that id. A plain create() appends at
+// version 0 onto that stream → version_conflict — the deleted (entity, fieldKey)
+// could never be re-defined. The lifecycle states and their handling:
+//   - active definition exists → let create() raise the natural version_conflict
+//     (409) the dedup contract relies on.
+//   - soft-deleted definition  → restore() the stream, then update() it to the
+//     new payload (the caller is defining it afresh).
+//   - never defined            → create().
+//
+// restore-before-create matters: a create() version_conflict aborts the
+// surrounding tx, so a follow-up restore()/update() on the same connection would
+// fail with "current transaction is aborted". detail() (a read) + restore()
+// (which sees soft-deleted rows via a tenant-scoped fetch and only writes on
+// success) keep the tx clean until the single terminal write.
+export async function defineOrResurrectFieldDefinition(
+  aggregateId: string,
+  columns: FieldDefinitionColumns,
+  user: DefineUser,
+  db: DefineDb,
+): Promise<WriteResult> {
+  const active = await fieldDefinitionExecutor.detail({ id: aggregateId }, user, db);
+  if (active) {
+    return fieldDefinitionExecutor.create({ id: aggregateId, ...columns }, user, db);
+  }
+
+  const restored = await fieldDefinitionExecutor.restore({ id: aggregateId }, user, db);
+  if (restored.isSuccess) {
+    // restore() just un-deleted the row in this same tx; no concurrent writer
+    // exists, so skip the optimistic-lock version match (we'd otherwise have to
+    // thread the post-restore stream version through). Overwrite with the new
+    // definition payload — the caller is defining the field afresh.
+    // Spread to a mutable copy: `changes` is Record<string, unknown> and the
+    // readonly FieldDefinitionColumns isn't assignable to it.
+    return fieldDefinitionExecutor.update({ id: aggregateId, changes: { ...columns } }, user, db, {
+      skipOptimisticLock: true,
+    });
+  }
+  if (restored.error.code === "not_found") {
+    return fieldDefinitionExecutor.create({ id: aggregateId, ...columns }, user, db);
+  }
+  return restored;
+}

package/packages/bundled-features/src/custom-fields/lib/field-access.ts

@@ -0,0 +1,75 @@
+// T1.5b — per-field write access-check for the set/clear handlers.
+// Plus single-fetch loader so set-custom-field can run access-check AND
+// value-validation off one DB read (no double fetch).
+
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { selectSerializedFieldDefinition } from "../db/queries/field-access.js";
+import { parseSerializedField, type SerializedFieldShape } from "./parse-serialized-field.js";
+
+export type FieldAccessCheckResult =
+  | { ok: true }
+  | {
+      ok: false;
+      reason: "field_definition_not_found" | "field_definition_corrupt" | "field_access_denied";
+      requiredRoles?: ReadonlyArray<string>;
+    };
+
+export type LoadedFieldDefinition =
+  | { found: false }
+  // `field` is null when the row exists but its serialized_field is corrupt.
+  // A write access-gate treats this fail-closed (secure-by-default): a corrupt
+  // definition must not silently drop a per-field write restriction.
+  | { found: true; field: SerializedFieldShape | null };
+
+// `runner` is deliberately unscoped: tenant isolation rests solely on `tenantId`.
+export async function loadFieldDefinition(
+  runner: DbRunner,
+  tenantId: TenantId,
+  entityName: string,
+  fieldKey: string,
+): Promise<LoadedFieldDefinition> {
+  const serialized = await selectSerializedFieldDefinition(runner, tenantId, entityName, fieldKey);
+  if (serialized === null) return { found: false };
+  // parseSerializedField throws on a #972 legacy `sensitive` definition —
+  // that's a corrupt/unprocessable row from this write-gate's perspective,
+  // same fail-closed treatment as a shape that fails isShape().
+  try {
+    return { found: true, field: parseSerializedField(serialized) };
+  } catch {
+    return { found: true, field: null };
+  }
+}
+
+// Pure access-check on an already-loaded definition. Returns the required
+// roles when the caller is denied, or `null` when access is allowed.
+//
+// Contract: `fieldAccess.write` entries MUST be verbatim membership-system role
+// names (e.g. "TenantAdmin", not "Admin") — match is exact like framework-wide
+// `engine/access.ts`; no normalization, so a drifted name denies silently.
+export function fieldWriteAccessDeniedRoles(
+  field: SerializedFieldShape | null,
+  userRoles: ReadonlyArray<string>,
+): ReadonlyArray<string> | null {
+  const required = field?.fieldAccess?.write;
+  if (!required || required.length === 0) return null;
+  return userRoles.some((role) => required.includes(role)) ? null : required;
+}
+
+// Convenience wrapper retained for clear-custom-field (no value-validation
+// needed there) — does the load + access-check in one call.
+export async function checkFieldAccessForWrite(
+  runner: DbRunner,
+  tenantId: TenantId,
+  entityName: string,
+  fieldKey: string,
+  userRoles: ReadonlyArray<string>,
+): Promise<FieldAccessCheckResult> {
+  const loaded = await loadFieldDefinition(runner, tenantId, entityName, fieldKey);
+  if (!loaded.found) return { ok: false, reason: "field_definition_not_found" };
+  if (loaded.field === null) return { ok: false, reason: "field_definition_corrupt" };
+
+  const deniedRoles = fieldWriteAccessDeniedRoles(loaded.field, userRoles);
+  if (!deniedRoles) return { ok: true };
+  return { ok: false, reason: "field_access_denied", requiredRoles: deniedRoles };
+}

package/packages/bundled-features/src/custom-fields/lib/field-definition-row.ts

@@ -0,0 +1,33 @@
+import type { DefineFieldPayload } from "../schemas.js";
+
+export interface FieldDefinitionColumns {
+  readonly entityName: string;
+  readonly fieldKey: string;
+  readonly type: string;
+  readonly required: boolean;
+  readonly searchable: boolean;
+  readonly displayOrder: number;
+  readonly serializedField: string;
+}
+
+// The required/searchable/displayOrder columns are a denormalized projection of
+// serializedField — derive, don't default. Zod gives top-level `required` a
+// `.default(false)`, so "caller omitted it" is indistinguishable from `false`
+// post-parse; serializedField-present therefore wins to preserve caller intent.
+export function buildFieldDefinitionColumns(payload: DefineFieldPayload): FieldDefinitionColumns {
+  const sf = payload.serializedField;
+  const required = typeof sf["required"] === "boolean" ? sf["required"] : payload.required;
+  const searchable = typeof sf["searchable"] === "boolean" ? sf["searchable"] : payload.searchable;
+  const displayOrder =
+    typeof sf["displayOrder"] === "number" ? sf["displayOrder"] : payload.displayOrder;
+
+  return {
+    entityName: payload.entityName,
+    fieldKey: payload.fieldKey,
+    type: sf.type,
+    required,
+    searchable,
+    displayOrder,
+    serializedField: JSON.stringify({ ...sf, label: payload.label }),
+  };
+}

package/packages/bundled-features/src/custom-fields/lib/parse-serialized-field.ts

@@ -0,0 +1,64 @@
+// Centralised parser for `fieldDefinition.serializedField`.
+//
+// The column is stored as `text` in B1 (entity.ts) — what the db row hands
+// back depends on the driver: postgres-js returns text as a `string`, but
+// jsonb-tolerant drivers and middleware can deliver an already-parsed
+// object. This helper normalises both, validates the shape, and centralises
+// the single boundary cast so callers don't sprinkle `as { … }`-narrowings
+// across the bundle.
+//
+// All structured `serializedField`-keys recognised today (`fieldAccess`,
+// `retention`) live on this shape. New keys go here so the other call-sites
+// can read them via the typed result instead of re-parsing.
+
+import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+
+export interface SerializedFieldShape {
+  readonly type: string;
+  readonly fieldAccess?: {
+    readonly read?: ReadonlyArray<string>;
+    readonly write?: ReadonlyArray<string>;
+  };
+  readonly retention?: {
+    readonly keepFor: string;
+    readonly strategy: "delete" | "anonymize";
+  };
+}
+
+function isShape(v: unknown): v is SerializedFieldShape {
+  if (!v || typeof v !== "object") return false;
+  // `in` narrows v's type from `object` to `object & { type: unknown }` so
+  // the property access below does not need a cast.
+  if (!("type" in v)) return false;
+  return typeof v.type === "string";
+}
+
+/**
+ * Normalises the row's `serialized_field` column. Returns `null` for
+ * absent/corrupt rows so callers can short-circuit cleanly without
+ * having to mirror the safe-json fallback semantics themselves.
+ */
+export function parseSerializedField(raw: unknown): SerializedFieldShape | null {
+  const parsed = typeof raw === "string" ? parseJsonSafe<unknown>(raw, null) : raw;
+  if (!isShape(parsed)) return null;
+  // Fail loud instead of silently dropping the key: a stored definition with
+  // `sensitive` predates #972 and its PII expectations (event-log exclusion,
+  // forget-strip) no longer hold — the field must be recreated.
+  if ("sensitive" in parsed) {
+    throw new Error(
+      "custom-field definition contains the removed `sensitive` key (#972) — custom fields don't support PII. Recreate the field without it; model personal data as a schema entity field with a pii annotation.",
+    );
+  }
+  return parsed;
+}
+
+export interface FieldDefinitionRow {
+  readonly field_key: string;
+  readonly serialized_field: unknown;
+}
+
+export function isFieldDefinitionRow(value: unknown): value is FieldDefinitionRow {
+  if (!value || typeof value !== "object") return false;
+  if (!("field_key" in value)) return false;
+  return typeof value.field_key === "string";
+}

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

@@ -0,0 +1,5 @@
+// T1.5e — per-tenant fieldDefinition quota.
+//
+// Re-exports from db/queries/quota.ts for backward-compatible import paths.
+
+export { countTenantFieldDefinitions } from "../db/queries/quota.js";

package/packages/bundled-features/src/custom-fields/lib/value-schema.ts

@@ -0,0 +1,91 @@
+import {
+  DEFAULT_CURRENCIES,
+  type FieldDefinition,
+  fieldToZod,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type * as z from "zod";
+import { SUPPORTED_FIELD_TYPES } from "../constants.js";
+
+// Builds a Zod schema that validates a custom-field VALUE against its
+// fieldDefinition. Reuses the framework's `fieldToZod` (Builder-Reuse /
+// Stammfeld-Identität, Plan-Doc) — one field-type-schema source, no drift
+// between Stammfeld- and Custom-Field-validation.
+//
+// Scope: type-shape only. fieldToZod also folds `required`, `maxLength`,
+// `format`, and `default` into Zod refinements; we strip those before the
+// call so set-custom-field rejects type-mismatches and only type-mismatches.
+// Required-on-set, default-application, and length/format-enforcement remain
+// out-of-scope per the Plan-Doc ("Stammfeld-Identität" lists them as
+// separate concerns).
+//
+// Vocabulary bridge: custom-fields expose `enum` (Plan + `r.field.enum([...])`)
+// where the framework's FieldDefinition calls the equivalent type `select`
+// with an `options` array.
+//
+// Returns `null` when the serialized field is unparseable or names a type
+// outside the custom-fields-supported set — callers then skip value-validation.
+
+const SUPPORTED_TYPES_SET: ReadonlySet<string> = new Set(SUPPORTED_FIELD_TYPES);
+const SUPPORTED_EMBEDDED_SUB_TYPES: ReadonlySet<string> = new Set([
+  "text",
+  "number",
+  "boolean",
+  "date",
+]);
+
+// Constraint-keys fieldToZod converts into Zod refinements. Stripped so the
+// resulting schema validates the type-shape only, not the constraint.
+const CONSTRAINT_KEYS = ["required", "maxLength", "format", "default"] as const;
+
+export function buildCustomFieldValueSchema(parsedField: unknown): z.ZodTypeAny | null {
+  if (!parsedField || typeof parsedField !== "object") return null;
+  const obj = parsedField as Record<string, unknown>;
+  const rawType = obj["type"];
+  if (typeof rawType !== "string") return null;
+  if (!SUPPORTED_TYPES_SET.has(rawType)) return null;
+
+  // Embedded sub-fields: pre-check the sub-type set so we surface unknown
+  // sub-types as "skip validation" (return null) rather than letting
+  // fieldToZod's assertUnreachable throw and the catch swallow real bugs.
+  // Build a constraint-stripped copy of each sub-field in the same pass —
+  // symmetric with the top-level strip below. Without it a sub-field's
+  // `required` folds into z.string().min(1) + non-optional, re-enforcing a
+  // constraint the contract ("type-mismatches and ONLY type-mismatches")
+  // drops everywhere else.
+  let strippedSubSchema: Record<string, Record<string, unknown>> | undefined;
+  if (rawType === "embedded") {
+    const schema = obj["schema"];
+    if (!schema || typeof schema !== "object") return null;
+    strippedSubSchema = {};
+    for (const [subKey, sub] of Object.entries(schema)) {
+      if (!sub || typeof sub !== "object") return null;
+      const subObj = sub as Record<string, unknown>;
+      const subType = subObj["type"];
+      if (typeof subType !== "string" || !SUPPORTED_EMBEDDED_SUB_TYPES.has(subType)) {
+        return null;
+      }
+      const strippedSub = { ...subObj };
+      for (const k of CONSTRAINT_KEYS) delete strippedSub[k];
+      strippedSubSchema[subKey] = strippedSub;
+    }
+  }
+
+  const fieldDef: Record<string, unknown> = { ...obj };
+  for (const k of CONSTRAINT_KEYS) delete fieldDef[k];
+  if (strippedSubSchema !== undefined) fieldDef["schema"] = strippedSubSchema;
+  if (rawType === "enum") {
+    fieldDef["type"] = "select";
+    fieldDef["options"] = obj["values"] ?? obj["options"] ?? [];
+  }
+
+  // fieldToZod's money case validates `currency` against the passed list, not
+  // a field-level key — so surface the field's own currency when it declares
+  // one, else fall back to the framework defaults.
+  const currencies =
+    typeof obj["currency"] === "string" ? [obj["currency"] as string] : DEFAULT_CURRENCIES;
+
+  // @cast-boundary serialized-field is the dehydrated r.field.X() output =
+  // a FieldDefinition; fieldToZod reads only its type-specific keys (the
+  // extra fieldAccess/retention/label keys are ignored).
+  return fieldToZod(fieldDef as unknown as FieldDefinition, currencies);
+}

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

@@ -0,0 +1,201 @@
+// T1.5d — per-field retention sweep for the customFields jsonb.
+//
+// Iterates one host entity's rows, looks up every fieldDefinition with a
+// `retention` policy, and strips/nulls customField values whose host-row
+// `modified_at` is older than the policy's `keepFor`.
+//
+// Typically invoked by a daily cron in the consumer app — alongside (or
+// inside) the data-retention bundle's own cleanup job. We don't auto-
+// register a cron here because the consumer chooses the schedule, and
+// because some apps want to sweep multiple host entities in one run.
+//
+// Caveat: the reference timestamp is the *host row's* `modified_at`, not
+// a per-customField timestamp. A row's customField hasn't been touched
+// in `keepFor` only when the entire row hasn't been touched in `keepFor`
+// — for value-level granularity, future work needs a value-timestamp
+// jsonb shape, which would be a breaking schema change.
+
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { extractTableName } from "@cosmicdrift/kumiko-framework/db";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { applyRetentionRemovals, selectHostRowsWithCustomFields } from "./db/queries/retention.js";
+import { selectFieldDefinitionsForEntity } from "./db/queries/user-data-rights.js";
+import { isFieldDefinitionRow, parseSerializedField } from "./lib/parse-serialized-field.js";
+
+type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+
+// Lifted from data-retention/keep-for.ts because the helper isn't re-exported
+// from the bundle's public index. Same parser semantics: "/^\\d+[hdwmy]$/",
+// month = 30d, year = 365d, hour as exact unit. If data-retention exports it
+// in a future minor we can switch the import back.
+const KEEP_FOR_PATTERN = /^(\d+)([hdwmy])$/;
+const UNIT_TO_DAYS: Record<string, number> = { d: 1, w: 7, m: 30, y: 365 };
+
+function isPastCutoff(args: {
+  readonly referenceTimestamp: Instant;
+  readonly keepFor: string;
+  readonly now: Instant;
+}): boolean {
+  const match = args.keepFor.match(KEEP_FOR_PATTERN);
+  if (!match) return false;
+  const amount = Number.parseInt(match[1] ?? "0", 10);
+  const unit = match[2] ?? "";
+  const hours = unit === "h" ? amount : amount * (UNIT_TO_DAYS[unit] ?? 0) * 24;
+  const cutoff = args.now.subtract({ hours });
+  return getTemporal().Instant.compare(args.referenceTimestamp, cutoff) < 0;
+}
+
+export interface RunCustomFieldsRetentionOptions {
+  readonly db: DbRunner;
+  readonly tenantId: string;
+  readonly entityName: string;
+  readonly entityTable: unknown;
+  /** Current time, injected for time-travel-tests. */
+  readonly now: Instant;
+}
+
+export interface CustomFieldsRetentionReport {
+  /** How many host rows were scanned (any customFields content). */
+  readonly rowsScanned: number;
+  /** How many host rows were updated because at least one key expired. */
+  readonly rowsUpdated: number;
+  /** Per-fieldKey count of expired-and-removed values. */
+  readonly removalsByFieldKey: Record<string, number>;
+}
+
+interface RetentionPolicy {
+  readonly keepFor: string;
+  readonly strategy: "delete" | "anonymize";
+}
+
+export async function runCustomFieldsRetention(
+  opts: RunCustomFieldsRetentionOptions,
+): Promise<CustomFieldsRetentionReport> {
+  const policies = await loadRetentionPolicies(opts.db, opts.tenantId, opts.entityName);
+  if (policies.size === 0) {
+    return { rowsScanned: 0, rowsUpdated: 0, removalsByFieldKey: {} };
+  }
+
+  const tableName = extractTableName(opts.entityTable, "custom-fields/run-retention");
+  const rows = await selectHostRowsWithCustomFields(opts.db, tableName, opts.tenantId);
+
+  const removalsByFieldKey: Record<string, number> = {};
+  let rowsUpdated = 0;
+  let rowsScanned = 0;
+
+  for (const raw of rows) {
+    rowsScanned++;
+    const row = asHostRow(raw);
+    // skip: see asHostRow rationale — defense in depth for driver shape drift.
+    if (!row) continue;
+    if (Object.keys(row.customFields).length === 0) continue;
+
+    const modifiedAt = parseInstant(row.modifiedAt);
+    // skip: rows without a parseable modified_at can't be aged against any
+    // cutoff, leave them untouched.
+    if (!modifiedAt) continue;
+
+    const removals: Array<{ key: string; strategy: "delete" | "anonymize" }> = [];
+    for (const [fieldKey, policy] of policies) {
+      if (!(fieldKey in row.customFields)) continue;
+      const expired = isPastCutoff({
+        referenceTimestamp: modifiedAt,
+        keepFor: policy.keepFor,
+        now: opts.now,
+      });
+      if (expired) {
+        removals.push({ key: fieldKey, strategy: policy.strategy });
+      }
+    }
+
+    // skip: nothing on this row aged out — no UPDATE needed.
+    if (removals.length === 0) continue;
+
+    const deleteKeys: string[] = [];
+    const anonymizeKeys: string[] = [];
+    for (const { key, strategy } of removals) {
+      if (strategy === "delete") {
+        deleteKeys.push(key);
+      } else {
+        anonymizeKeys.push(key);
+      }
+      removalsByFieldKey[key] = (removalsByFieldKey[key] ?? 0) + 1;
+    }
+
+    await applyRetentionRemovals(opts.db, tableName, deleteKeys, anonymizeKeys, row.id);
+    rowsUpdated++;
+  }
+
+  return { rowsScanned, rowsUpdated, removalsByFieldKey };
+}
+
+interface HostRow {
+  readonly id: string;
+  readonly modifiedAt: unknown;
+  readonly customFields: Record<string, unknown>;
+}
+
+function asHostRow(value: unknown): HostRow | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  if (!("id" in value) || typeof value.id !== "string") return null;
+  if (!("custom_fields" in value)) return null;
+  const cf = value.custom_fields;
+  if (!cf || typeof cf !== "object" || Array.isArray(cf)) return null;
+  return {
+    id: value.id,
+    modifiedAt: "modified_at" in value ? value.modified_at : null,
+    customFields: Object.fromEntries(Object.entries(cf)),
+  };
+}
+
+async function loadRetentionPolicies(
+  db: DbRunner,
+  tenantId: string,
+  entityName: string,
+): Promise<Map<string, RetentionPolicy>> {
+  const rows = await selectFieldDefinitionsForEntity(db, entityName, tenantId);
+  const out = new Map<string, RetentionPolicy>();
+  for (const raw of rows) {
+    // skip: see asHostRow rationale.
+    if (!isFieldDefinitionRow(raw)) continue;
+    // parseSerializedField throws on a #972 legacy `sensitive` definition —
+    // one unmigrated field must not abort the whole tenant's retention sweep
+    // for every other field; skip it (no retention policy to apply anyway).
+    let parsed: ReturnType<typeof parseSerializedField>;
+    try {
+      parsed = parseSerializedField(raw.serialized_field);
+    } catch {
+      continue;
+    }
+    if (parsed?.retention) {
+      out.set(raw.field_key, parsed.retention);
+    }
+  }
+  return out;
+}
+
+interface InstantLike {
+  readonly epochMilliseconds: number;
+}
+
+// guard:dup-ok — false positive: gleiche TypeGuard-Struktur wie isFieldDefinitionRow, völlig andere Semantik
+function isInstantLike(value: unknown): value is InstantLike {
+  if (!value || typeof value !== "object") return false;
+  if (!("epochMilliseconds" in value)) return false;
+  return typeof value.epochMilliseconds === "number";
+}
+
+function parseInstant(value: unknown): Instant | null {
+  if (value == null) return null;
+  const T = getTemporal();
+  try {
+    if (typeof value === "string") return T.Instant.from(value);
+    // `Number(date)` on a Date instance returns epoch-ms — matches getTime()
+    // without tripping the no-date-api guard.
+    if (value instanceof Date) return T.Instant.fromEpochMilliseconds(Number(value));
+    if (isInstantLike(value)) return T.Instant.fromEpochMilliseconds(value.epochMilliseconds);
+    return null;
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,98 @@
+import * as z from "zod";
+import { SUPPORTED_FIELD_TYPES } from "./constants.js";
+
+// Field-Type-Validator — pinnt valid type-Werte für fieldDefinition.
+const fieldTypeSchema = z.enum(SUPPORTED_FIELD_TYPES);
+
+// Per-field access-control. When set, `set/clear-custom-field` handlers
+// require the calling user to hold at least one of the listed roles —
+// in addition to the handler-level RBAC. Absent or empty `write` means
+// the handler-level RBAC is the only gate.
+//
+// `read` is reserved for the postQuery-flatten pipeline (T1.5c+); not
+// enforced in T1.5b.
+export const customFieldAccessSchema = z
+  .object({
+    read: z.array(z.string()).optional(),
+    write: z.array(z.string()).optional(),
+  })
+  .optional();
+export type CustomFieldAccess = z.infer<typeof customFieldAccessSchema>;
+
+// 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: { ... } }
+//
+// `fieldAccess` (T1.5b) is the structured key recognised by the handlers.
+// Everything else stays loose pending B2's per-type discriminated-union —
+// EXCEPT `sensitive`, which is explicitly rejected below: custom fields
+// carry supplemental business data only, PII support was removed (#972).
+const serializedFieldSchema = z
+  .looseObject({
+    type: fieldTypeSchema,
+    fieldAccess: customFieldAccessSchema,
+    // `retention` (T1.5d): per-field expiry. The retention-cron strips
+    // values whose host-row `modified_at` is older than `keepFor`. Strategy
+    // `delete` removes the key from the customFields jsonb; `anonymize`
+    // sets it to `null` (key stays, value gone — preserves the schema
+    // shape for downstream consumers).
+    retention: z
+      .object({
+        keepFor: z
+          .string()
+          .regex(/^\d+[hdwmy]$/, "keepFor must match /^\\d+[hdwmy]$/ (e.g. '30d', '10y')"),
+        strategy: z.enum(["delete", "anonymize"]),
+      })
+      .optional(),
+  })
+  .refine((v) => typeof v["type"] === "string", "serializedField must have a string `type`")
+  .refine(
+    (v) => !("sensitive" in v),
+    "custom fields don't support PII — `sensitive` was removed (#972). Model personal data as a schema entity field with a pii/userOwned/tenantOwned annotation instead.",
+  );
+
+// 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 `update-tenant-field` — bewusst dieselbe Shape wie define
+// (Vollersatz-Semantik: der Edit-Screen schickt den kompletten neuen Stand;
+// entityName+fieldKey sind die Identität, type ist immutable und wird im
+// Handler gegen den Bestand geprüft).
+export const updateFieldPayloadSchema = defineFieldPayloadSchema;
+export type UpdateFieldPayload = DefineFieldPayload;
+
+// 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>;

package/packages/bundled-features/src/custom-fields/web/client-plugin.tsx

@@ -0,0 +1,27 @@
+// @runtime client
+// Client-Feature-Factory für custom-fields. Wird vom App-Code in
+// createKumikoApp({ clientFeatures: [customFieldsClient()] }) eingehängt
+// und registriert die CustomFieldsFormSection unter dem Namen
+// CUSTOM_FIELDS_FORM_EXTENSION_NAME im ExtensionSectionsProvider. Apps
+// referenzieren den Namen im Screen-Schema:
+//
+//   layout: { sections: [
+//     { kind: "extension", title: "...", contributesToFormSubmit: true, component: {
+//       react: { __component: CUSTOM_FIELDS_FORM_EXTENSION_NAME }
+//     } },
+//   ]}
+
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { CUSTOM_FIELDS_FEATURE_NAME, CUSTOM_FIELDS_FORM_EXTENSION_NAME } from "../constants.js";
+import { CustomFieldsFormSection } from "./custom-fields-form-section.js";
+import { defaultTranslations } from "./i18n.js";
+
+export function customFieldsClient(): ClientFeatureDefinition {
+  return {
+    name: CUSTOM_FIELDS_FEATURE_NAME,
+    extensionSectionComponents: {
+      [CUSTOM_FIELDS_FORM_EXTENSION_NAME]: CustomFieldsFormSection,
+    },
+    translations: defaultTranslations,
+  };
+}