@cosmicdrift/kumiko-bundled-features 0.351.0 → 0.353.0

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/entity.d.ts

@@ -3,6 +3,7 @@ export declare const capCounterEntity: import("@cosmicdrift/kumiko-types/fields"
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;

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

package/dist/cap-counter/with-cap-enforcement.d.ts

@@ -44,13 +44,11 @@ export type RollingCapResolver = (event: WriteEvent, ctx: HandlerContext) => Pro
 /**
  * Wrap a write-handler with rolling-window cap-enforcement.
  *
- * Same flow as `withCapEnforcement` but uses
- * `enforceRollingCapAndMaybeNotify` + dispatches
- * `cap-counter:write:increment-rolling` post-success.
+ * Same flow as `withCapEnforcement` but uses `enforceRollingCapAndMaybeNotify` and reserves by
+ * appending a `rolling-incremented` event before the handler transaction; a release appends
+ * `rolling-released`.
  *
- * **Notification-Storm-Caveat:** rolling-counter trackt KEIN
- * lastSoftWarnedAt — der Notifier feuert bei JEDEM Call solange
- * der counter im soft-Bereich ist. Caller sollte einen TTL-Cache
- * (`Map<capName, lastNotifiedAt>`) im notify-callback einbauen.
+ * Rolling counters track no lastSoftWarnedAt, so the notifier fires on every call while usage
+ * sits in the soft range; throttle inside the notify callback (e.g. a per-capName TTL cache).
  */
 export declare function withRollingCapEnforcement(handler: WriteHandlerDef, capResolver: RollingCapResolver): WriteHandlerDef;

package/dist/cap-counter/with-cap-enforcement.js

@@ -6,26 +6,26 @@
 // the wrapper keeps the pattern explicit and co-located.
 //
 // **Calendar reservation:** the wrapper only declares the cap; the dispatcher runs the
-// reservation (reserveBeforeTransaction) before the handler transaction opens, in its own short
-// committed write, and releases it after that transaction ended without committing (rollback,
-// failure result, failed COMMIT). No connection is held across the handler, so capped requests
-// cannot exhaust the pool, and the counter stream is not locked while the handler runs. If a
-// COMMIT fails with an unknown outcome the release can under-count; a wrapped handler must not
-// book the same counter itself. Reached through a nested ctx.write the cap is not reserved, so
-// the dispatcher rejects that call unless the top-level batch reserved the same handler.
+// reservation (reserveBeforeTransaction) after all pre-handler gates and before the handler
+// transaction opens, in its own short committed write (counter increment plus a
+// store_cap_reservations row). The handler transaction deletes the row on its own commit; a release
+// after a rollback, failure result or failed COMMIT only gives back what is still booked, so an
+// unknown COMMIT outcome cannot under-count. No connection is held across the handler. Rows a
+// crashed process left behind expire after CAP_RESERVATION_TTL_MINUTES and are given back before the
+// next reserve of the same cap. Reached through a nested ctx.write the cap is not reserved, so the
+// dispatcher rejects that call unless the top-level batch reserved the same handler.
 //
-// Rolling booking still dispatches the SystemAdmin-only increment-rolling
-// handler and has no reservation: it would need a compensating event type,
-// a changed readRollingCapUsage and a version-guarded append behind the
-// SystemAdmin dispatch. Rolling callers need a SystemAdmin identity until
-// cap-counter declares an explicit foreign-booking opt-in.
+// The wrapper spreads the wrapped handler and chains its reserveBeforeTransaction: inner reserves
+// first, release runs in reverse, and an outer failure gives the inner reservation back.
+//
+// Rolling caps reserve the same way: a version-guarded `rolling-incremented` append plus a
+// reservation row, undone by a `rolling-released` event. The window sum is incremented minus released.
 //
 // No automatic markSoftWarned here — that's inside enforceCapAndMaybeNotify
 // (enforce-cap.ts).
-import { reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
-import { bookCapUsage, releaseCapUsage } from "./book-cap-usage.js";
-import { CapCounterHandlers } from "./constants.js";
+import { releaseExpiredCapReservations, reserveCalendarCap, reserveRollingCap, } from "./cap-reservation.js";
 import { assertBelowHardCap, enforceCapAndMaybeNotify, enforceRollingCapAndMaybeNotify, } from "./enforce-cap.js";
+import { chainReservations } from "./reservation-chain.js";
 /**
  * Wrap a write-handler with calendar-period cap-enforcement.
  *
@@ -39,8 +39,9 @@ import { assertBelowHardCap, enforceCapAndMaybeNotify, enforceRollingCapAndMaybe
 export function withCapEnforcement(handler, capResolver) {
     return {
         ...handler,
-        reserveBeforeTransaction: async (event, ctx) => {
+        reserveBeforeTransaction: chainReservations(handler.reserveBeforeTransaction, async (event, ctx) => {
             const cap = await capResolver(event, ctx);
+            await releaseExpiredCapReservations(ctx, cap.capName);
             await enforceCapAndMaybeNotify(ctx, {
                 capName: cap.capName,
                 periodStartIso: cap.periodStartIso,
@@ -51,47 +52,31 @@ export function withCapEnforcement(handler, capResolver) {
                 ...(cap.amount !== undefined && { amount: cap.amount }),
             });
             const amount = cap.amount ?? 1;
-            const reserved = await bookCapUsage(ctx, {
+            return reserveCalendarCap(ctx, {
                 capName: cap.capName,
                 amount,
                 periodStartIso: cap.periodStartIso,
-                outsideTransaction: true,
                 guardCurrentValue: (currentValue) => assertBelowHardCap(currentValue + amount - 1, cap),
             });
-            if (!reserved.isSuccess)
-                throw reraiseAsKumikoError(reserved.error);
-            return async () => {
-                const released = await releaseCapUsage(ctx, {
-                    capName: cap.capName,
-                    amount,
-                    periodStartIso: cap.periodStartIso,
-                    outsideTransaction: true,
-                });
-                if (!released.isSuccess)
-                    throw reraiseAsKumikoError(released.error);
-            };
-        },
+        }),
     };
 }
 /**
  * Wrap a write-handler with rolling-window cap-enforcement.
  *
- * Same flow as `withCapEnforcement` but uses
- * `enforceRollingCapAndMaybeNotify` + dispatches
- * `cap-counter:write:increment-rolling` post-success.
+ * Same flow as `withCapEnforcement` but uses `enforceRollingCapAndMaybeNotify` and reserves by
+ * appending a `rolling-incremented` event before the handler transaction; a release appends
+ * `rolling-released`.
  *
- * **Notification-Storm-Caveat:** rolling-counter trackt KEIN
- * lastSoftWarnedAt — der Notifier feuert bei JEDEM Call solange
- * der counter im soft-Bereich ist. Caller sollte einen TTL-Cache
- * (`Map<capName, lastNotifiedAt>`) im notify-callback einbauen.
+ * Rolling counters track no lastSoftWarnedAt, so the notifier fires on every call while usage
+ * sits in the soft range; throttle inside the notify callback (e.g. a per-capName TTL cache).
  */
 export function withRollingCapEnforcement(handler, capResolver) {
     return {
-        name: handler.name,
-        schema: handler.schema,
-        access: handler.access,
-        handler: async (event, ctx) => {
+        ...handler,
+        reserveBeforeTransaction: chainReservations(handler.reserveBeforeTransaction, async (event, ctx) => {
             const cap = await capResolver(event, ctx);
+            await releaseExpiredCapReservations(ctx, cap.capName);
             await enforceRollingCapAndMaybeNotify(ctx, {
                 capName: cap.capName,
                 windowDays: cap.windowDays,
@@ -99,14 +84,13 @@ export function withRollingCapEnforcement(handler, capResolver) {
                 profile: cap.profile,
                 notify: cap.notify,
             });
-            const result = await handler.handler(event, ctx);
-            if (result.isSuccess) {
-                await ctx.write(CapCounterHandlers.incrementRolling, {
-                    capName: cap.capName,
-                    amount: cap.amount ?? 1,
-                });
-            }
-            return result;
-        },
+            const amount = cap.amount ?? 1;
+            return reserveRollingCap(ctx, {
+                capName: cap.capName,
+                windowDays: cap.windowDays,
+                amount,
+                guardCurrentValue: (usage) => assertBelowHardCap(usage + amount - 1, cap),
+            });
+        }),
     };
 }

package/dist/cap-overview/access.js

@@ -1,4 +1,4 @@
-import { access } from "@cosmicdrift/kumiko-framework/engine";
+import { access, BUILT_IN_MEMBERSHIP_ROLES } from "@cosmicdrift/kumiko-framework/engine";
 // Usage numbers are an operator concern by default; wider visibility is an
 // explicit `usageVisibleTo` opt-in on createCapOverviewFeature. The my-caps
 // screen and the query that fills its cards must carry the SAME rule, or the
@@ -7,14 +7,7 @@ export const DEFAULT_CAP_USAGE_ROLES = access.roles(...access.admin);
 // Roles the engine itself knows (role-assignment.ts ranks). App-declared roles
 // (assignableRole) only exist once the registry is composed, which is after
 // this feature is defined, so they cannot be validated here.
-const BUILT_IN_USAGE_VISIBLE_ROLES = new Set([
-    "User",
-    "Member",
-    "Editor",
-    "Admin",
-    "TenantAdmin",
-    "SystemAdmin",
-]);
+const BUILT_IN_USAGE_VISIBLE_ROLES = new Set(BUILT_IN_MEMBERSHIP_ROLES);
 export function resolveCapUsageRoles(usageVisibleTo) {
     if (usageVisibleTo === undefined)
         return DEFAULT_CAP_USAGE_ROLES;

package/dist/cap-overview/handlers/tenant-caps-list.query.js

@@ -4,7 +4,7 @@ import { definePagedQueryHandler, MAX_LIST_LIMIT, } from "@cosmicdrift/kumiko-fr
 import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { subscriptionsProjectionTable } from "../../billing-foundation/index.js";
-import { tenantTable } from "../../tenant/index.js";
+import { decryptTenantNames, tenantTable } from "../../tenant/index.js";
 import { tierAssignmentEntity } from "../../tier-engine/index.js";
 import { capFieldName } from "../constants.js";
 import { computeFraction } from "../usage-math.js";
@@ -115,7 +115,7 @@ export function createTenantCapsListQuery(caps, listCaps) {
                 });
             }
             const db = ctx.systemDb.acknowledgeCrossTenant("cap-overview:tenant-caps:list — SystemAdmin platform-wide tenant overview");
-            const tenants = await selectMany(db, tenantTable, {});
+            const tenants = await decryptTenantNames(await selectMany(db, tenantTable, {}), "cap-overview:tenant-caps:list");
             const assignments = await selectMany(db, tierAssignmentTable, {});
             const subscriptions = await selectMany(db, subscriptionsProjectionTable, {});
             const assignmentByTenant = new Map(assignments.map((row) => [row.tenantId, row]));