@cosmicdrift/kumiko-framework 0.237.2 → 0.239.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.237.2",
+  "version": "0.239.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.237.2",
+    "@cosmicdrift/kumiko-types": "0.239.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.237.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.239.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/db/__tests__/event-store-executor-reference-search.integration.test.ts

@@ -0,0 +1,381 @@
+// fw#2660 — a text search on an entity must also match its `searchable`
+// reference fields by the target row's labelField, not just the raw FK
+// column (a GUID never contains the search term a human types). Covers the
+// four cases the issue mandates: reference-only match, union with a native
+// text match (no duplicates), cross-tenant target label match (must yield
+// zero rows — the hard security constraint), and the >200-match cap (drop
+// the reference clause, native search still applies).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { asRawClient } from "../../db/query";
+import { createEntity, createTextField } from "../../engine";
+import type { EntityDefinition } from "../../engine/types";
+import { createEventsTable } from "../../event-store";
+import { createInMemorySearchAdapter } from "../../search";
+import { TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { seedRows } from "../../testing";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
+import { createEventStoreExecutor } from "../event-store-executor";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb, type TenantDb } from "../tenant-db";
+
+const customerEntity = createEntity({
+  table: "read_ref_search_customers",
+  fields: {
+    name: createTextField({ required: true }),
+  },
+});
+const customerTable = buildEntityTable("refSearchCustomer", customerEntity);
+
+const orderEntity = createEntity({
+  table: "read_ref_search_orders",
+  fields: {
+    note: createTextField({ searchable: true }),
+    customerId: {
+      type: "reference",
+      entity: "refSearchCustomer",
+      labelField: "name",
+      searchable: true,
+    },
+  },
+});
+const orderTable = buildEntityTable("refSearchOrder", orderEntity);
+
+// A caller who cannot read `customerId` itself must not be able to infer its
+// value by matching the target's label through the reference clause — same
+// probe surface fw#2629 already closed for filter/sort (fw#2660 parity).
+const restrictedOrderEntity = createEntity({
+  table: "read_ref_search_restricted_orders",
+  fields: {
+    note: createTextField({ searchable: true }),
+    customerId: {
+      type: "reference",
+      entity: "refSearchCustomer",
+      labelField: "name",
+      searchable: true,
+      access: { read: { Admin: "all" } },
+    },
+  },
+});
+const restrictedOrderTable = buildEntityTable("refSearchRestrictedOrder", restrictedOrderEntity);
+
+// Minimal stand-in for the real bundled `tenant` entity (table `read_tenants`)
+// — mirrors the pattern in entity-table-from-registry.test.ts. Only `name`
+// matters here: the implicit tenantId->tenant.name row-meta reference
+// (LIST_ROW_META_REFERENCES) is what's under test, not tenant's full schema.
+const tenantMetaEntity = createEntity({
+  table: "read_tenants",
+  fields: { name: createTextField({ required: true }) },
+});
+const tenantMetaTable = buildEntityTable("tenant", tenantMetaEntity);
+
+function resolveEntity(name: string): EntityDefinition | undefined {
+  return name === "refSearchCustomer" ? customerEntity : undefined;
+}
+
+const referenceSearch = {
+  fields: [{ fieldName: "customerId", targetEntityName: "refSearchCustomer", labelField: "name" }],
+  resolveEntity,
+};
+
+const restrictedReferenceSearch = {
+  fields: referenceSearch.fields,
+  resolveEntity,
+};
+
+// Same fields as `referenceSearch`, but resolves "tenant" too — kept separate
+// from the module-default `referenceSearch` so the other tests (whose
+// resolveEntity never resolves "tenant") never issue a query against
+// `read_tenants`.
+const referenceSearchWithTenant = {
+  fields: referenceSearch.fields,
+  resolveEntity: (name: string) => (name === "tenant" ? tenantMetaEntity : resolveEntity(name)),
+};
+
+let testDb: BunTestDb;
+let tdbA: TenantDb;
+let tdbB: TenantDb;
+const admin = TestUsers.admin;
+const otherTenantAdmin = TestUsers.otherTenant;
+const orderExec = createEventStoreExecutor(orderTable, orderEntity, {
+  entityName: "refSearchOrder",
+});
+const restrictedOrderExec = createEventStoreExecutor(restrictedOrderTable, restrictedOrderEntity, {
+  entityName: "refSearchRestrictedOrder",
+});
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, customerEntity, "refSearchCustomer");
+  await unsafeCreateEntityTable(testDb.db, orderEntity, "refSearchOrder");
+  await unsafeCreateEntityTable(testDb.db, restrictedOrderEntity, "refSearchRestrictedOrder");
+  await unsafeCreateEntityTable(testDb.db, tenantMetaEntity, "tenant");
+  await createEventsTable(testDb.db);
+  tdbA = createTenantDb(testDb.db, admin.tenantId);
+  tdbB = createTenantDb(testDb.db, otherTenantAdmin.tenantId);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(testDb.db).unsafe(
+    "TRUNCATE kumiko_events, read_ref_search_customers, read_ref_search_orders, " +
+      "read_ref_search_restricted_orders, read_tenants RESTART IDENTITY CASCADE",
+  );
+});
+
+describe("event-store-executor.list — searchable reference fields (fw#2660)", () => {
+  test("matches via the reference column's label with no text-field match", async () => {
+    const [acme] = await seedRows(testDb.db, customerTable, [
+      { id: crypto.randomUUID(), tenantId: admin.tenantId, name: "Acme Corp" },
+    ]);
+    const [order] = await seedRows(testDb.db, orderTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        note: "totally unrelated note",
+        customerId: (acme as { id: string }).id,
+      },
+    ]);
+
+    const searchAdapter = createInMemorySearchAdapter();
+    await searchAdapter.configure(admin.tenantId, { searchableFields: ["note"] });
+    await searchAdapter.index(admin.tenantId, {
+      entityType: "refSearchOrder",
+      entityId: (order as { id: string }).id,
+      weight: 1,
+      fields: { note: "totally unrelated note" },
+    });
+
+    const res = await orderExec.list({ search: "acme" }, admin, tdbA, {
+      searchAdapter,
+      referenceSearch,
+    });
+    expect(res.rows.map((r) => r["id"])).toEqual([(order as { id: string }).id]);
+  });
+
+  test("unions a native text-field match with a reference-label match, no duplicates", async () => {
+    const [acme, other] = await seedRows(testDb.db, customerTable, [
+      { id: crypto.randomUUID(), tenantId: admin.tenantId, name: "Acme Corp" },
+      { id: crypto.randomUUID(), tenantId: admin.tenantId, name: "Some Other Customer" },
+    ]);
+    const [textMatchOrder, refMatchOrder, decoyOrder] = await seedRows(testDb.db, orderTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        note: "great acme deal closed",
+        customerId: (other as { id: string }).id,
+      },
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        note: "nothing special here",
+        customerId: (acme as { id: string }).id,
+      },
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        note: "nothing special here either",
+        customerId: (other as { id: string }).id,
+      },
+    ]);
+
+    const searchAdapter = createInMemorySearchAdapter();
+    await searchAdapter.configure(admin.tenantId, { searchableFields: ["note"] });
+    for (const o of [textMatchOrder, refMatchOrder, decoyOrder]) {
+      const row = o as { id: string; note: string };
+      await searchAdapter.index(admin.tenantId, {
+        entityType: "refSearchOrder",
+        entityId: row.id,
+        weight: 1,
+        fields: { note: row.note },
+      });
+    }
+
+    const res = await orderExec.list({ search: "acme" }, admin, tdbA, {
+      searchAdapter,
+      referenceSearch,
+    });
+    const ids = res.rows.map((r) => r["id"]);
+    expect(ids.sort()).toEqual(
+      [(textMatchOrder as { id: string }).id, (refMatchOrder as { id: string }).id].sort(),
+    );
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  test("a target label match in a foreign tenant never surfaces a row (mandatory)", async () => {
+    const [confidential] = await seedRows(testDb.db, customerTable, [
+      { id: crypto.randomUUID(), tenantId: admin.tenantId, name: "Confidential Co" },
+    ]);
+    // Reference UUIDs are freely settable (no FK constraint) — a tenant-B
+    // row can point at a tenant-A id. If the target lookup weren't
+    // tenant-scoped, this order would surface and leak that a
+    // "Confidential Co" row exists in another tenant.
+    const [order] = await seedRows(testDb.db, orderTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: otherTenantAdmin.tenantId,
+        note: "unrelated",
+        customerId: (confidential as { id: string }).id,
+      },
+    ]);
+
+    const searchAdapter = createInMemorySearchAdapter();
+    await searchAdapter.configure(otherTenantAdmin.tenantId, { searchableFields: ["note"] });
+    await searchAdapter.index(otherTenantAdmin.tenantId, {
+      entityType: "refSearchOrder",
+      entityId: (order as { id: string }).id,
+      weight: 1,
+      fields: { note: "unrelated" },
+    });
+
+    const res = await orderExec.list({ search: "confidential" }, otherTenantAdmin, tdbB, {
+      searchAdapter,
+      referenceSearch,
+    });
+    expect(res.rows).toHaveLength(0);
+  });
+
+  test("drops the reference clause above 200 target matches — native search still applies", async () => {
+    const fooCustomers = Array.from({ length: 201 }, (_, i) => ({
+      id: crypto.randomUUID(),
+      tenantId: admin.tenantId,
+      name: `Foo Customer ${i}`,
+    }));
+    await seedRows(testDb.db, customerTable, fooCustomers);
+
+    const [refOnlyOrder, textMatchOrder] = await seedRows(testDb.db, orderTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        note: "no keyword here",
+        customerId: fooCustomers[5]?.id,
+      },
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        note: "foo appears right here",
+        customerId: fooCustomers[10]?.id,
+      },
+    ]);
+
+    const searchAdapter = createInMemorySearchAdapter();
+    await searchAdapter.configure(admin.tenantId, { searchableFields: ["note"] });
+    for (const o of [refOnlyOrder, textMatchOrder]) {
+      const row = o as { id: string; note: string };
+      await searchAdapter.index(admin.tenantId, {
+        entityType: "refSearchOrder",
+        entityId: row.id,
+        weight: 1,
+        fields: { note: row.note },
+      });
+    }
+
+    const res = await orderExec.list({ search: "foo" }, admin, tdbA, {
+      searchAdapter,
+      referenceSearch,
+    });
+    expect(res.rows.map((r) => r["id"])).toEqual([(textMatchOrder as { id: string }).id]);
+  });
+
+  test("a caller without read access to the reference column gets no reference-match hit (fw#2629 parity)", async () => {
+    const [acme] = await seedRows(testDb.db, customerTable, [
+      { id: crypto.randomUUID(), tenantId: admin.tenantId, name: "Acme Corp" },
+    ]);
+    const [order] = await seedRows(testDb.db, restrictedOrderTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        note: "totally unrelated note",
+        customerId: (acme as { id: string }).id,
+      },
+    ]);
+
+    const searchAdapter = createInMemorySearchAdapter();
+    await searchAdapter.configure(admin.tenantId, { searchableFields: ["note"] });
+
+    const asUser = await restrictedOrderExec.list({ search: "acme" }, TestUsers.user, tdbA, {
+      searchAdapter,
+      referenceSearch: restrictedReferenceSearch,
+    });
+    expect(asUser.rows).toHaveLength(0);
+
+    const asAdmin = await restrictedOrderExec.list({ search: "acme" }, admin, tdbA, {
+      searchAdapter,
+      referenceSearch: restrictedReferenceSearch,
+    });
+    expect(asAdmin.rows.map((r) => r["id"])).toEqual([(order as { id: string }).id]);
+  });
+
+  test("matches via the implicit tenantId->tenant.name row-meta reference in a system-scoped cross-tenant search", async () => {
+    const [acmeTenant] = await seedRows(testDb.db, tenantMetaTable, [
+      { id: admin.tenantId, tenantId: admin.tenantId, name: "Acme Tenant" },
+    ]);
+    await seedRows(testDb.db, tenantMetaTable, [
+      { id: otherTenantAdmin.tenantId, tenantId: otherTenantAdmin.tenantId, name: "Globex Tenant" },
+    ]);
+    const [someCustomer] = await seedRows(testDb.db, customerTable, [
+      { id: crypto.randomUUID(), tenantId: admin.tenantId, name: "Some Customer" },
+    ]);
+
+    const [tenantAOrder] = await seedRows(testDb.db, orderTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        note: "nothing relevant here",
+        customerId: (someCustomer as { id: string }).id,
+      },
+    ]);
+    await seedRows(testDb.db, orderTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: otherTenantAdmin.tenantId,
+        note: "also nothing relevant",
+        customerId: (someCustomer as { id: string }).id,
+      },
+    ]);
+
+    const searchAdapter = createInMemorySearchAdapter();
+    await searchAdapter.configure(TestUsers.systemAdmin.tenantId, { searchableFields: ["note"] });
+
+    const systemDb = createTenantDb(testDb.db, TestUsers.systemAdmin.tenantId, "system");
+    const res = await orderExec.list({ search: "acme" }, TestUsers.systemAdmin, systemDb, {
+      searchAdapter,
+      referenceSearch: referenceSearchWithTenant,
+    });
+
+    expect(res.rows.map((r) => r["id"])).toEqual([(tenantAOrder as { id: string }).id]);
+    // sanity: the match is scoped to the matching tenant, not "everything"
+    expect((acmeTenant as { id: string }).id).toBe(admin.tenantId);
+  });
+
+  test("tenant-mode search never issues the tenantId row-meta lookup (gate)", async () => {
+    await seedRows(testDb.db, tenantMetaTable, [
+      { id: admin.tenantId, tenantId: admin.tenantId, name: "Acme Tenant" },
+    ]);
+    await seedRows(testDb.db, orderTable, [
+      { id: crypto.randomUUID(), tenantId: admin.tenantId, note: "nothing relevant" },
+    ]);
+
+    const searchAdapter = createInMemorySearchAdapter();
+    await searchAdapter.configure(admin.tenantId, { searchableFields: ["note"] });
+
+    // Drop the lookup target so the gated query would throw ("relation does
+    // not exist") if it were still issued — proves absence of the query, not
+    // just an equal-looking result.
+    await asRawClient(testDb.db).unsafe('DROP TABLE "read_tenants"');
+    try {
+      const res = await orderExec.list({ search: "acme" }, admin, tdbA, {
+        searchAdapter,
+        referenceSearch: referenceSearchWithTenant,
+      });
+      expect(res.rows).toHaveLength(0);
+    } finally {
+      await unsafeCreateEntityTable(testDb.db, tenantMetaEntity, "tenant");
+    }
+  });
+});

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

