@cosmicdrift/kumiko-samples 0.356.0 → 0.358.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.356.0",
+  "version": "0.358.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.356.0",
+  "version": "0.358.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>",

package/packages/bundled-features/src/auth-mfa/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.357.0",
+    "type": "improvement",
+    "title": "MFA enable asks to confirm saved recovery codes, code field autocompletes one-time codes",
+    "detail": "secretMint `reveal.acknowledge` (i18n key) renders a checkbox on the reveal card that must be ticked before the confirm step or the acknowledge button can be used; the tick never reaches the payload. Text fields accept an `autoComplete` token that reaches the input. The MFA enable screen uses both: a \"saved my recovery codes\" gate and `one-time-code` on the code field"
+  },
   {
     "version": "0.354.0",
     "type": "breaking",

package/packages/bundled-features/src/auth-mfa/i18n.ts

@@ -28,6 +28,7 @@ export const AUTH_MFA_FEATURE_I18N: Readonly<Record<string, LocalizedString>> =
   "mfa.enable.reveal.qr": { en: "Scan this QR code" },
   "mfa.enable.reveal.secret": { en: "Or enter this code manually" },
   "mfa.enable.reveal.recoveryCodes": { en: "Recovery codes" },
+  "mfa.enable.reveal.savedCodes": { en: "I have saved my recovery codes." },
 
   "mfa.enable.confirm.submit": { en: "Enable" },
   "mfa.enable.confirm.done": { en: "Two-factor authentication is now enabled." },

package/packages/bundled-features/src/auth-mfa/screens.ts

@@ -34,6 +34,7 @@ export const mfaEnableScreen: SecretMintScreenDefinition = {
   reveal: {
     title: i18nKey("mfa.enable.reveal.title"),
     warning: i18nKey("mfa.enable.reveal.warning"),
+    acknowledge: i18nKey("mfa.enable.reveal.savedCodes"),
     fields: [
       {
         field: "otpauthUri",
@@ -58,7 +59,13 @@ export const mfaEnableScreen: SecretMintScreenDefinition = {
   confirm: {
     handler: AuthMfaHandlers.enableConfirm,
     fields: {
-      code: { type: "text", required: true, minLength: 6, maxLength: 6 },
+      code: {
+        type: "text",
+        required: true,
+        minLength: 6,
+        maxLength: 6,
+        autoComplete: "one-time-code",
+      },
     },
     layout: { sections: [{ fields: ["code"] }] },
     carry: ["setupToken"],

package/packages/bundled-features/src/cap-counter/book-cap-usage.ts

@@ -4,10 +4,12 @@ import { runInOwnTransaction, type TenantDb } from "@cosmicdrift/kumiko-framewor
 import {
   createEntityExecutor,
   type HandlerContext,
+  type JobContext,
   type SessionUser,
   type TenantId,
   type WriteResult,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
 import { eventsTable, VersionConflictError } from "@cosmicdrift/kumiko-framework/event-store";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
@@ -82,17 +84,69 @@ export type BookCapUsageOptions = {
   readonly guardCurrentValue?: (currentValue: number) => void;
 };
 
-export function requireOutsideTransactionDb(ctx: HandlerContext): TenantDb {
-  if (!ctx.dbOutsideTransaction) {
+export type CapCounterContext = HandlerContext | JobContext;
+
+export type CapCounterScope = {
+  readonly user: SessionUser;
+  readonly readDb: TenantDb;
+  readonly writeDb: TenantDb;
+};
+
+// A tenant-mode db pins every row it writes to its own tenant; counter and reservation row would
+// silently land on different tenants if that is not the user's.
+function assertDbServesUser(db: TenantDb, user: SessionUser): TenantDb {
+  if (db.mode === "tenant" && db.tenantId !== user.tenantId) {
+    throw new AccessDeniedError({
+      message: "cap-counter: the context's database belongs to a different tenant than its user",
+    });
+  }
+  return db;
+}
+
+// Jobs write in place (their db is not transaction-bound); systemScope handlers reach both dbs via
+// systemDb, because their ctx.db / ctx.dbOutsideTransaction are fail-closed proxies.
+export function resolveCapCounterScope(
+  ctx: CapCounterContext,
+  outsideTransaction: boolean,
+): CapCounterScope {
+  // A job context spread into a handler-shaped one (user set) is a handler context: its user, not
+  // the job's systemUser, names the metered tenant.
+  if (!("user" in ctx) || !ctx.user) {
+    const jobUser = "systemUser" in ctx ? ctx.systemUser : undefined;
+    if (!jobUser) {
+      throw new Error("cap-counter: ctx.user.tenantId missing — required to resolve the counter");
+    }
+    const db = assertDbServesUser(ctx.db, jobUser);
+    return { user: jobUser, readDb: db, writeDb: db };
+  }
+  const { user } = ctx;
+  if (!user.tenantId) {
+    throw new Error("cap-counter: ctx.user.tenantId missing — required to resolve the counter");
+  }
+  if (ctx.systemDb) {
+    const readDb = ctx.systemDb.assertTenantMatch(user.tenantId);
+    const writeDb = outsideTransaction
+      ? ctx.systemDb.outsideTransaction.assertTenantMatch(user.tenantId)
+      : readDb;
+    return { user, readDb, writeDb };
+  }
+  const writeDb = outsideTransaction ? ctx.dbOutsideTransaction : ctx.db;
+  if (!writeDb) {
     throw new Error(
-      "cap-counter.bookCapUsage: outsideTransaction requested but ctx.dbOutsideTransaction is undefined",
+      outsideTransaction
+        ? "cap-counter: outsideTransaction requested but ctx.dbOutsideTransaction is undefined"
+        : "cap-counter: ctx.db missing — run inside a handler context",
     );
   }
-  return ctx.dbOutsideTransaction;
+  return {
+    user,
+    readDb: assertDbServesUser(ctx.db, user),
+    writeDb: assertDbServesUser(writeDb, user),
+  };
 }
 
 export async function bookCapUsage(
-  ctx: HandlerContext,
+  ctx: CapCounterContext,
   options: BookCapUsageOptions,
 ): Promise<WriteResult> {
   return applyCapDelta(ctx, options, "add");
@@ -100,7 +154,7 @@ export async function bookCapUsage(
 
 // Gives back a reservation whose operation failed afterwards; the counter never drops below 0.
 export async function releaseCapUsage(
-  ctx: HandlerContext,
+  ctx: CapCounterContext,
   options: Omit<BookCapUsageOptions, "guardCurrentValue">,
 ): Promise<WriteResult> {
   return applyCapDelta(ctx, options, "subtract");
@@ -157,18 +211,18 @@ export async function applyCapDeltaOn(
 }
 
 async function applyCapDelta(
-  ctx: HandlerContext,
+  ctx: CapCounterContext,
   options: BookCapUsageOptions,
   direction: "add" | "subtract",
 ): Promise<WriteResult> {
+  const { user, writeDb } = resolveCapCounterScope(ctx, options.outsideTransaction === true);
   if (options.outsideTransaction) {
-    const outsideDb = requireOutsideTransactionDb(ctx);
     return retryCounterWriteOnVersionConflict(() =>
-      runInOwnTransaction(outsideDb, (txDb) => applyCapDeltaOn(txDb, ctx.user, options, direction)),
+      runInOwnTransaction(writeDb, (txDb) => applyCapDeltaOn(txDb, user, options, direction)),
     );
   }
   return retryCounterWriteOnVersionConflict(() =>
-    applyCapDeltaOn(ctx.db, ctx.user, options, direction),
+    applyCapDeltaOn(writeDb, user, options, direction),
   );
 }
 
@@ -179,21 +233,18 @@ export type MarkCapSoftWarnedOptions = {
 };
 
 export async function markCapSoftWarned(
-  ctx: HandlerContext,
+  ctx: CapCounterContext,
   options: MarkCapSoftWarnedOptions,
 ): Promise<WriteResult> {
   const parsed = capPeriodSchema.parse(options);
-  const aggregateId = capCounterAggregateId(
-    ctx.user.tenantId,
-    parsed.capName,
-    parsed.periodStartIso,
-  );
+  const { user, writeDb } = resolveCapCounterScope(ctx, options.outsideTransaction === true);
+  const aggregateId = capCounterAggregateId(user.tenantId, parsed.capName, parsed.periodStartIso);
 
   async function attemptMark(db: TenantDb): Promise<WriteResult> {
     const existing = await 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=${parsed.capName} period=${parsed.periodStartIso}`,
+        `cap-counter: cannot mark-soft-warned, no counter found for tenant=${user.tenantId} cap=${parsed.capName} period=${parsed.periodStartIso}`,
       );
     }
     const row = existing[0];
@@ -213,16 +264,15 @@ export async function markCapSoftWarned(
         version: currentVersion,
         changes: { lastSoftWarnedAt: Temporal.Now.instant() },
       },
-      ctx.user,
+      user,
       db,
     );
   }
 
   if (options.outsideTransaction) {
-    const outsideDb = requireOutsideTransactionDb(ctx);
-    return retryCounterWriteOnVersionConflict(() => runInOwnTransaction(outsideDb, attemptMark));
+    return retryCounterWriteOnVersionConflict(() => runInOwnTransaction(writeDb, attemptMark));
   }
-  return retryCounterWriteOnVersionConflict(() => attemptMark(ctx.db));
+  return retryCounterWriteOnVersionConflict(() => attemptMark(writeDb));
 }
 
 export type ReadRollingCapUsageOptions = {

package/packages/bundled-features/src/cap-counter/calendar-cap-usage-reservation.ts

@@ -0,0 +1,99 @@
+import type { CapCounterContext } from "./book-cap-usage.js";
+import {
+  type CalendarCapReservation,
+  releaseExpiredCapReservations,
+  reserveCalendarCap,
+  settleCalendarCapReservation,
+} from "./cap-reservation.js";
+import {
+  assertBelowHardCap,
+  enforceCapAndMaybeNotify,
+  type SoftHitNotifier,
+} from "./enforce-cap.js";
+import type { CalendarCapDef } from "./with-cap-enforcement.js";
+
+export type CalendarCapUsageReservationSpec = Omit<CalendarCapDef, "amount" | "notify"> & {
+  readonly amount: number;
+  readonly notify?: SoftHitNotifier;
+  // Default true: the reservation must commit on its own, not roll back with the caller's transaction.
+  readonly outsideTransaction?: boolean;
+};
+
+export type CalendarCapUsageReservation = {
+  readonly amount: number;
+  // Counter value right after this reservation was booked.
+  readonly counterValue: number;
+  // Replaces the reserved amount with the actual one; rejects a second settle and one after release.
+  settle(actualAmount: number): Promise<void>;
+  // Gives the reserved amount back; a no-op once settled.
+  release(): Promise<void>;
+};
+
+// Shared by withCapEnforcement and the public reservation API so both enforce identically.
+export async function reserveEnforcedCalendarCap(
+  ctx: CapCounterContext,
+  cap: CalendarCapUsageReservationSpec,
+): Promise<CalendarCapReservation> {
+  const outsideTransaction = cap.outsideTransaction ?? true;
+  await releaseExpiredCapReservations(ctx, cap.capName, outsideTransaction);
+  if (cap.notify) {
+    await enforceCapAndMaybeNotify(ctx, {
+      capName: cap.capName,
+      periodStartIso: cap.periodStartIso,
+      limit: cap.limit,
+      profile: cap.profile,
+      notify: cap.notify,
+      amount: cap.amount,
+      markSoftWarnedOutsideTransaction: outsideTransaction,
+    });
+  }
+  return reserveCalendarCap(
+    ctx,
+    {
+      capName: cap.capName,
+      amount: cap.amount,
+      periodStartIso: cap.periodStartIso,
+      guardCurrentValue: (currentValue) => assertBelowHardCap(currentValue + cap.amount - 1, cap),
+    },
+    outsideTransaction,
+  );
+}
+
+type ReservationState = "open" | "settled" | "released";
+
+export async function reserveCalendarCapUsage(
+  ctx: CapCounterContext,
+  spec: CalendarCapUsageReservationSpec,
+): Promise<CalendarCapUsageReservation> {
+  const outsideTransaction = spec.outsideTransaction ?? true;
+  const reservation = await reserveEnforcedCalendarCap(ctx, spec);
+  let state: ReservationState = "open";
+
+  return {
+    amount: spec.amount,
+    counterValue: reservation.counterValue,
+    async settle(actualAmount) {
+      if (state !== "open") {
+        throw new Error(`cap-counter: reservation for "${spec.capName}" is already ${state}`);
+      }
+      state = "settled";
+      try {
+        await settleCalendarCapReservation(
+          ctx,
+          reservation.reservationId,
+          { capName: spec.capName, periodStartIso: spec.periodStartIso, actualAmount },
+          outsideTransaction,
+        );
+      } catch (error) {
+        state = "open";
+        throw error;
+      }
+    },
+    async release() {
+      // skip: release after settle, or a second release, is a no-op by contract.
+      if (state !== "open") return;
+      await reservation.release();
+      state = "released";
+    },
+  };
+}

package/packages/bundled-features/src/cap-counter/cap-reservation.ts

@@ -1,9 +1,5 @@
 import { deleteMany, runInOwnTransaction, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
-import type {
-  HandlerContext,
-  SessionUser,
-  WriteResult,
-} from "@cosmicdrift/kumiko-framework/engine";
+import type { SessionUser, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
 import { reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
 import {
   appendEventInTenantDb,
@@ -19,9 +15,10 @@ import { rollingCapAggregateId } from "./aggregate-id.js";
 import {
   applyCapDeltaOn,
   type BookCapUsageOptions,
+  type CapCounterContext,
   type ReadRollingCapUsageOptions,
   readRollingCapUsage,
-  requireOutsideTransactionDb,
+  resolveCapCounterScope,
   retryCounterWriteOnVersionConflict,
   retryOnStreamVersionConflict,
 } from "./book-cap-usage.js";
@@ -47,10 +44,16 @@ const NOTHING_TO_RELEASE: WriteResult = { isSuccess: true, data: {} };
 type ReservationRowDraft = Pick<CapReservationRow, "capName" | "kind" | "amount"> &
   Pick<Partial<CapReservationRow>, "periodStartIso">;
 
-async function insertReservationRow(txDb: TenantDb, id: string, draft: ReservationRowDraft) {
+async function insertReservationRow(
+  txDb: TenantDb,
+  user: SessionUser,
+  id: string,
+  draft: ReservationRowDraft,
+) {
   const now = Temporal.Now.instant();
   await txDb.insertOne(capReservationsTable, {
     id,
+    tenantId: user.tenantId,
     capName: draft.capName,
     kind: draft.kind,
     periodStartIso: draft.periodStartIso ?? null,
@@ -60,9 +63,19 @@ async function insertReservationRow(txDb: TenantDb, id: string, draft: Reservati
   });
 }
 
-function toHandle(ctx: HandlerContext, id: string): ReservationHandle {
+export type CalendarCapReservation = ReservationHandle & {
+  readonly reservationId: string;
+  // Counter value right after this reservation was booked.
+  readonly counterValue: number;
+};
+
+function toHandle(
+  ctx: CapCounterContext,
+  id: string,
+  outsideTransaction: boolean,
+): ReservationHandle {
   return {
-    release: () => releaseCapReservation(ctx, id),
+    release: () => releaseCapReservation(ctx, id, outsideTransaction),
     confirmInTransaction: (confirm) => confirmCapReservation(confirm, id),
   };
 }
@@ -75,16 +88,26 @@ export type ReserveCalendarCapOptions = Required<
 // The counter increment and the reservation row commit together, so a booked amount never exists
 // without a row that can give it back.
 export async function reserveCalendarCap(
-  ctx: HandlerContext,
+  ctx: CapCounterContext,
   options: ReserveCalendarCapOptions,
-): Promise<ReservationHandle> {
-  const outsideDb = requireOutsideTransactionDb(ctx);
+  outsideTransaction = true,
+): Promise<CalendarCapReservation> {
+  const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
   const id = generateId();
+  // The last attempt is the one that committed, so this holds the value its increment started from.
+  let valueBeforeBooking = 0;
+  const observedOptions: ReserveCalendarCapOptions = {
+    ...options,
+    guardCurrentValue: (currentValue) => {
+      options.guardCurrentValue?.(currentValue);
+      valueBeforeBooking = currentValue;
+    },
+  };
   const reserved = await retryCounterWriteOnVersionConflict(() =>
-    runInOwnTransaction(outsideDb, async (txDb) => {
-      const booked = await applyCapDeltaOn(txDb, ctx.user, options, "add");
+    runInOwnTransaction(writeDb, async (txDb) => {
+      const booked = await applyCapDeltaOn(txDb, user, observedOptions, "add");
       if (!booked.isSuccess) return booked;
-      await insertReservationRow(txDb, id, {
+      await insertReservationRow(txDb, user, id, {
         capName: options.capName,
         kind: "calendar",
         periodStartIso: options.periodStartIso,
@@ -94,7 +117,11 @@ export async function reserveCalendarCap(
     }),
   );
   if (!reserved.isSuccess) throw reraiseAsKumikoError(reserved.error);
-  return toHandle(ctx, id);
+  return {
+    ...toHandle(ctx, id, outsideTransaction),
+    reservationId: id,
+    counterValue: valueBeforeBooking + options.amount,
+  };
 }
 
 export type ReserveRollingCapOptions = ReadRollingCapUsageOptions & {
@@ -123,28 +150,23 @@ function rollingEvent(
 // The append is version-guarded: a booker that read the usage before another one appended loses the
 // race and repeats the whole attempt, so the hard-cap check always sees the stream it appends to.
 export async function reserveRollingCap(
-  ctx: HandlerContext,
+  ctx: CapCounterContext,
   options: ReserveRollingCapOptions,
+  outsideTransaction = true,
 ): Promise<ReservationHandle> {
-  const outsideDb = requireOutsideTransactionDb(ctx);
+  const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
   const id = generateId();
-  const aggregateId = rollingCapAggregateId(ctx.user.tenantId, options.capName);
+  const aggregateId = rollingCapAggregateId(user.tenantId, options.capName);
   await retryOnStreamVersionConflict(() =>
-    runInOwnTransaction(outsideDb, async (txDb) => {
+    runInOwnTransaction(writeDb, async (txDb) => {
       const version = await getStreamVersionInTenantDb(txDb, aggregateId);
-      const usage = await readRollingCapUsage(txDb, ctx.user.tenantId, options);
+      const usage = await readRollingCapUsage(txDb, user.tenantId, options);
       options.guardCurrentValue?.(usage);
       await appendEventInTenantDb(
         txDb,
-        rollingEvent(
-          ctx.user,
-          options.capName,
-          options.amount,
-          version,
-          ROLLING_INCREMENTED_EVENT_QN,
-        ),
+        rollingEvent(user, options.capName, options.amount, version, ROLLING_INCREMENTED_EVENT_QN),
       );
-      await insertReservationRow(txDb, id, {
+      await insertReservationRow(txDb, user, id, {
         capName: options.capName,
         kind: "rolling",
         amount: options.amount,
@@ -152,7 +174,7 @@ export async function reserveRollingCap(
       return NOTHING_TO_RELEASE;
     }),
   );
-  return toHandle(ctx, id);
+  return toHandle(ctx, id, outsideTransaction);
 }
 
 // Deleting the row takes its row lock inside the handler transaction, so a release started after a
@@ -201,45 +223,123 @@ async function giveBackReservation(
   user: SessionUser,
   id: string,
 ): Promise<WriteResult> {
-  const row = await txDb.fetchOne<CapReservationRow>(capReservationsTable, { id });
+  const ownRow = { id, tenantId: user.tenantId };
+  const row = await txDb.fetchOne<CapReservationRow>(capReservationsTable, ownRow);
   if (!row) return NOTHING_TO_RELEASE;
-  // Waits for a confirm still holding the row; zero rows back means that confirm committed.
-  const claimed = await txDb.updateMany(capReservationsTable, { expiresAt: row.expiresAt }, { id });
-  if (claimed.length === 0) return NOTHING_TO_RELEASE;
+  const claimed = await claimReservationRow(txDb, user, row);
+  if (!claimed) return NOTHING_TO_RELEASE;
   const given =
     row.kind === "rolling"
       ? await giveBackRolling(txDb, user, row)
       : await giveBackCalendar(txDb, user, row);
   if (!given.isSuccess) return given;
-  await txDb.deleteMany(capReservationsTable, { id });
+  await txDb.deleteMany(capReservationsTable, ownRow);
   return given;
 }
 
-export async function releaseCapReservation(ctx: HandlerContext, id: string): Promise<void> {
-  const outsideDb = requireOutsideTransactionDb(ctx);
+// Waits for a confirm still holding the row; false means that confirm (or another release) won.
+async function claimReservationRow(
+  txDb: TenantDb,
+  user: SessionUser,
+  row: CapReservationRow,
+): Promise<boolean> {
+  const claimed = await txDb.updateMany(
+    capReservationsTable,
+    { expiresAt: row.expiresAt },
+    { id: row.id, tenantId: user.tenantId },
+  );
+  return claimed.length > 0;
+}
+
+export async function releaseCapReservation(
+  ctx: CapCounterContext,
+  id: string,
+  outsideTransaction = true,
+): Promise<void> {
+  const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
   const released = await retryOnStreamVersionConflict(() =>
     retryCounterWriteOnVersionConflict(() =>
-      runInOwnTransaction(outsideDb, (txDb) => giveBackReservation(txDb, ctx.user, id)),
+      runInOwnTransaction(writeDb, (txDb) => giveBackReservation(txDb, user, id)),
     ),
   );
   if (!released.isSuccess) throw reraiseAsKumikoError(released.error);
 }
 
+export type SettleCalendarCapOptions = {
+  readonly capName: string;
+  readonly periodStartIso: string;
+  readonly actualAmount: number;
+};
+
+function bookCalendarDelta(
+  txDb: TenantDb,
+  user: SessionUser,
+  period: Pick<SettleCalendarCapOptions, "capName" | "periodStartIso">,
+  delta: number,
+): Promise<WriteResult> {
+  if (delta === 0) return Promise.resolve({ isSuccess: true, data: {} });
+  return applyCapDeltaOn(
+    txDb,
+    user,
+    { ...period, amount: Math.abs(delta) },
+    delta > 0 ? "add" : "subtract",
+  );
+}
+
+// Replaces the reserved amount by the actual one in a single transaction. When the row is already
+// gone (swept or released), the reserved amount was given back, so the full actual amount is booked.
+export async function settleCalendarCapReservation(
+  ctx: CapCounterContext,
+  id: string,
+  options: SettleCalendarCapOptions,
+  outsideTransaction = true,
+): Promise<void> {
+  if (!Number.isInteger(options.actualAmount) || options.actualAmount < 0) {
+    throw new Error(
+      `cap-counter: settle amount must be a non-negative integer, got ${options.actualAmount}`,
+    );
+  }
+  const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
+  const settled = await retryCounterWriteOnVersionConflict(() =>
+    runInOwnTransaction(writeDb, async (txDb) => {
+      const row = await txDb.fetchOne<CapReservationRow>(capReservationsTable, {
+        id,
+        tenantId: user.tenantId,
+      });
+      const claimed = row ? await claimReservationRow(txDb, user, row) : false;
+      if (!row || !claimed) {
+        return bookCalendarDelta(txDb, user, options, options.actualAmount);
+      }
+      const booked = await bookCalendarDelta(
+        txDb,
+        user,
+        options,
+        options.actualAmount - row.amount,
+      );
+      if (!booked.isSuccess) return booked;
+      await txDb.deleteMany(capReservationsTable, { id, tenantId: user.tenantId });
+      return booked;
+    }),
+  );
+  if (!settled.isSuccess) throw reraiseAsKumikoError(settled.error);
+}
+
 // A failed release leaves its row behind; giving it back once the TTL passed bounds how long that
 // capacity stays counted.
 export async function releaseExpiredCapReservations(
-  ctx: HandlerContext,
+  ctx: CapCounterContext,
   capName: string,
+  outsideTransaction = true,
 ): Promise<void> {
-  const outsideDb = requireOutsideTransactionDb(ctx);
-  const expired = await outsideDb.selectMany<Pick<CapReservationRow, "id">>(capReservationsTable, {
-    tenantId: ctx.user.tenantId,
+  const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
+  const expired = await writeDb.selectMany<Pick<CapReservationRow, "id">>(capReservationsTable, {
+    tenantId: user.tenantId,
     capName,
     expiresAt: { lt: Temporal.Now.instant() },
   });
   for (const { id } of expired) {
     try {
-      await releaseCapReservation(ctx, id);
+      await releaseCapReservation(ctx, id, outsideTransaction);
     } catch (error) {
       ctx.log?.error("releasing an expired cap reservation failed", { id, capName, error });
     }

package/packages/bundled-features/src/cap-counter/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.358.0",
+    "type": "improvement",
+    "title": "Reserve and settle cap usage outside the dispatcher",
+    "detail": "reserveCalendarCapUsage(ctx, { capName, periodStartIso, limit, profile, amount, notify? }) runs the same sweep, soft-hit notification and guarded hard-cap reservation as withCapEnforcement and returns a handle. settle(actualAmount) replaces the reserved amount by the actual one in one transaction (and books the full actual amount if the reservation was swept or released meanwhile); release() gives it back. Parallel callers cannot exceed the hard cap. It works with a HandlerContext (also r.systemScope() handlers) and a JobContext. Pattern: `const r = await reserveCalendarCapUsage(ctx, {...}); try { ...; await r.settle(actual) } catch (e) { await r.release(); throw e }`. bookCapUsage, markCapSoftWarned, releaseCapUsage and the enforceCap family accept a JobContext as well.",
+    "migration": "withCapEnforcement and bookCapUsage now work on r.systemScope() handlers; before, they failed on the fail-closed ctx.db. Reservation rows carry the tenant of ctx.user explicitly, and a context whose tenant-mode db belongs to another tenant than ctx.user is rejected with access_denied. enforceCap now filters the counter by ctx.user.tenantId, so a system-mode db no longer reads another tenant's counter."
+  },
   {
     "version": "0.352.0",
     "type": "breaking",