@cosmicdrift/kumiko-bundled-features 0.277.0 → 0.280.0

package/src/cap-counter/changes.json

@@ -1 +1,16 @@
-[]
+[
+  {
+    "version": "0.278.0",
+    "type": "improvement",
+    "title": "bookCapUsage/markCapSoftWarned/readRollingCapUsage — in-process calendar-cap booking bound to the caller's own tenant (fw#2854).",
+    "detail": "New helpers in `book-cap-usage.ts`: `bookCapUsage(ctx, options)` and `markCapSoftWarned(ctx, options)` run the calendar-counter create-or-update / soft-warn-flip logic in-process against `ctx.db`/`ctx.user`; `readRollingCapUsage(db, tenantId, options)` sums a rolling window without throwing and works as the `usage` callback for an existing rolling stream. `enforceCapAndMaybeNotify` and `withCapEnforcement` now call `bookCapUsage`/`markCapSoftWarned` in-process instead of dispatching the `SystemAdmin`-only `increment`/`mark-soft-warned` write-handlers through `ctx.write` — a plain `TenantAdmin` caller (no `SystemAdmin` role, no `escapeHatch`, no `ctx.writeAs` identity-switch) can now use calendar cap-enforcement end to end. `withRollingCapEnforcement` still books through the `SystemAdmin`-only `increment-rolling` write-handler via `ctx.write` — the framework's event-ownership rule rejects `unsafeAppendEvent` calls for a foreign feature made in-process, so rolling callers still need a `SystemAdmin` identity.",
+    "migration": "No action required for the call signatures — `enforceCapAndMaybeNotify`/`withCapEnforcement`/`withRollingCapEnforcement` keep their existing signatures and result shapes. An app that previously worked around the `SystemAdmin`-only calendar dispatch with its own `escapeHatch` + `ctx.writeAs(SystemAdmin, ...)` wrapper can remove that workaround for `withCapEnforcement`; `withRollingCapEnforcement` callers still need a `SystemAdmin` identity (role or `ctx.writeAs`)."
+  },
+  {
+    "version": "0.278.0",
+    "type": "breaking",
+    "title": "createStockCapGuard/checkStockCap/withStockCap resolve through the caller's TenantDb, not a raw DbRunner + explicit tenantId (fw#2854).",
+    "detail": "`createStockCapGuard`'s resolver is now `(db: TenantDb) => Promise<TCaps>` instead of `(db: DbRunner, tenantId: TenantId) => Promise<TCaps>`. `checkStockCap(db: TenantDb, spec)` drops the separate `tenantId` parameter — the tenant comes from `db.tenantId`, and the count runs through `TenantDb.count` instead of the raw `countWhere`. `StockCapSpec.table` is now typed `SchemaTable | EntityTableMeta` (matching `TenantDb.count`'s table parameter) instead of `Parameters<typeof countWhere>[1]`. `withStockCap` no longer declares an `escapeHatch` on the wrapped handler and no longer reads through `ctx.db.unsafeRaw(...)` — it calls `checkStockCap(ctx.db, spec)` directly, so a `TenantAdmin`-only handler with no `escapeHatch` can use it.",
+    "migration": "`createStockCapGuard(async (db, tenantId) => ...)` → `createStockCapGuard(async (db) => ...)`, reading `db.tenantId` instead of the removed second argument. A direct `checkStockCap(runner, tenantId, spec)` call → `checkStockCap(tenantDb, spec)` with a `TenantDb` built via `createTenantDb(runner, tenantId)` (or `ctx.db` inside a handler). If your wrapped handler relied on `withStockCap`'s auto-added `escapeHatch` for some other reason, declare it explicitly on the handler instead — `withStockCap` no longer adds one."
+  }
+]

package/src/cap-counter/enforce-cap.ts

