@cosmicdrift/kumiko-framework 0.353.0 → 0.354.1

package/dist/db/eagerload.js

@@ -1,34 +1,34 @@
-// Tier 2.7e Server-Side Eagerload für Reference-Felder.
+// Server-side eagerload for reference fields.
 //
-// Nach `executor.list`/`detail` scannen wir die zurückgelieferten
-// rows nach reference-Field-Values, sammeln pro Reference die UUIDs
-// (deduped), führen einen einzigen WHERE id IN (...)-Lookup pro
-// Referenced-Entity aus, und hängen die resolved Rows als
-// `_refs.<fieldName>` (single) bzw. `_refs.<fieldName>: Row[]`
-// (multiple) an die Original-Rows.
+// After `executor.list`/`detail` we scan the returned rows for reference
+// values, collect the UUIDs per reference (deduped), run one
+// WHERE id IN (...) lookup per referenced entity, and attach the resolved rows
+// as `_refs.<fieldName>` (single) or `_refs.<fieldName>: Row[]` (multiple).
 //
-// Tenant-Scope: TenantDb hat den Tenant-Filter eingebaut (mode:
-// "tenant"); der Lookup erbt das transparent. Cross-Feature-Refs
-// landen automatisch im selben Tenant — falls ein referenced Item
-// dem User nicht gehört, kommt es aus dem Lookup nicht zurück
-// (TenantDb filtert), und der Renderer fällt auf UUID zurück.
+// Access scope: `_refs` only returns what the viewer could read on the target
+// entity itself (tenant, access.read, parentRef gate, field-level read). An
+// unreadable ref is absent exactly like a missing one, so there is no
+// existence oracle; the renderer falls back to the UUID. The target detail
+// handler's handler-level `access` is not evaluated (same as reference
+// search/sort).
 //
-// Limit: kein expliziter limit auf den Lookup-SELECT — wir
-// fragen genau die UUIDs ab die in den main-Rows vorkommen, also
-// O(n) pro Page (bei pageSize:50 mit 2 ref-Spalten = max 100 IDs).
-// Render-Side limit:200-Workaround entfällt damit komplett.
+// No explicit limit on the lookup SELECT: it asks for exactly the UUIDs present
+// in the main rows, so it is O(n) per page.
 //
-// Diese Datei lebt im framework/db damit sie an einer Stelle
-// zwischen executor und entity-handlers gemounted ist; sie nutzt
-// keine framework-engine-Internals und kann auch von custom
-// query-handlern manuell aufgerufen werden.
+// Custom handlers must pass the viewer explicitly so the parentRef gate is
+// never skipped silently.
 import { requestContext } from "../api/request-context.js";
 import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, } from "../crypto/index.js";
 import { selectMany } from "../db/query.js";
-import { maskWriteOnlyFields } from "../engine/field-access.js";
+import { filterReadFields } from "../engine/field-access.js";
+import { buildOwnershipClause, combineClauses, shiftParams, tableNameOf, } from "../engine/ownership.js";
 import { parseRefTargetEntityName } from "../engine/parse-ref-target.js";
