@cosmicdrift/kumiko-framework 0.270.0 → 0.274.0

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/__tests__/event-store-executor-write-verbs.integration.test.ts

@@ -385,6 +385,83 @@ describe("event-store-executor write-verbs — version_conflict edge cases", ()
   });
 });
 
+// =============================================================================
+// Explicit-id create: cross-tenant isolation, no resurrection of a deleted row
+// =============================================================================
+
+const deletedIdEntity = createEntity({
+  table: "read_es_write_deleted_id",
+  fields: {
+    email: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+  },
+  softDelete: true,
+});
+const deletedIdTable = buildEntityTable("esWriteDeletedId", deletedIdEntity);
+
+describe("event-store-executor write-verbs — explicit-id tenant isolation + soft-delete", () => {
+  const crud = createEventStoreExecutor(deletedIdTable, deletedIdEntity, {
+    entityName: "esWriteDeletedId",
+  });
+  let otherTenantDb: TenantDb;
+
+  beforeAll(async () => {
+    await unsafeCreateEntityTable(testDb.db, deletedIdEntity, "esWriteDeletedId");
+    otherTenantDb = createTenantDb(testDb.db, TestUsers.otherTenant.tenantId);
+  });
+
+  beforeEach(async () => {
+    await asRawClient(testDb.db).unsafe(
+      `TRUNCATE kumiko_events, read_es_write_deleted_id RESTART IDENTITY CASCADE`,
+    );
+  });
+
+  test("create with an id already used by another tenant → conflict, tenant A's row untouched, no leak", async () => {
+    // The event log itself is tenant-scoped (UNIQUE (tenant_id, aggregate_id,
+    // version)) and would happily let tenant B open its own stream at the
+    // same id — but every entity's projection table has a plain `id` primary
+    // key (table-builder.ts), shared across all tenants for that entity
+    // type. So a same-id create for a different tenant fails at the
+    // projection-insert step with `unique_violation`, not `version_conflict`
+    // — a different, still-typed error, and the mapped error's details carry
+    // only entityName/constraintName, nothing that identifies tenant A's row.
+    const first = await crud.create({ email: "tenant-a@test.de" }, admin, tdb);
+    if (!first.isSuccess) throw new Error("setup failed");
+
+    const other = await crud.create(
+      { id: first.data.id, email: "tenant-b@test.de" },
+      TestUsers.otherTenant,
+      otherTenantDb,
+    );
+    expect(other.isSuccess).toBe(false);
+    if (other.isSuccess) return;
+    expect(other.error.code).toBe("unique_violation");
+    expect(JSON.stringify(other.error.details)).not.toContain(admin.tenantId);
+
+    const row = await asRawClient(testDb.db).unsafe(
+      `SELECT email FROM read_es_write_deleted_id WHERE id = $1`,
+      [first.data.id],
+    );
+    expect((row as unknown as { email: string }[])[0]?.email).toBe("tenant-a@test.de");
+  });
+
+  test("create with the id of a soft-deleted row → version_conflict, no resurrection", async () => {
+    const created = await crud.create({ email: "gone@test.de" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+
+    const deleted = await crud.delete({ id: created.data.id }, admin, tdb);
+    expect(deleted.isSuccess).toBe(true);
+
+    const resurrect = await crud.create(
+      { id: created.data.id, email: "back-from-the-dead@test.de" },
+      admin,
+      tdb,
+    );
+    expect(resurrect.isSuccess).toBe(false);
+    if (resurrect.isSuccess) return;
+    expect(resurrect.error.code).toBe("version_conflict");
+  });
+});
+
 // =============================================================================
 // Concurrent update race → EventStoreVersionConflict catch + entityCache.del
 // on forget/restore (create/update/delete already exercise cache in the

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

@@ -807,7 +807,7 @@ describe("event-store-executor — pii subject encryption", () => {
       0,
     );
     if (!storedEvent) throw new Error("no persisted event for the aggregate");
-    const applied = await applyEntityEvent(storedEvent, piiTable, piiEntity, tdb.raw);
+    const applied = await applyEntityEvent(storedEvent, piiTable, piiEntity, testDb.db);
     expect(applied.kind).toBe("applied");
 
     const rawRows = (await asRawClient(testDb.db).unsafe(

package/src/db/__tests__/replay-migration-sql.test.ts

@@ -365,6 +365,23 @@ ALTER TABLE "widgets" OWNER TO app_user;`,
     }
   });
 
+  test("FORCE / NO FORCE ROW LEVEL SECURITY is shape-neutral (fw#2907)", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE IF NOT EXISTS "widgets" ("id" uuid PRIMARY KEY, "title" text);
+ALTER TABLE "widgets" FORCE ROW LEVEL SECURITY;
+ALTER TABLE widgets NO FORCE ROW LEVEL SECURITY;`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("widgets")?.columns ?? [])].sort()).toEqual(["id", "title"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
   test("unexpected table: migrations create a table the snapshot doesn't know about", () => {
     const dir = tmpMigrationsDir();
     try {

package/src/db/__tests__/tenant-db-convention-cross-tenant.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+import type { EscapeHatchKind } from "@cosmicdrift/kumiko-types/handlers";
+import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { InternalError } from "../../errors";
+import { testTenantId } from "../../stack";
+import type { DbRunner } from "../connection";
+import * as dbIndex from "../index";
+import { acknowledgeConventionCrossTenant, createTenantDb, withUnsafeRawGrant } from "../tenant-db";
+import { tenantDbRunner } from "../tenant-db-runner";
+
+const tenantId = testTenantId(1);
+const REASON = "operator scan across every tenant";
+
+function fakeRunner(): DbRunner {
+  return {
+    unsafe: async () => [],
+    begin: async () => {
+      throw new Error("begin not used in these tests");
+    },
+  } as unknown as DbRunner;
+}
+
+describe("acknowledgeConventionCrossTenant", () => {
+  test("returns a system-mode TenantDb with the same tenantId", () => {
+    const tdb = createTenantDb(fakeRunner(), tenantId);
+    const result = acknowledgeConventionCrossTenant(tdb, REASON);
+    expect(result.mode).toBe("system");
+    expect(result.tenantId).toBe(tenantId);
+  });
+
+  test("reports acknowledge-cross-tenant exactly once via grants.report", () => {
+    const reports: Array<{ kind: EscapeHatchKind; reason: string }> = [];
+    const tdb = createTenantDb(fakeRunner(), tenantId, "tenant", undefined, undefined, undefined, {
+      report: (kind, reason) => {
+        reports.push({ kind, reason });
+      },
+    });
+    acknowledgeConventionCrossTenant(tdb, REASON);
+    expect(reports).toEqual([{ kind: "acknowledge-cross-tenant", reason: REASON }]);
+  });
+
+  test("throws for an empty reason", () => {
+    const tdb = createTenantDb(fakeRunner(), tenantId);
+    expect(() => acknowledgeConventionCrossTenant(tdb, "")).toThrow();
+    expect(() => acknowledgeConventionCrossTenant(tdb, "   ")).toThrow();
+  });
+
+  test("throws InternalError for a TenantDb not built by createTenantDb", () => {
+    const handBuilt = { tenantId, mode: "tenant" } as unknown as TenantDb;
+    expect(() => acknowledgeConventionCrossTenant(handBuilt, REASON)).toThrow(InternalError);
+  });
+
+  test("still resolves after withUnsafeRawGrant rebinds the TenantDb", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId);
+    const regranted = withUnsafeRawGrant(tdb, { reason: "unrelated unsafeRaw grant" });
+    const result = acknowledgeConventionCrossTenant(regranted, REASON);
+    expect(result.mode).toBe("system");
+    expect(tenantDbRunner(result)).toBe(runner);
+  });
+
+  test("tenantDbRunner(result) resolves to the original runner", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId);
+    const result = acknowledgeConventionCrossTenant(tdb, REASON);
+    expect(tenantDbRunner(result)).toBe(runner);
+  });
+
+  test("db/index.ts does not export acknowledgeConventionCrossTenant", () => {
+    expect("acknowledgeConventionCrossTenant" in dbIndex).toBe(false);
+  });
+});

package/src/db/__tests__/tenant-db-declared-unsafe-raw.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, test } from "bun:test";
+import type { EscapeHatchKind } from "@cosmicdrift/kumiko-types/handlers";
+import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { AccessDeniedError, InternalError } from "../../errors";
+import { testTenantId } from "../../stack";
+import type { DbRunner } from "../connection";
+import {
+  createTenantDb,
+  createUncheckedSystemDb,
+  unsafeRawForDeclaredStep,
+  withUnsafeRawGrant,
+} from "../tenant-db";
+
+const tenantId = testTenantId(1);
+const REASON = "declared step forwarding unsafeRaw";
+
+function fakeRunner(): DbRunner {
+  return {
+    unsafe: async () => [],
+    begin: async () => {
+      throw new Error("begin not used in these tests");
+    },
+  } as unknown as DbRunner;
+}
+
+describe("unsafeRawForDeclaredStep", () => {
+  test("throws AccessDeniedError without a grant, without reporting", () => {
+    const reports: Array<{ kind: EscapeHatchKind; reason: string }> = [];
+    const tdb = createTenantDb(fakeRunner(), tenantId, "tenant", undefined, undefined, undefined, {
+      report: (kind, reason) => {
+        reports.push({ kind, reason });
+      },
+    });
+
+    expect(() => unsafeRawForDeclaredStep(tdb, REASON)).toThrow(AccessDeniedError);
+    expect(reports).toEqual([]);
+  });
+
+  test("returns exactly the bound runner and reports unsafe-raw exactly once, with a grant", () => {
+    const runner = fakeRunner();
+    const reports: Array<{ kind: EscapeHatchKind; reason: string }> = [];
+    const tdb = createTenantDb(runner, tenantId, "tenant", undefined, undefined, undefined, {
+      unsafeRaw: { reason: "handler declared unsafeRaw" },
+      report: (kind, reason) => {
+        reports.push({ kind, reason });
+      },
+    });
+
+    expect(unsafeRawForDeclaredStep(tdb, REASON)).toBe(runner);
+    expect(reports).toEqual([{ kind: "unsafe-raw", reason: REASON }]);
+  });
+
+  test("throws for an empty or whitespace-only reason", () => {
+    const tdb = createTenantDb(fakeRunner(), tenantId, "tenant", undefined, undefined, undefined, {
+      unsafeRaw: { reason: "handler declared unsafeRaw" },
+    });
+
+    expect(() => unsafeRawForDeclaredStep(tdb, "")).toThrow(/non-empty reason/);
+    expect(() => unsafeRawForDeclaredStep(tdb, "   ")).toThrow(/non-empty reason/);
+  });
+
+  test("throws InternalError for a TenantDb not built by createTenantDb", () => {
+    const handBuilt = { tenantId, mode: "tenant" } as unknown as TenantDb;
+    expect(() => unsafeRawForDeclaredStep(handBuilt, REASON)).toThrow(InternalError);
+  });
+
+  test("throws InternalError for a throwing guard Proxy, without the proxy's get trap firing", () => {
+    let getTrapFired = false;
+    const guardProxy = new Proxy(
+      {},
+      {
+        get() {
+          getTrapFired = true;
+          throw new Error("systemScope guard: property access denied");
+        },
+      },
+    ) as unknown as TenantDb;
+
+    expect(() => unsafeRawForDeclaredStep(guardProxy, REASON)).toThrow(InternalError);
+    expect(getTrapFired).toBe(false);
+  });
+
+  test("resolves to the bound runner for a createUncheckedSystemDb holder, reporting once", () => {
+    const runner = fakeRunner();
+    const reports: Array<{ kind: EscapeHatchKind; reason: string }> = [];
+    const systemDb = createTenantDb(runner, tenantId, "system");
+    const unchecked = createUncheckedSystemDb(systemDb, undefined, (kind, reason) => {
+      reports.push({ kind, reason });
+    });
+
+    expect(unsafeRawForDeclaredStep(unchecked, REASON)).toBe(runner);
+    expect(reports).toEqual([{ kind: "unsafe-raw", reason: REASON }]);
+  });
+
+  test("still resolves after withUnsafeRawGrant rebinds the TenantDb", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId, "tenant", undefined, undefined, undefined, {
+      unsafeRaw: { reason: "original grant" },
+    });
+    const regranted = withUnsafeRawGrant(tdb, { reason: "rebind grant" });
+
+    expect(unsafeRawForDeclaredStep(regranted, REASON)).toBe(runner);
+  });
+});