@nehorai/credits 1.7.0 → 2.1.0

package/dist/core/index.d.cts

@@ -1,7 +1,127 @@
-import { c as PortableReservation } from '../types-CjLj3GW5.cjs';
-export { A as AIProviderType, B as BuiltinTier, g as CreditCheckResult, a as CreditOperationType, C as CreditSource, D as DeductCreditsResult, J as JournalReferenceType, M as MonthlyResetResult, f as PortableJournalEntry, P as PortableTransaction, d as PortableUsageLog, b as PortableUserCredits, R as ReservationStatus, 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-CjLj3GW5.cjs';
+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';
 export { D as DeferredExecutor, c as createDeferredExecutor, g as genericDeferred, n as noopDeferred, s as synchronousDeferred } from '../deferred-C7rrRfkm.cjs';
-import { I as ICreditRepository } from '../types-DFe5BoJY.cjs';
+
+/**
+ * Trust checks for a *persisted* reservation row.
+ *
+ * A reservation is written once and read back on every transition, and nothing
+ * between those two moments belongs to this library: a direct `UPDATE`, a
+ * half-finished migration, a legacy adapter or a future version can all leave a
+ * row this code never wrote. Two of the fields it reads back are load-bearing.
+ *
+ * **`status`** decides whether a transition runs at all. It used to be cast —
+ * `reservation.status as TerminalReservationStatus` — so a row holding
+ * `'gremlin'` was reported as `already_terminal` with `terminalStatus:
+ * 'gremlin'`: a *success* outcome, telling the caller the reservation had been
+ * resolved, over a row nothing in this library can resolve. The cast is a lie
+ * the type system cannot catch, so the value is checked against the closed set
+ * instead and anything outside it quarantines the row.
+ *
+ * **`holdPlacedAt`** decides whether the hold behind the row exists. See
+ * {@link assertHoldPlaced}.
+ *
+ * Both refusals happen before any state changes, and neither one repairs
+ * anything: a corrupt row stops moving and waits for an operator. Silently
+ * reconciling it would need an audit trail and a recovery procedure, and
+ * guessing is how a bad row becomes a wrong balance.
+ */
+
+/** Every status this library knows how to reason about. */
+declare const RESERVATION_STATUSES: readonly ReservationStatus[];
+/** The statuses a reservation can no longer transition out of. */
+declare const TERMINAL_RESERVATION_STATUSES: readonly TerminalReservationStatus[];
+declare function isReservationStatus(value: unknown): value is ReservationStatus;
+declare function isTerminalReservationStatus(value: unknown): value is TerminalReservationStatus;
+/** The subset of a reservation these checks read, so callers can pass a row. */
+interface ReservationIntegrityView {
+    id: string;
+    userId: string;
+    status: unknown;
+    /** Set by the atomic reserve, in the same transaction as the hold. */
+    holdPlacedAt?: string | null;
+    idempotencyKey?: string | null;
+}
+/**
+ * Refuse a transition over a status this library does not define.
+ *
+ * Runs ahead of every early exit, including the `already_terminal` one, for the
+ * reason in the module header: `already_terminal` is a success outcome, and a
+ * success outcome over an unknown status is the failure mode being prevented.
+ */
+declare function assertKnownReservationStatus(reservation: ReservationIntegrityView, transition: string): asserts reservation is ReservationIntegrityView & {
+    status: ReservationStatus;
+};
+/**
+ * Narrow a non-`reserved` status for the `already_terminal` outcomes.
+ *
+ * Validates rather than casts. `assertKnownReservationStatus` has usually run
+ * already; this repeats the check because the cast it replaces was the defect,
+ * and a second closed-set test costs nothing next to a database round trip.
+ */
+declare function terminalStatusOf(reservation: ReservationIntegrityView, transition: string): TerminalReservationStatus;
+/**
+ * Refuse a transition over a hold that was never atomically placed.
+ *
+ * `holdPlacedAt` is the single invariant behind the V2 boundary: **a row is
+ * only a reservation if the same atomic operation that wrote it also increased
+ * `reserved` by its amount.** The atomic reserve sets the field inside that one
+ * transaction, so the fact and the hold commit together or not at all.
+ *
+ * Without it, `createReservation` — a plain row writer that does not touch
+ * `reserved` — could mint a keyed row, and a later `reserveCreditsV2` with that
+ * key would adopt it as a `replayed` hold that no credits back. The caller then
+ * commits it, and the commit passes its `reserved >= amount` guard by consuming
+ * coverage that belongs to a *different*, real hold: two holds, one payment.
+ *
+ * So this is checked before adopting a replay and before every transition, and
+ * `createReservation` refuses a key outright — the two halves of the same rule.
+ */
+declare function assertHoldPlaced(reservation: ReservationIntegrityView, transition: string): void;
+/**
+ * Refuse an idempotency key on the direct, non-atomic reservation writer.
+ *
+ * The other half of {@link assertHoldPlaced}. `createReservation` inserts a row
+ * and does not touch `reserved`, so a key registered here would name a hold
+ * that does not exist. Rejecting the key at the boundary means the unbacked
+ * keyed row cannot be created in the first place, rather than only being
+ * refused later by every transition that tries to move it.
+ *
+ * The amount check that runs alongside this is about a value the ledger cannot
+ * honour; this is about a *claim* the writer cannot honour.
+ */
+declare function assertUnkeyedDirectReservation(input: {
+    userId: string;
+    idempotencyKey?: string;
+}): void;
+/** True when the row records an atomically placed hold. */
+declare function hasPlacedHold(reservation: Pick<PortableReservation, "holdPlacedAt">): boolean;
+/**
+ * Refuse a direct status write that would bypass the V2 state machine.
+ *
+ * `updateReservationStatus` assigns a status and nothing else: it does not
+ * check the current status, move the balance, adjust `reserved`, or journal.
+ * On a row whose hold was atomically placed, that is not an update — it is a
+ * bypass. Writing `committed` onto a live hold strands `reserved` forever (the
+ * real commit then reports `already_terminal` and never debits), and writing
+ * `reserved` onto a terminal row re-arms a settled reservation so it can be
+ * settled again.
+ *
+ * Two refusals, mirroring the createReservation/reserveCredits split:
+ *
+ * - A row bearing `holdPlacedAt` belongs to the V2 transitions. Every status it
+ *   will ever hold is assigned by commit/release/expire, atomically with the
+ *   ledger movement that status implies.
+ * - No row, V2 or legacy, may be *reopened* — status can never be assigned back
+ *   to `reserved`, because nothing here re-places the hold that status claims.
+ *
+ * Rows written by `createReservation` (no hold, no key) remain freely
+ * annotatable with terminal statuses: their statuses never carried ledger
+ * meaning, and the V2 transitions refuse them anyway.
+ */
+declare function assertDirectStatusWriteAllowed(reservation: ReservationIntegrityView, status: ReservationStatus): void;
 
 /**
  * Credit system error classes - framework agnostic
@@ -21,6 +141,31 @@ declare const CreditErrorCode: {
     readonly INVALID_OPERATION_TYPE: "INVALID_OPERATION_TYPE";
     readonly CONFIGURATION_ERROR: "CONFIGURATION_ERROR";
     readonly DATABASE_ERROR: "DATABASE_ERROR";
+    /** Caller reused an idempotency key with a different immutable payload. */
+    readonly IDEMPOTENCY_CONFLICT: "IDEMPOTENCY_CONFLICT";
+    /**
+     * Retryable infrastructure failure — serialization/deadlock, lock timeout,
+     * connection loss, pool exhaustion. Distinct from `DATABASE_ERROR`, which is
+     * a deterministic failure that will fail again identically on retry.
+     */
+    readonly TRANSIENT_ERROR: "TRANSIENT_ERROR";
+    /** The configured repository adapter does not implement the requested V2 method. */
+    readonly UNSUPPORTED_OPERATION: "UNSUPPORTED_OPERATION";
+    /** Amount was not a finite positive number. */
+    readonly INVALID_AMOUNT: "INVALID_AMOUNT";
+    /** Idempotency key was supplied but empty or whitespace-only. */
+    readonly INVALID_IDEMPOTENCY_KEY: "INVALID_IDEMPOTENCY_KEY";
+    /**
+     * A persisted reservation holds a status this library does not define, so no
+     * transition can reason about it. Quarantined rather than cast; nothing moved.
+     */
+    readonly CORRUPT_RESERVATION_STATUS: "CORRUPT_RESERVATION_STATUS";
+    /**
+     * A persisted reservation does not record that its hold was placed
+     * atomically, so the credits it claims are not known to be reserved. Moving
+     * it would spend another hold's coverage; nothing moved.
+     */
+    readonly UNBACKED_RESERVATION: "UNBACKED_RESERVATION";
 };
 type CreditErrorCodeType = (typeof CreditErrorCode)[keyof typeof CreditErrorCode];
 /**
@@ -80,6 +225,432 @@ declare function createUserNotFoundError(userId: string): CreditError;
  * Create an invalid operation type error
  */
 declare function createInvalidOperationTypeError(operationType: string, validTypes: string[]): CreditError;
