@cosmicdrift/kumiko-framework 0.270.0 → 0.273.0

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);
+  });
+});

package/src/db/__tests__/tenant-db-global.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
+import type { EscapeHatchReporter, EscapeHatchTarget } from "@cosmicdrift/kumiko-types/handlers";
 import type { TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 import { createEntity, createTextField } from "../../engine";
 import { AccessDeniedError } from "../../errors";
@@ -69,6 +70,19 @@ const explicitGlobalLiteralTable = buildEntityTable("globalGuardExplicitGlobal",
 
 const own = testTenantId(1);
 
+function recordingReporter(): {
+  readonly report: EscapeHatchReporter;
+  readonly calls: Array<{ kind: string; reason: string; target: EscapeHatchTarget | undefined }>;
+} {
+  const calls: Array<{ kind: string; reason: string; target: EscapeHatchTarget | undefined }> = [];
+  return {
+    report: (kind, reason, target) => {
+      calls.push({ kind, reason, target });
+    },
+    calls,
+  };
+}
+
 // Type-only assertions — never invoked, checked by `tsc --build` only.
 function typeAssertions(tdb: TenantDb): void {
   // @ts-expect-error db.global() on a "tenant"-tenancy table (default tenancy) is a type error.
@@ -157,6 +171,41 @@ describe("TenantDb.global()", () => {
     expect(captured).toHaveLength(1);
   });
 
+  test("write with an escapeHatch reports global-write once with the grant's reason", async () => {
+    const db: DbRunner = {
+      unsafe: async () => [{ id: "x" }],
+      begin: async () => {
+        throw new Error("begin not used in this test");
+      },
+    } as DbRunner;
+    const { report, calls } = recordingReporter();
+    const tdb = createTenantDb(db, own, "tenant", undefined, undefined, undefined, {
+      globalWrites: { reason: "cross-tenant backfill job" },
+      report,
+    });
+    await tdb.global(globalUnmanagedTable).insertOne({ name: "x" });
+    expect(calls).toEqual([
+      { kind: "global-write", reason: "cross-tenant backfill job", target: undefined },
+    ]);
+  });
+
+  test("denied global write (no grant) reports nothing", async () => {
+    const { report, calls } = recordingReporter();
+    const tdb = createTenantDb(
+      unreachableRunner(),
+      own,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      {
+        report,
+      },
+    );
+    await expect(tdb.global(globalUnmanagedTable).insertOne({ name: "x" })).rejects.toThrow();
+    expect(calls).toEqual([]);
+  });
+
   test("write with an explicit non-SYSTEM tenantId rejects even with a valid escapeHatch", async () => {
     const tdb = createTenantDb(
       unreachableRunner(),
@@ -214,6 +263,41 @@ describe("TenantDb.unsafeRaw()", () => {
     });
     expect(tdb.unsafeRaw("some reason")).toBe(rawDb);
   });
+
+  test("with a valid grant reports unsafe-raw once with the reason", () => {
+    const { report, calls } = recordingReporter();
+    const tdb = createTenantDb(
+      unreachableRunner(),
+      own,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      {
+        unsafeRaw: { reason: "granted" },
+        report,
+      },
+    );
+    tdb.unsafeRaw("cleanup read");
+    expect(calls).toEqual([{ kind: "unsafe-raw", reason: "cleanup read", target: undefined }]);
+  });
+
+  test("without a grant reports nothing", () => {
+    const { report, calls } = recordingReporter();
+    const tdb = createTenantDb(
+      unreachableRunner(),
+      own,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      {
+        report,
+      },
+    );
+    expect(() => tdb.unsafeRaw("some reason")).toThrow(AccessDeniedError);
+    expect(calls).toEqual([]);
+  });
 });
 
 describe("withUnsafeRawGrant", () => {
@@ -257,4 +341,12 @@ describe("UncheckedSystemDb.unsafeRaw", () => {
     const sysDb = createUncheckedSystemDb(tdb);
     expect(sysDb.unsafeRaw("cleanup job")).toBe(rawDb);
   });
+
+  test("reports unsafe-raw once with the reason", () => {
+    const tdb = createTenantDb(unreachableRunner(), own);
+    const { report, calls } = recordingReporter();
+    const sysDb = createUncheckedSystemDb(tdb, undefined, report);
+    sysDb.unsafeRaw("cleanup job");
+    expect(calls).toEqual([{ kind: "unsafe-raw", reason: "cleanup job", target: undefined }]);
+  });
 });

package/src/db/__tests__/tenant-db-no-raw.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from "bun:test";
+import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { InternalError } from "../../errors";
+import { testTenantId } from "../../stack";
+import type { DbRunner } from "../connection";
+import { createTenantDb, createUncheckedSystemDb, withUnsafeRawGrant } from "../tenant-db";
+import { tenantDbRunner } from "../tenant-db-runner";
+
+// TenantDb.raw is gone from the type; framework-internal callers resolve
+// the bound DbRunner through tenant-db-runner.ts's WeakMap instead.
+
+const tenantId = testTenantId(1);
+
+function fakeRunner(): DbRunner {
+  return {
+    unsafe: async () => [],
+    begin: async () => {
+      throw new Error("begin not used in these tests");
+    },
+  } as unknown as DbRunner;
+}
+
+describe("TenantDb has no .raw", () => {
+  test("compile-time: .raw is not a property of TenantDb", () => {
+    const tdb = createTenantDb(fakeRunner(), tenantId);
+    // @ts-expect-error TenantDb no longer exposes `raw`.
+    expect(tdb.raw).toBeUndefined();
+  });
+});
+
+describe("tenantDbRunner", () => {
+  test("returns the runner bound at createTenantDb() (identity)", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId);
+    expect(tenantDbRunner(tdb)).toBe(runner);
+  });
+
+  test("withUnsafeRawGrant rebinds also resolve to the original runner", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId);
+    const regranted = withUnsafeRawGrant(tdb, { reason: "test grant" });
+    expect(regranted).not.toBe(tdb);
+    expect(tenantDbRunner(regranted)).toBe(runner);
+  });
+
+  test("throws InternalError for a hand-built object not built by createTenantDb", () => {
+    const handBuilt = { tenantId, mode: "tenant" } as unknown as TenantDb;
+    expect(() => tenantDbRunner(handBuilt)).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(() => tenantDbRunner(guardProxy)).toThrow(InternalError);
+    expect(getTrapFired).toBe(false);
+  });
+});
+
+describe("createUncheckedSystemDb(...).unsafeRaw", () => {
+  test("resolves to the runner bound at createTenantDb()", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId, "system");
+    const systemDb = createUncheckedSystemDb(tdb);
+    expect(systemDb.unsafeRaw("test reason")).toBe(runner);
+  });
+});

