@nehorai/credits 2.0.0 → 2.2.0

package/dist/core/index.d.cts

@@ -1,7 +1,7 @@
-import { R as ReservationStatus, a as PortableReservation, P as PortableTransaction, b as CreditSource, J as JournalReferenceType } from '../types-DJ8yqaVr.cjs';
-export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, C as CreditOperationType, D as DeductCreditsResult, M as MonthlyResetResult, f as PortableJournalEntry, d as PortableUsageLog, c as PortableUserCredits, h as ResourceType, e as SubscriptionExpiryResult, S as SubscriptionTier, T as TierConfig, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from '../types-DJ8yqaVr.cjs';
-import { T as TerminalReservationStatus, I as ICreditRepository } from '../types-C8hZMe8a.cjs';
-export { a as AddCreditsOutcome, C as CommitOutcome, E as ExpireOutcome, R as ReleaseOutcome, n as ReserveOutcome, p as isCreditedOutcome, q as isReservedOutcome, r as isWinningOutcome } from '../types-C8hZMe8a.cjs';
+import { R as ReservationStatus, a as PortableReservation, P as PortableTransaction, b as CreditSource, J as JournalReferenceType } from '../types-MaViK5tD.cjs';
+export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, C as CreditOperationType, D as DeductCreditsResult, M as MonthlyResetResult, f as PortableJournalEntry, d as PortableUsageLog, c as PortableUserCredits, h as ResourceType, e as SubscriptionExpiryResult, S as SubscriptionTier, T as TierConfig, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from '../types-MaViK5tD.cjs';
+import { T as TerminalReservationStatus, I as ICreditRepository } from '../types-XSjNXO5l.cjs';
+export { a as AddCreditsOutcome, C as CommitOutcome, E as ExpireOutcome, R as ReleaseOutcome, o as ReserveOutcome, q as isCreditedOutcome, r as isReservedOutcome, s as isWinningOutcome } from '../types-XSjNXO5l.cjs';
 export { D as DeferredExecutor, c as createDeferredExecutor, g as genericDeferred, n as noopDeferred, s as synchronousDeferred } from '../deferred-C7rrRfkm.cjs';
 
 /**
@@ -393,6 +393,7 @@ declare function createPaymentRefConflictError(paymentRef: string, details: {
  * These live in core rather than in an adapter so every repository — shipped
  * or third-party — validates identically.
  */
+
 /** `numeric(12, 2)`: 12 significant digits, 2 of them after the point. */
 declare const CREDIT_AMOUNT_SCALE = 2;
 /** Largest representable amount: ten integer digits plus two decimals. */
