@nehorai/credits 2.2.0 → 3.1.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-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';
+import { R as ReservationStatus, a as PortableReservation, P as PortableTransaction, b as CreditSource, J as JournalReferenceType, E as ExpiredBackingFrontier } from '../types-C3sxDvNb.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-C3sxDvNb.cjs';
+import { T as TerminalReservationStatus, I as ICreditRepository } from '../types-YLAB8bFk.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-YLAB8bFk.cjs';
 export { D as DeferredExecutor, c as createDeferredExecutor, g as genericDeferred, n as noopDeferred, s as synchronousDeferred } from '../deferred-C7rrRfkm.cjs';
 
 /**
@@ -432,6 +432,40 @@ declare function toCents(value: number): number | null;
  * derived result is not enough and never was.
  */
 declare function sumAmounts(...values: number[]): number;
+/**
+ * Multiply a price by a whole quantity, in cents.
+ *
+ * `1.1 * 3` is `3.3000000000000003`, which the amount validators refuse: the price
+ * was legal, and the float product blames the caller for a rounding artefact. A
+ * fractional quantity has no exact result on the grid and is refused rather than
+ * rounded, so the rounding policy stays with whoever prices fractions.
+ */
+declare function multiplyAmount(unit: number, quantity: number): number;
+/**
+ * The cent-grid value a float landed next to, or the value unchanged.
+ *
+ * Documents written by older versions can hold the result of IEEE 754 additions
+ * (`FieldValue.increment` stored `0.30000000000000004`), and an application can pass
+ * a raw float difference to a ledger record. That is noise, not an amount. A value
+ * genuinely off the grid, such as `0.005`, is not noise and comes back as it went in.
+ */
+declare function canonicalAmount(value: number): number;
+/**
+ * Read a stored amount the account owns as a cent-grid value, rounding down.
+ *
+ * A stored `24.999` makes every later sum off-grid, the validators then refuse the
+ * commit or release that needs it, and the holds on that account lock. Rounding down
+ * unlocks them. A value within {@link canonicalAmount}'s noise of the next cent reads as
+ * that cent, because a float cannot tell the two apart, so this can add at most that noise:
+ * 1e-6 up to 7e7, and about 1.4e-4 at the maximum. A non-finite value is left for the
+ * validators to refuse.
+ */
+declare function storedAmountFloor(value: number): number;
+/**
+ * Read a stored amount the account owes as a cent-grid value, rounding up, so what
+ * stands against the balance is never understated. See {@link storedAmountFloor}.
+ */
+declare function storedAmountCeil(value: number): number;
 /** Amounts that may be *moved*: strictly positive and on the cent grid. */
 declare function isValidCreditAmount(value: unknown): value is number;
 /**
@@ -493,6 +527,13 @@ interface PlannedBalance {
     balance: number;
     expiredHoldBacking: number;
 }
+/**
+ * The expired credits actually held in a balance: `0 <= held <= balance`, whatever
+ * is stored. Every read of `expiredHoldBacking` goes through this. Trusting the stored
+ * value made a negative one mint credits: `balance - (-10)` read as spendable, and a
+ * close that "used" -10 of backing added 10 to the balance.
+ */
+declare function heldExpiredBacking(balance: number, stored?: number): 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;
 /**
@@ -509,8 +550,7 @@ declare function planBalanceTarget(target: number, reserved: number, bonusCredit
 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}.
+ * and nothing of another hold's. `holdBacking` comes from {@link holdExpiredBacking}.
  */
 declare function settleExpiredHoldBacking(balance: number, expiredHoldBacking: number, holdBacking: number): {
     used: number;
@@ -530,28 +570,79 @@ interface PlannedHoldCommit {
  */
 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">;
+type ExpiredBackingHold = Pick<PortableReservation, "id" | "amount" | "holdPlacedAt" | "expiredBacking">;
+/** A hold whose stored share has to change for a new total. */
+interface ExpiredBackingRewrite {
+    id: string;
+    expiredBacking: number;
+}
+/** The marked credits on an account and where they end among its open holds. */
+interface ExpiredBackingAllocation {
+    total: number;
+    frontier: ExpiredBackingFrontier | null;
+    /** Stored shares to write with this total. Absent when none changes. */
+    rewrites?: ExpiredBackingRewrite[];
+}
+/**
+ * A frontier before every hold: no hold shares through it. It records that the account's
+ * marks are placed, so the next close does not walk the holds again.
+ */
+declare const NO_EXPIRED_BACKING_PREFIX: ExpiredBackingFrontier;
 /**
- * Split `total` marked credits across open holds, returning each hold's share.
+ * The share a 2.2.0 hold document recorded for itself: the order of record for that hold.
+ * Clocks are not, since the server that placed a hold may lag the one before it. Rounded
+ * up, like every amount that stands against the balance, and never above the hold. Zero
+ * means no record, which leaves the hold to the frontier.
+ */
+declare function recordedExpiredBacking(hold: ExpiredBackingHold): number;
+/**
+ * Place `total` marked credits on the open holds, so that what each hold takes does not
+ * depend on the order they close in.
+ *
+ * Shares a 2.2.0 hold document stored stand as recorded: they need not be a prefix of
+ * anything, and they sit on documents that already exist. The rest goes to the other
+ * holds oldest first, each up to its amount. That part is a prefix, so one
+ * {@link ExpiredBackingFrontier} on the account describes it and no hold document changes
+ * however many there are. A new hold carries no share, so no record is ever added.
  *
- * 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.
+ * A total below the records trims them newest first, and only when every other hold has
+ * nothing, and a total the other holds cannot take fills what the records left free. Those
+ * are the only hold writes: `rewrites`, at most one per record, each record being an open
+ * hold from before the upgrade.
  *
- * 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.
+ * Marks no hold can carry stay marked. They were out of reach before this ran, and
+ * dropping them would make them spendable; the next absolute balance write replaces
+ * them. A row without `holdPlacedAt` is a record, not a hold, and a row with an unusable
+ * amount cannot close, so neither takes a share.
  */
-declare function attributeExpiredBacking(holds: readonly ExpiredBackingHold[], total: number): Map<string, number>;
+declare function allocateExpiredBacking(holds: readonly ExpiredBackingHold[], total: number): ExpiredBackingAllocation;
 /**
- * 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.
+ * This hold's share of the marked credits: its own record if it has one, otherwise where
+ * it falls against the account's frontier. Pass the `rewrites` of an allocation made in
+ * this same step, since the document does not hold them yet.
  */
-declare function expiredHoldBackingPatch(next: number, stored?: number): {
+declare function holdExpiredBacking(hold: ExpiredBackingHold, frontier?: ExpiredBackingFrontier | null, rewrites?: readonly ExpiredBackingRewrite[]): number;
+/**
+ * When a new hold counts as placed: `now`, or just after the frontier if this server's
+ * clock is behind the server that placed it. A hold that sorted before the frontier
+ * would read as fully marked, taking expired credits that belong to older holds.
+ */
+declare function holdPlacedAtAfter(now: string, frontier?: ExpiredBackingFrontier | null): string;
+/** The account fields that hold the marked credits. */
+interface ExpiredBackingFields {
     expiredHoldBacking?: number;
-};
+    expiredBackingFrontier?: ExpiredBackingFrontier | null;
+}
+/**
+ * The fields to write for a new marked total: nothing when it was and stays 0, so an
+ * account that never had any keeps a document without the fields. A stored value that
+ * is not the new one is overwritten, which is what repairs a bad one. A `frontier` left
+ * undefined keeps the stored one.
+ */
+declare function expiredBackingPatch(next: {
+    total: number;
+    frontier?: ExpiredBackingFrontier | null;
+}, stored: ExpiredBackingFields): ExpiredBackingFields;
 /**
  * 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.
@@ -781,4 +872,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, 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 };
+export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, type CreditErrorCodeType, CreditSource, type ExpiredBackingAllocation, type ExpiredBackingFields, ExpiredBackingFrontier, type ExpiredBackingHold, type ExpiredBackingRewrite, JournalReferenceType, NO_EXPIRED_BACKING_PREFIX, type PaymentEventPayload, PortableReservation, PortableTransaction, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, type ReservationIntegrityView, ReservationStatus, type StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, TerminalReservationStatus, 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 };

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-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';
+import { R as ReservationStatus, a as PortableReservation, P as PortableTransaction, b as CreditSource, J as JournalReferenceType, E as ExpiredBackingFrontier } from '../types-C3sxDvNb.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-C3sxDvNb.js';
+import { T as TerminalReservationStatus, I as ICreditRepository } from '../types-BL3YqxUD.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-BL3YqxUD.js';
 export { D as DeferredExecutor, c as createDeferredExecutor, g as genericDeferred, n as noopDeferred, s as synchronousDeferred } from '../deferred-C7rrRfkm.js';
 
 /**
@@ -432,6 +432,40 @@ declare function toCents(value: number): number | null;
  * derived result is not enough and never was.
  */
 declare function sumAmounts(...values: number[]): number;
+/**
+ * Multiply a price by a whole quantity, in cents.
+ *
+ * `1.1 * 3` is `3.3000000000000003`, which the amount validators refuse: the price
+ * was legal, and the float product blames the caller for a rounding artefact. A
+ * fractional quantity has no exact result on the grid and is refused rather than
+ * rounded, so the rounding policy stays with whoever prices fractions.
+ */
+declare function multiplyAmount(unit: number, quantity: number): number;
+/**
+ * The cent-grid value a float landed next to, or the value unchanged.
+ *
+ * Documents written by older versions can hold the result of IEEE 754 additions
+ * (`FieldValue.increment` stored `0.30000000000000004`), and an application can pass
+ * a raw float difference to a ledger record. That is noise, not an amount. A value
+ * genuinely off the grid, such as `0.005`, is not noise and comes back as it went in.
+ */
+declare function canonicalAmount(value: number): number;
+/**
+ * Read a stored amount the account owns as a cent-grid value, rounding down.
+ *
+ * A stored `24.999` makes every later sum off-grid, the validators then refuse the
+ * commit or release that needs it, and the holds on that account lock. Rounding down
+ * unlocks them. A value within {@link canonicalAmount}'s noise of the next cent reads as
+ * that cent, because a float cannot tell the two apart, so this can add at most that noise:
+ * 1e-6 up to 7e7, and about 1.4e-4 at the maximum. A non-finite value is left for the
+ * validators to refuse.
+ */
+declare function storedAmountFloor(value: number): number;
+/**
+ * Read a stored amount the account owes as a cent-grid value, rounding up, so what
+ * stands against the balance is never understated. See {@link storedAmountFloor}.
+ */
+declare function storedAmountCeil(value: number): number;
 /** Amounts that may be *moved*: strictly positive and on the cent grid. */
 declare function isValidCreditAmount(value: unknown): value is number;
 /**
@@ -493,6 +527,13 @@ interface PlannedBalance {
     balance: number;
     expiredHoldBacking: number;
 }
+/**
+ * The expired credits actually held in a balance: `0 <= held <= balance`, whatever
+ * is stored. Every read of `expiredHoldBacking` goes through this. Trusting the stored
+ * value made a negative one mint credits: `balance - (-10)` read as spendable, and a
+ * close that "used" -10 of backing added 10 to the balance.
+ */
+declare function heldExpiredBacking(balance: number, stored?: number): 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;
 /**
@@ -509,8 +550,7 @@ declare function planBalanceTarget(target: number, reserved: number, bonusCredit
 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}.
+ * and nothing of another hold's. `holdBacking` comes from {@link holdExpiredBacking}.
  */
 declare function settleExpiredHoldBacking(balance: number, expiredHoldBacking: number, holdBacking: number): {
     used: number;
@@ -530,28 +570,79 @@ interface PlannedHoldCommit {
  */
 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">;
+type ExpiredBackingHold = Pick<PortableReservation, "id" | "amount" | "holdPlacedAt" | "expiredBacking">;
+/** A hold whose stored share has to change for a new total. */
+interface ExpiredBackingRewrite {
+    id: string;
+    expiredBacking: number;
+}
+/** The marked credits on an account and where they end among its open holds. */
+interface ExpiredBackingAllocation {
+    total: number;
+    frontier: ExpiredBackingFrontier | null;
+    /** Stored shares to write with this total. Absent when none changes. */
+    rewrites?: ExpiredBackingRewrite[];
+}
+/**
+ * A frontier before every hold: no hold shares through it. It records that the account's
+ * marks are placed, so the next close does not walk the holds again.
+ */
+declare const NO_EXPIRED_BACKING_PREFIX: ExpiredBackingFrontier;
 /**
- * Split `total` marked credits across open holds, returning each hold's share.
+ * The share a 2.2.0 hold document recorded for itself: the order of record for that hold.
+ * Clocks are not, since the server that placed a hold may lag the one before it. Rounded
+ * up, like every amount that stands against the balance, and never above the hold. Zero
+ * means no record, which leaves the hold to the frontier.
+ */
+declare function recordedExpiredBacking(hold: ExpiredBackingHold): number;
+/**
+ * Place `total` marked credits on the open holds, so that what each hold takes does not
+ * depend on the order they close in.
+ *
+ * Shares a 2.2.0 hold document stored stand as recorded: they need not be a prefix of
+ * anything, and they sit on documents that already exist. The rest goes to the other
+ * holds oldest first, each up to its amount. That part is a prefix, so one
+ * {@link ExpiredBackingFrontier} on the account describes it and no hold document changes
+ * however many there are. A new hold carries no share, so no record is ever added.
  *
- * 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.
+ * A total below the records trims them newest first, and only when every other hold has
+ * nothing, and a total the other holds cannot take fills what the records left free. Those
+ * are the only hold writes: `rewrites`, at most one per record, each record being an open
+ * hold from before the upgrade.
  *
- * 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.
+ * Marks no hold can carry stay marked. They were out of reach before this ran, and
+ * dropping them would make them spendable; the next absolute balance write replaces
+ * them. A row without `holdPlacedAt` is a record, not a hold, and a row with an unusable
+ * amount cannot close, so neither takes a share.
  */
-declare function attributeExpiredBacking(holds: readonly ExpiredBackingHold[], total: number): Map<string, number>;
+declare function allocateExpiredBacking(holds: readonly ExpiredBackingHold[], total: number): ExpiredBackingAllocation;
 /**
- * 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.
+ * This hold's share of the marked credits: its own record if it has one, otherwise where
+ * it falls against the account's frontier. Pass the `rewrites` of an allocation made in
+ * this same step, since the document does not hold them yet.
  */
-declare function expiredHoldBackingPatch(next: number, stored?: number): {
+declare function holdExpiredBacking(hold: ExpiredBackingHold, frontier?: ExpiredBackingFrontier | null, rewrites?: readonly ExpiredBackingRewrite[]): number;
+/**
+ * When a new hold counts as placed: `now`, or just after the frontier if this server's
+ * clock is behind the server that placed it. A hold that sorted before the frontier
+ * would read as fully marked, taking expired credits that belong to older holds.
+ */
+declare function holdPlacedAtAfter(now: string, frontier?: ExpiredBackingFrontier | null): string;
+/** The account fields that hold the marked credits. */
+interface ExpiredBackingFields {
     expiredHoldBacking?: number;
-};
+    expiredBackingFrontier?: ExpiredBackingFrontier | null;
+}
+/**
+ * The fields to write for a new marked total: nothing when it was and stays 0, so an
+ * account that never had any keeps a document without the fields. A stored value that
+ * is not the new one is overwritten, which is what repairs a bad one. A `frontier` left
+ * undefined keeps the stored one.
+ */
+declare function expiredBackingPatch(next: {
+    total: number;
+    frontier?: ExpiredBackingFrontier | null;
+}, stored: ExpiredBackingFields): ExpiredBackingFields;
 /**
  * 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.
@@ -781,4 +872,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, 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 };
+export { CREDIT_AMOUNT_MAX, CREDIT_AMOUNT_SCALE, CreditError, CreditErrorCode, type CreditErrorCodeType, CreditSource, type ExpiredBackingAllocation, type ExpiredBackingFields, ExpiredBackingFrontier, type ExpiredBackingHold, type ExpiredBackingRewrite, JournalReferenceType, NO_EXPIRED_BACKING_PREFIX, type PaymentEventPayload, PortableReservation, PortableTransaction, RESERVATION_STATUSES, RESERVED_JOURNAL_KEY_PREFIX, type ReservationIntegrityView, ReservationStatus, type StoredPaymentEvent, TERMINAL_RESERVATION_STATUSES, TerminalReservationStatus, 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 };

package/dist/core/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",
@@ -809,17 +907,25 @@ var DEFAULT_CONFIG = {
   }
 };
 var currentConfig = DEFAULT_CONFIG;
+function isOperationCostMap(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every((cost) => isRepresentableAmount(cost) && cost >= 0);
+}
 function loadConfigFromEnv() {
   const envConfig = {};
   const operationCostsEnv = process.env.CREDITS_OPERATION_COSTS;
   if (operationCostsEnv) {
     try {
       const parsed = JSON.parse(operationCostsEnv);
-      if (typeof parsed === "object" && parsed !== null) {
+      if (isOperationCostMap(parsed)) {
         envConfig.operationCosts = {
           ...DEFAULT_CONFIG.operationCosts,
           ...parsed
         };
+      } else {
+        console.warn(
+          "[Credits Config] Ignoring CREDITS_OPERATION_COSTS: it must be a JSON object whose costs are numbers >= 0, exact to the cent"
+        );
       }
     } catch {
       console.warn("[Credits Config] Failed to parse CREDITS_OPERATION_COSTS env var as JSON");
@@ -1074,9 +1180,11 @@ export {
   CREDIT_AMOUNT_SCALE,
   CreditError,
   CreditErrorCode,
+  NO_EXPIRED_BACKING_PREFIX,
   RESERVATION_STATUSES,
   RESERVED_JOURNAL_KEY_PREFIX,
   TERMINAL_RESERVATION_STATUSES,
+  allocateExpiredBacking,
   assertDirectStatusWriteAllowed,
   assertHoldPlaced,
   assertKnownReservationStatus,
@@ -1092,9 +1200,9 @@ export {
   assertValidStoredAmount,
   assertValidStoredAmountRaw,
   assertValidTierBalanceInput,
-  attributeExpiredBacking,
   backedBalanceFloor,
   calculateAvailableCredits,
+  canonicalAmount,
   cappedBalance,
   classifyDatabaseError,
   commitReservationWithJournal,
@@ -1111,10 +1219,13 @@ export {
   createUnsupportedOperationError,
   createUserNotFoundError,
   describePaymentMismatch,
-  expiredHoldBackingPatch,
+  expiredBackingPatch,
   genericDeferred,
   getSqlState,
   hasPlacedHold,
+  heldExpiredBacking,
+  holdExpiredBacking,
+  holdPlacedAtAfter,
   isCreditError,
   isCreditedOutcome,
   isIdempotencyConflictError,
@@ -1130,17 +1241,21 @@ export {
   isValidCreditAmount,
   isValidIdempotencyKey,
   isWinningOutcome,
+  multiplyAmount,
   noopDeferred,
   normalizePaymentRef,
   numericToCents,
   planBalanceCap,
   planBalanceTarget,
   planHoldCommit,
+  recordedExpiredBacking,
   releaseReservationWithJournal,
   reserveCreditsForOperation,
   sameAmount,
   settleExpiredHoldBacking,
   spendableBalance,
+  storedAmountCeil,
+  storedAmountFloor,
   storedMonthlyLimit,
   sumAmounts,
   synchronousDeferred,