@@ -1,17 +1,21 @@
 import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
-import { computeBlindIndex, configuredBlindIndexKey } from "../crypto";
+import { collectPiiSubjectFields, computeBlindIndex, configuredBlindIndexKey } from "../crypto";
+import { escapeLikePattern } from "../crypto/ciphertext-pattern";
 import { executeRawQueryRead } from "../db/queries/raw-sql";
 import { coerceRow, extractTableInfo } from "../db/query";
 import { buildOwnershipClause, normalizeAccessEntry, shiftParams } from "../engine/ownership";
-import type { EntityId } from "../engine/types";
+import type { EntityDefinition, EntityId } from "../engine/types";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
 import { UnprocessableError } from "../errors";
 import { getStreamVersion } from "../event-store";
+import { LIST_ROW_META_REFERENCES } from "../ui-types/list-row-meta";
 import { rehydrateCompoundTypes } from "./compound-types";
 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 { toSnakeCase } from "./table-builder";
+import { buildEntityTable, toSnakeCase } from "./table-builder";
+import type { TenantDb, TenantDbMode } from "./tenant-db";
 
 // The two read verbs (list/detail) of the event-store-executor. Split out
 // of event-store-executor.ts (#1005, Welle 2) — behavior-preserving
@@ -183,9 +187,9 @@ function applyScreenFilter(
         whereSql.push(`${colSql(field)} ${opSym} $${params.length}`);
       }
     } else {
-      // Blind-Index-OR-Rewrite (#818), lock-step mit buildWhereClause
-      // in bun-db/query.ts — Equality auf lookupable-Feldern matcht
-      // Klartext-Arm ODER HMAC-Arm.
+      // Blind-index OR rewrite (#818), lock-step with buildWhereClause
+      // in bun-db/query.ts — equality on lookupable fields matches the
+      // plaintext arm OR the HMAC arm.
       const bidxKey = configuredBlindIndexKey();
       if (bidxKey !== undefined && typeof value === "string" && table[`${field}Bidx`]) {
         params.push(value, computeBlindIndex(bidxKey, value));
@@ -200,6 +204,102 @@ function applyScreenFilter(
   }
 }
 
+// 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;
+  readonly labelField: string;
+};
+
+// Registry-declared `searchable` reference fields, plus the implicit
+// tenantId→tenant.name row-meta reference (fw#2660) — both resolve a text
+// search term against a target row's label instead of the raw FK column.
+function collectReferenceSearchDescriptors(
+  table: Table,
+  referenceSearch: NonNullable<Parameters<EventStoreExecutor["list"]>[3]>["referenceSearch"],
+  dbMode: TenantDbMode,
+): readonly ReferenceSearchDescriptor[] {
+  if (!referenceSearch) return [];
+  const descriptors: ReferenceSearchDescriptor[] = referenceSearch.fields.map((f) => ({
+    ownColumn: f.fieldName,
+    targetEntityName: f.targetEntityName,
+    labelField: f.labelField,
+  }));
+  for (const [ownColumn, ref] of Object.entries(LIST_ROW_META_REFERENCES)) {
+    if (table[ownColumn] === undefined) continue;
+    // In "tenant" mode the outer tenant filter already pins tenantId to one
+    // of exactly two values, so a by-name lookup here can never narrow that further.
+    if (ownColumn === "tenantId" && dbMode === "tenant") continue;
+    descriptors.push({ ownColumn, targetEntityName: ref.refEntity, labelField: ref.refLabelField });
+  }
+  return descriptors;
+}
+
+// Tenant-scoped ILIKE lookup against one reference target — never raw/
+// unscoped SQL, a match in a foreign tenant must never surface a row here
+// (fw#2660's hard constraint). Mirrors the main table's own tenant filter
+// (see the `table["tenantId"]` check further down in list()).
+async function resolveReferenceMatches(
+  descriptor: ReferenceSearchDescriptor,
+  searchTerm: string,
+  resolveEntity: (entityName: string) => EntityDefinition | undefined,
+  db: TenantDb,
+): Promise<{ readonly ownColumn: string; readonly ids: readonly string[] } | undefined> {
+  const targetEntity = resolveEntity(descriptor.targetEntityName);
+  if (targetEntity === undefined) {
+    // skip: unknown target entity — registry inconsistency the boot-validator
+    // should have caught; fail open (no clause) rather than 500 the request
+    return undefined;
+  }
+  if (targetEntity.fields[descriptor.labelField] === undefined) {
+    // skip: labelField isn't a real (declared) column on the target entity —
+    // row-meta references (e.g. tenant.name) always resolve here since
+    // `name` is a declared field on the tenant entity, not an id/row-meta column
+    return undefined;
+  }
+  if (
+    collectEncryptedFieldNames(targetEntity).has(descriptor.labelField) ||
+    collectPiiSubjectFields(targetEntity).includes(descriptor.labelField)
+  ) {
+    // skip: encrypted/PII labelField — ILIKE can never match ciphertext,
+    // emitting the query would just be a silent, permanent non-match
+    return undefined;
+  }
+
+  const targetTable = buildEntityTable(descriptor.targetEntityName, targetEntity);
+  const targetTableName = String(
+    (targetTable as unknown as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL],
+  );
+  const labelCol = physicalColumnName(targetTable, descriptor.labelField);
+  const subParams: unknown[] = [`%${escapeLikePattern(searchTerm)}%`];
+  let tenantClause = "";
+  if (targetTable["tenantId"] !== undefined && db.mode === "tenant") {
+    subParams.push(db.tenantId, SYSTEM_TENANT_ID);
+    tenantClause = ` AND "${physicalColumnName(targetTable, "tenantId")}" IN ($2, $3)`;
+  }
+  // ::text cast covers a non-text labelField (e.g. a number/select column
+  // used as label) — Postgres has no ILIKE for those types otherwise.
+  const sql =
+    `SELECT "id" FROM "${targetTableName}" WHERE ("${labelCol}")::text ILIKE $1${tenantClause} ` +
+    `LIMIT ${MAX_REFERENCE_SEARCH_IDS + 1}`;
+  const rows = await executeRawQueryRead<{ id: string }>(db.raw, sql, subParams);
+  if (rows.length === 0 || rows.length > MAX_REFERENCE_SEARCH_IDS) {
+    // skip: no match, or over the cap — drop the clause rather than
+    // truncate to an arbitrary slice of matching targets
+    return undefined;
+  }
+  return { ownColumn: descriptor.ownColumn, ids: rows.map((r) => r.id) };
+}
+
 export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor, "list" | "detail"> {
   const {
     table,
@@ -231,12 +331,35 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
       }
 
       let filterIds: EntityId[] | undefined;
+      // fw#2660 — true once a searchable-reference or row-meta-reference
+      // clause contributed rows, so the total-count fast-path below knows
+      // `filterIds.length` alone would undercount.
+      let referenceClauseActive = false;
+      // Build the WHERE clause as raw SQL — ownership produces a
+      // parameterised fragment that we splice in alongside simple WhereObject
+      // conditions (cursor, search-filter-IDs, screen-filter, tenant-scope).
+      const 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);
+      const colSql = (field: string): string => `"${physicalCol(field)}"`;
+
+      // Field-level read access gates filtering and sorting the same way it
+      // gates the projected row: a caller who cannot read a field must not be
+      // able to probe its values through result counts or ordering (fw#2629).
+      // Hoisted above the search block (fw#2660) — a searchable-reference
+      // clause is the same probe surface as a filter/sort and must be gated
+      // the same way, before the reference-match query even runs.
+      const fieldReadClause = (field: string) =>
+        buildOwnershipClause(user, normalizeAccessEntry(entity.fields[field]?.access?.read), table);
+
       // Build-Time options.searchAdapter gewinnt; runtime-Override ist
       // Fallback für die defaultEntityQueryHandler-Pipe (die nutzt den
       // ctx.searchAdapter erst zur Laufzeit weil createEventStoreExecutor
       // beim Definition-Time noch keinen Server-Context hat).
       const effectiveSearchAdapter = searchAdapter ?? runtimeOptions?.searchAdapter;
       if (payload.search) {
+        const searchTerm = payload.search;
         // #2032 — a search term with no adapter wired must fail loud, not
         // silently return the unfiltered list dressed up as a search result.
         if (!effectiveSearchAdapter) {
@@ -251,29 +374,63 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
         // SYSTEM_TENANT_ID; everything else under the session tenant — db.mode
         // must not invent a second predicate (kumiko-framework#2412).
         const searchTenantId = streamTenantFor(user);
-        const results = await effectiveSearchAdapter.search(searchTenantId, payload.search, {
+        const results = await effectiveSearchAdapter.search(searchTenantId, searchTerm, {
           filterType: entityName,
         });
         filterIds = results.map((r) => r.entityId);
-        if (filterIds.length === 0) {
+
+        // fw#2660 — union in reference-column label matches: a searchable
+        // reference field (or the implicit tenantId→tenant.name row-meta
+        // reference) whose target row's labelField matches the search term
+        // also counts as a hit on this entity, not just a raw text-field hit.
+        const referenceSearch = runtimeOptions?.referenceSearch;
+        // fw#2629 parity: a caller who cannot read the reference column itself
+        // must not be able to infer its value by matching the target's label —
+        // same probe surface as filtering/sorting on it directly.
+        const descriptors = collectReferenceSearchDescriptors(
+          table,
+          referenceSearch,
+          db.mode,
+        ).filter((d) => fieldReadClause(d.ownColumn).kind === "pass");
+        const referenceMatches = referenceSearch
+          ? (
+              await Promise.all(
+                descriptors.map((d) =>
+                  resolveReferenceMatches(d, searchTerm, referenceSearch.resolveEntity, db),
+                ),
+              )
+            ).filter(
+              (m): m is { readonly ownColumn: string; readonly ids: readonly string[] } =>
+                m !== undefined,
+            )
+          : [];
+
+        if (filterIds.length === 0 && referenceMatches.length === 0) {
           return { rows: [], nextCursor: null, ...(totalCount && { total: 0 }) };
         }
+
+        const orParts: string[] = [];
+        if (filterIds.length > 0) {
+          const placeholders = filterIds.map((id) => {
+            params.push(id);
+            return `$${params.length}`;
+          });
+          orParts.push(`${colSql("id")} IN (${placeholders.join(", ")})`);
+        }
+        for (const match of referenceMatches) {
+          const placeholders = match.ids.map((id) => {
+            params.push(id);
+            return `$${params.length}`;
+          });
+          orParts.push(`${colSql(match.ownColumn)} IN (${placeholders.join(", ")})`);
+          referenceClauseActive = true;
+        }
+        // Parenthesized as one whereSql entry — whereSql is joined with
+        // " AND " below, an unparenthesized OR here would leak past the
+        // tenant filter that follows.
+        whereSql.push(`(${orParts.join(" OR ")})`);
       }
 
-      // 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 =>
-        (table[field] as { name?: string } | undefined)?.name ?? toSnakeCase(field);
-      const colSql = (field: string): string => `"${physicalCol(field)}"`;
-      // Field-level read access gates filtering and sorting the same way it
-      // gates the projected row: a caller who cannot read a field must not be
-      // able to probe its values through result counts or ordering (fw#2629).
-      const fieldReadClause = (field: string) =>
-        buildOwnershipClause(user, normalizeAccessEntry(entity.fields[field]?.access?.read), table);
       const sortField =
         payload.sort && table[payload.sort] && fieldReadClause(payload.sort).kind === "pass"
           ? payload.sort
@@ -305,13 +462,6 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
           );
         }
       }
-      if (filterIds) {
-        const placeholders = filterIds.map((id) => {
-          params.push(id);
-          return `$${params.length}`;
-        });
-        whereSql.push(`${colSql("id")} IN (${placeholders.join(", ")})`);
-      }
       if (ownership.kind === "sql") {
         const shifted = shiftParams(
           { sqlText: ownership.sqlText, params: ownership.params },
@@ -397,13 +547,15 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
           sortText === undefined ? encodeCursor(cursorId) : encodeKeysetCursor(sortText, cursorId);
       }
 
-      // total: extra COUNT(*) — nur wenn explizit angefordert (Pager-UI).
-      // Postgres-Cost ist O(table-scan) ohne Filter, mit Filter so teuer
-      // wie der entsprechende WHERE — bei indexed columns billig genug.
-      // Bei Search-Path ist `total = filterIds.length` ohne extra Query.
+      // total: extra COUNT(*) — only when explicitly requested (pager UI).
+      // Postgres cost is O(table-scan) without a filter, with a filter as
+      // expensive as the corresponding WHERE — cheap enough on indexed columns.
+      // On the search path, `total = filterIds.length` needs no extra query —
+      // unless a reference match contributed additional rows (fw#2660), in
+      // which case the raw filterIds length alone would undercount.
       let total: number | undefined;
       if (totalCount) {
-        if (filterIds) {
+        if (filterIds && !referenceClauseActive) {
           total = filterIds.length;
         } else {
           const countSql = `SELECT COUNT(*)::int AS count FROM "${tableName}"${whereClauseSqlText}`;

package/src/engine/__tests__/engine.test.ts

@@ -621,6 +621,83 @@ describe("createRegistry", () => {
     expect(registry.getSearchableFields("user")).toEqual(["email", "lastName"]);
     expect(registry.getSearchableFields("nonexistent")).toEqual([]);
   });
+
+  test("returns searchable reference fields for entity, without leaking them into getSearchableFields (fw#2660)", () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "customer",
+        createEntity({ table: "Customers", fields: { name: createTextField() } }),
+      );
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            note: createTextField({ searchable: true }),
+            customerId: {
+              type: "reference",
+              entity: "customer",
+              labelField: "name",
+              searchable: true,
+            },
+          },
+        }),
+      );
+    });
+
+    const registry = createRegistry([feature]);
+    // Meili invariant: the search-index build reads getSearchableFields, and
+    // a reference field is never text-indexed there — it's resolved via a
+    // live DB lookup at query time instead (getSearchableReferences).
+    expect(registry.getSearchableFields("order")).toEqual(["note"]);
+    expect(registry.getSearchableReferences("order")).toEqual([
+      { fieldName: "customerId", targetEntityName: "customer", labelField: "name" },
+    ]);
+    expect(registry.getSearchableReferences("nonexistent")).toEqual([]);
+  });
+
+  test("throws at boot when a searchable reference field has no explicit labelField (fw#2660)", () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "customer",
+        createEntity({ table: "Customers", fields: { name: createTextField() } }),
+      );
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            customerId: { type: "reference", entity: "customer", searchable: true },
+          },
+        }),
+      );
+    });
+
+    expect(() => createRegistry([feature])).toThrow(/labelField/);
+  });
+
+  test("throws at boot when searchable is combined with multiple on a reference field (fw#2660)", () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity("tag", createEntity({ table: "Tags", fields: { name: createTextField() } }));
+      r.entity(
+        "post",
+        createEntity({
+          table: "Posts",
+          fields: {
+            tagIds: {
+              type: "reference",
+              entity: "tag",
+              labelField: "name",
+              searchable: true,
+              multiple: true,
+            },
+          },
+        }),
+      );
+    });
+
+    expect(() => createRegistry([feature])).toThrow(/multiple/);
+  });
 });
 
 // --- Access ---