@@ -479,6 +480,92 @@ declare function assertRepresentableFields(fields: Record<string, unknown>, cont
  * fund commits, so they count toward the backing.
  */
 declare function backedBalanceFloor(reserved: number, bonusCredits: number): number;
+/**
+ * The balance left by a cap: lowered to `cap` at most, never raised, and never
+ * cut through the credits backing outstanding holds (see
+ * {@link backedBalanceFloor}). A balance already under `cap` is left alone,
+ * which is the point of computing this from the stored row inside a transaction
+ * rather than writing a value the caller read earlier.
+ */
+declare function cappedBalance(balance: number, cap: number, reserved: number, bonusCredits: number): number;
+/** A balance a lowering write lands on, and how much of it only backs holds. */
+interface PlannedBalance {
+    balance: number;
+    expiredHoldBacking: number;
+}
+/** The part of a balance not kept only for holds. A missing field reads as 0. */
+declare function spendableBalance(balance: number, expiredHoldBacking?: number): number;
+/**
+ * An absolute balance write: `target`, floored at what backs outstanding holds.
+ * Whatever the floor kept above `target` is not the account's to spend.
+ */
+declare function planBalanceTarget(target: number, reserved: number, bonusCredits: number): PlannedBalance;
+/**
+ * A cap on the spendable part of a balance. Like {@link cappedBalance} it never
+ * raises the balance and never cuts through what backs holds, and it records the
+ * part kept above the cap so a later release cannot hand it back. Credits already
+ * marked stay marked, so applying a cap twice changes nothing.
+ */
+declare function planBalanceCap(balance: number, cap: number, reserved: number, bonusCredits: number, expiredHoldBacking?: number): PlannedBalance;
+/**
+ * What a closing hold takes out of the credits kept only for holds: its own share
+ * and nothing of another hold's. `holdBacking` comes from
+ * {@link attributeExpiredBacking}.
+ */
+declare function settleExpiredHoldBacking(balance: number, expiredHoldBacking: number, holdBacking: number): {
+    used: number;
+    remaining: number;
+};
+/** The balances a commit lands on, and whether the account could pay it. */
+interface PlannedHoldCommit {
+    covered: boolean;
+    balance: number;
+    bonusCredits: number;
+    expiredHoldBacking: number;
+}
+/**
+ * Pay a hold: first its own share of the marked credits, then spendable balance,
+ * then bonus. Marked credits backing other holds are never touched, so what this
+ * commit costs does not depend on which holds closed before it.
+ */
+declare function planHoldCommit(balance: number, bonusCredits: number, expiredHoldBacking: number, holdBacking: number, amount: number): PlannedHoldCommit;
+/** The fields of an open hold that decide its share of the marked credits. */
+type ExpiredBackingHold = Pick<PortableReservation, "id" | "amount" | "expiredBacking" | "holdPlacedAt">;
+/**
+ * Split `total` marked credits across open holds, returning each hold's share.
+ *
+ * Shares a hold already has are kept first, oldest hold first, so lowering `total`
+ * trims the newest and raising it never moves credits off a hold. Only what is left
+ * goes to holds with room, again oldest first, which makes the split a function of
+ * the holds and not of the order they later close in. A hold never carries more than
+ * its amount. A row without `holdPlacedAt` is a record, not a hold, and gets nothing.
+ *
+ * The account's `expiredHoldBacking` is written as the sum of these shares, in the
+ * same write, so what `total` could not attribute is not marked. Such credits stay out
+ * of reach anyway, because the `reserved` that kept them still counts against them.
+ */
+declare function attributeExpiredBacking(holds: readonly ExpiredBackingHold[], total: number): Map<string, number>;
+/**
+ * The field to write for a new backing value: nothing when it was and stays 0, so
+ * an account that never had any keeps a document without the field.
+ */
+declare function expiredHoldBackingPatch(next: number, stored?: number): {
+    expiredHoldBacking?: number;
+};
+/**
+ * Validate a balance target supplied by the application: a cap or the result of
+ * a monthly-reset decision. It must be storable and cannot be negative.
+ */
+declare function assertValidBalanceTarget(value: unknown, field: string, context?: Record<string, unknown>): asserts value is number;
+/**
+ * Validate how a tier write changes the balance. `balance` sets a value the
+ * caller computed and `balanceCap` lowers the stored value, so naming both has
+ * no single meaning and is refused.
+ */
+declare function assertValidTierBalanceInput(input: {
+    balance?: number;
+    balanceCap?: number;
+}, context?: Record<string, unknown>): void;
 /**
  * Validate a limit derived from tier configuration.
  *
@@ -694,4 +781,4 @@ declare function releaseReservationWithJournal(repository: ICreditRepository, us
  */
 declare function reserveCreditsForOperation(repository: ICreditRepository, userId: string, amount: number, operationType: string, expiryMs?: number, idempotencyKey?: string): Promise<PortableReservation>;
 
-export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, type CreditErrorCodeType, CreditSource, JournalReferenceType, type PaymentEventPayload, PortableReservation, PortableTransaction, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, type ReservationIntegrityView, ReservationStatus, type StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, TerminalReservationStatus, 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 };
+export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, type CreditErrorCodeType, CreditSource, JournalReferenceType, type PaymentEventPayload, PortableReservation, PortableTransaction, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, type ReservationIntegrityView, ReservationStatus, type StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, TerminalReservationStatus, 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 };

package/dist/core/index.d.ts