@@ -1,12 +1,6 @@
 import { createEntityExecutor, type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { KumikoError } from "@cosmicdrift/kumiko-framework/errors";
-import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
-import { rollingCapAggregateId } from "./aggregate-id";
-import {
-  CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
-  CapCounterHandlers,
-  ROLLING_INCREMENTED_EVENT_QN,
-} from "./constants";
+import { markCapSoftWarned, readRollingCapUsage } from "./book-cap-usage";
 import { capCounterEntity } from "./entity";
 
 // Temporal globally provided by the framework's polyfill init
@@ -180,33 +174,11 @@ export async function enforceRollingCap(
   const softThreshold = options.limit * tolerance.soft;
   const hardThreshold = options.limit * tolerance.hard;
 
-  const aggregateId = rollingCapAggregateId(ctx.user.tenantId, options.capName);
-  const cutoff = Temporal.Now.instant().subtract({ hours: options.windowDays * 24 });
-
-  // events_tenant_type_idx (tenant_id, aggregate_type, created_at)
-  // covers the prefix; the additional aggregate_id eq narrows to the
-  // single rolling-stream. Postgres can use the index even with the
-  // aggregate_id filter applied as a residual.
-  const rows = await ctx.db.selectMany<{ payload: { amount?: number } }>(eventsTable, {
-    tenantId: ctx.user.tenantId,
-    aggregateType: CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
-    aggregateId,
-    type: ROLLING_INCREMENTED_EVENT_QN,
-    createdAt: { gte: cutoff },
+  const value = await readRollingCapUsage(ctx.db, ctx.user.tenantId, {
+    capName: options.capName,
+    windowDays: options.windowDays,
   });
 
-  let value = 0;
-  for (const row of rows) {
-    // @cast-boundary engine-payload — events.payload is jsonb (typed as
-    // unknown by drizzle's $type<Record<string,unknown>>); narrowing
-    // the shape here is a deliberate read-side contract for the
-    // rolling-incremented-event we authored.
-    const payload = row["payload"] as { amount?: number };
-    if (typeof payload.amount === "number") {
-      value += payload.amount;
-    }
-  }
-
   if (value >= hardThreshold) {
     throw new CapExceededError(options.capName, options.limit, value, tolerance);
   }
@@ -335,11 +307,7 @@ export async function enforceCapAndMaybeNotify(
       tenantId: ctx.user.tenantId,
     });
     // Flip the soft-warned flag so the same period doesn't re-notify.
-    // We're already inside a write-handler-context, so dispatching the
-    // mark-soft-warned-handler in-line works via ctx.write (re-uses
-    // the request user; the handler's own access-check enforces the
-    // SystemAdmin role on the caller).
-    await ctx.write(CapCounterHandlers.markSoftWarned, {
+    await markCapSoftWarned(ctx, {
       capName: options.capName,
       periodStartIso: options.periodStartIso,
     });

package/src/cap-counter/handlers/increment.write.ts

@@ -1,10 +1,6 @@
-import { createEntityExecutor, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
-import { Temporal } from "temporal-polyfill";
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
-import { capCounterAggregateId } from "../aggregate-id";
-import { capCounterEntity } from "../entity";
-
-const { table, executor } = createEntityExecutor("cap-counter", capCounterEntity);
+import { bookCapUsage } from "../book-cap-usage";
 
 const incrementSchema = z.object({
   /** App-defined cap-name. e.g. "platform-mails", "ai-tokens-7day". */
@@ -47,46 +43,10 @@ export const incrementCapHandler: WriteHandlerDef = {
   access: { roles: ["SystemAdmin"] },
   handler: async (event, ctx) => {
     const payload = event.payload as IncrementPayload; // @cast-boundary engine-payload
-    const aggregateId = capCounterAggregateId(
-      event.user.tenantId,
-      payload.capName,
-      payload.periodStartIso,
-    );
-
-    // Read existing aggregate's projection-row to decide create vs update.
-    // ctx.db is auto-tenant-scoped — id-lookup is unique per tenant.
-    const existing = await ctx.db.selectMany(table, { id: aggregateId }, { limit: 1 });
-
-    if (existing.length === 0) {
-      return executor.create(
-        {
-          id: aggregateId,
-          capName: payload.capName,
-          value: payload.amount,
-          periodStart: Temporal.Instant.from(payload.periodStartIso),
-          lastSoftWarnedAt: null,
-        },
-        event.user,
-        ctx.db,
-      );
-    }
-
-    const currentRow = existing[0];
-    if (!currentRow) {
-      // Defensive — length-check above means this is unreachable. Throws
-      // clearer than a possibly-null deref later.
-      throw new Error("cap-counter:increment: row vanished between length-check and read");
-    }
-    const currentValue = currentRow["value"] as number; // @cast-boundary db-row
-    const currentVersion = currentRow["version"] as number; // @cast-boundary db-row
-    return executor.update(
-      {
-        id: aggregateId,
-        version: currentVersion,
-        changes: { value: currentValue + payload.amount },
-      },
-      event.user,
-      ctx.db,
-    );
+    return bookCapUsage(ctx, {
+      capName: payload.capName,
+      periodStartIso: payload.periodStartIso,
+      amount: payload.amount,
+    });
   },
 };

package/src/cap-counter/handlers/mark-soft-warned.write.ts

@@ -1,10 +1,6 @@
-import { createEntityExecutor, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
-import { Temporal } from "temporal-polyfill";
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
-import { capCounterAggregateId } from "../aggregate-id";
-import { capCounterEntity } from "../entity";
-
-const { table, executor } = createEntityExecutor("cap-counter", capCounterEntity);
+import { markCapSoftWarned } from "../book-cap-usage";
 
 // mark-soft-warned — sets lastSoftWarnedAt on the counter so subsequent
 // soft-cap-hits in the same period don't re-trigger notifications.
@@ -26,32 +22,9 @@ export const markSoftWarnedHandler: WriteHandlerDef = {
   access: { roles: ["SystemAdmin"] },
   handler: async (event, ctx) => {
     const payload = event.payload as z.infer<typeof markSoftWarnedSchema>; // @cast-boundary engine-payload
-    const aggregateId = capCounterAggregateId(
-      event.user.tenantId,
-      payload.capName,
-      payload.periodStartIso,
-    );
-
-    const existing = await ctx.db.selectMany(table, { id: aggregateId }, { limit: 1 });
-    if (existing.length === 0) {
-      throw new Error(
-        `cap-counter: cannot mark-soft-warned, no counter found for tenant=${event.user.tenantId} cap=${payload.capName} period=${payload.periodStartIso}`,
-      );
-    }
-    const row = existing[0];
-    if (!row) {
-      throw new Error("cap-counter:mark-soft-warned: row vanished between length-check and read");
-    }
-    const currentVersion = row["version"] as number; // @cast-boundary db-row
-
-    return executor.update(
-      {
-        id: aggregateId,
-        version: currentVersion,
-        changes: { lastSoftWarnedAt: Temporal.Now.instant() },
-      },
-      event.user,
-      ctx.db,
-    );
+    return markCapSoftWarned(ctx, {
+      capName: payload.capName,
+      periodStartIso: payload.periodStartIso,
+    });
   },
 };

package/src/cap-counter/index.ts

@@ -1,6 +1,14 @@
 // Public API of the cap-counter bundled-feature.
 
 export { capCounterAggregateId, rollingCapAggregateId } from "./aggregate-id";
+export {
+  type BookCapUsageOptions,
+  bookCapUsage,
+  type MarkCapSoftWarnedOptions,
+  markCapSoftWarned,
+  type ReadRollingCapUsageOptions,
+  readRollingCapUsage,
+} from "./book-cap-usage";
 export {
   CAP_COUNTER_FEATURE,
   CAP_COUNTER_ROLLING_AGGREGATE_TYPE,

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

@@ -3,8 +3,13 @@
 // only per-app variable was the Caps shape and how to resolve it for a
 // tenant, so both are now factory parameters.
 
-import { countWhere, type DbRunner, type WhereObject } from "@cosmicdrift/kumiko-framework/db";
-import type { TenantId, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import type {
+  EntityTableMeta,
+  SchemaTable,
+  TenantDb,
+  WhereObject,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import {
   UnprocessableError,
   type WriteFailure,
@@ -13,7 +18,7 @@ import {
 import { enforceStockCap } from "./enforce-cap";
 
 export type StockCapSpec<TCaps> = {
-  readonly table: Parameters<typeof countWhere>[1];
+  readonly table: SchemaTable | EntityTableMeta;
   readonly limit: (caps: TCaps) => number;
   readonly where?: WhereObject;
   readonly code: string;
@@ -22,24 +27,19 @@ export type StockCapSpec<TCaps> = {
 };
 
 export type StockCapGuard<TCaps> = {
-  readonly checkStockCap: (
-    db: DbRunner,
-    tenantId: TenantId,
-    spec: StockCapSpec<TCaps>,
-  ) => Promise<WriteFailure | null>;
+  readonly checkStockCap: (db: TenantDb, spec: StockCapSpec<TCaps>) => Promise<WriteFailure | null>;
   readonly withStockCap: (handler: WriteHandlerDef, spec: StockCapSpec<TCaps>) => WriteHandlerDef;
 };
 
 export function createStockCapGuard<TCaps>(
-  resolveTierCaps: (db: DbRunner, tenantId: TenantId) => Promise<TCaps>,
+  resolveTierCaps: (db: TenantDb) => Promise<TCaps>,
 ): StockCapGuard<TCaps> {
   async function checkStockCap(
-    db: DbRunner,
-    tenantId: TenantId,
+    db: TenantDb,
     spec: StockCapSpec<TCaps>,
   ): Promise<WriteFailure | null> {
-    const caps = await resolveTierCaps(db, tenantId);
-    const current = await countWhere(db, spec.table, { ...spec.where, tenantId });
+    const caps = await resolveTierCaps(db);
+    const current = await db.count(spec.table, { ...spec.where, tenantId: db.tenantId });
     const { state, limit } = enforceStockCap({
       current,
       limit: spec.limit(caps),
@@ -55,15 +55,10 @@ 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.unsafeRaw(capReason), event.user.tenantId, spec);
+        const failure = await checkStockCap(ctx.db, spec);
         return failure ?? handler.handler(event, ctx);
       },
     };

package/src/cap-counter/with-cap-enforcement.ts

@@ -1,5 +1,5 @@
 // withCapEnforcement / withRollingCapEnforcement — handler-wrapper die
-// pre-call enforceCap-And-Notify + post-call increment um den
+// pre-call enforceCap-And-Notify + post-call booking um den
 // gewrappten Handler legen.
 //
 // **Warum Wrapper statt manuelle Calls im Handler:**
@@ -8,22 +8,20 @@
 // pre-call zu machen — beides ist atomic-mit-dem-Handler-zusammen.
 // Wrapper macht das Pattern explizit + co-located.
 //
-// **Atomicity-Vorbehalt:** Pre-enforce + Handler + Post-Increment
-// laufen in DREI getrennten Transaktionen (Dispatcher öffnet jede
-// ctx.write-call eine eigene). Bei einem Crash zwischen Handler-
-// Success und Post-Increment kommt der Counter unter — Tenant
-// kriegt 1-2 Mails extra. Akzeptabel weil Cap-Toleranzen (110/120%)
-// genau für solche Drift-Fälle gebaut sind.
+// **Atomicity caveat:** calendar booking runs in-process via bookCapUsage
+// (see book-cap-usage.ts). Rolling booking still dispatches the
+// SystemAdmin-only increment-rolling handler (event ownership), so rolling
+// callers need a SystemAdmin identity.
 //
-// **Kein automatic markSoftWarned:** das passiert in
-// enforceCapAndMaybeNotify drin (siehe enforce-cap.ts). Wrapper ruft
-// nur den Helper, der den write dispatched.
+// No automatic markSoftWarned here — that's inside enforceCapAndMaybeNotify
+// (enforce-cap.ts).
 
 import type {
   HandlerContext,
   WriteEvent,
   WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { bookCapUsage } from "./book-cap-usage";
 import { CapCounterHandlers } from "./constants";
 import {
   type CapToleranceProfileName,
@@ -103,7 +101,7 @@ export function withCapEnforcement(
       // Post-success increment. Skip on failure so a failed write
       // doesn't burn cap-quota. amount default 1.
       if (result.isSuccess) {
-        await ctx.write(CapCounterHandlers.increment, {
+        await bookCapUsage(ctx, {
           capName: cap.capName,
           amount: cap.amount ?? 1,
           periodStartIso: cap.periodStartIso,

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

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

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

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

package/src/data-retention/resolve-for-tenant.ts

@@ -7,15 +7,22 @@
 // + `resolveRetentionPolicy`, also kein Drift-Risiko.
 
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { parseRetentionOverrideOrNull } from "./_internal/parse-override";
 import type { RetentionPresetKey } from "./presets";
 import { type EffectiveRetentionPolicy, resolveRetentionPolicy } from "./resolver";
 import { tenantRetentionOverrideTable } from "./schema/tenant-retention-override";
 
+function isTenantDb(db: DbRunner | TenantDb): db is TenantDb {
+  return typeof (db as Partial<TenantDb>).unsafeRaw === "function";
+}
+
 export interface ResolveForTenantArgs {
-  readonly db: DbRunner;
+  // fw#2914 — a EXT_USER_DATA hook's ctx.db is a TenantDb (method-form);
+  // the cleanup cron's own db is still a raw DbRunner. Both are valid here —
+  // this lookup is a plain tenant-scoped read either way.
+  readonly db: DbRunner | TenantDb;
   readonly registry: Registry;
   readonly tenantId: TenantId;
   readonly entityName: string;
@@ -43,10 +50,15 @@ export async function resolveRetentionPolicyForTenant(
   const overrideRow =
     args.preloadedOverride !== undefined
       ? args.preloadedOverride
-      : ((await fetchOne(args.db, tenantRetentionOverrideTable, {
-          tenantId: args.tenantId,
-          entityName: args.entityName,
-        })) as { config: string | null } | null); // @cast-boundary db-runner
+      : isTenantDb(args.db)
+        ? ((await args.db.fetchOne<{ config: string | null }>(tenantRetentionOverrideTable, {
+            tenantId: args.tenantId,
+            entityName: args.entityName,
+          })) ?? null)
+        : ((await fetchOne(args.db, tenantRetentionOverrideTable, {
+            tenantId: args.tenantId,
+            entityName: args.entityName,
+          })) as { config: string | null } | null); // @cast-boundary db-runner
 
   const tenantOverride = parseRetentionOverrideOrNull(
     overrideRow?.config ?? null,

package/src/delivery/db/queries/preferences.ts

@@ -8,6 +8,7 @@ export type NotificationPreferenceRow = {
   readonly enabled: boolean;
 };
 
+// @wrapper-known semantic-alias
 export async function selectNotificationPreferences(
   db: DbConnection,
   tenantId: TenantId,

package/src/files-tenant-data/hooks.ts

@@ -18,8 +18,7 @@
 //     cross into another tenant's keys (the provider's own list() prefix
 //     already scopes it).
 
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
   type StorageProviderDestroyTenantHook,
@@ -34,13 +33,12 @@ import {
 const crud = createEventStoreExecutor(fileRefsTable, fileRefEntity, { entityName: "fileRef" });
 
 export const fileRefTenantDestroyHook: TenantDataDestroyHook = async (ctx) => {
-  const rows = await selectMany<{ id: string }>(ctx.db, fileRefsTable, {
+  const rows = await ctx.db.selectMany<{ id: string }>(fileRefsTable, {
     tenantId: ctx.tenantId,
   });
   const user = createSystemUser(ctx.tenantId);
-  const db = createTenantDb(ctx.db, ctx.tenantId, "system");
   for (const row of rows) {
-    const result = await crud.forget({ id: row.id }, user, db);
+    const result = await crud.forget({ id: row.id }, user, ctx.db);
     // Executor writes return {isSuccess:false} instead of throwing — a
     // discarded result would report this destroy stage "succeeded" while the
     // row (and its PII fileName) survives. Throw so the pipeline's

package/src/folders/__tests__/folders.integration.test.ts

@@ -17,6 +17,7 @@
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
@@ -402,7 +403,7 @@ describe("folders-user-data — tenantScopedDelete hooks", () => {
   test("multi-user tenant: no-op, rows survive", async () => {
     await seedOneFolderWithAssignment();
     const ctx = {
-      db: stack.db,
+      db: createTenantDb(stack.db, admin.tenantId, "tenant"),
       registry: stack.registry,
       tenantId: admin.tenantId,
       userId: admin.id,
@@ -417,7 +418,7 @@ describe("folders-user-data — tenantScopedDelete hooks", () => {
   test("anonymize strategy: no-op even on a single-user tenant", async () => {
     await seedOneFolderWithAssignment();
     const ctx = {
-      db: stack.db,
+      db: createTenantDb(stack.db, admin.tenantId, "tenant"),
       registry: stack.registry,
       tenantId: admin.tenantId,
       userId: admin.id,
@@ -432,7 +433,7 @@ describe("folders-user-data — tenantScopedDelete hooks", () => {
   test("single-user tenant + delete: rows are purged", async () => {
     await seedOneFolderWithAssignment();
     const ctx = {
-      db: stack.db,
+      db: createTenantDb(stack.db, admin.tenantId, "tenant"),
       registry: stack.registry,
       tenantId: admin.tenantId,
       userId: admin.id,

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

@@ -11,6 +11,7 @@
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
@@ -87,7 +88,7 @@ describe("folderAssignmentExportHook", () => {
     );
 
     const snippet = await folderAssignmentExportHook({
-      db: stack.db,
+      db: createTenantDb(stack.db, admin.tenantId, "tenant"),
       registry: stack.registry,
       tenantId: admin.tenantId,
       userId: admin.id,

package/src/folders-user-data/hooks.ts

@@ -4,8 +4,7 @@
 // Mirrors credit-user-data — standard tenant-scoped pattern, no name-stripping
 // (a folder name is tenant data, not per-user PII).
 
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { createTenantDb, type EventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import type { EventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntityExecutor,
   createSystemUser,
@@ -27,9 +26,7 @@ const { table: folderAssignmentTable, executor: folderAssignmentExecutor } = cre
 // all tenant folders in-app, so bundling them into the user's export is no new
 // exposure — it gives the data subject the organisation of the loans they work with.
 export const folderExportHook: UserDataExportHook = async (ctx) => {
-  const rows = await selectMany<Record<string, unknown>>(ctx.db, folderTable, {
-    tenantId: ctx.tenantId,
-  });
+  const rows = await ctx.db.selectMany(folderTable, { tenantId: ctx.tenantId });
   if (rows.length === 0) return null;
   return { entity: "folder", rows };
 };
@@ -38,7 +35,7 @@ export const folderAssignmentExportHook: UserDataExportHook = async (ctx) => {
   // folderAssignmentEntity is softDelete: true — a cleared assignment
   // (isDeleted: true) is a removed folder membership, not something the GDPR
   // export should still surface as current data.
-  const rows = await selectMany<Record<string, unknown>>(ctx.db, folderAssignmentTable, {
+  const rows = await ctx.db.selectMany(folderAssignmentTable, {
     tenantId: ctx.tenantId,
     isDeleted: false,
   });
@@ -65,11 +62,9 @@ function tenantScopedDelete(
     // eventless, so a projection rebuild resurrects the rows. Bounded — forget
     // only fires for single-user tenants.
     const systemUser = createSystemUser(ctx.tenantId);
-    // The executor needs a TenantDb (loadById → db.fetchOne), not the raw ctx.db.
-    const tdb = createTenantDb(ctx.db, ctx.tenantId, "system");
-    const rows = await selectMany<{ id: string }>(ctx.db, table, { tenantId: ctx.tenantId });
+    const rows = await ctx.db.selectMany<{ id: string }>(table, { tenantId: ctx.tenantId });
     for (const row of rows) {
-      await executor.delete({ id: row.id }, systemUser, tdb);
+      await executor.delete({ id: row.id }, systemUser, ctx.db);
     }
   };
 }