@cosmicdrift/kumiko-types 0.399.0 → 0.400.0

package/dist/entity-row-visibility.d.ts

@@ -0,0 +1,26 @@
+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 ReadGateDef = {
+    /** Row readable only if at least one live row of `entity` with `field` = row.id is readable
+     *  through that entity's own parentRef gate (host visibility). */
+    readonly anyLink?: {
+        readonly entity: string;
+        readonly field: string;
+    };
+    /** Row readable only if the file_ref in `field` is live and readable through its owner: owner
+     *  row readable (ownership, parentRef, handler gate) and the field read access on the file_ref's
+     *  fieldName passes. A file owned by this row itself passes this part. */
+    readonly fileOwner?: {
+        readonly field: string;
+    };
+    /** Roles that skip `anyLink` (they also see unlinked rows). `fileOwner` still applies; only
+     *  the framework SYSTEM user skips both. */
+    readonly linkExemptRoles?: readonly string[];
+};

package/dist/entity-row-visibility.js

@@ -0,0 +1 @@
+export {};

package/dist/event-store-executor-types.d.ts

@@ -4,10 +4,13 @@ import type { SessionUser, WriteResult } from "./handlers.ts";
 import type { DeleteContext, SaveContext } from "./hooks.ts";
 import type { EntityId, TenantId } from "./identifiers.ts";
 import type { ListAggregatePayload, ListAggregateResult } from "./list-aggregate-types.ts";
+import type { SchemaTable } from "./schema-table-types.ts";
 import type { SearchAdapter } from "./search-adapter.ts";
 import type { TenantDb } from "./tenant-db-types.ts";
 export type ParentVisibilityOption = {
     readonly entities: ReadonlyMap<string, EntityDefinition>;
+    readonly canReadEntity?: (entityName: string) => boolean;
+    readonly resolveTable?: (entityName: string) => SchemaTable;
 };
 export type ParentVisibilityGateOption = {
     readonly parentVisibility?: ParentVisibilityOption;
@@ -35,6 +38,7 @@ export type ListRuntimeOptions = {
             readonly labelField: string;
         }>;
         readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
+        readonly resolveTable?: (entityName: string) => SchemaTable;
     };
     readonly referenceSort?: {
         readonly fields: ReadonlyArray<{
@@ -43,8 +47,16 @@ export type ListRuntimeOptions = {
             readonly labelField: string;
         }>;
         readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
+        readonly resolveTable?: (entityName: string) => SchemaTable;
     };
     readonly parentVisibility?: ParentVisibilityOption;
+    readonly derivedSql?: {
+        readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
+        readonly resolveTable: (entityName: string) => SchemaTable;
+        readonly canReadEntity: (entityName: string) => boolean;
+        readonly today: string;
+        readonly now: string;
+    };
 };
 type ListFilterOption = {
     readonly field: string;

package/dist/field-state-conditions.d.ts

@@ -0,0 +1,48 @@
+export type FieldCondition = boolean | {
+    readonly field: string;
+    readonly eq: unknown;
+} | {
+    readonly field: string;
+    readonly ne: unknown;
+} | {
+    readonly field: string;
+    readonly in: readonly unknown[];
+} | {
+    readonly field: string;
+    readonly notIn: readonly unknown[];
+};
+export type FieldStateConditions = {
+    /** Field is shown only while the condition holds on the record values. Hidden values are kept, never dropped. */
+    readonly visibleWhen?: Exclude<FieldCondition, boolean>;
+    /** Field is required while the condition holds (and the field is visible). Enforced by the server write path, not only the form. */
+    readonly requiredWhen?: Exclude<FieldCondition, boolean>;
+};
+/** Value is an array of FileRef ids; `file_refs.fieldName` stays the top-level embedded field name. */
+export type EmbeddedFilesSubFieldProps = {
+    readonly maxSize?: string;
+    readonly accept?: readonly string[];
+    readonly maxCount?: number;
+};
+export type EmbeddedImagesSubFieldProps = EmbeddedFilesSubFieldProps & {
+    readonly capture?: "environment" | "user";
+};
+/** 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 = {
+    /** Row-level condition on a sibling sub-field. When it does not hold for a row, the cell is not
+     *  derived there: it stays a normal input and the row value is left untouched. */
+    readonly when?: Exclude<FieldCondition, boolean>;
+} & ({
+    /** `percent` = `from[0] * from[1] / 100` (exactly two sources, e.g. amount and rate). */
+    readonly op: "multiply" | "sum" | "subtract" | "percent";
+    readonly from: readonly string[];
+} | {
+    /** `from` is exactly `[value, min, max]`; bounds are inclusive and each may be missing. */
+    readonly op: "inRange";
+    readonly from: readonly string[];
+    readonly inside: string;
+    readonly outside: string;
+});

