@cosmicdrift/kumiko-types 0.326.1 → 0.328.0

package/dist/fields.d.ts

@@ -0,0 +1,729 @@
+import type { VariantSpec } from "./derivatives-types.js";
+import type { OwnershipMap } from "./ownership.js";
+import type { EntityTenancy } from "./tenancy-brand.js";
+export type FieldAccess = {
+    readonly read?: OwnershipMap | readonly string[];
+    readonly write?: OwnershipMap | readonly string[];
+};
+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;
+};
+export type PersonalSubject = "self" | {
+    readonly of: string;
+} | "tenant";
+export type Findability = "exact" | "fuzzy" | "none" | "secret";
+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>;
+};
+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>;
+};
+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;
+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 SelectOptionTone = "ok" | "warn" | "bad" | "neutral";
+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";
+    /** Status tone per option, shown as a toned badge with dot in lists and
+     *  detail bands. Options without an entry keep the renderer's own
+     *  value-based heuristic. */
+    readonly optionTones?: {
+        readonly [K in TOptions[number]]?: SelectOptionTone;
+    };
+} & ResolvedPiiFlags;
+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 declare 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;
+};
+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;
+export type DefaultCurrency = "EUR" | "USD" | "GBP" | "CHF" | "JPY" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "CAD" | "AUD" | "NZD" | "CNY" | "INR";
+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;
+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;
+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;
+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;
+export type TzFieldDef = {
+    readonly type: "tz";
+    readonly description?: string;
+    readonly required?: boolean;
+    readonly sensitive?: boolean;
+    readonly access?: FieldAccess;
+} & ResolvedPiiFlags;
+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;
+export declare const FIELD_TYPE_NAMES: readonly 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;
+});
+export type AnyFileFieldDef = FileFieldDef | ImageFieldDef | FilesFieldDef | ImagesFieldDef;
+export declare const NO_WIDGET_FIELD_TYPES: readonly FieldDefinition["type"][];
+/** 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">;
+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;
+};
+export {};