@nehorai/credits 1.6.0 → 2.0.0

package/dist/repository/index.cjs

@@ -21,15 +21,28 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var repository_exports = {};
 __export(repository_exports, {
   InMemoryCreditRepository: () => InMemoryCreditRepository,
+  addCreditsThroughRepository: () => addCreditsThroughRepository,
+  commitThroughRepository: () => commitThroughRepository,
   createInMemoryCreditRepository: () => createInMemoryCreditRepository,
   generateId: () => generateId,
   getNextMonthlyReset: () => getNextMonthlyReset,
+  releaseThroughRepository: () => releaseThroughRepository,
+  reservationJournalKey: () => reservationJournalKey,
+  reserveThroughRepository: () => reserveThroughRepository,
+  supportsCreditsV2: () => supportsCreditsV2,
+  supportsIdempotentCredit: () => supportsIdempotentCredit,
   toClientUserCredits: () => toClientUserCredits,
   toDate: () => toDate
 });
 module.exports = __toCommonJS(repository_exports);
 
 // 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,
@@ -55,24 +68,246 @@ function toISOString(value) {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
 
-// src/repository/utils.ts
-function generateId() {
-  return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+// 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 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) {
-    return value.toDate();
+function sumAmounts(...values) {
+  let cents = 0;
+  for (const value of values) {
+    const valueCents = toCents(value);
+    if (valueCents === null) return floatSum(values);
+    cents += valueCents;
   }
-  return /* @__PURE__ */ new Date();
+  return Number.isSafeInteger(cents) ? cents / 100 : floatSum(values);
 }
-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 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 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/errors.ts
+var CreditErrorCode = {
+  INSUFFICIENT_CREDITS: "INSUFFICIENT_CREDITS",
+  RESERVATION_NOT_FOUND: "RESERVATION_NOT_FOUND",
+  RESERVATION_EXPIRED: "RESERVATION_EXPIRED",
+  RESERVATION_ALREADY_PROCESSED: "RESERVATION_ALREADY_PROCESSED",
+  USER_NOT_FOUND: "USER_NOT_FOUND",
+  INVALID_OPERATION_TYPE: "INVALID_OPERATION_TYPE",
+  CONFIGURATION_ERROR: "CONFIGURATION_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;
+  details;
+  constructor(message, code, details) {
+    super(message);
+    this.name = "CreditError";
+    this.code = code;
+    this.details = details;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _CreditError);
+    }
+  }
+  /**
+   * Convert to JSON-serializable object
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      ...this.details && { details: this.details }
+    };
+  }
+};
+function isCreditError(error) {
+  return error instanceof CreditError;
+}
+function isInsufficientCreditsError(error) {
+  if (isCreditError(error)) {
+    return error.code === CreditErrorCode.INSUFFICIENT_CREDITS;
+  }
+  if (error instanceof Error) {
+    return error.message.toLowerCase().includes("insufficient credits");
+  }
+  return false;
+}
+function createInsufficientCreditsError(required, available) {
+  return new CreditError(
+    `Insufficient credits: available ${available}, required ${required}`,
+    CreditErrorCode.INSUFFICIENT_CREDITS,
+    { required, available, shortfall: sumAmounts(required, -available) }
+  );
+}
+function createReservationNotFoundError(reservationId) {
+  return new CreditError(
+    `Reservation ${reservationId} not found`,
+    CreditErrorCode.RESERVATION_NOT_FOUND,
+    { reservationId }
+  );
+}
+function createReservationAlreadyProcessedError(reservationId, status) {
+  return new CreditError(
+    `Reservation ${reservationId} has already been ${status}`,
+    CreditErrorCode.RESERVATION_ALREADY_PROCESSED,
+    { reservationId, status }
+  );
+}
+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 } : {} }
+  );
+}
+
+// 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/repository/v2-types.ts
+function reservationJournalKey(reservationId, transition) {
+  return `${RESERVED_JOURNAL_KEY_PREFIX}${reservationId}:${transition}`;
 }
 
 // src/config/index.ts
@@ -341,6 +576,13 @@ function getDefaultTier() {
   const def = entries.find(([, c]) => c.isDefault)?.[0] ?? entries.find(([, c]) => c.isFree ?? c.priceUsd === 0)?.[0];
   return def ?? "free";
 }
+var UNLIMITED_BALANCE_SENTINEL = 999999;
+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;
@@ -354,20 +596,771 @@ function getConfigMonthlyLimit(tier) {
   return isUnlimitedTier(tier) ? Infinity : getConfigTierConfig(tier).monthlyCredits;
 }
 var tierSchema = import_zod.z.string().refine(isValidTier, { message: "Unknown subscription tier" });
+function snakeCaseToTitleCase(str) {
+  return str.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function getOperationLabel(operationType) {
+  const labels = getConfig().operationLabels;
+  if (labels && operationType in labels) {
+    return labels[operationType];
+  }
+  return snakeCaseToTitleCase(operationType);
+}
 initializeConfig();
 
-// src/repository/memory/index.ts
-var InMemoryCreditRepository = class {
+// 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/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) 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);
+  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 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);
+  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/repository/utils.ts
+function generateId() {
+  return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+}
+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) {
+    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/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 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/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) };
+  });
+}
+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
+    };
+  });
+}
+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
+    };
+  });
+}
+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 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 {
+  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,
@@ -375,61 +1368,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) {
@@ -439,10 +1464,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(),
@@ -453,19 +1480,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}`);
     }
@@ -473,119 +1500,219 @@ 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) {
-    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 };
+      }
+    }
+    if (!this.store.users.has(userId)) {
+      const tier = getDefaultTier();
+      this.seedUser(userId, tier, storedMonthlyLimit(getConfigMonthlyLimit(tier)));
     }
-    const previousBalance = credits.bonusCredits;
-    credits.bonusCredits += amount;
+    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);
-    await this.createTransaction({
+    this.store.users.set(userId, credits);
+    const transaction = this.recordTransaction({
       userId,
       type: "purchase",
       amount,
       description,
       paymentRef,
-      previousBalance,
-      newBalance: credits.bonusCredits
+      previousBalance: previousTotal,
+      newBalance: newTotal
+    });
+    const journalMetadata = {
+      ...paymentRef ? { paymentRef } : {},
+      ...options?.metadata ?? {}
+    };
+    const entry = await this.createJournalEntry({
+      userId,
+      entryType: "credit",
+      amount,
+      balanceAfter: newTotal,
+      source: payload.source,
+      referenceId: transaction.id ?? paymentRef ?? "unknown",
+      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,
@@ -597,23 +1724,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 = toDate(a.createdAt).getTime();
       const bDate = toDate(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,
@@ -625,14 +1753,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);
     }
@@ -659,7 +1787,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 });
@@ -667,6 +1795,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,
@@ -677,17 +1828,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);
     }
@@ -711,7 +1864,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({
@@ -722,53 +1875,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" && toDate(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" && toDate(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 = toDate(credits.monthlyResetAt).getTime();
     const expected = toDate(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`);
     }
@@ -777,7 +1968,7 @@ var InMemoryCreditRepository = class {
         wasDowngraded: false,
         inGracePeriod: false,
         graceDaysRemaining: 0,
-        credits
+        credits: { ...credits }
       };
     }
     const now = /* @__PURE__ */ new Date();
@@ -788,7 +1979,7 @@ var InMemoryCreditRepository = class {
         wasDowngraded: false,
         inGracePeriod: false,
         graceDaysRemaining: 0,
-        credits
+        credits: { ...credits }
       };
     }
     if (daysSinceExpiry <= gracePeriodDays) {
@@ -796,22 +1987,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 ====================
@@ -819,25 +2036,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() {
@@ -846,9 +2071,16 @@ function createInMemoryCreditRepository() {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   InMemoryCreditRepository,
+  addCreditsThroughRepository,
+  commitThroughRepository,
   createInMemoryCreditRepository,
   generateId,
   getNextMonthlyReset,
+  releaseThroughRepository,
+  reservationJournalKey,
+  reserveThroughRepository,
+  supportsCreditsV2,
+  supportsIdempotentCredit,
   toClientUserCredits,
   toDate
 });