@cosmicdrift/kumiko-bundled-features 0.265.0 → 0.268.0

package/src/user-data-rights/handlers/download-by-job.query.ts

@@ -40,6 +40,9 @@ import { EXPORT_JOB_STATUS, exportJobsTable } from "../schema/export-job";
 
 const SIGNED_URL_TTL_SECONDS = 300; // 5 min — matched download-by-token
 
+const DOWNLOAD_BY_JOB_REASON =
+  "export jobs, their download tokens and audit rows are keyed by job id / userId across the user's tenant memberships, not the caller's current tenant";
+
 interface TokenRow {
   readonly id: string;
   readonly version: number;
@@ -63,6 +66,9 @@ export const downloadByJobQuery = defineQueryHandler({
   access: { openToAll: true }, // openToAll = auth-required, kein anonymous
   description:
     "Returns a short-lived signed download URL for the calling user's own finished data-export job named by job id, backing the download button in the privacy center once export-status reports the job done.",
+  escapeHatch: {
+    reason: DOWNLOAD_BY_JOB_REASON,
+  },
   handler: async (query, ctx) => {
     const T = getTemporal();
     const now = T.Now.instant();
@@ -74,15 +80,14 @@ export const downloadByJobQuery = defineQueryHandler({
     // Wert (603/2).
     const auditIp = requestContext.get()?.ip ?? null;
     const auditUa = requestContext.get()?.userAgent ?? null;
+    const runner = ctx.db.unsafeRaw(DOWNLOAD_BY_JOB_REASON);
 
     // Step 1-2: job-lookup + cross-user-isolation
-    // ctx.db.raw weil tenant-agnostisch — Alice in Tenant B sucht den
-    // aus Tenant A erstellten Job.
-    const jobRow = await fetchOne<JobRow>(ctx.db.raw, exportJobsTable, { id: jobId });
+    const jobRow = await fetchOne<JobRow>(runner, exportJobsTable, { id: jobId });
 
     if (!jobRow || jobRow.userId !== userId) {
       await recordInvalidAttempt({
-        db: ctx.db.raw as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
+        db: runner,
         tenantId,
         now,
         result: "notFound",
@@ -100,7 +105,7 @@ export const downloadByJobQuery = defineQueryHandler({
 
     if (jobRow.status !== EXPORT_JOB_STATUS.Done) {
       await recordInvalidAttempt({
-        db: ctx.db.raw as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
+        db: runner,
         tenantId,
         now,
         result: "failed",
@@ -117,7 +122,7 @@ export const downloadByJobQuery = defineQueryHandler({
     }
     if (!jobRow.downloadStorageKey) {
       await recordInvalidAttempt({
-        db: ctx.db.raw as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
+        db: runner,
         tenantId,
         now,
         result: "expired",
@@ -140,13 +145,15 @@ export const downloadByJobQuery = defineQueryHandler({
       registry: ctx.registry,
       configResolver: ctx.configResolver,
       secrets: ctx.secrets,
-      db: ctx.db.raw as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
+      // @cast-boundary db-runner — helpers use only the query API that
+      // DbConnection and DbTx share.
+      db: runner as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
       userId: SYSTEM_USER_ID,
       handlerName: "user-data-rights:query:download-by-job",
     })(jobRow.requestedFromTenantId as TenantId); // @cast-boundary engine-payload: TenantId brand
     if (!provider.getSignedUrl) {
       await recordInvalidAttempt({
-        db: ctx.db.raw as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
+        db: runner,
         tenantId,
         now,
         result: "signedUrlNotSupported",
@@ -177,13 +184,13 @@ export const downloadByJobQuery = defineQueryHandler({
     // den plain-Token, aber wir wollen den useCount inkrementieren
     // damit die Audit-Felder konsistent sind (UI-clicks zaehlen auch
     // als Use). Lookup via jobId — UNIQUE-Index garantiert max 1 Row.
-    const tokenRow = await fetchOne<TokenRow>(ctx.db.raw, exportDownloadTokensTable, {
+    const tokenRow = await fetchOne<TokenRow>(runner, exportDownloadTokensTable, {
       jobId,
     });
 
     if (tokenRow) {
       await recordDownloadUse({
-        db: ctx.db.raw as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
+        db: runner,
         tokenId: tokenRow.id,
         tokenVersion: tokenRow.version,
         tokenUseCount: tokenRow.useCount ?? 0,

package/src/user-data-rights/handlers/download-by-token.query.ts

@@ -45,6 +45,9 @@ type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 
 const SIGNED_URL_TTL_SECONDS = 300; // 5 min — kurz genug fuer Replay-Schutz, lang genug fuer slow connections
 
+const DOWNLOAD_BY_TOKEN_REASON =
+  "the download token, its job and audit rows are keyed by token hash / job id, not the caller's tenant — the anonymous magic-link path has no tenant context at all";
+
 interface TokenRow {
   readonly id: string;
   readonly version: number;
@@ -82,15 +85,17 @@ export const downloadByTokenQuery = defineQueryHandler({
   // Connection-Abbruch); blockiert automatisierte Probing-Loops.
   // Memory `feedback_security_default_on`.
   rateLimit: { per: "ip", limit: 30, windowSeconds: 60 },
+  escapeHatch: {
+    reason: DOWNLOAD_BY_TOKEN_REASON,
+  },
   handler: async (query, ctx) => {
     const T = getTemporal();
     const now = T.Now.instant();
+    const runner = ctx.db.unsafeRaw(DOWNLOAD_BY_TOKEN_REASON);
 
     // Step 1: hash + lookup
     const hash = await hashDownloadToken(query.payload.token);
-    // ctx.db.raw weil Token+Job tenant-agnostisch — anonymous-pfad hat
-    // keinen tenant-context im query.user.
-    const tokenRow = await fetchOne<TokenRow>(ctx.db.raw, exportDownloadTokensTable, {
+    const tokenRow = await fetchOne<TokenRow>(runner, exportDownloadTokensTable, {
       tokenHash: hash,
     });
 
@@ -118,13 +123,15 @@ export const downloadByTokenQuery = defineQueryHandler({
       // tenantId unbekannt. Wir laden den Job hier noch fuer Audit-Context
       // (best-effort — wenn Job auch fehlt, audit-skip ist akzeptabel).
       const jobForAudit = await fetchOne<{ requestedFromTenantId: string }>(
-        ctx.db.raw,
+        runner,
         exportJobsTable,
-        { id: tokenRow.jobId },
+        {
+          id: tokenRow.jobId,
+        },
       );
       if (jobForAudit) {
         await recordInvalidAttempt({
-          db: ctx.db.raw as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
+          db: runner,
           tenantId: jobForAudit.requestedFromTenantId,
           now,
           result: "expired",
@@ -142,7 +149,7 @@ export const downloadByTokenQuery = defineQueryHandler({
     }
 
     // Step 3-4: job-checks
-    const jobRow = await fetchOne<JobRow>(ctx.db.raw, exportJobsTable, {
+    const jobRow = await fetchOne<JobRow>(runner, exportJobsTable, {
       id: tokenRow.jobId,
     });
 
@@ -153,7 +160,7 @@ export const downloadByTokenQuery = defineQueryHandler({
     }
     if (jobRow.status !== EXPORT_JOB_STATUS.Done) {
       await recordInvalidAttempt({
-        db: ctx.db.raw as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
+        db: runner,
         tenantId: jobRow.requestedFromTenantId,
         now,
         result: "failed",
@@ -170,7 +177,7 @@ export const downloadByTokenQuery = defineQueryHandler({
     }
     if (!jobRow.downloadStorageKey) {
       await recordInvalidAttempt({
-        db: ctx.db.raw as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
+        db: runner,
         tenantId: jobRow.requestedFromTenantId,
         now,
         result: "expired",
@@ -193,13 +200,15 @@ export const downloadByTokenQuery = defineQueryHandler({
       registry: ctx.registry,
       configResolver: ctx.configResolver,
       secrets: ctx.secrets,
-      db: ctx.db.raw as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
+      // @cast-boundary db-runner — helpers use only the query API that
+      // DbConnection and DbTx share.
+      db: runner as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
       userId: SYSTEM_USER_ID,
       handlerName: "user-data-rights:query:download-by-token",
     })(jobRow.requestedFromTenantId as TenantId); // @cast-boundary engine-payload: TenantId brand
     if (!provider.getSignedUrl) {
       await recordInvalidAttempt({
-        db: ctx.db.raw as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
+        db: runner,
         tenantId: jobRow.requestedFromTenantId,
         now,
         result: "signedUrlNotSupported",
@@ -230,7 +239,7 @@ export const downloadByTokenQuery = defineQueryHandler({
     // Wrapper (trusted-source). Direct-API-caller koennen luegen, aber
     // Audit ist nicht security-relevant.
     await recordDownloadUse({
-      db: ctx.db.raw as import("@cosmicdrift/kumiko-types/db-connection").DbConnection,
+      db: runner,
       tokenId: tokenRow.id,
       tokenVersion: tokenRow.version,
       tokenUseCount: tokenRow.useCount ?? 0,

package/src/user-data-rights/handlers/export-status.query.ts

@@ -5,7 +5,7 @@
 //
 // **Cross-User-Isolation:** Filter ist `userId === query.user.id` — kein
 // User kann fremde Job-Status sehen, auch nicht via ID-Guess. Pre-Check
-// nutzt ctx.db.raw weil ExportJob tenant-agnostisch ist (Plan-Doc-
+// uses ctx.db.unsafeRaw — ExportJob is tenant-agnostic (see plan doc,
 // "Cross-Tenant-Semantik").
 //
 // **Read-Only-Endpoint:** Pollt nur, kein State-Flip. Idempotent + cache-
@@ -19,6 +19,9 @@ import { exportJobsTable } from "../schema/export-job";
 
 type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 
+const EXPORT_STATUS_REASON =
+  "export jobs are keyed by userId across all of the user's tenant memberships, not the caller's current tenant";
+
 type ExportJobRow = {
   readonly id: string;
   readonly status: string;
@@ -35,11 +38,12 @@ export const exportStatusQuery = defineQueryHandler({
   access: { openToAll: true },
   description:
     "Returns the calling user's own most recent data-export job with its status, expiry and error, or hasJob false, for polling after a request-export while the job is still running.",
+  escapeHatch: {
+    reason: EXPORT_STATUS_REASON,
+  },
   handler: async (query, ctx) => {
-    // ctx.db.raw weil tenant-agnostisch — ein User der aus Tenant B
-    // pollt, sieht den aus Tenant A erstellten Job.
     const rows = await selectMany<ExportJobRow>(
-      ctx.db.raw,
+      ctx.db.unsafeRaw(EXPORT_STATUS_REASON),
       exportJobsTable,
       { userId: query.user.id },
       { limit: 1, orderBy: { col: "requestedAt", direction: "desc" } },

package/src/user-data-rights/handlers/lift-restriction.write.ts

@@ -1,4 +1,3 @@
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
@@ -6,6 +5,13 @@ import { USER_STATUS, userTable } from "../../user";
 import { denyIfTargetOutsideAdminTenant } from "../lib/deny-if-target-outside-admin-tenant";
 import { updateUserLifecycle } from "../lib/update-user-lifecycle";
 
+const LIFT_RESTRICTION_ESCAPE_HATCH_REASON =
+  "checks the target user's membership in the admin's tenant and appends the user lifecycle status change on the SYSTEM_TENANT_ID user stream, both via DbRunner helpers outside the admin's own tenant scope.";
+const CHECK_TARGET_MEMBERSHIP_REASON =
+  "checks the target user's membership in the admin's tenant via the DbRunner helper";
+const APPEND_LIFECYCLE_EVENT_REASON =
+  "appends the user lifecycle event on the SYSTEM_TENANT_ID user stream";
+
 // POST /api/user/lift-restriction (S2.U6) — DSGVO Art. 18 Reverse.
 //
 // Operator-only. A Restricted user's own session is unconditionally
@@ -14,11 +20,8 @@ import { updateUserLifecycle } from "../lib/update-user-lifecycle";
 // endpoint. There is no self-service path today, so lifting a restriction
 // always targets someone else's account by id.
 //
-// Tenant scope: `access.admin` includes TenantAdmin, which is tenant-
-// scoped even though the User-entity lookup below uses `ctx.db.raw`
-// (bypasses the auto-tenant-filter, same as restrict-account.write.ts —
-// User status is intentionally global, see user-data-rights.md
-// "Cross-Tenant-Semantik"). Without a membership check, a TenantAdmin
+// Tenant scope: `access.admin` includes TenantAdmin (tenant-scoped) even
+// though the User-entity is global — see user-data-rights.md "Cross-Tenant-Semantik". Without a membership check, a TenantAdmin
 // from tenant A could unrestrict/reactivate a user who has never been a
 // member of tenant A. Only SystemAdmin (platform-wide) skips the check;
 // the target must have a membership row in the acting admin's
@@ -35,13 +38,20 @@ export const liftRestrictionWrite = defineWriteHandler({
   access: { roles: access.admin },
   description:
     "Lifts a GDPR Art. 18 processing restriction on the named user and returns the account to active; operator-only, because a restricted user's own session is rejected and cannot reach this endpoint.",
+  escapeHatch: {
+    reason: LIFT_RESTRICTION_ESCAPE_HATCH_REASON,
+  },
   handler: async (event, ctx) => {
     const targetUserId = event.payload.userId;
 
-    const outside = await denyIfTargetOutsideAdminTenant(ctx.db.raw, event.user, targetUserId);
+    const outside = await denyIfTargetOutsideAdminTenant(
+      ctx.db.unsafeRaw(CHECK_TARGET_MEMBERSHIP_REASON),
+      event.user,
+      targetUserId,
+    );
     if (outside) return outside;
 
-    const userRow = await fetchOne<{ status: string }>(ctx.db.raw, userTable, {
+    const userRow = await ctx.db.global(userTable).fetchOne<{ status: string }>({
       id: targetUserId,
     });
 
@@ -62,7 +72,9 @@ export const liftRestrictionWrite = defineWriteHandler({
       );
     }
 
-    await updateUserLifecycle(ctx.db.raw, targetUserId, { status: USER_STATUS.Active });
+    await updateUserLifecycle(ctx.db.unsafeRaw(APPEND_LIFECYCLE_EVENT_REASON), targetUserId, {
+      status: USER_STATUS.Active,
+    });
 
     return {
       isSuccess: true as const,

package/src/user-data-rights/handlers/my-audit-log.query.ts

@@ -10,6 +10,9 @@ import { z } from "zod";
 // auf account-weite Sicht ueber alle Memberships — analog Forget-Pfad.
 const MAX_LIMIT = 100;
 
+const MY_AUDIT_LOG_REASON =
+  "reads the caller's own events across all tenant memberships, bounded by createdBy = caller";
+
 export const myAuditLogQuery = defineQueryHandler({
   name: "my-audit-log",
   schema: z
@@ -28,12 +31,12 @@ export const myAuditLogQuery = defineQueryHandler({
   access: { openToAll: true },
   description:
     "Returns the calling user's own event-store entries across all their tenant memberships, paged and filterable by aggregate type, event type and time range, for the GDPR Art. 15 self-disclosure; it can never read another user's history.",
+  escapeHatch: {
+    reason: MY_AUDIT_LOG_REASON,
+  },
   handler: async (query, ctx) => {
     const p = query.payload;
 
-    // ctx.db.raw weil events-table tenantId-Spalte hat und TenantDb
-    // sonst auto-filtert auf currentTenant. Account-weite Sicht ist
-    // hier explizit gewollt; Sicherung erfolgt via createdBy-Filter.
     const where: WhereObject = { createdBy: query.user.id };
     if (p.aggregateType) where["aggregateType"] = p.aggregateType;
     if (p.eventType) where["type"] = p.eventType;
@@ -53,7 +56,7 @@ export const myAuditLogQuery = defineQueryHandler({
       type: string;
       payload: Record<string, unknown>;
       created_at: unknown;
-    }>(ctx.db.raw, eventsTable, where, {
+    }>(ctx.db.unsafeRaw(MY_AUDIT_LOG_REASON), eventsTable, where, {
       orderBy: { col: "id", direction: "desc" },
       limit: p.limit,
     });

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

@@ -1,4 +1,3 @@
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { USER_STATUS, userTable } from "../../user";
@@ -41,6 +40,9 @@ export type RequestDeletionByEmailOptions = {
 // logs, unlike `?token=`). Same convention as the export-download link
 // (feature.ts, issue #1271). Preserves any existing query params on `base`
 // (`?lang=de` stays a query param; only the token is a fragment).
+const APPEND_LIFECYCLE_EVENT_REASON =
+  "appends the user lifecycle event on the SYSTEM_TENANT_ID user stream";
+
 export function buildDeletionVerifyUrl(base: string, token: string): string {
   const url = new URL(base);
   url.hash = `token=${encodeURIComponent(token)}`;
@@ -66,18 +68,21 @@ export function createRequestDeletionByEmailHandler(opts: RequestDeletionByEmail
     agent: { risk: "high" },
     // Defense-in-depth gegen Email-Probing auf dem anonymen Endpoint.
     rateLimit: { per: "ip", limit: 10, windowSeconds: 60 },
+    escapeHatch: {
+      reason: APPEND_LIFECYCLE_EVENT_REASON,
+    },
     handler: async (event, ctx) => {
       const success = { isSuccess: true as const, data: { kind: "requested" as const } };
 
       // not-configured-safe: ohne Secret/URL kein Link, aber gleiche Antwort.
       if (!opts.deletionTokenSecret || !opts.deletionVerifyUrl) return success;
 
-      // userTable ist tenant-agnostisch (Account-weite Löschung) → ctx.db.raw.
-      const userRow = await fetchOne<{ id: string; status: string; email: string }>(
-        ctx.db.raw,
-        userTable,
-        { email: event.payload.email, isDeleted: false },
-      );
+      const userRow = await ctx.db
+        .global(userTable)
+        .fetchOne<{ id: string; status: string; email: string }>({
+          email: event.payload.email,
+          isDeleted: false,
+        });
       if (!userRow || userRow["status"] !== USER_STATUS.Active || !userRow["email"]) {
         return success;
       }
@@ -86,7 +91,7 @@ export function createRequestDeletionByEmailHandler(opts: RequestDeletionByEmail
       // user-Row landet und in die Token-HMAC-Purpose gefaltet wird. cancel
       // nullt sie → ein nach Cancel nachgespieltes Token verifiziert nicht mehr.
       const requestId = crypto.randomUUID();
-      await updateUserLifecycle(ctx.db.raw, userRow["id"], {
+      await updateUserLifecycle(ctx.db.unsafeRaw(APPEND_LIFECYCLE_EVENT_REASON), userRow["id"], {
         pendingDeletionRequestId: requestId,
       });
 

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

@@ -48,7 +48,8 @@ export function createRequestDeletionHandler(opts: RequestDeletionOptions = {})
       reason:
         "startDeletionGracePeriod reads the tenant compliance profile via ctx.queryAs(SYSTEM, " +
         "...) to compute the grace period end — the calling user's own identity has no read " +
-        "access to that tenant-config projection.",
+        "access to that tenant-config projection. It also appends the user lifecycle event on " +
+        "the SYSTEM_TENANT_ID user stream.",
     },
     description:
       "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.",

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

@@ -14,10 +14,8 @@
 //      Catch + re-fetch + return existing als isExisting=true. Race-
 //      Window <1ms, in Production extrem selten.
 //
-// **Cross-Tenant-Semantik:** ExportJob ist tenant-agnostisch (1 Job pro
-// userId ueber alle Memberships). Pre-Check nutzt ctx.db.raw (kein
-// TenantDb-Filter) — Alice klickt aus Tenant A, klickt dann aus Tenant
-// B → Pre-Check aus B findet den A-Job, kein 2. Job entsteht.
+// **Cross-Tenant-Semantik:** ExportJob is tenant-agnostic (1 job per userId
+// across all memberships) — the pre-check uses ctx.db.unsafeRaw (no TenantDb filter) so a click from tenant B still finds the job from tenant A.
 // `requestedFromTenantId` persistiert den Initial-Tenant aus dem
 // 1. Klick — Worker liest sein Compliance-Profile aus DIESEM Tenant
 // fuer Job-TTL/Stale/Cleanup.
@@ -39,6 +37,9 @@ const crud = createEventStoreExecutor(exportJobsTable, exportJobEntity, {
   entityName: "export-job",
 });
 
+const REQUEST_EXPORT_REASON =
+  "export jobs are keyed by userId across all of the user's tenant memberships, not the caller's current tenant";
+
 /**
  * Race-Loss-Detection: createEventStoreExecutor.create catched 23505
  * intern + returnt `WriteFailure(UniqueViolationError)`, **kein throw**.
@@ -62,14 +63,18 @@ export const requestExportWrite = defineWriteHandler({
   access: { openToAll: true },
   description:
     "Queues a GDPR Art. 15 and 20 data export for the calling user and returns its job id, handing back the running job with isExisting true instead of a second one when an export is already pending.",
+  escapeHatch: {
+    reason: REQUEST_EXPORT_REASON,
+  },
   handler: async (event, ctx) => {
     const userId = event.user.id;
     const T = getTemporal();
     const now = T.Now.instant();
+    const exportJobRunner = ctx.db.unsafeRaw(REQUEST_EXPORT_REASON);
 
-    // Pre-Check: ctx.db.raw weil ExportJob tenant-agnostisch ist —
-    // der TenantDb-Wrapper wuerde Cross-Tenant-Jobs ausblenden.
-    const existing = await findActiveJob(ctx.db.raw, userId);
+    // Pre-Check: exportJobRunner bypasses the TenantDb-Filter — the
+    // TenantDb-Wrapper would hide cross-tenant jobs.
+    const existing = await findActiveJob(exportJobRunner, userId);
     if (existing) {
       // Snapshot-Status (kann zwischen fetchOne + Response stale werden
       // wenn Worker parallel den State flippt; window minimal). User
@@ -104,7 +109,7 @@ export const requestExportWrite = defineWriteHandler({
       // Constraint. Re-fetch + return existing als isExisting=true.
       // Andere Failures (validation, version-conflict, ...) propagieren.
       if (isActiveJobConflict(result)) {
-        const winner = await findActiveJob(ctx.db.raw, userId);
+        const winner = await findActiveJob(exportJobRunner, userId);
         if (!winner) {
           // Sollte nie passieren — Constraint-Violation ohne existing
           // active Job hiesse der Constraint matcht etwas anderes.

package/src/user-data-rights/handlers/restrict-account.write.ts

@@ -1,4 +1,3 @@
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createSystemUser, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import {
   AccessDeniedError,
@@ -27,12 +26,8 @@ import { updateUserLifecycle } from "../lib/update-user-lifecycle";
 // sessionChecker and they can no longer call this (or any) endpoint
 // themselves; only an operator path reaches it at that point.
 //
-// Tenant scope: `isAdminActor` accepts access.admin, which includes
-// TenantAdmin — tenant-scoped, even though the User-entity lookup below
-// uses `ctx.db.raw` (bypasses the auto-tenant-filter, same as
-// lift-restriction.write.ts — User status is intentionally global, see
-// user-data-rights.md "Cross-Tenant-Semantik"). Without a membership
-// check, a TenantAdmin from tenant A could restrict/unrestrict a user who
+// Tenant scope: `isAdminActor` accepts access.admin, which includes TenantAdmin
+// (tenant-scoped) even though the User-entity is global — see user-data-rights.md "Cross-Tenant-Semantik". Without a membership check, a TenantAdmin from tenant A could restrict/unrestrict a user who
 // has never been a member of tenant A. Only SystemAdmin (platform-wide)
 // skips the check; the target must have a membership row in the acting
 // admin's `event.user.tenantId` (row existence only — no active-status field).
@@ -50,7 +45,9 @@ export const restrictAccountWrite = defineWriteHandler({
     reason:
       "Revokes all live sessions of the (possibly self-)restricted user via ctx.writeAs(SYSTEM, " +
       "sessions:write:user-session:revoke-all-for-user) — that handler's own access gate needs " +
-      "privileged roles the acting caller doesn't necessarily have.",
+      "privileged roles the acting caller doesn't necessarily have. It also checks the target " +
+      "user's membership in the admin's tenant and appends the user lifecycle status change on " +
+      "the SYSTEM_TENANT_ID user stream, both via DbRunner helpers.",
   },
   description:
     "Freezes an account under GDPR Art. 18 by flipping it to restricted and revoking all of its live sessions, locking the user out until an admin calls lift-restriction; targets the caller by default, an admin may name another userId.",
@@ -65,13 +62,17 @@ export const restrictAccountWrite = defineWriteHandler({
           }),
         );
       }
-      const outside = await denyIfTargetOutsideAdminTenant(ctx.db.raw, event.user, targetUserId);
+      const outside = await denyIfTargetOutsideAdminTenant(
+        ctx.db.unsafeRaw(
+          "checks the target user's membership in the admin's tenant via the DbRunner helper",
+        ),
+        event.user,
+        targetUserId,
+      );
       if (outside) return outside;
     }
 
-    // ctx.db.raw weil User-Entity tenant-agnostisch ist (analog
-    // request-deletion.write.ts Cross-Tenant-Section).
-    const userRow = await fetchOne<{ status: string }>(ctx.db.raw, userTable, {
+    const userRow = await ctx.db.global(userTable).fetchOne<{ status: string }>({
       id: targetUserId,
     });
 
@@ -99,7 +100,11 @@ export const restrictAccountWrite = defineWriteHandler({
       );
     }
 
-    await updateUserLifecycle(ctx.db.raw, targetUserId, { status: USER_STATUS.Restricted });
+    await updateUserLifecycle(
+      ctx.db.unsafeRaw("appends the user lifecycle event on the SYSTEM_TENANT_ID user stream"),
+      targetUserId,
+      { status: USER_STATUS.Restricted },
+    );
 
     // Cross-Feature: alle live sessions revoken — sonst koennte der User
     // mit existierendem JWT bis zur Token-Expiry weiter schreiben.

package/src/user-data-rights/handlers/run-forget-cleanup.write.ts

@@ -23,12 +23,18 @@ export type RunForgetCleanupOptions = {
   readonly sendDeletionExecutedEmail?: SendDeletionExecutedEmailFn;
 };
 
+const RUN_FORGET_CLEANUP_REASON =
+  "operator forget cleanup iterates users across tenants in per-user sub-transactions";
+
 export function createRunForgetCleanupHandler(opts: RunForgetCleanupOptions = {}) {
   return defineWriteHandler({
     name: "run-forget-cleanup",
     schema: z.object({}),
     access: { roles: access.privileged },
     agent: { expose: false },
+    escapeHatch: {
+      reason: RUN_FORGET_CLEANUP_REASON,
+    },
     handler: async (_event, ctx) => {
       if (!ctx.registry) {
         return writeFailure(
@@ -38,15 +44,13 @@ export function createRunForgetCleanupHandler(opts: RunForgetCleanupOptions = {}
         );
       }
 
-      // ctx.db.raw ist DbRunner. runForgetCleanup oeffnet pro User eine
-      // Sub-Tx (SAVEPOINT wenn Outer-Dispatcher-Tx aktiv) — siehe
-      // run-forget-cleanup.ts Header.
       const T = getTemporal();
+      const runner = ctx.db.unsafeRaw(RUN_FORGET_CLEANUP_REASON);
       // Operator-triggered forget must also erase binaries, not just rows —
       // it flips users to Deleted, after which the cron never re-processes
       // them, so a row-only delete here would permanently leak the binaries.
       // Resolve through the same file-foundation path the cron uses.
-      const forgetDb = ctx.db.raw as DbConnection; // @cast-boundary db-operator: config reads tolerate the outer tx
+      const forgetDb = runner as DbConnection; // @cast-boundary db-runner — DbRunner narrows to DbConnection, config reads tolerate the outer tx
       const tenantModel = await resolveAppTenantModel({
         registry: ctx.registry,
         configResolver: ctx.configResolver,
@@ -54,7 +58,7 @@ export function createRunForgetCleanupHandler(opts: RunForgetCleanupOptions = {}
         userId: ctx._userId ?? SYSTEM_USER_ID,
       });
       const result = await runForgetCleanup({
-        db: ctx.db.raw,
+        db: runner,
         registry: ctx.registry,
         now: T.Now.instant(),
         tenantModel,

package/src/user-data-rights/lib/update-user-lifecycle.ts

@@ -21,8 +21,8 @@ import { USER_STATUS, userEntity, userTable } from "../../user";
 // kann abweichen).
 const userExecutor = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
 
-// `conn` ist ctx.db.raw (regulaere Handler) ODER die offene tx (forget-cleanup
-// Sub-Tx) — so bleibt der Event-Append atomar mit dem umgebenden Write.
+// `conn` is ctx.db.unsafeRaw(reason) (regular handlers) or the open tx
+// (forget-cleanup sub-tx) — keeps the event append atomic with the write.
 export async function updateUserLifecycle(
   conn: DbRunner,
   userId: string,

package/src/user-data-rights/run-forget-cleanup.ts

@@ -510,8 +510,8 @@ async function runInSubTransaction(
   db: DbRunner,
   fn: (tx: DbRunner) => Promise<void>,
 ): Promise<void> {
-  // `db` is already the raw runner (the handler passes ctx.db.raw, the tests a
-  // top-level connection) — cast to read the transaction surface directly,
+  // `db` is already the raw runner (the handler passes ctx.db.unsafeRaw(...),
+  // the tests a top-level connection) — cast to read the transaction surface directly,
   // without asRawClient (a test-only escape hatch). A top-level connection
   // exposes `.begin`; a TransactionSql only `.savepoint`. They are mutually
   // exclusive, so prefer whichever is present.

package/src/user-data-rights/schema/export-job.ts

@@ -45,10 +45,8 @@ const EXPORT_JOB_STATUS_OPTIONS = [
   EXPORT_JOB_STATUS.Failed,
 ] as const;
 
-// **Tenant-agnostisch** wie userTable — 1 Job pro {userId} ueber alle
-// Memberships. Die Framework-Auto-`tenant_id`-Spalte ist da, wird aber
-// in der Domain ignoriert (Cross-Tenant-Iteration laeuft im Worker via
-// ctx.db.raw, gleiches Pattern wie runForgetCleanup).
+// **Tenant-agnostic** like userTable — one job per userId across all
+// memberships; the worker iterates cross-tenant via ctx.db.unsafeRaw (same pattern as runForgetCleanup).
 //
 // **Idempotency:** Partial-UNIQUE-Index auf `(userId)` WHERE
 // `status IN ('pending', 'running')`. User mit pending-Job kann keinen