@cosmicdrift/kumiko-bundled-features 0.277.0 → 0.278.0

package/package.json

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

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

@@ -296,14 +296,16 @@ describe("enforceCapAndMaybeNotify — calendar", () => {
     expect(notify).not.toHaveBeenCalled();
   });
 
-  test("soft-hit, crossed=true → notifier mit info-payload + ctx.write markSoftWarned", async () => {
+  // markCapSoftWarned (fw#2854) now runs the real event-store executor
+  // against ctx.db instead of a mockable ctx.write call — this pure-mock
+  // ctx.db can't satisfy that, so it throws after notify() already fired.
+  // The DB flag-flip itself is covered by cap-counter.integration.test.ts's
+  // real-stack "scenario 6" test.
+  test("soft-hit, crossed=true → notifier fires with the info-payload", async () => {
     const ctx = stubCalendarCtx([{ value: 1100, lastSoftWarnedAt: null }]);
-    const write = mock(async () => ({ isSuccess: true, data: {} }));
-    (ctx as unknown as { write: typeof write }).write = write;
     const notify = mock();
 
-    const result = await enforceCapAndMaybeNotify(ctx, { ...baseOpts, notify });
-    expect(result.state).toBe("soft-hit");
+    await expect(enforceCapAndMaybeNotify(ctx, { ...baseOpts, notify })).rejects.toThrow();
     expect(notify).toHaveBeenCalledTimes(1);
     expect(notify).toHaveBeenCalledWith({
       capName: "mails-per-month",
@@ -311,11 +313,6 @@ describe("enforceCapAndMaybeNotify — calendar", () => {
       limit: 1000,
       tenantId: "tenant-test",
     });
-    expect(write).toHaveBeenCalledTimes(1);
-    expect(write).toHaveBeenCalledWith("cap-counter:write:mark-soft-warned", {
-      capName: "mails-per-month",
-      periodStartIso: PERIOD,
-    });
   });
 
   test("soft-hit, crossed=false (already warned) → notifier NICHT erneut aufgerufen", async () => {

package/src/cap-counter/__tests__/stock-cap-guard.integration.test.ts

@@ -1,20 +1,29 @@
 // Regression test for the tenant-scope override bug: checkStockCap used to
 // spread `spec.where` AFTER the injected `tenantId`, so a `where` object
 // carrying its own `tenantId` key silently overrode the caller's real tenant
-// and the count ran against the wrong tenant's rows.
+// and the count ran against the wrong tenant's rows. fw#2854: checkStockCap
+// now takes a TenantDb (not a raw DbRunner + explicit tenantId) — the
+// tenant-scoping guarantee comes from TenantDb.count's own readWhere
+// narrowing instead of a hand-rolled spread order.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
-import { createEntityExecutor, type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { createTenantDb, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntityExecutor,
+  defineFeature,
+  type SessionUser,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
+  createTestUser,
   setupTestStack,
   type TestStack,
   testTenantId,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
+import { z } from "zod";
 import { capCounterEntity } from "../entity";
 import { createStockCapGuard } from "../stock-cap-guard";
 
@@ -62,7 +71,7 @@ describe("checkStockCap tenant scoping", () => {
     }
 
     const guard = createStockCapGuard(async () => ({}));
-    const failure = await guard.checkStockCap(db, realTenant, {
+    const failure = await guard.checkStockCap(createTenantDb(db, realTenant), {
       table: capCounterTable,
       limit: () => 1,
       // A where object that (accidentally or maliciously) carries its own
@@ -84,7 +93,7 @@ describe("checkStockCap tenant scoping", () => {
     }
 
     const guard = createStockCapGuard(async () => ({}));
-    const failure = await guard.checkStockCap(db, tenant, {
+    const failure = await guard.checkStockCap(createTenantDb(db, tenant), {
       table: capCounterTable,
       limit: () => 1,
       where: { capName: "x" },
@@ -96,3 +105,111 @@ describe("checkStockCap tenant scoping", () => {
     expect(failure).not.toBeNull();
   });
 });
+
+// =============================================================================
+// withStockCap over HTTP — proves the guard works end-to-end through the
+// real dispatcher for a TenantAdmin-only handler with no escapeHatch (fw#2854
+// withStockCap no longer declares one — checkStockCap resolves through the
+// caller's own TenantDb, no unfiltered read needed).
+// =============================================================================
+
+const STOCK_LIMIT = 2;
+const stockGuard = createStockCapGuard(async () => ({ maxItems: STOCK_LIMIT }));
+
+const createItemSchema = z.object({ capName: z.string() });
+
+const createItemHandler: WriteHandlerDef = {
+  name: "create-item",
+  schema: createItemSchema,
+  access: { roles: ["TenantAdmin"] },
+  handler: async (event, ctx) => {
+    const payload = event.payload as z.infer<typeof createItemSchema>; // @cast-boundary engine-payload
+    return executor.create(
+      {
+        tenantId: event.user.tenantId,
+        capName: payload.capName,
+        value: 0,
+        periodStart: "2026-07-01T00:00:00Z",
+      },
+      event.user,
+      ctx.db,
+    );
+  },
+};
+
+const guardedCreateItemHandler = stockGuard.withStockCap(createItemHandler, {
+  table: capCounterTable,
+  limit: (caps: { maxItems: number }) => caps.maxItems,
+  where: { capName: "http-stock-item" },
+  code: "stock_cap_exceeded",
+  i18nKey: "cap.stock-exceeded",
+  field: "capName",
+});
+
+const STOCK_ITEM_QN = "stock-item:write:create-item";
+const stockItemFeature = defineFeature("stock-item", (r) => {
+  r.writeHandler(guardedCreateItemHandler);
+});
+
+describe("withStockCap over HTTP — TenantAdmin-only caller, no escapeHatch", () => {
+  let httpStack: TestStack;
+
+  beforeAll(async () => {
+    httpStack = await setupTestStack({ features: [stockItemFeature] });
+    await unsafeCreateEntityTable(httpStack.db, capCounterEntity, "cap-counter");
+    await createEventsTable(httpStack.db);
+  });
+
+  afterAll(async () => {
+    await httpStack.cleanup();
+  });
+
+  beforeEach(async () => {
+    await resetTestTables(httpStack.db, [capCounterTable, eventsTable]);
+  });
+
+  function tenantAdminOnlyFor(tenantNumber: number) {
+    return createTestUser({
+      id: tenantNumber,
+      tenantId: testTenantId(tenantNumber),
+      roles: ["TenantAdmin"],
+    });
+  }
+
+  test("tenant A reaches its cap over HTTP and gets the failure", async () => {
+    const admin = tenantAdminOnlyFor(3101);
+
+    await httpStack.http.writeOk(STOCK_ITEM_QN, { capName: "http-stock-item" }, admin);
+    await httpStack.http.writeOk(STOCK_ITEM_QN, { capName: "http-stock-item" }, admin);
+
+    const error = await httpStack.http.writeErr(
+      STOCK_ITEM_QN,
+      { capName: "http-stock-item" },
+      admin,
+    );
+    expect(error.httpStatus).toBe(422);
+    expect(error.i18nKey).toBe("cap.stock-exceeded");
+    expect(error.details).toMatchObject({ reason: "stock_cap_exceeded", current: 2, limit: 2 });
+  });
+
+  test("tenant B with 0 rows still succeeds (tenant isolation through the real dispatcher)", async () => {
+    const admin = tenantAdminOnlyFor(3102);
+    const other = tenantAdminOnlyFor(3103);
+
+    await httpStack.http.writeOk(STOCK_ITEM_QN, { capName: "http-stock-item" }, admin);
+    await httpStack.http.writeOk(STOCK_ITEM_QN, { capName: "http-stock-item" }, admin);
+
+    // Tenant A is now at its cap, but tenant B has zero rows of its own.
+    const created = await httpStack.http.writeOk(
+      STOCK_ITEM_QN,
+      { capName: "http-stock-item" },
+      other,
+    );
+    expect(created["data"]).toMatchObject({ capName: "http-stock-item" });
+
+    const otherCount = await createTenantDb(httpStack.db, other.tenantId).count(capCounterTable, {
+      capName: "http-stock-item",
+    });
+    expect(otherCount).toBe(1);
+  });
+});

package/src/cap-counter/__tests__/with-cap-enforcement.integration.test.ts

@@ -9,7 +9,7 @@
 //      verbrannt für gescheiterte writes)
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { createTenantDb, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntityExecutor,
   defineFeature,
@@ -25,6 +25,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/stack";
 import { resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
+import { bookCapUsage, readRollingCapUsage } from "../book-cap-usage";
 import { CapCounterQueries } from "../constants";
 import type { SoftHitNotifier } from "../enforce-cap";
 import { capCounterEntity } from "../entity";
@@ -87,9 +88,58 @@ const wrappedRolling = withRollingCapEnforcement(
 
 const NEWSLETTER_QN = "newsletter:write:send-newsletter";
 const NEWSLETTER_ROLLING_QN = "newsletter:write:send-rolling";
+
+// =============================================================================
+// TenantAdmin-only probes (fw#2854 gap): the users above carry BOTH
+// TenantAdmin and SystemAdmin, which hid the bug that enforceCapAndMaybeNotify
+// / withCapEnforcement / withRollingCapEnforcement used to dispatch
+// SystemAdmin-only handlers (ctx.write(CapCounterHandlers.increment) etc.) —
+// a plain TenantAdmin caller with no escapeHatch would have gotten
+// access_denied. These handlers carry ONLY TenantAdmin and no escapeHatch,
+// proving the in-process booking helpers (book-cap-usage.ts) work for
+// ordinary tenant callers.
+// =============================================================================
+
+const tenantOnlyInnerHandler: WriteHandlerDef = {
+  name: "send-newsletter-tenant-only",
+  schema: z.object({ to: z.string() }),
+  access: { roles: ["TenantAdmin"] },
+  handler: async (_event, _ctx) => ({ isSuccess: true as const, data: { sent: true } }),
+};
+
+const TENANT_ONLY_PERIOD = "2026-08-01T00:00:00Z";
+
+const wrappedCalendarTenantOnly = withCapEnforcement(tenantOnlyInnerHandler, () => ({
+  capName: "newsletter-cap-tenant-only",
+  periodStartIso: TENANT_ONLY_PERIOD,
+  limit: 10,
+  profile: "burstable",
+  notify: recordingNotifier,
+}));
+
+const OUTSIDE_TX_CAP_NAME = "outside-tx-booking-cap";
+const bookOutsideTxThenFailHandler: WriteHandlerDef = {
+  name: "book-outside-tx-then-fail",
+  schema: z.object({}),
+  access: { roles: ["TenantAdmin"] },
+  handler: async (_event, ctx) => {
+    await bookCapUsage(ctx, {
+      capName: OUTSIDE_TX_CAP_NAME,
+      periodStartIso: TENANT_ONLY_PERIOD,
+      outsideTransaction: true,
+    });
+    throw new Error("boom-after-booking");
+  },
+};
+
+const NEWSLETTER_TENANT_ONLY_QN = "newsletter:write:send-newsletter-tenant-only";
+const BOOK_OUTSIDE_TX_QN = "newsletter:write:book-outside-tx-then-fail";
+
 const newsletterFeature = defineFeature("newsletter", (r) => {
   r.writeHandler(wrappedCalendar);
   r.writeHandler(wrappedRolling);
+  r.writeHandler(wrappedCalendarTenantOnly);
+  r.writeHandler(bookOutsideTxThenFailHandler);
 });
 
 // =============================================================================
@@ -122,6 +172,14 @@ function adminFor(tenantNumber: number) {
   });
 }
 
+function tenantAdminOnlyFor(tenantNumber: number) {
+  return createTestUser({
+    id: tenantNumber,
+    tenantId: testTenantId(tenantNumber),
+    roles: ["TenantAdmin"],
+  });
+}
+
 async function readCounter(user: ReturnType<typeof adminFor>, capName: string, period: string) {
   return (await stack.http.queryOk(
     CapCounterQueries.getCounter,
@@ -277,3 +335,79 @@ describe("withRollingCapEnforcement — rolling", () => {
     expect(sendCallCount).toBe(7); // wrapper hat den blockierten handler NICHT gerufen
   });
 });
+
+// =============================================================================
+// TenantAdmin-only calendar callers (no SystemAdmin, no escapeHatch) — fw#2854
+// =============================================================================
+
+describe("withCapEnforcement — calendar, TenantAdmin-only callers", () => {
+  test("calendar: TenantAdmin-only caller books usage, soft-warn flag gets set, hard cap blocks", async () => {
+    const user = tenantAdminOnlyFor(2201);
+
+    // limit=10, burstable(soft=1.1,hard=1.2) → soft=11, hard=12. 12 successful
+    // calls cross the soft threshold on the 12th (pre-check sees value=11);
+    // the 13th sees value=12 >= hard and blocks.
+    for (let i = 0; i < 12; i++) {
+      await stack.http.writeOk(NEWSLETTER_TENANT_ONLY_QN, { to: `${i}@x.de` }, user);
+    }
+    const row = await readCounter(user, "newsletter-cap-tenant-only", TENANT_ONLY_PERIOD);
+    expect(row).not.toBeNull();
+    expect(row!["value"]).toBe(12);
+    expect(row!["lastSoftWarnedAt"]).not.toBeNull();
+
+    const blocked = await stack.http.writeErr(
+      NEWSLETTER_TENANT_ONLY_QN,
+      { to: "blocked@x.de" },
+      user,
+    );
+    expect(blocked.code).toBe("cap_exceeded");
+    expect(blocked.httpStatus).toBe(429);
+  });
+
+  test("tenant B's counter is unaffected by tenant A's TenantAdmin-only bookings", async () => {
+    const tenantA = tenantAdminOnlyFor(2301);
+    const tenantB = tenantAdminOnlyFor(2302);
+
+    for (let i = 0; i < 3; i++) {
+      await stack.http.writeOk(NEWSLETTER_TENANT_ONLY_QN, { to: `${i}@x.de` }, tenantA);
+    }
+
+    const rowA = await readCounter(tenantA, "newsletter-cap-tenant-only", TENANT_ONLY_PERIOD);
+    expect(rowA!["value"]).toBe(3);
+
+    const rowB = await readCounter(tenantB, "newsletter-cap-tenant-only", TENANT_ONLY_PERIOD);
+    expect(rowB).toBeNull();
+  });
+
+  test("bookCapUsage(..., outsideTransaction: true) survives the handler's own rollback", async () => {
+    const user = tenantAdminOnlyFor(2401);
+
+    const error = await stack.http.writeErr(BOOK_OUTSIDE_TX_QN, {}, user);
+    expect(error.httpStatus).toBeGreaterThanOrEqual(400);
+
+    const row = await readCounter(user, OUTSIDE_TX_CAP_NAME, TENANT_ONLY_PERIOD);
+    expect(row).not.toBeNull();
+    expect(row!["value"]).toBe(1);
+  });
+
+  test("readRollingCapUsage: tenant B reads 0 for the same capName after tenant A booked", async () => {
+    const tenantA = adminFor(2501);
+    const tenantB = adminFor(2502);
+
+    await stack.http.writeOk(NEWSLETTER_ROLLING_QN, { to: "a@x.de" }, tenantA);
+
+    const usageA = await readRollingCapUsage(
+      createTenantDb(stack.db, tenantA.tenantId),
+      tenantA.tenantId,
+      { capName: "newsletter-rolling-cap", windowDays: 7 },
+    );
+    expect(usageA).toBe(1);
+
+    const usageB = await readRollingCapUsage(
+      createTenantDb(stack.db, tenantB.tenantId),
+      tenantB.tenantId,
+      { capName: "newsletter-rolling-cap", windowDays: 7 },
+    );
+    expect(usageB).toBe(0);
+  });
+});

package/src/cap-counter/book-cap-usage.ts

@@ -0,0 +1,158 @@
+// In-process cap booking for the caller's own tenant; no SystemAdmin dispatch needed.
+
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntityExecutor,
+  type HandlerContext,
+  type TenantId,
+  type WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { Temporal } from "temporal-polyfill";
+import { z } from "zod";
+import { capCounterAggregateId, rollingCapAggregateId } from "./aggregate-id";
+import { CAP_COUNTER_ROLLING_AGGREGATE_TYPE, ROLLING_INCREMENTED_EVENT_QN } from "./constants";
+import { capCounterEntity } from "./entity";
+
+const { table, executor } = createEntityExecutor("cap-counter", capCounterEntity);
+
+const capBookingSchema = z.object({
+  capName: z.string().min(1).max(100),
+  periodStartIso: z.string().min(1),
+  amount: z.number().int().positive().default(1),
+});
+
+export type BookCapUsageOptions = {
+  readonly capName: string;
+  readonly periodStartIso: string;
+  readonly amount?: number;
+  readonly outsideTransaction?: boolean;
+};
+
+function requireOutsideTransactionDb(ctx: HandlerContext): TenantDb {
+  if (!ctx.dbOutsideTransaction) {
+    throw new Error(
+      "cap-counter.bookCapUsage: outsideTransaction requested but ctx.dbOutsideTransaction is undefined",
+    );
+  }
+  return ctx.dbOutsideTransaction;
+}
+
+export async function bookCapUsage(
+  ctx: HandlerContext,
+  options: BookCapUsageOptions,
+): Promise<WriteResult> {
+  const parsed = capBookingSchema.parse(options);
+  const db = options.outsideTransaction ? requireOutsideTransactionDb(ctx) : ctx.db;
+  const aggregateId = capCounterAggregateId(
+    ctx.user.tenantId,
+    parsed.capName,
+    parsed.periodStartIso,
+  );
+
+  const existing = await db.selectMany(table, { id: aggregateId }, { limit: 1 });
+  if (existing.length === 0) {
+    return executor.create(
+      {
+        id: aggregateId,
+        capName: parsed.capName,
+        value: parsed.amount,
+        periodStart: Temporal.Instant.from(parsed.periodStartIso),
+        lastSoftWarnedAt: null,
+      },
+      ctx.user,
+      db,
+    );
+  }
+
+  const currentRow = existing[0];
+  if (!currentRow) {
+    throw new Error("cap-counter.bookCapUsage: 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 + parsed.amount },
+    },
+    ctx.user,
+    db,
+  );
+}
+
+export type MarkCapSoftWarnedOptions = {
+  readonly capName: string;
+  readonly periodStartIso: string;
+};
+
+export async function markCapSoftWarned(
+  ctx: HandlerContext,
+  options: MarkCapSoftWarnedOptions,
+): Promise<WriteResult> {
+  const aggregateId = capCounterAggregateId(
+    ctx.user.tenantId,
+    options.capName,
+    options.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=${ctx.user.tenantId} cap=${options.capName} period=${options.periodStartIso}`,
+    );
+  }
+  const row = existing[0];
+  if (!row) {
+    throw new Error("cap-counter.markCapSoftWarned: 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() },
+    },
+    ctx.user,
+    ctx.db,
+  );
+}
+
+export type ReadRollingCapUsageOptions = {
+  readonly capName: string;
+  readonly windowDays: number;
+};
+
+// Sums usage without throwing — for callers that only need the raw number
+// (e.g. a CapSpec.usage callback), not the enforce-and-throw path.
+export async function readRollingCapUsage(
+  db: TenantDb,
+  tenantId: TenantId,
+  options: ReadRollingCapUsageOptions,
+): Promise<number> {
+  const aggregateId = rollingCapAggregateId(tenantId, options.capName);
+  const cutoff = Temporal.Now.instant().subtract({ hours: options.windowDays * 24 });
+
+  const rows = await db.selectMany<{ payload: { amount?: number } }>(eventsTable, {
+    tenantId,
+    aggregateType: CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
+    aggregateId,
+    type: ROLLING_INCREMENTED_EVENT_QN,
+    createdAt: { gte: cutoff },
+  });
+
+  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 mirrors enforceRollingCap's own read-side contract.
+    const payload = row["payload"] as { amount?: number };
+    if (typeof payload.amount === "number") {
+      value += payload.amount;
+    }
+  }
+
+  return value;
+}

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/tier-engine/__tests__/tier-resolver.integration.test.ts

@@ -0,0 +1,138 @@
+// createTierResolver (fw#2854): resolveTier/resolveTierCaps take only a
+// TenantDb — the tenant comes from db.tenantId, so a caller can't request a
+// foreign tenant's tier. Proves defaultTier for an unassigned tenant, the
+// assigned tier for an assigned one, and the same behavior end-to-end
+// through a TenantAdmin-only query handler with no escapeHatch.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { configValuesTable } from "@cosmicdrift/kumiko-bundled-features/config";
+import { tenantSecretsTable } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { tenantMembershipsTable, tenantTable } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { userTable } from "@cosmicdrift/kumiko-bundled-features/user";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { buildEntityTable, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { defineFeature, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";
+import { z } from "zod";
+import { tierAssignmentEntity } from "../entity";
+import { tierEngineFeature } from "../feature";
+import { createTierResolver } from "../tier-resolver";
+
+type TestCaps = { readonly maxItems: number };
+type TestTier = "free" | "pro";
+
+function isTestTierName(value: string): value is TestTier {
+  return value === "free" || value === "pro";
+}
+
+function capsForTier(tier: TestTier): TestCaps {
+  return tier === "pro" ? { maxItems: 5 } : { maxItems: 1 };
+}
+
+const { resolveTier, resolveTierCaps } = createTierResolver<TestTier, TestCaps>({
+  capsForTier,
+  isTierName: isTestTierName,
+  defaultTier: "free",
+});
+
+const RESOLVED_CAPS_QN = "resolver-probe:query:resolved-caps";
+const resolverProbeFeature = defineFeature("resolver-probe", (r) => {
+  r.queryHandler({
+    name: "resolved-caps",
+    schema: z.object({}),
+    access: { roles: ["TenantAdmin"] },
+    handler: async (_query, ctx) => resolveTierCaps(ctx.db),
+  });
+});
+
+const features = composeFeatures([tierEngineFeature, resolverProbeFeature], {
+  includeBundled: true,
+});
+
+// Same underlying table createTierResolver builds internally — pushed here
+// so the schema exists before the write-handler + resolver read it.
+const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEntity);
+
+let stack: TestStack;
+const tenantA = "00000000-0000-4000-8000-0000000000c1" as TenantId;
+const tenantB = "00000000-0000-4000-8000-0000000000c2" as TenantId;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features });
+  await unsafePushTables(stack.db, {
+    config_values: configValuesTable,
+    users: userTable,
+    tenants: tenantTable,
+    tenant_memberships: tenantMembershipsTable,
+    tenant_secrets: tenantSecretsTable,
+    tier_assignments: tierAssignmentTable,
+  });
+});
+
+afterAll(async () => stack?.cleanup());
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`TRUNCATE read_tier_assignments RESTART IDENTITY CASCADE`);
+});
+
+function sysAdminFor(tenantId: TenantId) {
+  return createTestUser({ id: `sys-${tenantId}`, tenantId, roles: ["SystemAdmin", "TenantAdmin"] });
+}
+
+function tenantAdminOnlyFor(tenantId: TenantId) {
+  return createTestUser({ id: `admin-${tenantId}`, tenantId, roles: ["TenantAdmin"] });
+}
+
+async function assignTier(tenantId: TenantId, tier: TestTier): Promise<void> {
+  await stack.http.writeOk(
+    "tier-engine:write:tier-assignment:create",
+    { tier },
+    sysAdminFor(tenantId),
+  );
+}
+
+describe("createTierResolver — resolveTier/resolveTierCaps", () => {
+  test("unassigned tenant B resolves to defaultTier, not tenant A's assigned tier", async () => {
+    await assignTier(tenantA, "pro");
+
+    const tierA = await resolveTier(createTenantDb(stack.db, tenantA));
+    expect(tierA).toBe("pro");
+
+    const tierB = await resolveTier(createTenantDb(stack.db, tenantB));
+    expect(tierB).toBe("free");
+  });
+
+  test("resolveTierCaps maps the resolved tier via capsForTier", async () => {
+    await assignTier(tenantA, "pro");
+
+    const capsA = await resolveTierCaps(createTenantDb(stack.db, tenantA));
+    expect(capsA).toEqual({ maxItems: 5 });
+
+    const capsB = await resolveTierCaps(createTenantDb(stack.db, tenantB));
+    expect(capsB).toEqual({ maxItems: 1 });
+  });
+
+  test("end-to-end via a TenantAdmin-only query handler (no escapeHatch)", async () => {
+    await assignTier(tenantA, "pro");
+
+    const capsA = await stack.http.queryOk<TestCaps>(
+      RESOLVED_CAPS_QN,
+      {},
+      tenantAdminOnlyFor(tenantA),
+    );
+    expect(capsA).toEqual({ maxItems: 5 });
+
+    const capsB = await stack.http.queryOk<TestCaps>(
+      RESOLVED_CAPS_QN,
+      {},
+      tenantAdminOnlyFor(tenantB),
+    );
+    expect(capsB).toEqual({ maxItems: 1 });
+  });
+});

package/src/tier-engine/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.278.0",
+    "type": "breaking",
+    "title": "createTierResolver's resolveTier/resolveTierCaps take only a TenantDb — no separate tenantId argument (fw#2854).",
+    "detail": "`resolveTier(db)` and `resolveTierCaps(db)` (from `createTierResolver`) now read the tenant from `db.tenantId` instead of taking a second `tenantId` parameter, so a caller can no longer pass a `TenantDb` for one tenant alongside a different `tenantId` and resolve a foreign tenant's tier.",
+    "migration": "`resolveTier(ctx.db.raw|runner, tenantId)` → `resolveTier(ctx.db)` (same for `resolveTierCaps`). Outside a handler: `resolveTier(createTenantDb(runner, tenantId))`."
+  },
   {
     "version": "0.241.0",
     "type": "breaking",

package/src/tier-engine/tier-resolver.ts

@@ -3,8 +3,7 @@
 // only per-app variables were the TierName union and its caps/defaults, so
 // both are now factory parameters.
 
-import { buildEntityTable, type DbRunner, fetchOne } from "@cosmicdrift/kumiko-framework/db";
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { buildEntityTable, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { tierAssignmentEntity } from "./entity";
 
 export type TierResolverDeps<TTier extends string, TCaps> = {
@@ -18,14 +17,16 @@ export function createTierResolver<TTier extends string, TCaps>(
 ) {
   const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEntity);
 
-  async function resolveTier(db: DbRunner, tenantId: TenantId): Promise<TTier> {
-    const row = await fetchOne<{ tier?: unknown }>(db, tierAssignmentTable, { tenantId });
+  async function resolveTier(db: TenantDb): Promise<TTier> {
+    const row = await db.fetchOne<{ tier?: unknown }>(tierAssignmentTable, {
+      tenantId: db.tenantId,
+    });
     const tier = row?.tier;
     return typeof tier === "string" && deps.isTierName(tier) ? tier : deps.defaultTier;
   }
 
-  async function resolveTierCaps(db: DbRunner, tenantId: TenantId): Promise<TCaps> {
-    return deps.capsForTier(await resolveTier(db, tenantId));
+  async function resolveTierCaps(db: TenantDb): Promise<TCaps> {
+    return deps.capsForTier(await resolveTier(db));
   }
 
   return { tierAssignmentTable, resolveTier, resolveTierCaps };