@cosmicdrift/kumiko-samples 0.351.0 → 0.352.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.351.0",
+  "version": "0.352.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.351.0",
+  "version": "0.352.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>",
@@ -164,7 +164,7 @@
     "nodemailer": "^10.0.13",
     "qrcode": "^1.5.4",
     "react": "^19.2.6",
-    "sharp": "^0.35.4",
+    "sharp": "^0.35.5",
     "stripe": "^22.6.2",
     "tailwind-merge": "^3.6.0",
     "temporal-polyfill": "^0.3.2",

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

@@ -4,14 +4,19 @@ import { runInOwnTransaction, type TenantDb } from "@cosmicdrift/kumiko-framewor
 import {
   createEntityExecutor,
   type HandlerContext,
+  type SessionUser,
   type TenantId,
   type WriteResult,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { eventsTable, VersionConflictError } from "@cosmicdrift/kumiko-framework/event-store";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { capCounterAggregateId, rollingCapAggregateId } from "./aggregate-id.js";
-import { CAP_COUNTER_ROLLING_AGGREGATE_TYPE, ROLLING_INCREMENTED_EVENT_QN } from "./constants.js";
+import {
+  CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
+  ROLLING_INCREMENTED_EVENT_QN,
+  ROLLING_RELEASED_EVENT_QN,
+} from "./constants.js";
 import { capCounterEntity } from "./entity.js";
 
 const { table, executor } = createEntityExecutor("cap-counter", capCounterEntity);
@@ -39,7 +44,7 @@ function sleepMs(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-async function retryCounterWriteOnVersionConflict(
+export async function retryCounterWriteOnVersionConflict(
   writeAttempt: () => Promise<WriteResult>,
 ): Promise<WriteResult> {
   let result: WriteResult = await writeAttempt();
@@ -54,6 +59,20 @@ async function retryCounterWriteOnVersionConflict(
   return result;
 }
 
+// Event-store appends signal a lost race by throwing; the whole attempt (read, guard, append) is repeated.
+export async function retryOnStreamVersionConflict<T>(attempt: () => Promise<T>): Promise<T> {
+  for (let tries = 1; ; tries++) {
+    try {
+      return await attempt();
+    } catch (error) {
+      if (!(error instanceof VersionConflictError) || tries >= MAX_COUNTER_WRITE_ATTEMPTS) {
+        throw error;
+      }
+      await sleepMs(Math.random() * tries * BACKOFF_JITTER_MS_PER_ATTEMPT);
+    }
+  }
+}
+
 export type BookCapUsageOptions = {
   readonly capName: string;
   readonly periodStartIso: string;
@@ -63,7 +82,7 @@ export type BookCapUsageOptions = {
   readonly guardCurrentValue?: (currentValue: number) => void;
 };
 
-function requireOutsideTransactionDb(ctx: HandlerContext): TenantDb {
+export function requireOutsideTransactionDb(ctx: HandlerContext): TenantDb {
   if (!ctx.dbOutsideTransaction) {
     throw new Error(
       "cap-counter.bookCapUsage: outsideTransaction requested but ctx.dbOutsideTransaction is undefined",
@@ -87,64 +106,70 @@ export async function releaseCapUsage(
   return applyCapDelta(ctx, options, "subtract");
 }
 
-async function applyCapDelta(
-  ctx: HandlerContext,
+// One attempt against an already-open db handle; a lost race comes back as a version_conflict failure the caller retries.
+export async function applyCapDeltaOn(
+  db: TenantDb,
+  user: SessionUser,
   options: BookCapUsageOptions,
   direction: "add" | "subtract",
 ): Promise<WriteResult> {
   const parsed = capBookingSchema.parse(options);
-  const aggregateId = capCounterAggregateId(
-    ctx.user.tenantId,
-    parsed.capName,
-    parsed.periodStartIso,
-  );
-
-  async function attemptWrite(db: TenantDb): Promise<WriteResult> {
-    const existing = await db.selectMany(table, { id: aggregateId }, { limit: 1 });
-    if (existing.length === 0) {
-      options.guardCurrentValue?.(0);
-      if (direction === "subtract") return { isSuccess: true, data: {} };
-      return executor.create(
-        {
-          id: aggregateId,
-          capName: parsed.capName,
-          value: parsed.amount,
-          periodStart: Temporal.Instant.from(parsed.periodStartIso),
-          lastSoftWarnedAt: null,
-        },
-        ctx.user,
-        db,
-      );
-    }
+  const aggregateId = capCounterAggregateId(user.tenantId, parsed.capName, parsed.periodStartIso);
 
-    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
-    options.guardCurrentValue?.(currentValue);
-    return executor.update(
+  const existing = await db.selectMany(table, { id: aggregateId }, { limit: 1 });
+  if (existing.length === 0) {
+    options.guardCurrentValue?.(0);
+    if (direction === "subtract") return { isSuccess: true, data: {} };
+    return executor.create(
       {
         id: aggregateId,
-        version: currentVersion,
-        changes: {
-          value:
-            direction === "add"
-              ? currentValue + parsed.amount
-              : Math.max(0, currentValue - parsed.amount),
-        },
+        capName: parsed.capName,
+        value: parsed.amount,
+        periodStart: Temporal.Instant.from(parsed.periodStartIso),
+        lastSoftWarnedAt: null,
       },
-      ctx.user,
+      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
+  options.guardCurrentValue?.(currentValue);
+  return executor.update(
+    {
+      id: aggregateId,
+      version: currentVersion,
+      changes: {
+        value:
+          direction === "add"
+            ? currentValue + parsed.amount
+            : Math.max(0, currentValue - parsed.amount),
+      },
+    },
+    user,
+    db,
+  );
+}
+
+async function applyCapDelta(
+  ctx: HandlerContext,
+  options: BookCapUsageOptions,
+  direction: "add" | "subtract",
+): Promise<WriteResult> {
   if (options.outsideTransaction) {
     const outsideDb = requireOutsideTransactionDb(ctx);
-    return retryCounterWriteOnVersionConflict(() => runInOwnTransaction(outsideDb, attemptWrite));
+    return retryCounterWriteOnVersionConflict(() =>
+      runInOwnTransaction(outsideDb, (txDb) => applyCapDeltaOn(txDb, ctx.user, options, direction)),
+    );
   }
-  return retryCounterWriteOnVersionConflict(() => attemptWrite(ctx.db));
+  return retryCounterWriteOnVersionConflict(() =>
+    applyCapDeltaOn(ctx.db, ctx.user, options, direction),
+  );
 }
 
 export type MarkCapSoftWarnedOptions = {
@@ -205,12 +230,11 @@ export type ReadRollingCapUsageOptions = {
   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(
+async function sumRollingEventAmounts(
   db: TenantDb,
   tenantId: TenantId,
   options: ReadRollingCapUsageOptions,
+  type: string,
 ): Promise<number> {
   const aggregateId = rollingCapAggregateId(tenantId, options.capName);
   const cutoff = Temporal.Now.instant().subtract({ hours: options.windowDays * 24 });
@@ -219,20 +243,37 @@ export async function readRollingCapUsage(
     tenantId,
     aggregateType: CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
     aggregateId,
-    type: ROLLING_INCREMENTED_EVENT_QN,
+    type,
     createdAt: { gte: cutoff },
   });
 
-  let value = 0;
+  let total = 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;
+      total += payload.amount;
     }
   }
+  return total;
+}
 
-  return value;
+// Sums usage without throwing — for callers that only need the raw number
+// (e.g. a CapSpec.usage callback), not the enforce-and-throw path.
+// Incremented minus released amounts inside the window; a release whose increment already left the window cannot push it below 0.
+export async function readRollingCapUsage(
+  db: TenantDb,
+  tenantId: TenantId,
+  options: ReadRollingCapUsageOptions,
+): Promise<number> {
+  const incremented = await sumRollingEventAmounts(
+    db,
+    tenantId,
+    options,
+    ROLLING_INCREMENTED_EVENT_QN,
+  );
+  const released = await sumRollingEventAmounts(db, tenantId, options, ROLLING_RELEASED_EVENT_QN);
+  return Math.max(0, incremented - released);
 }

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

@@ -0,0 +1,247 @@
+import { deleteMany, runInOwnTransaction, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type {
+  HandlerContext,
+  SessionUser,
+  WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  appendEventInTenantDb,
+  getStreamVersionInTenantDb,
+} from "@cosmicdrift/kumiko-framework/event-store";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import type {
+  ReservationConfirmContext,
+  ReservationHandle,
+} from "@cosmicdrift/kumiko-types/handlers";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { rollingCapAggregateId } from "./aggregate-id.js";
+import {
+  applyCapDeltaOn,
+  type BookCapUsageOptions,
+  type ReadRollingCapUsageOptions,
+  readRollingCapUsage,
+  requireOutsideTransactionDb,
+  retryCounterWriteOnVersionConflict,
+  retryOnStreamVersionConflict,
+} from "./book-cap-usage.js";
+import {
+  CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
+  CAP_RESERVATION_TTL_MINUTES,
+  ROLLING_INCREMENTED_EVENT_QN,
+  ROLLING_RELEASED_EVENT_QN,
+} from "./constants.js";
+import { capReservationsTable } from "./tables.js";
+
+type CapReservationRow = {
+  readonly id: string;
+  readonly capName: string;
+  readonly kind: "calendar" | "rolling";
+  readonly periodStartIso: string | null;
+  readonly amount: number;
+  readonly expiresAt: Temporal.Instant;
+};
+
+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) {
+  const now = Temporal.Now.instant();
+  await txDb.insertOne(capReservationsTable, {
+    id,
+    capName: draft.capName,
+    kind: draft.kind,
+    periodStartIso: draft.periodStartIso ?? null,
+    amount: draft.amount,
+    expiresAt: now.add({ minutes: CAP_RESERVATION_TTL_MINUTES }),
+    createdAt: now,
+  });
+}
+
+function toHandle(ctx: HandlerContext, id: string): ReservationHandle {
+  return {
+    release: () => releaseCapReservation(ctx, id),
+    confirmInTransaction: (confirm) => confirmCapReservation(confirm, id),
+  };
+}
+
+export type ReserveCalendarCapOptions = Required<
+  Pick<BookCapUsageOptions, "capName" | "periodStartIso" | "amount">
+> &
+  Pick<BookCapUsageOptions, "guardCurrentValue">;
+
+// 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,
+  options: ReserveCalendarCapOptions,
+): Promise<ReservationHandle> {
+  const outsideDb = requireOutsideTransactionDb(ctx);
+  const id = generateId();
+  const reserved = await retryCounterWriteOnVersionConflict(() =>
+    runInOwnTransaction(outsideDb, async (txDb) => {
+      const booked = await applyCapDeltaOn(txDb, ctx.user, options, "add");
+      if (!booked.isSuccess) return booked;
+      await insertReservationRow(txDb, id, {
+        capName: options.capName,
+        kind: "calendar",
+        periodStartIso: options.periodStartIso,
+        amount: options.amount,
+      });
+      return booked;
+    }),
+  );
+  if (!reserved.isSuccess) throw reraiseAsKumikoError(reserved.error);
+  return toHandle(ctx, id);
+}
+
+export type ReserveRollingCapOptions = ReadRollingCapUsageOptions & {
+  readonly amount: number;
+  // Runs on every attempt with the usage seen by that attempt's append.
+  readonly guardCurrentValue?: (currentValue: number) => void;
+};
+
+function rollingEvent(
+  user: SessionUser,
+  capName: string,
+  amount: number,
+  expectedVersion: number,
+  type: string,
+) {
+  return {
+    aggregateId: rollingCapAggregateId(user.tenantId, capName),
+    aggregateType: CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
+    expectedVersion,
+    type,
+    payload: { capName, amount },
+    metadata: { userId: user.id },
+  };
+}
+
+// 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,
+  options: ReserveRollingCapOptions,
+): Promise<ReservationHandle> {
+  const outsideDb = requireOutsideTransactionDb(ctx);
+  const id = generateId();
+  const aggregateId = rollingCapAggregateId(ctx.user.tenantId, options.capName);
+  await retryOnStreamVersionConflict(() =>
+    runInOwnTransaction(outsideDb, async (txDb) => {
+      const version = await getStreamVersionInTenantDb(txDb, aggregateId);
+      const usage = await readRollingCapUsage(txDb, ctx.user.tenantId, options);
+      options.guardCurrentValue?.(usage);
+      await appendEventInTenantDb(
+        txDb,
+        rollingEvent(
+          ctx.user,
+          options.capName,
+          options.amount,
+          version,
+          ROLLING_INCREMENTED_EVENT_QN,
+        ),
+      );
+      await insertReservationRow(txDb, id, {
+        capName: options.capName,
+        kind: "rolling",
+        amount: options.amount,
+      });
+      return NOTHING_TO_RELEASE;
+    }),
+  );
+  return toHandle(ctx, id);
+}
+
+// Deleting the row takes its row lock inside the handler transaction, so a release started after a
+// failed COMMIT waits for the real outcome and finds the row gone when the commit went through.
+async function confirmCapReservation(
+  confirm: ReservationConfirmContext,
+  id: string,
+): Promise<void> {
+  await deleteMany(confirm.tx, capReservationsTable, { id, tenantId: confirm.tenantId });
+}
+
+async function giveBackCalendar(
+  txDb: TenantDb,
+  user: SessionUser,
+  row: CapReservationRow,
+): Promise<WriteResult> {
+  if (row.periodStartIso === null) {
+    throw new Error(`cap-counter: calendar reservation ${row.id} has no period to release against`);
+  }
+  return applyCapDeltaOn(
+    txDb,
+    user,
+    { capName: row.capName, periodStartIso: row.periodStartIso, amount: row.amount },
+    "subtract",
+  );
+}
+
+async function giveBackRolling(
+  txDb: TenantDb,
+  user: SessionUser,
+  row: CapReservationRow,
+): Promise<WriteResult> {
+  const version = await getStreamVersionInTenantDb(
+    txDb,
+    rollingCapAggregateId(user.tenantId, row.capName),
+  );
+  await appendEventInTenantDb(
+    txDb,
+    rollingEvent(user, row.capName, row.amount, version, ROLLING_RELEASED_EVENT_QN),
+  );
+  return NOTHING_TO_RELEASE;
+}
+
+async function giveBackReservation(
+  txDb: TenantDb,
+  user: SessionUser,
+  id: string,
+): Promise<WriteResult> {
+  const row = await txDb.fetchOne<CapReservationRow>(capReservationsTable, { id });
+  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 given =
+    row.kind === "rolling"
+      ? await giveBackRolling(txDb, user, row)
+      : await giveBackCalendar(txDb, user, row);
+  if (!given.isSuccess) return given;
+  await txDb.deleteMany(capReservationsTable, { id });
+  return given;
+}
+
+export async function releaseCapReservation(ctx: HandlerContext, id: string): Promise<void> {
+  const outsideDb = requireOutsideTransactionDb(ctx);
+  const released = await retryOnStreamVersionConflict(() =>
+    retryCounterWriteOnVersionConflict(() =>
+      runInOwnTransaction(outsideDb, (txDb) => giveBackReservation(txDb, ctx.user, id)),
+    ),
+  );
+  if (!released.isSuccess) throw reraiseAsKumikoError(released.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,
+  capName: string,
+): Promise<void> {
+  const outsideDb = requireOutsideTransactionDb(ctx);
+  const expired = await outsideDb.selectMany<Pick<CapReservationRow, "id">>(capReservationsTable, {
+    tenantId: ctx.user.tenantId,
+    capName,
+    expiresAt: { lt: Temporal.Now.instant() },
+  });
+  for (const { id } of expired) {
+    try {
+      await releaseCapReservation(ctx, id);
+    } 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,32 @@
 [
+  {
+    "version": "0.352.0",
+    "type": "breaking",
+    "title": "Calendar cap reservations are stored in the new store_cap_reservations table",
+    "detail": "Capped writes now insert and delete rows in store_cap_reservations, so they fail until the table exists.",
+    "migration": "Generate and apply a migration with `kumiko-schema generate` — capped writes fail without the new store_cap_reservations table"
+  },
+  {
+    "version": "0.352.0",
+    "type": "improvement",
+    "title": "Reservations expire after 60 minutes and are swept before the next reserve of the same cap"
+  },
+  {
+    "version": "0.352.0",
+    "type": "fix",
+    "title": "withCapEnforcement keeps the wrapped handler's settings (rateLimit, additionalRateLimits) and composes with an inner reserveBeforeTransaction"
+  },
+  {
+    "version": "0.352.0",
+    "type": "improvement",
+    "title": "withRollingCapEnforcement reserves before the handler transaction and releases through the new rolling-released event, so rejected or failed writes no longer consume rolling cap"
+  },
+  {
+    "version": "0.352.0",
+    "type": "improvement",
+    "title": "createValueCapGuard rejects a written number outside the min and max of the tenant's tier",
+    "detail": "A number written by a handler can be bounded per tier\n`createValueCapGuard(resolveTierCaps)` returns `checkValueCap` and `withValueCap`. The spec names the payload field, optional `min` and `max` functions over the tier caps (`undefined` means unbounded), an error code and an i18n key. The value is read from the payload or, for entity updates, from `changes`; an absent or non-numeric value passes. A value below the minimum or above the maximum is rejected with `UnprocessableError` and `details: { field, value, min, max }`. `withValueCap` spreads the wrapped handler, so it composes with `withCapEnforcement`."
+  },
   {
     "version": "0.348.0",
     "type": "fix",

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

@@ -20,6 +20,14 @@ export const CAP_COUNTER_ROLLING_AGGREGATE_TYPE = "cap-counter-rolling" as const
 export const ROLLING_INCREMENTED_EVENT_SHORT = "rolling-incremented" as const;
 export const ROLLING_INCREMENTED_EVENT_QN = "cap-counter:event:rolling-incremented" as const;
 
+// Gives back a reserved rolling amount; the window sum is incremented minus released.
+export const ROLLING_RELEASED_EVENT_SHORT = "rolling-released" as const;
+export const ROLLING_RELEASED_EVENT_QN = "cap-counter:event:rolling-released" as const;
+
+// A reservation row older than this is treated as a lost release and given back before the next
+// reservation for the same cap, which bounds the over-count a failed release can leave behind.
+export const CAP_RESERVATION_TTL_MINUTES = 60;
+
 // Qualified write handler names (QN format: scope:type:name).
 export const CapCounterHandlers = {
   increment: "cap-counter:write:increment",

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

@@ -54,6 +54,7 @@ import {
   CAP_COUNTER_FEATURE,
   CAP_COUNTER_LIST_SCREEN_ID,
   ROLLING_INCREMENTED_EVENT_SHORT,
+  ROLLING_RELEASED_EVENT_SHORT,
 } from "./constants.js";
 import { capCounterEntity } from "./entity.js";
 import { getCounterQuery } from "./handlers/get-counter.query.js";
@@ -61,9 +62,11 @@ import { incrementCapHandler } from "./handlers/increment.write.js";
 import {
   incrementRollingCapHandler,
   rollingIncrementedSchema,
+  rollingReleasedSchema,
 } from "./handlers/increment-rolling.write.js";
 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(
@@ -75,6 +78,9 @@ export const capCounterFeature = defineFeature(CAP_COUNTER_FEATURE, (r) => {
     recommended: false,
   });
   r.entity("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
@@ -82,6 +88,7 @@ export const capCounterFeature = defineFeature(CAP_COUNTER_FEATURE, (r) => {
   // "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 write-handlers.
   // - increment: Calendar-Period (CRUD via projection-row).

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

@@ -37,6 +37,11 @@ type IncrementRollingPayload = z.infer<typeof incrementRollingSchema>;
  *  der Caller zahlt amount, wir hängen es 1:1 an den Stream. */
 export const rollingIncrementedSchema = incrementRollingSchema;
 
+/** Payload of the event that gives a reserved rolling amount back. */
+export const rollingReleasedSchema = incrementRollingSchema.extend({
+  amount: z.number().int().positive(),
+});
+
 // Rolling-Increment-Handler — append-only. Race-frei: zwei parallele
 // Increments für (tenant, cap) hängen sich am selben aggregate-stream
 // in unterschiedlichen versions auf, das event-store ordert.

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

@@ -16,6 +16,8 @@ export {
   CapCounterQueries,
   ROLLING_INCREMENTED_EVENT_QN,
   ROLLING_INCREMENTED_EVENT_SHORT,
+  ROLLING_RELEASED_EVENT_QN,
+  ROLLING_RELEASED_EVENT_SHORT,
 } from "./constants.js";
 export {
   CAP_TOLERANCES,
@@ -34,12 +36,19 @@ export {
 } from "./enforce-cap.js";
 export { capCounterEntity } from "./entity.js";
 export { capCounterFeature } from "./feature.js";
+export { readPayloadField } from "./payload-field.js";
 export {
+  type CapGuardContext,
   type CapLimitContext,
   createStockCapGuard,
   type StockCapGuard,
   type StockCapSpec,
 } from "./stock-cap-guard.js";
+export {
+  createValueCapGuard,
+  type ValueCapGuard,
+  type ValueCapSpec,
+} from "./value-cap-guard.js";
 export {
   type CalendarCapDef,
   type CalendarCapResolver,

package/packages/bundled-features/src/cap-counter/payload-field.ts

@@ -0,0 +1,10 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-framework/utils";
+
+// Create payloads are flat, entity update payloads carry the edited fields under `changes`
+// (`{ id, version, changes }`), so a guard that follows one field has to look at both.
+export function readPayloadField(payload: unknown, field: string): unknown {
+  if (!isPlainObject(payload)) return undefined;
+  if (field in payload) return payload[field];
+  const { changes } = payload;
+  return isPlainObject(changes) ? changes[field] : undefined;
+}