@blamejs/blamejs-shop 0.3.76 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,10 @@ Pre-1.0 the surface is intentionally evolving — every release may
 change something operators depend on. Read each entry before
 upgrading across more than a few patches at a time.
 
+## v0.4.x
+
+- v0.4.0 (2026-06-05) — **Inventory is enforced at the point of sale, completing the transactions, checkout, and analytics surface.** Stock levels were previously display-only: the product page showed honest availability, but nothing reserved inventory at checkout or debited it on a sale, so concurrent buyers could oversell a SKU and stock counts never moved. Checkout now places an atomic per-SKU hold before any charge — a sold-out line re-renders the form with a friendly message instead of charging — and the order lifecycle settles the hold: payment converts it to a real stock decrement (idempotent across webhook re-deliveries), cancellation releases it, and refunds deliberately leave restocking to the operator's judgment. Untracked SKUs remain unlimited, and pre-order campaigns keep their own reservation flow. The README previously described an oversell-prevention mechanism that was not actually wired; it now describes the real one. This minor release caps the transactions, checkout, and analytics arc: server-validated addresses and digital-cart checkout, discount codes with console authoring, gift cards, loyalty, store pickup, a dark-themed Stripe payment surface with express wallets and verified 3-D Secure, shipment tracking timelines, consent-gated funnel analytics with an admin dashboard, abandoned-cart visibility with honest recovery codes, operator error logs, and confirmation resends. Known, documented deferrals: customer receipt downloads (the confirmation page and signed email serve as the receipt), partial refunds from the browser console (the JSON API supports them), and a real-time new-order notification (the dashboard and outbound webhooks cover arrival today). **Added:** *Point-of-sale inventory enforcement* — Checkout reserves stock with an atomic conditional hold per shippable line before charging — insufficient stock re-renders the checkout with a clear message and charges nothing, and two concurrent buyers of the last unit resolve to exactly one sale. Payment converts holds into stock decrements, idempotently across webhook re-deliveries; cancelling a pending order releases its holds precisely, even when other shoppers hold the same SKU. Refunds do not auto-restock — returned goods re-enter stock through the operator's existing restock action, by judgment. SKUs without an inventory row remain available without limit, and pre-order campaigns are unaffected. The inventory primitive gains the hold and decrement operations its documentation previously described, and the README now reflects the actual oversell-prevention mechanism. **Changed:** *The 0.3 series rolls up* — This release follows nineteen 0.3.x patches that built out the commerce surface: server-side address validation with accessible per-field errors, digital-cart checkout without an address, delivery-date estimates, discount unlock codes with cart redemption and console authoring, full shipment-tracking timelines, consent-gated funnel analytics and an Analytics console screen, abandoned-cart visibility with single-use recovery codes, an operator-readable error log with a JSON API, order-confirmation resends, segment CSV exports, payment-processor TLS fixes verified by live payment, a dark-themed payment surface with express wallets, and a vendored-framework refresh. See the changelog for the full sequence.
+
 ## v0.3.x
 
 - v0.3.76 (2026-06-05) — **Abandoned-cart visibility in the admin console, with honest recovery.** The admin console gains a Carts screen showing abandoned carts: active carts with items whose last activity is older than a tunable window (twenty-four hours by default), listed freshest-first with line counts, subtotals, guest or signed-in attribution, and a value-at-risk summary. Recovery is built around what the privacy stance actually permits: buyer email addresses are stored only as one-way hashes, so a recovery email is impossible by design and the screen says so plainly. Instead, a per-cart action mints a single-use, code-gated percent-off discount — composing the existing unlock-code rules — and shows the code once for the operator to share through whatever channel they have. Fresh, empty, and converted carts are excluded; queries are window- and limit-bounded; the screen and its JSON shape are bearer-gated like every other console surface. **Added:** *Abandoned-carts screen with single-use recovery codes* — GET /admin/carts lists abandoned carts — active, containing items, idle past the window (tunable via the hours parameter, clamped to sane bounds) — with per-cart line counts, subtotal, last activity, and the customer link for signed-in carts, plus a count and value-at-risk summary. The per-cart Issue-code action creates a single-use unlock-code discount rule at the operator's chosen percentage and reveals the code once; the action is audited and appears only when the discounts primitive is wired. Session identifiers never appear in the JSON shape, and the screen states why no email recovery exists: addresses are one-way hashed.

