@nehorai/credits 2.1.0 → 2.2.0

package/dist/index.d.cts

@@ -1,10 +1,10 @@
-import { S as SubscriptionTier, T as TierConfig, a as PortableReservation } from './types-Dzc443vy.cjs';
-export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, C as CreditOperationType, b as CreditSource, D as DeductCreditsResult, J as JournalReferenceType, M as MonthlyResetResult, f as PortableJournalEntry, P as PortableTransaction, d as PortableUsageLog, c as PortableUserCredits, R as ReservationStatus, h as ResourceType, g as SDKCreditCheckResult, e as SubscriptionExpiryResult, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, c as UserCredits, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from './types-Dzc443vy.cjs';
-export { A as AddCreditsAtomicOptions, a as AddCreditsOutcome, b as AddCreditsV2Input, C as CommitOutcome, c as CreateJournalEntryInput, d as CreateReservationInput, e as CreateTransactionInput, f as CreateUsageLogInput, g as CreditBalanceUpdate, h as CreditRepositoryFactory, E as ExpireOutcome, i as ExpireReservationV2Options, I as ICreditRepository, j as ICreditRepositoryCreditsV2, k as ICreditRepositoryV2, J as JournalEntryQuery, R as ReleaseOutcome, l as ReservationTransitionOptions, m as ReserveCreditsV2Input, n as ReserveOutcome, T as TerminalReservationStatus, o as TierUpdateInput, U as UsageLogQuery, p as isCreditedOutcome, q as isReservedOutcome, r as isWinningOutcome, s as reservationJournalKey, t as supportsCreditsV2, u as supportsIdempotentCredit, v as toClientUserCredits } from './types-wtksMa4n.cjs';
-export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, CreditErrorCodeType, PaymentEventPayload, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, ReservationIntegrityView, StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, assertDirectStatusWriteAllowed, assertHoldPlaced, assertKnownReservationStatus, assertPublicJournalKey, assertRepresentableAmount, assertRepresentableFields, assertRepresentableTierAmount, assertUnkeyedDirectReservation, assertUnreferencedDirectTransaction, assertValidCreditAmount, assertValidIdempotencyKey, assertValidStoredAmount, assertValidStoredAmountRaw, backedBalanceFloor, classifyDatabaseError, commitReservationWithJournal, createIdempotencyConflictError, createInsufficientCreditsError, createInvalidAmountError, createInvalidOperationTypeError, createPaymentRefConflictError, createReservationAlreadyProcessedError, createReservationExpiredError, createReservationNotFoundError, createTransientError, createUnsupportedOperationError, createUserNotFoundError, describePaymentMismatch, getSqlState, hasPlacedHold, isCreditError, isIdempotencyConflictError, isInsufficientCreditsError, isRepresentableAmount, isReservationStatus, isReservedJournalKey, isTerminalReservationStatus, isTransientDatabaseError, isTransientError, isUniqueViolation, isValidCreditAmount, isValidIdempotencyKey, normalizePaymentRef, numericToCents, releaseReservationWithJournal, reserveCreditsForOperation, sameAmount, storedMonthlyLimit, sumAmounts, terminalStatusOf, toCents } from './core/index.cjs';
+import { S as SubscriptionTier, T as TierConfig, a as PortableReservation } from './types-MaViK5tD.cjs';
+export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, C as CreditOperationType, b as CreditSource, D as DeductCreditsResult, J as JournalReferenceType, M as MonthlyResetResult, f as PortableJournalEntry, P as PortableTransaction, d as PortableUsageLog, c as PortableUserCredits, R as ReservationStatus, h as ResourceType, g as SDKCreditCheckResult, e as SubscriptionExpiryResult, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, c as UserCredits, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from './types-MaViK5tD.cjs';
+export { A as AddCreditsAtomicOptions, a as AddCreditsOutcome, b as AddCreditsV2Input, C as CommitOutcome, c as CreateJournalEntryInput, d as CreateReservationInput, e as CreateTransactionInput, f as CreateUsageLogInput, g as CreditBalanceUpdate, h as CreditPolicyOptions, i as CreditRepositoryFactory, E as ExpireOutcome, j as ExpireReservationV2Options, I as ICreditRepository, k as ICreditRepositoryCreditsV2, l as ICreditRepositoryV2, J as JournalEntryQuery, R as ReleaseOutcome, m as ReservationTransitionOptions, n as ReserveCreditsV2Input, o as ReserveOutcome, T as TerminalReservationStatus, p as TierUpdateInput, U as UsageLogQuery, q as isCreditedOutcome, r as isReservedOutcome, s as isWinningOutcome, t as reservationJournalKey, u as supportsCreditsV2, v as supportsIdempotentCredit, w as toClientUserCredits } from './types-XSjNXO5l.cjs';
+export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, CreditErrorCodeType, PaymentEventPayload, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, ReservationIntegrityView, StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, assertDirectStatusWriteAllowed, assertHoldPlaced, assertKnownReservationStatus, assertPublicJournalKey, assertRepresentableAmount, assertRepresentableFields, assertRepresentableTierAmount, assertUnkeyedDirectReservation, assertUnreferencedDirectTransaction, assertValidBalanceTarget, assertValidCreditAmount, assertValidIdempotencyKey, assertValidStoredAmount, assertValidStoredAmountRaw, assertValidTierBalanceInput, attributeExpiredBacking, backedBalanceFloor, cappedBalance, classifyDatabaseError, commitReservationWithJournal, createIdempotencyConflictError, createInsufficientCreditsError, createInvalidAmountError, createInvalidOperationTypeError, createPaymentRefConflictError, createReservationAlreadyProcessedError, createReservationExpiredError, createReservationNotFoundError, createTransientError, createUnsupportedOperationError, createUserNotFoundError, describePaymentMismatch, expiredHoldBackingPatch, getSqlState, hasPlacedHold, isCreditError, isIdempotencyConflictError, isInsufficientCreditsError, isRepresentableAmount, isReservationStatus, isReservedJournalKey, isTerminalReservationStatus, isTransientDatabaseError, isTransientError, isUniqueViolation, isValidCreditAmount, isValidIdempotencyKey, normalizePaymentRef, numericToCents, planBalanceCap, planBalanceTarget, planHoldCommit, releaseReservationWithJournal, reserveCreditsForOperation, sameAmount, settleExpiredHoldBacking, spendableBalance, storedMonthlyLimit, sumAmounts, terminalStatusOf, toCents } from './core/index.cjs';
 export { D as DeferredExecutor, c as createDeferredExecutor, g as genericDeferred, n as noopDeferred, s as synchronousDeferred } from './deferred-C7rrRfkm.cjs';
 import { z } from 'zod';
