@nehorai/credits 1.7.0 → 2.1.0

package/dist/index.cjs

@@ -24,6 +24,8 @@ __export(src_exports, {
   ApiKeyCreditsProvider: () => ApiKeyCreditsProvider,
   AuthenticationError: () => AuthenticationError,
   AuthorizationError: () => AuthorizationError,
+  CREDIT_AMOUNT_MAX: () => CREDIT_AMOUNT_MAX,
+  CREDIT_AMOUNT_SCALE: () => CREDIT_AMOUNT_SCALE,
   ConsoleNotificationHandler: () => ConsoleNotificationHandler,
   CreditError: () => CreditError,
   CreditErrorCode: () => CreditErrorCode,
@@ -32,31 +34,57 @@ __export(src_exports, {
   CreditsService: () => CreditsService,
   InMemoryCreditRepository: () => InMemoryCreditRepository,
   NetworkError: () => NetworkError,
+  RESERVATION_STATUSES: () => RESERVATION_STATUSES,
+  RESERVED_JOURNAL_KEY_PREFIX: () => RESERVED_JOURNAL_KEY_PREFIX,
   SDKErrorCode: () => SDKErrorCode,
   SDKInsufficientCreditsError: () => InsufficientCreditsError,
   SDKReservationExpiredError: () => ReservationExpiredError,
   SDKReservationNotFoundError: () => ReservationNotFoundError,
   ServerError: () => ServerError,
+  TERMINAL_RESERVATION_STATUSES: () => TERMINAL_RESERVATION_STATUSES,
   UNLIMITED_BALANCE_SENTINEL: () => UNLIMITED_BALANCE_SENTINEL,
   ValidationError: () => ValidationError,
+  addCreditsThroughRepository: () => addCreditsThroughRepository,
+  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,
   checkAndNotifyLowBalance: () => checkAndNotifyLowBalance,
+  classifyDatabaseError: () => classifyDatabaseError,
   clearConfigProvider: () => clearConfigProvider,
   clearCooldownState: () => clearCooldownState,
   clearNotificationHandlers: () => clearNotificationHandlers,
   commitReservationWithJournal: () => commitReservationWithJournal,
+  commitThroughRepository: () => commitThroughRepository,
   createApiKeyProvider: () => createApiKeyProvider,
   createCreditsService: () => createCreditsService,
   createDeferredExecutor: () => createDeferredExecutor,
   createDummyReservation: () => createDummyReservation2,
   createGenericAdapter: () => createGenericAdapter,
+  createIdempotencyConflictError: () => createIdempotencyConflictError,
   createInMemoryCreditRepository: () => createInMemoryCreditRepository,
   createInsufficientCreditsError: () => createInsufficientCreditsError,
+  createInvalidAmountError: () => createInvalidAmountError,
   createInvalidOperationTypeError: () => createInvalidOperationTypeError,
+  createPaymentRefConflictError: () => createPaymentRefConflictError,
   createReservationAlreadyProcessedError: () => createReservationAlreadyProcessedError,
   createReservationExpiredError: () => createReservationExpiredError,
   createReservationNotFoundError: () => createReservationNotFoundError,
+  createTransientError: () => createTransientError,
+  createUnsupportedOperationError: () => createUnsupportedOperationError,
   createUserNotFoundError: () => createUserNotFoundError,
+  describePaymentMismatch: () => describePaymentMismatch,
   generateId: () => generateId,
   generateRequestId: () => generateRequestId2,
   genericDeferred: () => genericDeferred,
@@ -75,35 +103,63 @@ __export(src_exports, {
   getOperationLabel: () => getOperationLabel,
   getOperationLabels: () => getOperationLabels,
   getReservationExpiryMs: () => getReservationExpiryMs,
+  getSqlState: () => getSqlState,
   getTierConfig: () => getTierConfig,
   getTotalCredits: () => getTotalCredits,
   getUnlimitedSentinelBalance: () => getUnlimitedSentinelBalance,
   getValidOperationTypes: () => getValidOperationTypes,
   getValidTiers: () => getValidTiers,
+  hasPlacedHold: () => hasPlacedHold,
   initializeConfig: () => initializeConfig,
   isCreditError: () => isCreditError,
   isCreditErrorMessage: () => isCreditErrorMessage,
+  isCreditedOutcome: () => isCreditedOutcome,
   isFeatureEnabled: () => isFeatureEnabled,
   isFreeTier: () => isFreeTier,
+  isIdempotencyConflictError: () => isIdempotencyConflictError,
   isInsufficientCreditsError: () => isInsufficientCreditsError,
   isPreviewMode: () => isPreviewMode2,
+  isRepresentableAmount: () => isRepresentableAmount,
+  isReservationStatus: () => isReservationStatus,
+  isReservedJournalKey: () => isReservedJournalKey,
+  isReservedOutcome: () => isReservedOutcome,
+  isTerminalReservationStatus: () => isTerminalReservationStatus,
+  isTransientDatabaseError: () => isTransientDatabaseError,
+  isTransientError: () => isTransientError,
+  isUniqueViolation: () => isUniqueViolation,
   isUnlimitedTier: () => isUnlimitedTier,
+  isValidCreditAmount: () => isValidCreditAmount,
+  isValidIdempotencyKey: () => isValidIdempotencyKey,
   isValidOperationType: () => isValidOperationType,
   isValidTier: () => isValidTier,
+  isWinningOutcome: () => isWinningOutcome,
   loadConfigFromEnv: () => loadConfigFromEnv,
+  monthlyResetBalance: () => monthlyResetBalance,
   noopDeferred: () => noopDeferred,
+  normalizePaymentRef: () => normalizePaymentRef,
   notifySubscriptionExpired: () => notifySubscriptionExpired,
   notifySubscriptionExpiring: () => notifySubscriptionExpiring,
+  numericToCents: () => numericToCents,
   parseApiError: () => parseApiError,
   parseCreditError: () => parseCreditError,
   parseTier: () => parseTier,
   registerConfigProvider: () => registerConfigProvider,
   registerNotificationHandler: () => registerNotificationHandler,
   releaseReservationWithJournal: () => releaseReservationWithJournal,
+  releaseThroughRepository: () => releaseThroughRepository,
+  reservationJournalKey: () => reservationJournalKey,
   reserveCreditsForOperation: () => reserveCreditsForOperation,
+  reserveThroughRepository: () => reserveThroughRepository,
   resetConfig: () => resetConfig,
+  sameAmount: () => sameAmount,
+  storedMonthlyLimit: () => storedMonthlyLimit,
+  sumAmounts: () => sumAmounts,
+  supportsCreditsV2: () => supportsCreditsV2,
+  supportsIdempotentCredit: () => supportsIdempotentCredit,
   synchronousDeferred: () => synchronousDeferred,
+  terminalStatusOf: () => terminalStatusOf,
   tierSchema: () => tierSchema,
+  toCents: () => toCents,
   toClientUserCredits: () => toClientUserCredits,
   toDate: () => toDate,
   toPortableTimestamp: () => toPortableTimestamp,
@@ -112,38 +168,6 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_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",
@@ -153,7 +177,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;
@@ -195,7 +244,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) {
@@ -233,6 +282,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 = {
@@ -291,11 +769,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).
@@ -553,6 +1033,12 @@ var UNLIMITED_BALANCE_SENTINEL = 999999;
 function getUnlimitedSentinelBalance() {
   return UNLIMITED_BALANCE_SENTINEL;
 }
+function monthlyResetBalance(tier) {
+  if (isUnlimitedTier(tier)) {
+    return { kind: "atLeast", value: UNLIMITED_BALANCE_SENTINEL };
+  }
+  return { kind: "absolute", value: getConfigMonthlyLimit(tier) };
+}
 function getConfigTierConfig(tier) {
   const cfg = getConfig().tierConfigs[tier];
   if (cfg) return cfg;
@@ -595,57 +1081,203 @@ function resetConfig() {
 }
 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";
+}
+function supportsIdempotentCredit(repository) {
+  return typeof repository.addCreditsV2 === "function";
+}
+function toClientUserCredits(credits) {
+  return {
+    userId: credits.userId,
+    balance: credits.balance,
+    bonusCredits: credits.bonusCredits ?? 0,
+    reserved: credits.reserved,
+    tier: credits.tier,
+    monthlyLimit: credits.monthlyLimit,
+    monthlyUsed: credits.monthlyUsed,
+    monthlyResetAt: toISOString(credits.monthlyResetAt),
+    subscriptionExpiresAt: credits.subscriptionExpiresAt ? toISOString(credits.subscriptionExpiresAt) : null,
+    createdAt: toISOString(credits.createdAt),
+    updatedAt: toISOString(credits.updatedAt)
+  };
+}
+function toISOString(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" && "toDate" in value && typeof value.toDate === "function") {
+    return value.toDate().toISOString();
+  }
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+
+// 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
+  };
+}
+async function addCreditsThroughRepository(repository, input) {
+  assertValidCreditAmount(input.amount, { userId: input.userId, operation: "addCredits" });
+  const paymentRef = normalizePaymentRef(input.paymentRef);
+  if (supportsIdempotentCredit(repository)) {
+    return repository.addCreditsV2({ ...input, paymentRef });
+  }
+  await repository.addCreditsAtomic(
+    input.userId,
+    input.amount,
+    input.description,
+    paymentRef,
+    input.options
+  );
+  return paymentRef ? { outcome: "created", paymentRef } : { outcome: "created" };
+}
+
+// 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
+  );
 }
 
 // src/config/costs.ts
@@ -680,64 +1312,493 @@ function getOperationCostsWithLabels() {
   return result;
 }
 
-// src/repository/types.ts
-function toClientUserCredits(credits) {
-  return {
-    userId: credits.userId,
-    balance: credits.balance,
-    bonusCredits: credits.bonusCredits ?? 0,
-    reserved: credits.reserved,
-    tier: credits.tier,
-    monthlyLimit: credits.monthlyLimit,
-    monthlyUsed: credits.monthlyUsed,
-    monthlyResetAt: toISOString(credits.monthlyResetAt),
-    subscriptionExpiresAt: credits.subscriptionExpiresAt ? toISOString(credits.subscriptionExpiresAt) : null,
-    createdAt: toISOString(credits.createdAt),
-    updatedAt: toISOString(credits.updatedAt)
+// src/repository/v2-types.ts
+function reservationJournalKey(reservationId, transition) {
+  return `${RESERVED_JOURNAL_KEY_PREFIX}${reservationId}:${transition}`;
+}
+
+// src/repository/utils.ts
+function generateId() {
+  return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+}
+function toDate2(value) {
+  if (value instanceof Date) return value;
+  if (typeof value === "string") return new Date(value);
+  if (typeof value === "object" && value !== null && "toDate" in value) {
+    return value.toDate();
+  }
+  return /* @__PURE__ */ new Date();
+}
+function getNextMonthlyReset(from = /* @__PURE__ */ new Date()) {
+  const next = new Date(from);
+  next.setMonth(next.getMonth() + 1);
+  next.setDate(1);
+  next.setHours(0, 0, 0, 0);
+  return next;
+}
+
+// src/repository/memory/snapshot.ts
+function copyRecord(record) {
+  if (!record) return void 0;
+  const copy = { ...record };
+  const metadata = record.metadata;
+  if (metadata && typeof metadata === "object") {
+    copy.metadata = { ...metadata };
+  }
+  return copy;
+}
+function copyRecords(records) {
+  return records.map((record) => copyRecord(record));
+}
+
+// src/repository/memory/mutex.ts
+var KeyedMutex = class {
+  tails = /* @__PURE__ */ new Map();
+  /**
+   * Run `fn` with exclusive access to `key`.
+   *
+   * Callers queue in arrival order. The stored tail settles either way, so one
+   * caller throwing does not wedge the queue behind it.
+   */
+  async run(key, fn) {
+    const previous = this.tails.get(key) ?? Promise.resolve();
+    const result = previous.then(fn, fn);
+    const tail = result.then(
+      () => void 0,
+      () => void 0
+    );
+    this.tails.set(key, tail);
+    try {
+      return await result;
+    } finally {
+      if (this.tails.get(key) === tail) {
+        this.tails.delete(key);
+      }
+    }
+  }
+};
+
+// src/repository/memory/store.ts
+var MemoryStore = class {
+  users = /* @__PURE__ */ new Map();
+  reservations = /* @__PURE__ */ new Map();
+  transactions = /* @__PURE__ */ new Map();
+  usageLogs = [];
+  journalEntries = /* @__PURE__ */ new Map();
+  /** Stands in for the reservations table's partial unique index. */
+  reservationKeys = /* @__PURE__ */ new Map();
+  /** Stands in for the journal table's partial unique index. */
+  journalKeys = /* @__PURE__ */ new Map();
+  /** Stands in for the database's per-user row locks. */
+  locks = new KeyedMutex();
+  /**
+   * Test-only yield point, awaited between reading state and mutating it.
+   *
+   * Unset in production, so the critical sections stay synchronous and this
+   * costs nothing. Tests set it to a real macrotask yield, which forces
+   * concurrent callers to interleave at exactly the spot a database would have
+   * them contend — turning the lock above from decoration into the thing the
+   * concurrency tests actually depend on.
+   */
+  schedulingHook;
+  clear() {
+    this.users.clear();
+    this.reservations.clear();
+    this.transactions.clear();
+    this.usageLogs = [];
+    this.journalEntries.clear();
+    this.reservationKeys.clear();
+    this.journalKeys.clear();
+  }
+};
+function scopedKey(userId, key) {
+  return `${userId}
+${key}`;
+}
+
+// src/repository/memory/transition-journal.ts
+function describeJournalMismatch(row, input) {
+  if (row.userId !== input.userId) return "user_id";
+  if (row.entryType !== input.entryType) return "entry_type";
+  if (!sameAmount(row.amount, input.amount)) return "amount";
+  if (!sameAmount(row.balanceAfter, input.balanceAfter)) return "balance_after";
+  if (row.source !== input.source) return "source";
+  if (row.referenceId !== input.reservationId) return "reference_id";
+  if (row.referenceType !== "reservation") return "reference_type";
+  const existingMeta = row.metadata ?? {};
+  const expectedMeta = input.metadata ?? {};
+  if (existingMeta.operationType !== expectedMeta.operationType) {
+    return "metadata.operationType";
+  }
+  const hadAmount = existingMeta.amount !== void 0;
+  const wantsAmount = expectedMeta.amount !== void 0;
+  if (hadAmount !== wantsAmount) return "metadata.amount";
+  if (wantsAmount && !sameAmount(existingMeta.amount, expectedMeta.amount)) {
+    return "metadata.amount";
+  }
+  return null;
+}
+function findEntry(store, userId, entryId) {
+  return store.journalEntries.get(userId)?.find((entry) => entry.id === entryId);
+}
+function planTransitionJournal(store, input) {
+  assertRepresentableFields(
+    { amount: input.amount, "journal balanceAfter": input.balanceAfter },
+    { userId: input.userId, reservationId: input.reservationId, operation: input.operation }
+  );
+  const existingId = store.journalKeys.get(scopedKey(input.userId, input.idempotencyKey));
+  if (!existingId) return void 0;
+  const row = findEntry(store, input.userId, existingId);
+  const mismatch = row ? describeJournalMismatch(row, input) : "the key is registered but its entry is missing";
+  if (mismatch) {
+    throw new CreditError(
+      `Journal key ${input.idempotencyKey} is already used by a different entry (${mismatch}). The transition was refused rather than reported as applied.`,
+      CreditErrorCode.DATABASE_ERROR,
+      {
+        idempotencyKey: input.idempotencyKey,
+        reservationId: input.reservationId,
+        mismatch
+      }
+    );
+  }
+  return existingId;
+}
+function commitTransitionJournal(store, input, existingId) {
+  if (existingId) return existingId;
+  const entry = {
+    id: generateId(),
+    userId: input.userId,
+    entryType: input.entryType,
+    amount: input.amount,
+    balanceAfter: input.balanceAfter,
+    source: input.source,
+    referenceId: input.reservationId,
+    referenceType: "reservation",
+    description: input.description,
+    metadata: input.metadata,
+    idempotencyKey: input.idempotencyKey,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
   };
+  if (!store.journalEntries.has(input.userId)) {
+    store.journalEntries.set(input.userId, []);
+  }
+  store.journalEntries.get(input.userId).push(entry);
+  store.journalKeys.set(scopedKey(input.userId, input.idempotencyKey), entry.id);
+  return entry.id;
+}
+
+// src/repository/memory/v2.ts
+async function yieldPoint(store) {
+  if (store.schedulingHook) await store.schedulingHook();
+}
+function assertReservedCoversHold(credits, userId, reservationId, amount) {
+  if (credits.reserved >= amount) return;
+  throw new CreditError(
+    `Credit balance invariant violated for user ${userId} while processing reservation ${reservationId}: reserved (${credits.reserved}) is less than the hold (${amount}). The transition was rolled back.`,
+    CreditErrorCode.DATABASE_ERROR,
+    { userId, reservationId, amount, reserved: credits.reserved }
+  );
+}
+function assertLockedAmount(reservation, transition) {
+  assertValidStoredAmount(reservation.amount, {
+    userId: reservation.userId,
+    reservationId: reservation.id,
+    transition
+  });
+}
+function terminalStatusOf2(reservation, transition) {
+  return terminalStatusOf(reservation, transition);
+}
+function assertTrustworthy(reservation, transition) {
+  assertKnownReservationStatus(reservation, transition);
+  assertLockedAmount(reservation, transition);
+  assertHoldPlaced(reservation, transition);
+}
+function getReservation(store, userId, reservationId) {
+  return store.reservations.get(userId)?.get(reservationId);
+}
+function requireUser(store, userId) {
+  const credits = store.users.get(userId);
+  if (!credits) {
+    throw new CreditError(
+      `User credits not found for user ${userId}`,
+      CreditErrorCode.USER_NOT_FOUND,
+      { userId }
+    );
+  }
+  return credits;
+}
+async function reserveCreditsV2(store, input) {
+  assertValidCreditAmount(input.amount, { userId: input.userId });
+  assertValidIdempotencyKey(input.idempotencyKey, { userId: input.userId });
+  return store.locks.run(input.userId, async () => {
+    if (input.idempotencyKey) {
+      const existingId = store.reservationKeys.get(
+        scopedKey(input.userId, input.idempotencyKey)
+      );
+      if (existingId) {
+        const existing = getReservation(store, input.userId, existingId);
+        if (existing) {
+          assertHoldPlaced(existing, "reserve replay");
+          const samePayload = existing.amount === input.amount && existing.operationType === input.operationType;
+          return samePayload ? { outcome: "replayed", reservation: copyRecord(existing) } : {
+            outcome: "idempotency_conflict",
+            idempotencyKey: input.idempotencyKey,
+            existing: copyRecord(existing)
+          };
+        }
+      }
+    }
+    const credits = requireUser(store, input.userId);
+    const available = sumAmounts(credits.balance, credits.bonusCredits, -credits.reserved);
+    await yieldPoint(store);
+    if (available < input.amount) {
+      return {
+        outcome: "insufficient",
+        available,
+        required: input.amount,
+        shortfall: sumAmounts(input.amount, -available)
+      };
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const reservation = {
+      id: generateId(),
+      userId: input.userId,
+      amount: input.amount,
+      operationType: input.operationType,
+      status: "reserved",
+      createdAt: now,
+      expiresAt: input.expiresAt.toISOString(),
+      idempotencyKey: input.idempotencyKey,
+      // The hold-origin fact. Written here and nowhere else, in the same
+      // critical section that raises `reserved` below, so the row and the hold
+      // become visible together. `createReservation` cannot set it.
+      holdPlacedAt: now
+    };
+    if (!store.reservations.has(input.userId)) {
+      store.reservations.set(input.userId, /* @__PURE__ */ new Map());
+    }
+    const nextReserved = sumAmounts(credits.reserved, input.amount);
+    assertRepresentableFields(
+      { reserved: nextReserved },
+      { userId: input.userId, operation: "reserveCredits" }
+    );
+    store.reservations.get(input.userId).set(reservation.id, reservation);
+    if (input.idempotencyKey) {
+      store.reservationKeys.set(
+        scopedKey(input.userId, input.idempotencyKey),
+        reservation.id
+      );
+    }
+    credits.reserved = nextReserved;
+    credits.updatedAt = now;
+    return { outcome: "created", reservation: copyRecord(reservation) };
+  });
 }
-function toISOString(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" && "toDate" in value && typeof value.toDate === "function") {
-    return value.toDate().toISOString();
-  }
-  return (/* @__PURE__ */ new Date()).toISOString();
+async function commitReservationV2(store, userId, reservationId, options) {
+  return store.locks.run(userId, async () => {
+    const reservation = getReservation(store, userId, reservationId);
+    if (!reservation) return { outcome: "not_found", reservationId };
+    assertTrustworthy(reservation, "commit");
+    if (reservation.status !== "reserved") {
+      return {
+        outcome: "already_terminal",
+        reservation: copyRecord(reservation),
+        terminalStatus: terminalStatusOf2(reservation, "commit")
+      };
+    }
+    const credits = requireUser(store, userId);
+    const amount = reservation.amount;
+    await yieldPoint(store);
+    assertReservedCoversHold(credits, userId, reservationId, amount);
+    if (sumAmounts(credits.balance, credits.bonusCredits) < amount) {
+      throw new CreditError(
+        `Insufficient credits to commit reservation ${reservationId}`,
+        CreditErrorCode.INSUFFICIENT_CREDITS,
+        { userId, reservationId, required: amount }
+      );
+    }
+    const fromBalance = Math.min(credits.balance, amount);
+    const nextBalance = sumAmounts(credits.balance, -fromBalance);
+    const nextBonusCredits = sumAmounts(credits.bonusCredits, -sumAmounts(amount, -fromBalance));
+    const balanceAfter = sumAmounts(nextBalance, nextBonusCredits);
+    const journal = {
+      userId,
+      operation: "commitReservation",
+      entryType: "debit",
+      amount,
+      balanceAfter,
+      source: "operation_commit",
+      reservationId,
+      description: options?.description ?? `Committed ${amount} credits for ${getOperationLabel(reservation.operationType)}`,
+      // Caller metadata first: the deterministic fields carry the identity of
+      // the event that the collision check compares on.
+      metadata: { ...options?.metadata, operationType: reservation.operationType, amount },
+      idempotencyKey: reservationJournalKey(reservationId, "commit")
+    };
+    const nextReserved = sumAmounts(credits.reserved, -amount);
+    const nextMonthlyUsed = sumAmounts(credits.monthlyUsed, amount);
+    assertRepresentableFields(
+      {
+        balance: nextBalance,
+        bonusCredits: nextBonusCredits,
+        reserved: nextReserved,
+        monthlyUsed: nextMonthlyUsed
+      },
+      { userId, operation: "commitReservation" }
+    );
+    const existingEntryId = planTransitionJournal(store, journal);
+    reservation.status = "committed";
+    reservation.completedAt = (/* @__PURE__ */ new Date()).toISOString();
+    credits.balance = nextBalance;
+    credits.bonusCredits = nextBonusCredits;
+    credits.reserved = nextReserved;
+    credits.monthlyUsed = nextMonthlyUsed;
+    credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const journalEntryId = commitTransitionJournal(store, journal, existingEntryId);
+    return {
+      outcome: "committed",
+      reservation: copyRecord(reservation),
+      amount,
+      balanceAfter,
+      journalEntryId
+    };
+  });
 }
-
-// src/repository/utils.ts
-function generateId() {
-  return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+async function releaseReservationV2(store, userId, reservationId, options) {
+  return store.locks.run(userId, async () => {
+    const reservation = getReservation(store, userId, reservationId);
+    if (!reservation) return { outcome: "not_found", reservationId };
+    assertTrustworthy(reservation, "release");
+    if (reservation.status !== "reserved") {
+      return {
+        outcome: "already_terminal",
+        reservation: copyRecord(reservation),
+        terminalStatus: terminalStatusOf2(reservation, "release")
+      };
+    }
+    await yieldPoint(store);
+    const journalEntryId = finishUnspent(store, reservation, {
+      status: "released",
+      source: "operation_release",
+      transition: "release",
+      verb: "Released",
+      options
+    });
+    return {
+      outcome: "released",
+      reservation: copyRecord(reservation),
+      amount: reservation.amount,
+      journalEntryId
+    };
+  });
 }
-function toDate2(value) {
-  if (value instanceof Date) return value;
-  if (typeof value === "string") return new Date(value);
-  if (typeof value === "object" && value !== null && "toDate" in value) {
-    return value.toDate();
-  }
-  return /* @__PURE__ */ new Date();
+async function expireReservationV2(store, userId, reservationId, options) {
+  const asOf = options?.asOf ?? /* @__PURE__ */ new Date();
+  return store.locks.run(userId, async () => {
+    const reservation = getReservation(store, userId, reservationId);
+    if (!reservation) return { outcome: "not_found", reservationId };
+    assertTrustworthy(reservation, "expire");
+    if (reservation.status !== "reserved") {
+      return {
+        outcome: "already_terminal",
+        reservation: copyRecord(reservation),
+        terminalStatus: terminalStatusOf2(reservation, "expire")
+      };
+    }
+    if (new Date(reservation.expiresAt).getTime() > asOf.getTime()) {
+      return { outcome: "not_due", reservation: copyRecord(reservation) };
+    }
+    await yieldPoint(store);
+    const journalEntryId = finishUnspent(store, reservation, {
+      status: "expired",
+      source: "reservation_expired",
+      transition: "expire",
+      verb: "Expired",
+      options
+    });
+    return {
+      outcome: "expired",
+      reservation: copyRecord(reservation),
+      amount: reservation.amount,
+      journalEntryId
+    };
+  });
 }
-function getNextMonthlyReset(from = /* @__PURE__ */ new Date()) {
-  const next = new Date(from);
-  next.setMonth(next.getMonth() + 1);
-  next.setDate(1);
-  next.setHours(0, 0, 0, 0);
-  return next;
+function finishUnspent(store, reservation, transition) {
+  const credits = requireUser(store, reservation.userId);
+  assertReservedCoversHold(
+    credits,
+    reservation.userId,
+    reservation.id,
+    reservation.amount
+  );
+  const journal = {
+    userId: reservation.userId,
+    operation: `${transition.transition}Reservation`,
+    entryType: "credit",
+    amount: 0,
+    balanceAfter: sumAmounts(credits.balance, credits.bonusCredits),
+    source: transition.source,
+    reservationId: reservation.id,
+    description: transition.options?.description ?? `${transition.verb} ${reservation.amount} reserved credits for ${getOperationLabel(reservation.operationType)}`,
+    metadata: {
+      ...transition.options?.metadata,
+      operationType: reservation.operationType,
+      amount: reservation.amount
+    },
+    idempotencyKey: reservationJournalKey(reservation.id, transition.transition)
+  };
+  const nextReserved = sumAmounts(credits.reserved, -reservation.amount);
+  assertRepresentableFields(
+    { reserved: nextReserved },
+    { userId: reservation.userId, operation: `${transition.transition}Reservation` }
+  );
+  const existingEntryId = planTransitionJournal(store, journal);
+  reservation.status = transition.status;
+  reservation.completedAt = (/* @__PURE__ */ new Date()).toISOString();
+  credits.reserved = nextReserved;
+  credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  return commitTransitionJournal(store, journal, existingEntryId);
 }
 
 // src/repository/memory/index.ts
+function isoOf(value) {
+  return value instanceof Date ? value.toISOString() : value;
+}
 var InMemoryCreditRepository = class {
-  users = /* @__PURE__ */ new Map();
-  reservations = /* @__PURE__ */ new Map();
-  transactions = /* @__PURE__ */ new Map();
-  usageLogs = [];
-  journalEntries = /* @__PURE__ */ new Map();
+  store = new MemoryStore();
   // ==================== User Credits ====================
+  /**
+   * A copy, never the live record.
+   *
+   * Handing out the stored object made this adapter behave unlike any real
+   * one: a caller holding a "before" snapshot saw it mutate under them. The
+   * service's monthly reset compared `resetResult.credits.balance` against the
+   * balance it had read moments earlier, got zero because both were the same
+   * object, and silently skipped the reset's journal entry — while the SQL
+   * adapter, which maps each row into a fresh object, wrote it.
+   */
   async getUserCredits(userId) {
-    return this.users.get(userId) ?? null;
+    const credits = this.store.users.get(userId);
+    return copyRecord(credits) ?? null;
   }
   async initializeUserCredits(userId, tier, initialBalance) {
+    return copyRecord(this.seedUser(userId, tier, initialBalance));
+  }
+  /**
+   * The synchronous body of `initializeUserCredits`.
+   *
+   * Kept `await`-free on purpose: `addCreditsV2` seeds a missing user *inside*
+   * its critical section, and an `await` between the payment-reference check
+   * and the transaction write opens a gap another caller can run through — two
+   * simultaneous first deliveries of the same reference would then both credit.
+   */
+  seedUser(userId, tier, initialBalance) {
+    assertRepresentableAmount(initialBalance, "initialBalance", { userId });
+    const configured = getConfigMonthlyLimit(tier);
+    assertRepresentableTierAmount(configured, "monthlyLimit", { userId, tier });
+    const monthlyLimit = storedMonthlyLimit(configured);
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const credits = {
       userId,
@@ -745,61 +1806,93 @@ var InMemoryCreditRepository = class {
       bonusCredits: 0,
       reserved: 0,
       tier,
-      monthlyLimit: getConfigMonthlyLimit(tier),
+      monthlyLimit,
       monthlyUsed: 0,
       monthlyResetAt: getNextMonthlyReset().toISOString(),
       subscriptionExpiresAt: null,
       createdAt: now,
       updatedAt: now
     };
-    this.users.set(userId, credits);
+    this.store.users.set(userId, credits);
     return credits;
   }
   async updateUserCredits(userId, updates) {
-    const credits = this.users.get(userId);
+    assertRepresentableFields(
+      {
+        balance: updates.balance,
+        bonusCredits: updates.bonusCredits,
+        reserved: updates.reserved,
+        monthlyLimit: updates.monthlyLimit,
+        monthlyUsed: updates.monthlyUsed,
+        balanceIncrement: updates.balanceIncrement,
+        bonusCreditsIncrement: updates.bonusCreditsIncrement,
+        reservedIncrement: updates.reservedIncrement,
+        monthlyUsedIncrement: updates.monthlyUsedIncrement
+      },
+      { userId, operation: "updateUserCredits" }
+    );
+    const credits = this.store.users.get(userId);
     if (!credits) {
       throw new Error(`User ${userId} not found`);
     }
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    if (updates.balance !== void 0) credits.balance = updates.balance;
-    if (updates.bonusCredits !== void 0) credits.bonusCredits = updates.bonusCredits;
-    if (updates.reserved !== void 0) credits.reserved = updates.reserved;
-    if (updates.tier !== void 0) credits.tier = updates.tier;
-    if (updates.monthlyLimit !== void 0) credits.monthlyLimit = updates.monthlyLimit;
-    if (updates.monthlyUsed !== void 0) credits.monthlyUsed = updates.monthlyUsed;
+    const next = { ...credits };
+    if (updates.balance !== void 0) next.balance = updates.balance;
+    if (updates.bonusCredits !== void 0) next.bonusCredits = updates.bonusCredits;
+    if (updates.reserved !== void 0) next.reserved = updates.reserved;
+    if (updates.tier !== void 0) next.tier = updates.tier;
+    if (updates.monthlyLimit !== void 0) next.monthlyLimit = updates.monthlyLimit;
+    if (updates.monthlyUsed !== void 0) next.monthlyUsed = updates.monthlyUsed;
     if (updates.monthlyResetAt !== void 0) {
-      credits.monthlyResetAt = updates.monthlyResetAt instanceof Date ? updates.monthlyResetAt.toISOString() : updates.monthlyResetAt;
+      next.monthlyResetAt = isoOf(updates.monthlyResetAt);
     }
     if (updates.subscriptionExpiresAt !== void 0) {
-      if (updates.subscriptionExpiresAt === null) {
-        credits.subscriptionExpiresAt = null;
-      } else {
-        credits.subscriptionExpiresAt = updates.subscriptionExpiresAt instanceof Date ? updates.subscriptionExpiresAt.toISOString() : updates.subscriptionExpiresAt;
-      }
+      next.subscriptionExpiresAt = updates.subscriptionExpiresAt === null ? null : isoOf(updates.subscriptionExpiresAt);
     }
     if (updates.balanceIncrement !== void 0) {
-      credits.balance += updates.balanceIncrement;
+      next.balance = sumAmounts(next.balance, updates.balanceIncrement);
     }
     if (updates.bonusCreditsIncrement !== void 0) {
-      credits.bonusCredits += updates.bonusCreditsIncrement;
+      next.bonusCredits = sumAmounts(next.bonusCredits, updates.bonusCreditsIncrement);
     }
     if (updates.reservedIncrement !== void 0) {
-      credits.reserved += updates.reservedIncrement;
+      next.reserved = sumAmounts(next.reserved, updates.reservedIncrement);
     }
     if (updates.monthlyUsedIncrement !== void 0) {
-      credits.monthlyUsed += updates.monthlyUsedIncrement;
+      next.monthlyUsed = sumAmounts(next.monthlyUsed, updates.monthlyUsedIncrement);
     }
-    credits.updatedAt = now;
-    this.users.set(userId, credits);
+    assertRepresentableFields(
+      {
+        balance: next.balance,
+        bonusCredits: next.bonusCredits,
+        reserved: next.reserved,
+        monthlyUsed: next.monthlyUsed
+      },
+      { userId, operation: "updateUserCredits" }
+    );
+    assertRepresentableTierAmount(next.monthlyLimit, "monthlyLimit", {
+      userId,
+      operation: "updateUserCredits"
+    });
+    next.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.store.users.set(userId, next);
   }
   async updateUserTier(userId, input) {
-    const credits = this.users.get(userId);
+    assertRepresentableFields(
+      { monthlyLimit: input.monthlyLimit, balance: input.balance, monthlyUsed: input.monthlyUsed },
+      { userId, operation: "updateUserTier" }
+    );
+    const credits = this.store.users.get(userId);
     if (!credits) {
       throw new Error(`User ${userId} not found`);
     }
     credits.tier = input.tier;
     credits.monthlyLimit = input.monthlyLimit;
-    if (input.balance !== void 0) credits.balance = input.balance;
+    if (input.balance !== void 0) {
+      credits.balance = Math.max(
+        input.balance,
+        backedBalanceFloor(credits.reserved, credits.bonusCredits)
+      );
+    }
     if (input.monthlyUsed !== void 0) credits.monthlyUsed = input.monthlyUsed;
     if (input.subscriptionExpiresAt !== void 0) {
       if (input.subscriptionExpiresAt === null) {
@@ -809,10 +1902,12 @@ var InMemoryCreditRepository = class {
       }
     }
     credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    this.users.set(userId, credits);
+    this.store.users.set(userId, credits);
   }
   // ==================== Reservations ====================
   async createReservation(input) {
+    assertValidCreditAmount(input.amount, { userId: input.userId, operation: "createReservation" });
+    assertUnkeyedDirectReservation(input);
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const reservation = {
       id: generateId(),
@@ -823,19 +1918,19 @@ var InMemoryCreditRepository = class {
       createdAt: now,
       expiresAt: input.expiresAt.toISOString()
     };
-    if (!this.reservations.has(input.userId)) {
-      this.reservations.set(input.userId, /* @__PURE__ */ new Map());
+    if (!this.store.reservations.has(input.userId)) {
+      this.store.reservations.set(input.userId, /* @__PURE__ */ new Map());
     }
-    this.reservations.get(input.userId).set(reservation.id, reservation);
-    return reservation;
+    this.store.reservations.get(input.userId).set(reservation.id, reservation);
+    return copyRecord(reservation);
   }
   async getReservation(userId, reservationId) {
-    const userReservations = this.reservations.get(userId);
+    const userReservations = this.store.reservations.get(userId);
     if (!userReservations) return null;
-    return userReservations.get(reservationId) ?? null;
+    return copyRecord(userReservations.get(reservationId)) ?? null;
   }
   async updateReservationStatus(userId, reservationId, status, completedAt) {
-    const userReservations = this.reservations.get(userId);
+    const userReservations = this.store.reservations.get(userId);
     if (!userReservations) {
       throw new Error(`No reservations found for user ${userId}`);
     }
@@ -843,86 +1938,125 @@ var InMemoryCreditRepository = class {
     if (!reservation) {
       throw new Error(`Reservation ${reservationId} not found`);
     }
+    assertDirectStatusWriteAllowed(reservation, status);
     reservation.status = status;
     if (completedAt) reservation.completedAt = completedAt.toISOString();
     userReservations.set(reservationId, reservation);
   }
   // ==================== Atomic Operations ====================
+  // ==================== V2 boundary ====================
+  //
+  // As in the Drizzle adapter, V2 is the real implementation and the legacy
+  // `*Atomic` methods are adapters over it, so both APIs share one set of
+  // guarantees.
+  async reserveCreditsV2(input) {
+    return reserveCreditsV2(this.store, input);
+  }
+  async commitReservationV2(userId, reservationId, options) {
+    return commitReservationV2(this.store, userId, reservationId, options);
+  }
+  async releaseReservationV2(userId, reservationId, options) {
+    return releaseReservationV2(this.store, userId, reservationId, options);
+  }
+  async expireReservationV2(userId, reservationId, options) {
+    return expireReservationV2(this.store, userId, reservationId, options);
+  }
+  // ==================== Legacy atomic operations ====================
   async reserveCreditsAtomic(userId, amount, operationType, expiresAt) {
-    const credits = this.users.get(userId);
-    if (!credits) {
-      throw new Error(`User ${userId} not found`);
+    const outcome = await this.reserveCreditsV2({ userId, amount, operationType, expiresAt });
+    if (outcome.outcome === "created" || outcome.outcome === "replayed") {
+      return outcome.reservation;
     }
-    const available = credits.balance + credits.bonusCredits - credits.reserved;
-    if (available < amount) {
-      throw new Error(
-        `Insufficient credits. Available: ${available}, Required: ${amount}`
-      );
+    if (outcome.outcome === "insufficient") {
+      throw createInsufficientCreditsError(outcome.required, outcome.available);
     }
-    const reservation = await this.createReservation({
-      userId,
-      amount,
-      operationType,
-      expiresAt
-    });
-    credits.reserved += amount;
-    credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    this.users.set(userId, credits);
-    return reservation;
+    throw createReservationAlreadyProcessedError(outcome.existing.id, outcome.existing.status);
   }
   async commitReservationAtomic(userId, reservationId) {
-    const credits = this.users.get(userId);
-    if (!credits) {
-      throw new Error(`User ${userId} not found`);
-    }
-    const reservation = await this.getReservation(userId, reservationId);
-    if (!reservation) {
-      throw new Error(`Reservation ${reservationId} not found`);
-    }
-    if (reservation.status === "committed") {
-      return;
-    }
-    if (reservation.status !== "reserved") {
-      throw new Error(
-        `Cannot commit reservation in ${reservation.status} state`
-      );
-    }
-    const amount = reservation.amount;
-    credits.balance -= amount;
-    credits.reserved -= amount;
-    credits.monthlyUsed += amount;
-    credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    this.users.set(userId, credits);
-    await this.updateReservationStatus(userId, reservationId, "committed", /* @__PURE__ */ new Date());
+    const outcome = await this.commitReservationV2(userId, reservationId);
+    if (outcome.outcome === "committed") return;
+    if (outcome.outcome === "not_found") throw createReservationNotFoundError(reservationId);
+    if (outcome.terminalStatus === "committed") return;
+    throw createReservationAlreadyProcessedError(reservationId, outcome.terminalStatus);
   }
   async releaseReservationAtomic(userId, reservationId) {
-    const credits = this.users.get(userId);
-    if (!credits) {
-      throw new Error(`User ${userId} not found`);
-    }
-    const reservation = await this.getReservation(userId, reservationId);
-    if (!reservation) {
-      throw new Error(`Reservation ${reservationId} not found`);
-    }
-    if (reservation.status !== "reserved") {
-      return;
+    const outcome = await this.releaseReservationV2(userId, reservationId);
+    if (outcome.outcome === "not_found") throw createReservationNotFoundError(reservationId);
+  }
+  /**
+   * The stored transaction carrying this reference, in *any* user's ledger.
+   *
+   * Deliberately not scoped to one user. The SQL adapter's unique index covers
+   * `payment_ref` alone, so searching only the crediting user's own history made
+   * the same reference credit two different accounts here while the SQL adapter
+   * treated the second delivery as a duplicate. See `core/payment-ref.ts`.
+   */
+  findByPaymentRef(paymentRef) {
+    for (const recorded of this.store.transactions.values()) {
+      const hit = recorded.find((transaction) => transaction.paymentRef === paymentRef);
+      if (hit) return hit;
     }
-    credits.reserved -= reservation.amount;
-    credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    this.users.set(userId, credits);
-    await this.updateReservationStatus(userId, reservationId, "released", /* @__PURE__ */ new Date());
+    return void 0;
   }
-  async addCreditsAtomic(userId, amount, description, paymentRef, options) {
-    const credits = this.users.get(userId);
-    if (!credits) {
-      throw new Error(`User ${userId} not found`);
+  /** The journal entry written alongside a stored purchase, if there is one. */
+  journalForTransaction(transaction) {
+    return this.store.journalEntries.get(transaction.userId)?.find((entry) => entry.referenceId === transaction.id);
+  }
+  /**
+   * Credit an account, resolving `paymentRef` to created / replayed / conflict.
+   *
+   * The reference is checked and the transaction is recorded with no `await`
+   * between them. `createTransaction` is `async` but its body is synchronous, so
+   * under JavaScript's run-to-completion semantics no other caller can observe
+   * the gap — which is what stands in for the SQL adapter's unique index.
+   *
+   * A `replayed` or `conflict` outcome writes nothing at all: the check runs
+   * before the balance moves, not after.
+   */
+  async addCreditsV2(input) {
+    const { userId, amount, description, options } = input;
+    assertValidCreditAmount(amount, { userId, operation: "addCredits" });
+    const paymentRef = normalizePaymentRef(input.paymentRef);
+    const payload = {
+      userId,
+      amount,
+      type: "purchase",
+      source: options?.source ?? "purchase",
+      referenceType: options?.referenceType ?? "transaction"
+    };
+    if (paymentRef) {
+      const existing = this.findByPaymentRef(paymentRef);
+      if (existing) {
+        const journal = this.journalForTransaction(existing);
+        const mismatch = describePaymentMismatch(
+          {
+            userId: existing.userId,
+            amount: existing.amount,
+            type: existing.type,
+            source: journal?.source,
+            referenceType: journal?.referenceType
+          },
+          payload
+        );
+        return mismatch === null ? { outcome: "replayed", paymentRef, transaction: copyRecord(existing) } : { outcome: "conflict", paymentRef, existing: copyRecord(existing), mismatch };
+      }
     }
-    const previousTotal = credits.balance + credits.bonusCredits;
-    credits.bonusCredits += amount;
+    if (!this.store.users.has(userId)) {
+      const tier = getDefaultTier();
+      this.seedUser(userId, tier, storedMonthlyLimit(getConfigMonthlyLimit(tier)));
+    }
+    const credits = this.store.users.get(userId);
+    const previousTotal = sumAmounts(credits.balance, credits.bonusCredits);
+    const nextBonusCredits = sumAmounts(credits.bonusCredits, amount);
+    const newTotal = sumAmounts(credits.balance, nextBonusCredits);
+    assertRepresentableFields(
+      { previousBalance: previousTotal, bonusCredits: nextBonusCredits, newBalance: newTotal },
+      { userId, operation: "addCredits" }
+    );
+    credits.bonusCredits = nextBonusCredits;
     credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    this.users.set(userId, credits);
-    const newTotal = credits.balance + credits.bonusCredits;
-    const transaction = await this.createTransaction({
+    this.store.users.set(userId, credits);
+    const transaction = this.recordTransaction({
       userId,
       type: "purchase",
       amount,
@@ -935,43 +2069,88 @@ var InMemoryCreditRepository = class {
       ...paymentRef ? { paymentRef } : {},
       ...options?.metadata ?? {}
     };
-    await this.createJournalEntry({
+    const entry = await this.createJournalEntry({
       userId,
       entryType: "credit",
       amount,
       balanceAfter: newTotal,
-      source: options?.source ?? "purchase",
+      source: payload.source,
       referenceId: transaction.id ?? paymentRef ?? "unknown",
-      referenceType: options?.referenceType ?? "transaction",
+      referenceType: payload.referenceType,
       description,
       metadata: Object.keys(journalMetadata).length > 0 ? journalMetadata : void 0
     });
+    return paymentRef ? { outcome: "created", paymentRef, transaction, journalEntryId: entry.id } : { outcome: "created", transaction, journalEntryId: entry.id };
   }
-  async deductCreditsAtomic(userId, amount) {
-    if (amount <= 0) {
-      throw new Error(`deductCreditsAtomic amount must be positive (got ${amount})`);
+  /**
+   * The legacy signature, on top of {@link addCreditsV2}.
+   *
+   * `Promise<void>` has nowhere to report a conflict, and silently returning is
+   * indistinguishable from "credited" — the exact failure this round is closing
+   * — so a conflict throws. A genuine replay still returns quietly, because
+   * that *is* the idempotent no-op the caller asked for.
+   */
+  async addCreditsAtomic(userId, amount, description, paymentRef, options) {
+    const outcome = await this.addCreditsV2({
+      userId,
+      amount,
+      description,
+      paymentRef,
+      options
+    });
+    if (outcome.outcome === "conflict") {
+      throw createPaymentRefConflictError(outcome.paymentRef, {
+        userId,
+        mismatch: outcome.mismatch,
+        existingUserId: outcome.existing.userId
+      });
     }
-    const credits = this.users.get(userId);
+  }
+  async deductCreditsAtomic(userId, amount) {
+    assertValidCreditAmount(amount, { userId, operation: "deductCredits" });
+    const credits = this.store.users.get(userId);
     if (!credits) {
       throw new Error(`User credits not found for userId: ${userId}`);
     }
-    const available = credits.balance + credits.bonusCredits - credits.reserved;
+    const available = sumAmounts(credits.balance, credits.bonusCredits, -credits.reserved);
     if (available < amount) {
       throw new Error(
         `Insufficient credits. Available: ${available}, requested: ${amount}`
       );
     }
     const balanceDeduction = Math.min(credits.balance, amount);
-    const bonusDeduction = amount - balanceDeduction;
-    const previousBalance = credits.balance + credits.bonusCredits;
-    credits.balance -= balanceDeduction;
-    credits.bonusCredits -= bonusDeduction;
+    const bonusDeduction = sumAmounts(amount, -balanceDeduction);
+    const previousBalance = sumAmounts(credits.balance, credits.bonusCredits);
+    const nextBalance = sumAmounts(credits.balance, -balanceDeduction);
+    const nextBonusCredits = sumAmounts(credits.bonusCredits, -bonusDeduction);
+    const newBalance = sumAmounts(previousBalance, -amount);
+    assertRepresentableFields(
+      { previousBalance, balance: nextBalance, bonusCredits: nextBonusCredits, newBalance },
+      { userId, operation: "deductCredits" }
+    );
+    credits.balance = nextBalance;
+    credits.bonusCredits = nextBonusCredits;
     credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    this.users.set(userId, credits);
-    return { previousBalance, newBalance: previousBalance - amount };
+    this.store.users.set(userId, credits);
+    return { previousBalance, newBalance };
   }
   // ==================== Transactions ====================
   async createTransaction(input) {
+    assertUnreferencedDirectTransaction(input);
+    return this.recordTransaction({
+      ...input,
+      paymentRef: normalizePaymentRef(input.paymentRef)
+    });
+  }
+  /** The unguarded writer, for `addCreditsV2` — which has moved the balance. */
+  recordTransaction(input) {
+    assertRepresentableAmount(input.amount, "transaction amount", { userId: input.userId });
+    assertRepresentableAmount(input.previousBalance, "transaction previousBalance", {
+      userId: input.userId
+    });
+    assertRepresentableAmount(input.newBalance, "transaction newBalance", {
+      userId: input.userId
+    });
     const transaction = {
       id: generateId(),
       userId: input.userId,
@@ -983,23 +2162,24 @@ var InMemoryCreditRepository = class {
       newBalance: input.newBalance,
       createdAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-    if (!this.transactions.has(input.userId)) {
-      this.transactions.set(input.userId, []);
+    if (!this.store.transactions.has(input.userId)) {
+      this.store.transactions.set(input.userId, []);
     }
-    this.transactions.get(input.userId).push(transaction);
-    return transaction;
+    this.store.transactions.get(input.userId).push(transaction);
+    return copyRecord(transaction);
   }
   async getTransactions(userId, limit = 50, offset = 0) {
-    const userTransactions = this.transactions.get(userId) ?? [];
+    const userTransactions = this.store.transactions.get(userId) ?? [];
     const sorted = [...userTransactions].sort((a, b) => {
       const aDate = toDate2(a.createdAt).getTime();
       const bDate = toDate2(b.createdAt).getTime();
       return bDate - aDate;
     });
-    return sorted.slice(offset, offset + limit);
+    return copyRecords(sorted.slice(offset, offset + limit));
   }
   // ==================== Usage Logs ====================
   async logUsage(input) {
+    assertRepresentableAmount(input.creditsUsed, "creditsUsed", { userId: input.userId });
     const log = {
       id: generateId(),
       userId: input.userId,
@@ -1011,14 +2191,14 @@ var InMemoryCreditRepository = class {
       resourceId: input.resourceId,
       resourceType: input.resourceType,
       requestId: input.requestId,
-      metadata: input.metadata,
+      metadata: input.metadata ? { ...input.metadata } : input.metadata,
       createdAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-    this.usageLogs.push(log);
-    return log;
+    this.store.usageLogs.push(log);
+    return copyRecord(log);
   }
   async getUsageLogs(query) {
-    let results = [...this.usageLogs];
+    let results = [...this.store.usageLogs];
     if (query.userId) {
       results = results.filter((log) => log.userId === query.userId);
     }
@@ -1045,7 +2225,7 @@ var InMemoryCreditRepository = class {
     });
     const offset = query.offset ?? 0;
     const limit = query.limit ?? 50;
-    return results.slice(offset, offset + limit);
+    return copyRecords(results.slice(offset, offset + limit));
   }
   async getUsageLogsCount(query) {
     const results = await this.getUsageLogs({ ...query, limit: Infinity, offset: 0 });
@@ -1053,6 +2233,29 @@ var InMemoryCreditRepository = class {
   }
   // ==================== Journal Entries ====================
   async createJournalEntry(input) {
+    return this.recordJournalEntry(input);
+  }
+  /**
+   * The synchronous body of `createJournalEntry`, so `atomicMonthlyReset` can
+   * write its journal line inside the same run-to-completion step as the
+   * balance write — an `await` between the two is exactly the gap that loses
+   * the line when the second half fails.
+   */
+  recordJournalEntry(input) {
+    assertRepresentableAmount(input.amount, "journal amount", { userId: input.userId });
+    assertRepresentableAmount(input.balanceAfter, "journal balanceAfter", {
+      userId: input.userId
+    });
+    assertValidIdempotencyKey(input.idempotencyKey, { userId: input.userId });
+    assertPublicJournalKey(input.idempotencyKey, input.userId);
+    const key = input.idempotencyKey !== void 0 ? scopedKey(input.userId, input.idempotencyKey) : void 0;
+    if (key !== void 0 && this.store.journalKeys.has(key)) {
+      throw new CreditError(
+        `Journal idempotency key ${input.idempotencyKey} is already used for user ${input.userId}. The unique constraint refuses a second entry.`,
+        CreditErrorCode.DATABASE_ERROR,
+        { userId: input.userId, idempotencyKey: input.idempotencyKey }
+      );
+    }
     const entry = {
       id: generateId(),
       userId: input.userId,
@@ -1063,17 +2266,19 @@ var InMemoryCreditRepository = class {
       referenceId: input.referenceId,
       referenceType: input.referenceType,
       description: input.description,
-      metadata: input.metadata,
+      metadata: input.metadata ? { ...input.metadata } : input.metadata,
+      idempotencyKey: input.idempotencyKey,
       createdAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-    if (!this.journalEntries.has(input.userId)) {
-      this.journalEntries.set(input.userId, []);
+    if (!this.store.journalEntries.has(input.userId)) {
+      this.store.journalEntries.set(input.userId, []);
     }
-    this.journalEntries.get(input.userId).push(entry);
-    return entry;
+    this.store.journalEntries.get(input.userId).push(entry);
+    if (key !== void 0) this.store.journalKeys.set(key, entry.id);
+    return copyRecord(entry);
   }
   async getJournalEntries(query) {
-    let results = this.journalEntries.get(query.userId) ?? [];
+    let results = this.store.journalEntries.get(query.userId) ?? [];
     if (query.source) {
       results = results.filter((entry) => entry.source === query.source);
     }
@@ -1097,7 +2302,7 @@ var InMemoryCreditRepository = class {
     });
     const offset = query.offset ?? 0;
     const limit = query.limit ?? 50;
-    return results.slice(offset, offset + limit);
+    return copyRecords(results.slice(offset, offset + limit));
   }
   async getJournalEntriesCount(query) {
     const results = await this.getJournalEntries({
@@ -1108,53 +2313,91 @@ var InMemoryCreditRepository = class {
     return results.length;
   }
   // ==================== Cleanup Operations ====================
+  /**
+   * Expire every hold whose deadline has passed.
+   *
+   * Each candidate goes through the guarded {@link expireReservationV2}, which
+   * re-checks the status and the deadline under the user's lock. The previous
+   * implementation released the hold and then overwrote the status to
+   * `expired`, so a commit landing in between got its credits handed back and
+   * was then relabelled.
+   */
   async findAndExpireReservations(_batchSize = 100, _maxIterations = 100) {
-    const now = /* @__PURE__ */ new Date();
+    const asOf = /* @__PURE__ */ new Date();
     let expiredCount = 0;
     let creditsReleased = 0;
     const errors = [];
-    for (const [userId, userReservations] of this.reservations) {
+    const candidates = [];
+    for (const [userId, userReservations] of this.store.reservations) {
       for (const [reservationId, reservation] of userReservations) {
-        if (reservation.status === "reserved" && toDate2(reservation.expiresAt).getTime() < now.getTime()) {
-          try {
-            await this.releaseReservationAtomic(userId, reservationId);
-            reservation.status = "expired";
-            userReservations.set(reservationId, reservation);
-            expiredCount++;
-            creditsReleased += reservation.amount;
-          } catch (error) {
-            errors.push(
-              `Failed to expire reservation ${reservationId}: ${error}`
-            );
-          }
+        if (reservation.status === "reserved" && toDate2(reservation.expiresAt).getTime() < asOf.getTime()) {
+          candidates.push({ userId, reservationId });
+        }
+      }
+    }
+    for (const candidate of candidates) {
+      try {
+        const outcome = await this.expireReservationV2(
+          candidate.userId,
+          candidate.reservationId,
+          { asOf }
+        );
+        if (outcome.outcome === "expired") {
+          expiredCount++;
+          creditsReleased = sumAmounts(creditsReleased, outcome.amount);
         }
+      } catch (error) {
+        errors.push(
+          `Failed to expire reservation ${candidate.reservationId}: ${error}`
+        );
       }
     }
     return { expiredCount, creditsReleased, errors };
   }
   // ==================== Atomic Monthly Reset ====================
   async atomicMonthlyReset(userId, tier, expectedResetAt) {
-    const credits = this.users.get(userId);
+    const credits = this.store.users.get(userId);
     if (!credits) {
       throw new Error(`User ${userId} not found`);
     }
     const currentResetAt = toDate2(credits.monthlyResetAt).getTime();
     const expected = toDate2(expectedResetAt).getTime();
     if (currentResetAt !== expected) {
-      return { wasReset: false, credits };
+      return { wasReset: false, credits: { ...credits } };
     }
-    const newBalance = getConfigMonthlyLimit(tier);
+    assertRepresentableTierAmount(getConfigMonthlyLimit(tier), "monthlyLimit", { userId, tier });
     const nextReset = getNextMonthlyReset();
-    credits.balance = newBalance === Infinity ? credits.balance : newBalance;
+    const target = monthlyResetBalance(tier);
+    const floor = backedBalanceFloor(credits.reserved, credits.bonusCredits);
+    const previousBalance = credits.balance;
+    const newBalance = target.kind === "atLeast" ? Math.max(credits.balance, target.value, floor) : Math.max(target.value, floor);
+    const change = sumAmounts(newBalance, -previousBalance);
+    const balanceAfter = sumAmounts(newBalance, credits.bonusCredits);
+    assertRepresentableAmount(Math.abs(change), "journal amount", { userId });
+    assertRepresentableAmount(balanceAfter, "journal balanceAfter", { userId });
+    credits.balance = newBalance;
     credits.monthlyUsed = 0;
     credits.monthlyResetAt = nextReset.toISOString();
     credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    this.users.set(userId, credits);
-    return { wasReset: true, credits };
+    this.store.users.set(userId, credits);
+    if (change !== 0) {
+      this.recordJournalEntry({
+        userId,
+        entryType: change > 0 ? "credit" : "debit",
+        amount: Math.abs(change),
+        balanceAfter,
+        source: "monthly_reset",
+        referenceId: `reset-${Date.now()}`,
+        referenceType: "reset",
+        description: `Monthly credit reset for ${tier} tier.`,
+        metadata: { tier, previousBalance, newBalance }
+      });
+    }
+    return { wasReset: true, credits: { ...credits }, journaled: true };
   }
   // ==================== Subscription Expiry ====================
   async checkAndHandleSubscriptionExpiry(userId, gracePeriodDays = 3) {
-    const credits = this.users.get(userId);
+    const credits = this.store.users.get(userId);
     if (!credits) {
       throw new Error(`User ${userId} not found`);
     }
@@ -1163,7 +2406,7 @@ var InMemoryCreditRepository = class {
         wasDowngraded: false,
         inGracePeriod: false,
         graceDaysRemaining: 0,
-        credits
+        credits: { ...credits }
       };
     }
     const now = /* @__PURE__ */ new Date();
@@ -1174,7 +2417,7 @@ var InMemoryCreditRepository = class {
         wasDowngraded: false,
         inGracePeriod: false,
         graceDaysRemaining: 0,
-        credits
+        credits: { ...credits }
       };
     }
     if (daysSinceExpiry <= gracePeriodDays) {
@@ -1182,22 +2425,48 @@ var InMemoryCreditRepository = class {
         wasDowngraded: false,
         inGracePeriod: true,
         graceDaysRemaining: Math.ceil(gracePeriodDays - daysSinceExpiry),
-        credits
+        credits: { ...credits }
       };
     }
     const defaultTier = getDefaultTier();
-    const defaultTierConfig = getConfigTierConfig(defaultTier);
+    const configured = getConfigMonthlyLimit(defaultTier);
+    assertRepresentableTierAmount(configured, "monthlyLimit", {
+      userId,
+      tier: defaultTier
+    });
+    const limit = storedMonthlyLimit(configured);
+    const previousTier = credits.tier;
+    const previousBalance = credits.balance;
+    const newBalance = Math.max(
+      Math.min(credits.balance, limit),
+      backedBalanceFloor(credits.reserved, credits.bonusCredits)
+    );
+    const balanceAfter = sumAmounts(newBalance, credits.bonusCredits);
+    assertRepresentableAmount(balanceAfter, "journal balanceAfter", { userId });
     credits.tier = defaultTier;
-    credits.monthlyLimit = defaultTierConfig.monthlyCredits;
-    credits.balance = Math.min(credits.balance, defaultTierConfig.monthlyCredits);
+    credits.monthlyLimit = limit;
+    credits.balance = newBalance;
     credits.subscriptionExpiresAt = null;
     credits.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    this.users.set(userId, credits);
+    this.store.users.set(userId, credits);
+    this.recordJournalEntry({
+      userId,
+      entryType: "debit",
+      amount: 0,
+      // No credits deducted, just tier change
+      balanceAfter,
+      source: "subscription_downgrade",
+      referenceId: `downgrade-${Date.now()}`,
+      referenceType: "subscription",
+      description: `Subscription expired. Downgraded from ${previousTier} to ${defaultTier} tier.`,
+      metadata: { previousTier, previousBalance, newBalance }
+    });
     return {
       wasDowngraded: true,
       inGracePeriod: false,
       graceDaysRemaining: 0,
-      credits
+      credits: { ...credits },
+      journaled: true
     };
   }
   // ==================== Testing Utilities ====================
@@ -1205,25 +2474,33 @@ var InMemoryCreditRepository = class {
    * Clear all data (useful for testing)
    */
   clear() {
-    this.users.clear();
-    this.reservations.clear();
-    this.transactions.clear();
-    this.usageLogs = [];
-    this.journalEntries.clear();
+    this.store.clear();
+  }
+  /**
+   * Install a yield point inside every V2 critical section (testing only).
+   *
+   * Unset, the critical sections run start-to-finish synchronously, so
+   * concurrent callers never interleave and a concurrency test would pass even
+   * with the locking removed. Setting this to a real yield (a macrotask or a
+   * barrier) makes callers genuinely overlap, so the tests exercise the lock
+   * instead of the event loop. Never call this in production code.
+   */
+  setSchedulingHook(hook) {
+    this.store.schedulingHook = hook;
   }
   /**
    * Get all users (useful for testing/debugging)
    */
   getAllUsers() {
-    return Array.from(this.users.values());
+    return copyRecords(Array.from(this.store.users.values()));
   }
   /**
    * Get all reservations for a user (useful for testing)
    */
   getAllReservations(userId) {
-    const userReservations = this.reservations.get(userId);
+    const userReservations = this.store.reservations.get(userId);
     if (!userReservations) return [];
-    return Array.from(userReservations.values());
+    return copyRecords(Array.from(userReservations.values()));
   }
 };
 function createInMemoryCreditRepository() {
@@ -1334,28 +2611,38 @@ var CreditsService = class {
         userId,
         getConfig().subscriptionGracePeriodDays
       );
-      if (expiryResult.wasDowngraded) {
+      if (expiryResult.wasDowngraded && !expiryResult.journaled) {
         await this.repository.createJournalEntry({
           userId,
           entryType: "debit",
           amount: 0,
           // No credits deducted, just tier change
-          balanceAfter: expiryResult.credits.balance,
+          // The ledger balance, matching every other journal writer: the V2
+          // transitions and add/deduct all record `balance + bonusCredits`, so
+          // recording `balance` alone made the audit trail disagree with itself
+          // for any user holding bonus credits.
+          balanceAfter: sumAmounts(
+            expiryResult.credits.balance,
+            expiryResult.credits.bonusCredits
+          ),
           source: "subscription_downgrade",
           referenceId: `downgrade-${Date.now()}`,
           referenceType: "subscription",
-          description: `Subscription expired. Downgraded from ${data.tier} to free tier.`,
+          // The tier actually landed on, not a hard-coded "free": the downgrade
+          // target is configurable, so naming `free` here could describe a
+          // transition that never happened.
+          description: `Subscription expired. Downgraded from ${data.tier} to ${expiryResult.credits.tier} tier.`,
           metadata: {
             previousTier: data.tier,
             previousBalance: data.balance,
             newBalance: expiryResult.credits.balance
           }
         });
-        if (this.subscriptionExpiredCallback) {
-          this.subscriptionExpiredCallback(userId, true).catch((error) => {
-            console.error("[Credits] Failed to send subscription expired notification:", error);
-          });
-        }
+      }
+      if (expiryResult.wasDowngraded && this.subscriptionExpiredCallback) {
+        this.subscriptionExpiredCallback(userId, true).catch((error) => {
+          console.error("[Credits] Failed to send subscription expired notification:", error);
+        });
       }
       data = expiryResult.credits;
     }
@@ -1366,14 +2653,17 @@ var CreditsService = class {
         data.tier,
         expectedResetAt
       );
-      if (resetResult.wasReset) {
-        const balanceChange = resetResult.credits.balance - data.balance;
+      if (resetResult.wasReset && !resetResult.journaled) {
+        const balanceChange = sumAmounts(resetResult.credits.balance, -data.balance);
         if (balanceChange !== 0) {
           await this.repository.createJournalEntry({
             userId,
             entryType: balanceChange > 0 ? "credit" : "debit",
             amount: Math.abs(balanceChange),
-            balanceAfter: resetResult.credits.balance,
+            balanceAfter: sumAmounts(
+              resetResult.credits.balance,
+              resetResult.credits.bonusCredits
+            ),
             source: "monthly_reset",
             referenceId: `reset-${Date.now()}`,
             referenceType: "reset",
@@ -1424,14 +2714,14 @@ var CreditsService = class {
    */
   async checkCredits(userId, requiredCredits) {
     const credits = await this.getOrCreateUserCredits(userId);
-    const totalBalance = credits.balance + credits.bonusCredits;
-    const available = totalBalance - credits.reserved;
+    const totalBalance = sumAmounts(credits.balance, credits.bonusCredits);
+    const available = sumAmounts(totalBalance, -credits.reserved);
     const hasCredits = available >= requiredCredits;
     return {
       hasCredits,
       balance: totalBalance,
       required: requiredCredits,
-      shortfall: hasCredits ? 0 : requiredCredits - available
+      shortfall: hasCredits ? 0 : sumAmounts(requiredCredits, -available)
     };
   }
   /**
@@ -1445,74 +2735,110 @@ var CreditsService = class {
    * @throws Error if insufficient credits
    */
   async reserveCredits(userId, amount, operationType, options) {
+    const outcome = await this.reserveCreditsDetailed(userId, amount, operationType, options);
+    if (outcome.outcome === "created" || outcome.outcome === "replayed") {
+      return outcome.reservation;
+    }
+    if (outcome.outcome === "insufficient") {
+      throw createInsufficientCreditsError(outcome.required, outcome.available);
+    }
+    throw createIdempotencyConflictError(outcome.idempotencyKey, {
+      userId,
+      requested: { amount, operationType },
+      existing: {
+        amount: outcome.existing.amount,
+        operationType: outcome.existing.operationType
+      }
+    });
+  }
+  /**
+   * Reserve credits and get the typed outcome instead of an exception.
+   *
+   * Prefer this over {@link reserveCredits} in async callers: it distinguishes
+   * a fresh hold from an idempotent replay, and reports insufficient funds as
+   * a value rather than as control flow.
+   */
+  async reserveCreditsDetailed(userId, amount, operationType, options) {
     const ttlMs = options?.ttlMs ?? getConfig().reservationExpiryMs;
     const expiresAt = new Date(Date.now() + ttlMs);
-    return this.repository.reserveCreditsAtomic(userId, amount, operationType, expiresAt);
+    return reserveThroughRepository(this.repository, {
+      userId,
+      amount,
+      operationType,
+      expiresAt,
+      idempotencyKey: options?.idempotencyKey
+    });
   }
   /**
-   * Commit a reservation (phase 2 of two-phase commit - success)
-   * Deducts credits and marks reservation as committed
-   * Also triggers low balance notifications if balance drops below threshold
+   * Commit a reservation (phase 2 of two-phase commit - success).
+   *
+   * Idempotent: re-delivering a commit for an already-committed reservation is
+   * a no-op. Committing one that was released or expired throws, because the
+   * credits are no longer held and pretending otherwise would hide a real bug.
    */
-  async commitCredits(userId, reservationId) {
-    const reservation = await this.repository.getReservation(userId, reservationId);
-    if (!reservation) {
-      throw new Error(`Reservation ${reservationId} not found`);
+  async commitCredits(userId, reservationId, options) {
+    const outcome = await this.commitCreditsDetailed(userId, reservationId, options);
+    if (outcome.outcome === "not_found") {
+      throw createReservationNotFoundError(reservationId);
     }
-    if (reservation.status === "committed") {
-      return;
+    if (outcome.outcome === "already_terminal" && outcome.terminalStatus !== "committed") {
+      throw createReservationAlreadyProcessedError(reservationId, outcome.terminalStatus);
     }
-    await this.repository.commitReservationAtomic(userId, reservationId);
-    const credits = await this.repository.getUserCredits(userId);
-    if (credits) {
-      await this.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
-        }
+  }
+  /**
+   * Commit a reservation and get the typed outcome.
+   *
+   * Exactly one concurrent caller sees `committed`; that call moved the balance
+   * and wrote the single journal entry. On a V2 repository the journal is
+   * written inside the same transaction, so this method adds none of its own —
+   * the duplicate entry the previous implementation wrote is gone.
+   *
+   * The low-balance notification fires only for the winner, and only after the
+   * transaction has committed, so no callback runs inside a database
+   * transaction.
+   */
+  async commitCreditsDetailed(userId, reservationId, options) {
+    const outcome = await commitThroughRepository(
+      this.repository,
+      userId,
+      reservationId,
+      options
+    );
+    if (outcome.outcome === "committed" && this.lowBalanceCallback) {
+      this.lowBalanceCallback(userId, outcome.balanceAfter).catch((error) => {
+        console.error("[Credits] Failed to send low balance notification:", error);
       });
-      if (this.lowBalanceCallback) {
-        this.lowBalanceCallback(userId, credits.balance).catch((error) => {
-          console.error("[Credits] Failed to send low balance notification:", error);
-        });
-      }
     }
+    return outcome;
   }
   /**
-   * Release a reservation (phase 2 of two-phase commit - failure)
-   * Returns reserved credits and marks reservation as released
+   * Release a reservation (phase 2 of two-phase commit - failure).
+   *
+   * Throws `RESERVATION_NOT_FOUND` for an unknown reservation, matching the
+   * pre-V2 behaviour — a release naming a reservation that does not exist is a
+   * caller bug, and swallowing it hides the bug while the credits stay held.
+   *
+   * Releasing one that is already terminal — `released`, `expired`, or
+   * `committed` — is a no-op, which is the behaviour this method has always
+   * had. A release that loses a race to a concurrent commit is the common
+   * case in a retry-heavy caller, and callers written against the pre-V2
+   * contract handle it by not handling it.
+   *
+   * That does mean this method cannot tell you that the credits were spent
+   * rather than returned. Use {@link releaseCreditsDetailed}, which reports
+   * `already_terminal` with `terminalStatus: 'committed'`, when you need to
+   * branch on it.
    */
-  async releaseCredits(userId, reservationId) {
-    const reservation = await this.repository.getReservation(userId, reservationId);
-    await this.repository.releaseReservationAtomic(userId, reservationId);
-    if (reservation?.status === "reserved") {
-      const credits = await this.repository.getUserCredits(userId);
-      if (credits) {
-        await this.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
-          }
-        });
-      }
+  async releaseCredits(userId, reservationId, options) {
+    const outcome = await this.releaseCreditsDetailed(userId, reservationId, options);
+    if (outcome.outcome === "not_found") {
+      throw createReservationNotFoundError(reservationId);
     }
   }
+  /** Release a reservation and get the typed outcome. */
+  async releaseCreditsDetailed(userId, reservationId, options) {
+    return releaseThroughRepository(this.repository, userId, reservationId, options);
+  }
   /**
    * Log usage for audit trail
    * @param log - Usage log data
@@ -1528,9 +2854,20 @@ var CreditsService = class {
    * @param paymentRef - Optional payment reference
    * @param options - Optional journal source / reference type / extra metadata
    *   for the credit journal entry (e.g. revenue-attribution fields).
+   * @returns Whether this delivery credited the account (`created`), repeated an
+   *   earlier one (`replayed`), or reused the reference for a different credit
+   *   event (`conflict`, which credited nothing). On a repository without
+   *   `addCreditsV2` the result is always `created` and carries no
+   *   deduplication guarantee — see {@link addCreditsThroughRepository}.
    */
   async addCredits(userId, amount, description, paymentRef, options) {
-    return this.repository.addCreditsAtomic(userId, amount, description, paymentRef, options);
+    return addCreditsThroughRepository(this.repository, {
+      userId,
+      amount,
+      description,
+      paymentRef,
+      options
+    });
   }
   /**
    * One-shot atomic "deduct-if-sufficient" credit charge.
@@ -1554,15 +2891,14 @@ var CreditsService = class {
    * @throws Error if amount is not a positive number
    */
   async deductCredits(userId, amount, options) {
-    if (!(amount > 0)) {
-      throw new Error(`deductCredits amount must be positive (got ${amount})`);
-    }
+    assertValidCreditAmount(amount, { userId, operation: "deductCredits" });
     let deduction;
     try {
       deduction = await this.repository.deductCreditsAtomic(userId, amount);
     } catch (error) {
+      if (isCreditError(error) && error.code === CreditErrorCode.INVALID_AMOUNT) throw error;
       const credits = await this.repository.getUserCredits(userId);
-      const available = credits ? credits.balance + credits.bonusCredits - credits.reserved : 0;
+      const available = credits ? sumAmounts(credits.balance, credits.bonusCredits, -credits.reserved) : 0;
       if (available >= amount) {
         throw error;
       }
@@ -1571,7 +2907,7 @@ var CreditsService = class {
         reason: "insufficient",
         available,
         required: amount,
-        shortfall: amount - available
+        shortfall: sumAmounts(amount, -available)
       };
     }
     const operationType = options?.operationType;
@@ -1585,8 +2921,8 @@ var CreditsService = class {
       referenceType: "adjustment",
       description: operationType ? `Deducted ${amount} credits for ${getOperationLabel(operationType)}` : `Deducted ${amount} credits`,
       metadata: {
-        ...operationType && { operationType },
-        ...options?.metadata
+        ...options?.metadata,
+        ...operationType && { operationType }
       }
     });
     if (operationType) {
@@ -1621,8 +2957,15 @@ var CreditsService = class {
     const free = isFreeTier(tier);
     await this.repository.updateUserTier(userId, {
       tier,
-      // Stored monthlyLimit uses the 0-means-unlimited convention.
-      monthlyLimit: unlimited ? 0 : monthlyLimit,
+      // Through the shared contract, like every path that resolves the tier's
+      // limit from configuration. (The repository's `updateUserCredits` and
+      // `updateUserTier` still store a caller-supplied `monthlyLimit` verbatim;
+      // they are given a value, not a tier, so there is no sentinel to map.)
+      // This used to store 0 for an unlimited tier under a "0 means unlimited"
+      // convention that nothing actually implemented — no read path anywhere in
+      // the library branches on it — so upgrading a user to unlimited gave them
+      // an allowance of zero.
+      monthlyLimit: storedMonthlyLimit(monthlyLimit),
       // Reset balance to new tier limit if upgrading
       balance: !free ? unlimited ? getUnlimitedSentinelBalance() : monthlyLimit : void 0,
       monthlyUsed: !free ? 0 : void 0,
@@ -1765,9 +3108,11 @@ function createGenericAdapter(config) {
           return handler(user, data, dummyReservation);
         }
         let reservation;
+        let isFree = false;
         try {
           const cost = options.customCost ?? getOperationCost2(options.operationType);
-          reservation = await reserveCreditsForOperation(
+          isFree = options.customCost === void 0 && cost === 0;
+          reservation = isFree ? { ...createDummyReservation(user.id, options.operationType), id: "free-operation" } : await reserveCreditsForOperation(
             repository,
             user.id,
             cost,
@@ -1790,7 +3135,7 @@ function createGenericAdapter(config) {
         try {
           const result = await handler(user, data, reservation);
           if (result.success) {
-            await commitReservationWithJournal(repository, user.id, reservation.id);
+            if (!isFree) await commitReservationWithJournal(repository, user.id, reservation.id);
             logUsage({
               userId: user.id,
               operationType: options.operationType,
@@ -1801,7 +3146,7 @@ function createGenericAdapter(config) {
               requestId
             });
           } else {
-            await releaseReservationWithJournal(repository, user.id, reservation.id);
+            if (!isFree) await releaseReservationWithJournal(repository, user.id, reservation.id);
             logUsage({
               userId: user.id,
               operationType: options.operationType,
@@ -1816,7 +3161,7 @@ function createGenericAdapter(config) {
           return result;
         } catch (error) {
           const message = error instanceof Error ? error.message : "An unexpected error occurred";
-          await releaseReservationWithJournal(repository, user.id, reservation.id);
+          if (!isFree) await releaseReservationWithJournal(repository, user.id, reservation.id);
           logUsage({
             userId: user.id,
             operationType: options.operationType,
@@ -2313,7 +3658,7 @@ var CreditsClient = class {
    */
   async getAvailableCredits() {
     const balance = await this.getBalance();
-    return balance.balance + balance.bonusCredits - balance.reserved;
+    return sumAmounts(balance.balance, balance.bonusCredits, -balance.reserved);
   }
   /**
    * Execute an operation with automatic credit handling
@@ -2542,7 +3887,7 @@ function parseCreditError(error) {
   return {
     available,
     required,
-    shortfall: required - available,
+    shortfall: sumAmounts(required, -available),
     rawMessage: error
   };
 }
@@ -2553,7 +3898,7 @@ function isCreditErrorMessage(error) {
 
 // src/utils/index.ts
 function getTotalCredits(credits) {
-  return credits.balance + credits.bonusCredits;
+  return sumAmounts(credits.balance, credits.bonusCredits);
 }
 function generateRequestId2() {
   const timestamp = Date.now();
@@ -2581,6 +3926,8 @@ function createDummyReservation2(userId, operationType) {
   ApiKeyCreditsProvider,
   AuthenticationError,
   AuthorizationError,
+  CREDIT_AMOUNT_MAX,
+  CREDIT_AMOUNT_SCALE,
   ConsoleNotificationHandler,
   CreditError,
   CreditErrorCode,
@@ -2589,31 +3936,57 @@ function createDummyReservation2(userId, operationType) {
   CreditsService,
   InMemoryCreditRepository,
   NetworkError,
+  RESERVATION_STATUSES,
+  RESERVED_JOURNAL_KEY_PREFIX,
   SDKErrorCode,
   SDKInsufficientCreditsError,
   SDKReservationExpiredError,
   SDKReservationNotFoundError,
   ServerError,
+  TERMINAL_RESERVATION_STATUSES,
   UNLIMITED_BALANCE_SENTINEL,
   ValidationError,
+  addCreditsThroughRepository,
+  assertDirectStatusWriteAllowed,
+  assertHoldPlaced,
+  assertKnownReservationStatus,
+  assertPublicJournalKey,
+  assertRepresentableAmount,
+  assertRepresentableFields,
+  assertRepresentableTierAmount,
+  assertUnkeyedDirectReservation,
+  assertUnreferencedDirectTransaction,
+  assertValidCreditAmount,
+  assertValidIdempotencyKey,
+  assertValidStoredAmount,
+  assertValidStoredAmountRaw,
+  backedBalanceFloor,
   calculateAvailableCredits,
   checkAndNotifyLowBalance,
+  classifyDatabaseError,
   clearConfigProvider,
   clearCooldownState,
   clearNotificationHandlers,
   commitReservationWithJournal,
+  commitThroughRepository,
   createApiKeyProvider,
   createCreditsService,
   createDeferredExecutor,
   createDummyReservation,
   createGenericAdapter,
+  createIdempotencyConflictError,
   createInMemoryCreditRepository,
   createInsufficientCreditsError,
+  createInvalidAmountError,
   createInvalidOperationTypeError,
+  createPaymentRefConflictError,
   createReservationAlreadyProcessedError,
   createReservationExpiredError,
   createReservationNotFoundError,
+  createTransientError,
+  createUnsupportedOperationError,
   createUserNotFoundError,
+  describePaymentMismatch,
   generateId,
   generateRequestId,
   genericDeferred,
@@ -2632,35 +4005,63 @@ function createDummyReservation2(userId, operationType) {
   getOperationLabel,
   getOperationLabels,
   getReservationExpiryMs,
+  getSqlState,
   getTierConfig,
   getTotalCredits,
   getUnlimitedSentinelBalance,
   getValidOperationTypes,
   getValidTiers,
+  hasPlacedHold,
   initializeConfig,
   isCreditError,
   isCreditErrorMessage,
+  isCreditedOutcome,
   isFeatureEnabled,
   isFreeTier,
+  isIdempotencyConflictError,
   isInsufficientCreditsError,
   isPreviewMode,
+  isRepresentableAmount,
+  isReservationStatus,
+  isReservedJournalKey,
+  isReservedOutcome,
+  isTerminalReservationStatus,
+  isTransientDatabaseError,
+  isTransientError,
+  isUniqueViolation,
   isUnlimitedTier,
+  isValidCreditAmount,
+  isValidIdempotencyKey,
   isValidOperationType,
   isValidTier,
+  isWinningOutcome,
   loadConfigFromEnv,
+  monthlyResetBalance,
   noopDeferred,
+  normalizePaymentRef,
   notifySubscriptionExpired,
   notifySubscriptionExpiring,
+  numericToCents,
   parseApiError,
   parseCreditError,
   parseTier,
   registerConfigProvider,
   registerNotificationHandler,
   releaseReservationWithJournal,
+  releaseThroughRepository,
+  reservationJournalKey,
   reserveCreditsForOperation,
+  reserveThroughRepository,
   resetConfig,
+  sameAmount,
+  storedMonthlyLimit,
+  sumAmounts,
+  supportsCreditsV2,
+  supportsIdempotentCredit,
   synchronousDeferred,
+  terminalStatusOf,
   tierSchema,
+  toCents,
   toClientUserCredits,
   toDate,
   toPortableTimestamp,