package/dist/field-state-conditions.js

@@ -0,0 +1 @@
+export {};

package/dist/fields-derived.d.ts

@@ -1,27 +1,81 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
 /** 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";
+ *  choice in the view-model, parallel to FieldDefinition["type"]. `money` is
+ *  SQL-only and only for a `related` + `first` measure of a money field: the
+ *  value is the stored money read shape (`{ amount, currency, ... }`), the
+ *  currency read next to the amount. A JS `derive` cannot return money. */
+export type DerivedValueType = "text" | "number" | "decimal" | "boolean" | "date" | "timestamp" | "money";
 /** 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 = {
+export type JsDerivedFieldDef = {
     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`). */
+     *  `date`). Runs after SQL derived values are on the row. */
     readonly derive: (row: Readonly<Record<string, unknown>>, ctx: DeriveContext) => unknown;
 };
+export type SqlDerivedFieldDef = {
+    readonly valueType: DerivedValueType;
+    readonly sortable?: boolean;
+    readonly sql: DerivedSqlSpec;
+    readonly derive?: undefined;
+};
+export type DerivedFieldDef = JsDerivedFieldDef | SqlDerivedFieldDef;
+export type DerivedSqlSpec = {
+    readonly kind: "coalesce";
+    readonly fields: readonly string[];
+} | {
+    readonly kind: "related";
+    /** Same convention as a reference field's `entity` ("feature:entity"). */
+    readonly entity: string;
+    /** related.<field> = outer.<outer ?? "id"> */
+    readonly on: {
+        readonly field: string;
+        readonly outer?: string;
+    };
+    readonly measure: DerivedRelatedMeasure;
+    /** AND-ed. */
+    readonly where?: readonly DerivedCondition[];
+};
+export type DerivedRelatedMeasure = {
+    readonly kind: "count";
+} | {
+    readonly kind: "countDistinct";
+    readonly field: string;
+} | {
+    readonly kind: "first";
+    readonly field: string;
+    readonly orderBy: string;
+    readonly direction: "asc" | "desc";
+    /** Only for a reference field with labelField: yields the referenced row's label. */
+    readonly label?: boolean;
+};
+export type DerivedConditionValue = string | number | boolean | null | readonly (string | number)[] | {
+    readonly today: true;
+} | {
+    readonly now: true;
+};
+export type DerivedCondition = {
+    readonly field: string;
+    readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
+    readonly value: DerivedConditionValue;
+}
+/** from <= today AND (to IS NULL OR to >= today) */
+ | {
+    readonly activeOn: {
+        readonly from: string;
+        readonly to: string;
+    };
+};
+export declare function isSqlDerivedField(def: DerivedFieldDef): def is SqlDerivedFieldDef;
 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">;
+/** Client-facing projection of DerivedFieldDef: `derive`/`sql` are server-only
+ *  (not JSON-safe), so the browser schema only carries `valueType` and `sortable`. */
+export type ClientDerivedFieldDef = {
+    readonly valueType: DerivedValueType;
+    readonly sortable?: true;
+};

package/dist/fields-derived.js

@@ -1,20 +1,13 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
 // --- 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.
