@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/src/db/event-store-executor-read.ts

@@ -1,916 +0,0 @@
-import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
-import { collectPiiSubjectFields, computeBlindIndex, configuredBlindIndexKey } from "../crypto";
-import { escapeLikePattern } from "../crypto/ciphertext-pattern";
-import { executeRawQueryRead } from "../db/queries/raw-sql";
-import { coerceRow, extractTableInfo } from "../db/query";
-import {
-  buildOwnershipClause,
-  combineClauses,
-  normalizeAccessEntry,
-  shiftParams,
-} from "../engine/ownership";
-import type { EntityDefinition, EntityId, SessionUser } from "../engine/types";
-import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
-import { UnprocessableError } from "../errors";
-import { getStreamVersion } from "../event-store";
-import type { SearchAdapter } from "../search/types";
-import { LIST_ROW_META_REFERENCES } from "../ui-types/list-row-meta";
-import { rehydrateCompoundTypes } from "./compound-types";
-import { decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor";
-import {
-  collectEncryptedFieldNames,
-  hasSearchablePlaintext,
-  isSensitiveLabelField,
-} from "./entity-field-encryption";
-import type { EventStoreExecutor } from "./event-store-executor";
-import { buildFilterWhere, type ExecutorContext, type Table } from "./event-store-executor-context";
-import { buildParentRefClause } from "./parent-ref-clause";
-import { buildEntityTable, physicalColumnName } from "./table-builder";
-import type { TenantDb, TenantDbMode } from "./tenant-db";
-import { tenantDbRunner } from "./tenant-db-runner";
-
-// 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: {
-  readonly limit?: unknown;
-  readonly offset?: unknown;
-}): { readonly limit: number; readonly offset: number } {
-  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: unknown): string | null | undefined {
-  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 as { [Symbol.toStringTag]?: unknown })[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: string,
-  idCol: string,
-  cursor: { readonly id: string; readonly sortValue: string | null },
-  descending: boolean,
-  params: unknown[],
-): string {
-  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})`;
-}
-
-type ListFilter = {
-  readonly field: string;
-  readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
-  readonly value: unknown;
-};
-
-// 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: (field: string) => string,
-  whereSql: string[],
-  params: unknown[],
-  f: ListFilter,
-): void {
-  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: Table,
-  colSql: (field: string) => string,
-  whereSql: string[],
-  params: unknown[],
-  f: ListFilter,
-): void {
-  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 as Record<string, unknown>;
-      if (valueObj["ne"] === null && Object.keys(valueObj).length === 1) {
-        whereSql.push(`${colSql(field)} IS NOT NULL`);
-        continue;
-      }
-      const opMap: Record<string, string> = {
-        gt: ">",
-        gte: ">=",
-        lt: "<",
-        lte: "<=",
-        ne: "<>",
-      };
-      for (const [opKey, opSym] of Object.entries(opMap)) {
-        if (!(opKey in value)) continue;
-        params.push((value as Record<string, unknown>)[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: EntityDefinition,
-  payload: { readonly filter?: ListFilter; readonly filters?: readonly ListFilter[] },
-): ReadonlySet<string> | undefined {
-  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: Set<string> | undefined;
-  for (const f of typeFilters) {
-    let values: readonly string[] | undefined;
-    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;
-
-type ReferenceSearchDescriptor = {
-  readonly ownColumn: string;
-  readonly targetEntityName: string;
-  readonly labelField: string;
-};
-
-// 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: Table,
-  referenceSearch: NonNullable<Parameters<EventStoreExecutor["list"]>[3]>["referenceSearch"],
-  dbMode: TenantDbMode,
-): readonly ReferenceSearchDescriptor[] {
-  if (!referenceSearch) return [];
-  const descriptors: ReferenceSearchDescriptor[] = 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: ReferenceSearchDescriptor,
-  searchTerm: string,
-  targetTable: Table,
-  targetTableName: string,
-  db: TenantDb,
-): Promise<{ readonly ownColumn: string; readonly ids: readonly string[] } | undefined> {
-  const labelCol = physicalColumnName(targetTable, descriptor.labelField);
-  const subParams: unknown[] = [`%${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<{ id: string }>(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: ReferenceSearchDescriptor,
-  searchTerm: string,
-  targetEntity: EntityDefinition,
-  targetTable: Table,
-  targetTableName: string,
-  user: SessionUser,
-  db: TenantDb,
-  searchAdapter: SearchAdapter,
-): Promise<{ readonly ownColumn: string; readonly ids: readonly string[] } | undefined> {
-  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: unknown[] = [...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<{ id: string }>(tenantDbRunner(db), sql, params);
-  if (rows.length === 0) return undefined;
-  return { ownColumn: descriptor.ownColumn, ids: rows.map((r) => r.id) };
-}
-
-async function resolveReferenceMatches(
-  descriptor: ReferenceSearchDescriptor,
-  searchTerm: string,
-  resolveEntity: (entityName: string) => EntityDefinition | undefined,
-  db: TenantDb,
-  user: SessionUser,
-  searchAdapter: SearchAdapter,
-): Promise<{ readonly ownColumn: string; readonly ids: readonly string[] } | undefined> {
-  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 as unknown as Record<symbol, unknown>)[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: string,
-  ownColumnSql: string,
-  descriptor: { readonly targetEntityName: string; readonly labelField: string },
-  resolveEntity: (entityName: string) => EntityDefinition | undefined,
-  db: TenantDb,
-): ((params: unknown[]) => string) | undefined {
-  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 as unknown as Record<symbol, unknown>)[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: unknown[]): string => {
-    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: ExecutorContext): Pick<EventStoreExecutor, "list" | "detail"> {
-  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 as unknown as Record<symbol, unknown>)[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: EntityId[] | undefined;
-      // 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: string[] = [];
-      const params: unknown[] = [];
-      const physicalCol = (field: string): string => physicalColumnName(table, field);
-      const colSql = (field: string): string => `"${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: string) =>
-        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 is { readonly ownColumn: string; readonly ids: readonly string[] } =>
-                m !== undefined,
-            )
-          : [];
-
-        if (filterIds.length === 0 && referenceMatches.length === 0) {
-          return { rows: [], nextCursor: null, ...(totalCount && { total: 0 }) };
-        }
-
-        const orParts: string[] = [];
-        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: string | undefined;
-      let referenceSortExpr: ((params: unknown[]) => string) | undefined;
-      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: ListFilter): void => {
-        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<Record<string, unknown>>(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"] as EntityId, data: r })), // @cast-boundary engine-payload
-        );
-      }
-
-      const lastRow = rows[rows.length - 1];
-      const lastRaw = rawRows[rawRows.length - 1];
-      let nextCursor: string | null = null;
-      if (rows.length === limit && lastRow && lastRaw) {
-        const cursorId = lastRow["id"] as string; // @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: number | undefined;
-      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<{ count: number }>(
-            runner,
-            countSql,
-            whereParams,
-          );
-          total = countRows[0]?.count ?? 0;
-        }
-      }
-
-      return { rows, nextCursor, ...(total !== undefined && { total }) };
-    },
-
-    async detail(payload, user, db, options) {
-      const tableName = String((table as unknown as Record<symbol, unknown>)[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: Record<string, unknown>,
-      ): Promise<Record<string, unknown>> => {
-        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);
-    },
-  };
-}