@blamejs/blamejs-shop 0.4.57 → 0.4.58

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.58 (2026-06-19) — **Make concurrent state transitions atomic across payouts, key rotation, and credit accounting.** Closes a class of concurrency races where a state transition or ledger write read the current state, checked it in application code, and then wrote — leaving a window in which two requests for the same record could both pass the check and both apply their effect. Each of these now performs the check and the write as a single conditional statement (the update or insert only lands when the record is still in the expected state, or the balance still satisfies the invariant), so exactly one of two racing callers wins and the other is cleanly refused. The affected operations: an affiliate commission can no longer be marked paid (or voided) twice, so a second payout reference can't be issued for one commission; rotating an API key claims the rotation before minting the replacement, so two concurrent rotations can't issue two successor keys; a B2B credit charge, hold release, and payment now evaluate the credit limit and running balance inside the insert, so concurrent charges can't push an account past its limit or corrupt its denormalized balance; fulfilling or cancelling a backorder line debits the per-SKU pending counter only when it wins the line transition, so the counter can't be double-debited; and a click-and-collect pickup advances the parent order exactly once. No API change and no migration — the operations behave identically for a single caller and now stay correct under concurrent ones. **Fixed:** *Affiliate commission payout transitions are atomic* — markCommissionPaid and markCommissionVoided now gate the status change on the row still being pending in the UPDATE itself and refuse (AFFILIATE_COMMISSION_TRANSITION_REFUSED) when they lose the race. Previously the pending check ran in application code before an unconditional write, so two concurrent payouts for the same commission could both proceed and issue two payout references for one commission, or a void could clobber a paid row. · *API-key rotation claims the rotation before issuing the replacement* — rotate now transitions the key from active to rotated with a conditional update and refuses (API_KEY_NOT_ROTATABLE) if the row is no longer active, before minting the successor key. Previously two concurrent rotations of the same key could both pass the active check and both issue a replacement, leaving an unexpected extra valid credential. · *B2B credit charges, releases, and payments enforce their invariant atomically* — chargeOrder, releaseHold, and recordPayment now compute the new running balance and evaluate their invariant (the credit limit for a charge, the outstanding balance for a payment, the order's net exposure for a release) inside a single conditional insert. Previously the balance was read, checked, and written in separate steps, so two concurrent charges could both pass the limit check — pushing the account past its credit limit and stamping the same balance_after on both rows, permanently under-stating outstanding exposure. Refusals carry the same typed codes (CREDIT_LIMIT_EXCEEDED, CREDIT_PAYMENT_EXCEEDS_OUTSTANDING, CREDIT_RELEASE_NOT_FOUND) and the denormalized per-customer balance chain stays correct under concurrent writes. · *Backorder fulfilment and cancellation debit the counter exactly once* — fulfillBackorder and cancelBackorder now claim the line's pending to fulfilled/cancelled transition with a conditional update and only decrement the per-SKU pending_quantity counter when the claim wins. Previously the line status was checked in application code before an unconditional write and counter decrement, so two concurrent calls for one line could both decrement the counter, under-counting pending demand. · *Click-and-collect pickup advances the order once* — markPickedUp now claims the schedule's ready to picked_up transition with a conditional update before driving the parent order to its delivered state, so two concurrent pickups for one order can't both advance the order FSM.
+
 - v0.4.57 (2026-06-19) — **Refresh the vendored blamejs framework to 0.15.13.** Refreshes the vendored blamejs framework from 0.15.12 to 0.15.13, which consolidates a set of duplicated, security-sensitive code paths onto shared hardened primitives so the strongest available guard now applies everywhere an operation happens. The shop picks up several concrete fixes by composing the framework: a webhook delivery that fails with a transient transport error (connection reset, timeout, 5xx) now backs off and retries up to the configured limit instead of being recorded as permanently failed and dead-lettered, with the SSRF / blocked-host destination check the only permanent failure; an inline webhook delivery is claim-guarded before the POST so a concurrent retry pass can no longer pick up and re-send the same delivery; the webhook deliveries table now creates on a MySQL backend (the pending-delivery index is dialect-aware); and the best-effort final audit checkpoint fired during database shutdown now binds to the database it measured and refuses to write if that handle has been closed or replaced, so a checkpoint can never anchor one database's chain tip into a freshly opened one. File reads across the framework route through a single TOCTOU-safe reader that binds a file's size, contents, and integrity measurement to the inode an open fd holds, closing the swap-after-stat race on operator-writable paths. The Content-Security-Policy response-header parser now splits on the literal comma in linear time, removing a quadratic stall on a crafted header. Two configuration-validation paths (HTTP client pool options, database stream-limit) now throw the framework's typed error instead of a bare Error; both remain Error subclasses, so existing try/catch handling is unaffected. This refresh carries no shop-facing API change and applies no migration; it keeps the bundled framework current and tightens the security posture without adding any opt-in. **Changed:** *Vendored blamejs refreshed to 0.15.13* — The bundled framework is updated to blamejs 0.15.13. Webhook deliveries that hit a transient transport failure (connection reset, timeout, 5xx) now retry with backoff up to the configured limit instead of being dead-lettered as permanently failed; only the SSRF / blocked-host destination check is a permanent failure. An inline webhook delivery is claimed (marked in-flight before the POST) so a concurrent retry pass cannot double-send it, and a row left in-flight by a crash is reclaimed after the stale-claim window. The webhook deliveries table now creates on MySQL via a dialect-aware index. The audit checkpoint fired at database shutdown binds to the database it read the tip from and fail-closes (writes nothing) if that handle has since been closed or replaced. Every framework file read now uses a TOCTOU-safe reader (open fd, then bind size / contents / integrity to that inode), with symlink refusal, inode-equality, a byte cap, and an integrity hash available to callers. The Content-Security-Policy header parser splits on the literal comma in linear time (removing a quadratic-stall vector on a crafted header). Parsed INI and OpenAPI path maps are null-prototype objects, so a parser gap could only set an own property and never reach Object.prototype. HTTP-client pool-option and database stream-limit configuration errors now throw the module's typed framework error (still an Error subclass). No shop API change; the framework's PQC-first crypto, security middleware, and request lifecycle are carried forward as-is.
 
 - v0.4.56 (2026-06-14) — **Win-back campaigns: re-engage lapsed customers with an escalating sequence of offers.** A new operator console defines win-back campaigns that re-engage customers who have not ordered in a while. A campaign sets a lapse window and an escalating sequence of steps, each with its own delay and an optional coupon. A scheduled pass enrols customers who cross the lapse window and sends each due step through the store's email transport, minting the step's coupon. The send is gated for consent and deliverability: a customer who has withdrawn marketing-email consent or sits on the marketing suppression list is never emailed, and an opted-out customer is removed from the sequence so no later step reaches them — and if the suppression check itself is unavailable the send is held rather than risked. Each step is sent at most once even if two scheduled passes overlap. Campaigns are inert until an operator creates and activates one and the store's email transport is configured. No migration to apply. **Added:** *Win-back campaign console + scheduled send* — Operators can create, list, activate, pause, and archive win-back campaigns from a new loyalty/marketing console screen: a lapse window plus an escalating sequence of steps, each with a delay and an optional coupon (a single-use, per-customer discount code minted when the step sends). A scheduled pass scans for lapsed customers, enrols them, advances each enrolment through the sequence, sends the due step via the store's email transport, and records a delivery log and per-campaign metrics. Every send is consent- and suppression-gated: a customer who withdrew marketing-email consent or is on the marketing suppression list is never emailed and is dropped from the sequence; a suppression-check outage holds the send rather than risking an unwanted message. The scheduled pass is idempotent — a step is sent at most once even if two passes overlap. The feature is inert until a campaign is created and activated and the email transport is configured.

package/lib/affiliates.js

@@ -886,10 +886,27 @@ function create(opts) {
         refused.code = "AFFILIATE_COMMISSION_TRANSITION_REFUSED";
         throw refused;
       }
-      await query(
-        "UPDATE affiliate_commissions SET status = 'paid', paid_at = ?1, payout_reference = ?2 WHERE id = ?3",
+      // Atomic claim: the `AND status = 'pending'` predicate is the
+      // serialization point. The JS check above only refuses a
+      // SEQUENTIAL re-pay; two concurrent calls would both read
+      // 'pending' and both issue a payout reference. Gating the UPDATE
+      // on the status means exactly one caller transitions the row —
+      // the loser sees zero rows and is refused, so a second payout
+      // reference can never be issued for one commission.
+      var paidUpd = await query(
+        "UPDATE affiliate_commissions SET status = 'paid', paid_at = ?1, payout_reference = ?2 " +
+        "WHERE id = ?3 AND status = 'pending'",
         [paidAt, reference, id],
       );
+      if (Number(paidUpd.rowCount || 0) !== 1) {
+        var racedPaid = await _getCommissionRaw(id);
+        var refusedPaid = new Error(
+          "affiliates.markCommissionPaid: refused — commission is " +
+          (racedPaid ? racedPaid.status : "gone")
+        );
+        refusedPaid.code = "AFFILIATE_COMMISSION_TRANSITION_REFUSED";
+        throw refusedPaid;
+      }
       return await _getCommissionRaw(id);
     },
 
@@ -926,10 +943,24 @@ function create(opts) {
         throw refused;
       }
       var ts = _now();
-      await query(
-        "UPDATE affiliate_commissions SET status = 'voided', voided_at = ?1, void_reason = ?2 WHERE id = ?3",
+      // Atomic claim (see markCommissionPaid). Gating on 'pending'
+      // stops a void from racing a concurrent pay — without it both
+      // transitions could fire, clobbering a paid row (and its payout
+      // reference) into 'voided', or vice versa.
+      var voidUpd = await query(
+        "UPDATE affiliate_commissions SET status = 'voided', voided_at = ?1, void_reason = ?2 " +
+        "WHERE id = ?3 AND status = 'pending'",
         [ts, reason, id],
       );
+      if (Number(voidUpd.rowCount || 0) !== 1) {
+        var racedVoid = await _getCommissionRaw(id);
+        var refusedVoid = new Error(
+          "affiliates.markCommissionVoided: refused — commission is " +
+          (racedVoid ? racedVoid.status : "gone")
+        );
+        refusedVoid.code = "AFFILIATE_COMMISSION_TRANSITION_REFUSED";
+        throw refusedVoid;
+      }
       return await _getCommissionRaw(id);
     },
 

package/lib/api-keys.js

@@ -558,11 +558,26 @@ function create(opts) {
       var placeholderHash = b.crypto.namespaceHash(
         "api-key-rotated-placeholder", current.id + ":" + ts
       );
-      await query(
+      // Atomic claim: gate the active->rotated transition on the row
+      // still being 'active'. The JS status check above only refuses a
+      // sequential re-rotate; two concurrent rotates would both pass it
+      // and both issue a replacement key (credential over-issuance).
+      // The `AND status = 'active'` predicate lets exactly one caller
+      // claim the rotation — the loser is refused before any new key is
+      // minted.
+      var rotateClaim = await query(
         "UPDATE api_keys SET status = 'rotated', rotated_at = ?1, " +
-        "token_hash_previous = ?2, token_hash = ?3 WHERE id = ?4",
+        "token_hash_previous = ?2, token_hash = ?3 WHERE id = ?4 AND status = 'active'",
         [ts, current.token_hash, placeholderHash, id],
       );
+      if (Number(rotateClaim.rowCount || 0) !== 1) {
+        var lost = await _getRaw(id);
+        var refusedRotate = new Error(
+          "apiKeys.rotate: refused — key is " + (lost ? lost.status : "gone")
+        );
+        refusedRotate.code = "API_KEY_NOT_ROTATABLE";
+        throw refusedRotate;
+      }
 
       // Issue the replacement row. Scopes / rate-limit / expiry /
       // owner all carry forward verbatim — rotation is plaintext-only.

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.57",
+  "version": "0.4.58",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-imfe0otYErcB8rr2h6KLSGTtStirysptpXETSPY4zLv3bZoIT75Lo1dOvkOav+xL",

package/lib/backorder.js

@@ -322,10 +322,20 @@ function create(opts) {
           ", only pending lines can be fulfilled");
       }
       var ts = _now();
-      await query(
-        "UPDATE backorder_lines SET status = 'fulfilled', fulfilled_at = ?1 WHERE id = ?2",
+      // Atomic claim: gate on `status = 'pending'`. The JS check above
+      // only refuses a sequential re-fulfill; two concurrent calls
+      // would both pass it and both decrement the per-SKU counter for
+      // one line (a double debit). Claiming the line first means the
+      // counter is only debited by the caller that won the transition.
+      var fulfillClaim = await query(
+        "UPDATE backorder_lines SET status = 'fulfilled', fulfilled_at = ?1 " +
+        "WHERE id = ?2 AND status = 'pending'",
         [ts, line.id],
       );
+      if (Number(fulfillClaim.rowCount || 0) !== 1) {
+        throw new TypeError("backorder.fulfillBackorder: line is no longer pending " +
+          "(concurrently fulfilled or cancelled)");
+      }
       // MAX(0, ...) clamps the counter so an out-of-band counter
       // corruption (operator hand-edited a row) can't drive it
       // negative. The CHECK constraint on pending_quantity would
@@ -359,11 +369,18 @@ function create(opts) {
           ", only pending lines can be cancelled");
       }
       var ts = _now();
-      await query(
+      // Atomic claim (see fulfillBackorder): gate on `status = 'pending'`
+      // so a cancel racing a concurrent fulfill/cancel can't double-debit
+      // the per-SKU counter for one line.
+      var cancelClaim = await query(
         "UPDATE backorder_lines SET status = 'cancelled', reason = ?1, cancelled_at = ?2 " +
-        "WHERE id = ?3",
+        "WHERE id = ?3 AND status = 'pending'",
         [reason, ts, line.id],
       );
+      if (Number(cancelClaim.rowCount || 0) !== 1) {
+        throw new TypeError("backorder.cancelBackorder: line is no longer pending " +
+          "(concurrently fulfilled or cancelled)");
+      }
       await query(
         "UPDATE backorder_skus SET pending_quantity = MAX(0, pending_quantity - ?1), " +
         "updated_at = ?2 WHERE sku = ?3",

package/lib/click-and-collect.js

@@ -581,12 +581,21 @@ function create(opts) {
       }
 
       var now = _now();
-      await query(
+      // Atomic claim: gate on `status = 'ready'`. The JS status check
+      // above only refuses a sequential re-pickup; two concurrent
+      // markPickedUp calls would both pass it and both drive the parent
+      // order FSM to `delivered`. Claiming the schedule first means
+      // exactly one caller advances the order.
+      var pickupClaim = await query(
         "UPDATE pickup_schedules SET status = 'picked_up', picked_up_at = ?1, " +
         "signature_hash = ?2, customer_id_proof_kind = ?3, updated_at = ?4 " +
-        "WHERE order_id = ?5",
+        "WHERE order_id = ?5 AND status = 'ready'",
         [input.picked_up_at, sigHash, proofKind, now, orderId],
       );
+      if (Number(pickupClaim.rowCount || 0) !== 1) {
+        throw new TypeError("click-and-collect.markPickedUp: schedule is no longer ready " +
+          "(concurrently picked up)");
+      }
 
       // Drive the parent order FSM to `delivered` so the order really
       // reaches its terminal state when the goods leave the store.

package/lib/credit-limits.js

@@ -61,10 +61,10 @@
  *
  *   Monotonic per-customer `occurred_at`: two writes in the same
  *   millisecond would tie and make the "latest row" ambiguous for
- *   the denormalized balance read. `_resolveOccurredAt` bumps the
- *   requested timestamp to `prior + 1` on collision, guaranteeing
- *   strict monotonicity in the `(customer_id, occurred_at DESC)`
- *   index.
+ *   the denormalized balance read. Every ledger append bumps the
+ *   requested timestamp to `prior + 1` on collision (in-statement,
+ *   atomically with the write), guaranteeing strict monotonicity in
+ *   the `(customer_id, occurred_at DESC)` index.
  *
  *   Surface:
  *     - defineAccount({ customer_id, credit_limit_minor, currency,
@@ -249,27 +249,58 @@ function create(opts) {
     return { balance: r.rows[0].balance_after_minor, occurred_at: r.rows[0].occurred_at };
   }
 
-  // Two writes against the same customer in the same millisecond
-  // would tie on `occurred_at` and make the "latest row" ambiguous
-  // for denormalized-balance reads. Bump to `prior + 1` on
-  // collision; the result is a strictly-monotonic per-customer
-  // `occurred_at` sequence in the `(customer_id, occurred_at DESC)`
-  // index.
-  function _resolveOccurredAt(requestedTs, latestTs) {
-    if (latestTs == null) return requestedTs;
-    if (requestedTs > latestTs) return requestedTs;
-    return latestTs + 1;
-  }
-
-  async function _writeTxn(customerId, kind, orderId, amountMinor, balanceAfter, paymentRef, ts) {
+  // Shared subquery for the customer's current outstanding balance —
+  // the denormalized `balance_after_minor` of their latest transaction.
+  // References ?2 (customer_id), so every _appendTxnAtomic call binds
+  // customer_id as the second parameter.
+  var _BAL_SUB = "COALESCE((SELECT balance_after_minor FROM credit_transactions " +
+                 "WHERE customer_id = ?2 ORDER BY occurred_at DESC LIMIT 1), 0)";
+
+  // Append a ledger transaction ATOMICALLY. The new balance, the
+  // strictly-monotonic occurred_at, and the operation's invariant
+  // (credit limit / sufficient balance / outstanding charge) are all
+  // evaluated inside one INSERT ... SELECT ... WHERE statement, so the
+  // read of the latest balance can't be separated from the write that
+  // depends on it. SQLite serializes writers, so a second concurrent
+  // append sees the first's committed row: the denormalized running
+  // balance chains correctly and an invariant can't be bypassed by
+  // interleaving. (The racy read-check-write this replaced let two
+  // concurrent charges both pass the limit check, exceed the limit,
+  // and stamp the same balance_after — permanently under-stating
+  // exposure.) `guardExpr` false -> zero rows inserted -> returns
+  // null, and the caller raises its own typed refusal after a re-read.
+  //
+  // Fixed params: ?1 id, ?2 customer_id, ?3 kind, ?4 order_id,
+  // ?5 requested occurred_at, ?6 payment_ref. amountExpr / afterExpr /
+  // guardExpr may reference _BAL_SUB and bind extra params from ?7 up.
+  async function _appendTxnAtomic(customerId, kind, orderId, paymentRef, requestedTs,
+                                  amountExpr, afterExpr, guardExpr, extraParams) {
     var id = b.uuid.v7();
-    await query(
+    var tsSub = "COALESCE((SELECT occurred_at FROM credit_transactions " +
+                "WHERE customer_id = ?2 ORDER BY occurred_at DESC LIMIT 1), 0)";
+    // Strictly-monotonic per-customer occurred_at: bump to prior + 1 on
+    // a same-ms collision so the "latest row" stays unambiguous for the
+    // denormalized-balance reads.
+    var tsExpr = "CASE WHEN ?5 > " + tsSub + " THEN ?5 ELSE " + tsSub + " + 1 END";
+    var params = [id, customerId, kind, orderId, requestedTs, paymentRef].concat(extraParams || []);
+    var res = await query(
       "INSERT INTO credit_transactions " +
       "(id, customer_id, kind, order_id, amount_minor, balance_after_minor, payment_ref, occurred_at) " +
-      "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
-      [id, customerId, kind, orderId, amountMinor, balanceAfter, paymentRef, ts],
+      "SELECT ?1, ?2, ?3, ?4, " + amountExpr + ", " + afterExpr + ", ?6, " + tsExpr + " " +
+      "WHERE " + guardExpr,
+      params,
     );
-    return id;
+    if (Number(res.rowCount || 0) === 0) return null;
+    var row = (await query(
+      "SELECT amount_minor, balance_after_minor, occurred_at FROM credit_transactions WHERE id = ?1",
+      [id],
+    )).rows[0];
+    return {
+      id:                  id,
+      amount_minor:        row.amount_minor,
+      balance_after_minor: row.balance_after_minor,
+      occurred_at:         row.occurred_at,
+    };
   }
 
   async function _requireActive(customerId, op) {
@@ -475,29 +506,48 @@ function create(opts) {
       var requested  = _epochMs(input.occurred_at, "occurred_at");
       if (requested == null) requested = _now();
 
-      var acct   = await _requireActive(customerId, "chargeOrder");
-      var latest = await _readLatestTxn(customerId);
-      var after  = latest.balance + amount;
-      if (after > acct.credit_limit_minor) {
+      // Fast pre-check for a clean NOT_FOUND / NOT_ACTIVE error; the
+      // credit-limit invariant itself is enforced atomically in the
+      // INSERT guard below (re-checking status = 'active' there too),
+      // so a charge can't slip past the limit by racing another charge.
+      await _requireActive(customerId, "chargeOrder");
+      var written = await _appendTxnAtomic(
+        customerId, "charge", orderId, null, requested,
+        "?7",                                    // amount_minor: the charge
+        _BAL_SUB + " + ?7",                      // balance_after = outstanding + amount
+        "(" + _BAL_SUB + " + ?7) <= COALESCE((SELECT credit_limit_minor " +
+          "FROM credit_accounts WHERE customer_id = ?2 AND status = 'active'), -1)",
+        [amount],
+      );
+      if (!written) {
+        // Guard refused. Re-read to report precisely: a status change
+        // since the pre-check (rare race with suspend/close) vs the
+        // limit being exceeded.
+        var acctNow = await _readAccount(customerId);
+        if (!acctNow || acctNow.status !== "active") {
+          var na = new Error("creditLimits.chargeOrder: account status is " +
+            (acctNow ? acctNow.status : "missing") + " — operation refused");
+          na.code = acctNow ? "CREDIT_ACCOUNT_NOT_ACTIVE" : "CREDIT_ACCOUNT_NOT_FOUND";
+          throw na;
+        }
+        var curBal = (await _readLatestTxn(customerId)).balance;
         var over = new Error("creditLimits.chargeOrder: amount " + amount +
-          " would exceed credit limit (outstanding " + latest.balance +
-          " + amount " + amount + " > limit " + acct.credit_limit_minor + ")");
+          " would exceed credit limit (outstanding " + curBal +
+          " + amount " + amount + " > limit " + acctNow.credit_limit_minor + ")");
         over.code = "CREDIT_LIMIT_EXCEEDED";
-        over.outstanding_minor   = latest.balance;
-        over.credit_limit_minor  = acct.credit_limit_minor;
+        over.outstanding_minor   = curBal;
+        over.credit_limit_minor  = acctNow.credit_limit_minor;
         over.attempted_minor     = amount;
         throw over;
       }
-      var ts = _resolveOccurredAt(requested, latest.occurred_at);
-      var id = await _writeTxn(customerId, "charge", orderId, amount, after, null, ts);
       return {
-        id:                  id,
+        id:                  written.id,
         customer_id:         customerId,
         kind:                "charge",
         order_id:            orderId,
         amount_minor:        amount,
-        balance_after_minor: after,
-        occurred_at:         ts,
+        balance_after_minor: written.balance_after_minor,
+        occurred_at:         written.occurred_at,
       };
     },
 
@@ -527,50 +577,42 @@ function create(opts) {
         throw closed;
       }
 
-      // Sum the customer's net exposure to this order: charge +
-      // hold sums minus prior release sums. Refuse if zero (the
-      // order was never charged, or has already been fully
-      // released) — re-releasing would drive the balance below the
-      // genuine outstanding and corrupt the ledger.
-      var sumRow = (await query(
-        "SELECT " +
-        "  COALESCE(SUM(CASE WHEN kind IN ('charge', 'hold')   THEN amount_minor ELSE 0 END), 0) AS charged, " +
-        "  COALESCE(SUM(CASE WHEN kind = 'release' THEN amount_minor ELSE 0 END), 0) AS released " +
-        "FROM credit_transactions " +
-        "WHERE customer_id = ?1 AND order_id = ?2",
-        [customerId, orderId],
-      )).rows[0];
-      var charged  = sumRow ? sumRow.charged  : 0;
-      var released = sumRow ? sumRow.released : 0;
-      var remaining = charged - released;
-      if (remaining <= 0) {
+      // Net exposure to this order — charge + hold sums minus prior
+      // release sums — capped at the live balance, computed and written
+      // in ONE atomic statement. The racy read-sum-then-write this
+      // replaced let two concurrent releases (or a release racing a
+      // payment) both read the same remaining/balance and both write,
+      // double-releasing the order and corrupting the running balance.
+      // The guard refuses when nothing is outstanding (never charged /
+      // already fully released) or the balance is drained, so a release
+      // can't drive the ledger negative. Capping at _BAL_SUB stays
+      // defensive against operator-induced ledger drift.
+      var remainingSub = "COALESCE((SELECT SUM(CASE " +
+        "WHEN kind IN ('charge', 'hold') THEN amount_minor " +
+        "WHEN kind = 'release' THEN -amount_minor ELSE 0 END) " +
+        "FROM credit_transactions WHERE customer_id = ?2 AND order_id = ?4), 0)";
+      var toReleaseExpr = "CASE WHEN " + remainingSub + " < " + _BAL_SUB +
+        " THEN " + remainingSub + " ELSE " + _BAL_SUB + " END";
+      var written = await _appendTxnAtomic(
+        customerId, "release", orderId, null, requested,
+        toReleaseExpr,                                   // amount actually released
+        _BAL_SUB + " - (" + toReleaseExpr + ")",         // new balance
+        remainingSub + " > 0 AND " + _BAL_SUB + " > 0",  // nothing outstanding / drained -> refuse
+        [],
+      );
+      if (!written) {
         var nothing = new Error("creditLimits.releaseHold: no outstanding charge for order " + JSON.stringify(orderId));
         nothing.code = "CREDIT_RELEASE_NOT_FOUND";
         throw nothing;
       }
-
-      var latest = await _readLatestTxn(customerId);
-      // Cap the release at the outstanding balance — defensive
-      // against operator-induced ledger drift (a payment that
-      // somehow shrank the balance below the charge total
-      // shouldn't drive a release into negative territory).
-      var toRelease = remaining > latest.balance ? latest.balance : remaining;
-      if (toRelease <= 0) {
-        var drained = new Error("creditLimits.releaseHold: outstanding balance is zero — nothing to release");
-        drained.code = "CREDIT_RELEASE_NOT_FOUND";
-        throw drained;
-      }
-      var ts    = _resolveOccurredAt(requested, latest.occurred_at);
-      var after = latest.balance - toRelease;
-      var id    = await _writeTxn(customerId, "release", orderId, toRelease, after, null, ts);
       return {
-        id:                  id,
+        id:                  written.id,
         customer_id:         customerId,
         kind:                "release",
         order_id:            orderId,
-        amount_minor:        toRelease,
-        balance_after_minor: after,
-        occurred_at:         ts,
+        amount_minor:        written.amount_minor,
+        balance_after_minor: written.balance_after_minor,
+        occurred_at:         written.occurred_at,
       };
     },
 
@@ -594,31 +636,37 @@ function create(opts) {
       // customer with a closed account paying down their balance is
       // a legitimate AR workflow.
 
-      var latest = await _readLatestTxn(customerId);
-      // Refuse payments that exceed the outstanding balance —
+      // Refuse a payment that exceeds the outstanding balance —
       // credit-on-account-from-overpayment is a separate primitive
-      // (store-credit) and the operator must route the overage
-      // there explicitly rather than implicitly inflating the
-      // outstanding into negative territory.
-      if (amount > latest.balance) {
+      // (store-credit) and the operator must route the overage there
+      // explicitly rather than implicitly inflating the outstanding
+      // into negative territory. Enforced in the atomic INSERT guard so
+      // two concurrent payments can't both pass an outdated balance
+      // read and over-apply (driving the ledger negative).
+      var written = await _appendTxnAtomic(
+        customerId, "payment", null, paymentRef, requested,
+        "?7",                   // amount paid
+        _BAL_SUB + " - ?7",     // new balance
+        "?7 <= " + _BAL_SUB,    // amount <= outstanding, else refuse
+        [amount],
+      );
+      if (!written) {
+        var curBal = (await _readLatestTxn(customerId)).balance;
         var over = new Error("creditLimits.recordPayment: amount " + amount +
-          " exceeds outstanding balance " + latest.balance);
+          " exceeds outstanding balance " + curBal);
         over.code = "CREDIT_PAYMENT_EXCEEDS_OUTSTANDING";
-        over.outstanding_minor = latest.balance;
+        over.outstanding_minor = curBal;
         over.attempted_minor   = amount;
         throw over;
       }
-      var ts    = _resolveOccurredAt(requested, latest.occurred_at);
-      var after = latest.balance - amount;
-      var id    = await _writeTxn(customerId, "payment", null, amount, after, paymentRef, ts);
       return {
-        id:                  id,
+        id:                  written.id,
         customer_id:         customerId,
         kind:                "payment",
         amount_minor:        amount,
         payment_ref:         paymentRef,
-        balance_after_minor: after,
-        occurred_at:         ts,
+        balance_after_minor: written.balance_after_minor,
+        occurred_at:         written.occurred_at,
       };
     },
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.4.57",
+  "version": "0.4.58",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {