@blamejs/blamejs-shop 0.3.75 → 0.4.0

package/CHANGELOG.md

@@ -6,8 +6,14 @@ 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.
+
 - v0.3.75 (2026-06-05) — **The analytics funnel records real shopper events — only with analytics consent.** The admin Analytics screen's browse-to-buy funnel, top search terms, and most-viewed products read an event stream that nothing previously wrote, so those tables stayed empty. The storefront now records five events — product view, search, add to cart, checkout started, order completed — strictly gated on the visitor's analytics consent: no consent decision means no recording, Do Not Track and Global Privacy Control suppress recording even after an accept-all, session identifiers are stored only as keyed hashes, and no name or email ever rides an event. Recording is fire-and-forget and can never affect a request. Edge-cached anonymous pages are deliberately not recorded — the cache stays shared and fast — so the funnel reflects consented, container-served traffic, and the dashboard's own copy now says exactly that. **Added:** *Consent-gated shopper event recording* — Product views, searches, cart adds, checkout starts, and completed orders record into the analytics event stream when — and only when — the session's consent grants the analytics category. The gate is the consent primitive's own server-side read: default-deny without a decision, policy-version-aware, and honoring Do Not Track and Sec-GPC over a stored acceptance. Events carry a hashed session key and bounded payloads, never personal data. The Analytics screen's funnel now states that its counts cover consented, container-served traffic; anonymous edge-cached page views are not tracked by design.
 
 - v0.3.74 (2026-06-05) — **The payment form matches the shop's dark theme.** The Stripe Payment Element and the express wallet buttons on the pay page previously rendered in Stripe's default light style — a white card floating on the shop's near-black page. The elements now use Stripe's night appearance recolored with the shop's own design tokens: violet accent on focus and selected tabs, the shop's charcoal input surfaces, soft ink text, and matching corner radii. The Apple Pay, Google Pay, and PayPal express buttons switch to their white and outline variants, which keep each brand's contrast rules legible on the dark card. No payment behavior changes; this is purely the appearance configuration on the existing elements. **Changed:** *Dark-themed payment elements* — The pay page's Stripe elements adopt the night appearance with the shop's design tokens — violet primary, charcoal surfaces, soft ink, ten-pixel radii, violet focus rings — and the express wallet buttons render in their white and outline variants sized to the page's controls. Inside Stripe's cross-origin frame the typeface falls back to the system stack; everything else mirrors the storefront's stylesheet tokens.

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`)
@@ -97,7 +97,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/giftcards.js`** | Prepaid bearer gift cards. `issue({ amount_minor, currency })` generates a 16-char code (32-glyph alphabet, no ambiguous letters) via `b.crypto.generateBytes`, stores only its `namespaceHash` digest + a 4-char hint, and returns the plaintext code once. `balance(code)` / `lookup(code)` resolve a code to its live balance (constant-time hash compare); `redeem({ code, order_id, amount_minor })` decrements the balance with an atomic `balance >= amount` SQL guard so concurrent spends can't overdraw. Redeemed at checkout as a credit against the order grand total: the amount due drops by the applied balance (never below zero), the order still records the full total it owed, and the debit is recorded once per order — a card that fully covers the order is marked paid with no Stripe charge. Customers check a balance at `GET /gift-cards`; the page is not a code-existence oracle (unknown / malformed / expired all return the same generic not-found). |
 | **`lib/gift-card-ledger.js`** | Append-only credit / debit / expire history per gift card, with a denormalized `balance_after_minor` snapshot for O(1) balance reads. `credit` / `debit` / `expire` write one row each; `history(id)` paginates a card's transactions; `transactionsForOrder(id)` lists a card's movements for one order. The audit trail behind the admin gift-card ledger console; overdraft is refused at the primitive layer. |
 | **`lib/newsletter.js`** | Operator-collected email broadcast list — `signup({ email, source })` composes `b.guardEmail` for shape validation, `b.crypto.namespaceHash` for the dedup key, and `INSERT OR IGNORE` for idempotency. Storefront POST `/newsletter` route renders a designed thank-you card with separate copy for the `new` vs `dedup` branches. |
-| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. Also serves a **browser admin console**: sign in at `/admin` by pasting the API key (sealed `shop_admin` session cookie, SameSite=Strict, /admin-scoped), with a persistent nav across every signed-in page. A guided **setup wizard** at `/admin/setup` writes shop identity to config; **Products** (`/admin/products`) browses the catalog and creates / archives / restores, and each product opens a management screen that edits its fields, adds / edits / removes variants, sets a variant's price and shows its price history, and attaches / uploads / removes images — the full path to a sellable product; **Inventory** (`/admin/inventory`) lists stock per SKU (on-hand / held / available) with a low-stock filter, restocks, sets per-SKU thresholds, and tracks new SKUs; **Orders** (`/admin/orders`) lists recent orders with status filters, opens an order's items, totals, and shipping address, and drives the lifecycle (mark paid → fulfil → ship → deliver, cancel — Refund goes through the payment provider) through the order FSM, with a rate-bounded resend of the order confirmation to an operator-supplied address (the buyer's email is stored only as a hash, so the operator types the recipient), and attaches a shipment (carrier + tracking number) with recorded shipment events that surface a public tracking link to the customer; **Customers** (`/admin/customers`) is a read-only roster, newest first — display name, short id, join date, sign-in method (passkey count + linked OAuth providers), and order count, with the count and sign-in methods resolved by bounded aggregate queries so a page of customers costs no per-row trips (email addresses aren't stored in the clear, so they're not shown); customer segments export their members as a streamed CSV — id, display name, join date, order count, deliberately no email column; **Returns** (`/admin/returns`) is the RMA moderation queue — filter by status, open a request's items and reason, and approve (with refund amount) → mark received → refund, or reject with a reason, over the return FSM; **Reviews** (`/admin/reviews`) is the review moderation queue — filter by status and publish, reject (with a reason), or take down each submission inline; **Q&A** (`/admin/questions`) is the question moderation queue — filter by status, open a question to its full answer thread, approve / reject the question, post the seller answer, and approve / reject / pin individual answers; **Subscriptions** (`/admin/subscription-plans`) is the recurring-offer catalog — filter active / archived, create a plan (Stripe price id, interval, amount, trial), and archive one, with archiving terminal because the mirrored Stripe price can go stale; **Collections** (`/admin/collections`) manages manual + smart product collections — filter active / archived, create a collection (manual or smart with a starter rule), and per collection edit title / description / sort strategy, manage manual members (add by product id, remove, reorder) or edit a smart collection's rule set with a live preview of the products the rules currently match, and archive; **Gift cards** (`/admin/gift-cards`) is the gift-card ledger — list issued cards (masked code, original + remaining balance, status, issued date) filtered by lifecycle status, issue a new card (the bearer code shown once, right after creation), open a card to see its full credit / debit / expire ledger, and void an active card through a confirmation step; **Webhooks** (`/admin/webhooks`) registers outbound endpoints (https:// only) with a one-time signing-secret reveal, enables / disables / deletes them, and opens an endpoint's delivery feed to retry a failed delivery — the signing secret is shown once on create and never in the list, and order transitions fan out signed deliveries to subscribed endpoints. **Tax** (`/admin/tax-rates`), **Shipping** (`/admin/shipping`), and **Discounts** (`/admin/discounts`) configure tax rates per jurisdiction, shipping zones + rates, and automatic-discount rules — including code-unlocked rules a shopper redeems with a discount code on the cart page — + coupon-stacking policies — create / edit / archive each. **Audit** (`/admin/audit`) is a read-only activity log of every privileged action — filtered by outcome (success / failure / denied) and paginated — composed on the framework's tamper-evident `b.audit` chain; opening it is itself recorded as an `audit.read` event. **Errors** (`/admin/errors`) lists captured server-error detail — time, status, route, and a truncated message for scrubbed 500-class failures (checkout confirm, public API, admin actions) — newest-first, with the same path answering a bearer-token request with JSON so the log is one `curl` away. **Analytics** (`/admin/analytics`) is the pre-purchase view the sales report can't see — browse-to-buy funnel with conversion rate, top search terms, most-viewed products, units-ranked top SKUs, and a revenue-by-day sparkline — cross-linked with the Reports screen, read-only, every aggregate window- and limit-bounded. The Customers, Returns, Reviews, Q&A, Subscriptions, Collections, Gift cards, Webhooks, Tax, Shipping, Discounts, Delivery estimates, Analytics, and Errors links appear only when those primitives are wired. Each console path content-negotiates: a bearer-token client still gets the JSON API unchanged, a signed-in browser gets HTML. Reachable by the cookie or the bearer token. The console's styling is an external, integrity-pinned stylesheet (`themes/default/assets/css/admin.css`) with the same self-hosted typeface — no inline styles and no third-party font host, so it renders correctly under the strict `style-src 'self'` / `font-src 'self'` CSP that governs the route. |
+| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. Also serves a **browser admin console**: sign in at `/admin` by pasting the API key (sealed `shop_admin` session cookie, SameSite=Strict, /admin-scoped), with a persistent nav across every signed-in page. A guided **setup wizard** at `/admin/setup` writes shop identity to config; **Products** (`/admin/products`) browses the catalog and creates / archives / restores, and each product opens a management screen that edits its fields, adds / edits / removes variants, sets a variant's price and shows its price history, and attaches / uploads / removes images — the full path to a sellable product; **Inventory** (`/admin/inventory`) lists stock per SKU (on-hand / held / available) with a low-stock filter, restocks, sets per-SKU thresholds, and tracks new SKUs; **Orders** (`/admin/orders`) lists recent orders with status filters, opens an order's items, totals, and shipping address, and drives the lifecycle (mark paid → fulfil → ship → deliver, cancel — Refund goes through the payment provider) through the order FSM, with a rate-bounded resend of the order confirmation to an operator-supplied address (the buyer's email is stored only as a hash, so the operator types the recipient), and attaches a shipment (carrier + tracking number) with recorded shipment events that surface a public tracking link to the customer; **Customers** (`/admin/customers`) is a read-only roster, newest first — display name, short id, join date, sign-in method (passkey count + linked OAuth providers), and order count, with the count and sign-in methods resolved by bounded aggregate queries so a page of customers costs no per-row trips (email addresses aren't stored in the clear, so they're not shown); customer segments export their members as a streamed CSV — id, display name, join date, order count, deliberately no email column; **Returns** (`/admin/returns`) is the RMA moderation queue — filter by status, open a request's items and reason, and approve (with refund amount) → mark received → refund, or reject with a reason, over the return FSM; **Reviews** (`/admin/reviews`) is the review moderation queue — filter by status and publish, reject (with a reason), or take down each submission inline; **Q&A** (`/admin/questions`) is the question moderation queue — filter by status, open a question to its full answer thread, approve / reject the question, post the seller answer, and approve / reject / pin individual answers; **Subscriptions** (`/admin/subscription-plans`) is the recurring-offer catalog — filter active / archived, create a plan (Stripe price id, interval, amount, trial), and archive one, with archiving terminal because the mirrored Stripe price can go stale; **Collections** (`/admin/collections`) manages manual + smart product collections — filter active / archived, create a collection (manual or smart with a starter rule), and per collection edit title / description / sort strategy, manage manual members (add by product id, remove, reorder) or edit a smart collection's rule set with a live preview of the products the rules currently match, and archive; **Gift cards** (`/admin/gift-cards`) is the gift-card ledger — list issued cards (masked code, original + remaining balance, status, issued date) filtered by lifecycle status, issue a new card (the bearer code shown once, right after creation), open a card to see its full credit / debit / expire ledger, and void an active card through a confirmation step; **Webhooks** (`/admin/webhooks`) registers outbound endpoints (https:// only) with a one-time signing-secret reveal, enables / disables / deletes them, and opens an endpoint's delivery feed to retry a failed delivery — the signing secret is shown once on create and never in the list, and order transitions fan out signed deliveries to subscribed endpoints. **Tax** (`/admin/tax-rates`), **Shipping** (`/admin/shipping`), and **Discounts** (`/admin/discounts`) configure tax rates per jurisdiction, shipping zones + rates, and automatic-discount rules — including code-unlocked rules a shopper redeems with a discount code on the cart page — + coupon-stacking policies — create / edit / archive each. **Audit** (`/admin/audit`) is a read-only activity log of every privileged action — filtered by outcome (success / failure / denied) and paginated — composed on the framework's tamper-evident `b.audit` chain; opening it is itself recorded as an `audit.read` event. **Errors** (`/admin/errors`) lists captured server-error detail — time, status, route, and a truncated message for scrubbed 500-class failures (checkout confirm, public API, admin actions) — newest-first, with the same path answering a bearer-token request with JSON so the log is one `curl` away. **Carts** (`/admin/carts`) lists abandoned carts — active, has items, idle past a tunable window (24h default) — with line counts, value at risk, and guest/signed-in attribution; a per-cart action mints a single-use, code-gated discount the operator shares through their own channel (recovery email is impossible by design: buyer addresses are stored only as hashes, and the screen says so). **Analytics** (`/admin/analytics`) is the pre-purchase view the sales report can't see — browse-to-buy funnel with conversion rate, top search terms, most-viewed products, units-ranked top SKUs, and a revenue-by-day sparkline — cross-linked with the Reports screen, read-only, every aggregate window- and limit-bounded. The Customers, Returns, Reviews, Q&A, Subscriptions, Collections, Gift cards, Webhooks, Tax, Shipping, Discounts, Delivery estimates, Analytics, Carts, and Errors links appear only when those primitives are wired. Each console path content-negotiates: a bearer-token client still gets the JSON API unchanged, a signed-in browser gets HTML. Reachable by the cookie or the bearer token. The console's styling is an external, integrity-pinned stylesheet (`themes/default/assets/css/admin.css`) with the same self-hosted typeface — no inline styles and no third-party font host, so it renders correctly under the strict `style-src 'self'` / `font-src 'self'` CSP that governs the route. |
 | **`lib/catalog-import.js`** | Bulk CSV import — `POST /admin/catalog/import` accepts a `text/csv` body, parses via `b.csv`, content-safety-filters every cell through `b.guardCsv` (formula-injection / bidi / control / dangerous-function denylist), validates exact header order, de-dupes rows by `product_slug`, returns per-row errors without aborting. Default 1 MiB / 10000 rows caps. |
 | **`lib/theme.js`** | File-backed templates with fallback chain. Operators register a named theme under `<themesDir>/<name>/*.html` and the storefront dispatches every renderer through it. `assetUrl(path)` resolves to `/assets/themes/<name>/<path>`. The shipped `default` theme is the fallback. |
 

package/lib/admin.js

@@ -36,10 +36,19 @@ var quantityDiscountsModule = require("./quantity-discounts");
 var loyaltyEarnRulesModule = require("./loyalty-earn-rules");
 var loyaltyRedemptionModule = require("./loyalty-redemption");
 var trustBadgesModule = require("./trust-badges");
+var cartModule = require("./cart");   // ABANDONED_* window/limit constants for the /admin/carts console
 var textGuard = require("./text-guard");
 var { AsyncLocalStorage } = require("node:async_hooks");   // allow:non-shop-require — Node-core per-request context (no npm dep); the framework itself composes it in db-role-context / log. No b.* request-context primitive exists to wrap it.
 
 var b = require("./vendor/blamejs");
+// Framework duration constants (C.TIME.hours(n) etc.). The index entry
+// point exposes `framework` before the require cascade, so resolving this
+// at module-eval is safe — same pattern lib/cart.js uses.
+var C = b.constants;
+
+// One hour in ms, named once so the hours<->ms conversions on the
+// abandoned-cart window read in named units rather than a bare literal.
+var MS_PER_HOUR = C.TIME.hours(1);
 
 var AUDIT_NAMESPACE = "shop_admin";
 
@@ -523,6 +532,7 @@ function mount(router, deps) {
   }
   var catalog       = deps.catalog;
   var order         = deps.order;
+  var cart          = deps.cart          || null;   // abandoned-cart visibility console (/admin/carts) disabled when absent
   var payment       = deps.payment       || null;   // refund endpoints disabled when absent
   var mailer        = deps.mailer        || null;   // transactional email factory (lib/email.js) — resend-confirmation disabled when absent
   var _checkout     = deps.checkout      || null;   // reserved — future webhook handler wiring
@@ -574,7 +584,7 @@ function mount(router, deps) {
   // `reports` is always present in the nav (read-only sales summary needs no
   // extra dep); its route mounts unconditionally and renders an unconfigured
   // notice when the salesReports primitive isn't wired.
-  var navAvailable = { analytics: !!deps.analytics, returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, deliveryEstimate: !!deps.deliveryEstimate, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, clickAndCollect: !!clickAndCollect, giftOptions: !!giftOptions, searchRanking: !!searchRanking, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog };
+  var navAvailable = { analytics: !!deps.analytics, returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, deliveryEstimate: !!deps.deliveryEstimate, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, clickAndCollect: !!clickAndCollect, giftOptions: !!giftOptions, searchRanking: !!searchRanking, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog, carts: !!cart };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -9431,6 +9441,154 @@ function mount(router, deps) {
     return patch;
   }
 
+  // ---- abandoned carts (visibility + honest recovery) -----------------
+  //
+  // Operators have zero abandoned-cart visibility without this screen — no
+  // list, no value-at-risk total, no recovery surface. This reads the live
+  // `carts` table directly (active cart + has lines + untouched for >N
+  // hours), so it works WITHOUT the cart-abandonment scanner cron having
+  // ever run. The window is operator-tunable via `?hours=` (default 24).
+  //
+  // Recovery, honest version: a buyer's email is one-way hashed at every
+  // layer (the `carts` row carries only a sealed-cookie `session_id`, the
+  // customer record stores only an `email_hash`), so the framework cannot
+  // send a recovery EMAIL to ANY cart — guest or signed-in — on its own.
+  // The screen states this plainly. What it CAN do is compose the existing
+  // `autoDiscount` unlock-code surface: the "issue recovery code" action
+  // mints a single-use, code-gated percent-off rule (`max_redemptions_total
+  // = 1`) and shows the code ONCE for the operator to share through their
+  // own channel (the order-confirmation reply, an SMS, a printed receipt).
+  // No email is claimed where none is possible. When `autoDiscount` isn't
+  // wired the action is absent and the screen documents it as the next step.
+
+  // The recovery-code action composes deps.autoDiscount. Read it through a
+  // helper rather than the `autoDiscount` local (which is declared further
+  // down, inside the discounts block) so this block doesn't depend on
+  // var-hoist ordering.
+  function autoDiscountForCarts() { return deps.autoDiscount || null; }
+
+  // Defensive request-shape readers for the abandoned-cart window. The
+  // console accepts `?hours=` (whole hours) + `?limit=`; the cart primitive
+  // clamps the ms window + limit again, but converting here keeps the
+  // operator-facing unit (hours) at the route boundary. Garbage falls back
+  // to the default rather than 500-ing the screen.
+  function _cartHoursToMs(hoursRaw) {
+    if (hoursRaw == null || hoursRaw === "") return cartModule.ABANDONED_DEFAULT_IDLE_MS;
+    var h = Number(hoursRaw);
+    if (!isFinite(h) || h <= 0) return cartModule.ABANDONED_DEFAULT_IDLE_MS;
+    return Math.floor(h * MS_PER_HOUR);
+  }
+  function _cartListLimit(limitRaw) {
+    if (limitRaw == null || limitRaw === "") return undefined;
+    var n = parseInt(limitRaw, 10);
+    if (!isFinite(n) || n <= 0) return undefined;
+    return n;
+  }
+
+  // Mint a single-use, code-gated percent-off rule for one abandoned cart.
+  // Returns `{ rule_slug, unlock_code, percent_off }` on success, or null
+  // when the cart id doesn't resolve to an abandonable cart (so the route
+  // 404s rather than minting a code for nothing). Throws TypeError on bad
+  // input (a non-1..99 percent, a bad cart id) → clean 400 at the route.
+  async function _issueCartRecoveryCode(cartId, body) {
+    var ad = autoDiscountForCarts();
+    if (!ad) return null;   // defensive — the route only mounts when wired
+    // Resolve the cart so we don't mint a code for a non-existent / already
+    // converted cart. cart.get validates the id shape (throws TypeError on
+    // garbage → 400).
+    var row = await cart.get(cartId);
+    if (!row || row.status !== "active") return null;
+    // Percent off — operator-chosen, 1..99. Default 10% when blank.
+    var pctRaw = body.percent_off;
+    var pct = (pctRaw == null || pctRaw === "") ? 10 : Number(pctRaw);
+    if (!isFinite(pct) || !Number.isInteger(pct) || pct < 1 || pct > 99) {
+      throw new TypeError("percent_off must be a whole number between 1 and 99");
+    }
+    // Mint a short, human-shareable code. The unlock_code grammar is
+    // alnum + . _ - ; an uppercased hex slice of random bytes keeps it
+    // typeable. generateToken(n) returns n random bytes as 2n hex chars.
+    var code = "SAVE" + b.crypto.generateToken(4).slice(0, 6).toUpperCase();
+    var slug = "cart-recovery-" + String(cartId).slice(0, 8).toLowerCase() + "-" + Date.now().toString(36);
+    // Single-use, code-gated, no automatic trigger (cart_total_min: 0 fires
+    // on any cart once the code is presented). The lib rejects a code clash
+    // with another active rule (→ TypeError → 400), so a duplicate is safe.
+    await ad.defineRule({
+      slug:  slug,
+      title: "Cart recovery — " + pct + "% off",
+      trigger: { kind: "cart_total_min", min_minor: 0 },
+      value:   { kind: "percent_off", basis_points: pct * 100 },
+      unlock_code: code,
+      max_redemptions_total: 1,
+    });
+    return { rule_slug: slug, unlock_code: code, percent_off: pct };
+  }
+
+  if (cart) {
+    var cartRecoveryCodeEnabled = !!autoDiscountForCarts();
+
+    router.get("/admin/carts", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var hours = url && url.searchParams.get("hours");
+        var idleMs = _cartHoursToMs(hours);
+        var limit = _cartListLimit(url && url.searchParams.get("limit"));
+        var carts = await cart.listAbandoned({ idle_threshold_ms: idleMs, limit: limit });
+        var summary = await cart.abandonedSummary({ idle_threshold_ms: idleMs });
+        _json(res, 200, { carts: carts, summary: summary });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var hoursRaw = url && url.searchParams.get("hours");
+        var idleMs = _cartHoursToMs(hoursRaw);
+        var hours = Math.round(idleMs / MS_PER_HOUR);
+        var carts = await cart.listAbandoned({ idle_threshold_ms: idleMs, limit: cartModule.ABANDONED_MAX_LIMIT });
+        var summary = await cart.abandonedSummary({ idle_threshold_ms: idleMs });
+        _sendHtml(res, 200, renderAdminCarts({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          carts: carts, summary: summary, hours: hours,
+          recovery_enabled: cartRecoveryCodeEnabled,
+          issued: url && url.searchParams.get("issued"),
+          issued_code: url && url.searchParams.get("code"),
+          issued_cart: url && url.searchParams.get("cart"),
+          notice: (url && url.searchParams.get("err")) ? "That action couldn't be completed." : null,
+        }));
+      },
+    ));
+
+    // Issue a single-use recovery code for one cart. Composes the existing
+    // autoDiscount unlock-code surface — NO new primitive. Only mounted
+    // when autoDiscount is wired; absent it, the screen never renders the
+    // form (so this route stays an honest 404 for the unwired deploy).
+    if (cartRecoveryCodeEnabled) {
+      router.post("/admin/carts/:id/recovery-code", _pageOrApi(false,
+        W("cart_recovery_code.issue", async function (req, res) {
+          var out;
+          try { out = await _issueCartRecoveryCode(req.params.id, req.body || {}); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          if (!out) return _problem(res, 404, "cart-not-found");
+          _json(res, 201, out);
+          return { id: out.rule_slug };
+        }),
+        async function (req, res) {
+          var out;
+          try { out = await _issueCartRecoveryCode(req.params.id, req.body || {}); }
+          catch (e) {
+            if (!(e instanceof TypeError)) throw e;
+            return _redirect(res, "/admin/carts?err=1");
+          }
+          if (!out) return _redirect(res, "/admin/carts?err=1");
+          b.audit.safeEmit({
+            action: AUDIT_NAMESPACE + ".cart_recovery_code.issue",
+            outcome: "success",
+            metadata: { rule_slug: out.rule_slug },
+          });
+          _redirect(res, "/admin/carts?issued=1&code=" + encodeURIComponent(out.unlock_code) +
+            "&cart=" + encodeURIComponent(String(req.params.id).slice(0, 8)));
+        },
+      ));
+    }
+  }
+
   // ---- automatic discounts + stacking policies ------------------------
   //
   // Two related concerns on one console screen. `autoDiscount` rules are
@@ -11334,6 +11492,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "products",     href: "/admin/products",     label: "Products" },
   { key: "inventory",    href: "/admin/inventory",    label: "Inventory" },
   { key: "orders",       href: "/admin/orders",       label: "Orders" },
+  { key: "carts",        href: "/admin/carts",        label: "Abandoned carts", requires: "carts" },
   { key: "reports",      href: "/admin/reports",      label: "Reports" },
   { key: "analytics",    href: "/admin/analytics",    label: "Analytics",    requires: "analytics" },
   { key: "audit",        href: "/admin/audit",        label: "Audit",        requires: "auditLog" },
@@ -11655,6 +11814,138 @@ function renderAdminOrders(opts) {
   return _renderAdminShell(opts.shop_name, "Orders", body, "orders", opts.nav_available);
 }
 
+// Format an idle duration (ms) as a coarse human string for the abandoned-
+// cart "last activity" column: "3h", "2d", "<1h". Coarse on purpose — the
+// operator wants the order of magnitude, not a precise stopwatch.
+function _fmtIdle(ms) {
+  if (typeof ms !== "number" || !isFinite(ms) || ms < 0) return "—";
+  var hours = ms / MS_PER_HOUR;
+  if (hours < 1)  return "<1h";
+  if (hours < 48) return Math.floor(hours) + "h";
+  return Math.floor(hours / 24) + "d";
+}
+
+// Abandoned-cart visibility. Lists active carts with at least one line that
+// haven't been touched for the selected window (default 24h, tunable via the
+// `?hours=` filter), freshest-abandonment first, with a value-at-risk summary.
+//
+// Recovery is honest about the framework's hash-only stance: buyer emails are
+// one-way hashed everywhere (the cart row carries only a sealed-cookie
+// session_id; the customer record stores only an email_hash), so NO recovery
+// EMAIL is possible — for guest OR signed-in carts. The screen says so. When
+// `autoDiscount` is wired it offers the one recovery that IS possible: minting
+// a single-use code-gated discount whose code the operator shares through
+// their own channel.
+//
+// XSS note: customer_id + cart id are framework-issued UUIDs, but every value
+// still flows through _htmlEscape (escape-by-default) — the discipline holds
+// regardless of the field's provenance.
+function renderAdminCarts(opts) {
+  opts = opts || {};
+  var carts = opts.carts || [];
+  var summary = opts.summary || { cart_count: 0, by_currency: [] };
+  var hours = opts.hours || 24;
+  var recoveryEnabled = !!opts.recovery_enabled;
+
+  var notice = opts.notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  // PRG success banner after issuing a recovery code — shows the code ONCE
+  // (the operator copies it to share through their own channel; it isn't
+  // re-displayed on reload).
+  var issued = "";
+  if (opts.issued && opts.issued_code) {
+    issued = "<div class=\"banner banner--ok\">" +
+      "Recovery code <code class=\"order-id\">" + _htmlEscape(opts.issued_code) + "</code> issued" +
+      (opts.issued_cart ? " for cart " + _htmlEscape(opts.issued_cart) : "") + ". " +
+      "Share it through your own channel — it's single-use and won't be shown again." +
+      "</div>";
+  }
+
+  // Value-at-risk summary line(s) — one per currency present in the window.
+  var valueLine;
+  if (summary.cart_count === 0) {
+    valueLine = "<span class=\"meta\">No carts have been idle longer than " + _htmlEscape(String(hours)) + "h.</span>";
+  } else {
+    var perCur = (summary.by_currency || []).map(function (c) {
+      return _htmlEscape(pricing.format(c.value_minor, c.currency)) +
+        " across " + _htmlEscape(String(c.cart_count)) + " cart" + (c.cart_count === 1 ? "" : "s");
+    }).join("; ");
+    valueLine = "<strong>" + _htmlEscape(String(summary.cart_count)) + "</strong> abandoned cart" +
+      (summary.cart_count === 1 ? "" : "s") + " — " + perCur + " at risk.";
+  }
+
+  // Window filter chips — common windows plus the current one highlighted.
+  var WINDOWS = [1, 6, 24, 72, 168];
+  var chips = "<div class=\"order-filters\">" +
+    WINDOWS.map(function (h) {
+      var label = h < 24 ? h + "h" : (h / 24) + "d";
+      return "<a class=\"chip" + (hours === h ? " chip--on" : "") +
+        "\" href=\"/admin/carts?hours=" + h + "\">&gt; " + _htmlEscape(label) + "</a>";
+    }).join("") +
+    "</div>";
+
+  var rows = carts.map(function (c) {
+    var isGuest = !c.customer_id;
+    var who = isGuest
+      ? "<span class=\"chip\">Guest</span>"
+      : "<a href=\"/admin/customers/" + _htmlEscape(encodeURIComponent(c.customer_id)) +
+        "\"><span class=\"chip\">Signed in</span></a>";
+    // The recovery-code form (only when autoDiscount is wired). A guest cart
+    // gets the same code-mint affordance — the code is shared out-of-band, so
+    // it doesn't depend on a deliverable address either way.
+    var action = recoveryEnabled
+      ? "<form method=\"post\" action=\"/admin/carts/" + _htmlEscape(encodeURIComponent(c.id)) +
+          "/recovery-code\" class=\"form-inline\">" +
+          "<input type=\"number\" name=\"percent_off\" min=\"1\" max=\"99\" step=\"1\" value=\"10\" " +
+            "class=\"input-code\" aria-label=\"Percent off\"> " +
+          "<button class=\"btn btn--ghost btn--sm\" type=\"submit\">Issue code</button>" +
+        "</form>"
+      : "<span class=\"meta\">—</span>";
+    return "<tr>" +
+      "<td><code class=\"order-id\">" + _htmlEscape(String(c.id).slice(0, 8)) + "</code></td>" +
+      "<td class=\"num\">" + _htmlEscape(String(c.line_count)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(pricing.format(c.subtotal_minor, c.currency)) + "</td>" +
+      "<td>" + _htmlEscape(_fmtIdle(c.idle_ms)) + " ago <span class=\"meta\">(" + _htmlEscape(_fmtDate(c.updated_at)) + ")</span></td>" +
+      "<td>" + who + "</td>" +
+      "<td>" + action + "</td>" +
+      "</tr>";
+  }).join("");
+
+  var table = carts.length
+    ? "<div class=\"panel\">" + _tableWrap("<table><thead><tr>" +
+        "<th scope=\"col\">Cart</th>" +
+        "<th scope=\"col\" class=\"num\">Items</th>" +
+        "<th scope=\"col\" class=\"num\">Subtotal</th>" +
+        "<th scope=\"col\">Last activity</th>" +
+        "<th scope=\"col\">Shopper</th>" +
+        "<th scope=\"col\">" + (recoveryEnabled ? "Recovery" : "<span class=\"sr-only\">Recovery</span>") + "</th>" +
+      "</tr></thead><tbody>" + rows + "</tbody></table>") + "</div>"
+    : "<p class=\"empty\">No carts have been abandoned longer than " + _htmlEscape(String(hours)) + "h.</p>";
+
+  // The honest-recovery explainer. Always shown — it's the load-bearing
+  // caveat that distinguishes this screen from a store that emails idle
+  // shoppers (which this framework structurally cannot do).
+  var recoveryNote = recoveryEnabled
+    ? "<div class=\"panel mt\"><h3 class=\"subhead\">Recovering a cart</h3>" +
+        "<p class=\"meta\">Buyer emails are one-way hashed everywhere in this shop, so the " +
+        "framework can't send an abandoned-cart email — for guest or signed-in carts. " +
+        "Instead, issue a single-use discount code for a cart and share it through your own " +
+        "channel (an order-confirmation reply, SMS, or printed receipt). Each code works once " +
+        "and appears on your <a href=\"/admin/discounts\">discounts</a> list.</p></div>"
+    : "<div class=\"panel mt\"><h3 class=\"subhead\">Recovering a cart</h3>" +
+        "<p class=\"meta\">Buyer emails are one-way hashed everywhere in this shop, so the " +
+        "framework can't send an abandoned-cart email. The recovery path here is to issue a " +
+        "single-use discount code per cart and share it through your own channel — wire the " +
+        "discounts feature (the <code>autoDiscount</code> dependency) to enable it.</p></div>";
+
+  var body = "<section><h2>Abandoned carts</h2>" + notice + issued +
+    "<p class=\"meta\">Active carts with items that haven't been touched in a while. " +
+    "These are reads of live carts — no scanner or cron required.</p>" +
+    "<p class=\"meta\">" + valueLine + "</p>" +
+    chips + table + recoveryNote + "</section>";
+  return _renderAdminShell(opts.shop_name, "Abandoned carts", body, "carts", opts.nav_available);
+}
+
 // The outcomes an operator can filter the audit log by — drives the chips.
 var AUDIT_OUTCOME_FILTERS = ["success", "failure", "denied"];
 

package/lib/asset-manifest.json

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

package/lib/cart.js

@@ -42,6 +42,18 @@ var CURRENCY_RE     = /^[A-Z]{3}$/;
 var DISCOUNT_CODE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 var MAX_CODES_PER_CART = 16;
 
+// Abandoned-cart visibility defaults. A cart counts as "abandoned" for the
+// operator dashboard when it is still `active`, carries at least one line,
+// and has not been touched (no `updated_at` bump) for at least
+// `idle_threshold_ms`. This reads the live `carts` table directly — it does
+// NOT require the cart-abandonment scanner's detection rows to exist, so an
+// operator who never wired the recovery cron still sees their idle carts.
+var ABANDONED_DEFAULT_IDLE_MS = C.TIME.hours(24);
+var ABANDONED_MIN_IDLE_MS     = C.TIME.minutes(1);   // floor so a 0h window can't list live carts
+var ABANDONED_MAX_IDLE_MS     = C.TIME.days(90);     // ceiling — past this the TTL has abandoned it anyway
+var ABANDONED_DEFAULT_LIMIT   = 50;
+var ABANDONED_MAX_LIMIT       = 200;
+
 // ---- validators ---------------------------------------------------------
 
 function _uuid(s, label) {
@@ -77,6 +89,31 @@ function _discountCode(s) {
 
 function _now() { return Date.now(); }
 
+// Defensive request-shape readers for the abandoned-cart dashboard window.
+// A garbage / out-of-range value (a hand-typed `?hours=` query param) clamps
+// to a sane default rather than throwing — the console must never 500 on a
+// fat-fingered filter. The bounds also stop a caller widening the scan past
+// the ceiling (idle floor keeps live carts out; limit ceiling keeps the
+// payload bounded).
+function _abandonedIdleMs(v) {
+  if (v == null) return ABANDONED_DEFAULT_IDLE_MS;
+  var n = typeof v === "string" ? Number(v) : v;
+  if (typeof n !== "number" || !isFinite(n)) return ABANDONED_DEFAULT_IDLE_MS;
+  n = Math.floor(n);
+  if (n < ABANDONED_MIN_IDLE_MS) return ABANDONED_MIN_IDLE_MS;
+  if (n > ABANDONED_MAX_IDLE_MS) return ABANDONED_MAX_IDLE_MS;
+  return n;
+}
+function _abandonedLimit(v) {
+  if (v == null) return ABANDONED_DEFAULT_LIMIT;
+  var n = typeof v === "string" ? Number(v) : v;
+  if (typeof n !== "number" || !isFinite(n)) return ABANDONED_DEFAULT_LIMIT;
+  n = Math.floor(n);
+  if (n < 1) return ABANDONED_DEFAULT_LIMIT;
+  if (n > ABANDONED_MAX_LIMIT) return ABANDONED_MAX_LIMIT;
+  return n;
+}
+
 // ---- factory ------------------------------------------------------------
 
 function create(opts) {
@@ -317,6 +354,107 @@ function create(opts) {
       return (await query("SELECT * FROM carts WHERE id = ?1", [cartId])).rows[0];
     },
 
+    // ---- abandoned-cart visibility (operator dashboard) ---------------
+    //
+    // A cart is "abandoned" for dashboard purposes when it is still
+    // `active`, has at least one line, and hasn't been touched for
+    // `idle_threshold_ms` (default 24h, operator-tunable). This reads the
+    // live `carts` / `cart_lines` tables — it needs NO scanner detection
+    // rows and NO schema change, so an operator who never wired the
+    // recovery cron still sees their idle carts.
+    //
+    // Defensive request-shape reader tier: a missing / garbage option
+    // falls back to a sane default rather than throwing, so a hand-typed
+    // `?hours=` query param can't 500 the console. The window is clamped
+    // to [1min, 90d] and the limit to [1, 200] — a caller can't widen the
+    // scan past the bounded ceiling.
+
+    // List abandoned carts, most-recent-activity-first, each enriched with
+    // its line count + subtotal-in-minor-units + age. Bounded by `limit`
+    // (default 50, max 200). The `idle_threshold_ms` option sets the
+    // untouched-for window; carts updated more recently than that are still
+    // "live" and excluded. Carts with zero lines are excluded (an empty
+    // cart has nothing to recover).
+    listAbandoned: async function (listOpts) {
+      listOpts = listOpts || {};
+      var idleMs = _abandonedIdleMs(listOpts.idle_threshold_ms);
+      var limit  = _abandonedLimit(listOpts.limit);
+      var now    = listOpts.now == null ? _now() : listOpts.now;
+      var cutoff = now - idleMs;
+      // INNER JOIN onto an aggregate of cart_lines so the zero-line carts
+      // drop out (a cart with no lines produces no group row) and we read
+      // the line count + subtotal in one pass. ORDER BY updated_at DESC =
+      // freshest-abandonment first (the operator's most-actionable carts).
+      var rows = (await query(
+        "SELECT c.id AS id, c.session_id AS session_id, c.customer_id AS customer_id, " +
+        "       c.currency AS currency, c.created_at AS created_at, c.updated_at AS updated_at, " +
+        "       agg.line_count AS line_count, agg.subtotal_minor AS subtotal_minor " +
+        "FROM carts c " +
+        "JOIN (SELECT cart_id, COUNT(*) AS line_count, " +
+        "             SUM(qty * unit_amount_minor) AS subtotal_minor " +
+        "      FROM cart_lines GROUP BY cart_id) agg ON agg.cart_id = c.id " +
+        "WHERE c.status = 'active' AND c.updated_at <= ?1 " +
+        "ORDER BY c.updated_at DESC, c.id DESC LIMIT ?2",
+        [cutoff, limit],
+      )).rows;
+      var out = [];
+      for (var i = 0; i < rows.length; i += 1) {
+        var r = rows[i];
+        out.push({
+          id:             r.id,
+          // session_id is sealed-cookie material — never surface it raw to
+          // the operator screen; a short opaque tag of the cart id is the
+          // dashboard handle. customer_id passes through so the console can
+          // link signed-in carts to /admin/customers/<id>.
+          customer_id:    r.customer_id || null,
+          currency:       r.currency,
+          line_count:     Number(r.line_count || 0),
+          subtotal_minor: Number(r.subtotal_minor || 0),
+          created_at:     Number(r.created_at),
+          updated_at:     Number(r.updated_at),
+          idle_ms:        Math.max(0, now - Number(r.updated_at)),
+        });
+      }
+      return out;
+    },
+
+    // Summary stats for the same abandoned-cart window: how many carts are
+    // at risk + the total value (sum of subtotals) across them, per
+    // currency. The console renders this as the headline "N carts, X at
+    // risk" line. Unbounded COUNT/SUM (cheap aggregate, no row payload).
+    abandonedSummary: async function (sumOpts) {
+      sumOpts = sumOpts || {};
+      var idleMs = _abandonedIdleMs(sumOpts.idle_threshold_ms);
+      var now    = sumOpts.now == null ? _now() : sumOpts.now;
+      var cutoff = now - idleMs;
+      var rows = (await query(
+        "SELECT c.currency AS currency, COUNT(*) AS cart_count, " +
+        "       SUM(agg.subtotal_minor) AS value_minor " +
+        "FROM carts c " +
+        "JOIN (SELECT cart_id, SUM(qty * unit_amount_minor) AS subtotal_minor " +
+        "      FROM cart_lines GROUP BY cart_id) agg ON agg.cart_id = c.id " +
+        "WHERE c.status = 'active' AND c.updated_at <= ?1 " +
+        "GROUP BY c.currency",
+        [cutoff],
+      )).rows;
+      var byCurrency = [];
+      var totalCarts = 0;
+      for (var i = 0; i < rows.length; i += 1) {
+        var n = Number(rows[i].cart_count || 0);
+        totalCarts += n;
+        byCurrency.push({
+          currency:    rows[i].currency,
+          cart_count:  n,
+          value_minor: Number(rows[i].value_minor || 0),
+        });
+      }
+      return {
+        idle_threshold_ms: idleMs,
+        cart_count:        totalCarts,
+        by_currency:       byCurrency,
+      };
+    },
+
     // ---- applied discount codes ---------------------------------------
     //
     // A cart carries the discount codes a shopper applied on the cart page.
@@ -391,8 +529,10 @@ function create(opts) {
 }
 
 module.exports = {
-  create:           create,
-  DEFAULT_TTL_MS:   DEFAULT_TTL_MS,
-  MAX_QTY:          MAX_QTY,
-  CART_STATUSES:    CART_STATUSES,
+  create:                    create,
+  DEFAULT_TTL_MS:            DEFAULT_TTL_MS,
+  MAX_QTY:                   MAX_QTY,
+  CART_STATUSES:             CART_STATUSES,
+  ABANDONED_DEFAULT_IDLE_MS: ABANDONED_DEFAULT_IDLE_MS,
+  ABANDONED_MAX_LIMIT:       ABANDONED_MAX_LIMIT,
 };

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.75",
+  "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": {