@cosmicdrift/kumiko-framework 0.256.0 → 0.258.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.256.0",
+  "version": "0.258.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.256.0",
+    "@cosmicdrift/kumiko-types": "0.258.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.256.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.258.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/db/__tests__/parent-ref-clause.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, test } from "bun:test";
+import { createEntity, createTextField } from "../../engine/factories";
+import { combineClauses, from } from "../../engine/ownership";
+import type { EntityDefinition, SessionUser } from "../../engine/types";
+import { buildParentRefClause } from "../parent-ref-clause";
+import { buildEntityTable } from "../table-builder";
+import type { TenantDb } from "../tenant-db";
+
+const TENANT = "11111111-1111-4111-8111-111111111111";
+
+const user: SessionUser = {
+  id: "22222222-2222-4222-8222-222222222222",
+  tenantId: TENANT,
+  roles: ["TenantMember"],
+  claims: {},
+};
+
+// Only `mode` and `tenantId` are read by the clause builder.
+const tenantDb = { mode: "tenant", tenantId: TENANT } as unknown as TenantDb;
+const systemDb = { mode: "system", tenantId: TENANT } as unknown as TenantDb;
+
+const textField = () =>
+  createTextField({
+    required: true,
+    maxLength: 64,
+    personal: false,
+    reason: "technical_reference",
+  });
+
+const joinEntity = createEntity({
+  table: "read_test_joins",
+  fields: { entityType: textField(), entityId: textField() },
+  parentRef: { entityTypeField: "entityType", entityIdField: "entityId" },
+});
+
+function hostEntity(opts?: {
+  readonly access?: EntityDefinition["access"];
+  readonly softDelete?: boolean;
+  readonly idType?: "serial" | "uuid";
+  readonly parentRef?: EntityDefinition["parentRef"];
+}) {
+  return createEntity({
+    table: "read_test_hosts",
+    fields: { ownerId: textField(), entityType: textField(), entityId: textField() },
+    ...opts,
+  });
+}
+
+const joinTable = buildEntityTable("test-join", joinEntity);
+
+function build(
+  entities: ReadonlyMap<string, EntityDefinition> | undefined,
+  opts: { includeDeleted?: boolean; narrowTypes?: ReadonlySet<string>; db?: TenantDb } = {},
+) {
+  return buildParentRefClause(
+    joinEntity,
+    joinTable,
+    "read_test_joins",
+    user,
+    opts.db ?? tenantDb,
+    entities === undefined ? undefined : { entities },
+    {
+      ...(opts.includeDeleted !== undefined && { includeDeleted: opts.includeDeleted }),
+      ...(opts.narrowTypes !== undefined && { narrowTypes: opts.narrowTypes }),
+    },
+  );
+}
+
+describe("buildParentRefClause", () => {
+  test("an entity without parentRef is not gated", () => {
+    const plain = createEntity({ table: "read_plain", fields: { a: textField() } });
+    const clause = buildParentRefClause(
+      plain,
+      buildEntityTable("plain", plain),
+      "read_plain",
+      user,
+      tenantDb,
+      { entities: new Map([["host", hostEntity()]]) },
+      {},
+    );
+    expect(clause.kind).toBe("pass");
+  });
+
+  test("a raw executor call without the registry option stays ungated", () => {
+    expect(build(undefined).kind).toBe("pass");
+  });
+
+  test("no candidate at all denies every row", () => {
+    expect(build(new Map()).kind).toBe("empty");
+  });
+
+  test("a candidate whose read-ownership can never match is dropped, denying when it was the only one", () => {
+    // The role has a rule, but the column it names is not on the host — the
+    // ownership clause collapses to `empty`, so the branch cannot be satisfied.
+    const host = hostEntity({ access: { read: { TenantMember: from("user:id", "notAColumn") } } });
+    expect(build(new Map([["host", host]])).kind).toBe("empty");
+  });
+
+  test("a serial-id candidate is excluded — it has no event-store read path", () => {
+    const host = hostEntity({ idType: "serial" });
+    expect(build(new Map([["host", host]])).kind).toBe("empty");
+  });
+
+  test("a candidate that is itself a join row is excluded — no recursive gating", () => {
+    const host = hostEntity({
+      parentRef: { entityTypeField: "entityType", entityIdField: "entityId" },
+    });
+    expect(build(new Map([["host", host]])).kind).toBe("empty");
+  });
+
+  test("narrowTypes restricts the OR-chain to the named hosts", () => {
+    const entities = new Map([
+      ["host", hostEntity()],
+      ["other", hostEntity()],
+      ["third", hostEntity()],
+    ]);
+    const all = build(entities);
+    const narrowed = build(entities, { narrowTypes: new Set(["other"]) });
+    if (all.kind !== "sql" || narrowed.kind !== "sql") throw new Error("expected sql clauses");
+    expect(all.sqlText.split(" OR ")).toHaveLength(3);
+    expect(narrowed.sqlText.split(" OR ")).toHaveLength(1);
+    expect(narrowed.params).toContain("other");
+    expect(narrowed.params).not.toContain("host");
+  });
+
+  test("the host's soft-delete filter applies by default and lifts under includeDeleted", () => {
+    const entities = new Map([["host", hostEntity({ softDelete: true })]]);
+    const gated = build(entities);
+    const trash = build(entities, { includeDeleted: true });
+    if (gated.kind !== "sql" || trash.kind !== "sql") throw new Error("expected sql clauses");
+    expect(gated.sqlText).toContain('"is_deleted" = FALSE');
+    expect(trash.sqlText).not.toContain("is_deleted");
+  });
+
+  test("the host id is matched through a shape guard, so a foreign id form cannot raise 22P02", () => {
+    const clause = build(new Map([["host", hostEntity()]]));
+    if (clause.kind !== "sql") throw new Error("expected sql clause");
+    expect(clause.sqlText).toContain("CASE WHEN");
+    expect(clause.sqlText).toContain("::uuid");
+    // The shape itself is bound, never inlined — a literal carrying `$` would
+    // be rewritten by shiftParams when the clause is combined.
+    expect(clause.params[0]).toBe("^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$");
+    expect(clause.sqlText).not.toContain("[0-9a-f]");
+  });
+
+  test("the tenant predicate is bound once and reused across branches", () => {
+    const entities = new Map([
+      ["host", hostEntity()],
+      ["other", hostEntity()],
+    ]);
+    const clause = build(entities);
+    if (clause.kind !== "sql") throw new Error("expected sql clause");
+    expect(clause.params.filter((p) => p === TENANT)).toHaveLength(1);
+    // uuid shape + 2 tenant params + one host-name param per branch.
+    expect(clause.params).toHaveLength(5);
+  });
+
+  test("a system-mode db drops the tenant predicate, mirroring list()", () => {
+    const clause = build(new Map([["host", hostEntity()]]), { db: systemDb });
+    if (clause.kind !== "sql") throw new Error("expected sql clause");
+    expect(clause.sqlText).not.toContain("tenant_id");
+    expect(clause.params).not.toContain(TENANT);
+  });
+
+  test("a dropped branch reserves no placeholder — every $N still binds its own value", () => {
+    // First candidate collapses to `empty` (column missing on the host), so its
+    // tentatively-reserved indices must not leave a gap for the second.
+    const entities = new Map([
+      [
+        "dropped",
+        hostEntity({ access: { read: { TenantMember: from("user:id", "notAColumn") } } }),
+      ],
+      ["kept", hostEntity({ access: { read: { TenantMember: from("user:id", "ownerId") } } })],
+    ]);
+    const clause = build(entities);
+    if (clause.kind !== "sql") throw new Error("expected sql clause");
+
+    const indices = [...clause.sqlText.matchAll(/\$(\d+)/g)].map((m) => Number(m[1]));
+    expect(Math.max(...indices)).toBeLessThanOrEqual(clause.params.length);
+    expect(Math.min(...indices)).toBeGreaterThanOrEqual(1);
+
+    // The kept branch's host-name param must sit at the placeholder the SQL
+    // actually names for it, not one slot over.
+    const keptSlot = clause.params.indexOf("kept") + 1;
+    expect(keptSlot).toBeGreaterThan(0);
+    expect(clause.sqlText).toContain(`"entity_type" = $${keptSlot}`);
+    expect(clause.params).toContain(user.id);
+    expect(clause.params).not.toContain("dropped");
+  });
+});
+
+describe("combineClauses", () => {
+  const sqlA = { kind: "sql", sqlText: '"a" = $1', params: ["av"] } as const;
+  const sqlB = { kind: "sql", sqlText: '"b" = $1 OR "c" = $2', params: ["bv", "cv"] } as const;
+
+  test("empty on either side denies", () => {
+    expect(combineClauses({ kind: "empty" }, sqlA).kind).toBe("empty");
+    expect(combineClauses(sqlA, { kind: "empty" }).kind).toBe("empty");
+  });
+
+  test("pass is neutral", () => {
+    expect(combineClauses({ kind: "pass" }, sqlA)).toEqual(sqlA);
+    expect(combineClauses(sqlA, { kind: "pass" })).toEqual(sqlA);
+    expect(combineClauses({ kind: "pass" }, { kind: "pass" }).kind).toBe("pass");
+  });
+
+  test("the second clause's placeholders are shifted past the first's params", () => {
+    const combined = combineClauses(sqlA, sqlB);
+    if (combined.kind !== "sql") throw new Error("expected sql clause");
+    expect(combined.sqlText).toBe('("a" = $1 AND "b" = $2 OR "c" = $3)');
+    expect(combined.params).toEqual(["av", "bv", "cv"]);
+  });
+});

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

