@nehorai/credits 1.7.0 → 2.1.0

package/dist/core/index.cjs

@@ -20,61 +20,77 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/core/index.ts
 var core_exports = {};
 __export(core_exports, {
+  CREDIT_AMOUNT_MAX: () => CREDIT_AMOUNT_MAX,
+  CREDIT_AMOUNT_SCALE: () => CREDIT_AMOUNT_SCALE,
   CreditError: () => CreditError,
   CreditErrorCode: () => CreditErrorCode,
+  RESERVATION_STATUSES: () => RESERVATION_STATUSES,
+  RESERVED_JOURNAL_KEY_PREFIX: () => RESERVED_JOURNAL_KEY_PREFIX,
+  TERMINAL_RESERVATION_STATUSES: () => TERMINAL_RESERVATION_STATUSES,
+  assertDirectStatusWriteAllowed: () => assertDirectStatusWriteAllowed,
+  assertHoldPlaced: () => assertHoldPlaced,
+  assertKnownReservationStatus: () => assertKnownReservationStatus,
+  assertPublicJournalKey: () => assertPublicJournalKey,
+  assertRepresentableAmount: () => assertRepresentableAmount,
+  assertRepresentableFields: () => assertRepresentableFields,
+  assertRepresentableTierAmount: () => assertRepresentableTierAmount,
+  assertUnkeyedDirectReservation: () => assertUnkeyedDirectReservation,
+  assertUnreferencedDirectTransaction: () => assertUnreferencedDirectTransaction,
+  assertValidCreditAmount: () => assertValidCreditAmount,
+  assertValidIdempotencyKey: () => assertValidIdempotencyKey,
+  assertValidStoredAmount: () => assertValidStoredAmount,
+  assertValidStoredAmountRaw: () => assertValidStoredAmountRaw,
+  backedBalanceFloor: () => backedBalanceFloor,
   calculateAvailableCredits: () => calculateAvailableCredits,
+  classifyDatabaseError: () => classifyDatabaseError,
   commitReservationWithJournal: () => commitReservationWithJournal,
   createDeferredExecutor: () => createDeferredExecutor,
+  createIdempotencyConflictError: () => createIdempotencyConflictError,
   createInsufficientCreditsError: () => createInsufficientCreditsError,
+  createInvalidAmountError: () => createInvalidAmountError,
   createInvalidOperationTypeError: () => createInvalidOperationTypeError,
+  createPaymentRefConflictError: () => createPaymentRefConflictError,
   createReservationAlreadyProcessedError: () => createReservationAlreadyProcessedError,
   createReservationExpiredError: () => createReservationExpiredError,
   createReservationNotFoundError: () => createReservationNotFoundError,
+  createTransientError: () => createTransientError,
+  createUnsupportedOperationError: () => createUnsupportedOperationError,
   createUserNotFoundError: () => createUserNotFoundError,
+  describePaymentMismatch: () => describePaymentMismatch,
   genericDeferred: () => genericDeferred,
+  getSqlState: () => getSqlState,
+  hasPlacedHold: () => hasPlacedHold,
   isCreditError: () => isCreditError,
+  isCreditedOutcome: () => isCreditedOutcome,
+  isIdempotencyConflictError: () => isIdempotencyConflictError,
   isInsufficientCreditsError: () => isInsufficientCreditsError,
+  isRepresentableAmount: () => isRepresentableAmount,
+  isReservationStatus: () => isReservationStatus,
+  isReservedJournalKey: () => isReservedJournalKey,
+  isReservedOutcome: () => isReservedOutcome,
+  isTerminalReservationStatus: () => isTerminalReservationStatus,
+  isTransientDatabaseError: () => isTransientDatabaseError,
+  isTransientError: () => isTransientError,
+  isUniqueViolation: () => isUniqueViolation,
+  isValidCreditAmount: () => isValidCreditAmount,
+  isValidIdempotencyKey: () => isValidIdempotencyKey,
+  isWinningOutcome: () => isWinningOutcome,
   noopDeferred: () => noopDeferred,
+  normalizePaymentRef: () => normalizePaymentRef,
+  numericToCents: () => numericToCents,
   releaseReservationWithJournal: () => releaseReservationWithJournal,
   reserveCreditsForOperation: () => reserveCreditsForOperation,
+  sameAmount: () => sameAmount,
+  storedMonthlyLimit: () => storedMonthlyLimit,
+  sumAmounts: () => sumAmounts,
   synchronousDeferred: () => synchronousDeferred,
+  terminalStatusOf: () => terminalStatusOf,
+  toCents: () => toCents,
   toDate: () => toDate,
   toPortableTimestamp: () => toPortableTimestamp
 });
 module.exports = __toCommonJS(core_exports);
 
