@cosmicdrift/kumiko-framework 0.398.0 → 0.400.0

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;

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

@@ -6,6 +6,7 @@ import { LIST_ROW_META_REFERENCES } from "../ui-types/list-row-meta.js";
 import { hasSearchablePlaintext, isSensitiveLabelField } from "./entity-field-encryption.js";
 import { bindPlaceholders } from "./event-store-executor-read-filter.js";
 import { executeRawQueryRead } from "./queries/raw-sql.js";
+import { resolveReadOwnership } from "./read-ownership.js";
 import { buildEntityTable, physicalColumnName } from "./table-builder.js";
 import { schemaTableName } from "./table-introspection.js";
 import { tenantDbRunner } from "./tenant-db-runner.js";
@@ -42,6 +43,12 @@ function collectReferenceSearchDescriptors(table, referenceSearch, dbMode) {
     }
     return descriptors;
 }
+// The target of a reference is gated like a direct read of it (access rule, parent-ref and
+// readGate): a label of a row the viewer cannot open must not be findable by searching or
+// readable by ordering.
+export function referenceTargetOwnership(targetEntity, targetTable, targetTableName, user, db, parentVisibility) {
+    return resolveReadOwnership({ entity: targetEntity, table: targetTable }, targetTableName, user, db, parentVisibility, { includeDeleted: false, narrowTypes: undefined });
+}
 // Matches the main list's own default: soft-deleted rows are invisible, so a
 // deleted target must neither match a search nor influence an ordering.
 export function isSoftDeletedTargetHidden(targetEntity, targetTable) {
@@ -51,13 +58,13 @@ export function isSoftDeletedTargetHidden(targetEntity, targetTable) {
 // unscoped SQL, a match in a foreign tenant must never surface a row here.
 // Mirrors the main table's own tenant filter (see the `table["tenantId"]`
 // check further down in list()).
-async function resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db) {
+async function resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db, parentVisibility) {
     // The label must not leak through match counts: a viewer who cannot read the
     // target row or its label field would otherwise probe names by searching.
     const labelAccess = buildOwnershipClause(user, normalizeAccessEntry(targetEntity.fields[descriptor.labelField]?.access?.read), targetTable);
     if (labelAccess.kind !== "pass")
         return undefined;
-    const ownership = buildOwnershipClause(user, targetEntity.access?.read, targetTable);
+    const ownership = referenceTargetOwnership(targetEntity, targetTable, targetTableName, user, db, parentVisibility);
     if (ownership.kind === "empty")
         return undefined;
     const labelCol = physicalColumnName(targetTable, descriptor.labelField);
@@ -91,7 +98,7 @@ async function resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEnt
 }
 // Same lookup, but the target's index is tenant-wide, not per-viewer, so
 // candidate ids get re-checked against the target entity's own read access.
-async function resolveReferenceMatchesViaSearchIndex(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db, searchAdapter) {
+async function resolveReferenceMatchesViaSearchIndex(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db, searchAdapter, parentVisibility) {
     const searchTenantId = targetEntity.systemStream ? SYSTEM_TENANT_ID : user.tenantId;
     const results = await searchAdapter.search(searchTenantId, searchTerm, {
         filterType: descriptor.targetEntityName,
@@ -101,7 +108,7 @@ async function resolveReferenceMatchesViaSearchIndex(descriptor, searchTerm, tar
         // skip: no match, or over the cap — same drop-the-clause policy as the ILIKE path
         return undefined;
     }
-    const ownership = buildOwnershipClause(user, targetEntity.access?.read, targetTable);
+    const ownership = referenceTargetOwnership(targetEntity, targetTable, targetTableName, user, db, parentVisibility);
     if (ownership.kind === "empty")
         return undefined;
     const candidateIds = results.map((r) => String(r.entityId));
@@ -132,7 +139,7 @@ async function resolveReferenceMatchesViaSearchIndex(descriptor, searchTerm, tar
         return undefined;
     return { ownColumn: descriptor.ownColumn, ids: rows.map((r) => r.id) };
 }
-async function resolveReferenceMatches(descriptor, searchTerm, resolveEntity, db, user, searchAdapter) {
+async function resolveReferenceMatches(descriptor, searchTerm, resolveEntity, db, user, searchAdapter, resolveTable, parentVisibility) {
     const targetEntity = resolveEntity(descriptor.targetEntityName);
     if (targetEntity === undefined) {
         // skip: unknown target entity — registry inconsistency the boot-validator
@@ -145,17 +152,18 @@ async function resolveReferenceMatches(descriptor, searchTerm, resolveEntity, db
         // `name` is a declared field on the tenant entity, not an id/row-meta column
         return undefined;
     }
-    const targetTable = referenceTargetTable(descriptor.targetEntityName, targetEntity);
+    const targetTable = resolveTable?.(descriptor.targetEntityName) ??
+        referenceTargetTable(descriptor.targetEntityName, targetEntity);
     const targetTableName = String(schemaTableName(targetTable));
     if (!isSensitiveLabelField(targetEntity, descriptor.labelField)) {
-        return resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db);
+        return resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db, parentVisibility);
     }
     if (!hasSearchablePlaintext(targetEntity, descriptor.labelField)) {
         // skip: no plaintext anywhere to match — boot rejects this normally,
         // this is defense-in-depth for a target entity resolved only at runtime.
         return undefined;
     }
-    return resolveReferenceMatchesViaSearchIndex(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db, searchAdapter);
+    return resolveReferenceMatchesViaSearchIndex(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db, searchAdapter, parentVisibility);
 }
 // Building the table is pure but not free, and runs on every search request;
 // keyed by the definition object so a re-registered entity never sees a stale table.
@@ -216,6 +224,6 @@ async function resolveSearchableReferenceMatches(request, searchAdapter) {
     // to infer its value by matching the target's label — same probe
     // surface as filtering/sorting on it directly.
     const descriptors = collectReferenceSearchDescriptors(request.table, referenceSearch, request.db.mode).filter((d) => request.fieldReadClause(d.ownColumn).kind === "pass");
-    const matches = await Promise.all(descriptors.map((d) => resolveReferenceMatches(d, request.searchTerm, referenceSearch.resolveEntity, request.db, request.user, searchAdapter)));
+    const matches = await Promise.all(descriptors.map((d) => resolveReferenceMatches(d, request.searchTerm, referenceSearch.resolveEntity, request.db, request.user, searchAdapter, referenceSearch.resolveTable, request.parentVisibility)));
     return matches.filter((m) => m !== undefined);
 }

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

@@ -4,6 +4,7 @@ import type { SessionUser } from "../engine/types/index.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 ListPayload = Parameters<EventStoreExecutor["list"]>[0];
 type ReferenceSortOption = NonNullable<Parameters<EventStoreExecutor["list"]>[3]>["referenceSort"];
@@ -15,16 +16,20 @@ export type ListSort = {
     readonly descending: boolean;
     readonly nulls: SortNulls | undefined;
 } | {
-    readonly kind: "referenceLabel";
+    readonly kind: "expression";
     readonly field: string;
     readonly descending: boolean;
     readonly nulls: SortNulls | undefined;
-    readonly labelSql: (params: unknown[]) => string;
+    readonly sql: (params: unknown[]) => string;
 };
 export type SortedListSort = Exclude<ListSort, {
     readonly kind: "unsorted";
 }>;
 export declare function sortsNullsFirst(sort: SortedListSort): boolean;
+export declare function buildReferenceSortExpr(outerColumnSql: string, descriptor: {
+    readonly targetEntityName: string;
+    readonly labelField: string;
+}, resolveEntity: (entityName: string) => EntityDefinition | undefined, db: TenantDb, user: SessionUser, resolveTable: ((entityName: string) => Table) | undefined, parentVisibility: ParentVisibilityOption | undefined): ((params: unknown[]) => string) | undefined;
 export declare function resolveListSort(request: {
     readonly payload: Pick<ListPayload, "sort" | "sortDirection">;
     readonly table: Table;
@@ -33,8 +38,10 @@ export declare function resolveListSort(request: {
     readonly colSql: (field: string) => string;
     readonly fieldReadClause: (field: string) => OwnershipClause;
     readonly referenceSort: ReferenceSortOption;
+    readonly derivedSortExpr?: (field: string) => ((params: unknown[]) => string) | undefined;
     readonly db: TenantDb;
     readonly user: SessionUser;
+    readonly parentVisibility: ParentVisibilityOption | undefined;
 }): ListSort;
 export declare function renderSortSql(sort: SortedListSort, where: ListWhere): string;
 export declare function renderListOrderBy(sort: ListSort, where: ListWhere): {

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

@@ -1,12 +1,14 @@
 import { buildOwnershipClause, normalizeAccessEntry, shiftParams, } from "../engine/ownership.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { isListSortAllowed, isSensitiveLabelField } from "./entity-field-encryption.js";
-import { isSoftDeletedTargetHidden } from "./event-store-executor-read-search.js";
+import { isSoftDeletedTargetHidden, referenceTargetOwnership, } from "./event-store-executor-read-search.js";
 import { buildEntityTable, physicalColumnName } from "./table-builder.js";
 import { schemaTableName } from "./table-introspection.js";
 // Projected alongside the row when a reference sort is active, so the keyset
 // cursor carries the label that was ordered by instead of the FK's UUID.
 const SORT_LABEL_ALIAS = "__kumiko_sort_label";
+// Where-rules qualify with the table name they get; the target may be the outer entity itself.
+const TARGET_ALIAS = "t";
 function declaredSortNulls(entity, field) {
     const def = entity.fields[field];
     return def !== undefined && "sortNulls" in def ? def.sortNulls : undefined;
@@ -28,7 +30,7 @@ function nullsClause(sort) {
 // undefined means "cannot order by this label", which drops the sort to plain
 // id order; falling back to the UUID column would look deliberate to the user
 // while being arbitrary, which is worse than no sorting.
-function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolveEntity, db, user) {
+export function buildReferenceSortExpr(outerColumnSql, descriptor, resolveEntity, db, user, resolveTable, parentVisibility) {
     const targetEntity = resolveEntity(descriptor.targetEntityName);
     if (targetEntity === undefined) {
         // skip: unknown target entity — registry inconsistency the boot-validator
@@ -44,15 +46,16 @@ function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolv
         // arbitrary to the reader and would also rank rows by their stored secret
         return undefined;
     }
-    const targetTable = buildEntityTable(descriptor.targetEntityName, targetEntity);
+    const targetTable = resolveTable?.(descriptor.targetEntityName) ??
+        buildEntityTable(descriptor.targetEntityName, targetEntity);
     // The order of labels the viewer may not read would leak them bit by bit, same as the search path.
-    const labelAccess = buildOwnershipClause(user, normalizeAccessEntry(targetEntity.fields[descriptor.labelField]?.access?.read), targetTable);
+    const labelAccess = buildOwnershipClause(user, normalizeAccessEntry(targetEntity.fields[descriptor.labelField]?.access?.read), targetTable, 1, TARGET_ALIAS);
     if (labelAccess.kind !== "pass")
         return undefined;
-    const ownership = buildOwnershipClause(user, targetEntity.access?.read, targetTable);
+    const targetTableName = String(schemaTableName(targetTable));
+    const ownership = referenceTargetOwnership(targetEntity, targetTable, TARGET_ALIAS, user, db, parentVisibility);
     if (ownership.kind === "empty")
         return undefined;
-    const targetTableName = String(schemaTableName(targetTable));
     const labelCol = physicalColumnName(targetTable, descriptor.labelField);
     const tenantScoped = targetTable["tenantId"] !== undefined && db.mode === "tenant";
     const tenantCol = tenantScoped ? physicalColumnName(targetTable, "tenantId") : "";
@@ -77,11 +80,21 @@ function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolv
             ownershipClause = ` AND ${shifted.sqlText}`;
         }
         return (`(SELECT t."${labelCol}" FROM "${targetTableName}" t ` +
-            `WHERE t."id" = "${outerTableName}".${ownColumnSql}${tenantClause}${ownershipClause}${deletedClause})`);
+            `WHERE t."id" = ${outerColumnSql}${tenantClause}${ownershipClause}${deletedClause})`);
     };
 }
 export function resolveListSort(request) {
     const { payload, table, entity, referenceSort } = request;
+    const derivedSql = payload.sort ? request.derivedSortExpr?.(payload.sort) : undefined;
+    if (derivedSql !== undefined && payload.sort) {
+        return {
+            kind: "expression",
+            field: payload.sort,
+            descending: payload.sortDirection === "desc",
+            nulls: undefined,
+            sql: derivedSql,
+        };
+    }
     // A column sort must not 400 (the renderer sends one per header click), and the order of
     // ciphertext carries no meaning for the user while leaking the order of the plaintext.
     const field = payload.sort &&
@@ -101,15 +114,15 @@ export function resolveListSort(request) {
     // directly: either the field opted into `sortable` and we order by the
     // target row's label, or the sort is dropped to plain id order.
     const descriptor = referenceSort?.fields.find((f) => f.fieldName === field);
-    const labelSql = referenceSort && descriptor
-        ? buildReferenceSortExpr(request.tableName, request.colSql(field), descriptor, referenceSort.resolveEntity, request.db, request.user)
+    const sql = referenceSort && descriptor
+        ? buildReferenceSortExpr(`"${request.tableName}".${request.colSql(field)}`, descriptor, referenceSort.resolveEntity, request.db, request.user, referenceSort.resolveTable, request.parentVisibility)
         : undefined;
-    return labelSql === undefined
+    return sql === undefined
         ? { kind: "unsorted" }
-        : { kind: "referenceLabel", field, descending, nulls, labelSql };
+        : { kind: "expression", field, descending, nulls, sql };
 }
 export function renderSortSql(sort, where) {
-    return sort.kind === "referenceLabel" ? sort.labelSql(where.params) : where.colSql(sort.field);
+    return sort.kind === "expression" ? sort.sql(where.params) : where.colSql(sort.field);
 }
 export function renderListOrderBy(sort, where) {
     const idAscending = `${where.colSql("id")} ASC`;
@@ -124,7 +137,7 @@ export function renderListOrderBy(sort, where) {
             sortLabelProjection: "",
         };
     }
-    // The projected label alias is ordered by directly, so Postgres evaluates
+    // The projected alias is ordered by directly, so Postgres evaluates
     // the correlated subquery once per row instead of once for ORDER BY and
     // once for the SELECT list. Projecting it also lets the keyset cursor carry
     // the value that was ordered by rather than the FK column's UUID.
@@ -137,7 +150,7 @@ export function renderListOrderBy(sort, where) {
 // stripped before coercion; the last row's label feeds the keyset cursor.
 export function takeLastSortLabel(rawRows, sort) {
     const lastSortLabel = rawRows[rawRows.length - 1]?.[SORT_LABEL_ALIAS];
-    if (sort.kind === "referenceLabel") {
+    if (sort.kind === "expression") {
         for (const row of rawRows)
             delete row[SORT_LABEL_ALIAS];
     }

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

@@ -3,15 +3,10 @@ import type { SessionUser } from "../engine/types/index.ts";
 import type { EventStoreExecutor } from "./event-store-executor.ts";
 import type { ExecutorContext } 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";
 export type ListRuntimeOptions = NonNullable<Parameters<EventStoreExecutor["list"]>[3]>;
 export type ListWherePayload = Pick<Parameters<EventStoreExecutor["list"]>[0], "search" | "filter" | "filters">;
 export type FieldReadClause = (field: string) => OwnershipClause;
-export declare function resolveReadOwnership(ctx: Pick<ExecutorContext, "entity" | "table">, tableName: string, user: SessionUser, db: TenantDb, parentVisibility: ParentVisibilityOption | undefined, gate: {
-    readonly includeDeleted: boolean;
-    readonly narrowTypes: ReadonlySet<string> | undefined;
-}): OwnershipClause;
 export declare function createFieldReadClause(ctx: Pick<ExecutorContext, "entity" | "table">, user: SessionUser): FieldReadClause;
 export type ListWhereBuild = {
     readonly kind: "empty";

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

@@ -1,17 +1,10 @@
-import { buildOwnershipClause, combineClauses, normalizeAccessEntry, } from "../engine/ownership.js";
+import { buildOwnershipClause, normalizeAccessEntry, } from "../engine/ownership.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { appendShiftedClause, applyListFilter, collectListFilters, deriveParentNarrowTypes, } from "./event-store-executor-read-filter.js";
 import { applyListSearch } from "./event-store-executor-read-search.js";
-import { buildParentRefClause } from "./parent-ref-clause.js";
+import { resolveReadOwnership } from "./read-ownership.js";
 import { physicalColumnName } from "./table-builder.js";
 import { schemaTableName } from "./table-introspection.js";
-// H.2 — entity-level read ownership, AND-ed with the parent-ref read-gate
-// (join-row entities derive their visibility from a host row's own read path —
-// see db/parent-ref-clause.ts). `empty` means there's no row the user could ever see.
-export function resolveReadOwnership(ctx, tableName, user, db, parentVisibility, gate) {
-    const parentClause = buildParentRefClause(ctx.entity, ctx.table, tableName, user, db, parentVisibility, gate);
-    return combineClauses(buildOwnershipClause(user, ctx.entity.access?.read, ctx.table), parentClause);
-}
 // Replicates TenantDb's readWhere semantics for the raw list SQL.
 function appendTenantAndSoftDeleteScope(where, ctx, db, includeDeleted) {
     if (ctx.table["tenantId"] !== undefined && db.mode === "tenant") {
@@ -62,6 +55,7 @@ export async function buildListWhere(ctx, payload, user, db, runtimeOptions) {
             entityName,
             table,
             referenceSearch: runtimeOptions?.referenceSearch,
+            parentVisibility: runtimeOptions?.parentVisibility,
             fieldReadClause,
             streamTenantFor,
             user,

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

@@ -1,11 +1,13 @@
 import { executeRawQueryRead } from "../db/queries/raw-sql.js";
 import { extractTableInfo } from "../db/table-info.js";
 import { getStreamVersion } from "../event-store/index.js";
+import { buildDerivedSelect } from "./derived-field-sql.js";
 import { aggregateList } from "./event-store-executor-read-aggregate.js";
 import { appendCursorBoundary, countListRows, encodeNextCursor, resolveListPagination, } from "./event-store-executor-read-paging.js";
 import { appendStreamVersionProjection, coerceAndRehydrateRow, takeStreamVersions, withStreamVersion, } from "./event-store-executor-read-rows.js";
 import { renderListOrderBy, resolveListSort, takeLastSortLabel, } from "./event-store-executor-read-sort.js";
-import { buildListWhere, resolveReadOwnership } from "./event-store-executor-read-where.js";
+import { buildListWhere } from "./event-store-executor-read-where.js";
+import { resolveReadOwnership } from "./read-ownership.js";
 import { schemaTableName } from "./table-introspection.js";
 import { tenantDbRunner } from "./tenant-db-runner.js";
 // The read verbs (list/aggregate/detail) of the event-store-executor. Split out
@@ -30,6 +32,15 @@ export function createReadVerbs(ctx) {
             if (built.kind === "empty")
                 return emptyListPage(totalCount);
             const { where, fieldReadClause, searchTruncated } = built;
+            const derived = buildDerivedSelect({
+                entity,
+                table,
+                tableName,
+                fieldReadClause,
+                user,
+                db,
+                runtime: runtimeOptions,
+            });
             const sort = resolveListSort({
                 payload,
                 table,
@@ -38,8 +49,10 @@ export function createReadVerbs(ctx) {
                 colSql: where.colSql,
                 fieldReadClause,
                 referenceSort: runtimeOptions?.referenceSort,
+                derivedSortExpr: derived?.sortExpr,
                 db,
                 user,
+                parentVisibility: runtimeOptions?.parentVisibility,
             });
             if (payload.cursor)
                 appendCursorBoundary(where, payload.cursor, sort);
@@ -51,24 +64,30 @@ export function createReadVerbs(ctx) {
             const offsetClause = !payload.cursor && offset > 0 ? ` OFFSET ${offset}` : "";
             const whereClauseSqlText = where.whereSql.length > 0 ? ` WHERE ${where.whereSql.join(" AND ")}` : "";
             const streamVersionProjection = appendStreamVersionProjection(where.params, tableName, streamTenantFor(user));
-            const selectList = `*${sortLabelProjection}${streamVersionProjection}`;
+            const derivedProjection = derived?.projections(where.params) ?? "";
+            const selectList = `*${sortLabelProjection}${streamVersionProjection}${derivedProjection}`;
             const listSql = `SELECT ${selectList} FROM "${tableName}"${whereClauseSqlText}${orderByClause} LIMIT ${limit}${offsetClause}`;
             const rawRows = await executeRawQueryRead(runner, listSql, where.params);
             const lastSortLabel = takeLastSortLabel(rawRows, sort);
             const streamVersions = takeStreamVersions(rawRows);
+            const derivedValues = derived?.takeValues(rawRows);
             const tableInfo = extractTableInfo(table);
             const encryptedRows = rawRows.map((r) => coerceAndRehydrateRow(r, tableInfo, entity));
             const decryptedRows = await Promise.all(encryptedRows.map((r) => decryptForRead(r, { degradeUndecryptable: () => { } })));
             // Stream version is authoritative (see detail()): ctx.events.append bumps the
             // stream without touching row.version, so the raw row version would hand
             // clients a stale optimistic-lock base. Rows without events keep theirs.
-            const rows = decryptedRows.map((r, i) => withStreamVersion(r, streamVersions[i] ?? 0));
+            const storedRows = decryptedRows.map((r, i) => withStreamVersion(r, streamVersions[i] ?? 0));
             // Cache the still-encrypted raw rows (read-row version): same at-rest guarantee as
             // detail()'s encryptForStorage round-trip, without a re-encrypt; detail() rejects
             // a cached version that differs from the stream.
-            if (entityCache && entityName && rows.length > 0) {
+            if (entityCache && entityName && storedRows.length > 0) {
                 await entityCache.mset(user.tenantId, entityName, encryptedRows.map((r) => ({ id: r["id"], data: r })));
             }
+            // Viewer-dependent, so attached only after the cache write, as new row objects.
+            const rows = derivedValues === undefined
+                ? storedRows
+                : storedRows.map((r, i) => ({ ...r, ...derivedValues[i] }));
             const lastRow = rows[rows.length - 1];
             const lastRaw = rawRows[rawRows.length - 1];
             let nextCursor = null;