@cosmicdrift/kumiko-framework 0.269.2 → 0.273.0

package/src/__tests__/transition-guard.integration.test.ts

@@ -86,7 +86,7 @@ const feature = defineFeature("txguard", (r) => {
         event.user,
         ctx.db,
       ),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.writeHandler(
@@ -102,7 +102,7 @@ const feature = defineFeature("txguard", (r) => {
         event.user,
         ctx.db,
       ),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.writeHandler(
@@ -114,7 +114,7 @@ const feature = defineFeature("txguard", (r) => {
         event.user,
         ctx.db,
       ),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.writeHandler(
@@ -130,7 +130,7 @@ const feature = defineFeature("txguard", (r) => {
         event.user,
         ctx.db,
       ),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.writeHandler(
@@ -142,7 +142,7 @@ const feature = defineFeature("txguard", (r) => {
         event.user,
         ctx.db,
       ),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.writeHandler(
@@ -154,7 +154,7 @@ const feature = defineFeature("txguard", (r) => {
         event.user,
         ctx.db,
       ),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.writeHandler(
@@ -170,7 +170,7 @@ const feature = defineFeature("txguard", (r) => {
         event.user,
         ctx.db,
       ),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 

package/src/api/__tests__/api.test.ts

@@ -37,7 +37,7 @@ const testFeature = defineFeature("test", (r) => {
     "item:list",
     z.object({ search: z.string().optional() }),
     async () => [{ id: 1, name: "Test" }],
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.streamHandler(
@@ -750,7 +750,7 @@ describe("feature-declared HTTP routes (r.httpRoute)", () => {
       }),
     );
     r.queryHandler("item:list", z.object({}), async () => [{ id: 7 }], {
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     });
     r.httpRoute({
       method: "GET",

package/src/api/__tests__/body-limit.test.ts

@@ -18,7 +18,7 @@ const testFeature = defineFeature("blob", (r) => {
     "note:create",
     z.object({ body: z.string() }),
     async (event) => ({ isSuccess: true, data: { body: event.payload.body } }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 

package/src/api/__tests__/nested-write-ownership.integration.test.ts

@@ -0,0 +1,268 @@
+// fw#2861 — nested-write parent-row ownership check. A custom (non-executor)
+// `:create` handler can hand back an EXISTING row instead of inserting a
+// fresh one (find-or-create, or a bug) — the framework must refuse to attach
+// nested children to a parent row the caller does not own, both across
+// tenants (role-only entity, no ownership field) and within a tenant (an
+// ownership-bound field pointing at a different owner). Modelled on
+// nested-write.integration.test.ts's project/task fixture. Real HTTP via
+// setupTestStack + stack.http.write — never createTestDispatcher.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { executeRawQuery } from "../../db/queries/raw-sql";
+import { asRawClient, selectMany } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
+import { createEntity, createTextField, defineFeature, from } from "../../engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "../../stack";
+
+// project2/task2: same-tenant ownership scenario (b/c). ownerId is an
+// ownership-bound field — checkWriteFieldOwnership evaluates it.
+const project2Entity = createEntity({
+  table: "nested_own_projects2",
+  fields: {
+    name: createTextField({ personal: false, reason: "test_fixture", required: true }),
+    ownerId: createTextField({
+      personal: false,
+      reason: "test_fixture",
+      required: true,
+      access: { write: { User: from("user:id", "ownerId") } },
+    }),
+  },
+});
+const project2Table = buildEntityTable("project2", project2Entity);
+
+const task2Entity = createEntity({
+  table: "nested_own_tasks2",
+  fields: {
+    projectId: createTextField({ personal: false, reason: "test_fixture", required: true }),
+    title: createTextField({ personal: false, reason: "test_fixture", required: true }),
+  },
+});
+const task2Table = buildEntityTable("task2", task2Entity);
+
+// project3/task3: cross-tenant scenario (a). Role-only entity, no ownership
+// field — checkWriteFieldOwnership is a no-op here; only the tenant check
+// can catch it.
+const project3Entity = createEntity({
+  table: "nested_own_projects3",
+  fields: {
+    name: createTextField({ personal: false, reason: "test_fixture", required: true }),
+  },
+});
+const project3Table = buildEntityTable("project3", project3Entity);
+
+const task3Entity = createEntity({
+  table: "nested_own_tasks3",
+  fields: {
+    projectId: createTextField({ personal: false, reason: "test_fixture", required: true }),
+    title: createTextField({ personal: false, reason: "test_fixture", required: true }),
+  },
+});
+const task3Table = buildEntityTable("task3", task3Entity);
+
+const nestedOwnershipFeature = defineFeature("nested-own", (r) => {
+  r.entity("project2", project2Entity);
+  r.entity("task2", task2Entity);
+  r.relation("project2", "tasks", {
+    type: "hasMany",
+    target: "task2",
+    foreignKey: "projectId",
+    nestedWrite: true,
+  });
+
+  r.entity("project3", project3Entity);
+  r.entity("task3", task3Entity);
+  r.relation("project3", "tasks", {
+    type: "hasMany",
+    target: "task3",
+    foreignKey: "projectId",
+    nestedWrite: true,
+  });
+
+  // Custom (non-executor-entry) find-or-create: same-tenant only (tenant-
+  // scoped fetchOne), simulating a handler that doesn't strictly insert a
+  // fresh row every time — only the "found" branch skips the executor.
+  // No escapeHatch needed — the lookup stays within the caller's own tenant.
+  r.writeHandler(
+    "project2:create",
+    z.object({ name: z.string().min(1), ownerId: z.string().uuid().optional() }),
+    async (event, ctx) => {
+      const existing = await ctx.db.fetchOne(project2Table, { name: event.payload.name });
+      if (existing) return { isSuccess: true as const, data: existing };
+      const crud = createEventStoreExecutor(project2Table, project2Entity, {
+        entityName: "project2",
+      });
+      return crud.create(
+        { name: event.payload.name, ownerId: event.payload.ownerId ?? event.user.id },
+        event.user,
+        ctx.db,
+      );
+    },
+    { access: { roles: ["Admin", "User"] } },
+  );
+
+  r.writeHandler(
+    "task2:create",
+    z.object({ projectId: z.string().uuid(), title: z.string().min(1) }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(task2Table, task2Entity, { entityName: "task2" });
+      return crud.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin", "User"] } },
+  );
+
+  // Custom find-or-create for the cross-tenant scenario: an unfiltered raw
+  // lookup by name (declared escapeHatch) simulates a handler bug that finds
+  // a same-named row belonging to a DIFFERENT tenant and hands it back
+  // instead of inserting a fresh, tenant-scoped row.
+  r.writeHandler(
+    "project3:create",
+    z.object({ name: z.string().min(1) }),
+    async (event, ctx) => {
+      const runner = ctx.db.unsafeRaw(
+        "fw#2861 test fixture — simulate cross-tenant find-or-create bug",
+      );
+      const rows = await executeRawQuery<{
+        id: string;
+        name: string;
+        tenant_id: string;
+      }>(
+        runner,
+        `SELECT id, name, tenant_id FROM "${project3Table.tableName}" WHERE name = $1 LIMIT 1`,
+        [event.payload.name],
+      );
+      const existing = rows[0];
+      if (existing) {
+        return {
+          isSuccess: true as const,
+          data: { id: existing.id, name: existing.name, tenantId: existing.tenant_id },
+        };
+      }
+      const crud = createEventStoreExecutor(project3Table, project3Entity, {
+        entityName: "project3",
+      });
+      return crud.create({ name: event.payload.name }, event.user, ctx.db);
+    },
+    {
+      access: { roles: ["Admin", "User"] },
+      escapeHatch: { reason: "fw#2861 test fixture — simulate cross-tenant find-or-create bug" },
+    },
+  );
+
+  r.writeHandler(
+    "task3:create",
+    z.object({ projectId: z.string().uuid(), title: z.string().min(1) }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(task3Table, task3Entity, { entityName: "task3" });
+      return crud.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin", "User"] } },
+  );
+});
+
+let stack: TestStack;
+const TENANT_A = testTenantId(9101);
+const TENANT_B = testTenantId(9102);
+const ownerUser = createTestUser({ id: 9111, tenantId: TENANT_A, roles: ["User"] });
+const attackerUser = createTestUser({ id: 9112, tenantId: TENANT_A, roles: ["User"] });
+const tenantAOtherUser = createTestUser({ id: 9114, tenantId: TENANT_A, roles: ["User"] });
+const tenantBUser = createTestUser({ id: 9113, tenantId: TENANT_B, roles: ["User"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [nestedOwnershipFeature] });
+  await unsafeCreateEntityTable(stack.db, project2Entity, "project2");
+  await unsafeCreateEntityTable(stack.db, task2Entity, "task2");
+  await unsafeCreateEntityTable(stack.db, project3Entity, "project3");
+  await unsafeCreateEntityTable(stack.db, task3Entity, "task3");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${task2Table.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${task3Table.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${project2Table.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${project3Table.tableName}"`);
+});
+
+describe("nested-write parent-row ownership check (fw#2861)", () => {
+  test("(a) cross-tenant: existing role-only parent row in tenant B, tenant-A caller -> access_denied, zero task rows", async () => {
+    // Seed the foreign row in tenant B.
+    const seedRes = await stack.http.write(
+      "nested-own:write:project3:create",
+      { name: "cross-tenant" },
+      tenantBUser,
+    );
+    expect(seedRes.status).toBe(200);
+
+    const res = await stack.http.write(
+      "nested-own:write:project3:create",
+      { name: "cross-tenant", tasks: [{ title: "t1" }] },
+      tenantAOtherUser,
+    );
+
+    expect(res.status).toBeGreaterThanOrEqual(400);
+    expect(res.status).toBeLessThan(500);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.error.code).toBe("access_denied");
+
+    const dbTasks = await selectMany(stack.db, task3Table);
+    expect(dbTasks).toHaveLength(0);
+  });
+
+  test("(b) same tenant, ownership-bound field, row owned by a different user -> access_denied, zero task rows", async () => {
+    const seedRes = await stack.http.write(
+      "nested-own:write:project2:create",
+      { name: "owned-by-other" },
+      ownerUser,
+    );
+    expect(seedRes.status).toBe(200);
+
+    const res = await stack.http.write(
+      "nested-own:write:project2:create",
+      { name: "owned-by-other", tasks: [{ title: "t1" }] },
+      attackerUser,
+    );
+
+    expect(res.status).toBeGreaterThanOrEqual(400);
+    expect(res.status).toBeLessThan(500);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.error.code).toBe("access_denied");
+
+    const dbTasks = await selectMany(stack.db, task2Table);
+    expect(dbTasks).toHaveLength(0);
+  });
+
+  test("(c) caller owns the existing same-tenant row -> children attach (regression)", async () => {
+    const seedRes = await stack.http.write(
+      "nested-own:write:project2:create",
+      { name: "owned-by-self" },
+      ownerUser,
+    );
+    expect(seedRes.status).toBe(200);
+
+    const res = await stack.http.write(
+      "nested-own:write:project2:create",
+      { name: "owned-by-self", tasks: [{ title: "t1" }] },
+      ownerUser,
+    );
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(true);
+
+    const dbTasks = await selectMany(stack.db, task2Table);
+    expect(dbTasks).toHaveLength(1);
+  });
+});

package/src/api/__tests__/pii-leak-guard.integration.test.ts

@@ -18,7 +18,7 @@ const leakyFeature = defineFeature("leaky", (r) => {
     defineQueryHandler({
       name: "raw",
       schema: z.object({}),
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       handler: async () => ({ email: CIPHERTEXT, note: "plain" }),
     }),
   );
@@ -26,7 +26,7 @@ const leakyFeature = defineFeature("leaky", (r) => {
     defineQueryHandler({
       name: "clean",
       schema: z.object({}),
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       handler: async () => ({ email: "marc@example.com" }),
     }),
   );

package/src/api/__tests__/request-locale.integration.test.ts

@@ -18,7 +18,7 @@ const localeProbe = defineFeature("locale-probe", (r) => {
     "read-locale",
     z.object({}),
     async (_event, ctx) => ({ isSuccess: true, data: { locale: ctx.locale } }),
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 

package/src/api/__tests__/server-error-logging.test.ts

@@ -20,7 +20,7 @@ const boomFeature = defineFeature("boom", (r) => {
     async () => {
       throw new Error("disk on fire");
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 });
 

package/src/api/server.ts

@@ -1,17 +1,10 @@
 import { Hono } from "hono";
 import type { DbConnection, PgClient } from "../db/connection";
-import { createTenantDb } from "../db/tenant-db";
 import { createDerivativesContext } from "../derivatives/derivatives-context";
 import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names";
 import { runsInLane } from "../engine/run-in";
 import { createAnonymousUser } from "../engine/system-user";
-import {
-  type AppContext,
-  isFileField,
-  type Registry,
-  type RunIn,
-  SYSTEM_TENANT_ID,
-} from "../engine/types";
+import { type AppContext, isFileField, type Registry, type RunIn } from "../engine/types";
 import { createFileContext } from "../files/file-handle";
 import type { FileRoutesOptions } from "../files/file-routes";
 import { createFileRoutes } from "../files/file-routes";
@@ -491,9 +484,9 @@ export function buildServer(options: ServerOptions): KumikoServer {
 
   // MultiStreamProjections: one EventConsumer per MSP. Handler routes by
   // event.type into the MSP's apply map. MSPs aggregate cross-aggregate but
-  // still within one tenant by default — the applier receives the
-  // tenant-scoped DbRunner; SYSTEM_TENANT_ID events pass through the raw
-  // baseDb so system-level sinks can read across tenants.
+  // still within one tenant by default — the applier receives the plain
+  // baseDb DbRunner; tenant consistency comes from the triggering event's
+  // own tenantId, not a per-event TenantDb scope.
   //
   // Lane-filter (Welle 2.6.b): MSPs declare `runIn` to pin them to a
   // deploy-lane. An MSP with `runIn: "api"` won't be wired into the
@@ -535,12 +528,6 @@ export function buildServer(options: ServerOptions): KumikoServer {
         // production. Defensive return for the type-narrowing path.
         return;
       }
-      const scopedDb =
-        event.tenantId === SYSTEM_TENANT_ID ? baseDb : createTenantDb(baseDb, event.tenantId);
-      // Hand the raw DbRunner to apply(): MSPs write to their projection
-      // table directly, they don't go through the TenantDb wrapper.
-      const rawRunner =
-        event.tenantId === SYSTEM_TENANT_ID ? baseDb : (scopedDb as { raw: typeof baseDb }).raw; // @cast-boundary engine-bridge
       // Saga/process-manager ctx: apply can call ctx.appendEvent to cascade
       // a follow-up event onto another aggregate. Uses the triggering event's
       // tenantId + userId so the causal chain stays tenant-consistent.
@@ -553,7 +540,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
         : undefined;
       const applyCtx = createMultiStreamApplyContext({
         registry: options.registry,
-        db: rawRunner,
+        db: baseDb,
         tenantId: event.tenantId,
         userId: event.metadata.userId,
         ...(mspOwner && { callerFeature: mspOwner }),
@@ -562,12 +549,12 @@ export function buildServer(options: ServerOptions): KumikoServer {
           derivatives: createDerivativesContext({
             files: mspFiles,
             registry: options.registry,
-            db: rawRunner,
+            db: baseDb,
             tenantId: event.tenantId,
           }),
         }),
       });
-      await applyFn(event, rawRunner, applyCtx);
+      await applyFn(event, baseDb, applyCtx);
       // Keep ctx reachable to satisfy the EventConsumerHandler signature.
       void ctx;
     },

package/src/bun-db/__tests__/query-guards.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, test } from "bun:test";
+import type { DbRunner } from "../../db/connection";
 import type { EntityTableMeta } from "../../db/entity-table-meta";
-import { incrementCounter, selectMany } from "../query";
+import { createTenantDb } from "../../db/tenant-db";
+import { testTenantId } from "../../stack";
+import { asRawClient, countWhere, incrementCounter, selectMany, transaction } from "../query";
 
 const meta: EntityTableMeta = {
   source: "unmanaged",
@@ -35,9 +38,8 @@ describe("bun-db guards — limit injection", () => {
 });
 
 describe("bun-db guards — silent tenant-scope bypass", () => {
-  // A TenantDb-shaped handle: has .raw.unsafe + the scoped methods + tenantId.
+  // A TenantDb-shaped handle: the scoped methods + tenantId, no `.unsafe` of its own.
   const tenantDb = {
-    raw: { unsafe: async () => [] as unknown[] },
     tenantId: "00000000-0000-4000-8000-000000000001",
     selectMany: async () => [],
     fetchOne: async () => undefined,
@@ -52,3 +54,58 @@ describe("bun-db guards — silent tenant-scope bypass", () => {
     ).rejects.toThrow("does not apply the tenant filter");
   });
 });
+
+describe("bun-db guards — a real TenantDb has no unfiltered escape via asRawClient", () => {
+  const tenantId = testTenantId(1);
+
+  // A runner whose unsafe()/begin() blow up — proves each guard throws
+  // BEFORE reaching the driver, same contract as `explodingDb` above.
+  function explodingRunner(): DbRunner {
+    return {
+      unsafe: async () => {
+        throw new Error("unsafe must not be reached — asRawClient should fail closed first");
+      },
+      begin: async () => {
+        throw new Error("begin must not be reached — asRawClient should fail closed first");
+      },
+    } as unknown as DbRunner;
+  }
+
+  test("asRawClient throws and points callers at ctx.db.unsafeRaw", () => {
+    const tdb = createTenantDb(explodingRunner(), tenantId);
+    expect(() => asRawClient(tdb)).toThrow("unsafeRaw");
+  });
+
+  test("countWhere throws before issuing any SQL", async () => {
+    const tdb = createTenantDb(explodingRunner(), tenantId);
+    await expect(countWhere(tdb, meta, {})).rejects.toThrow("unsafeRaw");
+  });
+
+  test("transaction throws before issuing any SQL", async () => {
+    const tdb = createTenantDb(explodingRunner(), tenantId);
+    await expect(transaction(tdb, async () => "unreached")).rejects.toThrow("unsafeRaw");
+  });
+});
+
+describe("bun-db guards — selectMany still delegates a real TenantDb, tenant-filtered", () => {
+  test("selectMany(tenantDb, ...) issues tenant-filtered SQL via the bound runner", async () => {
+    const tenantId = testTenantId(2);
+    const captured: { sql: string; values: readonly unknown[] }[] = [];
+    const recordingRunner: DbRunner = {
+      unsafe: async (sql: string, values: readonly unknown[]) => {
+        captured.push({ sql, values });
+        return [] as unknown[];
+      },
+      begin: async () => {
+        throw new Error("begin not used in this test");
+      },
+    } as unknown as DbRunner;
+    const tdb = createTenantDb(recordingRunner, tenantId);
+
+    await selectMany(tdb, meta, {});
+
+    expect(captured).toHaveLength(1);
+    expect(captured[0]?.sql).toMatch(/tenant_id/i);
+    expect(captured[0]?.values).toContain(tenantId);
+  });
+});

package/src/bun-db/query.ts

@@ -100,11 +100,14 @@ export function asRawClient(db: unknown): RawClient {
   if (typeof dbAny["unsafe"] === "function") {
     return dbAny as unknown as RawClient;
   }
-  // TenantDb-shape: framework wrapper exposing the underlying runner as `.raw`.
-  // Callers that pass `ctx.db` instead of `ctx.db.raw` land here — unwrap once.
-  const raw = dbAny["raw"];
-  if (raw && typeof (raw as Record<string, unknown>)["unsafe"] === "function") {
-    return raw as unknown as RawClient;
+  // TenantDb (ctx.db) has no unfiltered escape via asRawClient anymore — fail
+  // closed instead of silently unwrapping a tenant-scoped handle.
+  if (isTenantDbShape(db)) {
+    throw new Error(
+      "asRawClient: received a tenant-scoped TenantDb (ctx.db). Raw SQL helpers do not apply the " +
+        "tenant filter — use a ctx.db.<method>, or ctx.db.unsafeRaw(reason) with escapeHatch: " +
+        "{ reason } on the handler/hook (r.systemScope() features: ctx.systemDb.unsafeRaw(reason)).",
+    );
   }
   // Drizzle DbConnection (legacy compat): $client = postgres-js Sql.
   const $client = dbAny["$client"];
@@ -118,7 +121,7 @@ export function asRawClient(db: unknown): RawClient {
     return sessionClient as unknown as RawClient;
   }
   throw new Error(
-    "bun-db: db argument has no .unsafe() — pass Bun.SQL, postgres-js Sql, TenantDb, or a transaction handle.",
+    "bun-db: db argument has no .unsafe() — pass Bun.SQL, postgres-js Sql, or a transaction handle.",
   );
 }
 
@@ -199,35 +202,35 @@ type TenantDbDelegate = {
   deleteMany(table: TableLike, where: WhereObject): Promise<void>;
 };
 
-function tenantDbDelegate(db: unknown): TenantDbDelegate | undefined {
-  if (typeof db !== "object" || db === null) return undefined;
+// Duck-types TenantDb: five scoped methods + tenantId, no `.unsafe` of its own.
+// A throwing systemScope guard Proxy fails closed here too — intended, not a bug.
+function isTenantDbShape(db: unknown): boolean {
+  if (typeof db !== "object" || db === null) return false;
   const d = db as Record<string, unknown>;
-  const raw = d["raw"];
-  if (
-    raw &&
-    typeof (raw as Record<string, unknown>)["unsafe"] === "function" &&
+  if (typeof d["unsafe"] === "function") return false;
+  return (
     typeof d["selectMany"] === "function" &&
     typeof d["fetchOne"] === "function" &&
     typeof d["insertOne"] === "function" &&
     typeof d["updateMany"] === "function" &&
     typeof d["deleteMany"] === "function" &&
     "tenantId" in d
-  ) {
-    return db as TenantDbDelegate;
-  }
-  return undefined;
+  );
+}
+
+function tenantDbDelegate(db: unknown): TenantDbDelegate | undefined {
+  return isTenantDbShape(db) ? (db as TenantDbDelegate) : undefined;
 }
 
-// Guard for helpers that do NOT delegate to TenantDb (upsert/increment/insertMany):
-// passing a TenantDb here would silently run unscoped against `.raw`, bypassing
-// the tenant filter. Fail loudly so the caller picks `ctx.db.<method>` (scoped)
-// or `ctx.db.raw` (explicit cross-tenant) on purpose.
+// Fails loudly for helpers that don't delegate to TenantDb (upsert/increment/insertMany) —
+// passing one here would otherwise reach asRawClient and throw with a less specific message.
 // @wrapper-known semantic-alias
 function assertNotTenantScoped(db: unknown, fnName: string): void {
   if (tenantDbDelegate(db) !== undefined) {
     throw new Error(
       `${fnName}: received a tenant-scoped db but this helper does not apply the tenant filter. ` +
-        `Pass ctx.db.raw for an explicit cross-tenant op, or use a scoped TenantDb method.`,
+        "Pass ctx.db.unsafeRaw(reason) (with escapeHatch: { reason } on the handler/hook) for an " +
+        "explicit cross-tenant op, or use a scoped TenantDb method.",
     );
   }
 }