@cosmicdrift/kumiko-framework 0.273.0 → 0.274.0

package/package.json

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

package/src/changes.json

@@ -1,4 +1,25 @@
 [
+  {
+    "version": "0.274.0",
+    "type": "breaking",
+    "title": "A searchable reference field targeting an encrypted/PII labelField now fails boot unless that label is itself searchable.",
+    "detail": "A searchable reference field can now match a search term against a target row's label even when that label is encrypted or personal data — the match runs through the target entity's own search index instead of the plain-text lookup used for a readable label, which could never match ciphertext and always returned zero matches. As with the plain-text lookup, an unusually large number of index matches drops the match clause instead of silently returning an incomplete page. A matched target row is also checked against the target entity's own read access for the current user, so a match can never surface a row the user could not otherwise see.",
+    "migration": "A searchable reference field whose target label is encrypted or personal data, but is not itself marked searchable (with fuzzy matching enabled if it also carries a personal-data annotation), now fails to boot instead of silently never matching at request time. Mark the target's label field searchable — with fuzzy matching if it holds personal data, so it is indexed for search — or remove the searchable flag from the reference field if the label was never meant to be searched."
+  },
+  {
+    "version": "0.274.0",
+    "type": "improvement",
+    "title": "Entity-list filters gain lte/gte comparison operators.",
+    "detail": "Entity-list filters — a screen's static filter, its faceted filters, and any handler built on the entity-list executor — now accept `lte` and `gte` alongside the existing `eq`/`ne`/`lt`/`gt`/`in`, so a \"valid as of today or earlier\" filter can be applied server-side instead of loading every row and filtering in memory. Allowed on the same field types as `lt`/`gt` (number/money/decimal/date/timestamp/locatedTimestamp) — the boot validator rejects them elsewhere the same way it already rejects `lt`/`gt`.",
+    "migration": "No action required — purely additive; existing filters and their allowed operators are unchanged."
+  },
+  {
+    "version": "0.274.0",
+    "type": "improvement",
+    "title": "Entity create handlers accept a caller-chosen id for idempotent creates from jobs/hooks.",
+    "detail": "`buildInsertSchema` — and every write handler built through `defineEntityCreateHandler`/`defineEntityWriteHandler`'s `create` verb — now accepts an optional `id` field validated as a UUID string. The create handler only honors it when the acting `SessionUser` is a system identity (`createSystemUser(tenantId, extraRoles)`; `extraRoles` is still needed to clear the handler's normal `hasAccess` role gate, and carrying `SYSTEM_ROLE` is what `isSystemIdentity` checks). An HTTP-authenticated end user's payload `id` is silently ignored and a fresh `generateId()` is minted, exactly as before this field existed — `SYSTEM_ROLE` is reserved and never assignable through tenant membership, so an ordinary caller can never present that identity. `executor.create()` already honored an explicit `id` (the seed/SCIM-import pattern); this only stops the generic create-handler schema from stripping it for a trusted caller. A same-id retry within the same tenant returns `version_conflict` (no duplicate row, no overwrite). A same id already used by a different tenant returns `unique_violation` instead — every entity's projection table has a plain `id` primary key that is not tenant-scoped, so the id space is shared per entity table across tenants; a deterministic id must fold the tenant id into its key to stay collision-free. New `generateDeterministicId(namespace, key)` (`@cosmicdrift/kumiko-framework/utils`, UUIDv5) sits next to `generateId()` for deriving such an id. The agent-tool manifest now lists `id` as an optional parameter on every entity's create tool; supplying it has no effect for a non-system caller, since agent-tool dispatch always passes the real caller's identity, never a system one.",
+    "migration": "No action for existing callers — the field is additive and inert for anyone but a system-identity caller, so no existing create request changes behavior. To create idempotently from an event-triggered job or hook: derive an id with `generateDeterministicId(namespace, key)` (fold the tenant id into `key` so two tenants can't collide), dispatch via `ctx.writeAs(createSystemUser(tenantId, [<a role your handler's access rule allows>]), qn, { ...payload, id })` instead of matching on description text or other business fields, and treat a `version_conflict` response as \"already created\"."
+  },
   {
     "version": "0.272.0",
     "type": "breaking",
@@ -27,13 +48,6 @@
     "migration": "Replace `crossTenant: true` with `escapeHatch: { reason: \"...\" }` on the same entity-convention handler call. Run `bun packages/framework/src/scripts/codemod/migrate-cross-tenant.ts [--dry-run] <path...>` first — it rewrites every `defineEntity*Handler`/`defineEntityWriteHandler`/`defineEntityQueryHandler` call whose entity name and verb it can read off the call itself, with a generated reason to replace with the concrete operator use case. Sites it lists as manual (a `crossTenant` on a shared/spread access object, a `registerEntityCrud` `write`/`read` block covering several verbs, a non-boolean-literal value, or an object that already declares `escapeHatch`) need a hand-written `escapeHatch: { reason }` per handler/verb.",
     "codemod": "scripts/codemod/migrate-cross-tenant.ts"
   },
-  {
-    "version": "0.271.0",
-    "type": "improvement",
-    "title": "Entity create handlers accept a caller-chosen id for idempotent creates from jobs/hooks.",
-    "detail": "`buildInsertSchema` — and every write handler built through `defineEntityCreateHandler`/`defineEntityWriteHandler`'s `create` verb — now accepts an optional `id` field validated as a UUID string. The create handler only honors it when the acting `SessionUser` is a system identity (`createSystemUser(tenantId, extraRoles)`; `extraRoles` is still needed to clear the handler's normal `hasAccess` role gate, and carrying `SYSTEM_ROLE` is what `isSystemIdentity` checks). An HTTP-authenticated end user's payload `id` is silently ignored and a fresh `generateId()` is minted, exactly as before this field existed — `SYSTEM_ROLE` is reserved and never assignable through tenant membership, so an ordinary caller can never present that identity. `executor.create()` already honored an explicit `id` (the seed/SCIM-import pattern); this only stops the generic create-handler schema from stripping it for a trusted caller. A same-id retry within the same tenant returns `version_conflict` (no duplicate row, no overwrite). A same id already used by a different tenant returns `unique_violation` instead — every entity's projection table has a plain `id` primary key that is not tenant-scoped, so the id space is shared per entity table across tenants; a deterministic id must fold the tenant id into its key to stay collision-free. New `generateDeterministicId(namespace, key)` (`@cosmicdrift/kumiko-framework/utils`, UUIDv5) sits next to `generateId()` for deriving such an id. The agent-tool manifest now lists `id` as an optional parameter on every entity's create tool; supplying it has no effect for a non-system caller, since agent-tool dispatch always passes the real caller's identity, never a system one.",
-    "migration": "No action for existing callers — the field is additive and inert for anyone but a system-identity caller, so no existing create request changes behavior. To create idempotently from an event-triggered job or hook: derive an id with `generateDeterministicId(namespace, key)` (fold the tenant id into `key` so two tenants can't collide), dispatch via `ctx.writeAs(createSystemUser(tenantId, [<a role your handler's access rule allows>]), qn, { ...payload, id })` instead of matching on description text or other business fields, and treat a `version_conflict` response as \"already created\"."
-  },
   {
     "version": "0.271.0",
     "type": "breaking",

package/src/db/__tests__/build-filter-where.test.ts

@@ -26,6 +26,14 @@ describe("buildFilterWhere", () => {
     expect(buildFilterWhere("createdAt", "gt", 100)).toEqual({ createdAt: { gt: 100 } });
   });
 
+  test("lte: wraps the value in a { lte } clause", () => {
+    expect(buildFilterWhere("createdAt", "lte", 100)).toEqual({ createdAt: { lte: 100 } });
+  });
+
+  test("gte: wraps the value in a { gte } clause", () => {
+    expect(buildFilterWhere("createdAt", "gte", 100)).toEqual({ createdAt: { gte: 100 } });
+  });
+
   test("in: non-empty array → direct array WhereObject", () => {
     expect(buildFilterWhere("status", "in", ["active", "pending"])).toEqual({
       status: ["active", "pending"],

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

@@ -283,6 +283,75 @@ describe("event-store-executor.list — filter (Tier 2.7c)", () => {
     expect(res.rows.map((r) => r["rank"])).toEqual([8, 9]);
   });
 
+  test("filter lte: rank <= 3 → 0,1,2,3 (boundary included)", async () => {
+    await seed(6);
+    const res = await exec.list(
+      {
+        limit: 50,
+        sort: "rank",
+        sortDirection: "asc",
+        filter: { field: "rank", op: "lte", value: 3 },
+      },
+      admin,
+      tdb,
+    );
+    expect(res.rows.map((r) => r["rank"])).toEqual([0, 1, 2, 3]);
+  });
+
+  test("filter gte: rank >= 7 → 7,8,9 (boundary included)", async () => {
+    await seed(10);
+    const res = await exec.list(
+      {
+        limit: 50,
+        sort: "rank",
+        sortDirection: "asc",
+        filter: { field: "rank", op: "gte", value: 7 },
+      },
+      admin,
+      tdb,
+    );
+    expect(res.rows.map((r) => r["rank"])).toEqual([7, 8, 9]);
+  });
+
+  test("filter lte on dueDate: boundary date included", async () => {
+    await exec.create({ title: "d-1", dueDate: "2026-01-10" }, admin, tdb);
+    await exec.create({ title: "d-2", dueDate: "2026-02-10" }, admin, tdb);
+    await exec.create({ title: "d-3", dueDate: "2026-03-10" }, admin, tdb);
+    const res = await exec.list(
+      {
+        limit: 50,
+        sort: "dueDate",
+        sortDirection: "asc",
+        filter: { field: "dueDate", op: "lte", value: "2026-02-10" },
+      },
+      admin,
+      tdb,
+    );
+    expect(res.rows.map((r) => r["title"])).toEqual(["d-1", "d-2"]);
+  });
+
+  test("filters[] gte+lte AND, kombiniert mit offset-Paging: zweite Seite korrekt", async () => {
+    await seed(10);
+    const res = await exec.list(
+      {
+        limit: 2,
+        offset: 2,
+        sort: "rank",
+        sortDirection: "asc",
+        totalCount: true,
+        filters: [
+          { field: "rank", op: "gte", value: 2 },
+          { field: "rank", op: "lte", value: 7 },
+        ],
+      },
+      admin,
+      tdb,
+    );
+    // range gte:2/lte:7 → [2,3,4,5,6,7] (6 rows), page size 2 offset 2 → [4,5]
+    expect(res.rows.map((r) => r["rank"])).toEqual([4, 5]);
+    expect(res.total).toBe(6);
+  });
+
   test("filter in: rank in [1,3,5]", async () => {
     await seed(10);
     const res = await exec.list(

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

@@ -9,7 +9,7 @@
 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 { createEntity, createTextField, from } from "../../engine";
 import type { EntityDefinition } from "../../engine/types";
 import { createEventsTable } from "../../event-store";
 import { createInMemorySearchAdapter } from "../../search";
@@ -70,6 +70,45 @@ const tenantMetaEntity = createEntity({
 });
 const tenantMetaTable = buildEntityTable("tenant", tenantMetaEntity);
 
+// PII target with a derived search index — ciphertext at rest, plaintext
+// mirrored into the adapter; `ownerId` + `access.read` gives a real row-owned rule.
+const piiCustomerEntity = createEntity({
+  table: "read_ref_search_pii_customers",
+  fields: {
+    ownerId: createTextField({ personal: false, reason: "test_fixture", required: true }),
+    name: createTextField({ required: true, personal: "self", find: "fuzzy" }),
+  },
+  access: {
+    read: { Admin: "all", User: from("user:id", "ownerId") },
+  },
+});
+const piiCustomerTable = buildEntityTable("refSearchPiiCustomer", piiCustomerEntity);
+
+const piiOrderEntity = createEntity({
+  table: "read_ref_search_pii_orders",
+  fields: {
+    note: createTextField({ searchable: true, personal: false, reason: "test_fixture" }),
+    customerId: {
+      type: "reference",
+      entity: "refSearchPiiCustomer",
+      labelField: "name",
+      searchable: true,
+    },
+  },
+});
+const piiOrderTable = buildEntityTable("refSearchPiiOrder", piiOrderEntity);
+
+function resolvePiiEntity(name: string): EntityDefinition | undefined {
+  return name === "refSearchPiiCustomer" ? piiCustomerEntity : undefined;
+}
+
+const piiReferenceSearch = {
+  fields: [
+    { fieldName: "customerId", targetEntityName: "refSearchPiiCustomer", labelField: "name" },
+  ],
+  resolveEntity: resolvePiiEntity,
+};
+
 function resolveEntity(name: string): EntityDefinition | undefined {
   return name === "refSearchCustomer" ? customerEntity : undefined;
 }
@@ -104,6 +143,9 @@ const orderExec = createEventStoreExecutor(orderTable, orderEntity, {
 const restrictedOrderExec = createEventStoreExecutor(restrictedOrderTable, restrictedOrderEntity, {
   entityName: "refSearchRestrictedOrder",
 });
+const piiOrderExec = createEventStoreExecutor(piiOrderTable, piiOrderEntity, {
+  entityName: "refSearchPiiOrder",
+});
 
 beforeAll(async () => {
   await ensureTemporalPolyfill();
@@ -111,6 +153,8 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(testDb.db, customerEntity, "refSearchCustomer");
   await unsafeCreateEntityTable(testDb.db, orderEntity, "refSearchOrder");
   await unsafeCreateEntityTable(testDb.db, restrictedOrderEntity, "refSearchRestrictedOrder");
+  await unsafeCreateEntityTable(testDb.db, piiCustomerEntity, "refSearchPiiCustomer");
+  await unsafeCreateEntityTable(testDb.db, piiOrderEntity, "refSearchPiiOrder");
   await unsafeCreateEntityTable(testDb.db, tenantMetaEntity, "tenant");
   await createEventsTable(testDb.db);
   tdbA = createTenantDb(testDb.db, admin.tenantId);
@@ -124,7 +168,8 @@ afterAll(async () => {
 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",
+      "read_ref_search_restricted_orders, read_ref_search_pii_customers, " +
+      "read_ref_search_pii_orders, read_tenants RESTART IDENTITY CASCADE",
   );
 });
 
@@ -379,3 +424,222 @@ describe("event-store-executor.list — searchable reference fields (fw#2660)",
     }
   });
 });
+
+describe("event-store-executor.list — searchable reference to an encrypted/PII labelField via the search index", () => {
+  test('matches via the target\'s derived search index when the labelField is PII (find: "fuzzy")', async () => {
+    const [contact] = await seedRows(testDb.db, piiCustomerTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        ownerId: admin.id,
+        name: "Confidential Contact",
+      },
+    ]);
+    const [order] = await seedRows(testDb.db, piiOrderTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        note: "totally unrelated",
+        customerId: (contact as { id: string }).id,
+      },
+    ]);
+
+    const searchAdapter = createInMemorySearchAdapter();
+    // One shared per-tenant index across every entity type (real Meilisearch
+    // adapter parity: one index per tenant, `_type` is only a filter
+    // attribute) — `searchableFields` must list every entity's own
+    // searchable field, not just this test's own entity's.
+    await searchAdapter.configure(admin.tenantId, { searchableFields: ["note", "name"] });
+    // Plaintext label lives in the search adapter under the target's own
+    // type — never a raw ILIKE scan of the (encrypted-at-rest) column.
+    await searchAdapter.index(admin.tenantId, {
+      entityType: "refSearchPiiCustomer",
+      entityId: (contact as { id: string }).id,
+      weight: 1,
+      fields: { name: "Confidential Contact" },
+    });
+
+    const res = await piiOrderExec.list({ search: "confidential" }, admin, tdbA, {
+      searchAdapter,
+      referenceSearch: piiReferenceSearch,
+    });
+    expect(res.rows.map((r) => r["id"])).toEqual([(order as { id: string }).id]);
+  });
+
+  test("drops the reference clause above 200 search-index matches — native search still applies", async () => {
+    const fooCustomers = Array.from({ length: 201 }, (_, i) => ({
+      id: crypto.randomUUID(),
+      tenantId: admin.tenantId,
+      ownerId: admin.id,
+      name: `Foo Contact ${i}`,
+    }));
+    await seedRows(testDb.db, piiCustomerTable, fooCustomers);
+
+    const [refOnlyOrder, textMatchOrder] = await seedRows(testDb.db, piiOrderTable, [
+      {
+        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", "name"] });
+    for (const c of fooCustomers) {
+      await searchAdapter.index(admin.tenantId, {
+        entityType: "refSearchPiiCustomer",
+        entityId: c.id,
+        weight: 1,
+        fields: { name: c.name },
+      });
+    }
+    for (const o of [refOnlyOrder, textMatchOrder]) {
+      const row = o as { id: string; note: string };
+      await searchAdapter.index(admin.tenantId, {
+        entityType: "refSearchPiiOrder",
+        entityId: row.id,
+        weight: 1,
+        fields: { note: row.note },
+      });
+    }
+
+    const res = await piiOrderExec.list({ search: "foo" }, admin, tdbA, {
+      searchAdapter,
+      referenceSearch: piiReferenceSearch,
+    });
+    expect(res.rows.map((r) => r["id"])).toEqual([(textMatchOrder as { id: string }).id]);
+  });
+
+  test("a target label match in a foreign tenant's search index never surfaces a row (mandatory)", async () => {
+    const [contact] = await seedRows(testDb.db, piiCustomerTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: otherTenantAdmin.tenantId,
+        ownerId: otherTenantAdmin.id,
+        name: "Foreign Contact",
+      },
+    ]);
+    await seedRows(testDb.db, piiOrderTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: otherTenantAdmin.tenantId,
+        note: "unrelated",
+        customerId: (contact as { id: string }).id,
+      },
+    ]);
+
+    const searchAdapter = createInMemorySearchAdapter();
+    await searchAdapter.configure(admin.tenantId, { searchableFields: ["note"] });
+    // Indexed only under the OTHER tenant's search index — admin's own
+    // search must never see it, regardless of the FK row's actual tenantId.
+    await searchAdapter.index(otherTenantAdmin.tenantId, {
+      entityType: "refSearchPiiCustomer",
+      entityId: (contact as { id: string }).id,
+      weight: 1,
+      fields: { name: "Foreign Contact" },
+    });
+
+    const res = await piiOrderExec.list({ search: "foreign" }, admin, tdbA, {
+      searchAdapter,
+      referenceSearch: piiReferenceSearch,
+    });
+    expect(res.rows).toHaveLength(0);
+  });
+
+  test("row-level ownership on the target entity intersects the search-index candidates, same as the target's own list would", async () => {
+    const [ownRow, otherRow] = await seedRows(testDb.db, piiCustomerTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        ownerId: TestUsers.user.id,
+        name: "Shared Label",
+      },
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        ownerId: admin.id,
+        name: "Shared Label",
+      },
+    ]);
+    const [ownOrder, otherOrder] = await seedRows(testDb.db, piiOrderTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        note: "n1",
+        customerId: (ownRow as { id: string }).id,
+      },
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        note: "n2",
+        customerId: (otherRow as { id: string }).id,
+      },
+    ]);
+
+    const searchAdapter = createInMemorySearchAdapter();
+    await searchAdapter.configure(admin.tenantId, { searchableFields: ["note", "name"] });
+    for (const row of [ownRow, otherRow]) {
+      const r = row as { id: string; name: string };
+      await searchAdapter.index(admin.tenantId, {
+        entityType: "refSearchPiiCustomer",
+        entityId: r.id,
+        weight: 1,
+        fields: { name: r.name },
+      });
+    }
+
+    // Both customers match "shared" in the index — the search index itself
+    // has no ownership awareness. Only the order pointing at the customer
+    // TestUsers.user (role "User") actually owns via ownerId may surface.
+    const res = await piiOrderExec.list({ search: "shared" }, TestUsers.user, tdbA, {
+      searchAdapter,
+      referenceSearch: piiReferenceSearch,
+    });
+    expect(res.rows.map((r) => r["id"])).toEqual([(ownOrder as { id: string }).id]);
+    expect(res.rows.map((r) => r["id"])).not.toContain((otherOrder as { id: string }).id);
+  });
+
+  test("a role with no read grant on the target entity gets no reference-match hit at all", async () => {
+    const [contact] = await seedRows(testDb.db, piiCustomerTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        ownerId: admin.id,
+        name: "Driver Blind Spot",
+      },
+    ]);
+    await seedRows(testDb.db, piiOrderTable, [
+      {
+        id: crypto.randomUUID(),
+        tenantId: admin.tenantId,
+        note: "unrelated",
+        customerId: (contact as { id: string }).id,
+      },
+    ]);
+
+    const searchAdapter = createInMemorySearchAdapter();
+    await searchAdapter.configure(admin.tenantId, { searchableFields: ["note", "name"] });
+    await searchAdapter.index(admin.tenantId, {
+      entityType: "refSearchPiiCustomer",
+      entityId: (contact as { id: string }).id,
+      weight: 1,
+      fields: { name: "Driver Blind Spot" },
+    });
+
+    // "Driver" has no rule at all on piiCustomerEntity.access.read →
+    // buildOwnershipClause returns "empty" — no reference-match hit, no
+    // matter what the search index found.
+    const res = await piiOrderExec.list({ search: "driver" }, TestUsers.driver, tdbA, {
+      searchAdapter,
+      referenceSearch: piiReferenceSearch,
+    });
+    expect(res.rows).toHaveLength(0);
+  });
+});

