@cosmicdrift/kumiko-samples 0.367.0 → 0.369.0

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

@@ -5,7 +5,7 @@ import {
   type TenantDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
-import { reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
+import { reraiseAsKumikoError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import {
   appendEventInTenantDb,
   getStreamVersionInTenantDb,
@@ -45,6 +45,9 @@ type CapReservationRow = {
   readonly expiresAt: Temporal.Instant;
   readonly createdAt: Temporal.Instant;
   readonly settledAt: Temporal.Instant | null;
+  // Units consume already turned into booked ones; the counter holds them on top of amount.
+  readonly consumedAmount: number;
+  readonly releasedAt: Temporal.Instant | null;
 };
 
 const NOTHING_TO_RELEASE: WriteResult = { isSuccess: true, data: {} };
@@ -69,6 +72,8 @@ async function insertReservationRow(
     expiresAt: now.add({ minutes: CAP_RESERVATION_TTL_MINUTES }),
     createdAt: now,
     settledAt: null,
+    consumedAmount: 0,
+    releasedAt: null,
   });
 }
 
@@ -197,6 +202,7 @@ async function confirmCapReservation(
     id,
     tenantId: confirm.tenantId,
     settledAt: null,
+    releasedAt: null,
   });
 }
 
@@ -208,6 +214,8 @@ async function giveBackCalendar(
   if (row.periodStartIso === null) {
     throw new Error(`cap-counter: calendar reservation ${row.id} has no period to release against`);
   }
+  // Fully consumed by consumeCalendarCapReservation: nothing left to give back.
+  if (row.amount === 0) return NOTHING_TO_RELEASE;
   return applyCapDeltaOn(
     txDb,
     user,
@@ -247,29 +255,45 @@ async function giveBackReservation(
   });
   if (!row) return NOTHING_TO_RELEASE;
   const claimed = await claimReservationRow(txDb, user, row);
-  if (!claimed) return NOTHING_TO_RELEASE;
+  if (!claimed || claimed.releasedAt !== null) return NOTHING_TO_RELEASE;
   const given =
-    row.kind === "rolling"
-      ? await giveBackRolling(txDb, user, row)
-      : await giveBackCalendar(txDb, user, row);
+    claimed.kind === "rolling"
+      ? await giveBackRolling(txDb, user, claimed)
+      : await giveBackCalendar(txDb, user, claimed);
   if (!given.isSuccess) return given;
-  await txDb.deleteMany(capReservationsTable, ownRow);
+  // Only consumed units need remembering: a later settle or consume must not count them twice.
+  if (claimed.kind === "rolling" || claimed.consumedAmount === 0) {
+    await txDb.deleteMany(capReservationsTable, ownRow);
+    return given;
+  }
+  const now = Temporal.Now.instant();
+  await txDb.updateMany(
+    capReservationsTable,
+    {
+      amount: 0,
+      releasedAt: now,
+      expiresAt: now.add({ minutes: CAP_SETTLED_TOMBSTONE_TTL_MINUTES }),
+    },
+    ownRow,
+  );
   return given;
 }
 