package/src/db/__tests__/tenant-db.integration.test.ts

@@ -110,7 +110,9 @@ describe("scoped mode (default)", () => {
 
       await tdb.insertOne(table, { name: "ColSelect" });
 
-      const rows = await asRawClient(tdb).unsafe<Record<string, unknown>>(
+      // This probes a custom column projection, not tenant-scoping, so it goes
+      // straight at the underlying runner tdb was built from.
+      const rows = await asRawClient(testDb.db).unsafe<Record<string, unknown>>(
         `SELECT id, name FROM "tenant_db_items" WHERE name = $1 LIMIT 10`,
         ["ColSelect"],
       );

package/src/db/__tests__/unchecked-system-db.test.ts

@@ -1,9 +1,23 @@
 import { describe, expect, test } from "bun:test";
+import type { EscapeHatchReporter, EscapeHatchTarget } from "@cosmicdrift/kumiko-types/handlers";
 import { SYSTEM_TENANT_ID } from "../../engine";
 import { testTenantId } from "../../stack";
 import type { DbRunner } from "../connection";
 import { createTenantDb, createUncheckedSystemDb, SYSTEM_SCOPE_CHECK_BRAND } from "../tenant-db";
 
+function recordingReporter(): {
+  readonly report: EscapeHatchReporter;
+  readonly calls: Array<{ kind: string; reason: string; target: EscapeHatchTarget | undefined }>;
+} {
+  const calls: Array<{ kind: string; reason: string; target: EscapeHatchTarget | undefined }> = [];
+  return {
+    report: (kind, reason, target) => {
+      calls.push({ kind, reason, target });
+    },
+    calls,
+  };
+}
+
 // createUncheckedSystemDb wraps a "system"-mode TenantDb (r.systemScope())
 // so a handler must explicitly clear a self-check before using it — none of
 // these checks execute a query, so a runner that always throws is enough to
@@ -44,6 +58,16 @@ describe("createUncheckedSystemDb", () => {
 
       expect(() => unchecked.assertTenantMatch(foreign)).toThrow(/tenant self-check failed/);
     });
+
+    test("does not report — it is a tenant-safe check", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const { report, calls } = recordingReporter();
+      const unchecked = createUncheckedSystemDb(systemDb, undefined, report);
+
+      unchecked.assertTenantMatch(own);
+      expect(() => unchecked.assertTenantMatch(foreign)).toThrow();
+      expect(calls).toEqual([]);
+    });
   });
 
   describe("assertRowsTenant", () => {
@@ -88,6 +112,16 @@ describe("createUncheckedSystemDb", () => {
 
       expect(unchecked.assertRowsTenant(rows, "tenantId")).toBe(rows);
     });
+
+    test("does not report — it is a tenant-safe check", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const { report, calls } = recordingReporter();
+      const unchecked = createUncheckedSystemDb(systemDb, undefined, report);
+      const rows = [{ tenantId: own, name: "a" }];
+
+      unchecked.assertRowsTenant(rows, "tenantId");
+      expect(calls).toEqual([]);
+    });
   });
 
   describe("acknowledgeCrossTenant", () => {
@@ -113,6 +147,30 @@ describe("createUncheckedSystemDb", () => {
 
       expect(() => unchecked.acknowledgeCrossTenant("   ")).toThrow(/non-empty reason/);
     });
+
+    test("reports acknowledge-cross-tenant once with the reason", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const { report, calls } = recordingReporter();
+      const unchecked = createUncheckedSystemDb(systemDb, undefined, report);
+
+      unchecked.acknowledgeCrossTenant("user feature is cross-tenant by design");
+      expect(calls).toEqual([
+        {
+          kind: "acknowledge-cross-tenant",
+          reason: "user feature is cross-tenant by design",
+          target: undefined,
+        },
+      ]);
+    });
+
+    test("an empty reason throws and does not report", () => {
+      const systemDb = createTenantDb(unusedRunner(), own, "system");
+      const { report, calls } = recordingReporter();
+      const unchecked = createUncheckedSystemDb(systemDb, undefined, report);
+
+      expect(() => unchecked.acknowledgeCrossTenant("")).toThrow();
+      expect(calls).toEqual([]);
+    });
   });
 
   describe("outsideTransaction", () => {
@@ -178,6 +236,24 @@ describe("createUncheckedSystemDb", () => {
           /no outside-transaction database source is configured/,
         );
       });
+
+      test("reports acknowledge-cross-tenant once with the reason", () => {
+        const systemDb = createTenantDb(unusedRunner(), own, "system");
+        const outsideTxDb = createTenantDb(unusedRunner(), own, "system");
+        const { report, calls } = recordingReporter();
+        const unchecked = createUncheckedSystemDb(systemDb, outsideTxDb, report);
+
+        unchecked.outsideTransaction.acknowledgeCrossTenant(
+          "durability write is cross-tenant by design",
+        );
+        expect(calls).toEqual([
+          {
+            kind: "acknowledge-cross-tenant",
+            reason: "durability write is cross-tenant by design",
+            target: undefined,
+          },
+        ]);
+      });
     });
   });
 });

