@blamejs/blamejs-shop 0.1.25 → 0.1.27

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.1.x
 
+- v0.1.27 (2026-05-25) — **Loyalty rewards go live — points earned on purchase, viewed in the account, and redeemed at checkout.** The loyalty points ledger now has a customer-facing surface. A new /account/loyalty page shows the signed-in customer's balance, tier, and earn/redeem activity, explains how points are earned, and lists the reward catalog with a one-click redeem. Paid orders award points automatically: the order primitive fans its paid transition into the earn rules (per-dollar-spent + per-order), fire-and-forget and deduplicated so a re-delivered payment webhook never double-credits. At checkout, a signed-in customer can spend points for a storefront credit against the order total — capped at the order's value and the balance, recorded once, with the same atomic double-spend guard the gift-card credit uses. **Added:** *Customer rewards page at /account/loyalty* — A login-gated page showing the points balance, current tier, lifetime points, and the cash value of the balance; how points are earned (the active earn rules in plain language); the reward catalog with a Redeem control per reward (disabled when the balance is short); the customer's past redemptions; and the earn/redeem ledger, paginated newest-first. Linked from the account dashboard as "Rewards". A redeem that the customer can't complete (not enough points, reward unavailable, per-customer limit reached) re-renders the page with the reason rather than erroring; a malformed history cursor degrades to the first page. · *Points earned automatically on paid orders* — When an order reaches paid, the configured earn rules award points to the customer's balance — per dollar of order subtotal and a flat per-order bonus, whichever rules the operator has defined. The award rides the order's paid transition (so every paid path — card, PayPal, gift-card-covered, admin — earns), runs fire-and-forget off the request path, and is keyed to the order so a re-delivered payment webhook collapses onto a single award instead of double-crediting. Guest orders (no customer account) earn nothing, by design. · *Redeem points at checkout as a credit* — A signed-in customer with a balance sees a "Redeem loyalty points" field on the checkout form. The points are valued via the ledger's redemption ratio (100 points = $1 by default), capped at the order total so the credit never exceeds what the order is worth, and the credit reduces the amount due. The order still records the full grand total it owed; the points are debited once, after the order row exists, behind the same balance-guarded SQL decrement that prevents a double-spend. Points worth more than the order spend only what the granted credit is worth — the surplus stays in the balance. A request for more points than the balance, or from a guest cart, is refused with a clean re-prompt. A points credit stacks with a gift-card credit; together they can pay an order in full with no card charge.
+
+- v0.1.26 (2026-05-25) — **Fix the container build gate that rejected a manifest absent from the image.** The asset-integrity drift gate added last release checked both the container and edge copies of the manifest. The container image excludes the edge worker directory from its build context, so when the gate runs inside the image build it can't see the worker copy and read it as empty — failing the build. The gate now skips a manifest that isn't present in the current build context; its drift is still caught wherever the file exists (the full-tree CI run checks both). **Fixed:** *Asset-manifest drift gate no longer fails the container build* — `generate-asset-manifest.js --check` compared both manifest copies (`lib/` for the container, `worker/` for the edge) against a fresh rebuild. The container image's build context excludes the `worker/` tree, so inside the image the worker copy is absent and the gate read it as empty — reporting false drift and failing `node test/smoke.js`, which is a build gate, so the container image never built. The check now treats a manifest that isn't present in the current context as not-applicable and skips it (requiring at least one copy to be present), so the same drift detection still runs in CI and at the edge build where both files exist, without breaking the container image build.
+
 - v0.1.25 (2026-05-25) — **Asset integrity and the cache-buster are correct in production now.** The renderers stamped a Subresource Integrity digest and a `?v=` cache-buster onto the theme stylesheet and island scripts by hashing the files at render time — which silently produced nothing in production, where the container image doesn't ship the theme files and the edge has no filesystem to read them. So the integrity attribute was absent live and edge-rendered pages pinned a `0.0.0` version that never changed between releases (a stylesheet update would render against a browser-cached copy). Both now come from a manifest built at release time and read directly by both runtimes. **Fixed:** *Subresource Integrity now applied on server-rendered pages* — The `integrity="sha384-…"` attribute on the default theme's stylesheet and island scripts was computed by reading the asset off disk during the render. That read fails in the deployed container (its image carries the code, not the `themes/` tree) and at the edge (no filesystem), so the attribute was silently dropped — the tamper-evidence it's meant to provide wasn't active. The digests are now computed once at release time into `lib/asset-manifest.json` (bundled for both the container and the edge worker) and read from there, so the browser actually verifies the served bytes against the pinned hash. · *Edge-rendered pages no longer pin a 0.0.0 cache-buster* — Pages rendered at the edge (home, product, search, the empty cart, blog) appended `?v=0.0.0` to the stylesheet URL because the worker had no release version to stamp — so the cache-buster never changed across deploys and a browser could keep serving an old stylesheet after a CSS update (markup against stale styling). The version now comes from the release manifest, so each release invalidates the cached asset as intended. The drift between the manifest and the on-disk assets is caught by a smoke gate (`generate-asset-manifest.js --check`).
 
 - v0.1.23 (2026-05-25) — **The admin console renders styled again, and both surfaces now self-host their fonts.** The admin console shipped its design system as an inline <style> block, inline style="" attributes, and a cross-origin Google Fonts link — all three of which the strict `style-src 'self'` / `font-src 'self'` CSP that governs container-served routes refuses, so the console rendered as an unstyled page in production. Its styling now lives in an external stylesheet served from /assets (like the storefront's), and the typeface is self-hosted, so the console renders as designed under the same CSP that protects it. Both the storefront and the console now serve Inter from /assets rather than naming it and hoping the visitor has it installed. **Changed:** *Inter is self-hosted on both the storefront and the console* — The default theme named Inter / Inter Tight first in its font stack but shipped no font files, so the intended typography only rendered for visitors who happened to have Inter installed locally — everyone else fell back to a system sans-serif. The latin subset of Inter (400/500/600) and Inter Tight (600/700) now ships under `themes/default/assets/fonts` and is referenced via `@font-face`, so the typeface renders for every visitor and loads same-origin under `font-src 'self'` — no cross-origin font CDN on any page. The fonts are SIL OFL 1.1 (license alongside the files); `font-display:swap` paints text immediately in the system fallback and swaps when the file arrives. · *Admin console visual refresh* — With the stylesheet external it also got a pass: a proper centered sign-in card (replacing the bare form that was the first thing an operator saw), softer surfaces and shadows on cards and panels, a sticky console nav, and consistent spacing. The brand palette (ink + the storefront's accent) and every screen's structure are unchanged — this is presentation only. **Fixed:** *Admin console renders unstyled in production* — Every `/admin` screen built its design system three ways the strict CSP refuses: an inline `<style>` block, inline `style=""` attributes, and a `<link>` to fonts.googleapis.com. Container-served routes run under `style-src 'self'` / `font-src 'self'`, which drops all three — so the console arrived as unstyled HTML (a plain page) once deployed, even though it looked correct in isolation. The styling now ships as `/assets/themes/default/css/admin.css`, an external file `'self'` allows, linked with a `sha384` Subresource Integrity digest so the browser rejects a tampered or stale object; the inline attributes are gone, folded into that stylesheet. A render-shell test asserts every admin screen links the external stylesheet, carries no inline styles, and pulls no third-party font host, so the regression can't return. Operators redeploy to pick this up — `npm run deploy` uploads the new stylesheet (and the fonts below) to R2 as part of the asset sync.

