@blamejs/blamejs-shop 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.2 (2026-06-05) — **Abandoned checkouts release their stock holds, and five more inventory and admin hardening fixes.** The inventory enforcement introduced in 0.4.0 placed a stock hold at checkout but had no path to free it when a buyer abandoned without paying or cancelling — each abandoned checkout permanently subtracted from sellable stock until an operator intervened. A scheduled reaper now cancels pending orders older than a configurable age (default two hours), cancelling the payment intent first so a late payment can never complete against a reaped order, and releasing the held stock through the existing cancellation path. Around it, five more fixes harden the same surface: settlement failures during payment confirmation no longer strand holds silently (each item settles independently and failures land in the operator error log with the exact item and quantity), a rollback path no longer releases holds belonging to an order that was successfully created, pre-order campaigns whose launch date has passed now enforce real stock limits instead of remaining exempt, the admin activity timeline rejects protocol-relative link targets, and activity reads are bounded instead of scanning a customer's full history per page view. **Fixed:** *Stock holds from abandoned checkouts are reclaimed* — A pending order that never completes payment now has its stock hold released automatically. The scheduled reaper cancels pending orders older than CHECKOUT_PENDING_TTL_MINUTES (default 120, minimum 5; invalid values refuse to boot). For card payments the payment intent is cancelled at the processor before the order is touched — if the processor reports the payment already succeeded, the order is left alone for the webhook to settle. Each sweep reports counts of reaped, skipped, and errored orders. · *Payment settlement is crash-safe per item* — When an order is marked paid, each line's stock decrement now settles independently: one item's database failure no longer blocks the others, no longer fails the payment webhook, and is captured to the operator error log naming the item, quantity, and order so the operator can reconcile stock from the existing adjustment screen. · *Checkout rollback no longer releases holds it does not own* — If checkout fails after the order record was created, the error path previously released all of the attempt's stock holds — which could free units belonging to the order itself or, on a shared item, a concurrent shopper's reservation. Holds are now released on failure only when no order was created; once an order exists it owns its holds, and cancellation or the reaper frees them. The same correction applies to the PayPal order-creation path. · *Pre-order campaigns enforce stock after their launch date* — An active pre-order campaign exempts its product from stock holds by design — pre-orders sell beyond the shelf. That exemption now ends when the campaign's launch date passes: a launched product sells from real inventory even if the campaign has not yet been moved out of its pre-order state in the console. · *Admin activity links and reads hardened* — The customer activity timeline's internal-link guard now rejects protocol-relative targets, and each activity source is read with a bound matching the requested page instead of scanning the customer's entire history. Pagination, ordering, and the summary counts are unchanged.
+
+- v0.4.1 (2026-06-05) — **Order notes and a customer activity timeline in the admin console.** Two operator surfaces land in the admin console. Every order detail screen gains a customer-service notes thread: operators record internal notes or customer-visible ones, pin the important thread to the top, and mark issues resolved or reopen them — with note bodies length-bounded, control-character-rejected, and escaped at render. Every customer detail screen gains a read-only activity timeline aggregating what that customer has done across the store — orders placed and their lifecycle transitions, loyalty points earned, wishlist additions, reviews submitted, and support tickets opened — read directly from the tables those features already populate, newest first. Both panels appear only when their backing modules are wired, and every note mutation is ownership-scoped to its order and audited. **Added:** *Customer-service notes on order detail* — The admin order screen shows a notes thread with pinned notes floated first and the rest newest-first. Operators add notes as internal (the default) or customer-visible, pin and unpin them, and resolve or reopen them with a short resolution summary; resolving a customer-visible note is refused so customer-facing context is never silently closed out. Bodies are validated server-side (8000-character cap, control characters rejected) and HTML-escaped at render. Each mutation verifies the note belongs to the order in the URL before acting, returns clean errors for unknown or malformed identifiers, and emits an audit event. The same surface is available as JSON under the admin bearer token. · *Customer activity timeline on customer detail* — The admin customer screen shows an aggregated, newest-first activity feed: order placements and status transitions, loyalty point movements, wishlist additions, review submissions, and support tickets. The timeline is a read-only view over the tables those features already write — no new tracking or recording was added anywhere in the request path. The panel shows the most recent fifty events, links each event to its admin screen where one exists, and renders an explicit empty state for customers with no history. The same feed is available as JSON under the admin bearer token.
+
 - 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

package/README.md

@@ -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. **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/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, 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. 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/SECURITY.md

@@ -180,6 +180,17 @@ node -e "
   Redemption decrements with an atomic `balance >= amount` SQL guard
   keyed on the order id, so concurrent or replayed checkouts can never
   overdraw a card or apply more than the remaining balance.
+- **Abandoned checkouts don't strand stock forever.** Checkout reserves
+  stock with an atomic conditional hold before charging; an order whose
+  buyer abandons the payment sheet (or whose PaymentIntent expires) would
+  otherwise hold that stock indefinitely. A background tick cancels
+  pending orders older than `CHECKOUT_PENDING_TTL_MINUTES` (default 120,
+  minimum 5) so their holds release back to the shelf. For a Stripe order
+  the tick cancels the PaymentIntent FIRST — if Stripe reports the payment
+  already succeeded, the order is left pending for the webhook to settle,
+  so a reap can never cancel an order whose payment completed. Tune the
+  TTL to the longest payment flow you support (slow 3-D Secure, manual
+  bank pushes) so a legitimate in-progress checkout is never reaped.
 - **Loyalty points are account-scoped money — earned and spent under
   the same double-spend discipline.** The `/account/loyalty` page and
   the redeem actions are login-gated and read the customer id from the

package/lib/admin.js

@@ -52,6 +52,12 @@ var MS_PER_HOUR = C.TIME.hours(1);
 
 var AUDIT_NAMESPACE = "shop_admin";
 
+// Newest-N bound on the order-detail customer-service notes panel + the
+// customer-detail activity timeline. Both are bounded reads — the console
+// renders the most recent slice rather than paginating an unbounded list.
+var NOTES_PANEL_LIMIT    = 50;
+var ACTIVITY_PANEL_LIMIT = 50;
+
 // Operator-readable error-log sink (lib/error-log.js), set by mount()
 // when the deployment wires `deps.errorLog`. `_safeNotice` records the
 // scrubbed message of a genuine 5xx here so the failure is reachable
