@cosmicdrift/kumiko-samples 0.350.0 → 0.352.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.350.0",
+  "version": "0.352.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.350.0",
+  "version": "0.352.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -164,7 +164,7 @@
     "nodemailer": "^10.0.13",
     "qrcode": "^1.5.4",
     "react": "^19.2.6",
-    "sharp": "^0.35.4",
+    "sharp": "^0.35.5",
     "stripe": "^22.6.2",
     "tailwind-merge": "^3.6.0",
     "temporal-polyfill": "^0.3.2",

package/packages/bundled-features/src/audit/handlers/list.query.ts

@@ -17,7 +17,7 @@
 import { selectMany, type WhereObject } 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/packages/bundled-features/src/auth-email-password/email-templates.ts

@@ -9,7 +9,7 @@
 // (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 type AuthMailLocale = string;
 

package/packages/bundled-features/src/auth-email-password/handlers/invite-accept-with-login.write.ts

@@ -31,7 +31,7 @@ import {
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
-import type { Temporal } from "temporal-polyfill";
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { decryptStoredPii, sessionLocaleField, sessionTimezoneField } from "../../shared/index.js";
 // kumiko-lint-ignore cross-feature-import invite-flow

package/packages/bundled-features/src/auth-email-password/handlers/invite-accept.write.ts

@@ -23,7 +23,7 @@ import {
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
-import type { Temporal } from "temporal-polyfill";
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { decryptStoredPii } from "../../shared/index.js";
 // kumiko-lint-ignore cross-feature-import invite-flow lebt in auth-email-password (Magic-Link), DB-row-owner ist tenant-feature

package/packages/bundled-features/src/auth-email-password/handlers/invite-create.write.ts

@@ -32,7 +32,7 @@ import {
   type WriteFailure,
   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 {

package/packages/bundled-features/src/auth-email-password/handlers/signup-request.write.ts

@@ -24,7 +24,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, type SignupHandoverBinding } from "../../shared/index.js";
 import { AUTH_SIGNUP_DEFAULT_TTL_MINUTES } from "../constants.js";

package/packages/bundled-features/src/auth-email-password/handlers/token-request-handler.ts

@@ -15,7 +15,7 @@
 import { createSystemUser, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { isValidIanaTimeZone } from "@cosmicdrift/kumiko-framework/time";
-import type { Temporal } from "temporal-polyfill";
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { UserQueries } from "../../user/index.js";
 import { type AuthUserRow, parseAuthUserRow } from "../auth-user-row.js";

package/packages/bundled-features/src/auth-email-password/reset-token.ts

@@ -3,7 +3,7 @@
 // the shared HMAC logic lives in one place. verification-token.ts mirrors
 // this pattern with purpose="verify".
 
-import type { Temporal } from "temporal-polyfill";
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { signToken, TokenPurpose, verifyToken } from "./signed-token.js";
 
 export type VerifyResult =

package/packages/bundled-features/src/auth-email-password/unlock-token.ts

@@ -1,7 +1,7 @@
 // Thin wrapper around signed-token.ts pinning the purpose to "unlock".
 // Mirrors reset-token.ts / verification-token.ts.
 
-import type { Temporal } from "temporal-polyfill";
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { signToken, TokenPurpose, verifyToken } from "./signed-token.js";
 
 export type VerifyResult =

package/packages/bundled-features/src/auth-email-password/verification-token.ts

@@ -2,7 +2,7 @@
 // Mirrors reset-token.ts so callers can import a flow-specific helper
 // without knowing the underlying HMAC scheme.
 
-import type { Temporal } from "temporal-polyfill";
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { signToken, TokenPurpose, verifyToken } from "./signed-token.js";
 
 export type VerifyResult =

package/packages/bundled-features/src/auth-mfa/handlers/enable-confirm-preauth.write.ts

@@ -7,7 +7,7 @@ import {
 } 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/packages/bundled-features/src/auth-mfa/handlers/enable-confirm.write.ts

@@ -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/packages/bundled-features/src/auth-mfa/hmac-token-codec.ts

@@ -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: string, secret: string): string {
   return createHmac("sha256", secret).update(input).digest("base64url");

package/packages/bundled-features/src/auth-mfa/mfa-challenge-token.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 { createHmacTokenCodec, type HmacTokenVerifyResult } from "./hmac-token-codec.js";
 
 export type MfaChallengePayload = {

package/packages/bundled-features/src/auth-mfa/mfa-preauth-setup-token.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 { createHmacTokenCodec, type HmacTokenVerifyResult } from "./hmac-token-codec.js";
 
 export type MfaPreauthSetupPayload = {

package/packages/bundled-features/src/auth-mfa/mfa-setup-token.ts

@@ -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";
 
 export type MfaSetupPayload = {
   readonly userId: string;

package/packages/bundled-features/src/billing-foundation/constants.ts

@@ -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" as const;
@@ -185,7 +179,7 @@ export function isTerminalSubscriptionStatus(status: string): boolean {
 // 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
@@ -199,15 +193,7 @@ export function isSubscriptionBlockingCheckout(
   if (isTerminalSubscriptionStatus(sub.status)) return false;
   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 as unknown as InstanceType<typeof TemporalPolyfill.Instant>,
-      staleAt as unknown as InstanceType<typeof TemporalPolyfill.Instant>,
-    ) < 0
-  );
+  return Temporal.Instant.compare(now, staleAt) < 0;
 }
 
 // A subscription in one of these statuses can be switched to a different

package/packages/bundled-features/src/billing-foundation/consumer-protection/confirmation-mail.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type { CheckoutConsentRecordedPayload } from "../events.js";
 import { CONSENT_TEXTS, type ConsentLocale, resolveConsentLocale } from "./consent-text.js";
 

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-mail.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "temporal-polyfill";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type {
   ContractTerminationDeclarationType,
   ContractTerminationKind,

package/packages/bundled-features/src/billing-foundation/feature.ts

@@ -55,10 +55,7 @@ import {
   EXT_TENANT_DATA,
   type FeatureDefinition,
 } 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,
@@ -131,11 +128,7 @@ export function createBillingFoundationFeature<TTier extends string = string>(
   // ever calls `Temporal.Now.instant` itself.
   const widened: ResolvedBillingFoundationOptions = {
     ...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() as unknown as Temporal.Instant),
+    now: options.now ?? (() => Temporal.Now.instant()),
     ...(options.baseUrl !== undefined && {
       baseUrl: options.baseUrl.endsWith("/") ? options.baseUrl.slice(0, -1) : options.baseUrl,
     }),

package/packages/bundled-features/src/billing-foundation/handlers/sync-subscription.write.ts

@@ -15,10 +15,7 @@
 
 import { createHash } from "node:crypto";
 import { SYSTEM_ROLE, type WriteHandlerDef } 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";
@@ -37,18 +34,13 @@ export type SyncSubscriptionResult =
   | { readonly synced: true }
   | { readonly synced: false; readonly reason: SyncSubscriptionSkipReason };
 
-// 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: string, b: string): boolean {
-  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.

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

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