@cosmicdrift/kumiko-bundled-features 0.265.0 → 0.268.0

package/src/delivery/jobs.ts

@@ -51,16 +51,17 @@ function requireTenantScopedDeps(
 ): { db: DbConnection; registry: Registry } {
   const registry = ctx.registry;
   if (!registry) throw new Error("delivery job: missing registry in job context");
-  // delivery is r.systemScope()'d (feature.ts), so JobContext.systemDb is
-  // guaranteed here. assertTenantMatch(tenantId).raw hands appendAttemptEvent/
-  // buildChannelContext the underlying DbConnection — safe because both
-  // filter by the same tenantId themselves (see JobContext.systemDb doc).
+  // delivery is r.systemScope()'d, so JobContext.systemDb is guaranteed; unsafeRaw
+  // hands the underlying DbConnection to both — safe since they filter by tenantId themselves.
   if (!ctx.systemDb) {
     throw new InternalError({
       message: "delivery job: ctx.systemDb missing on a system-scoped job",
     });
   }
-  const db = ctx.systemDb.assertTenantMatch(tenantId).raw as DbConnection; // @cast-boundary db-operator — TenantDb.raw is DbRunner, jobs never run inside a DbTx
+  ctx.systemDb.assertTenantMatch(tenantId);
+  const db = ctx.systemDb.unsafeRaw(
+    "delivery attempt append and channel context filter by this job's tenantId themselves",
+  ) as DbConnection; // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
   return { db, registry };
 }
 

package/src/feature-toggles/global-feature-state-table.ts

@@ -1,13 +1,16 @@
 import { asEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   boolean,
+  declareGlobalTenancy,
   type EntityTableMeta,
   instant,
   integer,
   table as pgTable,
+  type SchemaTable,
   sql,
   text,
 } from "@cosmicdrift/kumiko-framework/db";
