@blamejs/blamejs-shop 0.4.20 → 0.4.21

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.21 (2026-06-06) — **Subscription changes reach the payment processor, smart collections match real products, refunds claw back earned points, and the remaining balance races are closed.** A correctness release across the commerce surfaces. Changing a subscription's quantity now updates the processor before the local record — what the customer sees is what they're billed — and a cadence change on a processor-backed plan is honestly refused rather than silently ignored. Smart collections, which matched zero products in production because their rules read fields the catalog rows never carried, now evaluate against the real product data. Loyalty points earned on a purchase are reversed when the order is refunded or cancelled. And the loyalty, store-credit, gift-registry, and gift-card-ledger write paths that could lose updates or oversell under concurrency now use atomic guards. **Fixed:** *Subscription quantity changes reach the payment processor* — Changing a subscription's quantity updated the local record and showed a success message while the processor kept billing the original amount. The change is now pushed to the processor first — a processor failure leaves the local record untouched and surfaces the error, so the customer-visible state and the billed state can no longer diverge. Changing delivery frequency on a processor-backed subscription is refused with honest guidance (the billing cadence is bound to the plan's price and cannot be re-cadenced in place); self-managed local subscriptions keep their frequency controls. Self-manage controls also now respect the processor's status — a subscription the processor reports as cancelled or expired shows its state instead of live controls. · *Smart collections match real catalog products* — Smart-collection rules read fields like tags, price, and stock from each product row — fields the real catalog listing never carried, so every smart collection matched zero products in production even though admin previews built on richer mock rows looked right. Rule evaluation now joins the real tag, category, vendor, price, and inventory data onto each product page, and the admin preview routes through the same path the storefront uses. Smart-collection pages also stop re-walking the entire catalog on every paginated request — the matched set is briefly cached and a rule edit invalidates it. · *Refunds and cancellations reverse the loyalty points the order earned* — Points awarded when an order was paid survived a refund or cancellation — buying, earning, and refunding farmed points indefinitely. The earn record is now claimed atomically on the order's refund or cancel transition and the awarded points are clawed back from the balance, floored at zero when some were already spent. The reversal is idempotent (a re-delivered payment webhook reverses exactly once) and lifetime points — which drive tier — are deliberately untouched. · *Balance and inventory-adjacent races closed across loyalty, store credit, gift registry, and gift-card ledger* — Loyalty earn and adjust used read-then-write absolute updates that could lose concurrent updates; the gift-registry purchase check could oversell a registry item under two simultaneous purchases; and the gift-card ledger's overdraft check could let two concurrent debits both pass. All of these now use single-statement conditional writes that refuse cleanly when the guard fails. Store-credit expiry sweeps also stop under-expiring when operator-initiated deductions exist — the sweep now keys on its own prior output rather than netting all expiry rows together. · *Search-ranking click-through metrics are bounded and attributed* — The ranking metrics screen could show click-through rates above 100%, and clicks were attributed from the query string alone — trivially spoofable. A click now only counts when the same session recorded a real impression for that query, and displayed rates are bounded at 100%.
+
 - v0.4.20 (2026-06-06) — **Payment integrity: refunds, gift-card balances, and checkout submission are race-proof, and abandoned checkouts return gift-card funds.** A money-path hardening release. Concurrent refund clicks on the same return can no longer reach the payment provider twice. A gift card that part-paid a checkout gets its balance back when the order is cancelled, fails payment, or is reaped as stale. Double-submitting checkout can no longer create two charges and two orders. Return requests are refused server-side on orders that aren't in a returnable state, the refund confirmation screen shows the currency the provider will actually refund, and a buy-online-pickup-in-store order now reaches its delivered state when picked up. **Fixed:** *A return can only be refunded once, even under concurrent requests* — Two simultaneous refund requests for the same approved return could both pass the status check and both reach the payment provider, each with a fresh idempotency key — a double refund. The refund now claims the return atomically before the provider is called (the second request answers 409), the provider call uses a key derived from the return itself so even a retry collapses into the same refund, and a provider failure releases the claim so the refund can be retried. · *Gift-card funds come back when a part-paid checkout dies* — When a gift card partially covered a checkout and the order was then cancelled, failed payment, or sat abandoned until reaped, the card's debit was never returned — the balance was permanently gone. Redemptions are now reversed on those order transitions: the card balance is restored (a fully drained card is reactivated), the reversal is idempotent, and it rides the same order lifecycle that releases inventory holds. · *Double-submitting checkout creates one charge and one order* — Two concurrent checkout submissions could both pass the cart-status read and each create a payment intent and an order. The cart is now claimed atomically as the single gate — the second submission is redirected back to the cart — and the payment-provider idempotency key is derived from the cart, so even a duplicate that slipped through would collapse into one charge on the provider's side. A failure before the order exists releases the claim so the customer can retry. · *Return requests are validated server-side* — The return-request form and its submission are now refused on orders that are not in a returnable state — a refunded, cancelled, or unpaid order answers with a clear message instead of opening a return that could feed a second refund downstream. Previously only the button's visibility enforced this. · *A failed gift-card settlement no longer strands a completed payment* — If recording a gift card's redemption failed after the payment had already succeeded and the order existed, the checkout aborted mid-way — leaving a paid order with a cart that never converted. The settlement step now completes the order regardless and surfaces the failure for follow-up instead of stranding the purchase. · *The refund confirmation shows the currency the provider refunds* — The confirmation screen displayed the return's approved currency, but the provider refunds in the original charge's currency. The screen now reads the same source the refund uses. · *Pickup orders reach their delivered state* — Marking a pickup order as picked up drove an order transition that was only legal for shipped orders, and the failure was silently swallowed — the pickup schedule said picked up while the order stayed in its paid state. The order lifecycle now has a pickup-completion transition, so a picked-up order genuinely lands in delivered and downstream reporting sees it.
 
 - v0.4.19 (2026-06-06) — **Wishlist alerts fire once per event instead of repeating daily, stale digests catch up with a single email, and webhook delivery stops throttling itself.** A set of notification and delivery fixes. Back-in-stock and price-drop wishlist alerts now fire only when something actually changes — a steadily in-stock item no longer re-alerts every day. A wishlist digest whose schedule fell behind sends one catch-up email instead of one per minute until current. Outbound webhook delivery no longer counts its own rate-limit refusals against the limit (which kept the throttle tripped once hit), retrying an exhausted delivery no longer duplicates its dead-letter record, and the blog RSS feed renders correctly when a post title or body contains dollar-sign sequences. **Fixed:** *Back-in-stock and price-drop alerts fire on the change, not the state* — The wishlist alert sweep evaluated the current state of each item, so anything in stock re-alerted every wishlister on every sweep — the daily dedupe window just made the flood daily. Alerts now track the last-observed state per customer and item: back-in-stock fires only on an out-of-stock-to-in-stock transition, price-drop only when the price falls below the level already alerted, and a recovered price re-arms the alert. A steadily in-stock item never re-fires. The weekly cap and dedupe are also enforced atomically, so two overlapping sweeps can't double-send past the cap. · *A stale digest enrollment catches up with one email* — A wishlist digest whose next-send time had fallen far behind advanced one period per scheduler tick and sent an email each time — a subscriber could receive dozens of digests in an hour while the schedule caught up. Catching up now snaps the schedule to the present and sends at most one digest. · *Webhook delivery rate limiting no longer feeds on its own refusals* — The outbound webhook rate-limit gate counted its own refusal records toward the limit, so once an endpoint tripped the throttle it could stay tripped indefinitely, and every suppressed attempt persisted another row. Refusals are no longer counted by the gate and collapse to a single record per endpoint per window. · *Retrying an exhausted webhook delivery is idempotent* — Manually retrying a delivery that had already exhausted its attempts inserted a fresh dead-letter record on every click. Retry of an exhausted or already-delivered delivery now answers as a clean no-op, and the dead-letter table enforces one record per delivery. · *The RSS feed renders posts containing dollar-sign sequences* — The feed assembled items with a plain string replacement, which gives `$` sequences special meaning — a post title or body containing a dollar sign followed by a backtick or ampersand could corrupt the entire feed XML. The feed now uses the same literal splice the page renderers use. The feed's author field also no longer exposes an internal identifier; it carries the shop name, matching the blog pages.