@@ -547,6 +553,8 @@ function mount(router, deps) {
   var storeCredit      = deps.storeCredit      || null;  // per-customer store-credit panel + grant/deduct disabled when absent
   var customerNotes    = deps.customerNotes    || null;  // per-customer CRM notes panel disabled when absent
   var customerSegments = deps.customerSegments || null;  // per-customer segment-membership panel disabled when absent
+  var customerActivity = deps.customerActivity || null;  // per-customer chronological activity-timeline panel disabled when absent
+  var orderNotes       = deps.orderNotes       || null;  // per-order customer-service notes panel + add/lifecycle disabled when absent
   var orderTracking = deps.orderTracking || null;   // shipment/tracking panel disabled when absent
   var salesReports  = deps.salesReports  || null;   // /admin/reports degrades to an unconfigured notice when absent
   var orderExport   = deps.orderExport   || null;   // /admin/exports (date-range CSV/NDJSON dump + scheduled-export queue) disabled when absent
@@ -1777,6 +1785,16 @@ function mount(router, deps) {
         try { splitPlans = await splitShipments.splitsForOrder(o.id); }
         catch (_se) { splitPlans = []; }
       }
+      // Customer-service notes attached to the order — both visibility tiers
+      // (internal + customer-visible), pinned-first then newest-first, bounded
+      // to the most recent NOTES_PANEL_LIMIT. Best-effort: an unmigrated
+      // order_notes table degrades to "no notes" rather than 500-ing the page.
+      var notes = [];
+      if (orderNotes) {
+        try {
+          notes = (await orderNotes.listForOrder({ order_id: o.id, limit: NOTES_PANEL_LIMIT })).rows || [];
+        } catch (_ne) { notes = []; }
+      }
       _sendHtml(res, 200, renderAdminOrder({
         shop_name:   deps.shop_name,
         nav_available: navAvailable,
@@ -1816,11 +1834,173 @@ function mount(router, deps) {
         ship_done:   url && url.searchParams.get("ship"),
         label_done:  url && url.searchParams.get("label"),
         split_done:  url && url.searchParams.get("split"),
+        // Customer-service notes panel — renders only when the order-notes
+        // primitive is wired (its routes mount only then). `note_done` flags a
+        // successful add / lifecycle action (PRG); `note_err` surfaces a clean
+        // operator-facing notice from a refused write.
+        can_notes:   !!orderNotes,
+        notes:       notes,
+        note_done:   url && url.searchParams.get("note"),
+        note_err:    url && url.searchParams.get("note_err") ? url.searchParams.get("note_err") : null,
+        note_authors:    orderNotes ? orderNotes.ALLOWED_AUTHORS : null,
+        note_visibility: orderNotes ? orderNotes.ALLOWED_VISIBILITY : null,
         notice:      url && url.searchParams.get("err") ? "That action couldn't be completed for this order." : null,
       }));
     },
   ));
 
+  // ---- order notes (customer-service threaded notes) ------------------
+  //
+  // The operator's customer-service surface on the order-detail screen: a
+  // list of notes attached to the order (both internal + customer-visible
+  // tiers, pinned-first then newest-first) plus an add form and the lifecycle
+  // the order-notes primitive offers — pin / unpin (float to the top) and
+  // resolve / reopen (close out an internal thread with a short summary). The
+  // note body is operator free text, escaped at render and length-capped by
+  // the primitive's validator. Every mutation is audited; the panel renders
+  // only when the order-notes primitive is wired.
+  if (orderNotes) {
+    // Resolve the :id to an order. A malformed id throws inside order.get's
+    // defensive reader — treat that as "no such order" so the route refuses
+    // cleanly (404) rather than 500-ing.
+    async function _resolveOrder(id) {
+      try { return await order.get(id); }
+      catch (e) { if (e instanceof TypeError) return null; throw e; }
+    }
+
+    // A note belongs to an order. The primitive's pin / resolve / reopen move
+    // a row by note id alone — they carry no notion of which order the
+    // operator is acting on — so every per-note write route under :id MUST
+    // first assert the note belongs to THAT order before mutating it, or an
+    // operator on order A's screen could pin / resolve order B's note by
+    // guessing its id (an IDOR). Mirrors the customer-notes
+    // _noteBelongsToCustomer scoping. A malformed note id throws inside get's
+    // UUID guard -> a clean 400; a well-formed unknown id (or one on a
+    // different order) returns null -> a clean 404, with nothing written.
+    async function _orderNoteBelongs(noteId, orderId) {
+      var note;
+      try { note = await orderNotes.get(noteId); }
+      catch (e) { if (e instanceof TypeError) throw e; return false; }
+      return (note && note.order_id === orderId) ? note : false;
+    }
+
+    // ---- add a note ----------------------------------------------------
+    // Scoped to the :id order. Defaults author "operator" + visibility
+    // "internal" (the console never writes a system note; an operator can opt
+    // a note customer-visible via the form's visibility select). Bad input
+    // (empty / over-long body, bad author / visibility) is a clean 4xx with
+    // nothing written.
+    router.post("/admin/orders/:id/notes", _pageOrApi(false,
+      W("order.note.add", async function (req, res) {
+        var o = await _resolveOrder(req.params.id);
+        if (!o) return _problem(res, 404, "order-not-found");
+        var body = req.body || {};
+        var note;
+        try {
+          note = await orderNotes.add({
+            order_id:   o.id,
+            author:     (body.author === "customer" || body.author === "system") ? body.author : "operator",
+            visibility: body.visibility === "customer_visible" ? "customer_visible" : "internal",
+            body:       body.body,
+          });
+        } catch (e) {
+          if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+          throw e;
+        }
+        _json(res, 201, note);
+        return { id: o.id };
+      }),
+      async function (req, res) {
+        var o = await _resolveOrder(req.params.id);
+        if (!o) return _sendHtml(res, 404, renderAdminOrders({
+          shop_name: deps.shop_name, nav_available: navAvailable, orders: [], notice: "Order not found.",
+        }));
+        var body = req.body || {};
+        var enc = encodeURIComponent(o.id);
+        try {
+          await orderNotes.add({
+            order_id:   o.id,
+            author:     (body.author === "customer" || body.author === "system") ? body.author : "operator",
+            visibility: body.visibility === "customer_visible" ? "customer_visible" : "internal",
+            body:       body.body,
+          });
+        } catch (e) {
+          var n = _safeNotice(e, "order.note.add");
+          return _redirect(res, "/admin/orders/" + enc +
+            "?note_err=" + encodeURIComponent(n.message.replace(/^(?:admin|orderNotes)[.:]\s*/, "")));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".order.note.add", outcome: "success", metadata: { id: o.id } });
+        _redirect(res, "/admin/orders/" + enc + "?note=1");
+      },
+    ));
+
+    // ---- per-note lifecycle (pin / unpin / resolve / reopen) -----------
+    // Each route asserts note-belongs-to-order BEFORE mutating, then runs the
+    // matching primitive call. `mutate(note, body)` returns the updated note
+    // (bearer JSON) or throws a TypeError on bad input (-> a clean 400 /
+    // note_err redirect). A missing / cross-order note is a clean 404 (bearer)
+    // / note_err redirect (browser); nothing is mutated on any refusal.
+    function _orderNoteWriteRoute(routePath, audit, mutate) {
+      router.post(routePath, _pageOrApi(false,
+        W(audit, async function (req, res) {
+          var o = await _resolveOrder(req.params.id);
+          if (!o) return _problem(res, 404, "order-not-found");
+          var owned;
+          try { owned = await _orderNoteBelongs(req.params.noteId, o.id); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          if (!owned) return _problem(res, 404, "note-not-found");
+          var updated;
+          try { updated = await mutate(owned, req.body || {}); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          _json(res, 200, updated);
+          return { id: o.id };
+        }),
+        async function (req, res) {
+          var o = await _resolveOrder(req.params.id);
+          if (!o) return _sendHtml(res, 404, renderAdminOrders({
+            shop_name: deps.shop_name, nav_available: navAvailable, orders: [], notice: "Order not found.",
+          }));
+          var enc = encodeURIComponent(o.id);
+          var owned;
+          try { owned = await _orderNoteBelongs(req.params.noteId, o.id); }
+          catch (e) {
+            var nm = _safeNotice(e, audit);
+            return _redirect(res, "/admin/orders/" + enc +
+              "?note_err=" + encodeURIComponent(nm.message.replace(/^(?:admin|orderNotes)[.:]\s*/, "")));
+          }
+          if (!owned) {
+            return _redirect(res, "/admin/orders/" + enc +
+              "?note_err=" + encodeURIComponent("That note was not found on this order."));
+          }
+          try { await mutate(owned, req.body || {}); }
+          catch (e) {
+            var n = _safeNotice(e, audit);
+            return _redirect(res, "/admin/orders/" + enc +
+              "?note_err=" + encodeURIComponent(n.message.replace(/^(?:admin|orderNotes)[.:]\s*/, "")));
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + "." + audit, outcome: "success", metadata: { id: o.id } });
+          _redirect(res, "/admin/orders/" + enc + "?note=1");
+        },
+      ));
+    }
+
+    // Pin / unpin — a pinned note floats to the top of the order's note list
+    // (listForOrder orders pinned DESC). Idempotent at the primitive.
+    _orderNoteWriteRoute("/admin/orders/:id/notes/:noteId/pin", "order.note.pin",
+      function (owned) { return orderNotes.pin(owned.id); });
+    _orderNoteWriteRoute("/admin/orders/:id/notes/:noteId/unpin", "order.note.unpin",
+      function (owned) { return orderNotes.unpin(owned.id); });
+
+    // Resolve / reopen — close out an INTERNAL thread with a short (<=280-char)
+    // operator summary, or reopen it. The primitive refuses to resolve a
+    // customer-visible note (only internal threads carry a resolution) — that
+    // refusal surfaces as a clean 4xx / note_err, never a 500.
+    _orderNoteWriteRoute("/admin/orders/:id/notes/:noteId/resolve", "order.note.resolve",
+      function (owned, body) { return orderNotes.resolve({ note_id: owned.id, resolution: body.resolution }); });
+    _orderNoteWriteRoute("/admin/orders/:id/notes/:noteId/reopen", "order.note.reopen",
+      function (owned) { return orderNotes.reopen(owned.id); });
+  }
+
   // ---- audit / activity log (read-only) -------------------------------
   //
   // A read-only window onto the framework's tamper-evident audit chain —