-export {};
+// A derived field is read-time only: never persisted, no DB column, never in a
+// write schema. It lives in `EntityDefinition.derivedFields`, not in `fields`.
+// JS `derive` fields run in the list handler after the SQL fetch and are
+// display-only. `sql` fields are computed inside the list SELECT as correlated
+// subqueries (identifiers come from registry-validated field names, values are
+// always bound params) and can opt into `sortable`. Time-dependent values stay
+// read-time; neither kind enters the entity cache.
+export function isSqlDerivedField(def) {
+    return "sql" in def;
+}

package/dist/fields.d.ts

@@ -1,10 +1,14 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
 import type { VariantSpec } from "./derivatives-types.ts";
+import type { EmbeddedDerivedCellDef, EmbeddedFilesSubFieldProps, EmbeddedImagesSubFieldProps, FieldCondition, FieldStateConditions } from "./field-state-conditions.ts";
+export type { EmbeddedDerivedCellDef, EmbeddedFilesSubFieldProps, EmbeddedImagesSubFieldProps, FieldCondition, FieldStateConditions, } from "./field-state-conditions.ts";
+import type { ParentRefDef, ReadGateDef } from "./entity-row-visibility.ts";
 import type { DerivedFieldsMap } from "./fields-derived.ts";
 import type { EventUpcastCtx } from "./handlers.ts";
 import type { OwnershipMap } from "./ownership.ts";
 import type { EntityTenancy } from "./tenancy-brand.ts";
