@blamejs/blamejs-shop 0.4.23 → 0.4.25

package/lib/asset-manifest.json

@@ -1,13 +1,13 @@
 {
-  "version": "0.4.23",
+  "version": "0.4.25",
   "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/compliance-export.js

@@ -115,6 +115,48 @@ var STATUSES       = Object.freeze([
   "received", "processing", "fulfilled", "delivered", "dismissed",
 ]);
 
+// Statutory response window per jurisdiction — the clock a supervisory
+// authority measures the controller against once a subject files the
+// request. The deadline is `requested_at + days`. GDPR Art. 12(3): one
+// month from receipt (encoded as 30 days — the controller-defensible
+// reading; extendable by two further months for complex requests, which an
+// operator records out of band). CCPA Cal. Civ. Code §1798.130(a)(2): 45
+// days (one 45-day extension permitted). LGPD Art. 19 §II / §3: 15 days for
+// the full declaration. `other` carries no statutory clock — the operator's
+// own SLA governs, so no deadline is surfaced rather than inventing one.
+//
+// This is the DSR-response analogue of b.breach.deadline (which encodes the
+// US-state breach-NOTIFICATION statutes — a different clock with different
+// citations); a subject-access response window has no entry in that
+// registry, so the per-jurisdiction window lives here keyed to the same
+// jurisdiction vocabulary the request rows already carry.
+var DSR_RESPONSE_WINDOW = Object.freeze({
+  gdpr: Object.freeze({ days: 30, statute: "GDPR Art. 12(3) (one month from receipt)" }),
+  ccpa: Object.freeze({ days: 45, statute: "Cal. Civ. Code §1798.130(a)(2)" }),
+  lgpd: Object.freeze({ days: 15, statute: "LGPD Art. 19 §II" }),
+  other: null,   // operator SLA governs — no statutory clock to surface
+});
+
+var MS_PER_DAY = b.constants.TIME.days(1);
+
+// Compute the statutory response deadline for a DSR request. Returns null
+// for a jurisdiction with no statutory clock (`other`) or a non-finite
+// requested-at. The shape mirrors b.breach.deadline.forStates entries —
+// `{ jurisdiction, days, due_by, statute }` — so a future operator clock
+// (b.breach.deadline.createClock-style escalation) can adapt it without a
+// reshape.
+function _statutoryDeadline(jurisdiction, requestedAtMs) {
+  var win = DSR_RESPONSE_WINDOW[jurisdiction];
+  if (!win) return null;
+  if (typeof requestedAtMs !== "number" || !isFinite(requestedAtMs)) return null;
+  return {
+    jurisdiction: jurisdiction,
+    days:         win.days,
+    due_by:       requestedAtMs + (win.days * MS_PER_DAY),
+    statute:      win.statute,
+  };
+}
+
 var MAX_REASON_LEN          = 4000;
 var MAX_DISMISS_REASON_LEN  = 4000;
 var MAX_DELIVERY_METHOD_LEN = 64;
@@ -264,6 +306,7 @@ function _isEmptySection(section) {
 
 function _hydrate(r) {
   if (!r) return null;
+  var requestedAt = Number(r.requested_at);
   return {
     id:               r.id,
     customer_id:      r.customer_id,
@@ -272,13 +315,19 @@ function _hydrate(r) {
     scope:            r.scope == null ? null : r.scope,
     status:           r.status,
     requested_by:     r.requested_by,
-    requested_at:     Number(r.requested_at),
+    requested_at:     requestedAt,
     fulfilled_at:     r.fulfilled_at == null ? null : Number(r.fulfilled_at),
     delivered_at:     r.delivered_at == null ? null : Number(r.delivered_at),
     dismiss_reason:   r.dismiss_reason == null ? null : r.dismiss_reason,
     delivery_method:  r.delivery_method == null ? null : r.delivery_method,
     delivery_address: r.delivery_address == null ? null : r.delivery_address,
     reason:           r.reason == null ? null : r.reason,
+    // Derived: the statutory response deadline the supervisory authority
+    // measures against (computed from jurisdiction + requested_at, never
+    // persisted — so it always reflects the current registry). Null for a
+    // jurisdiction with no statutory clock. The admin DSR console surfaces
+    // `due_by` so an operator sees the wall before it elapses.
+    statutory_deadline: _statutoryDeadline(r.jurisdiction, requestedAt),
   };
 }
 
@@ -658,10 +707,15 @@ function create(opts) {
 }
 
 module.exports = {
-  create:         create,
-  REQUEST_KINDS:  REQUEST_KINDS,
-  JURISDICTIONS:  JURISDICTIONS,
-  SCOPES:         SCOPES,
-  STATUSES:       STATUSES,
-  SCOPE_SECTIONS: SCOPE_SECTIONS,
+  create:               create,
+  REQUEST_KINDS:        REQUEST_KINDS,
+  JURISDICTIONS:        JURISDICTIONS,
+  SCOPES:               SCOPES,
+  STATUSES:             STATUSES,
+  SCOPE_SECTIONS:       SCOPE_SECTIONS,
+  // DSR statutory response-window registry + the per-request deadline
+  // calculator (the console reads the calculator's `due_by`; tests pin the
+  // per-jurisdiction windows).
+  DSR_RESPONSE_WINDOW:  DSR_RESPONSE_WINDOW,
+  statutoryDeadline:    _statutoryDeadline,
 };

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));
   }