@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

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

@@ -0,0 +1,203 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/index.js";
+import { shiftParams } from "../engine/ownership.js";
+import { ValidationError } from "../errors/index.js";
+import { isListFilterAllowed } from "./entity-field-encryption.js";
+import { buildFilterWhere } from "./event-store-executor-context.js";
+// Rebases a clause's local $1..$n onto `params` and returns the shifted text.
+export function bindShiftedClause(params, clause) {
+    const shifted = shiftParams({ sqlText: clause.sqlText, params: clause.params }, params.length);
+    for (const p of shifted.params)
+        params.push(p);
+    return shifted.sqlText;
+}
+export function appendShiftedClause(where, clause) {
+    where.whereSql.push(bindShiftedClause(where.params, clause));
+}
+export function bindPlaceholders(params, values) {
+    return values
+        .map((value) => {
+        params.push(value);
+        return `$${params.length}`;
+    })
+        .join(", ");
+}
+// multiSelect stores its options as a jsonb array — a filter value is one
+// option, not the whole array, so eq/ne/in must check array containment
+// (`@>`) instead of scalar `=`/`<>`/`IN` against the jsonb column.
+// lt/gt/lte/gte have no containment analogue; the boot-validator already
+// blocks them for screen-declared filters (screen-filter-ops.ts
+// EQUALITY_ONLY), but a client-supplied facet filter reaches here
+// unvalidated, so treat it as unsatisfiable rather than emitting SQL
+// Postgres would reject.
+function applyMultiSelectFilter(colSql, whereSql, params, f) {
+    if (f.op === "lt" || f.op === "gt" || f.op === "lte" || f.op === "gte") {
+        whereSql.push("FALSE");
+        // skip: lt/gt/lte/gte is unsatisfiable on a multiSelect column
+        return;
+    }
+    if (f.op === "in") {
+        if (!Array.isArray(f.value) || f.value.length === 0) {
+            whereSql.push("FALSE");
+            // skip: empty/non-array `in` is unsatisfiable, mirrors buildFilterWhere's "in" short-circuit
+            return;
+        }
+        const parts = f.value.map((v) => {
+            params.push(JSON.stringify([v]));
+            return `${colSql(f.field)} @> $${params.length}::text::jsonb`;
+        });
+        whereSql.push(`(${parts.join(" OR ")})`);
+        // skip: containment condition already pushed — don't fall through to the eq/ne branch below
+        return;
+    }
+    const candidates = Array.isArray(f.value) ? f.value : [f.value];
+    // `@> '[]'` is true for every non-null row, so an empty array would turn
+    // the filter into a silent match-all.
+    if (candidates.length === 0) {
+        whereSql.push("FALSE");
+        // skip: empty candidate list is unsatisfiable
+        return;
+    }
+    // Bound as text then cast: a JS array makes postgres.js infer boolean[]/int4[]
+    // for client-supplied non-string values, and `boolean[]::jsonb` is rejected
+    // (500 on client input). An array value means "contains all of these".
+    params.push(JSON.stringify(candidates));
+    const containment = `${colSql(f.field)} @> $${params.length}::text::jsonb`;
+    // A NULL column must count as "does not contain" — plain NOT(...) yields
+    // NULL and would drop those rows.
+    whereSql.push(f.op === "ne" ? `(${colSql(f.field)} IS NULL OR NOT (${containment}))` : containment);
+}
+// Falls through to the screen-filter WHERE builder shared with
+// screen-declared filters — buildFilterWhere flattens the op into a
+// WhereObject, which this then lowers to raw SQL fragments.
+function applyScreenFilter(table, colSql, whereSql, params, f) {
+    const screen = buildFilterWhere(f.field, f.op, f.value);
+    if (screen === null) {
+        whereSql.push("FALSE");
+        // skip: filter is unsatisfiable → emit FALSE, no params to bind
+        return;
+    }
+    for (const [field, value] of Object.entries(screen)) {
+        // `x <> NULL` is never true — mirror buildWhereClause's IS [NOT] NULL handling in db/where-clause.ts.
+        if (value === null) {
+            whereSql.push(`${colSql(field)} IS NULL`);
+        }
+        else if (Array.isArray(value)) {
+            const placeholders = value.map((v) => {
+                params.push(v);
+                return `$${params.length}`;
+            });
+            whereSql.push(`${colSql(field)} IN (${placeholders.join(", ")})`);
+        }
+        else if (isPlainObject(value)) {
+            if (value["ne"] === null && Object.keys(value).length === 1) {
+                whereSql.push(`${colSql(field)} IS NOT NULL`);
+                continue;
+            }
+            const opMap = {
+                gt: ">",
+                gte: ">=",
+                lt: "<",
+                lte: "<=",
+                ne: "<>",
+            };
+            for (const [opKey, opSym] of Object.entries(opMap)) {
+                if (!(opKey in value))
+                    continue;
+                params.push(value[opKey]);
+                whereSql.push(`${colSql(field)} ${opSym} $${params.length}`);
+            }
+        }
+        else {
+            // Blind-index OR rewrite, lock-step with buildWhereClause
+            // in db/where-clause.ts — equality on lookupable fields matches the
+            // plaintext arm OR the HMAC arm.
+            const bidxKey = configuredBlindIndexKey();
+            if (bidxKey !== undefined && typeof value === "string" && table[`${field}Bidx`]) {
+                params.push(value, computeBlindIndex(bidxKey, value));
+                whereSql.push(`(${colSql(field)} = $${params.length - 1} OR ${colSql(`${field}Bidx`)} = $${params.length})`);
+            }
+            else {
+                params.push(value);
+                whereSql.push(`${colSql(field)} = $${params.length}`);
+            }
+        }
+    }
+}
+// A `filter`/`filters` entry that already pins the parentRef's entityType
+// field is a real subset of the parent-ref clause's own OR-branches — the
+// client-supplied filter can't widen the result, only narrow which branches
+// the SQL even needs to consider. Skipped for multiSelect fields, where `eq`
+// means containment (see applyMultiSelectFilter) rather than equality.
+export function deriveParentNarrowTypes(entity, payload) {
+    const parentRef = entity.parentRef;
+    if (parentRef === undefined)
+        return undefined;
+    if (entity.fields[parentRef.entityTypeField]?.type === "multiSelect")
+        return undefined;
+    const typeFilters = [
+        ...(payload.filter ? [payload.filter] : []),
+        ...(payload.filters ?? []),
+    ].filter((f) => f.field === parentRef.entityTypeField);
+    let narrowed;
+    for (const f of typeFilters) {
+        let values;
+        if (f.op === "eq" && typeof f.value === "string") {
+            values = [f.value];
+        }
+        else if (f.op === "in" &&
+            Array.isArray(f.value) &&
+            f.value.every((v) => typeof v === "string")) {
+            values = f.value;
+        }
+        if (values === undefined)
+            continue;
+        narrowed =
+            narrowed === undefined
+                ? new Set(values)
+                : new Set([...narrowed].filter((v) => values.includes(v)));
+    }
+    return narrowed;
+}
+export function collectListFilters(payload) {
+    const single = payload.filter !== undefined ? [payload.filter] : [];
+    return payload.filters !== undefined ? [...single, ...payload.filters] : single;
+}
+export function applyListFilter(where, f, table, entity, fieldReadClause) {
+    if (!Object.hasOwn(table, f.field)) {
+        // skip: unknown field — not a real column, drop the filter (injection guard)
+        return;
+    }
+    const readClause = fieldReadClause(f.field);
+    if (readClause.kind === "empty") {
+        where.whereSql.push("FALSE");
+        // skip: no role grants read on this field, so no row may be probed
+        // through it — an unsatisfiable filter beats an error, which would
+        // itself confirm the field exists (field-access.ts strips silently)
+        return;
+    }
+    if (!isListFilterAllowed(entity, f.field, f)) {
+        throw new ValidationError({
+            fields: [
+                {
+                    path: `filter.${f.field}`,
+                    code: "field_not_filterable",
+                    i18nKey: "errors.validation.invalid_value",
+                    params: {
+                        field: f.field,
+                        op: f.op,
+                        hint: "Encrypted, personal and secret fields cannot be filtered; only equality on a field with find: exact or fuzzy.",
+                    },
+                },
+            ],
+        });
+    }
+    if (readClause.kind === "sql")
+        appendShiftedClause(where, readClause);
+    if (entity.fields[f.field]?.type === "multiSelect") {
+        applyMultiSelectFilter(where.colSql, where.whereSql, where.params, f);
+        // skip: multiSelect already handled — don't fall through to applyScreenFilter
+        return;
+    }
+    applyScreenFilter(table, where.colSql, where.whereSql, where.params, f);
+}

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