+/**
+ * Create an idempotency conflict error
+ *
+ * Raised when a caller reuses an idempotency key with a different immutable
+ * payload (different amount or operation type). This is a caller bug, never a
+ * retryable condition — the details carry both payloads so it can be diffed.
+ */
+declare function createIdempotencyConflictError(idempotencyKey: string, details?: Record<string, unknown>): CreditError;
+/**
+ * Create a transient (retryable) error
+ */
+declare function createTransientError(message: string, details?: Record<string, unknown>): CreditError;
+/**
+ * Create an error for a V2 method the configured adapter does not implement
+ */
+declare function createUnsupportedOperationError(operation: string, hint?: string): CreditError;
+/**
+ * Create an invalid amount error
+ */
+declare function createInvalidAmountError(amount: unknown): CreditError;
+/**
+ * Check if an error is an idempotency conflict
+ */
+declare function isIdempotencyConflictError(error: unknown): boolean;
+/**
+ * Check if an error is safe to retry
+ *
+ * Only `TRANSIENT_ERROR` qualifies. Use {@link classifyDatabaseError} first to
+ * turn a raw driver error into a classified `CreditError`.
+ */
+declare function isTransientError(error: unknown): boolean;
+
+/**
+ * `paymentRef` as a global, semantic idempotency boundary.
+ *
+ * A payment reference is the identity of a *credit event* — one webhook, one
+ * invoice, one charge. It is deliberately not scoped to a user: a processor's
+ * reference is unique across the processor's whole account, and the SQL adapter
+ * has always enforced it with a unique index over `payment_ref` alone. Two
+ * problems followed from treating it as anything less.
+ *
+ * **It was scoped per user in memory and globally in SQL.** The in-memory
+ * adapter searched only the crediting user's own transactions, so replaying a
+ * reference against a *different* user credited both accounts, while the SQL
+ * adapter silently no-opped. Same call, two ledgers, opposite results — and the
+ * memory one is the direction that invents money.
+ *
+ * **It was compared on presence, never on payload.** A reference that arrived a
+ * second time carrying a different amount was accepted as a replay of the
+ * first, so a corrected or spoofed webhook credited the original amount and
+ * reported success. Presence is only sound when the payload is known to match;
+ * otherwise the honest answer is a conflict.
+ *
+ * So a reference now resolves to exactly one of three outcomes — `created`,
+ * `replayed`, `conflict` — in both adapters, and `conflict` mutates nothing.
+ */
+
+/**
+ * The fields that define the credit event a reference names.
+ *
+ * `description` is excluded on purpose: it is human-facing copy that a retry
+ * may legitimately regenerate ("Purchase 100 credits" versus "Purchase of 100
+ * credits") without the event being different. Everything that decides *how
+ * much lands where* is in.
+ */
+interface PaymentEventPayload {
+    userId: string;
+    amount: number;
+    /** The transaction row's `type` — the operation the reference names. */
+    type: PortableTransaction["type"];
+    /** The journal entry's `source` — where the credits came from. */
+    source: CreditSource;
+    /** The journal entry's `referenceType`. */
+    referenceType: JournalReferenceType;
+}
+/**
+ * The stored side of the comparison, as either adapter can produce it.
+ *
+ * `amount` is `unknown` because SQL returns `numeric` as a string, and
+ * comparing the mapped `Number` is exactly the rounding hole that let
+ * `9999999999.9900001` match a request for `9999999999.99`.
+ */
+interface StoredPaymentEvent {
+    userId: string;
+    amount: unknown;
+    type: string;
+    /** Absent when no journal entry could be located for the stored transaction. */
+    source?: string;
+    referenceType?: string;
+}
+/**
+ * Normalise a payment reference to "a reference" or "no reference".
+ *
+ * Empty and whitespace-only strings are *not* references: they cannot identify
+ * a payment, and treating them as one produced the divergence where SQL skipped
+ * the duplicate check (falsy) but still stored the value, so the replay hit the
+ * unique index and threw while memory quietly credited twice.
+ *
+ * Unlike an idempotency key, a blank reference is normalised rather than
+ * rejected. A key is the caller's explicit request for exactly-once and a blank
+ * one means they got it wrong; `paymentRef` is an optional annotation on a
+ * credit, and an absent one is a normal, supported call.
+ */
+declare function normalizePaymentRef(ref?: string | null): string | undefined;
+/**
+ * Name the first field on which a stored credit event disagrees, or `null`.
+ *
+ * `null` means the delivery is a genuine replay and must change nothing.
+ * Anything else is a conflict: the same reference was used for a different
+ * event, and crediting on it would either double-credit or credit the wrong
+ * amount to the wrong account.
+ *
+ * `source` and `referenceType` are compared only when the stored side has them.
+ * They live on the journal entry, and a transaction written before this library
+ * journalled its purchases has none to compare against — treating that absence
+ * as a mismatch would turn every pre-existing reference into a permanent
+ * conflict, which is a refusal to credit rather than a protection against one.
+ */
+declare function describePaymentMismatch(stored: StoredPaymentEvent, expected: PaymentEventPayload): string | null;
+/**
+ * Refuse a payment reference on the direct, record-only transaction writer.
+ *
+ * `createTransaction` writes a ledger *record*: no balance moves and no journal
+ * entry is created. But a `paymentRef` on that record still occupies the global
+ * unique boundary, and `addCreditsV2` treats the row that holds a reference as
+ * the authoritative credit event — a later delivery of the real payment with
+ * the same reference then matches the record on user/amount/type, reports
+ * `replayed`, and credits nothing, forever. The record would have consumed the
+ * payment.
+ *
+ * Same shape as `assertUnkeyedDirectReservation`: the claim is refused at the
+ * boundary, so the row that could impersonate a credit event cannot be written
+ * in the first place. Credits that carry a reference go through
+ * `addCreditsAtomic` / `addCreditsV2`, which claim the reference and move the
+ * balance in one atomic step.
+ */
+declare function assertUnreferencedDirectTransaction(input: {
+    userId: string;
+    paymentRef?: string;
+}): void;
+/**
+ * The conflict, as an error, for the legacy `addCreditsAtomic` signature.
+ *
+ * That method returns `void`, so it has nowhere to put a `conflict` outcome.
+ * Swallowing one would be the original bug in a new place — the SQL adapter
+ * used to no-op on a cross-user reference reuse, which reads to the caller as
+ * "credited" — so the legacy path throws instead. Callers that want to *handle*
+ * a conflict rather than catch it should use `addCreditsV2`.
+ */
+declare function createPaymentRefConflictError(paymentRef: string, details: {
+    userId: string;
+    mismatch: string;
+    existingUserId?: string;
+}): CreditError;
+
+/**
+ * Validation and exact comparison for credit amounts.
+ *
+ * Every amount ends up in a `numeric(12, 2)` column, so the ledger can only
+ * represent values on the cent grid, with at most ten integer digits. A value
+ * outside that grid is not "close enough" — PostgreSQL silently rounds it on
+ * write, and the row that comes back no longer equals what the caller asked
+ * for. Rejecting it before any row is touched is the only way the ledger and
+ * the caller can agree on what happened.
+ *
+ * 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. */
+declare const CREDIT_AMOUNT_MAX = 9999999999.99;
+/**
+ * Convert an amount to whole cents, or `null` if it is not exactly on the grid.
+ *
+ * `Math.round(value * 100) === value * 100` is the tempting check and it is
+ * wrong: `1.005 * 100` is `100.49999999999999` in binary float, so a genuinely
+ * invalid value can pass and a valid one can fail. Rounding first and then
+ * confirming the value round-trips (`value === cents / 100`) is exact for
+ * everything in range, because a cent count below 2^53 divided by 100 is the
+ * nearest double to that decimal, which is what the literal parsed to.
+ */
+declare function toCents(value: number): number | null;
+/**
+ * Add amounts on the cent grid, exactly.
+ *
+ * Deriving a total with `+` is not safe in a ledger that validates against the
+ * grid: `0.10 + 0.20` is `0.30000000000000004` and `0.30 - 0.10` is
+ * `0.19999999999999998`, neither of which is a value `numeric(12, 2)` can hold.
+ * Two perfectly legal columns would therefore produce a total the validator
+ * rejects with `INVALID_AMOUNT`, blaming the caller for a rounding artefact.
+ * Summing whole cents is exact for every value in range, and `cents / 100` is
+ * the nearest double to that decimal — the same one the literal would parse to.
+ *
+ * Subtract by negating: `sumAmounts(total, -amount)`. Negation is exact.
+ *
+ * This is arithmetic, not validation. If any input is itself off the grid the
+ * float sum is returned unchanged — deliberately, so a corrupt value is never
+ * rounded into legitimacy here — but that is not a guarantee the result will be
+ * rejected downstream: two off-grid inputs can cancel, and `sumAmounts(0.005,
+ * -0.005)` is a perfectly representable `0`. Inputs read from storage must be
+ * validated as inputs, with `assertValidStoredAmount` or
+ * `assertValidStoredAmountRaw`, before they are summed. Checking only the
+ * derived result is not enough and never was.
+ */
+declare function sumAmounts(...values: number[]): number;
+/** Amounts that may be *moved*: strictly positive and on the cent grid. */
+declare function isValidCreditAmount(value: unknown): value is number;
+/**
+ * Reject an unusable amount before any row is written.
+ *
+ * @param context - merged into the error details, e.g. `{ userId }`.
+ */
+declare function assertValidCreditAmount(value: unknown, context?: Record<string, unknown>): asserts value is number;
+/**
+ * Amounts the ledger can *record*: on the cent grid and in range, but free to
+ * be zero or negative.
+ *
+ * Not every numeric column holds something spendable. A release journal entry
+ * records `amount: 0` because no credits changed hands, and `balanceAfter` goes
+ * negative for an account that was corrected or allowed to overdraw. Forcing
+ * those through {@link isValidCreditAmount} would reject legitimate ledger
+ * rows; skipping validation entirely would let `Infinity` or a third decimal
+ * reach the column and be silently rounded or rejected by the driver.
+ */
+declare function isRepresentableAmount(value: unknown): value is number;
+/**
+ * Reject a ledger value the `numeric(12, 2)` column cannot hold exactly.
+ *
+ * @param field - the column being written, so the error names the culprit.
+ */
+declare function assertRepresentableAmount(value: unknown, field: string, context?: Record<string, unknown>): asserts value is number;
+/**
+ * Check a whole set of optional ledger fields at once.
+ *
+ * The balance writers each take a handful of independently optional numbers,
+ * and validating them one `if` at a time is where one quietly gets missed.
+ * Undefined entries are skipped — they mean "leave this column alone".
+ */
+declare function assertRepresentableFields(fields: Record<string, unknown>, context?: Record<string, unknown>): void;
+/**
+ * The lowest `balance` that keeps every outstanding hold committable.
+ *
+ * Commit's funding guard is `balance + bonusCredits >= amount`, and every live
+ * hold is counted in `reserved`, so any write that lowers `balance` must keep
+ * `balance + bonusCredits >= reserved` — otherwise a hold that was fully backed
+ * when it was placed throws `INSUFFICIENT_CREDITS` at commit time and is
+ * stranded. Monthly resets, tier downgrades and explicit tier writes all lower
+ * `balance` to a configured target; this is the floor they may not cut through.
+ *
+ * The floor is `reserved - bonusCredits`, never below zero: bonus credits also
+ * fund commits, so they count toward the backing.
+ */
+declare function backedBalanceFloor(reserved: number, bonusCredits: number): number;
+/**
+ * Validate a limit derived from tier configuration.
+ *
+ * `Infinity` is this codebase's sentinel for an unlimited tier, so it is
+ * accepted here; {@link storedMonthlyLimit} decides what actually reaches the
+ * column. Every other value ends up in `numeric(12, 2)` and has to fit, so a
+ * tier configured with `monthlyCredits: 1.005` is caught here rather than
+ * silently rounded to `1.01` by PostgreSQL.
+ */
+declare function assertRepresentableTierAmount(value: unknown, field: string, context?: Record<string, unknown>): void;
+/**
+ * Validate a stored amount in the representation storage actually returned.
+ *
+ * Checking the mapped float is not enough, because the mapping is lossy in both
+ * directions. A `numeric` column with no scale constraint can hold
+ * `9999999999.9900001`; `Number()` rounds that to `9999999999.99`, which is a
+ * perfectly valid amount, so a validator looking at the mapped value sees
+ * nothing wrong and the transition proceeds — while PostgreSQL goes on doing
+ * exact arithmetic with the digits JavaScript threw away. `NaN` and values past
+ * double range are worse: the mapper turns them into `0`, which misreports what
+ * the row holds.
+ *
+ * So this runs on the driver's own output — a string, for `numeric` — and uses
+ * exact integer arithmetic. It returns the amount as a float only after
+ * establishing that the float is a faithful representation of it.
+ *
+ * @returns the stored amount, exactly representable as a JS number.
+ */
+/**
+ * How an unlimited tier's monthly limit is stored.
+ *
+ * `getConfigMonthlyLimit` returns `Infinity` for an unlimited tier, and no
+ * numeric column can hold that. Both adapters therefore store the ceiling of
+ * the representable range instead: any real usage compares below it, so
+ * "unlimited" keeps behaving like unlimited, and a reader that knows nothing
+ * about the sentinel sees a very large allowance rather than a wrong one.
+ *
+ * This exists so the two adapters cannot drift. The SQL adapter previously
+ * stored `0` here, which reads as *no* allowance — the exact opposite — while
+ * the in-memory adapter kept `Infinity`.
+ */
+declare function storedMonthlyLimit(limit: number): number;
+declare function assertValidStoredAmountRaw(raw: unknown, context: Record<string, unknown>): number;
+/**
+ * Reject a *persisted* amount that the ledger cannot honour.
+ *
+ * A reservation row is written once and read back on every transition, and
+ * nothing stops a direct SQL write, a botched migration, or an older version of
+ * this library from leaving an amount the invariants cannot reason about. A
+ * negative one is the dangerous case: `reserved >= amount` is trivially true
+ * for it, and `balance - (-10)` *adds* credits, so a transition that trusts the
+ * stored value mints money. Every transition therefore re-validates what it
+ * locked before it changes anything.
+ *
+ * Deliberately fails release and expire as well as commit. Returning a hold of
+ * an unknown size is not obviously safer than spending one — it hands back
+ * coverage that may never have been taken — so a corrupt row stops moving
+ * entirely and waits for an operator, rather than being partially honoured.
+ *
+ * This is the float-typed form, used by the in-memory adapter where the stored
+ * value *is* a JS number and no conversion has happened. A repository whose
+ * storage returns some other representation must use
+ * {@link assertValidStoredAmountRaw} instead, or the conversion will hide the
+ * corruption from the check.
+ */
+declare function assertValidStoredAmount(value: unknown, context: Record<string, unknown>): asserts value is number;
+/**
+ * Parse a value read back from a `numeric` column into exact cents.
+ *
+ * Drivers return `numeric` as a string precisely so no precision is lost in
+ * transit; comparing the parsed floats would throw that away again. Returns
+ * `null` for anything unparseable so callers can treat it as "not equal"
+ * rather than crashing on malformed ledger data.
+ */
+declare function numericToCents(value: unknown): bigint | null;
+/**
+ * Exact equality for two amounts that may be numbers or `numeric` strings.
+ *
+ * Unparseable input is *not* equal to anything, including itself — a
+ * comparison against corrupt data must never come back "matches".
+ */
+declare function sameAmount(a: unknown, b: unknown): boolean;
+
+/**
+ * Validation for caller-supplied idempotency keys.
+ *
+ * The keys are enforced by a *partial* unique index (`WHERE idempotency_key IS
+ * NOT NULL`), so "no key" and "a key" are genuinely different states and the
+ * boundary between them has to be unambiguous. An empty string sat in between:
+ * the SQL adapter stored it — occupying a row in the unique index — while every
+ * `if (key)` check read it as absent, so the key was written but never
+ * deduplicated anything, and the in-memory adapter ignored it outright. Two
+ * adapters, two behaviours, neither of them the one the caller asked for.
+ *
+ * Rejecting is preferred over trimming. Normalising `" job-1 "` to `"job-1"`
+ * would mean two callers who sent different strings silently share a hold, and
+ * a caller whose key is accidentally whitespace would rather hear about it than
+ * have it quietly repaired.
+ */
+/** A usable key: a string with at least one non-whitespace character. */
+declare function isValidIdempotencyKey(value: unknown): value is string;
+/**
+ * Reject an unusable idempotency key before anything is written.
+ *
+ * `undefined` is allowed and means "no key" — that is the legacy, at-least-once
+ * behaviour, and it is a valid choice. Only a key that was *supplied* and
+ * cannot work is an error.
+ */
+declare function assertValidIdempotencyKey(value: unknown, context?: Record<string, unknown>): asserts value is string | undefined;
+/**
+ * Namespace the V2 reservation transitions own. Public writes may not use it.
+ *
+ * A transition that finds its deterministic key already present treats an
+ * exactly-matching row as its own retry and reuses it. That is correct against
+ * a row the transition itself wrote — and a hole if any caller can write one.
+ * A caller who pre-seeds `reservation:<id>:commit` with a plausible-looking
+ * entry would have the commit adopt it: the reservation flips to committed and
+ * the balance moves, while the only journal row is the caller's, never written
+ * by the transition and not necessarily describing what it did.
+ *
+ * Reserving the prefix removes the premise. Nothing outside the transitions can
+ * create a key in it, so an existing key is either the transition's own retry
+ * or corruption — and corruption is refused.
+ */
+declare const RESERVED_JOURNAL_KEY_PREFIX = "reservation:";
+/** True when a key belongs to the namespace the V2 transitions own. */
+declare function isReservedJournalKey(key: unknown): boolean;
+/**
+ * Refuse a public journal write that claims a key in the reserved namespace.
+ *
+ * Called from the adapters' public `createJournalEntry`, never from the
+ * transitions themselves — they are the ones the namespace belongs to.
+ */
+declare function assertPublicJournalKey(key: unknown, userId: string): void;
+
+/**
+ * Driver-error classification.
+ *
+ * Consuming apps need to react differently to "the user is out of credits"
+ * (show a paywall), "the database blinked" (retry), and "our SQL is wrong"
+ * (page someone). Drivers signal that distinction through a SQLSTATE on the
+ * thrown object, so this maps SQLSTATE classes onto {@link CreditErrorCode}
+ * without taking a dependency on any particular driver.
+ */
+
+/**
+ * Read a SQLSTATE-ish `code` off an unknown thrown value.
+ *
+ * The chain matters. Wrapping drivers — and Drizzle itself, in places — rethrow
+ * with the original error on `cause` and no `code` of their own, so looking only
+ * at the outermost object reports "no SQLSTATE" for an error that plainly has
+ * one. The walk is bounded and tracks what it has seen, since a `cause` graph
+ * can be circular.
+ */
+declare function getSqlState(error: unknown): string | undefined;
+/**
+ * True when the SQLSTATE is a unique-violation (`23505`).
+ *
+ * Callers that race on a partial unique index use this to tell "someone else
+ * inserted the same idempotency key" from a genuine schema error.
+ */
+declare function isUniqueViolation(error: unknown): boolean;
+/** True when the error is worth retrying. */
+declare function isTransientDatabaseError(error: unknown): boolean;
+/**
+ * Wrap an unknown thrown value in a classified {@link CreditError}.
+ *
+ * Already-classified `CreditError`s pass through untouched so a domain outcome
+ * (insufficient credits, idempotency conflict) is never downgraded to
+ * `DATABASE_ERROR` by a generic catch further up the stack.
+ */
+declare function classifyDatabaseError(error: unknown, context?: Record<string, unknown>): CreditError;
 
 /**
  * Core credit operations - framework agnostic
@@ -91,6 +662,11 @@ declare function createInvalidOperationTypeError(operationType: string, validTyp
 /**
  * Commit a reservation with journal entry
  *
+ * On a V2 repository the balance move and the journal entry happen in one
+ * transaction and this function adds nothing of its own — the duplicate entry
+ * the previous implementation wrote is gone. Legacy adapters keep the old
+ * read-then-write path, journal included.
+ *
  * @param repository - The credit repository
  * @param userId - User ID
  * @param reservationId - Reservation to commit
@@ -112,8 +688,10 @@ declare function releaseReservationWithJournal(repository: ICreditRepository, us
  * @param amount - Credits to reserve
  * @param operationType - Type of operation
  * @param expiryMs - Reservation expiry time in milliseconds
+ * @param idempotencyKey - Optional caller key; a replay with the same
+ *   amount/operation returns the original reservation instead of a second hold
  * @returns The reservation
  */
-declare function reserveCreditsForOperation(repository: ICreditRepository, userId: string, amount: number, operationType: string, expiryMs?: number): Promise<PortableReservation>;
+declare function reserveCreditsForOperation(repository: ICreditRepository, userId: string, amount: number, operationType: string, expiryMs?: number, idempotencyKey?: string): Promise<PortableReservation>;
 
-export { CreditError, CreditErrorCode, type CreditErrorCodeType, PortableReservation, commitReservationWithJournal, createInsufficientCreditsError, createInvalidOperationTypeError, createReservationAlreadyProcessedError, createReservationExpiredError, createReservationNotFoundError, createUserNotFoundError, isCreditError, isInsufficientCreditsError, releaseReservationWithJournal, reserveCreditsForOperation };
+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 };