@cosmicdrift/kumiko-types 0.326.1 → 0.328.0

package/src/fields.ts

@@ -1,1114 +0,0 @@
-// --- Field Types ---
-
-import type { VariantSpec } from "./derivatives-types";
-
-// OwnershipMap is declared in ./ownership.ts — field-access maps to
-// per-role ownership rules. A legacy `readonly string[]` form is still
-// accepted at the type layer during migration: features that pass an
-// array are auto-normalized to { [role]: "all" } at registry build.
-// Long-term: string[] disappears.
-import type { OwnershipMap } from "./ownership";
-import type { EntityTenancy } from "./tenancy-brand";
-
-export type FieldAccess = {
-  readonly read?: OwnershipMap | readonly string[];
-  readonly write?: OwnershipMap | readonly string[];
-};
-
-// `sensitive: true` — the field's value is excluded from caller-facing event
-// echoes in write responses (#820) and MUST be ciphertext-at-rest: boot
-// validation requires a subject annotation (pii / userOwned / tenantOwned)
-// or `encrypted: true` (#967). Event payloads carry the table ciphertext,
-// so replay reproduces the row byte-identically; plaintext never lands in
-// permanent history. Use for password hashes, API tokens, bank details,
-// tax IDs. See docs/plans/architecture/projections.md.
-
-// --- PII / Subject-Key Annotations (GDPR Art. 17) ---
-//
-// Four independent mechanisms, NOT interchangeable. Picking the wrong
-// `personal`/`find` combination is the recurring mistake this table exists
-// to prevent: `encrypted: true` looks like the strongest option and is the
-// only one with NO erasure guarantee.
-//
-//   resolved flag                               | at rest    | searchable | Art. 17 erasure
-//   --------------------------------------------|------------|------------|---------------
-//   (none)                                      | plaintext  | yes        | no
-//   allowPlaintext + anonymize                  | plaintext  | yes        | read side only
-//   pii / userOwned / tenantOwned / recordOwned | ciphertext | yes *      | yes, key erase
-//   encrypted: true                             | ciphertext | no         | NO
-//
-//   * Subject-annotated + `searchable: true` (#1610): search consumer
-//     decrypts into Meilisearch. Events/projection stay ciphertext.
-//     eraseKey paths purge docs via purgeSearchDocumentsForSubject.
-//     `lookupable: true` still covers equality (blind index). `sortable`
-//     stays forbidden — sorting reads the ciphertext column.
-//
-// Encrypting a field is NOT a reason to make it unfindable. A user table you
-// cannot search by name is a user table with no working search. The line that
-// actually forbids search is `sensitive: true` — nobody may read those values
-// back, and the event-store executor already strips them before the search
-// consumer ever sees a payload. Password hashes, API tokens, bank details:
-// never indexed. Email, username, display name: encrypted at rest, findable.
-//
-// Why `encrypted: true` erases nothing: it uses the app-wide master key,
-// which is never destroyed per subject. Encryption-at-rest, nothing more.
-// Only a subject annotation binds the field to a per-subject key that
-// `crypto-shredding:write:forget-subject` (or the tenant-destroy hook's
-// eraseSubjectKeys) can destroy, which makes every event and every
-// projection copy of that subject unreadable at once.
-//
-// Why `anonymize` only covers the read side: it overwrites projection rows.
-// `kumiko_events` is append-only and keeps the original payload forever
-// (archiveStream stops REPLAY, it does not delete the row). A plaintext
-// field stays permanently readable in the event log for anyone with database
-// access — an access + retention question, not a crypto one. Choose it
-// deliberately, not by forgetting to annotate.
-//
-// Which subject owns the field — expressed via `personal` on the field
-// factory, resolved to these flags:
-//   - `personal: "self"`         → `pii: true`. the entity itself, user.email.
-//   - `personal: { of: "<f>" }`  → `userOwned: { ownerField: "<f>" }`. the
-//                                  user referenced in that field.
-//                                  comment.body → comment.authorId.
-//   - `personal: "tenant"`       → `tenantOwned: true`. the current tenant
-//                                  (ctx.tenantId at write time).
-//                                  tenantBranding.brandColor.
-//   - `personal: "ref"`          → `subjectRef: true`. FK into `user` with no
-//                                  annotated content of its own (authorId,
-//                                  assigneeId).
-//   - `personal: { of: "id" }`   → `recordOwned: true`. the row itself is the
-//                                  subject — free-text content with no user
-//                                  reference of its own (a support note keyed
-//                                  only by its own row id).
-//   - `personal: false, reason`  → `allowPlaintext: "<reason>"`. deliberately
-//                                  plaintext; `reason` is mandatory snake_case.
-//
-// How findable it must stay — `find`, mandatory whenever `personal` names a
-// subject ("self" / { of } / "tenant"):
-//   - `find: "exact"`  → `lookupable: true`. equality only, via blind index.
-//   - `find: "fuzzy"`  → `lookupable: true, searchable: true`. substring/
-//                        full-text via the Meilisearch consumer (#1610).
-//   - `find: "none"`   → neither.
-//   - `find: "secret"` → `sensitive: true`. longText fields only allow
-//                        "none" | "secret" — no lookup/search machinery there.
-//
-// Worked examples, all live in this repo:
-//
-//   user.email (user/schema/user.ts) — login identifier, must stay findable.
-//     `personal: "self", find: "exact"`. Ciphertext everywhere, exact lookup
-//     via the blind index, gone when the user's subject key dies.
-//
-//   user.displayName (same file) — real name; substring search via Meili.
-//     `personal: "self", find: "fuzzy"` (#1610). Ciphertext in
-//     events/projection; plaintext only in the derived index; purged on
-//     forget.
-//
-//   ledger.description (ledger/entity.ts) — "Miete Januar" is accounting
-//     data that happens to read like PII, and full-text search over it is the
-//     point. `personal: false, reason: "is_business_data"`, cleaned up via
-//     retention, event log keeps the original. Accepted deliberately.
-//
-//   subscription.providerCustomerId (billing-foundation/entities.ts) — a
-//     Mollie/Stripe id, never searched. `personal: "tenant", find: "none"`,
-//     explicitly NOT `encrypted: true`: tenant-destroy erases the tenant
-//     subject key, and only the subject path shreds along with it (#800).
-//     Budget maxLength for ciphertext
-//     (`kumiko-pii:v1:<subject>:<blob>`, roughly plaintext × 2.3).
-//
-// `sensitive: true` is orthogonal to all of this — see its own note above.
-//
-// `anonymize` is the per-field function the retention-cleanup job calls when
-// the entity strategy is "anonymize" or a `blockDelete` deadline expired.
-// Sync or async (async when the pseudonym needs a lookup); the job awaits it.
-// Example: `() => "[ANONYMIZED]"` or `() => null`.
-//
-// Background specs (both shipped, kumiko-platform/docs/archive/plans/):
-// datenschutz/crypto-shredding.md, datenschutz/blind-index.md.
-// Internal, expanded flag shape a field definition carries after a factory
-// (createTextField, createTimestampField, ...) resolves the author-facing
-// `personal`/`find` annotations below. No field author sets this directly.
-export type ResolvedPiiFlags = {
-  readonly pii?: boolean;
-  readonly userOwned?: { readonly ownerField: string };
-  readonly tenantOwned?: boolean;
-  readonly recordOwned?: true;
-  readonly anonymize?: () => unknown | Promise<unknown>;
-  readonly allowPlaintext?: string;
-  /** Equality-Lookups (fetchOne/filter eq) bleiben trotz Verschluesselung
-   *  moeglich: generierte `<snake>_bidx`-Spalte traegt einen HMAC-Blind-
-   *  Index, Query-Compiler matchen `(col = $1 OR col_bidx = $2)`. Nur auf
-   *  text-Feldern MIT Subject-Annotation erlaubt (Boot-Validator).
-   *  Siehe docs/plans/datenschutz/blind-index.md (kumiko-framework#818). */
-  readonly lookupable?: true;
-  /** Foreign key into the `user` entity (authorId, assigneeId, ...) with no
-   *  annotated content of its own. Triggers no encryption — feeds only the
-   *  GDPR-hook-coverage boot guard, which otherwise can't see subject data
-   *  that lives purely in an FK column. */
-  readonly subjectRef?: true;
-};
-
-// --- Author-facing PII API (kumiko-framework#2250) ---
-//
-// Two questions instead of the twelve raw flags above: whose data is this
-// (`personal`, resolved to a subject key) and how findable must it stay
-// (`find`, resolved to the search/lookup flags). Field factories expand
-// these into `ResolvedPiiFlags` — see packages/framework/src/engine/factories.ts.
-export type PersonalSubject = "self" | { readonly of: string } | "tenant";
-export type Findability = "exact" | "fuzzy" | "none" | "secret";
-
-// Marks "no personal annotation given" — plain `Record<string, never>` would
-// force every OTHER intersected property (e.g. a factory's `required?: R`)
-// to `never` too, since its index signature applies to all string keys.
-// Naming the three annotation keys explicitly avoids that trap.
-//
-// kumiko-framework#2921: no longer part of PersonalAnnotations /
-// PersonalAnnotationsLongText — text and longText fields must declare an
-// explicit stance. It still applies to PersonalAnnotationsNoFind, whose
-// factories keep `personal` optional.
-type NoPersonalAnnotation = {
-  readonly personal?: never;
-  readonly find?: never;
-  readonly reason?: never;
-  readonly anonymize?: never;
-};
-
-export type PersonalAnnotations =
-  | {
-      readonly personal: PersonalSubject;
-      readonly find: Findability;
-      readonly anonymize?: () => unknown | Promise<unknown>;
-    }
-  | { readonly personal: "ref" }
-  | {
-      readonly personal: false;
-      readonly reason: string;
-      readonly anonymize?: () => unknown | Promise<unknown>;
-    };
-
-// longText has no lookupable/searchable machinery ("Kein searchable" — see
-// LongTextFieldDef doc) — only "does this need to stay a secret" applies.
-// Kept mandatory like `find` on PersonalAnnotations: no silent default.
-export type LongTextFindability = "none" | "secret";
-
-export type PersonalAnnotationsLongText =
-  | {
-      readonly personal: PersonalSubject;
-      readonly find: LongTextFindability;
-      readonly anonymize?: () => unknown | Promise<unknown>;
-    }
-  | { readonly personal: "ref" }
-  | {
-      readonly personal: false;
-      readonly reason: string;
-      readonly anonymize?: () => unknown | Promise<unknown>;
-    };
-
-// Same as PersonalAnnotations but without `find` — for field types with no
-// full-text/blind-index machinery (everything except text and longText).
-export type PersonalAnnotationsNoFind =
-  | {
-      readonly personal: PersonalSubject;
-      readonly anonymize?: () => unknown | Promise<unknown>;
-    }
-  | { readonly personal: "ref" }
-  | {
-      readonly personal: false;
-      readonly reason: string;
-      readonly anonymize?: () => unknown | Promise<unknown>;
-    }
-  | NoPersonalAnnotation;
-
-// --- Retention (DSGVO Art. 5(1)(e) + HGB/AO Aufbewahrungspflichten) ---
-//
-// Pro Entity definiert der Author eine Default-Retention-Policy. Tenant-
-// Admin uebersteuert sie via Compliance-Profile + Tenant-Override (Sprint 2).
-// Vier Strategien:
-//
-//   - "hardDelete"  — Row physisch weg nach `keepFor`. Logs, Sessions.
-//   - "softDelete"  — `deletedAt = now()`. Erlaubt spaetere Restore.
-//   - "anonymize"   — Felder mit `anonymize`-Funktion ueberschrieben,
-//                     Row bleibt. Order/Invoice mit gemischter PII +
-//                     Geschaeftsdaten.
-//   - "blockDelete" — Cleanup-Job ignoriert; User-Forget loest stattdessen
-//                     `anonymize` aus. Buchhaltung, Mandate, Patientenakten.
-//
-// `keepFor` ist eine Duration-String wie "30d", "10y", "6m". Parser
-// kommt im Cleanup-Job (Sprint 2). `reference` ist das Field das den
-// Lebenszeit-Anker liefert (Default: `createdAt`). Sessions z.B. nutzen
-// `lastSeenAt` damit aktive Sessions nicht weggemueht werden.
-//
-// Siehe docs/plans/features/core-data-retention.md und Sprint 2 in roadmap.md.
-export type RetentionDef = {
-  readonly keepFor: string;
-  readonly strategy: "hardDelete" | "softDelete" | "anonymize" | "blockDelete";
-  readonly reference?: string;
-};
-
-export type TextFieldDef = {
-  readonly type: "text";
-  /** Optional free-text semantics for the AI agent manifest — never rendered;
-   *  the i18n label is what users see. */
-  readonly description?: string;
-  readonly maxLength?: number;
-  readonly required?: boolean;
-  readonly searchable?: boolean;
-  readonly sortable?: boolean;
-  /** Author erlaubt Screen-Filter auf diesem Feld (Tier 2.7c).
-   *  Boot-Validator weist Filter mit `filterable !== true` zurück.
-   *  Default: false — analog zu `sortable`, opt-in. */
-  readonly filterable?: boolean;
-  readonly encrypted?: boolean;
-  readonly sensitive?: boolean;
-  /** A later run reads this field's value as an instruction — prompt, rule,
-   *  template. Every create/update whose payload writes it requires agent.risk
-   *  "high" on the directly-dispatched entry handler; a revert doesn't undo a
-   *  run that already read the compromised value. See irreversible-operation-gate. */
-  readonly readAsInstruction?: boolean;
-  /** "password" is a pure render hint (masked input) — no storage semantics. */
-  readonly format?: "email" | "url" | "phone" | "password";
-  readonly default?: string;
-  readonly access?: FieldAccess;
-  /** Mehrzeiliger Text — DefaultInput rendert dann ein <textarea> statt
-   *  <input type="text">. `true` = Default 4 Zeilen, `{ rows: N }` =
-   *  explizite Höhe. Search/sort/encrypt verhalten sich unverändert
-   *  identisch zu single-line — nur die Render-Surface wechselt. */
-  readonly multiline?: boolean | { readonly rows?: number };
-} & ResolvedPiiFlags;
-
-/**
- * Long-form text content — source-code, markdown, blog-posts, email-
- * templates, anything that can be megabytes large. Bewusst MINIMALE
- * Surface gegen `text`:
- *
- *   - **Kein `sortable`**: ORDER BY auf 100 KB-Strings kostet I/O ohne
- *     sinnvolles UX-Outcome (lex-Sortierung von Code ist Nonsense).
- *   - **Kein `searchable`**: ILIKE/Substring-Suche auf langen Texten
- *     skaliert nicht. Wer wirklich Volltextsuche will, nimmt den
- *     SearchAdapter (Meilisearch) — der hat eine eigene Pipeline mit
- *     Tokenizer + Index, NICHT diesen field-flag.
- *   - **Kein `filterable`**: WHERE auf langen Strings same Story wie
- *     sortable.
- *   - **Kein `format`**: email/url/phone sind kurz definierte Inputs,
- *     longText ist per Definition unstrukturiert.
- *
- * Type-level enforcement statt convention: wer sortable/searchable
- * braucht, nimmt `text` (mit den entsprechenden Skalierungs-Trade-offs).
- * DB-mapping ist identisch zu text (Postgres `text` ist unbounded).
- */
-export type LongTextFieldDef = {
-  readonly type: "longText";
-  readonly description?: string;
-  /** Optionale soft-Cap. Default unbounded (= Postgres-text-limit, 1 GB).
-   *  Nützlich für defensive Caps wie 1 MB damit ein verirrter Browser-
-   *  Paste nicht die DB sprengt. */
-  readonly maxLength?: number;
-  readonly required?: boolean;
-  readonly encrypted?: boolean;
-  readonly sensitive?: boolean;
-  /** A later run reads this field's value as an instruction — prompt, rule,
-   *  template. Every create/update whose payload writes it requires agent.risk
-   *  "high" on the directly-dispatched entry handler; a revert doesn't undo a
-   *  run that already read the compromised value. See irreversible-operation-gate. */
-  readonly readAsInstruction?: boolean;
-  readonly default?: string;
-  readonly access?: FieldAccess;
-  readonly multiline?: boolean | { readonly rows?: number };
-} & ResolvedPiiFlags;
-
-export type BooleanFieldDef = {
-  readonly type: "boolean";
-  readonly description?: string;
-  readonly required?: boolean;
-  readonly sortable?: boolean;
-  readonly filterable?: boolean;
-  readonly sensitive?: boolean;
-  readonly default?: boolean;
-  readonly access?: FieldAccess;
-};
-
-export type SelectFieldDef<TOptions extends readonly string[] = readonly string[]> = {
-  readonly type: "select";
-  readonly description?: string;
-  readonly options: TOptions;
-  readonly required?: boolean;
-  readonly sortable?: boolean;
-  readonly filterable?: boolean;
-  readonly sensitive?: boolean;
-  readonly default?: TOptions[number];
-  readonly access?: FieldAccess;
-  /** Renderer metadata: `"radio"` always renders the option set as a visible
-   *  radio group, `"dropdown"` always renders the combobox. Omitted = the
-   *  renderer's own heuristic picks (radio group for a few short labels,
-   *  dropdown otherwise). A `"radio"` group with many or long labels wraps —
-   *  the author owns that trade-off, the renderer does not override it. */
-  readonly display?: "radio" | "dropdown";
-} & ResolvedPiiFlags;
-
-// Mehrere Werte aus einer festen Options-Liste — UI rendert als
-// Checkbox-/Multi-Select-Kontrolle. Storage: jsonb-Array<string>;
-// jeder Eintrag muss in `options` enthalten sein.
-//
-// Wann statt `select`: wenn der User mehr als einen Wert gleichzeitig
-// auswählen darf (Führerscheinklassen, Tags, Sprachen, Skills).
-// Wann statt `embedded` mit Booleans: wenn die Option-Liste nicht
-// hardcoded sein soll oder bei mehr als ~5 Optionen — sonst explodiert
-// das embedded-Schema.
-//
-// Ordering: das Array bewahrt die Caller-Reihenfolge (jsonb-array, nicht
-// set). Das Framework dedupliziert beim Schreiben nicht — Validator
-// rejected Duplikate erst wenn Bedarf da ist.
-export type MultiSelectFieldDef<TOptions extends readonly string[] = readonly string[]> = {
-  readonly type: "multiSelect";
-  readonly description?: string;
-  readonly options: TOptions;
-  readonly required?: boolean;
-  readonly filterable?: boolean;
-  readonly sensitive?: boolean;
-  /** Default-Auswahl. Jeder Eintrag muss in `options` sein (Boot-Validator). */
-  readonly default?: readonly TOptions[number][];
-  readonly access?: FieldAccess;
-  /** Renderer metadata: `"checkboxes"` renders every option as a visible
-   *  checkbox with a select-all toggle. Default (omitted) stays the combobox
-   *  dropdown. */
-  readonly display?: "checkboxes" | "dropdown";
-  /** Renderer metadata: column count for the `"checkboxes"` grid at the widest
-   *  breakpoint; narrow viewports always collapse to one column. Omitted =
-   *  the renderer picks a sensible count. Ignored unless
-   *  `display: "checkboxes"`. */
-  readonly columns?: 1 | 2 | 3 | 4;
-  /** Renderer metadata: how many grid rows stay visible before the
-   *  `"checkboxes"` grid becomes scrollable. Omitted = the grid grows with its
-   *  content and never scrolls. Ignored unless `display: "checkboxes"`. */
-  readonly maxRows?: number;
-} & ResolvedPiiFlags;
-
-/**
- * Storage: `integer` flag decides the Postgres column type, not just Zod
- * validation. `integer: true` → `integer` column (32-bit, ~±2.1 billion),
- * write-boundary enforces `.int()`. Omitted/`false` (the default) →
- * `double precision` column — fractional values are accepted end to end.
- * Need exact decimal storage instead of a binary float (money-adjacent
- * math, no representation error)? Use `createDecimalField` (`numeric`).
- */
-export type NumberFieldDef = {
-  readonly type: "number";
-  readonly description?: string;
-  readonly required?: boolean;
-  readonly sortable?: boolean;
-  readonly filterable?: boolean;
-  readonly sensitive?: boolean;
-  readonly default?: number;
-  readonly access?: FieldAccess;
-  readonly min?: number;
-  /** Upper bound at the write boundary (Zod `.max`). */
-  readonly max?: number;
-  /** `true` → `integer` column + `.int()` Zod validation. Omitted/`false` →
-   *  `double precision` column, fractional values allowed. */
-  readonly integer?: boolean;
-  /** Display-only suffix: a static string, or a sibling field name whose
-   *  value supplies it. Never converts the stored number. */
-  readonly unit?: string | { readonly field: string };
-  /** Thousands-grouping in the rendered display (Intl `useGrouping`).
-   *  Default `true`. Set `false` for values that read wrong grouped (e.g. a
-   *  model year: "2021", not "2.021"). Never affects the stored value. */
-  readonly grouping?: boolean;
-} & ResolvedPiiFlags;
-
-/**
- * 64-bit-Integer-Spalte fuer Audit-Counter, Byte-Sizes, Event-IDs und
- * andere Werte die >2^31 (~2.1 Mrd) wandern koennen. Storage als
- * Postgres `bigint`, JS-Round-trip als `number` (mode:"number" — sicher
- * bis 2^53 ≈ 9 PB, JSON-serialisierbar). Wer >2^53 braucht (rare),
- * nutzt einen `text`-Field mit eigenem Codec.
- *
- * Vorrang vor `NumberFieldDef`-(integer 32-bit-Cap, ~2.1 GB) immer dann
- * wenn der Wert physisch ueber dieses Limit klettern kann: Bytes,
- * Events, Counters in High-Throughput-Apps, Cumulative-Sums. Money
- * hat dafuer den eigenen `MoneyFieldDef` (mit Currency-Spalte).
- */
-export type BigIntFieldDef = {
-  readonly type: "bigInt";
-  readonly description?: string;
-  readonly required?: boolean;
-  readonly sortable?: boolean;
-  readonly filterable?: boolean;
-  readonly sensitive?: boolean;
-  readonly default?: number;
-  readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
-
-/**
- * Exact decimal — Postgres `numeric(precision, scale)`. For values that need
- * fractional precision the integer `number` field (32-bit int) and `money`
- * field (BIGINT minor units + currency) can't hold: interest rates,
- * percentages, ratios, measurements.
- *
- * `precision` = total significant digits, `scale` = digits after the decimal
- * point (both required — no silent default that could truncate). pg returns
- * `numeric` as a string to preserve precision; the read-codec surfaces it as
- * a JS `number` (safe ≤ 2^53, same trade-off as `bigInt` mode:"number" — a
- * value past that boundary loses precision, so keep `precision - scale` ≤ 15).
- */
-export type DecimalFieldDef = {
-  readonly type: "decimal";
-  readonly description?: string;
-  readonly precision: number;
-  readonly scale: number;
-  readonly required?: boolean;
-  readonly sortable?: boolean;
-  readonly filterable?: boolean;
-  readonly sensitive?: boolean;
-  readonly default?: number;
-  readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
-
-/** Where a money field's currency comes from. `"tenant"` is the
- *  tenant-settings bundle's per-tenant currency (`tenant-settings:config:
- *  currency`, kumiko-framework#2933); `"literal"` names a fixed ISO code and
- *  is checked against the app's `currencies` list at boot
- *  (kumiko-framework#2839). Discriminated union so a `{ kind: "field", of }`
- *  variant (amount and currency-picker side by side) can still be added
- *  without a breaking change, once a multi-currency form actually exists. */
-export type MoneyCurrencySource =
-  | { readonly kind: "tenant" }
-  | { readonly kind: "literal"; readonly code: string };
-
-/** Qualified config key a `{ kind: "tenant" }` MoneyCurrencySource resolves
- *  against — the tenant-settings bundle's per-tenant currency. Lives here
- *  (client-safe) rather than framework/engine so renderer code can read it
- *  without a runtime-only import (kumiko-framework#2937). */
-export const TENANT_CURRENCY_CONFIG_KEY = "tenant-settings:config:currency";
-
-export type MoneyFieldDef = {
-  readonly type: "money";
-  readonly description?: string;
-  readonly required?: boolean;
-  readonly sortable?: boolean;
-  readonly filterable?: boolean;
-  readonly sensitive?: boolean;
-  readonly access?: FieldAccess;
-  /** Declares where this field's currency comes from for a currently-empty
-   *  value in an entityEdit form. Undefined = unchanged existing behaviour
-   *  (`entity.defaultCurrency ?? "EUR"`); a stored value always keeps its
-   *  own currency regardless of this declaration. */
-  readonly currency?: MoneyCurrencySource;
-};
-
-// Reference-Field (Tier 2.7e-3) — FK-Style Verweis auf eine andere
-// Entity. Gespeichert als UUID-Spalte (uuid type), Read-Side liefert
-// optional die referenced Row mit (Tier 2.7e-4 eagerload).
-//
-// `entity` akzeptiert zwei Formen:
-//   - kurz ("customer") — same-feature reference, Default-Pfad.
-//   - qualifiziert ("users:user") — cross-feature, Format
-//     "<featureName>:<entityName>". Renderer baut die Lookup-Query-QN
-//     gegen das angegebene Feature (`users:query:user:list`).
-//
-// `labelField` (optional) — welches Feld der referenced Entity wird
-// im Select-Dropdown als Label gezeigt. Default: "id". Best practice
-// ist ein menschlich-lesbares Feld wie "name", "title", "email".
-export type ReferenceFieldDef = {
-  readonly type: "reference";
-  readonly description?: string;
-  readonly entity: string;
-  readonly required?: boolean;
-  readonly filterable?: boolean;
-  readonly sensitive?: boolean;
-  readonly access?: FieldAccess;
-  /** Welches Feld der referenced Entity als Display-Label im
-   *  Select-Dropdown erscheint. Default: "id". Boot-Validator pinst
-   *  dass das Feld auf der referenced Entity existiert. */
-  readonly labelField?: string;
-  /** Multi-Reference (Tier 2.7e-Multi): Wert ist ein Array von UUIDs
-   *  statt single UUID. Storage als jsonb-Array<uuid>. UI rendert
-   *  Multi-Select-Combobox mit Tag-Anzeige der gewählten Items. */
-  readonly multiple?: boolean;
-  /** Include a row in this entity's result set on a text-search hit against
-   *  the referenced entity's `labelField`, instead of only matching the UUID
-   *  column itself (fw#2660). Requires an explicit `labelField` — the boot
-   *  validator rejects it otherwise, since the default "id" is a UUID column
-   *  and ILIKE against it would crash at runtime. */
-  readonly searchable?: true;
-  /** Order a list by the referenced entity's `labelField` instead of by the raw
-   *  UUID column (fw#2741). Requires an explicit, non-"id" `labelField` — the
-   *  boot validator rejects it otherwise, since ordering by a UUID produces a
-   *  sequence that looks meaningful to the user but is arbitrary. */
-  readonly sortable?: true;
-  /** Fill the picker from this query handler instead of the referenced
-   *  entity's own list handler (fw#2780) — for targets whose identity is
-   *  composed from joined rows, where no single column of the referenced
-   *  entity is a readable label. Fully-qualified QN
-   *  ("<feature>:query:<short>"), boot-validated against the registered
-   *  handlers; result contract `{ rows: { id, label }[] }`, called with
-   *  `{ limit, search? }` like the default list handler. `id` rather than the
-   *  `{ value, label }` of `DashboardFilterDefinition.optionsQuery`, because
-   *  the stored value here IS the referenced row's id.
-   *
-   *  Additive to `labelField`, which keeps serving the paths a query handler
-   *  cannot back: list cells, `searchable` and `sortable` all resolve to an
-   *  SQL column on the referenced table.
-   *
-   *  The handler must return the row for an id that is already stored, even
-   *  when it otherwise curates its result (say, to active records only) —
-   *  the read-only display resolves a stored value against these rows and
-   *  falls back to the raw id for one it does not find. */
-  readonly optionsQuery?: string;
-} & ResolvedPiiFlags;
-
-// --- Currency ---
-
-// Keep in sync with DEFAULT_CURRENCIES in ../field-helpers.ts.
-export type DefaultCurrency =
-  | "EUR"
-  | "USD"
-  | "GBP"
-  | "CHF"
-  | "JPY"
-  | "SEK"
-  | "NOK"
-  | "DKK"
-  | "PLN"
-  | "CZK"
-  | "CAD"
-  | "AUD"
-  | "NZD"
-  | "CNY"
-  | "INR";
-
-// --- Embedded Object ---
-
-type EmbeddedSubFieldBase = {
-  readonly required?: boolean;
-  readonly searchable?: boolean;
-  readonly access?: FieldAccess;
-};
-
-/** `money` is a signed integer amount in minor units (cents); which currency
- *  it means is defined by the owning aggregate (a head-level field or tenant
- *  config), not per row. Unlike the top-level `money` field (BIGINT + currency
- *  column) the value lives in jsonb, so it must stay within ±(2^53 − 1).
- *
- *  `decimal` bounds a JSON number to `scale` fractional digits (0–15). `scale`
- *  is required — no silent default that could truncate — and there is no
- *  `precision`: jsonb has no numeric column behind it whose width `precision`
- *  could describe. */
-export type EmbeddedSubFieldDef =
-  | (EmbeddedSubFieldBase & {
-      readonly type: "text" | "number" | "boolean" | "date" | "money" | "timestamp";
-    })
-  | (EmbeddedSubFieldBase & {
-      readonly type: "decimal";
-      readonly scale: number;
-    })
-  | (EmbeddedSubFieldBase & {
-      readonly type: "select";
-      readonly options: readonly string[];
-    })
-  | (EmbeddedSubFieldBase & {
-      readonly type: "reference";
-      readonly entity: string;
-      readonly labelField?: string;
-      /** Same contract as `ReferenceFieldDef.optionsQuery` (fw#2780). */
-      readonly optionsQuery?: string;
-    });
-
-/** A cell computed from other cells of the same row. `from` names the
- *  sub-fields the operation reads (order matters for `subtract`). Renderer
- *  metadata — the derived value is rounded server- and client-side to the
- *  precision its target sub-field in `schema` declares (money → integer,
- *  decimal → `scale`) before it's validated. */
-export type EmbeddedDerivedCellDef = {
-  readonly op: "multiply" | "sum" | "subtract";
-  readonly from: readonly string[];
-};
-
-export type EmbeddedFieldDef = {
-  readonly type: "embedded";
-  readonly description?: string;
-  readonly required?: boolean;
-  readonly sensitive?: boolean;
-  readonly schema: Readonly<Record<string, EmbeddedSubFieldDef>>;
-  readonly access?: FieldAccess;
-  /** A list of like-shaped objects instead of exactly one: the value is an
-   *  array and every element is validated against `schema`. Storage stays
-   *  jsonb, the column default becomes `[]` instead of `{}`. Built via
-   *  `createEmbeddedListField()`.
-   *
-   *  Only for rows that come into being with their head and stay immutable
-   *  with it (posting lines, invoice positions). A row with its own lifetime
-   *  (own from/to dates, own history) belongs in its own entity referencing
-   *  the head — an embedded array is rewritten whole on every change and has
-   *  no per-row history. */
-  readonly multiple?: boolean;
-  /** Minimum row count for an embedded list. Only valid with `multiple: true`. */
-  readonly minItems?: number;
-  /** Maximum row count for an embedded list. Only valid with `multiple: true`. */
-  readonly maxItems?: number;
-  /** Renderer metadata: sub-field name → how to compute its cell from other
-   *  sub-fields of the same row, rounded to that sub-field's declared
-   *  precision. Only valid with `multiple: true`. */
-  readonly derived?: Readonly<Record<string, EmbeddedDerivedCellDef>>;
-  /** Renderer metadata: numeric sub-field names to sum in a totals row. Only
-   *  valid with `multiple: true`. */
-  readonly totals?: readonly string[];
-  /** Maps an embedded-list subfield name to a sibling top-level money field
-   *  name — the sum of that subfield across all rows must equal the sibling
-   *  field's amount. Validated both client- and server-side (schema-builder
-   *  superRefine). Only meaningful with `multiple: true`. Compares against
-   *  rounded `derived` cells, i.e. "sum-of-rounded" not "round-of-sum" —
-   *  see kumiko-framework#1866. */
-  readonly totalsMatch?: Readonly<Record<string, string>>;
-} & ResolvedPiiFlags;
-
-// Free-form jsonb — keys/shape NOT validated at write-time. Use for:
-//   - Tenant-defined extension data (custom-fields-bundle uses this for
-//     `customFields` on host-entities — keys are dynamic per fieldDefinition)
-//   - Configuration-blobs with shape that evolves outside Stammfeld-schema
-//   - AI-inferred metadata where shape is provider-dependent
-//
-// Vs. embedded: embedded enforces a typed sub-schema; jsonb accepts any
-// JSON-shaped object. Read-side both map to Postgres `jsonb`. Default `{}`
-// + NOT NULL, identisch zu embedded.
-export type JsonbFieldDef = {
-  readonly type: "jsonb";
-  readonly description?: string;
-  readonly sensitive?: boolean;
-  /** A later run reads this field's value as an instruction — prompt, rule,
-   *  template. Every create/update whose payload writes it requires agent.risk
-   *  "high" on the directly-dispatched entry handler; a revert doesn't undo a
-   *  run that already read the compromised value. See irreversible-operation-gate. */
-  readonly readAsInstruction?: boolean;
-  readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
-
-// Legacy "date" — JS-Date-Object, semantisch unklar (Wall-Clock vs Instant).
-// Für neue Felder bevorzuge:
-//   - `timestamp` für UTC-Instant ("wann ist das passiert")
-//   - `createLocatedTimestampField()` für Termine die an einem Ort
-//     stattfinden ("Pickup um 10:00 in Lissabon")
-//   - (kommt) `plainDate` für Kalender-Daten ohne Uhrzeit (z.B. Geburtstag)
-// Siehe docs/plans/architecture/timezones.md
-export type DateFieldDef = {
-  readonly type: "date";
-  readonly description?: string;
-  readonly required?: boolean;
-  readonly sortable?: boolean;
-  readonly filterable?: boolean;
-  readonly sensitive?: boolean;
-  readonly access?: FieldAccess;
-  /** Erlaubte Datumsgrenzen als ISO `yyyy-mm-dd` (z.B. Geburtsdatum nicht
-   *  in der Zukunft: `max` = heute). Begrenzt den Picker und wird vom
-   *  Zod-Schema beim Write durchgesetzt. */
-  readonly min?: string;
-  readonly max?: string;
-  /** Format/Locale-Override für Anzeige und Eingabe-Parsing (z.B.
-   *  "de-DE"). Default = App-Locale. */
-  readonly locale?: string;
-} & ResolvedPiiFlags;
-
-// UTC-Instant (Temporal.Instant). Für Ereignisse die zu einem bestimmten
-// Augenblick passieren, ohne Location-Bezug: createdAt, loginAt, actualPickupAt.
-// JSON-Form: ISO-UTC-String "2026-04-18T10:00:00Z" via .toJSON().
-//
-// Mit `locatedBy: "<name>Tz"` markiert: bildet ein Wall-Clock+TZ-Pair mit dem
-// referenzierten tz-Feld. JSON-Form wird dann zwei Felder ({ at, tz }), DB
-// speichert Wall-Clock+tz und konvertiert transparent (siehe DB-Wrapper,
-// kommt in einer späteren Iteration).
-//
-// Für neue Felder bevorzuge `createLocatedTimestampField()` — EIN atomares
-// Feld statt eines lose verdrahteten Pairs (siehe LocatedTimestampFieldDef).
-export type TimestampFieldDef = {
-  readonly type: "timestamp";
-  readonly description?: string;
-  readonly required?: boolean;
-  readonly sortable?: boolean;
-  readonly filterable?: boolean;
-  readonly sensitive?: boolean;
-  readonly access?: FieldAccess;
-  /**
-   * Marker: dieses Timestamp-Feld ist Wall-Clock-Zeit an einem Ort.
-   * Wert ist der Name des begleitenden tz-Felds (IANA-Zone).
-   *
-   * Beispiel: manuelles Pair
-   *   { pickupAt: { type: "timestamp", locatedBy: "pickupTz" }, pickupTz: { type: "tz" } }
-   * — bevorzuge stattdessen `createLocatedTimestampField()`.
-   */
-  readonly locatedBy?: string;
-  /** Erlaubte Grenzen als ISO-Datetime. Begrenzt den Picker auf
-   *  Tages-Granularität; die exakte Uhrzeit-Grenze setzt das Zod-Schema
-   *  beim Write durch. */
-  readonly min?: string;
-  readonly max?: string;
-  /** Format/Locale-Override für Anzeige und Eingabe-Parsing. Default =
-   *  App-Locale. */
-  readonly locale?: string;
-} & ResolvedPiiFlags;
-
-// IANA-Zonenname (z.B. "Europe/Berlin", "America/Los_Angeles").
-// Wird via `Intl.supportedValuesOf("timeZone")` validiert (kommt im
-// Zod-Validator-Schritt). Eigener Field-Typ damit Type-Safety + Storage
-// (TEXT-Spalte) korrekt sind und der `locatedBy`-Marker eindeutig auflöst.
-export type TzFieldDef = {
-  readonly type: "tz";
-  readonly description?: string;
-  readonly required?: boolean;
-  readonly sensitive?: boolean;
-  readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
-
-// Wall-Clock-Termin an einem Ort als ATOMARES Konzept.
-// EIN Feld in der Schema-Definition, ZWEI Spalten in der DB
-// (`<name>_utc TIMESTAMPTZ` + `<name>_tz TEXT`), DREI Felder im API-Object
-// ({ at, tz, utc }). Drizzle-Wrapper macht die Konvertierung transparent —
-// Feature-Code sieht das 3-Felder-Object beim Read und schreibt
-// { at, tz } beim Insert (utc wird berechnet).
-//
-// API-Form:
-//   Write: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" }
-//   Read:  { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon", utc: "2026-04-15T09:00:00Z" }
-//
-// Default-Sicht für `at`: Wall-Clock am Ort (`tz`). Wer User-lokale Sicht
-// will, projeziert `utc` separat per ctx.tz.fromInstantInZone(utc, userTz).
-//
-// Ersetzt das alte `locatedTimestamp(name)` Helper-Pattern (zwei separate
-// Pair-Felder). Sauberer Single-Field-Typ + Auto-Convert-Logik.
-//
-// Siehe docs/plans/architecture/timezones.md.
-export type LocatedTimestampFieldDef = {
-  readonly type: "locatedTimestamp";
-  readonly description?: string;
-  readonly required?: boolean;
-  readonly sortable?: boolean;
-  readonly filterable?: boolean;
-  readonly sensitive?: boolean;
-  readonly access?: FieldAccess;
-  /** Erlaubte Grenzen als ISO-Datetime (Wall-Clock). Begrenzt den Picker
-   *  auf Tages-Granularität; die exakte Uhrzeit-Grenze setzt das Zod-Schema
-   *  beim Write durch. */
-  readonly min?: string;
-  readonly max?: string;
-  /** Format/Locale-Override für Anzeige und Eingabe-Parsing. Default =
-   *  App-Locale. */
-  readonly locale?: string;
-} & ResolvedPiiFlags;
-
-export type FileFieldDef = {
-  readonly type: "file";
-  readonly description?: string;
-  readonly required?: boolean;
-  readonly maxSize?: string;
-  readonly accept?: readonly string[];
-  readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
-
-export type ImageFieldDef = {
-  readonly type: "image";
-  readonly description?: string;
-  readonly required?: boolean;
-  readonly maxSize?: string;
-  readonly accept?: readonly string[];
-  /** Named derived versions of the uploaded image. The name is the only
-   *  thing a caller may ask for — the spec lives here, never in a request,
-   *  so nobody can drive arbitrary renders. Boot-validated. */
-  readonly variants?: Readonly<Record<string, VariantSpec>>;
-  /** Forwarded to the file input's `capture` attribute so a phone opens the
-   *  camera instead of the file picker. */
-  readonly capture?: "environment" | "user";
-  readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
-
-export type FilesFieldDef = {
-  readonly type: "files";
-  readonly description?: string;
-  readonly maxSize?: string;
-  readonly accept?: readonly string[];
-  readonly maxCount?: number;
-  readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
-
-export type ImagesFieldDef = {
-  readonly type: "images";
-  readonly description?: string;
-  readonly maxSize?: string;
-  readonly accept?: readonly string[];
-  readonly maxCount?: number;
-  readonly variants?: Readonly<Record<string, VariantSpec>>;
-  readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
-
-export type FieldDefinition =
-  | TextFieldDef
-  | LongTextFieldDef
-  | BooleanFieldDef
-  | SelectFieldDef
-  | MultiSelectFieldDef
-  | NumberFieldDef
-  | BigIntFieldDef
-  | DecimalFieldDef
-  | MoneyFieldDef
-  | ReferenceFieldDef
-  | EmbeddedFieldDef
-  | JsonbFieldDef
-  | DateFieldDef
-  | TimestampFieldDef
-  | TzFieldDef
-  | LocatedTimestampFieldDef
-  | FileFieldDef
-  | ImageFieldDef
-  | FilesFieldDef
-  | ImagesFieldDef;
-
-// Exhaustive catalogue of `FieldDefinition["type"]` values, derived from a
-// `Record` so an added/removed union member fails to compile here instead of
-// silently drifting out of sync with the runtime validator that consults
-// this list (feature-ast's pattern-change-schema). Plain array, not a Set —
-// same rationale as NO_WIDGET_FIELD_TYPES (guard-types-class-free.test.ts).
-const FIELD_TYPE_NAME_FLAGS: Record<FieldDefinition["type"], true> = {
-  text: true,
-  longText: true,
-  boolean: true,
-  select: true,
-  multiSelect: true,
-  number: true,
-  bigInt: true,
-  decimal: true,
-  money: true,
-  reference: true,
-  embedded: true,
-  jsonb: true,
-  date: true,
-  timestamp: true,
-  tz: true,
-  locatedTimestamp: true,
-  file: true,
-  image: true,
-  files: true,
-  images: true,
-};
-
-export const FIELD_TYPE_NAMES: readonly FieldDefinition["type"][] = Object.keys(
-  FIELD_TYPE_NAME_FLAGS,
-) as FieldDefinition["type"][];
-
-/** FieldDefinition as an entity-less inline form screen (actionForm,
- *  secretMint) may declare it: a `money` field there has no entity to borrow
- *  `defaultCurrency` from, so it must name its own currency source, or the
- *  form seeds a bare `0` that the handler's zod schema then rejects
- *  (kumiko-framework#2839). Entity fields keep the optional `currency` —
- *  `entity.defaultCurrency` is already boot-enforced for them. */
-export type FormFieldDefinition =
-  | Exclude<FieldDefinition, MoneyFieldDef>
-  | (MoneyFieldDef & { readonly currency: MoneyCurrencySource });
-
-// Union of all field variants that represent uploaded files. They share
-// `maxSize` and `accept`, which is what upload validation cares about.
-export type AnyFileFieldDef = FileFieldDef | ImageFieldDef | FilesFieldDef | ImagesFieldDef;
-
-// Field types with no bound, editable widget on the auto-wired entityEdit
-// path (render-field.tsx renders a read-only banner instead) — shared by
-// the boot validator (packages/framework/src/engine/boot-validator/screens.ts)
-// and the client-side required-field check (packages/renderer/src/app/form-schema.ts).
-// Embedded LIST fields (`multiple: true`) are the one exception — they get
-// their own EmbeddedListField grid widget (#1838) — callers must check that
-// separately, this array alone doesn't distinguish plain embedded from embedded lists.
-// A plain array, not a Set: kumiko-types stays free of module-scope runtime
-// identity (guard-types-class-free.test.ts) since a consumer may resolve two
-// copies of this package.
-export const NO_WIDGET_FIELD_TYPES: readonly FieldDefinition["type"][] = [
-  "jsonb",
-  "embedded",
-  "files",
-  "images",
-];
-
-// --- Derived (computed) fields ---
-//
-// A derived field is read-time only: its value is computed from the stored row
-// (and the clock) when an entityList query runs (676/2 — NOT detail; only the
-// "list" case in entity-handlers.ts calls augmentDerivedFields), never
-// persisted. It lives in
-// `EntityDefinition.derivedFields` — deliberately NOT in `fields`, so it
-// produces no DB column, never enters a write schema, and can't be the target
-// of an entityEdit. A declarative `entityList` can name it like any column and
-// the view-model renders the appended value.
-//
-// LIMIT: derived columns are DISPLAY ONLY. A declarative `entityList` loads its
-// rows server-side and a column-header sort round-trips to the server, where
-// `executor.list` sorts/filters/searches over real SQL columns — so a derived
-// field (no column) silently no-ops. There is no client-side sort path. Need a
-// derived value sortable/searchable? Materialize it as a stored field; it then
-// rides the existing `searchable`/`sortable` machinery. Time-dependent values
-// (as-of-today) can't be materialized without a daily re-index anyway.
-
-/** Display type a derived value formats as — drives the column's renderer
- *  choice in the view-model, parallel to FieldDefinition["type"]. Single-column
- *  types only: `money` is excluded because it needs a `<name>Currency`
- *  companion column a derived field has no place to put — use `number`/
- *  `decimal` plus a `{ format: "currency" }` column renderer instead. */
-export type DerivedValueType = "text" | "number" | "decimal" | "boolean" | "date" | "timestamp";
-
-/** Clock injected into `derive` — never read `Temporal.Now`/`Date` inside a
- *  derive body (no-date-api guard + testability). The list-query handler passes
- *  the read-time instant; unit tests pass a fixed one. */
-export type DeriveContext = {
-  readonly asOf: Temporal.Instant;
-};
-
-export type DerivedFieldDef = {
-  readonly valueType: DerivedValueType;
-  /** Pure function of the stored row + clock. Returns the JSON-safe display
-   *  value (e.g. integer minor units for a currency column, ISO string for a
-   *  `date`). */
-  readonly derive: (row: Readonly<Record<string, unknown>>, ctx: DeriveContext) => unknown;
-};
-
-export type DerivedFieldsMap = Readonly<Record<string, DerivedFieldDef>>;
-
-/** Client-facing projection of DerivedFieldDef — `derive` is server-only and
- *  not JSON-safe (would trip the output-walk guard), so the browser schema
- *  only ever carries `valueType`. A real `Pick`, not a same-shape cast: TS
- *  itself proves `derive` isn't there instead of a `{ valueType } as
- *  DerivedFieldDef` cast lying about a field that's actually missing. */
-export type ClientDerivedFieldDef = Pick<DerivedFieldDef, "valueType">;
-
-// --- Entity ---
-
-// --- State Transitions ---
-
-export type TransitionMap = Readonly<Record<string, readonly string[]>>;
-
-/** Composite-Index auf einer Entity. Spalten werden via field-Name
- *  referenziert (camelCase). buildEntityTable mapped sie auf snake_case-
- *  Spaltennamen und benennt den Index nach Convention:
- *
- *    <table>_<col1>_<col2>_idx          (non-unique)
- *    <table>_<col1>_<col2>_unique       (unique)
- *
- *  Eine `name`-Override ist erlaubt — Convention-Bruch in Bestandscode
- *  vermeidet Migration-Churn beim Refactor.
- *
- *  Single-column indices über `tenantId` sind redundant (buildEntityTable
- *  legt die immer automatisch an); die Boot-Validation warnt (außer
- *  `{ unique: true }` — semantische 1:1-Constraint, kein Performance-Hint). */
-export type EntityIndexDef = {
-  readonly columns: readonly [string, ...string[]];
-  readonly unique?: boolean;
-  readonly name?: string;
-  /**
-   * Optional SQL-Fragment fuer Partial-Index — `CREATE [UNIQUE] INDEX
-   * ... WHERE <condition>`. Postgres-Pattern fuer "Index nur unter
-   * bestimmten Bedingungen", typisches Beispiel: ExportJob-Idempotency
-   * `UNIQUE(userId) WHERE status IN ('pending', 'running')`.
-   *
-   * Caller baut das Fragment via drizzle-orm `sql\`...\``-Tagged-
-   * Template. table-builder.ts emittiert `.where(def.where)` auf den
-   * Drizzle-IndexBuilder — wirkt sowohl fuer unique- als auch fuer
-   * non-unique-Indexes (PG erlaubt beides; non-unique partial nutzt
-   * man z.B. fuer scharfe BTREE-Indexes nur auf einer Status-Teilmenge
-   * statt voller Tabelle).
-   */
-  readonly where?: unknown;
-};
-
-export type FieldsMap = Readonly<Record<string, FieldDefinition>>;
-
-export type ParentRefDef = {
-  /** Field holding the name of the host entity this row hangs off. */
-  readonly entityTypeField: string;
-  /** Field holding the host row's id. */
-  readonly entityIdField: string;
-  /** Narrow which registered entities may act as host. Omitted means every
-   *  registered entity is a candidate, which also widens the read-gate's SQL. */
-  readonly allowedTypes?: readonly string[];
-};
-
-export type EntityDefinition<
-  F extends FieldsMap = FieldsMap,
-  T extends EntityTenancy = EntityTenancy,
-> = {
-  readonly table?: string;
-  readonly fields: F;
-  readonly softDelete?: boolean;
-  /** "tenant" (default): auto-filtered by every db accessor. "global": shared across
-   *  tenants, reachable only via `db.global(table)`. Not named `scope` — config keys use that. */
-  readonly tenancy?: T;
-  /** This aggregate's event stream lives on SYSTEM_TENANT_ID rather than the
-   *  creator's tenant. Opt-in per entity (NOT inherited from r.systemScope()):
-   *  only for genuinely tenant-independent aggregates like `user`. The first
-   *  event (create) is what's routed; updates resolve the stream tenant upstream. */
-  readonly systemStream?: boolean;
-  readonly searchWeight?: number;
-  readonly defaultCurrency?: string;
-  /** Allowed state transitions per field. Boot validates against select options. */
-  readonly transitions?: Readonly<Record<string, TransitionMap>>;
-  /** Composite-Indices über mehrere Felder. Single-column FK-Indices und
-   *  der tenant_id-Index werden weiterhin automatisch von buildEntityTable
-   *  angelegt — diese Liste ist nur für Custom-Indices die der Author
-   *  explizit deklariert (z.B. `{ unique: true, columns: ["key", "tenantId", "userId"] }`). */
-  readonly indexes?: readonly EntityIndexDef[];
-  /**
-   * PK-Typ der Entity.
-   * - `"serial"` (default): bigserial integer — schneller, kompakter, perfekt für klassische CRUD-Entities.
-   * - `"uuid"`: uuid mit `gen_random_uuid()` default — verpflichtend für Entities deren `id` als
-   *   Foreign-Key-Wert in multi-tenant Kontexten reist (z.B. `tenant.id` IS der `tenantId`). Auch für
-   *   ES-Aggregate (Phase 2+) notwendig, da Events per UUID aggregiert werden.
-   */
-  readonly idType?: "serial" | "uuid";
-  /**
-   * Row-level ownership rules (H.2). read runs as WHERE-predicate on list/
-   * detail/queryProjection, scoping which rows the caller sees. write runs
-   * pre-save on create/update/delete, scoping which rows the caller may
-   * modify (Straddle-safe, multi-role atomic — see engine/ownership.ts).
-   *
-   * Keys are role names; rules use the `from()` helper or `{ where }`
-   * escape hatch. Entity-level ownership is AND-ed with tenant isolation —
-   * a user's tenant filter still applies first.
-   */
-  readonly access?: {
-    readonly read?: OwnershipMap;
-    readonly write?: OwnershipMap;
-  };
-  /**
-   * Join-row carrier reference. Rows of this entity hang off a host row named
-   * by two of the entity's own fields. Both paths derive one visibility gate
-   * from this single declaration: write handlers deny with NotFoundError, and
-   * list/detail filter in SQL against the host entity's own read path (tenant
-   * scope, soft-delete, `access.read` ownership). A host type that names no
-   * registered entity is denied.
-   */
-  readonly parentRef?: ParentRefDef;
-  /**
-   * Default-Retention-Policy fuer diese Entity. Tenant-Admin kann via
-   * Compliance-Profile + Tenant-Override (Sprint 2) uebersteuern.
-   * Cleanup-Job (Sprint 2) verarbeitet die Strategy:
-   *
-   *   - "hardDelete" → Row physisch weg nach keepFor
-   *   - "softDelete" → deletedAt = now() (mit core-soft-delete-Feature)
-   *   - "anonymize"  → Felder mit `anonymize`-Funktion ueberschrieben,
-   *                    Row bleibt
-   *   - "blockDelete" → Cleanup-Job ignoriert; User-Forget loest
-   *                     stattdessen anonymize aus. Buchhaltung, Mandate,
-   *                     Patientenakten.
-   *
-   * Siehe docs/plans/features/core-data-retention.md.
-   */
-  readonly retention?: RetentionDef;
-  /**
-   * Read-time computed fields, keyed by name. Not stored, not a DB column,
-   * not writable — appended to each row by the list/detail query handler and
-   * nameable as a column in a declarative `entityList`. See DerivedFieldDef.
-   */
-  readonly derivedFields?: DerivedFieldsMap;
-  /** Optional free-text semantics for the AI agent manifest — see TextFieldDef.description. */
-  readonly description?: string;
-  /**
-   * Opts this entity's rows into the `tenant-handover` bundled feature
-   * (kumiko-framework#3035): a row-bound-grant-legitimated ownership change
-   * from an anonymous/public tenant to a freshly signed-up account's tenant.
-   * An entity reachable from a transfer's root — the root itself, or any
-   * entity whose `parentRef` names the root's type — that is NOT declared
-   * `transferable: true` makes the whole transfer fail with a named error
-   * instead of silently leaving that entity's rows behind.
-   */
-  readonly transferable?: boolean;
-};