@cosmicdrift/kumiko-bundled-features 0.265.0 → 0.268.0

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

@@ -119,7 +119,11 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
     escapeHatch: {
       reason:
         "Anonymous invite-accept has no session in the invited tenant yet — checks existing " +
-        "membership via ctx.queryAs(SYSTEM, tenant:query:memberships) of the invitation's tenant.",
+        "membership via ctx.queryAs(SYSTEM, tenant:query:memberships) of the invitation's tenant. " +
+        "Also reads the pending invitation by id (the invitee is not yet a member of the " +
+        "invitation's tenant), adds the membership and accepts the invitation in the " +
+        "invitation's tenant, which differs from the caller's tenant, and reads the MFA " +
+        "enrollment of that tenant via the mfaStatusChecker callback.",
     },
     agent: { expose: false },
     // kumiko-lint-ignore complexity-budget reuses login.write.ts's gate chain (lockout/password/email/status/membership/mfa) plus invite-specific branches (email match, already-member check, invitation update, unburn-on-failure) — splitting would scatter gate order across functions without reducing risk
@@ -154,9 +158,13 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
 
       let committed = false;
       try {
-        const invitation = await fetchOne<InvitationRow>(ctx.db.raw, tenantInvitationsTable, {
-          id: invitationId,
-        });
+        const invitation = await fetchOne<InvitationRow>(
+          ctx.db.unsafeRaw(
+            "reads the pending invitation by id; the invitee is not yet a member of the invitation's tenant",
+          ),
+          tenantInvitationsTable,
+          { id: invitationId },
+        );
         if (!invitation || invitation.status !== INVITATION_STATUS.pending)
           return invalidInviteToken();
 
@@ -178,7 +186,7 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
         // login.write.ts runs (see login-gates.test.ts for the gate contracts).
         // Email uniqueness is partial on live rows (framework#2593) — without
         // this filter the lookup can resolve a soft-deleted row.
-        const userRow = await fetchOne<UserAuthRow>(ctx.db.raw, userTable, {
+        const userRow = await ctx.db.global(userTable).fetchOne<UserAuthRow>({
           email: invitationEmail,
           isDeleted: false,
         });
@@ -215,7 +223,9 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
         )) as Array<{ tenantId: string }>; // @cast-boundary db-row
         const alreadyMember = memberships.some((m) => m.tenantId === invitationTenantId);
 
-        const dbConn = ctx.db.raw;
+        const dbConn = ctx.db.unsafeRaw(
+          "adds the membership and accepts the invitation in the invitation's tenant, which differs from the caller's tenant",
+        );
 
         if (!alreadyMember) {
           const forbiddenInviteRole = findForbiddenMembershipRole([invitationRole]);

package/src/auth-email-password/handlers/invite-accept.write.ts

@@ -67,6 +67,13 @@ const invitationExecutor = createEventStoreExecutor(
   { entityName: "tenant-invitation" },
 );
 
+const INVITE_ACCEPT_ESCAPE_HATCH_REASON =
+  "reads the pending invitation by id; the invitee is not yet a member of the invitation's tenant. Adds the membership and accepts the invitation in the invitation's tenant, which differs from the caller's tenant.";
+const READ_PENDING_INVITATION_REASON =
+  "reads the pending invitation by id; the invitee is not yet a member of the invitation's tenant";
+const ADD_MEMBERSHIP_INVITATION_TENANT_REASON =
+  "adds the membership and accepts the invitation in the invitation's tenant, which differs from the caller's tenant";
+
 export function createInviteAcceptHandler() {
   return defineWriteHandler<"invite-accept", typeof InviteAcceptSchema, InviteAcceptData>({
     name: "invite-accept",
@@ -76,6 +83,9 @@ export function createInviteAcceptHandler() {
     // dispatched wird.
     access: { openToAll: true },
     agent: { expose: false },
+    escapeHatch: {
+      reason: INVITE_ACCEPT_ESCAPE_HATCH_REASON,
+    },
     // kumiko-lint-ignore complexity-budget invite branches (auth/anon/burn) stay in one handler
     handler: async (event, ctx) => {
       if (!ctx.redis) {
@@ -101,9 +111,11 @@ export function createInviteAcceptHandler() {
 
       let committed = false;
       try {
-        const invitation = await fetchOne<InvitationRow>(ctx.db.raw, tenantInvitationsTable, {
-          id: invitationId,
-        });
+        const invitation = await fetchOne<InvitationRow>(
+          ctx.db.unsafeRaw(READ_PENDING_INVITATION_REASON),
+          tenantInvitationsTable,
+          { id: invitationId },
+        );
         if (!invitation || invitation.status !== INVITATION_STATUS.pending)
           return invalidInviteToken();
 
@@ -119,7 +131,7 @@ export function createInviteAcceptHandler() {
         // Email-Match: User muss mit der eingeladenen Email matchen.
         // Sonst kann ein Angreifer mit Zugriff zur invitee-Mail seinen
         // eigenen Account dem Tenant zuschlagen.
-        const userRow = await fetchOne<UserEmailRow>(ctx.db.raw, userTable, {
+        const userRow = await ctx.db.global(userTable).fetchOne<UserEmailRow>({
           id: event.user.id,
         });
         const userEmail = userRow?.email
@@ -134,13 +146,14 @@ export function createInviteAcceptHandler() {
         // ein Re-Invite in einen (vorübergehend) disabled Tenant würde dort
         // alreadyMember=false sehen und am Unique-Constraint scheitern.
         // Idempotenz: schon Member → no-op + 200 mit alreadyMember=true.
-        const membershipRow = await fetchOne(ctx.db.raw, tenantMembershipsTable, {
+        const invitationTenantRunner = ctx.db.unsafeRaw(ADD_MEMBERSHIP_INVITATION_TENANT_REASON);
+        const membershipRow = await fetchOne(invitationTenantRunner, tenantMembershipsTable, {
           userId: event.user.id,
           tenantId: invitationTenantId,
         });
         const alreadyMember = membershipRow !== undefined;
 
-        const dbConn = ctx.db.raw;
+        const dbConn = invitationTenantRunner;
 
         if (!alreadyMember) {
           // Membership-Add via seedTenantMembership-helper (event-store-

package/src/auth-email-password/handlers/invite-create.write.ts

@@ -18,7 +18,6 @@
 // invite-create.
 
 import { generateToken } from "@cosmicdrift/kumiko-framework/api";
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
@@ -132,7 +131,7 @@ export function createInviteCreateHandler(opts: InviteCreateOptions) {
       // max. eine Row. Status egal (cancelled/accepted/expired/pending);
       // wir setzen sie auf pending zurück und vergeben einen frischen
       // Token wenn der bisherige nicht mehr lebt.
-      const existing = await fetchOne(ctx.db.raw, tenantInvitationsTable, { tenantId, email });
+      const existing = await ctx.db.fetchOne(tenantInvitationsTable, { tenantId, email });
 
       let invitationId: string;
       let token: string;

package/src/auth-email-password/handlers/invite-signup-complete.write.ts

@@ -77,6 +77,13 @@ const invitationExecutor = createEventStoreExecutor(
   { entityName: "tenant-invitation" },
 );
 
+const INVITE_SIGNUP_COMPLETE_ESCAPE_HATCH_REASON =
+  "reads the pending invitation by id; the invitee is not yet a member of the invitation's tenant. Creates the user and adds the membership and accepts the invitation in the invitation's tenant, before any caller tenant context exists.";
+const READ_PENDING_INVITATION_REASON =
+  "reads the pending invitation by id; the invitee is not yet a member of the invitation's tenant";
+const CREATE_USER_AND_MEMBERSHIP_INVITATION_TENANT_REASON =
+  "creates the user and adds the membership and accepts the invitation in the invitation's tenant, before any caller tenant context exists";
+
 export function createInviteSignupCompleteHandler() {
   return defineWriteHandler<
     "invite-signup-complete",
@@ -87,6 +94,9 @@ export function createInviteSignupCompleteHandler() {
     schema: InviteSignupCompleteSchema,
     access: { roles: ["all"] },
     agent: { expose: false },
+    escapeHatch: {
+      reason: INVITE_SIGNUP_COMPLETE_ESCAPE_HATCH_REASON,
+    },
     handler: async (event, ctx) => {
       if (!ctx.redis) {
         return writeFailure(
@@ -110,9 +120,11 @@ export function createInviteSignupCompleteHandler() {
 
       let committed = false;
       try {
-        const invitation = await fetchOne<InvitationRow>(ctx.db.raw, tenantInvitationsTable, {
-          id: invitationId,
-        });
+        const invitation = await fetchOne<InvitationRow>(
+          ctx.db.unsafeRaw(READ_PENDING_INVITATION_REASON),
+          tenantInvitationsTable,
+          { id: invitationId },
+        );
         if (!invitation || invitation.status !== INVITATION_STATUS.pending)
           return invalidInviteToken();
 
@@ -131,7 +143,7 @@ export function createInviteSignupCompleteHandler() {
         // Password zu setzen für denselben User.
         // Email uniqueness is partial on live rows (framework#2593) — without
         // this filter the lookup can resolve a soft-deleted row.
-        const existingUser = await fetchOne(ctx.db.raw, userTable, {
+        const existingUser = await ctx.db.global(userTable).fetchOne({
           email: invitationEmail,
           isDeleted: false,
         });
@@ -139,9 +151,11 @@ export function createInviteSignupCompleteHandler() {
 
         // User anlegen via seedUserWithPassword (gleiches Pattern wie
         // signup-confirm), emailVerified=true wegen Magic-Link.
-        // @cast-boundary db-runner — TenantDb.raw is DbRunner; seed-helpers
-        // operate on plain drizzle-API which both shapes expose identically.
-        const dbConn = ctx.db.raw as DbConnection;
+        // @cast-boundary db-runner — helpers use only the query API that
+        // DbConnection and DbTx share.
+        const dbConn = ctx.db.unsafeRaw(
+          CREATE_USER_AND_MEMBERSHIP_INVITATION_TENANT_REASON,
+        ) as DbConnection;
         const { id: userId } = await seedUserWithPassword(dbConn, {
           email: invitationEmail,
           password: event.payload.password,

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

@@ -287,7 +287,9 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
       reason:
         "Unauthenticated login has no caller identity yet — it looks up the user row by " +
         "email via ctx.queryAs(SYSTEM, ...) and resolves tenant membership via " +
-        "ctx.resolveActiveMembership before a session exists.",
+        "ctx.resolveActiveMembership before a session exists. It also reads the MFA " +
+        "enrollment of the tenant named in the signed login/setup token, not the guest " +
+        "dispatch tenant, via the mfaStatusChecker callback.",
     },
     description:
       "Signs a user in with email and password, running the lockout, email-verification, account-status, tenant-membership and MFA gates, and answering with a session or with an MFA challenge or setup requirement.",

package/src/auth-email-password/handlers/signup-confirm.write.ts

@@ -60,12 +60,18 @@ export type SignupConfirmData = {
   readonly tenantKey: string;
 };
 
+const SIGNUP_CONFIRM_PROVISION_REASON =
+  "provisions a new tenant, its first user and membership before any tenant context exists";
+
 export function createSignupConfirmHandler() {
   return defineWriteHandler<"signup-confirm", typeof SignupConfirmSchema, SignupConfirmData>({
     name: "signup-confirm",
     schema: SignupConfirmSchema,
     access: { roles: ["all"] },
     agent: { expose: false },
+    escapeHatch: {
+      reason: SIGNUP_CONFIRM_PROVISION_REASON,
+    },
     handler: async (event, ctx) => {
       if (!ctx.redis) {
         return writeFailure(
@@ -90,11 +96,9 @@ export function createSignupConfirmHandler() {
         // Tenant-Key: 2-Wort-Slug aus framework/random, mit DB-Conflict-
         // Check gegen tenants.key. 22.500 Default-Combos + Suffix-
         // Fallback bei Kollision (siehe generateUniqueName).
-        // @cast-boundary db-runner — TenantDb.raw is DbRunner (Connection|Tx);
-        // provisioning helpers operate on plain drizzle-API that both shapes
-        // expose identically. Inside an event-store transaction the cast lands
-        // on the Tx flavor — same drizzle calls, same behavior.
-        const dbConn = ctx.db.raw as DbConnection;
+        // @cast-boundary db-runner — helpers use only the query API that
+        // DbConnection and DbTx share.
+        const dbConn = ctx.db.unsafeRaw(SIGNUP_CONFIRM_PROVISION_REASON) as DbConnection;
 
         const tenantKey = await generateUniqueName({
           isAvailable: async (slug) => {

package/src/auth-mfa/handlers/enable-confirm-preauth.write.ts

@@ -67,7 +67,9 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
     escapeHatch: {
       reason:
         "Pre-auth MFA enrollment step has no session yet — re-checks status via ctx.queryAs(SYSTEM, " +
-        "user:findForAuth) and membership via ctx.resolveActiveMembership for the setup token's user.",
+        "user:findForAuth) and membership via ctx.resolveActiveMembership for the setup token's user. " +
+        "Also reads the MFA enrollment of the tenant named in the signed login/setup token, not the " +
+        "guest dispatch tenant.",
     },
     description:
       "Completes the enrollment that unblocks a sign-in forced into two-factor setup: verifies the code against the pre-auth setup token, stores the factor and derives the session the blocked login never got.",
@@ -125,7 +127,13 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
 
       // "system" mode: no session exists yet, tenantId comes from the
       // verified token, mirroring enable-start-preauth.write.ts.
-      const scopedDb = createTenantDb(ctx.db.raw, tenantId, "system");
+      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",
+        ),
+        tenantId,
+        "system",
+      );
       const scopedUser: SessionUser = { id: userId, tenantId, roles: ["User"] };
       const existing = await findUserMfaRow(scopedDb, scopedUser);
       if (existing) return mfaAlreadyEnabled();

package/src/auth-mfa/handlers/enable-start-preauth.write.ts

@@ -11,6 +11,9 @@ import { buildOtpauthUri } from "../otpauth-uri";
 import { generateRecoveryCodes, hashRecoveryCodes } from "../recovery-codes";
 import { generateTotpSecret } from "../totp";
 
+const ENABLE_START_PREAUTH_TENANT_REASON =
+  "reads the MFA enrollment of the tenant named in the signed login/setup token, not the guest dispatch tenant";
+
 export type EnableStartPreauthOptions = {
   // Verifies the incoming preauthSetupToken — must match login.write.ts's
   // mfaStatusChecker (challengeTokenSecret), NOT setupTokenSecret.
@@ -39,6 +42,9 @@ export function createEnableStartPreauthHandler(opts: EnableStartPreauthOptions)
       "Begins TOTP enrollment for a user whose sign-in was blocked because the tenant requires two-factor authentication, taking identity from the pre-auth token login issued instead of from a session.",
     // Same secret-bearing result as enable-start.
     agent: { expose: false },
+    escapeHatch: {
+      reason: ENABLE_START_PREAUTH_TENANT_REASON,
+    },
     handler: async (event, ctx) => {
       const verified = verifyMfaPreauthSetupToken(
         event.payload.preauthSetupToken,
@@ -53,7 +59,11 @@ export function createEnableStartPreauthHandler(opts: EnableStartPreauthOptions)
       // "system" mode: the guest dispatch identity's own tenantId is
       // meaningless here — the preauthSetupToken is the source of truth
       // for which tenant's row to read, mirroring verify.write.ts.
-      const scopedDb = createTenantDb(ctx.db.raw, tenantId, "system");
+      const scopedDb = createTenantDb(
+        ctx.db.unsafeRaw(ENABLE_START_PREAUTH_TENANT_REASON),
+        tenantId,
+        "system",
+      );
       const scopedUser: SessionUser = { id: userId, tenantId, roles: ["User"] };
       const existing = await findUserMfaRow(scopedDb, scopedUser);
       if (existing) return mfaAlreadyEnabled();

package/src/auth-mfa/handlers/verify.write.ts

@@ -49,7 +49,9 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
     escapeHatch: {
       reason:
         "Pre-auth MFA step has no session yet — re-derives it via ctx.queryAs(SYSTEM, " +
-        "user:findForAuth) and ctx.resolveActiveMembership for the user the challenge token names.",
+        "user:findForAuth) and ctx.resolveActiveMembership for the user the challenge token names. " +
+        "Also reads the MFA enrollment of the tenant named in the signed login/setup token, not the " +
+        "guest dispatch tenant.",
     },
     description:
       "Finishes a two-step sign-in by checking a TOTP or recovery code against the challenge token that login handed back, under a per-account attempt cap, and derives the resulting session.",
@@ -92,7 +94,13 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
       // "system" mode: this handler runs with a guest identity whose own
       // tenantId is meaningless here — the challenge token is the source
       // of truth for which tenant's row to read.
-      const scopedDb = createTenantDb(ctx.db.raw, tenantId, "system");
+      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",
+        ),
+        tenantId,
+        "system",
+      );
       const scopedUser: SessionUser = { id: userId, tenantId, roles: ["User"] };
       const row = await findUserMfaRow(scopedDb, scopedUser);
       // MFA got disabled between login and verify (race, or a stale

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

@@ -21,7 +21,11 @@ export type MfaCodeVerifier = (
 // codes exist for.
 export function createMfaCodeVerifier(): MfaCodeVerifier {
   return async (ctx, userId, tenantId, code) => {
-    const scopedDb = createTenantDb(ctx.db.raw, tenantId, "system");
+    const scopedDb = createTenantDb(
+      ctx.db.unsafeRaw("reads the MFA enrollment of the user being re-authenticated"),
+      tenantId,
+      "system",
+    );
     const row = await findUserMfaRow(scopedDb, { id: userId, tenantId, roles: [] });
     if (!row) return { enrolled: false, ok: false };
     // Fail closed without ctx.redis, matching disable.write.ts/verify.write.ts —

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

@@ -38,7 +38,13 @@ export function createMfaStatusChecker(opts: {
   readonly challengeTokenSecret: string;
 }): MfaStatusChecker {
   return async (ctx, userId, tenantId, roles) => {
-    const scopedDb = createTenantDb(ctx.db.raw, tenantId, "system");
+    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",
+      ),
+      tenantId,
+      "system",
+    );
     const scopedUser: SessionUser = { id: userId, tenantId, roles: ["User"] };
     const row = await findUserMfaRow(scopedDb, scopedUser);
 

package/src/billing-foundation/handlers/list-subscriptions.query.ts

@@ -2,8 +2,6 @@
 // `read_subscriptions`-projection. Tenant-Admins lesen ihre eigene
 // subscription via getSubscriptionForTenant-helper (= ctx.db ist
 // tenant-scoped, gibt automatisch nur die row des Callers zurück).
-
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   configuredPiiSubjectKms,
   decryptPiiFieldValues,
@@ -22,7 +20,7 @@ export const listSubscriptionsQuery: QueryHandlerDef = {
   schema: listSchema,
   access: { roles: ["SystemAdmin", "TenantAdmin"] },
   handler: async (_query, ctx) => {
-    const rows = await selectMany(ctx.db.raw, subscriptionsProjectionTable, {
+    const rows = await ctx.db.selectMany(subscriptionsProjectionTable, {
       tenantId: ctx.user.tenantId,
     });
     const piiKms = configuredPiiSubjectKms();

package/src/cap-counter/stock-cap-guard.ts

@@ -55,10 +55,15 @@ export function createStockCapGuard<TCaps>(
   }
 
   function withStockCap(handler: WriteHandlerDef, spec: StockCapSpec<TCaps>): WriteHandlerDef {
+    const capReason =
+      "counts the caller tenant's rows and resolves its tier caps through the raw-runner cap API";
     return {
       ...handler,
+      escapeHatch: handler.escapeHatch
+        ? { reason: `${handler.escapeHatch.reason} ${capReason}` }
+        : { reason: capReason },
       handler: async (event, ctx) => {
-        const failure = await checkStockCap(ctx.db.raw, event.user.tenantId, spec);
+        const failure = await checkStockCap(ctx.db.unsafeRaw(capReason), event.user.tenantId, spec);
         return failure ?? handler.handler(event, ctx);
       },
     };

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

@@ -230,25 +230,28 @@ 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.raw, {
-    aggregateId: generateId(),
-    aggregateType: CRYPTO_SHREDDING_AGGREGATE_TYPE,
-    // MUST be event.user.tenantId (the prober's own tenant), never
-    // SYSTEM_TENANT_ID — .raw bypasses TenantDb's scoping wrapper, so this
-    // is the only thing keeping the denial event out of the foreign
-    // subject's tenant (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(
+    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 } : {}),
+      },
     },
-  });
+  );
   return null;
 }
 
@@ -270,6 +273,13 @@ export const forgetSubjectWrite = defineWriteHandler({
   // Erasing the subject key is irreversible: there is no undo, so an agent must
   // not be able to reach it at all.
   agent: { expose: false },
+  escapeHatch: {
+    reason:
+      "denial audit append names the prober's own tenant stream on the outside-transaction db; " +
+      "the tenant-scope check runs against the subject's tenant, not necessarily the caller's; " +
+      "the blind-index sweep and search purge address the subject across tenants; the user " +
+      "lifecycle update and PAT revoke run on the SYSTEM user stream.",
+  },
   handler: async (event, ctx) => {
     const kms = configuredPiiSubjectKms();
     if (!kms) {
@@ -292,7 +302,9 @@ export const forgetSubjectWrite = defineWriteHandler({
     const subjectKey = subjectIdToKey(subject);
 
     const tenantScopeDenial = await resolveTenantScopeDenial(
-      ctx.db.raw,
+      ctx.db.unsafeRaw(
+        "tenant-scope check runs against the subject's tenant, not necessarily the caller's",
+      ),
       ctx.registry.features,
       event.user,
       raw,
@@ -337,17 +349,18 @@ export const forgetSubjectWrite = defineWriteHandler({
       eraseReason: event.payload.reason,
     });
 
-    // Blind-index sweep (#818): null the erased subject's bidx columns now —
-    // otherwise the deterministic HMAC stays equality-matchable until the next
-    // rebuild. Deliberately ctx.db.raw: the ciphertext prefix addresses the
-    // subject across tenants.
-    await nullBlindIndexesForSubject(ctx.db.raw, ctx.registry.features, subjectKey);
+    // Blind-index sweep (#818): nulls bidx columns now so the deterministic
+    // HMAC doesn't stay equality-matchable; raw because the ciphertext prefix addresses the subject across tenants.
+    const crossTenantSubjectRunner = ctx.db.unsafeRaw(
+      "blind-index sweep and search purge address the subject across tenants",
+    );
+    await nullBlindIndexesForSubject(crossTenantSubjectRunner, ctx.registry.features, subjectKey);
 
     // Derived search index still holds plaintext (#1610) — purge next to the
     // blind-index sweep. No adapter → no-op (apps without search).
     if (ctx.searchAdapter) {
       await purgeSearchDocumentsForSubject(
-        ctx.db.raw,
+        crossTenantSubjectRunner,
         ctx.registry.features,
         ctx.searchAdapter,
         subjectKey,
@@ -376,9 +389,12 @@ export const forgetSubjectWrite = defineWriteHandler({
     // update is best-effort for real users.
     if (raw.kind === "user" && ctx.registry.features.has("user")) {
       try {
-        await updateUserLifecycle(ctx.db.raw, raw.userId, { status: USER_STATUS.Deleted });
+        const userLifecycleRunner = ctx.db.unsafeRaw(
+          "user lifecycle update and PAT revoke run on the SYSTEM user stream",
+        );
+        await updateUserLifecycle(userLifecycleRunner, raw.userId, { status: USER_STATUS.Deleted });
         if (ctx.registry.features.has("personal-access-tokens")) {
-          await revokeAllPatTokensForUser(ctx.db.raw, raw.userId);
+          await revokeAllPatTokensForUser(userLifecycleRunner, raw.userId);
         }
       } catch {
         // User row may not exist (e.g. email subscribers with user-style

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

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

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

@@ -8,7 +8,9 @@ export async function selectSerializedFieldDefinition(
   fieldKey: string,
 ): Promise<unknown | null> {
   const rows = await unsafeReadRetrying(
-    db.raw,
+    db.unsafeRaw(
+      "reads custom field definitions with an explicit tenant_id = caller tenant via raw SQL with read retry",
+    ),
     "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

@@ -5,7 +5,9 @@ export async function countTenantFieldDefinitions(db: TenantDb, tenantId: string
   // 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.raw,
+    db.unsafeRaw(
+      "counts custom field definitions with an explicit tenant_id = caller tenant via raw SQL with read retry",
+    ),
     "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

@@ -16,6 +16,9 @@ export const clearCustomFieldPayloadSchema = z.object({
 });
 export type ClearCustomFieldPayload = z.infer<typeof clearCustomFieldPayloadSchema>;
 
+const CLEAR_CUSTOM_FIELD_REASON =
+  "reads custom field definitions with an explicit tenant_id = caller tenant via raw SQL with read retry";
+
 // clear-custom-field — entfernt einen Custom-Field-Wert von einer host-
 // entity. Emittiert customField.cleared-Event; MSP entfernt key aus
 // jsonb-column (key-removal, nicht null-set).
@@ -29,6 +32,9 @@ export const clearCustomFieldHandler: WriteHandlerDef = {
   access: { roles: DEFAULT_VALUE_WRITE_ROLES },
   description:
     "Removes the stored value of one custom field from a single host entity row after re-checking that field's per-field write roles; use it to blank a field the user emptied instead of writing a null value.",
+  escapeHatch: {
+    reason: CLEAR_CUSTOM_FIELD_REASON,
+  },
   handler: async (event, ctx) => {
     const payload = event.payload as ClearCustomFieldPayload; // @cast-boundary engine-payload
 

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

@@ -45,6 +45,9 @@ export interface DefineTenantFieldOptions {
   readonly roles?: readonly string[];
 }
 
+const DEFINE_TENANT_FIELD_REASON =
+  "counts custom field definitions with an explicit tenant_id = caller tenant via raw SQL with read retry";
+
 export function createDefineTenantFieldHandler(
   opts: DefineTenantFieldOptions = {},
 ): WriteHandlerDef {
@@ -55,6 +58,9 @@ export function createDefineTenantFieldHandler(
     access: { roles: opts.roles ?? DEFAULT_FIELD_DEFINITION_WRITE_ROLES },
     description:
       "Creates a custom-field definition owned by the caller's own tenant on the named entity, rejecting the write once the tenant's definition quota is reached; use it when one tenant needs an extra field the other tenants must not see.",
+    escapeHatch: {
+      reason: DEFINE_TENANT_FIELD_REASON,
+    },
     handler: async (event, ctx) => {
       const payload = event.payload as DefineFieldPayload; // @cast-boundary engine-payload
       const tenantId = event.user.tenantId;

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

@@ -22,6 +22,9 @@ export const setCustomFieldPayloadSchema = z.object({
 });
 export type SetCustomFieldPayload = z.infer<typeof setCustomFieldPayloadSchema>;
 
+const SET_CUSTOM_FIELD_REASON =
+  "reads custom field definitions with an explicit tenant_id = caller tenant via raw SQL with read retry";
+
 // set-custom-field — schreibt einen Custom-Field-Wert auf eine host-entity.
 //
 // **ES-Option-B**: emittiert customField.set-Event auf dem host-aggregate
@@ -52,6 +55,9 @@ export const setCustomFieldHandler: WriteHandlerDef = {
   access: { roles: DEFAULT_VALUE_WRITE_ROLES },
   description:
     "Stores one custom-field value on a single host entity row after validating it against the field definition's declared type and per-field write roles; use it to save what a user entered into a custom field.",
+  escapeHatch: {
+    reason: SET_CUSTOM_FIELD_REASON,
+  },
   handler: async (event, ctx) => {
     const payload = event.payload as SetCustomFieldPayload; // @cast-boundary engine-payload