@cosmicdrift/kumiko-framework 0.273.0 → 0.275.0

package/package.json

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

package/src/changes.json

@@ -1,4 +1,32 @@
 [
+  {
+    "version": "0.275.0",
+    "type": "breaking",
+    "title": "JobContext.db is a tenant-filtered TenantDb; unfiltered job access needs r.job({ escapeHatch }) or r.systemScope() (fw#2914).",
+    "detail": "Job handlers no longer receive the unfiltered boot `DbConnection` as `ctx.db`. `JobContext.db` is now a `TenantDb` in \"tenant\" mode, bound to the job's resolved tenant (`_tenantId`, `payload.tenantId`, or `SYSTEM_TENANT_ID` for tenant-less cron jobs). Reads see that tenant plus `SYSTEM_TENANT_ID` reference rows, and writes are scoped to it. `JobDefinition` gains `escapeHatch?: { reason }`: it grants `ctx.db.unsafeRaw(reason)` for that job and reports an `\"unsafe-raw\"` escape-hatch audit event through `_escapeHatchAuditSink` (deduplicated like handler grants). Without it, `ctx.db.unsafeRaw` throws `AccessDeniedError`. `r.systemScope()` features keep `ctx.systemDb` unchanged. `r.job` throws at registration for an `escapeHatch` with an empty reason. Framework `soft-delete` cleanup jobs run on the tenant-filtered `TenantDb` without a grant. Bundled cross-tenant jobs now declare `escapeHatch`: auth-mfa reencrypt, sessions cleanup, form-draft cleanup, secrets rotate, files-tenant-data sweep-orphaned-derivatives, data-retention retention-cleanup, inbound-mail-retention, tenant-lifecycle run-tenant-destruction, and user-data-rights run-export-jobs/run-forget-cleanup. The systemScope features config, jobs and workflow-runner use `ctx.systemDb.unsafeRaw`. The exported `rotateJob` (secrets) and `sweepOrphanedDerivativesJob` (files-tenant-data) take the raw `DbConnection` as a third argument.",
+    "migration": "Jobs that only read and write their own tenant through `ctx.db` method calls or `selectMany/fetchOne/insertOne/updateMany/deleteMany(ctx.db, ...)` need no change. A job that treated `ctx.db` as a `DbConnection` (casts, `asRawClient`, `countWhere`, `upsert*`, `incrementCounter`, `createTenantDb(ctx.db, ...)`, `runProjectionsForEvent(..., ctx.db)`, or `\"raw\" in db ? db.raw : db`) must declare the grant and fetch the runner explicitly. Use `r.job({ name, trigger, escapeHatch: { reason: \"<why>\" }, handler: async (payload, ctx) => work(ctx.db.unsafeRaw(\"<why>\")) })`; keep the `unsafeRaw` call inside the inline `handler` next to `escapeHatch` so `guard-escape-hatch-declared` recognizes the declaration. `r.systemScope()` features use `ctx.systemDb.unsafeRaw(reason)` instead. WARNING: a job that is not migrated but passes a foreign `where.tenantId` through `ctx.db` does not fail; the filter silently narrows it to the job's own tenant (`SYSTEM_TENANT_ID` for tenant-less cron jobs), so cross-tenant sweeps silently read nothing. Audit every cross-tenant job. Hand-built `JobContext` objects in tests need `db: createTenantDb(conn, tenantId)` (plus `systemDb` for systemScope jobs). Direct callers of `rotateJob`/`sweepOrphanedDerivativesJob` pass the raw connection as the third argument."
+  },
+  {
+    "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 +55,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 };