@blamejs/blamejs-shop 0.4.23 → 0.4.24

package/lib/asset-manifest.json

@@ -1,13 +1,13 @@
 {
-  "version": "0.4.23",
+  "version": "0.4.24",
   "assets": {
     "css/admin.css": {
-      "integrity": "sha384-6k53cvkRrxMgmeStLIoLjVXZQHqIJgTmv1Izd8TYhh1HOC4POgE6GCvx1bsalyEP",
-      "fingerprinted": "css/admin.44eb97700c660798.css"
+      "integrity": "sha384-imfe0otYErcB8rr2h6KLSGTtStirysptpXETSPY4zLv3bZoIT75Lo1dOvkOav+xL",
+      "fingerprinted": "css/admin.6941d5151488a7c1.css"
     },
     "css/main.css": {
-      "integrity": "sha384-nRqjlZAYU5a0XVp9OWxcVw3zzZpj6vPcj+5XRf4byAgK49fg8W5QFx8vFLm40ldA",
-      "fingerprinted": "css/main.4eb7c53f87817566.css"
+      "integrity": "sha384-z6x2cNhNfsxxs7OZi3ZIg84HAcsJIUyhH4RjZwuHCdf03Rr68dm9zxciLgThkGLh",
+      "fingerprinted": "css/main.cf0a6763075ece73.css"
     },
     "js/announcement.js": {
       "integrity": "sha384-z4zcEMn+tScoVnYRE4nEf8N/oyvpxdpaxTNrT4QO/jURChid4+qjAvWkzatCaAPq",

package/lib/customers.js

@@ -167,6 +167,23 @@ function create(opts) {
     return b.crypto.namespaceHash(EMAIL_NAMESPACE, email);
   }
 
+  // Monotonic upsert of the per-customer session-revocation boundary. The
+  // INSERT-OR-conflict keeps the LATER of the existing and incoming value
+  // so two concurrent revokes (erasure + a passkey-revoke firing together)
+  // can never roll the boundary backwards and resurrect a cookie one of
+  // them meant to kill. `MAX(...)` on the conflict path is the conservation
+  // guard; `excluded` references the row the INSERT tried to add.
+  async function _bumpSessionRevocation(id, at) {
+    await query(
+      "INSERT INTO customer_session_revocations (customer_id, sessions_valid_from, updated_at) " +
+      "VALUES (?1, ?2, ?2) " +
+      "ON CONFLICT(customer_id) DO UPDATE SET " +
+      "sessions_valid_from = MAX(customer_session_revocations.sessions_valid_from, excluded.sessions_valid_from), " +
+      "updated_at = excluded.updated_at",
+      [id, at],
+    );
+  }
+
   var api = {
     EMAIL_NAMESPACE: EMAIL_NAMESPACE,
 
@@ -600,6 +617,12 @@ function create(opts) {
         );
         emailHashCleared = Number((upd && upd.rowCount) || 0);
       }
+      // Terminate every live sealed auth cookie for the erased account.
+      // Deleting the durable credentials stops a NEW session from being
+      // minted, but a cookie issued before erasure is stateless and stays
+      // valid for its 14-day TTL — so the anonymized account remains usable
+      // until then unless we move the revocation boundary forward now.
+      await _bumpSessionRevocation(id, ts);
       return {
         passkeys:            Number((pkDel && pkDel.rowCount) || 0),
         oauth_identities:    Number((oaDel && oaDel.rowCount) || 0),
@@ -607,6 +630,36 @@ function create(opts) {
       };
     },
 
+    // Move the customer's session-revocation boundary to `at` (default
+    // now). Every sealed auth cookie whose `iat` predates the boundary —
+    // and every pre-`iat` cookie once a boundary exists — fails the
+    // revocation check on its next authenticated request and signs out.
+    // Idempotent and monotonic: a later bump only ever moves the boundary
+    // forward, so two concurrent revokes can't roll it backwards. Used by
+    // erasure (above), passkey-revoke, and explicit sign-out.
+    revokeSessionsForCustomer: async function (id, at) {
+      _uuid(id, "customer id");
+      var boundary = (at == null) ? _now() : at;
+      if (!Number.isInteger(boundary) || boundary < 0) {
+        throw new TypeError("customers.revokeSessionsForCustomer: at must be a non-negative integer epoch-ms or null");
+      }
+      await _bumpSessionRevocation(id, boundary);
+      return { customer_id: id, sessions_valid_from: boundary };
+    },
+
+    // The customer's session-revocation boundary (epoch-ms), or 0 when no
+    // revocation has ever been recorded (the default-allow state). The
+    // auth-cookie reader compares the cookie's `iat` against this: a cookie
+    // is live when the boundary is 0, or when its `iat` is >= the boundary.
+    sessionsValidFrom: async function (id) {
+      _uuid(id, "customer id");
+      var row = (await query(
+        "SELECT sessions_valid_from FROM customer_session_revocations WHERE customer_id = ?1 LIMIT 1",
+        [id],
+      )).rows[0];
+      return row ? Number(row.sessions_valid_from) : 0;
+    },
+
     // Mutate a customer's editable profile fields. v1 covers display_name
     // only — the one field a customer can safely change without a
     // verification round trip.

package/lib/cycle-counting.js

@@ -576,6 +576,25 @@ function create(opts) {
         throw new TypeError("cycle-counting.finalizeCount: count is " + header.status +
           ", only scheduled or in_progress counts can be finalized");
       }
+      // Claim the (scheduled|in_progress) -> finalized transition atomically
+      // BEFORE computing variances or applying adjustments. Two concurrent
+      // finalizes both pass the read above, but only one UPDATE matches the
+      // expected status; the loser refuses, so the per-shelf adjustments are
+      // applied exactly once. (Without this guard both calls would write the
+      // variance adjustments through inventoryLocations.adjustStock, double-
+      // applying.) The final aggregate counts are stamped below once the loop
+      // has run.
+      var ts = _now();
+      var claim = await query(
+        "UPDATE cycle_counts SET status = 'finalized', finalized_at = ?1 " +
+        "WHERE slug = ?2 AND status IN ('scheduled', 'in_progress')",
+        [ts, input.slug],
+      );
+      if (Number(claim.rowCount || 0) !== 1) {
+        throw new TypeError("cycle-counting.finalizeCount: count " +
+          JSON.stringify(input.slug) + " is no longer scheduled or in_progress " +
+          "(finalized by a concurrent call)");
+      }
       var lines = await _getLines(input.slug);
       var varianceCount = 0;
       var varianceValueMinor = 0;
@@ -616,11 +635,12 @@ function create(opts) {
           }
         }
       }
-      var ts = _now();
+      // Status + finalized_at were already claimed above; stamp the computed
+      // aggregate variance totals onto the (now-finalized) header.
       await query(
-        "UPDATE cycle_counts SET status = 'finalized', variance_count = ?1, " +
-        "variance_value_minor = ?2, finalized_at = ?3 WHERE slug = ?4",
-        [varianceCount, varianceValueMinor, ts, input.slug],
+        "UPDATE cycle_counts SET variance_count = ?1, variance_value_minor = ?2 " +
+        "WHERE slug = ?3",
+        [varianceCount, varianceValueMinor, input.slug],
       );
       return {
         variance_count:       varianceCount,

package/lib/gift-card-ledger.js

@@ -72,6 +72,13 @@ var b = require("./vendor/blamejs");
 var KINDS    = ["credit", "debit", "expire"];
 var SOURCES  = ["purchase", "refund_to_giftcard", "promotional", "manual"];
 
+var SHA3_512_HEX_LEN = 128;
+// Genesis anchor for a card's first ledger row. Each gift card is its own
+// independent chain — the first row keyed by a `gift_card_id` links to
+// ZERO, every subsequent row links to the prior row's row_hash for the
+// SAME card.
+var ZERO_HASH = "0".repeat(SHA3_512_HEX_LEN);
+
 var MAX_SOURCE_REF_LEN = 128;
 // Source_ref / reason are short correlation handles (originating
 // order id, refund handle, campaign code, operator note). Refuse
@@ -130,6 +137,44 @@ function _epochMs(ts, label) {
 
 function _now() { return Date.now(); }
 
+// ---- chain hashing ------------------------------------------------------
+//
+// Mirrors operator-audit-log's composition exactly: the preimage is
+//
+//   row_hash = SHA3-512(prev_hash || canonical-json(row-fields))
+//
+// where row-fields is every persisted ledger column except prev_hash +
+// row_hash. `b.auditChain.canonicalize` (RFC 8785 walker, sorted keys,
+// hash columns excluded) makes the preimage byte-identical across
+// deployments + node versions. We deliberately do NOT use
+// b.auditChain.computeRowHash / verifyChain — those expect camelCase
+// rowHash / monotonicCounter / nonce columns this snake_case schema does
+// not carry; composing canonicalize + sha3Hash directly is the
+// snake_case-compatible path.
+
+function _rowFieldsForHash(row) {
+  return {
+    id:                  row.id,
+    gift_card_id:        row.gift_card_id,
+    kind:                row.kind,
+    amount_minor:        Number(row.amount_minor),
+    source:              row.source == null ? null : row.source,
+    source_ref:          row.source_ref == null ? null : row.source_ref,
+    order_id:            row.order_id == null ? null : row.order_id,
+    balance_after_minor: Number(row.balance_after_minor),
+    occurred_at:         Number(row.occurred_at),
+  };
+}
+
+function _computeRowHash(prevHash, rowFields) {
+  var canonical = b.auditChain.canonicalize(rowFields, ["prev_hash", "row_hash"]);
+  var preimage  = Buffer.concat([
+    Buffer.from(prevHash, "hex"),
+    Buffer.from(canonical, "utf8"),
+  ]);
+  return b.crypto.sha3Hash(preimage);
+}
+
 // ---- factory ------------------------------------------------------------
 
 function create(opts) {
@@ -158,12 +203,21 @@ function create(opts) {
   // `_resolveOccurredAt`).
   async function _readLatest(giftCardId) {
     var r = await query(
-      "SELECT balance_after_minor, occurred_at FROM gift_card_ledger " +
-      "WHERE gift_card_id = ?1 ORDER BY occurred_at DESC LIMIT 1",
+      "SELECT id, balance_after_minor, occurred_at, row_hash FROM gift_card_ledger " +
+      "WHERE gift_card_id = ?1 ORDER BY occurred_at DESC, id DESC LIMIT 1",
       [giftCardId],
     );
-    if (!r.rows.length) return { balance: 0, occurred_at: null };
-    return { balance: r.rows[0].balance_after_minor, occurred_at: r.rows[0].occurred_at };
+    if (!r.rows.length) return { id: null, balance: 0, occurred_at: null, row_hash: ZERO_HASH };
+    return {
+      id:          r.rows[0].id,
+      balance:     r.rows[0].balance_after_minor,
+      occurred_at: r.rows[0].occurred_at,
+      // A legacy pre-chain row carries NULL row_hash — chain forward from
+      // ZERO so the first hashed row anchors the chain; verifyChain treats
+      // the unhashed legacy prefix as unverifiable (NULL row_hash break)
+      // rather than silently trusting it.
+      row_hash:    r.rows[0].row_hash == null ? ZERO_HASH : r.rows[0].row_hash,
+    };
   }
 
   async function _currentBalance(giftCardId) {
@@ -187,13 +241,30 @@ function create(opts) {
     return latestTs + 1;
   }
 
-  async function _writeRow(giftCardId, kind, amountMinor, source, sourceRef, orderId, balanceAfter, ts) {
+  // credit() + expire() write through here: they already read the prior
+  // row (balance + occurred_at), so chaining is a straight read-then-write
+  // — `prevHash` is that prior row's row_hash, and row_hash is computed
+  // over the fully-resolved field tuple before the INSERT. debit() does
+  // NOT use this path: its overdraft guard must stay a single atomic
+  // statement, so it chains separately (see below).
+  async function _writeRow(giftCardId, kind, amountMinor, source, sourceRef, orderId, balanceAfter, ts, prevHash) {
     var id = b.uuid.v7();
+    var rowHash = _computeRowHash(prevHash, {
+      id:                  id,
+      gift_card_id:        giftCardId,
+      kind:                kind,
+      amount_minor:        amountMinor,
+      source:              source,
+      source_ref:          sourceRef,
+      order_id:            orderId,
+      balance_after_minor: balanceAfter,
+      occurred_at:         ts,
+    });
     await query(
       "INSERT INTO gift_card_ledger " +
-      "(id, gift_card_id, kind, amount_minor, source, source_ref, order_id, balance_after_minor, occurred_at) " +
-      "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)",
-      [id, giftCardId, kind, amountMinor, source, sourceRef, orderId, balanceAfter, ts],
+      "(id, gift_card_id, kind, amount_minor, source, source_ref, order_id, balance_after_minor, occurred_at, prev_hash, row_hash) " +
+      "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)",
+      [id, giftCardId, kind, amountMinor, source, sourceRef, orderId, balanceAfter, ts, prevHash, rowHash],
     );
     return id;
   }
@@ -216,7 +287,7 @@ function create(opts) {
       var latest = await _readLatest(giftCardId);
       var ts     = _resolveOccurredAt(requested, latest.occurred_at);
       var after  = latest.balance + amount;
-      var id = await _writeRow(giftCardId, "credit", amount, source, sourceRef, null, after, ts);
+      var id = await _writeRow(giftCardId, "credit", amount, source, sourceRef, null, after, ts, latest.row_hash);
 
       return {
         id:                  id,
@@ -334,7 +405,7 @@ function create(opts) {
       }
       var ts    = _resolveOccurredAt(requested, latest.occurred_at);
       var after = latest.balance - toBurn;
-      var id = await _writeRow(giftCardId, "expire", toBurn, null, reason, null, after, ts);
+      var id = await _writeRow(giftCardId, "expire", toBurn, null, reason, null, after, ts, latest.row_hash);
 
       return {
         id:                  id,

package/lib/giftcards.js

@@ -406,6 +406,94 @@ function create(opts) {
       return reversed;
     },
 
+    // Credit a card's spend back PROPORTIONALLY to a partial refund — the
+    // refund-by-amount counterpart to reverseRedemption's all-or-nothing
+    // (cancel) release. A full refund (cancel / payment-failed) returns the
+    // whole spend; a partial refund must return only the share the refund
+    // covers, or a 10%-refunded order would re-mint the entire gift-card
+    // value as spendable while the customer keeps 90% of the goods.
+    //
+    // For each redemption against the order the target cumulative reversal is
+    // floor(amount_minor * refunded_minor / order_total_minor), clamped to
+    // amount_minor so rounding + a refund that exceeds the recorded total can
+    // never credit back more than the card actually paid. The credit is the
+    // delta between that target and what's already been reversed
+    // (reversed_minor), so a partial-then-final refund sequence converges
+    // exactly on the spend without ever over-crediting. reversed_minor is
+    // advanced under a guarded UPDATE keyed on the row's live value, so two
+    // concurrent reversals can't both credit the same slice (the second sees
+    // its expected-prior value no longer matches and re-derives the delta as
+    // zero). A redemption that reaches full reversal also stamps reversed_at
+    // so the existing (binary) reverseRedemption short-circuits it.
+    //
+    // Returns the list of redemptions that received a non-zero credit, each
+    // with the minor-units credited this call — the caller writes the
+    // matching ledger credits. An order that used no gift card, or one
+    // already reversed up to the requested proportion, returns [].
+    reverseRedemptionProRata: async function (orderId, input) {
+      _uuid(orderId, "order_id");
+      input = input || {};
+      var refundedMinor = input.refunded_minor;
+      var orderTotalMinor = input.order_total_minor;
+      if (!Number.isInteger(refundedMinor) || refundedMinor < 0) {
+        throw new TypeError("giftcards.reverseRedemptionProRata: refunded_minor must be a non-negative integer (minor units)");
+      }
+      if (!Number.isInteger(orderTotalMinor) || orderTotalMinor <= 0) {
+        throw new TypeError("giftcards.reverseRedemptionProRata: order_total_minor must be a positive integer (minor units)");
+      }
+      // A refund can't exceed the order total; clamp the fraction at 1 so a
+      // recorded over-refund (rounding at the provider, a manual adjustment)
+      // never targets more than the full spend.
+      var effRefunded = refundedMinor > orderTotalMinor ? orderTotalMinor : refundedMinor;
+      var rows = (await query(
+        "SELECT id, giftcard_id, amount_minor, reversed_minor FROM giftcard_redemptions " +
+        "WHERE order_id = ?1",
+        [orderId],
+      )).rows;
+      var credited = [];
+      for (var i = 0; i < rows.length; i += 1) {
+        var red = rows[i];
+        var amount = Number(red.amount_minor);
+        var already = Number(red.reversed_minor || 0);
+        // Proportional target in minor units. floor so we never round UP
+        // into crediting a fraction the refund didn't cover; clamp to the
+        // full spend so cumulative reversals can't exceed it.
+        var target = Math.floor((amount * effRefunded) / orderTotalMinor);
+        if (target > amount) target = amount;
+        var delta = target - already;
+        if (delta <= 0) continue;   // already reversed to (or past) this proportion
+        var ts = _now();
+        var nowFull = target >= amount;
+        // Claim the slice: advance reversed_minor from its expected prior
+        // value so a concurrent reversal can't double-credit. Stamp
+        // reversed_at only when the redemption is now fully reversed (so the
+        // binary reverseRedemption treats it as done).
+        var claim = await query(
+          "UPDATE giftcard_redemptions SET reversed_minor = ?1, " +
+          "reversed_at = CASE WHEN ?2 = 1 THEN ?3 ELSE reversed_at END " +
+          "WHERE id = ?4 AND reversed_minor = ?5",
+          [target, nowFull ? 1 : 0, ts, red.id, already],
+        );
+        if (Number(claim.rowCount || 0) === 0) continue;   // lost the claim to a concurrent reversal
+        // Restore the spendable balance on the card row. Capped at the card's
+        // issued_minor by the schema CHECK; the cumulative reversed_minor is
+        // bounded by amount_minor, so it can't exceed the face value.
+        // Reactivate a card drained to `redeemed` — it carries balance again.
+        await query(
+          "UPDATE giftcards SET balance_minor = balance_minor + ?1, " +
+          "status = CASE WHEN status = 'redeemed' THEN 'active' ELSE status END, " +
+          "updated_at = ?2 WHERE id = ?3",
+          [delta, ts, red.giftcard_id],
+        );
+        credited.push({
+          redemption_id: red.id,
+          gift_card_id:  red.giftcard_id,
+          amount_minor:  delta,
+        });
+      }
+      return credited;
+    },
+
     "void": async function (id, opts2) {
       opts2 = opts2 || {};
       _uuid(id, "giftcard id");

package/lib/inventory-allocations.js

@@ -369,25 +369,44 @@ function create(opts) {
         " has no location_code — pin a location before commit");
     }
 
-    // Debit the committed shelf through inventoryLocations.adjustStock
-    // FIRST. If the shelf write fails (insufficient stock, unknown
-    // location), the hold row stays in 'held' status so a retry or
-    // a manual release decides next. Only after the debit lands does
-    // the hold flip to 'committed' — the audit trail then proves
-    // the commit happened.
-    await locations.adjustStock({
-      sku:           existing.sku,
-      location_code: existing.location_code,
-      delta:         -existing.quantity,
-      reason:        "hold-commit:" + existing.id + " order:" + input.order_id,
-    });
-
+    // Claim the held -> committed transition atomically BEFORE debiting the
+    // shelf. Two concurrent commits both pass the status read above, but only
+    // one UPDATE matches `status = 'held'`; the loser sees rowCount 0 and
+    // refuses, so the committed shelf is debited exactly once. (Without this
+    // guard both calls would debit the shelf, oversell.) The committed_order_id
+    // also lands now so the row's order pointer is set before the debit.
     var ts = _monotonicTs();
-    await query(
+    var claim = await query(
       "UPDATE inventory_holds SET status = 'committed', committed_at = ?1, " +
       "committed_order_id = ?2 WHERE id = ?3 AND status = 'held'",
       [ts, input.order_id, input.hold_id],
     );
+    if (Number(claim.rowCount || 0) !== 1) {
+      throw new TypeError("inventory-allocations.commitHold: hold " + existing.id +
+        " is no longer held (committed by a concurrent call)");
+    }
+
+    // Debit the committed shelf through inventoryLocations.adjustStock. If the
+    // shelf write fails (insufficient stock, unknown location), release the
+    // claim back to 'held' so a retry or a manual release decides next — the
+    // hold must not strand in 'committed' with no shelf movement behind it.
+    try {
+      await locations.adjustStock({
+        sku:           existing.sku,
+        location_code: existing.location_code,
+        delta:         -existing.quantity,
+        reason:        "hold-commit:" + existing.id + " order:" + input.order_id,
+      });
+    } catch (e) {
+      try {
+        await query(
+          "UPDATE inventory_holds SET status = 'held', committed_at = NULL, " +
+          "committed_order_id = NULL WHERE id = ?1 AND status = 'committed'",
+          [input.hold_id],
+        );
+      } catch (_e2) { /* drop-silent — the adjustStock error is the caller's signal */ }
+      throw e;
+    }
     return _shapeHold(await _getHoldRow(input.hold_id));
   }
 

package/lib/inventory-receive.js

@@ -78,6 +78,43 @@ var MAX_LIST_LIMIT  = 200;
 var RECEIPT_STATUSES = Object.freeze(["pending", "applied", "reversed"]);
 var RECEIPT_ORDER_KEY = ["received_at:desc", "id:desc"];
 
+// The receipt lifecycle, modelled on b.fsm — the same composition the order /
+// quote / stock-transfer primitives use. The FSM is the single source of truth
+// for which (status, event) pairs are legal:
+//
+//   apply    pending -> applied    (apply; restocks every line)
+//   reverse  applied -> reversed   (reverse; decrements every line back out)
+//
+// Terminal (reversed) declares no outgoing edge, so the machine itself refuses
+// a reverse-after-reverse. `apply` on an already-'applied' receipt is a
+// documented IDEMPOTENT no-op (returns { applied_count: 0 }) — apply() short-
+// circuits to that no-op before consulting the machine, preserving the
+// replay-safe contract callers depend on.
+var RECEIPT_TRANSITIONS = Object.freeze([
+  { from: "pending", to: "applied",  on: "apply" },
+  { from: "applied", to: "reversed", on: "reverse" },
+]);
+
+var _receiptFsm = null;
+function _getReceiptFsm() {
+  if (_receiptFsm) return _receiptFsm;
+  try { b.audit.registerNamespace("fsm"); } catch (_e) { /* idempotent; ignore */ }
+  _receiptFsm = b.fsm.define({
+    name:    "inventory_receipt",
+    initial: "pending",
+    states:  { pending: {}, applied: {}, reversed: {} },
+    transitions: RECEIPT_TRANSITIONS.map(function (t) {
+      return { from: t.from, to: t.to, on: t.on };
+    }),
+  });
+  return _receiptFsm;
+}
+
+function _canReceipt(fromStatus, event) {
+  var fsm = _getReceiptFsm();
+  return fsm.restore({ state: fromStatus, history: [], context: {} }).can(event);
+}
+
 // ---- validators ---------------------------------------------------------
 
 function _id(s, label) {
@@ -293,13 +330,32 @@ function create(opts) {
       if (!receipt) {
         throw new TypeError("inventory-receive.apply: receipt " + receiptId + " not found");
       }
-      if (receipt.status === "applied") {
-        // Idempotent — caller can replay without surprise.
-        return { id: receiptId, applied_count: 0, stock_changes: [] };
-      }
-      if (receipt.status !== "pending") {
+      // Preserve the idempotent no-op on an already-'applied' receipt: the
+      // FSM has no apply edge out of 'applied', so short-circuit here BEFORE
+      // asserting the transition (regression-safe replay contract — callers
+      // replay apply() without surprise).
+      if (!_canReceipt(receipt.status, "apply")) {
+        if (receipt.status === "applied") {
+          return { id: receiptId, applied_count: 0, stock_changes: [] };
+        }
         throw new TypeError("inventory-receive.apply: receipt is " + receipt.status + ", only pending receipts can be applied");
       }
+      // Claim the pending -> applied transition atomically BEFORE restocking.
+      // Two concurrent applies both pass the read above, but only one UPDATE
+      // matches `status = 'pending'`; the loser sees rowCount 0 and returns the
+      // idempotent no-op instead of double-restocking the catalog. (Without
+      // this guard both calls would restock every line, inflating
+      // stock_on_hand.)
+      var ts = _now();
+      var claim = await query(
+        "UPDATE inventory_receipts SET status = 'applied', updated_at = ?1 WHERE id = ?2 AND status = 'pending'",
+        [ts, receiptId],
+      );
+      if (Number(claim.rowCount || 0) !== 1) {
+        // A concurrent call won the claim and is restocking (or already did).
+        // Replay-safe no-op so the loser doesn't double-apply.
+        return { id: receiptId, applied_count: 0, stock_changes: [] };
+      }
       var stockChanges = [];
       var applied      = [];
       try {
@@ -310,8 +366,8 @@ function create(opts) {
           stockChanges.push({ sku: l.sku, qty: l.qty_received });
         }
       } catch (e) {
-        // Undo every successful restock so the database state matches
-        // the pre-apply snapshot. The receipt stays 'pending' so the
+        // Undo every successful restock so the database state matches the
+        // pre-apply snapshot, then release the claim back to 'pending' so the
         // operator can fix the offending line and retry.
         for (var j = applied.length - 1; j >= 0; j -= 1) {
           try {
@@ -321,15 +377,16 @@ function create(opts) {
             );
           } catch (_e3) { /* drop-silent — the original apply error is what the operator needs to fix */ }
         }
+        try {
+          await query(
+            "UPDATE inventory_receipts SET status = 'pending', updated_at = ?1 WHERE id = ?2 AND status = 'applied'",
+            [_now(), receiptId],
+          );
+        } catch (_e4) { /* drop-silent — the original apply error is the operator's signal */ }
         var err = new Error("inventory-receive.apply: restock failed — " + (e && e.message || e));
         err.cause = e;
         throw err;
       }
-      var ts = _now();
-      await query(
-        "UPDATE inventory_receipts SET status = 'applied', updated_at = ?1 WHERE id = ?2",
-        [ts, receiptId],
-      );
       return {
         id:            receiptId,
         applied_count: applied.length,
@@ -352,18 +409,55 @@ function create(opts) {
       if (!receipt) {
         throw new TypeError("inventory-receive.reverse: receipt " + receiptId + " not found");
       }
-      if (receipt.status !== "applied") {
+      if (!_canReceipt(receipt.status, "reverse")) {
         throw new TypeError("inventory-receive.reverse: receipt is " + receipt.status + ", only applied receipts can be reversed");
       }
+      // Claim the applied -> reversed transition atomically BEFORE decrementing.
+      // Two concurrent reverses both pass the read above, but only one UPDATE
+      // matches `status = 'applied'`; the loser refuses, so the shelf is
+      // decremented exactly once. (Without this guard both calls would
+      // decrement every line, destroying unrelated base stock.)
+      var claimTs = _now();
+      var claim = await query(
+        "UPDATE inventory_receipts SET status = 'reversed', updated_at = ?1 WHERE id = ?2 AND status = 'applied'",
+        [claimTs, receiptId],
+      );
+      if (Number(claim.rowCount || 0) !== 1) {
+        throw new TypeError("inventory-receive.reverse: receipt " + receiptId +
+          " is no longer applied (reversed by a concurrent call)");
+      }
       var stockChanges = [];
-      for (var i = 0; i < receipt.lines.length; i += 1) {
-        var l = receipt.lines[i];
-        var ts = _now();
+      var decremented  = [];
+      try {
+        for (var i = 0; i < receipt.lines.length; i += 1) {
+          var l = receipt.lines[i];
+          var ts = _now();
+          await query(
+            "UPDATE inventory SET stock_on_hand = MAX(0, stock_on_hand - ?1), updated_at = ?2 WHERE sku = ?3",
+            [l.qty_received, ts, l.sku],
+          );
+          decremented.push(l);
+          stockChanges.push({ sku: l.sku, qty: -l.qty_received });
+        }
+      } catch (e) {
+        // Compensate the decrements that already landed and release the claim so
+        // the receipt stays eligible for another reverse — otherwise a mid-loop
+        // failure strands it 'reversed' with only a partial stock rollback that
+        // the status check then refuses to retry.
+        for (var c = 0; c < decremented.length; c += 1) {
+          var dl = decremented[c];
+          try {
+            await query(
+              "UPDATE inventory SET stock_on_hand = stock_on_hand + ?1, updated_at = ?2 WHERE sku = ?3",
+              [dl.qty_received, _now(), dl.sku],
+            );
+          } catch (_compErr) { /* best-effort compensation; the claim release below restores retryability */ }
+        }
         await query(
-          "UPDATE inventory SET stock_on_hand = MAX(0, stock_on_hand - ?1), updated_at = ?2 WHERE sku = ?3",
-          [l.qty_received, ts, l.sku],
+          "UPDATE inventory_receipts SET status = 'applied', updated_at = ?1 WHERE id = ?2 AND status = 'reversed'",
+          [_now(), receiptId],
         );
-        stockChanges.push({ sku: l.sku, qty: -l.qty_received });
+        throw e;
       }
       // Append the reason into the receipt notes so the audit trail
       // carries the rationale. Operators that want a richer reversal
@@ -377,9 +471,11 @@ function create(opts) {
           newNotes = newNotes.slice(0, MAX_NOTES_LEN);
         }
       }
+      // Status was already flipped to 'reversed' by the atomic claim above;
+      // this write only stamps the reversal reason into the notes.
       var ts2 = _now();
       await query(
-        "UPDATE inventory_receipts SET status = 'reversed', notes = ?1, updated_at = ?2 WHERE id = ?3",
+        "UPDATE inventory_receipts SET notes = ?1, updated_at = ?2 WHERE id = ?3",
         [newNotes, ts2, receiptId],
       );
       return {