package/README.md

@@ -43,7 +43,7 @@ node test/smoke.js
 
 - **Cloudflare deploy topology** — `Dockerfile` (multi-stage Node LTS, non-root, tini PID 1, vendor refresh + smoke run as build stages), `wrangler.toml` (Container + Worker + D1 + R2 + KV + Durable Objects), `worker/index.js` (edge router: health, asset pass-through, Stripe webhook signature pre-verification, D1 service-binding bridge, container forward, cold-start retry).
 - **`b.externalDb` adapter for Cloudflare D1** (`lib/externaldb-d1.js`) — service-binding + REST-API modes, normalized result envelope, AbortController timeouts, jittered retry on transient errors.
-- **`InventoryLock` Durable Object** — per-SKU serialization point so concurrent checkouts across container replicas can't oversell.
+- **Oversell-safe stock at checkout** — checkout reserves stock with an atomic conditional `UPDATE` (`held = held + qty WHERE on_hand - held >= qty`) before charging, converts the hold to a shelf debit when the order is paid, and releases it if the pending order is cancelled or expires; pre-order / backorder / digital lines are exempt. The conditional write is the serialization point, so two concurrent checkouts for the last unit can't both succeed — the loser gets a friendly out-of-stock re-prompt. An `InventoryLock` Durable Object ships as an optional per-SKU serialization aid for multi-replica deployments.
 - **`docs/deploy-cloudflare.md`** — operator deploy recipe end-to-end.
 - **Database backup & recovery** — D1 Time Travel gives 30 days of
   always-on point-in-time recovery; `npm run d1-export` (`scripts/d1-export.js`)

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.76",
+  "version": "0.4.0",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-6k53cvkRrxMgmeStLIoLjVXZQHqIJgTmv1Izd8TYhh1HOC4POgE6GCvx1bsalyEP",

package/lib/catalog.js

@@ -10,7 +10,8 @@
  *   - `products`   — create, get, bySlug, list, update, archive, restore
  *   - `variants`   — create, get, listForProduct, update, delete
  *   - `prices`     — set (versioned), current, history
- *   - `inventory`  — create, get, decrement, release, restock
+ *   - `inventory`  — create, get, list, hold, decrement, release,
+ *                    restock, setThreshold, checkLowStock
  *   - `media`      — attach, get, listForProduct, listForVariant, delete,
  *                    reorder, setPrimary
  *
@@ -679,10 +680,16 @@ function _inventoryModule(query, opts) {
       return { rows: (await query(sql, [limit])).rows };
     },
 