package/src/db/apply-entity-event.ts

@@ -89,7 +89,7 @@ export async function applyEntityEvent(
   switch (verb) {
     case "created": {
       // tenantId-Resolution explizit, nicht via Spread-Reihenfolge:
-      // Live-Pfad nutzt tx=db.raw (kein TenantDb-Wrapper-Auto-Inject),
+      // Live-Pfad nutzt tx=tenantDbRunner(db) (kein TenantDb-Wrapper-Auto-Inject),
       // beim Replay erst recht keiner. Default = event.tenantId; payload
       // gewinnt NUR wenn gültig string mit length > 0 (seedTenantMembership-
       // Pfad: Operator schreibt im Ziel-Tenant, Event im Operator-Tenant).

package/src/db/assert-exists-in.ts

@@ -5,7 +5,7 @@ import type { DbConnection } from "./connection";
 import type { TenantDb } from "./tenant-db";
 
 function isTenantDb(db: DbConnection | TenantDb): db is TenantDb {
-  return typeof (db as TenantDb).fetchOne === "function" && "raw" in db;
+  return "tenantId" in db && "fetchOne" in db && typeof db.fetchOne === "function";
 }
 
 /**

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

@@ -38,6 +38,7 @@ import type { EventStoreExecutorOptions } from "./event-store-executor";
 import { constraintOf, isUniqueViolation } from "./pg-error";
 import { toSnakeCase } from "./table-builder";
 import type { TenantDb } from "./tenant-db";
+import { tenantDbRunner } from "./tenant-db-runner";
 
 // Shared context-building for the event-store-executor CRUD verbs (create/
 // update/delete/forget/restore/list/detail — see event-store-executor-write.ts
@@ -358,7 +359,7 @@ export function buildExecutorContext(
     id: EntityId,
     tenantId: TenantId,
   ): Promise<void> {
-    if (await isStreamArchived(db.raw, tenantId, String(id))) {
+    if (await isStreamArchived(tenantDbRunner(db), tenantId, String(id))) {
       throw new ArchivedStreamError(tenantId, String(id));
     }
   }
@@ -401,7 +402,9 @@ export function buildExecutorContext(
     whereParts.push(shifted.sqlText);
     for (const p of shifted.params) params.push(p);
     const sqlText = `SELECT * FROM "${tableName}" WHERE ${whereParts.join(" AND ")} LIMIT 1`;
-    return [...(await executeRawQueryRead<Record<string, unknown>>(db.raw, sqlText, params))];
+    return [
+      ...(await executeRawQueryRead<Record<string, unknown>>(tenantDbRunner(db), sqlText, params)),
+    ];
   }
 
   return {

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

@@ -22,6 +22,7 @@ import { buildFilterWhere, type ExecutorContext, type Table } from "./event-stor
 import { buildParentRefClause } from "./parent-ref-clause";
 import { buildEntityTable, physicalColumnName } from "./table-builder";
 import type { TenantDb, TenantDbMode } from "./tenant-db";
+import { tenantDbRunner } from "./tenant-db-runner";
 
 // The two read verbs (list/detail) of the event-store-executor. Split out
 // of event-store-executor.ts (#1005, Welle 2) — behavior-preserving
@@ -332,7 +333,7 @@ async function resolveReferenceMatches(
   const sql =
     `SELECT "id" FROM "${targetTableName}" WHERE ("${labelCol}")::text ILIKE $1${tenantClause} ` +
     `LIMIT ${MAX_REFERENCE_SEARCH_IDS + 1}`;
-  const rows = await executeRawQueryRead<{ id: string }>(db.raw, sql, subParams);
+  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
@@ -423,6 +424,7 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
     // list + detail are unchanged from crud-executor — projections are the
     // read-model and serve these queries directly.
     async list(payload, user, db, runtimeOptions) {
+      const runner = tenantDbRunner(db);
       const { limit, offset } = resolveListPagination(payload);
       const totalCount = payload.totalCount === true;
       const tableName = String((table as unknown as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL]);
@@ -674,7 +676,7 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
           : "*";
       const listSql = `SELECT ${selectList} FROM "${tableName}"${whereClauseSqlText}${orderByClause} LIMIT ${limit}${offsetClause}`;
 
-      const rawRows = await executeRawQueryRead<Record<string, unknown>>(db.raw, listSql, params);
+      const rawRows = await executeRawQueryRead<Record<string, unknown>>(runner, listSql, params);
       const lastSortLabel = rawRows[rawRows.length - 1]?.[SORT_LABEL_ALIAS];
       if (referenceSortExpr !== undefined) {
         // The alias is a sort artifact, not a column of this entity — strip it
@@ -735,7 +737,7 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
         } else {
           const countSql = `SELECT COUNT(*)::int AS count FROM "${tableName}"${whereClauseSqlText}`;
           const countRows = await executeRawQueryRead<{ count: number }>(
-            db.raw,
+            runner,
             countSql,
             whereParams,
           );
@@ -779,7 +781,7 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
         row: Record<string, unknown>,
       ): Promise<Record<string, unknown>> => {
         const streamVersion = await getStreamVersion(
-          db.raw,
+          tenantDbRunner(db),
           String(payload.id),
           streamTenantFor(user),
         );