@blamejs/blamejs-shop 0.4.23 → 0.4.24

package/lib/quotes.js

@@ -764,17 +764,26 @@ function create(opts) {
 
       // Update header + each line. The line update sets
       // unit_price_minor + currency per-line so a future single-line
-      // re-quote (out of scope here) has a place to land.
-      await query(
+      // re-quote (out of scope here) has a place to land. The header
+      // UPDATE claims the requested -> responded transition atomically
+      // (`AND status = 'requested'`) so a concurrent cancel/respond can't
+      // both commit against the same row.
+      var claim = await query(
         "UPDATE quotes SET status = 'responded', shipping_minor = ?1, " +
         "tax_minor = ?2, total_minor = ?3, currency = ?4, valid_until = ?5, " +
         "operator_notes = ?6, " +
         "delivery_terms = COALESCE(?7, delivery_terms), " +
         "payment_terms  = COALESCE(?8, payment_terms),  " +
-        "updated_at = ?9 WHERE id = ?10",
+        "updated_at = ?9 WHERE id = ?10 AND status = 'requested'",
         [shipping, tax, total, currency, validUntil, operatorNotes,
          delivery, payment, ts, quoteId],
       );
+      if (Number(claim.rowCount || 0) !== 1) {
+        var raced = new Error("quotes.respondToQuote: refused — quote " + quoteId +
+          " is no longer in the requested state (settled by a concurrent call)");
+        raced.code = "QUOTE_TRANSITION_REFUSED";
+        throw raced;
+      }
       for (var j = 0; j < lines.length; j += 1) {
         var line = lines[j];
         await query(
@@ -810,11 +819,23 @@ function create(opts) {
         expired.code = "QUOTE_EXPIRED";
         throw expired;
       }
-      await query(
+      // Claim the responded -> accepted transition atomically. The in-memory
+      // FSM assert above only checks the row we read; the `AND status =
+      // 'responded'` clause is what serializes a concurrent double-accept (two
+      // customerAccept calls on one responded quote) and a withdraw-vs-accept
+      // race (an operator cancelQuote running alongside) — only one wins, so a
+      // single accept lands and a later convert can't fire twice.
+      var claim = await query(
         "UPDATE quotes SET status = 'accepted', accepted_at = ?1, " +
-        "accepted_by_customer = ?2, updated_at = ?1 WHERE id = ?3",
+        "accepted_by_customer = ?2, updated_at = ?1 WHERE id = ?3 AND status = 'responded'",
         [ts, acceptedBy, quoteId],
       );
+      if (Number(claim.rowCount || 0) !== 1) {
+        var raced = new Error("quotes.customerAccept: refused — quote " + quoteId +
+          " is no longer responded (accepted, rejected, or withdrawn by a concurrent call)");
+        raced.code = "QUOTE_TRANSITION_REFUSED";
+        throw raced;
+      }
       return await _hydrated(quoteId);
     },
 
@@ -835,11 +856,19 @@ function create(opts) {
       }
       _assertTransition(current.status, "reject", "customerReject");
       var ts = _now();
-      await query(
+      // Claim the responded -> rejected transition atomically so a concurrent
+      // accept / cancel can't both commit against the same responded quote.
+      var claim = await query(
         "UPDATE quotes SET status = 'rejected', rejected_at = ?1, " +
-        "reject_reason = ?2, updated_at = ?1 WHERE id = ?3",
+        "reject_reason = ?2, updated_at = ?1 WHERE id = ?3 AND status = 'responded'",
         [ts, reason, quoteId],
       );
+      if (Number(claim.rowCount || 0) !== 1) {
+        var raced = new Error("quotes.customerReject: refused — quote " + quoteId +
+          " is no longer responded (settled by a concurrent call)");
+        raced.code = "QUOTE_TRANSITION_REFUSED";
+        throw raced;
+      }
       return await _hydrated(quoteId);
     },
 
@@ -863,11 +892,24 @@ function create(opts) {
       }
       _assertTransition(current.status, "cancel", "cancelQuote");
       var ts = _now();
-      await query(
+      // Claim the (requested|responded) -> cancelled transition atomically.
+      // The `AND status IN (...)` clause closes the withdraw-vs-accept race:
+      // an operator cancelQuote and a customer customerAccept on the same
+      // responded quote can't both commit — whichever UPDATE lands first wins,
+      // and the loser refuses instead of silently clobbering the other side's
+      // transition (a cancel clobbering an accept would otherwise kill an
+      // order the operator thought was live, and vice-versa).
+      var claim = await query(
         "UPDATE quotes SET status = 'cancelled', cancelled_at = ?1, " +
-        "cancel_reason = ?2, updated_at = ?1 WHERE id = ?3",
+        "cancel_reason = ?2, updated_at = ?1 WHERE id = ?3 AND status IN ('requested', 'responded')",
         [ts, reason, quoteId],
       );
+      if (Number(claim.rowCount || 0) !== 1) {
+        var raced = new Error("quotes.cancelQuote: refused — quote " + quoteId +
+          " is no longer cancellable (accepted, rejected, or settled by a concurrent call)");
+        raced.code = "QUOTE_TRANSITION_REFUSED";
+        throw raced;
+      }
       return await _hydrated(quoteId);
     },
 
@@ -890,10 +932,45 @@ function create(opts) {
       }
       _assertTransition(current.status, "convert", "convertToOrder");
 
-      var lines = await _getLinesRaw(quoteId);
       var ts = _now();
+      // Claim the accepted -> converted transition atomically BEFORE placing
+      // inventory holds or creating the pending order. The in-memory FSM
+      // `_assertTransition` above only answers "is this edge legal for the row
+      // I read?" — two concurrent convertToOrder calls both read 'accepted'
+      // and both pass it. The conditional UPDATE is the real serialization
+      // point: only one matches `status = 'accepted'`, so only one mints holds
+      // + an order. (Without it both would create a pending order + double the
+      // inventory holds from a single accepted quote.) converted_order_id is
+      // backfilled once the order id is known; on any failure the claim is
+      // released back to 'accepted' so the operator can retry.
+      var claim = await query(
+        "UPDATE quotes SET status = 'converted', converted_at = ?1, updated_at = ?1 " +
+        "WHERE id = ?2 AND status = 'accepted'",
+        [ts, quoteId],
+      );
+      if (Number(claim.rowCount || 0) !== 1) {
+        var raced = new Error("quotes.convertToOrder: refused — quote " + quoteId +
+          " is no longer accepted (converted by a concurrent call)");
+        raced.code = "QUOTE_TRANSITION_REFUSED";
+        throw raced;
+      }
+
+      // Release the claim back to 'accepted' so a retry is possible after a
+      // downstream (hold / order-creation) failure leaves no order behind.
+      async function _releaseConvertClaim() {
+        try {
+          await query(
+            "UPDATE quotes SET status = 'accepted', converted_at = NULL, updated_at = ?1 " +
+            "WHERE id = ?2 AND status = 'converted' AND converted_order_id IS NULL",
+            [_now(), quoteId],
+          );
+        } catch (_e0) { /* drop-silent — the downstream error is the caller's signal */ }
+      }
+
+      var lines = await _getLinesRaw(quoteId);
       var orderId;
 
+      try {
       if (orderHandle) {
         // The order primitive requires cart_id + session_id as
         // UUID-shape inputs. For a quote-driven order, the operator
@@ -982,11 +1059,18 @@ function create(opts) {
         }
         orderId = input.converted_order_id;
       }
+      } catch (eConvert) {
+        // The claim already flipped status to 'converted'; nothing downstream
+        // produced an order, so release it back to 'accepted' for a retry.
+        await _releaseConvertClaim();
+        throw eConvert;
+      }
 
+      // Status + converted_at were claimed atomically above; backfill the
+      // resolved order id onto the (already-converted) quote.
       await query(
-        "UPDATE quotes SET status = 'converted', converted_at = ?1, " +
-        "converted_order_id = ?2, updated_at = ?1 WHERE id = ?3",
-        [ts, orderId, quoteId],
+        "UPDATE quotes SET converted_order_id = ?1, updated_at = ?2 WHERE id = ?3",
+        [orderId, _now(), quoteId],
       );
       return await _hydrated(quoteId);
     },
@@ -1145,10 +1229,18 @@ function create(opts) {
         notYet.code = "QUOTE_NOT_EXPIRED";
         throw notYet;
       }
-      await query(
-        "UPDATE quotes SET status = 'expired', updated_at = ?1 WHERE id = ?2",
+      // Claim the responded -> expired transition atomically so a concurrent
+      // accept / cancel can't both commit against the same responded quote.
+      var claim = await query(
+        "UPDATE quotes SET status = 'expired', updated_at = ?1 WHERE id = ?2 AND status = 'responded'",
         [asOf, quoteId],
       );
+      if (Number(claim.rowCount || 0) !== 1) {
+        var raced = new Error("quotes.markExpired: refused — quote " + quoteId +
+          " is no longer responded (settled by a concurrent call)");
+        raced.code = "QUOTE_TRANSITION_REFUSED";
+        throw raced;
+      }
       return await _hydrated(quoteId);
     },
   };

package/lib/referrals.js

@@ -452,6 +452,77 @@ function create(opts) {
       return out;
     },
 
+    // Reverse the funnel completion when the order that qualified it is
+    // refunded or cancelled — the counterpart to trackPurchase on an order's
+    // terminal refund / cancel edge. trackPurchase flips the invitation to
+    // `both-rewarded`, pins the first qualifying order, and bumps the
+    // referrer's leaderboard `referrals_count`; without this, a referred
+    // customer can buy (completing the funnel + ticking the leaderboard) then
+    // refund and keep the completion — buy-then-refund reward farming.
+    //
+    // Keyed on the ORDER id (first_order_id) — the qualifying purchase whose
+    // settlement is reversing the funnel. Rolls the invitation back to
+    // `pending`, clears first_purchase_at / first_order_id, and decrements the
+    // referrer's referrals_count (floored at zero by the schema CHECK + the
+    // `referrals_count > 0` guard). Unlike the money tenders this is BINARY,
+    // not pro-rata: a refund of the qualifying order — partial or full —
+    // un-completes the funnel (the purchase that earned the reward was
+    // reversed), so the operator's actual payouts (rewardReferrer /
+    // rewardReferee) are NOT touched here — they're separate instruments the
+    // operator claws back manually; this only rolls back the funnel state +
+    // the leaderboard counter the FSM auto-advanced.
+    //
+    // Idempotent + concurrency-safe: the invitation is claimed with
+    // `WHERE first_order_id = ? AND reversed_at IS NULL` so a re-delivered
+    // refund webhook reverses the funnel exactly once; a row whose
+    // reward_status is no longer `both-rewarded` (an operator already advanced
+    // it past trackPurchase) keeps its reward_status but still drops out of
+    // the leaderboard count. A no-op for an order that never completed a
+    // funnel (organic purchase, or one already reversed). Returns the reversed
+    // invitation row, or null when there was nothing to reverse.
+    reverseForOrder: async function (orderId) {
+      var oid = _uuid(orderId, "order_id");
+      var r = await query(
+        "SELECT id, referral_code_id, reward_status FROM referral_invitations " +
+        "WHERE first_order_id = ?1 AND reversed_at IS NULL LIMIT 1",
+        [oid],
+      );
+      if (!r.rows.length) return null;
+      var inv = r.rows[0];
+      var ts = _now();
+      // Claim the invitation — the reversed_at predicate is the
+      // serialization point so two concurrent reversals can't both
+      // decrement the leaderboard. Roll reward_status back to `pending`
+      // only from the `both-rewarded` completion trackPurchase set; an
+      // operator-advanced terminal (`expired` / `voided`) or an
+      // operator-issued payout state is left as the operator chose.
+      var claim = await query(
+        "UPDATE referral_invitations SET reversed_at = ?1, " +
+        "first_purchase_at = NULL, first_order_id = NULL, " +
+        "reward_status = CASE WHEN reward_status = 'both-rewarded' THEN 'pending' ELSE reward_status END " +
+        "WHERE id = ?2 AND reversed_at IS NULL",
+        [ts, inv.id],
+      );
+      if (Number(claim.rowCount || 0) === 0) return null;   // lost the claim
+      // Decrement the referrer's leaderboard count, floored at zero (the
+      // `> 0` guard plus the schema CHECK keep it non-negative even if the
+      // count drifted).
+      await query(
+        "UPDATE referral_codes " +
+        "SET referrals_count = referrals_count - 1, updated_at = ?1 " +
+        "WHERE id = ?2 AND referrals_count > 0",
+        [ts, inv.referral_code_id],
+      );
+      var after = await query(
+        "SELECT id, referral_code_id, reward_status, first_purchase_at, first_order_id, reversed_at " +
+        "FROM referral_invitations WHERE id = ?1",
+        [inv.id],
+      );
+      var out = after.rows[0] || null;
+      if (out) out.status = "reversed";
+      return out;
+    },
+
     // Operator records that the referrer payout has been issued.
     // `reward_id` is opaque (operator's gift-card id, discount-code
     // id, ledger-credit id — whatever instrument they chose). The

package/lib/security-middleware.js

@@ -103,6 +103,23 @@ var INTERNAL_BRIDGE_PATHS = [
   "/_/stale-order-reap",
 ];
 
+// Public well-known paths fetched by third-party verification crawlers
+// rather than browsers. Apple's Apple Pay domain-verification crawl GETs
+// the merchantid association file and is not guaranteed to send
+// Accept-Language, which the bot-guard's missing-Accept-Language heuristic
+// would 403 — silently hiding the Apple Pay button (the same
+// machine-caller-blocked-before-its-real-gate failure the worker→container
+// paths above hit). The file is a static, unauthenticated, state-free
+// public resource (the route 404s when unconfigured and only ever serves
+// the operator-supplied association bytes), so skipping the browser
+// fingerprint check on it weakens nothing. In production the crawl lands on
+// the edge Worker, which serves the file before any container hop; this
+// skip keeps a direct-to-container fetch (or an edge-serving-off deploy)
+// from refusing the verification crawl.
+var PUBLIC_WELL_KNOWN_PATHS = [
+  "/.well-known/apple-developer-merchantid-domain-association",
+];
+
 // The abusable endpoints — POST / auth surfaces where a human does
 // well under five requests a minute. Each gets its own per-client-IP
 // budget so a spray against one can't borrow another's headroom, and a
@@ -145,6 +162,12 @@ var TIGHT_PREFIXES = [
   "/orders/",
   "/stock-alert/",
   "/cart/coupon",
+  // Public suggestion box — anonymous submit + vote POSTs. The submit writes
+  // a free-text row and the vote bumps a counter; on the loose global bucket
+  // alone an anonymous sprayer could flood the backlog or grind a vote. The
+  // tight per-(IP+path) budget caps the rate. Container-only (CSRF-tokened),
+  // so it is NOT in EDGE_POST_PATHS — the page carries a per-session token.
+  "/suggestions",
 ];
 
 // Edge-served state-changing POST endpoints. These forms are rendered at
@@ -584,7 +607,9 @@ function globalRateLimitOpts() {
  */
 function botGuardOpts() {
   return {
-    skipPaths: INTERNAL_BRIDGE_PATHS.slice().concat([/^\/admin(\/|$)/]),
+    skipPaths: INTERNAL_BRIDGE_PATHS.slice()
+      .concat(PUBLIC_WELL_KNOWN_PATHS)
+      .concat([/^\/admin(\/|$)/]),
   };
 }
 
@@ -733,4 +758,5 @@ module.exports = {
   HEALTH_PATH:          HEALTH_PATH,
   TIGHT_PREFIXES:       TIGHT_PREFIXES,
   EDGE_POST_PATHS:      EDGE_POST_PATHS,
+  PUBLIC_WELL_KNOWN_PATHS: PUBLIC_WELL_KNOWN_PATHS,
 };

package/lib/stock-transfers.js

@@ -118,6 +118,70 @@ var TRANSFER_STATUSES = Object.freeze([
 var TRANSFER_ROLES    = Object.freeze(["origin", "destination"]);
 var TRANSFER_ORDER_KEY = ["opened_at:desc", "id:desc"];
 
+// The transfer lifecycle, modelled on b.fsm — the same composition the order
+// and quote primitives use (lib/order.js#_getOrderFsm, lib/quotes.js). The FSM
+// is the single source of truth for which (status, event) pairs are legal:
+// every status-changing verb replays the machine from the row's current status
+// and asks whether the edge is allowed before it touches the database, so an
+// illegal transition is refused identically regardless of which surface fired
+// it. Each event name maps 1:1 to the verb that fires it:
+//
+//   ship       open                 -> shipped     (markShipped)
+//   transit    shipped|in_transit   -> in_transit  (markInTransit; self-edge
+//                                                    keeps the scan-beat log)
+//   receive    shipped|in_transit   -> received    (markReceived)
+//   reconcile  received             -> reconciled  (reconcile; credits dest)
+//   except     open|shipped|in_transit|received
+//                                   -> exception   (markException)
+//
+// Terminal states (reconciled, exception) declare no outgoing edge, so the
+// machine itself refuses a double-reconcile / re-ship-after-exception without
+// a hand-written status check.
+var TRANSFER_TRANSITIONS = Object.freeze([
+  { from: "open",       to: "shipped",    on: "ship" },
+  { from: "shipped",    to: "in_transit", on: "transit" },
+  { from: "in_transit", to: "in_transit", on: "transit" },
+  { from: "shipped",    to: "received",   on: "receive" },
+  { from: "in_transit", to: "received",   on: "receive" },
+  { from: "received",   to: "reconciled", on: "reconcile" },
+  { from: "open",       to: "exception",  on: "except" },
+  { from: "shipped",    to: "exception",  on: "except" },
+  { from: "in_transit", to: "exception",  on: "except" },
+  { from: "received",   to: "exception",  on: "except" },
+]);
+
+var _transferFsm = null;
+function _getTransferFsm() {
+  if (_transferFsm) return _transferFsm;
+  // b.fsm emits audit events under the 'fsm' namespace — register it
+  // (idempotent) so the audit sink keeps the events instead of dropping them
+  // with a noisy warning, exactly as the order/quote FSMs do.
+  try { b.audit.registerNamespace("fsm"); } catch (_e) { /* idempotent; ignore */ }
+  _transferFsm = b.fsm.define({
+    name:    "stock_transfer",
+    initial: "open",
+    states: {
+      open:       {}, shipped:    {}, in_transit: {},
+      received:   {}, reconciled: {}, exception:  {},
+    },
+    transitions: TRANSFER_TRANSITIONS.map(function (t) {
+      return { from: t.from, to: t.to, on: t.on };
+    }),
+  });
+  return _transferFsm;
+}
+
+// Validate one status-changing edge through the FSM. Returns true when the
+// edge is legal from `fromStatus`, false otherwise. The verbs below use this
+// to decide whether to issue the atomic claim-guard UPDATE — they keep
+// throwing a TypeError on an illegal transition so the admin route's
+// `e instanceof TypeError -> 400` mapping (admin.js#_transferAction) stays
+// intact rather than surfacing a wrong-state as a 500.
+function _canTransfer(fromStatus, event) {
+  var fsm = _getTransferFsm();
+  return fsm.restore({ state: fromStatus, history: [], context: {} }).can(event);
+}
+
 // ---- validators ---------------------------------------------------------
 
 function _id(s, label) {
@@ -419,15 +483,21 @@ function create(opts) {
       if (!transfer) {
         throw new TypeError("stock-transfers.markShipped: transfer " + id + " not found");
       }
-      if (transfer.status !== "open") {
+      if (!_canTransfer(transfer.status, "ship")) {
         throw new TypeError("stock-transfers.markShipped: transfer is " + transfer.status +
           ", only open transfers can be shipped");
       }
-      await query(
+      // Claim the open -> shipped transition atomically — the WHERE status
+      // clause makes a concurrent double-ship a no-op for the loser.
+      var claim = await query(
         "UPDATE stock_transfers SET status = 'shipped', shipped_at = ?1, " +
-        "carrier = ?2, tracking_number = ?3 WHERE id = ?4",
+        "carrier = ?2, tracking_number = ?3 WHERE id = ?4 AND status = 'open'",
         [shippedAt, carrier, tracking, id],
       );
+      if (Number(claim.rowCount || 0) !== 1) {
+        throw new TypeError("stock-transfers.markShipped: transfer " + id +
+          " is no longer open (shipped by a concurrent call)");
+      }
       await _writeEvent(id, "ship", transfer.from_location, {
         carrier: carrier, tracking_number: tracking,
       }, shippedAt);
@@ -448,13 +518,17 @@ function create(opts) {
       if (!transfer) {
         throw new TypeError("stock-transfers.markInTransit: transfer " + id + " not found");
       }
-      if (transfer.status !== "shipped" && transfer.status !== "in_transit") {
+      if (!_canTransfer(transfer.status, "transit")) {
         throw new TypeError("stock-transfers.markInTransit: transfer is " + transfer.status +
           ", only shipped or in_transit transfers can record an in_transit scan");
       }
+      // Only the shipped -> in_transit edge flips status; the in_transit
+      // self-edge is an idempotent scan-beat that just appends an event. Claim
+      // the shipped -> in_transit flip with a WHERE status clause so two
+      // concurrent first-scans don't both believe they advanced the row.
       if (transfer.status === "shipped") {
         await query(
-          "UPDATE stock_transfers SET status = 'in_transit' WHERE id = ?1",
+          "UPDATE stock_transfers SET status = 'in_transit' WHERE id = ?1 AND status = 'shipped'",
           [id],
         );
       }
@@ -495,7 +569,7 @@ function create(opts) {
       if (!transfer) {
         throw new TypeError("stock-transfers.markReceived: transfer " + id + " not found");
       }
-      if (transfer.status !== "shipped" && transfer.status !== "in_transit") {
+      if (!_canTransfer(transfer.status, "receive")) {
         throw new TypeError("stock-transfers.markReceived: transfer is " + transfer.status +
           ", only shipped or in_transit transfers can be received");
       }
@@ -514,20 +588,44 @@ function create(opts) {
             " was not on the original transfer");
         }
       }
-      // Walk every shipped line; write quantity_received (defaulting
-      // to 0 for SKUs the operator didn't scan).
-      for (var u = 0; u < transfer.lines.length; u += 1) {
-        var line = transfer.lines[u];
-        var got  = Object.prototype.hasOwnProperty.call(rxMap, line.sku) ? rxMap[line.sku] : 0;
+      // Claim the (shipped|in_transit) -> received transition atomically
+      // BEFORE writing the per-line received quantities. Two concurrent
+      // receives both pass the read above, but only one UPDATE matches the
+      // expected status — the loser refuses, so a single set of
+      // quantity_received values lands and reconcile can't later credit twice.
+      var priorStatus = transfer.status;
+      var claim = await query(
+        "UPDATE stock_transfers SET status = 'received', received_at = ?1 " +
+        "WHERE id = ?2 AND status IN ('shipped', 'in_transit')",
+        [receivedAt, id],
+      );
+      if (Number(claim.rowCount || 0) !== 1) {
+        throw new TypeError("stock-transfers.markReceived: transfer " + id +
+          " is no longer shipped or in_transit (received by a concurrent call)");
+      }
+      // Walk every shipped line; write quantity_received (defaulting to 0 for
+      // SKUs the operator didn't scan). Each write is idempotent (the same
+      // quantity lands on a retry), so if a line throws the terminal claim is
+      // rolled back to its prior status — the transfer stays eligible for
+      // markReceived rather than stranding with partial / default quantities a
+      // later reconcile would then credit against.
+      try {
+        for (var u = 0; u < transfer.lines.length; u += 1) {
+          var line = transfer.lines[u];
+          var got  = Object.prototype.hasOwnProperty.call(rxMap, line.sku) ? rxMap[line.sku] : 0;
+          await query(
+            "UPDATE stock_transfer_lines SET quantity_received = ?1 WHERE id = ?2",
+            [got, line.id],
+          );
+        }
+      } catch (e) {
         await query(
-          "UPDATE stock_transfer_lines SET quantity_received = ?1 WHERE id = ?2",
-          [got, line.id],
+          "UPDATE stock_transfers SET status = ?1, received_at = NULL " +
+          "WHERE id = ?2 AND status = 'received'",
+          [priorStatus, id],
         );
+        throw e;
       }
-      await query(
-        "UPDATE stock_transfers SET status = 'received', received_at = ?1 WHERE id = ?2",
-        [receivedAt, id],
-      );
       await _writeEvent(id, "receive", transfer.to_location, {
         received_lines: input.received_lines,
       }, receivedAt);
@@ -546,48 +644,74 @@ function create(opts) {
       if (!transfer) {
         throw new TypeError("stock-transfers.reconcile: transfer " + id + " not found");
       }
-      if (transfer.status !== "received") {
+      // Refuse an illegal transition with a TypeError (kept for the route's
+      // 400 mapping). The status read here is only a fast-fail / clear-message
+      // path; the conditional claim-guard below is what actually serializes
+      // two concurrent reconciles.
+      if (!_canTransfer(transfer.status, "reconcile")) {
         throw new TypeError("stock-transfers.reconcile: transfer is " + transfer.status +
           ", only received transfers can be reconciled");
       }
       var ts = _now();
+      // Claim the received -> reconciled transition atomically BEFORE crediting
+      // the destination. Two concurrent reconciles both pass the read above,
+      // but only one UPDATE matches `status = 'received'` — the loser gets
+      // rowCount 0 and refuses, so the destination shelf is credited exactly
+      // once. (Without this guard both calls would credit, minting phantom
+      // inventory at the destination.)
+      var claim = await query(
+        "UPDATE stock_transfers SET status = 'reconciled', reconciled_at = ?1 " +
+        "WHERE id = ?2 AND status = 'received'",
+        [ts, id],
+      );
+      if (Number(claim.rowCount || 0) !== 1) {
+        throw new TypeError("stock-transfers.reconcile: transfer " + id +
+          " is no longer received (already reconciled by a concurrent call) — refusing to double-credit");
+      }
       var discrepancies = [];
-      // Credit the destination one line at a time. A failure here
-      // leaves the operator with a known-bad state: the receiving
-      // shelf is partially credited and the transfer is still
-      // 'received'. The operator can retry — every adjustStock that
-      // already landed shows up in the audit log so the second
-      // attempt won't double-credit because the FSM gate refuses
-      // reconcile on non-'received' status.
-      for (var i = 0; i < transfer.lines.length; i += 1) {
-        var line = transfer.lines[i];
-        var rx   = line.quantity_received == null ? 0 : line.quantity_received;
-        if (rx > 0) {
-          await locations.adjustStock({
-            sku: line.sku,
-            location_code: transfer.to_location,
-            delta: rx,
-            reason: "stock-transfer:reconcile:" + id,
-          });
+      // Credit the destination one line at a time. The claim above flipped the
+      // status, so a concurrent call can't reach this loop for the same
+      // transfer. Each line is skipped once its discrepancy column is stamped,
+      // so a retry (after the compensation below rolls the claim back) re-credits
+      // ONLY the lines that hadn't landed yet — no double-credit on the lines
+      // that already succeeded. If any line throws, the terminal claim is rolled
+      // back to 'received' so the transfer stays eligible for another reconcile
+      // that finishes the remaining credits, rather than stranding it.
+      try {
+        for (var i = 0; i < transfer.lines.length; i += 1) {
+          var line = transfer.lines[i];
+          if (line.discrepancy != null) continue;   // already credited on a prior attempt
+          var rx   = line.quantity_received == null ? 0 : line.quantity_received;
+          if (rx > 0) {
+            await locations.adjustStock({
+              sku: line.sku,
+              location_code: transfer.to_location,
+              delta: rx,
+              reason: "stock-transfer:reconcile:" + id,
+            });
+          }
+          var diff = line.quantity_shipped - rx;
+          await query(
+            "UPDATE stock_transfer_lines SET discrepancy = ?1 WHERE id = ?2",
+            [diff, line.id],
+          );
+          if (diff !== 0) {
+            discrepancies.push({
+              sku:               line.sku,
+              quantity_shipped:  line.quantity_shipped,
+              quantity_received: rx,
+              discrepancy:       diff,
+            });
+          }
         }
-        var diff = line.quantity_shipped - rx;
+      } catch (e) {
         await query(
-          "UPDATE stock_transfer_lines SET discrepancy = ?1 WHERE id = ?2",
-          [diff, line.id],
+          "UPDATE stock_transfers SET status = 'received', reconciled_at = NULL " +
+          "WHERE id = ?1 AND status = 'reconciled'",
+          [id],
         );
-        if (diff !== 0) {
-          discrepancies.push({
-            sku:               line.sku,
-            quantity_shipped:  line.quantity_shipped,
-            quantity_received: rx,
-            discrepancy:       diff,
-          });
-        }
+        throw e;
       }
-      await query(
-        "UPDATE stock_transfers SET status = 'reconciled', reconciled_at = ?1 WHERE id = ?2",
-        [ts, id],
-      );
       await _writeEvent(id, "reconcile", transfer.to_location, {
         discrepancies: discrepancies,
       }, ts);
@@ -612,15 +736,23 @@ function create(opts) {
       if (!transfer) {
         throw new TypeError("stock-transfers.markException: transfer " + id + " not found");
       }
-      if (transfer.status === "reconciled" || transfer.status === "exception") {
+      if (!_canTransfer(transfer.status, "except")) {
         throw new TypeError("stock-transfers.markException: transfer is " + transfer.status +
           ", terminal states cannot transition to exception");
       }
       var ts = _now();
-      await query(
-        "UPDATE stock_transfers SET status = 'exception', exception_reason = ?1 WHERE id = ?2",
+      // Claim the non-terminal -> exception transition atomically. The WHERE
+      // status clause refuses if a concurrent reconcile / exception already
+      // moved the row to a terminal state.
+      var claim = await query(
+        "UPDATE stock_transfers SET status = 'exception', exception_reason = ?1 " +
+        "WHERE id = ?2 AND status IN ('open', 'shipped', 'in_transit', 'received')",
         [reason, id],
       );
+      if (Number(claim.rowCount || 0) !== 1) {
+        throw new TypeError("stock-transfers.markException: transfer " + id +
+          " is no longer in a non-terminal state (settled by a concurrent call)");
+      }
       await _writeEvent(id, "exception", null, { reason: reason }, ts);
       return await _getHydrated(id);
     },