@nehorai/credits 2.2.0 → 3.0.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-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';
+import { S as SubscriptionTier, T as TierConfig, a as PortableReservation } from './types-C3sxDvNb.cjs';
+export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, C as CreditOperationType, b as CreditSource, D as DeductCreditsResult, E as ExpiredBackingFrontier, 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-C3sxDvNb.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, D as DeductJournalInput, 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-DOjguhEX.cjs';
+export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, CreditErrorCodeType, ExpiredBackingAllocation, ExpiredBackingFields, ExpiredBackingHold, ExpiredBackingRewrite, NO_EXPIRED_BACKING_PREFIX, PaymentEventPayload, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, ReservationIntegrityView, StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, allocateExpiredBacking, assertDirectStatusWriteAllowed, assertHoldPlaced, assertKnownReservationStatus, assertPublicJournalKey, assertRepresentableAmount, assertRepresentableFields, assertRepresentableTierAmount, assertUnkeyedDirectReservation, assertUnreferencedDirectTransaction, assertValidBalanceTarget, assertValidCreditAmount, assertValidIdempotencyKey, assertValidStoredAmount, assertValidStoredAmountRaw, assertValidTierBalanceInput, backedBalanceFloor, canonicalAmount, cappedBalance, classifyDatabaseError, commitReservationWithJournal, createIdempotencyConflictError, createInsufficientCreditsError, createInvalidAmountError, createInvalidOperationTypeError, createPaymentRefConflictError, createReservationAlreadyProcessedError, createReservationExpiredError, createReservationNotFoundError, createTransientError, createUnsupportedOperationError, createUserNotFoundError, describePaymentMismatch, expiredBackingPatch, getSqlState, hasPlacedHold, heldExpiredBacking, holdExpiredBacking, holdPlacedAtAfter, isCreditError, isIdempotencyConflictError, isInsufficientCreditsError, isRepresentableAmount, isReservationStatus, isReservedJournalKey, isTerminalReservationStatus, isTransientDatabaseError, isTransientError, isUniqueViolation, isValidCreditAmount, isValidIdempotencyKey, multiplyAmount, normalizePaymentRef, numericToCents, planBalanceCap, planBalanceTarget, planHoldCommit, recordedExpiredBacking, releaseReservationWithJournal, reserveCreditsForOperation, sameAmount, settleExpiredHoldBacking, spendableBalance, storedAmountCeil, storedAmountFloor, 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 { BalanceValidationResult, InMemoryCreditRepository, addCreditsThroughRepository, assertValidBalanceUpdate, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository, validateBalanceUpdate } from './repository/index.cjs';

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-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';
+import { S as SubscriptionTier, T as TierConfig, a as PortableReservation } from './types-C3sxDvNb.js';
+export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, C as CreditOperationType, b as CreditSource, D as DeductCreditsResult, E as ExpiredBackingFrontier, 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-C3sxDvNb.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, D as DeductJournalInput, 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-CY-oHIMA.js';
+export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, CreditErrorCodeType, ExpiredBackingAllocation, ExpiredBackingFields, ExpiredBackingHold, ExpiredBackingRewrite, NO_EXPIRED_BACKING_PREFIX, PaymentEventPayload, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, ReservationIntegrityView, StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, allocateExpiredBacking, assertDirectStatusWriteAllowed, assertHoldPlaced, assertKnownReservationStatus, assertPublicJournalKey, assertRepresentableAmount, assertRepresentableFields, assertRepresentableTierAmount, assertUnkeyedDirectReservation, assertUnreferencedDirectTransaction, assertValidBalanceTarget, assertValidCreditAmount, assertValidIdempotencyKey, assertValidStoredAmount, assertValidStoredAmountRaw, assertValidTierBalanceInput, backedBalanceFloor, canonicalAmount, cappedBalance, classifyDatabaseError, commitReservationWithJournal, createIdempotencyConflictError, createInsufficientCreditsError, createInvalidAmountError, createInvalidOperationTypeError, createPaymentRefConflictError, createReservationAlreadyProcessedError, createReservationExpiredError, createReservationNotFoundError, createTransientError, createUnsupportedOperationError, createUserNotFoundError, describePaymentMismatch, expiredBackingPatch, getSqlState, hasPlacedHold, heldExpiredBacking, holdExpiredBacking, holdPlacedAtAfter, isCreditError, isIdempotencyConflictError, isInsufficientCreditsError, isRepresentableAmount, isReservationStatus, isReservedJournalKey, isTerminalReservationStatus, isTransientDatabaseError, isTransientError, isUniqueViolation, isValidCreditAmount, isValidIdempotencyKey, multiplyAmount, normalizePaymentRef, numericToCents, planBalanceCap, planBalanceTarget, planHoldCommit, recordedExpiredBacking, releaseReservationWithJournal, reserveCreditsForOperation, sameAmount, settleExpiredHoldBacking, spendableBalance, storedAmountCeil, storedAmountFloor, 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 { BalanceValidationResult, InMemoryCreditRepository, addCreditsThroughRepository, assertValidBalanceUpdate, commitThroughRepository, createInMemoryCreditRepository, generateId, getNextMonthlyReset, releaseThroughRepository, reserveThroughRepository, validateBalanceUpdate } from './repository/index.js';