@@ -1597,7 +1674,6 @@ describe("r.relation()", () => {
         type: "belongsTo",
         target: "department",
         foreignKey: "departmentId",
-        searchInclude: ["name"],
       });
     });
 
@@ -1613,7 +1689,6 @@ describe("r.relation()", () => {
         type: "manyToMany",
         target: "role",
         through: { table: "UserRoles", sourceKey: "userId", targetKey: "roleId" },
-        searchInclude: ["name"],
       });
     });
 
@@ -1648,7 +1723,6 @@ describe("registry relations", () => {
         type: "manyToMany",
         target: "role",
         through: { table: "UserRoles", sourceKey: "userId", targetKey: "roleId" },
-        searchInclude: ["name"],
       });
     });
 
@@ -1657,31 +1731,6 @@ describe("registry relations", () => {
     expect(rels["roles"]).toBeDefined();
   });
 
-  test("getSearchIncludes returns fields to index from relations", () => {
-    const feature = defineFeature("test", (r) => {
-      r.entity("user", createEntity({ table: "Users", fields: {} }));
-      r.entity("role", createEntity({ table: "Roles", fields: { name: createTextField() } }));
-      r.entity("department", createEntity({ table: "Depts", fields: { name: createTextField() } }));
-      r.relation("user", "roles", {
-        type: "manyToMany",
-        target: "role",
-        through: { table: "UserRoles", sourceKey: "userId", targetKey: "roleId" },
-        searchInclude: ["name"],
-      });
-      r.relation("user", "department", {
-        type: "belongsTo",
-        target: "department",
-        foreignKey: "departmentId",
-        searchInclude: ["name"],
-      });
-    });
-
-    const registry = createRegistry([feature]);
-    const includes = registry.getSearchIncludes("user");
-    expect(includes.get("roles")).toEqual(["name"]);
-    expect(includes.get("department")).toEqual(["name"]);
-  });
-
   test("throws on relation to non-existent entity", () => {
     const feature = defineFeature("test", (r) => {
       r.entity("user", createEntity({ table: "Users", fields: {} }));

package/src/engine/entity-handlers.ts

@@ -339,6 +339,13 @@ export function defineEntityQueryHandler(
         const result = await executor.list(listPayload, query.user, db, {
           ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
           ...(ctx.includeDeleted === true && { includeDeleted: true }),
+          // fw#2660 — registry access only exists at request time, so the
+          // searchable-reference cache + entity resolver travel through the
+          // same runtime-override extension point as searchAdapter above.
+          referenceSearch: {
+            fields: ctx.registry.getSearchableReferences(entityName),
+            resolveEntity: (name) => ctx.registry.getEntity(name),
+          },
         });
         const enrichedRows = hasRefFields
           ? await enrichWithReferences(

package/src/engine/registry-facade.ts

@@ -1,4 +1,4 @@
-import type { IncomingRelation, RegistryState } from "./registry-state";
+import type { IncomingRelation, RegistryState, SearchableReferenceField } from "./registry-state";
 import { filterByPhase, filterOwned } from "./registry-state";
 import type {
   AuthClaimsHookDef,
@@ -97,8 +97,8 @@ export function buildRegistryFacade(state: RegistryState): Registry {
       return (state.relationMap.get(entityName) ?? {}) as EntityRelations; // @cast-boundary schema-walk
     },
 
-    getSearchIncludes(entityName: string): ReadonlyMap<string, readonly string[]> {
-      return state.searchIncludesCache.get(entityName) ?? new Map();
+    getSearchableReferences(entityName: string): readonly SearchableReferenceField[] {
+      return state.searchableReferencesCache.get(entityName) ?? [];
     },
 
     getIncomingRelations(entityName: string): readonly IncomingRelation[] {

package/src/engine/registry-state.ts

@@ -49,6 +49,17 @@ export type IncomingRelation = {
   relation: RelationDefinition;
 };
 
+// One entry per `ReferenceFieldDef` with `searchable: true` (fw#2660) —
+// resolved once at boot so the read-path never re-parses `field.entity`
+// per request. `labelField` is guaranteed defined here: buildSearchableSortableCaches
+// throws at boot for a searchable reference missing an explicit labelField
+// (the "id" default is a UUID column, ILIKE against it would 500 at request time).
+export type SearchableReferenceField = {
+  readonly fieldName: string;
+  readonly targetEntityName: string;
+  readonly labelField: string;
+};
+
 const IMPLICIT_PROJECTION_SUFFIX = "-entity" as const;
 
 // Pro r.entity-Registration eine ImplicitProjection mit auto-generierten
@@ -223,7 +234,7 @@ export type RegistryState = {
   treeActionsMap: Map<string, Readonly<Record<string, TreeActionDef>>>;
   searchableFieldsCache: Map<string, readonly string[]>;
   sortableFieldsCache: Map<string, readonly string[]>;
-  searchIncludesCache: Map<string, ReadonlyMap<string, readonly string[]>>;
+  searchableReferencesCache: Map<string, readonly SearchableReferenceField[]>;
   incomingRelationsCache: Map<string, IncomingRelation[]>;
   hasRateLimitedHandlerCached: boolean;
 };
@@ -286,7 +297,7 @@ export function createInitialState(): RegistryState {
     treeActionsMap: new Map(),
     searchableFieldsCache: new Map(),
     sortableFieldsCache: new Map(),
-    searchIncludesCache: new Map(),
+    searchableReferencesCache: new Map(),
     incomingRelationsCache: new Map(),
     hasRateLimitedHandlerCached: false,
   };

package/src/engine/registry-validate.ts

@@ -1,6 +1,6 @@
 import { configureEventPiiCatalog } from "../crypto/event-pii";
 import { resolveName } from "./handler-helpers";
-import type { RegistryState } from "./registry-state";
+import type { RegistryState, SearchableReferenceField } from "./registry-state";
 import { buildImplicitProjection, hasFieldAccessRules, qualify } from "./registry-state";
 import {
   buildSoftDeleteCleanupJob,
@@ -10,7 +10,7 @@ import {
   SOFT_DELETE_GRACE_DAYS_KEY,
   softDeleteGraceDaysConfig,
 } from "./soft-delete-cleanup";
-import type { EventPiiFields, EventUpcastFn, FeatureDefinition } from "./types";
+import type { EventPiiFields, EventUpcastFn, FeatureDefinition, ReferenceFieldDef } from "./types";
 import { HookPhases } from "./types";
 
 function allHandlerQns(state: RegistryState): ReadonlySet<string> {
@@ -154,13 +154,50 @@ export function applyExtensionUsages(state: RegistryState): void {
   }
 }
 
-// Precompute: searchable/sortable fields.
-export function buildSearchableSortableCaches(state: RegistryState): void {
-  // Precompute: searchable/sortable fields, search includes, incoming relations
+// "customer" (same-feature) or "users:customer" (cross-feature,
+// "<featureName>:<entityName>") — only the entity name matters here, names
+// are globally unique in entityMap. Local duplicate of the same parse done
+// in db/eagerload.ts's parseRefEntity — this loop has no feature context to
+// hand to engine/parse-ref-target.ts's parseRefTarget.
+function parseReferenceTargetEntityName(raw: string): string {
+  const idx = raw.indexOf(":");
+  return idx < 0 ? raw : raw.slice(idx + 1);
+}
+
+// fw#2660: labelField defaults to "id" (a UUID column) elsewhere, but a
+// searchable reference ILIKEs the label column — an implicit or explicit
+// "id" default would 500 on every search request. Fail at boot.
+function buildSearchableReferenceField(
+  entityName: string,
+  fieldName: string,
+  field: ReferenceFieldDef,
+): SearchableReferenceField {
+  if (field.labelField === undefined || field.labelField === "id") {
+    throw new Error(
+      `[Entity ${entityName}] field "${fieldName}": searchable reference fields require an ` +
+        `explicit, non-"id" labelField. "id" is a UUID column — ILIKE against it fails ` +
+        `at request time. Set labelField to a human-readable field on the referenced entity.`,
+    );
+  }
+  if (field.multiple === true) {
+    throw new Error(
+      `[Entity ${entityName}] field "${fieldName}": searchable is not supported on multiple ` +
+        `(array) reference fields — remove "multiple" or "searchable".`,
+    );
+  }
+  return {
+    fieldName,
+    targetEntityName: parseReferenceTargetEntityName(field.entity),
+    labelField: field.labelField,
+  };
+}
 
+// Precompute: searchable/sortable fields, searchable reference fields.
+export function buildSearchableSortableCaches(state: RegistryState): void {
   for (const [name, entity] of state.entityMap) {
     const searchable: string[] = [];
     const sortable: string[] = [];
+    const searchableReferences: SearchableReferenceField[] = [];
     for (const [fieldName, field] of Object.entries(entity.fields)) {
       if (field.type === "text" && field.searchable === true) searchable.push(fieldName);
       if (field.type === "text" && field.sortable === true) sortable.push(fieldName);
@@ -169,9 +206,13 @@ export function buildSearchableSortableCaches(state: RegistryState): void {
           if (subField.searchable === true) searchable.push(`${fieldName}_${subName}`);
         }
       }
+      if (field.type === "reference" && field.searchable === true) {
+        searchableReferences.push(buildSearchableReferenceField(name, fieldName, field));
+      }
     }
     state.searchableFieldsCache.set(name, searchable);
     state.sortableFieldsCache.set(name, sortable);
+    state.searchableReferencesCache.set(name, searchableReferences);
   }
 }
 
@@ -223,16 +264,8 @@ export function buildImplicitProjections(
   }
 }
 
-export function buildSearchIncludesAndIncomingRelations(state: RegistryState): void {
+export function buildIncomingRelations(state: RegistryState): void {
   for (const [entityName, rels] of state.relationMap) {
-    const includes = new Map<string, readonly string[]>();
-    for (const [relName, rel] of Object.entries(rels)) {
-      if ((rel.type === "belongsTo" || rel.type === "manyToMany") && rel.searchInclude?.length) {
-        includes.set(relName, rel.searchInclude);
-      }
-    }
-    state.searchIncludesCache.set(entityName, includes);
-
     // Build reverse index for incoming relations
     for (const [relName, rel] of Object.entries(rels)) {
       const existing = state.incomingRelationsCache.get(rel.target) ?? [];

package/src/engine/registry.ts

@@ -20,8 +20,8 @@ import {
   autoWireSoftDeleteJobs,
   buildEventUpcasterChains,
   buildImplicitProjections,
+  buildIncomingRelations,
   buildSearchableSortableCaches,
-  buildSearchIncludesAndIncomingRelations,
   computeHasRateLimitedHandler,
   finalizeWorkspaceNavMembership,
   populateHandlerEntityMappings,
@@ -68,7 +68,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   applyExtensionUsages(state);
   buildSearchableSortableCaches(state);
   buildImplicitProjections(state, features);
-  buildSearchIncludesAndIncomingRelations(state);
+  buildIncomingRelations(state);
   validateFieldAccessHandlersAreEntityMapped(state, features);
   validateExtensionPreSaveWiring(features);
   validateRelationTargetsExist(state);

package/src/ui-types/index.ts

@@ -107,5 +107,13 @@ export type {
   QualifiedContentCollection,
   WorkspaceSchema,
 } from "./app-schema";
-export type { ListRowMetaColumnType, ListRowMetaReference } from "./list-row-meta";
-export { LIST_ROW_META_COLUMNS, LIST_ROW_META_REFERENCES } from "./list-row-meta";
+export type {
+  ListRowMetaColumnType,
+  ListRowMetaReference,
+  SystemReferenceLabel,
+} from "./list-row-meta";
+export {
+  LIST_ROW_META_COLUMNS,
+  LIST_ROW_META_REFERENCES,
+  SYSTEM_REFERENCE_LABELS,
+} from "./list-row-meta";

package/src/ui-types/list-row-meta.ts

@@ -12,6 +12,8 @@
 // deletedById) — this is also the SAME set the boot-validator's entityList
 // column checks accept, so a softDelete column stays a boot-time error
 // instead of a renderer-side throw (see screens.ts / entity-list-screens.ts).
+import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
+
 export type ListRowMetaColumnType = "text" | "number" | "timestamp";
 
 export const LIST_ROW_META_COLUMNS: Readonly<Record<string, ListRowMetaColumnType>> = {
@@ -39,3 +41,19 @@ export type ListRowMetaReference = {
 export const LIST_ROW_META_REFERENCES: Readonly<Record<string, ListRowMetaReference>> = {
   tenantId: { refFeature: "tenant", refEntity: "tenant", refLabelField: "name" },
 };
+
+export type SystemReferenceLabel = {
+  readonly id: string;
+  readonly labelKey: string;
+};
+
+// Reference ids that never resolve through the bulk id->row lookup because
+// no row exists for them (e.g. SYSTEM_TENANT_ID has no tenant record, see
+// isSystemTenant()) — every reference column falls back to the raw id
+// otherwise. Keyed by `${refFeature}:${refEntity}` so useReferenceLookup can
+// consult this generically instead of any screen/hook hardcoding an entity
+// name. Central so the label applies to every screen that references this
+// entity, not just delivery-log (fw#2662).
+export const SYSTEM_REFERENCE_LABELS: Readonly<Record<string, SystemReferenceLabel>> = {
+  "tenant:tenant": { id: SYSTEM_TENANT_ID, labelKey: "kumiko.reference.system-tenant" },
+};