@cosmicdrift/kumiko-bundled-features 0.277.0 → 0.280.0

package/package.json

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

package/src/auth-email-password/__tests__/invite-flow-kms.integration.test.ts

@@ -14,6 +14,7 @@ import {
   InMemoryKmsAdapter,
   isPiiCiphertext,
 } from "@cosmicdrift/kumiko-framework/crypto";
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -319,7 +320,7 @@ describe("auth flows with active KMS + blind index", () => {
     expect(isPiiCiphertext(rawInvitation["email"])).toBe(true);
 
     const result = await tenantInvitationExportHook({
-      db: stack.db,
+      db: createTenantDb(stack.db, TENANT_A_ID, "tenant"),
       registry: stack.registry,
       tenantId: TENANT_A_ID,
       userId: bobId,
@@ -347,7 +348,12 @@ describe("auth flows with active KMS + blind index", () => {
     expect(isPiiCiphertext(rawBefore["invited_by"])).toBe(true);
 
     await tenantInvitationDeleteHook(
-      { db: stack.db, registry: stack.registry, tenantId: TENANT_A_ID, userId: aliceId },
+      {
+        db: createTenantDb(stack.db, TENANT_A_ID, "tenant"),
+        registry: stack.registry,
+        tenantId: TENANT_A_ID,
+        userId: aliceId,
+      },
       "delete",
     );
 

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

@@ -3,7 +3,7 @@
 // (not just leave it dangling for a future projection rebuild to resurrect).
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import { configureEntityFieldEncryption, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import {
   createTestUser,
   setupTestStack,
@@ -77,7 +77,7 @@ describe("userMfaExportHook / userMfaDeleteHook", () => {
     const user = await enrollUser("export-1");
 
     const snippet = await userMfaExportHook({
-      db: stack.db,
+      db: createTenantDb(stack.db, user.tenantId, "tenant"),
       registry: stack.registry,
       tenantId: user.tenantId,
       userId: user.id,
@@ -94,7 +94,7 @@ describe("userMfaExportHook / userMfaDeleteHook", () => {
   test("export returns null for a user who never enrolled", async () => {
     const user = createTestUser({ id: "never-enrolled", roles: ["User"] });
     const snippet = await userMfaExportHook({
-      db: stack.db,
+      db: createTenantDb(stack.db, user.tenantId, "tenant"),
       registry: stack.registry,
       tenantId: user.tenantId,
       userId: user.id,
@@ -106,7 +106,7 @@ describe("userMfaExportHook / userMfaDeleteHook", () => {
     const user = await enrollUser("delete-1");
 
     const before = await userMfaExportHook({
-      db: stack.db,
+      db: createTenantDb(stack.db, user.tenantId, "tenant"),
       registry: stack.registry,
       tenantId: user.tenantId,
       userId: user.id,
@@ -115,7 +115,7 @@ describe("userMfaExportHook / userMfaDeleteHook", () => {
 
     await userMfaDeleteHook(
       {
-        db: stack.db,
+        db: createTenantDb(stack.db, user.tenantId, "tenant"),
         registry: stack.registry,
         tenantId: user.tenantId,
         userId: user.id,
@@ -124,7 +124,7 @@ describe("userMfaExportHook / userMfaDeleteHook", () => {
     );
 
     const after = await userMfaExportHook({
-      db: stack.db,
+      db: createTenantDb(stack.db, user.tenantId, "tenant"),
       registry: stack.registry,
       tenantId: user.tenantId,
       userId: user.id,

package/src/auth-mfa-user-data/hooks.ts

@@ -7,8 +7,7 @@
 // replays via the event, a raw DELETE would be resurrected by a
 // projection rebuild).
 
-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 UserDataDeleteHook,
@@ -26,7 +25,7 @@ const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
 // tokenHash exclusion in user-data-rights-defaults). Just confirms
 // enrollment + when, which is what a data subject actually needs to see.
 export const userMfaExportHook: UserDataExportHook = async (ctx) => {
-  const rows = await selectMany<{ id: string; enabledAt: unknown }>(ctx.db, userMfaTable, {
+  const rows = await ctx.db.selectMany<{ id: string; enabledAt: unknown }>(userMfaTable, {
     userId: ctx.userId,
     tenantId: ctx.tenantId,
   });
@@ -41,15 +40,14 @@ export const userMfaExportHook: UserDataExportHook = async (ctx) => {
 // secret can't be anonymized, and `personal: { of: "userId" }` already
 // means this row belongs to exactly one user (never shared tenant data).
 export const userMfaDeleteHook: UserDataDeleteHook = async (ctx) => {
-  const rows = await selectMany<{ id: string }>(ctx.db, userMfaTable, {
+  const rows = await ctx.db.selectMany<{ id: string }>(userMfaTable, {
     userId: ctx.userId,
     tenantId: ctx.tenantId,
   });
   // skip: nothing enrolled for this user — no row to erase
   if (rows.length === 0) return;
   const systemUser = createSystemUser(ctx.tenantId);
-  const tdb = createTenantDb(ctx.db, ctx.tenantId, "system");
   for (const row of rows) {
-    assertErased(await executor.forget({ id: row.id }, systemUser, tdb), "user-mfa", row.id);
+    assertErased(await executor.forget({ id: row.id }, systemUser, ctx.db), "user-mfa", row.id);
   }
 };

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;
+}