@cosmicdrift/kumiko-bundled-features 0.351.0 → 0.353.0

package/dist/agent-tools/agent-manifest.js

@@ -1,6 +1,7 @@
 import { hasAccess, isAgentVisibleScreen, resolveAgentExposure, SYSTEM_ONLY_JSON_SCHEMA_KEY, } from "@cosmicdrift/kumiko-framework/engine";
 import { translationValueOtherText } from "@cosmicdrift/kumiko-framework/ui-types";
 import * as z from "zod";
+import { recordManifestDenyQns } from "./manifest-deny-qns.js";
 /** The manifest surfaces one string per locale — a plural entry reads as its
  *  CLDR `other` form since the manifest has no `count` to select a category. */
 function entryAsLabels(entry) {
@@ -232,6 +233,9 @@ function lastSegment(qualifiedId) {
 function detailIdParam(screen) {
     return screen.type === "projectionDetail" ? (screen.idParam ?? "id") : "id";
 }
+function screenTitles(translations, screenId, shortId) {
+    return entryAsLabels(translations[`${screenId}.title`] ?? translations[`screen:${shortId}.title`] ?? {});
+}
 function buildScreens(screens, navs, workspaces, translations, roles, visibleNavIds) {
     const allNavs = [...navs.values()];
     const result = [];
@@ -257,7 +261,7 @@ function buildScreens(screens, navs, workspaces, translations, roles, visibleNav
         result.push({
             id: screen.id,
             type: screen.type,
-            titles: labelsForSuffix(translations, `screen:${shortId}.title`),
+            titles: screenTitles(translations, screen.id, shortId),
             // `screen.description` may be a raw i18n key (`registry.getAllTranslations()`
             // double-prefixes it, see build-app-schema.ts:77-81) — match on suffix like
             // `labelsForSuffix` does for entity/field labels, else fall back to the
@@ -304,7 +308,7 @@ export function buildAgentManifest(registry, options) {
     const navs = buildNavs(navMap, workspaceMap, translations, roles, screenMap);
     const screens = buildScreens(screenMap, navMap, workspaceMap, translations, roles, new Set(navs.map((nav) => nav.id)));
     const workspaces = buildWorkspaces(workspaceMap, translations, roles);
-    return {
+    const manifest = {
         builtForRoles: [...roles],
         features: sortedByKey(features, (f) => f.name),
         entities: sortedByKey(entities, (e) => e.name),
@@ -317,4 +321,6 @@ export function buildAgentManifest(registry, options) {
             ...(options.currency && { currency: options.currency }),
         },
     };
+    recordManifestDenyQns(manifest, new Set(options.denyQns ?? []));
+    return manifest;
 }

package/dist/agent-tools/manifest-deny-qns.d.ts

@@ -0,0 +1,3 @@
+import type { AgentManifest } from "./types.js";
+export declare function recordManifestDenyQns(manifest: AgentManifest, denyQns: ReadonlySet<string>): void;
+export declare function assertCatalogMirrorsManifestDenyQns(manifest: AgentManifest, catalogDenyQns: ReadonlySet<string>): void;

package/dist/agent-tools/manifest-deny-qns.js

@@ -0,0 +1,17 @@
+// The deny list is deliberately not a manifest field (the manifest is prompt
+// payload), so the catalog builder learns it through this side channel to
+// detect a manifest cut that the catalog would silently not mirror.
+const denyQnsByManifest = new WeakMap();
+export function recordManifestDenyQns(manifest, denyQns) {
+    denyQnsByManifest.set(manifest, denyQns);
+}
+export function assertCatalogMirrorsManifestDenyQns(manifest, catalogDenyQns) {
+    const manifestDenyQns = denyQnsByManifest.get(manifest);
+    // skip: manifest has no registered deny list, nothing to mirror
+    if (!manifestDenyQns)
+        return;
+    const missing = [...manifestDenyQns].filter((qn) => !catalogDenyQns.has(qn));
+    if (missing.length > 0) {
+        throw new Error(`agent denyQns passed to buildAgentManifest but not to buildToolCatalog: ${missing.join(", ")} — the catalog would still expose their entity CRUD tools`);
+    }
+}

package/dist/agent-tools/tool-catalog.d.ts

@@ -24,5 +24,6 @@ export declare const OPEN_FORM_TOOL_NAME = "open_form";
  *  to drop an entity CRUD tool, which no `agent.expose` on the manifest side can reach. It is
  *  NOT read off the manifest on purpose — the manifest is prompt payload, and a list of the
  *  handlers the model may not call has no business travelling to the provider. Pass the same
- *  list to `buildAgentManifest` so the manifest stops describing what the catalog withholds. */
+ *  list to `buildAgentManifest` so the manifest stops describing what the catalog withholds;
+ *  a manifest built with `denyQns` that the catalog lacks throws. */
 export declare function buildToolCatalog(registry: RegistrySearchView, manifest: AgentManifest, options: ToolCatalogOptions): ToolCatalog;

package/dist/agent-tools/tool-catalog.js

@@ -1,5 +1,6 @@
 import { hasAccess, normalizeAccessEntry } from "@cosmicdrift/kumiko-framework/engine";
 import { FILTER_OPS, isRecord } from "./filter-ops.js";
+import { assertCatalogMirrorsManifestDenyQns } from "./manifest-deny-qns.js";
 const MAX_TOOL_NAME_LENGTH = 64;
 /** Field types that declare `filterable` (per `packages/framework/src/engine/types/fields.ts`).
  *  Mapped to the JSON-Schema type an LLM tool-call argument should use. `undefined` = field type
@@ -466,13 +467,15 @@ function addClientTools(manifest, mode, sink) {
  *  to drop an entity CRUD tool, which no `agent.expose` on the manifest side can reach. It is
  *  NOT read off the manifest on purpose — the manifest is prompt payload, and a list of the
  *  handlers the model may not call has no business travelling to the provider. Pass the same
- *  list to `buildAgentManifest` so the manifest stops describing what the catalog withholds. */
+ *  list to `buildAgentManifest` so the manifest stops describing what the catalog withholds;
+ *  a manifest built with `denyQns` that the catalog lacks throws. */
 export function buildToolCatalog(registry, manifest, options) {
     const sink = { tools: [], dispatchTable: new Map(), usedNames: new Set() };
     const roleFilter = { roles: manifest.builtForRoles };
     const locale = manifest.tenantSettings.locale;
     const entityByName = new Map(manifest.entities.map((entity) => [entity.name, entity]));
     const denyQns = new Set(options.denyQns ?? []);
+    assertCatalogMirrorsManifestDenyQns(manifest, denyQns);
     addRegistrySearchTools(registry, roleFilter, denyQns, sink);
     const { detailQnByEntity, listQnByEntity, entityListDetailQns } = collectEntityHandlerQns(registry, roleFilter, denyQns);
     addGetTools(registry, detailQnByEntity, entityByName, locale, sink);

package/dist/audit/handlers/list.query.js

@@ -34,7 +34,7 @@ function buildDateRange(from, to) {
 function escapeLikePattern(value) {
     return value.replace(/[\\%_]/g, (m) => `\\${m}`);
 }
-function buildAuditWhere(tenantId, p) {
+function buildAuditWhere(tenantId, p, direction) {
     const where = { tenantId };
     if (p.aggregateType)
         where["aggregateType"] = p.aggregateType;
@@ -50,8 +50,10 @@ function buildAuditWhere(tenantId, p) {
     if (range)
         where["createdAt"] = range;
     const cursor = p.cursor ?? p.before;
+    // The cursor is an event id, so it only walks pages in id order: ascending
+    // pages continue past it, descending pages stop before it.
     if (cursor)
-        where["id"] = { lt: BigInt(cursor) };
+        where["id"] = direction === "asc" ? { gt: BigInt(cursor) } : { lt: BigInt(cursor) };
     return where;
 }
 export const listQuery = defineQueryHandler({
@@ -81,15 +83,17 @@ export const listQuery = defineQueryHandler({
     handler: async (query, ctx) => {
         const p = query.payload;
         const scopeFilter = resolveAuditScopeFilter(query.user, p.scope);
+        const direction = p.sortDirection ?? "desc";
         const where = buildAuditWhere(scopeFilter.tenantId, {
             ...p,
             aggregateType: scopeFilter.aggregateType ?? p.aggregateType,
-        });
+        }, direction);
         const rows = await selectMany(ctx.db, eventsTable, where, {
-            orderBy: {
-                col: query.payload.sort === "type" ? "type" : "createdAt",
-                direction: query.payload.sortDirection ?? "desc",
-            },
+            // `id` as tie-breaker keeps the order total, so pages never overlap.
+            orderBy: [
+                { col: p.sort === "type" ? "type" : "createdAt", direction },
+                { col: "id", direction },
+            ],
             limit: p.limit,
         });
         const serialised = rows.map((r) => ({
@@ -104,7 +108,8 @@ export const listQuery = defineQueryHandler({
             createdBy: r.createdBy,
         }));
         const last = serialised[serialised.length - 1];
-        const nextId = serialised.length === p.limit && last ? last.id : null;
+        // An id cursor cannot resume a type-ordered listing, so that sort is one page.
+        const nextId = serialised.length === p.limit && last && p.sort !== "type" ? last.id : null;
         return {
             rows: serialised,
             nextCursor: nextId,

package/dist/auth-email-password/handlers/signup-confirm.write.js

@@ -124,9 +124,8 @@ export function createSignupConfirmHandler(opts = {}) {
                         displayName,
                         tenantId,
                         tenantKey,
-                        // Tenant-Display-Name als Default = Email. User wechselt das im
-                        // Settings-Screen. Konzept "Tenant" leakt nicht in die Signup-UI.
-                        tenantName: email,
+                        // Generated slug as default name: no personal data (the email) in the tenant name.
+                        tenantName: tenantKey,
                     }, 
                     // #1463: seedTenant's postSave hooks (tier-engine's auto-default-
                     // tier, an app's auto-default-compliance) must fire on self-signup

package/dist/auth-mfa/schema/user-mfa.d.ts

@@ -3,6 +3,7 @@ export declare const userMfaEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -24,6 +25,7 @@ export declare const userMfaEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -45,6 +47,7 @@ export declare const userMfaEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -98,6 +101,7 @@ export declare const userMfaTable: import("@cosmicdrift/kumiko-framework/db").En
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -119,6 +123,7 @@ export declare const userMfaTable: import("@cosmicdrift/kumiko-framework/db").En
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -140,6 +145,7 @@ export declare const userMfaTable: import("@cosmicdrift/kumiko-framework/db").En
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;

package/dist/auth-mfa/screens.js

@@ -47,7 +47,7 @@ export const mfaEnableScreen = {
     confirm: {
         handler: AuthMfaHandlers.enableConfirm,
         fields: {
-            code: { type: "text", required: true, maxLength: 6 },
+            code: { type: "text", required: true, minLength: 6, maxLength: 6 },
         },
         layout: { sections: [{ fields: ["code"] }] },
         carry: ["setupToken"],
@@ -57,7 +57,7 @@ export const mfaEnableScreen = {
 };
 // Either a 6-digit TOTP code or a 9-char recovery code proves possession —
 // same bounds as the disable/regenerate-recovery handler schemas.
-const possessionCodeField = { type: "text", required: true, maxLength: 9 };
+const possessionCodeField = { type: "text", required: true, minLength: 6, maxLength: 9 };
 export const mfaDisableScreen = {
     id: MFA_DISABLE_SCREEN_ID,
     type: "actionForm",

package/dist/billing-foundation/checkout-core.d.ts

@@ -80,6 +80,13 @@ export type OpenCheckoutOptions = {
     readonly baseUrl?: string;
     readonly catalog?: BillingPlanCatalog;
     readonly now: () => Temporal.Instant;
+    /** The caller already ran `assertBillingEnabled` under its own handler name
+     *  (before a costly provider lookup), so the gate is not repeated here. */
+    readonly billingEnabledChecked?: boolean;
+    /** The caller already ran `assertNoActiveSubscription` and passes its result
+     *  (null = tenant has none); mode:"subscription" skips the second read and
+     *  the providerCustomerId check reuses it. */
+    readonly checkedSubscription?: Awaited<ReturnType<typeof getSubscriptionForTenant>>;
 };
 export type OpenCheckoutInput = {
     readonly providerName: string;

package/dist/billing-foundation/checkout-core.js

@@ -249,7 +249,9 @@ export async function assertCheckoutAllowed(ctx, options, input) {
     // Checked before the redirect-origin hardening for every mode — a
     // disabled provider must reject a mode:"payment" checkout just as much
     // as a mode:"subscription" one.
-    await assertBillingEnabled(ctx, plugin, "create-checkout-session");
+    if (options.billingEnabledChecked !== true) {
+        await assertBillingEnabled(ctx, plugin, "create-checkout-session");
+    }
     assertRedirectOrigins([input.successUrl, input.cancelUrl], options.baseUrl);
     const mode = input.mode ?? "subscription";
     // Reused by the providerCustomerId check below to avoid a second lookup
@@ -257,7 +259,10 @@ export async function assertCheckoutAllowed(ctx, options, input) {
     let ownSubscription;
     if (mode === "subscription") {
         assertSubscriptionPriceAllowed(plugin, options.catalog, input);
-        ownSubscription = await assertNoActiveSubscription(ctx, options.now());
+        ownSubscription =
+            options.checkedSubscription !== undefined
+                ? options.checkedSubscription
+                : await assertNoActiveSubscription(ctx, options.now());
     }
     else {
         assertOneOffPriceAllowed(plugin, input);

package/dist/billing-foundation/entities.d.ts

@@ -3,6 +3,7 @@ export declare const subscriptionEntity: import("@cosmicdrift/kumiko-types/field
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -24,6 +25,7 @@ export declare const subscriptionEntity: import("@cosmicdrift/kumiko-types/field
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -45,6 +47,7 @@ export declare const subscriptionEntity: import("@cosmicdrift/kumiko-types/field
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -66,6 +69,7 @@ export declare const subscriptionEntity: import("@cosmicdrift/kumiko-types/field
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -87,6 +91,7 @@ export declare const subscriptionEntity: import("@cosmicdrift/kumiko-types/field
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -141,6 +146,7 @@ export declare const paymentEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -162,6 +168,7 @@ export declare const paymentEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -183,6 +190,7 @@ export declare const paymentEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;

package/dist/billing-foundation/handlers/start-plan-checkout.write.js

@@ -40,7 +40,13 @@ export function createStartPlanCheckoutHandler(options, catalog) {
                 ? await prepareConsent(ctx, consumerProtection, payload.consent, "subscription")
                 : undefined;
             const baseUrl = options.baseUrl ?? "";
-            const result = await openCheckout(ctx, { baseUrl: options.baseUrl, catalog, now: options.now }, {
+            const result = await openCheckout(ctx, {
+                baseUrl: options.baseUrl,
+                catalog,
+                now: options.now,
+                billingEnabledChecked: true,
+                checkedSubscription: existing,
+            }, {
                 providerName,
                 priceId: resolved.priceId,
                 successUrl: joinBaseUrl(baseUrl, catalog.successPath),

package/dist/billing-foundation/projection.d.ts

@@ -3,6 +3,7 @@ export declare const subscriptionsProjectionTable: import("@cosmicdrift/kumiko-f
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -24,6 +25,7 @@ export declare const subscriptionsProjectionTable: import("@cosmicdrift/kumiko-f
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -45,6 +47,7 @@ export declare const subscriptionsProjectionTable: import("@cosmicdrift/kumiko-f
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -66,6 +69,7 @@ export declare const subscriptionsProjectionTable: import("@cosmicdrift/kumiko-f
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -87,6 +91,7 @@ export declare const subscriptionsProjectionTable: import("@cosmicdrift/kumiko-f
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -140,6 +145,7 @@ export declare const paymentsProjectionTable: import("@cosmicdrift/kumiko-framew
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -161,6 +167,7 @@ export declare const paymentsProjectionTable: import("@cosmicdrift/kumiko-framew
         readonly type: "text";
         readonly description?: string;
         readonly maxLength?: number;
+        readonly minLength?: number;
         readonly required?: boolean;
         readonly searchable?: boolean;
         readonly sortable?: boolean;
@@ -182,6 +189,7 @@ export declare const paymentsProjectionTable: import("@cosmicdrift/kumiko-framew
         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/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>;