@@ -0,0 +1,14 @@
+import type { DbRunner } from "./connection.ts";
+import type { Table } from "./event-store-executor-context.ts";
+import type { ListWhere } from "./event-store-executor-read-filter.ts";
+import { type ListSort } from "./event-store-executor-read-sort.ts";
+export declare function resolveListPagination(payload: {
+    readonly limit?: unknown;
+    readonly offset?: unknown;
+}): {
+    readonly limit: number;
+    readonly offset: number;
+};
+export declare function appendCursorBoundary(where: ListWhere, encodedCursor: string, sort: ListSort): void;
+export declare function encodeNextCursor(cursorId: string, sort: ListSort, lastRaw: Record<string, unknown>, lastSortLabel: unknown, table: Table): string;
+export declare function countListRows(runner: DbRunner, tableName: string, whereClauseSqlText: string, whereParams: readonly unknown[]): Promise<number>;

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

@@ -0,0 +1,99 @@
+import { UnprocessableError } from "../errors/index.js";
+import { decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor.js";
+import { renderSortSql } from "./event-store-executor-read-sort.js";
+import { executeRawQueryRead } from "./queries/raw-sql.js";
+import { physicalColumnName } from "./table-builder.js";
+// Defense-in-depth pagination guard. The handler boundary (entityListSchema)
+// already validates limit/offset, but the executor is public API for custom
+// handlers that pass their payload straight through — a non-integer limit
+// would otherwise be interpolated raw into `LIMIT ${limit}` SQL text.
+const MAX_LIST_LIMIT = 200; // keep in sync with engine/entity-handlers.ts MAX_LIST_LIMIT
+export function resolveListPagination(payload) {
+    const limit = payload.limit ?? 50;
+    const offset = payload.offset ?? 0;
+    if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 0) {
+        throw new UnprocessableError("invalid_list_limit", {
+            details: { hint: "limit must be a non-negative integer" },
+        });
+    }
+    if (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0) {
+        throw new UnprocessableError("invalid_list_offset", {
+            details: { hint: "offset must be a non-negative integer" },
+        });
+    }
+    return { limit: Math.min(limit, MAX_LIST_LIMIT), offset };
+}
+// Cursor sort values travel as text and bind as plain string params — Postgres
+// infers the parameter type from the column they are compared against, the same
+// way prepareValue binds a timestamptz as an ISO string. undefined means the
+// driver value has no faithful text form, which downgrades the page to the
+// legacy id-only boundary instead of emitting a wrong one.
+function toCursorSortText(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") {
+        return String(value);
+    }
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === "object") {
+        const tag = Reflect.get(value, Symbol.toStringTag);
+        if (typeof tag === "string" && tag.startsWith("Temporal."))
+            return String(value);
+        return JSON.stringify(value);
+    }
+    return undefined;
+}
+// Keyset boundary for `ORDER BY <sort> <dir>, id ASC` under Postgres' DEFAULT
+// null ordering (ASC → NULLS LAST, DESC → NULLS FIRST). An explicit NULLS clause
+// would change the visible order and cost the sort its index.
+function keysetBoundarySql(sortCol, idCol, cursor, descending, params) {
+    params.push(cursor.id);
+    const afterId = `${idCol} > $${params.length}`;
+    const nullsComeFirst = descending;
+    if (cursor.sortValue === null) {
+        return nullsComeFirst
+            ? `(${sortCol} IS NOT NULL OR ${afterId})`
+            : `(${sortCol} IS NULL AND ${afterId})`;
+    }
+    params.push(cursor.sortValue);
+    const sortParam = `$${params.length}`;
+    const beyond = `${sortCol} ${descending ? "<" : ">"} ${sortParam}`;
+    const tie = `(${sortCol} = ${sortParam} AND ${afterId})`;
+    return nullsComeFirst
+        ? `(${sortCol} IS NOT NULL AND (${beyond} OR ${tie}))`
+        : `(${sortCol} IS NULL OR ${beyond} OR ${tie})`;
+}
+export function appendCursorBoundary(where, encodedCursor, sort) {
+    const cursor = decodeKeysetCursor(encodedCursor);
+    if (sort.kind === "unsorted" || cursor.sortValue === undefined) {
+        where.params.push(cursor.id);
+        where.whereSql.push(`${where.colSql("id")} > $${where.params.length}`);
+    }
+    else {
+        where.whereSql.push(keysetBoundarySql(renderSortSql(sort, where), where.colSql("id"), { id: cursor.id, sortValue: cursor.sortValue }, sort.descending, where.params));
+    }
+}
+export function encodeNextCursor(cursorId, sort, lastRaw, lastSortLabel, table) {
+    const sortText = sort.kind === "unsorted"
+        ? undefined
+        : toCursorSortText(sort.kind === "referenceLabel"
+            ? lastSortLabel
+            : lastRaw[physicalColumnName(table, sort.field)]);
+    return sortText === undefined ? encodeCursor(cursorId) : encodeKeysetCursor(sortText, cursorId);
+}
+// total: extra COUNT(*) — only when explicitly requested (pager UI).
+// Postgres cost is O(table-scan) without a filter, with a filter as
+// expensive as the corresponding WHERE — cheap enough on indexed columns.
+// Always counted over the full WHERE: search ids, reference matches, tenant,
+// soft-delete, cursor, ownership and filters all narrow the result, so the
+// search hit count alone is never the total.
+export async function countListRows(runner, tableName, whereClauseSqlText, whereParams) {
+    const countSql = `SELECT COUNT(*)::int AS count FROM "${tableName}"${whereClauseSqlText}`;
+    const countRows = await executeRawQueryRead(runner, countSql, whereParams);
+    return countRows[0]?.count ?? 0;
+}

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

