@cosmicdrift/kumiko-bundled-features 0.280.0 → 0.282.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.280.0",
+  "version": "0.282.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.280.0",
-    "@cosmicdrift/kumiko-framework": "0.280.0",
-    "@cosmicdrift/kumiko-headless": "0.280.0",
-    "@cosmicdrift/kumiko-renderer": "0.280.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.280.0",
-    "@cosmicdrift/kumiko-types": "0.280.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.282.0",
+    "@cosmicdrift/kumiko-framework": "0.282.0",
+    "@cosmicdrift/kumiko-headless": "0.282.0",
+    "@cosmicdrift/kumiko-renderer": "0.282.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.282.0",
+    "@cosmicdrift/kumiko-types": "0.282.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.280.0",
-    "@cosmicdrift/kumiko-locale-es": "0.280.0"
+    "@cosmicdrift/kumiko-locale-de": "0.282.0",
+    "@cosmicdrift/kumiko-locale-es": "0.282.0"
   }
 }

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/cap-overview/__tests__/caps-usage-escape-hatch.integration.test.ts

@@ -0,0 +1,111 @@
+// fw#2971 — withUnsafeRawGrant was un-exported, so an app-owned CapSpec.usage()
+// provider's db.unsafeRaw() call was rejected even though caps:usage itself
+// runs with r.systemScope(). caps-usage.query.ts now declares its own
+// escapeHatch so those providers keep working. This proves the grant
+// actually reaches a cap provider doing a real raw-SQL SUM aggregate (the
+// shape a typed TenantDb helper like count() can't express) end to end
+// through the real caps:usage HTTP handler.
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { configurePiiSubjectKms, InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/db";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { billingFoundationFeature } from "../../billing-foundation";
+import {
+  createComplianceProfilesFeature,
+  tenantComplianceProfileEntity,
+} from "../../compliance-profiles";
+import { createConfigFeature } from "../../config";
+import { createTenantFeature } from "../../tenant/feature";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { seedTenant } from "../../tenant/seeding";
+import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
+import { TierEngineHandlers, tierAssignmentEntity, tierEngineFeature } from "../../tier-engine";
+import { CapOverviewQueries } from "../constants";
+import { createCapOverviewFeature } from "../feature";
+import type { CapSpec } from "../types";
+
+const RAW_USAGE_REASON =
+  "test: cap provider sums cap_overview_raw_usage_probe via raw SQL (fw#2971 regression)";
+const TENANT_A = testTenantId(9101);
+
+const rawSqlSumCap: CapSpec = {
+  id: "raw-sql-sum",
+  label: "test.cap.rawSqlSum",
+  limit: () => 1000,
+  usage: async (db, tenantId) => {
+    // @cast-boundary db-operator — unsafeRaw's DbRunner narrows to
+    // DbConnection|DbTx; this call site only ever runs outside a tx.
+    const raw = asRawClient(db.unsafeRaw(RAW_USAGE_REASON) as DbConnection);
+    const rows = await raw.unsafe<{ total: number }>(
+      "SELECT COALESCE(SUM(amount), 0)::int AS total FROM cap_overview_raw_usage_probe WHERE tenant_id = $1",
+      [tenantId],
+    );
+    return rows[0]?.total ?? 0;
+  },
+};
+
+let stack: TestStack;
+let db: DbConnection;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createTenantFeature(),
+      createComplianceProfilesFeature(),
+      createTenantLifecycleFeature(),
+      billingFoundationFeature,
+      tierEngineFeature,
+      createCapOverviewFeature({ caps: [rawSqlSumCap] }),
+    ],
+  });
+  db = stack.db;
+  await createEventsTable(db);
+  await unsafeCreateEntityTable(db, tenantEntity);
+  await unsafeCreateEntityTable(db, tierAssignmentEntity);
+  await unsafeCreateEntityTable(db, tenantComplianceProfileEntity);
+  configurePiiSubjectKms(new InMemoryKmsAdapter());
+
+  await asRawClient(db).unsafe(`
+    CREATE TABLE IF NOT EXISTS cap_overview_raw_usage_probe (
+      tenant_id text NOT NULL,
+      amount int NOT NULL
+    )
+  `);
+  await asRawClient(db).unsafe(
+    "INSERT INTO cap_overview_raw_usage_probe (tenant_id, amount) VALUES ($1, $2), ($1, $3)",
+    [TENANT_A, 30, 12],
+  );
+
+  await seedTenant(db, { id: TENANT_A, key: `cap-overview-raw-${TENANT_A}`, name: "Tenant Raw" });
+  const ownerA = createTestUser({
+    id: 91011,
+    tenantId: TENANT_A,
+    roles: ["TenantAdmin", "SystemAdmin"],
+  });
+  await stack.http.writeOk(TierEngineHandlers.create, { tier: "pro" }, ownerA);
+});
+
+afterAll(async () => {
+  await asRawClient(db).unsafe("DROP TABLE IF EXISTS cap_overview_raw_usage_probe");
+  await stack.cleanup();
+});
+
+describe("caps:usage's own escapeHatch grants a cap provider raw SQL", () => {
+  test("a cap provider's db.unsafeRaw() SUM aggregate runs successfully through caps:usage", async () => {
+    const memberA = createTestUser({ id: 91012, tenantId: TENANT_A, roles: ["User"] });
+    const result = await stack.http.queryOk<{
+      rows: readonly { id: string; used: number | null }[];
+    }>(CapOverviewQueries.capsUsage, {}, memberA);
+    const row = result.rows.find((r) => r.id === rawSqlSumCap.id);
+    expect(row?.used).toBe(42);
+  });
+});

