@blamejs/blamejs-shop 0.4.14 → 0.4.15

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.15 (2026-06-06) — **Multi-location inventory: stock locations, receiving, transfers, and write-offs in the admin console.** The admin console gains a location-aware inventory back office. Define warehouse, retail, and virtual stock locations and see per-location levels; record reason-coded inbound stock against a location; move stock between locations through a dispatch-and-receive flow; and record reason-coded write-offs with a full audit trail. Single-location stores are untouched — no configuration is needed and existing stock behavior is unchanged. **Added:** *Stock locations with per-location levels* — `/admin/inventory/locations` defines stock locations (warehouse, retail, or virtual, with a priority order) and shows each SKU's quantity at each location. A store that never defines a location keeps working exactly as before — the default location stays implicit and nothing about existing stock semantics changes. · *Receive stock against a location* — `/admin/inventory/receive` records inbound stock — SKU, quantity, location, reason — crediting both the location's level and the sellable aggregate in one step, with a batched receipt history on the same screen. If the receipt record cannot be written the stock credit is reversed, so the ledger and the levels never diverge. · *Location-to-location transfers with a dispatch/receive lifecycle* — `/admin/inventory/transfers` moves stock between locations through a real state machine: a draft transfer dispatches (debiting the source) and is later received (crediting the destination) or cancelled (restoring the source). Stock movements use the same atomic guards as checkout holds — a transfer dispatch racing a checkout for the last unit has exactly one winner, and a level can never go negative. · *Reason-coded write-offs with an audit trail* — `/admin/inventory/writeoffs` records stock losses — damage, shrinkage, expiry — against a location, with every write-off in the tamper-evident audit chain. A write-off that would eat into stock already promised to paid orders is refused with a clear message rather than silently unbalancing the ledgers, and low-stock alerts fire when a write-off takes a SKU under its threshold.
+
 - v0.4.14 (2026-06-06) — **Gift wrap charges exactly the fee it displays, the per-order wrap cap is enforced, low-stock events reach subscribed webhooks, and the admin API accepts curl as documented.** Three storefront fixes and two admin-surface fixes. Gift wrap now charges the configured wrap fee rather than the wrap variant's catalog price, and a wrap's per-order cap is enforced at the cart with a clear message. The low-stock inventory event is now a registered webhook event, so endpoints subscribed to specific events receive it. The account profile explains plainly why an email address cannot be changed. And the admin JSON API now answers automation clients such as curl the way the documentation has always shown, with the bearer key as the deciding check. **Changed:** *The account profile explains why the email address cannot be changed* — The store keeps only a one-way hash of each account's email address, so an address can never be read back or rewritten — an email change is not possible by design. The profile screen now says this plainly where an email-change control would normally sit, and points to the alternatives: create a new account under the new address, or contact the store to reconcile order history. **Fixed:** *Gift wrap charges the configured fee, not the wrap variant's catalog price* — The gift-wrap selector displayed the wrap fee configured in the admin console, but checkout added the wrap to the order at the underlying catalog variant's price — when the two diverged, the customer was silently charged a different amount than the page showed. The cart now snapshots the configured fee onto the wrap line, so the displayed fee and the charged fee always agree. A regression test keeps the two amounts pinned together with deliberately different fee and catalog values. · *A gift wrap's per-order cap is enforced at the cart* — A wrap option's maximum-per-order value was validated, stored, and shown in the admin console but never enforced — any quantity could be applied. Applying a wrap beyond its cap is now rejected with a 422 and the cart page re-renders with a readable message; an application at the cap continues to succeed and the cart is left unchanged on rejection. · *The low-stock event is a registered webhook event* — Inventory low-stock alerts emitted `inventory.low_stock`, but the event was missing from the webhook event registry — endpoints subscribed to specific events never received it, and the admin endpoint form never offered it. The event is now registered, appears in the endpoint form's event checklist, and is delivered to endpoints that subscribe to it. Wildcard subscriptions, which already received it, are unchanged. · *Documented curl commands against the admin API work as written* — Every admin endpoint is bearer-key-gated JSON, and the documentation drives it with plain curl — but the bot guard's user-agent deny list refused automation clients on `/admin` before the key was ever checked, so the documented commands answered 403. The admin surface now runs the bot guard in tag mode: automation is recorded in the audit trail (`system.botguard.tag`) instead of refused, and the timing-safe bearer key remains the deciding check. A curl call with a valid key reaches the endpoint; one without a key is refused by the key check with a 401.
 
 - v0.4.13 (2026-06-06) — **Security: a passkey can no longer be added to an existing account from the public register page, and the email sign-in link no longer reveals which addresses have accounts.** Two fixes to the account sign-in surface. The public passkey-registration endpoint reused an existing customer record when the submitted email already had an account, which let anyone who knew a registered email enroll their own authenticator onto that account and sign in as its owner. Registration now creates new accounts only: it refuses any email that already has an account — whether it signs in by passkey, by Google or Apple, or is a guest order awaiting a sign-in link — and directs the visitor to sign in instead. Separately, the email sign-in-link request did its account lookup, session creation, and email send before replying, so a registered address took measurably longer to answer than an unregistered one — a timing signal that revealed which addresses have accounts despite the identical on-screen confirmation. The reply is now sent first and the link is prepared and mailed afterward, so both cases answer at the same speed. **Security:** *Passkey registration can no longer enroll a credential onto someone else's account* — The public passkey-registration ceremony reused an existing customer record whenever the submitted email already had an account, then bound the registration challenge to that account — so a visitor who knew a registered email could complete the ceremony on their own device and be issued a sign-in session for the account's owner, without any proof of controlling the email. The path now creates new accounts only: it refuses any email that already has an account and binds no challenge to it, returning a clear "this email already has an account — sign in instead" response. The refusal covers every existing account, not only those with a passkey — a Google or Apple account and a guest order awaiting a sign-in link both have no passkey yet a real owner, and an attacker enrolling onto either would take it over just the same. An owner adding a second passkey continues to use the signed-in add-a-passkey flow, which has always required an active session and matches the challenge to the signed-in account; an owner who has no passkey, or whose first attempt was interrupted, signs in with the email link. · *The email sign-in link no longer leaks which addresses have accounts* — The "email me a sign-in link" request answered with the same confirmation whether or not the address matched an account, but it performed the account lookup, session creation, and email dispatch before replying when the address did match — so a registered address answered measurably more slowly than an unregistered one, a timing side channel that distinguished real accounts from non-accounts. The confirmation is now sent before any of that work; when the address matches an account, the sign-in link is prepared and mailed afterward, off the response path. A matched and an unmatched address now take the same time to answer, and the link still arrives for real accounts.

package/README.md