@@ -0,0 +1,6 @@
+import type { EntityDefinition, TenantId } from "../engine/types/index.ts";
+import type { TableInfo } from "./table-info.ts";
+export declare function withStreamVersion(row: Record<string, unknown>, streamVersion: number): Record<string, unknown>;
+export declare function coerceAndRehydrateRow(raw: Record<string, unknown>, tableInfo: TableInfo, entity: EntityDefinition): Record<string, unknown>;
+export declare function appendStreamVersionProjection(params: unknown[], tableName: string, streamTenantId: TenantId): string;
+export declare function takeStreamVersions(rawRows: readonly Record<string, unknown>[]): number[];

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

@@ -0,0 +1,32 @@
+import { rehydrateCompoundTypes } from "./compound-types.js";
+import { coerceRow } from "./query.js";
+const STREAM_VERSION_ALIAS = "__streamVersion";
+export function withStreamVersion(row, streamVersion) {
+    return streamVersion > 0 ? { ...row, version: streamVersion } : row;
+}
+// Coerce BEFORE rehydrate/decrypt: raw SQL rows carry snake_case column names,
+// while compound-type lookups (rehydrateMoney et al.) and the encrypted/pii
+// field lists are all camelCase — running either first on a still-snake_case
+// row silently no-ops (money) or skips every multi-word field (ciphertext
+// leaked to the caller).
+export function coerceAndRehydrateRow(raw, tableInfo, entity) {
+    return rehydrateCompoundTypes(coerceRow(raw, tableInfo), entity);
+}
+// Stream version in the same statement as the rows: a separate read could pair a
+// post-write version with a pre-write row, and update({version}) would then pass
+// the optimistic lock against a state the client never saw (see loadDetailSnapshot).
+export function appendStreamVersionProjection(params, tableName, streamTenantId) {
+    params.push(streamTenantId);
+    return (`, (SELECT MAX("version") FROM "kumiko_events" ` +
+        `WHERE "aggregate_id" = "${tableName}"."id" AND "tenant_id" = $${params.length}) ` +
+        `AS "${STREAM_VERSION_ALIAS}"`);
+}
+// The alias is a query artifact, not a column of this entity — stripped before
+// coercion so it never reaches the caller or the entity cache.
+export function takeStreamVersions(rawRows) {
+    return rawRows.map((r) => {
+        const v = r[STREAM_VERSION_ALIAS];
+        delete r[STREAM_VERSION_ALIAS];
+        return typeof v === "number" ? v : 0;
+    });
+}

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