+import type { TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 
 // Global feature-toggle override state. One row per feature that has ever
 // been explicitly flipped by an operator. Missing row = "no override,
@@ -17,17 +20,18 @@ import {
 // name IS the identity here. No tenantId: this is a global override that
 // applies across every tenant (per-tenant toggles are intentionally out of
 // scope, see core-feature-toggles.md).
-export const globalFeatureStateTable = pgTable("store_global_feature_state", {
-  featureName: text("feature_name").primaryKey(),
-  enabled: boolean("enabled").notNull(),
-  // Optimistic-lock column. The set-handler reads the existing row, then
-  // updates with `WHERE feature_name = ? AND version = ?`; a 0-row update
-  // means someone else wrote concurrently — the handler retries the fetch.
-  version: integer("version").notNull().default(1),
-  updatedAt: instant("updated_at").default(sql`now()`).notNull(),
-  // UserId (text — SessionUser.id is a uuid string post-ES).
-  updatedBy: text("updated_by"),
-});
+export const globalFeatureStateTable: SchemaTable & TenancyBrand<"global"> = declareGlobalTenancy(
+  pgTable("store_global_feature_state", {
+    featureName: text("feature_name").primaryKey(),
+    enabled: boolean("enabled").notNull(),
+    // Optimistic-lock column: the set-handler updates `WHERE feature_name = ? AND
+    // version = ?`; a 0-row update means a concurrent write, so it retries the fetch.
+    version: integer("version").notNull().default(1),
+    updatedAt: instant("updated_at").default(sql`now()`).notNull(),
+    // UserId (text — SessionUser.id is a uuid string post-ES).
+    updatedBy: text("updated_by"),
+  }),
+);
 
 // r.storeTable meta — without this, collectTableMetas(FEATURES) never
 // sees the table, so `kumiko schema generate` reports no changes and no

package/src/feature-toggles/handlers/list.query.ts

@@ -1,4 +1,3 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { FEATURE_TOGGLE_CROSS_TENANT_REASON } from "../constants";
@@ -32,7 +31,7 @@ export const listQuery = defineQueryHandler({
       updatedAt: Temporal.Instant;
       updatedBy: string;
     };
-    const rows = await selectMany<Row>(db.raw, globalFeatureStateTable);
+    const rows = await db.global(globalFeatureStateTable).selectMany<Row>();
     return {
       items: rows.map((r) => ({
         featureName: r.featureName,

package/src/feature-toggles/handlers/registered.query.ts

@@ -1,4 +1,3 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { FEATURE_TOGGLE_CROSS_TENANT_REASON } from "../constants";
@@ -36,7 +35,7 @@ export const registeredQuery = defineQueryHandler({
     const db = ctx.systemDb.acknowledgeCrossTenant(FEATURE_TOGGLE_CROSS_TENANT_REASON);
 
     type OverrideRow = { featureName: string; enabled: boolean };
-    const overrideRows = await selectMany<OverrideRow>(db.raw, globalFeatureStateTable);
+    const overrideRows = await db.global(globalFeatureStateTable).selectMany<OverrideRow>();
     const overrides = new Map(overrideRows.map((r) => [r.featureName, r.enabled]));
 
     // SystemAdmin operator-tooling: das listing soll die PLATTFORM-truth

package/src/form-draft/handlers/discard.write.ts

@@ -17,6 +17,9 @@ const fileRefExecutor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
   entityName: "fileRef",
 });
 
+const DISCARD_DRAFT_FILE_REFS_REASON =
+  "matches draft storage keys against the caller's own file_refs rows via raw SQL";
+
 // discard — the caller's own draft only. Ownership is enforced by the
 // lookup predicate (tenantId + ownerId + draftKey), not by a separate
 // permission check: a foreign user's discard call for someone else's
@@ -30,6 +33,9 @@ export const discardDraftWrite = defineWriteHandler({
   description:
     "Deletes the calling user's draft for one draftKey and, when releaseFiles is set, hard-deletes the file references that draft alone uploaded; use it after a successful submit or when the user abandons the form.",
   agent: { risk: "high" },
+  escapeHatch: {
+    reason: DISCARD_DRAFT_FILE_REFS_REASON,
+  },
   handler: async (event, ctx) => {
     const ownerId = event.user.id;
     const existing = await lookupDraft(
@@ -62,7 +68,7 @@ export const discardDraftWrite = defineWriteHandler({
       // predates the draft row, so the insertedAt filter must not apply.
       const isCreateMode = event.payload.draftKey.includes(":new:");
       const ownedRefs = await filterOwnedFileRefs(
-        ctx.db.raw,
+        ctx.db.unsafeRaw(DISCARD_DRAFT_FILE_REFS_REASON),
         event.user.tenantId,
         ownerId,
         candidateKeys,

package/src/form-draft/handlers/save.write.ts

@@ -31,12 +31,18 @@ function isDraftKeyConflict(failure: WriteFailure): boolean {
   );
 }
 
+const SAVE_DRAFT_COUNT_REASON =
+  "COUNT(*) of the caller's own drafts without loading 64KB value blobs";
+
 export const saveDraftWrite = defineWriteHandler({
   name: "save",
   schema: saveDraftPayloadSchema,
   access: FORM_DRAFT_ACCESS,
   description:
     "Upserts the calling user's draft for one draftKey with the given form values and step index, stamping savedAt server-side and refusing a brand-new draft once the per-owner draft cap is reached; use it to persist an in-progress form before the real entity exists.",
+  escapeHatch: {
+    reason: SAVE_DRAFT_COUNT_REASON,
+  },
   handler: async (event, ctx) => {
     const ownerId = event.user.id;
     const { draftKey, values, stepIndex } = event.payload;
@@ -55,7 +61,11 @@ export const saveDraftWrite = defineWriteHandler({
     // Cap check only on the create path — an update never grows the number
     // of drafts this owner has, so a user already at the limit can still
     // keep saving their existing drafts.
-    const draftCount = await countDraftsByOwner(ctx.db.raw, event.user.tenantId, ownerId);
+    const draftCount = await countDraftsByOwner(
+      ctx.db.unsafeRaw(SAVE_DRAFT_COUNT_REASON),
+      event.user.tenantId,
+      ownerId,
+    );
     if (draftCount >= FORM_DRAFT_MAX_PER_OWNER) {
       return failUnprocessable("draft_limit_reached", { limit: FORM_DRAFT_MAX_PER_OWNER });
     }

package/src/inbound-mail-foundation/__tests__/inbound-mail-foundation.integration.test.ts

@@ -396,7 +396,9 @@ describe("scenario 2d: ingest-message — thread-rollup retry exhaustion (#1229)
     const accountId = await connectSharedAccount(admin);
     const messageIdHeader = "exhaustion-root@example.com";
 
-    const tenantDb = createTenantDb(db, admin.tenantId, "system");
+    const tenantDb = createTenantDb(db, admin.tenantId, "system", undefined, undefined, undefined, {
+      unsafeRaw: { reason: "test: hand-built ctx driving ingestMessageHandler directly" },
+    });
     let threadAppendAttempts = 0;
     const ctx = {
       db: tenantDb,

package/src/inbound-mail-foundation/handlers/ingest-message.write.ts

@@ -20,7 +20,7 @@
 // SystemAdmin-only: Aufrufer ist der Watch/Sync-Supervisor bzw. der
 // Poll-Cron mit programmatic SystemUser — nie ein Tenant-Request.
 
-import { countWhere, insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { countWhere } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   configuredPiiSubjectKms,
   encryptPiiFieldValues,
@@ -106,11 +106,16 @@ const THREAD_ROLLUP_MAX_ATTEMPTS = 5;
 // — 'inbm' as ASCII, keeps it disjoint from the framework's other fixed
 // single-int advisory-lock keys (schema bootstrap, es-ops boot).
 const THREAD_ROLLUP_LOCK_NAMESPACE = 0x696e626d;
+const THREAD_ROLLUP_ADVISORY_LOCK_REASON =
+  "takes the per-thread advisory lock and counts the caller tenant's thread messages; TenantDb has no lock/count API";
 export const ingestMessageHandler: WriteHandlerDef = {
   name: "ingest-message",
   schema: ingestMessageSchema,
   access: { roles: ["SystemAdmin"] },
   agent: { expose: false },
+  escapeHatch: {
+    reason: THREAD_ROLLUP_ADVISORY_LOCK_REASON,
+  },
   handler: async (event, ctx) => {
     // @cast-boundary engine-payload — dispatcher-zod-validated payload
     const payload = event.payload as IngestMessagePayload;
@@ -125,7 +130,7 @@ export const ingestMessageHandler: WriteHandlerDef = {
     //    Check ist billig und macht den Handler rebuild-robust falls
     //    store_mail_seen_messages je getruncated wird).
     // ---------------------------------------------------------------
-    const seenRows = await selectMany(ctx.db.raw, seenMessageTable, {
+    const seenRows = await ctx.db.selectMany(seenMessageTable, {
       accountId: payload.accountId,
       providerMessageId: payload.providerMessageId,
     });
@@ -138,7 +143,7 @@ export const ingestMessageHandler: WriteHandlerDef = {
     const existingEvents = await ctx.loadAggregate(messageAggId);
     if (existingEvents.length > 0) {
       // Stream existiert, Anchor fehlte → Anchor nachziehen, dann raus.
-      await insertOne(ctx.db.raw, seenMessageTable, {
+      await ctx.db.insertOne(seenMessageTable, {
         tenantId,
         accountId: payload.accountId,
         providerMessageId: payload.providerMessageId,
@@ -267,7 +272,12 @@ export const ingestMessageHandler: WriteHandlerDef = {
         )
       : threadPlainPii;
 
-    await acquireNamespacedAdvisoryLock(ctx.db.raw, THREAD_ROLLUP_LOCK_NAMESPACE, threadAggId);
+    const threadRollupRunner = ctx.db.unsafeRaw(THREAD_ROLLUP_ADVISORY_LOCK_REASON);
+    await acquireNamespacedAdvisoryLock(
+      threadRollupRunner,
+      THREAD_ROLLUP_LOCK_NAMESPACE,
+      threadAggId,
+    );
 
     let threadAppendOk = false;
     for (let attempt = 1; attempt <= THREAD_ROLLUP_MAX_ATTEMPTS && !threadAppendOk; attempt++) {
@@ -278,7 +288,7 @@ export const ingestMessageHandler: WriteHandlerDef = {
       const previousLastAt = previousThread?.lastMessageAtIso ?? "";
       const newLastAt =
         payload.receivedAtIso > previousLastAt ? payload.receivedAtIso : previousLastAt;
-      const messageCount = await countWhere(ctx.db.raw, inboundMessagesProjectionTable, {
+      const messageCount = await countWhere(threadRollupRunner, inboundMessagesProjectionTable, {
         tenantId,
         threadKey,
       });
@@ -308,7 +318,7 @@ export const ingestMessageHandler: WriteHandlerDef = {
     // 6. Dedup-Anchor. Läuft in derselben TX wie die appends — stirbt
     //    der Handler, rollt alles zusammen zurück.
     // ---------------------------------------------------------------
-    await insertOne(ctx.db.raw, seenMessageTable, {
+    await ctx.db.insertOne(seenMessageTable, {
       tenantId,
       accountId: payload.accountId,
       providerMessageId: payload.providerMessageId,

package/src/inbound-mail-foundation/handlers/list-accounts.query.ts

@@ -7,8 +7,6 @@
 // selbst + TenantAdmin/SystemAdmin (Compliance-Sicht). Filter läuft
 // in-memory nach dem tenant-scoped select — Volumen ist die Anzahl
 // verbundener Postfächer eines Tenants (einstellig bis zweistellig).
-
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   configuredPiiSubjectKms,
   decryptPiiFieldValues,
@@ -28,7 +26,7 @@ export const listAccountsQuery: QueryHandlerDef = {
   description:
     "Lists the connected mailboxes of the caller's tenant with the mailbox address decrypted, hiding personal mailboxes the caller neither owns nor administers; use it for the mail connect and settings views.",
   handler: async (_query, ctx) => {
-    const allRows = await selectMany(ctx.db.raw, mailAccountsProjectionTable, {
+    const allRows = await ctx.db.selectMany(mailAccountsProjectionTable, {
       tenantId: ctx.user.tenantId,
     });
     const rows = allRows.filter((row) => isVisibleToCaller(row, ctx.user));

package/src/inbound-mail-foundation/handlers/list-messages.query.ts

@@ -8,7 +8,6 @@
 // das Inbox-Cockpit lädt begrenzte Zeiträume; ein `limit`-Feld ist
 // vorwärtskompatibel ergänzbar ohne den QN zu brechen.
 
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   configuredPiiSubjectKms,
   decryptPiiFieldValues,
@@ -42,7 +41,7 @@ export const listMessagesQuery: QueryHandlerDef = {
     if (payload.threadKey) filter["threadKey"] = payload.threadKey;
     if (payload.scope) filter["scope"] = payload.scope;
 
-    const allRows = await selectMany(ctx.db.raw, inboundMessagesProjectionTable, filter);
+    const allRows = await ctx.db.selectMany(inboundMessagesProjectionTable, filter);
     // Scope-Sichtbarkeit (Plan Entscheidung 2): Messages persönlicher
     // Postfächer nur für Owner + TenantAdmin/SystemAdmin.
     const rows = allRows.filter((row) => isVisibleToCaller(row, ctx.user));

package/src/jobs/handlers/projection-rebuild.job.ts

@@ -27,10 +27,10 @@ export const projectionRebuildJob: JobHandlerFn = async (rawPayload, ctx): Promi
         "[jobs:projection-rebuild] ctx.registry missing — job context requires the registry.",
     });
   }
-  // Global rebuild by design (streams every tenant's events, not just one) —
-  // acknowledgeCrossTenant documents that instead of the previous implicit
-  // ctx.db cast. .raw is the same DbConnection ctx.db carried before.
-  const db = ctx.systemDb.acknowledgeCrossTenant("global projection rebuild").raw as DbConnection; // @cast-boundary db-operator
+  // Global rebuild by design (streams every tenant's events) — acknowledgeCrossTenant
+  // documents that instead of the previous implicit ctx.db cast.
+  ctx.systemDb.acknowledgeCrossTenant("global projection rebuild");
+  const db = ctx.systemDb.unsafeRaw("projection rebuild spans every tenant's rows") as DbConnection; // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
   const result = await rebuildProjection(projection, {
     db,
     registry: ctx.registry,

package/src/jobs/handlers/reindex-entity.job.ts

@@ -42,9 +42,12 @@ export const reindexEntityJob: JobHandlerFn = async (rawPayload, ctx): Promise<v
         "[jobs:reindex-entity] ctx.systemDb missing — the owning feature must declare r.systemScope().",
     });
   }
-  // .raw bypasses tenant filtering, safe here only because reindexEntity
+  // unsafeRaw bypasses tenant filtering, safe here only because reindexEntity
   // filters `WHERE tenant_id = $1` itself with this same tenantId.
-  const db = ctx.systemDb.assertTenantMatch(tenantId).raw;
+  ctx.systemDb.assertTenantMatch(tenantId);
+  const db = ctx.systemDb.unsafeRaw(
+    "reindexEntity filters WHERE tenant_id = $1 itself with this job's tenantId",
+  );
   const result = await reindexEntity(db, ctx.registry, ctx.searchAdapter, entity, tenantId);
   ctx.log?.info?.(
     `[jobs:reindex-entity] tenant=${tenantId} reindexed ${entity}: ${result.indexedRows}/${result.scannedRows} rows indexed` +

package/src/ledger/__tests__/ledger-reports-tenant-isolation.integration.test.ts

@@ -0,0 +1,148 @@
+// Regression for fw#2858: reports.query.ts's loadBooks() reads accounts and
+// transactions via a raw DbRunner with an explicit `tenantId` where-clause.
+// If that filter is ever dropped (e.g. a future refactor swaps back to an
+// unfiltered runner), a tenant's report would silently aggregate every other
+// tenant's books. Two tenants book distinct, non-cancelling amounts so a
+// cross-tenant leak changes the report totals, not just adds zero-sum noise.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { type AccountType, LedgerHandlers, LedgerQueries } from "../constants";
+import { accountEntity, scheduleEntity, transactionEntity } from "../entity";
+import { createLedgerFeature } from "../feature";
+import type { Posting } from "../schemas";
+
+const ledgerFeature = createLedgerFeature();
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [ledgerFeature] });
+  await unsafeCreateEntityTable(stack.db, accountEntity);
+  await unsafeCreateEntityTable(stack.db, transactionEntity);
+  await unsafeCreateEntityTable(stack.db, scheduleEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_ledger_accounts");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_ledger_transactions");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_ledger_schedules");
+});
+
+const tenantA = createTestUser({ roles: ["TenantAdmin"] });
+const tenantB = createTestUser({
+  roles: ["TenantAdmin"],
+  tenantId: "00000000-0000-4000-8000-0000000000bb",
+});
+
+async function createAccount(
+  name: string,
+  type: AccountType,
+  user: typeof tenantA,
+): Promise<string> {
+  const acc = await stack.http.writeOk<{ id: string }>(
+    LedgerHandlers.createAccount,
+    { name, type },
+    user,
+  );
+  return acc.id;
+}
+
+async function createTransaction(
+  lines: readonly Posting[],
+  opts: { date?: string; description?: string },
+  user: typeof tenantA,
+): Promise<void> {
+  await stack.http.writeOk(
+    LedgerHandlers.createTransaction,
+    { date: opts.date ?? "2026-01-15", description: opts.description ?? "Entry", lines },
+    user,
+  );
+}
+
+async function seedBooks(user: typeof tenantA, capital: number, income: number, expense: number) {
+  const bank = await createAccount("Bank", "asset", user);
+  const equity = await createAccount("Equity", "equity", user);
+  const rent = await createAccount("Rent", "income", user);
+  const cost = await createAccount("Cost", "expense", user);
+  await createTransaction(
+    [
+      { accountId: bank, amount: capital },
+      { accountId: equity, amount: -capital },
+    ],
+    { date: "2026-01-01", description: "Capital" },
+    user,
+  );
+  await createTransaction(
+    [
+      { accountId: bank, amount: income },
+      { accountId: rent, amount: -income },
+    ],
+    { date: "2026-01-10", description: "Income" },
+    user,
+  );
+  await createTransaction(
+    [
+      { accountId: cost, amount: expense },
+      { accountId: bank, amount: -expense },
+    ],
+    { date: "2026-01-20", description: "Expense" },
+    user,
+  );
+  return { bank };
+}
+
+describe("ledger integration — report tenant isolation", () => {
+  test("reportBalances excludes the other tenant's accounts and amounts", async () => {
+    const { bank: bankA } = await seedBooks(tenantA, 500000, 100000, 30000);
+    const { bank: bankB } = await seedBooks(tenantB, 200000, 50000, 10000);
+
+    const reportA = await stack.http.queryOk<{
+      accounts: Array<{ id: string; balance: number }>;
+      trialBalance: number;
+    }>(LedgerQueries.reportBalances, {}, tenantA);
+    expect(reportA.accounts).toHaveLength(4);
+    expect(reportA.accounts.some((a) => a.id === bankB)).toBe(false);
+    expect(reportA.accounts.find((a) => a.id === bankA)?.balance).toBe(570000);
+
+    const reportB = await stack.http.queryOk<{
+      accounts: Array<{ id: string; balance: number }>;
+      trialBalance: number;
+    }>(LedgerQueries.reportBalances, {}, tenantB);
+    expect(reportB.accounts).toHaveLength(4);
+    expect(reportB.accounts.some((a) => a.id === bankA)).toBe(false);
+    expect(reportB.accounts.find((a) => a.id === bankB)?.balance).toBe(240000);
+  });
+
+  test("reportIncomeStatement does not sum the other tenant's income/expense", async () => {
+    await seedBooks(tenantA, 500000, 100000, 30000);
+    await seedBooks(tenantB, 200000, 50000, 10000);
+
+    const stmtA = await stack.http.queryOk<{
+      income: number;
+      expense: number;
+      netIncome: number;
+    }>(LedgerQueries.reportIncomeStatement, {}, tenantA);
+    expect(stmtA).toEqual({ income: 100000, expense: 30000, netIncome: 70000 });
+
+    const stmtB = await stack.http.queryOk<{
+      income: number;
+      expense: number;
+      netIncome: number;
+    }>(LedgerQueries.reportIncomeStatement, {}, tenantB);
+    expect(stmtB).toEqual({ income: 50000, expense: 10000, netIncome: 40000 });
+  });
+});

package/src/ledger/handlers/confirm-schedule-period.write.ts

@@ -1,4 +1,3 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type {
   AccessRule,
   WriteHandlerDef,
@@ -68,14 +67,14 @@ export function createConfirmSchedulePeriodHandler(
       // ponytail: read-then-write, so two confirms racing the same period could
       // double-book; add a unique index on (tenantId, reference) when concurrent
       // confirms become real.
-      const candidates = await selectMany(ctx.db.raw, transactionTable, {
+      const candidates = await ctx.db.selectMany(transactionTable, {
         tenantId: event.user.tenantId,
         reference,
       });
       const candidateIds = candidates.map((r) => String(r["id"]));
       const stornos =
         candidateIds.length > 0
-          ? await selectMany(ctx.db.raw, transactionTable, {
+          ? await ctx.db.selectMany(transactionTable, {
               tenantId: event.user.tenantId,
               reference: { in: candidateIds },
             })

package/src/ledger/handlers/reports.query.ts

@@ -1,4 +1,3 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { AccessRule, QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { DEFAULT_LEDGER_ACCESS } from "../constants";
@@ -25,8 +24,8 @@ type QueryCtx = Parameters<QueryHandlerDef["handler"]>[1];
 async function loadBooks(
   ctx: QueryCtx,
 ): Promise<{ accounts: LedgerAccount[]; entries: LedgerEntry[] }> {
-  const accountRows = await selectMany(ctx.db.raw, accountTable, { tenantId: ctx.user.tenantId });
-  const txRows = await selectMany(ctx.db.raw, transactionTable, { tenantId: ctx.user.tenantId });
+  const accountRows = await ctx.db.selectMany(accountTable, { tenantId: ctx.user.tenantId });
+  const txRows = await ctx.db.selectMany(transactionTable, { tenantId: ctx.user.tenantId });
   return { accounts: toAccounts(accountRows), entries: toEntries(txRows) };
 }
 

package/src/ledger/handlers/reverse-transaction.write.ts

@@ -1,4 +1,3 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import {
   ConflictError,
@@ -48,7 +47,7 @@ export function createReverseTransactionHandler(
       // an independently-balanced Storno (the global trial balance stays 0
       // either way, masking the bug), doubling the per-account effect. The
       // reference column ties a Storno back to its original 1:1.
-      const alreadyReversed = await selectMany(ctx.db.raw, transactionTable, {
+      const alreadyReversed = await ctx.db.selectMany(transactionTable, {
         tenantId: event.user.tenantId,
         reference: payload.id,
       });

package/src/managed-pages/handlers/set.write.ts

@@ -23,6 +23,9 @@ const langSchema = z
 
 const executor = createEventStoreExecutor(pagesTable, pageEntity, { entityName: "page" });
 
+const SET_PAGE_TENANT_OVERRIDE_REASON =
+  "SystemAdmin tenantIdOverride re-scopes the page write to the target tenant";
+
 // Upsert einer Page — eine Operation pro (tenantId, slug, lang). Tenant-
 // Scope default aus event.user; SystemAdmin kann via `tenantIdOverride`
 // für einen anderen Tenant schreiben (typisch SYSTEM_TENANT_ID für app-
@@ -45,6 +48,9 @@ export const setWrite = defineWriteHandler({
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   description:
     "Creates or overwrites one managed page addressed by slug and language, keeping the existing published flag, description and OG image when the payload omits them; use it for content edits and publish toggles, and as SystemAdmin to write another tenant's pages.",
+  escapeHatch: {
+    reason: SET_PAGE_TENANT_OVERRIDE_REASON,
+  },
   handler: async (event, ctx) => {
     const db = ctx.db;
     const override = event.payload.tenantIdOverride;
@@ -63,7 +69,13 @@ export const setWrite = defineWriteHandler({
     // on both the existing-check and the executor's stream reads; re-scope to the target.
     // Safe: the override branch is SystemAdmin-gated above.
     const scopedDb =
-      override !== undefined ? createTenantDb(db.raw, override as TenantId, "tenant") : db; // @cast-boundary engine-bridge
+      override !== undefined
+        ? createTenantDb(
+            db.unsafeRaw(SET_PAGE_TENANT_OVERRIDE_REASON),
+            override as TenantId, // @cast-boundary engine-bridge
+            "tenant",
+          )
+        : db;
     const existing = await fetchOne<PageRow>(scopedDb, pagesTable, {
       tenantId,
       slug: event.payload.slug,

package/src/notes-history/handlers/add-note.write.ts

@@ -7,6 +7,9 @@ import { DEFAULT_NOTES_HISTORY_ACCESS } from "../constants";
 import { noteEntryExecutor, noteMentionExecutor } from "../executor";
 import { type AddNotePayload, addNotePayloadSchema } from "../schemas";
 
+const READ_AUTHOR_DISPLAY_NAME_REASON =
+  "reads the author's displayName from the global users table inside a savepoint so a missing user feature cannot poison the note transaction";
+
 // add-note — appends a note-entry to (entityType, entityId). authorId is
 // NEVER read from the payload: it is always the authenticated caller
 // (event.user.id), so a note can't be authored as someone else. No update or
@@ -28,6 +31,9 @@ export function createAddNoteHandler(
     access,
     description:
       "Appends a note to one host entity's history, stamping the author from the authenticated caller rather than the payload; use it for every remark and correction alike, because entries can never be edited or removed afterwards.",
+    escapeHatch: {
+      reason: READ_AUTHOR_DISPLAY_NAME_REASON,
+    },
     handler: async (event, ctx) => {
       const payload = event.payload as AddNotePayload; // @cast-boundary engine-payload
 
@@ -47,16 +53,19 @@ export function createAddNoteHandler(
 
       let authorName: string | null = null;
       try {
-        // read_users is tenant-agnostic → ctx.db.raw, not the tenant-scoped ctx.db.
+        // read_users is tenant-agnostic → ctx.db.unsafeRaw, not the tenant-scoped ctx.db.
         // Bun.SQL poisons the whole tx after any error inside it, even one that's
         // caught — a bare try/catch here would take the note write down with it.
-        authorName = await runInSavepointIfSupported(ctx.db.raw, async (sp) => {
-          const userRow = await fetchOne<{ displayName: string | null }>(sp, userTable, {
-            id: event.user.id,
-          });
-          if (!userRow?.displayName) return null;
-          return decryptStoredPii(userRow.displayName, "displayName", "notes-history:add-note");
-        });
+        authorName = await runInSavepointIfSupported(
+          ctx.db.unsafeRaw(READ_AUTHOR_DISPLAY_NAME_REASON),
+          async (sp) => {
+            const userRow = await fetchOne<{ displayName: string | null }>(sp, userTable, {
+              id: event.user.id,
+            });
+            if (!userRow?.displayName) return null;
+            return decryptStoredPii(userRow.displayName, "displayName", "notes-history:add-note");
+          },
+        );
       } catch (e) {
         ctx.log?.warn("notes-history: authorName lookup failed", {
           error: e,

package/src/personal-access-tokens/handlers/create.write.ts

@@ -61,7 +61,8 @@ export function createPatCreateHandler(opts: CreatePatOptions = {}) {
     escapeHatch: {
       reason:
         "Reads the caller's own passwordHash (privileged-only field) via ctx.queryAs(SYSTEM, " +
-        "user:findForAuth) to re-verify the current password before minting the token.",
+        "user:findForAuth) to re-verify the current password before minting the token. Also " +
+        "reads the MFA enrollment of the user being re-authenticated via the mfaVerifier callback.",
     },
     description:
       "Mints a personal access token for the calling user after re-verifying their password (and MFA code when enrolled) and returns the plaintext token exactly once; use it when a user needs a long-lived API credential.",

package/src/secrets/handlers/list.query.ts

@@ -1,4 +1,3 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { type AccessRule, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { DEFAULT_SECRETS_ACCESS } from "../constants";
@@ -15,14 +14,13 @@ export function createListHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS) {
     schema: z.object({}),
     access,
     handler: async (event, ctx) => {
-      const rows = await selectMany<{
+      const rows = await ctx.db.selectMany<{
         key: string;
         kekVersion: number;
         metadata: { redactedPreview?: string; hint?: string };
         lastRotatedAt: unknown;
         insertedAt: unknown;
       }>(
-        ctx.db.raw,
         tenantSecretsTable,
         { tenantId: event.user.tenantId },
         {