@cosmicdrift/kumiko-bundled-features 0.278.0 → 0.281.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.278.0",
+  "version": "0.281.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -129,12 +129,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.278.0",
-    "@cosmicdrift/kumiko-framework": "0.278.0",
-    "@cosmicdrift/kumiko-headless": "0.278.0",
-    "@cosmicdrift/kumiko-renderer": "0.278.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.278.0",
-    "@cosmicdrift/kumiko-types": "0.278.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.281.0",
+    "@cosmicdrift/kumiko-framework": "0.281.0",
+    "@cosmicdrift/kumiko-headless": "0.281.0",
+    "@cosmicdrift/kumiko-renderer": "0.281.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.281.0",
+    "@cosmicdrift/kumiko-types": "0.281.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -163,7 +163,7 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.278.0",
-    "@cosmicdrift/kumiko-locale-es": "0.278.0"
+    "@cosmicdrift/kumiko-locale-de": "0.281.0",
+    "@cosmicdrift/kumiko-locale-es": "0.281.0"
   }
 }

package/src/auth-email-password/__tests__/invite-flow-kms.integration.test.ts

@@ -14,6 +14,7 @@ import {
   InMemoryKmsAdapter,
   isPiiCiphertext,
 } from "@cosmicdrift/kumiko-framework/crypto";
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -319,7 +320,7 @@ describe("auth flows with active KMS + blind index", () => {
     expect(isPiiCiphertext(rawInvitation["email"])).toBe(true);
 
     const result = await tenantInvitationExportHook({
-      db: stack.db,
+      db: createTenantDb(stack.db, TENANT_A_ID, "tenant"),
       registry: stack.registry,
       tenantId: TENANT_A_ID,
       userId: bobId,
@@ -347,7 +348,12 @@ describe("auth flows with active KMS + blind index", () => {
     expect(isPiiCiphertext(rawBefore["invited_by"])).toBe(true);
 
     await tenantInvitationDeleteHook(
-      { db: stack.db, registry: stack.registry, tenantId: TENANT_A_ID, userId: aliceId },
+      {
+        db: createTenantDb(stack.db, TENANT_A_ID, "tenant"),
+        registry: stack.registry,
+        tenantId: TENANT_A_ID,
+        userId: aliceId,
+      },
       "delete",
     );
 

package/src/auth-email-password/handlers/confirm-token-flow.ts

@@ -24,6 +24,7 @@
 
 import {
   createSystemUser,
+  declareEscapeHatch,
   type HandlerContext,
   type SessionUser,
   SYSTEM_TENANT_ID,
@@ -69,6 +70,10 @@ export async function runConfirmTokenFlow<TSuccessData>(
   expiresAtMs: number,
   spec: ConfirmTokenFlowSpec<TSuccessData>,
 ): Promise<WriteResult<TSuccessData>> {
+  declareEscapeHatch({
+    reason:
+      "writes the confirming user's row via UserHandlers.update on the caller's handler context, using a SYSTEM_TENANT-scoped identity; the calling handler declares its own escapeHatch",
+  });
   if (!ctx.redis) {
     return writeFailure(new InternalError({ message: spec.redisRequiredMessage }));
   }
@@ -131,6 +136,10 @@ async function loadValidatedUser(
   systemUser: SessionUser,
   userId: string,
 ): Promise<(AuthUserRow & { version: number }) | null> {
+  declareEscapeHatch({
+    reason:
+      "reads the confirming user's row via UserQueries.findForAuth on the caller's handler context, using a SYSTEM_TENANT-scoped identity; the calling handler declares its own escapeHatch",
+  });
   const me = parseAuthUserRow(
     await ctx.queryAs(systemUser, UserQueries.findForAuth, { id: userId }),
   );

package/src/auth-email-password/handlers/login.write.ts

@@ -95,12 +95,9 @@ type AuthenticatableUserRow = AuthUserRow & { readonly passwordHash: string };
 
 /** Uniform response on any credential miss — burns argon2 cost (#774). */
 export async function gateResolveAuthUser(
-  ctx: HandlerContext,
-  systemUser: SessionUser,
-  email: string,
+  found: AuthUserRow | null,
   password: string,
 ): Promise<GateOutcome<AuthenticatableUserRow>> {
-  const found = parseAuthUserRow(await ctx.queryAs(systemUser, UserQueries.findForAuth, { email }));
   if (!found?.passwordHash || found.isDeleted) {
     await verifyDummyPassword(password);
     return reject(invalidCredentials());
@@ -176,15 +173,9 @@ export function gateEnforceAccountStatus(found: AuthUserRow): GateOutcome<undefi
 /** Pick membership (last-active preferred); merge global + tenant roles. */
 export async function gateResolveMembership(
   ctx: HandlerContext,
-  systemUser: SessionUser,
   found: AuthUserRow,
+  memberships: ReadonlyArray<Membership>,
 ): Promise<GateOutcome<{ readonly chosen: Membership; readonly mergedRoles: readonly string[] }>> {
-  // Still needed for candidate ORDER (preferred tenant first) — the actual
-  // active/blocked/teardown decision comes from ctx.resolveActiveMembership below.
-  const memberships = (await ctx.queryAs(systemUser, TENANT_MEMBERSHIPS_QUERY, {
-    userId: found.id,
-  })) as Array<Membership>; // @cast-boundary db-runner
-
   if (memberships.length === 0) {
     return reject(noMembership());
   }
@@ -296,12 +287,10 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
     handler: async (event, ctx): Promise<WriteResult<LoginResult>> => {
       const systemUser = createSystemUser(SYSTEM_USER_ID);
 
-      const userGate = await gateResolveAuthUser(
-        ctx,
-        systemUser,
-        event.payload.email,
-        event.payload.password,
+      const foundRow = parseAuthUserRow(
+        await ctx.queryAs(systemUser, UserQueries.findForAuth, { email: event.payload.email }),
       );
+      const userGate = await gateResolveAuthUser(foundRow, event.payload.password);
       if (!userGate.ok) return userGate.result;
       const found = userGate.value;
 
@@ -323,7 +312,13 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
       const statusGate = gateEnforceAccountStatus(found);
       if (!statusGate.ok) return statusGate.result;
 
-      const membershipGate = await gateResolveMembership(ctx, systemUser, found);
+      // Still needed for candidate ORDER (preferred tenant first) — the actual
+      // active/blocked/teardown decision comes from ctx.resolveActiveMembership below.
+      const memberships = (await ctx.queryAs(systemUser, TENANT_MEMBERSHIPS_QUERY, {
+        userId: found.id,
+      })) as Array<Membership>; // @cast-boundary db-runner
+
+      const membershipGate = await gateResolveMembership(ctx, found, memberships);
       if (!membershipGate.ok) return membershipGate.result;
       const { chosen, mergedRoles } = membershipGate.value;
 

package/src/auth-mfa/mfa-code-verifier.ts

@@ -1,5 +1,9 @@
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
-import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  declareEscapeHatch,
+  type HandlerContext,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { findUserMfaRow } from "./db/queries";
 import { verifyMfaFactor } from "./verify-factor";
 
@@ -21,6 +25,10 @@ export type MfaCodeVerifier = (
 // codes exist for.
 export function createMfaCodeVerifier(): MfaCodeVerifier {
   return async (ctx, userId, tenantId, code) => {
+    declareEscapeHatch({
+      reason:
+        "reads the MFA enrollment of the user being re-authenticated on the caller's handler context; the calling handler declares its own escapeHatch",
+    });
     const scopedDb = createTenantDb(
       ctx.db.unsafeRaw("reads the MFA enrollment of the user being re-authenticated"),
       tenantId,

package/src/auth-mfa/mfa-status-checker.ts

@@ -1,6 +1,7 @@
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
+  declareEscapeHatch,
   type HandlerContext,
   type SessionUser,
   type TenantId,
@@ -38,6 +39,10 @@ export function createMfaStatusChecker(opts: {
   readonly challengeTokenSecret: string;
 }): MfaStatusChecker {
   return async (ctx, userId, tenantId, roles) => {
+    declareEscapeHatch({
+      reason:
+        "reads the MFA enrollment of the tenant named in the signed login/setup token, not the guest dispatch tenant, on the caller's handler context; the calling handler declares its own escapeHatch",
+    });
     const scopedDb = createTenantDb(
       ctx.db.unsafeRaw(
         "reads the MFA enrollment of the tenant named in the signed login/setup token, not the guest dispatch tenant",

package/src/auth-mfa-user-data/__tests__/hooks.integration.test.ts

@@ -3,7 +3,7 @@
 // (not just leave it dangling for a future projection rebuild to resurrect).
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import { configureEntityFieldEncryption, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import {
   createTestUser,
   setupTestStack,
@@ -77,7 +77,7 @@ describe("userMfaExportHook / userMfaDeleteHook", () => {
     const user = await enrollUser("export-1");
 
     const snippet = await userMfaExportHook({
-      db: stack.db,
+      db: createTenantDb(stack.db, user.tenantId, "tenant"),
       registry: stack.registry,
       tenantId: user.tenantId,
       userId: user.id,
@@ -94,7 +94,7 @@ describe("userMfaExportHook / userMfaDeleteHook", () => {
   test("export returns null for a user who never enrolled", async () => {
     const user = createTestUser({ id: "never-enrolled", roles: ["User"] });
     const snippet = await userMfaExportHook({
-      db: stack.db,
+      db: createTenantDb(stack.db, user.tenantId, "tenant"),
       registry: stack.registry,
       tenantId: user.tenantId,
       userId: user.id,
@@ -106,7 +106,7 @@ describe("userMfaExportHook / userMfaDeleteHook", () => {
     const user = await enrollUser("delete-1");
 
     const before = await userMfaExportHook({
-      db: stack.db,
+      db: createTenantDb(stack.db, user.tenantId, "tenant"),
       registry: stack.registry,
       tenantId: user.tenantId,
       userId: user.id,
@@ -115,7 +115,7 @@ describe("userMfaExportHook / userMfaDeleteHook", () => {
 
     await userMfaDeleteHook(
       {
-        db: stack.db,
+        db: createTenantDb(stack.db, user.tenantId, "tenant"),
         registry: stack.registry,
         tenantId: user.tenantId,
         userId: user.id,
@@ -124,7 +124,7 @@ describe("userMfaExportHook / userMfaDeleteHook", () => {
     );
 
     const after = await userMfaExportHook({
-      db: stack.db,
+      db: createTenantDb(stack.db, user.tenantId, "tenant"),
       registry: stack.registry,
       tenantId: user.tenantId,
       userId: user.id,

package/src/auth-mfa-user-data/hooks.ts

@@ -7,8 +7,7 @@
 // replays via the event, a raw DELETE would be resurrected by a
 // projection rebuild).
 
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
   type UserDataDeleteHook,
@@ -26,7 +25,7 @@ const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
 // tokenHash exclusion in user-data-rights-defaults). Just confirms
 // enrollment + when, which is what a data subject actually needs to see.
 export const userMfaExportHook: UserDataExportHook = async (ctx) => {
-  const rows = await selectMany<{ id: string; enabledAt: unknown }>(ctx.db, userMfaTable, {
+  const rows = await ctx.db.selectMany<{ id: string; enabledAt: unknown }>(userMfaTable, {
     userId: ctx.userId,
     tenantId: ctx.tenantId,
   });
@@ -41,15 +40,14 @@ export const userMfaExportHook: UserDataExportHook = async (ctx) => {
 // secret can't be anonymized, and `personal: { of: "userId" }` already
 // means this row belongs to exactly one user (never shared tenant data).
 export const userMfaDeleteHook: UserDataDeleteHook = async (ctx) => {
-  const rows = await selectMany<{ id: string }>(ctx.db, userMfaTable, {
+  const rows = await ctx.db.selectMany<{ id: string }>(userMfaTable, {
     userId: ctx.userId,
     tenantId: ctx.tenantId,
   });
   // skip: nothing enrolled for this user — no row to erase
   if (rows.length === 0) return;
   const systemUser = createSystemUser(ctx.tenantId);
-  const tdb = createTenantDb(ctx.db, ctx.tenantId, "system");
   for (const row of rows) {
-    assertErased(await executor.forget({ id: row.id }, systemUser, tdb), "user-mfa", row.id);
+    assertErased(await executor.forget({ id: row.id }, systemUser, ctx.db), "user-mfa", row.id);
   }
 };

package/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -192,9 +192,9 @@ async function appendDenialAuditEvent(
   subjectKey: string,
   subjectKind: SubjectIdInput["kind"],
   denialCode: string,
+  denialAuditRunner: DbRunner | undefined,
 ): Promise<WriteFailure | null> {
-  const outsideTx = ctx.dbOutsideTransaction;
-  if (!outsideTx) {
+  if (!denialAuditRunner) {
     return writeFailure(
       new InternalError({
         message:
@@ -230,28 +230,23 @@ async function appendDenialAuditEvent(
   // This event is the only proof the denial happened. Skipping
   // runProjectionsForEvent here is fine — nothing projects
   // crypto-shredding:event:forget-denied.
-  await append(
-    outsideTx.unsafeRaw(
-      "denial audit append: names the prober's own tenant stream on the outside-transaction db",
-    ),
-    {
-      aggregateId: generateId(),
-      aggregateType: CRYPTO_SHREDDING_AGGREGATE_TYPE,
-      // MUST be event.user.tenantId, never SYSTEM_TENANT_ID — unsafeRaw
-      // bypasses TenantDb's scoping, so this is the only guard against a cross-tenant denial event (fw#2452).
-      tenantId: event.user.tenantId,
-      expectedVersion: 0,
-      type: SUBJECT_FORGET_DENIED_EVENT_NAME,
-      eventVersion: eventDef.version,
-      payload,
-      metadata: {
-        userId: event.user.id,
-        ...(reqCtx?.requestId ? { requestId: reqCtx.requestId } : {}),
-        ...(reqCtx?.correlationId ? { correlationId: reqCtx.correlationId } : {}),
-        ...(reqCtx?.causationId ? { causationId: reqCtx.causationId } : {}),
-      },
+  await append(denialAuditRunner, {
+    aggregateId: generateId(),
+    aggregateType: CRYPTO_SHREDDING_AGGREGATE_TYPE,
+    // MUST be event.user.tenantId, never SYSTEM_TENANT_ID — unsafeRaw
+    // bypasses TenantDb's scoping, so this is the only guard against a cross-tenant denial event (fw#2452).
+    tenantId: event.user.tenantId,
+    expectedVersion: 0,
+    type: SUBJECT_FORGET_DENIED_EVENT_NAME,
+    eventVersion: eventDef.version,
+    payload,
+    metadata: {
+      userId: event.user.id,
+      ...(reqCtx?.requestId ? { requestId: reqCtx.requestId } : {}),
+      ...(reqCtx?.correlationId ? { correlationId: reqCtx.correlationId } : {}),
+      ...(reqCtx?.causationId ? { causationId: reqCtx.causationId } : {}),
     },
-  );
+  });
   return null;
 }
 
@@ -316,6 +311,9 @@ export const forgetSubjectWrite = defineWriteHandler({
         subjectKey,
         raw.kind,
         tenantScopeDenial.error.code,
+        ctx.dbOutsideTransaction?.unsafeRaw(
+          "denial audit append: names the prober's own tenant stream on the outside-transaction db",
+        ),
       );
       return auditFailure ?? tenantScopeDenial;
     }
@@ -335,6 +333,9 @@ export const forgetSubjectWrite = defineWriteHandler({
         subjectKey,
         raw.kind,
         TARGET_RECORD_RETENTION_BLOCK_DELETE,
+        ctx.dbOutsideTransaction?.unsafeRaw(
+          "denial audit append: names the prober's own tenant stream on the outside-transaction db",
+        ),
       );
       return auditFailure ?? retentionDenial;
     }

package/src/custom-fields/__tests__/user-data-rights.integration.test.ts

@@ -71,8 +71,14 @@ const propertyTable = buildEntityTable("property", propertyEntity);
 // Host entity gets its own EXT_USER_DATA-registration too — that's the
 // canonical setup. The host's anonymize hook NULLS inserted_by_id; the
 // custom-fields wiring contributes export only (#972).
+// fw#2914 — "property" is a managed r.entity table (EXECUTOR_ONLY-branded), so
+// TenantDb's typed write methods reject it; these host hooks need raw SQL,
+// still filtered by inserted_by_id + tenant_id.
+const HOST_HOOK_REASON =
+  "fw#2914 test fixture: host export/delete against a managed entity table needs raw SQL (TenantDb's typed write API rejects EXECUTOR_ONLY tables); filtered by inserted_by_id + tenant_id";
+
 const hostExportHook: UserDataExportHook = async (ctx) => {
-  const rows = await asRawClient(ctx.db).unsafe(
+  const rows = await asRawClient(ctx.db.unsafeRaw(HOST_HOOK_REASON)).unsafe(
     `SELECT id, name FROM read_t15c_properties WHERE inserted_by_id = $1 AND tenant_id = $2`,
     [ctx.userId, ctx.tenantId],
   );
@@ -86,13 +92,13 @@ const hostExportHook: UserDataExportHook = async (ctx) => {
 
 const hostDeleteHook: UserDataDeleteHook = async (ctx, strategy) => {
   if (strategy === "delete") {
-    await asRawClient(ctx.db).unsafe(
+    await asRawClient(ctx.db.unsafeRaw(HOST_HOOK_REASON)).unsafe(
       `DELETE FROM read_t15c_properties WHERE inserted_by_id = $1 AND tenant_id = $2`,
       [ctx.userId, ctx.tenantId],
     );
   } else {
     // anonymize: clear owner, keep row + customFields.
-    await asRawClient(ctx.db).unsafe(
+    await asRawClient(ctx.db.unsafeRaw(HOST_HOOK_REASON)).unsafe(
       `UPDATE read_t15c_properties SET inserted_by_id = NULL WHERE inserted_by_id = $1 AND tenant_id = $2`,
       [ctx.userId, ctx.tenantId],
     );
@@ -111,6 +117,7 @@ const propertyFeature = defineFeature("property-t15c", (r) => {
   r.useExtension(EXT_USER_DATA, "property", {
     export: hostExportHook,
     delete: hostDeleteHook,
+    escapeHatch: { reason: HOST_HOOK_REASON },
   });
 
   const { executor } = createEntityExecutor("property", propertyEntity);

package/src/custom-fields/db/queries/__tests__/unsafe-read-retrying.test.ts

@@ -43,19 +43,14 @@ function fakeClient(failures: Error[], row: Record<string, unknown>): FakeClient
 describe("custom-fields db/queries — closed-connection retry (#2323)", () => {
   test("selectSerializedFieldDefinition retries once through db.unsafeRaw and returns the row", async () => {
     const raw = fakeClient([closedConnectionError()], { serialized_field: "sf1" });
-    const result = await selectSerializedFieldDefinition(
-      { unsafeRaw: () => raw } as never,
-      "t1",
-      "entity",
-      "field",
-    );
+    const result = await selectSerializedFieldDefinition(raw, "t1", "entity", "field");
     expect(result).toBe("sf1");
     expect(raw.calls).toBe(2);
   });
 
   test("countTenantFieldDefinitions retries once through db.unsafeRaw and returns the count", async () => {
     const raw = fakeClient([closedConnectionError()], { n: 3 });
-    const result = await countTenantFieldDefinitions({ unsafeRaw: () => raw } as never, "t1");
+    const result = await countTenantFieldDefinitions(raw, "t1");
     expect(result).toBe(3);
     expect(raw.calls).toBe(2);
   });
@@ -90,9 +85,9 @@ describe("custom-fields db/queries — closed-connection retry (#2323)", () => {
     const raw = fakeClient([closedConnectionError(), closedConnectionError()], {
       serialized_field: "sf1",
     });
-    await expect(
-      selectSerializedFieldDefinition({ unsafeRaw: () => raw } as never, "t1", "entity", "field"),
-    ).rejects.toThrow("connection was closed");
+    await expect(selectSerializedFieldDefinition(raw, "t1", "entity", "field")).rejects.toThrow(
+      "connection was closed",
+    );
     expect(raw.calls).toBe(2);
   });
 });

package/src/custom-fields/db/queries/field-access.ts

@@ -1,16 +1,14 @@
 import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 
 export async function selectSerializedFieldDefinition(
-  db: TenantDb,
+  runner: DbRunner,
   tenantId: string,
   entityName: string,
   fieldKey: string,
 ): Promise<unknown | null> {
   const rows = await unsafeReadRetrying(
-    db.unsafeRaw(
-      "reads custom field definitions with an explicit tenant_id = caller tenant via raw SQL with read retry",
-    ),
+    runner,
     "SELECT serialized_field FROM read_custom_field_definitions WHERE entity_name = $1 AND field_key = $2 AND tenant_id = $3 LIMIT 1",
     [entityName, fieldKey, tenantId],
   );

package/src/custom-fields/db/queries/quota.ts

@@ -1,13 +1,14 @@
 import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 
-export async function countTenantFieldDefinitions(db: TenantDb, tenantId: string): Promise<number> {
+export async function countTenantFieldDefinitions(
+  runner: DbRunner,
+  tenantId: string,
+): Promise<number> {
   // Active definitions only — delete soft-deletes (the deterministic stream is
   // kept so a re-define can restore it), so isDeleted rows must not consume quota.
   const rowsResult = await unsafeReadRetrying(
-    db.unsafeRaw(
-      "counts custom field definitions with an explicit tenant_id = caller tenant via raw SQL with read retry",
-    ),
+    runner,
     "SELECT COUNT(*)::int AS n FROM read_custom_field_definitions WHERE tenant_id = $1 AND is_deleted = FALSE",
     [tenantId],
   );

package/src/custom-fields/handlers/clear-custom-field.write.ts

@@ -39,7 +39,7 @@ export const clearCustomFieldHandler: WriteHandlerDef = {
     const payload = event.payload as ClearCustomFieldPayload; // @cast-boundary engine-payload
 
     const accessCheck = await checkFieldAccessForWrite(
-      ctx.db,
+      ctx.db.unsafeRaw(CLEAR_CUSTOM_FIELD_REASON),
       event.user.tenantId,
       payload.entityName,
       payload.fieldKey,

package/src/custom-fields/handlers/define-tenant-field.write.ts

@@ -73,7 +73,10 @@ export function createDefineTenantFieldHandler(
       }
 
       if (limit !== undefined) {
-        const current = await countTenantFieldDefinitions(ctx.db, tenantId);
+        const current = await countTenantFieldDefinitions(
+          ctx.db.unsafeRaw(DEFINE_TENANT_FIELD_REASON),
+          tenantId,
+        );
         if (current >= limit) {
           return failUnprocessable("cap_exceeded", {
             capName: "customFields.fieldDefinition.count",

package/src/custom-fields/handlers/set-custom-field.write.ts

@@ -62,7 +62,7 @@ export const setCustomFieldHandler: WriteHandlerDef = {
     const payload = event.payload as SetCustomFieldPayload; // @cast-boundary engine-payload
 
     const loaded = await loadFieldDefinition(
-      ctx.db,
+      ctx.db.unsafeRaw(SET_CUSTOM_FIELD_REASON),
       event.user.tenantId,
       payload.entityName,
       payload.fieldKey,

package/src/custom-fields/lib/field-access.ts

@@ -2,7 +2,7 @@
 // Plus single-fetch loader so set-custom-field can run access-check AND
 // value-validation off one DB read (no double fetch).
 
-import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import { selectSerializedFieldDefinition } from "../db/queries/field-access";
 import { parseSerializedField, type SerializedFieldShape } from "./parse-serialized-field";
 
@@ -22,12 +22,12 @@ export type LoadedFieldDefinition =
   | { found: true; field: SerializedFieldShape | null };
 
 export async function loadFieldDefinition(
-  db: TenantDb,
+  runner: DbRunner,
   tenantId: string,
   entityName: string,
   fieldKey: string,
 ): Promise<LoadedFieldDefinition> {
-  const serialized = await selectSerializedFieldDefinition(db, tenantId, entityName, fieldKey);
+  const serialized = await selectSerializedFieldDefinition(runner, tenantId, entityName, fieldKey);
   if (serialized === null) return { found: false };
   // parseSerializedField throws on a #972 legacy `sensitive` definition —
   // that's a corrupt/unprocessable row from this write-gate's perspective,
@@ -57,13 +57,13 @@ export function fieldWriteAccessDeniedRoles(
 // Convenience wrapper retained for clear-custom-field (no value-validation
 // needed there) — does the load + access-check in one call.
 export async function checkFieldAccessForWrite(
-  db: TenantDb,
+  runner: DbRunner,
   tenantId: string,
   entityName: string,
   fieldKey: string,
   userRoles: ReadonlyArray<string>,
 ): Promise<FieldAccessCheckResult> {
-  const loaded = await loadFieldDefinition(db, tenantId, entityName, fieldKey);
+  const loaded = await loadFieldDefinition(runner, tenantId, entityName, fieldKey);
   if (!loaded.found) return { ok: false, reason: "field_definition_not_found" };
   if (loaded.field === null) return { ok: false, reason: "field_definition_corrupt" };
 

package/src/custom-fields/wire-user-data-rights.ts

@@ -1,7 +1,7 @@
 // T1.5c — user-data-rights wiring for custom-fields.
 
-import { extractTableName } from "@cosmicdrift/kumiko-framework/db";
-import type { UserDataExportHook } from "@cosmicdrift/kumiko-framework/engine";
+import { type DbRunner, extractTableName } from "@cosmicdrift/kumiko-framework/db";
+import type { UserDataExportSnippet, UserDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";
 import { EXT_USER_DATA, type FeatureRegistrar } from "@cosmicdrift/kumiko-framework/engine";
 import { selectCustomFieldsHostRows } from "./db/queries/user-data-rights";
 
@@ -27,6 +27,41 @@ function asCustomFieldsHostRow(value: unknown): CustomFieldsHostRow | null {
   return { id: value.id, customFields: Object.fromEntries(Object.entries(cf)) };
 }
 
+// fw#2914 — selectCustomFieldsHostRows runs raw SQL against a dynamic host
+// table name (opts.entityTable varies per call site), so it can't go through
+// TenantDb's typed method API (table param must be a known SchemaTable). The
+// SQL text itself still filters `tenant_id = ctx.tenantId`, so this stays a
+// single-tenant read — the escapeHatch is only for the raw-SQL mechanism, not
+// for cross-tenant access.
+const CUSTOM_FIELDS_EXPORT_REASON =
+  "custom-fields export reads a generic customFields column via raw SQL against a dynamic host table name, not expressible through TenantDb's typed method API; the query still filters tenant_id = ctx.tenantId";
+
+async function exportCustomFields(
+  db: DbRunner,
+  ctx: UserDataHookCtx,
+  tableName: string,
+  opts: WireCustomFieldsUserDataRightsOptions,
+): Promise<UserDataExportSnippet | null> {
+  const rows = await selectCustomFieldsHostRows(
+    db,
+    tableName,
+    opts.userIdColumn,
+    ctx.userId,
+    ctx.tenantId,
+  );
+  const snippetRows: Array<{ id: string; customFields: Record<string, unknown> }> = [];
+  for (const raw of rows) {
+    const row = asCustomFieldsHostRow(raw);
+    if (!row) continue;
+    const customFields = row.customFields;
+    if (customFields && Object.keys(customFields).length > 0) {
+      snippetRows.push({ id: row.id, customFields });
+    }
+  }
+  if (snippetRows.length === 0) return null;
+  return { entity: `${opts.entityName}.customFields`, rows: snippetRows };
+}
+
 // Export-only wiring: custom fields hold supplemental business data, not PII
 // (#972) — there is nothing to redact on user-forget, only Art. 20 export.
 export function wireCustomFieldsUserDataRightsFor<TReg extends FeatureRegistrar<string>>(
@@ -35,29 +70,10 @@ export function wireCustomFieldsUserDataRightsFor<TReg extends FeatureRegistrar<
 ): void {
   const tableName = extractTableName(opts.entityTable, "custom-fields/wire-user-data-rights");
 
-  const exportHook: UserDataExportHook = async (ctx) => {
-    const rows = await selectCustomFieldsHostRows(
-      ctx.db,
-      tableName,
-      opts.userIdColumn,
-      ctx.userId,
-      ctx.tenantId,
-    );
-    const snippetRows: Array<{ id: string; customFields: Record<string, unknown> }> = [];
-    for (const raw of rows) {
-      const row = asCustomFieldsHostRow(raw);
-      if (!row) continue;
-      const customFields = row.customFields;
-      if (customFields && Object.keys(customFields).length > 0) {
-        snippetRows.push({ id: row.id, customFields });
-      }
-    }
-    if (snippetRows.length === 0) return null;
-    return { entity: `${opts.entityName}.customFields`, rows: snippetRows };
-  };
-
   // biome-ignore lint/correctness/useHookAtTopLevel: r.useExtension is a registrar API, not a React hook.
   r.useExtension(EXT_USER_DATA, opts.entityName, {
-    export: exportHook,
+    export: async (ctx: UserDataHookCtx) =>
+      exportCustomFields(ctx.db.unsafeRaw(CUSTOM_FIELDS_EXPORT_REASON), ctx, tableName, opts),
+    escapeHatch: { reason: CUSTOM_FIELDS_EXPORT_REASON },
   });
 }