@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/custom-fields/web/custom-fields-form-section.tsx

@@ -0,0 +1,247 @@
+// @runtime client
+// CustomFieldsFormSection — extension-section component für entityEdit-
+// Screens. Lädt die fieldDefinition-Liste des Tenants, filtert auf die
+// host-Entity, rendert pro Definition einen typed Input, dispatched
+// `custom-fields:write:set-custom-field` pro non-empty Value beim Save.
+//
+// Mount via createKumikoApp({ clientFeatures: [customFieldsClient()] })
+// — der clientFeature-Factory registriert diese Component unter dem
+// Namen `CustomFieldsFormSection`, den die App im Screen-Schema via
+// `component: { react: { __component: CUSTOM_FIELDS_FORM_EXTENSION_NAME } }`
+// referenziert.
+
+import {
+  type ExtensionSubmitResult,
+  useDispatcher,
+  useExtensionFormSubmit,
+  usePrimitives,
+  useQuery,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { CustomFieldsHandlers, CustomFieldsQueries } from "../constants.js";
+
+type FieldDefinitionRow = {
+  readonly id: string;
+  readonly entityName: string;
+  readonly fieldKey: string;
+  readonly type: string;
+  readonly required: boolean;
+  readonly displayOrder: number;
+};
+
+type FieldDefinitionListResponse = {
+  readonly rows: readonly FieldDefinitionRow[];
+};
+
+export function CustomFieldsFormSection({
+  entityName,
+  entityId,
+  initialValues,
+}: {
+  readonly entityName: string;
+  readonly entityId: string | null;
+  /** Bereits gespeicherte customField-Werte der Entity (aus der detail-
+   *  row durchgereicht). Ohne sie wäre die Section write-only — die Inputs
+   *  zeigen den Bestand beim Edit. `pending` trackt nur Änderungen, also
+   *  bleibt der Save-Button bis zur ersten Eingabe disabled. */
+  readonly initialValues?: Readonly<Record<string, unknown>>;
+}): ReactNode {
+  const { Banner, Button, Field, Input, Text } = usePrimitives();
+  const t = useTranslation();
+  const dispatcher = useDispatcher();
+  const query = useQuery<FieldDefinitionListResponse>(
+    CustomFieldsQueries.fieldDefinitionList,
+    {},
+    { enabled: entityId !== null },
+  );
+  const [pending, setPending] = useState<Readonly<Record<string, string>>>({});
+  const [saving, setSaving] = useState(false);
+  const [errorKey, setErrorKey] = useState<string | null>(null);
+
+  // Vor den early-returns berechnet, weil useExtensionFormSubmit (Hook) davor
+  // laufen muss. matchingFields ist während des Loadings []; dirty bleibt dann
+  // false. Dirty = weicht vom GESPEICHERTEN Wert ab (nicht von ""), sonst ist
+  // das Leeren eines Bestandswerts unsichtbar und würde übersprungen statt
+  // gecleart.
+  const matchingFields = (query.data?.rows ?? [])
+    .filter((f) => f.entityName === entityName)
+    .slice()
+    .sort((a, b) => a.displayOrder - b.displayOrder);
+  const initialDisplay = (field: (typeof matchingFields)[number]): string =>
+    displayValue(field.type, initialValues?.[field.fieldKey]);
+  const changedFields = matchingFields.filter((field) => {
+    const raw = pending[field.fieldKey];
+    return raw !== undefined && raw !== initialDisplay(field);
+  });
+  const dirty = changedFields.length > 0;
+
+  // Schreibt alle geänderten Felder via set/clear. Genutzt vom composed-Submit
+  // (Haupt-Form ruft den Handler nach dem Entity-Write) UND vom standalone-
+  // Button (wenn die Section ohne umgebende composed-Form gemountet ist).
+  const flushChanges = async (targetEntityId: string): Promise<ExtensionSubmitResult> => {
+    for (const field of changedFields) {
+      const raw = pending[field.fieldKey] ?? "";
+      const result =
+        raw === ""
+          ? await dispatcher.write(CustomFieldsHandlers.clearCustomField, {
+              entityName,
+              entityId: targetEntityId,
+              fieldKey: field.fieldKey,
+            })
+          : await dispatcher.write(CustomFieldsHandlers.setCustomField, {
+              entityName,
+              entityId: targetEntityId,
+              fieldKey: field.fieldKey,
+              value: coerceValue(field.type, raw),
+            });
+      if (!result.isSuccess) {
+        return {
+          isSuccess: false,
+          errorKey: result.error?.i18nKey ?? "custom-fields.errors.saveFailed",
+        };
+      }
+    }
+    setPending({});
+    return { isSuccess: true };
+  };
+
+  // composed = innerhalb eines entityEdit-Forms → kein eigener Save-Button,
+  // die Section schreibt beim Haupt-Save mit (Bug-Bash 3 #1). Außerhalb einer
+  // composed-Form (composed === false) bleibt der standalone-Button.
+  const composed = useExtensionFormSubmit({
+    dirty,
+    onSubmit: (ctx) => flushChanges(ctx.entityId),
+  });
+
+  if (entityId === null) {
+    return (
+      <Banner variant="info" testId="custom-fields-form-create-mode">
+        <Text>{t("custom-fields.form.createMode")}</Text>
+      </Banner>
+    );
+  }
+  if (query.loading && query.data === null) {
+    return (
+      <Banner variant="loading" testId="custom-fields-form-loading">
+        <Text>{t("custom-fields.form.loading")}</Text>
+      </Banner>
+    );
+  }
+  if (query.error) {
+    return (
+      <Banner variant="error" testId="custom-fields-form-error">
+        <Text>{t(query.error.i18nKey, query.error.i18nParams)}</Text>
+      </Banner>
+    );
+  }
+  if (matchingFields.length === 0) {
+    return (
+      <Banner variant="info" testId="custom-fields-form-empty">
+        <Text>{t("custom-fields.form.empty", { entityName })}</Text>
+      </Banner>
+    );
+  }
+
+  const handleStandaloneSave = async (): Promise<void> => {
+    setSaving(true);
+    setErrorKey(null);
+    try {
+      const result = await flushChanges(entityId);
+      if (!result.isSuccess) {
+        setErrorKey(result.errorKey ?? "custom-fields.errors.saveFailed");
+      }
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <div data-testid="custom-fields-form-section">
+      {matchingFields.map((field) => (
+        <Field
+          key={field.id}
+          id={`custom-field-${field.fieldKey}`}
+          label={field.fieldKey}
+          required={field.required}
+        >
+          {renderInputFor(
+            field,
+            pending[field.fieldKey] ?? displayValue(field.type, initialValues?.[field.fieldKey]),
+            (v) => setPending((p) => ({ ...p, [field.fieldKey]: v })),
+          )}
+        </Field>
+      ))}
+      {!composed && (
+        <Button
+          variant="primary"
+          onClick={() => void handleStandaloneSave()}
+          disabled={saving || !dirty}
+          testId="custom-fields-form-save"
+        >
+          {saving ? t("custom-fields.form.saving") : t("custom-fields.form.save")}
+        </Button>
+      )}
+      {!composed && errorKey !== null && (
+        <Banner variant="error" testId="custom-fields-form-save-error">
+          <Text>{t(errorKey)}</Text>
+        </Banner>
+      )}
+    </div>
+  );
+
+  function renderInputFor(
+    field: FieldDefinitionRow,
+    raw: string,
+    onChange: (v: string) => void,
+  ): ReactNode {
+    const id = `custom-field-${field.fieldKey}`;
+    const name = field.fieldKey;
+    if (field.type === "number") {
+      return (
+        <Input
+          kind="number"
+          id={id}
+          name={name}
+          value={raw === "" ? "" : Number(raw)}
+          onChange={(v) => onChange(v === undefined ? "" : String(v))}
+        />
+      );
+    }
+    if (field.type === "boolean") {
+      return (
+        <Input
+          kind="boolean"
+          id={id}
+          name={name}
+          value={raw === "true"}
+          onChange={(v) => onChange(v ? "true" : "false")}
+        />
+      );
+    }
+    if (field.type === "date") {
+      return (
+        <Input kind="date" id={id} name={name} value={raw} onChange={(v) => onChange(v ?? "")} />
+      );
+    }
+    return <Input kind="text" id={id} name={name} value={raw} onChange={onChange} />;
+  }
+}
+
+function coerceValue(type: string, raw: string): unknown {
+  if (type === "number") {
+    const n = Number(raw);
+    return Number.isNaN(n) ? raw : n;
+  }
+  if (type === "boolean") return raw === "true";
+  return raw;
+}
+
+// Umkehrung von coerceValue: gespeicherter jsonb-Wert → string-Form für den
+// Input. number/boolean/date/text werden so dargestellt, wie der Input sie
+// erwartet; fehlende Werte werden zu "".
+function displayValue(type: string, value: unknown): string {
+  if (value === undefined || value === null) return "";
+  if (type === "boolean") return value === true ? "true" : "false";
+  return String(value);
+}

package/packages/bundled-features/src/custom-fields/web/i18n.ts

@@ -0,0 +1,22 @@
+// @runtime client
+// Default translation bundle for the custom-fields UI. customFieldsClient()
+// hangs it into the LocaleProvider as a fallback bundle — apps override
+// individual keys via `customFieldsClient({ translations })`.
+//
+// Keys follow `custom-fields.<area>.<slug>`. `custom-fields.errors.saveFailed`
+// is a LOCAL fallback only — server handlers emit generic error i18nKeys
+// (errors.unprocessable / errors.notFound via fail* defaults), never a
+// custom-fields-specific key; the form prefers the server key when present.
+
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+
+export const defaultTranslations: TranslationsByLocale = {
+  en: {
+    "custom-fields.form.createMode": "Save the entity first to add custom field values.",
+    "custom-fields.form.loading": "Loading…",
+    "custom-fields.form.empty": 'No custom fields defined for "{entityName}".',
+    "custom-fields.form.save": "Save custom fields",
+    "custom-fields.form.saving": "Saving…",
+    "custom-fields.errors.saveFailed": "Save failed.",
+  },
+};

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

@@ -0,0 +1,8 @@
+// @runtime client
+export {
+  CUSTOM_FIELDS_FORM_EXTENSION_NAME,
+  CustomFieldsHandlers,
+  CustomFieldsQueries,
+} from "../constants.js";
+export { customFieldsClient } from "./client-plugin.js";
+export { CustomFieldsFormSection } from "./custom-fields-form-section.js";

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

@@ -0,0 +1,226 @@
+import { type DbRunner, extractTableName } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createJsonbField,
+  type FeatureRegistrar,
+  isSystemTenant,
+  type JsonbFieldDef,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { StoredEvent } from "@cosmicdrift/kumiko-framework/event-store";
+import { CUSTOM_FIELDS_EXTENSION, FIELD_DEFINITION_AGGREGATE_TYPE } from "./constants.js";
+import {
+  clearCustomFieldKey,
+  removeCustomFieldKeyForTenant,
+  removeCustomFieldKeyFromAllTenants,
+  setCustomFieldValue,
+} from "./db/queries/projection.js";
+
+import type { CustomFieldClearedPayload, CustomFieldSetPayload } from "./events.js";
+import { customFieldsFeature } from "./feature.js";
+
+// Helper für entity-definitions — fügt eine `customFields jsonb`-Spalte
+// hinzu. Consumer:
+//
+//   const propertyEntity = createEntity({
+//     fields: {
+//       name: createTextField({ required: true }),
+//       customFields: customFieldsField(),
+//     },
+//   });
+//
+// Spec-Promise: customFields verhält sich wie Stammfelder. Default `{}`,
+// NOT NULL — analog zu embedded-Spalten.
+// @wrapper-known semantic-alias
+export function customFieldsField(): JsonbFieldDef {
+  return createJsonbField();
+}
+
+// Vollständige integration der custom-fields-Bundle für eine spezifische
+// host-entity. Eine einzige Aufruf-Stelle pro consumer registriert ALLE
+// wiring-Aspekte: extension-tracking, MSP für value-projection, rebuild-
+// replay via extendEntityProjection, postQuery-hook für API-flatten,
+// search-payload-extension für indexable customFields.
+//
+// Consumer-side:
+//
+//   defineFeature("property-mgmt", (r) => {
+//     r.entity("property", propertyEntity);  // muss customFieldsField() haben
+//     r.requires(CUSTOM_FIELDS_FEATURE_NAME);
+//     wireCustomFieldsFor(r, "property", propertyTable);
+//   });
+//
+// Der `entityTable`-Parameter ist die Drizzle-Table-Instance (typically
+// `buildEntityTable(name, entity)`-Output). Die Closure über `entityTable`
+// erspart der MSP-apply-fn einen runtime-table-lookup über die Registry.
+//
+// **Was registriert wird**:
+//
+//   1. r.useExtension("customFields", entityName) — opt-in marker,
+//      ermöglicht boot-validation und usage-tracking via Registry.
+//
+//   2. r.multiStreamProjection — consumes customField.set/.cleared events
+//      die customer's set-custom-field / clear-custom-field write-handlers
+//      emittiert haben. Updated entityTable.customFields jsonb über
+//      jsonb_set / jsonb-key-removal.
+//
+//   3. r.extendEntityProjection — hängt dieselben apply-Handler in die
+//      implicit projection der host-entity, damit rebuildProjection die
+//      customField-Events mit-replayt. Ohne das fällt customFields bei
+//      jedem Entity-Rebuild (Schema-Migration!) auf `{}` zurück (#759).
+//
+//   4. r.entityHook("postQuery", entity, flatten-fn) — bei JEDEM Read auf
+//      diese entity wird `row.customFields` jsonb auf root-level expanded
+//      damit die API-response wie Stammfelder aussieht.
+//
+//   5. r.searchPayloadExtension(entity, contributor) — searchable
+//      customFields-keys werden flach ins Meilisearch-Index-Doc beigetragen
+//      (F3-wiring).
+//
+//   6. fieldDefinition.deleted-Event-Handler im selben MSP — bei delete
+//      einer fieldDefinition werden orphan values aus allen entity-rows
+//      entfernt (key-removal pro fieldKey).
+export function wireCustomFieldsFor<TReg extends FeatureRegistrar<string>>(
+  r: TReg,
+  entityName: string,
+  entityTable: unknown,
+): void {
+  // biome-ignore lint/correctness/useHookAtTopLevel: r.useExtension is a registrar-API method, not a React hook — false positive on the "use"-prefix heuristic.
+  r.useExtension(CUSTOM_FIELDS_EXTENSION, entityName);
+
+  // Qualified event-type-names — sourced from typed EventDef.name handles
+  // (compile-time literal-typed, no Template-Literal-Drift à la toKebab-
+  // collapse-bug die T1 aufgedeckt hat).
+  const setEventType = customFieldsFeature.exports.setEvent.name;
+  const clearedEventType = customFieldsFeature.exports.clearedEvent.name;
+  const fieldDefDeletedType = customFieldsFeature.exports.fieldDefinitionDeletedEvent.name;
+
+  // Geteilte apply-Bodies: die MSP liefert sie live (async cursor), die
+  // entity-projection-extension replayt sie in rebuildProjection — gleiche
+  // SQL-Helper, beide idempotent. 2-Param-Signatur ist die gemeinsame
+  // Teilmenge von MultiStreamApplyFn und SingleStreamApplyFn.
+  const applyCustomFieldSet = async (event: StoredEvent, tx: DbRunner): Promise<void> => {
+    // skip: feuert für ALLE aggregate-types die customField.set emittieren —
+    // wir wollen nur die unserer wired host-entity. Andere consumers haben
+    // eigene Wirings für ihre Entities.
+    if (event.aggregateType !== entityName) return;
+    const payload = event.payload as CustomFieldSetPayload; // @cast-boundary engine-payload
+
+    // skip: a value-less customField.set is an anomaly since #972 (every set
+    // carries its value; the sensitive self-projection path was removed) —
+    // warn and leave the row untouched instead of binding undefined.
+    if (payload.value === undefined) {
+      // biome-ignore lint/suspicious/noConsole: boot-adjacent correctness canary, no logger available in an apply function
+      console.warn(
+        `[custom-fields] customField.set for "${payload.fieldKey}" on ${event.aggregateType}/${event.aggregateId} has no value — skipping (value-less sets should not exist since #972).`,
+      );
+      // skip: warned above — leave the row untouched instead of binding undefined
+      return;
+    }
+
+    // jsonb_set: setze key auf value. Wenn key noch nicht existiert →
+    // wird angelegt (create_missing=true ist default). value muss als
+    // jsonb-literal kommen.
+    const tableName = extractTableName(entityTable, "custom-fields/wire-for-entity");
+    await setCustomFieldValue(
+      tx,
+      tableName,
+      payload.fieldKey,
+      payload.value,
+      event.aggregateId,
+      event.tenantId,
+    );
+  };
+
+  const applyCustomFieldCleared = async (event: StoredEvent, tx: DbRunner): Promise<void> => {
+    // skip: feuert für alle aggregate-types — nur unsere host-entity
+    // verarbeiten.
+    if (event.aggregateType !== entityName) return;
+    const payload = event.payload as CustomFieldClearedPayload; // @cast-boundary engine-payload
+
+    // jsonb minus operator (`-`) entfernt key aus jsonb-object.
+    const tableName = extractTableName(entityTable, "custom-fields/wire-for-entity");
+    await clearCustomFieldKey(tx, tableName, payload.fieldKey, event.aggregateId, event.tenantId);
+  };
+
+  const applyFieldDefinitionDeleted = async (event: StoredEvent, tx: DbRunner): Promise<void> => {
+    // fieldDefinition.deleted fires nur einmal pro fieldDef-delete
+    // (NICHT per-entity). Wir entfernen den key aus ALLEN rows der host-
+    // entity falls die deleted-fieldDef für diese entity galt.
+    const payload = event.payload as {
+      entityName: string;
+      fieldKey: string;
+      tenantId?: TenantId;
+    }; // @cast-boundary engine-payload
+    // skip: fieldDefinition.deleted feuert für ALLE fieldDefs cross-entity;
+    // nur wenn die deleted-fieldDef diese host-entity betraf, cleanen wir
+    // ihre Rows.
+    if (payload.entityName !== entityName) return;
+
+    const tableName = extractTableName(entityTable, "custom-fields/wire-for-entity");
+    // Scope cleanup to the deleted definition's owning tenant. System-scope
+    // definitions apply to every tenant → cascade across all rows; tenant-
+    // scope deletions must only touch that tenant's rows, else deleting one
+    // tenant's field strips the same kebab key from every tenant (data loss).
+    // Fallback to the event's stream tenantId for events appended before the
+    // payload carried tenantId.
+    const defTenantId = payload.tenantId ?? event.tenantId;
+    if (isSystemTenant(defTenantId)) {
+      await removeCustomFieldKeyFromAllTenants(tx, tableName, payload.fieldKey);
+    } else {
+      await removeCustomFieldKeyForTenant(tx, tableName, payload.fieldKey, defTenantId);
+    }
+  };
+
+  r.multiStreamProjection({
+    name: `custom-fields-${entityName}-projection`,
+    apply: {
+      [setEventType]: applyCustomFieldSet,
+      [clearedEventType]: applyCustomFieldCleared,
+      [fieldDefDeletedType]: applyFieldDefinitionDeleted,
+    },
+  });
+
+  // Rebuild-wiring (#759): ohne das replayt rebuildProjection nur die
+  // entity-lifecycle-Events und resettet jede customFields-jsonb auf ihr
+  // Default `{}` — die Werte existieren ausschließlich als customField.set/
+  // .cleared-Events. set/cleared reiten auf dem HOST-entity-Stream
+  // (aggregateType = entityName, von source schon abgedeckt);
+  // fieldDefinition.deleted lebt auf dem "field-definition"-Stream und
+  // kommt deshalb als extra source dazu.
+  r.extendEntityProjection(entityName, {
+    sources: [FIELD_DEFINITION_AGGREGATE_TYPE],
+    apply: {
+      [setEventType]: applyCustomFieldSet,
+      [clearedEventType]: applyCustomFieldCleared,
+      [fieldDefDeletedType]: applyFieldDefinitionDeleted,
+    },
+  });
+
+  // postQuery-hook: flatten row.customFields jsonb auf root-level der
+  // API-response. Spec-Promise Z.4 "indistinguishable von Stammfeldern".
+  r.hook("postQuery", { allOf: entityName }, async ({ rows }) => ({
+    rows: rows.map((row) => {
+      const customFields = row["customFields"];
+      if (customFields && typeof customFields === "object" && !Array.isArray(customFields)) {
+        return {
+          ...(customFields as Record<string, unknown>), // @cast-boundary db-row jsonb runtime-untyped
+          ...row, // base fields win: a custom fieldKey named `id`/`name` must not shadow the real column
+        };
+      }
+      return row;
+    }),
+  }));
+
+  // Search-Payload-Extension: customFields-keys flach ins Index-Doc.
+  // Anders als postQuery-hook (der ALLE keys merged) trägt der Search-
+  // Contributor nur die als searchable=true definierten fields bei. v1
+  // ist conservatively: ALLES contribuieren — B2-follow-up filtert
+  // per fieldDefinition.searchable-flag.
+  r.searchPayloadExtension(entityName, ({ state }) => {
+    const customFields = state["customFields"];
+    if (customFields && typeof customFields === "object" && !Array.isArray(customFields)) {
+      return customFields as Record<string, unknown>; // @cast-boundary db-row jsonb runtime-untyped
+    }
+    return {};
+  });
+}

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

@@ -0,0 +1,79 @@
+// T1.5c — user-data-rights wiring for custom-fields.
+
+import { type DbRunner, extractTableName } from "@cosmicdrift/kumiko-framework/db";
+import type { UserDataExportSnippet, UserDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";
+import { EXT_USER_DATA, type FeatureRegistrar } from "@cosmicdrift/kumiko-framework/engine";
+import { selectCustomFieldsHostRows } from "./db/queries/user-data-rights.js";
+
+export interface WireCustomFieldsUserDataRightsOptions {
+  readonly entityName: string;
+  readonly entityTable: unknown;
+  readonly userIdColumn: string;
+}
+
+interface CustomFieldsHostRow {
+  readonly id: string;
+  readonly customFields: Record<string, unknown> | null;
+}
+
+function asCustomFieldsHostRow(value: unknown): CustomFieldsHostRow | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  if (!("id" in value) || typeof value.id !== "string") return null;
+  const record = value as Record<string, unknown>;
+  const cf = record["custom_fields"] ?? record["customFields"];
+  if (cf === undefined) return null;
+  if (cf === null) return { id: value.id, customFields: null };
+  if (!cf || typeof cf !== "object" || Array.isArray(cf)) return null;
+  return { id: value.id, customFields: Object.fromEntries(Object.entries(cf)) };
+}
+
+// fw#2914 — selectCustomFieldsHostRows runs raw SQL against a dynamic host
+// table name (opts.entityTable varies per call site), so it can't go through
+// TenantDb's typed method API (table param must be a known SchemaTable). The
+// SQL text itself still filters `tenant_id = ctx.tenantId`, so this stays a
+// single-tenant read — the escapeHatch is only for the raw-SQL mechanism, not
+// for cross-tenant access.
+const CUSTOM_FIELDS_EXPORT_REASON =
+  "custom-fields export reads a generic customFields column via raw SQL against a dynamic host table name, not expressible through TenantDb's typed method API; the query still filters tenant_id = ctx.tenantId";
+
+async function exportCustomFields(
+  db: DbRunner,
+  ctx: UserDataHookCtx,
+  tableName: string,
+  opts: WireCustomFieldsUserDataRightsOptions,
+): Promise<UserDataExportSnippet | null> {
+  const rows = await selectCustomFieldsHostRows(
+    db,
+    tableName,
+    opts.userIdColumn,
+    ctx.userId,
+    ctx.tenantId,
+  );
+  const snippetRows: Array<{ id: string; customFields: Record<string, unknown> }> = [];
+  for (const raw of rows) {
+    const row = asCustomFieldsHostRow(raw);
+    if (!row) continue;
+    const customFields = row.customFields;
+    if (customFields && Object.keys(customFields).length > 0) {
+      snippetRows.push({ id: row.id, customFields });
+    }
+  }
+  if (snippetRows.length === 0) return null;
+  return { entity: `${opts.entityName}.customFields`, rows: snippetRows };
+}
+
+// Export-only wiring: custom fields hold supplemental business data, not PII
+// (#972) — there is nothing to redact on user-forget, only Art. 20 export.
+export function wireCustomFieldsUserDataRightsFor<TReg extends FeatureRegistrar<string>>(
+  r: TReg,
+  opts: WireCustomFieldsUserDataRightsOptions,
+): void {
+  const tableName = extractTableName(opts.entityTable, "custom-fields/wire-user-data-rights");
+
+  // biome-ignore lint/correctness/useHookAtTopLevel: r.useExtension is a registrar API, not a React hook.
+  r.useExtension(EXT_USER_DATA, opts.entityName, {
+    export: async (ctx: UserDataHookCtx) =>
+      exportCustomFields(ctx.db.unsafeRaw(CUSTOM_FIELDS_EXPORT_REASON), ctx, tableName, opts),
+    escapeHatch: { reason: CUSTOM_FIELDS_EXPORT_REASON },
+  });
+}

package/packages/bundled-features/src/data-retention/_internal/parse-override.ts

@@ -0,0 +1,34 @@
+// Geteilter Override-Parser fuer policy-for-Query und resolve-for-tenant-
+// Helper. War vorher 1:1 in beiden Files dupliziert (Memory
+// `feedback_bulk_patterns` — Drift-Risiko bei Schema-Aenderungen).
+
+import { retentionOverrideSchema } from "../override-schema.js";
+import type { RetentionOverride } from "../resolver.js";
+
+export function parseRetentionOverrideOrNull(
+  raw: string | null,
+  tenantId: string,
+  callerLabel: string,
+): RetentionOverride | null {
+  if (!raw || raw.trim() === "") return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e: unknown) {
+    const reason = e instanceof Error ? e.message : String(e);
+    // biome-ignore lint/suspicious/noConsole: operator visibility for DB-corruption edge-case
+    console.warn(
+      `[${callerLabel}] tenant ${tenantId}: stored override is not valid JSON, ignoring. Reason: ${reason}`,
+    );
+    return null;
+  }
+  const validation = retentionOverrideSchema.safeParse(parsed);
+  if (!validation.success) {
+    // biome-ignore lint/suspicious/noConsole: operator visibility for schema-drift
+    console.warn(
+      `[${callerLabel}] tenant ${tenantId}: stored override fails schema validation, ignoring. Issue: ${validation.error.issues[0]?.path.join(".")}: ${validation.error.issues[0]?.message}`,
+    );
+    return null;
+  }
+  return validation.data;
+}

package/packages/bundled-features/src/data-retention/changes.json

@@ -0,0 +1,50 @@
+[
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Retention hardDelete keeps cross-entity shared files and isolates storage errors per row",
+    "detail": "Retention hardDelete no longer deletes a fileRef that a live row of another entity type still references in a file/image field (relevant for unbound uploads). A storage error while deleting a row's files (for example a missing list permission) now skips only that row with `file_delete_failed` instead of aborting the whole tenant's cleanup run."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Retention hardDelete pages past stuck file rows and blockDelete reports personal fields without anonymize",
+    "detail": "Retention hardDelete on entities with file fields now pages by id, so rows stuck on a storage failure or a missing file storage no longer starve the rows behind them. A `blockDelete` entity with a personal field but no `anonymize` function is reported as `missing_anonymize_fields` again after the hold expires; only entities without any anonymizable subject field stay silent. The framework exports `entityHasAnonymizableSubjectField` for this check."
+  },
+  {
+    "version": "0.330.1",
+    "type": "fix",
+    "title": "blockDelete entities without anonymize fields no longer log skips or boot warnings"
+  },
+  {
+    "version": "0.315.0",
+    "type": "breaking",
+    "title": "forget/policy-for now honor the tenant retention preset",
+    "migration": "ResolveForTenantArgs.tenantPreset was renamed to preloadedTenantPreset (mirrors preloadedOverride): omitting it now makes the resolver load the tenant's retention preset itself instead of skipping it. Behavior change: forget (Art. 17) and the policy-for query now honor the tenant's compliance-profile-derived retention preset, not just entity defaults and per-tenant overrides. For tenants with a mapped compliance profile (e.g. de-hr-dsgvo-hgb), forget now keeps invoice/booking/contract rows via blockDelete and anonymizes order rows instead of hard-deleting them; notes-history mentions on such hosts are no longer shredded when the mentioned note's host entity is preset-protected. policy-for (data-retention:query:policy-for) now returns source: \"preset\" where it previously returned \"none\" for these entities."
+  },
+  {
+    "version": "0.313.0",
+    "type": "fix",
+    "title": "data-retention hardDelete now erases a purged row's own KMS subject key",
+    "detail": "Refs #2057 (partial fix — the hardDelete path only). run-retention-\ncleanup's hardDelete forgot the row's event history via the executor but\nnever crypto-shredded its KMS subject key, leaving the DEK live after the\nrow was gone. It now erases the key in the same per-row sub-transaction as the\nforget (an eraseKey throw rolls the forget back too), mirroring run-\nforget-cleanup.ts's forget -> eraseKey -> nullBlindIndexesForSubject\nordering. Only the row's own recordOwned/self-pii subjects are erased;\na userOwned or tenantOwned field's subject is the REFERENCED user/tenant,\nnot this row, and may still protect other live rows elsewhere — those\nkeys are never touched. No migration needed."
+  },
+  {
+    "version": "0.309.0",
+    "type": "breaking",
+    "title": "data-retention hardDelete now purges file bytes + fileRef rows, not just the entity row (fw#3089)",
+    "migration": "hardDelete previously deleted only the entity row and left every file/image/files/images field's storage bytes and `file_refs` row behind — a DSGVO Art. 17 gap. As of this release, an expired row's un-shared fileRefs (same tenant, bound to this row, not referenced by another row of the same entity) have their storage bytes deleted (including derivatives/thumbnails), then their `file_refs` row, then the entity row itself. A fileRef still referenced by another row, or bound to a different entity/record, is left untouched. Without a resolvable file-storage provider in the retention cron's job context, an entity with pending file deletions is skipped entirely (`skipped` reason `missing_file_storage`) rather than silently dropping the row with orphaned bytes; a storage-delete failure skips the row too (`file_delete_failed`) and retries on the next run. Before upgrading, a consumer relying on hardDelete NOT touching file storage should: list entities with `retention.strategy: \"hardDelete\"` and at least one file/image/files/images field, count rows already past `keepFor` for each, and confirm the referenced files are safe to delete (not needed elsewhere) before the next cron run."
+  },
+  {
+    "version": "0.167.1",
+    "type": "fix",
+    "title": "blockDelete boot warning only fires for entities that have a subject (fw#1622).",
+    "detail": "The warning \"retention.strategy=blockDelete but no field has an anonymize-function\" checked the strategy alone. blockDelete is the legal-hold mode and therefore the obvious choice for anything under a statutory retention period — including entities that hold nothing but business data and foreign keys. Those got warned at every boot about something that cannot be satisfied: there is nothing to anonymize, and User-Forget never reaches a row without a subject. The warning made the correct declaration louder than the wrong one. It now requires at least one field annotated pii/userOwned/tenantOwned.",
+    "migration": "None. Warnings disappear for entities without subject-annotated fields; entities that do carry PII still get warned, unchanged."
+  },
+  {
+    "version": "0.116.0",
+    "type": "improvement",
+    "title": "data-retention cleanup now implements the `anonymize` strategy (per-field anonymize funct…",
+    "detail": "data-retention cleanup now implements the `anonymize` strategy (per-field anonymize functions applied via the event-store executor, idempotent — a re-run appends zero events) and completes `blockDelete`: rows stay untouched during the keepFor legal hold, after expiry the anonymize functions run (row stays, person link goes). `RunRetentionCleanupResult.anonymizeDeferred` is replaced by `anonymized: number`; entities with an anonymize/blockDelete policy but no anonymize-annotated fields are reported in `skipped` with reason `missing_anonymize_fields`."
+  }
+]