@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

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

@@ -0,0 +1,683 @@
+import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { escapeLikePattern } from "../crypto/ciphertext-pattern.js";
+import { collectPiiSubjectFields, computeBlindIndex, configuredBlindIndexKey, } from "../crypto/index.js";
+import { executeRawQueryRead } from "../db/queries/raw-sql.js";
+import { coerceRow, extractTableInfo } from "../db/query.js";
+import { buildOwnershipClause, combineClauses, normalizeAccessEntry, shiftParams, } from "../engine/ownership.js";
+import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
+import { UnprocessableError } from "../errors/index.js";
+import { getStreamVersion } from "../event-store/index.js";
+import { LIST_ROW_META_REFERENCES } from "../ui-types/list-row-meta.js";
+import { rehydrateCompoundTypes } from "./compound-types.js";
+import { decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor.js";
+import { collectEncryptedFieldNames, hasSearchablePlaintext, isSensitiveLabelField, } from "./entity-field-encryption.js";
+import { buildFilterWhere, } from "./event-store-executor-context.js";
+import { buildParentRefClause } from "./parent-ref-clause.js";
+import { buildEntityTable, physicalColumnName } from "./table-builder.js";
+import { tenantDbRunner } from "./tenant-db-runner.js";
+// The two read verbs (list/detail) of the event-store-executor. Split out
+// of event-store-executor.ts (#1005, Welle 2) — behavior-preserving
+// relocation, not a redesign: unchanged from the original, now behind an
+// explicit ExecutorContext instead of the factory's local scope.
+// 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 = 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})`;
+}
+// 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 (fw#2490).
+// 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([v]);
+            return `${colSql(f.field)} @> $${params.length}::jsonb`;
+        });
+        whereSql.push(`(${parts.join(" OR ")})`);
+        // skip: containment condition already pushed — don't fall through to the eq/ne branch below
+        return;
+    }
+    // Bind a JS array, not JSON.stringify(value) — postgres.js double-encodes
+    // a stringified array through an `::jsonb` cast, so `@>` would never match
+    // (see update-roles.ts:67-68). An array value means "contains all of
+    // these" (the natural `@>` reading).
+    params.push(Array.isArray(f.value) ? f.value : [f.value]);
+    const containment = `${colSql(f.field)} @> $${params.length}::jsonb`;
+    whereSql.push(f.op === "ne" ? `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)) {
+        // #2015: `x <> NULL` is never true — mirror buildWhereClause's IS [NOT] NULL handling in bun-db/query.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 (typeof value === "object") {
+            const valueObj = value;
+            if (valueObj["ne"] === null && Object.keys(valueObj).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 (#818), lock-step with buildWhereClause
+            // in bun-db/query.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.
+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;
+}
+// fw#2660 — 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;
+// Registry-declared `searchable` reference fields, plus the implicit
+// tenantId→tenant.name row-meta reference (fw#2660) — 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;
+}
+// Tenant-scoped ILIKE lookup against one reference target — never raw/
+// unscoped SQL, a match in a foreign tenant must never surface a row here
+// (fw#2660's hard constraint). Mirrors the main table's own tenant filter
+// (see the `table["tenantId"]` check further down in list()).
+async function resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetTable, targetTableName, db) {
+    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)`;
+    }
+    // ::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} ` +
+        `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));
+    if (ownership.kind === "pass") {
+        return { ownColumn: descriptor.ownColumn, ids: candidateIds };
+    }
+    const params = [...candidateIds];
+    const idPlaceholders = candidateIds.map((_, i) => `$${i + 1}`);
+    const shifted = shiftParams({ sqlText: ownership.sqlText, params: ownership.params }, params.length);
+    const sql = `SELECT "id" FROM "${targetTableName}" WHERE "id" IN (${idPlaceholders.join(", ")}) ` +
+        `AND ${shifted.sqlText}`;
+    for (const p of shifted.params)
+        params.push(p);
+    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 = buildEntityTable(descriptor.targetEntityName, targetEntity);
+    const targetTableName = String(targetTable[KUMIKO_NAME_SYMBOL]);
+    if (!isSensitiveLabelField(targetEntity, descriptor.labelField)) {
+        return resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetTable, targetTableName, 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);
+}
+// 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";
+// fw#2741 — resolve a `sortable: true` reference field's label inline for
+// ORDER BY. A correlated scalar subquery, not a join: the result set keeps one
+// row per entity row, the read model stays untouched, and the lookup rides the
+// target's primary key. Tenant-scoped exactly like the search path — a foreign
+// tenant's label must never influence this tenant's ordering.
+// 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 the issue calls worse than no sorting.
+function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolveEntity, db) {
+    const targetEntity = resolveEntity(descriptor.targetEntityName);
+    if (targetEntity === undefined) {
+        // skip: unknown target entity — registry inconsistency the boot-validator
+        // should have caught; drop the sort 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
+        return undefined;
+    }
+    if (collectEncryptedFieldNames(targetEntity).has(descriptor.labelField) ||
+        collectPiiSubjectFields(targetEntity).includes(descriptor.labelField)) {
+        // skip: encrypted/PII labelField — ciphertext orders by its bytes, which is
+        // arbitrary to the reader and would also rank rows by their stored secret
+        return undefined;
+    }
+    const targetTable = buildEntityTable(descriptor.targetEntityName, targetEntity);
+    const targetTableName = String(targetTable[KUMIKO_NAME_SYMBOL]);
+    const labelCol = physicalColumnName(targetTable, descriptor.labelField);
+    const tenantScoped = targetTable["tenantId"] !== undefined && db.mode === "tenant";
+    const tenantCol = tenantScoped ? physicalColumnName(targetTable, "tenantId") : "";
+    const tenantId = db.mode === "tenant" ? db.tenantId : undefined;
+    // No ::text cast (unlike the ILIKE search path): a non-text label must keep
+    // its native collation/numeric order, and the keyset param infers its type
+    // from the comparison anyway.
+    return (params) => {
+        let tenantClause = "";
+        if (tenantScoped) {
+            params.push(tenantId, SYSTEM_TENANT_ID);
+            tenantClause = ` AND t."${tenantCol}" IN ($${params.length - 1}, $${params.length})`;
+        }
+        return (`(SELECT t."${labelCol}" FROM "${targetTableName}" t ` +
+            `WHERE t."id" = "${outerTableName}".${ownColumnSql}${tenantClause})`);
+    };
+}
+export function createReadVerbs(ctx) {
+    const { table, entity, entityName, entityCache, searchAdapter, softDelete, streamTenantFor, idFilter, loadWithOwnership, decryptForRead, encryptForStorage, } = ctx;
+    return {
+        // list + detail are unchanged from crud-executor — projections are the
+        // read-model and serve these queries directly.
+        async list(payload, user, db, runtimeOptions) {
+            const runner = tenantDbRunner(db);
+            const { limit, offset } = resolveListPagination(payload);
+            const totalCount = payload.totalCount === true;
+            const tableName = String(table[KUMIKO_NAME_SYMBOL]);
+            // 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). Decide before
+            // touching search or the DB: `empty` means there's no row the user
+            // could ever see, so skip both paths and return an empty page.
+            const narrowTypes = deriveParentNarrowTypes(entity, payload);
+            const parentClause = buildParentRefClause(entity, table, tableName, user, db, runtimeOptions?.parentVisibility, { includeDeleted: runtimeOptions?.includeDeleted === true, narrowTypes });
+            const ownership = combineClauses(buildOwnershipClause(user, entity.access?.read, table), parentClause);
+            if (ownership.kind === "empty") {
+                return { rows: [], nextCursor: null, ...(totalCount && { total: 0 }) };
+            }
+            let filterIds;
+            // fw#2660 — true once a searchable-reference or row-meta-reference
+            // clause contributed rows, so the total-count fast-path below knows
+            // `filterIds.length` alone would undercount.
+            let referenceClauseActive = false;
+            // Build the WHERE clause as raw SQL — ownership produces a
+            // parameterised fragment that we splice in alongside simple WhereObject
+            // conditions (cursor, search-filter-IDs, screen-filter, tenant-scope).
+            const whereSql = [];
+            const params = [];
+            const physicalCol = (field) => physicalColumnName(table, field);
+            const colSql = (field) => `"${physicalCol(field)}"`;
+            // Field-level read access gates filtering and sorting the same way it
+            // gates the projected row: a caller who cannot read a field must not be
+            // able to probe its values through result counts or ordering (fw#2629).
+            // Hoisted above the search block (fw#2660) — a searchable-reference
+            // clause is the same probe surface as a filter/sort and must be gated
+            // the same way, before the reference-match query even runs.
+            const fieldReadClause = (field) => buildOwnershipClause(user, normalizeAccessEntry(entity.fields[field]?.access?.read), table);
+            // Build-Time options.searchAdapter gewinnt; runtime-Override ist
+            // Fallback für die defaultEntityQueryHandler-Pipe (die nutzt den
+            // ctx.searchAdapter erst zur Laufzeit weil createEventStoreExecutor
+            // beim Definition-Time noch keinen Server-Context hat).
+            const effectiveSearchAdapter = searchAdapter ?? runtimeOptions?.searchAdapter;
+            if (payload.search) {
+                const searchTerm = payload.search;
+                // #2032 — a search term with no adapter wired must fail loud, not
+                // silently return the unfiltered list dressed up as a search result.
+                if (!effectiveSearchAdapter) {
+                    throw new UnprocessableError("search_adapter_not_wired", {
+                        details: {
+                            entity: 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 (kumiko-framework#2412).
+                const searchTenantId = streamTenantFor(user);
+                const results = await effectiveSearchAdapter.search(searchTenantId, searchTerm, {
+                    filterType: entityName,
+                });
+                filterIds = results.map((r) => r.entityId);
+                // fw#2660 — union in reference-column label matches: 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.
+                const referenceSearch = runtimeOptions?.referenceSearch;
+                // fw#2629 parity: 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(table, referenceSearch, db.mode).filter((d) => fieldReadClause(d.ownColumn).kind === "pass");
+                const referenceMatches = referenceSearch
+                    ? (await Promise.all(descriptors.map((d) => resolveReferenceMatches(d, searchTerm, referenceSearch.resolveEntity, db, user, effectiveSearchAdapter)))).filter((m) => m !== undefined)
+                    : [];
+                if (filterIds.length === 0 && referenceMatches.length === 0) {
+                    return { rows: [], nextCursor: null, ...(totalCount && { total: 0 }) };
+                }
+                const orParts = [];
+                if (filterIds.length > 0) {
+                    const placeholders = filterIds.map((id) => {
+                        params.push(id);
+                        return `$${params.length}`;
+                    });
+                    orParts.push(`${colSql("id")} IN (${placeholders.join(", ")})`);
+                }
+                for (const match of referenceMatches) {
+                    const placeholders = match.ids.map((id) => {
+                        params.push(id);
+                        return `$${params.length}`;
+                    });
+                    orParts.push(`${colSql(match.ownColumn)} IN (${placeholders.join(", ")})`);
+                    referenceClauseActive = true;
+                }
+                // Parenthesized as one whereSql entry — whereSql is joined with
+                // " AND " below, an unparenthesized OR here would leak past the
+                // tenant filter that follows.
+                whereSql.push(`(${orParts.join(" OR ")})`);
+            }
+            // The total-count fast-path below is only valid while this is still
+            // true after every later clause (tenant, soft-delete, cursor,
+            // ownership, parent-ref, filters) — see where it's checked.
+            const whereSqlLenAfterSearch = whereSql.length;
+            const sortCandidate = payload.sort && table[payload.sort] && fieldReadClause(payload.sort).kind === "pass"
+                ? payload.sort
+                : undefined;
+            const sortDescending = payload.sortDirection === "desc";
+            // fw#2741 — a reference column stores a UUID, so it is never sorted by
+            // 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.
+            let sortField;
+            let referenceSortExpr;
+            if (sortCandidate !== undefined && entity.fields[sortCandidate]?.type === "reference") {
+                const referenceSort = runtimeOptions?.referenceSort;
+                const descriptor = referenceSort?.fields.find((f) => f.fieldName === sortCandidate);
+                referenceSortExpr =
+                    referenceSort && descriptor
+                        ? buildReferenceSortExpr(tableName, colSql(sortCandidate), descriptor, referenceSort.resolveEntity, db)
+                        : undefined;
+                if (referenceSortExpr !== undefined)
+                    sortField = sortCandidate;
+            }
+            else {
+                sortField = sortCandidate;
+            }
+            // Tenant-Filter (replicates TenantDb's readWhere semantics).
+            if (table["tenantId"] !== undefined && db.mode === "tenant") {
+                params.push(db.tenantId, SYSTEM_TENANT_ID);
+                whereSql.push(`${colSql("tenantId")} IN ($${params.length - 1}, $${params.length})`);
+            }
+            if (softDelete && table["isDeleted"] && runtimeOptions?.includeDeleted !== true) {
+                whereSql.push(`${colSql("isDeleted")} = FALSE`);
+            }
+            if (payload.cursor) {
+                const cursor = decodeKeysetCursor(payload.cursor);
+                if (sortField === undefined || cursor.sortValue === undefined) {
+                    params.push(cursor.id);
+                    whereSql.push(`${colSql("id")} > $${params.length}`);
+                }
+                else {
+                    whereSql.push(keysetBoundarySql(referenceSortExpr !== undefined ? referenceSortExpr(params) : colSql(sortField), colSql("id"), { id: cursor.id, sortValue: cursor.sortValue }, sortDescending, params));
+                }
+            }
+            if (ownership.kind === "sql") {
+                const shifted = shiftParams({ sqlText: ownership.sqlText, params: ownership.params }, params.length);
+                whereSql.push(shifted.sqlText);
+                for (const p of shifted.params)
+                    params.push(p);
+            }
+            const applyFilter = (f) => {
+                if (table[f.field] === undefined) {
+                    // skip: unknown field — not a real column, drop the filter (injection guard)
+                    return;
+                }
+                const readClause = fieldReadClause(f.field);
+                if (readClause.kind === "empty") {
+                    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 (readClause.kind === "sql") {
+                    const shifted = shiftParams({ sqlText: readClause.sqlText, params: readClause.params }, params.length);
+                    whereSql.push(shifted.sqlText);
+                    for (const p of shifted.params)
+                        params.push(p);
+                }
+                if (entity.fields[f.field]?.type === "multiSelect") {
+                    applyMultiSelectFilter(colSql, whereSql, params, f);
+                    // skip: multiSelect already handled — don't fall through to applyScreenFilter
+                    return;
+                }
+                applyScreenFilter(table, colSql, whereSql, params, f);
+            };
+            if (payload.filter !== undefined)
+                applyFilter(payload.filter);
+            if (payload.filters !== undefined)
+                for (const f of payload.filters)
+                    applyFilter(f);
+            // The COUNT below reuses the WHERE text only, so it must bind exactly the
+            // params that text references — Postgres rejects a statement supplied
+            // with more parameters than it uses, and ORDER BY may add its own.
+            const whereParams = params.slice();
+            const sortSql = sortField === undefined
+                ? undefined
+                : referenceSortExpr !== undefined
+                    ? referenceSortExpr(params)
+                    : colSql(sortField);
+            const orderByClause = sortSql !== undefined
+                ? ` ORDER BY ${sortSql} ${sortDescending ? "DESC" : "ASC"}, ${colSql("id")} ASC`
+                : ` ORDER BY ${colSql("id")} ASC`;
+            const useOffset = !payload.cursor && offset > 0;
+            const offsetClause = useOffset ? ` OFFSET ${offset}` : "";
+            const whereClauseSqlText = whereSql.length > 0 ? ` WHERE ${whereSql.join(" AND ")}` : "";
+            // Project the resolved label too, so the keyset cursor below carries the
+            // value that was ordered by rather than the FK column's UUID.
+            const selectList = referenceSortExpr !== undefined && sortSql !== undefined
+                ? `*, ${sortSql} AS "${SORT_LABEL_ALIAS}"`
+                : "*";
+            const listSql = `SELECT ${selectList} FROM "${tableName}"${whereClauseSqlText}${orderByClause} LIMIT ${limit}${offsetClause}`;
+            const rawRows = await executeRawQueryRead(runner, listSql, params);
+            const lastSortLabel = rawRows[rawRows.length - 1]?.[SORT_LABEL_ALIAS];
+            if (referenceSortExpr !== undefined) {
+                // The alias is a sort artifact, not a column of this entity — strip it
+                // before coercion so it never reaches the caller or the entity cache.
+                for (const row of rawRows)
+                    delete row[SORT_LABEL_ALIAS];
+            }
+            // Per-row read-side rehydrate + snake→camel coercion for driver-agnostic field names.
+            // Coerce BEFORE rehydrate/decrypt: the raw SELECT * 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).
+            const tableInfo = extractTableInfo(table);
+            const encryptedRows = rawRows.map((r) => rehydrateCompoundTypes(coerceRow(r, tableInfo), entity));
+            const rows = await Promise.all(encryptedRows.map((r) => decryptForRead(r)));
+            // list rows carry the READ-ROW version (display-only), never an optimistic-lock
+            // base — edit flows reload via detail(), which reconciles the stream version.
+            // Cache the still-encrypted form: same at-rest guarantee as detail()'s
+            // encryptForStorage round-trip, without paying a re-encrypt.
+            if (entityCache && entityName && rows.length > 0) {
+                await entityCache.mset(user.tenantId, entityName, encryptedRows.map((r) => ({ id: r["id"], data: r })));
+            }
+            const lastRow = rows[rows.length - 1];
+            const lastRaw = rawRows[rawRows.length - 1];
+            let nextCursor = null;
+            if (rows.length === limit && lastRow && lastRaw) {
+                const cursorId = lastRow["id"]; // @cast-boundary engine-payload
+                const sortText = sortField === undefined
+                    ? undefined
+                    : toCursorSortText(referenceSortExpr !== undefined ? lastSortLabel : lastRaw[physicalCol(sortField)]);
+                nextCursor =
+                    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.
+            // On the search path, `total = filterIds.length` needs no extra query —
+            // unless a reference match contributed additional rows (fw#2660), or the
+            // WHERE grew past the search block (ownership, parent-ref, filters,
+            // soft-delete, cursor all splice in afterwards), in which case the raw
+            // filterIds length alone would undercount.
+            let total;
+            if (totalCount) {
+                if (filterIds && !referenceClauseActive && whereSql.length === whereSqlLenAfterSearch) {
+                    total = filterIds.length;
+                }
+                else {
+                    const countSql = `SELECT COUNT(*)::int AS count FROM "${tableName}"${whereClauseSqlText}`;
+                    const countRows = await executeRawQueryRead(runner, countSql, whereParams);
+                    total = countRows[0]?.count ?? 0;
+                }
+            }
+            return { rows, nextCursor, ...(total !== undefined && { total }) };
+        },
+        async detail(payload, user, db, options) {
+            const tableName = String(table[KUMIKO_NAME_SYMBOL]);
+            // H.2 — ownership check, AND-ed with the parent-ref read-gate (see
+            // db/parent-ref-clause.ts). `empty` → the user can never see this row
+            // regardless of its id. Return null (same shape as "not found", so a
+            // probing attacker can't distinguish "no access" from "doesn't exist").
+            const parentClause = buildParentRefClause(entity, table, tableName, user, db, options?.parentVisibility, { includeDeleted: false, narrowTypes: undefined });
+            const ownership = combineClauses(buildOwnershipClause(user, entity.access?.read, table), parentClause);
+            if (ownership.kind === "empty")
+                return null;
+            const idWhere = idFilter(payload.id);
+            // Stream-version authoritative (same policy as update/Block 0):
+            // ctx.appendEvent (lifecycle-writes like incident:post-update) bumps
+            // the stream WITHOUT touching row.version — a detail-read that hands
+            // out the stale row.version dooms the next CRUD update built on it
+            // (entityEdit loads detail.version as its optimistic-lock base) to a
+            // guaranteed version_conflict.
+            const withStreamVersion = async (row) => {
+                const streamVersion = await getStreamVersion(tenantDbRunner(db), String(payload.id), streamTenantFor(user));
+                return streamVersion > 0 ? { ...row, version: streamVersion } : row;
+            };
+            if (entityCache && entityName) {
+                const cached = await entityCache.get(user.tenantId, entityName, payload.id);
+                if (cached) {
+                    if (ownership.kind === "sql") {
+                        // Re-check ownership predicate (incl. the parent-ref gate) against
+                        // the live row — the cache is keyed only by tenant + id, not by
+                        // role, so a cache hit can't bypass either gate. Deliberate price:
+                        // one extra roundtrip per cache hit once either gate produces SQL.
+                        const checkRows = await loadWithOwnership(db, idWhere, ownership);
+                        if (checkRows.length === 0)
+                            return null;
+                    }
+                    // Cached rows are stored re-encrypted (see the `set` below) so an
+                    // `encrypted` field's plaintext never sits in a second at-rest
+                    // store (Redis) the field-encryption feature doesn't cover.
+                    return withStreamVersion(await decryptForRead(cached));
+                }
+            }
+            const rows = await loadWithOwnership(db, idWhere, ownership);
+            const raw = rows[0];
+            if (!raw)
+                return null;
+            // Same coerce-before-rehydrate/decrypt ordering as list() above — raw
+            // is snake_case only on the ownership.kind==="sql" branch (raw SQL);
+            // coerceRow is a no-op on the already-camelCase "pass" branch rows.
+            const rowInfo = extractTableInfo(table);
+            const coerced = await decryptForRead(rehydrateCompoundTypes(coerceRow(raw, rowInfo), entity));
+            if (entityCache && entityName) {
+                await entityCache.set(user.tenantId, entityName, payload.id, await encryptForStorage(coerced, user));
+            }
+            return withStreamVersion(coerced);
+        },
+    };
+}