@@ -99,7 +99,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, tracks new SKUs, and opens the low-stock alert history (`/admin/inventory/alerts`) — each alert row is written when a checkout decrement crosses a SKU's threshold, alongside an `inventory.low_stock` webhook to subscribed endpoints; **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, plus a customer-service notes thread per order (internal or customer-visible, pinnable, resolvable); **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); each customer opens to an aggregated activity timeline (orders, loyalty, wishlist, reviews, support) read from the tables those primitives already populate; 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. **Search suggestions** (`/admin/search-suggestions`) curates the storefront autocomplete — pin a featured link to a typed prefix, set its priority / status / active window, edit or remove it inline — and surfaces a read-only popular-searches report (each term's 30-day count, zero-result share, and last-seen) so an unmatched term flags a stock or naming gap. The Customers, Returns, Reviews, Q&A, Subscriptions, Collections, Gift cards, Webhooks, Tax, Shipping, Discounts, Delivery estimates, Analytics, Search suggestions, 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/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, tracks new SKUs, and opens the low-stock alert history (`/admin/inventory/alerts`) — each alert row is written when a checkout decrement crosses a SKU's threshold, alongside an `inventory.low_stock` webhook to subscribed endpoints; **Stock locations** (`/admin/inventory/locations`) defines warehouse / retail / virtual locations with per-location stock levels (a single-location store needs no configuration — the default location stays implicit), **Receive stock** (`/admin/inventory/receive`) records reason-coded inbound stock against a location with a batched receipt history, **Transfers** (`/admin/inventory/transfers`) moves stock between locations through a dispatch → receive state machine — the source is debited at dispatch, the destination credited on receive, and a dispatch racing a checkout hold for the last unit has exactly one winner — and **Write-offs** (`/admin/inventory/writeoffs`) records reason-coded stock losses with an audit trail, refusing a write-off that would eat into stock already held for paid orders; **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, plus a customer-service notes thread per order (internal or customer-visible, pinnable, resolvable); **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); each customer opens to an aggregated activity timeline (orders, loyalty, wishlist, reviews, support) read from the tables those primitives already populate; 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. **Search suggestions** (`/admin/search-suggestions`) curates the storefront autocomplete — pin a featured link to a typed prefix, set its priority / status / active window, edit or remove it inline — and surfaces a read-only popular-searches report (each term's 30-day count, zero-result share, and last-seen) so an unmatched term flags a stock or naming gap. The Customers, Returns, Reviews, Q&A, Subscriptions, Collections, Gift cards, Webhooks, Tax, Shipping, Discounts, Delivery estimates, Analytics, Search suggestions, Carts, Errors, Stock locations, Receive stock, Transfers, and Write-offs 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

@@ -37,6 +37,7 @@ 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 inventoryWriteoffsModule = require("./inventory-writeoffs");   // WRITEOFF_REASONS enum for the /admin/inventory/writeoffs 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.
 
@@ -574,6 +575,10 @@ function mount(router, deps) {
   var searchSuggestions = deps.searchSuggestions || null; // featured-suggestion curation + popular-searches view disabled when absent
   var trustBadges     = deps.trustBadges     || null; // trust-badge authoring console disabled when absent
   var preorder        = deps.preorder        || null; // pre-order campaign console (define/launch/close) disabled when absent
+  var inventoryLocations = deps.inventoryLocations || null; // stock-location CRUD + per-location levels console disabled when absent
+  var inventoryReceive   = deps.inventoryReceive   || null; // inbound-stock receive console disabled when absent
+  var stockTransfers     = deps.stockTransfers     || null; // location→location transfer console (dispatch/receive FSM) disabled when absent
+  var inventoryWriteoffs = deps.inventoryWriteoffs || null; // reason-coded write-off / shrinkage console disabled when absent
   // Read-only activity log at /admin/audit. Defaults ON — the framework
   // audit chain is always booted by createApp, so the screen always has a
   // data source (unlike the optional primitives above, which default off).
@@ -593,7 +598,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, promoBanners: !!deps.promoBanners, 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, searchSuggestions: !!searchSuggestions, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog, carts: !!cart };
+  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, promoBanners: !!deps.promoBanners, 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, searchSuggestions: !!searchSuggestions, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog, carts: !!cart, inventoryLocations: !!inventoryLocations, inventoryReceive: !!inventoryReceive, stockTransfers: !!stockTransfers, inventoryWriteoffs: !!inventoryWriteoffs };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -5273,6 +5278,406 @@ function mount(router, deps) {
     });
   }
 