@@ -3,7 +3,12 @@ import { collectPiiSubjectFields, computeBlindIndex, configuredBlindIndexKey } f
 import { escapeLikePattern } from "../crypto/ciphertext-pattern";
 import { executeRawQueryRead } from "../db/queries/raw-sql";
 import { coerceRow, extractTableInfo } from "../db/query";
-import { buildOwnershipClause, normalizeAccessEntry, shiftParams } from "../engine/ownership";
+import {
+  buildOwnershipClause,
+  combineClauses,
+  normalizeAccessEntry,
+  shiftParams,
+} from "../engine/ownership";
 import type { EntityDefinition, EntityId } from "../engine/types";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
 import { UnprocessableError } from "../errors";
@@ -14,7 +19,8 @@ import { decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor";
 import { collectEncryptedFieldNames } from "./entity-field-encryption";
 import type { EventStoreExecutor } from "./event-store-executor";
 import { buildFilterWhere, type ExecutorContext, type Table } from "./event-store-executor-context";
-import { buildEntityTable, toSnakeCase } from "./table-builder";
+import { buildParentRefClause } from "./parent-ref-clause";
+import { buildEntityTable, physicalColumnName } from "./table-builder";
 import type { TenantDb, TenantDbMode } from "./tenant-db";
 
 // The two read verbs (list/detail) of the event-store-executor. Split out
@@ -204,16 +210,51 @@ function applyScreenFilter(
   }
 }
 