@@ -0,0 +1,28 @@
+import { type OwnershipClause } from "../engine/ownership.ts";
+import type { EntityDefinition, SessionUser, TenantId } from "../engine/types/index.ts";
+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 { TenantDb } from "./tenant-db.ts";
+type ReferenceSearchOption = NonNullable<Parameters<EventStoreExecutor["list"]>[3]>["referenceSearch"];
+export declare function isSoftDeletedTargetHidden(targetEntity: EntityDefinition, targetTable: Table): boolean;
+export type ListSearchRequest = {
+    readonly searchTerm: string;
+    readonly searchAdapter: SearchAdapter | undefined;
+    readonly entityName: string;
+    readonly table: Table;
+    readonly referenceSearch: ReferenceSearchOption;
+    readonly fieldReadClause: (field: string) => OwnershipClause;
+    readonly streamTenantFor: (user: SessionUser) => TenantId;
+    readonly user: SessionUser;
+    readonly db: TenantDb;
+};
+export type ListSearchOutcome = {
+    readonly kind: "noMatches";
+} | {
+    readonly kind: "applied";
+    readonly searchTruncated: boolean;
+};
+export declare function applyListSearch(request: ListSearchRequest, where: ListWhere): Promise<ListSearchOutcome>;
+export {};

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

@@ -0,0 +1,221 @@
+import { escapeLikePattern } from "../crypto/ciphertext-pattern.js";
+import { buildOwnershipClause, normalizeAccessEntry, shiftParams, } from "../engine/ownership.js";
+import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
+import { UnprocessableError } from "../errors/index.js";
+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 { buildEntityTable, physicalColumnName } from "./table-builder.js";
+import { schemaTableName } from "./table-introspection.js";
+import { tenantDbRunner } from "./tenant-db-runner.js";
+// Above this many target-row matches, drop the reference clause
+// entirely instead of truncating: an arbitrary 200-row slice of "which
+// targets match" would silently hide rows a full-cardinality match would
+// have found. Native text search on the entity's own fields still applies.
+const MAX_REFERENCE_SEARCH_IDS = 200;
+// The hit ids become an `id IN (...)` filter beneath the SQL cursor/filters/sort, so the
+// adapter must return the whole candidate set, not a page; matches Meilisearch's default
+// maxTotalHits, which caps a response at exactly this many hits however high a larger limit is
+// asked. A response that reaches the cap is therefore flagged `searchTruncated` rather than
+// treated as complete (a cap of N+1 could never be observed).
+const MAX_SEARCH_CANDIDATE_IDS = 1000;
+// Registry-declared `searchable` reference fields, plus the implicit
+// tenantId→tenant.name row-meta reference — both resolve a text
+// search term against a target row's label instead of the raw FK column.
+function collectReferenceSearchDescriptors(table, referenceSearch, dbMode) {
+    if (!referenceSearch)
+        return [];
+    const descriptors = referenceSearch.fields.map((f) => ({
+        ownColumn: f.fieldName,
+        targetEntityName: f.targetEntityName,
+        labelField: f.labelField,
+    }));
+    for (const [ownColumn, ref] of Object.entries(LIST_ROW_META_REFERENCES)) {
+        if (table[ownColumn] === undefined)
+            continue;
+        // In "tenant" mode the outer tenant filter already pins tenantId to one
+        // of exactly two values, so a by-name lookup here can never narrow that further.
+        if (ownColumn === "tenantId" && dbMode === "tenant")
+            continue;
+        descriptors.push({ ownColumn, targetEntityName: ref.refEntity, labelField: ref.refLabelField });
+    }
+    return descriptors;
+}
+// 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) {
+    return targetEntity.softDelete === true && targetTable["isDeleted"] !== undefined;
+}
+// Tenant-scoped ILIKE lookup against one reference target — never raw/
+// 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) {
+    // 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);
+    if (ownership.kind === "empty")
+        return undefined;
+    const labelCol = physicalColumnName(targetTable, descriptor.labelField);
+    const subParams = [`%${escapeLikePattern(searchTerm)}%`];
+    let tenantClause = "";
+    if (targetTable["tenantId"] !== undefined && db.mode === "tenant") {
+        subParams.push(db.tenantId, SYSTEM_TENANT_ID);
+        tenantClause = ` AND "${physicalColumnName(targetTable, "tenantId")}" IN ($2, $3)`;
+    }
+    let ownershipClause = "";
+    if (ownership.kind === "sql") {
+        const shifted = shiftParams({ sqlText: ownership.sqlText, params: ownership.params }, subParams.length);
+        ownershipClause = ` AND ${shifted.sqlText}`;
+        for (const p of shifted.params)
+            subParams.push(p);
+    }
+    const deletedClause = isSoftDeletedTargetHidden(targetEntity, targetTable)
+        ? ` AND "${physicalColumnName(targetTable, "isDeleted")}" = FALSE`
+        : "";
+    // ::text cast covers a non-text labelField (e.g. a number/select column
+    // used as label) — Postgres has no ILIKE for those types otherwise.
+    const sql = `SELECT "id" FROM "${targetTableName}" WHERE ("${labelCol}")::text ILIKE $1${tenantClause}${ownershipClause}${deletedClause} ` +
+        `LIMIT ${MAX_REFERENCE_SEARCH_IDS + 1}`;
+    const rows = await executeRawQueryRead(tenantDbRunner(db), sql, subParams);
+    if (rows.length === 0 || rows.length > MAX_REFERENCE_SEARCH_IDS) {
+        // skip: no match, or over the cap — drop the clause rather than
+        // truncate to an arbitrary slice of matching targets
+        return undefined;
+    }
+    return { ownColumn: descriptor.ownColumn, ids: rows.map((r) => r.id) };
+}
+// 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) {
+    const searchTenantId = targetEntity.systemStream ? SYSTEM_TENANT_ID : user.tenantId;
+    const results = await searchAdapter.search(searchTenantId, searchTerm, {
+        filterType: descriptor.targetEntityName,
+        limit: MAX_REFERENCE_SEARCH_IDS + 1,
+    });
+    if (results.length === 0 || results.length > MAX_REFERENCE_SEARCH_IDS) {
+        // 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);
+    if (ownership.kind === "empty")
+        return undefined;
+    const candidateIds = results.map((r) => String(r.entityId));
+    // The index is only trusted to name candidates: a stale or foreign-tenant document must
+    // never become a filter value, so tenant-scoped targets are always re-read from the DB.
+    const tenantScoped = targetTable["tenantId"] !== undefined && db.mode === "tenant";
+    if (ownership.kind === "pass" && !tenantScoped) {
+        return { ownColumn: descriptor.ownColumn, ids: candidateIds };
+    }
+    const params = [...candidateIds];
+    const idPlaceholders = candidateIds.map((_, i) => `$${i + 1}`);
+    let tenantClause = "";
+    if (tenantScoped) {
+        params.push(db.tenantId, SYSTEM_TENANT_ID);
+        tenantClause = ` AND "${physicalColumnName(targetTable, "tenantId")}" IN ($${params.length - 1}, $${params.length})`;
+    }
+    let ownershipClause = "";
+    if (ownership.kind === "sql") {
+        const shifted = shiftParams({ sqlText: ownership.sqlText, params: ownership.params }, params.length);
+        for (const p of shifted.params)
+            params.push(p);
+        ownershipClause = ` AND ${shifted.sqlText}`;
+    }
+    const sql = `SELECT "id" FROM "${targetTableName}" WHERE "id" IN (${idPlaceholders.join(", ")})` +
+        `${tenantClause}${ownershipClause}`;
+    const rows = await executeRawQueryRead(tenantDbRunner(db), sql, params);
+    if (rows.length === 0)
+        return undefined;
+    return { ownColumn: descriptor.ownColumn, ids: rows.map((r) => r.id) };
+}
+async function resolveReferenceMatches(descriptor, searchTerm, resolveEntity, db, user, searchAdapter) {
+    const targetEntity = resolveEntity(descriptor.targetEntityName);
+    if (targetEntity === undefined) {
+        // skip: unknown target entity — registry inconsistency the boot-validator
+        // should have caught; fail open (no clause) rather than 500 the request
+        return undefined;
+    }
+    if (targetEntity.fields[descriptor.labelField] === undefined) {
+        // skip: labelField isn't a real (declared) column on the target entity —
+        // row-meta references (e.g. tenant.name) always resolve here since
+        // `name` is a declared field on the tenant entity, not an id/row-meta column
+        return undefined;
+    }
+    const targetTable = referenceTargetTable(descriptor.targetEntityName, targetEntity);
+    const targetTableName = String(schemaTableName(targetTable));
+    if (!isSensitiveLabelField(targetEntity, descriptor.labelField)) {
+        return resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db);
+    }
+    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);
+}
+// 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.
+const referenceTargetTables = new WeakMap();
+function referenceTargetTable(name, entity) {
+    const cached = referenceTargetTables.get(entity);
+    if (cached?.name === name)
+        return cached.table;
+    const table = buildEntityTable(name, entity);
+    referenceTargetTables.set(entity, { name, table });
+    return table;
+}
+export async function applyListSearch(request, where) {
+    const { searchAdapter } = request;
+    // A search term with no adapter wired must fail loud, not
+    // silently return the unfiltered list dressed up as a search result.
+    if (!searchAdapter) {
+        throw new UnprocessableError("search_adapter_not_wired", {
+            details: {
+                entity: request.entityName,
+                hint: "Wire a SearchAdapter for this entity, or remove `searchable` from the field/screen.",
+            },
+        });
+    }
+    // Same choke-point as writes/index: systemStream docs live under
+    // SYSTEM_TENANT_ID; everything else under the session tenant — db.mode
+    // must not invent a second predicate.
+    const searchTenantId = request.streamTenantFor(request.user);
+    const results = await searchAdapter.search(searchTenantId, request.searchTerm, {
+        filterType: request.entityName,
+        limit: MAX_SEARCH_CANDIDATE_IDS,
+    });
+    const filterIds = results.map((r) => r.entityId);
+    const referenceMatches = await resolveSearchableReferenceMatches(request, searchAdapter);
+    if (filterIds.length === 0 && referenceMatches.length === 0)
+        return { kind: "noMatches" };
+    const orParts = [];
+    if (filterIds.length > 0) {
+        orParts.push(`${where.colSql("id")} IN (${bindPlaceholders(where.params, filterIds)})`);
+    }
+    for (const match of referenceMatches) {
+        orParts.push(`${where.colSql(match.ownColumn)} IN (${bindPlaceholders(where.params, match.ids)})`);
+    }
+    // Parenthesized as one whereSql entry — whereSql is joined with
+    // " AND " below, an unparenthesized OR here would leak past the
+    // tenant filter that follows.
+    where.whereSql.push(`(${orParts.join(" OR ")})`);
+    return { kind: "applied", searchTruncated: results.length >= MAX_SEARCH_CANDIDATE_IDS };
+}
+// A searchable reference field (or the implicit tenantId→tenant.name row-meta
+// reference) whose target row's labelField matches the search term also counts
+// as a hit on this entity, not just a raw text-field hit.
+async function resolveSearchableReferenceMatches(request, searchAdapter) {
+    const { referenceSearch } = request;
+    if (!referenceSearch)
+        return [];
+    // A caller who cannot read the reference column itself must not be able
+    // 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)));
+    return matches.filter((m) => m !== undefined);
+}

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