-// Waits for a confirm still holding the row; false means that confirm, a settle or another release
-// won (Postgres re-checks settled_at after the lock wait).
+// Waits for a confirm still holding the row; undefined means that confirm or a settle won (Postgres
+// re-checks settled_at after the lock wait). A released row is claimed too: callers branch on
+// releasedAt. The returned row is read after the lock wait, so it already includes a concurrent
+// consume.
 async function claimReservationRow(
   txDb: TenantDb,
   user: SessionUser,
   row: CapReservationRow,
-): Promise<boolean> {
-  const claimed = await txDb.updateMany(
+): Promise<CapReservationRow | undefined> {
+  const [claimed] = await txDb.updateMany<CapReservationRow>(
     capReservationsTable,
     { expiresAt: row.expiresAt },
     { id: row.id, tenantId: user.tenantId, settledAt: null },
   );
-  return claimed.length > 0;
+  return claimed;
 }
 
 export async function releaseCapReservation(
@@ -289,9 +313,28 @@ export async function releaseCapReservation(
 export type SettleCalendarCapOptions = {
   readonly capName: string;
   readonly periodStartIso: string;
+  // Total used, including units already consumed through a handle.
   readonly actualAmount: number;
 };
 
+export class CapSettleBelowConsumedError extends UnprocessableError {
+  constructor(capName: string, consumed: number, actualAmount: number) {
+    super("cap_settle_below_consumed", {
+      message: `Cap "${capName}": cannot settle ${actualAmount}, ${consumed} units were already consumed.`,
+      details: { capName, consumed, actualAmount },
+    });
+  }
+}
+
+export class CapReservationSettledError extends UnprocessableError {
+  constructor(capName: string) {
+    super("cap_reservation_settled", {
+      message: `Cap "${capName}": the reservation is already settled, consume is no longer possible.`,
+      details: { capName },
+    });
+  }
+}
+
 function bookCalendarDelta(
   txDb: TenantDb,
   user: SessionUser,
@@ -318,8 +361,22 @@ async function settleInTransaction(
     ...ownRow,
     settledAt: null,
   });
-  if (open && (await claimReservationRow(txDb, user, open))) {
-    const booked = await bookCalendarDelta(txDb, user, options, options.actualAmount - open.amount);
+  const claimed = open && (await claimReservationRow(txDb, user, open));
+  if (claimed) {
+    if (options.actualAmount < claimed.consumedAmount) {
+      throw new CapSettleBelowConsumedError(
+        options.capName,
+        claimed.consumedAmount,
+        options.actualAmount,
+      );
+    }
+    const alreadyBooked = claimed.amount + claimed.consumedAmount;
+    const booked = await bookCalendarDelta(
+      txDb,
+      user,
+      options,
+      options.actualAmount - alreadyBooked,
+    );
     if (!booked.isSuccess) return booked;
     const now = Temporal.Now.instant();
     await txDb.updateMany(
@@ -335,6 +392,10 @@ async function settleInTransaction(
   }
   // Row swept or released: its amount was given back, so the full actual amount is booked and a
   // tombstone makes a repeated settle a no-op. A parallel settle inserting first fails this insert.
+  // Booking first: a lost counter race returns a result instead of throwing, so the transaction
+  // commits and a tombstone written before it would turn the retry into a no-op.
+  const booked = await bookCalendarDelta(txDb, user, options, options.actualAmount);
+  if (!booked.isSuccess) return booked;
   const now = Temporal.Now.instant();
   await txDb.insertOne(capReservationsTable, {
     ...ownRow,
@@ -345,8 +406,10 @@ async function settleInTransaction(
     expiresAt: now.add({ minutes: CAP_SETTLED_TOMBSTONE_TTL_MINUTES }),
     createdAt: now,
     settledAt: now,
+    consumedAmount: 0,
+    releasedAt: null,
   });
-  return bookCalendarDelta(txDb, user, options, options.actualAmount);
+  return booked;
 }
 
 // The failed tombstone insert aborts the whole attempt, so nothing was booked; the repeat sees the
@@ -382,8 +445,128 @@ export async function settleCalendarCapReservation(
   if (!settled.isSuccess) throw reraiseAsKumikoError(settled.error);
 }
 
+export type ConsumeCalendarCapOptions = {
+  readonly capName: string;
+  readonly periodStartIso: string;
+  readonly units: number;
+};
+
+export class CapReservationOverConsumedError extends UnprocessableError {
+  constructor(capName: string, remaining: number, requested: number) {
+    super("cap_reservation_over_consumed", {
+      message: `Cap "${capName}": cannot consume ${requested} units, only ${remaining} still reserved.`,
+      details: { capName, remaining, requested },
+    });
+  }
+}
+
+async function consumeClaimedRow(
+  txDb: TenantDb,
+  user: SessionUser,
+  claimed: CapReservationRow,
+  options: ConsumeCalendarCapOptions,
+): Promise<WriteResult> {
+  const ownRow = { id: claimed.id, tenantId: user.tenantId };
+  if (claimed.releasedAt !== null) {
+    // The reserved rest was given back, so each unit is booked on top of what is still counted.
+    const booked = await bookCalendarDelta(txDb, user, options, options.units);
+    if (!booked.isSuccess) return booked;
+    await txDb.updateMany(
+      capReservationsTable,
+      { consumedAmount: claimed.consumedAmount + options.units },
+      ownRow,
+    );
+    return booked;
+  }
+  if (options.units > claimed.amount) {
+    throw new CapReservationOverConsumedError(options.capName, claimed.amount, options.units);
+  }
+  await txDb.updateMany(
+    capReservationsTable,
+    {
+      amount: claimed.amount - options.units,
+      consumedAmount: claimed.consumedAmount + options.units,
+    },
+    ownRow,
+  );
+  return NOTHING_TO_RELEASE;
+}
+
+// Row already expired away: the units are booked directly and a released tombstone remembers them
+// so a later settle subtracts them. A parallel consume inserting first fails this insert.
+async function consumeWithoutRow(
+  txDb: TenantDb,
+  user: SessionUser,
+  id: string,
+  options: ConsumeCalendarCapOptions,
+): Promise<WriteResult> {
+  // Booking first, for the same reason as settle's missing-row path.
+  const booked = await bookCalendarDelta(txDb, user, options, options.units);
+  if (!booked.isSuccess) return booked;
+  const now = Temporal.Now.instant();
+  await txDb.insertOne(capReservationsTable, {
+    id,
+    tenantId: user.tenantId,
+    capName: options.capName,
+    kind: "calendar",
+    periodStartIso: options.periodStartIso,
+    amount: 0,
+    expiresAt: now.add({ minutes: CAP_SETTLED_TOMBSTONE_TTL_MINUTES }),
+    createdAt: now,
+    settledAt: null,
+    consumedAmount: options.units,
+    releasedAt: now,
+  });
+  return booked;
+}
+
+async function consumeInTransaction(
+  txDb: TenantDb,
+  user: SessionUser,
+  id: string,
+  options: ConsumeCalendarCapOptions,
+): Promise<WriteResult> {
+  const ownRow = { id, tenantId: user.tenantId };
+  const open = await txDb.fetchOne<CapReservationRow>(capReservationsTable, {
+    ...ownRow,
+    settledAt: null,
+  });
+  if (open && open.capName !== options.capName) {
+    throw new Error(
+      `cap-counter: reservation ${id} belongs to cap "${open.capName}", not "${options.capName}"`,
+    );
+  }
+  const claimed = open && (await claimReservationRow(txDb, user, open));
+  if (claimed) return consumeClaimedRow(txDb, user, claimed, options);
+  if (await txDb.fetchOne<CapReservationRow>(capReservationsTable, ownRow)) {
+    throw new CapReservationSettledError(options.capName);
+  }
+  return consumeWithoutRow(txDb, user, id, options);
+}
+
+// Turns reserved units into booked ones without touching the counter; the row keeps the unconsumed
+// rest so a release gives back exactly that. After a release or sweep the units are booked directly.
+export async function consumeCalendarCapReservation(
+  ctx: CapCounterContext,
+  id: string,
+  options: ConsumeCalendarCapOptions,
+  outsideTransaction = true,
+): Promise<void> {
+  if (!Number.isInteger(options.units) || options.units < 1) {
+    throw new Error(`cap-counter: consume units must be a positive integer, got ${options.units}`);
+  }
+  const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
+  const consumed = await retryCounterWriteOnVersionConflict(() =>
+    retryOnceOnTombstoneRace(() =>
+      runInOwnTransaction(writeDb, (txDb) => consumeInTransaction(txDb, user, id, options)),
+    ),
+  );
+  if (!consumed.isSuccess) throw reraiseAsKumikoError(consumed.error);
+}
+
 // A failed release leaves its row behind; giving it back once the TTL passed bounds how long that
-// capacity stays counted. Expired settled tombstones are only deleted: their amount stays booked.
+// capacity stays counted. Expired settled and released tombstones are only deleted: what they
+// stand for stays booked.
 export async function releaseExpiredCapReservations(
   ctx: CapCounterContext,
   capName: string,
@@ -399,9 +582,14 @@ export async function releaseExpiredCapReservations(
     ...expiredWhere,
     settledAt: { ne: null },
   });
+  await writeDb.deleteMany(capReservationsTable, {
+    ...expiredWhere,
+    releasedAt: { ne: null },
+  });
   const expired = await writeDb.selectMany<Pick<CapReservationRow, "id">>(capReservationsTable, {
     ...expiredWhere,
     settledAt: null,
+    releasedAt: null,
   });
   for (const { id } of expired) {
     try {

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

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.368.0",
+    "type": "improvement",
+    "title": "calendarCapReservationHandle consumes a reservation per unit",
+    "detail": "`reserveCalendarCapUsage` now returns `reservationId`. `calendarCapReservationHandle(ctx, reservationId, { capName, periodStartIso })` returns a handle with `consume(units)` (turns reserved units into booked ones, counter unchanged) and `release()` (gives back the unconsumed rest). A handler reserves the worst case before the job is dispatched, the job consumes per written unit, so parallel dispatches can no longer overshoot the hard cap and a retry only counts what was written.\n\n`consume` beyond the still-reserved rest throws `CapReservationOverConsumedError` (422, `cap_reservation_over_consumed`). `consume` against a settle tombstone throws `CapReservationSettledError` (422, `cap_reservation_settled`); `release` against it is a no-op. When the reservation outlived its TTL and was swept, `consume` books the units directly, the way settle does for a missing row, without a hard-cap check."
+  },
+  {
+    "version": "0.368.0",
+    "type": "fix",
+    "title": "Swept or released calendar reservations remember the units consume booked",
+    "detail": "The reservation row now stores `consumed_amount`. A release or the TTL sweep gives back only the unconsumed rest. If units were consumed, it keeps the row as a released tombstone (`released_at` set, `amount` 0) until the tombstone TTL passes, instead of deleting it. A later `settle` subtracts the consumed units from the booking, and a `consume` after the sweep books its units directly and is remembered the same way, so the counter ends at exactly the settled total. `settle` below the consumed units throws `CapSettleBelowConsumedError` (422, `cap_settle_below_consumed`) in every state. Expired released tombstones are deleted by the sweep.",
+    "migration": "Apps with cap-counter generate a migration for the new columns store_cap_reservations.consumed_amount (integer NOT NULL DEFAULT 0) and store_cap_reservations.released_at (kumiko migrate generate)."
+  },
   {
     "version": "0.366.0",
     "type": "fix",

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

@@ -68,81 +68,92 @@ import { markSoftWarnedHandler } from "./handlers/mark-soft-warned.write.js";
 import { CAP_COUNTER_I18N } from "./i18n.js";
 import { capReservationsTableMeta } from "./tables.js";
 
-export const capCounterFeature = defineFeature(CAP_COUNTER_FEATURE, (r) => {
-  r.describe(
-    "Tracks per-tenant usage against configurable limits using two complementary storage models: calendar-period counters (one projection row per tenant/capName/period, reset implicitly by period rollover) and rolling-window counters (append-only event stream, no projection). Use `enforceCap` / `enforceRollingCap` (or the `withCapEnforcement` / `withRollingCapEnforcement` handler wrappers) in your write-handlers to check limits with soft-warn and hard-block tolerances; call `enforceCapAndMaybeNotify` when you also want to trigger a delivery notification on soft-threshold hits.",
-  );
-  r.uiHints({
-    displayLabel: "Cap Counter · Usage Limits",
-    category: "operations",
-    recommended: false,
-  });
-  r.entity({ name: "cap-counter", ...capCounterEntity });
-  r.storeTable(capReservationsTableMeta, {
-    reason: "coordination.cap_reservation_ledger",
-  });
+export function createCapCounterFeature() {
+  return defineFeature(
+    CAP_COUNTER_FEATURE,
+    (r) => {
+      r.describe(
+        "Tracks per-tenant usage against configurable limits using two complementary storage models: calendar-period counters (one projection row per tenant/capName/period, reset implicitly by period rollover) and rolling-window counters (append-only event stream, no projection). Use `enforceCap` / `enforceRollingCap` (or the `withCapEnforcement` / `withRollingCapEnforcement` handler wrappers) in your write-handlers to check limits with soft-warn and hard-block tolerances; call `enforceCapAndMaybeNotify` when you also want to trigger a delivery notification on soft-threshold hits.",
+      );
+      r.uiHints({
+        displayLabel: "Cap Counter · Usage Limits",
+        category: "operations",
+        recommended: false,
+      });
+      r.entity({ name: "cap-counter", ...capCounterEntity });
+      r.storeTable(capReservationsTableMeta, {
+        reason: "coordination.cap_reservation_ledger",
+      });
 
-  // Custom Domain-Event für Rolling-Counter. r.defineEvent registriert
-  // das Schema beim Registry; ctx.unsafeAppendEvent im Handler nutzt
-  // dasselbe Schema für Append-Time-Validation. QN nach Prefixing:
-  // "cap-counter:event:rolling-incremented" (siehe
-  // ROLLING_INCREMENTED_EVENT_QN).
-  r.defineEvent(ROLLING_INCREMENTED_EVENT_SHORT, rollingIncrementedSchema, { piiFields: "none" });
-  r.defineEvent(ROLLING_RELEASED_EVENT_SHORT, rollingReleasedSchema, { piiFields: "none" });
+      // Custom domain event for the rolling counter. r.defineEvent registers the
+      // schema with the registry; ctx.unsafeAppendEvent in the handler reuses the
+      // same schema for append-time validation. QN after prefixing:
+      // "cap-counter:event:rolling-incremented" (see
+      // ROLLING_INCREMENTED_EVENT_QN).
+      r.defineEvent(ROLLING_INCREMENTED_EVENT_SHORT, rollingIncrementedSchema, {
+        piiFields: "none",
+      });
+      r.defineEvent(ROLLING_RELEASED_EVENT_SHORT, rollingReleasedSchema, { piiFields: "none" });
 
-  // Custom write-handlers.
-  // - increment: Calendar-Period (CRUD via projection-row).
-  // - increment-rolling: Rolling-Window (Custom-Event, no projection).
-  // - mark-soft-warned: Anti-Notification-Storm-Flag (nur Calendar).
-  r.writeHandler(incrementCapHandler);
-  r.writeHandler(incrementRollingCapHandler);
-  r.writeHandler(markSoftWarnedHandler);
+      // Custom write-handlers.
+      // - increment: calendar period (CRUD via projection row).
+      // - increment-rolling: rolling window (custom event, no projection).
+      // - mark-soft-warned: anti-notification-storm flag (calendar only).
+      r.writeHandler(incrementCapHandler);
+      r.writeHandler(incrementRollingCapHandler);
+      r.writeHandler(markSoftWarnedHandler);
 
-  // Custom + standard reads. Sysadmin-cross-tenant via list, per-tenant
-  // single-row via get-counter. Detail-by-id-handler bewusst weggelassen
-  // (kein Use-Case; der natürliche Lookup ist über capName + period, nicht
-  // über aggregate-id).
-  r.queryHandler(
-    defineEntityListHandler("cap-counter", capCounterEntity, {
-      access: { roles: access.systemAdmin },
-      escapeHatch: {
-        reason:
-          "SystemAdmin quota operator view lists usage counters of every tenant to see who consumes which cap",
-      },
-      description:
-        "Lists usage-counter rows across all tenants with cap name, current value, period start and soft-warn timestamp; use it as the operator view of who is consuming which quota.",
-    }),
-  );
-  r.queryHandler(getCounterQuery);
+      // Custom + standard reads. Sysadmin cross-tenant via list, per-tenant
+      // single row via get-counter. Detail-by-id handler left out on purpose
+      // (no use case; the natural lookup is capName + period, not the
+      // aggregate id).
+      r.queryHandler(
+        defineEntityListHandler("cap-counter", capCounterEntity, {
+          access: { roles: access.systemAdmin },
+          escapeHatch: {
+            reason:
+              "SystemAdmin quota operator view lists usage counters of every tenant to see who consumes which cap",
+          },
+          description:
+            "Lists usage-counter rows across all tenants with cap name, current value, period start and soft-warn timestamp; use it as the operator view of who is consuming which quota.",
+        }),
+      );
+      r.queryHandler(getCounterQuery);
 
-  r.screen({
-    id: CAP_COUNTER_LIST_SCREEN_ID,
-    type: "entityList",
-    entity: "cap-counter",
-    columns: [
-      "tenantId",
-      "capName",
-      "value",
-      "periodStart",
-      { field: "lastSoftWarnedAt", hideOnNarrow: true },
-    ],
-    defaultSort: { field: "capName", dir: "asc" },
-    // Search resolves against the caller's own tenant stream, so on this
-    // cross-tenant operator list it would only ever hit the SystemAdmin's tenant.
-    searchable: false,
-    access: { roles: ["SystemAdmin"] },
-  });
-  r.nav({
-    id: "cap-list",
-    label: "cap-counter:nav.cap-list",
-    screen: "cap-counter:screen:cap-list",
-    icon: "gauge",
-    order: 60,
-  });
-  r.translations({
-    keys: {
-      ...CAP_COUNTER_I18N,
-      "cap-counter:nav.cap-list": { de: "Limits", en: "Caps" },
+      r.screen({
+        id: CAP_COUNTER_LIST_SCREEN_ID,
+        type: "entityList",
+        entity: "cap-counter",
+        columns: [
+          "tenantId",
+          "capName",
+          "value",
+          "periodStart",
+          { field: "lastSoftWarnedAt", hideOnNarrow: true },
+        ],
+        defaultSort: { field: "capName", dir: "asc" },
+        // Search resolves against the caller's own tenant stream, so on this
+        // cross-tenant operator list it would only ever hit the SystemAdmin's tenant.
+        searchable: false,
+        access: { roles: ["SystemAdmin"] },
+      });
+      r.nav({
+        id: "cap-list",
+        label: "cap-counter:nav.cap-list",
+        screen: "cap-counter:screen:cap-list",
+        icon: "gauge",
+        order: 60,
+      });
+      r.translations({
+        keys: {
+          ...CAP_COUNTER_I18N,
+          "cap-counter:nav.cap-list": { de: "Limits", en: "Caps" },
+        },
+      });
     },
-  });
-});
+    { dedupeOptions: {} },
+  );
+}
+
+/** @deprecated Use createCapCounterFeature(). Run `bun kumiko-upgrade --apply`. Removed in the first release after 2026-10-29. */
+export const capCounterFeature = createCapCounterFeature();

package/packages/bundled-features/src/cap-counter/handlers/increment-rolling.write.ts

@@ -68,10 +68,9 @@ export const incrementRollingCapHandler: WriteHandlerDef = {
     const payload = event.payload as IncrementRollingPayload;
     const aggregateId = rollingCapAggregateId(event.user.tenantId, payload.capName);
 
-    // unsafeAppendEvent — bundled-features-Pfad (apps mit bun kumiko
-    // codegen kriegen den strict-typed appendEvent-Wrapper). Schema-
-    // Validation läuft trotzdem, weil r.defineEvent das Schema
-    // registriert hat.
+    // unsafeAppendEvent: the strict appendEvent is bound to an app's own event map, which
+    // bundled-features cannot see. Schema validation still runs because r.defineEvent
+    // registered the schema.
     await ctx.unsafeAppendEvent({
       aggregateId,
       aggregateType: CAP_COUNTER_ROLLING_AGGREGATE_TYPE,

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

@@ -10,10 +10,18 @@ export {
   readRollingCapUsage,
 } from "./book-cap-usage.js";
 export {
+  type CalendarCapReservationHandle,
+  type CalendarCapReservationHandleSpec,
   type CalendarCapUsageReservation,
   type CalendarCapUsageReservationSpec,
+  calendarCapReservationHandle,
   reserveCalendarCapUsage,
 } from "./calendar-cap-usage-reservation.js";
+export {
+  CapReservationOverConsumedError,
+  CapReservationSettledError,
+  CapSettleBelowConsumedError,
+} from "./cap-reservation.js";
 export {
   CAP_COUNTER_FEATURE,
   CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
@@ -41,7 +49,7 @@ export {
   type StockCapResult,
 } from "./enforce-cap.js";
 export { capCounterEntity } from "./entity.js";
-export { capCounterFeature } from "./feature.js";
+export { capCounterFeature, createCapCounterFeature } from "./feature.js";
 export { readPayloadField } from "./payload-field.js";
 export {
   type CapGuardContext,

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

@@ -13,9 +13,12 @@ const CAP_RESERVATIONS_TENANT_CAP_EXPIRES_INDEX =
   "store_cap_reservations_tenant_id_cap_name_expires_at_idx";
 
 // One row per capacity that was booked before a handler transaction and is not settled yet. The
-// handler transaction deletes it on its own commit (confirm); a release or the TTL sweep deletes it
-// together with the counter decrement. A settle keeps the row as a tombstone (settled_at set) until
-// its shortened TTL passes, so a repeated settle or a late release finds it and does nothing.
+// handler transaction deletes it on its own commit (confirm). While a calendar row is open the
+// counter holds amount + consumed_amount for it. A release or the TTL sweep gives back amount and
+// keeps the row as a released tombstone (released_at set, amount 0, consumed_amount still booked)
+// until its shortened TTL passes, so a later consume or settle accounts for the consumed units.
+// A settle keeps the row as a settled tombstone (settled_at set) the same way, so a repeated settle
+// or a late release finds it and does nothing.
 // Unmanaged: the rows are a coordination aid, not state with an event history.
 export const capReservationsTable = pgTable(
   "store_cap_reservations",
@@ -30,6 +33,8 @@ export const capReservationsTable = pgTable(
     expiresAt: instant("expires_at").notNull(),
     createdAt: instant("created_at").notNull(),
     settledAt: instant("settled_at"),
+    consumedAmount: integer("consumed_amount").notNull().default(0),
+    releasedAt: instant("released_at"),
   },
   (t) => [index(CAP_RESERVATIONS_TENANT_CAP_EXPIRES_INDEX).on(t.tenantId, t.capName, t.expiresAt)],
 );
@@ -52,5 +57,7 @@ export const capReservationsTableMeta: EntityTableMeta = defineUnmanagedTable({
     { name: "expires_at", pgType: "timestamptz", notNull: true },
     { name: "created_at", pgType: "timestamptz", notNull: true },
     { name: "settled_at", pgType: "timestamptz", notNull: false },
+    { name: "consumed_amount", pgType: "integer", notNull: true, defaultSql: "0" },
+    { name: "released_at", pgType: "timestamptz", notNull: false },
   ],
 });

package/packages/bundled-features/src/cap-overview/handlers/caps-usage.query.ts

@@ -1,5 +1,4 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import { buildEntityTable, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import {
   defineQueryHandler,
   mayOverrideTenant,

package/packages/bundled-features/src/cap-overview/handlers/tenant-caps-list.query.ts

@@ -1,5 +1,9 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { buildEntityTable, decodeCursor, encodeCursor } from "@cosmicdrift/kumiko-framework/db";
+import {
+  buildEntityTable,
+  decodeCursor,
+  encodeCursor,
+  selectMany,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   type ConfigAccessor,
   definePagedQueryHandler,

package/packages/bundled-features/src/cap-overview/handlers/tenant-options.query.ts

@@ -1,4 +1,4 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";

package/packages/bundled-features/src/channel-email/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.369.0",
+    "type": "breaking",
+    "title": "The tenant mail transport applies per notification",
+    "detail": "r.notification(name, { tenantTransport: true }) marks a notification whose mails go through the tenant's own mail transport. channel-email consults its tenantTransport resolver only for these (also under a renamedFrom name); every other notification, such as password reset or sign-in mails, always takes the app transport, even when the tenant has a provider. With tenantTransport set, transport may be omitted: a mail that then has no transport fails with missing_credentials instead of throwing. The template test mail (template-resolver send-test) now gets the tenant config in its channel context and uses the template's notification, so it leaves through the same transport as the real mail.",
+    "migration": "Apps that pass tenantTransport to createChannelEmailFeature add `tenantTransport: true` to every r.notification whose mails should go through the tenant's provider; without the flag those mails now go through the app transport. Apps without an app SMTP server can drop transport and keep tenantTransport."
+  },
   {
     "version": "0.367.0",
     "type": "improvement",