@cosmicdrift/kumiko-framework 0.398.0 → 0.400.0

package/dist/engine/boot-validator/read-gate.js

@@ -0,0 +1,54 @@
+import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
+import { FILE_REF_ENTITY_NAME } from "../../files/types.js";
+import { findEntity } from "./parent-ref.js";
+function fail(check, message) {
+    throw new Error(`[Kumiko ReadGate] entity "${check.entityName}" (feature: "${check.feature.name}"): ${message}`);
+}
+function validateAnyLink(check, anyLink) {
+    const link = findEntity(check.featureMap, anyLink.entity);
+    if (link === undefined) {
+        fail(check, `readGate.anyLink.entity "${anyLink.entity}" is not registered.`);
+    }
+    if (link.parentRef === undefined) {
+        fail(check, `readGate.anyLink.entity "${anyLink.entity}" must declare a parentRef; its host visibility is what the gate checks.`);
+    }
+    if (link.fields[anyLink.field] === undefined) {
+        fail(check, `readGate.anyLink.field "${anyLink.field}" is not a field of "${anyLink.entity}".`);
+    }
+}
+function validateFileOwner(check, fileOwner) {
+    const fileField = check.entity.fields[fileOwner.field];
+    if (fileField?.type !== "file" && fileField?.type !== "image") {
+        fail(check, `readGate.fileOwner.field "${fileOwner.field}" must be a single file or image field.`);
+    }
+    if (findEntity(check.featureMap, FILE_REF_ENTITY_NAME) === undefined) {
+        fail(check, `readGate.fileOwner needs the files feature (entity "${FILE_REF_ENTITY_NAME}").`);
+    }
+}
+function validateNoHandWrittenReaders(check) {
+    for (const verb of ["list", "detail"]) {
+        const handlerName = `${check.entityName}:${verb}`;
+        for (const f of check.featureMap.values()) {
+            const handler = f.queryHandlers[handlerName];
+            if (handler !== undefined && handler[ENTITY_CONVENTION_QUERY_BRAND] !== true) {
+                fail(check, `query handler "${handlerName}" is hand-written and would bypass the readGate. Fix: register it via defineEntityListHandler/defineEntityDetailHandler.`);
+            }
+        }
+    }
+}
+export function validateReadGates(feature, featureMap) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+        const gate = entity.readGate;
+        if (gate === undefined)
+            continue;
+        const check = { feature, featureMap, entityName, entity };
+        if (entity.parentRef !== undefined) {
+            fail(check, "readGate and parentRef cannot be combined; a gated entity cannot be a join row.");
+        }
+        if (gate.anyLink !== undefined)
+            validateAnyLink(check, gate.anyLink);
+        if (gate.fileOwner !== undefined)
+            validateFileOwner(check, gate.fileOwner);
+        validateNoHandWrittenReaders(check);
+    }
+}

package/dist/engine/boot-validator/screens-forms.js

@@ -3,6 +3,22 @@ import { isKebabSegment } from "../qualified-name.js";
 import { isExtensionEditSection, isWriteFormEditSection, normalizeEditField, sectionFieldSpecs, } from "../screen-helpers.js";
 import { validateFormDerivations, validateFormDerivationsEnforced } from "./form-derivations.js";
 import { assertWriteHandlerRegistered, isSensitiveOrPasswordField, validateIdlessSuccessLink, validateRedirectTarget, validateScreenNavTarget, } from "./screens-actions.js";
+function assertKnownSubFields(where, option, cells, schema) {
+    for (const cell of cells ?? []) {
+        if (schema[cell] === undefined) {
+            throw new Error(`${where} embeddedList.${option} names "${cell}", which is not a sub-field ` +
+                `(known: ${Object.keys(schema).sort().join(", ")}).`);
+        }
+    }
+}
+function assertCardHiddenCellsReadOnly(where, cardHiddenCells, readOnlyCells) {
+    for (const cell of cardHiddenCells ?? []) {
+        if (readOnlyCells?.includes(cell) !== true) {
+            throw new Error(`${where} embeddedList.cardHiddenCells names "${cell}", which is editable; ` +
+                `only read-only cells (readOnlyCells) can be hidden on cards, otherwise phone users cannot fill it.`);
+        }
+    }
+}
 // A field type in NO_WIDGET_FIELD_TYPES renders read-only on the auto-wired
 // entityEdit path — a required field the user can never fill would
 // block every save. Only the statically-resolvable case is caught here: a