package/README.md

@@ -68,6 +68,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/save-for-later.js`** | Per-customer cart holding list. Each cart line gets a login-gated "Save for later" control (`POST /cart/lines/:id/save` → `moveFromCart`); `/account/saved` lists items with Move-to-cart / Remove. `moveToCart` reprices to the current catalog price and stock-gates (out-of-stock + non-backorderable is refused). Composes `catalog.inventory` + `catalog.prices` + `catalog.variants`. |
 | **`lib/addresses.js`** | Per-customer address book at `/account/addresses` — add / edit / set default shipping or billing / remove. One-default-per-role invariant (promoting clears the prior). Every by-id route confirms the address belongs to the signed-in customer before acting (a guessed id returns 404). `b.guardUuid` ids, 2-char ISO country. |
 | **`lib/returns.js`** | Self-serve RMAs. Customer requests a return against their own order at `/account/orders/:id/return` (items + reason, ownership-checked, lines built from the order's own records) and tracks status at `/account/returns`. Operators work `/admin/returns` — approve (refund amount) / mark received / refund / reject — over the pending → approved → received → refunded FSM; illegal transitions are 409, bad ids 404. |
+| **`lib/loyalty.js`** + **`lib/loyalty-earn-rules.js`** + **`lib/loyalty-redemption.js`** | Customer rewards. `loyalty` owns the points balance, lifetime total, tier (bronze → platinum on operator-tunable thresholds), and an audited transaction ledger. `loyalty-earn-rules` defines how points are minted (per-dollar-spent, per-order, signup, birthday, …) keyed to lifecycle events; `loyalty-redemption` is the reward catalog customers spend points against. Customers see all of it at `/account/loyalty` — balance + tier, the earn rules in plain language, the reward catalog with a one-click Redeem, past redemptions, and the paginated earn/redeem ledger (login-gated). Paid orders award points automatically: the order FSM's paid transition fans out to the earn rules fire-and-forget, deduped on the order id so a re-delivered payment webhook never double-credits. At checkout a signed-in customer can spend points for a credit against the order total — valued by the redemption ratio (100 points = $1 default), capped at the order's worth and the balance, debited once behind a balance-guarded SQL decrement, stacking with any gift-card credit; surplus points stay in the balance. |
 | **`lib/recently-viewed.js`** | Signed-in customer browse history. A product-page visit records the view server-side against the customer's account (drop-silent — never blocks the page); `/account/recently-viewed` lists them newest-first as a grid with a Clear-history control. De-duped + capped per customer, archived products drop out, login-gated. Guest/session history is opt-in (a client beacon) and not shipped — the lib's `forSession` + `merge` support it. |
 | **`lib/recommendations.js`** | Product-recommendation engine. Operator-curated override pins first (`setOverride` — "when viewing A, show B", kind-scoped + weight-ordered), then a signal-based fallback: co-purchase (products bought in the same orders), category-popular, and in-stock-random filler. `recommendForProduct` / `recommendForCart` / `recommendForCustomer` / `recommendForCategory` each return renderable picks (active + in-stock, source product excluded). The order confirmation page (`/orders/:id`) renders a "Customers also bought" rail from it — best-effort, anchored on the order's items, excluding what was just bought. |
 | **`lib/collections.js`** | Curated + smart product groupings. `GET /collections` lists the shop's active collections; `GET /collections/:slug` renders the grid — manual collections list hand-picked members, smart collections evaluate stored rules against the active catalog and apply the collection's sort strategy. Each product resolves fresh, so archived products drop out. Public, no sign-in; a bad or unknown slug is a 404 (never a 500). Linked from the footer on every page. |
@@ -102,6 +103,9 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 - `migrations-d1/0043_collections.sql` — manual + smart product collections (members + rules + sort strategy)
 - `migrations-d1/0050_recently_viewed.sql` — per-customer / per-session product browse history (dedup + per-subject cap)
 - `migrations-d1/0105_recommendations.sql` — operator-curated recommendation overrides (kind-scoped, weight-ordered)
+- `migrations-d1/0022_loyalty.sql` — loyalty accounts (balance + lifetime + tier) + audited points transactions
+- `migrations-d1/0085_loyalty_redemptions.sql` — reward catalog + per-redemption records (FSM: active → consumed / expired / cancelled)
+- `migrations-d1/0163_loyalty_earn_rules.sql` — per-event earn rules + dedup-keyed award log
 
 ### Demo seed
 

package/SECURITY.md

@@ -160,3 +160,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.
+- **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
+  sealed session cookie, never from request input, so a customer only
+  ever sees and spends their own balance. Points earned on a paid order
+  are awarded fire-and-forget off the request path and deduped on the
+  order id (`loyalty_earn_log`'s `(rule, customer, event-ref)` UNIQUE),
+  so a re-delivered payment webhook can't double-credit. Spending points
+  — redeeming a reward or applying a checkout credit — debits through
+  the same atomic `balance >= points` SQL guard, so concurrent or
+  replayed requests can't overdraw. A checkout credit is capped at both
+  the order total and the live balance (a request for more than either
+  is refused, not silently clamped to a windfall), and a guest cart
+  with no account can't redeem at all.

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.25",
+  "version": "0.1.27",
   "assets": {
     "css/admin.css": "sha384-rvjL1QySBgNJGEUDusbbMCkL3fsjmzcwUvTp9pljo/0Nn/lErxq2AbY8EYvDF9Ch",
     "css/main.css": "sha384-qBY97FWZDGOploZRppwrDi0A/+R4R3iCFtyS1dfrAlqHNEPluPmY0R3HB9cJntyV",

package/lib/checkout.js

@@ -112,6 +112,15 @@ function create(deps) {
   // either is absent — the rest of the flow is unchanged.
   var giftcards     = deps.giftcards || null;
   var giftCardLedger = deps.giftCardLedger || null;
+  // Optional loyalty points credit. When wired, a signed-in customer
+  // can spend points at checkout for a storefront credit against the
+  // grand total. `loyalty.balance` reads the spendable balance;
+  // `loyalty.redeem` is the atomic debit (its `balance >= ?` SQL guard
+  // is the authoritative double-spend defense). The redemption value is
+  // derived from the ledger's own `REDEMPTION_POINTS_PER_USD` ratio so
+  // checkout never re-derives the conversion constant. Disabled when
+  // the handle is absent — the rest of the flow is unchanged.
+  var loyalty       = deps.loyalty || null;
 
   // Validate a gift-card code against a priced quote: the card exists,
   // is active, not expired, and matches the order currency. Returns
@@ -194,6 +203,82 @@ function create(deps) {
     return redemption;
   }
 
+  // Resolve an optional loyalty points credit against a priced quote.
+  // `points` is the number of points the customer asked to spend;
+  // `customerId` is the signed-in customer's UUID (a guest cart has
+  // none — loyalty redemption needs an account, so a points request on
+  // a guest order is refused). Returns the credit to apply (the points
+  // converted to minor units via the ledger's redemption ratio, then
+  // capped at the grand total so a customer can't redeem more value
+  // than the order is worth) plus the integer points that credit
+  // actually consumes. Throws a structured (non-TypeError) error on a
+  // request that can't be honored so callers surface a clean re-prompt;
+  // returns null when no points were requested or loyalty isn't wired.
+  //
+  // Capping in points-space (not minor-units) matters: redeeming 250
+  // points worth $2.50 against a $1.00 order should debit only the 100
+  // points the $1.00 credit consumes, leaving the remaining 150 points
+  // in the balance — never silently burning the surplus.
+  async function _resolveLoyaltyCredit(points, customerId, quote) {
+    if (points == null) return null;
+    if (!Number.isInteger(points) || points <= 0) {
+      var bad = new Error("checkout: loyalty_redeem_points must be a positive integer");
+      bad.code = "LOYALTY_REDEEM_INVALID";
+      throw bad;
+    }
+    if (!loyalty) {
+      var unwired = new Error("checkout: loyalty redemption is not configured");
+      unwired.code = "LOYALTY_NOT_CONFIGURED";
+      throw unwired;
+    }
+    if (!customerId) {
+      var guest = new Error("checkout: sign in to redeem loyalty points");
+      guest.code = "LOYALTY_REQUIRES_ACCOUNT";
+      throw guest;
+    }
+    var perUsd = loyalty.REDEMPTION_POINTS_PER_USD;
+    var bal = await loyalty.balance(customerId);
+    if (bal.balance < points) {
+      var insuff = new Error("checkout: loyalty balance is " + bal.balance + ", cannot redeem " + points);
+      insuff.code = "LOYALTY_INSUFFICIENT_BALANCE";
+      throw insuff;
+    }
+    // Value the requested points in minor units, then cap at the grand
+    // total. The applied minor-units are floored to a whole point's
+    // worth so the points actually debited map exactly to the credit
+    // granted (no fractional-point credit).
+    var grand = quote.totals.grand_total_minor;
+    var requestedMinor = Math.floor((points * 100) / perUsd);
+    var appliedMinor = requestedMinor < grand ? requestedMinor : grand;
+    if (appliedMinor <= 0) {
+      var tooFew = new Error("checkout: " + points + " points is worth less than the minimum redeemable credit");
+      tooFew.code = "LOYALTY_REDEEM_TOO_SMALL";
+      throw tooFew;
+    }
+    // Points the applied credit actually consumes — re-derived from the
+    // capped minor-units so a partial cap only spends the points the
+    // granted credit is worth.
+    var spentPoints = Math.ceil((appliedMinor * perUsd) / 100);
+    if (spentPoints > points) spentPoints = points;          // floor/ceil guard — never spend more than asked
+    return { points: spentPoints, applied_minor: appliedMinor };
+  }
+
+  // Burn the resolved loyalty credit against the created order. The
+  // `loyalty.redeem` decrement is the authoritative double-spend guard
+  // (its `balance_points >= ?` SQL predicate refuses an overdraw), and
+  // the `order_id` link records the redemption against the order in the
+  // loyalty audit trail. Called once per order, after the order row
+  // exists, so points are never spent for an order that failed to
+  // create.
+  async function _redeemLoyalty(resolved, customerId, orderId) {
+    await loyalty.redeem({
+      customer_id: customerId,
+      points:      resolved.points,
+      order_id:    orderId,
+      notes:       "checkout-credit:" + orderId,
+    });
+  }
+
   // Compose a quote from a cart + ship-to + (optional) selected
   // shipping service. Pure read — no DB writes.
   async function _buildQuote(input) {
@@ -292,7 +377,27 @@ function create(deps) {
       // credit reduces the amount due; the order still records the
       // full grand total it owed.
       var gc = await _resolveGiftCard(input.gift_card_code, quote);
-      var amountDue = quote.totals.grand_total_minor - (gc ? gc.applied_minor : 0);
+      // Loyalty points credit stacks on top of any gift-card credit —
+      // both reduce the same amount due. The loyalty credit is capped
+      // at the grand total inside the resolver, but since the gift card
+      // may already cover part of the order, cap the loyalty credit
+      // again at what's still due so the two credits together never
+      // drive the amount due below zero.
+      var cartRowForCustomer = await cart.get(quote.cart_id);
+      var loyaltyCustomerId = cartRowForCustomer ? (cartRowForCustomer.customer_id || null) : null;
+      var loy = await _resolveLoyaltyCredit(input.loyalty_redeem_points, loyaltyCustomerId, quote);
+      var afterGiftCard = quote.totals.grand_total_minor - (gc ? gc.applied_minor : 0);
+      if (loy && loy.applied_minor > afterGiftCard) {
+        // The gift card already covers more of the order than the
+        // points were valued against — re-cap the points credit to the
+        // residual so the two never overlap. Re-derive the spent points
+        // from the smaller credit so surplus points stay in the balance.
+        loy.applied_minor = afterGiftCard < 0 ? 0 : afterGiftCard;
+        var perUsd = loyalty.REDEMPTION_POINTS_PER_USD;
+        loy.points = Math.ceil((loy.applied_minor * perUsd) / 100);
+        if (loy.applied_minor <= 0) loy = null;
+      }
+      var amountDue = afterGiftCard - (loy ? loy.applied_minor : 0);
 
       var orderLines = quote.lines.map(function (l) {
         return {
@@ -303,15 +408,17 @@ function create(deps) {
           unit_currency:     l.unit_currency,
         };
       });
-      var cartRow = await cart.get(quote.cart_id);
+      // Reuse the cart row already fetched for the loyalty
+      // customer-id lookup above — one read, not two.
+      var cartRow = cartRowForCustomer;
       // Hash of the buyer email (same key as the customers table) so a
       // later verified-email sign-in can claim this guest order.
       var emailHash = customers ? customers.hashEmail(email) : null;
 
-      // Zero amount due — the gift card fully covers the order. No
-      // PaymentIntent (Stripe refuses a zero-amount intent); create
-      // the order, burn the card against it, and advance it straight
-      // to paid via the FSM.
+      // Zero amount due — gift-card + loyalty credit fully cover the
+      // order. No PaymentIntent (Stripe refuses a zero-amount intent);
+      // create the order, burn the credits against it, and advance it
+      // straight to paid via the FSM.
       if (amountDue === 0) {
         var paidOrder = await order.createFromCart({
           cart_id:            quote.cart_id,
@@ -328,15 +435,17 @@ function create(deps) {
           customer_email_hash: emailHash,
           lines:             orderLines,
         });
-        await _redeemGiftCard(gc, paidOrder.id);
+        if (gc) await _redeemGiftCard(gc, paidOrder.id);
+        if (loy) await _redeemLoyalty(loy, loyaltyCustomerId, paidOrder.id);
         await cart.setStatus(quote.cart_id, "converted");
         var settled = await order.transition(paidOrder.id, "mark_paid", {
-          reason: "gift_card:full",
+          reason: loy && !gc ? "loyalty:full" : "gift_card:full",
         });
         return {
           order: settled,
           payment_intent: null,
-          gift_card: { applied_minor: gc.applied_minor, amount_due_minor: 0 },
+          gift_card: gc ? { applied_minor: gc.applied_minor, amount_due_minor: 0 } : null,
+          loyalty: loy ? { points: loy.points, applied_minor: loy.applied_minor, amount_due_minor: 0 } : null,
         };
       }
 
@@ -354,6 +463,7 @@ function create(deps) {
           tax_minor:      String(quote.totals.tax_minor),
           shipping_minor: String(quote.totals.shipping_minor),
           gift_card_applied_minor: String(gc ? gc.applied_minor : 0),
+          loyalty_applied_minor:   String(loy ? loy.applied_minor : 0),
         },
       }, idempotencyKey);
 
@@ -374,10 +484,12 @@ function create(deps) {
         lines:             orderLines,
       });
 
-      // Burn the gift-card credit against the created order. Runs
-      // after the order row exists so a failed order never burns the
-      // card; the redeem decrement is the double-spend guard.
+      // Burn the gift-card + loyalty credits against the created order.
+      // Runs after the order row exists so a failed order never spends
+      // either credit; each redeem decrement is its own double-spend
+      // guard.
       if (gc) await _redeemGiftCard(gc, createdOrder.id);
+      if (loy) await _redeemLoyalty(loy, loyaltyCustomerId, createdOrder.id);
 
       // Mark the cart converted so a refresh of the storefront
       // doesn't accidentally re-quote the same cart.
@@ -391,6 +503,7 @@ function create(deps) {
           status:        pi.status,
         },
         gift_card: gc ? { applied_minor: gc.applied_minor, amount_due_minor: amountDue } : null,
+        loyalty: loy ? { points: loy.points, applied_minor: loy.applied_minor, amount_due_minor: amountDue } : null,
       };
     },
 

package/lib/order.js

@@ -141,6 +141,15 @@ function create(opts) {
   // dependency is opt-in so existing callers (and the test suite)
   // can run without standing up a webhooks primitive.
   var webhooks = opts.webhooks || null;
+  // Optional loyalty earn dispatcher — when present, an order reaching
+  // `paid` fans out to the customer's loyalty balance via the earn
+  // rules (per_dollar_spent / per_purchase / first_purchase). Opt-in
+  // like `webhooks` so callers and the test suite can run without
+  // standing up a loyalty primitive. The award runs fire-and-forget on
+  // the same detached-promise discipline as the webhook fan-out: the
+  // transition has already persisted, so a loyalty read/write must not
+  // add latency to (or fail) the order transition.
+  var loyaltyEarnRules = opts.loyaltyEarnRules || 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
@@ -306,6 +315,39 @@ function create(opts) {
           return webhooks.send("order." + event, _whPayload);
         }).catch(function () { /* drop-silent — delivery rows hold the failure */ });
       }
+      // Loyalty earn-on-purchase fan-out — fire-and-forget, same
+      // discipline as the webhook block. Only on the paid transition
+      // and only for an order that carries a customer_id (guest orders
+      // have no loyalty account to credit). The per-event dedup on
+      // `loyalty_earn_log` (rule_slug, customer_id, trigger_event_ref)
+      // collapses a re-delivered mark_paid (Stripe + PayPal webhook
+      // backstops both fire it) onto one award, so a retried transition
+      // never double-credits. dollars_spent is derived from the order
+      // subtotal (the revenue the customer actually spent on goods,
+      // excluding tax + shipping); per_purchase / first_purchase rules
+      // ignore it. The award is detached so a loyalty failure lives in
+      // the loyalty ledger's own audit trail, never as an
+      // unhandledRejection and never on the transition's latency.
+      if (loyaltyEarnRules && typeof loyaltyEarnRules.awardForEvent === "function"
+          && result.to === "paid" && refreshed && refreshed.customer_id) {
+        var _loyCustomer = refreshed.customer_id;
+        var _loyOrderId  = refreshed.id;
+        var _loyDollars  = Math.floor((Number(refreshed.subtotal_minor) || 0) / 100);
+        Promise.resolve().then(function () {
+          return loyaltyEarnRules.awardForEvent({
+            trigger:           "per_dollar_spent",
+            customer_id:       _loyCustomer,
+            dollars_spent:     _loyDollars,
+            trigger_event_ref: "order:" + _loyOrderId,
+          });
+        }).then(function () {
+          return loyaltyEarnRules.awardForEvent({
+            trigger:           "per_purchase",
+            customer_id:       _loyCustomer,
+            trigger_event_ref: "order:" + _loyOrderId,
+          });
+        }).catch(function () { /* drop-silent — loyalty ledger holds its own audit trail */ });
+      }
       return refreshed;
     },