-    // Hot-path decrement happens via the Worker's InventoryLock
-    // Durable Object — this primitive is for admin restock / release
-    // operations that don't need the DO serialization. Concurrent
-    // decrements MUST go through the DO (see worker/index.js).
+    // `hold`, `decrement`, and `release` are the checkout-time stock
+    // primitives; `restock` and `setThreshold` are admin operations.
+    // Concurrency on the buy path is enforced by the conditional-UPDATE
+    // guards in `hold` / `decrement` (the WHERE clause refuses the write
+    // when stock is insufficient), so two racing confirms against the
+    // same SKU can never both succeed beyond the shelf. The container
+    // runs a single replica today; the guards are written to hold under
+    // N replicas without change — D1 applies each UPDATE atomically and
+    // the WHERE clause re-reads the row inside the same statement, so the
+    // check-and-set is a single SQL operation, not a read-then-write race.
     restock: async function (sku, qty) {
       _sku(sku);
       _positiveInt(qty, "qty");
@@ -714,6 +721,71 @@ function _inventoryModule(query, opts) {
       return await this.get(sku);
     },
 
+    // Place an atomic hold against available stock (on_hand − held).
+    // Called at checkout-confirm time, BEFORE the buyer is charged, so
+    // two concurrent confirms for the last unit can't both proceed. The
+    // conditional WHERE is the serialization point: D1 evaluates the
+    // `(stock_on_hand - stock_held) >= qty` predicate and applies the
+    // `stock_held = stock_held + qty` write in one atomic statement, so
+    // the second racer's predicate sees the first racer's increment and
+    // the UPDATE matches zero rows.
+    //
+    // Returns `{ held: true, sku, qty }` when the hold lands;
+    // `{ held: false, sku, qty }` when there's a row but it lacks the
+    // available stock (the caller renders the friendly out-of-stock
+    // message); `null` when the SKU has NO inventory row at all — an
+    // un-tracked SKU is treated as unlimited everywhere in the storefront
+    // (PDP, facets, edge all read a missing row as available), so a hold
+    // simply doesn't apply and the caller lets the line through.
+    hold: async function (sku, qty) {
+      _sku(sku);
+      _positiveInt(qty, "qty");
+      var ts = _now();
+      var r = await query(
+        "UPDATE inventory SET stock_held = stock_held + ?1, updated_at = ?2 " +
+        "WHERE sku = ?3 AND (stock_on_hand - stock_held) >= ?1",
+        [qty, ts, sku],
+      );
+      if (r.rowCount === 1) {
+        // Hold lowers available; a low-stock threshold may now trip.
+        await _afterMutation(sku);
+        return { held: true, sku: sku, qty: qty };
+      }
+      // Zero rows: either the SKU has no row, or it has a row but
+      // insufficient available stock. Distinguish so the caller can let
+      // an un-tracked SKU through while refusing a tracked-but-empty one.
+      var existing = await this.get(sku);
+      if (!existing) return null;
+      return { held: false, sku: sku, qty: qty };
+    },
+
+    // Convert a hold into a sale: debit on_hand and clear the matching
+    // held units in one atomic statement. Called on the order's paid
+    // transition. The `stock_held >= qty AND stock_on_hand >= qty` guard
+    // makes this a no-op for any SKU that was never held (an exempt or
+    // un-tracked line) and for a re-delivered paid event whose hold was
+    // already consumed — so it is idempotent: a second call against an
+    // already-debited SKU matches zero rows and returns `{ decremented:
+    // false }`. Both columns stay non-negative (the schema CHECKs would
+    // reject otherwise), so a bookkeeping drift can never write a
+    // negative shelf.
+    decrement: async function (sku, qty) {
+      _sku(sku);
+      _positiveInt(qty, "qty");
+      var ts = _now();
+      var r = await query(
+        "UPDATE inventory SET stock_on_hand = stock_on_hand - ?1, " +
+        "stock_held = stock_held - ?1, updated_at = ?2 " +
+        "WHERE sku = ?3 AND stock_held >= ?1 AND stock_on_hand >= ?1",
+        [qty, ts, sku],
+      );
+      if (r.rowCount === 1) {
+        await _afterMutation(sku);
+        return { decremented: true, sku: sku, qty: qty };
+      }
+      return { decremented: false, sku: sku, qty: qty };
+    },
+
     // Set / clear the per-SKU low-stock threshold. `threshold = null`
     // disables alerts for the SKU. Operators set this via the admin
     // API (`PATCH /admin/inventory/:sku/threshold`).

package/lib/checkout.js

@@ -234,6 +234,17 @@ function create(deps) {
   // Disabled when absent — the buy path is byte-identical to the un-wired
   // flow.
   var discountAllocation = deps.discountAllocation || null;
+  // Optional backorder + preorder handles. When wired, a line whose SKU
+  // is actively backorderable (`backorder.availabilityFor` →
+  // `backorderable`) or has an open pre-order campaign
+  // (`preorder.openCampaignForSku` → a row) is EXEMPT from the
+  // confirm-time stock hold: those flows deliberately sell beyond the
+  // shelf (the operator commits to ship later / the unit isn't released
+  // yet). Absent — no SKU is exempted on these grounds, which matches
+  // production today (neither primitive is mounted on the buy path);
+  // a SKU with no inventory row is still treated as unlimited regardless.
+  var backorder = deps.backorder || null;
+  var preorder  = deps.preorder  || null;
 
   // Reprice a list of cart lines through the quantity-discount engine.
   // Returns a shallow copy with `unit_amount_minor` overwritten by the
@@ -587,6 +598,80 @@ function create(deps) {
     }
   }
 
+  // Is this SKU exempt from the confirm-time stock hold? Pre-order and
+  // backorder lines deliberately sell beyond the shelf, so they pass
+  // through without a hold. Both lookups are optional (the handles may
+  // be unwired) and defensive — any read failure falls back to "not
+  // exempt" so a flaky lookup tightens (never loosens) enforcement.
+  async function _holdExempt(sku) {
+    if (preorder && typeof preorder.openCampaignForSku === "function") {
+      try {
+        if (await preorder.openCampaignForSku(sku)) return true;
+      } catch (_e) { /* not exempt on lookup failure */ }
+    }
+    if (backorder && typeof backorder.availabilityFor === "function") {
+      try {
+        var a = await backorder.availabilityFor(sku);
+        if (a && a.status === "backorderable") return true;
+      } catch (_e) { /* not exempt on lookup failure */ }
+    }
+    return false;
+  }
+
+  // Reserve stock for every shippable, non-exempt line BEFORE any charge.
+  // Each hold is an atomic conditional UPDATE (`catalog.inventory.hold`):
+  // the SKU's available stock (on_hand − held) must cover the line qty or
+  // the write matches zero rows. On the FIRST insufficient line we release
+  // every hold already placed in this pass and throw a coded
+  // INSUFFICIENT_STOCK error carrying a friendly, per-line message — the
+  // storefront re-renders the checkout form inline with that message, the
+  // same recoverable UX a rejected gift-card / loyalty code gets. Nothing
+  // is charged and no order row is created, so a refused checkout leaves
+  // zero side effects beyond the already-rolled-back holds.
+  //
+  // Digital lines (requires_shipping false) never debit stock. An
+  // un-tracked SKU (no inventory row) is unlimited (hold → null) and
+  // passes through. Each line that DID hold is annotated with `_held_qty`
+  // so the order line records the exact reserved quantity (the paid
+  // decrement + cancel release act on it). Returns the list of placed
+  // { sku, qty } holds so the caller can release them if a LATER step
+  // (gift-card burn, order create) throws before the order is committed.
+  async function _placeStockHolds(quoteLines) {
+    var placed = [];
+    for (var i = 0; i < quoteLines.length; i += 1) {
+      var l = quoteLines[i];
+      l._held_qty = 0;                                 // default: held nothing
+      if (!l.requires_shipping) continue;             // digital — no shelf
+      if (await _holdExempt(l.sku)) continue;          // preorder / backorder
+      var res = await catalog.inventory.hold(l.sku, l.qty);
+      if (res == null) continue;                       // un-tracked SKU — unlimited
+      if (res.held) { l._held_qty = l.qty; placed.push({ sku: l.sku, qty: l.qty }); continue; }
+      // Insufficient stock for this line — roll back the pass and refuse.
+      await _releaseStockHolds(placed);
+      var title = l.title || l.sku;
+      var refused = new Error("checkout: " + title + " — only a limited quantity is in stock. " +
+        "Lower the quantity or remove it to continue.");
+      refused.code = "INSUFFICIENT_STOCK";
+      refused.sku  = l.sku;
+      throw refused;
+    }
+    return placed;
+  }
+
+  // Best-effort release of a set of placed holds (the rollback path).
+  // Drop-silent per hold: a release failure must not mask the original
+  // error that triggered the rollback, and the TTL-free holds here are
+  // only ever consumed by the paid decrement or cleared by a cancel, so
+  // a missed release self-heals when the abandoned pending order is later
+  // cancelled / expired.
+  async function _releaseStockHolds(holds) {
+    if (!Array.isArray(holds)) return;
+    for (var i = 0; i < holds.length; i += 1) {
+      try { await catalog.inventory.release(holds[i].sku, holds[i].qty); }
+      catch (_e) { /* drop-silent — rollback best-effort */ }
+    }
+  }
+
   // Compose a quote from a cart + ship-to + (optional) selected
   // shipping service. Pure read — no DB writes.
   async function _buildQuote(input) {
@@ -726,10 +811,39 @@ function create(deps) {
         throw new TypeError("checkout.confirm: grand_total_minor must be > 0 (zero-total orders use a separate freebie flow)");
       }
 
-      // Resolve an optional gift-card credit BEFORE any charge so a
-      // bad code fails the checkout without touching Stripe. The
-      // credit reduces the amount due; the order still records the
-      // full grand total it owed.
+      // Reserve stock for every shippable, non-exempt line BEFORE any
+      // charge. Insufficient stock throws a coded INSUFFICIENT_STOCK error
+      // here (no PaymentIntent, no order) which the storefront re-renders
+      // inline. The holds placed here ride into the pending order and are
+      // converted to a real shelf debit on the paid transition (or released
+      // when the order is cancelled / expires). Everything AFTER this point
+      // runs inside a guard that releases the holds if a later step throws
+      // before the order is committed, so a refused gift-card / payment
+      // error never strands held stock.
+      var stockHolds = await _placeStockHolds(quote.lines);
+      try {
+        return await this._confirmAfterHolds(input, quote, email, stockHolds);
+      } catch (e) {
+        await _releaseStockHolds(stockHolds);
+        throw e;
+      }
+    },
+
+    // The body of confirm() once stock is held. Split out so the holds
+    // placed in confirm() release on any throw from here down via the
+    // single try/catch above — the two return paths (fully-credited and
+    // Stripe-intent) both live inside that guard. Internal — invoked only
+    // through confirm() above (hence the `_` prefix); `stockHolds` is the
+    // list of placed holds, which both terminal paths leave in place (the
+    // pending order owns them until paid / cancelled).
+    _confirmAfterHolds: async function (input, quote, email, stockHolds) {
+      // Already validated in confirm() above; re-read here since the PI
+      // creation moved into this split-out body.
+      var idempotencyKey = input.idempotency_key;
+      // Resolve an optional gift-card credit BEFORE any charge so a bad
+      // code fails the checkout without touching Stripe. The credit
+      // reduces the amount due; the order still records the full grand
+      // total it owed.
       var gc = await _resolveGiftCard(input.gift_card_code, quote);
       // Loyalty points credit stacks on top of any gift-card credit —
       // both reduce the same amount due. The loyalty credit is capped
@@ -760,6 +874,9 @@ function create(deps) {
           qty:               l.qty,
           unit_amount_minor: l.unit_amount_minor,
           unit_currency:     l.unit_currency,
+          // Units this line reserved at confirm (0 unless a hold landed) so
+          // the order's paid/cancel transitions settle the exact hold.
+          stock_held_qty:    l._held_qty || 0,
         };
       });
       // Reuse the cart row already fetched for the loyalty