@@ -23,12 +39,9 @@ export function validateEditFieldExtras(featureName, screenId, entityDef, fieldS
             throw new Error(`${where} sets embeddedList, which only applies to an embedded list ` +
                 `(createEmbeddedListField); the field is type "${fieldDef.type}". Remove embeddedList or point it at an embedded list field.`);
         }
-        for (const cell of listSpec.readOnlyCells ?? []) {
-            if (fieldDef.schema[cell] === undefined) {
-                throw new Error(`${where} embeddedList.readOnlyCells names "${cell}", which is not a sub-field ` +
-                    `(known: ${Object.keys(fieldDef.schema).sort().join(", ")}).`);
-            }
-        }
+        assertKnownSubFields(where, "readOnlyCells", listSpec.readOnlyCells, fieldDef.schema);
+        assertKnownSubFields(where, "cardHiddenCells", listSpec.cardHiddenCells, fieldDef.schema);
+        assertCardHiddenCellsReadOnly(where, listSpec.cardHiddenCells, listSpec.readOnlyCells);
     }
     const prefill = fieldSpec.prefill;
     // skip: no prefill declared

package/dist/engine/boot-validator/screens-kind-entity-list.js

@@ -3,6 +3,7 @@ import { rowMetaFieldNames } from "../../db/table-builder.js";
 import { qualifyEntityName } from "../qualified-name.js";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops.js";
 import { normalizeListColumn } from "../screen-helpers.js";
+import { isSortableSqlDerivedField } from "./derived-sql-fields.js";
 import { validateEntityListAggregateOptions } from "./entity-list-aggregate-options.js";
 import { LIST_ROW_META_COLUMN_NAMES } from "./entity-list-screens.js";
 import { validateListBulkActions } from "./list-bulk-actions.js";