package/lib/asset-manifest.json

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

package/lib/collections.js

@@ -248,21 +248,45 @@ function _now() { return Date.now(); }
 // in isolation against a synthetic product.
 function _matchRule(rule, product) {
   var fieldVal = product == null ? undefined : product[rule.field];
+  // A catalog field can be MULTI-VALUED — a product carries an array
+  // of `tags` and an array of `category` memberships. For the scalar
+  // ops (`eq` / `neq` / `in` / `not_in`) an array field matches with
+  // membership semantics ("any of the product's categories equals X").
+  // A scalar field value keeps strict-equality semantics, so the
+  // existing single-valued fields (`vendor`, numeric fields) are
+  // unaffected. This is what lets a smart rule like
+  // `{ field: "category", op: "eq", value: "apparel" }` match a
+  // product that lives in apparel + clearance + outdoor.
+  var isArrayVal = Array.isArray(fieldVal);
   switch (rule.op) {
-    case "eq":  return fieldVal === rule.value;
-    case "neq": return fieldVal !== rule.value;
+    case "eq":  return isArrayVal ? fieldVal.indexOf(rule.value) >= 0 : fieldVal === rule.value;
+    case "neq": return isArrayVal ? fieldVal.indexOf(rule.value) < 0  : fieldVal !== rule.value;
     case "contains": {
       // Validator guaranteed an array field; if the catalog row
       // hasn't populated it, treat as empty (not a match).
-      if (!Array.isArray(fieldVal)) return false;
+      if (!isArrayVal) return false;
       return fieldVal.indexOf(rule.value) >= 0;
     }
     case "gt":  return typeof fieldVal === "number" && fieldVal >  rule.value;
     case "gte": return typeof fieldVal === "number" && fieldVal >= rule.value;
     case "lt":  return typeof fieldVal === "number" && fieldVal <  rule.value;
     case "lte": return typeof fieldVal === "number" && fieldVal <= rule.value;
-    case "in":  return rule.value.indexOf(fieldVal) >= 0;
-    case "not_in": return rule.value.indexOf(fieldVal) < 0;
+    case "in":
+      if (isArrayVal) {
+        for (var ai = 0; ai < fieldVal.length; ai += 1) {
+          if (rule.value.indexOf(fieldVal[ai]) >= 0) return true;
+        }
+        return false;
+      }
+      return rule.value.indexOf(fieldVal) >= 0;
+    case "not_in":
+      if (isArrayVal) {
+        for (var ni = 0; ni < fieldVal.length; ni += 1) {
+          if (rule.value.indexOf(fieldVal[ni]) >= 0) return false;
+        }
+        return true;
+      }
+      return rule.value.indexOf(fieldVal) < 0;
     case "between": {
       if (typeof fieldVal !== "number") return false;
       return fieldVal >= rule.value[0] && fieldVal <= rule.value[1];
@@ -299,6 +323,20 @@ function _evaluateRules(input) {
   return _matchRuleset(rules, product);
 }
 
+// Collect the distinct catalog fields a (validated) rule set reads, so
+// the smart-eval path can enrich ONLY the fields a collection actually
+// references rather than every supported field on every product. `rules`
+// is the `{ all, any }` shape `_validateRules` returns.
+function _fieldsReferenced(rules) {
+  var seen = Object.create(null);
+  function _walk(list) {
+    for (var i = 0; i < list.length; i += 1) seen[list[i].field] = true;
+  }
+  _walk(rules.all);
+  _walk(rules.any);
+  return Object.keys(seen);
+}
+
 // ---- sort comparators for smart collections ------------------------------
 
 // Best-selling needs a sales-rank on the product object; the catalog
@@ -369,6 +407,63 @@ function create(opts) {
   }
   var cursorSecret = opts.cursorSecret;
 
+  // Smart-collection matched-roster cache. A smart collection has no
+  // materialised membership — `productsIn` walks the WHOLE catalog,
+  // evaluates rules, sorts, then slices the requested page. Paginating
+  // a smart collection therefore re-walked the entire catalog on every
+  // page request (page 2 redid the work page 1 already did). This brief
+  // in-process cache holds the sorted matched roster keyed by the
+  // collection's identity + rule fingerprint, so successive page
+  // requests within the TTL slice the cached roster instead of
+  // re-walking. The TTL is short (a smart collection that just lost a
+  // product to an archive shows the stale member for at most one TTL)
+  // and configurable; pass `smartCacheTtlMs: 0` to disable. The cache
+  // is per-factory-instance and bounded by an LRU-ish cap so it can't
+  // grow unbounded across many distinct collections.
+  var SMART_CACHE_TTL_MS = opts.smartCacheTtlMs != null
+    ? opts.smartCacheTtlMs
+    : b.constants.TIME.seconds(30);
+  if (typeof SMART_CACHE_TTL_MS !== "number" || !isFinite(SMART_CACHE_TTL_MS) || SMART_CACHE_TTL_MS < 0) {
+    throw new TypeError("collections.create: smartCacheTtlMs must be a non-negative number of ms");
+  }
+  var SMART_CACHE_MAX_ENTRIES = 64;
+  var _smartCache = new Map();   // key -> { roster, expires_at }
+
+  function _smartCacheKey(slug, row) {
+    // The rule fingerprint + sort_strategy + updated_at are part of the
+    // key, so re-defining a smart collection's rules (which bumps
+    // updated_at and rewrites rules_json) misses the prior entry and
+    // re-walks — no stale roster after an operator edit. NUL joins the
+    // parts (it can't appear in a slug, timestamp, sort strategy, or
+    // JSON, so the parts can't collide), written as an escape so the
+    // source stays plain text.
+    return slug + "\u0000" + (row.updated_at == null ? "" : row.updated_at) +
+      "\u0000" + (row.sort_strategy || "") + "\u0000" + (row.rules_json || "");
+  }
+
+  function _smartCacheGet(key) {
+    if (SMART_CACHE_TTL_MS === 0) return null;
+    var hit = _smartCache.get(key);
+    if (!hit) return null;
+    if (hit.expires_at <= _now()) { _smartCache.delete(key); return null; }
+    // Refresh LRU recency.
+    _smartCache.delete(key);
+    _smartCache.set(key, hit);
+    return hit.roster;
+  }
+
+  function _smartCacheSet(key, roster) {
+    if (SMART_CACHE_TTL_MS === 0) return;
+    if (_smartCache.size >= SMART_CACHE_MAX_ENTRIES) {
+      // Evict the least-recently-used entry (first key in insertion
+      // order — `get` re-inserts on hit so live entries drift to the
+      // tail).
+      var oldest = _smartCache.keys().next().value;
+      if (oldest !== undefined) _smartCache.delete(oldest);
+    }
+    _smartCache.set(key, { roster: roster, expires_at: _now() + SMART_CACHE_TTL_MS });
+  }
+
   // ---- internal helpers --------------------------------------------------
 
   async function _row(slug) {
@@ -406,8 +501,12 @@ function create(opts) {
   // caller-supplied visitor. The catalog is expected to expose
   // `products.list({ limit, cursor?, status? })`; the smart-eval
   // path filters to `status = 'active'` so archived rows never leak
-  // into a smart collection.
-  async function _walkCatalogActive(visit) {
+  // into a smart collection. `enrichFields` (optional) is the list of
+  // smart-rule fields to join onto each page's rows before the visitor
+  // sees them, so the rule evaluator reads real catalog data rather
+  // than `undefined` — enrichment is batched per page (one query per
+  // referenced supporting table per page, not per product).
+  async function _walkCatalogActive(visit, enrichFields) {
     var cursor = null;
     var pages = 0;
     var pageLimit = 200;
@@ -419,6 +518,7 @@ function create(opts) {
     while (pages < MAX_PAGES) {
       var page = await catalog.products.list({ status: "active", limit: pageLimit, cursor: cursor });
       var rows = (page && page.rows) || [];
+      if (enrichFields && enrichFields.length) await _enrichRows(rows, enrichFields);
       for (var i = 0; i < rows.length; i += 1) await visit(rows[i]);
       cursor = (page && page.next_cursor) || null;
       pages += 1;
@@ -427,6 +527,149 @@ function create(opts) {
     throw new Error("collections: catalog walk exceeded " + MAX_PAGES + " pages — pre-materialise smart membership");
   }
 
+  // ---- smart-rule field enrichment --------------------------------------
+
+  // The catalog's `products.list` returns the bare product row — id,
+  // slug, title, description, status, created_at, updated_at. A smart
+  // collection's rules read `tags`, `category`, `vendor`, `price_minor`,
+  // and `inventory_count`, none of which live on that row; they're
+  // joined from supporting tables (`product_tags`, `product_categories`,
+  // `vendor_skus` via `variants.sku`, `prices`, `inventory`). Without
+  // this enrichment every rule on those fields evaluated against
+  // `undefined` and a smart collection matched ZERO products in
+  // production while the unit-test mock (which pre-stuffs the fields)
+  // stayed green — a dark feature.
+  //
+  // Enrichment is batched per catalog page and scoped to ONLY the fields
+  // the active rule set references (computed once by the caller), so a
+  // collection that filters on price alone never pays for the tag /
+  // category / vendor joins. A row that ALREADY carries a field (e.g. a
+  // caller that pre-decorated, or the test mock) is left untouched — the
+  // enrichment only fills gaps. Each supporting-table read is wrapped so
+  // an unmigrated table degrades the field to its empty form (empty
+  // array / null / 0) rather than throwing out of the catalog walk.
+  async function _enrichRows(rows, fields) {
+    if (!rows.length || !fields.length) return;
+    var need = {};
+    for (var f = 0; f < fields.length; f += 1) need[fields[f]] = true;
+
+    // Only enrich product rows that are MISSING the requested field —
+    // gather their ids per field so a pre-decorated row is never
+    // re-queried.
+    var ids = [];
+    var idSeen = Object.create(null);
+    for (var i = 0; i < rows.length; i += 1) {
+      var id = rows[i] && rows[i].id;
+      if (id == null) continue;
+      if (!idSeen[id]) { idSeen[id] = true; ids.push(id); }
+    }
+    if (!ids.length) return;
+    var ph = ids.map(function (_v, n) { return "?" + (n + 1); }).join(",");
+
+    async function _safeQuery(sql, params) {
+      try { return (await query(sql, params)).rows; }
+      catch (_e) { return []; }   // unmigrated supporting table → empty
+    }
+
+    var tagsByProduct = null;
+    if (need.tags) {
+      tagsByProduct = Object.create(null);
+      var tagRows = await _safeQuery(
+        "SELECT product_id, tag FROM product_tags WHERE product_id IN (" + ph + ")",
+        ids,
+      );
+      for (var t = 0; t < tagRows.length; t += 1) {
+        var tp = tagRows[t].product_id;
+        (tagsByProduct[tp] || (tagsByProduct[tp] = [])).push(tagRows[t].tag);
+      }
+    }
+
+    var catByProduct = null;
+    if (need.category) {
+      catByProduct = Object.create(null);
+      var catRows = await _safeQuery(
+        "SELECT product_id, category FROM product_categories WHERE product_id IN (" + ph + ")",
+        ids,
+      );
+      for (var c = 0; c < catRows.length; c += 1) {
+        var cp = catRows[c].product_id;
+        (catByProduct[cp] || (catByProduct[cp] = [])).push(catRows[c].category);
+      }
+    }
+
+    var vendorByProduct = null;
+    if (need.vendor) {
+      vendorByProduct = Object.create(null);
+      // Vendor binds to a SKU (vendor_skus.sku), and a SKU belongs to a
+      // variant of a product. A product with several variants could in
+      // principle map to more than one vendor; the smart-rule field is
+      // scalar, so we take the lexicographically-smallest assigned
+      // vendor slug for determinism. Products with no assigned vendor
+      // get null (no row), and the rule on `vendor` simply won't match.
+      var venRows = await _safeQuery(
+        "SELECT v.product_id AS product_id, MIN(vs.vendor_slug) AS vendor " +
+        "FROM variants v JOIN vendor_skus vs ON vs.sku = v.sku " +
+        "WHERE v.product_id IN (" + ph + ") GROUP BY v.product_id",
+        ids,
+      );
+      for (var vi = 0; vi < venRows.length; vi += 1) {
+        vendorByProduct[venRows[vi].product_id] = venRows[vi].vendor;
+      }
+    }
+
+    var priceByProduct = null;
+    if (need.price_minor) {
+      priceByProduct = Object.create(null);
+      // Lowest CURRENT price across the product's variants — the
+      // `effective_until IS NULL` row is the live price the catalog's
+      // own decorator reads. "Starting at" is the natural price a
+      // price-bounded smart rule (`price_minor < 5000`) should test.
+      var priceRows = await _safeQuery(
+        "SELECT v.product_id AS product_id, MIN(pr.amount_minor) AS price_minor " +
+        "FROM variants v JOIN prices pr ON pr.variant_id = v.id " +
+        "WHERE v.product_id IN (" + ph + ") AND pr.effective_until IS NULL " +
+        "GROUP BY v.product_id",
+        ids,
+      );
+      for (var pi = 0; pi < priceRows.length; pi += 1) {
+        priceByProduct[priceRows[pi].product_id] = priceRows[pi].price_minor;
+      }
+    }
+
+    var invByProduct = null;
+    if (need.inventory_count) {
+      invByProduct = Object.create(null);
+      // Total on-hand units across the product's variant SKUs. A rule
+      // like `inventory_count > 0` ("only in-stock") reads this.
+      var invRows = await _safeQuery(
+        "SELECT v.product_id AS product_id, COALESCE(SUM(inv.stock_on_hand), 0) AS inventory_count " +
+        "FROM variants v JOIN inventory inv ON inv.sku = v.sku " +
+        "WHERE v.product_id IN (" + ph + ") GROUP BY v.product_id",
+        ids,
+      );
+      for (var ii = 0; ii < invRows.length; ii += 1) {
+        invByProduct[invRows[ii].product_id] = invRows[ii].inventory_count;
+      }
+    }
+
+    for (var r = 0; r < rows.length; r += 1) {
+      var row = rows[r];
+      var rid = row && row.id;
+      if (rid == null) continue;
+      if (need.tags && !("tags" in row)) row.tags = tagsByProduct[rid] || [];
+      if (need.category && !("category" in row)) row.category = catByProduct[rid] || [];
+      if (need.vendor && !("vendor" in row)) {
+        row.vendor = Object.prototype.hasOwnProperty.call(vendorByProduct, rid) ? vendorByProduct[rid] : null;
+      }
+      if (need.price_minor && !("price_minor" in row)) {
+        row.price_minor = Object.prototype.hasOwnProperty.call(priceByProduct, rid) ? priceByProduct[rid] : null;
+      }
+      if (need.inventory_count && !("inventory_count" in row)) {
+        row.inventory_count = Object.prototype.hasOwnProperty.call(invByProduct, rid) ? invByProduct[rid] : 0;
+      }
+    }
+  }
+
   // ---- defineManual ------------------------------------------------------
 
   async function defineManual(input) {
@@ -824,12 +1067,22 @@ function create(opts) {
       }
     }
 
-    var matched = [];
-    await _walkCatalogActive(function (product) {
-      if (_matchRuleset(rules, product)) matched.push(product);
-    });
-    var sortStrategy = row.sort_strategy === "manual" ? "newest" : row.sort_strategy;
-    matched.sort(_smartCompare(sortStrategy));
+    // Reuse the cached sorted roster when a recent page request already
+    // walked + sorted this exact (slug, rules, sort, updated_at)
+    // combination; otherwise walk the catalog once, sort, and cache.
+    // Paginating no longer re-walks the whole catalog per page.
+    var cacheKey = _smartCacheKey(input.slug, row);
+    var matched = _smartCacheGet(cacheKey);
+    if (matched == null) {
+      var enrichFields = _fieldsReferenced(rules);
+      matched = [];
+      await _walkCatalogActive(function (product) {
+        if (_matchRuleset(rules, product)) matched.push(product);
+      }, enrichFields);
+      var sortStrategy = row.sort_strategy === "manual" ? "newest" : row.sort_strategy;
+      matched.sort(_smartCompare(sortStrategy));
+      _smartCacheSet(cacheKey, matched);
+    }
     var slice = matched.slice(startIdx, startIdx + limit);
     var nextS = null;
     if (startIdx + slice.length < matched.length) {
@@ -879,12 +1132,27 @@ function create(opts) {
           "SELECT * FROM collections WHERE type = 'smart' AND archived_at IS NULL",
           [],
         );
+        // Parse every active smart rule set once, collecting the UNION
+        // of catalog fields they read so the single product can be
+        // enriched with real tag / category / vendor / price /
+        // inventory data in one batch before any rule evaluates —
+        // mirroring the productsIn smart path. Without this the reverse
+        // lookup matched zero smart collections for the same dark-feature
+        // reason the forward path did.
+        var parsed = [];
+        var fieldSeen = Object.create(null);
         for (var s = 0; s < smartRows.rows.length; s += 1) {
           if (seen[smartRows.rows[s].slug]) continue;
           var rules;
           try { rules = JSON.parse(smartRows.rows[s].rules_json); }
           catch (_e) { continue; }
-          if (_matchRuleset(rules, product)) out.push(_decode(smartRows.rows[s]));
+          parsed.push({ row: smartRows.rows[s], rules: rules });
+          var refs = _fieldsReferenced(rules);
+          for (var rf = 0; rf < refs.length; rf += 1) fieldSeen[refs[rf]] = true;
+        }
+        await _enrichRows([product], Object.keys(fieldSeen));
+        for (var pj = 0; pj < parsed.length; pj += 1) {
+          if (_matchRuleset(parsed[pj].rules, product)) out.push(_decode(parsed[pj].row));
         }
       }
     }

package/lib/gift-card-ledger.js

@@ -240,24 +240,53 @@ function create(opts) {
       var requested  = _epochMs(input.occurred_at, "occurred_at");
       if (requested == null) requested = _now();
 
-      var latest = await _readLatest(giftCardId);
-      if (amount > latest.balance) {
+      // Atomic guarded INSERT — the overdraft check and the row write
+      // happen in ONE statement so two concurrent debits can't both
+      // read the same balance, both pass the check, and both write
+      // (the read-then-write race that corrupted `balance_after_minor`).
+      // The latest row's snapshot (balance + occurred_at) is read by
+      // correlated scalar subqueries INSIDE the INSERT; the WHERE gates
+      // the write on `current_balance >= amount` against that live
+      // value, and the inserted `balance_after_minor` /  monotonic
+      // `occurred_at` are derived from the same subqueries — so on D1
+      // (where a single statement is atomic) exactly one of two racing
+      // debits lands. rowCount === 0 means the guard refused: either a
+      // genuine overdraft or the loser of a race.
+      var id = b.uuid.v7();
+      var balSub =
+        "COALESCE((SELECT balance_after_minor FROM gift_card_ledger " +
+        "WHERE gift_card_id = ?2 ORDER BY occurred_at DESC LIMIT 1), 0)";
+      var tsSub =
+        "(SELECT occurred_at FROM gift_card_ledger " +
+        "WHERE gift_card_id = ?2 ORDER BY occurred_at DESC LIMIT 1)";
+      var ins = await query(
+        "INSERT INTO gift_card_ledger " +
+        "(id, gift_card_id, kind, amount_minor, source, source_ref, order_id, balance_after_minor, occurred_at) " +
+        "SELECT ?1, ?2, 'debit', ?3, NULL, NULL, ?4, " +
+        balSub + " - ?3, " +
+        "CASE WHEN ?5 > COALESCE(" + tsSub + ", 0) THEN ?5 ELSE COALESCE(" + tsSub + ", 0) + 1 END " +
+        "WHERE " + balSub + " >= ?3",
+        [id, giftCardId, amount, orderId, requested],
+      );
+      if (Number(ins.rowCount || 0) === 0) {
         var insufficient = new Error("giftCardLedger.debit: amount exceeds available balance");
         insufficient.code = "GIFT_CARD_LEDGER_INSUFFICIENT_BALANCE";
         throw insufficient;
       }
-      var ts    = _resolveOccurredAt(requested, latest.occurred_at);
-      var after = latest.balance - amount;
-      var id = await _writeRow(giftCardId, "debit", amount, null, null, orderId, after, ts);
-
+      // Re-read the row we just wrote to surface the resolved
+      // balance_after / occurred_at without recomputing them client-side.
+      var wrote = (await query(
+        "SELECT balance_after_minor, occurred_at FROM gift_card_ledger WHERE id = ?1",
+        [id],
+      )).rows[0];
       return {
         id:                  id,
         gift_card_id:        giftCardId,
         kind:                "debit",
         amount_minor:        amount,
         order_id:            orderId,
-        balance_after_minor: after,
-        occurred_at:         ts,
+        balance_after_minor: wrote ? wrote.balance_after_minor : null,
+        occurred_at:         wrote ? wrote.occurred_at : requested,
       };
     },
 

package/lib/gift-registry.js

@@ -622,10 +622,12 @@ function create(opts) {
     if (item.archived_at != null) {
       throw new TypeError("giftRegistry.purchaseItem: item " + JSON.stringify(itemId) + " has been removed");
     }
-    // Refuse over-purchase: aggregate prior purchases + this one
-    // must not exceed `quantity_desired`. The owner's wish-list is
+    // Refuse over-purchase: aggregate prior purchases + this one must
+    // not exceed `quantity_desired`. The owner's wish-list is
     // authoritative — a fourth blender is not a gift, it's a return
-    // pending.
+    // pending. The pre-read below only shapes a friendly "remaining N"
+    // error for the common (uncontended) case; the AUTHORITATIVE check
+    // is the guarded INSERT that follows.
     var priorRes = await query(
       "SELECT COALESCE(SUM(quantity), 0) AS sum FROM gift_registry_purchases " +
       "WHERE registry_slug = ?1 AND item_id = ?2",
@@ -644,12 +646,48 @@ function create(opts) {
 
     var id = b.uuid.v7();
     var ts = _now();
-    await query(
+    // Atomic guarded INSERT — the SUM-of-prior-purchases check and the
+    // purchase write land in ONE statement so two concurrent buyers
+    // can't both read the same prior sum, both pass the pre-check, and
+    // both insert (the read-then-write race that let purchases exceed
+    // `quantity_desired`). The constraint is re-evaluated against the
+    // LIVE purchase sum + the item's live `quantity_desired` inside the
+    // INSERT; the item must also still exist and be unarchived. On D1 a
+    // single statement is atomic, so exactly one of two racing
+    // purchases for the last unit lands. rowCount === 0 means the guard
+    // refused — a concurrent purchase claimed the remaining quantity
+    // first (or the item was archived between the pre-check and here).
+    var ins = await query(
       "INSERT INTO gift_registry_purchases " +
       "(id, registry_slug, item_id, quantity, buyer_customer_id, buyer_message, reveal_buyer, occurred_at) " +
-      "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
+      "SELECT ?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8 " +
+      "WHERE EXISTS (" +
+      "  SELECT 1 FROM gift_registry_items gi " +
+      "  WHERE gi.id = ?3 AND gi.registry_slug = ?2 AND gi.archived_at IS NULL " +
+      "  AND (" +
+      "    SELECT COALESCE(SUM(gp.quantity), 0) FROM gift_registry_purchases gp " +
+      "    WHERE gp.registry_slug = ?2 AND gp.item_id = ?3" +
+      "  ) + ?4 <= gi.quantity_desired" +
+      ")",
       [id, slug, itemId, qty, buyerId, buyerMsg, reveal ? 1 : 0, ts],
     );
+    if (Number(ins.rowCount || 0) === 0) {
+      // Lost the race (or the item was archived between the pre-check
+      // and the guarded INSERT). Recompute the live remaining for an
+      // honest message; the write applied nothing.
+      var liveSum = Number((await query(
+        "SELECT COALESCE(SUM(quantity), 0) AS sum FROM gift_registry_purchases " +
+        "WHERE registry_slug = ?1 AND item_id = ?2",
+        [slug, itemId],
+      )).rows[0].sum || 0);
+      var raced = new Error(
+        "giftRegistry.purchaseItem: quantity " + qty +
+        " exceeds remaining " + Math.max(0, item.quantity_desired - liveSum) +
+        " on item " + itemId,
+      );
+      raced.code = "GIFT_REGISTRY_OVER_PURCHASE";
+      throw raced;
+    }
     await query(
       "UPDATE gift_registries SET updated_at = ?1 WHERE slug = ?2",
       [ts, slug],

package/lib/loyalty-earn-rules.js

@@ -648,6 +648,111 @@ function create(opts) {
     };
   }
 
+  // ---- reverseForEvent ------------------------------------------------
+
+  // Reverse every award booked for one (customer, event) — the
+  // counterpart to awardForEvent on an order's cancel / refund edge. A
+  // paid order awards points; if that order later dies the points must
+  // come back off the balance or a buy-then-refund mints free rewards.
+  //
+  // The earn-log `reversed_at` claim IS the idempotency guard: the
+  // `UPDATE ... WHERE reversed_at IS NULL` serializes a concurrent
+  // double-fire (a re-delivered webhook, or the stale-order reaper
+  // racing a refund) so the points are clawed back exactly once. A
+  // never-awarded event (a guest order, or one that never reached paid)
+  // claims zero rows and is a natural no-op — no paid-state precondition
+  // needed. Returns { reversed_points, clawed_points }: reversed_points
+  // is what the awards totalled; clawed_points is what actually came off
+  // the balance (floored at zero — a customer may have already spent the
+  // points, and the balance can't go negative).
+  async function reverseForEvent(input) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("loyaltyEarnRules.reverseForEvent: input object required");
+    }
+    var customerId      = _uuid(input.customer_id, "customer_id");
+    var triggerEventRef = _triggerEventRef(input.trigger_event_ref);
+
+    // Atomic claim across every rule that awarded for this event. The
+    // unreversed predicate is the serialization point — a row claimed
+    // here can't be claimed by a racing reversal, and an already-reversed
+    // (or never-awarded) event claims nothing.
+    var ts = _now();
+    var claim = await query(
+      "UPDATE loyalty_earn_log SET reversed_at = ?1 " +
+      "WHERE customer_id = ?2 AND trigger_event_ref = ?3 AND reversed_at IS NULL",
+      [ts, customerId, triggerEventRef],
+    );
+    if (Number(claim.rowCount || 0) === 0) {
+      return { reversed_points: 0, clawed_points: 0 };
+    }
+
+    // Sum exactly the rows this call claimed (reversed_at === ts pins them
+    // to this reversal, not an earlier one against the same event).
+    var sumRow = (await query(
+      "SELECT COALESCE(SUM(points_awarded), 0) AS earned FROM loyalty_earn_log " +
+      "WHERE customer_id = ?1 AND trigger_event_ref = ?2 AND reversed_at = ?3",
+      [customerId, triggerEventRef, ts],
+    )).rows[0] || { earned: 0 };
+    var earned = Number(sumRow.earned || 0);
+
+    // Claw the earned points back off the running balance, floored at
+    // zero. loyalty.adjust refuses an underflow by THROWING an Error with
+    // code LOYALTY_INSUFFICIENT_BALANCE; a concurrent spend can shrink the
+    // balance between our read and the adjust, so on that refusal we
+    // re-read and retry against the smaller balance (≤3 attempts). The
+    // non-negative guard inside adjust makes the race safe — the worst
+    // case is we claw less, never below zero, never negative. Lifetime is
+    // not decremented (adjust's stance — tier never downgrades
+    // retroactively). Skip the adjust entirely when there's nothing to
+    // claw (adjust requires a non-zero delta).
+    var clawed = 0;
+    if (loyaltyHandle && typeof loyaltyHandle.adjust === "function"
+        && typeof loyaltyHandle.balance === "function" && earned > 0) {
+      try {
+        for (var attempt = 0; attempt < 3; attempt += 1) {
+          var bal = await loyaltyHandle.balance(customerId);
+          var claw = Math.min(earned, Number((bal && bal.balance) || 0));
+          if (claw <= 0) break;
+          try {
+            await loyaltyHandle.adjust({
+              customer_id: customerId,
+              points:      -claw,
+              source:      "earn-reversal",
+              notes:       "reversed ref=" + triggerEventRef,
+            });
+            clawed = claw;
+            break;
+          } catch (err) {
+            // A concurrent spend drained the balance below `claw` between
+            // the read and the adjust. Re-read and retry against the new,
+            // smaller balance. Any other failure escapes to the claim
+            // release below.
+            if (!(err && err.code === "LOYALTY_INSUFFICIENT_BALANCE")) throw err;
+          }
+        }
+      } catch (clawErr) {
+        // The clawback failed for a reason that is NOT the floor-at-zero
+        // refusal (a transient DB fault, an unmigrated ledger). Holding
+        // the claim would be a silent loss: a retry would see the rows
+        // already reversed and no-op while the balance keeps the points.
+        // Release the claim so a later reversal can run, then surface the
+        // original failure. The release is best-effort — if it ALSO
+        // fails, the original error still propagates and the rows stay
+        // claimed for manual reconciliation.
+        try {
+          await query(
+            "UPDATE loyalty_earn_log SET reversed_at = NULL " +
+            "WHERE customer_id = ?1 AND trigger_event_ref = ?2 AND reversed_at = ?3",
+            [customerId, triggerEventRef, ts],
+          );
+        } catch (_releaseErr) { /* drop-silent — the original failure is the signal */ }
+        throw clawErr;
+      }
+    }
+
+    return { reversed_points: earned, clawed_points: clawed };
+  }
+
   // ---- metricsForRule -------------------------------------------------
 
   async function metricsForRule(input) {
@@ -767,6 +872,7 @@ function create(opts) {
     archiveRule:       archiveRule,
     evaluateForEvent:  evaluateForEvent,
     awardForEvent:     awardForEvent,
+    reverseForEvent:   reverseForEvent,
     metricsForRule:    metricsForRule,
     applyBatch:        applyBatch,
   };