package/src/db/entity-field-encryption.ts

@@ -4,6 +4,7 @@
 // single-key ciphertexts (pre-envelope ENCRYPTION_KEY era) readable via
 // the cipher's legacy fallback until re-encrypted.
 
+import { collectPiiSubjectFields } from "../crypto";
 import type { EntityDefinition, TenantId } from "../engine/types";
 import { createEnvMasterKeyProvider } from "../secrets/env-master-key-provider";
 import type { EnvelopeCipher } from "../secrets/envelope-cipher";
@@ -19,6 +20,23 @@ export function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySe
   return names;
 }
 
+// A field whose stored value is ciphertext, either always (encrypted) or
+// depending on runtime KMS wiring (PII) — either way it has no plaintext
+// column to compare against directly.
+export function isSensitiveLabelField(entity: EntityDefinition, field: string): boolean {
+  return (
+    collectEncryptedFieldNames(entity).has(field) || collectPiiSubjectFields(entity).includes(field)
+  );
+}
+
+// `searchable: true` on a text field means it is indexed plaintext
+// somewhere findable by term — a plain text field's own column, or (for a
+// personal-data field) the derived search index mirroring it.
+export function hasSearchablePlaintext(entity: EntityDefinition, field: string): boolean {
+  const def = entity.fields[field];
+  return def?.type === "text" && def.searchable === true;
+}
+
 // BYOK hook: thread the row's tenant to the cipher when the row carries one
 // (system-scope rows may not).
 function scopeOf(row: Record<string, unknown>): KeyScope | undefined {

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

@@ -51,11 +51,11 @@ export type Table = TableColumns<any>;
 
 // Screen-Filter (Tier 2.7c) — Op-Mapping als Where-Operator. Boot-
 // Validator pinst field-Existenz + filterable + op-vs-Type-Compat.
-// `op` ist auf {eq,ne,lt,gt,in} normalisiert; "in" mit empty-array ist
-// explizit no-match.
+// `op` ist auf {eq,ne,lt,gt,lte,gte,in} normalisiert; "in" mit
+// empty-array ist explizit no-match.
 export function buildFilterWhere(
   field: string,
-  op: "eq" | "ne" | "lt" | "gt" | "in",
+  op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in",
   value: unknown,
 ): WhereObject | null {
   switch (op) {
@@ -67,6 +67,10 @@ export function buildFilterWhere(
       return { [field]: { lt: value } };
     case "gt":
       return { [field]: { gt: value } };
+    case "lte":
+      return { [field]: { lte: value } };
+    case "gte":
+      return { [field]: { gte: value } };
     case "in":
       if (Array.isArray(value) && value.length > 0) {
         return { [field]: value };

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

@@ -9,14 +9,19 @@ import {
   normalizeAccessEntry,
   shiftParams,
 } from "../engine/ownership";
-import type { EntityDefinition, EntityId } from "../engine/types";
+import type { EntityDefinition, EntityId, SessionUser } from "../engine/types";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
 import { UnprocessableError } from "../errors";
 import { getStreamVersion } from "../event-store";
+import type { SearchAdapter } from "../search/types";
 import { LIST_ROW_META_REFERENCES } from "../ui-types/list-row-meta";
 import { rehydrateCompoundTypes } from "./compound-types";
 import { decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor";
-import { collectEncryptedFieldNames } from "./entity-field-encryption";
+import {
+  collectEncryptedFieldNames,
+  hasSearchablePlaintext,
+  isSensitiveLabelField,
+} from "./entity-field-encryption";
 import type { EventStoreExecutor } from "./event-store-executor";
 import { buildFilterWhere, type ExecutorContext, type Table } from "./event-store-executor-context";
 import { buildParentRefClause } from "./parent-ref-clause";
@@ -104,26 +109,27 @@ function keysetBoundarySql(
 
 type ListFilter = {
   readonly field: string;
-  readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+  readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
   readonly value: unknown;
 };
 
 // multiSelect stores its options as a jsonb array — a filter value is one
 // option, not the whole array, so eq/ne/in must check array containment
 // (`@>`) instead of scalar `=`/`<>`/`IN` against the jsonb column (fw#2490).
-// lt/gt have no containment analogue; the boot-validator already blocks them
-// for screen-declared filters (screen-filter-ops.ts EQUALITY_ONLY), but a
-// client-supplied facet filter reaches here unvalidated, so treat it as
-// unsatisfiable rather than emitting SQL Postgres would reject.
+// lt/gt/lte/gte have no containment analogue; the boot-validator already
+// blocks them for screen-declared filters (screen-filter-ops.ts
+// EQUALITY_ONLY), but a client-supplied facet filter reaches here
+// unvalidated, so treat it as unsatisfiable rather than emitting SQL
+// Postgres would reject.
 function applyMultiSelectFilter(
   colSql: (field: string) => string,
   whereSql: string[],
   params: unknown[],
   f: ListFilter,
 ): void {
-  if (f.op === "lt" || f.op === "gt") {
+  if (f.op === "lt" || f.op === "gt" || f.op === "lte" || f.op === "gte") {
     whereSql.push("FALSE");
-    // skip: lt/gt is unsatisfiable on a multiSelect column
+    // skip: lt/gt/lte/gte is unsatisfiable on a multiSelect column
     return;
   }
   if (f.op === "in") {
@@ -290,11 +296,86 @@ function collectReferenceSearchDescriptors(
 // unscoped SQL, a match in a foreign tenant must never surface a row here
 // (fw#2660's hard constraint). Mirrors the main table's own tenant filter
 // (see the `table["tenantId"]` check further down in list()).
+async function resolveReferenceMatchesViaIlike(
+  descriptor: ReferenceSearchDescriptor,
+  searchTerm: string,
+  targetTable: Table,
+  targetTableName: string,
+  db: TenantDb,
+): Promise<{ readonly ownColumn: string; readonly ids: readonly string[] } | undefined> {
+  const labelCol = physicalColumnName(targetTable, descriptor.labelField);
+  const subParams: unknown[] = [`%${escapeLikePattern(searchTerm)}%`];
+  let tenantClause = "";
+  if (targetTable["tenantId"] !== undefined && db.mode === "tenant") {
+    subParams.push(db.tenantId, SYSTEM_TENANT_ID);
+    tenantClause = ` AND "${physicalColumnName(targetTable, "tenantId")}" IN ($2, $3)`;
+  }
+  // ::text cast covers a non-text labelField (e.g. a number/select column
+  // used as label) — Postgres has no ILIKE for those types otherwise.
+  const sql =
+    `SELECT "id" FROM "${targetTableName}" WHERE ("${labelCol}")::text ILIKE $1${tenantClause} ` +
+    `LIMIT ${MAX_REFERENCE_SEARCH_IDS + 1}`;
+  const rows = await executeRawQueryRead<{ id: string }>(tenantDbRunner(db), sql, subParams);
+  if (rows.length === 0 || rows.length > MAX_REFERENCE_SEARCH_IDS) {
+    // skip: no match, or over the cap — drop the clause rather than
+    // truncate to an arbitrary slice of matching targets
+    return undefined;
+  }
+  return { ownColumn: descriptor.ownColumn, ids: rows.map((r) => r.id) };
+}
+
+// Same lookup, but the target's index is tenant-wide, not per-viewer, so
+// candidate ids get re-checked against the target entity's own read access.
+async function resolveReferenceMatchesViaSearchIndex(
+  descriptor: ReferenceSearchDescriptor,
+  searchTerm: string,
+  targetEntity: EntityDefinition,
+  targetTable: Table,
+  targetTableName: string,
+  user: SessionUser,
+  db: TenantDb,
+  searchAdapter: SearchAdapter,
+): Promise<{ readonly ownColumn: string; readonly ids: readonly string[] } | undefined> {
+  const searchTenantId = targetEntity.systemStream ? SYSTEM_TENANT_ID : user.tenantId;
+  const results = await searchAdapter.search(searchTenantId, searchTerm, {
+    filterType: descriptor.targetEntityName,
+    limit: MAX_REFERENCE_SEARCH_IDS + 1,
+  });
+  if (results.length === 0 || results.length > MAX_REFERENCE_SEARCH_IDS) {
+    // skip: no match, or over the cap — same drop-the-clause policy as the ILIKE path
+    return undefined;
+  }
+
+  const ownership = buildOwnershipClause(user, targetEntity.access?.read, targetTable);
+  if (ownership.kind === "empty") return undefined;
+
+  const candidateIds = results.map((r) => String(r.entityId));
+  if (ownership.kind === "pass") {
+    return { ownColumn: descriptor.ownColumn, ids: candidateIds };
+  }
+
+  const params: unknown[] = [...candidateIds];
+  const idPlaceholders = candidateIds.map((_, i) => `$${i + 1}`);
+  const shifted = shiftParams(
+    { sqlText: ownership.sqlText, params: ownership.params },
+    params.length,
+  );
+  const sql =
+    `SELECT "id" FROM "${targetTableName}" WHERE "id" IN (${idPlaceholders.join(", ")}) ` +
+    `AND ${shifted.sqlText}`;
+  for (const p of shifted.params) params.push(p);
+  const rows = await executeRawQueryRead<{ id: string }>(tenantDbRunner(db), sql, params);
+  if (rows.length === 0) return undefined;
+  return { ownColumn: descriptor.ownColumn, ids: rows.map((r) => r.id) };
+}
+
 async function resolveReferenceMatches(
   descriptor: ReferenceSearchDescriptor,
   searchTerm: string,
   resolveEntity: (entityName: string) => EntityDefinition | undefined,
   db: TenantDb,
+  user: SessionUser,
+  searchAdapter: SearchAdapter,
 ): Promise<{ readonly ownColumn: string; readonly ids: readonly string[] } | undefined> {
   const targetEntity = resolveEntity(descriptor.targetEntityName);
   if (targetEntity === undefined) {
@@ -308,38 +389,36 @@ async function resolveReferenceMatches(
     // `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)`;
+
+  if (!isSensitiveLabelField(targetEntity, descriptor.labelField)) {
+    return resolveReferenceMatchesViaIlike(
+      descriptor,
+      searchTerm,
+      targetTable,
+      targetTableName,
+      db,
+    );
   }
-  // ::text cast covers a non-text labelField (e.g. a number/select column
-  // used as label) — Postgres has no ILIKE for those types otherwise.
-  const sql =
-    `SELECT "id" FROM "${targetTableName}" WHERE ("${labelCol}")::text ILIKE $1${tenantClause} ` +
-    `LIMIT ${MAX_REFERENCE_SEARCH_IDS + 1}`;
-  const rows = await executeRawQueryRead<{ id: string }>(tenantDbRunner(db), sql, subParams);
-  if (rows.length === 0 || rows.length > MAX_REFERENCE_SEARCH_IDS) {
-    // skip: no match, or over the cap — drop the clause rather than
-    // truncate to an arbitrary slice of matching targets
+  if (!hasSearchablePlaintext(targetEntity, descriptor.labelField)) {
+    // skip: no plaintext anywhere to match — boot rejects this normally,
+    // this is defense-in-depth for a target entity resolved only at runtime.
     return undefined;
   }
-  return { ownColumn: descriptor.ownColumn, ids: rows.map((r) => r.id) };
+  return resolveReferenceMatchesViaSearchIndex(
+    descriptor,
+    searchTerm,
+    targetEntity,
+    targetTable,
+    targetTableName,
+    user,
+    db,
+    searchAdapter,
+  );
 }
 
 // Projected alongside the row when a reference sort is active, so the keyset
@@ -517,7 +596,14 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
           ? (
               await Promise.all(
                 descriptors.map((d) =>
-                  resolveReferenceMatches(d, searchTerm, referenceSearch.resolveEntity, db),
+                  resolveReferenceMatches(
+                    d,
+                    searchTerm,
+                    referenceSearch.resolveEntity,
+                    db,
+                    user,
+                    effectiveSearchAdapter,
+                  ),
                 ),
               )
             ).filter(

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

@@ -2306,7 +2306,7 @@ describe("boot-validator", () => {
     function makeFeature(
       filter: {
         readonly field: string;
-        readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+        readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
         readonly value: unknown;
       },
       fields: Record<string, unknown> = {
@@ -2365,6 +2365,25 @@ describe("boot-validator", () => {
       ).not.toThrow();
     });
 
+    test("filter.op=lte/gte auf number-Feld → kein Throw (vergleichbar)", () => {
+      const fields = {
+        name: { type: "text", filterable: true },
+        rank: { type: "number", filterable: true },
+      };
+      expect(() =>
+        validateBoot([makeFeature({ field: "rank", op: "lte", value: 5 }, fields)]),
+      ).not.toThrow();
+      expect(() =>
+        validateBoot([makeFeature({ field: "rank", op: "gte", value: 5 }, fields)]),
+      ).not.toThrow();
+    });
+
+    test("filter.op=lte auf text-Feld → Throw (op-vs-Type-Compat)", () => {
+      expect(() => validateBoot([makeFeature({ field: "status", op: "lte", value: "x" })])).toThrow(
+        /filter\.op "lte" is not allowed on field "status" \(type "text"\)/,
+      );
+    });
+
     test('filter.op="in" mit non-array value → Throw', () => {
       expect(() =>
         validateBoot([makeFeature({ field: "status", op: "in", value: "active" })]),

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

@@ -754,6 +754,92 @@ describe("createRegistry", () => {
     expect(() => createRegistry([feature])).toThrow(/multiple/);
   });
 
+  test("throws at boot when a searchable reference targets an encrypted labelField", () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "customer",
+        createEntity({
+          table: "Customers",
+          fields: {
+            name: createTextField({ personal: false, reason: "test_fixture", encrypted: true }),
+          },
+        }),
+      );
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            customerId: {
+              type: "reference",
+              entity: "customer",
+              labelField: "name",
+              searchable: true,
+            },
+          },
+        }),
+      );
+    });
+
+    expect(() => createRegistry([feature])).toThrow(/encrypted\/PII/);
+  });
+
+  test('throws at boot when a searchable reference targets a PII labelField without find: "fuzzy" (no plaintext index)', () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "contact",
+        createEntity({
+          table: "Contacts",
+          fields: { displayName: createTextField({ personal: "self", find: "exact" }) },
+        }),
+      );
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            contactId: {
+              type: "reference",
+              entity: "contact",
+              labelField: "displayName",
+              searchable: true,
+            },
+          },
+        }),
+      );
+    });
+
+    expect(() => createRegistry([feature])).toThrow(/encrypted\/PII/);
+  });
+
+  test('does not throw when a searchable reference targets a PII labelField with find: "fuzzy" (derived search index)', () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "contact",
+        createEntity({
+          table: "Contacts",
+          fields: { displayName: createTextField({ personal: "self", find: "fuzzy" }) },
+        }),
+      );
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            contactId: {
+              type: "reference",
+              entity: "contact",
+              labelField: "displayName",
+              searchable: true,
+            },
+          },
+        }),
+      );
+    });
+
+    expect(() => createRegistry([feature])).not.toThrow();
+  });
+
   test("returns sortable reference fields for entity, without leaking them into getSortableFields (fw#2741)", () => {
     const feature = defineFeature("crm", (r) => {
       r.entity(

package/src/engine/__tests__/screen-filter-ops.test.ts

@@ -3,7 +3,7 @@ import { createDecimalField, createMoneyField, createNumberField } from "../fact
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
 import type { ScreenFilterOp } from "../types";
 
-const COMPARABLE: ScreenFilterOp[] = ["eq", "ne", "lt", "gt", "in"];
+const COMPARABLE: ScreenFilterOp[] = ["eq", "ne", "lt", "gt", "lte", "gte", "in"];
 
 describe("getAllowedFilterOps — decimal is comparable (#343/1)", () => {
   test("decimal yields the full comparable op-set, not the empty default", () => {

package/src/engine/boot-validator/projection-list-screens.ts

@@ -96,7 +96,7 @@ function validateProjectionListFilterSchemaAcceptance(
   if (screen.filter === undefined || schemaAccepts(schema, "filter")) return;
   throw new Error(
     `${prefix}: declares filter but query "${screen.query}" has no "filter" parameter in its Zod ` +
-      `schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","in"]), ` +
+      `schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","lte","gte","in"]), ` +
       `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`,
   );
 }
@@ -203,7 +203,7 @@ function validateRelatedListParentFilter(
   if (!schemaAccepts(schema, "filter")) {
     throw new Error(
       `${prefix}: declares parentFilter but query "${section.query}" has no "filter" parameter in its ` +
-        `Zod schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","in"]), ` +
+        `Zod schema — add filter: z.object({ field: z.string(), op: z.enum(["eq","ne","lt","gt","lte","gte","in"]), ` +
         `value: z.unknown() }).optional() (or reuse entityListSchema's shape) to the handler's schema.`,
     );
   }

package/src/engine/entity-handlers.ts

@@ -102,7 +102,7 @@ type ListPayload = {
   // den gleichen Query-Handler.
   filter?: {
     readonly field: string;
-    readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+    readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
     readonly value: unknown;
   };
 };
@@ -157,7 +157,7 @@ export const entityListSchema = z.object({
   filter: z
     .object({
       field: z.string(),
-      op: z.enum(["eq", "ne", "lt", "gt", "in"]),
+      op: z.enum(["eq", "ne", "lt", "gt", "lte", "gte", "in"]),
       // Value ist `unknown` zur Compile-Zeit; Server-Side prüft beim
       // Build der WHERE-Clause ob der Type zum Field passt. z.unknown()
       // lässt alles durch; Type-Check kommt im executor.list.
@@ -170,7 +170,7 @@ export const entityListSchema = z.object({
     .array(
       z.object({
         field: z.string(),
-        op: z.enum(["eq", "ne", "lt", "gt", "in"]),
+        op: z.enum(["eq", "ne", "lt", "gt", "lte", "gte", "in"]),
         value: z.unknown(),
       }),
     )

package/src/engine/registry-validate.ts

@@ -1,4 +1,5 @@
 import { configureEventPiiCatalog } from "../crypto/event-pii";
+import { hasSearchablePlaintext, isSensitiveLabelField } from "../db/entity-field-encryption";
 import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch";
 import { resolveName } from "./handler-helpers";
 import type {
@@ -16,6 +17,7 @@ import {
   softDeleteGraceDaysConfig,
 } from "./soft-delete-cleanup";
 import type {
+  EntityDefinition,
   EventPiiFields,
   EventUpcastFn,
   FeatureDefinition,
@@ -206,6 +208,7 @@ function buildSearchableReferenceField(
   entityName: string,
   fieldName: string,
   field: ReferenceFieldDef,
+  entityMap: ReadonlyMap<string, EntityDefinition>,
 ): SearchableReferenceField {
   if (field.labelField === undefined || field.labelField === "id") {
     throw new Error(
@@ -220,9 +223,26 @@ function buildSearchableReferenceField(
         `(array) reference fields — remove "multiple" or "searchable".`,
     );
   }
+  const targetEntityName = parseReferenceTargetEntityName(field.entity);
+  const targetEntity = entityMap.get(targetEntityName);
+  if (targetEntity !== undefined) {
+    if (
+      isSensitiveLabelField(targetEntity, field.labelField) &&
+      !hasSearchablePlaintext(targetEntity, field.labelField)
+    ) {
+      throw new Error(
+        `[Entity ${entityName}] field "${fieldName}": searchable reference targets ` +
+          `"${targetEntityName}.${field.labelField}", which is encrypted/PII and not itself ` +
+          `searchable — there is no plaintext anywhere to match a search term against. Mark ` +
+          `"${targetEntityName}.${field.labelField}" searchable: true (add find: "fuzzy" if it ` +
+          `also carries a personal annotation, so it lands in the derived search index) or ` +
+          `remove searchable from "${fieldName}".`,
+      );
+    }
+  }
   return {
     fieldName,
-    targetEntityName: parseReferenceTargetEntityName(field.entity),
+    targetEntityName,
     labelField: field.labelField,
   };
 }
@@ -273,7 +293,9 @@ export function buildSearchableSortableCaches(state: RegistryState): void {
         }
       }
       if (field.type === "reference" && field.searchable === true) {
-        searchableReferences.push(buildSearchableReferenceField(name, fieldName, field));
+        searchableReferences.push(
+          buildSearchableReferenceField(name, fieldName, field, state.entityMap),
+        );
       }
       if (field.type === "reference" && field.sortable === true) {
         sortableReferences.push(buildSortableReferenceField(name, fieldName, field));

package/src/engine/screen-filter-ops.ts

@@ -6,7 +6,7 @@
 //     compare nutzt der Author selten bewusst); Author kann den
 //     Filter dann einfach nicht setzen.
 //   - boolean: eq, ne (in/lt/gt sinnlos für 2-Werte-Type).
-//   - number/money/decimal/date/timestamp/locatedTimestamp: alle 5
+//   - number/money/decimal/date/timestamp/locatedTimestamp: alle 7
 //     Ops — die Felder sind natürlich vergleichbar.
 //
 // Boot-Validator nutzt diese Map um Author-Fehler früh zu fangen
@@ -17,7 +17,15 @@
 import type { FieldDefinition, ScreenFilterOp } from "./types";
 
 const EQUALITY_ONLY = ["eq", "ne", "in"] as const satisfies readonly ScreenFilterOp[];
-const COMPARABLE = ["eq", "ne", "lt", "gt", "in"] as const satisfies readonly ScreenFilterOp[];
+const COMPARABLE = [
+  "eq",
+  "ne",
+  "lt",
+  "gt",
+  "lte",
+  "gte",
+  "in",
+] as const satisfies readonly ScreenFilterOp[];
 const BOOL_OPS = ["eq", "ne"] as const satisfies readonly ScreenFilterOp[];
 
 export function getAllowedFilterOps(field: FieldDefinition): readonly ScreenFilterOp[] {