-export type { ClientDerivedFieldDef, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, } from "./fields-derived.ts";
+export type { ClientDerivedFieldDef, DeriveContext, DerivedCondition, DerivedConditionValue, DerivedFieldDef, DerivedFieldsMap, DerivedRelatedMeasure, DerivedSqlSpec, DerivedValueType, JsDerivedFieldDef, SqlDerivedFieldDef, } from "./fields-derived.ts";
+export { isSqlDerivedField } from "./fields-derived.ts";
 export type FieldAccess = {
     readonly read?: OwnershipMap | readonly string[];
     readonly write?: OwnershipMap | readonly string[];
@@ -30,6 +34,7 @@ export type ResolvedPiiFlags = {
      *  that lives purely in an FK column. */
     readonly subjectRef?: true;
 };
+type PiiAndFieldState = ResolvedPiiFlags & FieldStateConditions;
 export type EntityPiiAbsentSubject = "tenant" | "self";
 export type PersonalSubject = "self" | {
     readonly of: string;
@@ -137,7 +142,7 @@ export type TextFieldDef = {
     readonly multiline?: boolean | {
         readonly rows?: number;
     };
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 /**
  * Long-form text content — source code, markdown, blog posts, email
  * templates, and anything that can be megabytes large. Its surface is
@@ -176,7 +181,7 @@ export type LongTextFieldDef = {
     readonly multiline?: boolean | {
         readonly rows?: number;
     };
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 export type BooleanFieldDef = {
     readonly type: "boolean";
     readonly description?: string;
@@ -187,7 +192,7 @@ export type BooleanFieldDef = {
     readonly sensitive?: boolean;
     readonly default?: boolean;
     readonly access?: FieldAccess;
-};
+} & FieldStateConditions;
 export declare const SELECT_OPTION_TONES: readonly ["ok", "warn", "bad", "critical", "accent", "neutral"];
 export type SelectOptionTone = (typeof SELECT_OPTION_TONES)[number];
 /** One `optionsQueryPayload` entry: a literal, or `{ field }` = the current value of
@@ -200,19 +205,6 @@ export declare function isOptionsQueryFieldRef(value: OptionsQueryPayloadValue):
     readonly field: string;
 };
 export declare function optionsQueryFieldRefs(payload: OptionsQueryPayload | undefined): string[];
-export type FieldCondition = boolean | {
-    readonly field: string;
-    readonly eq: unknown;
-} | {
-    readonly field: string;
-    readonly ne: unknown;
-} | {
-    readonly field: string;
-    readonly in: readonly unknown[];
-} | {
-    readonly field: string;
-    readonly notIn: readonly unknown[];
-};
 /** Options of a select field that are only available while `when` holds for the row values. */
 export type SelectConditionalOptions<TOption extends string = string> = {
     readonly options: readonly TOption[];
@@ -262,7 +254,7 @@ export type SelectFieldDef<TOptions extends readonly string[] = readonly string[
      *  in no rule are always available. The write path enforces it, the renderer only
      *  filters. Only valid on entity fields. */
     readonly conditionalOptions?: readonly SelectConditionalOptions<TOptions[number]>[];
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 export type MultiSelectFieldDef<TOptions extends readonly string[] = readonly string[]> = {
     readonly type: "multiSelect";
     readonly description?: string;
@@ -291,7 +283,7 @@ export type MultiSelectFieldDef<TOptions extends readonly string[] = readonly st
      *  `hint` is ignored. Static `options` stay authoritative and the write path must
      *  enforce the same rule, the renderer only mirrors it. Called with an empty payload. */
     readonly optionsAvailabilityQuery?: string;
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 /**
  * Storage: `integer` flag decides the Postgres column type, not just Zod
  * validation. `integer: true` → `integer` column (32-bit, ~±2.1 billion),
@@ -325,7 +317,7 @@ export type NumberFieldDef = {
      *  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;
+} & PiiAndFieldState;
 /**
  * 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`,
@@ -347,7 +339,7 @@ export type BigIntFieldDef = {
     readonly sensitive?: boolean;
     readonly default?: number;
     readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 /**
  * Exact decimal — Postgres `numeric(precision, scale)`. For values that need
  * fractional precision the integer `number` field (32-bit int) and `money`
@@ -372,7 +364,7 @@ export type DecimalFieldDef = {
     readonly sensitive?: boolean;
     readonly default?: number;
     readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 /** Where a money field's currency comes from. `"tenant"` is the
  *  tenant-settings bundle's per-tenant currency (`tenant-settings:config:
  *  currency`); `"literal"` names a fixed ISO code and
@@ -405,7 +397,7 @@ export type MoneyFieldDef = {
      *  (`entity.defaultCurrency ?? "EUR"`); a stored value always keeps its
      *  own currency regardless of this declaration. */
     readonly currency?: MoneyCurrencySource;
-};
+} & FieldStateConditions;
 export type ReferenceFieldDef = {
     readonly type: "reference";
     readonly description?: string;
@@ -460,13 +452,13 @@ export type ReferenceFieldDef = {
      *  reference then deliberately crosses the tenant boundary after the
      *  handover. Use it for an entity that must not move with its host. */
     readonly handover?: "stay";
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 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;
-};
+} & FieldStateConditions;
 /** `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
@@ -487,23 +479,23 @@ export type EmbeddedSubFieldDef = (EmbeddedSubFieldBase & {
     /** Same contract as `SelectFieldDef.display`; in a table cell the
      *  default stays a dropdown. */
     readonly display?: "radio" | "dropdown";
+    readonly optionTones?: {
+        readonly [option: string]: SelectOptionTone;
+    };
 }) | (EmbeddedSubFieldBase & {
     readonly type: "reference";
     readonly entity: string;
     readonly labelField?: string;
     /** Same contract as `ReferenceFieldDef.optionsQuery`. */
     readonly optionsQuery?: string;
+}) | (EmbeddedSubFieldBase & EmbeddedImagesSubFieldProps & {
+    readonly type: "images";
+}) | (EmbeddedSubFieldBase & EmbeddedFilesSubFieldProps & {
+    readonly type: "files";
 });
-/** 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 = {
-    /** `percent` = `from[0] * from[1] / 100` (exactly two sources, e.g. amount and rate). */
-    readonly op: "multiply" | "sum" | "subtract" | "percent";
-    readonly from: readonly string[];
-};
+export type EmbeddedFileSubFieldDef = Extract<EmbeddedSubFieldDef, {
+    type: "images" | "files";
+}>;
 export type EmbeddedTotalDef = string | {
     readonly label: string;
     readonly from: readonly string[];
@@ -547,7 +539,7 @@ export type EmbeddedFieldDef = {
      *  rounded `derived` cells, i.e. "sum-of-rounded" not "round-of-sum" —
      *  see the embedded-list totals-matching behavior. */
     readonly totalsMatch?: Readonly<Record<string, string>>;
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 export type JsonbFieldDef = {
     readonly type: "jsonb";
     readonly description?: string;
@@ -561,7 +553,7 @@ export type JsonbFieldDef = {
      *  run that already read the compromised value. See irreversible-operation-gate. */
     readonly readAsInstruction?: boolean;
     readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 export type JsonbEmptyValue = "object" | "array";
 export type DateFieldDef = {
     readonly type: "date";
@@ -580,7 +572,7 @@ export type DateFieldDef = {
     /** Format/locale override for display and input parsing (for example,
      *  "de-DE"). Default: app locale. */
     readonly locale?: string;
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 export type TimestampFieldDef = {
     readonly type: "timestamp";
     readonly description?: string;
@@ -606,14 +598,14 @@ export type TimestampFieldDef = {
     /** Format/locale override for display and input parsing. Default: app
      *  locale. */
     readonly locale?: string;
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 export type TzFieldDef = {
     readonly type: "tz";
     readonly description?: string;
     readonly required?: boolean;
     readonly sensitive?: boolean;
     readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 export type LocatedTimestampFieldDef = {
     readonly type: "locatedTimestamp";
     readonly description?: string;
@@ -631,7 +623,7 @@ export type LocatedTimestampFieldDef = {
     /** Format/locale override for display and input parsing. Default: app
      *  locale. */
     readonly locale?: string;
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 export type FileFieldDef = {
     readonly type: "file";
     readonly description?: string;
@@ -642,7 +634,7 @@ export type FileFieldDef = {
     readonly anonymousUpload?: boolean;
     readonly accept?: readonly string[];
     readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 export type ImageFieldDef = {
     readonly type: "image";
     readonly description?: string;
@@ -660,7 +652,7 @@ export type ImageFieldDef = {
      *  camera instead of the file picker. */
     readonly capture?: "environment" | "user";
     readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 export type FilesFieldDef = {
     readonly type: "files";
     readonly description?: string;
@@ -675,7 +667,7 @@ export type FilesFieldDef = {
      *  `maxCount`/`accept`/`maxSize` as hints. The stored value is the same array of FileRef ids. */
     readonly display?: "list" | "dropzone";
     readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 export type ImagesFieldDef = {
     readonly type: "images";
     readonly description?: string;
@@ -694,7 +686,7 @@ export type ImagesFieldDef = {
      *  camera instead of the file picker. */
     readonly capture?: "environment" | "user";
     readonly access?: FieldAccess;
-} & ResolvedPiiFlags;
+} & PiiAndFieldState;
 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,
@@ -758,15 +750,7 @@ export type EntityTextFieldDef = TextFieldDef & ResolvedPiiStance;
 export type EntityLongTextFieldDef = LongTextFieldDef & ResolvedPiiStance;
 export type EntityFieldDefinition = Exclude<FieldDefinition, TextFieldDef | LongTextFieldDef> | EntityTextFieldDef | EntityLongTextFieldDef;
 export type FieldsMap = Readonly<Record<string, EntityFieldDefinition>>;
-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 { ParentRefDef, ReadGateDef } from "./entity-row-visibility.ts";
 export type EntityEventMigration = {
     readonly fromVersion: number;
     readonly toVersion: number;
@@ -841,6 +825,13 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTe
      * registered entity is denied.
      */
     readonly parentRef?: ParentRefDef;
+    /**
+     * Declarative read gate for rows readable only through other rows (a link to a visible host,
+     * a file whose owner is readable). AND-ed with `access.read` and `parentRef` in list, detail,
+     * count, aggregate, live signals and the writers' readability check. Without the request-time
+     * registry the gate denies every non-system caller.
+     */
+    readonly readGate?: ReadGateDef;
     /**
      * Default retention policy for this entity. Tenant administrators can
      *   override it through compliance profiles and tenant overrides.

package/dist/fields.js

@@ -1,5 +1,6 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
 // --- Field Types ---
+export { isSqlDerivedField } from "./fields-derived.js";
 export const SELECT_OPTION_TONES = ["ok", "warn", "bad", "critical", "accent", "neutral"];
 export function isOptionsQueryFieldRef(value) {
     return typeof value === "object" && value !== null;

package/dist/handlers.d.ts

@@ -117,10 +117,14 @@ export type QueryEvent<TPayload = unknown> = {
     readonly payload: TPayload;
     readonly user: SessionUser;
 };
+import type { LifecycleResult } from "./hooks.ts";
 import type { WriteFailure } from "./write-error-info-types.ts";
 export type WriteResult<TData = unknown> = {
     readonly isSuccess: true;
     readonly data: TData;
+    /** The executor result behind a handler that answers with its own `data`. Hooks and
+     *  projections run on it; the dispatcher removes it from what leaves the pipeline. */
+    readonly lifecycle?: LifecycleResult;
 } | WriteFailure;
 import type { Registry } from "./feature.ts";
 import type { TenantId } from "./identifiers.ts";

package/dist/screen-entity-edit.d.ts

@@ -79,6 +79,9 @@ export type FieldFillAction = {
 export type EmbeddedListEditSpec = {
     /** Sub-fields shown as read-only cells; every other cell stays editable. */
     readonly readOnlyCells?: readonly string[];
+    /** Sub-fields that only steer a row (e.g. the kind that decides which controls
+     *  appear) and are not shown on phone cards; the desktop table still shows them. */
+    readonly cardHiddenCells?: readonly string[];
     /** `true` keeps the rows as they are: no add, remove, duplicate, move or
      *  paste-appended rows. Cells stay editable (unless in `readOnlyCells`). */
     readonly fixedRows?: boolean;
@@ -195,6 +198,10 @@ export type EditRelatedListSection = {
     readonly id?: string;
     readonly kind: "relatedList";
     readonly title: string;
+    /** Rows are aggregates or other values with no record of their own, so they lead nowhere on
+     *  purpose. Declares that to the screen-conventions guard; with `rowClick`/`rowActions` it is a
+     *  boot error. */
+    readonly readOnly?: boolean;
     /** Fully qualified query QN. Same paged envelope as projectionList.query:
      *  `{ rows, nextCursor, total? }`. */
     readonly query: string;
@@ -282,6 +289,11 @@ export type EditRelatedListSection = {
      *  Ignored outside tabs mode or when the field's value is not a finite
      *  number. */
     readonly countField?: string;
+    /** Tab badge counted from this section's own query (`limit: 1, totalCount: true`
+     *  → `total`), so it matches the tab's rows and stays live. Tabs mode only,
+     *  exclusive with `countField`; the query's Zod schema must accept `totalCount`
+     *  and `limit`. */
+    readonly count?: true;
     /** Rendered top-right in the section's Card title row — same
      *  navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`,
      *  evaluated against the parent record. Every action must resolve an icon

package/dist/screen-expandable-row.d.ts

@@ -9,7 +9,7 @@ export type ExpandableRowGrouping = Omit<ListTableGrouping, "field" | "userChoic
  *  layout and are therefore omitted. `kind` stays the discriminator so further
  *  expansion kinds can be added without a breaking change. `table` takes only
  *  `grouping`; the other table options belong on the entityList itself. */
-export type EntityListExpandableRow = Omit<EditRelatedListSection, "id" | "countField" | "table" | "bulkActions"> & {
+export type EntityListExpandableRow = Omit<EditRelatedListSection, "id" | "countField" | "count" | "table" | "bulkActions"> & {
     readonly table?: {
         readonly grouping?: ExpandableRowGrouping;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.399.0",
+  "version": "0.400.0",
   "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt keine identitaets-sensitiven Runtime-Werte mehr (Error-Klassen leben seit #1629 in kumiko-framework, Brand-Symbole nutzen Symbol.for) und ist deshalb eine plain dependency, keine peerDependency.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",