@cosmicdrift/kumiko-types 0.386.0 → 0.388.0

package/dist/fields.d.ts

@@ -17,11 +17,10 @@ export type ResolvedPiiFlags = {
     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). */
+    /** Equality lookups (`fetchOne`/`filter eq`) remain possible despite encryption:
+     *  the generated `<snake>_bidx` column carries an HMAC blind index, and the
+     *  query compiler matches `(col = $1 OR col_bidx = $2)`. Allowed only on text
+     *  fields with subject annotations, as enforced by the boot validator. */
     readonly lookupable?: true;
     /** Foreign key into the `user` entity (authorId, assigneeId, ...) with no
      *  annotated content of its own. Triggers no encryption — feeds only the
@@ -94,9 +93,9 @@ export type TextFieldDef = {
     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. */
+    /** Allows screen filters on this field.
+     *  The boot validator rejects filters with `filterable !== true`.
+     *  Default: false, analogous to `sortable`, and therefore opt-in. */
     readonly filterable?: boolean;
     readonly encrypted?: boolean;
     readonly sensitive?: boolean;
@@ -125,40 +124,38 @@ export type TextFieldDef = {
     readonly format?: "email" | "url" | "phone" | "password" | "month" | "iban";
     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. */
+    /** Multiline text causes DefaultInput to render a <textarea> instead of
+     *  <input type="text">. `true` uses four rows by default; `{ rows: N }`
+     *  sets an explicit height. Search, sort, and encryption remain unchanged;
+     *  only the rendering surface differs. */
     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`:
+ * Long-form text content — source code, markdown, blog posts, email
+ * templates, and anything that can be megabytes large. Its surface is
+ * intentionally minimal compared with `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.
+ *   - **No `sortable`**: ordering 100 KB strings costs I/O without useful UX;
+ *     lexicographic ordering of code is not meaningful.
+ *   - **No `searchable`**: ILIKE/substring searches do not scale on long text.
+ *     Full-text search should use the SearchAdapter (Meilisearch), which has
+ *     its own tokenizer and index rather than this field flag.
+ *   - **No `filterable`**: filtering long strings has the same issue as sorting.
+ *   - **No `format`**: email/url/phone are short, structured inputs, whereas
+ *     longText is unstructured by definition.
  *
- * 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).
+ * Type-level enforcement means callers who need sorting or searching must use
+ * `text` and accept its scaling trade-offs. Database mapping is identical to
+ * `text` (Postgres `text` is 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. */
+    /** Optional soft cap. Default is unbounded (= Postgres text limit, 1 GB).
+     *  Useful for defensive limits such as 1 MB so an accidental browser paste
+     *  does not overwhelm the database. */
     readonly maxLength?: number;
     readonly required?: boolean;
     readonly encrypted?: boolean;
@@ -265,7 +262,7 @@ export type MultiSelectFieldDef<TOptions extends readonly string[] = readonly st
     readonly required?: boolean;
     readonly filterable?: boolean;
     readonly sensitive?: boolean;
-    /** Default-Auswahl. Jeder Eintrag muss in `options` sein (Boot-Validator). */
+    /** Default selection. Every entry must occur in `options` (boot validator). */
     readonly default?: readonly TOptions[number][];
     readonly access?: FieldAccess;
     /** Renderer metadata: `"checkboxes"` renders every option as a visible
@@ -321,16 +318,15 @@ export type NumberFieldDef = {
     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.
+ * 64-bit integer field for audit counters, byte sizes, event IDs, and other
+ * values that can exceed 2^31 (~2.1 billion). Stored as Postgres `bigint`,
+ * with a JavaScript `number` round trip (`mode:"number"`, safe through 2^53
+ * ≈ 9 PB and JSON-serializable). Values above 2^53 should use a `text` field
+ * with a custom 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).
+ * Prefer this over `NumberFieldDef`'s 32-bit integer cap whenever a value can
+ * physically exceed that limit: bytes, events, high-throughput counters, and
+ * cumulative sums. Money has its own `MoneyFieldDef` with a currency column.
  */
 export type BigIntFieldDef = {
     readonly type: "bigInt";
@@ -368,9 +364,9 @@ export type DecimalFieldDef = {
 } & 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 }`
+ *  currency`); `"literal"` names a fixed ISO code and
+ *  is checked against the app's `currencies` list at boot.
+ *  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 = {
@@ -382,7 +378,7 @@ export type MoneyCurrencySource = {
 /** 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). */
+ *  without a runtime-only import. */
 export declare const TENANT_CURRENCY_CONFIG_KEY = "tenant-settings:config:currency";
 export type MoneyFieldDef = {
     readonly type: "money";
@@ -406,27 +402,27 @@ export type ReferenceFieldDef = {
     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. */
+    /** Field of the referenced entity displayed as the Select dropdown label.
+     *  Default: "id". The boot validator ensures that the field exists on the
+     *  referenced entity. */
     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. */
+    /** Multi-reference: the value is an array of UUIDs rather than a single UUID.
+     *  Stored as a jsonb array of UUIDs; the UI renders a multi-select combobox
+     *  with tags for the selected 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
+     *  column itself. 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
+     *  UUID column. 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
+     *  entity's own list handler — 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
@@ -481,7 +477,7 @@ export type EmbeddedSubFieldDef = (EmbeddedSubFieldBase & {
     readonly type: "reference";
     readonly entity: string;
     readonly labelField?: string;
-    /** Same contract as `ReferenceFieldDef.optionsQuery` (fw#2780). */
+    /** Same contract as `ReferenceFieldDef.optionsQuery`. */
     readonly optionsQuery?: string;
 });
 /** A cell computed from other cells of the same row. `from` names the
@@ -535,7 +531,7 @@ export type EmbeddedFieldDef = {
      *  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. */
+     *  see the embedded-list totals-matching behavior. */
     readonly totalsMatch?: Readonly<Record<string, string>>;
 } & ResolvedPiiFlags;
 export type JsonbFieldDef = {
@@ -557,13 +553,13 @@ export type DateFieldDef = {
     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. */
+    /** Permitted date bounds as ISO `yyyy-mm-dd` (for example, a birth date
+     *  cannot be in the future when `max` is today). The bounds constrain the
+     *  picker and are enforced by the Zod schema on write. */
     readonly min?: string;
     readonly max?: string;
-    /** Format/Locale-Override für Anzeige und Eingabe-Parsing (z.B.
-     *  "de-DE"). Default = App-Locale. */
+    /** Format/locale override for display and input parsing (for example,
+     *  "de-DE"). Default: app locale. */
     readonly locale?: string;
 } & ResolvedPiiFlags;
 export type TimestampFieldDef = {
@@ -575,21 +571,20 @@ export type TimestampFieldDef = {
     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).
+     * Marker: this timestamp field represents wall-clock time at a location.
+     * The value is the name of the accompanying tz field (IANA zone).
      *
-     * Beispiel: manuelles Pair
+     * Example: manual pair
      *   { pickupAt: { type: "timestamp", locatedBy: "pickupTz" }, pickupTz: { type: "tz" } }
-     * — bevorzuge stattdessen `createLocatedTimestampField()`.
+     * — prefer `createLocatedTimestampField()` instead.
      */
     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. */
+    /** Permitted bounds as ISO datetime values. The picker is limited to day
+     *  granularity; the Zod schema enforces the exact time bound on write. */
     readonly min?: string;
     readonly max?: string;
-    /** Format/Locale-Override für Anzeige und Eingabe-Parsing. Default =
-     *  App-Locale. */
+    /** Format/locale override for display and input parsing. Default: app
+     *  locale. */
     readonly locale?: string;
 } & ResolvedPiiFlags;
 export type TzFieldDef = {
@@ -607,13 +602,13 @@ export type LocatedTimestampFieldDef = {
     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. */
+    /** Permitted bounds as ISO datetime values (wall-clock time). The picker is
+     *  limited to day granularity; the Zod schema enforces the exact time bound
+     *  on write. */
     readonly min?: string;
     readonly max?: string;
-    /** Format/Locale-Override für Anzeige und Eingabe-Parsing. Default =
-     *  App-Locale. */
+    /** Format/locale override for display and input parsing. Default: app
+     *  locale. */
     readonly locale?: string;
 } & ResolvedPiiFlags;
 export type FileFieldDef = {
@@ -673,7 +668,7 @@ export declare const FIELD_TYPE_NAMES: readonly FieldDefinition["type"][];
  *  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 fields keep the optional `currency` —
  *  `entity.defaultCurrency` is already boot-enforced for them. */
 export type FormFieldDefinition = Exclude<FieldDefinition, MoneyFieldDef> | (MoneyFieldDef & {
     readonly currency: MoneyCurrencySource;
@@ -707,35 +702,35 @@ export type DerivedFieldsMap = Readonly<Record<string, DerivedFieldDef>>;
  *  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:
+/** Composite index on an entity. Columns are referenced by field name
+ *  (camelCase). `buildEntityTable` maps them to snake_case column names and
+ *  names the index by 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.
+ *  A `name` override is allowed to avoid migration churn when refactoring
+ *  existing code.
  *
- *  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). */
+ *  Single-column indexes over `tenantId` are redundant because
+ *  `buildEntityTable` creates them automatically; boot validation warns about
+ *  them unless `{ unique: true }`, which expresses a semantic 1:1 constraint
+ *  rather than a 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')`.
+     * Optional SQL fragment for a partial index — `CREATE [UNIQUE] INDEX
+     * ... WHERE <condition>`. This is PostgreSQL's pattern for indexing only
+     * rows that meet specified conditions; a typical example is export-job
+     * 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).
+     * Callers build the fragment with the drizzle-orm `sql\`...\`` tagged
+     * template. table-builder.ts emits `.where(def.where)` on the Drizzle
+     * IndexBuilder. It applies to both unique and non-unique indexes; a
+     * non-unique partial index can target a status subset instead of the full
+     * table.
      */
     readonly where?: unknown;
 };
@@ -800,17 +795,20 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTe
     readonly lockedWhen?: FieldCondition;
     /** 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"] }`). */
+    /** Composite indexes over multiple fields. Single-column foreign-key indexes
+     *  and the tenant_id index are still created automatically by
+     *  `buildEntityTable`; this list is only for custom indexes explicitly
+     *  declared by the author (for example,
+     *  `{ 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.
+     * Entity primary-key type.
+     * - `"serial"` (default): bigserial integer — faster and more compact, suitable
+     *   for classic CRUD entities.
+     * - `"uuid"`: UUID with a `gen_random_uuid()` default — required for entities
+     *   whose `id` travels as a foreign-key value in multi-tenant contexts (for
+     *   example, `tenant.id` is the `tenantId`). Also required for event-sourced
+     *   aggregates because events are grouped by UUID.
      */
     readonly idType?: "serial" | "uuid";
     /**
@@ -837,19 +835,19 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTe
      */
     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:
+     * Default retention policy for this entity. Tenant administrators can
+     *   override it through compliance profiles and tenant overrides.
+     *   The cleanup job applies these strategies:
      *
-     *   - "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.
+     *   - "hardDelete" → physically remove the row after `keepFor`
+     *   - "softDelete" → set `deletedAt = now()` (with the core-soft-delete feature)
+     *   - "anonymize"  → overwrite fields with an `anonymize` function while the
+     *                    row remains
+     *   - "blockDelete" → the cleanup job skips the row; user forget instead
+     *                    triggers anonymization. Accounting records, mandates,
+     *                    and patient records.
      *
-     * Siehe docs/plans/features/core-data-retention.md.
+     * See docs/plans/features/core-data-retention.md.
      */
     readonly retention?: RetentionDef;
     /**
@@ -862,7 +860,7 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTe
     readonly description?: string;
     /**
      * Opts this entity's rows into the `tenant-handover` bundled feature
-     * (kumiko-framework#3035): a row-bound-grant-legitimated ownership change
+     *: 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

package/dist/fields.js

@@ -12,7 +12,7 @@ export function optionsQueryFieldRefs(payload) {
 /** 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). */
+ *  without a runtime-only import. */
 export const TENANT_CURRENCY_CONFIG_KEY = "tenant-settings:config:currency";
 // Exhaustive catalogue of `FieldDefinition["type"]` values, derived from a
 // `Record` so an added/removed union member fails to compile here instead of
@@ -41,13 +41,16 @@ const FIELD_TYPE_NAME_FLAGS = {
     files: true,
     images: true,
 };
-export const FIELD_TYPE_NAMES = Object.keys(FIELD_TYPE_NAME_FLAGS);
+function isFieldTypeName(name) {
+    return Object.hasOwn(FIELD_TYPE_NAME_FLAGS, name);
+}
+export const FIELD_TYPE_NAMES = Object.keys(FIELD_TYPE_NAME_FLAGS).filter(isFieldTypeName);
 // 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)
+// the boot validator (packages/framework/src/engine/boot-validator/screens-forms.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
+// their own EmbeddedListField grid widget — 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

package/dist/handlers.d.ts

@@ -268,23 +268,23 @@ export type AppContext = SharedContextFields & {
         readonly id: string;
         readonly tenantId: TenantId;
     } | null;
-    /** Bei Job-Handler-Aufrufen die aus einem Event-Trigger heraus laufen
-     *  (r.job mit `trigger: { on: ... }`): der Name des Handlers der das
-     *  Event ausgelöst hat. Bei Multi-Trigger-Jobs (`on: [...]`) ist das
-     *  die einzige Möglichkeit für den Handler zu wissen WELCHER Trigger
-     *  gefeuert hat. Cron- und manual-Jobs lassen das Feld undefined. */
+    /** For job-handler calls triggered by an event
+     *  (`r.job` with `trigger: { on: ... }`): the name of the handler that
+     *  emitted the event. For multi-trigger jobs (`on: [...]`), this is the
+     *  only way for the handler to know which trigger fired. Cron and manual
+     *  jobs leave the field undefined. */
     readonly triggerName?: string;
-    /** Optionaler Geo→Zone-Adapter. Wenn gesetzt (via buildServer-context oder
-     *  runProdApp/runDevApp extraContext), reicht der Dispatcher ihn an
-     *  ctx.tz.fromCoordinates / fromAddress weiter. Ohne Provider werfen diese. */
+    /** Optional Geo→zone adapter. When set (via buildServer context or
+     *  `runProdApp`/`runDevApp` `extraContext`), the dispatcher passes it to
+     *  `ctx.tz.fromCoordinates` / `fromAddress`. These methods throw without
+     *  a provider. */
     readonly geoTzProvider?: GeoTzProvider;
     /** Overrides the system clock behind ctx.tz in handlers and jobs; tests inject a fixed time. */
     readonly clock?: Clock;
-    /** Tenant des aktuellen Pipeline-Calls. Wird vom Dispatcher beim Bauen
-     *  des HandlerContext aus `user.tenantId` gespiegelt, damit lifecycle-
-     *  pipeline + system-hooks den Wert ohne Zugriff auf user-Object haben.
-     *  Sprint-8a Tier-Composition: `effectiveFeatures(ctx._tenantId)`-call
-     *  in den hook-filter-Stellen. */
+    /** Tenant of the current pipeline call. The dispatcher mirrors
+     *  `user.tenantId` here when building HandlerContext so the lifecycle
+     *  pipeline and system hooks can access it without the user object.
+     *  `effectiveFeatures(ctx._tenantId)` uses it at hook-filter points. */
     readonly _tenantId?: TenantId;
     /** Boot-configured default locale (BCP-47). Last fallback in ctx.locale's
      *  Request-Locale → Boot-Default chain (dispatch-shared.ts) — used when
@@ -307,13 +307,11 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
     readonly systemDb?: UncheckedSystemDb;
     readonly crossTenantReads?: CrossTenantReads;
     readonly registry: Registry;
-    /** Aktiver SessionUser des Handler-Aufrufs — Convenience-Alias zu
-     *  `event.user`. Existiert weil Handler intuitiv `ctx.user.tenantId`
-     *  schreiben (Context = "kennt seinen User") und der Pfad sonst nur
-     *  über `event.user` läuft, was typo-anfällig ist und stillschweigend
-     *  zu `internal_error` führt wenn der falsche Pfad gewählt wird.
-     *  Identisch zum event.user-Wert; Identity-Switches nutzen
-     *  weiterhin queryAs/writeAs. */
+    /** The active SessionUser for the handler call, exposed as a convenience
+     *  alias for `event.user`. Handlers naturally write `ctx.user.tenantId`;
+     *  without the alias that path does not exist and silently ends in `internal_error`.
+     *  The value is identical to `event.user`; identity switches still use
+     *  `queryAs`/`writeAs`. */
     readonly user: SessionUser;
     readonly systemUser?: SessionUser;
     readonly log?: Logger;
@@ -634,6 +632,9 @@ export type WriteHandlerDef = {
     /** Per-payload-field limits, e.g. per recipient address. Complements
      *  `rateLimit`; anonymous handlers still need an ip-keyed `rateLimit`. */
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
+    /** Tokens each request books on every declared rateLimit bucket, computed from the validated
+     *  payload (e.g. `(p) => p.files.length`). Replaces the options' `cost`; results below 1 count as 1. */
+    readonly rateLimitCost?: (payload: unknown) => number;
     readonly escapeHatch?: EscapeHatchDeclaration;
     /** Reserves before the handler transaction opens. Reached through a nested ctx.write the
      *  reservation cannot run, so the dispatcher rejects it unless the top-level batch reserved it. */
@@ -676,7 +677,7 @@ export type QueryHandlerDef = {
      *  the boot-validator skips any column-reference check that would need
      *  it (screens.ts projectionList/relatedList `columns`, projectionDetail
      *  `header`/`metrics`, dashboard `valueField`/`subField`/etc.) rather
-     *  than requiring it retroactively. See fw#2493. */
+     *  than requiring it retroactively. */
     readonly outputSchema?: ZodType;
     /** Entities whose changes this query reflects. Anonymous callers with
      *  access to this query receive /api/sse change signals (no field values)

package/dist/http-route.d.ts

@@ -1,19 +1,19 @@
 import type { Context } from "hono";
 import type { RateLimitOption } from "./handlers.ts";
-/** Subset von HTTP-Methoden den wir aktiv unterstützen. Hono spricht
- *  alle, aber das hier sind die einzigen die ein Feature-Author
- *  realistisch deklariert. */
+/** Subset of HTTP methods actively supported. Hono supports all methods,
+ *  but these are the only ones a feature author is expected to declare. */
 export type HttpRouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
-/** Dependencies die der Handler vom Framework bekommt. App-Author kann
- *  die App selbst aufrufen (`deps.app.fetch(...)` für intern-call) oder
- *  direkt per dispatcher Daten ziehen. Db/Redis sind die rohen Connections
- *  — wer Tenant-Scope braucht muss durch dispatcher.query gehen.
+/** Dependencies provided to the handler by the framework. The app can be
+ *  called directly (`deps.app.fetch(...)` for internal calls), or data can
+ *  be fetched through the dispatcher. Db/Redis are raw connections — tenant
+ *  scoping requires going through dispatcher.query.
  *
- *  Hono-typing: `Context<any, any>` weil das Hono-Type-Param-Setup nur
- *  intern relevant ist. Concrete Hono-app wird im Boot-Path zugewiesen. */
+ *  Hono typing: `Context<any, any>` is used because Hono's type-parameter
+ *  setup is only relevant internally. The concrete Hono app is assigned
+ *  during boot. */
 export type HttpRouteHandlerDeps = {
-    /** Die Hono-app — Handler kann via app.fetch(...) interne Routes
-     *  ansprechen (z.B. /api/query mit der vollen Auth-/Anonymous-Chain). */
+    /** The Hono app — the handler can use app.fetch(...) to call internal routes
+     *  (e.g. /api/query with the full auth/anonymous chain). */
     readonly app: import("hono").Hono<any, any>;
     /** Run a query handler in-process, forcing a SPECIFIC tenant — WITHOUT
      *  going through the public /api/query HTTP layer (no header parsing, no
@@ -45,9 +45,9 @@ export type HttpRouteRateLimit = Omit<RateLimitOption, "per"> & {
     readonly per: "ip" | "ip+handler";
 };
 export type HttpRouteDefinition = {
-    /** HTTP-Methode — bei Hono-Mount via app.{get,post,...}(path). */
+    /** HTTP method — mounted in Hono via app.{get,post,...}(path). */
     readonly method: HttpRouteMethod;
-    /** URL-Pfad (Hono-Pattern, z.B. "/feed.xml" oder "/og/:tenantId.png"). */
+    /** URL path (Hono pattern, e.g. "/feed.xml" or "/og/:tenantId.png"). */
     readonly path: string;
     /** true = public, no session required. false = mounted behind the
      *  session auth chain (global IP rate limit when configured, PII
@@ -56,8 +56,8 @@ export type HttpRouteDefinition = {
      *  `/api/*` chain only. A request without a session gets 401. The
      *  handler reads the caller via getUser(c). */
     readonly anonymous: boolean;
-    /** Hono-Handler. Bekommt Hono-Context + Framework-Deps; returnt
-     *  Response (sync oder async). */
+    /** Hono handler. Receives the Hono context and framework dependencies;
+     *  returns a Response synchronously or asynchronously. */
     readonly handler: HttpRouteHandler;
     /** Enforced before the route's guards through the server's rate-limit
      *  resolver (fail-open like the global L1 limiter: a limiter outage

package/dist/http-route.js

@@ -4,7 +4,7 @@
 // feature author controls the wire format themselves.
 //
 // Pattern symmetric to r.queryHandler / r.writeHandler: definition as
-// part of the feature (not the app bootstrapping). Phase-3 multi-tenant
+// part of the feature (not the app bootstrapping). Multi-tenant support
 // becomes trivial because tenant context is picked up via host resolution.
 //
 // Escape-hatch stays: runProdApp.extraRoutes (declarative list with

package/dist/list-aggregate-types.d.ts

@@ -0,0 +1,38 @@
+import * as z from "zod";
+import type { AggregateKey } from "./aggregate-types.ts";
+export declare const MAX_LIST_AGGREGATE_MEASURES = 20;
+export declare const LIST_AGGREGATE_MEASURE_KINDS: readonly ["sum", "avg", "count", "min", "max"];
+export type ListAggregateMeasureKind = (typeof LIST_AGGREGATE_MEASURE_KINDS)[number];
+export declare const listAggregatePayloadSchema: z.ZodObject<{
+    groupBy: z.ZodOptional<z.ZodString>;
+    measures: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        kind: z.ZodEnum<{
+            avg: "avg";
+            count: "count";
+            max: "max";
+            min: "min";
+            sum: "sum";
+        }>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ListAggregatePayload = {
+    readonly groupBy?: string | undefined;
+    readonly measures: readonly {
+        readonly field: string;
+        readonly kind: ListAggregateMeasureKind;
+    }[];
+};
+export type ListAggregateValue = number | string | null;
+export type ListAggregateGroup = {
+    readonly key: AggregateKey;
+    readonly label?: string | null;
+    readonly count: number;
+    readonly measures: readonly ListAggregateValue[];
+};
+export type ListAggregateResult = {
+    readonly groups: readonly ListAggregateGroup[];
+    readonly truncated?: true;
+    readonly searchTruncated?: true;
+};
+export declare function isListAggregateResult(value: unknown): value is ListAggregateResult;