-export { InMemoryCreditRepository, addCreditsThroughRepository, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository } from './repository/index.cjs';
+export { BalanceValidationResult, InMemoryCreditRepository, addCreditsThroughRepository, assertValidBalanceUpdate, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository, validateBalanceUpdate } from './repository/index.cjs';
 export { C as CreditsAuthProviderFactory, a as CreditsUser, I as ICreditsAuthProvider } from './types-OZU3I5OM.cjs';
 export { ApiKeyCreditsProvider, createApiKeyProvider, verifyAdminApiKey, verifyBearerToken } from './auth/index.cjs';
 export { CreditsService, DeductCreditsOptions, LowBalanceNotificationCallback, ReserveCreditsOptions, SubscriptionExpiredNotificationCallback, createCreditsService } from './service/index.cjs';
@@ -61,7 +61,7 @@ declare const creditSystemConfigSchema: z.ZodObject<{
      */
     reservationExpiryMs: z.ZodDefault<z.ZodNumber>;
     /**
-     * Default credits for new users (free tier)
+     * Default credits for new users (free tier). 0 means no signup grant.
      */
     defaultFreeCredits: z.ZodDefault<z.ZodNumber>;
     /**

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { S as SubscriptionTier, T as TierConfig, a as PortableReservation } from './types-Dzc443vy.js';
-export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, C as CreditOperationType, b as CreditSource, D as DeductCreditsResult, J as JournalReferenceType, M as MonthlyResetResult, f as PortableJournalEntry, P as PortableTransaction, d as PortableUsageLog, c as PortableUserCredits, R as ReservationStatus, h as ResourceType, g as SDKCreditCheckResult, e as SubscriptionExpiryResult, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, c as UserCredits, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from './types-Dzc443vy.js';
-export { A as AddCreditsAtomicOptions, a as AddCreditsOutcome, b as AddCreditsV2Input, C as CommitOutcome, c as CreateJournalEntryInput, d as CreateReservationInput, e as CreateTransactionInput, f as CreateUsageLogInput, g as CreditBalanceUpdate, h as CreditRepositoryFactory, E as ExpireOutcome, i as ExpireReservationV2Options, I as ICreditRepository, j as ICreditRepositoryCreditsV2, k as ICreditRepositoryV2, J as JournalEntryQuery, R as ReleaseOutcome, l as ReservationTransitionOptions, m as ReserveCreditsV2Input, n as ReserveOutcome, T as TerminalReservationStatus, o as TierUpdateInput, U as UsageLogQuery, p as isCreditedOutcome, q as isReservedOutcome, r as isWinningOutcome, s as reservationJournalKey, t as supportsCreditsV2, u as supportsIdempotentCredit, v as toClientUserCredits } from './types-BhCdep_t.js';
-export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, CreditErrorCodeType, PaymentEventPayload, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, ReservationIntegrityView, StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, assertDirectStatusWriteAllowed, assertHoldPlaced, assertKnownReservationStatus, assertPublicJournalKey, assertRepresentableAmount, assertRepresentableFields, assertRepresentableTierAmount, assertUnkeyedDirectReservation, assertUnreferencedDirectTransaction, assertValidCreditAmount, assertValidIdempotencyKey, assertValidStoredAmount, assertValidStoredAmountRaw, backedBalanceFloor, classifyDatabaseError, commitReservationWithJournal, createIdempotencyConflictError, createInsufficientCreditsError, createInvalidAmountError, createInvalidOperationTypeError, createPaymentRefConflictError, createReservationAlreadyProcessedError, createReservationExpiredError, createReservationNotFoundError, createTransientError, createUnsupportedOperationError, createUserNotFoundError, describePaymentMismatch, getSqlState, hasPlacedHold, isCreditError, isIdempotencyConflictError, isInsufficientCreditsError, isRepresentableAmount, isReservationStatus, isReservedJournalKey, isTerminalReservationStatus, isTransientDatabaseError, isTransientError, isUniqueViolation, isValidCreditAmount, isValidIdempotencyKey, normalizePaymentRef, numericToCents, releaseReservationWithJournal, reserveCreditsForOperation, sameAmount, storedMonthlyLimit, sumAmounts, terminalStatusOf, toCents } from './core/index.js';
+import { S as SubscriptionTier, T as TierConfig, a as PortableReservation } from './types-MaViK5tD.js';
+export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, C as CreditOperationType, b as CreditSource, D as DeductCreditsResult, J as JournalReferenceType, M as MonthlyResetResult, f as PortableJournalEntry, P as PortableTransaction, d as PortableUsageLog, c as PortableUserCredits, R as ReservationStatus, h as ResourceType, g as SDKCreditCheckResult, e as SubscriptionExpiryResult, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, c as UserCredits, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from './types-MaViK5tD.js';
+export { A as AddCreditsAtomicOptions, a as AddCreditsOutcome, b as AddCreditsV2Input, C as CommitOutcome, c as CreateJournalEntryInput, d as CreateReservationInput, e as CreateTransactionInput, f as CreateUsageLogInput, g as CreditBalanceUpdate, h as CreditPolicyOptions, i as CreditRepositoryFactory, E as ExpireOutcome, j as ExpireReservationV2Options, I as ICreditRepository, k as ICreditRepositoryCreditsV2, l as ICreditRepositoryV2, J as JournalEntryQuery, R as ReleaseOutcome, m as ReservationTransitionOptions, n as ReserveCreditsV2Input, o as ReserveOutcome, T as TerminalReservationStatus, p as TierUpdateInput, U as UsageLogQuery, q as isCreditedOutcome, r as isReservedOutcome, s as isWinningOutcome, t as reservationJournalKey, u as supportsCreditsV2, v as supportsIdempotentCredit, w as toClientUserCredits } from './types-3c-IAwZI.js';
+export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, CreditErrorCodeType, PaymentEventPayload, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, ReservationIntegrityView, StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, assertDirectStatusWriteAllowed, assertHoldPlaced, assertKnownReservationStatus, assertPublicJournalKey, assertRepresentableAmount, assertRepresentableFields, assertRepresentableTierAmount, assertUnkeyedDirectReservation, assertUnreferencedDirectTransaction, assertValidBalanceTarget, assertValidCreditAmount, assertValidIdempotencyKey, assertValidStoredAmount, assertValidStoredAmountRaw, assertValidTierBalanceInput, attributeExpiredBacking, backedBalanceFloor, cappedBalance, classifyDatabaseError, commitReservationWithJournal, createIdempotencyConflictError, createInsufficientCreditsError, createInvalidAmountError, createInvalidOperationTypeError, createPaymentRefConflictError, createReservationAlreadyProcessedError, createReservationExpiredError, createReservationNotFoundError, createTransientError, createUnsupportedOperationError, createUserNotFoundError, describePaymentMismatch, expiredHoldBackingPatch, getSqlState, hasPlacedHold, isCreditError, isIdempotencyConflictError, isInsufficientCreditsError, isRepresentableAmount, isReservationStatus, isReservedJournalKey, isTerminalReservationStatus, isTransientDatabaseError, isTransientError, isUniqueViolation, isValidCreditAmount, isValidIdempotencyKey, normalizePaymentRef, numericToCents, planBalanceCap, planBalanceTarget, planHoldCommit, releaseReservationWithJournal, reserveCreditsForOperation, sameAmount, settleExpiredHoldBacking, spendableBalance, storedMonthlyLimit, sumAmounts, terminalStatusOf, toCents } from './core/index.js';
 export { D as DeferredExecutor, c as createDeferredExecutor, g as genericDeferred, n as noopDeferred, s as synchronousDeferred } from './deferred-C7rrRfkm.js';
 import { z } from 'zod';
-export { InMemoryCreditRepository, addCreditsThroughRepository, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository } from './repository/index.js';
+export { BalanceValidationResult, InMemoryCreditRepository, addCreditsThroughRepository, assertValidBalanceUpdate, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository, validateBalanceUpdate } from './repository/index.js';
 export { C as CreditsAuthProviderFactory, a as CreditsUser, I as ICreditsAuthProvider } from './types-OZU3I5OM.js';
 export { ApiKeyCreditsProvider, createApiKeyProvider, verifyAdminApiKey, verifyBearerToken } from './auth/index.js';
 export { CreditsService, DeductCreditsOptions, LowBalanceNotificationCallback, ReserveCreditsOptions, SubscriptionExpiredNotificationCallback, createCreditsService } from './service/index.js';
@@ -61,7 +61,7 @@ declare const creditSystemConfigSchema: z.ZodObject<{
      */
     reservationExpiryMs: z.ZodDefault<z.ZodNumber>;
     /**
-     * Default credits for new users (free tier)
+     * Default credits for new users (free tier). 0 means no signup grant.
      */
     defaultFreeCredits: z.ZodDefault<z.ZodNumber>;
     /**

package/dist/index.js

@@ -219,6 +219,86 @@ function backedBalanceFloor(reserved, bonusCredits) {
   assertRepresentableAmount(floor, "backedBalanceFloor", { reserved, bonusCredits });
   return floor;
 }
+function cappedBalance(balance, cap, reserved, bonusCredits) {
+  return Math.min(balance, Math.max(cap, backedBalanceFloor(reserved, bonusCredits)));
+}
+function spendableBalance(balance, expiredHoldBacking = 0) {
+  return sumAmounts(balance, -Math.min(expiredHoldBacking, balance));
+}
+function planBalanceTarget(target, reserved, bonusCredits) {
+  const balance = Math.max(target, backedBalanceFloor(reserved, bonusCredits));
+  return { balance, expiredHoldBacking: sumAmounts(balance, -target) };
+}
+function planBalanceCap(balance, cap, reserved, bonusCredits, expiredHoldBacking = 0) {
+  const spendable = spendableBalance(balance, expiredHoldBacking);
+  const target = Math.min(spendable, cap);
+  const kept = Math.max(
+    sumAmounts(balance, -spendable),
+    sumAmounts(backedBalanceFloor(reserved, bonusCredits), -target)
+  );
+  const next = Math.min(balance, sumAmounts(target, kept));
+  return { balance: next, expiredHoldBacking: Math.max(0, sumAmounts(next, -target)) };
+}
+function settleExpiredHoldBacking(balance, expiredHoldBacking, holdBacking) {
+  const held = Math.min(expiredHoldBacking, balance);
+  const used = Math.min(held, holdBacking);
+  return { used, remaining: sumAmounts(held, -used) };
+}
+function planHoldCommit(balance, bonusCredits, expiredHoldBacking, holdBacking, amount) {
+  const backing = settleExpiredHoldBacking(balance, expiredHoldBacking, holdBacking);
+  const rest = sumAmounts(amount, -backing.used);
+  const fromSpendable = Math.min(spendableBalance(balance, expiredHoldBacking), rest);
+  const fromBonus = sumAmounts(rest, -fromSpendable);
+  return {
+    covered: fromBonus <= bonusCredits,
+    balance: sumAmounts(balance, -backing.used, -fromSpendable),
+    bonusCredits: sumAmounts(bonusCredits, -fromBonus),
+    expiredHoldBacking: backing.remaining
+  };
+}
+function attributeExpiredBacking(holds, total) {
+  const placed = holds.filter((hold) => hold.holdPlacedAt).sort(
+    (a, b) => a.holdPlacedAt === b.holdPlacedAt ? a.id < b.id ? -1 : 1 : a.holdPlacedAt < b.holdPlacedAt ? -1 : 1
+  );
+  const shares = /* @__PURE__ */ new Map();
+  let left = total;
+  for (const hold of placed) {
+    const kept = Math.min(hold.expiredBacking ?? 0, hold.amount, left);
+    shares.set(hold.id, kept);
+    left = sumAmounts(left, -kept);
+  }
+  for (const hold of placed) {
+    const share = shares.get(hold.id);
+    const added = Math.min(sumAmounts(hold.amount, -share), left);
+    shares.set(hold.id, sumAmounts(share, added));
+    left = sumAmounts(left, -added);
+  }
+  return shares;
+}
+function expiredHoldBackingPatch(next, stored = 0) {
+  return next > 0 || stored > 0 ? { expiredHoldBacking: next } : {};
+}
+function assertValidBalanceTarget(value, field, context) {
+  assertRepresentableAmount(value, field, context);
+  if (value < 0) {
+    throw new CreditError(
+      `${field} cannot be negative (got ${value})`,
+      CreditErrorCode.INVALID_AMOUNT,
+      { field, value, ...context }
+    );
+  }
+}
+function assertValidTierBalanceInput(input, context) {
+  if (input.balanceCap === void 0) return;
+  if (input.balance !== void 0) {
+    throw new CreditError(
+      "A tier update cannot set both balance and balanceCap",
+      CreditErrorCode.INVALID_AMOUNT,
+      { balance: input.balance, balanceCap: input.balanceCap, ...context }
+    );
+  }
+  assertValidBalanceTarget(input.balanceCap, "balanceCap", context);
+}
 function assertRepresentableTierAmount(value, field, context) {
   if (value === Number.POSITIVE_INFINITY) return;
   assertRepresentableAmount(value, field, context);
@@ -627,9 +707,9 @@ var creditSystemConfigSchema = z.object({
    */
   reservationExpiryMs: z.number().positive().default(5 * 60 * 1e3),
   /**
-   * Default credits for new users (free tier)
+   * Default credits for new users (free tier). 0 means no signup grant.
    */
-  defaultFreeCredits: z.number().positive().default(25),
+  defaultFreeCredits: z.number().min(0).default(25),
   /**
    * Grace period in days after subscription expires before downgrade
    */
@@ -929,6 +1009,8 @@ function toClientUserCredits(credits) {
     monthlyUsed: credits.monthlyUsed,
     monthlyResetAt: toISOString(credits.monthlyResetAt),
     subscriptionExpiresAt: credits.subscriptionExpiresAt ? toISOString(credits.subscriptionExpiresAt) : null,
+    ...credits.expiredHoldBacking !== void 0 ? { expiredHoldBacking: credits.expiredHoldBacking } : {},
+    ...credits.signupGrant !== void 0 ? { signupGrant: credits.signupGrant } : {},
     createdAt: toISOString(credits.createdAt),
     updatedAt: toISOString(credits.updatedAt)
   };
@@ -1160,11 +1242,36 @@ function toDate2(value) {
   return /* @__PURE__ */ new Date();
 }
 function getNextMonthlyReset(from = /* @__PURE__ */ new Date()) {
-  const next = new Date(from);
-  next.setMonth(next.getMonth() + 1);
-  next.setDate(1);
-  next.setHours(0, 0, 0, 0);
-  return next;
+  return new Date(from.getFullYear(), from.getMonth() + 1, 1);
+}
+function validateBalanceUpdate(current, updates) {
+  const next = (base, absolute, increment) => sumAmounts(absolute ?? base, increment ?? 0);
+  const balance = next(current.balance, updates.balance, updates.balanceIncrement);
+  const bonusCredits = next(
+    current.bonusCredits ?? 0,
+    updates.bonusCredits,
+    updates.bonusCreditsIncrement
+  );
+  const reserved = next(current.reserved ?? 0, updates.reserved, updates.reservedIncrement);
+  const errors = [];
+  if (balance < 0) errors.push(`Balance cannot be negative: ${balance}`);
+  const marked = updates.balance === void 0 ? current.expiredHoldBacking ?? 0 : 0;
+  if ((updates.balanceIncrement ?? 0) < 0 && balance >= 0 && balance < marked) {
+    errors.push(`Balance (${balance}) cannot go below expired hold backing (${marked})`);
+  }
+  if (bonusCredits < 0) errors.push(`BonusCredits cannot be negative: ${bonusCredits}`);
+  if (reserved < 0) errors.push(`Reserved cannot be negative: ${reserved}`);
+  const covering = sumAmounts(balance, bonusCredits);
+  if (reserved > covering) {
+    errors.push(`Reserved (${reserved}) exceeds balance + bonusCredits (${covering})`);
+  }
+  return { valid: errors.length === 0, errors };
+}
+function assertValidBalanceUpdate(current, updates) {
+  const result = validateBalanceUpdate(current, updates);
+  if (!result.valid) {
+    throw new Error(`Invalid balance update: ${result.errors.join("; ")}`);
+  }
 }
 
 // src/repository/memory/snapshot.ts
@@ -1344,6 +1451,22 @@ function assertTrustworthy(reservation, transition) {
   assertLockedAmount(reservation, transition);
   assertHoldPlaced(reservation, transition);
 }
+function openHolds(store, userId) {
+  return [...store.reservations.get(userId)?.values() ?? []].filter(
+    (reservation) => reservation.status === "reserved"
+  );
+}
+function writeExpiredHoldBacking(store, credits, next) {
+  const stored = credits.expiredHoldBacking;
+  if (next <= 0 && !stored) return;
+  const holds = openHolds(store, credits.userId);
+  const shares = attributeExpiredBacking(holds, next);
+  for (const hold of holds) {
+    const share = shares.get(hold.id) ?? 0;
+    if (share !== (hold.expiredBacking ?? 0)) hold.expiredBacking = share;
+  }
+  Object.assign(credits, expiredHoldBackingPatch(sumAmounts(...shares.values()), stored));
+}
 function getReservation(store, userId, reservationId) {
   return store.reservations.get(userId)?.get(reservationId);
 }
@@ -1441,16 +1564,22 @@ async function commitReservationV2(store, userId, reservationId, options) {
     const amount = reservation.amount;
     await yieldPoint(store);
     assertReservedCoversHold(credits, userId, reservationId, amount);
-    if (sumAmounts(credits.balance, credits.bonusCredits) < amount) {
+    const paid = planHoldCommit(
+      credits.balance,
+      credits.bonusCredits,
+      credits.expiredHoldBacking ?? 0,
+      reservation.expiredBacking ?? 0,
+      amount
+    );
+    if (!paid.covered) {
       throw new CreditError(
         `Insufficient credits to commit reservation ${reservationId}`,
         CreditErrorCode.INSUFFICIENT_CREDITS,
         { userId, reservationId, required: amount }
       );
     }
-    const fromBalance = Math.min(credits.balance, amount);
-    const nextBalance = sumAmounts(credits.balance, -fromBalance);
-    const nextBonusCredits = sumAmounts(credits.bonusCredits, -sumAmounts(amount, -fromBalance));
+    const nextBalance = paid.balance;
+    const nextBonusCredits = paid.bonusCredits;
     const balanceAfter = sumAmounts(nextBalance, nextBonusCredits);
     const journal = {
       userId,
@@ -1484,6 +1613,10 @@ async function commitReservationV2(store, userId, reservationId, options) {
     credits.bonusCredits = nextBonusCredits;
     credits.reserved = nextReserved;
     credits.monthlyUsed = nextMonthlyUsed;
+    Object.assign(
+      credits,
+      expiredHoldBackingPatch(paid.expiredHoldBacking, credits.expiredHoldBacking)
+    );
     credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     const journalEntryId = commitTransitionJournal(store, journal, existingEntryId);
     return {
@@ -1563,19 +1696,26 @@ function finishUnspent(store, reservation, transition) {
     reservation.id,
     reservation.amount
   );
+  const backing = settleExpiredHoldBacking(
+    credits.balance,
+    credits.expiredHoldBacking ?? 0,
+    reservation.expiredBacking ?? 0
+  );
+  const nextBalance = sumAmounts(credits.balance, -backing.used);
   const journal = {
     userId: reservation.userId,
     operation: `${transition.transition}Reservation`,
     entryType: "credit",
     amount: 0,
-    balanceAfter: sumAmounts(credits.balance, credits.bonusCredits),
+    balanceAfter: sumAmounts(nextBalance, credits.bonusCredits),
     source: transition.source,
     reservationId: reservation.id,
     description: transition.options?.description ?? `${transition.verb} ${reservation.amount} reserved credits for ${getOperationLabel(reservation.operationType)}`,
     metadata: {
       ...transition.options?.metadata,
       operationType: reservation.operationType,
-      amount: reservation.amount
+      amount: reservation.amount,
+      ...backing.used > 0 ? { expiredCreditsRemoved: backing.used } : {}
     },
     idempotencyKey: reservationJournalKey(reservation.id, transition.transition)
   };
@@ -1588,6 +1728,8 @@ function finishUnspent(store, reservation, transition) {
   reservation.status = transition.status;
   reservation.completedAt = (/* @__PURE__ */ new Date()).toISOString();
   credits.reserved = nextReserved;
+  credits.balance = nextBalance;
+  Object.assign(credits, expiredHoldBackingPatch(backing.remaining, credits.expiredHoldBacking));
   credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
   return commitTransitionJournal(store, journal, existingEntryId);
 }
@@ -1598,6 +1740,10 @@ function isoOf(value) {
 }
 var InMemoryCreditRepository = class {
   store = new MemoryStore();
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
   // ==================== User Credits ====================
   /**
    * A copy, never the live record.
@@ -1614,7 +1760,8 @@ var InMemoryCreditRepository = class {
     return copyRecord(credits) ?? null;
   }
   async initializeUserCredits(userId, tier, initialBalance) {
-    return copyRecord(this.seedUser(userId, tier, initialBalance));
+    const existing = this.store.users.get(userId);
+    return copyRecord(existing ?? this.seedUser(userId, tier, initialBalance));
   }
   /**
    * The synchronous body of `initializeUserCredits`.
@@ -1665,8 +1812,11 @@ var InMemoryCreditRepository = class {
     if (!credits) {
       throw new Error(`User ${userId} not found`);
     }
+    assertValidBalanceUpdate(credits, updates);
     const next = { ...credits };
-    if (updates.balance !== void 0) next.balance = updates.balance;
+    if (updates.balance !== void 0) {
+      next.balance = updates.balance;
+    }
     if (updates.bonusCredits !== void 0) next.bonusCredits = updates.bonusCredits;
     if (updates.reserved !== void 0) next.reserved = updates.reserved;
     if (updates.tier !== void 0) next.tier = updates.tier;
@@ -1703,6 +1853,9 @@ var InMemoryCreditRepository = class {
       userId,
       operation: "updateUserCredits"
     });
+    if ((credits.expiredHoldBacking ?? 0) > 0 && updates.balance !== void 0) {
+      writeExpiredHoldBacking(this.store, next, 0);
+    }
     next.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     this.store.users.set(userId, next);
   }
@@ -1711,17 +1864,28 @@ var InMemoryCreditRepository = class {
       { monthlyLimit: input.monthlyLimit, balance: input.balance, monthlyUsed: input.monthlyUsed },
       { userId, operation: "updateUserTier" }
     );
+    assertValidTierBalanceInput(input, { userId, operation: "updateUserTier" });
     const credits = this.store.users.get(userId);
     if (!credits) {
       throw new Error(`User ${userId} not found`);
     }
+    if (input.balanceCap !== void 0 && !isFreeTier(credits.tier)) {
+      const capped = planBalanceCap(
+        credits.balance,
+        input.balanceCap,
+        credits.reserved,
+        credits.bonusCredits,
+        credits.expiredHoldBacking
+      );
+      credits.balance = capped.balance;
+      writeExpiredHoldBacking(this.store, credits, capped.expiredHoldBacking);
+    }
     credits.tier = input.tier;
     credits.monthlyLimit = input.monthlyLimit;
     if (input.balance !== void 0) {
-      credits.balance = Math.max(
-        input.balance,
-        backedBalanceFloor(credits.reserved, credits.bonusCredits)
-      );
+      const planned = planBalanceTarget(input.balance, credits.reserved, credits.bonusCredits);
+      credits.balance = planned.balance;
+      writeExpiredHoldBacking(this.store, credits, planned.expiredHoldBacking);
     }
     if (input.monthlyUsed !== void 0) credits.monthlyUsed = input.monthlyUsed;
     if (input.subscriptionExpiresAt !== void 0) {
@@ -1942,13 +2106,17 @@ var InMemoryCreditRepository = class {
     if (!credits) {
       throw new Error(`User credits not found for userId: ${userId}`);
     }
-    const available = sumAmounts(credits.balance, credits.bonusCredits, -credits.reserved);
+    const spendable = spendableBalance(credits.balance, credits.expiredHoldBacking);
+    const available = Math.min(
+      sumAmounts(credits.balance, credits.bonusCredits, -credits.reserved),
+      sumAmounts(spendable, credits.bonusCredits)
+    );
     if (available < amount) {
       throw new Error(
         `Insufficient credits. Available: ${available}, requested: ${amount}`
       );
     }
-    const balanceDeduction = Math.min(credits.balance, amount);
+    const balanceDeduction = Math.min(spendable, amount);
     const bonusDeduction = sumAmounts(amount, -balanceDeduction);
     const previousBalance = sumAmounts(credits.balance, credits.bonusCredits);
     const nextBalance = sumAmounts(credits.balance, -balanceDeduction);
@@ -2185,7 +2353,11 @@ var InMemoryCreditRepository = class {
     return { expiredCount, creditsReleased, errors };
   }
   // ==================== Atomic Monthly Reset ====================
-  async atomicMonthlyReset(userId, tier, expectedResetAt) {
+  /**
+   * @param _tier - Not trusted. The caller read it earlier and the account may
+   *   have changed tier since, so the reset uses the tier stored on the account.
+   */
+  async atomicMonthlyReset(userId, _tier, expectedResetAt) {
     const credits = this.store.users.get(userId);
     if (!credits) {
       throw new Error(`User ${userId} not found`);
@@ -2195,17 +2367,41 @@ var InMemoryCreditRepository = class {
     if (currentResetAt !== expected) {
       return { wasReset: false, credits: { ...credits } };
     }
-    assertRepresentableTierAmount(getConfigMonthlyLimit(tier), "monthlyLimit", { userId, tier });
+    const tier = credits.tier;
+    const spendable = spendableBalance(credits.balance, credits.expiredHoldBacking);
+    const decision = this.options.resolveMonthlyReset?.({ tier, balance: spendable });
+    if (decision === null) {
+      return { wasReset: false, credits: { ...credits } };
+    }
+    if (decision) {
+      assertValidBalanceTarget(decision.balance, "resolveMonthlyReset balance", { userId, tier });
+      if (decision.monthlyLimit !== void 0) {
+        assertValidBalanceTarget(decision.monthlyLimit, "resolveMonthlyReset monthlyLimit", {
+          userId,
+          tier
+        });
+      }
+    } else {
+      assertRepresentableTierAmount(getConfigMonthlyLimit(tier), "monthlyLimit", { userId, tier });
+    }
     const nextReset = getNextMonthlyReset();
-    const target = monthlyResetBalance(tier);
-    const floor = backedBalanceFloor(credits.reserved, credits.bonusCredits);
     const previousBalance = credits.balance;
-    const newBalance = target.kind === "atLeast" ? Math.max(credits.balance, target.value, floor) : Math.max(target.value, floor);
+    let target;
+    if (decision) {
+      target = decision.balance;
+    } else {
+      const configured = monthlyResetBalance(tier);
+      target = configured.kind === "atLeast" ? Math.max(spendable, configured.value) : configured.value;
+    }
+    const planned = planBalanceTarget(target, credits.reserved, credits.bonusCredits);
+    const newBalance = planned.balance;
     const change = sumAmounts(newBalance, -previousBalance);
     const balanceAfter = sumAmounts(newBalance, credits.bonusCredits);
     assertRepresentableAmount(Math.abs(change), "journal amount", { userId });
     assertRepresentableAmount(balanceAfter, "journal balanceAfter", { userId });
     credits.balance = newBalance;
+    writeExpiredHoldBacking(this.store, credits, planned.expiredHoldBacking);
+    if (decision?.monthlyLimit !== void 0) credits.monthlyLimit = decision.monthlyLimit;
     credits.monthlyUsed = 0;
     credits.monthlyResetAt = nextReset.toISOString();
     credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -2259,23 +2455,34 @@ var InMemoryCreditRepository = class {
       };
     }
     const defaultTier = getDefaultTier();
-    const configured = getConfigMonthlyLimit(defaultTier);
-    assertRepresentableTierAmount(configured, "monthlyLimit", {
-      userId,
-      tier: defaultTier
-    });
-    const limit = storedMonthlyLimit(configured);
+    let limit;
+    if (this.options.getDowngradeBalanceCap) {
+      limit = this.options.getDowngradeBalanceCap();
+      assertValidBalanceTarget(limit, "getDowngradeBalanceCap", { userId, tier: defaultTier });
+    } else {
+      const configured = getConfigMonthlyLimit(defaultTier);
+      assertRepresentableTierAmount(configured, "monthlyLimit", {
+        userId,
+        tier: defaultTier
+      });
+      limit = storedMonthlyLimit(configured);
+    }
     const previousTier = credits.tier;
     const previousBalance = credits.balance;
-    const newBalance = Math.max(
-      Math.min(credits.balance, limit),
-      backedBalanceFloor(credits.reserved, credits.bonusCredits)
+    const planned = planBalanceCap(
+      credits.balance,
+      limit,
+      credits.reserved,
+      credits.bonusCredits,
+      credits.expiredHoldBacking
     );
+    const newBalance = planned.balance;
     const balanceAfter = sumAmounts(newBalance, credits.bonusCredits);
     assertRepresentableAmount(balanceAfter, "journal balanceAfter", { userId });
     credits.tier = defaultTier;
     credits.monthlyLimit = limit;
     credits.balance = newBalance;
+    writeExpiredHoldBacking(this.store, credits, planned.expiredHoldBacking);
     credits.subscriptionExpiresAt = null;
     credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     this.store.users.set(userId, credits);
@@ -2333,8 +2540,8 @@ var InMemoryCreditRepository = class {
     return copyRecords(Array.from(userReservations.values()));
   }
 };
-function createInMemoryCreditRepository() {
-  return new InMemoryCreditRepository();
+function createInMemoryCreditRepository(options = {}) {
+  return new InMemoryCreditRepository(options);
 }
 
 // src/auth/api-key.ts
@@ -2497,9 +2704,11 @@ var CreditsService = class {
             source: "monthly_reset",
             referenceId: `reset-${Date.now()}`,
             referenceType: "reset",
-            description: `Monthly credit reset for ${data.tier} tier.`,
+            // The tier the reset ran on, which a concurrent downgrade may have
+            // changed since `data` was read.
+            description: `Monthly credit reset for ${resetResult.credits.tier} tier.`,
             metadata: {
-              tier: data.tier,
+              tier: resetResult.credits.tier,
               previousBalance: data.balance,
               newBalance: resetResult.credits.balance
             }
@@ -3785,12 +3994,17 @@ export {
   assertRepresentableTierAmount,
   assertUnkeyedDirectReservation,
   assertUnreferencedDirectTransaction,
+  assertValidBalanceTarget,
+  assertValidBalanceUpdate,
   assertValidCreditAmount,
   assertValidIdempotencyKey,
   assertValidStoredAmount,
   assertValidStoredAmountRaw,
+  assertValidTierBalanceInput,
+  attributeExpiredBacking,
   backedBalanceFloor,
   calculateAvailableCredits,
+  cappedBalance,
   checkAndNotifyLowBalance,
   classifyDatabaseError,
   clearConfigProvider,
@@ -3816,6 +4030,7 @@ export {
   createUnsupportedOperationError,
   createUserNotFoundError,
   describePaymentMismatch,
+  expiredHoldBackingPatch,
   generateId,
   generateRequestId2 as generateRequestId,
   genericDeferred,
@@ -3874,6 +4089,9 @@ export {
   parseApiError,
   parseCreditError,
   parseTier,
+  planBalanceCap,
+  planBalanceTarget,
+  planHoldCommit,
   registerConfigProvider,
   registerNotificationHandler,
   releaseReservationWithJournal,
@@ -3883,6 +4101,8 @@ export {
   reserveThroughRepository,
   resetConfig,
   sameAmount,
+  settleExpiredHoldBacking,
+  spendableBalance,
   storedMonthlyLimit,
   sumAmounts,
   supportsCreditsV2,
@@ -3894,6 +4114,7 @@ export {
   toClientUserCredits,
   toDate,
   toPortableTimestamp,
+  validateBalanceUpdate,
   verifyAdminApiKey,
   verifyBearerToken
 };