@@ -968,6 +1085,13 @@ function create(deps) {
       if (quote.totals.grand_total_minor <= 0) {
         throw new TypeError("checkout.createPaypalOrder: grand_total_minor must be > 0");
       }
+      // Reserve stock before opening the PayPal order — same atomic holds
+      // the Stripe confirm places, so the two payment paths can't oversell
+      // against each other. Insufficient stock throws INSUFFICIENT_STOCK
+      // here (no PayPal order created). Released on any throw before the
+      // local order row commits.
+      var ppHolds = await _placeStockHolds(quote.lines);
+      try {
       // Resolve an optional gift-card credit before opening the PayPal
       // order so a bad code fails without a remote round-trip.
       var gc = await _resolveGiftCard(input.gift_card_code, quote);
@@ -975,7 +1099,7 @@ function create(deps) {
       var cartRow = await cart.get(quote.cart_id);
       var emailHash = customers ? customers.hashEmail(email) : null;
       var ppLines = quote.lines.map(function (l) {
-        return { variant_id: l.variant_id, sku: l.sku, qty: l.qty, unit_amount_minor: l.unit_amount_minor, unit_currency: l.unit_currency };
+        return { variant_id: l.variant_id, sku: l.sku, qty: l.qty, unit_amount_minor: l.unit_amount_minor, unit_currency: l.unit_currency, stock_held_qty: l._held_qty || 0 };
       });
 
       // Gift card fully covers the order — no PayPal order (PayPal
@@ -1028,6 +1152,12 @@ function create(deps) {
       if (gc) await _redeemGiftCard(gc, createdOrder.id);
       await cart.setStatus(quote.cart_id, "converted");
       return { order: createdOrder, paypal_order_id: ppOrder.id, status: ppOrder.status, gift_card: gc ? { applied_minor: gc.applied_minor, amount_due_minor: amountDue } : null };
+      } catch (e) {
+        // Any throw before the order row commits (PayPal open failure,
+        // gift-card error) releases the holds so PayPal can't strand stock.
+        await _releaseStockHolds(ppHolds);
+        throw e;
+      }
     },
 
     // Capture an approved PayPal order, then advance the local order to paid.

package/lib/order.js

@@ -128,6 +128,34 @@ function _shipTo(s) {
 
 function _now() { return Date.now(); }
 
+// Read the per-SKU stock-hold map an order recorded at creation time. It
+// lives in the `__init__` transition's metadata (`{ stock_holds: { sku:
+// qty } }`), written by createFromCart when the checkout reserved shelf
+// units. Returns `{}` for an order that held nothing (digital-only, an
+// inventory-less deploy, or an order created before this was wired) so the
+// settlement loop is a clean no-op. Defensive against a missing /
+// malformed metadata blob — a parse failure yields no holds rather than a
+// throw that would break a legitimate state transition.
+function _stockHoldMap(order) {
+  if (!order || !Array.isArray(order.transitions)) return {};
+  var init = null;
+  for (var i = 0; i < order.transitions.length; i += 1) {
+    if (order.transitions[i].from_state === "__init__") { init = order.transitions[i]; break; }
+  }
+  if (!init || !init.metadata_json) return {};
+  var parsed;
+  try { parsed = JSON.parse(init.metadata_json); }
+  catch (_e) { return {}; }
+  if (!parsed || typeof parsed.stock_holds !== "object" || !parsed.stock_holds) return {};
+  var out = {};
+  var skus = Object.keys(parsed.stock_holds);
+  for (var s = 0; s < skus.length; s += 1) {
+    var q = Number(parsed.stock_holds[skus[s]]);
+    if (Number.isInteger(q) && q > 0) out[skus[s]] = q;
+  }
+  return out;
+}
+
 // ---- factory ------------------------------------------------------------
 
 function create(opts) {
@@ -162,6 +190,25 @@ function create(opts) {
   // fire-and-forget on the same detached-promise discipline as the
   // loyalty fan-out: the transition has already persisted.
   var referrals = opts.referrals || null;
+  // Optional inventory handle — when present, the order FSM converts the
+  // confirm-time stock holds into real shelf movements as the order
+  // changes state. On `mark_paid` (pending → paid) each shippable line's
+  // held units are debited from on_hand via `inventory.decrement`; on
+  // `cancel` FROM PENDING (pending → cancelled — a never-paid order that
+  // timed out or the buyer abandoned) each line's hold is released via
+  // `inventory.release`. Both run SYNCHRONOUSLY inside the transition,
+  // before the fire-and-forget fan-outs, because stock truth is not
+  // best-effort: a paid order MUST debit the shelf and a cancelled
+  // pending order MUST free its hold. Both verbs are idempotent and
+  // self-targeting — `decrement` matches only lines that still hold the
+  // qty (so a re-delivered mark_paid is a no-op and an exempt / un-tracked
+  // line is skipped), and `release` only clears an active hold. Refund
+  // (paid → refunded) and cancel-after-paid (paid → cancelled) DO NOT
+  // touch inventory: a returned item is not automatically back on the
+  // shelf — the operator restocks via the admin inventory console once
+  // the physical return is inspected. Opt-in like the other handles so
+  // tests and an inventory-less deploy run unchanged.
+  var inventory = opts.inventory || null;
   // Pagination cursors for listForCustomer are HMAC-tagged via
   // b.pagination so an operator can't hand-craft one to skip past a
   // hidden order or replay across deployments. The secret defaults
@@ -215,10 +262,22 @@ function create(opts) {
           input.customer_email_hash || null, ts,
         ],
       );
+      // Accumulate the per-SKU stock-hold map as we write the lines. The
+      // checkout passes `stock_held_qty` on every line that reserved shelf
+      // units at confirm; lines that held nothing (digital / preorder /
+      // backorder / un-tracked SKU) contribute 0. The map is stamped onto
+      // the init-transition metadata below so the paid-time decrement and
+      // the cancel-time release settle exactly the units THIS order held —
+      // no schema column needed, and a cancel can never release stock that
+      // belongs to another shopper's hold on the same SKU.
+      var heldBySku = {};
       for (var i = 0; i < input.lines.length; i += 1) {
         var l = input.lines[i];
         _positiveInt(l.qty, "lines[" + i + "].qty");
         _nonNegInt(l.unit_amount_minor, "lines[" + i + "].unit_amount_minor");
+        var heldQty = l.stock_held_qty == null ? 0 : l.stock_held_qty;
+        _nonNegInt(heldQty, "lines[" + i + "].stock_held_qty");
+        if (heldQty > 0) heldBySku[l.sku] = (heldBySku[l.sku] || 0) + heldQty;
         await query(
           "INSERT INTO order_lines (id, order_id, variant_id, sku, qty, " +
           "unit_amount_minor, unit_currency, line_total_minor) " +
@@ -230,11 +289,14 @@ function create(opts) {
           ],
         );
       }
-      // Initial transition row — from no-prior-state into pending.
+      // Initial transition row — from no-prior-state into pending. Its
+      // metadata carries the stock-hold map (`{ stock_holds: { sku: qty } }`)
+      // so the FSM can settle the holds without a dedicated column.
+      var initMeta = Object.keys(heldBySku).length ? JSON.stringify({ stock_holds: heldBySku }) : "{}";
       await query(
         "INSERT INTO order_transitions (id, order_id, from_state, to_state, on_event, reason, metadata_json, occurred_at) " +
-        "VALUES (?1, ?2, '__init__', 'pending', 'create', ?3, '{}', ?4)",
-        [b.uuid.v7(), id, input.reason || null, ts],
+        "VALUES (?1, ?2, '__init__', 'pending', 'create', ?3, ?5, ?4)",
+        [b.uuid.v7(), id, input.reason || null, ts, initMeta],
       );
       return await this.get(id);
     },
@@ -301,6 +363,41 @@ function create(opts) {
         ],
       );
       var refreshed = await this.get(orderId);
+      // Inventory settlement — SYNCHRONOUS, before the fire-and-forget
+      // fan-outs below. Stock truth is not best-effort: a paid order debits
+      // the shelf, a cancelled-while-pending order frees its hold. The
+      // edge (result.from → result.to) is authoritative, so this runs once
+      // per real state change — a re-delivered webhook is collapsed to a
+      // no-op transition upstream (the FSM refuses a second mark_paid from
+      // `paid`), and the underlying verbs are idempotent regardless. Only
+      // the two edges that own a hold act; refund and cancel-after-paid are
+      // deliberately inert (the operator restocks a physical return by hand).
+      if (inventory) {
+        var holdMap = _stockHoldMap(refreshed);
+        var holdSkus = Object.keys(holdMap);
+        if (holdSkus.length) {
+          if (result.from === "pending" && result.to === "paid"
+              && typeof inventory.decrement === "function") {
+            // Convert each held SKU's reservation into a real shelf debit,
+            // scoped to the exact units this order held. decrement's own
+            // guard (stock_held >= qty) makes a re-delivered mark_paid a
+            // no-op, so this is idempotent across webhook re-deliveries.
+            for (var di = 0; di < holdSkus.length; di += 1) {
+              await inventory.decrement(holdSkus[di], holdMap[holdSkus[di]]);
+            }
+          } else if (result.from === "pending" && result.to === "cancelled"
+              && typeof inventory.release === "function") {
+            // Free the holds of a pending order that never paid (timed out,
+            // payment_intent.canceled, or an explicit cancel), scoped to the
+            // exact units this order held so a cancel can never release stock
+            // another shopper holds on the same SKU. release floors at zero
+            // so a double-cancel can't underflow stock_held.
+            for (var ri = 0; ri < holdSkus.length; ri += 1) {
+              await inventory.release(holdSkus[ri], holdMap[holdSkus[ri]]);
+            }
+          }
+        }
+      }
       // Fan-out to merchant webhook subscribers is fire-and-forget. The
       // transition has already persisted; the request must not wait on
       // outbound HTTP, or a slow / unreachable endpoint would block the

package/lib/storefront.js

@@ -12869,11 +12869,15 @@ function mount(router, deps) {
         // fat-fingered value re-prompts rather than 500-ing checkout.
         var code = (e && typeof e.code === "string") ? e.code : "";
         var msg = (e && e.message) || "checkout failed";
-        // A coded gift-card / loyalty error is something the shopper can
-        // fix in place — re-render the checkout form with the message
-        // inline (preserving the cart + their prefilled fields where
+        // A coded gift-card / loyalty / out-of-stock error is something the
+        // shopper can fix in place — re-render the checkout form with the
+        // message inline (preserving the cart + their prefilled fields where
         // possible) rather than dead-ending on a separate page.
-        if (code.indexOf("GIFTCARD_") === 0 || code.indexOf("LOYALTY_") === 0) {
+        // INSUFFICIENT_STOCK carries a friendly per-line message and means
+        // the buyer must lower a quantity or drop a line; nothing was
+        // charged and any holds placed mid-confirm were already released.
+        if (code.indexOf("GIFTCARD_") === 0 || code.indexOf("LOYALTY_") === 0 ||
+            code === "INSUFFICIENT_STOCK") {
           try {
             var coLines = await _repriceCartLines(await deps.cart.listLines(c.id));
             if (coLines.length) {
@@ -12999,7 +13003,14 @@ function mount(router, deps) {
           // The PayPal JS SDK's createOrder expects `{ id }`.
           return _json(200, { id: created.paypal_order_id, order_id: created.order.id });
         } catch (e) {
-          var gcErr = e && typeof e.code === "string" && e.code.indexOf("GIFTCARD_") === 0;
+          var ecode = (e && typeof e.code === "string") ? e.code : "";
+          var gcErr = ecode.indexOf("GIFTCARD_") === 0;
+          // Out-of-stock is a 409 (conflict) carrying the friendly per-line
+          // message so the PayPal button surfaces it; nothing was charged
+          // and the mid-confirm holds were already released.
+          if (ecode === "INSUFFICIENT_STOCK") {
+            return _json(409, { error: (e && e.message) || "out-of-stock", code: ecode });
+          }
           return _json((e instanceof TypeError || gcErr) ? 400 : 502, { error: (e && e.message) || "paypal-create-failed" });
         }
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.3.76",
+  "version": "0.4.0",
   "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": {