+  // ---- inventory-ops back-office --------------------------------------
+  //
+  // Per-location stock on top of the single-bucket catalog inventory. The
+  // catalog `inventory.stock_on_hand` stays the storefront source of truth;
+  // these screens keep it in step with the per-location detail so a
+  // multi-location operator's warehouse breakdown never diverges from the
+  // count the storefront sells against. A store that never defines a
+  // location keeps using /admin/inventory unchanged — the default location
+  // is implicit, zero config.
+
+  // Credit ALL THREE ledgers for an inbound receive of one (sku,
+  // location) line:
+  //   1. inventoryReceive.draft + apply — the batched-receipt record the
+  //      "Recent receipts" history reads, AND the storefront-aggregate
+  //      credit (apply composes catalog.inventory.restock, which fires the
+  //      low-stock observer). A unique reference is auto-generated so two
+  //      receives in the same millisecond don't collide on the UNIQUE
+  //      constraint.
+  //   2. inventoryLocations.adjustStock(+qty) — the per-location detail +
+  //      its reason-coded inventory_adjustments audit row.
+  //
+  // The location credit lands first: it's the verb that refuses an unknown
+  // / deactivated location (a credit never refuses on insufficiency), so a
+  // bad location is rejected before any receipt row is written. If the
+  // receipt record then fails (duplicate reference race, DB error) the
+  // location credit is reversed so the per-location detail doesn't sit
+  // ahead of the aggregate. Returns the location adjust result.
+  async function _receiveToLocation(sku, locationCode, qty, reason) {
+    var adj = await inventoryLocations.adjustStock({
+      sku: sku, location_code: locationCode, delta: qty,
+      reason: reason ? ("receive: " + reason) : "receive",
+    });
+    try {
+      var ref = "RCV-" + Date.now().toString(36).toUpperCase() + "-" +
+        b.uuid.v7().slice(0, 8);
+      var draft = await inventoryReceive.draft({
+        reference:   ref,
+        supplier:    reason ? reason.slice(0, 256) : "",
+        received_by: "admin-console",
+        notes:       locationCode ? ("location: " + locationCode) : "",
+        lines:       [{ sku: sku, qty_received: qty }],
+      });
+      // apply credits the storefront aggregate (restock → low-stock
+      // observer). restock is a no-op for an un-tracked SKU (no inventory
+      // row) — fine: an un-tracked SKU is unlimited in the storefront, so
+      // the per-location detail is the only ledger that needed the credit.
+      await inventoryReceive.apply(draft.id);
+    } catch (e) {
+      // Compensate the per-location credit so the detail doesn't disagree
+      // with the aggregate, then surface the original failure.
+      try {
+        await inventoryLocations.adjustStock({
+          sku: sku, location_code: locationCode, delta: -qty,
+          reason: "receive: rollback",
+        });
+      } catch (_e2) { /* drop-silent — the original error is the operator's signal */ }
+      throw e;
+    }
+    return adj;
+  }
+
+  // Debit BOTH ledgers for a write-off: the per-location detail (via the
+  // writeoffs primitive, which composes inventoryLocations.adjustStock and
+  // owns the reason-coded audit row) AND the storefront aggregate (catalog
+  // adjustOnHand, which fires the low-stock observer + refuses to eat into
+  // held stock).
+  //
+  // The aggregate mirror is applied BEFORE the write-off is committed as a
+  // real record so the two ledgers never silently diverge. adjustOnHand
+  // returns `{ adjusted: false }` (not a throw) when the debit would eat
+  // into stock already held for paid-but-unfulfilled orders — that's a real
+  // operational conflict (you're writing off units promised to a paid
+  // order), so we reverse the per-location debit and surface it as a
+  // refusal rather than committing a write-off that leaves the storefront
+  // count ahead of the physical shelf. A null result means the SKU is
+  // un-tracked in the catalog aggregate (no inventory row) — the
+  // per-location detail is then the only ledger, and the write-off stands.
+  async function _writeoffFromLocation(input) {
+    var row = await inventoryWriteoffs.recordWriteoff(input);
+    if (input.location_code) {
+      // The per-location debit already landed inside recordWriteoff. Mirror
+      // it onto the storefront aggregate.
+      var mirror = await catalog.inventory.adjustOnHand(input.sku, -input.quantity);
+      if (mirror && mirror.adjusted === false) {
+        // The aggregate refused — reverse the per-location debit AND the
+        // write-off record so neither ledger carries a half-applied move,
+        // then surface the conflict.
+        try {
+          await inventoryWriteoffs.reverseWriteoff({
+            id: row.id,
+            reason: "aggregate-conflict: would oversell held stock",
+          });
+        } catch (_e) { /* drop-silent — the thrown conflict is the operator's signal */ }
+        throw new TypeError("admin.inventory.writeoff: " + input.quantity +
+          " unit(s) of " + input.sku + " can't be written off — that would eat " +
+          "into stock already held for paid orders. Fulfil or cancel those orders first.");
+      }
+    }
+    return row;
+  }
+
+  if (inventoryLocations) {
+    // GET /admin/inventory/locations — location list with per-location
+    // levels for an optional ?sku= drill-down. JSON for the bearer token.
+    router.get("/admin/inventory/locations", _pageOrApi(true,
+      R(async function (req, res) {
+        var rows = await inventoryLocations.listLocations({});
+        _json(res, 200, { rows: rows });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var sku = url && url.searchParams.get("sku");
+        var rows = await inventoryLocations.listLocations({});
+        var levels = null;
+        if (sku) {
+          try { levels = await inventoryLocations.stockForSku(sku); }
+          catch (e) { if (!(e instanceof TypeError)) throw e; levels = null; }
+        }
+        _sendHtml(res, 200, renderAdminInvLocations({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          locations: rows, sku: sku || "", levels: levels,
+          saved:  url && url.searchParams.get("saved"),
+          notice: url && url.searchParams.get("err") ? "That location couldn't be saved — check the fields and try again." : null,
+        }));
+      },
+    ));
+
+    // POST /admin/inventory/locations — defineLocation, or updateLocation
+    // when the code already exists (operator-friendly upsert). A bad shape
+    // is a plain TypeError → 400.
+    router.post("/admin/inventory/locations", _pageOrApi(false,
+      W("inventory.location.save", async function (req, res) {
+        var loc;
+        try { loc = await _saveInvLocationFromBody(req.body || {}); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 201, loc);
+        return loc;
+      }),
+      async function (req, res) {
+        try { await _saveInvLocationFromBody(req.body || {}); }
+        catch (e) { if (e instanceof TypeError) return _redirect(res, "/admin/inventory/locations?err=1"); throw e; }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".inventory.location.save", outcome: "success", metadata: { code: (req.body || {}).code } });
+        _redirect(res, "/admin/inventory/locations?saved=1");
+      },
+    ));
+
+    async function _saveInvLocationFromBody(body) {
+      var input = {
+        code:     body.code,
+        name:     body.name,
+        type:     body.type,
+        priority: body.priority == null || body.priority === "" ? undefined : (parseInt(body.priority, 10)),
+      };
+      if (input.priority !== undefined && !Number.isFinite(input.priority)) {
+        throw new TypeError("admin.inventory.location.save: priority must be an integer");
+      }
+      var existing = await inventoryLocations.getLocation(body.code);
+      if (existing) {
+        var patch = { name: input.name, type: input.type };
+        if (input.priority !== undefined) patch.priority = input.priority;
+        return inventoryLocations.updateLocation(body.code, patch);
+      }
+      return inventoryLocations.defineLocation(input);
+    }
+
+    // POST /admin/inventory/locations/:code/deactivate — soft-delete. The
+    // row survives so historical adjustments still resolve their location.
+    router.post("/admin/inventory/locations/:code/deactivate", _pageOrApi(false,
+      W("inventory.location.deactivate", async function (req, res) {
+        var code = req.params.code;
+        var existing;
+        try { existing = await inventoryLocations.getLocation(code); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        if (!existing) return _problem(res, 404, "inventory-location-not-found");
+        var row = await inventoryLocations.deactivateLocation(code);
+        _json(res, 200, row);
+        return row;
+      }),
+      async function (req, res) {
+        var code = req.params.code;
+        var existing;
+        try { existing = await inventoryLocations.getLocation(code); }
+        catch (e) { if (e instanceof TypeError) return _redirect(res, "/admin/inventory/locations?err=1"); throw e; }
+        if (!existing) return _redirect(res, "/admin/inventory/locations?err=1");
+        await inventoryLocations.deactivateLocation(code);
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".inventory.location.deactivate", outcome: "success", metadata: { code: code } });
+        _redirect(res, "/admin/inventory/locations?saved=1");
+      },
+    ));
+  }
+
+  if (inventoryReceive && inventoryLocations) {
+    // GET /admin/inventory/receive — the receive form + recent receipt
+    // history (the inventory-receive ledger). The form credits a single
+    // (sku, location) line; the history reads the batched-receipt records.
+    router.get("/admin/inventory/receive", _pageOrApi(true,
+      R(async function (req, res) {
+        var page = await inventoryReceive.list({ limit: 50 });
+        _json(res, 200, { rows: page.rows, next_cursor: page.next_cursor });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var locs = await inventoryLocations.listLocations({ active_only: true });
+        var page = await inventoryReceive.list({ limit: 50 });
+        _sendHtml(res, 200, renderAdminInvReceive({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          locations: locs, receipts: page.rows || [],
+          saved:  url && url.searchParams.get("saved"),
+          notice: url && url.searchParams.get("err") ? "That receipt couldn't be recorded — check the SKU, location, and quantity." : null,
+        }));
+      },
+    ));
+
+    // POST /admin/inventory/receive — credit a single (sku, location) line
+    // to both ledgers. quantity must be a positive integer; the location
+    // must exist (adjustStock refuses an unknown one).
+    router.post("/admin/inventory/receive", _pageOrApi(false,
+      W("inventory.receive", async function (req, res) {
+        var body = req.body || {};
+        var qty = parseInt(body.quantity, 10);
+        if (!Number.isInteger(qty) || qty <= 0) return _problem(res, 400, "bad-request", "quantity must be a positive integer");
+        var out;
+        try { out = await _receiveToLocation(body.sku, body.location_code, qty, body.reason); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 201, out);
+        return out;
+      }),
+      async function (req, res) {
+        var body = req.body || {};
+        var qty = parseInt(body.quantity, 10);
+        if (!Number.isInteger(qty) || qty <= 0) return _redirect(res, "/admin/inventory/receive?err=1");
+        try { await _receiveToLocation(body.sku, body.location_code, qty, body.reason); }
+        catch (e) { if (e instanceof TypeError) return _redirect(res, "/admin/inventory/receive?err=1"); throw e; }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".inventory.receive", outcome: "success", metadata: { sku: body.sku, location_code: body.location_code, quantity: qty } });
+        _redirect(res, "/admin/inventory/receive?saved=1");
+      },
+    ));
+  }
+
+  if (stockTransfers && inventoryLocations) {
+    // GET /admin/inventory/transfers — the open-transfer queue + the open
+    // form. The queue shows non-terminal transfers with the FSM actions
+    // legal from each status.
+    router.get("/admin/inventory/transfers", _pageOrApi(true,
+      R(async function (req, res) {
+        var rows = await stockTransfers.listOpen({});
+        _json(res, 200, { rows: rows });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var locs = await inventoryLocations.listLocations({ active_only: true });
+        var rows = await stockTransfers.listOpen({});
+        _sendHtml(res, 200, renderAdminInvTransfers({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          locations: locs, transfers: rows,
+          saved:  url && url.searchParams.get("saved"),
+          notice: url && url.searchParams.get("err") ? "That transfer action couldn't be completed — check stock at the source and the transfer state." : null,
+        }));
+      },
+    ));
+
+    // POST /admin/inventory/transfers — openTransfer for one (sku, qty)
+    // line. Debits the source immediately (stock leaves at dispatch).
+    router.post("/admin/inventory/transfers", _pageOrApi(false,
+      W("inventory.transfer.open", async function (req, res) {
+        var body = req.body || {};
+        var qty = parseInt(body.quantity, 10);
+        if (!Number.isInteger(qty) || qty <= 0) return _problem(res, 400, "bad-request", "quantity must be a positive integer");
+        var t;
+        try {
+          t = await stockTransfers.openTransfer({
+            from_location: body.from_location, to_location: body.to_location,
+            lines: [{ sku: body.sku, quantity: qty }], reason: body.reason,
+          });
+        } catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 201, t);
+        return t;
+      }),
+      async function (req, res) {
+        var body = req.body || {};
+        var qty = parseInt(body.quantity, 10);
+        if (!Number.isInteger(qty) || qty <= 0) return _redirect(res, "/admin/inventory/transfers?err=1");
+        try {
+          await stockTransfers.openTransfer({
+            from_location: body.from_location, to_location: body.to_location,
+            lines: [{ sku: body.sku, quantity: qty }], reason: body.reason,
+          });
+        } catch (e) { if (e instanceof TypeError) return _redirect(res, "/admin/inventory/transfers?err=1"); throw e; }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".inventory.transfer.open", outcome: "success", metadata: { sku: body.sku, from: body.from_location, to: body.to_location, quantity: qty } });
+        _redirect(res, "/admin/inventory/transfers?saved=1");
+      },
+    ));
+
+    // The FSM-action routes: ship → in-transit → receive → reconcile, plus
+    // exception. Each resolves the transfer first (unknown id → err) and
+    // calls the matching primitive verb; a wrong-state transition is a
+    // plain TypeError surfaced as an error redirect / 400.
+    function _transferAction(action, verb) {
+      router.post("/admin/inventory/transfers/:id/" + action, _pageOrApi(false,
+        W("inventory.transfer." + action, async function (req, res) {
+          var id = req.params.id;
+          var out;
+          try { out = await verb(id, req.body || {}); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          _json(res, 200, out);
+          return out;
+        }),
+        async function (req, res) {
+          var id = req.params.id;
+          try { await verb(id, req.body || {}); }
+          catch (e) { if (e instanceof TypeError) return _redirect(res, "/admin/inventory/transfers?err=1"); throw e; }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".inventory.transfer." + action, outcome: "success", metadata: { transfer_id: id } });
+          _redirect(res, "/admin/inventory/transfers?saved=1");
+        },
+      ));
+    }
+    _transferAction("ship", function (id, body) {
+      return stockTransfers.markShipped({ transfer_id: id, carrier: body.carrier || null, tracking_number: body.tracking_number || null });
+    });
+    _transferAction("in-transit", function (id, body) {
+      return stockTransfers.markInTransit({ transfer_id: id, location: body.location || null });
+    });
+    _transferAction("receive", function (id, body) {
+      // Single-line transfers from the open form: receive the full shipped
+      // qty unless the operator overrides quantity_received. Resolve the
+      // shipped line so a blank field receives everything (the happy path).
+      return (async function () {
+        var t = await stockTransfers.getTransfer(id);
+        if (!t) throw new TypeError("transfer not found");
+        var rx = t.lines.map(function (l) {
+          var got = body["rx_" + l.sku];
+          var q = got == null || got === "" ? l.quantity_shipped : parseInt(got, 10);
+          if (!Number.isInteger(q) || q < 0) throw new TypeError("quantity_received must be a non-negative integer");
+          return { sku: l.sku, quantity_received: q };
+        });
+        return stockTransfers.markReceived({ transfer_id: id, received_lines: rx });
+      })();
+    });
+    _transferAction("reconcile", function (id) {
+      return stockTransfers.reconcile({ transfer_id: id });
+    });
+    _transferAction("exception", function (id, body) {
+      return stockTransfers.markException({ transfer_id: id, reason: body.reason });
+    });
+  }
+
+  if (inventoryWriteoffs && inventoryLocations) {
+    // GET /admin/inventory/writeoffs — the write-off log + the record form.
+    router.get("/admin/inventory/writeoffs", _pageOrApi(true,
+      R(async function (req, res) {
+        var page = await inventoryWriteoffs.listWriteoffs({ limit: 50 });
+        _json(res, 200, { rows: page.rows, next_cursor: page.next_cursor });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var locs = await inventoryLocations.listLocations({ active_only: true });
+        var page = await inventoryWriteoffs.listWriteoffs({ limit: 50 });
+        _sendHtml(res, 200, renderAdminInvWriteoffs({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          locations: locs, writeoffs: page.rows || [],
+          reasons: inventoryWriteoffsModule.WRITEOFF_REASONS,
+          saved:  url && url.searchParams.get("saved"),
+          notice: url && url.searchParams.get("err") ? "That write-off couldn't be recorded — check the SKU, location, quantity, and reason." : null,
+        }));
+      },
+    ));
+
+    // POST /admin/inventory/writeoffs — recordWriteoff against a location +
+    // mirror the debit onto the storefront aggregate.
+    router.post("/admin/inventory/writeoffs", _pageOrApi(false,
+      W("inventory.writeoff", async function (req, res) {
+        var body = req.body || {};
+        var qty = parseInt(body.quantity, 10);
+        if (!Number.isInteger(qty) || qty <= 0) return _problem(res, 400, "bad-request", "quantity must be a positive integer");
+        var row;
+        try {
+          row = await _writeoffFromLocation({
+            sku: body.sku, location_code: body.location_code, quantity: qty,
+            reason: body.reason, actor: body.actor || "admin-console", notes: body.notes || null,
+          });
+        } catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 201, row);
+        return row;
+      }),
+      async function (req, res) {
+        var body = req.body || {};
+        var qty = parseInt(body.quantity, 10);
+        if (!Number.isInteger(qty) || qty <= 0) return _redirect(res, "/admin/inventory/writeoffs?err=1");
+        try {
+          await _writeoffFromLocation({
+            sku: body.sku, location_code: body.location_code, quantity: qty,
+            reason: body.reason, actor: body.actor || "admin-console", notes: body.notes || null,
+          });
+        } catch (e) { if (e instanceof TypeError) return _redirect(res, "/admin/inventory/writeoffs?err=1"); throw e; }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".inventory.writeoff", outcome: "success", metadata: { sku: body.sku, location_code: body.location_code, quantity: qty, reason: body.reason } });
+        _redirect(res, "/admin/inventory/writeoffs?saved=1");
+      },
+    ));
+  }
+
   // ---- gift wraps -----------------------------------------------------
   //
   // The operator-defined gift-wrap catalog: define / update / archive a wrap