@@ -0,0 +1,41 @@
+import { type OwnershipClause } from "../engine/ownership.ts";
+import type { EntityDefinition, 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 { TenantDb } from "./tenant-db.ts";
+type ListPayload = Parameters<EventStoreExecutor["list"]>[0];
+type ReferenceSortOption = NonNullable<Parameters<EventStoreExecutor["list"]>[3]>["referenceSort"];
+export type ListSort = {
+    readonly kind: "unsorted";
+} | {
+    readonly kind: "column";
+    readonly field: string;
+    readonly descending: boolean;
+} | {
+    readonly kind: "referenceLabel";
+    readonly field: string;
+    readonly descending: boolean;
+    readonly labelSql: (params: unknown[]) => string;
+};
+export type SortedListSort = Exclude<ListSort, {
+    readonly kind: "unsorted";
+}>;
+export declare function resolveListSort(request: {
+    readonly payload: Pick<ListPayload, "sort" | "sortDirection">;
+    readonly table: Table;
+    readonly entity: EntityDefinition;
+    readonly tableName: string;
+    readonly colSql: (field: string) => string;
+    readonly fieldReadClause: (field: string) => OwnershipClause;
+    readonly referenceSort: ReferenceSortOption;
+    readonly db: TenantDb;
+    readonly user: SessionUser;
+}): ListSort;
+export declare function renderSortSql(sort: SortedListSort, where: ListWhere): string;
+export declare function renderListOrderBy(sort: ListSort, where: ListWhere): {
+    readonly orderByClause: string;
+    readonly sortLabelProjection: string;
+};
+export declare function takeLastSortLabel(rawRows: readonly Record<string, unknown>[], sort: ListSort): unknown;
+export {};