package/src/cap-overview/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.282.0",
+    "type": "fix",
+    "title": "caps:usage declares escapeHatch again so raw-SQL cap providers work",
+    "detail": "fw#2971 un-exported withUnsafeRawGrant, the mechanism app-owned CapSpec.usage() providers used (via caps:usage's system-mode db) to run raw SQL for aggregates TenantDb has no typed helper for (a SUM, unlike the COUNT(*)-only TenantDb.count() added in fw#2854). caps:usage's own defineQueryHandler(...) call now carries `escapeHatch: { reason: \"...\" }`, restoring the grant through the same mechanism every other handler-owned unsafeRaw use goes through. Cap providers that only need COUNT(*) should migrate to TenantDb.count(table, where) instead — it needs no escapeHatch at all."
+  },
   {
     "version": "0.233.0",
     "type": "improvement",

package/src/cap-overview/handlers/caps-usage.query.ts

@@ -23,6 +23,12 @@ export function createCapsUsageQuery(caps: readonly CapSpec[]): QueryHandlerDefi
       "Returns the calling user's own tenant's configured caps with used amount, tier limit and utilisation fraction; use it to answer how close a tenant is to its quota (only SystemAdmin may target another tenant via tenantId).",
     schema: z.object({ tenantId: z.string().min(1).optional() }),
     access: { roles: MY_CAPS_ACCESS_ROLES },
+    // App-owned CapSpec.usage() providers get this handler's db; a SUM has
+    // no TenantDb helper (count() is COUNT(*)-only), so they need raw SQL.
+    escapeHatch: {
+      reason:
+        "cap-overview:caps:usage — grants app-owned CapSpec.usage() providers raw SQL for aggregates TenantDb has no typed helper for (e.g. a SUM)",
+    },
     handler: async (query, ctx) => {
       if (!ctx.systemDb) {
         throw new InternalError({

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/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/user-data-rights/handlers/confirm-deletion-by-token.write.ts

@@ -1,4 +1,9 @@
-import { defineWriteHandler, type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { DurationSpec } from "@cosmicdrift/kumiko-framework/compliance";
+import {
+  createSystemUser,
+  defineWriteHandler,
+  type HandlerContext,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { USER_STATUS, userTable } from "../../user";
@@ -81,7 +86,19 @@ export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByToken
       );
       if (!verified.ok) return writeFailure(invalidToken());
 
-      const res = await startDeletionGracePeriod(ctx, verified.userId, event.user.tenantId);
+      // @cast-boundary engine-payload — queryAs returns unknown, narrowed to
+      // the compliance-profile shape.
+      const profile = (await ctx.queryAs(
+        createSystemUser(event.user.tenantId),
+        "compliance-profiles:query:for-tenant",
+        {},
+      )) as { profile: { userRights: { gracePeriod: DurationSpec } } };
+      const res = await startDeletionGracePeriod(
+        ctx,
+        verified.userId,
+        profile.profile.userRights.gracePeriod,
+        ctx.db.unsafeRaw("appends the user lifecycle event on the SYSTEM_TENANT_ID user stream"),
+      );
       if (!res.ok) {
         // Generischer 422 statt res.error: dieser Endpoint ist anonym-öffentlich,
         // res.error trägt den konkreten User-Status (currentStatus aus

package/src/user-data-rights/handlers/deletion-grace-period.ts

@@ -1,5 +1,6 @@
 import { addDurationSpec, type DurationSpec } from "@cosmicdrift/kumiko-framework/compliance";
-import { createSystemUser, type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { decryptStoredPii } from "../../shared";
@@ -17,19 +18,23 @@ export type StartGracePeriodResult =
     }
   | { readonly ok: false; readonly error: UnprocessableError };
 
-// Flippt einen aktiven User auf DeletionRequested + setzt gracePeriodEnd aus
-// dem Compliance-Profile. Geteilt zwischen dem authentifizierten
-// request-deletion-Pfad (event.user) und dem anonymen confirm-by-token-Pfad
-// (userId aus verifiziertem Token) — eine Quelle für die Grace-Period-Logik.
+// Flips an active user to DeletionRequested and sets gracePeriodEnd from the
+// caller-supplied grace period. Shared between the authenticated
+// request-deletion path (event.user) and the anonymous confirm-by-token path
+// (userId from a verified token) — one source for the grace-period logic.
 //
-// `complianceTenantId`: Tenant dessen Compliance-Profile die Grace-Dauer
-// liefert. Authenticated = aktiver Tenant des Users; anonym = Dispatch-Tenant
-// der Apex-Surface. Die User-Row ist tenant-agnostisch (Account-weite
-// Löschung), nur die Grace-Dauer ist tenant-konfiguriert.
+// The user row is tenant-agnostic (account-wide deletion), so it is read via
+// ctx.db.global(userTable); only the grace period duration is tenant-configured.
+//
+// `gracePeriod` and `lifecycleRunner` are resolved by the caller: both
+// require an escalation (reading the tenant compliance profile, appending to
+// the SYSTEM_TENANT_ID user stream) that only the declaring handler's
+// escapeHatch covers.
 export async function startDeletionGracePeriod(
   ctx: HandlerContext,
   userId: string,
-  complianceTenantId: string,
+  gracePeriod: DurationSpec,
+  lifecycleRunner: DbRunner,
 ): Promise<StartGracePeriodResult> {
   const userRow = await ctx.db
     .global(userTable)
@@ -51,26 +56,13 @@ export async function startDeletionGracePeriod(
     };
   }
 
-  // @cast-boundary engine-payload — queryAs liefert unknown, narrow auf den
-  // effektiven Profile-Shape (siehe request-deletion-Original).
-  const profile = (await ctx.queryAs(
-    createSystemUser(complianceTenantId),
-    "compliance-profiles:query:for-tenant",
-    {},
-  )) as { profile: { userRights: { gracePeriod: DurationSpec } } };
-
-  const gracePeriod = profile.profile.userRights.gracePeriod;
   const T = getTemporal();
   const gracePeriodEnd = addDurationSpec(T.Now.instant(), gracePeriod);
 
-  await updateUserLifecycle(
-    ctx.db.unsafeRaw("appends the user lifecycle event on the SYSTEM_TENANT_ID user stream"),
-    userId,
-    {
-      status: USER_STATUS.DeletionRequested,
-      gracePeriodEnd,
-    },
-  );
+  await updateUserLifecycle(lifecycleRunner, userId, {
+    status: USER_STATUS.DeletionRequested,
+    gracePeriodEnd,
+  });
 
   return {
     ok: true,

package/src/user-data-rights/handlers/request-deletion.write.ts

@@ -1,5 +1,6 @@
 import { createTransportForTenant } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
-import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import type { DurationSpec } from "@cosmicdrift/kumiko-framework/compliance";
+import { createSystemUser, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { USER_STATUS } from "../../user";
@@ -61,7 +62,19 @@ export function createRequestDeletionHandler(opts: RequestDeletionOptions = {})
       "Starts the GDPR Art. 17 deletion of the calling user's own account by arming the grace period from the tenant compliance profile and mailing a confirmation, after which only cancel-deletion can stop the erasure.",
     agent: { risk: "high" },
     handler: async (event, ctx) => {
-      const res = await startDeletionGracePeriod(ctx, event.user.id, event.user.tenantId);
+      // @cast-boundary engine-payload — queryAs returns unknown, narrowed to
+      // the compliance-profile shape.
+      const profile = (await ctx.queryAs(
+        createSystemUser(event.user.tenantId),
+        "compliance-profiles:query:for-tenant",
+        {},
+      )) as { profile: { userRights: { gracePeriod: DurationSpec } } };
+      const res = await startDeletionGracePeriod(
+        ctx,
+        event.user.id,
+        profile.profile.userRights.gracePeriod,
+        ctx.db.unsafeRaw("appends the user lifecycle event on the SYSTEM_TENANT_ID user stream"),
+      );
       if (!res.ok) return writeFailure(res.error);
       const { gracePeriodEnd, userEmail, userLocale } = res;