+// 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;
 
-function physicalColumnName(table: Table, field: string): string {
-  return (table[field] as { name?: string } | undefined)?.name ?? toSnakeCase(field);
-}
-
 type ReferenceSearchDescriptor = {
   readonly ownColumn: string;
   readonly targetEntityName: string;
@@ -384,11 +425,27 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
     async list(payload, user, db, runtimeOptions) {
       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. 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 ownership = buildOwnershipClause(user, entity.access?.read, table);
+      // 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 }) };
       }
@@ -401,7 +458,6 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
       // 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 tableName = String((table as unknown as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL]);
       const whereSql: string[] = [];
       const params: unknown[] = [];
       const physicalCol = (field: string): string => physicalColumnName(table, field);
@@ -493,6 +549,10 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
         // 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"
@@ -664,11 +724,13 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
       // 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), in
-      // which case the raw filterIds length alone would undercount.
+      // 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) {
+        if (filterIds && !referenceClauseActive && whereSql.length === whereSqlLenAfterSearch) {
           total = filterIds.length;
         } else {
           const countSql = `SELECT COUNT(*)::int AS count FROM "${tableName}"${whereClauseSqlText}`;
@@ -684,11 +746,25 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
       return { rows, nextCursor, ...(total !== undefined && { total }) };
     },
 
-    async detail(payload, user, db) {
-      // H.2 — ownership check. `empty` → the user can never see this row
+    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 ownership = buildOwnershipClause(user, entity.access?.read, table);
+      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);
@@ -714,8 +790,10 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
         const cached = await entityCache.get(user.tenantId, entityName, payload.id);
         if (cached) {
           if (ownership.kind === "sql") {
-            // Re-check ownership predicate against the live row — the cache
-            // is keyed only by tenant + id, not by role.
+            // 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;
           }

package/src/db/parent-ref-clause.ts

@@ -0,0 +1,182 @@
+import type { ParentVisibilityOption } from "@cosmicdrift/kumiko-types/event-store-executor-types";
+import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { buildOwnershipClause, type OwnershipClause } from "../engine/ownership";
+import type { EntityDefinition, SessionUser } from "../engine/types";
+import { SYSTEM_TENANT_ID, UUID_SHAPE_PATTERN } from "../engine/types/identifiers";
+import type { Table } from "./event-store-executor-context";
+import { buildEntityTable, physicalColumnName } from "./table-builder";
+import type { TenantDb } from "./tenant-db";
+
+export type { ParentVisibilityOption } from "@cosmicdrift/kumiko-types/event-store-executor-types";
+
+// Static, per-candidate SQL fragments (table name + physical column names) —
+// derived from the entity definition alone, so they're the same on every
+// request. buildEntityTable is too expensive to redo per request per
+// candidate, hence the cache keyed by the entity object itself.
+type CandidateStatics = {
+  readonly table: Table;
+  readonly tableName: string;
+  readonly tenantIdCol: string | undefined;
+  readonly isDeletedCol: string | undefined;
+};
+
+const candidateStaticsCache = new WeakMap<EntityDefinition, CandidateStatics>();
+
+function candidateStaticsFor(candidateName: string, candidate: EntityDefinition): CandidateStatics {
+  const cached = candidateStaticsCache.get(candidate);
+  if (cached) return cached;
+  const table = buildEntityTable(candidateName, candidate);
+  const tableName = String((table as unknown as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL]);
+  const statics: CandidateStatics = {
+    table,
+    tableName,
+    tenantIdCol:
+      table["tenantId"] !== undefined ? physicalColumnName(table, "tenantId") : undefined,
+    isDeletedCol:
+      table["isDeleted"] !== undefined ? physicalColumnName(table, "isDeleted") : undefined,
+  };
+  candidateStaticsCache.set(candidate, statics);
+  return statics;
+}
+
+// Candidate order follows `option.entities` (Registry insertion order) —
+// deterministic given a fixed feature-registration order.
+function selectCandidates(
+  parentRef: NonNullable<EntityDefinition["parentRef"]>,
+  option: ParentVisibilityOption,
+  narrowTypes: ReadonlySet<string> | undefined,
+): ReadonlyArray<readonly [string, EntityDefinition]> {
+  const candidates: Array<readonly [string, EntityDefinition]> = [];
+  for (const [name, candidate] of option.entities) {
+    if (parentRef.allowedTypes && !parentRef.allowedTypes.includes(name)) continue;
+    if (narrowTypes && !narrowTypes.has(name)) continue;
+    // No recursive gating — a host that is itself a join-row entity would
+    // need its own visibility resolved first, which this function doesn't do.
+    if (candidate.parentRef !== undefined) continue;
+    // event-store-executor-context.ts rejects non-uuid idType at executor
+    // build time, so there is no read path to check such a candidate against.
+    if (candidate.idType !== undefined && candidate.idType !== "uuid") continue;
+    candidates.push([name, candidate]);
+  }
+  return candidates;
+}
+
+export function buildParentRefClause(
+  entity: EntityDefinition,
+  table: Table,
+  tableName: string,
+  user: SessionUser,
+  db: TenantDb,
+  option: ParentVisibilityOption | undefined,
+  opts: {
+    readonly includeDeleted?: boolean;
+    readonly narrowTypes?: ReadonlySet<string>;
+  },
+): OwnershipClause {
+  const parentRef = entity.parentRef;
+  if (parentRef === undefined) return { kind: "pass" };
+  // The raw executor stays ungated when no registry is available — the
+  // fail-closed guarantee for client-reachable paths comes from the boot
+  // guard (validateParentRefs), not from throwing here. Throwing would 500
+  // every existing custom handler and framework-internal detail() call that
+  // doesn't pass parentVisibility.
+  if (option === undefined) return { kind: "pass" };
+
+  if (
+    entity.fields[parentRef.entityTypeField] === undefined ||
+    entity.fields[parentRef.entityIdField] === undefined
+  ) {
+    // Misconfigured parentRef — fail closed here; the boot guard catches
+    // this earlier for any entity the registry actually validates.
+    return { kind: "empty" };
+  }
+  const typeCol = physicalColumnName(table, parentRef.entityTypeField);
+  const idCol = physicalColumnName(table, parentRef.entityIdField);
+
+  const candidates = selectCandidates(parentRef, option, opts.narrowTypes);
+  if (candidates.length === 0) return { kind: "empty" };
+
+  // The uuid shape and the tenant ids are bound once and shared by every
+  // branch. The shape is a parameter rather than a literal because shiftParams
+  // rewrites `$<digits>` anywhere in the text, including inside a string.
+  const params: unknown[] = [UUID_SHAPE_PATTERN];
+  const uuidIdx = params.length;
+  let tenantIdx: readonly [number, number] | undefined;
+  if (db.mode === "tenant") {
+    params.push(db.tenantId, SYSTEM_TENANT_ID);
+    tenantIdx = [params.length - 1, params.length];
+  }
+
+  const branches: string[] = [];
+  for (const [candidateName, candidate] of candidates) {
+    const branch = buildCandidateBranch(candidateName, candidate, user, {
+      joinTableName: tableName,
+      typeCol,
+      idCol,
+      uuidIdx,
+      tenantIdx,
+      includeDeleted: opts.includeDeleted === true,
+      // Ownership params are laid out right after the branch's own host-type
+      // placeholder. Nothing reaches the shared `params` until the branch is
+      // kept, so a dropped branch reserves no index and can't shift the
+      // positional binding of the branches after it.
+      typeParamIdx: params.length + 1,
+    });
+    if (branch === undefined) continue;
+    params.push(candidateName, ...branch.params);
+    branches.push(branch.sqlText);
+  }
+
+  if (branches.length === 0) return { kind: "empty" };
+  return { kind: "sql", sqlText: `(${branches.join(" OR ")})`, params };
+}
+
+type BranchContext = {
+  readonly joinTableName: string;
+  readonly typeCol: string;
+  readonly idCol: string;
+  readonly uuidIdx: number;
+  readonly tenantIdx: readonly [number, number] | undefined;
+  readonly includeDeleted: boolean;
+  readonly typeParamIdx: number;
+};
+
+// One `entity_type = $n AND EXISTS (...)` arm, or undefined when the host's own
+// read ownership can never match — an unsatisfiable arm is dropped rather than
+// emitted, which is what keeps an unreadable host from widening the OR-chain.
+function buildCandidateBranch(
+  candidateName: string,
+  candidate: EntityDefinition,
+  user: SessionUser,
+  ctx: BranchContext,
+): { readonly sqlText: string; readonly params: readonly unknown[] } | undefined {
+  const statics = candidateStaticsFor(candidateName, candidate);
+  const ownership = buildOwnershipClause(
+    user,
+    candidate.access?.read,
+    statics.table,
+    ctx.typeParamIdx + 1,
+  );
+  if (ownership.kind === "empty") return undefined;
+
+  const hostId = `"${ctx.joinTableName}"."${ctx.idCol}"`;
+  // CASE, not a bare cast: an id shaped for another host entity would abort the
+  // whole statement with 22P02, and AND does not guarantee evaluation order.
+  const conditions: string[] = [
+    `"${statics.tableName}"."id" = (CASE WHEN ${hostId} ~ $${ctx.uuidIdx} THEN ${hostId} END)::uuid`,
+  ];
+  if (statics.tenantIdCol !== undefined && ctx.tenantIdx !== undefined) {
+    conditions.push(
+      `"${statics.tableName}"."${statics.tenantIdCol}" IN ($${ctx.tenantIdx[0]}, $${ctx.tenantIdx[1]})`,
+    );
+  }
+  if (candidate.softDelete === true && statics.isDeletedCol !== undefined && !ctx.includeDeleted) {
+    conditions.push(`"${statics.tableName}"."${statics.isDeletedCol}" = FALSE`);
+  }
+  if (ownership.kind === "sql") conditions.push(ownership.sqlText);
+
+  return {
+    sqlText: `("${ctx.joinTableName}"."${ctx.typeCol}" = $${ctx.typeParamIdx} AND EXISTS (SELECT 1 FROM "${statics.tableName}" WHERE ${conditions.join(" AND ")}))`,
+    params: ownership.kind === "sql" ? ownership.params : [],
+  };
+}

package/src/db/table-builder.ts

@@ -7,6 +7,7 @@ import type {
 } from "../engine/types";
 import { assertUnreachable } from "../utils";
 import { toSnakeCase } from "../utils/case";
+import type { Table } from "./event-store-executor-context";
 
 export { toSnakeCase } from "../utils/case";
 
@@ -35,6 +36,12 @@ import {
   uuid,
 } from "./dialect";
 
+// Shared by the CRUD executor and the parent-ref read-gate — a field's
+// declared column name if it has one, else its snake_case default.
+export function physicalColumnName(table: Table, field: string): string {
+  return (table[field] as { name?: string } | undefined)?.name ?? toSnakeCase(field);
+}
+
 // Local AnyPgColumn alias — kept for legacy field-definition callers that
 // still import this name as a type. ColumnHandle from the native dialect
 // matches the same role (snake_case name + sql type accessor).