@cosmicdrift/kumiko-framework 0.257.0 → 0.258.1

package/src/db/__tests__/table-builder-indexes.test.ts

@@ -40,8 +40,8 @@ describe("buildEntityTable — entity.indexes", () => {
   test("composite unique-index landet als unique=true in Drizzle table-config", () => {
     const entity = createEntity({
       fields: {
-        key: createTextField({ required: true }),
-        userId: createTextField({}),
+        key: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+        userId: createTextField({ personal: false, reason: "test_fixture" }),
       },
       indexes: [{ unique: true, columns: ["key", "tenantId", "userId"] }],
     });
@@ -62,8 +62,8 @@ describe("buildEntityTable — entity.indexes", () => {
   test("composite non-unique-index landet als unique=false in Drizzle table-config", () => {
     const entity = createEntity({
       fields: {
-        startedAt: createTextField({}),
-        endedAt: createTextField({}),
+        startedAt: createTextField({ personal: false, reason: "test_fixture" }),
+        endedAt: createTextField({ personal: false, reason: "test_fixture" }),
       },
       indexes: [{ columns: ["startedAt", "endedAt"] }],
     });
@@ -78,7 +78,9 @@ describe("buildEntityTable — entity.indexes", () => {
 
   test("custom name override wird respektiert", () => {
     const entity = createEntity({
-      fields: { slug: createTextField({ required: true }) },
+      fields: {
+        slug: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+      },
       indexes: [{ unique: true, columns: ["slug"], name: "my_custom_idx" }],
     });
     const tbl = buildEntityTable("page", entity);
@@ -91,7 +93,7 @@ describe("buildEntityTable — entity.indexes", () => {
   test("ohne indexes — keine zusätzlichen Indices, kein Error", () => {
     const entity = createEntity({
       fields: {
-        title: createTextField({}),
+        title: createTextField({ personal: false, reason: "test_fixture" }),
       },
     });
     expect(() => buildEntityTable("widget", entity)).not.toThrow();
@@ -120,7 +122,7 @@ describe("validateBoot — entity.indexes", () => {
   test("Tippfehler im column-Namen wirft", () => {
     const feature = defineFeature("widgetFeature", (r) => {
       r.entity("widget", {
-        fields: { title: createTextField({}) },
+        fields: { title: createTextField({ personal: false, reason: "test_fixture" }) },
         indexes: [{ columns: ["titel"] }], // typo
       });
     });
@@ -130,7 +132,7 @@ describe("validateBoot — entity.indexes", () => {
   test("leere column-Liste wirft", () => {
     const feature = defineFeature("widgetFeature", (r) => {
       r.entity("widget", {
-        fields: { title: createTextField({}) },
+        fields: { title: createTextField({ personal: false, reason: "test_fixture" }) },
         indexes: [{ columns: [] as never }],
       });
     });
@@ -140,7 +142,7 @@ describe("validateBoot — entity.indexes", () => {
   test("single-column index nur auf tenantId ist redundant", () => {
     const feature = defineFeature("widgetFeature", (r) => {
       r.entity("widget", {
-        fields: { title: createTextField({}) },
+        fields: { title: createTextField({ personal: false, reason: "test_fixture" }) },
         indexes: [{ columns: ["tenantId"] }],
       });
     });
@@ -155,7 +157,7 @@ describe("validateBoot — entity.indexes", () => {
     // sonst fliegt der Branch beim nächsten Revert/Refactor stumm raus.
     const feature = defineFeature("widgetFeature", (r) => {
       r.entity("widget", {
-        fields: { title: createTextField({}) },
+        fields: { title: createTextField({ personal: false, reason: "test_fixture" }) },
         indexes: [{ unique: true, columns: ["tenantId"] }],
       });
     });
@@ -166,7 +168,7 @@ describe("validateBoot — entity.indexes", () => {
     const feature = defineFeature("widgetFeature", (r) => {
       r.entity("widget", {
         fields: {
-          key: createTextField({ required: true }),
+          key: createTextField({ required: true, personal: false, reason: "test_fixture" }),
           archived: createBooleanField({}),
         },
         indexes: [{ unique: true, columns: ["key", "tenantId"] }],
@@ -178,7 +180,7 @@ describe("validateBoot — entity.indexes", () => {
   test("base columns (id, tenantId, version) sind erlaubt", () => {
     const feature = defineFeature("widgetFeature", (r) => {
       r.entity("widget", {
-        fields: { key: createTextField({}) },
+        fields: { key: createTextField({ personal: false, reason: "test_fixture" }) },
         indexes: [{ columns: ["tenantId", "version"] }],
       });
     });

package/src/db/__tests__/table-builder-required.test.ts

@@ -44,8 +44,8 @@ describe("buildEntityTable — required: true → NOT NULL", () => {
   test("text field — required true makes column NOT NULL", () => {
     const entity = createEntity({
       fields: {
-        title: createTextField({ required: true }),
-        subtitle: createTextField({}),
+        title: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+        subtitle: createTextField({ personal: false, reason: "test_fixture" }),
       },
     });
     const tbl = buildEntityTable("widget", entity);

package/src/db/__tests__/tenant-db-where-merge.integration.test.ts

@@ -25,7 +25,7 @@ import { buildEntityTable } from "../table-builder";
 
 const noteEntity = createEntity({
   fields: {
-    title: createTextField({ required: true }),
+    title: createTextField({ required: true, personal: false, reason: "test_fixture" }),
   },
   table: "where_merge_notes",
 });

package/src/db/__tests__/tenant-db-where-merge.test.ts

@@ -14,7 +14,7 @@ import { createTenantDb } from "../tenant-db";
 
 const entity = createEntity({
   table: "merge_items",
-  fields: { name: createTextField({ required: true }) },
+  fields: { name: createTextField({ required: true, personal: false, reason: "test_fixture" }) },
 });
 // Brand (#742) is compile-time-only; hold the handle at the unbranded TableColumns
 // view so the method-form scoping test still compiles (runtime shape is identical).
@@ -130,7 +130,10 @@ describe("tenant-db WHERE merge — narrowing within the enforced scope", () =>
 describe("tenant-db WHERE merge — unmanaged EntityTableMeta tables (deriveEntityTableMeta)", () => {
   const unmanagedEntity = createEntity({
     table: "merge_meta_items",
-    fields: { tenantId: createTextField({ required: true }), name: createTextField() },
+    fields: {
+      tenantId: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+      name: createTextField({ personal: false, reason: "test_fixture" }),
+    },
   });
   const unmanagedTable = deriveEntityTableMeta("merge-meta-item", unmanagedEntity);
 

package/src/db/__tests__/tenant-db.integration.test.ts

@@ -19,8 +19,8 @@ import { createTenantDb } from "../tenant-db";
 const entity = createEntity({
   table: "tenant_db_items",
   fields: {
-    name: createTextField({ required: true }),
-    status: createTextField({ default: "draft" }),
+    name: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+    status: createTextField({ default: "draft", personal: false, reason: "test_fixture" }),
     isActive: createBooleanField({ default: true }),
   },
   softDelete: true,

package/src/db/__tests__/unique-violation-mapping.integration.test.ts

@@ -27,8 +27,8 @@ import { createTenantDb, type TenantDb } from "../tenant-db";
 const userEntity = createEntity({
   table: "read_unique_users",
   fields: {
-    email: createTextField({ required: true }),
-    displayName: createTextField({ required: true }),
+    email: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+    displayName: createTextField({ required: true, personal: false, reason: "test_fixture" }),
   },
   // softDelete=true damit wir den restore-Pfad pinnen können (siehe
   // restore-Test unten — "kein 23505 möglich" claim).

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).

package/src/engine/__tests__/boot-validator-action-wiring.test.ts

@@ -7,7 +7,12 @@ import { createEntity, createTextField } from "../factories";
 describe("validateBoot — action wiring (no function values)", () => {
   test("rowAction writeHandler payload as function → Throw", () => {
     const feature = defineFeature("shop", (r) => {
-      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.entity(
+        "product",
+        createEntity({
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
       r.screen({
         id: "product-list",
         type: "entityList",
@@ -33,7 +38,14 @@ describe("validateBoot — action wiring (no function values)", () => {
 
   test("rowAction writeHandler payload as declarative pick → kein Throw", () => {
     const feature = defineFeature("shop", (r) => {
-      r.entity("product", createEntity({ fields: { name: createTextField({ sortable: true }) } }));
+      r.entity(
+        "product",
+        createEntity({
+          fields: {
+            name: createTextField({ sortable: true, personal: false, reason: "test_fixture" }),
+          },
+        }),
+      );
       r.screen({
         id: "product-list",
         type: "entityList",
@@ -65,7 +77,12 @@ describe("validateBoot — action wiring (no function values)", () => {
 
   test("rowAction navigate visible as function → Throw", () => {
     const feature = defineFeature("shop", (r) => {
-      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.entity(
+        "product",
+        createEntity({
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
       r.screen({
         id: "product-list",
         type: "entityList",
@@ -88,7 +105,12 @@ describe("validateBoot — action wiring (no function values)", () => {
 
   test("toolbarAction writeHandler payload as function → Throw", () => {
     const feature = defineFeature("shop", (r) => {
-      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.entity(
+        "product",
+        createEntity({
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
       r.screen({
         id: "product-list",
         type: "entityList",
@@ -136,7 +158,12 @@ describe("validateBoot — action wiring (no function values)", () => {
 
   test("entityList column renderer as function → Throw", () => {
     const feature = defineFeature("shop", (r) => {
-      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.entity(
+        "product",
+        createEntity({
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
       r.screen({
         id: "product-list",
         type: "entityList",
@@ -152,7 +179,12 @@ describe("validateBoot — action wiring (no function values)", () => {
 
   test("entityEdit field visible as function → Throw", () => {
     const feature = defineFeature("shop", (r) => {
-      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.entity(
+        "product",
+        createEntity({
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
       r.screen({
         id: "product-edit",
         type: "entityEdit",
@@ -173,7 +205,12 @@ describe("validateBoot — action wiring (no function values)", () => {
 
   test("entityEdit field renderer as function → Throw", () => {
     const feature = defineFeature("shop", (r) => {
-      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.entity(
+        "product",
+        createEntity({
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
       r.screen({
         id: "product-edit",
         type: "entityEdit",
@@ -194,7 +231,12 @@ describe("validateBoot — action wiring (no function values)", () => {
 
   test("entityEdit field with declarative visible/readOnly/required → kein Throw", () => {
     const feature = defineFeature("shop", (r) => {
-      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.entity(
+        "product",
+        createEntity({
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
       r.screen({
         id: "product-edit",
         type: "entityEdit",