@cosmicdrift/kumiko-bundled-features 0.13.0 → 0.15.0

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

@@ -11,28 +11,22 @@
 // **Read-Only-Endpoint:** Pollt nur, kein State-Flip. Idempotent + cache-
 // fest. UI poll-Intervall typisch 2-5s waehrend running.
 
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
-import { desc, eq } from "drizzle-orm";
 import { z } from "zod";
 import { exportJobsTable } from "../schema/export-job";
 
 type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 
-// @cast-boundary db-row — drizzle's typed-select gibt korrekte Shapes
-// fuer instant-Spalten zurueck (Temporal.Instant), aber TS-Inference
-// ueber TenantDb-Wrapper kennt das nicht. Cast auf den narrow-Shape
-// macht den Read-Pfad explizit. requestedAt ist `notNull` im Schema
-// → niemals null. Lifecycle-Felder (completedAt/expiresAt) sind
-// nullable bis Worker sie setzt.
 type ExportJobRow = {
   readonly id: string;
   readonly status: string;
-  readonly requestedAt: Instant;
-  readonly completedAt: Instant | null;
-  readonly expiresAt: Instant | null;
-  readonly errorMessage: string | null;
-  readonly bytesWritten: number | null;
+  readonly requested_at: Instant;
+  readonly completed_at: Instant | null;
+  readonly expires_at: Instant | null;
+  readonly error_message: string | null;
+  readonly bytes_written: number | null;
 };
 
 export const exportStatusQuery = defineQueryHandler({
@@ -42,20 +36,12 @@ export const exportStatusQuery = defineQueryHandler({
   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 ctx.db.raw
-      .select({
-        id: exportJobsTable["id"],
-        status: exportJobsTable["status"],
-        requestedAt: exportJobsTable["requestedAt"],
-        completedAt: exportJobsTable["completedAt"],
-        expiresAt: exportJobsTable["expiresAt"],
-        errorMessage: exportJobsTable["errorMessage"],
-        bytesWritten: exportJobsTable["bytesWritten"],
-      })
-      .from(exportJobsTable)
-      .where(eq(exportJobsTable["userId"], query.user.id))
-      .orderBy(desc(exportJobsTable["requestedAt"]))
-      .limit(1)) as ExportJobRow[]; // @cast-boundary db-row
+    const rows = await selectMany<ExportJobRow>(
+      ctx.db.raw,
+      exportJobsTable,
+      { userId: query.user.id },
+      { limit: 1, orderBy: { col: "requestedAt", direction: "desc" } },
+    );
 
     const latest = rows[0];
     if (!latest) return { hasJob: false as const };
@@ -63,13 +49,13 @@ export const exportStatusQuery = defineQueryHandler({
     return {
       hasJob: true as const,
       job: {
-        id: latest.id,
-        status: latest.status,
-        requestedAt: latest.requestedAt.toString(),
-        completedAt: latest.completedAt?.toString() ?? null,
-        expiresAt: latest.expiresAt?.toString() ?? null,
-        errorMessage: latest.errorMessage,
-        bytesWritten: latest.bytesWritten,
+        id: latest["id"],
+        status: latest["status"],
+        requestedAt: latest["requested_at"].toString(),
+        completedAt: latest["completed_at"]?.toString() ?? null,
+        expiresAt: latest["expires_at"]?.toString() ?? null,
+        errorMessage: latest["error_message"],
+        bytesWritten: latest["bytes_written"],
       },
     };
   },

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

@@ -1,6 +1,6 @@
+import { fetchOne, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
-import { eq } from "drizzle-orm";
 import { z } from "zod";
 import { USER_STATUS, userTable } from "../../user";
 
@@ -29,13 +29,11 @@ export const liftRestrictionWrite = defineWriteHandler({
   schema: z.object({}),
   access: { openToAll: true },
   handler: async (event, ctx) => {
-    const userRow = await ctx.db.raw
-      .select({ status: userTable["status"] })
-      .from(userTable)
-      .where(eq(userTable["id"], event.user.id))
-      .limit(1);
+    const userRow = await fetchOne<{ status: string }>(ctx.db.raw, userTable, {
+      id: event.user.id,
+    });
 
-    if (userRow.length === 0) {
+    if (!userRow) {
       return writeFailure(
         new UnprocessableError("user_not_found", {
           details: { reason: "user_not_found", userId: event.user.id },
@@ -43,7 +41,7 @@ export const liftRestrictionWrite = defineWriteHandler({
       );
     }
 
-    const currentStatus = userRow[0]?.status;
+    const currentStatus = userRow["status"];
     if (currentStatus !== USER_STATUS.Restricted) {
       return writeFailure(
         new UnprocessableError("not_restricted", {
@@ -52,10 +50,7 @@ export const liftRestrictionWrite = defineWriteHandler({
       );
     }
 
-    await ctx.db.raw
-      .update(userTable)
-      .set({ status: USER_STATUS.Active })
-      .where(eq(userTable["id"], event.user.id));
+    await updateMany(ctx.db.raw, userTable, { status: USER_STATUS.Active }, { id: event.user.id });
 
     return {
       isSuccess: true as const,

package/src/user-data-rights/handlers/list-download-attempts.query.ts

@@ -1,5 +1,5 @@
+import { selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { and, desc, eq, gte, lte } from "drizzle-orm";
 import { z } from "zod";
 import { downloadAttemptsTable } from "../schema/download-attempt";
 
@@ -24,29 +24,20 @@ export const listDownloadAttemptsQuery = defineQueryHandler({
   access: { roles: ["Admin", "SystemAdmin"] },
   handler: async (query, ctx) => {
     const p = query.payload;
-    const t = downloadAttemptsTable;
-    const conditions = [eq(t["tenantId"], query.user.tenantId)];
-    if (p.result) conditions.push(eq(t["result"], p.result));
-    if (p.ip) conditions.push(eq(t["ip"], p.ip));
-    if (p.from) conditions.push(gte(t["attemptedAt"], Temporal.Instant.from(p.from)));
-    if (p.to) conditions.push(lte(t["attemptedAt"], Temporal.Instant.from(p.to)));
+    const where: WhereObject = { tenantId: query.user.tenantId };
+    if (p.result) where["result"] = p.result;
+    if (p.ip) where["ip"] = p.ip;
+    if (p.from || p.to) {
+      const range: { gte?: unknown; lte?: unknown } = {};
+      if (p.from) range.gte = Temporal.Instant.from(p.from);
+      if (p.to) range.lte = Temporal.Instant.from(p.to);
+      where["attemptedAt"] = range;
+    }
 
-    const rows = await ctx.db
-      .select({
-        id: t["id"],
-        result: t["result"],
-        via: t["via"],
-        tokenHash: t["tokenHash"],
-        jobId: t["jobId"],
-        attemptedByUserId: t["attemptedByUserId"],
-        ip: t["ip"],
-        userAgent: t["userAgent"],
-        attemptedAt: t["attemptedAt"],
-      })
-      .from(t)
-      .where(and(...conditions))
-      .orderBy(desc(t["attemptedAt"]))
-      .limit(p.limit);
+    const rows = await selectMany(ctx.db, downloadAttemptsTable, where, {
+      orderBy: { col: "attemptedAt", direction: "desc" },
+      limit: p.limit,
+    });
 
     return { rows };
   },

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

@@ -1,6 +1,6 @@
+import { selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
-import { and, desc, eq, gte, lt, lte } from "drizzle-orm";
 import { z } from "zod";
 
 // DSGVO Art. 15 Selbstauskunft — User reads HIS OWN audit-log.
@@ -28,32 +28,42 @@ export const myAuditLogQuery = defineQueryHandler({
   handler: async (query, ctx) => {
     const p = query.payload;
 
-    const conditions = [eq(eventsTable.createdBy, query.user.id)];
-    if (p.aggregateType) conditions.push(eq(eventsTable.aggregateType, p.aggregateType));
-    if (p.eventType) conditions.push(eq(eventsTable.type, p.eventType));
-    if (p.from) conditions.push(gte(eventsTable.createdAt, Temporal.Instant.from(p.from)));
-    if (p.to) conditions.push(lte(eventsTable.createdAt, Temporal.Instant.from(p.to)));
-    if (p.before) conditions.push(lt(eventsTable.id, BigInt(p.before)));
-
     // 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 rows = await ctx.db.raw
-      .select({
-        id: eventsTable.id,
-        aggregateId: eventsTable.aggregateId,
-        aggregateType: eventsTable.aggregateType,
-        version: eventsTable.version,
-        type: eventsTable.type,
-        payload: eventsTable.payload,
-        createdAt: eventsTable.createdAt,
-      })
-      .from(eventsTable)
-      .where(and(...conditions))
-      .orderBy(desc(eventsTable.id))
-      .limit(p.limit);
+    const where: WhereObject = { createdBy: query.user.id };
+    if (p.aggregateType) where["aggregateType"] = p.aggregateType;
+    if (p.eventType) where["type"] = p.eventType;
+    if (p.from || p.to) {
+      const range: { gte?: unknown; lte?: unknown } = {};
+      if (p.from) range.gte = Temporal.Instant.from(p.from);
+      if (p.to) range.lte = Temporal.Instant.from(p.to);
+      where["createdAt"] = range;
+    }
+    if (p.before) where["id"] = { lt: BigInt(p.before) };
+
+    const rows = await selectMany<{
+      id: bigint;
+      aggregate_id: string;
+      aggregate_type: string;
+      version: number;
+      type: string;
+      payload: Record<string, unknown>;
+      created_at: unknown;
+    }>(ctx.db.raw, eventsTable, where, {
+      orderBy: { col: "id", direction: "desc" },
+      limit: p.limit,
+    });
 
-    const serialised = rows.map((r) => ({ ...r, id: String(r["id"]) }));
+    const serialised = rows.map((r) => ({
+      id: String(r["id"]),
+      aggregateId: r["aggregate_id"],
+      aggregateType: r["aggregate_type"],
+      version: r["version"],
+      type: r["type"],
+      payload: r["payload"],
+      createdAt: r["created_at"],
+    }));
     const last = serialised[serialised.length - 1];
     return {
       rows: serialised,

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

@@ -1,8 +1,8 @@
+import { fetchOne, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { addDurationSpec, type DurationSpec } from "@cosmicdrift/kumiko-framework/compliance";
 import { createSystemUser, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
-import { eq } from "drizzle-orm";
 import { z } from "zod";
 import { USER_STATUS, userTable } from "../../user";
 
@@ -36,13 +36,11 @@ export function createRequestDeletionHandler(opts: RequestDeletionOptions = {})
     handler: async (event, ctx) => {
       // ctx.db.raw (kein TenantDb-Wrapper) weil User-Entity tenant-agnostisch
       // ist — siehe Plan-Doc Cross-Tenant-Section.
-      const userRow = await ctx.db.raw
-        .select({ status: userTable["status"], email: userTable["email"] })
-        .from(userTable)
-        .where(eq(userTable["id"], event.user.id))
-        .limit(1);
+      const userRow = await fetchOne<{ status: string; email: string }>(ctx.db.raw, userTable, {
+        id: event.user.id,
+      });
 
-      if (userRow.length === 0) {
+      if (!userRow) {
         return writeFailure(
           new UnprocessableError("user_not_found", {
             details: { reason: "user_not_found", userId: event.user.id },
@@ -50,12 +48,12 @@ export function createRequestDeletionHandler(opts: RequestDeletionOptions = {})
         );
       }
 
-      if (userRow[0]?.status !== USER_STATUS.Active) {
+      if (userRow["status"] !== USER_STATUS.Active) {
         return writeFailure(
           new UnprocessableError("user_not_in_active_state", {
             details: {
               reason: "user_not_in_active_state",
-              currentStatus: userRow[0]?.status,
+              currentStatus: userRow["status"],
             },
           }),
         );
@@ -78,19 +76,21 @@ export function createRequestDeletionHandler(opts: RequestDeletionOptions = {})
       const T = getTemporal();
       const gracePeriodEnd = addDurationSpec(T.Now.instant(), gracePeriod);
 
-      await ctx.db.raw
-        .update(userTable)
-        .set({
+      await updateMany(
+        ctx.db.raw,
+        userTable,
+        {
           status: USER_STATUS.DeletionRequested,
           gracePeriodEnd,
-        })
-        .where(eq(userTable["id"], event.user.id));
+        },
+        { id: event.user.id },
+      );
 
       // Best-effort Email-Notification. Send-Failure darf das Write nicht
       // killen — siehe Type-Doc oben. console.warn ist die Operator-
       // Sichtbarkeit; defineWriteHandler-Context fuehrt aktuell keinen
       // structured-logger durch, Refactor-Kandidat wenn ctx.log threadet.
-      const userEmail = userRow[0]?.email;
+      const userEmail = userRow["email"];
       if (opts.sendDeletionRequestedEmail && userEmail && userEmail.length > 0) {
         try {
           await opts.sendDeletionRequestedEmail({

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

@@ -22,11 +22,11 @@
 // 1. Klick — Worker liest sein Compliance-Profile aus DIESEM Tenant
 // fuer Job-TTL/Stale/Cleanup.
 
-import { createEventStoreExecutor, fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler, type SaveContext } from "@cosmicdrift/kumiko-framework/engine";
 import type { WriteFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
-import { eq, inArray } from "drizzle-orm";
 import { z } from "zod";
 import {
   ACTIVE_JOB_CONSTRAINT,
@@ -143,13 +143,9 @@ async function findActiveJob(
   db: import("@cosmicdrift/kumiko-framework/db").DbRunner,
   userId: string,
 ): Promise<{ id: string; status: string } | null> {
-  // @cast-boundary db-row — fetchOne liefert generic DbRow.
-  // Variadic-conditions werden intern mit AND verknuepft.
-  const row = (await fetchOne(
-    db,
-    exportJobsTable,
-    eq(exportJobsTable["userId"], userId),
-    inArray(exportJobsTable["status"], [EXPORT_JOB_STATUS.Pending, EXPORT_JOB_STATUS.Running]),
-  )) as { id: string; status: string } | null;
-  return row;
+  const row = await fetchOne<{ id: string; status: string }>(db, exportJobsTable, {
+    userId,
+    status: [EXPORT_JOB_STATUS.Pending, EXPORT_JOB_STATUS.Running],
+  });
+  return row ?? null;
 }

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

@@ -1,6 +1,6 @@
+import { fetchOne, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createSystemUser, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
-import { eq } from "drizzle-orm";
 import { z } from "zod";
 import { USER_STATUS, userTable } from "../../user";
 
@@ -26,13 +26,11 @@ export const restrictAccountWrite = defineWriteHandler({
   handler: async (event, ctx) => {
     // ctx.db.raw weil User-Entity tenant-agnostisch ist (analog
     // request-deletion.write.ts Cross-Tenant-Section).
-    const userRow = await ctx.db.raw
-      .select({ status: userTable["status"] })
-      .from(userTable)
-      .where(eq(userTable["id"], event.user.id))
-      .limit(1);
+    const userRow = await fetchOne<{ status: string }>(ctx.db.raw, userTable, {
+      id: event.user.id,
+    });
 
-    if (userRow.length === 0) {
+    if (!userRow) {
       return writeFailure(
         new UnprocessableError("user_not_found", {
           details: { reason: "user_not_found", userId: event.user.id },
@@ -40,7 +38,7 @@ export const restrictAccountWrite = defineWriteHandler({
       );
     }
 
-    const currentStatus = userRow[0]?.status;
+    const currentStatus = userRow.status;
     if (currentStatus === USER_STATUS.Restricted) {
       return writeFailure(
         new UnprocessableError("already_restricted", {
@@ -56,10 +54,12 @@ export const restrictAccountWrite = defineWriteHandler({
       );
     }
 
-    await ctx.db.raw
-      .update(userTable)
-      .set({ status: USER_STATUS.Restricted })
-      .where(eq(userTable["id"], event.user.id));
+    await updateMany(
+      ctx.db.raw,
+      userTable,
+      { status: USER_STATUS.Restricted },
+      { id: event.user.id },
+    );
 
     // Cross-Feature: alle live sessions revoken — sonst koennte der User
     // mit existierendem JWT bis zur Token-Expiry weiter schreiben.

package/src/user-data-rights/run-export-jobs.ts

@@ -44,13 +44,10 @@
 // (`expiresAt + exportStorageCleanupGraceHours < now`) — abgelaufene ZIPs
 // auf S3 sollen nicht ewig liegen.
 
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { addDurationSpec } from "@cosmicdrift/kumiko-framework/compliance";
 import type { DbConnection, DbRunner } from "@cosmicdrift/kumiko-framework/db";
-import {
-  createEventStoreExecutor,
-  createTenantDb,
-  fetchOne,
-} from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -59,9 +56,9 @@ import {
   type ZipEntry,
 } from "@cosmicdrift/kumiko-framework/files";
 import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
-import { and, asc, eq, isNotNull, or } from "drizzle-orm";
 import { resolveProfileForTenant } from "../compliance-profiles";
 import { userTable } from "../user";
+import { selectExportJobsForStorageCleanup } from "./db/queries/export-jobs";
 import { runUserExport, type UserExportBundle } from "./run-user-export";
 import { exportDownloadTokenEntity, exportDownloadTokensTable } from "./schema/download-token";
 import { EXPORT_JOB_STATUS, exportJobEntity, exportJobsTable } from "./schema/export-job";
@@ -306,17 +303,14 @@ interface JobRow {
 }
 
 async function fetchPendingJobs(db: DbRunner): Promise<readonly JobRow[]> {
-  // @cast-boundary db-row.
-  return (await db
-    .select({
-      id: exportJobsTable["id"],
-      version: exportJobsTable["version"],
-      userId: exportJobsTable["userId"],
-      requestedFromTenantId: exportJobsTable["requestedFromTenantId"],
-    })
-    .from(exportJobsTable)
-    .where(eq(exportJobsTable["status"], EXPORT_JOB_STATUS.Pending))
-    .orderBy(asc(exportJobsTable["requestedAt"]))) as readonly JobRow[];
+  return selectMany<JobRow>(
+    db,
+    exportJobsTable,
+    { status: EXPORT_JOB_STATUS.Pending },
+    {
+      orderBy: { col: "requestedAt", direction: "asc" },
+    },
+  );
 }
 
 type ProcessOutcome =
@@ -530,23 +524,13 @@ async function staleDetectionPass(args: {
   // wuerde 30-60min-alte stale-Jobs UNERKANNT lassen. Cron laeuft alle
   // 60s, zu jedem Zeitpunkt sind nur wenige Jobs in `running` —
   // alle fetchen + profile-resolve im Loop ist bezahlbar + korrekt.
-  // @cast-boundary db-row.
-  const candidates = (await db
-    .select({
-      id: exportJobsTable["id"],
-      version: exportJobsTable["version"],
-      userId: exportJobsTable["userId"],
-      requestedFromTenantId: exportJobsTable["requestedFromTenantId"],
-      startedAt: exportJobsTable["startedAt"],
-    })
-    .from(exportJobsTable)
-    .where(eq(exportJobsTable["status"], EXPORT_JOB_STATUS.Running))) as readonly {
+  const candidates = await selectMany<{
     id: string;
     version: number;
     userId: string;
     requestedFromTenantId: TenantId;
     startedAt: Instant | null;
-  }[];
+  }>(db, exportJobsTable, { status: EXPORT_JOB_STATUS.Running });
 
   const failed: string[] = [];
   for (const c of candidates) {
@@ -615,36 +599,12 @@ async function storageCleanupPass(args: {
   // bereits in der DB statt im Loop. Bei skalierender DB-Historie (10k+
   // done-jobs nach 30 Tagen) reduziert das den Worker-Roundtrip drastisch.
   //
-  // @cast-boundary db-row.
-  const candidates = (await db
-    .select({
-      id: exportJobsTable["id"],
-      version: exportJobsTable["version"],
-      status: exportJobsTable["status"],
-      requestedFromTenantId: exportJobsTable["requestedFromTenantId"],
-      downloadStorageKey: exportJobsTable["downloadStorageKey"],
-      expiresAt: exportJobsTable["expiresAt"],
-    })
-    .from(exportJobsTable)
-    .where(
-      and(
-        // Beide Pfade: status in (done, failed) + downloadStorageKey gesetzt.
-        // Filter im Loop verfeinert (done braucht expiresAt+grace, failed
-        // sofort).
-        or(
-          eq(exportJobsTable["status"], EXPORT_JOB_STATUS.Done),
-          eq(exportJobsTable["status"], EXPORT_JOB_STATUS.Failed),
-        ),
-        isNotNull(exportJobsTable["downloadStorageKey"]),
-      ),
-    )) as readonly {
-    id: string;
-    version: number;
-    status: string;
-    requestedFromTenantId: TenantId;
-    downloadStorageKey: string | null;
-    expiresAt: Instant | null;
-  }[];
+  // or() + isNotNull(): no bun-db helper covers this combination — raw SQL.
+  const candidates = await selectExportJobsForStorageCleanup(
+    db,
+    EXPORT_JOB_STATUS.Done,
+    EXPORT_JOB_STATUS.Failed,
+  );
 
   const cleaned: string[] = [];
   for (const c of candidates) {
@@ -796,7 +756,7 @@ function countingStream(source: AsyncIterable<Uint8Array>): {
 // aus jedem Worker-Tenant-Context.
 async function lookupUserEmail(db: DbConnection, userId: string): Promise<string | null> {
   // @cast-boundary db-row.
-  const row = (await fetchOne(db, userTable, eq(userTable["id"], userId))) as {
+  const row = (await fetchOne(db, userTable, { id: userId })) as {
     email: string | null;
   } | null;
   return row?.email ?? null;

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

@@ -18,7 +18,7 @@
 // Outer-Tx aktiv, BEGIN sonst). Folge: ein failing Hook bei User A
 // rollt nur dessen Sub-Tx zurueck, User B + bisherige User-Status-Flips
 // bleiben commit-able. Ohne diese Sub-Tx wuerde der Outer-Dispatcher-Tx
-// (alle writeHandler laufen in `db.transaction(...)`) den ganzen
+// (alle writeHandler laufen in `db.begin(...)`) den ganzen
 // Cleanup-Run beim ersten Hook-Throw zurueckrollen.
 //
 // **Idempotenz:** Hooks sind idempotent designed (siehe
@@ -32,6 +32,7 @@
 // gefailten Hooks bleibt im DeletionRequested-Status (next Lauf
 // retried automatisch).
 
+import { fetchOne, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import {
   EXT_USER_DATA,
@@ -41,10 +42,10 @@ import {
   type UserDataDeleteStrategy,
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
-import { and, eq, lte } from "drizzle-orm";
 import { resolveRetentionPolicyForTenant } from "../data-retention";
 import { tenantMembershipsTable } from "../tenant";
 import { USER_STATUS, userTable } from "../user";
+import { selectUsersDueForForgetCleanup } from "./db/queries/forget-cleanup";
 
 type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 
@@ -111,16 +112,12 @@ export async function runForgetCleanup(
   const { db, registry, now, sendDeletionExecutedEmail } = args;
 
   // Step 1: Find users with expired grace period.
-  // @cast-boundary db-row — drizzle-select gibt Record-Shape zurueck.
-  const dueUsers = (await db
-    .select({ id: userTable["id"] })
-    .from(userTable)
-    .where(
-      and(
-        eq(userTable["status"], USER_STATUS.DeletionRequested),
-        lte(userTable["gracePeriodEnd"], now),
-      ),
-    )) as Array<{ id: string }>;
+  // lte with Instant: no bun-db operator covers this — raw SQL.
+  const dueUsers = await selectUsersDueForForgetCleanup(
+    db,
+    USER_STATUS.DeletionRequested,
+    now.toString(),
+  );
 
   if (dueUsers.length === 0) {
     return { processedUserIds: [], hookCallsAttempted: 0, errors: [] };
@@ -212,23 +209,14 @@ async function processUser(args: {
   // Nach der Tx ist email = "deleted-{id}@{tenant}.example" oder NULL.
   // Memory-cache laesst Atom-5b-Callback nach success-flip den
   // ORIGINAL-email an App-Author-Callback geben.
-  // @cast-boundary db-row.
-  const userPreTx = (await db
-    .select({ email: userTable["email"] })
-    .from(userTable)
-    .where(eq(userTable["id"], userId))
-    .limit(1)) as Array<{ email: string | null }>;
+  const userPreTx = await fetchOne<{ email: string | null }>(db, userTable, { id: userId });
   const userEmailBeforeDelete =
-    userPreTx[0]?.email && userPreTx[0].email.length > 0 ? userPreTx[0].email : null;
+    userPreTx?.email && userPreTx.email.length > 0 ? userPreTx.email : null;
 
   // Memberships fuer diesen User holen — alle Tenants in denen er Mitglied ist.
-  // @cast-boundary db-row.
-  const memberships = (await db
-    .select({ tenantId: tenantMembershipsTable["tenantId"] })
-    .from(tenantMembershipsTable)
-    .where(eq(tenantMembershipsTable["userId"], userId))) as Array<{
-    tenantId: TenantId;
-  }>;
+  const memberships = await selectMany<{ tenantId: TenantId }>(db, tenantMembershipsTable, {
+    userId,
+  });
   // tenant-Liste fuer Atom 5b Email — Memberships VOR Tx, weil hooks
   // memberships in der Tx loeschen. Orphan-User (0 memberships) liefert
   // [] in Email-args; App-Author-Template kann das case-handlen.
@@ -259,8 +247,8 @@ async function processUser(args: {
   let currentTenantId: TenantId | null = null;
   let currentEntityName: string | null = null;
   try {
-    await (db as { transaction: (fn: (tx: DbRunner) => Promise<void>) => Promise<void> }) // @cast-boundary db-runner
-      .transaction(async (tx) => {
+    await (db as { begin: (fn: (tx: DbRunner) => Promise<void>) => Promise<void> }).begin(
+      async (tx) => {
         for (const tenantId of tenantList) {
           currentTenantId = tenantId;
           for (const entry of hookEntries) {
@@ -282,12 +270,10 @@ async function processUser(args: {
         // geworfen hat, kommen wir hier nicht an — die Tx rollback'd
         // alles, der User bleibt im DeletionRequested-Status, naechster
         // Run retried.
-        await tx
-          .update(userTable)
-          .set({ status: USER_STATUS.Deleted })
-          .where(eq(userTable["id"], userId));
+        await updateMany(tx, userTable, { status: USER_STATUS.Deleted }, { id: userId });
         txSucceeded = true;
-      });
+      },
+    );
   } catch (e) {
     // currentTenantId/currentEntityName tracken den Failing-Hook —
     // Operator sieht "Hook fileRef in Tenant A failed for user X" statt