@@ -11946,6 +12351,10 @@ var ADMIN_NAV_ITEMS = [
   { key: "dashboard",    href: "/admin/dashboard",    label: "Dashboard" },
   { key: "products",     href: "/admin/products",     label: "Products" },
   { key: "inventory",    href: "/admin/inventory",    label: "Inventory" },
+  { key: "inventory-locations", href: "/admin/inventory/locations", label: "Stock locations", requires: "inventoryLocations" },
+  { key: "inventory-receive",   href: "/admin/inventory/receive",   label: "Receive stock",   requires: "inventoryReceive" },
+  { key: "inventory-transfers", href: "/admin/inventory/transfers", label: "Transfers",       requires: "stockTransfers" },
+  { key: "inventory-writeoffs", href: "/admin/inventory/writeoffs", label: "Write-offs",      requires: "inventoryWriteoffs" },
   { key: "orders",       href: "/admin/orders",       label: "Orders" },
   { key: "carts",        href: "/admin/carts",        label: "Abandoned carts", requires: "carts" },
   { key: "reports",      href: "/admin/reports",      label: "Reports" },
@@ -14687,6 +15096,236 @@ function renderAdminPickupLocations(opts) {
   return _renderAdminShell(opts.shop_name, "Pickup locations", body, "pickup-locations", opts.nav_available);
 }
 
+// Stock-location list + the define/update form + an optional per-SKU
+// levels drill-down. Location names and codes are operator free text —
+// escaped at the sink.
+function renderAdminInvLocations(opts) {
+  opts = opts || {};
+  var list = opts.locations || [];
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Stock location saved.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var rows = list.map(function (l) {
+    return "<tr>" +
+      "<td><code class=\"order-id\">" + _htmlEscape(l.code) + "</code></td>" +
+      "<td>" + _htmlEscape(l.name) + "</td>" +
+      "<td>" + _htmlEscape(l.type) + "</td>" +
+      "<td>" + _htmlEscape(String(l.priority)) + "</td>" +
+      "<td>" + (l.active ? "<span class=\"status-pill\">active</span>" : "<span class=\"meta\">inactive</span>") + "</td>" +
+      "<td>" +
+        (l.active
+          ? "<form method=\"post\" action=\"/admin/inventory/locations/" + encodeURIComponent(l.code) + "/deactivate\" class=\"form-inline\">" +
+              "<button class=\"btn btn--ghost btn--sm\" type=\"submit\">Deactivate</button></form>"
+          : "<span class=\"meta\">—</span>") +
+      "</td>" +
+      "</tr>";
+  }).join("");
+
+  var table = list.length
+    ? "<div class=\"panel\">" + _tableWrap("<table><thead><tr><th scope=\"col\">Code</th><th scope=\"col\">Name</th><th scope=\"col\">Type</th><th scope=\"col\">Priority</th><th scope=\"col\">Status</th><th scope=\"col\">Action</th></tr></thead><tbody>" + rows + "</tbody></table>") + "</div>"
+    : "<p class=\"empty\">No stock locations yet. A store with one warehouse needs no location — the default bucket is implicit. Add a location below once you ship from more than one place.</p>";
+
+  // Per-SKU levels drill-down.
+  var levelsBlock = "";
+  if (opts.levels) {
+    var lv = opts.levels;
+    var lvRows = (lv.by_location || []).map(function (r) {
+      return "<tr><td><code class=\"order-id\">" + _htmlEscape(r.code) + "</code></td><td>" + _htmlEscape(String(r.quantity)) + "</td></tr>";
+    }).join("");
+    levelsBlock =
+      "<div class=\"panel mt\"><h3 class=\"subhead\">Levels for " + _htmlEscape(opts.sku) + " — total " + _htmlEscape(String(lv.total)) + "</h3>" +
+        (lv.by_location && lv.by_location.length
+          ? _tableWrap("<table><thead><tr><th scope=\"col\">Location</th><th scope=\"col\">On hand</th></tr></thead><tbody>" + lvRows + "</tbody></table>")
+          : "<p class=\"empty\">No per-location stock recorded for this SKU.</p>") +
+      "</div>";
+  }
+  var lookup =
+    "<div class=\"panel mt\"><h3 class=\"subhead\">Per-location levels</h3>" +
+      "<form method=\"get\" action=\"/admin/inventory/locations\" class=\"form-inline\">" +
+        _setupField("SKU", "sku", opts.sku || "", "text", "Show the per-location breakdown for one SKU.", " maxlength=\"128\"") +
+        "<button class=\"btn btn--ghost btn--sm\" type=\"submit\">Look up</button>" +
+      "</form>" + levelsBlock +
+    "</div>";
+
+  var form =
+    "<div class=\"panel mt\"><h3 class=\"subhead\">Add / update a stock location</h3>" +
+      "<form method=\"post\" action=\"/admin/inventory/locations\">" +
+        _setupField("Code", "code", "", "text", "Stable identifier (alnum + . _ -). Re-using a code updates that location.", " maxlength=\"64\" required") +
+        _setupField("Name", "name", "", "text", "Operator-facing label (e.g. East warehouse).", " maxlength=\"128\" required") +
+        "<label class=\"form-field\"><span>Type</span>" +
+          "<select name=\"type\" required>" +
+            "<option value=\"warehouse\">warehouse</option>" +
+            "<option value=\"retail\">retail</option>" +
+            "<option value=\"dropship\">dropship</option>" +
+          "</select>" +
+          "<small>Drives default routing weight; override with priority.</small>" +
+        "</label>" +
+        _setupField("Priority", "priority", "", "number", "Lower picks first (default 100).", " min=\"0\"") +
+        "<div class=\"actions-row\"><button type=\"submit\" class=\"btn\">Save location</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var body = "<section><h2>Stock locations</h2>" + saved + notice + table + lookup + form + "</section>";
+  return _renderAdminShell(opts.shop_name, "Stock locations", body, "inventory-locations", opts.nav_available);
+}
+
+// Receive inbound stock against a location. Credits both the per-location
+// detail and the storefront aggregate. Recent receipts (the batched
+// inventory-receive ledger) render below the form. Reference / supplier
+// are operator free text — escaped at the sink.
+function renderAdminInvReceive(opts) {
+  opts = opts || {};
+  var locs = opts.locations || [];
+  var receipts = opts.receipts || [];
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Stock received.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var locOptions = locs.map(function (l) {
+    return "<option value=\"" + _htmlEscape(l.code) + "\">" + _htmlEscape(l.name) + " (" + _htmlEscape(l.code) + ")</option>";
+  }).join("");
+
+  var form = locs.length
+    ? "<div class=\"panel\"><h3 class=\"subhead\">Receive stock</h3>" +
+        "<form method=\"post\" action=\"/admin/inventory/receive\">" +
+          _setupField("SKU", "sku", "", "text", "", " maxlength=\"128\" required") +
+          "<label class=\"form-field\"><span>Location</span><select name=\"location_code\" required>" + locOptions + "</select></label>" +
+          _setupField("Quantity", "quantity", "", "number", "Units received (positive).", " min=\"1\" required") +
+          _setupField("Reason / reference", "reason", "", "text", "Optional — PO number, supplier, note.", " maxlength=\"256\"") +
+          "<div class=\"actions-row\"><button type=\"submit\" class=\"btn\">Receive</button></div>" +
+        "</form></div>"
+    : "<p class=\"empty\">Add a stock location first, then receive stock against it.</p>";
+
+  var recRows = receipts.map(function (r) {
+    return "<tr>" +
+      "<td>" + _htmlEscape(String(r.reference || "")) + "</td>" +
+      "<td>" + _htmlEscape(String(r.supplier || "")) + "</td>" +
+      "<td><span class=\"status-pill\">" + _htmlEscape(String(r.status)) + "</span></td>" +
+      "<td>" + _htmlEscape(String(r.total_qty)) + "</td>" +
+      "<td>" + _htmlEscape(_fmtDate(r.received_at)) + "</td>" +
+      "</tr>";
+  }).join("");
+  var history = receipts.length
+    ? "<div class=\"panel mt\"><h3 class=\"subhead\">Recent receipts</h3>" +
+        _tableWrap("<table><thead><tr><th scope=\"col\">Reference</th><th scope=\"col\">Supplier</th><th scope=\"col\">Status</th><th scope=\"col\">Qty</th><th scope=\"col\">Received</th></tr></thead><tbody>" + recRows + "</tbody></table>") +
+      "</div>"
+    : "";
+
+  var body = "<section><h2>Receive stock</h2>" + saved + notice + form + history + "</section>";
+  return _renderAdminShell(opts.shop_name, "Receive stock", body, "inventory-receive", opts.nav_available);
+}
+
+// Location→location transfer console: the open form + the open-transfer
+// queue with the FSM action legal from each row's status. Reasons,
+// carriers, and tracking numbers are operator free text — escaped.
+function renderAdminInvTransfers(opts) {
+  opts = opts || {};
+  var locs = opts.locations || [];
+  var transfers = opts.transfers || [];
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Transfer updated.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var locOptions = locs.map(function (l) {
+    return "<option value=\"" + _htmlEscape(l.code) + "\">" + _htmlEscape(l.name) + " (" + _htmlEscape(l.code) + ")</option>";
+  }).join("");
+
+  function _transferActions(t) {
+    var blocks = [];
+    var act = function (action, label, extra) {
+      return "<form method=\"post\" action=\"/admin/inventory/transfers/" + encodeURIComponent(t.id) + "/" + action + "\" class=\"form-inline\">" +
+        (extra || "") + "<button class=\"btn btn--sm\" type=\"submit\">" + _htmlEscape(label) + "</button></form>";
+    };
+    if (t.status === "open") blocks.push(act("ship", "Mark shipped"));
+    if (t.status === "shipped" || t.status === "in_transit") {
+      blocks.push(act("receive", "Mark received"));
+    }
+    if (t.status === "received") blocks.push(act("reconcile", "Reconcile"));
+    if (t.status !== "reconciled" && t.status !== "exception") {
+      blocks.push(act("exception", "Exception",
+        "<input type=\"text\" name=\"reason\" placeholder=\"reason\" maxlength=\"280\" required>"));
+    }
+    return blocks.length ? blocks.join("") : "<span class=\"meta\">—</span>";
+  }
+
+  var rows = transfers.map(function (t) {
+    var lineSummary = (t.lines || []).map(function (l) {
+      return _htmlEscape(l.sku) + "×" + _htmlEscape(String(l.quantity_shipped));
+    }).join(", ");
+    return "<tr>" +
+      "<td><code class=\"order-id\">" + _htmlEscape(String(t.id).slice(0, 8)) + "</code></td>" +
+      "<td>" + _htmlEscape(t.from_location) + " → " + _htmlEscape(t.to_location) + "</td>" +
+      "<td>" + lineSummary + "</td>" +
+      "<td><span class=\"status-pill\">" + _htmlEscape(t.status) + "</span></td>" +
+      "<td>" + _transferActions(t) + "</td>" +
+      "</tr>";
+  }).join("");
+
+  var queue = transfers.length
+    ? "<div class=\"panel\">" + _tableWrap("<table><thead><tr><th scope=\"col\">ID</th><th scope=\"col\">Route</th><th scope=\"col\">Lines</th><th scope=\"col\">Status</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + rows + "</tbody></table>") + "</div>"
+    : "<p class=\"empty\">No open transfers.</p>";
+
+  var form = locs.length >= 2
+    ? "<div class=\"panel mt\"><h3 class=\"subhead\">Open a transfer</h3>" +
+        "<form method=\"post\" action=\"/admin/inventory/transfers\">" +
+          "<label class=\"form-field\"><span>From</span><select name=\"from_location\" required>" + locOptions + "</select></label>" +
+          "<label class=\"form-field\"><span>To</span><select name=\"to_location\" required>" + locOptions + "</select></label>" +
+          _setupField("SKU", "sku", "", "text", "", " maxlength=\"128\" required") +
+          _setupField("Quantity", "quantity", "", "number", "Units to move (leaves the source immediately).", " min=\"1\" required") +
+          _setupField("Reason", "reason", "", "text", "Optional note.", " maxlength=\"280\"") +
+          "<div class=\"actions-row\"><button type=\"submit\" class=\"btn\">Open transfer</button></div>" +
+        "</form></div>"
+    : "<p class=\"empty\">Define at least two stock locations to transfer between them.</p>";
+
+  var body = "<section><h2>Stock transfers</h2>" + saved + notice + queue + form + "</section>";
+  return _renderAdminShell(opts.shop_name, "Transfers", body, "inventory-transfers", opts.nav_available);
+}
+
+// Reason-coded write-off log + record form. SKU, reason, notes, and actor
+// are operator free text — escaped at the sink.
+function renderAdminInvWriteoffs(opts) {
+  opts = opts || {};
+  var locs = opts.locations || [];
+  var list = opts.writeoffs || [];
+  var reasons = opts.reasons || [];
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Write-off recorded.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var locOptions = locs.map(function (l) {
+    return "<option value=\"" + _htmlEscape(l.code) + "\">" + _htmlEscape(l.name) + " (" + _htmlEscape(l.code) + ")</option>";
+  }).join("");
+  var reasonOptions = reasons.map(function (r) {
+    return "<option value=\"" + _htmlEscape(r) + "\">" + _htmlEscape(r) + "</option>";
+  }).join("");
+
+  var rows = list.map(function (w) {
+    return "<tr>" +
+      "<td>" + _htmlEscape(String(w.sku)) + "</td>" +
+      "<td>" + (w.location_code ? "<code class=\"order-id\">" + _htmlEscape(String(w.location_code)) + "</code>" : "<span class=\"meta\">—</span>") + "</td>" +
+      "<td>" + _htmlEscape(String(w.quantity)) + "</td>" +
+      "<td>" + _htmlEscape(String(w.reason)) + "</td>" +
+      "<td><span class=\"status-pill\">" + _htmlEscape(String(w.status)) + "</span></td>" +
+      "<td>" + _htmlEscape(_fmtDate(w.occurred_at)) + "</td>" +
+      "</tr>";
+  }).join("");
+  var table = list.length
+    ? "<div class=\"panel\">" + _tableWrap("<table><thead><tr><th scope=\"col\">SKU</th><th scope=\"col\">Location</th><th scope=\"col\">Qty</th><th scope=\"col\">Reason</th><th scope=\"col\">Status</th><th scope=\"col\">When</th></tr></thead><tbody>" + rows + "</tbody></table>") + "</div>"
+    : "<p class=\"empty\">No write-offs recorded.</p>";
+
+  var form = locs.length
+    ? "<div class=\"panel mt\"><h3 class=\"subhead\">Record a write-off</h3>" +
+        "<form method=\"post\" action=\"/admin/inventory/writeoffs\">" +
+          _setupField("SKU", "sku", "", "text", "", " maxlength=\"128\" required") +
+          "<label class=\"form-field\"><span>Location</span><select name=\"location_code\" required>" + locOptions + "</select></label>" +
+          _setupField("Quantity", "quantity", "", "number", "Units removed (positive).", " min=\"1\" required") +
+          "<label class=\"form-field\"><span>Reason</span><select name=\"reason\" required>" + reasonOptions + "</select></label>" +
+          _setupField("Notes", "notes", "", "text", "Optional.", " maxlength=\"4096\"") +
+          "<div class=\"actions-row\"><button type=\"submit\" class=\"btn btn--danger\">Record write-off</button></div>" +
+        "</form></div>"
+    : "<p class=\"empty\">Add a stock location first, then record write-offs against it.</p>";
+
+  var body = "<section><h2>Write-offs</h2>" + saved + notice + table + form + "</section>";
+  return _renderAdminShell(opts.shop_name, "Write-offs", body, "inventory-writeoffs", opts.nav_available);
+}
+
 // Pickup queue for one location: a location selector + status chips, the
 // scheduled/ready rows, and the FSM action forms (ready / picked-up /
 // no-show) legal from each row's status. The no_show reason is operator-

package/lib/asset-manifest.json

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

package/lib/catalog.js

@@ -11,7 +11,7 @@
  *   - `variants`   — create, get, listForProduct, update, delete
  *   - `prices`     — set (versioned), current, history
  *   - `inventory`  — create, get, list, hold, decrement, release,
- *                    restock, setThreshold, checkLowStock
+ *                    restock, adjustOnHand, setThreshold, checkLowStock
  *   - `media`      — attach, get, listForProduct, listForVariant, delete,
  *                    reorder, setPrimary
  *
@@ -706,6 +706,56 @@ function _inventoryModule(query, opts) {
       return await this.get(sku);
     },
 
+    // Signed-delta adjustment of the storefront aggregate, fired by the
+    // inventory-ops back-office when a per-location move changes the
+    // total a single-bucket storefront sells against (a receive credits
+    // the aggregate, a write-off / shrinkage debits it). `restock` only
+    // grows on-hand and `decrement` only consumes a matching hold;
+    // neither expresses "the warehouse count just dropped by 5 because a
+    // pallet was damaged." A positive delta is an unconditional credit.
+    // A negative delta is an atomic conditional UPDATE — the
+    // `stock_on_hand - stock_held >= need` guard refuses (zero rows →
+    // `{ adjusted: false }`) when the debit would eat into stock that is
+    // already held for in-flight orders, so a write-off can never
+    // oversell a paid-but-unfulfilled line. Returns `{ adjusted, sku,
+    // delta }`; `null` when the SKU has no inventory row at all
+    // (un-tracked SKUs are unlimited everywhere in the storefront, so an
+    // aggregate adjustment simply doesn't apply). Fires the low-stock
+    // observer on success so a debit that crosses the threshold alerts.
+    adjustOnHand: async function (sku, delta) {
+      _sku(sku);
+      if (!Number.isInteger(delta) || delta === 0) {
+        throw new TypeError("catalog.inventory.adjustOnHand: delta must be a non-zero integer");
+      }
+      var ts = _now();
+      if (delta > 0) {
+        var rUp = await query(
+          "UPDATE inventory SET stock_on_hand = stock_on_hand + ?1, updated_at = ?2 WHERE sku = ?3",
+          [delta, ts, sku],
+        );
+        if (rUp.rowCount === 0) return null;
+        await _afterMutation(sku);
+        return { adjusted: true, sku: sku, delta: delta };
+      }
+      var need = -delta;
+      var rDown = await query(
+        "UPDATE inventory SET stock_on_hand = stock_on_hand - ?1, updated_at = ?2 " +
+        "WHERE sku = ?3 AND (stock_on_hand - stock_held) >= ?1",
+        [need, ts, sku],
+      );
+      if (rDown.rowCount === 1) {
+        await _afterMutation(sku);
+        return { adjusted: true, sku: sku, delta: delta };
+      }
+      // Zero rows: either no inventory row (un-tracked SKU) or the debit
+      // would eat into held stock. Distinguish so the caller can let an
+      // un-tracked SKU through while refusing a tracked-but-insufficient
+      // one.
+      var existing = await this.get(sku);
+      if (!existing) return null;
+      return { adjusted: false, sku: sku, delta: delta };
+    },
+
     release: async function (sku, qty) {
       _sku(sku);
       _positiveInt(qty, "qty");

package/lib/inventory-locations.js

@@ -32,12 +32,20 @@
  *                              duplicate code, invalid type, etc).
  *     listLocations / getLocation / updateLocation / deactivateLocation
  *                            — operator CRUD over the location set.
- *     setStock               — absolute set (overwrite).
- *     adjustStock            — relative delta with audit row.
- *     transferStock          — atomic two-row write moving qty
- *                              from one location to another; if
- *                              the source doesn't have enough, the
- *                              whole transfer refuses (no money
+ *     setStock               — absolute set (overwrite) via an
+ *                              atomic upsert.
+ *     adjustStock            — relative delta with audit row. Debits
+ *                              run as a single conditional UPDATE
+ *                              (`quantity >= need`); credits as an
+ *                              upsert. No read-then-write window — a
+ *                              debit that would drive the row below
+ *                              zero matches no rows and refuses.
+ *     transferStock          — moves qty from one location to
+ *                              another; the source debit is the same
+ *                              conditional UPDATE guard, so a transfer
+ *                              racing a checkout debit (or another
+ *                              transfer) for the last unit can't
+ *                              oversell — the loser refuses (no money
  *                              created, no row half-committed).
  *     stockForSku            — `{ total, by_location: [...] }`.
  *     totalForSku            — sum across every location.
@@ -521,20 +529,21 @@ function create(opts) {
         throw new TypeError("inventory-locations.setStock: location_code " +
           JSON.stringify(input.location_code) + " not found");
       }
+      // Absolute set is last-writer-wins by contract — the operator is
+      // declaring the authoritative count, not applying a relative
+      // change. The prior value is read only to record the signed
+      // delta on the audit row; the upsert itself is a single atomic
+      // statement so a first-touch insert and an overwrite never
+      // collide on the composite PK.
       var prev = await _getStockRow(input.sku, input.location_code);
       var prevQty = prev ? prev.quantity : 0;
       var ts = _now();
-      if (prev) {
-        await query(
-          "UPDATE inventory_stock SET quantity = ?1, updated_at = ?2 WHERE sku = ?3 AND location_code = ?4",
-          [input.quantity, ts, input.sku, input.location_code],
-        );
-      } else {
-        await query(
-          "INSERT INTO inventory_stock (sku, location_code, quantity, updated_at) VALUES (?1, ?2, ?3, ?4)",
-          [input.sku, input.location_code, input.quantity, ts],
-        );
-      }
+      await query(
+        "INSERT INTO inventory_stock (sku, location_code, quantity, updated_at) " +
+        "VALUES (?1, ?2, ?3, ?4) " +
+        "ON CONFLICT(sku, location_code) DO UPDATE SET quantity = ?3, updated_at = ?4",
+        [input.sku, input.location_code, input.quantity, ts],
+      );
       var delta = input.quantity - prevQty;
       await _audit(input.sku, input.location_code, delta, _reason(input.reason));
       return { sku: input.sku, location_code: input.location_code, quantity: input.quantity, delta: delta };
@@ -545,6 +554,18 @@ function create(opts) {
     // row below zero refuses the whole operation. Inserts a row
     // at quantity 0 + delta if the (sku, location_code) pair has
     // never been touched before (and delta is positive).
+    //
+    // Concurrency: the negative-delta path is a single atomic
+    // conditional UPDATE — `SET quantity = quantity + delta WHERE
+    // quantity + delta >= 0` — mirroring the catalog hold/decrement
+    // guards. D1 evaluates the predicate and applies the write inside
+    // one statement, so two racing debits against the last unit can't
+    // both succeed: the second racer's predicate sees the first's
+    // decrement and matches zero rows. The positive-delta path is an
+    // upsert (ON CONFLICT DO UPDATE) so a credit and a fresh-row
+    // insert never collide. Both paths re-read the post-write quantity
+    // for the audit row + return value rather than trusting a stale
+    // pre-read.
     adjustStock: async function (input) {
       if (!input || typeof input !== "object") {
         throw new TypeError("inventory-locations.adjustStock: input object required");
@@ -560,28 +581,42 @@ function create(opts) {
         throw new TypeError("inventory-locations.adjustStock: location_code " +
           JSON.stringify(input.location_code) + " not found");
       }
-      var prev = await _getStockRow(input.sku, input.location_code);
-      var prevQty = prev ? prev.quantity : 0;
-      var next = prevQty + input.delta;
-      if (next < 0) {
-        throw new TypeError("inventory-locations.adjustStock: delta " + input.delta +
-          " would drive stock below zero (current=" + prevQty + ", sku=" + input.sku +
-          ", location=" + input.location_code + ")");
-      }
       var ts = _now();
-      if (prev) {
+      if (input.delta > 0) {
+        // Credit: upsert in one atomic statement. A concurrent credit
+        // + first-touch insert serialize on the composite PK.
         await query(
-          "UPDATE inventory_stock SET quantity = ?1, updated_at = ?2 WHERE sku = ?3 AND location_code = ?4",
-          [next, ts, input.sku, input.location_code],
+          "INSERT INTO inventory_stock (sku, location_code, quantity, updated_at) " +
+          "VALUES (?1, ?2, ?3, ?4) " +
+          "ON CONFLICT(sku, location_code) DO UPDATE SET " +
+          "quantity = quantity + ?3, updated_at = ?4",
+          [input.sku, input.location_code, input.delta, ts],
         );
       } else {
-        await query(
-          "INSERT INTO inventory_stock (sku, location_code, quantity, updated_at) VALUES (?1, ?2, ?3, ?4)",
-          [input.sku, input.location_code, next, ts],
+        // Debit: atomic conditional UPDATE. The WHERE predicate is the
+        // serialization point — it refuses the write (zero rows) when
+        // the shelf lacks enough to cover the debit, so the row never
+        // goes negative even under concurrent debits. A SKU with no
+        // row at this location can't be debited (no negative
+        // first-touch); zero rows there is the insufficient case too.
+        var need = -input.delta;
+        var r = await query(
+          "UPDATE inventory_stock SET quantity = quantity + ?1, updated_at = ?2 " +
+          "WHERE sku = ?3 AND location_code = ?4 AND quantity >= ?5",
+          [input.delta, ts, input.sku, input.location_code, need],
         );
+        if (r.rowCount === 0) {
+          var cur = await _getStockRow(input.sku, input.location_code);
+          var have = cur ? cur.quantity : 0;
+          throw new TypeError("inventory-locations.adjustStock: delta " + input.delta +
+            " would drive stock below zero (current=" + have + ", sku=" + input.sku +
+            ", location=" + input.location_code + ")");
+        }
       }
+      var after = await _getStockRow(input.sku, input.location_code);
+      var nextQty = after ? after.quantity : 0;
       await _audit(input.sku, input.location_code, input.delta, _reason(input.reason));
-      return { sku: input.sku, location_code: input.location_code, quantity: next, delta: input.delta };
+      return { sku: input.sku, location_code: input.location_code, quantity: nextQty, delta: input.delta };
     },
 
     // Atomic two-row move. Reads the source quantity; if
@@ -612,44 +647,44 @@ function create(opts) {
           JSON.stringify(input.to_location) + " not found");
       }
 
-      var fromRow = await _getStockRow(input.sku, input.from_location);
-      var fromQty = fromRow ? fromRow.quantity : 0;
-      if (fromQty < input.quantity) {
-        throw new TypeError("inventory-locations.transferStock: insufficient stock at " +
-          input.from_location + " (have " + fromQty + ", need " + input.quantity + ")");
-      }
-      var toRow = await _getStockRow(input.sku, input.to_location);
-      var toQty = toRow ? toRow.quantity : 0;
-
       var ts = _now();
-      // Decrement source first. If the destination upsert below
-      // fails for any reason, the rollback path re-increments the
-      // source so the invariant (total quantity unchanged) holds.
-      await query(
-        "UPDATE inventory_stock SET quantity = ?1, updated_at = ?2 WHERE sku = ?3 AND location_code = ?4",
-        [fromQty - input.quantity, ts, input.sku, input.from_location],
+      // Debit the source with a single atomic conditional UPDATE. The
+      // `quantity >= need` predicate is the serialization point: two
+      // racing transfers (or a transfer racing a checkout debit)
+      // against the last unit can't both succeed — the second sees the
+      // first's decrement and matches zero rows, which we surface as
+      // the insufficient-stock refusal. No read-then-write window.
+      var srcDebit = await query(
+        "UPDATE inventory_stock SET quantity = quantity - ?1, updated_at = ?2 " +
+        "WHERE sku = ?3 AND location_code = ?4 AND quantity >= ?1",
+        [input.quantity, ts, input.sku, input.from_location],
       );
+      if (srcDebit.rowCount === 0) {
+        var fromRow = await _getStockRow(input.sku, input.from_location);
+        var fromHave = fromRow ? fromRow.quantity : 0;
+        throw new TypeError("inventory-locations.transferStock: insufficient stock at " +
+          input.from_location + " (have " + fromHave + ", need " + input.quantity + ")");
+      }
       try {
-        if (toRow) {
-          await query(
-            "UPDATE inventory_stock SET quantity = ?1, updated_at = ?2 WHERE sku = ?3 AND location_code = ?4",
-            [toQty + input.quantity, ts, input.sku, input.to_location],
-          );
-        } else {
-          await query(
-            "INSERT INTO inventory_stock (sku, location_code, quantity, updated_at) VALUES (?1, ?2, ?3, ?4)",
-            [input.sku, input.to_location, input.quantity, ts],
-          );
-        }
+        // Credit the destination via an atomic upsert. A concurrent
+        // credit + first-touch insert serialize on the composite PK.
+        await query(
+          "INSERT INTO inventory_stock (sku, location_code, quantity, updated_at) " +
+          "VALUES (?1, ?2, ?3, ?4) " +
+          "ON CONFLICT(sku, location_code) DO UPDATE SET " +
+          "quantity = quantity + ?3, updated_at = ?4",
+          [input.sku, input.to_location, input.quantity, ts],
+        );
       } catch (e) {
-        // Best-effort compensating restore on the source so the
-        // pair stays balanced. If THIS write also fails the
-        // operator will see two adjacent audit rows with no
-        // counterpart — the caller can replay or reconcile.
+        // Best-effort compensating restore on the source so the pair
+        // stays balanced. The restore is itself an atomic increment
+        // (no read-then-write), so it can't clobber a concurrent
+        // mutation that landed between the debit and this catch.
         try {
           await query(
-            "UPDATE inventory_stock SET quantity = ?1, updated_at = ?2 WHERE sku = ?3 AND location_code = ?4",
-            [fromQty, _now(), input.sku, input.from_location],
+            "UPDATE inventory_stock SET quantity = quantity + ?1, updated_at = ?2 " +
+            "WHERE sku = ?3 AND location_code = ?4",
+            [input.quantity, _now(), input.sku, input.from_location],
           );
         } catch (_e2) { /* drop-silent — the original error is what the caller needs to fix */ }
         throw e;
@@ -659,13 +694,15 @@ function create(opts) {
       await _audit(input.sku, input.from_location, -input.quantity, reason);
       await _audit(input.sku, input.to_location,    input.quantity, reason);
 
+      var fromAfterRow = await _getStockRow(input.sku, input.from_location);
+      var toAfterRow   = await _getStockRow(input.sku, input.to_location);
       return {
         sku:           input.sku,
         from_location: input.from_location,
         to_location:   input.to_location,
         quantity:      input.quantity,
-        from_after:    fromQty - input.quantity,
-        to_after:      toQty + input.quantity,
+        from_after:    fromAfterRow ? fromAfterRow.quantity : 0,
+        to_after:      toAfterRow ? toAfterRow.quantity : 0,
       };
     },
 

package/package.json

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