@cosmicdrift/kumiko-bundled-features 0.351.0 → 0.352.0

package/dist/cap-counter/book-cap-usage.d.ts

@@ -1,5 +1,7 @@
 import { type TenantDb } from "@cosmicdrift/kumiko-framework/db";
-import { type HandlerContext, type TenantId, type WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import { type HandlerContext, type SessionUser, type TenantId, type WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+export declare function retryCounterWriteOnVersionConflict(writeAttempt: () => Promise<WriteResult>): Promise<WriteResult>;
+export declare function retryOnStreamVersionConflict<T>(attempt: () => Promise<T>): Promise<T>;
 export type BookCapUsageOptions = {
     readonly capName: string;
     readonly periodStartIso: string;
@@ -7,8 +9,10 @@ export type BookCapUsageOptions = {
     readonly outsideTransaction?: boolean;
     readonly guardCurrentValue?: (currentValue: number) => void;
 };
+export declare function requireOutsideTransactionDb(ctx: HandlerContext): TenantDb;
 export declare function bookCapUsage(ctx: HandlerContext, options: BookCapUsageOptions): Promise<WriteResult>;
 export declare function releaseCapUsage(ctx: HandlerContext, options: Omit<BookCapUsageOptions, "guardCurrentValue">): Promise<WriteResult>;
+export declare function applyCapDeltaOn(db: TenantDb, user: SessionUser, options: BookCapUsageOptions, direction: "add" | "subtract"): Promise<WriteResult>;
 export type MarkCapSoftWarnedOptions = {
     readonly capName: string;
     readonly periodStartIso: string;

package/dist/cap-counter/book-cap-usage.js

@@ -1,11 +1,11 @@
 // In-process cap booking for the caller's own tenant; no SystemAdmin dispatch needed.
 import { runInOwnTransaction } from "@cosmicdrift/kumiko-framework/db";
 import { createEntityExecutor, } 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);
 // periodStartIso feeds the aggregate id and Temporal.Instant.from(); a non-instant string would
@@ -26,7 +26,7 @@ const BACKOFF_JITTER_MS_PER_ATTEMPT = 5;
 function sleepMs(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-async function retryCounterWriteOnVersionConflict(writeAttempt) {
+export async function retryCounterWriteOnVersionConflict(writeAttempt) {
     let result = await writeAttempt();
     for (let attempt = 1; attempt < MAX_COUNTER_WRITE_ATTEMPTS && isLostCounterRace(result); attempt++) {
         await sleepMs(Math.random() * attempt * BACKOFF_JITTER_MS_PER_ATTEMPT);
@@ -34,7 +34,21 @@ async function retryCounterWriteOnVersionConflict(writeAttempt) {
     }
     return result;
 }
-function requireOutsideTransactionDb(ctx) {
+// Event-store appends signal a lost race by throwing; the whole attempt (read, guard, append) is repeated.
+export async function retryOnStreamVersionConflict(attempt) {
+    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 function requireOutsideTransactionDb(ctx) {
     if (!ctx.dbOutsideTransaction) {
         throw new Error("cap-counter.bookCapUsage: outsideTransaction requested but ctx.dbOutsideTransaction is undefined");
     }
@@ -47,45 +61,46 @@ export async function bookCapUsage(ctx, options) {
 export async function releaseCapUsage(ctx, options) {
     return applyCapDelta(ctx, options, "subtract");
 }
-async function applyCapDelta(ctx, options, direction) {
+// 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, user, options, direction) {
     const parsed = capBookingSchema.parse(options);
-    const aggregateId = capCounterAggregateId(ctx.user.tenantId, parsed.capName, parsed.periodStartIso);
-    async function attemptWrite(db) {
-        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 currentRow = existing[0];
-        if (!currentRow) {
-            throw new Error("cap-counter.bookCapUsage: row vanished between length-check and read");
-        }
-        const currentValue = currentRow["value"]; // @cast-boundary db-row
-        const currentVersion = currentRow["version"]; // @cast-boundary db-row
-        options.guardCurrentValue?.(currentValue);
-        return executor.update({
+    const aggregateId = capCounterAggregateId(user.tenantId, parsed.capName, parsed.periodStartIso);
+    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),
-            },
-        }, ctx.user, db);
+            capName: parsed.capName,
+            value: parsed.amount,
+            periodStart: Temporal.Instant.from(parsed.periodStartIso),
+            lastSoftWarnedAt: null,
+        }, 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"]; // @cast-boundary db-row
+    const currentVersion = currentRow["version"]; // @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, options, direction) {
     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 async function markCapSoftWarned(ctx, options) {
     const parsed = capPeriodSchema.parse(options);
@@ -117,27 +132,33 @@ export async function markCapSoftWarned(ctx, options) {
     }
     return retryCounterWriteOnVersionConflict(() => attemptMark(ctx.db));
 }
-// 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, tenantId, options) {
+async function sumRollingEventAmounts(db, tenantId, options, type) {
     const aggregateId = rollingCapAggregateId(tenantId, options.capName);
     const cutoff = Temporal.Now.instant().subtract({ hours: options.windowDays * 24 });
     const rows = await db.selectMany(eventsTable, {
         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"];
         if (typeof payload.amount === "number") {
-            value += payload.amount;
+            total += payload.amount;
         }
     }
-    return value;
+    return total;
+}
+// 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, tenantId, options) {
+    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/dist/cap-counter/cap-reservation.d.ts

@@ -0,0 +1,12 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { ReservationHandle } from "@cosmicdrift/kumiko-types/handlers";
+import { type BookCapUsageOptions, type ReadRollingCapUsageOptions } from "./book-cap-usage.js";
+export type ReserveCalendarCapOptions = Required<Pick<BookCapUsageOptions, "capName" | "periodStartIso" | "amount">> & Pick<BookCapUsageOptions, "guardCurrentValue">;
+export declare function reserveCalendarCap(ctx: HandlerContext, options: ReserveCalendarCapOptions): Promise<ReservationHandle>;
+export type ReserveRollingCapOptions = ReadRollingCapUsageOptions & {
+    readonly amount: number;
+    readonly guardCurrentValue?: (currentValue: number) => void;
+};
+export declare function reserveRollingCap(ctx: HandlerContext, options: ReserveRollingCapOptions): Promise<ReservationHandle>;
+export declare function releaseCapReservation(ctx: HandlerContext, id: string): Promise<void>;
+export declare function releaseExpiredCapReservations(ctx: HandlerContext, capName: string): Promise<void>;

package/dist/cap-counter/cap-reservation.js

@@ -0,0 +1,135 @@
+import { deleteMany, runInOwnTransaction } from "@cosmicdrift/kumiko-framework/db";
+import { reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
+import { appendEventInTenantDb, getStreamVersionInTenantDb, } from "@cosmicdrift/kumiko-framework/event-store";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { rollingCapAggregateId } from "./aggregate-id.js";
+import { applyCapDeltaOn, 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";
+const NOTHING_TO_RELEASE = { isSuccess: true, data: {} };
+async function insertReservationRow(txDb, id, draft) {
+    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, id) {
+    return {
+        release: () => releaseCapReservation(ctx, id),
+        confirmInTransaction: (confirm) => confirmCapReservation(confirm, id),
+    };
+}
+// 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, options) {
+    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);
+}
+function rollingEvent(user, capName, amount, expectedVersion, type) {
+    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, options) {
+    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, id) {
+    await deleteMany(confirm.tx, capReservationsTable, { id, tenantId: confirm.tenantId });
+}
+async function giveBackCalendar(txDb, user, row) {
+    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, user, row) {
+    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, user, id) {
+    const row = await txDb.fetchOne(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, id) {
+    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, capName) {
+    const outsideDb = requireOutsideTransactionDb(ctx);
+    const expired = await outsideDb.selectMany(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/dist/cap-counter/constants.d.ts

@@ -3,6 +3,9 @@ export declare const CAP_COUNTER_LIST_SCREEN_ID: "cap-list";
 export declare const CAP_COUNTER_ROLLING_AGGREGATE_TYPE: "cap-counter-rolling";
 export declare const ROLLING_INCREMENTED_EVENT_SHORT: "rolling-incremented";
 export declare const ROLLING_INCREMENTED_EVENT_QN: "cap-counter:event:rolling-incremented";
+export declare const ROLLING_RELEASED_EVENT_SHORT: "rolling-released";
+export declare const ROLLING_RELEASED_EVENT_QN: "cap-counter:event:rolling-released";
+export declare const CAP_RESERVATION_TTL_MINUTES = 60;
 export declare const CapCounterHandlers: {
     readonly increment: "cap-counter:write:increment";
     readonly incrementRolling: "cap-counter:write:increment-rolling";

package/dist/cap-counter/constants.js

@@ -16,6 +16,12 @@ export const CAP_COUNTER_ROLLING_AGGREGATE_TYPE = "cap-counter-rolling";
 // Beide MÜSSEN konsistent sein (drift-pin im feature-test).
 export const ROLLING_INCREMENTED_EVENT_SHORT = "rolling-incremented";
 export const ROLLING_INCREMENTED_EVENT_QN = "cap-counter:event:rolling-incremented";
+// Gives back a reserved rolling amount; the window sum is incremented minus released.
+export const ROLLING_RELEASED_EVENT_SHORT = "rolling-released";
+export const ROLLING_RELEASED_EVENT_QN = "cap-counter:event:rolling-released";
+// 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/dist/cap-counter/feature.js

@@ -45,13 +45,14 @@
 // config, kein secrets, kein tenant-feature nötig. Tenant-Scoping kommt
 // vom Framework-Default (Base-Column tenantId).
 import { access, defineEntityListHandler, defineFeature, } from "@cosmicdrift/kumiko-framework/engine";
-import { CAP_COUNTER_FEATURE, CAP_COUNTER_LIST_SCREEN_ID, ROLLING_INCREMENTED_EVENT_SHORT, } from "./constants.js";
+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";
 import { incrementCapHandler } from "./handlers/increment.write.js";
-import { incrementRollingCapHandler, rollingIncrementedSchema, } from "./handlers/increment-rolling.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("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({
@@ -60,12 +61,16 @@ 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
     // 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 write-handlers.
     // - increment: Calendar-Period (CRUD via projection-row).
     // - increment-rolling: Rolling-Window (Custom-Event, no projection).

package/dist/cap-counter/handlers/increment-rolling.write.d.ts

@@ -6,4 +6,9 @@ export declare const rollingIncrementedSchema: z.ZodObject<{
     capName: z.ZodString;
     amount: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
+/** Payload of the event that gives a reserved rolling amount back. */
+export declare const rollingReleasedSchema: z.ZodObject<{
+    capName: z.ZodString;
+    amount: z.ZodNumber;
+}, z.core.$strip>;
 export declare const incrementRollingCapHandler: WriteHandlerDef;

package/dist/cap-counter/handlers/increment-rolling.write.js

@@ -31,6 +31,10 @@ const incrementRollingSchema = z.object({
 /** Schema des emittierten Custom-Events. Identisch zum Input-Schema:
  *  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/dist/cap-counter/index.d.ts

@@ -1,8 +1,10 @@
 export { capCounterAggregateId, rollingCapAggregateId } from "./aggregate-id.js";
 export { type BookCapUsageOptions, bookCapUsage, type MarkCapSoftWarnedOptions, markCapSoftWarned, type ReadRollingCapUsageOptions, readRollingCapUsage, } from "./book-cap-usage.js";
-export { CAP_COUNTER_FEATURE, CAP_COUNTER_ROLLING_AGGREGATE_TYPE, CapCounterHandlers, CapCounterQueries, ROLLING_INCREMENTED_EVENT_QN, ROLLING_INCREMENTED_EVENT_SHORT, } from "./constants.js";
+export { CAP_COUNTER_FEATURE, CAP_COUNTER_ROLLING_AGGREGATE_TYPE, CapCounterHandlers, CapCounterQueries, ROLLING_INCREMENTED_EVENT_QN, ROLLING_INCREMENTED_EVENT_SHORT, ROLLING_RELEASED_EVENT_QN, ROLLING_RELEASED_EVENT_SHORT, } from "./constants.js";
 export { CAP_TOLERANCES, CapExceededError, type CapToleranceProfile, type CapToleranceProfileName, currentCalendarMonthStartIso, type EnforceCapResult, enforceCap, enforceCapAndMaybeNotify, enforceRollingCap, enforceRollingCapAndMaybeNotify, enforceStockCap, type SoftHitNotifier, type StockCapResult, } from "./enforce-cap.js";
 export { capCounterEntity } from "./entity.js";
 export { capCounterFeature } from "./feature.js";
-export { type CapLimitContext, createStockCapGuard, type StockCapGuard, type StockCapSpec, } from "./stock-cap-guard.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, type RollingCapDef, type RollingCapResolver, withCapEnforcement, withRollingCapEnforcement, } from "./with-cap-enforcement.js";

package/dist/cap-counter/index.js

@@ -1,9 +1,11 @@
 // Public API of the cap-counter bundled-feature.
 export { capCounterAggregateId, rollingCapAggregateId } from "./aggregate-id.js";
 export { bookCapUsage, markCapSoftWarned, readRollingCapUsage, } from "./book-cap-usage.js";
-export { CAP_COUNTER_FEATURE, CAP_COUNTER_ROLLING_AGGREGATE_TYPE, CapCounterHandlers, CapCounterQueries, ROLLING_INCREMENTED_EVENT_QN, ROLLING_INCREMENTED_EVENT_SHORT, } from "./constants.js";
+export { CAP_COUNTER_FEATURE, CAP_COUNTER_ROLLING_AGGREGATE_TYPE, CapCounterHandlers, CapCounterQueries, ROLLING_INCREMENTED_EVENT_QN, ROLLING_INCREMENTED_EVENT_SHORT, ROLLING_RELEASED_EVENT_QN, ROLLING_RELEASED_EVENT_SHORT, } from "./constants.js";
 export { CAP_TOLERANCES, CapExceededError, currentCalendarMonthStartIso, enforceCap, enforceCapAndMaybeNotify, enforceRollingCap, enforceRollingCapAndMaybeNotify, enforceStockCap, } from "./enforce-cap.js";
 export { capCounterEntity } from "./entity.js";
 export { capCounterFeature } from "./feature.js";
+export { readPayloadField } from "./payload-field.js";
 export { createStockCapGuard, } from "./stock-cap-guard.js";
+export { createValueCapGuard, } from "./value-cap-guard.js";
 export { withCapEnforcement, withRollingCapEnforcement, } from "./with-cap-enforcement.js";

package/dist/cap-counter/payload-field.d.ts

@@ -0,0 +1 @@
+export declare function readPayloadField(payload: unknown, field: string): unknown;

package/dist/cap-counter/payload-field.js

@@ -0,0 +1,11 @@
+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, field) {
+    if (!isPlainObject(payload))
+        return undefined;
+    if (field in payload)
+        return payload[field];
+    const { changes } = payload;
+    return isPlainObject(changes) ? changes[field] : undefined;
+}

package/dist/cap-counter/reservation-chain.d.ts

@@ -0,0 +1,2 @@
+import type { PreTransactionReservation } from "@cosmicdrift/kumiko-types/handlers";
+export declare function chainReservations(inner: PreTransactionReservation | undefined, own: PreTransactionReservation): PreTransactionReservation;

package/dist/cap-counter/reservation-chain.js

@@ -0,0 +1,44 @@
+function toHandle(outcome) {
+    if (outcome === undefined)
+        return { release: async () => { }, confirmInTransaction: async () => { } };
+    if (typeof outcome === "function") {
+        return { release: outcome, confirmInTransaction: async () => { } };
+    }
+    return outcome;
+}
+// Runs `inner` first, then `own`; a failing `own` gives the inner reservation back before it
+// throws. Release goes in reverse order, confirm covers both.
+export function chainReservations(inner, own) {
+    if (!inner)
+        return own;
+    return async (event, ctx) => {
+        const innerHandle = toHandle(await inner(event, ctx));
+        let ownHandle;
+        try {
+            ownHandle = toHandle(await own(event, ctx));
+        }
+        catch (error) {
+            try {
+                await innerHandle.release();
+            }
+            catch (releaseError) {
+                ctx.log?.error("releasing the inner cap reservation failed", { error: releaseError });
+            }
+            throw error;
+        }
+        return {
+            release: async () => {
+                try {
+                    await ownHandle.release();
+                }
+                finally {
+                    await innerHandle.release();
+                }
+            },
+            confirmInTransaction: async (confirm) => {
+                await innerHandle.confirmInTransaction(confirm);
+                await ownHandle.confirmInTransaction(confirm);
+            },
+        };
+    };
+}

package/dist/cap-counter/stock-cap-guard.d.ts

@@ -4,6 +4,9 @@ import { type WriteFailure } from "@cosmicdrift/kumiko-framework/errors";
 export type CapLimitContext = {
     readonly config?: ConfigAccessor;
 };
+export type CapGuardContext = CapLimitContext & {
+    readonly db: TenantDb;
+};
 export type StockCapSpec<TCaps> = {
     readonly table: SchemaTable | EntityTableMeta;
     readonly limit: (caps: TCaps) => number;

package/dist/cap-counter/tables.d.ts

@@ -0,0 +1,3 @@
+import { type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+export declare const capReservationsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const capReservationsTableMeta: EntityTableMeta;

package/dist/cap-counter/tables.js

@@ -0,0 +1,36 @@
+import { defineUnmanagedTable, index, instant, integer, table as pgTable, text, uuid, } from "@cosmicdrift/kumiko-framework/db";
+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. Unmanaged: the rows are a coordination aid, not state with
+// an event history.
+export const capReservationsTable = pgTable("store_cap_reservations", {
+    id: uuid("id").primaryKey(),
+    tenantId: uuid("tenant_id").notNull(),
+    capName: text("cap_name").notNull(),
+    kind: text("kind").notNull().$type(),
+    // Calendar only: raw string the counter's aggregate id was derived from; a normalized instant could point at another counter.
+    periodStartIso: text("period_start_iso"),
+    amount: integer("amount").notNull(),
+    expiresAt: instant("expires_at").notNull(),
+    createdAt: instant("created_at").notNull(),
+}, (t) => [index(CAP_RESERVATIONS_TENANT_CAP_EXPIRES_INDEX).on(t.tenantId, t.capName, t.expiresAt)]);
+export const capReservationsTableMeta = defineUnmanagedTable({
+    tableName: "store_cap_reservations",
+    indexes: [
+        {
+            name: CAP_RESERVATIONS_TENANT_CAP_EXPIRES_INDEX,
+            columns: ["tenant_id", "cap_name", "expires_at"],
+        },
+    ],
+    columns: [
+        { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+        { name: "tenant_id", pgType: "uuid", notNull: true },
+        { name: "cap_name", pgType: "text", notNull: true },
+        { name: "kind", pgType: "text", notNull: true },
+        { name: "period_start_iso", pgType: "text", notNull: false },
+        { name: "amount", pgType: "integer", notNull: true },
+        { name: "expires_at", pgType: "timestamptz", notNull: true },
+        { name: "created_at", pgType: "timestamptz", notNull: true },
+    ],
+});

package/dist/cap-counter/value-cap-guard.d.ts

@@ -0,0 +1,18 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { type WriteFailure } from "@cosmicdrift/kumiko-framework/errors";
+import type { CapGuardContext, CapLimitContext } from "./stock-cap-guard.js";
+export type ValueCapSpec<TCaps> = {
+    readonly field: string;
+    /** `undefined` = no lower bound for this tier. */
+    readonly min?: (caps: TCaps) => number | undefined;
+    /** `undefined` = no upper bound for this tier. */
+    readonly max?: (caps: TCaps) => number | undefined;
+    readonly code: string;
+    readonly i18nKey: string;
+};
+export type ValueCapGuard<TCaps> = {
+    readonly checkValueCap: (ctx: CapGuardContext, value: unknown, spec: ValueCapSpec<TCaps>) => Promise<WriteFailure | null>;
+    readonly withValueCap: (handler: WriteHandlerDef, spec: ValueCapSpec<TCaps>) => WriteHandlerDef;
+};
+export declare function createValueCapGuard<TCaps>(resolveTierCaps: (db: TenantDb, context: CapLimitContext) => Promise<TCaps>): ValueCapGuard<TCaps>;

package/dist/cap-counter/value-cap-guard.js

@@ -0,0 +1,33 @@
+// Per-tier bounds on a single written number (e.g. a retention period or a page size),
+// next to the stock-cap guard, which bounds how many rows may exist.
+import { UnprocessableError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
+import { readPayloadField } from "./payload-field.js";
+function isOutOfBounds(value, min, max) {
+    return (min !== undefined && value < min) || (max !== undefined && value > max);
+}
+export function createValueCapGuard(resolveTierCaps) {
+    async function checkValueCap(ctx, value, spec) {
+        // skip: an absent or non-numeric value is the schema's business, not a cap violation.
+        if (typeof value !== "number")
+            return null;
+        const caps = await resolveTierCaps(ctx.db, ctx.config ? { config: ctx.config } : {});
+        const min = spec.min?.(caps);
+        const max = spec.max?.(caps);
+        if (!isOutOfBounds(value, min, max))
+            return null;
+        return writeFailure(new UnprocessableError(spec.code, {
+            i18nKey: spec.i18nKey,
+            details: { field: spec.field, value, min, max },
+        }));
+    }
+    function withValueCap(handler, spec) {
+        return {
+            ...handler,
+            handler: async (event, ctx) => {
+                const failure = await checkValueCap(ctx, readPayloadField(event.payload, spec.field), spec);
+                return failure ?? handler.handler(event, ctx);
+            },
+        };
+    }
+    return { checkValueCap, withValueCap };
+}