@nehorai/credits 2.1.0 → 3.0.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-Dzc443vy.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-Dzc443vy.cjs';
-import { T as TerminalReservationStatus, I as ICreditRepository } from '../types-wtksMa4n.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-wtksMa4n.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-DOjguhEX.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-DOjguhEX.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. */
@@ -431,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;
 /**
@@ -479,6 +514,149 @@ 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 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;
+/**
+ * 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 holdExpiredBacking}.
+ */
+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" | "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;
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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 allocateExpiredBacking(holds: readonly ExpiredBackingHold[], total: number): ExpiredBackingAllocation;
+/**
+ * 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 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.
+ */
+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 +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, 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, 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-Dzc443vy.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-Dzc443vy.js';
-import { T as TerminalReservationStatus, I as ICreditRepository } from '../types-BhCdep_t.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-BhCdep_t.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-CY-oHIMA.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-CY-oHIMA.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. */
@@ -431,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;
 /**
@@ -479,6 +514,149 @@ 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 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;
+/**
+ * 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 holdExpiredBacking}.
+ */
+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" | "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;
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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 allocateExpiredBacking(holds: readonly ExpiredBackingHold[], total: number): ExpiredBackingAllocation;
+/**
+ * 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 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.
+ */
+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 +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, 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, 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 };