@blamejs/blamejs-shop 0.4.19 → 0.4.21

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/giftcards.js

@@ -346,6 +346,66 @@ function create(opts) {
       };
     },
 
+    // Credit a card's spend back when the order that redeemed it never
+    // completed (abandoned / cancelled / refunded). `redeem` debited the
+    // card row's balance at checkout; if the order dies, that money must
+    // return to the card or the customer's balance is silently gone.
+    //
+    // Keyed on the ORDER id — the order FSM drives this on its cancel /
+    // refund edges (the same transitions that release inventory holds), so
+    // reversal is transition-driven, not a separate operator action. Every
+    // unreversed redemption against the order is restored.
+    //
+    // Idempotent + concurrency-safe: each redemption is claimed with
+    // `WHERE id = ? AND reversed_at IS NULL` and the rowCount checked, so a
+    // double-fire (the stale-order reaper racing a payment-failed webhook,
+    // or a re-delivered cancel) credits the balance back exactly once. The
+    // balance restore is itself bounded by the card's issued_minor CHECK, so
+    // it can never push the card above its original face value. A card that
+    // had drained to `redeemed` is reactivated since it now carries balance
+    // again. Returns the list of reversed redemptions (empty when there was
+    // nothing to reverse — an order that used no gift card, or one already
+    // fully reversed).
+    reverseRedemption: async function (orderId) {
+      _uuid(orderId, "order_id");
+      var rows = (await query(
+        "SELECT id, giftcard_id, amount_minor FROM giftcard_redemptions " +
+        "WHERE order_id = ?1 AND reversed_at IS NULL",
+        [orderId],
+      )).rows;
+      var reversed = [];
+      for (var i = 0; i < rows.length; i += 1) {
+        var red = rows[i];
+        var ts = _now();
+        // Claim the redemption first — the unreversed predicate is the
+        // serialization point so two concurrent reversals can't both credit.
+        var claim = await query(
+          "UPDATE giftcard_redemptions SET reversed_at = ?1 WHERE id = ?2 AND reversed_at IS NULL",
+          [ts, red.id],
+        );
+        if (Number(claim.rowCount || 0) === 0) continue;   // lost the claim
+        // Restore the spendable balance on the card row. Capped at the card's
+        // issued_minor by the schema CHECK; the amount restored is exactly
+        // what this redemption debited, so it can't exceed the face value.
+        // Reactivate a card that had drained to `redeemed` — it carries
+        // balance again. A `voided`/`expired` card stays in its terminal
+        // status (the balance is restored on the row for reconciliation, but
+        // a voided/expired card isn't spendable regardless).
+        await query(
+          "UPDATE giftcards SET balance_minor = balance_minor + ?1, " +
+          "status = CASE WHEN status = 'redeemed' THEN 'active' ELSE status END, " +
+          "updated_at = ?2 WHERE id = ?3",
+          [red.amount_minor, ts, red.giftcard_id],
+        );
+        reversed.push({
+          redemption_id: red.id,
+          gift_card_id:  red.giftcard_id,
+          amount_minor:  red.amount_minor,
+        });
+      }
+      return reversed;
+    },
+
     "void": async function (id, opts2) {
       opts2 = opts2 || {};
       _uuid(id, "giftcard id");