+import { isUuid, SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { collectEncryptedFieldNames, decryptEntityFieldValues, resolveEntityFieldEncryption, } from "./entity-field-encryption.js";
-import { buildEntityTable } from "./table-builder.js";
+import { buildParentRefClause } from "./parent-ref-clause.js";
+import { executeRawQueryRead } from "./queries/raw-sql.js";
+import { buildEntityTable, physicalColumnName } from "./table-builder.js";
+import { tenantDbRunner } from "./tenant-db-runner.js";
 function isReferenceField(field) {
     return field.type === "reference";
 }
@@ -46,43 +46,12 @@ export function collectReferenceFields(entity) {
     return out;
 }
 // Referenced rows are read via a raw selectMany, not the referenced entity's
-// own executor context (enrichWithReferences only gets an
-// EagerLoadEntityResolver — routing through buildExecutorContext per ref
-// would need table/searchAdapter/entityCache wiring for no reason). Mirrors
+// own executor context (that would need table/searchAdapter/entityCache wiring
+// per ref). Access is enforced separately by readableRefIds. Mirrors
 // event-store-executor-context's decryptForRead ordering: PII is the outer
 // layer, peel it before the envelope-encrypted fields, or the envelope
 // cipher chokes on a still-PII-wrapped string.
-//
-// Ownership guard (fw#1671): the ref lookup below is tenant-scoped only, not
-// ownership-scoped — this function has no SessionUser to evaluate
-// refEntity.access.read against. If the ref entity declares row-level
-// ownership at all, decrypting here would hand a same-tenant User A the
-// plaintext PII of a User B row they merely reference (e.g. a freely-settable
-// reference UUID), even though refEntity.access.read says "own" — the caller
-// never gets to run that ownership check. Fail closed: strip PII/encrypted
-// fields entirely instead of decrypting (or leaking ciphertext) when that
-// guarantee can't be evaluated here.
-function hasOwnershipScopedRead(refEntity) {
-    const readMap = refEntity.access?.read;
-    if (readMap === undefined)
-        return false;
-    // "all" means that role sees every row unrestricted — a map where every
-    // rule is "all" carries no ownership restriction at all, so stripping
-    // here would just silently drop PII/encrypted fields #1667 wants
-    // decrypted, for no security benefit.
-    return Object.values(readMap).some((rule) => rule !== "all");
-}
-async function decryptReferencedRow(row, refEntity, piiFields, encryptedFields, kms) {
-    if (hasOwnershipScopedRead(refEntity)) {
-        if (piiFields.length === 0 && encryptedFields.size === 0)
-            return row;
-        const out = { ...row };
-        for (const field of piiFields)
-            delete out[field];
-        for (const field of encryptedFields)
-            delete out[field];
-        return out;
-    }
+async function decryptReferencedRow(row, piiFields, encryptedFields, kms) {
     let out = row;
     if (piiFields.length > 0 && kms) {
         out = await decryptPiiFieldValues(out, piiFields, kms, {
@@ -94,20 +63,45 @@ async function decryptReferencedRow(row, refEntity, piiFields, encryptedFields,
     }
     return out;
 }
+// One probe query per ref field: the ids the viewer may read on the target
+// entity. Raw SQL because ownership/parentRef clauses are SQL fragments; the
+// table is unaliased since where-rules qualify columns with the table name.
+async function resolveRefAccessScope(refEntity, refTable, refTableName, ids, db, viewer) {
+    const access = combineClauses(buildOwnershipClause(viewer.user, refEntity.access?.read, refTable), buildParentRefClause(refEntity, refTable, refTableName, viewer.user, db, viewer.parentVisibility, {
+        includeDeleted: false,
+    }));
+    if (access.kind === "empty")
+        return { kind: "none" };
+    if (access.kind === "pass")
+        return { kind: "unrestricted" };
+    // No read path exists for non-uuid ids, so nothing can be access-checked.
+    if (refEntity.idType !== undefined && refEntity.idType !== "uuid")
+        return { kind: "none" };
+    const params = [ids];
+    let tenantClause = "";
+    if (refTable["tenantId"] !== undefined && db.mode === "tenant") {
+        params.push(db.tenantId, SYSTEM_TENANT_ID);
+        tenantClause = ` AND "${physicalColumnName(refTable, "tenantId")}" IN ($2, $3)`;
+    }
+    const shifted = shiftParams({ sqlText: access.sqlText, params: access.params }, params.length);
+    params.push(...shifted.params);
+    const rows = await executeRawQueryRead(tenantDbRunner(db), `SELECT "id" FROM "${refTableName}" WHERE "id" = ANY($1::uuid[])${tenantClause} AND ${shifted.sqlText}`, params);
+    return { kind: "restricted", readableIds: new Set(rows.map((r) => r.id)) };
+}
 // Per-row, not Promise.all: a single legacy/backfilled row without a valid
 // envelope (decryptEntityFieldValues throws hard on malformed ciphertext)
 // must not 500 the whole list request — the main rows the caller asked for
 // are unrelated to this one broken reference. Drop just that row from the
 // map; the renderer falls back to the raw UUID.
 //
-// piiFields/encryptedFields/kms are constant per refEntity (fw#1671) — the
+// piiFields/encryptedFields/kms are constant per refEntity — the
 // caller computes them once and passes them in instead of recomputing per row.
-async function buildRefLookupMap(rawRefRows, refEntity, refEntityName, piiFields, encryptedFields, kms) {
+async function buildRefLookupMap(rawRefRows, refEntity, refEntityName, viewer, piiFields, encryptedFields, kms) {
     const map = new Map();
     for (const r of rawRefRows) {
         let decrypted;
         try {
-            decrypted = await decryptReferencedRow(r, refEntity, piiFields, encryptedFields, kms);
+            decrypted = await decryptReferencedRow(r, piiFields, encryptedFields, kms);
         }
         catch (e) {
             console.warn(`[eagerload] failed to decrypt referenced row entity=${refEntityName} id=${String(r["id"])}: ${e instanceof Error ? e.message : String(e)}`);
@@ -115,13 +109,25 @@ async function buildRefLookupMap(rawRefRows, refEntity, refEntityName, piiFields
         }
         const id = decrypted["id"];
         if (typeof id === "string")
-            map.set(id, maskWriteOnlyFields(refEntity, decrypted));
+            map.set(id, filterReadFields(refEntity, decrypted, viewer.user));
     }
     return map;
 }
+function collectRefIds(rows, rf) {
+    const ids = new Set();
+    for (const row of rows) {
+        const v = row[rf.fieldName];
+        const values = rf.multiple ? (Array.isArray(v) ? v : []) : [v];
+        for (const item of values) {
+            if (typeof item === "string" && item.length > 0)
+                ids.add(item);
+        }
+    }
+    return ids;
+}
 /** Eagerload für eine Liste von Rows. Mutiert nicht — gibt eine
  *  flache Kopie der Rows mit hinzugefügtem `_refs`-Property zurück. */
-export async function enrichWithReferences(rows, entity, resolveEntity, db) {
+export async function enrichWithReferences(rows, entity, resolveEntity, db, viewer) {
     const refFields = collectReferenceFields(entity);
     if (refFields.length === 0 || rows.length === 0) {
         return rows.map((r) => ({ ...r }));
@@ -130,21 +136,7 @@ export async function enrichWithReferences(rows, entity, resolveEntity, db) {
     // einziger SELECT WHERE id IN (...). Maps werden parallel gebaut
     // damit die Lookups nicht serialisieren (Promise.all).
     const lookupMaps = await Promise.all(refFields.map(async (rf) => {
-        const ids = new Set();
-        for (const row of rows) {
-            const v = row[rf.fieldName];
-            if (rf.multiple) {
-                if (Array.isArray(v)) {
-                    for (const item of v) {
-                        if (typeof item === "string" && item.length > 0)
-                            ids.add(item);
-                    }
-                }
-            }
-            else if (typeof v === "string" && v.length > 0) {
-                ids.add(v);
-            }
-        }
+        const ids = collectRefIds(rows, rf);
         if (ids.size === 0)
             return { fieldName: rf.fieldName, multiple: rf.multiple, map: new Map() };
         const refEntity = resolveEntity(rf.refEntityName);
@@ -156,12 +148,24 @@ export async function enrichWithReferences(rows, entity, resolveEntity, db) {
             return { fieldName: rf.fieldName, multiple: rf.multiple, map: new Map() };
         }
         const refTable = buildEntityTable(rf.refEntityName, refEntity);
-        const idArray = [...ids];
-        const rawRefRows = (await selectMany(db, refTable, { id: idArray }));
+        const refTableName = tableNameOf(refTable);
+        const usesUuidIds = refEntity.idType === undefined || refEntity.idType === "uuid";
+        // A malformed ref value must not 500 the whole list via the uuid cast.
+        const idArray = usesUuidIds ? [...ids].filter(isUuid) : [...ids];
+        const emptyLookup = { fieldName: rf.fieldName, multiple: rf.multiple, map: new Map() };
+        if (idArray.length === 0)
+            return emptyLookup;
+        const scope = await resolveRefAccessScope(refEntity, refTable, refTableName, idArray, db, viewer);
+        if (scope.kind === "none")
+            return emptyLookup;
+        const lookedUpRows = (await selectMany(db, refTable, { id: idArray }));
+        const rawRefRows = scope.kind === "restricted"
+            ? lookedUpRows.filter((r) => scope.readableIds.has(String(r["id"])))
+            : lookedUpRows;
         const piiFields = collectPiiSubjectFields(refEntity);
         const encryptedFields = collectEncryptedFieldNames(refEntity);
         const kms = configuredPiiSubjectKms();
-        const map = await buildRefLookupMap(rawRefRows, refEntity, rf.refEntityName, piiFields, encryptedFields, kms);
+        const map = await buildRefLookupMap(rawRefRows, refEntity, rf.refEntityName, viewer, piiFields, encryptedFields, kms);
         return { fieldName: rf.fieldName, multiple: rf.multiple, map };
     }));
     return rows.map((row) => {
@@ -186,7 +190,7 @@ export async function enrichWithReferences(rows, entity, resolveEntity, db) {
     });
 }
 /** Single-Row-Variante für detail-Calls. */
-export async function enrichRowWithReferences(row, entity, resolveEntity, db) {
-    const enriched = await enrichWithReferences([row], entity, resolveEntity, db);
+export async function enrichRowWithReferences(row, entity, resolveEntity, db, viewer) {
+    const enriched = await enrichWithReferences([row], entity, resolveEntity, db, viewer);
     return enriched[0] ?? { ...row, _refs: {} };
 }

package/dist/db/event-store-executor-context.d.ts

@@ -34,6 +34,18 @@ export type ExecutorContext = {
         sqlText: string;
         params: readonly unknown[];
     }) => Promise<Record<string, unknown>[]>;
+    readonly loadDetailSnapshot: (db: TenantDb, idWhere: WhereObject, ownership: {
+        kind: "pass";
+    } | {
+        kind: "empty";
+    } | {
+        kind: "sql";
+        sqlText: string;
+        params: readonly unknown[];
+    }, streamTenantId: TenantId, aggregateId: string) => Promise<{
+        readonly row: Record<string, unknown> | null;
+        readonly streamVersion: number;
+    }>;
     readonly loadExpectSnapshot: (db: TenantDb, id: EntityId, streamTenantId: TenantId, expectKeys: readonly string[]) => Promise<{
         readonly row: Record<string, unknown> | null;
         readonly streamVersion: number;

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

@@ -1,10 +1,10 @@
 import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { requestContext } from "../api/request-context.js";
-import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, encryptPiiFieldValues, } from "../crypto/index.js";
+import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, encryptPiiFieldValues, KeyErasedError, } from "../crypto/index.js";
 import { executeRawQueryRead } from "../db/queries/raw-sql.js";
 import { shiftParams } from "../engine/ownership.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
-import { InternalError, UniqueViolationError, writeFailure, } from "../errors/index.js";
+import { InternalError, subjectErasedConflict, UniqueViolationError, writeFailure, } from "../errors/index.js";
 import { ArchivedStreamError, isStreamArchived } from "../event-store/index.js";
 import { assertUnreachable } from "../utils/index.js";
 import { rehydrateCompoundTypes } from "./compound-types.js";
@@ -175,12 +175,19 @@ export function buildExecutorContext(table, entity, options) {
         }
         const kms = piiKms();
         if (hasPiiFields && kms) {
-            out = await encryptPiiFieldValues(out, entity, piiSubjectFields, kms, kmsContextFor(user), {
-                tenantId: user.tenantId,
-                entityName,
-                ...(opts?.onlyKeys !== undefined && { onlyKeys: opts.onlyKeys }),
-                ...(opts?.subjectSource !== undefined && { subjectSource: opts.subjectSource }),
-            });
+            try {
+                out = await encryptPiiFieldValues(out, entity, piiSubjectFields, kms, kmsContextFor(user), {
+                    tenantId: user.tenantId,
+                    entityName,
+                    ...(opts?.onlyKeys !== undefined && { onlyKeys: opts.onlyKeys }),
+                    ...(opts?.subjectSource !== undefined && { subjectSource: opts.subjectSource }),
+                });
+            }
+            catch (e) {
+                if (e instanceof KeyErasedError)
+                    throw subjectErasedConflict(e);
+                throw e;
+            }
         }
         return out;
     }
@@ -264,6 +271,16 @@ export function buildExecutorContext(table, entity, options) {
         // ownership has raw SQL — splice it into a raw query alongside the
         // idFilter + tenant-filter that TenantDb would have added.
         const tableName = String(table[KUMIKO_NAME_SYMBOL]);
+        const { whereParts, params } = buildRawIdWhere(db, idWhere, ownership);
+        const sqlText = `SELECT * FROM "${tableName}" WHERE ${whereParts.join(" AND ")} LIMIT 1`;
+        return [
+            ...(await executeRawQueryRead(tenantDbRunner(db), sqlText, params)),
+        ];
+    }
+    // Tenant filter + idFilter + ownership predicate as raw SQL, mirroring what
+    // TenantDb.fetchOne/readWhere add. idFilter only yields `id` and a boolean
+    // `isDeleted`, so no null/IS NULL branch is needed.
+    function buildRawIdWhere(db, idWhere, ownership) {
         const colSql = (field) => `"${table[field]?.name ?? toSnakeCase(field)}"`;
         const whereParts = [];
         const params = [];
@@ -280,14 +297,38 @@ export function buildExecutorContext(table, entity, options) {
                 whereParts.push(`${colSql(field)} = $${params.length}`);
             }
         }
-        const shifted = shiftParams(ownership, params.length);
-        whereParts.push(shifted.sqlText);
-        for (const p of shifted.params)
-            params.push(p);
-        const sqlText = `SELECT * FROM "${tableName}" WHERE ${whereParts.join(" AND ")} LIMIT 1`;
-        return [
-            ...(await executeRawQueryRead(tenantDbRunner(db), sqlText, params)),
-        ];
+        if (ownership.kind === "sql") {
+            const shifted = shiftParams(ownership, params.length);
+            whereParts.push(shifted.sqlText);
+            for (const p of shifted.params)
+                params.push(p);
+        }
+        return { whereParts, params };
+    }
+    function streamVersionSubquerySql(aggregateIdParam, tenantIdParam) {
+        return (`(SELECT MAX("version") FROM "kumiko_events" WHERE "aggregate_id" = $${aggregateIdParam} ` +
+            `AND "tenant_id" = $${tenantIdParam}) AS "__streamVersion"`);
+    }
+    // Row and MAX(version) in ONE statement: two reads can pair a post-write
+    // version with a pre-write row, and update({version: detail.version}) would
+    // then pass the optimistic lock and overwrite the newer write (lost update).
+    async function loadDetailSnapshot(db, idWhere, ownership, streamTenantId, aggregateId) {
+        if (ownership.kind === "empty")
+            return { row: null, streamVersion: 0 };
+        const tableName = String(table[KUMIKO_NAME_SYMBOL]);
+        const { whereParts, params } = buildRawIdWhere(db, idWhere, ownership);
+        params.push(aggregateId, streamTenantId);
+        const sqlText = `SELECT *, ${streamVersionSubquerySql(params.length - 1, params.length)} ` +
+            `FROM "${tableName}" WHERE ${whereParts.join(" AND ")} LIMIT 1`;
+        const rows = await executeRawQueryRead(tenantDbRunner(db), sqlText, params);
+        const first = rows[0];
+        if (!first)
+            return { row: null, streamVersion: 0 };
+        const { __streamVersion, ...row } = first;
+        return {
+            row,
+            streamVersion: typeof __streamVersion === "number" ? __streamVersion : 0,
+        };
     }
     // Reads the `expect:` fields and the aggregate's MAX(version) in ONE statement:
     // projection rows are written after their event commits, so two reads can
@@ -323,8 +364,7 @@ export function buildExecutorContext(table, entity, options) {
         const streamAggregateIdx = params.length - 1;
         const streamTenantIdx = params.length;
         const sqlText = `SELECT ${selectCols.join(", ")}, ` +
-            `(SELECT MAX("version") FROM "kumiko_events" WHERE "aggregate_id" = $${streamAggregateIdx} ` +
-            `AND "tenant_id" = $${streamTenantIdx}) AS "__streamVersion" ` +
+            `${streamVersionSubquerySql(streamAggregateIdx, streamTenantIdx)} ` +
             `FROM "${tableName}" WHERE ${whereParts.join(" AND ")} LIMIT 1`;
         const rows = await executeRawQueryRead(tenantDbRunner(db), sqlText, params);
         const row = rows[0];
@@ -348,6 +388,7 @@ export function buildExecutorContext(table, entity, options) {
         loadById,
         assertStreamWritable,
         loadWithOwnership,
+        loadDetailSnapshot,
         loadExpectSnapshot,
         encryptForStorage,
         decryptForRead,

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

@@ -6,7 +6,7 @@ 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 { getStreamVersion, getStreamVersions } 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";
@@ -64,6 +64,9 @@ function toCursorSortText(value) {
     }
     return undefined;
 }
+function withStreamVersion(row, streamVersion) {
+    return streamVersion > 0 ? { ...row, version: streamVersion } : row;
+}
 // 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.
@@ -227,6 +230,12 @@ function deriveParentNarrowTypes(entity, payload) {
 // 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 (fw#2660) — both resolve a text
 // search term against a target row's label instead of the raw FK column.
@@ -312,16 +321,28 @@ async function resolveReferenceMatchesViaSearchIndex(descriptor, searchTerm, tar
     if (ownership.kind === "empty")
         return undefined;
     const candidateIds = results.map((r) => String(r.entityId));
-    if (ownership.kind === "pass") {
+    // 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}`);
-    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);
+    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;
@@ -374,7 +395,7 @@ const SORT_LABEL_ALIAS = "__kumiko_sort_label";
 // 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) {
+function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolveEntity, db, user) {
     const targetEntity = resolveEntity(descriptor.targetEntityName);
     if (targetEntity === undefined) {
         // skip: unknown target entity — registry inconsistency the boot-validator
@@ -391,6 +412,13 @@ function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolv
         return undefined;
     }
     const targetTable = buildEntityTable(descriptor.targetEntityName, targetEntity);
+    // The order of labels the viewer may not read would leak them bit by bit, same as the search path.
+    const labelAccess = buildOwnershipClause(user, normalizeAccessEntry(targetEntity.fields[descriptor.labelField]?.access?.read), targetTable);
+    if (labelAccess.kind !== "pass")
+        return undefined;
+    const ownership = buildOwnershipClause(user, targetEntity.access?.read, targetTable);
+    if (ownership.kind === "empty")
+        return undefined;
     const targetTableName = String(targetTable[KUMIKO_NAME_SYMBOL]);
     const labelCol = physicalColumnName(targetTable, descriptor.labelField);
     const tenantScoped = targetTable["tenantId"] !== undefined && db.mode === "tenant";
@@ -408,12 +436,19 @@ function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolv
             params.push(tenantId, SYSTEM_TENANT_ID);
             tenantClause = ` AND t."${tenantCol}" 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}`;
+        }
         return (`(SELECT t."${labelCol}" FROM "${targetTableName}" t ` +
-            `WHERE t."id" = "${outerTableName}".${ownColumnSql}${tenantClause}${deletedClause})`);
+            `WHERE t."id" = "${outerTableName}".${ownColumnSql}${tenantClause}${ownershipClause}${deletedClause})`);
     };
 }
 export function createReadVerbs(ctx) {
-    const { table, entity, entityName, entityCache, searchAdapter, softDelete, streamTenantFor, idFilter, loadWithOwnership, decryptForRead, encryptForStorage, } = ctx;
+    const { table, entity, entityName, entityCache, searchAdapter, softDelete, streamTenantFor, idFilter, loadWithOwnership, loadDetailSnapshot, decryptForRead, encryptForStorage, } = ctx;
     return {
         // list + detail are unchanged from crud-executor — projections are the
         // read-model and serve these queries directly.
@@ -453,6 +488,7 @@ export function createReadVerbs(ctx) {
             // ctx.searchAdapter erst zur Laufzeit weil createEventStoreExecutor
             // beim Definition-Time noch keinen Server-Context hat).
             const effectiveSearchAdapter = searchAdapter ?? runtimeOptions?.searchAdapter;
+            let searchTruncated = false;
             if (payload.search) {
                 const searchTerm = payload.search;
                 // #2032 — a search term with no adapter wired must fail loud, not
@@ -471,7 +507,9 @@ export function createReadVerbs(ctx) {
                 const searchTenantId = streamTenantFor(user);
                 const results = await effectiveSearchAdapter.search(searchTenantId, searchTerm, {
                     filterType: entityName,
+                    limit: MAX_SEARCH_CANDIDATE_IDS,
                 });
+                searchTruncated = results.length >= MAX_SEARCH_CANDIDATE_IDS;
                 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
@@ -522,7 +560,7 @@ export function createReadVerbs(ctx) {
                 const descriptor = referenceSort?.fields.find((f) => f.fieldName === sortCandidate);
                 referenceSortExpr =
                     referenceSort && descriptor
-                        ? buildReferenceSortExpr(tableName, colSql(sortCandidate), descriptor, referenceSort.resolveEntity, db)
+                        ? buildReferenceSortExpr(tableName, colSql(sortCandidate), descriptor, referenceSort.resolveEntity, db, user)
                         : undefined;
                 if (referenceSortExpr !== undefined)
                     sortField = sortCandidate;
@@ -626,11 +664,17 @@ export function createReadVerbs(ctx) {
             // 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.
+            const decryptedRows = await Promise.all(encryptedRows.map((r) => decryptForRead(r)));
+            // Stream version is authoritative (see detail()): ctx.appendEvent bumps the
+            // stream without touching row.version, so the raw row version would hand
+            // clients a stale optimistic-lock base. Rows without events keep theirs.
+            const streamVersions = decryptedRows.length > 0
+                ? await getStreamVersions(runner, decryptedRows.map((r) => String(r["id"])), streamTenantFor(user))
+                : new Map();
+            const rows = decryptedRows.map((r) => withStreamVersion(r, streamVersions.get(String(r["id"])) ?? 0));
+            // Cache the still-encrypted raw rows (read-row version): same at-rest guarantee as
+            // detail()'s encryptForStorage round-trip, without a re-encrypt; detail() rejects
+            // a cached version that differs from the stream.
             if (entityCache && entityName && rows.length > 0) {
                 await entityCache.mset(user.tenantId, entityName, encryptedRows.map((r) => ({ id: r["id"], data: r })));
             }
@@ -657,7 +701,12 @@ export function createReadVerbs(ctx) {
                 const countRows = await executeRawQueryRead(runner, countSql, whereParams);
                 total = countRows[0]?.count ?? 0;
             }
-            return { rows, nextCursor, ...(total !== undefined && { total }) };
+            return {
+                rows,
+                nextCursor,
+                ...(total !== undefined && { total }),
+                ...(searchTruncated && { searchTruncated: true }),
+            };
         },
         async detail(payload, user, db, options) {
             const tableName = String(table[KUMIKO_NAME_SYMBOL]);
@@ -676,10 +725,8 @@ export function createReadVerbs(ctx) {
             // 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;
-            };
+            // A cache hit only counts when its version equals the live stream version:
+            // a late entityCache.set() can resurrect an old row after the writer's del().
             if (entityCache && entityName) {
                 const cached = await entityCache.get(user.tenantId, entityName, payload.id);
                 if (cached) {
@@ -692,25 +739,28 @@ export function createReadVerbs(ctx) {
                         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 streamVersion = await getStreamVersion(tenantDbRunner(db), String(payload.id), streamTenantFor(user));
+                    if (!(streamVersion > 0 && cached["version"] !== streamVersion)) {
+                        // 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), streamVersion);
+                    }
                 }
             }
-            const rows = await loadWithOwnership(db, idWhere, ownership);
-            const raw = rows[0];
+            const snapshot = await loadDetailSnapshot(db, idWhere, ownership, streamTenantFor(user), String(payload.id));
+            const raw = snapshot.row;
             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.
+            // is snake_case (raw SQL); coerceRow maps it to camelCase.
             const rowInfo = extractTableInfo(table);
             const coerced = await decryptForRead(rehydrateCompoundTypes(coerceRow(raw, rowInfo), entity));
+            const result = withStreamVersion(coerced, snapshot.streamVersion);
             if (entityCache && entityName) {
-                await entityCache.set(user.tenantId, entityName, payload.id, await encryptForStorage(coerced, user));
+                await entityCache.set(user.tenantId, entityName, payload.id, await encryptForStorage(result, user));
             }
-            return withStreamVersion(coerced);
+            return result;
         },
     };
 }