@@ -14,10 +15,9 @@ import { validateRelatedListSection, validateRowActionTarget } from "./screens-l
 function resolveEntityListFields(ctx, screenId, entityName) {
     const entityDef = resolveScreenEntity(ctx, screenId, entityName);
     const fieldNames = new Set(Object.keys(entityDef.fields));
-    // List columns may also name a read-time derived field (not a stored
-    // column). Allowed for display; deliberately NOT added to `fieldNames`, so
-    // defaultSort/filter on a derived field still fails — server-side sort over
-    // a non-column is a silent no-op (see DerivedFieldDef).
+    // List columns may also name a read-time derived field (not a stored column).
+    // Deliberately NOT added to `fieldNames`, so filtering one still fails; only a
+    // `sortable` SQL derived field may be the defaultSort (see isSortableSqlDerivedField).
     const columnFieldNames = entityDef.derivedFields !== undefined
         ? new Set([...fieldNames, ...Object.keys(entityDef.derivedFields)])
         : fieldNames;
@@ -52,7 +52,8 @@ function validateEntityListColumns(ctx, screenId, screen, fields) {
 }
 function validateEntityListDefaultSort(featureName, screenId, defaultSort, fields) {
     const sortField = defaultSort.field;
-    if (!fields.fieldNames.has(sortField)) {
+    const sortsOnDerived = isSortableSqlDerivedField(fields.entityDef, sortField);
+    if (!fields.fieldNames.has(sortField) && !sortsOnDerived) {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityList) defaultSort references unknown ` +
             `field "${sortField}". Known fields: ${[...fields.fieldNames].sort().join(", ")}`);
     }
@@ -64,7 +65,8 @@ function validateEntityListDefaultSort(featureName, screenId, defaultSort, field
     // Number/Date fields are naturally sortable. Authors can mark them
     // sortable when their field type supports it.
     const fieldDef = fields.entityDef.fields[sortField];
-    const isSortable = fieldDef !== undefined && "sortable" in fieldDef && fieldDef.sortable === true;
+    const isSortable = sortsOnDerived ||
+        (fieldDef !== undefined && "sortable" in fieldDef && fieldDef.sortable === true);
     if (!isSortable) {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityList) defaultSort.field "${sortField}" ` +
             `is not sortable. Set sortable: true on the field definition or pick another field.`);

package/dist/engine/boot-validator/screens-lists.js

@@ -84,11 +84,19 @@ function validateRelatedListTableAndBulk(args) {
         validateRelatedListRowActions(args, section.rowActions);
     validateListBulkActions(`[Feature ${featureName}] ${where}`, section.bulkActions, section.rowActions);
 }
+function assertReadOnlyHasNoRowInteraction(args) {
+    const { section } = args;
+    const interactive = section.rowClick !== undefined || (section.rowActions?.length ?? 0) > 0;
+    if (section.readOnly === true && interactive) {
+        throw new Error(`[Feature ${args.featureName}] ${args.where} is readOnly but declares rowClick/rowActions. Remove readOnly or the row interaction.`);
+    }
+}
 export function validateRelatedListSection(args) {
     const { featureName, featureMap, where, section } = args;
     if (!section.query || typeof section.query !== "string") {
         throw new Error(`[Feature ${featureName}] ${where} has empty or non-string query. Set query to a registered query name.`);
     }
+    assertReadOnlyHasNoRowInteraction(args);
     if (section.entity !== undefined) {
         assertRefTargetRegistered(`[Feature ${featureName}] ${where}`, "entity", section.entity, featureName, featureMap);
     }

package/dist/engine/boot-validator/zod-shape.js

@@ -1,4 +1,4 @@
-import { ZodArray, ZodCatch, ZodDefault, ZodIntersection, ZodLazy, ZodMap, ZodNonOptional, ZodNullable, ZodObject, ZodOptional, ZodPipe, ZodPrefault, ZodPromise, ZodReadonly, ZodRecord, ZodSet, ZodTuple, ZodUnion, ZodXor, } from "zod";
+import { ZodArray, ZodCatch, ZodDefault, ZodIntersection, ZodLazy, ZodMap, ZodNever, ZodNonOptional, ZodNullable, ZodObject, ZodOptional, ZodPipe, ZodPrefault, ZodPromise, ZodReadonly, ZodRecord, ZodSet, ZodTuple, ZodUnion, ZodXor, } from "zod";
 // Drills through wrapper types (.nullable(), .optional(), .default()) a
 // handler's schema may use around its actual object/array shape — e.g. a
 // detail query returning `Row | null` when the record doesn't exist.
@@ -29,7 +29,9 @@ export function getZodObjectShape(schema) {
     const unwrapped = unwrapZodType(schema);
     // loose()/catchall() objects accept keys beyond the declared shape, so the
     // declared keys are not the full set callers may legitimately reference.
-    const hasOpenKeys = unwrapped instanceof ZodObject && unwrapped.def.catchall !== undefined;
+    // .strict() also sets a catchall, ZodNever, which closes the keys instead.
+    const catchall = unwrapped instanceof ZodObject ? unwrapped.def.catchall : undefined;
+    const hasOpenKeys = catchall !== undefined && !(catchall instanceof ZodNever);
     return unwrapped instanceof ZodObject && !hasOpenKeys ? unwrapped.shape : undefined;
 }
 // The shape of one row for a query whose result follows the paged-list

package/dist/engine/build-app-schema.js

@@ -25,6 +25,7 @@
 // Feature toggles: this schema is tenant-independent and lists every feature.
 // The schema route strips features the caller's tenant has switched off
 // (r.toggleable) via stripDisabledFeaturesFromAppSchema.
+import { isSqlDerivedField } from "@cosmicdrift/kumiko-types/fields";
 import { ZodObject } from "zod";
 import { createFallbackLogger } from "../logging/utils.js";
 import { collectUrlPrefillFieldsByScreenQn } from "./boot-validator/url-prefill-fields.js";
@@ -426,12 +427,13 @@ function projectEntity(entityName, entity) {
         ...(entity.lockedWhen !== undefined && { lockedWhen: entity.lockedWhen }),
     };
 }
-// Only valueType is forwarded — the derive function is server-only and is not
-// JSON-safe (it would otherwise trigger the output-walk guard). Return
-// ClientDerivedFieldDef honestly instead of pretending to return a
-// DerivedFieldDef without its derive function.
+// derive/sql are server-only and not JSON-safe (they would trip the output-walk guard).
 function projectDerivedField(derivedDef) {
-    return { valueType: derivedDef.valueType };
+    return {
+        valueType: derivedDef.valueType,
+        ...(isSqlDerivedField(derivedDef) &&
+            derivedDef.sortable === true && { sortable: true }),
+    };
 }
 // A textarea height that is not a positive integer cannot render anywhere; fail
 // at boot with the field name instead of letting each renderer guess a fallback.
@@ -491,6 +493,9 @@ const FORWARDED_FIELD_PROPERTIES = [
     ["optionsAvailabilityQuery", isStringValue],
     // Select: options only offered while a sibling-field condition holds; the renderer filters, the write path enforces.
     ["conditionalOptions", Array.isArray],
+    // Conditional field state: the renderer evaluates it per row/form, the write path enforces requiredWhen.
+    ["visibleWhen", isJsonSafeObject],
+    ["requiredWhen", isJsonSafeObject],
     ["multiple", isBooleanValue],
     // MultiSelect: display picks checkboxes vs. combobox in the renderer,
     // columns/maxRows size the checkbox grid — without these the renderer
@@ -527,6 +532,7 @@ const FORWARDED_FIELD_PROPERTIES = [
     // the preview variant.
     ["accept", isJsonSafeArray],
     ["maxSize", isStringValue],
+    ["maxCount", isNumberValue],
     ["variants", isJsonSafeObject],
     // decimal, incl. embedded sub-fields: rounding of derived embedded-list cells.
     ["scale", isNumberValue],

package/dist/engine/embedded-derived.d.ts

@@ -1,11 +1,12 @@
 import type { EmbeddedDerivedCellDef, EmbeddedSubFieldDef } from "@cosmicdrift/kumiko-types/fields";
+export type NumericDerivedOp = Exclude<EmbeddedDerivedCellDef["op"], "inRange">;
 /** Computes a derived cell from its source values. Missing/non-numeric
  *  sources: "multiply"/"percent" with any missing source → undefined; "sum"/"subtract"
  *  treat missing as 0 only when at least one source is present — if every
  *  source is missing, return undefined (do not invent 0). Money cells are
  *  minor-unit integers — unit-agnostic arithmetic; `withDerivedCells` rounds
  *  to the target sub-field's declared precision afterward. */
-export declare function computeDerivedCellValue(op: EmbeddedDerivedCellDef["op"], values: readonly (number | undefined)[]): number | undefined;
+export declare function computeDerivedCellValue(op: NumericDerivedOp, values: readonly (number | undefined)[]): number | undefined;
 export type DerivedCellRoundingTarget = {
     readonly type: EmbeddedSubFieldDef["type"];
     readonly scale?: number;
@@ -19,11 +20,12 @@ export declare function roundDerivedCellValue(value: number, target: DerivedCell
 /** Recomputes every derived cell of an embedded-list row from its raw
  *  values, overwriting whatever the client sent instead of merely checking
  *  it — the server is the authority for derived cells. Reads source values
- *  from the working copy so already-recomputed sources feed later cells;
- *  boot-validator rejects derived-from-derived chains. A row that isn't a
+ *  from the working copy, so a cell declared after its source sees the
+ *  recomputed source. A row that isn't a
  *  plain object (already invalid, or not this field's shape) passes through
  *  untouched — validation downstream rejects it. The computed value is
- *  rounded to the target sub-field's declared precision (`schema`) before
+ *  rounded to the target sub-field's declared precision (`targets`) before
  *  it's written back, so a fractional product lands on a value the target
- *  type can actually represent. */
-export declare function withDerivedCells(row: unknown, derived: Readonly<Record<string, EmbeddedDerivedCellDef>>, schema: Readonly<Record<string, EmbeddedSubFieldDef>>): unknown;
+ *  type can actually represent. A cell whose `when` is false for the row is
+ *  not derived there: its row value is left as sent. */
+export declare function withDerivedCells(row: unknown, derived: Readonly<Record<string, EmbeddedDerivedCellDef>>, targets: Readonly<Record<string, DerivedCellRoundingTarget>>): unknown;

package/dist/engine/embedded-derived.js

@@ -1,4 +1,5 @@
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { evalFieldCondition } from "./screen-helpers.js";
 /** Computes a derived cell from its source values. Missing/non-numeric
  *  sources: "multiply"/"percent" with any missing source → undefined; "sum"/"subtract"
  *  treat missing as 0 only when at least one source is present — if every
@@ -58,33 +59,50 @@ function roundHalfAwayFromZero(value, decimals) {
     const scaled = Number((Math.abs(value) * factor).toPrecision(15));
     return (Math.sign(value) * Math.round(scaled)) / factor;
 }
+/** `from` is `[value, min, max]`; bounds are inclusive and either may be missing. */
+function computeInRangeCell(values, inside, outside) {
+    const [value, min, max] = values;
+    if (value === undefined || (min === undefined && max === undefined))
+        return undefined;
+    const aboveMin = min === undefined || value >= min;
+    const belowMax = max === undefined || value <= max;
+    return aboveMin && belowMax ? inside : outside;
+}
 /** Recomputes every derived cell of an embedded-list row from its raw
  *  values, overwriting whatever the client sent instead of merely checking
  *  it — the server is the authority for derived cells. Reads source values
- *  from the working copy so already-recomputed sources feed later cells;
- *  boot-validator rejects derived-from-derived chains. A row that isn't a
+ *  from the working copy, so a cell declared after its source sees the
+ *  recomputed source. A row that isn't a
  *  plain object (already invalid, or not this field's shape) passes through
  *  untouched — validation downstream rejects it. The computed value is
- *  rounded to the target sub-field's declared precision (`schema`) before
+ *  rounded to the target sub-field's declared precision (`targets`) before
  *  it's written back, so a fractional product lands on a value the target
- *  type can actually represent. */
-export function withDerivedCells(row, derived, schema) {
+ *  type can actually represent. A cell whose `when` is false for the row is
+ *  not derived there: its row value is left as sent. */
+export function withDerivedCells(row, derived, targets) {
     if (!isPlainObject(row))
         return row;
     const copy = { ...row };
     for (const [cellName, def] of Object.entries(derived)) {
+        if (def.when !== undefined && !evalFieldCondition(def.when, row))
+            continue;
         const sourceValues = def.from.map((sourceField) => {
             const value = copy[sourceField];
             return typeof value === "number" ? value : undefined;
         });
-        const computed = computeDerivedCellValue(def.op, sourceValues);
+        const computed = def.op === "inRange"
+            ? computeInRangeCell(sourceValues, def.inside, def.outside)
+            : computeDerivedCellValue(def.op, sourceValues);
         if (computed === undefined) {
             // Always clear — keeping a client value would let callers spoof required
             // derived cells when sources are missing (server must stay authoritative).
             delete copy[cellName];
         }
+        else if (typeof computed === "string") {
+            copy[cellName] = computed;
+        }
         else {
-            const target = schema[cellName];
+            const target = targets[cellName];
             copy[cellName] = target === undefined ? computed : roundDerivedCellValue(computed, target);
         }
     }

package/dist/engine/entity-handlers.d.ts

@@ -1,4 +1,4 @@
-import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
+import { type EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
 import type { AccessRule, EscapeHatchDeclaration, QueryHandlerDef, WriteHandlerDef } from "@cosmicdrift/kumiko-types/handlers";
 import * as z from "zod";
 import { type EventStoreExecutor } from "../db/event-store-executor.ts";

package/dist/engine/entity-handlers.js

@@ -1,3 +1,4 @@
+import { isSqlDerivedField, } from "@cosmicdrift/kumiko-types/fields";
 import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
 import { listAggregatePayloadSchema, } from "@cosmicdrift/kumiko-types/list-aggregate-types";
 import * as z from "zod";
@@ -10,7 +11,7 @@ import { InternalError } from "../errors/index.js";
 import { isSystemIdentity } from "../pipeline/system-identity-switch.js";
 import { assertUnreachable } from "../utils/index.js";
 import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler.js";
-import { entityListRuntime } from "./entity-list-runtime-options.js";
+import { entityListRuntime, parentVisibilityFor } from "./entity-list-runtime-options.js";
 import { assertReason } from "./escape-hatch-reason.js";
 import { dropEmptyWriteOnlyValues } from "./field-access.js";
 import { instructionFieldNames } from "./instruction-fields.js";
@@ -289,7 +290,7 @@ export function defineEntityWriteHandler(name, entity, options) {
                 // they rely on to intentionally force a fresh event/ciphertext.
                 return executor.update(payload, event.user, db, {
                     streamTenantId,
-                    parentVisibility: { entities: ctx.registry.getAllEntities() },
+                    parentVisibility: parentVisibilityFor(ctx, event.user),
                     skipUnchanged: true,
                     preSave: runPreSave &&
                         ((changes, previous, isNew) => runPreSave(event.type, changes, previous, isNew)),
@@ -304,7 +305,7 @@ export function defineEntityWriteHandler(name, entity, options) {
                 const streamTenantId = await foreignRowTenantFor(event.user, payload.id, db, ctx);
                 return executor.delete(payload, event.user, db, {
                     streamTenantId,
-                    parentVisibility: { entities: ctx.registry.getAllEntities() },
+                    parentVisibility: parentVisibilityFor(ctx, event.user),
                 });
             };
             break;
@@ -316,7 +317,7 @@ export function defineEntityWriteHandler(name, entity, options) {
                 const streamTenantId = await foreignRowTenantFor(event.user, payload.id, db, ctx);
                 return executor.restore(payload, event.user, db, {
                     streamTenantId,
-                    parentVisibility: { entities: ctx.registry.getAllEntities() },
+                    parentVisibility: parentVisibilityFor(ctx, event.user),
                 });
             };
             break;
@@ -334,23 +335,21 @@ export function defineEntityWriteHandler(name, entity, options) {
         ...(excludedFields.length > 0 && { excludedFields }),
     };
 }
-// Append read-time derived-field values (EntityDefinition.derivedFields) to
-// each row, after the SQL fetch + reference eagerload — i.e. on the row shape
-// the view-model will see. The clock is the read instant; derive bodies must
-// read it from ctx.asOf, never their own Date/Temporal.Now. No-op (returns the
-// rows untouched) when the entity declares no derived fields.
-function augmentDerivedFields(rows, entity) {
+// Runs the JS `derive` fields on the row shape the view-model will see (after the SQL fetch,
+// reference eagerload and SQL derived values), so a JS derive may read a SQL derived value.
+// Clock comes from the handler's tz context, never Temporal.Now.
+function augmentDerivedFields(rows, entity, asOf) {
     const derived = entity.derivedFields;
     if (derived === undefined)
         return rows;
-    const entries = Object.entries(derived);
-    if (entries.length === 0)
+    const jsEntries = Object.entries(derived).flatMap(([fieldName, def]) => isSqlDerivedField(def) ? [] : [[fieldName, def.derive]]);
+    if (jsEntries.length === 0)
         return rows;
-    const ctx = { asOf: Temporal.Now.instant() };
+    const ctx = { asOf };
     return rows.map((row) => {
         const out = { ...row };
-        for (const [fieldName, def] of entries) {
-            out[fieldName] = def.derive(row, ctx);
+        for (const [fieldName, derive] of jsEntries) {
+            out[fieldName] = derive(row, ctx);
         }
         return out;
     });
@@ -409,7 +408,7 @@ export function defineEntityQueryHandler(name, entity, options) {
                 const enrichedRows = hasRefFields
                     ? await enrichWithReferences(result.rows, entity, resolveEntity, db, eagerLoadViewer)
                     : result.rows;
-                return { ...result, rows: augmentDerivedFields(enrichedRows, entity) };
+                return { ...result, rows: augmentDerivedFields(enrichedRows, entity, ctx.tz.now()) };
             };
             break;
         case "detail":
@@ -417,13 +416,13 @@ export function defineEntityQueryHandler(name, entity, options) {
             handler = async (query, ctx) => {
                 const db = dbFor(ctx);
                 const row = await executor.detail(query.payload, query.user, db, {
-                    parentVisibility: { entities: ctx.registry.getAllEntities() },
+                    parentVisibility: parentVisibilityFor(ctx, query.user),
                 }); // @cast-boundary engine-payload
                 if (row === null || !hasRefFields)
                     return row;
                 return enrichRowWithReferences(row, entity, (name) => ctx.registry.getEntity(name), db, {
                     user: query.user,
-                    parentVisibility: { entities: ctx.registry.getAllEntities() },
+                    parentVisibility: parentVisibilityFor(ctx, query.user),
                 });
             };
             break;

package/dist/engine/entity-list-runtime-options.d.ts

@@ -1,8 +1,12 @@
-import type { ListRuntimeOptions } from "@cosmicdrift/kumiko-types/event-store-executor-types";
+import type { AggregateKey } from "@cosmicdrift/kumiko-types/aggregate-types";
+import type { ListRuntimeOptions, ParentVisibilityOption } from "@cosmicdrift/kumiko-types/event-store-executor-types";
 import type { EagerLoadEntityResolver, EagerLoadViewer } from "../db/eagerload.ts";
+import type { TenantDb } from "../db/tenant-db.ts";
 import type { HandlerContext, SessionUser } from "./types/index.ts";
+export declare function parentVisibilityFor(ctx: HandlerContext, user: SessionUser): ParentVisibilityOption;
 export declare function entityListRuntime(ctx: HandlerContext, entityName: string, user: SessionUser): {
     readonly runtimeOptions: ListRuntimeOptions;
     readonly eagerLoadViewer: EagerLoadViewer;
     readonly resolveEntity: EagerLoadEntityResolver;
 };
+export declare function referenceGroupLabels(ctx: HandlerContext, user: SessionUser, sourceTableName: string, groupByField: string, keys: readonly AggregateKey[], db: TenantDb): Promise<ReadonlyMap<string, string>>;

package/dist/engine/entity-list-runtime-options.js

@@ -1,20 +1,119 @@
+import { collectEntityDetailAccess, collectEntityReadAccess } from "../api/entity-read-access.js";
+import { resolveTableName } from "../db/entity-table-meta.js";
+import { labelListAggregateGroups } from "../db/list-aggregate-labels.js";
+import { buildEntityTable } from "../db/table-builder.js";
+import { extractTableInfo } from "../db/table-info.js";
+import { hasAccess } from "./access.js";
+import { IMPLICIT_PROJECTION_SUFFIX } from "./registry-state.js";
+// The rules only change with the registry, so they are collected once, not per request.
+const readAccessByRegistry = new WeakMap();
+const detailAccessByRegistry = new WeakMap();
+function detailAccessOf(registry) {
+    let rules = detailAccessByRegistry.get(registry);
+    if (rules === undefined) {
+        rules = collectEntityDetailAccess(registry);
+        detailAccessByRegistry.set(registry, rules);
+    }
+    return rules;
+}
+function readAccessOf(registry) {
+    let rules = readAccessByRegistry.get(registry);
+    if (rules === undefined) {
+        rules = collectEntityReadAccess(registry);
+        readAccessByRegistry.set(registry, rules);
+    }
+    return rules;
+}
+// An entity with a backingTable is read from that table; the implicit projection holds it.
+function readTableOf(ctx, entityName, entity) {
+    const implicit = ctx.registry
+        .getProjectionsForSource(entityName)
+        .find((projection) => projection.name.endsWith(`:projection:${entityName}${IMPLICIT_PROJECTION_SUFFIX}`));
+    return implicit?.table ?? buildEntityTable(entityName, entity);
+}
+// The join-row and read gates resolve hosts and file owners against the registry, which only
+// exists at request time; the handler check is the one live signals use too.
+export function parentVisibilityFor(ctx, user) {
+    const detailRules = detailAccessOf(ctx.registry);
+    return {
+        entities: ctx.registry.getAllEntities(),
+        canReadEntity: (name) => {
+            const rule = detailRules.get(name);
+            return rule !== undefined && hasAccess(user, rule);
+        },
+        resolveTable: (name) => {
+            const entity = ctx.registry.getEntity(name);
+            if (entity === undefined)
+                throw new Error(`parentVisibility: unknown entity "${name}"`);
+            return readTableOf(ctx, name, entity);
+        },
+    };
+}
 // Registry access only exists at request time, so the searchable/sortable-reference
 // caches, the entity resolver and the join-row read gate travel through the
 // runtime-override extension point of the executor verbs.
 export function entityListRuntime(ctx, entityName, user) {
-    const parentVisibility = { entities: ctx.registry.getAllEntities() };
+    const parentVisibility = parentVisibilityFor(ctx, user);
     const resolveEntity = (name) => ctx.registry.getEntity(name);
+    const resolveTable = (name) => {
+        const entity = ctx.registry.getEntity(name);
+        if (entity === undefined)
+            throw new Error(`entityListRuntime: unknown entity "${name}"`);
+        return readTableOf(ctx, name, entity);
+    };
+    const readRules = readAccessOf(ctx.registry);
     return {
         runtimeOptions: {
             ...(ctx.services.searchAdapter !== undefined && {
                 searchAdapter: ctx.services.searchAdapter,
             }),
             ...(ctx.includeDeleted === true && { includeDeleted: true }),
-            referenceSearch: { fields: ctx.registry.getSearchableReferences(entityName), resolveEntity },
-            referenceSort: { fields: ctx.registry.getSortableReferences(entityName), resolveEntity },
+            referenceSearch: {
+                fields: ctx.registry.getSearchableReferences(entityName),
+                resolveEntity,
+                resolveTable,
+            },
+            referenceSort: {
+                fields: ctx.registry.getSortableReferences(entityName),
+                resolveEntity,
+                resolveTable,
+            },
             parentVisibility,
+            derivedSql: {
+                resolveEntity,
+                resolveTable,
+                canReadEntity: (name) => (readRules.get(name) ?? []).some((rule) => hasAccess(user, rule)),
+                today: ctx.tz.today(ctx.tz.tenant).toString(),
+                now: ctx.tz.now().toString(),
+            },
         },
-        eagerLoadViewer: { user, parentVisibility },
+        eagerLoadViewer: { user, parentVisibility, resolveTable },
         resolveEntity,
     };
 }
+// An entity with a backingTable reads and writes that table, whose name the entity's own
+// `table` does not say; the implicit projection holds the table the executor really uses.
+function physicalReadTableName(ctx, entityName, entity) {
+    const implicit = ctx.registry
+        .getProjectionsForSource(entityName)
+        .find((projection) => projection.name.endsWith(`:projection:${entityName}${IMPLICIT_PROJECTION_SUFFIX}`));
+    return implicit !== undefined
+        ? extractTableInfo(implicit.table).name
+        : resolveTableName(entityName, entity, undefined);
+}
+// Resolved through the viewer's read access, like list-aggregate labels; non-entity sources yield none.
+export async function referenceGroupLabels(ctx, user, sourceTableName, groupByField, keys, db) {
+    const labels = new Map();
+    const owner = [...ctx.registry.getAllEntities()].find(([entityName, entity]) => physicalReadTableName(ctx, entityName, entity) === sourceTableName);
+    if (owner === undefined || keys.length === 0)
+        return labels;
+    const [entityName, entity] = owner;
+    const { eagerLoadViewer, resolveEntity } = entityListRuntime(ctx, entityName, user);
+    const labeled = await labelListAggregateGroups({ groups: keys.map((key) => ({ key, count: 0, measures: [] })) }, groupByField, { entity, resolveEntity, viewer: eagerLoadViewer }, db);
+    for (const group of labeled.groups) {
+        if (group.key !== null && group.label != null && group.label !== "") {
+            labels.set(String(group.key), group.label);
+        }
+    }
+    return labels;
+}

package/dist/engine/factories.d.ts

@@ -17,11 +17,9 @@ export declare function createTextField<R extends true | false = false>(override
  * (for example, `1_000_000 = 1 MB`).
  */
 /**
- * Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`).
- * The value is derived per row from the stored columns + the clock at query
- * time, never persisted. Display only — server-side sort/filter/search don't
- * apply and there's no client-side sort path (see DerivedFieldDef). `derive`
- * must take its clock from `ctx.asOf`, never `Temporal.Now`/`Date`.
+ * Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`), never persisted.
+ * `derive` (display only, clock from `ctx.asOf`) or `sql` (computed in the list SELECT, optionally
+ * `sortable`) — see DerivedFieldDef.
  */
 export declare function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef;
 export declare function createLongTextField<R extends true | false = false>(overrides: Partial<Omit<LongTextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsLongText & {
@@ -194,6 +192,8 @@ export declare function createEntity<const F, const T extends EntityTenancy = "t
     readonly access?: EntityDefinition["access"];
     /** Join-row carrier reference — see EntityDefinition.parentRef. */
     readonly parentRef?: EntityDefinition["parentRef"];
+    /** See EntityDefinition.readGate. */
+    readonly readGate?: EntityDefinition["readGate"];
     readonly retention?: RetentionDef;
     readonly derivedFields?: EntityDefinition["derivedFields"];
     readonly tenancy?: T;

package/dist/engine/factories.js

@@ -137,11 +137,9 @@ export function createTextField(overrides) {
  * (for example, `1_000_000 = 1 MB`).
  */
 /**
- * Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`).
- * The value is derived per row from the stored columns + the clock at query
- * time, never persisted. Display only — server-side sort/filter/search don't
- * apply and there's no client-side sort path (see DerivedFieldDef). `derive`
- * must take its clock from `ctx.asOf`, never `Temporal.Now`/`Date`.
+ * Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`), never persisted.
+ * `derive` (display only, clock from `ctx.asOf`) or `sql` (computed in the list SELECT, optionally
+ * `sortable`) — see DerivedFieldDef.
  */
 export function createDerivedField(spec) {
     return { ...spec };

package/dist/engine/field-access.d.ts

@@ -1,4 +1,5 @@
 import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
+import { type OwnershipMap } from "./ownership.ts";
 import type { SessionUser } from "./types/index.ts";
 export declare function maskWriteOnlyFields<T extends Readonly<Record<string, unknown>>>(entity: EntityDefinition, row: T): T;
 export declare function dropEmptyWriteOnlyValues<T extends Readonly<Record<string, unknown>>>(entity: EntityDefinition, values: T): T;
@@ -6,3 +7,4 @@ export declare function userMayReadFieldInBulk(entity: EntityDefinition, fieldNa
 export declare function filterReadFields(entity: EntityDefinition, data: Readonly<Record<string, unknown>>, user: SessionUser): Record<string, unknown>;
 export declare function checkWriteFieldRoles(entity: EntityDefinition, changes: Readonly<Record<string, unknown>>, user: SessionUser): string | null;
 export declare function checkWriteFieldOwnership(entity: EntityDefinition, submittedChanges: Readonly<Record<string, unknown>>, user: SessionUser, oldRow?: Readonly<Record<string, unknown>>, rowContext?: Readonly<Record<string, unknown>>): string | null;
+export declare function userHasWriteRole(user: Pick<SessionUser, "roles">, accessMap: OwnershipMap): boolean;