@@ -3049,6 +3229,21 @@ function mount(router, deps) {
         catch (_e) { segments = []; }
       }
 
+      // Chronological activity timeline — the read-only per-customer feed the
+      // aggregator flattens from the wired source primitives (order
+      // transitions, wishlist saves, loyalty ledger, support tickets,
+      // reviews), newest-first, bounded to the most recent N. Best-effort: an
+      // unmigrated source / cache table degrades the panel to "no activity"
+      // rather than 500-ing the page.
+      var activity = [];
+      if (customerActivity) {
+        try {
+          activity = (await customerActivity.forCustomer({
+            customer_id: customer.id, limit: ACTIVITY_PANEL_LIMIT,
+          })).events || [];
+        } catch (_e) { activity = []; }
+      }
+
       return Object.assign({
         shop_name:      deps.shop_name,
         nav_available:  navAvailable,
@@ -3065,6 +3260,8 @@ function mount(router, deps) {
         show_archived_notes: showArchivedNotes,
         can_segments:   !!customerSegments,
         segments:       segments,
+        can_activity:   !!customerActivity,
+        activity:       activity,
       }, flags);
     }
 
@@ -3096,6 +3293,7 @@ function mount(router, deps) {
           loyalty:              model.loyalty,
           notes:                model.notes,
           segments:             model.segments,
+          activity:             model.activity,
         });
       }),
       async function (req, res) {
@@ -12664,6 +12862,18 @@ function renderAdminOrder(opts) {
     splitPanel = _orderSplitPanel(o, opts.split_plans || []);
   }
 
+  // Customer-service notes panel — only when the order-notes primitive is
+  // wired (its routes mount only then). The note body is operator free text,
+  // escaped at render. `_orderNotesPanel` lists the notes newest-first with
+  // their per-note lifecycle controls, then the add form.
+  var notesPanel = "";
+  if (opts.can_notes) {
+    notesPanel = _orderNotesPanel(o.id, opts.notes || [],
+      opts.note_done ? "<div class=\"banner banner--ok\">Note saved.</div>" : "",
+      opts.note_err ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.note_err) + "</div>" : "",
+      opts.note_authors || [], opts.note_visibility || []);
+  }
+
   var body =
     "<section class=\"mw-48\">" +
       "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/orders\">&larr; Orders</a></div>" +
@@ -12684,12 +12894,85 @@ function renderAdminOrder(opts) {
       "</div>" +
       documentsPanel +
       resendPanel +
+      notesPanel +
       splitPanel +
       trackingPanel +
     "</section>";
   return _renderAdminShell(opts.shop_name, "Order " + o.id.slice(0, 8), body, "orders", opts.nav_available);
 }
 