package/dist/index.js

@@ -167,6 +167,40 @@ function floatSum(values) {
   for (const value of values) total += value;
   return total;
 }
+function multiplyAmount(unit, quantity) {
+  const cents = toCents(unit);
+  const product = cents === null ? Number.NaN : cents * quantity;
+  if (cents === null || cents < 0 || !Number.isSafeInteger(quantity) || quantity < 0 || !Number.isSafeInteger(product) || product > MAX_CENTS) {
+    throw new CreditError(
+      `Cannot price ${quantity} units at ${unit}: the price must be a non-negative amount exact to ${CREDIT_AMOUNT_SCALE} decimals, the quantity a whole number, and the result at most ${CREDIT_AMOUNT_MAX}`,
+      CreditErrorCode.INVALID_AMOUNT,
+      { unit, quantity, max: CREDIT_AMOUNT_MAX, scale: CREDIT_AMOUNT_SCALE }
+    );
+  }
+  return product / 100;
+}
+var FLOAT_NOISE_FLOOR = 1e-6;
+var FLOAT_NOISE_RELATIVE = 64 * Number.EPSILON;
+function floatNoise(value) {
+  return Math.max(FLOAT_NOISE_FLOOR, Math.abs(value) * FLOAT_NOISE_RELATIVE);
+}
+function canonicalAmount(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return value;
+  const cents = Math.round(value * 100);
+  if (!Number.isSafeInteger(cents)) return value;
+  const onGrid = cents / 100 + 0;
+  return Math.abs(value - onGrid) < floatNoise(value) ? onGrid : value;
+}
+function storedAmountFloor(value) {
+  const canonical = canonicalAmount(value);
+  if (!Number.isFinite(canonical) || toCents(canonical) !== null) return canonical;
+  return Math.floor(canonical * 100) / 100;
+}
+function storedAmountCeil(value) {
+  const canonical = canonicalAmount(value);
+  if (!Number.isFinite(canonical) || toCents(canonical) !== null) return canonical;
+  return Math.ceil(canonical * 100) / 100;
+}
 function isValidCreditAmount(value) {
   if (typeof value !== "number") return false;
   const cents = toCents(value);
@@ -222,14 +256,19 @@ function backedBalanceFloor(reserved, bonusCredits) {
 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 heldExpiredBacking(balance, stored) {
+  if (!(stored !== void 0 && stored > 0)) return 0;
+  return Math.max(0, Math.min(stored, balance));
+}
+function spendableBalance(balance, expiredHoldBacking) {
+  return sumAmounts(balance, -heldExpiredBacking(balance, expiredHoldBacking));
 }
 function planBalanceTarget(target, reserved, bonusCredits) {
+  assertValidBalanceTarget(target, "balance 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) {
+function planBalanceCap(balance, cap, reserved, bonusCredits, expiredHoldBacking) {
   const spendable = spendableBalance(balance, expiredHoldBacking);
   const target = Math.min(spendable, cap);
   const kept = Math.max(
@@ -240,8 +279,8 @@ function planBalanceCap(balance, cap, reserved, bonusCredits, expiredHoldBacking
   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);
+  const held = heldExpiredBacking(balance, expiredHoldBacking);
+  const used = Math.max(0, Math.min(held, holdBacking));
   return { used, remaining: sumAmounts(held, -used) };
 }
 function planHoldCommit(balance, bonusCredits, expiredHoldBacking, holdBacking, amount) {
@@ -256,27 +295,83 @@ function planHoldCommit(balance, bonusCredits, expiredHoldBacking, holdBacking,
     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);
+var NO_EXPIRED_BACKING_PREFIX = {
+  holdPlacedAt: "",
+  id: "",
+  share: 0
+};
+function compareHolds(a, b) {
+  if (a.holdPlacedAt !== b.holdPlacedAt) return a.holdPlacedAt < b.holdPlacedAt ? -1 : 1;
+  if (a.id === b.id) return 0;
+  return a.id < b.id ? -1 : 1;
+}
+function recordedExpiredBacking(hold) {
+  const stored = hold.expiredBacking;
+  if (typeof stored !== "number" || !Number.isFinite(stored) || stored <= 0) return 0;
+  if (!isValidCreditAmount(hold.amount)) return 0;
+  return Math.min(storedAmountCeil(stored), hold.amount);
+}
+function allocateExpiredBacking(holds, total) {
+  const placed = holds.filter((hold) => hold.holdPlacedAt && isValidCreditAmount(hold.amount)).map((hold) => ({ ...hold, holdPlacedAt: hold.holdPlacedAt })).sort(compareHolds);
+  const wanted = Math.max(0, total);
+  if (wanted === 0) return { total: 0, frontier: null };
+  const recorded = placed.filter((hold) => recordedExpiredBacking(hold) > 0);
+  const shares = new Map(recorded.map((hold) => [hold.id, recordedExpiredBacking(hold)]));
+  let left = sumAmounts(wanted, ...[...shares.values()].map((share) => -share));
+  for (const hold of [...recorded].reverse()) {
+    if (left >= 0) break;
+    const share = shares.get(hold.id);
+    const cut = Math.min(share, -left);
+    shares.set(hold.id, sumAmounts(share, -cut));
+    left = sumAmounts(left, cut);
   }
+  let frontier = NO_EXPIRED_BACKING_PREFIX;
   for (const hold of placed) {
+    if (left <= 0) break;
+    if (shares.has(hold.id)) continue;
+    const share = Math.min(hold.amount, left);
+    frontier = { holdPlacedAt: hold.holdPlacedAt, id: hold.id, share };
+    left = sumAmounts(left, -share);
+  }
+  for (const hold of recorded) {
+    if (left <= 0) break;
     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;
+  const rewrites = recorded.filter((hold) => shares.get(hold.id) !== hold.expiredBacking).map((hold) => ({ id: hold.id, expiredBacking: shares.get(hold.id) }));
+  return { total: wanted, frontier, ...rewrites.length > 0 ? { rewrites } : {} };
 }
-function expiredHoldBackingPatch(next, stored = 0) {
-  return next > 0 || stored > 0 ? { expiredHoldBacking: next } : {};
+function holdExpiredBacking(hold, frontier, rewrites) {
+  const rewritten = rewrites?.find((rewrite) => rewrite.id === hold.id);
+  const recorded = recordedExpiredBacking(
+    rewritten ? { ...hold, expiredBacking: rewritten.expiredBacking } : hold
+  );
+  if (recorded > 0) return recorded;
+  if (!frontier || !hold.holdPlacedAt) return 0;
+  const order = compareHolds({ holdPlacedAt: hold.holdPlacedAt, id: hold.id }, frontier);
+  if (order > 0) return 0;
+  return order < 0 ? hold.amount : Math.min(frontier.share, hold.amount);
+}
+function holdPlacedAtAfter(now, frontier) {
+  if (!frontier?.holdPlacedAt) return now;
+  const earliest = new Date(Date.parse(frontier.holdPlacedAt) + 1).toISOString();
+  return now > earliest ? now : earliest;
+}
+function expiredBackingPatch(next, stored) {
+  const total = Math.max(0, next.total);
+  const patch = {};
+  const storedTotal = stored.expiredHoldBacking;
+  if (total > 0 || storedTotal !== void 0 && storedTotal !== 0) {
+    patch.expiredHoldBacking = total;
+  }
+  if (total <= 0) {
+    if (stored.expiredBackingFrontier) patch.expiredBackingFrontier = null;
+  } else if (next.frontier) {
+    patch.expiredBackingFrontier = next.frontier;
+  }
+  return patch;
 }
 function assertValidBalanceTarget(value, field, context) {
   assertRepresentableAmount(value, field, context);
@@ -289,7 +384,10 @@ function assertValidBalanceTarget(value, field, context) {
   }
 }
 function assertValidTierBalanceInput(input, context) {
-  if (input.balanceCap === void 0) return;
+  if (input.balanceCap === void 0) {
+    if (input.balance !== void 0) assertValidBalanceTarget(input.balance, "balance", context);
+    return;
+  }
   if (input.balance !== void 0) {
     throw new CreditError(
       "A tier update cannot set both balance and balanceCap",
@@ -1255,7 +1353,7 @@ function validateBalanceUpdate(current, updates) {
   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;
+  const marked = updates.balance === void 0 ? heldExpiredBacking(current.balance, current.expiredHoldBacking) : 0;
   if ((updates.balanceIncrement ?? 0) < 0 && balance >= 0 && balance < marked) {
     errors.push(`Balance (${balance}) cannot go below expired hold backing (${marked})`);
   }
@@ -1407,6 +1505,7 @@ function commitTransitionJournal(store, input, existingId) {
     userId: input.userId,
     entryType: input.entryType,
     amount: input.amount,
+    balanceBefore: input.balanceBefore,
     balanceAfter: input.balanceAfter,
     source: input.source,
     referenceId: input.reservationId,
@@ -1456,16 +1555,28 @@ function openHolds(store, userId) {
     (reservation) => reservation.status === "reserved"
   );
 }
+function expiredBackingInForce(store, credits) {
+  const total = heldExpiredBacking(credits.balance, credits.expiredHoldBacking);
+  if (total > 0 && (!credits.expiredBackingFrontier || credits.expiredHoldBacking !== total)) {
+    return allocateExpiredBacking(openHolds(store, credits.userId), total);
+  }
+  return { total, frontier: credits.expiredBackingFrontier ?? null };
+}
+function writeRecordedShares(store, userId, allocation) {
+  for (const { id, expiredBacking } of allocation.rewrites ?? []) {
+    const hold = getReservation(store, userId, id);
+    if (hold) hold.expiredBacking = expiredBacking;
+  }
+}
 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;
+  if (next <= 0) {
+    Object.assign(credits, expiredBackingPatch({ total: 0 }, credits));
+    return;
   }
-  Object.assign(credits, expiredHoldBackingPatch(sumAmounts(...shares.values()), stored));
+  if (next === credits.expiredHoldBacking) return;
+  const allocation = allocateExpiredBacking(openHolds(store, credits.userId), next);
+  writeRecordedShares(store, credits.userId, allocation);
+  Object.assign(credits, expiredBackingPatch(allocation, credits));
 }
 function getReservation(store, userId, reservationId) {
   return store.reservations.get(userId)?.get(reservationId);
@@ -1514,6 +1625,7 @@ async function reserveCreditsV2(store, input) {
       };
     }
     const now = (/* @__PURE__ */ new Date()).toISOString();
+    const backing = expiredBackingInForce(store, credits);
     const reservation = {
       id: generateId(),
       userId: input.userId,
@@ -1526,7 +1638,7 @@ async function reserveCreditsV2(store, input) {
       // The hold-origin fact. Written here and nowhere else, in the same
       // critical section that raises `reserved` below, so the row and the hold
       // become visible together. `createReservation` cannot set it.
-      holdPlacedAt: now
+      holdPlacedAt: holdPlacedAtAfter(now, backing.total > 0 ? backing.frontier : null)
     };
     if (!store.reservations.has(input.userId)) {
       store.reservations.set(input.userId, /* @__PURE__ */ new Map());
@@ -1544,6 +1656,8 @@ async function reserveCreditsV2(store, input) {
       );
     }
     credits.reserved = nextReserved;
+    writeRecordedShares(store, input.userId, backing);
+    Object.assign(credits, expiredBackingPatch(backing, credits));
     credits.updatedAt = now;
     return { outcome: "created", reservation: copyRecord(reservation) };
   });
@@ -1564,11 +1678,12 @@ async function commitReservationV2(store, userId, reservationId, options) {
     const amount = reservation.amount;
     await yieldPoint(store);
     assertReservedCoversHold(credits, userId, reservationId, amount);
+    const backing = expiredBackingInForce(store, credits);
     const paid = planHoldCommit(
       credits.balance,
       credits.bonusCredits,
-      credits.expiredHoldBacking ?? 0,
-      reservation.expiredBacking ?? 0,
+      backing.total,
+      holdExpiredBacking(reservation, backing.frontier, backing.rewrites),
       amount
     );
     if (!paid.covered) {
@@ -1586,6 +1701,7 @@ async function commitReservationV2(store, userId, reservationId, options) {
       operation: "commitReservation",
       entryType: "debit",
       amount,
+      balanceBefore: sumAmounts(credits.balance, credits.bonusCredits),
       balanceAfter,
       source: "operation_commit",
       reservationId,
@@ -1613,9 +1729,10 @@ async function commitReservationV2(store, userId, reservationId, options) {
     credits.bonusCredits = nextBonusCredits;
     credits.reserved = nextReserved;
     credits.monthlyUsed = nextMonthlyUsed;
+    writeRecordedShares(store, userId, backing);
     Object.assign(
       credits,
-      expiredHoldBackingPatch(paid.expiredHoldBacking, credits.expiredHoldBacking)
+      expiredBackingPatch({ total: paid.expiredHoldBacking, frontier: backing.frontier }, credits)
     );
     credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     const journalEntryId = commitTransitionJournal(store, journal, existingEntryId);
@@ -1696,10 +1813,11 @@ function finishUnspent(store, reservation, transition) {
     reservation.id,
     reservation.amount
   );
+  const inForce = expiredBackingInForce(store, credits);
   const backing = settleExpiredHoldBacking(
     credits.balance,
-    credits.expiredHoldBacking ?? 0,
-    reservation.expiredBacking ?? 0
+    inForce.total,
+    holdExpiredBacking(reservation, inForce.frontier, inForce.rewrites)
   );
   const nextBalance = sumAmounts(credits.balance, -backing.used);
   const journal = {
@@ -1707,6 +1825,7 @@ function finishUnspent(store, reservation, transition) {
     operation: `${transition.transition}Reservation`,
     entryType: "credit",
     amount: 0,
+    balanceBefore: sumAmounts(credits.balance, credits.bonusCredits),
     balanceAfter: sumAmounts(nextBalance, credits.bonusCredits),
     source: transition.source,
     reservationId: reservation.id,
@@ -1729,7 +1848,11 @@ function finishUnspent(store, reservation, transition) {
   reservation.completedAt = (/* @__PURE__ */ new Date()).toISOString();
   credits.reserved = nextReserved;
   credits.balance = nextBalance;
-  Object.assign(credits, expiredHoldBackingPatch(backing.remaining, credits.expiredHoldBacking));
+  writeRecordedShares(store, reservation.userId, inForce);
+  Object.assign(
+    credits,
+    expiredBackingPatch({ total: backing.remaining, frontier: inForce.frontier }, credits)
+  );
   credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
   return commitTransitionJournal(store, journal, existingEntryId);
 }
@@ -1772,7 +1895,7 @@ var InMemoryCreditRepository = class {
    * simultaneous first deliveries of the same reference would then both credit.
    */
   seedUser(userId, tier, initialBalance) {
-    assertRepresentableAmount(initialBalance, "initialBalance", { userId });
+    assertValidBalanceTarget(initialBalance, "initialBalance", { userId });
     const configured = getConfigMonthlyLimit(tier);
     assertRepresentableTierAmount(configured, "monthlyLimit", { userId, tier });
     const monthlyLimit = storedMonthlyLimit(configured);
@@ -1853,9 +1976,11 @@ var InMemoryCreditRepository = class {
       userId,
       operation: "updateUserCredits"
     });
-    if ((credits.expiredHoldBacking ?? 0) > 0 && updates.balance !== void 0) {
-      writeExpiredHoldBacking(this.store, next, 0);
-    }
+    writeExpiredHoldBacking(
+      this.store,
+      next,
+      updates.balance !== void 0 ? 0 : Math.min(heldExpiredBacking(credits.balance, credits.expiredHoldBacking), next.balance)
+    );
     next.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     this.store.users.set(userId, next);
   }
@@ -1887,6 +2012,11 @@ var InMemoryCreditRepository = class {
       credits.balance = planned.balance;
       writeExpiredHoldBacking(this.store, credits, planned.expiredHoldBacking);
     }
+    writeExpiredHoldBacking(
+      this.store,
+      credits,
+      heldExpiredBacking(credits.balance, credits.expiredHoldBacking)
+    );
     if (input.monthlyUsed !== void 0) credits.monthlyUsed = input.monthlyUsed;
     if (input.subscriptionExpiresAt !== void 0) {
       if (input.subscriptionExpiresAt === null) {
@@ -2048,6 +2178,11 @@ var InMemoryCreditRepository = class {
       { userId, operation: "addCredits" }
     );
     credits.bonusCredits = nextBonusCredits;
+    writeExpiredHoldBacking(
+      this.store,
+      credits,
+      heldExpiredBacking(credits.balance, credits.expiredHoldBacking)
+    );
     credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     this.store.users.set(userId, credits);
     const transaction = this.recordTransaction({
@@ -2067,6 +2202,7 @@ var InMemoryCreditRepository = class {
       userId,
       entryType: "credit",
       amount,
+      balanceBefore: previousTotal,
       balanceAfter: newTotal,
       source: payload.source,
       referenceId: transaction.id ?? paymentRef ?? "unknown",
@@ -2100,7 +2236,7 @@ var InMemoryCreditRepository = class {
       });
     }
   }
-  async deductCreditsAtomic(userId, amount) {
+  async deductCreditsAtomic(userId, amount, journal) {
     assertValidCreditAmount(amount, { userId, operation: "deductCredits" });
     const credits = this.store.users.get(userId);
     if (!credits) {
@@ -2126,11 +2262,26 @@ var InMemoryCreditRepository = class {
       { previousBalance, balance: nextBalance, bonusCredits: nextBonusCredits, newBalance },
       { userId, operation: "deductCredits" }
     );
+    const held = heldExpiredBacking(credits.balance, credits.expiredHoldBacking);
     credits.balance = nextBalance;
     credits.bonusCredits = nextBonusCredits;
+    writeExpiredHoldBacking(this.store, credits, held);
     credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     this.store.users.set(userId, credits);
-    return { previousBalance, newBalance };
+    if (!journal) return { previousBalance, newBalance };
+    const entry = this.recordJournalEntry({
+      userId,
+      entryType: "debit",
+      amount,
+      balanceBefore: previousBalance,
+      balanceAfter: newBalance,
+      source: journal.source ?? "operation_commit",
+      referenceId: journal.referenceId,
+      referenceType: journal.referenceType ?? "adjustment",
+      description: journal.description,
+      metadata: journal.metadata
+    });
+    return { previousBalance, newBalance, journalEntryId: entry.id };
   }
   // ==================== Transactions ====================
   async createTransaction(input) {
@@ -2244,6 +2395,11 @@ var InMemoryCreditRepository = class {
     assertRepresentableAmount(input.balanceAfter, "journal balanceAfter", {
       userId: input.userId
     });
+    if (input.balanceBefore !== void 0) {
+      assertRepresentableAmount(input.balanceBefore, "journal balanceBefore", {
+        userId: input.userId
+      });
+    }
     assertValidIdempotencyKey(input.idempotencyKey, { userId: input.userId });
     assertPublicJournalKey(input.idempotencyKey, input.userId);
     const key = input.idempotencyKey !== void 0 ? scopedKey(input.userId, input.idempotencyKey) : void 0;
@@ -2259,6 +2415,7 @@ var InMemoryCreditRepository = class {
       userId: input.userId,
       entryType: input.entryType,
       amount: input.amount,
+      ...input.balanceBefore !== void 0 ? { balanceBefore: input.balanceBefore } : {},
       balanceAfter: input.balanceAfter,
       source: input.source,
       referenceId: input.referenceId,
@@ -2411,6 +2568,7 @@ var InMemoryCreditRepository = class {
         userId,
         entryType: change > 0 ? "credit" : "debit",
         amount: Math.abs(change),
+        balanceBefore: sumAmounts(previousBalance, credits.bonusCredits),
         balanceAfter,
         source: "monthly_reset",
         referenceId: `reset-${Date.now()}`,
@@ -2491,6 +2649,7 @@ var InMemoryCreditRepository = class {
       entryType: "debit",
       amount: 0,
       // No credits deducted, just tier change
+      balanceBefore: sumAmounts(previousBalance, credits.bonusCredits),
       balanceAfter,
       source: "subscription_downgrade",
       referenceId: `downgrade-${Date.now()}`,
@@ -2654,6 +2813,7 @@ var CreditsService = class {
           entryType: "debit",
           amount: 0,
           // No credits deducted, just tier change
+          balanceBefore: sumAmounts(data.balance, data.bonusCredits),
           // The ledger balance, matching every other journal writer: the V2
           // transitions and add/deduct all record `balance + bonusCredits`, so
           // recording `balance` alone made the audit trail disagree with itself
@@ -2697,6 +2857,7 @@ var CreditsService = class {
             userId,
             entryType: balanceChange > 0 ? "credit" : "debit",
             amount: Math.abs(balanceChange),
+            balanceBefore: sumAmounts(data.balance, data.bonusCredits),
             balanceAfter: sumAmounts(
               resetResult.credits.balance,
               resetResult.credits.bonusCredits
@@ -2931,9 +3092,18 @@ var CreditsService = class {
    */
   async deductCredits(userId, amount, options) {
     assertValidCreditAmount(amount, { userId, operation: "deductCredits" });
+    const operationType = options?.operationType;
+    const journal = {
+      referenceId: options?.requestId ?? `deduct-${Date.now()}`,
+      description: operationType ? `Deducted ${amount} credits for ${getOperationLabel(operationType)}` : `Deducted ${amount} credits`,
+      metadata: {
+        ...options?.metadata,
+        ...operationType && { operationType }
+      }
+    };
     let deduction;
     try {
-      deduction = await this.repository.deductCreditsAtomic(userId, amount);
+      deduction = await this.repository.deductCreditsAtomic(userId, amount, journal);
     } catch (error) {
       if (isCreditError(error) && error.code === CreditErrorCode.INVALID_AMOUNT) throw error;
       const credits = await this.repository.getUserCredits(userId);
@@ -2949,21 +3119,18 @@ var CreditsService = class {
         shortfall: sumAmounts(amount, -available)
       };
     }
-    const operationType = options?.operationType;
-    await this.repository.createJournalEntry({
-      userId,
-      entryType: "debit",
-      amount,
-      balanceAfter: deduction.newBalance,
-      source: "operation_commit",
-      referenceId: options?.requestId ?? `deduct-${Date.now()}`,
-      referenceType: "adjustment",
-      description: operationType ? `Deducted ${amount} credits for ${getOperationLabel(operationType)}` : `Deducted ${amount} credits`,
-      metadata: {
-        ...options?.metadata,
-        ...operationType && { operationType }
-      }
-    });
+    if (deduction.journalEntryId === void 0) {
+      await this.repository.createJournalEntry({
+        userId,
+        entryType: "debit",
+        amount,
+        balanceBefore: deduction.previousBalance,
+        balanceAfter: deduction.newBalance,
+        source: "operation_commit",
+        referenceType: "adjustment",
+        ...journal
+      });
+    }
     if (operationType) {
       await this.logUsage({
         userId,
@@ -3973,6 +4140,7 @@ export {
   CreditsSDKError,
   CreditsService,
   InMemoryCreditRepository,
+  NO_EXPIRED_BACKING_PREFIX,
   NetworkError,
   RESERVATION_STATUSES,
   RESERVED_JOURNAL_KEY_PREFIX,
@@ -3985,6 +4153,7 @@ export {
   UNLIMITED_BALANCE_SENTINEL,
   ValidationError,
   addCreditsThroughRepository,
+  allocateExpiredBacking,
   assertDirectStatusWriteAllowed,
   assertHoldPlaced,
   assertKnownReservationStatus,
@@ -4001,9 +4170,9 @@ export {
   assertValidStoredAmount,
   assertValidStoredAmountRaw,
   assertValidTierBalanceInput,
-  attributeExpiredBacking,
   backedBalanceFloor,
   calculateAvailableCredits,
+  canonicalAmount,
   cappedBalance,
   checkAndNotifyLowBalance,
   classifyDatabaseError,
@@ -4030,7 +4199,7 @@ export {
   createUnsupportedOperationError,
   createUserNotFoundError,
   describePaymentMismatch,
-  expiredHoldBackingPatch,
+  expiredBackingPatch,
   generateId,
   generateRequestId2 as generateRequestId,
   genericDeferred,
@@ -4056,6 +4225,9 @@ export {
   getValidOperationTypes,
   getValidTiers,
   hasPlacedHold,
+  heldExpiredBacking,
+  holdExpiredBacking,
+  holdPlacedAtAfter,
   initializeConfig,
   isCreditError,
   isCreditErrorMessage,
@@ -4081,6 +4253,7 @@ export {
   isWinningOutcome,
   loadConfigFromEnv,
   monthlyResetBalance,
+  multiplyAmount,
   noopDeferred,
   normalizePaymentRef,
   notifySubscriptionExpired,
@@ -4092,6 +4265,7 @@ export {
   planBalanceCap,
   planBalanceTarget,
   planHoldCommit,
+  recordedExpiredBacking,
   registerConfigProvider,
   registerNotificationHandler,
   releaseReservationWithJournal,
@@ -4103,6 +4277,8 @@ export {
   sameAmount,
   settleExpiredHoldBacking,
   spendableBalance,
+  storedAmountCeil,
+  storedAmountFloor,
   storedMonthlyLimit,
   sumAmounts,
   supportsCreditsV2,