@@ -1,7 +1,7 @@
-import { R as ReservationStatus, a as PortableReservation, P as PortableTransaction, b as CreditSource, J as JournalReferenceType } from '../types-DJ8yqaVr.js';
-export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, C as CreditOperationType, D as DeductCreditsResult, M as MonthlyResetResult, f as PortableJournalEntry, d as PortableUsageLog, c as PortableUserCredits, h as ResourceType, e as SubscriptionExpiryResult, S as SubscriptionTier, T as TierConfig, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from '../types-DJ8yqaVr.js';
-import { T as TerminalReservationStatus, I as ICreditRepository } from '../types-BmG5Omzj.js';
-export { a as AddCreditsOutcome, C as CommitOutcome, E as ExpireOutcome, R as ReleaseOutcome, n as ReserveOutcome, p as isCreditedOutcome, q as isReservedOutcome, r as isWinningOutcome } from '../types-BmG5Omzj.js';
+import { R as ReservationStatus, a as PortableReservation, P as PortableTransaction, b as CreditSource, J as JournalReferenceType } from '../types-MaViK5tD.js';
+export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, C as CreditOperationType, D as DeductCreditsResult, M as MonthlyResetResult, f as PortableJournalEntry, d as PortableUsageLog, c as PortableUserCredits, h as ResourceType, e as SubscriptionExpiryResult, S as SubscriptionTier, T as TierConfig, i as TransactionType, U as UsageHistoryEntry, j as UsageHistoryResponse, W as WithCreditsOptions, k as calculateAvailableCredits, t as toDate, l as toPortableTimestamp } from '../types-MaViK5tD.js';
+import { T as TerminalReservationStatus, I as ICreditRepository } from '../types-3c-IAwZI.js';
+export { a as AddCreditsOutcome, C as CommitOutcome, E as ExpireOutcome, R as ReleaseOutcome, o as ReserveOutcome, q as isCreditedOutcome, r as isReservedOutcome, s as isWinningOutcome } from '../types-3c-IAwZI.js';
 export { D as DeferredExecutor, c as createDeferredExecutor, g as genericDeferred, n as noopDeferred, s as synchronousDeferred } from '../deferred-C7rrRfkm.js';
 
 /**
@@ -393,6 +393,7 @@ declare function createPaymentRefConflictError(paymentRef: string, details: {
  * These live in core rather than in an adapter so every repository — shipped
  * or third-party — validates identically.
  */
+
 /** `numeric(12, 2)`: 12 significant digits, 2 of them after the point. */
 declare const CREDIT_AMOUNT_SCALE = 2;
 /** Largest representable amount: ten integer digits plus two decimals. */
@@ -479,6 +480,92 @@ declare function assertRepresentableFields(fields: Record<string, unknown>, cont
  * fund commits, so they count toward the backing.
  */
 declare function backedBalanceFloor(reserved: number, bonusCredits: number): number;
+/**
+ * The balance left by a cap: lowered to `cap` at most, never raised, and never
+ * cut through the credits backing outstanding holds (see
+ * {@link backedBalanceFloor}). A balance already under `cap` is left alone,
+ * which is the point of computing this from the stored row inside a transaction
+ * rather than writing a value the caller read earlier.
+ */
+declare function cappedBalance(balance: number, cap: number, reserved: number, bonusCredits: number): number;
+/** A balance a lowering write lands on, and how much of it only backs holds. */
+interface PlannedBalance {
+    balance: number;
+    expiredHoldBacking: number;
+}
+/** The part of a balance not kept only for holds. A missing field reads as 0. */
+declare function spendableBalance(balance: number, expiredHoldBacking?: number): number;
+/**
+ * An absolute balance write: `target`, floored at what backs outstanding holds.
+ * Whatever the floor kept above `target` is not the account's to spend.
+ */
+declare function planBalanceTarget(target: number, reserved: number, bonusCredits: number): PlannedBalance;
+/**
+ * A cap on the spendable part of a balance. Like {@link cappedBalance} it never
+ * raises the balance and never cuts through what backs holds, and it records the
+ * part kept above the cap so a later release cannot hand it back. Credits already
+ * marked stay marked, so applying a cap twice changes nothing.
+ */
+declare function planBalanceCap(balance: number, cap: number, reserved: number, bonusCredits: number, expiredHoldBacking?: number): PlannedBalance;
+/**
+ * What a closing hold takes out of the credits kept only for holds: its own share
+ * and nothing of another hold's. `holdBacking` comes from
+ * {@link attributeExpiredBacking}.
+ */
+declare function settleExpiredHoldBacking(balance: number, expiredHoldBacking: number, holdBacking: number): {
+    used: number;
+    remaining: number;
+};
+/** The balances a commit lands on, and whether the account could pay it. */
+interface PlannedHoldCommit {
+    covered: boolean;
+    balance: number;
+    bonusCredits: number;
+    expiredHoldBacking: number;
+}
+/**
+ * Pay a hold: first its own share of the marked credits, then spendable balance,
+ * then bonus. Marked credits backing other holds are never touched, so what this
+ * commit costs does not depend on which holds closed before it.
+ */
+declare function planHoldCommit(balance: number, bonusCredits: number, expiredHoldBacking: number, holdBacking: number, amount: number): PlannedHoldCommit;
+/** The fields of an open hold that decide its share of the marked credits. */
+type ExpiredBackingHold = Pick<PortableReservation, "id" | "amount" | "expiredBacking" | "holdPlacedAt">;
+/**
+ * Split `total` marked credits across open holds, returning each hold's share.
+ *
+ * Shares a hold already has are kept first, oldest hold first, so lowering `total`
+ * trims the newest and raising it never moves credits off a hold. Only what is left
+ * goes to holds with room, again oldest first, which makes the split a function of
+ * the holds and not of the order they later close in. A hold never carries more than
+ * its amount. A row without `holdPlacedAt` is a record, not a hold, and gets nothing.
+ *
+ * The account's `expiredHoldBacking` is written as the sum of these shares, in the
+ * same write, so what `total` could not attribute is not marked. Such credits stay out
+ * of reach anyway, because the `reserved` that kept them still counts against them.
+ */
+declare function attributeExpiredBacking(holds: readonly ExpiredBackingHold[], total: number): Map<string, number>;
+/**
+ * The field to write for a new backing value: nothing when it was and stays 0, so
+ * an account that never had any keeps a document without the field.
+ */
+declare function expiredHoldBackingPatch(next: number, stored?: number): {
+    expiredHoldBacking?: number;
+};
+/**
+ * Validate a balance target supplied by the application: a cap or the result of
+ * a monthly-reset decision. It must be storable and cannot be negative.
+ */
+declare function assertValidBalanceTarget(value: unknown, field: string, context?: Record<string, unknown>): asserts value is number;
+/**
+ * Validate how a tier write changes the balance. `balance` sets a value the
+ * caller computed and `balanceCap` lowers the stored value, so naming both has
+ * no single meaning and is refused.
+ */
+declare function assertValidTierBalanceInput(input: {
+    balance?: number;
+    balanceCap?: number;
+}, context?: Record<string, unknown>): void;
 /**
  * Validate a limit derived from tier configuration.
  *
@@ -694,4 +781,4 @@ declare function releaseReservationWithJournal(repository: ICreditRepository, us
  */
 declare function reserveCreditsForOperation(repository: ICreditRepository, userId: string, amount: number, operationType: string, expiryMs?: number, idempotencyKey?: string): Promise<PortableReservation>;
 
-export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, type CreditErrorCodeType, CreditSource, JournalReferenceType, type PaymentEventPayload, PortableReservation, PortableTransaction, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, type ReservationIntegrityView, ReservationStatus, type StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, TerminalReservationStatus, 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 };
+export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, type CreditErrorCodeType, CreditSource, JournalReferenceType, type PaymentEventPayload, PortableReservation, PortableTransaction, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, type ReservationIntegrityView, ReservationStatus, type StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, TerminalReservationStatus, 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 };