+// The order-detail customer-service notes panel. Lists the order's notes
+// newest-first (pinned float to the top, as the primitive orders them) with
+// each note's tier (internal / customer-visible), author, timestamp, pins,
+// resolution summary, and the legal lifecycle controls — pin / unpin always,
+// resolve (on an active internal note) / reopen (on a resolved one). Then an
+// add form (body + author + visibility). The note body is operator free text,
+// escaped with _htmlEscape at every interpolation. Every form renders through
+// _renderAdminShell, which injects the _csrf field into each POST form, so no
+// per-form token handling is needed here.
+function _orderNotesPanel(orderId, notes, doneBanner, errBanner, authors, visibilities) {
+  var enc = encodeURIComponent(orderId);
+  var noteItems = notes.map(function (n) {
+    var nenc = _htmlEscape(encodeURIComponent(n.id));
+    var base = "/admin/orders/" + _htmlEscape(enc) + "/notes/" + nenc;
+    var isPinned   = Number(n.pinned) === 1;
+    var isInternal = n.visibility === "internal";
+    var isResolved = n.resolved_at != null;
+    var pills =
+      "<span class=\"status-pill " + (isInternal ? "pending" : "shipped") + "\">" +
+        _htmlEscape(isInternal ? "Internal" : "Customer-visible") + "</span>" +
+      (isPinned ? "<span class=\"status-pill paid\">Pinned</span>" : "") +
+      (isResolved ? "<span class=\"status-pill refunded\">Resolved</span>" : "");
+    var pinForm = "<form method=\"post\" action=\"" + base + (isPinned ? "/unpin" : "/pin") + "\" class=\"form-inline\">" +
+      "<button class=\"btn btn--ghost\" type=\"submit\">" + (isPinned ? "Unpin" : "Pin") + "</button></form>";
+    // Resolve / reopen apply only to internal threads (the primitive refuses a
+    // customer-visible resolve). An active internal note offers a resolve form
+    // (with the required summary); a resolved one offers reopen.
+    var resolveForm = "";
+    if (isInternal) {
+      resolveForm = isResolved
+        ? "<form method=\"post\" action=\"" + base + "/reopen\" class=\"form-inline\">" +
+            "<button class=\"btn btn--ghost\" type=\"submit\">Reopen</button></form>"
+        : "<form method=\"post\" action=\"" + base + "/resolve\" class=\"return-action\">" +
+            "<input type=\"text\" name=\"resolution\" placeholder=\"Resolution summary\" maxlength=\"280\" aria-label=\"Resolution summary\" required>" +
+            "<button class=\"btn\" type=\"submit\">Resolve</button></form>";
+    }
+    var resolutionLine = (isResolved && n.resolution)
+      ? "<div class=\"note-meta\">Resolution: " + _htmlEscape(String(n.resolution)) + "</div>"
+      : "";
+    return "<li class=\"note-item\">" +
+      "<div class=\"note-meta\">" + _htmlEscape(String(n.author)) + " · " + _htmlEscape(_fmtDate(n.created_at)) +
+        " " + pills + "</div>" +
+      "<div class=\"note-body\">" + _htmlEscape(String(n.body)) + "</div>" +
+      resolutionLine +
+      "<div class=\"actions-row\">" + pinForm + resolveForm + "</div>" +
+    "</li>";
+  }).join("");
+  var authorOpts = (authors || []).map(function (a) {
+    return "<option value=\"" + _htmlEscape(a) + "\"" + (a === "operator" ? " selected" : "") + ">" + _htmlEscape(a) + "</option>";
+  }).join("");
+  var visibilityOpts = (visibilities || []).map(function (v) {
+    return "<option value=\"" + _htmlEscape(v) + "\"" + (v === "internal" ? " selected" : "") + ">" +
+      _htmlEscape(v === "customer_visible" ? "Customer-visible" : v) + "</option>";
+  }).join("");
+  return "<div class=\"panel mt\"><h3 class=\"subhead\">Customer-service notes</h3>" +
+    doneBanner + errBanner +
+    "<p class=\"meta\">Threaded notes attached to this order. Internal notes are operator-only; customer-visible notes surface on the customer's order page. Pin the notes every shift should see first; resolve an internal thread with a short summary once it's handled.</p>" +
+    (notes.length
+      ? "<ul class=\"note-list\">" + noteItems + "</ul>"
+      : "<p class=\"empty\">No notes on this order yet.</p>") +
+    "<form method=\"post\" action=\"/admin/orders/" + _htmlEscape(enc) + "/notes\">" +
+      "<label class=\"form-field\"><span>Note</span>" +
+        "<textarea name=\"body\" required maxlength=\"8000\" rows=\"3\" placeholder=\"e.g. Buyer asked to delay shipment until Monday\"></textarea></label>" +
+      "<div class=\"two-col\">" +
+        "<label class=\"form-field\"><span>Author</span><select name=\"author\">" + authorOpts + "</select></label>" +
+        "<label class=\"form-field\"><span>Visibility</span><select name=\"visibility\">" + visibilityOpts + "</select></label>" +
+      "</div>" +
+      "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Add note</button></div>" +
+    "</form>" +
+  "</div>";
+}
+
 // Per-shipment carrier-label sub-panel for the order detail. Lists the
 // recorded labels (tracking number, broker, cost, status pill) with a
 // "Mark used" action on purchased ones, then a form to record a freshly-
@@ -13260,11 +13543,45 @@ function renderAdminCustomerDetail(opts) {
     "</div>";
   }
 
+  // ---- activity timeline (read-only) ---------------------------------
+  // The chronological per-customer feed the customerActivity aggregator
+  // flattens from the wired source primitives, newest-first. Read-only — the
+  // operator never writes an event here; every row originates in a source
+  // primitive's own table. title / body / actor are escaped (title is a fixed
+  // canonical string per kind, but body can carry source free text — a review
+  // title, a ticket subject — so both pass through _htmlEscape).
+  var activityPanel = "";
+  if (opts.can_activity) {
+    var activityRows = (opts.activity || []).map(function (e) {
+      // Same-origin path only: a leading "/" that is NOT "//" — a
+      // protocol-relative "//evil.example/x" also starts with "/" but
+      // resolves to an off-site origin, and _htmlEscape leaves "/"
+      // untouched, so it would survive into a working cross-origin href.
+      var link = (typeof e.link === "string" && e.link.charAt(0) === "/" && e.link.charAt(1) !== "/") ? e.link : null;
+      var titleCell = link
+        ? "<a href=\"" + _htmlEscape(link) + "\">" + _htmlEscape(String(e.title || e.kind)) + "</a>"
+        : _htmlEscape(String(e.title || e.kind));
+      return "<li class=\"note-item\">" +
+        "<div class=\"note-meta\">" + _htmlEscape(_fmtDate(e.occurred_at)) +
+          " · <code class=\"order-id\">" + _htmlEscape(String(e.kind)) + "</code>" +
+          (e.actor ? " · " + _htmlEscape(String(e.actor)) : "") + "</div>" +
+        "<div class=\"note-body\">" + titleCell +
+          (e.body ? " <span class=\"meta\">" + _htmlEscape(String(e.body)) + "</span>" : "") + "</div>" +
+      "</li>";
+    }).join("");
+    activityPanel = "<div class=\"panel\"><h3 class=\"subhead\">Activity</h3>" +
+      "<p class=\"meta\">A read-only chronological feed of this customer's recent events — orders, wishlist saves, loyalty changes, support tickets, and reviews — newest first. Each event lives in its source record; nothing is edited here.</p>" +
+      ((opts.activity || []).length
+        ? "<ul class=\"note-list\">" + activityRows + "</ul>"
+        : "<p class=\"empty\">No recorded activity yet.</p>") +
+    "</div>";
+  }
+
   var body = "<section>" +
     "<div class=\"actions-row\"><h2>" + _htmlEscape(c.display_name) + "</h2>" +
       "<a class=\"btn btn--ghost\" href=\"/admin/customers\"><span aria-hidden=\"true\">←</span> All customers</a></div>" +
     saved +
