@cosmicdrift/kumiko-framework 0.399.0 → 0.401.0

package/agents/examples/relations.md

@@ -217,7 +217,12 @@ describe("cascade: deleting member removes tasks", () => {
 
 ```ts
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
-import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEntity,
+  createReferenceField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
 
 export const teamEntity = createEntity({
   table: "read_sample_teams",
@@ -230,7 +235,12 @@ export const memberEntity = createEntity({
   table: "read_sample_members",
   fields: {
     name: createTextField({ personal: { of: "id" }, find: "none", required: true }),
-    teamId: createTextField({ personal: false, reason: "is_system_identifier", required: true }),
+    teamId: createReferenceField({
+      entity: "team",
+      personal: false,
+      reason: "is_system_identifier",
+      required: true,
+    }),
     role: createTextField({ personal: false, reason: "is_business_data" }),
   },
 });
@@ -239,7 +249,7 @@ export const taskEntity = createEntity({
   table: "read_sample_member_tasks",
   fields: {
     title: createTextField({ personal: false, reason: "is_business_data", required: true }),
-    memberId: createTextField({ personal: "ref", required: true }),
+    memberId: createReferenceField({ entity: "member", personal: "ref", required: true }),
   },
 });
 

package/agents/examples.md

@@ -27,7 +27,9 @@
 | `custom-handlers` | Beyond CRUD — when your domain refuses to fit a table. | `examples/custom-handlers.md` |
 | `dashboard-stats` | Key figures on a dashboard: stat panels backed by one counting query. | `examples/dashboard-stats.md` |
 | `delivery-notifications` | Delivery flows plus notifications. Package tracking, minus the tracking. | `examples/delivery-notifications.md` |
+| `derived-fields-sql` | SQL derived fields on a list: coalesce, related count with a where, related first (text and money), sortable columns and a defaultSort on a derived value. | `examples/derived-fields-sql.md` |
 | `designer-demo` | Kumiko sample feature — scaffolded by `bun kumiko create` | `examples/designer-demo.md` |
+| `documents` | A document register on top of existing records: captured files, expiry dates and per-record visibility. | `examples/documents.md` |
 | `e2e-generator` | generateE2ESpec + withBootValidatorFixture — Registry → JSON-Specs für externen Playwright-Worker. Zeigt die 4 Test-Kinds, Feldtyp→Interaktion-Mapping und welche Feldtypen heute noch nicht generisch unterstützt sind. | `examples/e2e-generator.md` |
 | `embedded` | Embedded fields on entities. Structured JSON without the JSON part. | `examples/embedded.md` |
 | `embedded-entity-form` | RenderEdit hosted in a Drawer, no screen or route — externally-sourced prefill, controlled mode, and a custom write handler instead of the built-in CRUD create. | `examples/embedded-entity-form.md` |
@@ -43,6 +45,7 @@
 | `i18n` | Feature-scoped translations. 'Hallo' and 'Hello' in the same app. | `examples/i18n.md` |
 | `idempotency` | Same request, same result. Dedupes on request ID. | `examples/idempotency.md` |
 | `inbound-mail-triage` | Inbound-mail consumer pattern: inbound-mail-foundation + in-memory provider, a worker-lane triage job attached to the ingest handler, verified end-to-end through createAllInOneEntrypoint. | `examples/inbound-mail-triage.md` |
+| `inspection-checklist` | Embedded list as a phone inspection checklist: conditional fields, derived pass/fail, photos per row. | `examples/inspection-checklist.md` |
 | `lane-routing` | runIn lane-routing: r.job pinned to api/worker deploy-lanes, event-chain via ctx.events.append, verified end-to-end through createAllInOneEntrypoint. | `examples/lane-routing.md` |
 | `ledger-banking` | Bank accounts + transfers on the ledger primitive — balances are pure queries, never stored. | `examples/ledger-banking.md` |
 | `ledger-invoicing` | Accrual invoicing on the ledger primitive — revenue at invoice time, VAT as a liability, receivable cleared on payment. | `examples/ledger-invoicing.md` |

package/agents/features-index.md

@@ -62,6 +62,8 @@ One entry per feature a package ships: purpose, import of its factory, required
   `import { createDocumentDesignerFeature } from "@cosmicdrift/kumiko-document-designer"`; requires `template-resolver`
 - `document-ingest-foundation`: Shared PDF/Scan/Image → normalized-text ingest primitive.
   `import { createDocumentIngestFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/document-ingest-foundation"`; requires `config`, `tenant-lifecycle`
+- `documents`: Filed documents with title, category, issue and expiry date and one file, shown on the records they are linked to.
+  `import { createDocumentsFeature } from "@cosmicdrift/kumiko-bundled-features/documents"`; requires `files`
 - `feature-toggles`: Persists per-feature enabled/disabled state in the `store_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying.
   `import { createFeatureTogglesFeature } from "@cosmicdrift/kumiko-bundled-features/feature-toggles"`
 - `file-derivatives`: Declares the `derivativeRenderer` extension point.

package/agents/features.md

@@ -253,6 +253,14 @@ Config keys:
 | `max-pages-per-file` | number | tenant | `50` |
 | `ocr-language` | text | tenant | `deu+eng` |
 
+## documents
+
+Filed documents with title, category, issue and expiry date and one file, shown on the records they are linked to. A document is visible only through a linked record the viewer can read, and only while the record that owns its file is readable too, so linking never widens access to the file. Documents arrive through capture rules (a file saved into a configured field) or through the system-only import for migrations, which keeps the caller's id, refuses an id another record already uses, and stamps createdAt with the import time (issuedAt carries the business date; the event store does not backdate); users link, unlink, edit and delete them. Read a record's documents with for-record, count expired and expiring ones with expiry-overview, list them with an expiry state and an expiring filter with overview (the documents list screen), and add the documents tab to a record screen with documentsTab().
+
+Category: data
+
+Requires: `files`
+
 ## feature-toggles
 
 Persists per-feature enabled/disabled state in the `store_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: "shared"` syncs the snapshot across instances whenever a `toggle-set` event is appended.

package/dist/api/entity-read-access.d.ts

@@ -2,5 +2,7 @@ import type { AccessRule } from "@cosmicdrift/kumiko-types/handlers";
 import type { OwnershipMap } from "@cosmicdrift/kumiko-types/ownership";
 import type { Registry } from "../engine/types/index.ts";
 export declare function assertNoAggregateTypeKeyCollisions(registry: Registry): void;
+export declare function collectEntityDetailQueries(registry: Registry): ReadonlyMap<string, string>;
+export declare function collectEntityDetailAccess(registry: Registry): ReadonlyMap<string, AccessRule>;
 export declare function collectEntityReadAccess(registry: Registry): ReadonlyMap<string, readonly AccessRule[]>;
 export declare function collectEntityRowReadMaps(registry: Registry): ReadonlyMap<string, OwnershipMap>;

package/dist/api/entity-read-access.js

@@ -14,6 +14,47 @@ export function assertNoAggregateTypeKeyCollisions(registry) {
         }
     }
 }
+// Only the "<entity>:detail" handler counts: other "<entity>:...:detail"
+// queries map to the same entity but may return a different shape or scope.
+// Entity names are globally unique and only the owning feature maps handlers
+// to its entity, so at most one QN matches per entity.
+function isEntityDetailQuery(qn, entityName) {
+    return qn.endsWith(`:query:${toKebab(entityName)}:detail`);
+}
+export function collectEntityDetailQueries(registry) {
+    const detailQueryByEntity = new Map();
+    for (const qn of registry.getAllQueryHandlers().keys()) {
+        const entityName = registry.getHandlerEntity(qn);
+        if (entityName !== undefined && isEntityDetailQuery(qn, entityName)) {
+            detailQueryByEntity.set(entityName, qn);
+        }
+    }
+    for (const projection of registry.getAllProjections().values()) {
+        const entityName = projection.source;
+        if (typeof entityName !== "string")
+            continue;
+        const owner = registry.getReadModelEntityOwner(entityName);
+        if (owner === undefined)
+            continue;
+        const qn = `${owner}:query:${toKebab(entityName)}:detail`;
+        if (registry.getAllQueryHandlers().has(qn))
+            detailQueryByEntity.set(entityName, qn);
+    }
+    return detailQueryByEntity;
+}
+// The access rule of each entity's own detail query. The file route and the read gate both ask
+// "may this viewer open the record?" through this one rule, so a liveEntities or openToAll query
+// that merely names an entity never widens what a gated row exposes.
+export function collectEntityDetailAccess(registry) {
+    const handlers = registry.getAllQueryHandlers();
+    const accessByEntity = new Map();
+    for (const [entityName, qn] of collectEntityDetailQueries(registry)) {
+        const handler = handlers.get(qn);
+        if (handler !== undefined)
+            accessByEntity.set(entityName, handler.access);
+    }
+    return accessByEntity;
+}
 // Access rules of the query handlers that let a role read an entity (the
 // handler's own entity or one it declares via liveEntities). A live signal
 // carries the id of every row of the entity, so a signed-in connection gets it
@@ -45,8 +86,11 @@ export function collectEntityRowReadMaps(registry) {
     assertNoAggregateTypeKeyCollisions(registry);
     const mapsByEntity = new Map();
     for (const [entityName, entity] of registry.getAllEntities()) {
-        const readMap = entity.access?.read;
-        if (readMap === undefined || Object.keys(readMap).length === 0)
+        // A read gate narrows rows for every role, so no role reads every row: signals stay anonymous.
+        const readMap = entity.readGate !== undefined ? {} : entity.access?.read;
+        if (readMap === undefined)
+            continue;
+        if (entity.readGate === undefined && Object.keys(readMap).length === 0)
             continue;
         for (const aggregateType of new Set([entityName, toKebab(entityName)])) {
             mapsByEntity.set(aggregateType, readMap);

package/dist/api/server-boot-checks.js

@@ -1,5 +1,5 @@
 import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names.js";
-import { isFileField } from "../engine/field-helpers.js";
+import { holdsFileRefs } from "../files/file-field-slots.js";
 import { SHARED_INSTANCE_SENTINEL } from "../pipeline/event-consumer-state.js";
 import { generateId } from "../utils/index.js";
 // A payload-bucket handler without a resolver would answer every call with a
@@ -125,7 +125,7 @@ function registryDeclaresFileFields(registry) {
     for (const feature of registry.features.values()) {
         for (const entity of Object.values(feature.entities ?? {})) {
             for (const field of Object.values(entity.fields)) {
-                if (isFileField(field))
+                if (holdsFileRefs(field))
                     return true;
             }
         }

package/dist/api/server-routes.js

@@ -2,6 +2,7 @@ import { createProjectingTenantDb } from "../db/tenant-db.js";
 import { buildAppSchema } from "../engine/build-app-schema.js";
 import { projectAppSchemaForRoles } from "../engine/project-app-schema-for-roles.js";
 import { resolveDisabledFeatureNames, stripDisabledFeaturesFromAppSchema, } from "../engine/strip-disabled-features-from-app-schema.js";
+import { stripUnreadableRelatedLists } from "../engine/strip-unreadable-related-lists.js";
 import { createAnonymousUser, isAnonymousSessionUser } from "../engine/system-user.js";
 import { createFileRoutes, readFilesRouteOptions } from "../files/file-routes.js";
 import { createRecordReadCheck } from "../files/record-read-check.js";
@@ -109,7 +110,8 @@ export function mountSchemaRoute(app, options) {
                     searchAdapterMissing: !options.context.searchAdapter,
                 });
             }
-            const projected = projectAppSchemaForRoles(stripDisabledFeaturesFromAppSchema(fullSchema, options.registry, disabledFeatureNames), user?.roles ?? []);
+            const roles = user?.roles ?? [];
+            const projected = stripUnreadableRelatedLists(projectAppSchemaForRoles(stripDisabledFeaturesFromAppSchema(fullSchema, options.registry, disabledFeatureNames), roles), roles, (queryQn) => options.registry.getQueryHandler(queryQn)?.access);
             const json = JSON.stringify(projected);
             cached = { json, etag: computeStrongEtag(json) };
             projectedSchemaCache.set(roleKey, cached);

package/dist/config/index.d.ts

@@ -20,7 +20,7 @@ export type AppPorts = {
     readonly infra?: AppInfraPorts;
 };
 /** The boot-validator options an app owns; `env` and the cipher are injected by the runners. */
-export type AppValidateBootOptions = Pick<ValidateBootOptions, "navAllowlist" | "navAllowlistExempt" | "requiredLocales" | "warnOnUniqueAccessRoles">;
+export type AppValidateBootOptions = Pick<ValidateBootOptions, "navAllowlist" | "navAllowlistExempt" | "requiredLocales" | "requireFieldValueTranslations" | "warnOnUniqueAccessRoles">;
 export type AppConfig = {
     /** Features mounted in every environment: dev, tests, prod. */
     readonly features: readonly FeatureDefinition[];

package/dist/db/derived-field-sql.d.ts

@@ -0,0 +1,23 @@
+import type { ListRuntimeOptions } from "@cosmicdrift/kumiko-types/event-store-executor-types";
+import { type EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
+import type { SessionUser } from "../engine/types/index.ts";
+import type { Table } from "./event-store-executor-context.ts";
+import type { FieldReadClause } from "./event-store-executor-read-where.ts";
+import type { TenantDb } from "./tenant-db.ts";
+type SqlBuilder = (params: unknown[]) => string;
+export type DerivedSelect = {
+    readonly projections: (params: unknown[]) => string;
+    readonly sortExpr: (name: string) => SqlBuilder | undefined;
+    readonly takeValues: (rawRows: readonly Record<string, unknown>[]) => readonly Record<string, unknown>[];
+};
+type DerivedSelectInput = {
+    readonly entity: EntityDefinition;
+    readonly table: Table;
+    readonly tableName: string;
+    readonly fieldReadClause: FieldReadClause;
+    readonly user: SessionUser;
+    readonly db: TenantDb;
+    readonly runtime: ListRuntimeOptions | undefined;
+};
+export declare function buildDerivedSelect(input: DerivedSelectInput): DerivedSelect | undefined;
+export {};

package/dist/db/derived-field-sql.js

@@ -0,0 +1,115 @@
+import { isSqlDerivedField, } from "@cosmicdrift/kumiko-types/fields";
+import { parseRefTargetEntityName } from "../engine/parse-ref-target.js";
+import { buildRelatedSubquery } from "./derived-related-sql.js";
+import { coerceDriverValueOfPgType } from "./driver-row-coercion.js";
+import { holdsCiphertextOrSecret } from "./entity-field-encryption.js";
+import { FRAMEWORK_DEFAULT_CURRENCY, readMoney } from "./money.js";
+import { physicalColumnName } from "./table-builder.js";
+const DERIVED_ALIAS_PREFIX = "__kumiko_derived_";
+// Driver value coercion by the pg type a stored column of this value type would have.
+const PG_TYPE_OF_VALUE_TYPE = {
+    text: "text",
+    number: "integer",
+    decimal: "numeric",
+    boolean: "boolean",
+    date: "date",
+    timestamp: "timestamptz",
+    money: "bigint",
+};
+function buildCoalesceExpression(fields, input) {
+    const { entity, table, tableName, fieldReadClause } = input;
+    const allReadable = fields.every((f) => Object.hasOwn(table, f) &&
+        fieldReadClause(f).kind === "pass" &&
+        !holdsCiphertextOrSecret(entity, f));
+    if (!allReadable)
+        return undefined;
+    const columns = fields.map((f) => `"${tableName}"."${physicalColumnName(table, f)}"`);
+    const sql = `COALESCE(${columns.join(", ")})`;
+    return () => sql;
+}
+function relatedDefaultCurrency(spec, input) {
+    const related = spec.kind === "related"
+        ? input.runtime?.derivedSql?.resolveEntity(parseRefTargetEntityName(spec.entity))
+        : undefined;
+    return related?.defaultCurrency ?? FRAMEWORK_DEFAULT_CURRENCY;
+}
+function buildExpression(spec, input, currency = false) {
+    if (spec.kind === "coalesce")
+        return buildCoalesceExpression(spec.fields, input);
+    const runtime = input.runtime?.derivedSql;
+    if (runtime === undefined)
+        return undefined;
+    const outer = {
+        entity: input.entity,
+        table: input.table,
+        tableName: input.tableName,
+        isFieldReadable: (field) => input.fieldReadClause(field).kind === "pass",
+    };
+    return buildRelatedSubquery({
+        spec,
+        outer,
+        user: input.user,
+        db: input.db,
+        runtime,
+        parentVisibility: input.runtime?.parentVisibility,
+        currency,
+    });
+}
+export function buildDerivedSelect(input) {
+    if (input.runtime?.derivedSql === undefined)
+        return undefined;
+    const plans = [];
+    for (const [name, def] of Object.entries(input.entity.derivedFields ?? {})) {
+        if (!isSqlDerivedField(def))
+            continue;
+        const alias = `${DERIVED_ALIAS_PREFIX}${plans.length}`;
+        plans.push({
+            name,
+            alias,
+            valueType: def.valueType,
+            sortable: def.sortable === true,
+            expression: buildExpression(def.sql, input),
+            currency: def.valueType === "money"
+                ? {
+                    alias: `${alias}_currency`,
+                    expression: buildExpression(def.sql, input, true),
+                    fallback: relatedDefaultCurrency(def.sql, input),
+                }
+                : undefined,
+        });
+    }
+    if (plans.length === 0)
+        return undefined;
+    return {
+        projections: (params) => plans
+            .flatMap((plan) => [
+            { alias: plan.alias, expression: plan.expression },
+            ...(plan.currency === undefined ? [] : [plan.currency]),
+        ])
+            .map(({ alias, expression }) => `, ${expression?.(params) ?? "NULL"} AS "${alias}"`)
+            .join(""),
+        sortExpr: (name) => {
+            const plan = plans.find((p) => p.name === name);
+            return plan?.sortable === true ? plan.expression : undefined;
+        },
+        // Stripped before row coercion and the entity cache: the values depend on the viewer.
+        takeValues: (rawRows) => rawRows.map((raw) => {
+            const values = {};
+            for (const plan of plans) {
+                if (plan.currency !== undefined) {
+                    const amount = raw[plan.alias];
+                    // A stored money field without an amount has no key on the row; match that.
+                    if (amount !== null && amount !== undefined) {
+                        values[plan.name] = readMoney(plan.name, amount, raw[plan.currency.alias], plan.currency.fallback);
+                    }
+                    delete raw[plan.alias];
+                    delete raw[plan.currency.alias];
+                    continue;
+                }
+                values[plan.name] = coerceDriverValueOfPgType(raw[plan.alias], PG_TYPE_OF_VALUE_TYPE[plan.valueType], plan.alias);
+                delete raw[plan.alias];
+            }
+            return values;
+        }),
+    };
+}

package/dist/db/derived-related-sql.d.ts

@@ -0,0 +1,31 @@
+import type { DerivedSqlSpec, EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
+import type { SessionUser } from "../engine/types/index.ts";
+import type { Table } from "./event-store-executor-context.ts";
+import type { ParentVisibilityOption } from "./parent-ref-clause.ts";
+import type { TenantDb } from "./tenant-db.ts";
+export type RelatedDerivedSpec = Extract<DerivedSqlSpec, {
+    readonly kind: "related";
+}>;
+export type DerivedSqlRuntime = {
+    readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
+    readonly resolveTable: (entityName: string) => Table;
+    readonly canReadEntity: (entityName: string) => boolean;
+    readonly today: string;
+    readonly now: string;
+};
+export type OuterRow = {
+    readonly entity: EntityDefinition;
+    readonly table: Table;
+    readonly tableName: string;
+    readonly isFieldReadable: (field: string) => boolean;
+};
+export declare function buildRelatedSubquery(input: {
+    readonly spec: RelatedDerivedSpec;
+    readonly outer: OuterRow;
+    readonly user: SessionUser;
+    readonly db: TenantDb;
+    readonly runtime: DerivedSqlRuntime;
+    readonly parentVisibility: ParentVisibilityOption | undefined;
+    /** Select the measured money field's currency column instead of its amount. */
+    readonly currency?: boolean;
+}): ((params: unknown[]) => string) | undefined;

package/dist/db/derived-related-sql.js

@@ -0,0 +1,137 @@
+import { buildOwnershipClause, normalizeAccessEntry } from "../engine/ownership.js";
+import { parseRefTargetEntityName } from "../engine/parse-ref-target.js";
+import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
+import { holdsCiphertextOrSecret } from "./entity-field-encryption.js";
+import { bindPlaceholders, bindShiftedClause } from "./event-store-executor-read-filter.js";
+import { isSoftDeletedTargetHidden } from "./event-store-executor-read-search.js";
+import { buildReferenceSortExpr } from "./event-store-executor-read-sort.js";
+import { resolveReadOwnership } from "./read-ownership.js";
+import { physicalColumnName } from "./table-builder.js";
+import { extractTableInfo } from "./table-info.js";
+import { schemaTableName } from "./table-introspection.js";
+// Own alias for the related table: a where-rule qualifies columns with the table name it is
+// given, and the physical name could bind to an outer row of the same table (self-relation).
+const RELATED_ALIAS = "__kumiko_rel";
+const COMPARISON_SQL = { eq: "=", ne: "<>", lt: "<", gt: ">", lte: "<=", gte: ">=" };
+function conditionFields(condition) {
+    return "activeOn" in condition
+        ? [condition.activeOn.from, condition.activeOn.to]
+        : [condition.field];
+}
+function measureFields(measure) {
+    if (measure.kind === "count")
+        return [];
+    return measure.kind === "first" ? [measure.field, measure.orderBy] : [measure.field];
+}
+function usedRelatedFields(spec) {
+    return [
+        spec.on.field,
+        ...measureFields(spec.measure),
+        ...(spec.where ?? []).flatMap(conditionFields),
+    ];
+}
+function isRelatedFieldReadable(entity, table, user, field) {
+    if (!Object.hasOwn(table, field) || holdsCiphertextOrSecret(entity, field))
+        return false;
+    const access = normalizeAccessEntry(entity.fields[field]?.access?.read);
+    return buildOwnershipClause(user, access, table, 1, RELATED_ALIAS).kind === "pass";
+}
+function isPlaceholderValue(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function conditionSql(condition, column, params, runtime) {
+    if ("activeOn" in condition) {
+        params.push(runtime.today);
+        const today = `$${params.length}`;
+        const from = column(condition.activeOn.from);
+        const to = column(condition.activeOn.to);
+        return `(${from} <= ${today} AND (${to} IS NULL OR ${to} >= ${today}))`;
+    }
+    const col = column(condition.field);
+    const { value } = condition;
+    if (condition.op === "in") {
+        return Array.isArray(value) && value.length > 0
+            ? `${col} IN (${bindPlaceholders(params, value)})`
+            : "FALSE";
+    }
+    if (value === null) {
+        if (condition.op === "eq")
+            return `${col} IS NULL`;
+        return condition.op === "ne" ? `${col} IS NOT NULL` : "FALSE";
+    }
+    params.push(isPlaceholderValue(value) ? (value.today ? runtime.today : runtime.now) : value);
+    return `${col} ${COMPARISON_SQL[condition.op]} $${params.length}`;
+}
+// Correlated scalar subquery per row, like the reference-label sort: one result row per entity
+// row, the read model untouched. undefined means "this viewer cannot see the value": the field
+// projects NULL and is not sortable, so an order never leaks what the viewer is not allowed to read.
+export function buildRelatedSubquery(input) {
+    const { spec, outer, user, db, runtime } = input;
+    const relatedName = parseRefTargetEntityName(spec.entity);
+    const related = runtime.resolveEntity(relatedName);
+    if (related === undefined)
+        return undefined;
+    if (!runtime.canReadEntity(relatedName))
+        return undefined;
+    const relatedTable = runtime.resolveTable(relatedName);
+    const relatedTableName = String(schemaTableName(relatedTable));
+    const outerField = spec.on.outer ?? "id";
+    const fieldsReadable = usedRelatedFields(spec).every((f) => isRelatedFieldReadable(related, relatedTable, user, f)) &&
+        Object.hasOwn(outer.table, outerField) &&
+        outer.isFieldReadable(outerField);
+    if (!fieldsReadable)
+        return undefined;
+    const ownership = resolveReadOwnership({ entity: related, table: relatedTable }, RELATED_ALIAS, user, db, input.parentVisibility, { includeDeleted: false, narrowTypes: undefined });
+    if (ownership.kind === "empty")
+        return undefined;
+    const column = (field) => `"${RELATED_ALIAS}"."${physicalColumnName(relatedTable, field)}"`;
+    const selectSql = relatedSelect(spec.measure, column, related, input);
+    if (selectSql === undefined)
+        return undefined;
+    const joinColumn = physicalColumnName(relatedTable, spec.on.field);
+    const outerColumn = physicalColumnName(outer.table, outerField);
+    const joinTypesDiffer = extractTableInfo(relatedTable).pgTypeOf(joinColumn) !==
+        extractTableInfo(outer.table).pgTypeOf(outerColumn);
+    const joinSql = joinTypesDiffer
+        ? `${column(spec.on.field)}::text = "${outer.tableName}"."${outerColumn}"::text`
+        : `${column(spec.on.field)} = "${outer.tableName}"."${outerColumn}"`;
+    const tenantScoped = relatedTable["tenantId"] !== undefined && db.mode === "tenant";
+    const softDeleteSql = isSoftDeletedTargetHidden(related, relatedTable)
+        ? `${column("isDeleted")} = FALSE`
+        : undefined;
+    return (params) => {
+        const clauses = [joinSql];
+        if (tenantScoped && db.mode === "tenant") {
+            params.push(db.tenantId, SYSTEM_TENANT_ID);
+            clauses.push(`${column("tenantId")} IN ($${params.length - 1}, $${params.length})`);
+        }
+        if (ownership.kind === "sql")
+            clauses.push(bindShiftedClause(params, ownership));
+        if (softDeleteSql !== undefined)
+            clauses.push(softDeleteSql);
+        for (const condition of spec.where ?? []) {
+            clauses.push(conditionSql(condition, column, params, runtime));
+        }
+        const order = spec.measure.kind === "first"
+            ? ` ORDER BY ${column(spec.measure.orderBy)} ${spec.measure.direction === "desc" ? "DESC" : "ASC"} NULLS LAST, ${column("id")} ASC LIMIT 1`
+            : "";
+        return `(SELECT ${selectSql(params)} FROM "${relatedTableName}" AS "${RELATED_ALIAS}" WHERE ${clauses.join(" AND ")}${order})`;
+    };
+}
+function relatedSelect(measure, column, related, input) {
+    if (measure.kind === "count")
+        return () => "COUNT(*)::int";
+    if (measure.kind === "countDistinct")
+        return () => `COUNT(DISTINCT ${column(measure.field)})::int`;
+    if (measure.label !== true) {
+        const selected = input.currency === true ? `${measure.field}Currency` : measure.field;
+        return () => column(selected);
+    }
+    const def = related.fields[measure.field];
+    if (def?.type !== "reference" || def.labelField === undefined)
+        return undefined;
+    const labelTarget = parseRefTargetEntityName(def.entity);
+    if (!input.runtime.canReadEntity(labelTarget))
+        return undefined;
+    return buildReferenceSortExpr(column(measure.field), { targetEntityName: labelTarget, labelField: def.labelField }, input.runtime.resolveEntity, input.db, input.user, input.runtime.resolveTable, input.parentVisibility);
+}

package/dist/db/driver-row-coercion.d.ts

@@ -1,2 +1,3 @@
 import type { TableInfo } from "./table-info.ts";
+export declare function coerceDriverValueOfPgType(value: unknown, pgType: string, column: string): unknown;
 export declare function coerceDriverRow(row: Record<string, unknown>, info: TableInfo): Record<string, unknown>;

package/dist/db/driver-row-coercion.js

@@ -162,6 +162,19 @@ function driverValueCoercerFor(pgType) {
         return coercer;
     return pgType.startsWith("numeric") ? numberUnlessNaN : undefined;
 }
+const STANDALONE_VALUE_INFO = {
+    name: "",
+    columnOf: (field) => field,
+    pgTypeOf: () => undefined,
+    bigintJsModeOf: () => undefined,
+    fieldOf: (column) => column,
+    hasColumn: () => false,
+};
+// For computed values that have no table column: coerces by pg type exactly as a stored column of that type.
+export function coerceDriverValueOfPgType(value, pgType, column) {
+    const coercer = driverValueCoercerFor(pgType);
+    return coercer ? coercer(value, column, STANDALONE_VALUE_INFO) : value;
+}
 export function coerceDriverRow(row, info) {
     const out = {};
     let changed = false;

package/dist/db/eagerload.d.ts

@@ -1,6 +1,7 @@
 import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
 import type { SessionUser } from "../engine/types/index.ts";
-import { type ParentVisibilityOption } from "./parent-ref-clause.ts";
+import type { ParentVisibilityOption } from "./parent-ref-clause.ts";
+import { buildEntityTable } from "./table-builder.ts";
 import type { TenantDb } from "./tenant-db.ts";
 export type EagerLoadEntityResolver = (entityName: string) => EntityDefinition | undefined;
 export type EagerloadedRow<T extends Record<string, unknown> = Record<string, unknown>> = T & {
@@ -15,6 +16,7 @@ export declare function collectReferenceFields(entity: EntityDefinition): readon
 export type EagerLoadViewer = {
     readonly user: SessionUser;
     readonly parentVisibility: ParentVisibilityOption;
+    readonly resolveTable?: (entityName: string) => ReturnType<typeof buildEntityTable>;
 };
 /** Eagerloads a list of rows without mutating them; returns shallow copies
  *  with an added `_refs` property. */

package/dist/db/eagerload.js

@@ -21,15 +21,15 @@ import { requestContext } from "../api/request-context.js";
 import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, } from "../crypto/index.js";
 import { selectMany } from "../db/query.js";
 import { filterReadFields } from "../engine/field-access.js";
-import { buildOwnershipClause, combineClauses, shiftParams, tableNameOf, } from "../engine/ownership.js";
+import { shiftParams, tableNameOf } from "../engine/ownership.js";
 import { parseRefTargetEntityName } from "../engine/parse-ref-target.js";
 import { isUuid, SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { scrubLogValue } from "../logging/scrub.js";
 import { createFallbackLogger } from "../logging/utils.js";
 import { collectEncryptedFieldNames, decryptEntityFieldValues, resolveEntityFieldEncryption, } from "./entity-field-encryption.js";
-import { buildParentRefClause } from "./parent-ref-clause.js";
 import { toPostgresArrayLiteral } from "./queries/postgres-array-literal.js";
 import { executeRawQueryRead } from "./queries/raw-sql.js";
+import { resolveReadOwnership } from "./read-ownership.js";
 import { buildEntityTable, physicalColumnName } from "./table-builder.js";
 import { tenantDbRunner } from "./tenant-db-runner.js";
 const log = createFallbackLogger("eagerload");
@@ -71,9 +71,7 @@ async function decryptReferencedRow(row, piiFields, encryptedFields, kms) {
 // entity. Raw SQL because ownership/parentRef clauses are SQL fragments; the
 // table is unaliased since where-rules qualify columns with the table name.
 async function resolveRefAccessScope(refEntity, refTable, refTableName, ids, db, viewer) {
-    const access = combineClauses(buildOwnershipClause(viewer.user, refEntity.access?.read, refTable), buildParentRefClause(refEntity, refTable, refTableName, viewer.user, db, viewer.parentVisibility, {
-        includeDeleted: false,
-    }));
+    const access = resolveReadOwnership({ entity: refEntity, table: refTable }, refTableName, viewer.user, db, viewer.parentVisibility, { includeDeleted: false, narrowTypes: undefined });
     if (access.kind === "empty")
         return { kind: "none" };
     if (access.kind === "pass")
@@ -155,7 +153,7 @@ export async function enrichWithReferences(rows, entity, resolveEntity, db, view
             // to the UUID instead of crashing.
             return { fieldName: rf.fieldName, multiple: rf.multiple, map: new Map() };
         }
-        const refTable = buildEntityTable(rf.refEntityName, refEntity);
+        const refTable = viewer.resolveTable?.(rf.refEntityName) ?? buildEntityTable(rf.refEntityName, refEntity);
         const refTableName = tableNameOf(refTable);
         const usesUuidIds = refEntity.idType === undefined || refEntity.idType === "uuid";
         // A malformed ref value must not 500 the whole list via the uuid cast.

package/dist/db/event-store-executor-context.js

@@ -10,8 +10,8 @@ import { isStreamArchived } from "../event-store/index.js";
 import { assertUnreachable } from "../utils/index.js";
 import { rehydrateCompoundTypes } from "./compound-types.js";
 import { collectEncryptedFieldNames, decryptEntityFieldValues, encryptEntityFieldValues, logUndecryptableField, resolveEntityFieldEncryption, } from "./entity-field-encryption.js";
-import { resolveReadOwnership } from "./event-store-executor-read-where.js";
 import { constraintOf, isUniqueViolation } from "./pg-error.js";
+import { resolveReadOwnership } from "./read-ownership.js";
 import { toSnakeCase } from "./table-builder.js";
 import { columnHandleName, schemaTableName } from "./table-introspection.js";
 import { tenantDbRunner } from "./tenant-db-runner.js";

package/dist/db/event-store-executor-read-paging.js

@@ -81,7 +81,7 @@ export function appendCursorBoundary(where, encodedCursor, sort) {
 export function encodeNextCursor(cursorId, sort, lastRaw, lastSortLabel, table) {
     const sortText = sort.kind === "unsorted"
         ? undefined
-        : toCursorSortText(sort.kind === "referenceLabel"
+        : toCursorSortText(sort.kind === "expression"
             ? lastSortLabel
             : lastRaw[physicalColumnName(table, sort.field)]);
     return sortText === undefined ? encodeCursor(cursorId) : encodeKeysetCursor(sortText, cursorId);

package/dist/db/event-store-executor-read-search.d.ts

@@ -5,8 +5,10 @@ import type { SearchAdapter } from "../search/types.ts";
 import type { EventStoreExecutor } from "./event-store-executor.ts";
 import type { Table } from "./event-store-executor-context.ts";
 import { type ListWhere } from "./event-store-executor-read-filter.ts";
+import type { ParentVisibilityOption } from "./parent-ref-clause.ts";
 import type { TenantDb } from "./tenant-db.ts";
 type ReferenceSearchOption = NonNullable<Parameters<EventStoreExecutor["list"]>[3]>["referenceSearch"];
+export declare function referenceTargetOwnership(targetEntity: EntityDefinition, targetTable: Table, targetTableName: string, user: SessionUser, db: TenantDb, parentVisibility: ParentVisibilityOption | undefined): OwnershipClause;
 export declare function isSoftDeletedTargetHidden(targetEntity: EntityDefinition, targetTable: Table): boolean;
 export type ListSearchRequest = {
     readonly searchTerm: string;
@@ -14,6 +16,7 @@ export type ListSearchRequest = {
     readonly entityName: string;
     readonly table: Table;
     readonly referenceSearch: ReferenceSearchOption;
+    readonly parentVisibility: ParentVisibilityOption | undefined;
     readonly fieldReadClause: (field: string) => OwnershipClause;
     readonly streamTenantFor: (user: SessionUser) => TenantId;
     readonly user: SessionUser;