@cosmicdrift/kumiko-bundled-features 0.350.0 → 0.352.0

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

@@ -16,7 +16,7 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { AUDIT_SCOPE_VALUES } from "../constants.js";
 import { resolveAuditScopeFilter } from "./resolve-audit-tenant.js";

package/dist/auth-email-password/email-templates.js

@@ -8,7 +8,7 @@
 // English ships here. Other languages register via @cosmicdrift/kumiko-locale-*
 // (localeDe() / localeEs() call registerMailTranslations).
 import { mailT, registerMailTranslations } from "@cosmicdrift/kumiko-framework/i18n";
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 export const AUTH_MAIL_EN = {
     "auth.mail.appNameDefault": "Account",
     "auth.mail.reset.subject": "{app} — Reset your password",

package/dist/auth-email-password/handlers/invite-create.write.js

@@ -20,7 +20,7 @@ import { generateToken } from "@cosmicdrift/kumiko-framework/api";
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { access, assignableAppRolesOf, defineWriteHandler, } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 // kumiko-lint-ignore cross-feature-import invite-flow lebt in auth-email-password (Magic-Link-Pattern), DB-row-owner ist tenant-feature
 import { INVITATION_STATUS, tenantInvitationEntity, tenantInvitationsTable, } from "../../tenant/invitation-table.js";

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

@@ -23,7 +23,7 @@
 import { generateToken } from "@cosmicdrift/kumiko-framework/api";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { findSignupHandoverProvider } from "../../shared/index.js";
 import { AUTH_SIGNUP_DEFAULT_TTL_MINUTES } from "../constants.js";

package/dist/auth-email-password/handlers/token-request-handler.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "temporal-polyfill";
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { type AuthUserRow } from "../auth-user-row.js";
 import type { AuthMailContent, AuthMailLocale, RenderTokenContentArgs } from "../email-templates.js";

package/dist/auth-email-password/reset-token.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "temporal-polyfill";
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 export type VerifyResult = {
     readonly ok: true;
     readonly userId: string;

package/dist/auth-email-password/unlock-token.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "temporal-polyfill";
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 export type VerifyResult = {
     readonly ok: true;
     readonly userId: string;

package/dist/auth-email-password/verification-token.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "temporal-polyfill";
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 export type VerifyResult = {
     readonly ok: true;
     readonly userId: string;

package/dist/auth-mfa/handlers/enable-confirm-preauth.write.js

@@ -2,7 +2,7 @@ import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-fr
 import { buildSessionRoles, createSystemUser, defineWriteHandler, } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { burnToken, sessionLocaleField, sessionTimezoneField } from "../../shared/index.js";
 import { USER_STATUS, UserQueries } from "../../user/index.js";

package/dist/auth-mfa/handlers/enable-confirm.write.js

@@ -1,7 +1,7 @@
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { burnToken } from "../../shared/index.js";
 import { base32Decode } from "../base32.js";

package/dist/auth-mfa/hmac-token-codec.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 export type HmacTokenVerifyResult<TPayload> = {
     readonly ok: true;
     readonly payload: TPayload;

package/dist/auth-mfa/hmac-token-codec.js

@@ -1,5 +1,5 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 function hmacSign(input, secret) {
     return createHmac("sha256", secret).update(input).digest("base64url");
 }

package/dist/auth-mfa/mfa-challenge-token.d.ts

@@ -1,5 +1,5 @@
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { type HmacTokenVerifyResult } from "./hmac-token-codec.js";
 export type MfaChallengePayload = {
     readonly userId: string;

package/dist/auth-mfa/mfa-challenge-token.js

@@ -1,4 +1,4 @@
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { createHmacTokenCodec } from "./hmac-token-codec.js";
 function isPayload(value) {
     if (typeof value !== "object" || value === null)

package/dist/auth-mfa/mfa-preauth-setup-token.d.ts

@@ -1,5 +1,5 @@
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { type HmacTokenVerifyResult } from "./hmac-token-codec.js";
 export type MfaPreauthSetupPayload = {
     readonly userId: string;

package/dist/auth-mfa/mfa-preauth-setup-token.js

@@ -1,4 +1,4 @@
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { createHmacTokenCodec } from "./hmac-token-codec.js";
 function isPayload(value) {
     if (typeof value !== "object" || value === null)

package/dist/auth-mfa/mfa-setup-token.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 export type MfaSetupPayload = {
     readonly userId: string;
     readonly totpSecretBase32: string;

package/dist/auth-mfa/mfa-setup-token.js

@@ -10,7 +10,7 @@
 // signed-token.ts (userId-only payload) because setup needs to carry
 // generated secret material, not just re-derive it from a lookup.
 import { createHmac, timingSafeEqual } from "node:crypto";
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 function sign(input, secret) {
     return createHmac("sha256", secret).update(input).digest("base64url");
 }

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

@@ -1,5 +1,5 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
-import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 export declare const BILLING_FOUNDATION_FEATURE: "billing-foundation";
 export declare const SUBSCRIPTION_PROVIDER_EXTENSION: "subscriptionProvider";
 /** delivery notification type of the § 312f contract confirmation mail. */
@@ -119,7 +119,7 @@ export declare const BillingPlanActions: {
 export type BillingPlanAction = (typeof BillingPlanActions)[keyof typeof BillingPlanActions];
 export declare const TERMINAL_SUBSCRIPTION_STATUSES: ReadonlySet<string>;
 export declare function isTerminalSubscriptionStatus(status: string): boolean;
-export declare const STALE_INCOMPLETE_AFTER: TemporalPolyfill.Duration;
+export declare const STALE_INCOMPLETE_AFTER: globalThis.Temporal.Duration;
 /** Time-aware terminal check for the checkout gate: a canceled subscription
  *  is terminal (see `isTerminalSubscriptionStatus`), and so is an
  *  `incomplete` one once it's older than `STALE_INCOMPLETE_AFTER` — every

package/dist/billing-foundation/constants.js

@@ -1,12 +1,6 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
 // @runtime client
-// temporal-polyfill is a plain npm dependency (not a framework runtime
-// module), so importing it here doesn't break browser bundles. Aliased —
-// same reason as event-store.ts's own import: the un-aliased name would
-// shadow the ambient global `Temporal` TYPE every `Temporal.Instant`
-// annotation in this file (and its callers, e.g. StoredEvent.createdAt)
-// resolves against, see #1438.
-import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 // Feature name
 export const BILLING_FOUNDATION_FEATURE = "billing-foundation";
 // Extension-point name fuer Provider-Plugins (subscription-stripe,
@@ -158,7 +152,7 @@ export function isTerminalSubscriptionStatus(status) {
 // after roughly 23 hours; without a matching staleness cutoff on our side, a
 // stale incomplete row would block that tenant from ever starting a new
 // checkout, since the projection has no expiry-triggered event of its own.
-export const STALE_INCOMPLETE_AFTER = TemporalPolyfill.Duration.from({ hours: 24 });
+export const STALE_INCOMPLETE_AFTER = Temporal.Duration.from({ hours: 24 });
 /** Time-aware terminal check for the checkout gate: a canceled subscription
  *  is terminal (see `isTerminalSubscriptionStatus`), and so is an
  *  `incomplete` one once it's older than `STALE_INCOMPLETE_AFTER` — every
@@ -170,10 +164,7 @@ export function isSubscriptionBlockingCheckout(sub, now) {
     if (sub.status !== SubscriptionStatuses.incomplete)
         return true;
     const staleAt = sub.lastChangedAt.add(STALE_INCOMPLETE_AFTER);
-    // @cast-boundary temporal-polyfill-vs-ambient: same TC39 Temporal.Instant
-    // at runtime — row types resolve against ambient Temporal; polyfill Instant
-    // is a separate nominal type across the two .d.ts sources.
-    return (TemporalPolyfill.Instant.compare(now, staleAt) < 0);
+    return Temporal.Instant.compare(now, staleAt) < 0;
 }
 // A subscription in one of these statuses can be switched to a different
 // plan tier via the provider's confirmation page (Stripe portal

package/dist/billing-foundation/consumer-protection/confirmation-mail.js

@@ -1,4 +1,4 @@
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { CONSENT_TEXTS, resolveConsentLocale } from "./consent-text.js";
 const LABELS = {
     de: {

package/dist/billing-foundation/consumer-protection/termination-mail.js

@@ -1,4 +1,4 @@
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { TERMINATION_TEXTS } from "./termination-texts.js";
 const TIME_ZONE_BY_LOCALE = {
     de: "Europe/Berlin",

package/dist/billing-foundation/feature.js

@@ -50,10 +50,7 @@
 // (z.B. für analytics: "wie viele Wechsel im Monat?"), kommt ein
 // `subscription-provider-changed`-event-type später.
 import { defineFeature, EXT_TENANT_DATA, } from "@cosmicdrift/kumiko-framework/engine";
-// Aliased — an un-aliased `Temporal` would shadow the ambient global
-// `Temporal` TYPE `ResolvedBillingFoundationOptions.now`'s return type
-// resolves against, see event-store.ts's own import comment (#1438).
-import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { BILLING_FOUNDATION_FEATURE, SUBSCRIPTION_PROVIDER_EXTENSION, SubscriptionFoundationHandlers, } from "./constants.js";
 import { registerConsumerProtection } from "./consumer-protection/register-consent.js";
 import { paymentEntity, subscriptionEntity } from "./entities.js";
@@ -87,11 +84,7 @@ export function createBillingFoundationFeature(options = {}) {
     // ever calls `Temporal.Now.instant` itself.
     const widened = {
         ...options,
-        // @cast-boundary temporal-polyfill-vs-ambient: same TC39 Temporal.Instant
-        // at runtime — `now` is typed against the ambient Temporal global;
-        // TemporalPolyfill.Now.instant() returns the polyfill's own nominal
-        // Instant type across the two .d.ts sources.
-        now: options.now ?? (() => TemporalPolyfill.Now.instant()),
+        now: options.now ?? (() => Temporal.Now.instant()),
         ...(options.baseUrl !== undefined && {
             baseUrl: options.baseUrl.endsWith("/") ? options.baseUrl.slice(0, -1) : options.baseUrl,
         }),

package/dist/billing-foundation/handlers/sync-subscription.write.js

@@ -14,23 +14,20 @@
 // the same reason. A human SystemAdmin can still dispatch this directly.
 import { createHash } from "node:crypto";
 import { SYSTEM_ROLE } from "@cosmicdrift/kumiko-framework/engine";
-// Aliased — an un-aliased `Temporal` would shadow the ambient global
-// `Temporal` TYPE `SubscriptionView.currentPeriodEnd`/`.cancelAt` resolve
-// against, same reasoning as constants.ts's own import.
-import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { findProviderPlugin } from "../checkout-core.js";
 import { isTerminalSubscriptionStatus, SubscriptionEventTypes } from "../constants.js";
 import { getSubscriptionForTenant } from "../get-subscription-for-tenant.js";
 import { appendSubscriptionEvent } from "./process-event.write.js";
 export const syncSubscriptionSchema = z.object({}).strict();
-// Parses both sides fresh via the polyfill before comparing — tolerant of a
+// Parses both sides fresh via Temporal before comparing — tolerant of a
 // provider snapshot's ISO string using a different (but equivalent)
 // representation than `Temporal.Instant#toString()`'s canonical form
 // (offset spelling, sub-second precision, ...), unlike a plain `===` on the
 // raw strings.
 function isoInstantsEqual(a, b) {
-    return (TemporalPolyfill.Instant.compare(TemporalPolyfill.Instant.from(a), TemporalPolyfill.Instant.from(b)) === 0);
+    return Temporal.Instant.compare(Temporal.Instant.from(a), Temporal.Instant.from(b)) === 0;
 }
 // Deterministic per (snapshot-content, current stream head) — not per-call.
 // Folding in `lastChangedAt` (not just the snapshot's own fields) closes a

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 { Temporal } from "temporal-polyfill";
+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";