-    identity + ordersPanel + creditPanel + loyaltyPanel + notesPanel + segmentsPanel +
+    identity + ordersPanel + creditPanel + loyaltyPanel + notesPanel + segmentsPanel + activityPanel +
   "</section>";
   return _renderAdminShell(opts.shop_name, c.display_name || "Customer", body, "customers", opts.nav_available);
 }

package/lib/asset-manifest.json

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

package/lib/checkout.js

@@ -606,7 +606,24 @@ function create(deps) {
   async function _holdExempt(sku) {
     if (preorder && typeof preorder.openCampaignForSku === "function") {
       try {
-        if (await preorder.openCampaignForSku(sku)) return true;
+        var campaign = await preorder.openCampaignForSku(sku);
+        // A pre-order line sells beyond the shelf only while the campaign
+        // is genuinely pre-launch: before `launch_at` the unit isn't
+        // released yet, so the hold is deliberately skipped. ONCE
+        // `launch_at` has passed, the SKU is selling against real stock —
+        // keep it hold-exempt and a past-launch campaign that the operator
+        // never manually flipped to `launched` would oversell real
+        // inventory without bound. So past-launch_at → NOT exempt (holds
+        // apply). openCampaignForSku's own semantics are unchanged (the
+        // storefront PDP CTA still keys off the active row); the launch_at
+        // gate lives here, on the buy path. A campaign with no launch_at
+        // is treated as still-pre-launch (exempt).
+        if (campaign) {
+          var launchAt = campaign.launch_at == null ? null : Number(campaign.launch_at);
+          if (launchAt == null || !Number.isFinite(launchAt) || launchAt > Date.now()) {
+            return true;
+          }
+        }
       } catch (_e) { /* not exempt on lookup failure */ }
     }
     if (backorder && typeof backorder.availabilityFor === "function") {
@@ -660,10 +677,12 @@ function create(deps) {
 
   // 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.
+  // error that triggered the rollback. This path runs ONLY when no pending
+  // order was created (the conditional rollback in confirm) — once an order
+  // exists it owns its holds, and the only thing that frees them is the
+  // paid decrement, an explicit cancel, or the stale-pending-order reaper
+  // (`reapStalePending`), driven once a minute by the worker cron, which
+  // cancels pending orders older than the TTL so their holds release.
   async function _releaseStockHolds(holds) {
     if (!Array.isArray(holds)) return;
     for (var i = 0; i < holds.length; i += 1) {
@@ -821,10 +840,19 @@ function create(deps) {
       // before the order is committed, so a refused gift-card / payment
       // error never strands held stock.
       var stockHolds = await _placeStockHolds(quote.lines);
+      // Conditional rollback: the catch releases the placed holds ONLY when
+      // no pending order was created. Once createFromCart succeeds, the
+      // order row OWNS those holds — releasing them here would double-free
+      // (the paid decrement / cancel release, or the stale-pending reaper,
+      // settles them once the order exists), and a floored blanket release
+      // could even eat a CONCURRENT shopper's hold on the same SKU. The
+      // context object is mutated inside _confirmAfterHolds the instant the
+      // order is created.
+      var rollbackCtx = { orderCreated: false };
       try {
-        return await this._confirmAfterHolds(input, quote, email, stockHolds);
+        return await this._confirmAfterHolds(input, quote, email, stockHolds, rollbackCtx);
       } catch (e) {
-        await _releaseStockHolds(stockHolds);
+        if (!rollbackCtx.orderCreated) await _releaseStockHolds(stockHolds);
         throw e;
       }
     },
@@ -835,8 +863,11 @@ function create(deps) {
     // 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) {
+    // pending order owns them until paid / cancelled). `rollbackCtx` is the
+    // mutable flag the catch reads: set `orderCreated` true the moment a
+    // pending order exists so a LATER throw doesn't release holds the order
+    // now owns.
+    _confirmAfterHolds: async function (input, quote, email, stockHolds, rollbackCtx) {
       // Already validated in confirm() above; re-read here since the PI
       // creation moved into this split-out body.
       var idempotencyKey = input.idempotency_key;
@@ -906,6 +937,9 @@ function create(deps) {
           customer_email_hash: emailHash,
           lines:             orderLines,
         });
+        // The pending order now owns the holds — a throw from here on must
+        // NOT blanket-release them (see the conditional rollback in confirm).
+        if (rollbackCtx) rollbackCtx.orderCreated = true;
         if (gc) await _redeemGiftCard(gc, paidOrder.id);
         if (loy) await _redeemLoyalty(loy, loyaltyCustomerId, paidOrder.id);
         // Best-effort: record the auto-discount redemptions against the
@@ -962,6 +996,11 @@ function create(deps) {
         customer_email_hash: emailHash,
         lines:             orderLines,
       });
+      // The pending order now owns the holds — a throw from here on (gift-card
+      // burn, discount recording) must NOT blanket-release them (see the
+      // conditional rollback in confirm). The reaper / cancel / paid edge
+      // settles them now that the order exists.
+      if (rollbackCtx) rollbackCtx.orderCreated = true;
 
       // Burn the gift-card + loyalty credits against the created order.
       // Runs after the order row exists so a failed order never spends
@@ -995,6 +1034,93 @@ function create(deps) {
       };
     },
 
+    // Stale-pending-order reaper. A pending order whose buyer abandoned the
+    // payment sheet (Stripe / PayPal) or whose PaymentIntent expired holds
+    // its reserved stock forever — `confirm` places the holds and creates
+    // the pending order, but the only hold-freeing FSM edges are
+    // pending→paid (decrement) and pending→cancelled (release), and nothing
+    // fires the cancel automatically. This reaper, driven once a minute by
+    // the worker cron's `/_/stale-order-reap` tick, cancels orders older
+    // than the TTL so their holds release.
+    //
+    // Per order, Stripe-paid orders: cancel the PaymentIntent FIRST so a
+    // late authorization can't complete AFTER we cancel the order. If Stripe
+    // reports the PI already succeeded / is not cancelable
+    // (`payment_intent_unexpected_state`, or any non-success cancel), SKIP
+    // the order — the webhook has settled or will settle it, and cancelling
+    // an order whose payment may have completed would lose a real sale.
+    // Only after a clean PI cancel (or for an order with no Stripe
+    // PaymentIntent — a PayPal-created order, whose capture path guards on
+    // local status so reaping first is safe, or a zero-amount leftover) do
+    // we fire the cancel transition, which releases the holds via the
+    // existing path.
+    //
+    // Per-order failures are drop-silent + continue (hot-path sink tier) but
+    // COUNTED in the returned summary so the operator sees the reap's shape.
+    // `ttlMinutes` is validated config-time by the caller (the tick handler
+    // throws on garbage at boot); defended here too with a documented
+    // default so a direct call is never unsafe.
+    reapStalePending: async function (opts) {
+      opts = opts || {};
+      var ttlMinutes = opts.ttl_minutes;
+      if (ttlMinutes == null) ttlMinutes = 120;
+      if (typeof ttlMinutes !== "number" || !isFinite(ttlMinutes) || !Number.isInteger(ttlMinutes) || ttlMinutes < 5) {
+        throw new TypeError("checkout.reapStalePending: ttl_minutes must be an integer >= 5");
+      }
+      var nowMs    = typeof opts.now === "number" ? opts.now : Date.now();
+      var cutoffTs = nowMs - b.constants.TIME.minutes(ttlMinutes);
+      var batchLimit = opts.limit == null ? 100 : opts.limit;
+
+      var summary = {
+        scanned:        0,
+        reaped:         0,   // cancelled (holds released)
+        skipped_paid:   0,   // PI already succeeded / not cancelable — left pending
+        errored:        0,   // a per-order failure, dropped + counted
+      };
+
+      var stale;
+      try {
+        stale = (await order.listStalePending(cutoffTs, batchLimit)).rows;
+      } catch (e) {
+        // The candidate read itself failed — surface it in the summary
+        // rather than throwing out of the tick (which would 5xx the cron).
+        return Object.assign({ ok: false, error: (e && e.message) || String(e) }, summary);
+      }
+      summary.scanned = stale.length;
+
+      for (var i = 0; i < stale.length; i += 1) {
+        var row = stale[i];
+        try {
+          var piId = row.payment_intent_id;
+          // A Stripe PaymentIntent id is `pi_…`; a PayPal order id is opaque
+          // (no `pi_` prefix) and has no cancel API for an unapproved order
+          // (its capture path guards on local status, so reaping first can
+          // never double-charge). Only the Stripe case needs a pre-cancel.
+          var isStripePi = typeof piId === "string" && piId.indexOf("pi_") === 0;
+          if (isStripePi && payment && typeof payment.cancelPaymentIntent === "function") {
+            try {
+              await payment.cancelPaymentIntent(piId);
+            } catch (_cancelErr) {
+              // PI already succeeded / not cancelable → the webhook owns this
+              // order's settlement. Leave it pending; never cancel an order
+              // whose payment may have completed.
+              summary.skipped_paid += 1;
+              continue;
+            }
+          }
+          // PI cancelled cleanly (or no Stripe PI) — release the holds by
+          // cancelling the order through the existing FSM edge.
+          await order.transition(row.id, "cancel", { reason: "stale-pending-reap" });
+          summary.reaped += 1;
+        } catch (_e) {
+          // drop-silent per order — by design (hot-path sink): one bad order
+          // must not poison the sweep. Counted so the operator sees it.
+          summary.errored += 1;
+        }
+      }
+      return Object.assign({ ok: true }, summary);
+    },
+
     // Verify a Stripe webhook payload and dispatch the order
     // transition. Returns { handled, order?, event_type }.
     handleStripeEvent: async function (input) {
@@ -1091,6 +1217,14 @@ function create(deps) {
       // here (no PayPal order created). Released on any throw before the
       // local order row commits.
       var ppHolds = await _placeStockHolds(quote.lines);
+      // Conditional rollback, identical discipline to the Stripe confirm:
+      // release the placed holds ONLY when no pending order was created.
+      // Once createFromCart succeeds the order owns the holds; releasing
+      // them here would double-free and could eat a concurrent shopper's
+      // hold on the same SKU. A pending PayPal order that the buyer never
+      // approves is reaped by the stale-pending reaper (no PayPal-side
+      // cancel needed — the capture path guards on local status).
+      var ppOrderCreated = false;
       try {
       // Resolve an optional gift-card credit before opening the PayPal
       // order so a bad code fails without a remote round-trip.
@@ -1121,6 +1255,7 @@ function create(deps) {
           customer_email_hash: emailHash,
           lines:               ppLines,
         });
+        ppOrderCreated = true;
         await _redeemGiftCard(gc, paidOrder.id);
         await cart.setStatus(quote.cart_id, "converted");
         var settled = await order.transition(paidOrder.id, "mark_paid", { reason: "gift_card:full" });
@@ -1149,13 +1284,15 @@ function create(deps) {
         customer_email_hash: emailHash,
         lines:               ppLines,
       });
+      ppOrderCreated = true;
       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,
+        // A throw BEFORE the order row commits (PayPal open failure,
         // gift-card error) releases the holds so PayPal can't strand stock.
-        await _releaseStockHolds(ppHolds);
+        // After the order commits it owns the holds — don't blanket-release.
+        if (!ppOrderCreated) await _releaseStockHolds(ppHolds);
         throw e;
       }
     },

package/lib/customer-activity.js

@@ -248,7 +248,11 @@ function create(opts) {
   // the aggregator). Missing peers collapse to an empty list so the
   // aggregator stays the same shape regardless of wiring.
 
-  async function _collectOrderEvents(customerId, fromTs, toTs) {
+  // A read bound is "active" only for a positive integer; null / undefined
+  // (the summary path) means read everything, as before.
+  function _isBound(n) { return Number.isInteger(n) && n > 0; }
+
+  async function _collectOrderEvents(customerId, fromTs, toTs, boundLimit) {
     if (!orderPeer) return [];
     var sql = "SELECT ot.order_id, ot.from_state, ot.to_state, ot.on_event, " +
               "ot.reason, ot.occurred_at " +
@@ -259,7 +263,11 @@ function create(opts) {
     var idx = 2;
     if (fromTs != null) { sql += " AND ot.occurred_at >= ?" + idx; params.push(fromTs); idx += 1; }
     if (toTs   != null) { sql += " AND ot.occurred_at <= ?" + idx; params.push(toTs);   idx += 1; }
-    sql += " ORDER BY ot.occurred_at ASC";
+    // Bounded read: newest-N (DESC + LIMIT) when the paginated caller supplies
+    // a bound; the aggregator re-sorts newest-first so the DESC here is just
+    // the read order. Unbounded (summary path) keeps the full ASC scan.
+    if (_isBound(boundLimit)) { sql += " ORDER BY ot.occurred_at DESC LIMIT ?" + idx; params.push(boundLimit); }
+    else                      { sql += " ORDER BY ot.occurred_at ASC"; }
     var rows = (await query(sql, params)).rows;
     var out = [];
     for (var i = 0; i < rows.length; i += 1) {
@@ -278,7 +286,7 @@ function create(opts) {
     return out;
   }
 
-  async function _collectWishlistEvents(customerId, fromTs, toTs) {
+  async function _collectWishlistEvents(customerId, fromTs, toTs, boundLimit) {
     if (!wishlistPeer) return [];
     var sql = "SELECT id, product_id, variant_id, notes, created_at " +
               "FROM wishlist_entries WHERE customer_id = ?1";
@@ -286,7 +294,8 @@ function create(opts) {
     var idx = 2;
     if (fromTs != null) { sql += " AND created_at >= ?" + idx; params.push(fromTs); idx += 1; }
     if (toTs   != null) { sql += " AND created_at <= ?" + idx; params.push(toTs);   idx += 1; }
-    sql += " ORDER BY created_at ASC";
+    if (_isBound(boundLimit)) { sql += " ORDER BY created_at DESC LIMIT ?" + idx; params.push(boundLimit); }
+    else                      { sql += " ORDER BY created_at ASC"; }
     var rows = (await query(sql, params)).rows;
     var out = [];
     for (var i = 0; i < rows.length; i += 1) {
@@ -303,7 +312,7 @@ function create(opts) {
     return out;
   }
 
-  async function _collectLoyaltyEvents(customerId, fromTs, toTs) {
+  async function _collectLoyaltyEvents(customerId, fromTs, toTs, boundLimit) {
     if (!loyaltyPeer) return [];
     var sql = "SELECT id, transaction_type, points, source, order_id, notes, " +
               "occurred_at FROM loyalty_transactions WHERE customer_id = ?1";
@@ -311,7 +320,8 @@ function create(opts) {
     var idx = 2;
     if (fromTs != null) { sql += " AND occurred_at >= ?" + idx; params.push(fromTs); idx += 1; }
     if (toTs   != null) { sql += " AND occurred_at <= ?" + idx; params.push(toTs);   idx += 1; }
-    sql += " ORDER BY occurred_at ASC";
+    if (_isBound(boundLimit)) { sql += " ORDER BY occurred_at DESC LIMIT ?" + idx; params.push(boundLimit); }
+    else                      { sql += " ORDER BY occurred_at ASC"; }
     var rows = (await query(sql, params)).rows;
     var out = [];
     for (var i = 0; i < rows.length; i += 1) {
@@ -331,19 +341,27 @@ function create(opts) {
     return out;
   }
 
-  async function _collectSupportEvents(customerId, fromTs, toTs) {
+  async function _collectSupportEvents(customerId, fromTs, toTs, boundLimit) {
     if (!supportPeer) return [];
     // The support_tickets row contributes an "opened" event at
     // opened_at and a "resolved" event at resolved_at when stamped.
     // The bounded-window filter is applied per-event after
     // splitting (a ticket opened inside the window but resolved
-    // outside still surfaces its opened event).
-    var rows = (await query(
-      "SELECT id, subject, category, status, priority, opened_at, " +
-      "resolved_at, closed_at FROM support_tickets WHERE customer_id = ?1 " +
-      "ORDER BY opened_at ASC",
-      [customerId],
-    )).rows;
+    // outside still surfaces its opened event). Bounded read: order by
+    // the ticket's NEWEST event timestamp — MAX(opened_at, resolved_at)
+    // — not opened_at alone, or an old ticket resolved recently would
+    // be dropped and its resolved event would vanish from the page.
+    // Every event in the true newest-`boundLimit` set belongs to a
+    // ticket whose newest-event timestamp is at least that event's, so
+    // the newest `boundLimit` tickets under this ordering cover any
+    // single page of `boundLimit` events. Unbounded (summary path)
+    // keeps the full ASC scan for exact windowed counts.
+    var supSql = "SELECT id, subject, category, status, priority, opened_at, " +
+      "resolved_at, closed_at FROM support_tickets WHERE customer_id = ?1 ";
+    var supParams = [customerId];
+    if (_isBound(boundLimit)) { supSql += "ORDER BY MAX(opened_at, COALESCE(resolved_at, opened_at)) DESC LIMIT ?2"; supParams.push(boundLimit); }
+    else                      { supSql += "ORDER BY opened_at ASC"; }
+    var rows = (await query(supSql, supParams)).rows;
     var out = [];
     for (var i = 0; i < rows.length; i += 1) {
       var t = rows[i];
@@ -375,7 +393,7 @@ function create(opts) {
     return out;
   }
 
-  async function _collectReviewEvents(customerId, fromTs, toTs) {
+  async function _collectReviewEvents(customerId, fromTs, toTs, boundLimit) {
     if (!reviewsPeer) return [];
     // Only authenticated-customer reviews carry a customer_id (the
     // anonymous email-hash submissions land in the reviews table
@@ -387,7 +405,8 @@ function create(opts) {
     var idx = 2;
     if (fromTs != null) { sql += " AND created_at >= ?" + idx; params.push(fromTs); idx += 1; }
     if (toTs   != null) { sql += " AND created_at <= ?" + idx; params.push(toTs);   idx += 1; }
-    sql += " ORDER BY created_at ASC";
+    if (_isBound(boundLimit)) { sql += " ORDER BY created_at DESC LIMIT ?" + idx; params.push(boundLimit); }
+    else                      { sql += " ORDER BY created_at ASC"; }
     var rows = (await query(sql, params)).rows;
     var out = [];
     for (var i = 0; i < rows.length; i += 1) {
@@ -406,13 +425,18 @@ function create(opts) {
 
   // ---- aggregation ------------------------------------------------------
 
-  async function _collectAll(customerId, fromTs, toTs) {
+  // `boundLimit` (optional) caps each collector's read to the newest N rows
+  // — passed by the paginated `forCustomer` read where a page is at most
+  // `limit` events. The summary path passes null/undefined (unbounded) so
+  // the 30/90/365-day windowed kind-counts stay exact for a very active
+  // customer. A null bound preserves the original read-everything behavior.
+  async function _collectAll(customerId, fromTs, toTs, boundLimit) {
     var batches = await Promise.all([
-      _collectOrderEvents(customerId, fromTs, toTs),
-      _collectWishlistEvents(customerId, fromTs, toTs),
-      _collectLoyaltyEvents(customerId, fromTs, toTs),
-      _collectSupportEvents(customerId, fromTs, toTs),
-      _collectReviewEvents(customerId, fromTs, toTs),
+      _collectOrderEvents(customerId, fromTs, toTs, boundLimit),
+      _collectWishlistEvents(customerId, fromTs, toTs, boundLimit),
+      _collectLoyaltyEvents(customerId, fromTs, toTs, boundLimit),
+      _collectSupportEvents(customerId, fromTs, toTs, boundLimit),
+      _collectReviewEvents(customerId, fromTs, toTs, boundLimit),
     ]);
     var flat = [];
     for (var b = 0; b < batches.length; b += 1) {
@@ -647,7 +671,32 @@ function create(opts) {
       var limit  = _limit(input.limit, MAX_LIMIT, DEFAULT_LIMIT);
       var cursor = _decodeCursor(input.cursor, "forCustomer");
 
-      var events = await _collectAll(customerId, fromTs, toTs);
+      // Per-collector read bound: a single page draws at most `limit` events
+      // total across all sources, so the newest rows from EACH source (at or
+      // before the cursor's timestamp when paginating) are a sufficient
+      // superset — the merge + sort + cursor + slice below can never need an
+      // older row than the `limit`-th newest of any one source. A customer
+      // with thousands of events no longer reads them all per panel render.
+      //
+      // The cursor's tail timestamp tightens the upper edge so deep pages
+      // stay correct: collectors return the newest events at-or-before it,
+      // and _applyCursor then drops the equal-or-newer boundary tuple. Because
+      // that drop removes the single boundary event per source, the bound is
+      // `limit + 1` — enough that a full `limit` page (and a correct
+      // next_cursor) survives the drop and pagination doesn't stall early.
+      // A `kinds` filter narrows the OUTPUT after collection, so when one is
+      // active the bound widens to MAX_LIMIT to give the filter enough
+      // candidates per source.
+      var collectorBound = kinds ? MAX_LIMIT : (limit + 1);
+      var collectorToTs = toTs;
+      if (cursor && cursor.length) {
+        var cursorTs = Number(cursor[0]);
+        if (Number.isFinite(cursorTs)) {
+          collectorToTs = (collectorToTs == null) ? cursorTs : Math.min(collectorToTs, cursorTs);
+        }
+      }
+
+      var events = await _collectAll(customerId, fromTs, collectorToTs, collectorBound);
       events = _filterKinds(events, kinds);
       _sortNewestFirst(events);
       if (cursor) events = _applyCursor(events, cursor);

package/lib/order.js

@@ -209,6 +209,14 @@ function create(opts) {
   // 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;
+  // Optional error-log handle — when present, an inventory settlement
+  // failure (a decrement / release throw on the paid / cancel edge) is
+  // captured to the operator's error feed (/admin/errors) with the exact
+  // sku / qty / order so the stranded hold is reconcilable by hand via the
+  // inventory-adjustment surface. Opt-in like the other handles; absent it,
+  // settlement failures still surface to the audit sink (b.audit.safeEmit
+  // below), just not the durable error feed.
+  var errorLog = opts.errorLog || 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
@@ -223,6 +231,48 @@ function create(opts) {
   }
   var cursorSecret = opts.cursorSecret;
 
+  // Settle one held SKU on a state edge — `inventory.decrement` on the
+  // paid edge, `inventory.release` on the cancel-from-pending edge.
+  //
+  // drop-silent-with-capture — by design: the order's payment has already
+  // succeeded (paid edge) or the cancel has already persisted (cancel
+  // edge), and the webhook driving this MUST return 2xx or Stripe retries
+  // forever. A throw here would 500 the webhook, the retry would hit the
+  // already-advanced guard and skip, and the hold would strand silently.
+  // So a per-SKU settlement failure is caught, NOT re-thrown, and surfaced
+  // LOUDLY instead: an `order.settlement.error` audit event plus, when the
+  // error-log handle is wired, a durable row in /admin/errors carrying the
+  // exact sku / qty / order so the operator reconciles the stranded hold
+  // via the inventory-adjustment surface. Returns true on success, false on
+  // a (captured) failure so the caller can count strandings.
+  async function _settleSku(verb, sku, qty, orderId) {
+    try {
+      await inventory[verb](sku, qty);
+      return true;
+    } catch (e) {
+      var message = "order.settlement." + verb + " failed — sku=" + sku +
+        " qty=" + qty + " order=" + orderId + ": " + (e && e.message || e);
+      try {
+        b.audit.safeEmit({
+          action:   "order.settlement.error",
+          outcome:  "failure",
+          metadata: { verb: verb, sku: sku, qty: qty, order_id: orderId, message: (e && e.message) || String(e) },
+        });
+      } catch (_auditErr) { /* drop-silent — the capture below is the durable record */ }
+      if (errorLog && typeof errorLog.captureServerError === "function") {
+        try {
+          await errorLog.captureServerError({
+            route:   "/order/" + orderId + "/settlement",
+            method:  "POST",
+            status:  500,
+            message: message,
+          });
+        } catch (_logErr) { /* drop-silent — never let the error-feed write mask the original failure */ }
+      }
+      return false;
+    }
+  }
+
   return {
     TERMINAL_STATES: TERMINAL_STATES,
 
@@ -376,6 +426,13 @@ function create(opts) {
         var holdMap = _stockHoldMap(refreshed);
         var holdSkus = Object.keys(holdMap);
         if (holdSkus.length) {
+          // Each SKU settles in its own try/catch (_settleSku) so a single
+          // SKU's decrement / release throw on a transient DB error can't
+          // strand the OTHER SKUs' holds or 500 the webhook — the remaining
+          // SKUs in the loop still settle, and each failure surfaces loudly
+          // (audit + error-feed) for manual reconciliation. The transition
+          // has already persisted; settlement is post-commit best-effort
+          // with a durable failure trail, never a hard gate.
           if (result.from === "pending" && result.to === "paid"
               && typeof inventory.decrement === "function") {
             // Convert each held SKU's reservation into a real shelf debit,
@@ -383,7 +440,7 @@ function create(opts) {
             // 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]]);
+              await _settleSku("decrement", holdSkus[di], holdMap[holdSkus[di]], orderId);
             }
           } else if (result.from === "pending" && result.to === "cancelled"
               && typeof inventory.release === "function") {
@@ -393,7 +450,7 @@ function create(opts) {
             // 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]]);
+              await _settleSku("release", holdSkus[ri], holdMap[holdSkus[ri]], orderId);
             }
           }
         }
@@ -586,6 +643,34 @@ function create(opts) {
       return { rows: rows };
     },
 
+    // Pending orders whose `created_at` is at or before `olderThanTs` —
+    // the candidate set for the stale-pending-order reaper. A pending
+    // order that never advanced to paid (the buyer abandoned the Stripe /
+    // PayPal sheet, the PaymentIntent expired) holds its reserved stock
+    // forever with no FSM edge to free it; the reaper cancels these so the
+    // hold releases. Bounded (`limit`, default 100, capped at
+    // MAX_LIST_LIMIT) so one tick reaps a chunk and the next picks up the
+    // rest. Returns the raw row (id + payment_intent_id + created_at are
+    // what the reaper needs); the reaper drives the actual hold release
+    // through `transition(id, "cancel", …)`. Oldest-first so the longest-
+    // stranded holds free first.
+    listStalePending: async function (olderThanTs, limit) {
+      if (typeof olderThanTs !== "number" || !isFinite(olderThanTs) || olderThanTs < 0) {
+        throw new TypeError("order.listStalePending: olderThanTs must be a non-negative epoch-ms number");
+      }
+      var lim = limit == null ? 100 : limit;
+      if (!Number.isInteger(lim) || lim <= 0 || lim > MAX_LIST_LIMIT) {
+        throw new TypeError("order.listStalePending: limit must be 1..." + MAX_LIST_LIMIT);
+      }
+      var rows = (await query(
+        "SELECT id, payment_intent_id, created_at FROM orders " +
+        "WHERE status = 'pending' AND created_at <= ?1 " +
+        "ORDER BY created_at ASC, id ASC LIMIT ?2",
+        [olderThanTs, lim],
+      )).rows;
+      return { rows: rows };
+    },
+
     // The actions available from a given status, as {on, to, label} —
     // drives the transition buttons on the operator order-detail page.
     // A terminal status returns []. Synchronous (pure lookup).

package/package.json

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