package/dist/core/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);
@@ -593,11 +673,13 @@ var creditSystemConfigSchema = z.object({
   /**
    * Operation costs in credits
    * Keys are operation type names (any non-empty string)
-   * Values are positive numbers representing credit cost
+   * Values are non-negative numbers representing credit cost. 0 marks a free
+   * operation: `withCredits` runs it without touching the ledger. Amounts that
+   * move credits stay strictly positive, so `reserveCredits` refuses a 0.
    */
   operationCosts: z.record(
     z.string().min(1),
-    z.number().positive()
+    z.number().nonnegative()
   ),
   /**
    * Display labels for operation types (English canonical labels).
@@ -619,9 +701,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
    */
@@ -1004,12 +1086,16 @@ export {
   assertRepresentableTierAmount,
   assertUnkeyedDirectReservation,
   assertUnreferencedDirectTransaction,
+  assertValidBalanceTarget,
   assertValidCreditAmount,
   assertValidIdempotencyKey,
   assertValidStoredAmount,
   assertValidStoredAmountRaw,
+  assertValidTierBalanceInput,
+  attributeExpiredBacking,
   backedBalanceFloor,
   calculateAvailableCredits,
+  cappedBalance,
   classifyDatabaseError,
   commitReservationWithJournal,
   createDeferredExecutor,
@@ -1025,6 +1111,7 @@ export {
   createUnsupportedOperationError,
   createUserNotFoundError,
   describePaymentMismatch,
+  expiredHoldBackingPatch,
   genericDeferred,
   getSqlState,
   hasPlacedHold,
@@ -1046,9 +1133,14 @@ export {
   noopDeferred,
   normalizePaymentRef,
   numericToCents,
+  planBalanceCap,
+  planBalanceTarget,
+  planHoldCommit,
   releaseReservationWithJournal,
   reserveCreditsForOperation,
   sameAmount,
+  settleExpiredHoldBacking,
+  spendableBalance,
   storedMonthlyLimit,
   sumAmounts,
   synchronousDeferred,