-// src/core/types.ts
-function calculateAvailableCredits(balance, bonusCredits, reserved) {
-  return balance + bonusCredits - reserved;
-}
-function toPortableTimestamp(value) {
-  if (!value) {
-    return (/* @__PURE__ */ new Date()).toISOString();
-  }
-  if (typeof value === "string") {
-    return value;
-  }
-  if (value instanceof Date) {
-    return value.toISOString();
-  }
-  if (typeof value === "object" && value !== null && "toDate" in value && typeof value.toDate === "function") {
-    return value.toDate().toISOString();
-  }
-  return (/* @__PURE__ */ new Date()).toISOString();
-}
-function toDate(value) {
-  if (value instanceof Date) {
-    return value;
-  }
-  if (typeof value === "string") {
-    return new Date(value);
-  }
-  if (typeof value === "object" && value !== null && "toDate" in value && typeof value.toDate === "function") {
-    return value.toDate();
-  }
-  return /* @__PURE__ */ new Date();
-}
-
 // src/core/errors.ts
 var CreditErrorCode = {
   INSUFFICIENT_CREDITS: "INSUFFICIENT_CREDITS",
@@ -84,7 +100,32 @@ var CreditErrorCode = {
   USER_NOT_FOUND: "USER_NOT_FOUND",
   INVALID_OPERATION_TYPE: "INVALID_OPERATION_TYPE",
   CONFIGURATION_ERROR: "CONFIGURATION_ERROR",
-  DATABASE_ERROR: "DATABASE_ERROR"
+  DATABASE_ERROR: "DATABASE_ERROR",
+  /** Caller reused an idempotency key with a different immutable payload. */
+  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.
+   */
+  TRANSIENT_ERROR: "TRANSIENT_ERROR",
+  /** The configured repository adapter does not implement the requested V2 method. */
+  UNSUPPORTED_OPERATION: "UNSUPPORTED_OPERATION",
+  /** Amount was not a finite positive number. */
+  INVALID_AMOUNT: "INVALID_AMOUNT",
+  /** Idempotency key was supplied but empty or whitespace-only. */
+  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.
+   */
+  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.
+   */
+  UNBACKED_RESERVATION: "UNBACKED_RESERVATION"
 };
 var CreditError = class _CreditError extends Error {
   code;
@@ -126,7 +167,7 @@ function createInsufficientCreditsError(required, available) {
   return new CreditError(
     `Insufficient credits: available ${available}, required ${required}`,
     CreditErrorCode.INSUFFICIENT_CREDITS,
-    { required, available, shortfall: required - available }
+    { required, available, shortfall: sumAmounts(required, -available) }
   );
 }
 function createReservationNotFoundError(reservationId) {
@@ -164,6 +205,435 @@ function createInvalidOperationTypeError(operationType, validTypes) {
     { operationType, validTypes }
   );
 }
+function createIdempotencyConflictError(idempotencyKey, details) {
+  return new CreditError(
+    `Idempotency key ${idempotencyKey} was reused with a different payload`,
+    CreditErrorCode.IDEMPOTENCY_CONFLICT,
+    { idempotencyKey, ...details }
+  );
+}
+function createTransientError(message, details) {
+  return new CreditError(message, CreditErrorCode.TRANSIENT_ERROR, details);
+}
+function createUnsupportedOperationError(operation, hint) {
+  return new CreditError(
+    hint ? `Repository does not support ${operation}. ${hint}` : `Repository does not support ${operation}`,
+    CreditErrorCode.UNSUPPORTED_OPERATION,
+    { operation, ...hint ? { hint } : {} }
+  );
+}
+function createInvalidAmountError(amount) {
+  return new CreditError(
+    `Credit amount must be a finite positive number (got ${String(amount)})`,
+    CreditErrorCode.INVALID_AMOUNT,
+    { amount }
+  );
+}
+function isIdempotencyConflictError(error) {
+  return isCreditError(error) && error.code === CreditErrorCode.IDEMPOTENCY_CONFLICT;
+}
+function isTransientError(error) {
+  return isCreditError(error) && error.code === CreditErrorCode.TRANSIENT_ERROR;
+}
+
+// src/core/amount.ts
+var CREDIT_AMOUNT_SCALE = 2;
+var CREDIT_AMOUNT_MAX = 999999999999e-2;
+var MAX_CENTS = 999999999999;
+function toCents(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  const cents = Math.round(value * 100);
+  if (!Number.isSafeInteger(cents)) return null;
+  return value === cents / 100 ? cents : null;
+}
+function sumAmounts(...values) {
+  let cents = 0;
+  for (const value of values) {
+    const valueCents = toCents(value);
+    if (valueCents === null) return floatSum(values);
+    cents += valueCents;
+  }
+  return Number.isSafeInteger(cents) ? cents / 100 : floatSum(values);
+}
+function floatSum(values) {
+  let total = 0;
+  for (const value of values) total += value;
+  return total;
+}
+function isValidCreditAmount(value) {
+  if (typeof value !== "number") return false;
+  const cents = toCents(value);
+  return cents !== null && cents > 0 && cents <= MAX_CENTS;
+}
+function assertValidCreditAmount(value, context) {
+  if (isValidCreditAmount(value)) return;
+  throw new CreditError(
+    creditAmountReason(value),
+    CreditErrorCode.INVALID_AMOUNT,
+    { amount: value, max: CREDIT_AMOUNT_MAX, scale: CREDIT_AMOUNT_SCALE, ...context }
+  );
+}
+function creditAmountReason(value) {
+  if (typeof value !== "number") {
+    return `Credit amount must be a number (got ${typeof value})`;
+  }
+  if (!Number.isFinite(value)) {
+    return `Credit amount must be finite (got ${String(value)})`;
+  }
+  if (value <= 0) {
+    return `Credit amount must be greater than zero (got ${value})`;
+  }
+  if (value > CREDIT_AMOUNT_MAX) {
+    return `Credit amount ${value} exceeds the maximum of ${CREDIT_AMOUNT_MAX}`;
+  }
+  return `Credit amount ${value} is not exact to ${CREDIT_AMOUNT_SCALE} decimal places`;
+}
+function isRepresentableAmount(value) {
+  if (typeof value !== "number") return false;
+  const cents = toCents(value);
+  return cents !== null && Math.abs(cents) <= MAX_CENTS;
+}
+function assertRepresentableAmount(value, field, context) {
+  if (isRepresentableAmount(value)) return;
+  throw new CreditError(
+    `${field} must be a finite number exact to ${CREDIT_AMOUNT_SCALE} decimal places within \xB1${CREDIT_AMOUNT_MAX} (got ${String(value)})`,
+    CreditErrorCode.INVALID_AMOUNT,
+    { field, value, max: CREDIT_AMOUNT_MAX, scale: CREDIT_AMOUNT_SCALE, ...context }
+  );
+}
+function assertRepresentableFields(fields, context) {
+  for (const [field, value] of Object.entries(fields)) {
+    if (value === void 0) continue;
+    assertRepresentableAmount(value, field, context);
+  }
+}
+function backedBalanceFloor(reserved, bonusCredits) {
+  const floor = Math.max(0, sumAmounts(reserved, -bonusCredits));
+  assertRepresentableAmount(floor, "backedBalanceFloor", { reserved, bonusCredits });
+  return floor;
+}
+function assertRepresentableTierAmount(value, field, context) {
+  if (value === Number.POSITIVE_INFINITY) return;
+  assertRepresentableAmount(value, field, context);
+}
+function storedMonthlyLimit(limit) {
+  return Number.isFinite(limit) ? limit : CREDIT_AMOUNT_MAX;
+}
+function assertValidStoredAmountRaw(raw, context) {
+  const cents = numericToCents(raw);
+  if (cents !== null && cents > 0n && cents <= BigInt(MAX_CENTS)) {
+    return Number(cents) / 100;
+  }
+  throw new CreditError(
+    `Stored credit amount ${String(raw)} is not a valid amount, so this transition was refused before any state changed. The row must be repaired before it can be committed, released or expired.`,
+    CreditErrorCode.INVALID_AMOUNT,
+    {
+      amount: typeof raw === "string" ? raw : String(raw),
+      reason: "corrupt_stored_amount",
+      max: CREDIT_AMOUNT_MAX,
+      scale: CREDIT_AMOUNT_SCALE,
+      ...context
+    }
+  );
+}
+function assertValidStoredAmount(value, context) {
+  if (isValidCreditAmount(value)) return;
+  throw new CreditError(
+    `Stored credit amount ${String(value)} is not a valid amount, so this transition was refused before any state changed. The row must be repaired before it can be committed, released or expired.`,
+    CreditErrorCode.INVALID_AMOUNT,
+    { amount: value, reason: "corrupt_stored_amount", max: CREDIT_AMOUNT_MAX, ...context }
+  );
+}
+function numericToCents(value) {
+  if (typeof value === "number") {
+    const cents2 = toCents(value);
+    return cents2 === null ? null : BigInt(cents2);
+  }
+  if (typeof value !== "string") return null;
+  const match = /^([+-]?)(\d+)(?:\.(\d*))?$/.exec(value.trim());
+  if (!match) return null;
+  const [, sign, whole, fraction = ""] = match;
+  if (/[1-9]/.test(fraction.slice(CREDIT_AMOUNT_SCALE))) return null;
+  const cents = BigInt(whole) * 100n + BigInt(fraction.slice(0, CREDIT_AMOUNT_SCALE).padEnd(CREDIT_AMOUNT_SCALE, "0"));
+  return sign === "-" ? -cents : cents;
+}
+function sameAmount(a, b) {
+  const left = numericToCents(a);
+  const right = numericToCents(b);
+  return left !== null && right !== null && left === right;
+}
+
+// src/core/types.ts
+function calculateAvailableCredits(balance, bonusCredits, reserved) {
+  return sumAmounts(balance, bonusCredits, -reserved);
+}
+function toPortableTimestamp(value) {
+  if (!value) {
+    return (/* @__PURE__ */ new Date()).toISOString();
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === "object" && value !== null && "toDate" in value && typeof value.toDate === "function") {
+    return value.toDate().toISOString();
+  }
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function toDate(value) {
+  if (value instanceof Date) {
+    return value;
+  }
+  if (typeof value === "string") {
+    return new Date(value);
+  }
+  if (typeof value === "object" && value !== null && "toDate" in value && typeof value.toDate === "function") {
+    return value.toDate();
+  }
+  return /* @__PURE__ */ new Date();
+}
+
+// src/core/outcomes.ts
+function isCreditedOutcome(outcome) {
+  return outcome.outcome === "created";
+}
+function isWinningOutcome(outcome) {
+  return outcome.outcome === "committed" || outcome.outcome === "released" || outcome.outcome === "expired";
+}
+function isReservedOutcome(outcome) {
+  return outcome.outcome === "created" || outcome.outcome === "replayed";
+}
+
+// src/core/reservation-integrity.ts
+var RESERVATION_STATUSES = [
+  "reserved",
+  "committed",
+  "released",
+  "expired"
+];
+var TERMINAL_RESERVATION_STATUSES = [
+  "committed",
+  "released",
+  "expired"
+];
+function isReservationStatus(value) {
+  return RESERVATION_STATUSES.includes(value);
+}
+function isTerminalReservationStatus(value) {
+  return TERMINAL_RESERVATION_STATUSES.includes(value);
+}
+function assertKnownReservationStatus(reservation, transition) {
+  if (isReservationStatus(reservation.status)) return;
+  throw new CreditError(
+    `Reservation ${reservation.id} holds the status ${JSON.stringify(reservation.status)}, which is not one of ${RESERVATION_STATUSES.join(", ")}. The ${transition} was refused before any state changed; the row must be repaired by an operator.`,
+    CreditErrorCode.CORRUPT_RESERVATION_STATUS,
+    {
+      userId: reservation.userId,
+      reservationId: reservation.id,
+      transition,
+      status: typeof reservation.status === "string" ? reservation.status : String(reservation.status),
+      allowed: [...RESERVATION_STATUSES],
+      reason: "corrupt_reservation_status"
+    }
+  );
+}
+function terminalStatusOf(reservation, transition) {
+  assertKnownReservationStatus(reservation, transition);
+  if (isTerminalReservationStatus(reservation.status)) return reservation.status;
+  throw new CreditError(
+    `Reservation ${reservation.id} is ${reservation.status}, which is not a terminal status, but the ${transition} tried to report it as one.`,
+    CreditErrorCode.CORRUPT_RESERVATION_STATUS,
+    {
+      userId: reservation.userId,
+      reservationId: reservation.id,
+      transition,
+      status: reservation.status,
+      reason: "not_terminal"
+    }
+  );
+}
+function assertHoldPlaced(reservation, transition) {
+  if (reservation.holdPlacedAt) return;
+  throw new CreditError(
+    `Reservation ${reservation.id} does not record that its hold was placed atomically (holdPlacedAt is absent), so the credits it claims to hold may never have been reserved. The ${transition} was refused before any state changed: honouring it would spend coverage belonging to another reservation. Rows written by createReservation are not V2 reservations; place holds with reserveCredits.`,
+    CreditErrorCode.UNBACKED_RESERVATION,
+    {
+      userId: reservation.userId,
+      reservationId: reservation.id,
+      transition,
+      idempotencyKey: reservation.idempotencyKey ?? void 0,
+      reason: "hold_not_placed"
+    }
+  );
+}
+function assertUnkeyedDirectReservation(input) {
+  if (input.idempotencyKey === void 0 || input.idempotencyKey === null) return;
+  throw new CreditError(
+    "createReservation cannot accept an idempotencyKey: it writes the reservation row without placing the hold, so the key would name credits that were never reserved, and a later reserveCredits with the same key would adopt it as a replay. Call reserveCredits (or reserveCreditsV2) with the key instead \u2014 it claims the key and places the hold in one transaction.",
+    CreditErrorCode.UNSUPPORTED_OPERATION,
+    {
+      userId: input.userId,
+      idempotencyKey: input.idempotencyKey,
+      operation: "createReservation",
+      reason: "keyed_direct_reservation"
+    }
+  );
+}
+function hasPlacedHold(reservation) {
+  return Boolean(reservation.holdPlacedAt);
+}
+function assertDirectStatusWriteAllowed(reservation, status) {
+  if (status === "reserved") {
+    throw new CreditError(
+      `Reservation ${reservation.id} cannot have its status set back to "reserved": updateReservationStatus does not place a hold, so the reopened row would claim credits nothing reserved. Create a new reservation with reserveCredits instead.`,
+      CreditErrorCode.UNSUPPORTED_OPERATION,
+      {
+        userId: reservation.userId,
+        reservationId: reservation.id,
+        status,
+        reason: "reopen_reservation"
+      }
+    );
+  }
+  if (!reservation.holdPlacedAt) return;
+  throw new CreditError(
+    `Reservation ${reservation.id} is backed by an atomically placed hold, so its status may only be assigned by the transition that settles it. Writing "${status}" directly would change the status without moving the credits it stands for, stranding the hold. Use commitReservation / releaseReservation / expireReservation (or their V2 forms) instead.`,
+    CreditErrorCode.UNSUPPORTED_OPERATION,
+    {
+      userId: reservation.userId,
+      reservationId: reservation.id,
+      status,
+      reason: "direct_status_write_on_backed_hold"
+    }
+  );
+}
+
+// src/core/payment-ref.ts
+function normalizePaymentRef(ref) {
+  if (typeof ref !== "string") return void 0;
+  const trimmed = ref.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function describePaymentMismatch(stored, expected) {
+  if (stored.userId !== expected.userId) return "userId";
+  if (!sameAmount(stored.amount, expected.amount)) return "amount";
+  if (stored.type !== expected.type) return "type";
+  if (stored.source !== void 0 && stored.source !== expected.source) return "source";
+  if (stored.referenceType !== void 0 && stored.referenceType !== expected.referenceType) {
+    return "referenceType";
+  }
+  return null;
+}
+function assertUnreferencedDirectTransaction(input) {
+  if (normalizePaymentRef(input.paymentRef) === void 0) return;
+  throw new CreditError(
+    "createTransaction cannot accept a paymentRef: it records a transaction without crediting the account, and the reference would then be treated as an already-delivered payment \u2014 a later addCredits call with the same reference reports `replayed` and credits nothing. Record unreferenced transactions here, or deliver referenced payments through addCredits (addCreditsAtomic / addCreditsV2), which claims the reference and moves the balance atomically.",
+    CreditErrorCode.UNSUPPORTED_OPERATION,
+    {
+      userId: input.userId,
+      paymentRef: input.paymentRef,
+      operation: "createTransaction",
+      reason: "referenced_direct_transaction"
+    }
+  );
+}
+function createPaymentRefConflictError(paymentRef, details) {
+  return new CreditError(
+    `Payment reference ${paymentRef} has already been used for a different credit event (${details.mismatch} differs). Nothing was credited. A payment reference identifies one credit event globally; reusing it for another user, amount or source is refused rather than silently ignored.`,
+    CreditErrorCode.IDEMPOTENCY_CONFLICT,
+    { paymentRef, reason: "payment_ref_conflict", ...details }
+  );
+}
+
+// src/core/idempotency.ts
+function isValidIdempotencyKey(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function assertValidIdempotencyKey(value, context) {
+  if (value === void 0 || value === null) return;
+  if (isValidIdempotencyKey(value)) return;
+  throw new CreditError(
+    typeof value === "string" ? "An idempotency key was supplied but is empty or whitespace-only. It cannot deduplicate anything, so it was rejected rather than stored as a key that never matches. Omit the key for at-least-once behaviour, or send a meaningful one." : `Idempotency key must be a string (got ${typeof value})`,
+    CreditErrorCode.INVALID_IDEMPOTENCY_KEY,
+    { idempotencyKey: value, ...context }
+  );
+}
+var RESERVED_JOURNAL_KEY_PREFIX = "reservation:";
+function isReservedJournalKey(key) {
+  return typeof key === "string" && key.startsWith(RESERVED_JOURNAL_KEY_PREFIX);
+}
+function assertPublicJournalKey(key, userId) {
+  if (!isReservedJournalKey(key)) return;
+  throw new CreditError(
+    `Idempotency keys starting with "${RESERVED_JOURNAL_KEY_PREFIX}" are reserved for the V2 reservation transitions and cannot be written directly. Use a key of your own, or commit/release/expire the reservation through the V2 methods.`,
+    CreditErrorCode.INVALID_IDEMPOTENCY_KEY,
+    { userId, idempotencyKey: key, reason: "reserved_namespace" }
+  );
+}
+
+// src/core/error-classify.ts
+var TRANSIENT_SQLSTATES = /* @__PURE__ */ new Set([
+  "40000",
+  "40001",
+  "40P01",
+  "55P03",
+  "57014",
+  "57P01",
+  "57P02",
+  "57P03",
+  "53200",
+  "53300",
+  "53400"
+]);
+var TRANSIENT_DRIVER_CODES = /* @__PURE__ */ new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "EPIPE",
+  "ETIMEDOUT",
+  "ENOTFOUND",
+  "EHOSTUNREACH"
+]);
+var NUMERIC_OVERFLOW = "22003";
+function getSqlState(error) {
+  const seen = /* @__PURE__ */ new Set();
+  let current = error;
+  for (let depth = 0; depth < 8; depth += 1) {
+    if (typeof current !== "object" || current === null || seen.has(current)) return void 0;
+    seen.add(current);
+    const code = current.code;
+    if (typeof code === "string") return code;
+    current = current.cause;
+  }
+  return void 0;
+}
+function isUniqueViolation(error) {
+  return getSqlState(error) === "23505";
+}
+function isTransientDatabaseError(error) {
+  const code = getSqlState(error);
+  if (!code) return false;
+  if (TRANSIENT_SQLSTATES.has(code)) return true;
+  if (TRANSIENT_DRIVER_CODES.has(code)) return true;
+  return code.startsWith("08");
+}
+function classifyDatabaseError(error, context) {
+  if (isCreditError(error)) return error;
+  const sqlState = getSqlState(error);
+  const message = error instanceof Error ? error.message : String(error);
+  const details = { ...context, ...sqlState ? { sqlState } : {} };
+  if (isTransientDatabaseError(error)) {
+    return new CreditError(message, CreditErrorCode.TRANSIENT_ERROR, details);
+  }
+  if (sqlState === NUMERIC_OVERFLOW) {
+    return new CreditError(message, CreditErrorCode.INVALID_AMOUNT, {
+      ...details,
+      reason: "amount_out_of_range"
+    });
+  }
+  return new CreditError(message, CreditErrorCode.DATABASE_ERROR, details);
+}
 
 // src/core/deferred.ts
 var genericDeferred = {
@@ -216,11 +686,13 @@ var creditSystemConfigSchema = import_zod.z.object({
   /**
    * Operation costs in credits
    * Keys are operation type names (any non-empty string)
-   * Values are positive numbers representing credit cost
+   * Values are non-negative numbers representing credit cost. 0 marks a free
+   * operation: `withCredits` runs it without touching the ledger. Amounts that
+   * move credits stay strictly positive, so `reserveCredits` refuses a 0.
    */
   operationCosts: import_zod.z.record(
     import_zod.z.string().min(1),
-    import_zod.z.number().positive()
+    import_zod.z.number().nonnegative()
   ),
   /**
    * Display labels for operation types (English canonical labels).
@@ -454,78 +926,230 @@ function getOperationLabel(operationType) {
 }
 initializeConfig();
 
-// src/core/operations.ts
-async function commitReservationWithJournal(repository, userId, reservationId) {
+// src/repository/types.ts
+function supportsCreditsV2(repository) {
+  return typeof repository.reserveCreditsV2 === "function" && typeof repository.commitReservationV2 === "function" && typeof repository.releaseReservationV2 === "function" && typeof repository.expireReservationV2 === "function";
+}
+
+// src/repository/flow.ts
+async function reserveThroughRepository(repository, input) {
+  const v2 = supportsCreditsV2(repository);
+  if (!v2 && input.idempotencyKey !== void 0) {
+    throw createUnsupportedOperationError(
+      "reserveCredits with an idempotencyKey",
+      "This repository does not implement the V2 boundary, so it cannot enforce idempotency keys. Use a V2 repository (check with supportsCreditsV2) or omit the key and accept at-least-once holds."
+    );
+  }
+  assertValidCreditAmount(input.amount, { userId: input.userId });
+  if (v2) {
+    return repository.reserveCreditsV2(input);
+  }
+  try {
+    const reservation = await repository.reserveCreditsAtomic(
+      input.userId,
+      input.amount,
+      input.operationType,
+      input.expiresAt
+    );
+    return { outcome: "created", reservation };
+  } catch (error) {
+    if (!isInsufficientCreditsError(error)) throw error;
+    const credits = await repository.getUserCredits(input.userId);
+    const available = credits ? sumAmounts(credits.balance, credits.bonusCredits, -credits.reserved) : 0;
+    return {
+      outcome: "insufficient",
+      available,
+      required: input.amount,
+      shortfall: Math.max(sumAmounts(input.amount, -available), 0)
+    };
+  }
+}
+async function commitThroughRepository(repository, userId, reservationId, options) {
+  if (supportsCreditsV2(repository)) {
+    return repository.commitReservationV2(userId, reservationId, options);
+  }
   const reservation = await repository.getReservation(userId, reservationId);
-  if (!reservation) {
-    throw new Error(`Reservation ${reservationId} not found`);
+  if (!reservation) return { outcome: "not_found", reservationId };
+  if (reservation.status !== "reserved") {
+    return {
+      outcome: "already_terminal",
+      reservation,
+      terminalStatus: reservation.status
+    };
   }
   await repository.commitReservationAtomic(userId, reservationId);
   const credits = await repository.getUserCredits(userId);
-  if (credits) {
-    await repository.createJournalEntry({
-      userId,
-      entryType: "debit",
-      amount: reservation.amount,
-      balanceAfter: credits.balance,
-      source: "operation_commit",
-      referenceId: reservationId,
-      referenceType: "reservation",
-      description: `Committed ${reservation.amount} credits for ${getOperationLabel(reservation.operationType)}`,
-      metadata: {
-        operationType: reservation.operationType
-      }
-    });
-  }
+  const balanceAfter = credits ? sumAmounts(credits.balance, credits.bonusCredits) : 0;
+  const entry = await repository.createJournalEntry({
+    userId,
+    entryType: "debit",
+    amount: reservation.amount,
+    balanceAfter,
+    source: "operation_commit",
+    referenceId: reservationId,
+    referenceType: "reservation",
+    description: options?.description ?? `Committed ${reservation.amount} credits for ${getOperationLabel(reservation.operationType)}`,
+    // Deterministic fields last: they carry the identity of the event, and a
+    // caller who happens to send an `operationType` or an `amount` must not
+    // relabel what actually moved.
+    metadata: {
+      ...options?.metadata,
+      operationType: reservation.operationType,
+      amount: reservation.amount
+    }
+  });
+  return {
+    outcome: "committed",
+    reservation: { ...reservation, status: "committed" },
+    amount: reservation.amount,
+    balanceAfter,
+    journalEntryId: entry.id
+  };
 }
-async function releaseReservationWithJournal(repository, userId, reservationId) {
+async function releaseThroughRepository(repository, userId, reservationId, options) {
+  if (supportsCreditsV2(repository)) {
+    return repository.releaseReservationV2(userId, reservationId, options);
+  }
   const reservation = await repository.getReservation(userId, reservationId);
+  if (!reservation) {
+    await repository.releaseReservationAtomic(userId, reservationId);
+    return { outcome: "not_found", reservationId };
+  }
+  if (reservation.status !== "reserved") {
+    await repository.releaseReservationAtomic(userId, reservationId).catch(() => void 0);
+    return {
+      outcome: "already_terminal",
+      reservation,
+      terminalStatus: reservation.status
+    };
+  }
   await repository.releaseReservationAtomic(userId, reservationId);
-  if (reservation?.status === "reserved") {
-    const credits = await repository.getUserCredits(userId);
-    if (credits) {
-      await repository.createJournalEntry({
-        userId,
-        entryType: "credit",
-        amount: 0,
-        // No actual credits returned (they were reserved, not spent)
-        balanceAfter: credits.balance,
-        source: "operation_release",
-        referenceId: reservationId,
-        referenceType: "reservation",
-        description: `Released ${reservation.amount} reserved credits for ${getOperationLabel(reservation.operationType)}`,
-        metadata: {
-          operationType: reservation.operationType,
-          amount: reservation.amount
-        }
-      });
+  const credits = await repository.getUserCredits(userId);
+  const entry = await repository.createJournalEntry({
+    userId,
+    entryType: "credit",
+    // No credits changed hands — the hold just moved back into "available".
+    amount: 0,
+    balanceAfter: credits ? sumAmounts(credits.balance, credits.bonusCredits) : 0,
+    source: "operation_release",
+    referenceId: reservationId,
+    referenceType: "reservation",
+    description: options?.description ?? `Released ${reservation.amount} reserved credits for ${getOperationLabel(reservation.operationType)}`,
+    metadata: {
+      ...options?.metadata,
+      operationType: reservation.operationType,
+      amount: reservation.amount
     }
+  });
+  return {
+    outcome: "released",
+    reservation: { ...reservation, status: "released" },
+    amount: reservation.amount,
+    journalEntryId: entry.id
+  };
+}
+
+// src/core/operations.ts
+async function commitReservationWithJournal(repository, userId, reservationId) {
+  const outcome = await commitThroughRepository(repository, userId, reservationId);
+  if (outcome.outcome === "not_found") {
+    throw createReservationNotFoundError(reservationId);
   }
+  if (outcome.outcome === "already_terminal" && outcome.terminalStatus !== "committed") {
+    throw createReservationAlreadyProcessedError(reservationId, outcome.terminalStatus);
+  }
+}
+async function releaseReservationWithJournal(repository, userId, reservationId) {
+  await releaseThroughRepository(repository, userId, reservationId);
 }
-async function reserveCreditsForOperation(repository, userId, amount, operationType, expiryMs = 5 * 60 * 1e3) {
+async function reserveCreditsForOperation(repository, userId, amount, operationType, expiryMs = 5 * 60 * 1e3, idempotencyKey) {
   const expiresAt = new Date(Date.now() + expiryMs);
-  return repository.reserveCreditsAtomic(userId, amount, operationType, expiresAt);
+  const outcome = await reserveThroughRepository(repository, {
+    userId,
+    amount,
+    operationType,
+    expiresAt,
+    idempotencyKey
+  });
+  if (outcome.outcome === "created" || outcome.outcome === "replayed") {
+    return outcome.reservation;
+  }
+  if (outcome.outcome === "insufficient") {
+    throw createInsufficientCreditsError(outcome.required, outcome.available);
+  }
+  throw createReservationAlreadyProcessedError(
+    outcome.existing.id,
+    outcome.existing.status
+  );
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CREDIT_AMOUNT_MAX,
+  CREDIT_AMOUNT_SCALE,
   CreditError,
   CreditErrorCode,
+  RESERVATION_STATUSES,
+  RESERVED_JOURNAL_KEY_PREFIX,
+  TERMINAL_RESERVATION_STATUSES,
+  assertDirectStatusWriteAllowed,
+  assertHoldPlaced,
+  assertKnownReservationStatus,
+  assertPublicJournalKey,
+  assertRepresentableAmount,
+  assertRepresentableFields,
+  assertRepresentableTierAmount,
+  assertUnkeyedDirectReservation,
+  assertUnreferencedDirectTransaction,
+  assertValidCreditAmount,
+  assertValidIdempotencyKey,
+  assertValidStoredAmount,
+  assertValidStoredAmountRaw,
+  backedBalanceFloor,
   calculateAvailableCredits,
+  classifyDatabaseError,
   commitReservationWithJournal,
   createDeferredExecutor,
+  createIdempotencyConflictError,
   createInsufficientCreditsError,
+  createInvalidAmountError,
   createInvalidOperationTypeError,
+  createPaymentRefConflictError,
   createReservationAlreadyProcessedError,
   createReservationExpiredError,
   createReservationNotFoundError,
+  createTransientError,
+  createUnsupportedOperationError,
   createUserNotFoundError,
+  describePaymentMismatch,
   genericDeferred,
+  getSqlState,
+  hasPlacedHold,
   isCreditError,
+  isCreditedOutcome,
+  isIdempotencyConflictError,
   isInsufficientCreditsError,
+  isRepresentableAmount,
+  isReservationStatus,
+  isReservedJournalKey,
+  isReservedOutcome,
+  isTerminalReservationStatus,
+  isTransientDatabaseError,
+  isTransientError,
+  isUniqueViolation,
+  isValidCreditAmount,
+  isValidIdempotencyKey,
+  isWinningOutcome,
   noopDeferred,
+  normalizePaymentRef,
+  numericToCents,
   releaseReservationWithJournal,
   reserveCreditsForOperation,
+  sameAmount,
+  storedMonthlyLimit,
+  sumAmounts,
   synchronousDeferred,
+  terminalStatusOf,
+  toCents,
   toDate,
   toPortableTimestamp
 });