@blamejs/blamejs-shop 0.4.19 → 0.4.21

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,
   };

package/lib/loyalty.js

@@ -228,6 +228,25 @@ function create(opts) {
     );
   }
 
+  // SQL fragment that derives the tier from a lifetime-points
+  // expression evaluated INSIDE the UPDATE statement, so balance,
+  // lifetime, and tier all move in one atomic write off the row's
+  // live value rather than a stale snapshot. `lifetimeExpr` is the
+  // post-mutation lifetime SQL (e.g. `lifetime_points + ?2`). The
+  // operator-tunable thresholds bind as literals — they're validated
+  // non-negative integers at factory time, never operator input here,
+  // so inlining them keeps the CASE a single self-contained
+  // expression without widening the bound-parameter list per call.
+  // Mirrors computeTier's highest-threshold-first ladder so the SQL
+  // and JS classifications never diverge.
+  function _tierCase(lifetimeExpr) {
+    return "CASE" +
+      " WHEN (" + lifetimeExpr + ") >= " + thresholds.platinum + " THEN 'platinum'" +
+      " WHEN (" + lifetimeExpr + ") >= " + thresholds.gold     + " THEN 'gold'" +
+      " WHEN (" + lifetimeExpr + ") >= " + thresholds.silver   + " THEN 'silver'" +
+      " ELSE 'bronze' END";
+  }
+
   return {
     TIERS:                  TIERS.slice(),
     TX_TYPES:               TX_TYPES.slice(),
@@ -260,24 +279,27 @@ function create(opts) {
 
       var ts = _now();
       await _ensureAccountRow(customerId, ts);
+      // Snapshot the tier ONLY to report `tier_changed` — the balance /
+      // lifetime / tier mutation itself is relative-atomic below, so a
+      // concurrent earn can't clobber this credit (the lost-update the
+      // absolute write suffered). The tier is recomputed in-SQL off the
+      // row's live `lifetime_points`, not this stale snapshot.
       var before = await _readAccount(customerId);
-      var newLifetime = before.lifetime_points + points;
-      var newBalance  = before.balance_points + points;
-      var newTier     = computeTier(newLifetime);
-      var tierChanged = newTier !== before.tier;
-
       await query(
-        "UPDATE loyalty_accounts SET balance_points = ?1, lifetime_points = ?2, " +
-        "tier = ?3, updated_at = ?4 WHERE customer_id = ?5",
-        [newBalance, newLifetime, newTier, ts, customerId],
+        "UPDATE loyalty_accounts SET balance_points = balance_points + ?1, " +
+        "lifetime_points = lifetime_points + ?1, " +
+        "tier = " + _tierCase("lifetime_points + ?1") + ", " +
+        "updated_at = ?2 WHERE customer_id = ?3",
+        [points, ts, customerId],
       );
       await _writeTx(customerId, "earn", points, source, orderId, notes, ts);
 
+      var after = await _readAccount(customerId);
       return {
-        balance:      newBalance,
-        lifetime:     newLifetime,
-        tier:         newTier,
-        tier_changed: tierChanged,
+        balance:      after.balance_points,
+        lifetime:     after.lifetime_points,
+        tier:         after.tier,
+        tier_changed: after.tier !== before.tier,
       };
     },
 
@@ -335,34 +357,45 @@ function create(opts) {
 
       var ts = _now();
       await _ensureAccountRow(customerId, ts);
+      // Snapshot the pre-adjust tier only to report `tier_changed`. The
+      // mutation is relative-atomic with an underflow guard at the SQL
+      // tier so two concurrent adjustments can't lose an update or drive
+      // the balance negative past each other.
       var before = await _readAccount(customerId);
 
-      var newBalance = before.balance_points + delta;
-      if (newBalance < 0) {
-        var ins = new Error("loyalty.adjust: adjustment would underflow balance");
-        ins.code = "LOYALTY_INSUFFICIENT_BALANCE";
-        throw ins;
-      }
       // Positive adjustments also increment lifetime — operators
       // crediting a customer for a service recovery should see that
       // credit count toward tier. Negative adjustments do NOT
       // decrement lifetime (otherwise a clawback could downgrade tier
-      // retroactively, which is a customer-facing surprise).
-      var newLifetime = delta > 0 ? before.lifetime_points + delta : before.lifetime_points;
-      var newTier     = computeTier(newLifetime);
-
-      await query(
-        "UPDATE loyalty_accounts SET balance_points = ?1, lifetime_points = ?2, " +
-        "tier = ?3, updated_at = ?4 WHERE customer_id = ?5",
-        [newBalance, newLifetime, newTier, ts, customerId],
+      // retroactively, which is a customer-facing surprise). The
+      // lifetime delta is therefore the positive part of `delta`.
+      var lifetimeDelta = delta > 0 ? delta : 0;
+      // Conditional UPDATE: the row mutates ONLY when the post-adjust
+      // balance stays non-negative, checked against the row's LIVE
+      // balance (not the stale snapshot). A racing concurrent adjust
+      // that already spent the balance makes this match zero rows, so
+      // we surface the same insufficient-balance refusal rather than
+      // writing a ledger row that diverges from the account.
+      var upd = await query(
+        "UPDATE loyalty_accounts SET balance_points = balance_points + ?1, " +
+        "lifetime_points = lifetime_points + ?2, " +
+        "tier = " + _tierCase("lifetime_points + ?2") + ", " +
+        "updated_at = ?3 WHERE customer_id = ?4 AND balance_points + ?1 >= 0",
+        [delta, lifetimeDelta, ts, customerId],
       );
+      if (Number(upd.rowCount || 0) === 0) {
+        var ins = new Error("loyalty.adjust: adjustment would underflow balance");
+        ins.code = "LOYALTY_INSUFFICIENT_BALANCE";
+        throw ins;
+      }
       await _writeTx(customerId, "adjust", delta, source, null, notes, ts);
 
+      var after = await _readAccount(customerId);
       return {
-        balance:      newBalance,
-        lifetime:     newLifetime,
-        tier:         newTier,
-        tier_changed: newTier !== before.tier,
+        balance:      after.balance_points,
+        lifetime:     after.lifetime_points,
+        tier:         after.tier,
+        tier_changed: after.tier !== before.tier,
       };
     },
 

package/lib/order.js

@@ -58,6 +58,25 @@ var ORDER_TRANSITIONS = Object.freeze([
   { from: "delivered",  to: "refunded",   on: "refund",            label: "Refund" },
 ]);
 
+// Pickup (BOPIS) edges. An in-store collection has no carrier ship leg:
+// the goods sit on the hold shelf and the customer walks in. So a pickup
+// order goes straight from `paid` (or `fulfilling`, if the picker started
+// staging) to `delivered` on a single `mark_picked_up` event — driving it
+// through mark_shipped would record a carrier handoff that never happened.
+// These edges are kept OUT of ORDER_TRANSITIONS (and therefore out of
+// transitionsFrom) so the operator order-detail page doesn't sprout a
+// "mark picked up" button on every paid order — the click-and-collect
+// primitive fires the event when the front-counter operator captures the
+// pickup. They ARE merged into the FSM definition below so the transition
+// is legal: previously markPickedUp tried `mark_delivered` from `paid`,
+// which the FSM refused (delivered is only reachable from shipped) and the
+// caller swallowed — leaving the pickup schedule `picked_up` while the
+// parent order stayed stuck at paid/fulfilling.
+var PICKUP_TRANSITIONS = Object.freeze([
+  { from: "paid",       to: "delivered",  on: "mark_picked_up" },
+  { from: "fulfilling", to: "delivered",  on: "mark_picked_up" },
+]);
+
 function _getOrderFsm() {
   if (_orderFsm) return _orderFsm;
   // b.fsm emits audit events under the 'fsm' namespace —
@@ -76,7 +95,7 @@ function _getOrderFsm() {
       refunded:   {},
       cancelled:  {},
     },
-    transitions: ORDER_TRANSITIONS.map(function (t) {
+    transitions: ORDER_TRANSITIONS.concat(PICKUP_TRANSITIONS).map(function (t) {
       return { from: t.from, to: t.to, on: t.on };
     }),
   });
@@ -217,6 +236,28 @@ function create(opts) {
   // settlement failures still surface to the audit sink (b.audit.safeEmit
   // below), just not the durable error feed.
   var errorLog = opts.errorLog || null;
+  // Optional gift-card handle — when present, the order FSM credits a
+  // gift-card spend back when the order dies without completing. A checkout
+  // that partially covers payment with a gift card debits the card's balance
+  // at confirm; if the order is then cancelled (the stale-pending reaper, an
+  // explicit cancel) or refunded (a payment-failed / refund webhook), that
+  // debit must return to the card or the customer's balance is silently
+  // burned. This mirrors the inventory-hold release: it's transition-driven
+  // on the same cancel / refund edges, runs synchronously before the
+  // fire-and-forget fan-outs, and is idempotent (reverseRedemption claims
+  // each redemption with an unreversed predicate) so a re-delivered webhook
+  // can't double-credit. Opt-in like the other handles; absent it, an
+  // unwired deploy (or a test with no gift cards) runs unchanged.
+  var giftCards = opts.giftCards || null;
+  if (giftCards && typeof giftCards.reverseRedemption !== "function") {
+    throw new TypeError("order.create: opts.giftCards must expose a reverseRedemption(order_id) method");
+  }
+  // Optional gift-card ledger handle — when present alongside giftCards, a
+  // reversal also writes a refund_to_giftcard credit so the append-only
+  // ledger history records the money returning to the card (the card row's
+  // balance is authoritative; the ledger is the audit trail surfaced in the
+  // admin console).
+  var giftCardLedger = opts.giftCardLedger || 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
@@ -273,6 +314,60 @@ function create(opts) {
     }
   }
 
+  // Credit back any gift-card spend on an order that died without
+  // completing — the cancel / refund edge releasing the customer's money,
+  // mirroring how _settleSku releases an inventory hold. reverseRedemption
+  // is idempotent (each redemption claimed with an unreversed predicate), so
+  // a re-delivered webhook or the reaper racing the cancel can't double-
+  // credit. For each restored redemption a refund_to_giftcard ledger credit
+  // is written when the ledger is wired so the audit trail records the money
+  // returning.
+  //
+  // drop-silent-with-capture — same discipline as _settleSku: the cancel /
+  // refund has already persisted and the webhook driving it MUST return 2xx,
+  // so a reversal failure is caught, NOT re-thrown, and surfaced loudly (an
+  // `order.giftcard.reversal.error` audit event plus, when the error-log
+  // handle is wired, a durable /admin/errors row) for manual reconciliation.
+  async function _settleGiftCards(orderId) {
+    if (!giftCards) return;
+    try {
+      var reversed = await giftCards.reverseRedemption(orderId);
+      if (giftCardLedger && typeof giftCardLedger.credit === "function") {
+        for (var i = 0; i < reversed.length; i += 1) {
+          var rev = reversed[i];
+          try {
+            // allow:money-binding-currency-without-catalog-check — this is a REVERSAL credit of an existing redemption: it replays the exact amount already debited from an already-issued card (whose currency was ISO-4217-validated at giftcards.issue time). No currency is supplied or chosen here — the ledger credit carries no currency field; it inherits the card's. There is no new currency surface to catalog-check.
+            await giftCardLedger.credit({
+              gift_card_id: rev.gift_card_id,
+              amount_minor: rev.amount_minor,
+              source:       "refund_to_giftcard",
+              source_ref:   orderId,
+            });
+          } catch (_ledgerErr) { /* drop-silent — the card-row balance restore above is authoritative; the ledger credit is the audit trail */ }
+        }
+      }
+    } catch (e) {
+      var message = "order.giftcard-reversal failed — order=" + orderId + ": " + (e && e.message || e);
+      try {
+        b.audit.safeEmit({
+          action:   "order.giftcard.reversal.error",
+          outcome:  "failure",
+          metadata: { order_id: orderId, message: (e && e.message) || String(e) },
+        });
+      } catch (_auditErr) { /* drop-silent — the capture below is the durable record */ }
+      if (errorLog && typeof errorLog.captureServerError === "function") {
+        try {
+          await errorLog.captureServerError({
+            route:   "/order/" + orderId + "/giftcard-reversal",
+            method:  "POST",
+            status:  500,
+            message: message,
+          });
+        } catch (_logErr) { /* drop-silent — never let the error-feed write mask the original failure */ }
+      }
+    }
+  }
+
   return {
     TERMINAL_STATES: TERMINAL_STATES,
 
@@ -477,6 +572,45 @@ function create(opts) {
           }
         }
       }
+      // Gift-card settlement — SYNCHRONOUS, alongside the inventory release.
+      // An order that reaches a terminal state WITHOUT completing the sale
+      // (cancelled — pending-abandon or post-paid; refunded — payment failed
+      // or a refund issued) must return any gift-card spend to the card.
+      // Unlike inventory (where a refund deliberately doesn't auto-restock a
+      // physical good), the gift-card credit is the customer's own money, so
+      // it's released on every death edge. reverseRedemption is idempotent,
+      // so a re-delivered webhook or the reaper racing a cancel credits back
+      // exactly once. Drop-silent-with-capture (see _settleGiftCards): the
+      // transition has already persisted and the webhook must return 2xx, so
+      // a reversal failure surfaces loudly for reconciliation rather than
+      // 500ing the request.
+      if (result.to === "cancelled" || result.to === "refunded") {
+        await _settleGiftCards(orderId);
+      }
+      // Loyalty earn-reversal fan-out — fire-and-forget, same discipline
+      // as the earn-on-purchase block below. On a cancel / refund edge for
+      // an order carrying a customer_id, the points awarded when the order
+      // went paid are clawed back off the balance (floored at zero), or a
+      // buy-then-refund mints free rewards. reverseForEvent claims the
+      // earn-log rows with an unreversed predicate, so it is idempotent (a
+      // re-delivered cancel webhook or the reaper racing a refund reverses
+      // exactly once) and a natural no-op for an order that never earned
+      // (a guest order, or one that never reached paid — the never-awarded
+      // earn-log is empty). 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.reverseForEvent === "function"
+          && (result.to === "cancelled" || result.to === "refunded")
+          && refreshed && refreshed.customer_id) {
+        var _revCustomer = refreshed.customer_id;
+        var _revOrderId  = refreshed.id;
+        Promise.resolve().then(function () {
+          return loyaltyEarnRules.reverseForEvent({
+            customer_id:       _revCustomer,
+            trigger_event_ref: "order:" + _revOrderId,
+          });
+        }).catch(function () { /* drop-silent — loyalty ledger holds its own audit trail */ });
+      }
       // Fan-out to merchant webhook subscribers is fire-and-forget. The
       // transition has already persisted; the request must not wait on
       // outbound HTTP, or a slow / unreachable endpoint would block the

package/lib/returns.js

@@ -376,21 +376,61 @@ function create(opts) {
       var refundedAt    = _epochOrNull(input.refunded_at, "refunded_at");
       var operatorNotes = _boundedString(input.operator_notes, "operator_notes", MAX_NOTE_LEN);
 
-      var current = await this._currentStatus(rmaId);
-      _assertTransition(current, "refund");
-
       var ts = _now();
       var rfAt = refundedAt == null ? ts : refundedAt;
-      await query(
+      // Atomic claim: the `AND status = 'received'` predicate is the
+      // serialization point. Two concurrent refund POSTs (an operator
+      // double-click, two operators on the same RMA) both read 'received'
+      // up the stack, but on D1 a single UPDATE is atomic — exactly one
+      // matches the row and writes 'refunded'; the loser matches zero rows
+      // and is refused. Without this the read-then-write let both pass and
+      // both moved the RMA to refunded (and, on the provider-backed path,
+      // both issued a refund). A zero-row result distinguishes "already
+      // refunded / not received" — surfaced as RMA_TRANSITION_REFUSED so
+      // the request layer maps it to 409, the same shape the prior
+      // _assertTransition refusal produced.
+      var upd = await query(
         "UPDATE return_authorizations SET status = 'refunded', " +
         "refunded_at = ?1, " +
         "operator_notes = CASE WHEN ?2 = '' THEN operator_notes ELSE ?2 END, " +
-        "updated_at = ?3 WHERE id = ?4",
+        "updated_at = ?3 WHERE id = ?4 AND status = 'received'",
         [rfAt, operatorNotes, ts, rmaId],
       );
+      if (Number(upd.rowCount || 0) === 0) {
+        // Either the RMA doesn't exist or it isn't in 'received'. Read the
+        // current status to surface the right typed refusal (RMA_NOT_FOUND
+        // vs RMA_TRANSITION_REFUSED) so the caller's mapping is unchanged.
+        var current = await this._currentStatus(rmaId);
+        _assertTransition(current, "refund");
+        // _assertTransition throws for any non-'received' state; reaching
+        // here means the RMA was 'received' a moment ago but a concurrent
+        // claim won the row first. Refuse with the transition-refused shape.
+        var raced = new Error("returns: refund already claimed for rma " + rmaId);
+        raced.code = "RMA_TRANSITION_REFUSED";
+        throw raced;
+      }
       return await this.get(rmaId);
     },
 
+    // Revert a refund claim back to 'received'. The provider-backed refund
+    // flow claims the RMA (refund() above) BEFORE moving money so a
+    // concurrent racer is locked out; if the provider call then fails, the
+    // caller releases the claim so a retry can run. Atomic + self-targeting:
+    // the `AND status = 'refunded'` predicate makes a double-release (or a
+    // release of an RMA a webhook already advanced) a no-op, never an
+    // underflow. Returns true when the claim was released, false when there
+    // was nothing to release.
+    releaseRefundClaim: async function (rmaId) {
+      _uuid(rmaId, "rma id");
+      var ts = _now();
+      var upd = await query(
+        "UPDATE return_authorizations SET status = 'received', refunded_at = NULL, " +
+        "updated_at = ?1 WHERE id = ?2 AND status = 'refunded'",
+        [ts, rmaId],
+      );
+      return Number(upd.rowCount || 0) === 1;
+    },
+
     reject: async function (rmaId, input) {
       _uuid(rmaId, "rma id");
       if (!input || typeof input !== "object") {

package/lib/search-ranking.js

@@ -700,6 +700,48 @@ function create(opts) {
       if (input.session_id != null) {
         sessionHash = _hashSession(_sessionIdRaw(input.session_id, "searchRanking.recordSearchEvent"));
       }
+
+      // Server-side click attribution. A `click` carries a `?sq=<query>`
+      // marker from the result link, but the marker is attacker-
+      // controllable: anyone can hit a PDP with `?from=search&sq=dress`
+      // and inflate the click count for "dress" without ever having
+      // seen — let alone clicked through — a real result list. That let
+      // CTR be spoofed and pushed past 100% (more clicks than the
+      // impressions that were ever rendered). When the click carries a
+      // session, we only record it if THAT session already logged an
+      // `impression` for the same (weights_slug, query): the click must
+      // descend from a search the same session actually ran. An
+      // unattributed click (no matching impression for the session) is
+      // dropped — it never reaches the event log, so the rollup can't
+      // count it. Clicks without a session (a session-less worker
+      // deployment, or a click whose session cookie was lost) can't be
+      // attribution-checked, so they record as before; the storefront
+      // attaches the session whenever one exists, so the spoof path is
+      // closed in the deployed configuration.
+      if (eventType === "click" && sessionHash != null) {
+        var imp = await query(
+          "SELECT 1 FROM search_events " +
+          "WHERE weights_slug = ?1 AND query = ?2 AND session_id_hash = ?3 " +
+          "AND event_type = 'impression' LIMIT 1",
+          [weightsSlug, normalizedQuery, sessionHash]
+        );
+        if (!imp.rows.length) {
+          // No impression for this session + query under this weight
+          // set — the click can't be a genuine result-list click-
+          // through. Refuse to record it (drop, don't throw — the hot
+          // path swallows the result).
+          return {
+            query:        normalizedQuery,
+            product_id:   productId,
+            weights_slug: weightsSlug,
+            event_type:   eventType,
+            position:     position,
+            recorded:     false,
+            reason:       "click-without-matching-impression",
+          };
+        }
+      }
+
       var ts = _now();
       await query(
         "INSERT INTO search_events " +
@@ -714,6 +756,7 @@ function create(opts) {
         event_type:   eventType,
         position:     position,
         occurred_at:  ts,
+        recorded:     true,
       };
     },
 
@@ -757,6 +800,19 @@ function create(opts) {
         else if (row.event_type === "click")      clicks      = c;
         else if (row.event_type === "purchase")   purchases   = c;
       }
+      // A single rendered result list (one impression) can legitimately
+      // yield more than one click — the shopper opens a product, returns
+      // to the same list, opens another. So clicks/impressions can
+      // exceed 1.0 even on honest data; an unbounded ratio reads as a
+      // nonsensical ">100% CTR" on the operator dashboard. Bound the
+      // reported CTR at 1.0 so the metric stays interpretable (the raw
+      // counts remain available for an operator who wants the unbounded
+      // figure). conversion_rate is bounded the same way — purchases are
+      // gated by clicks which are gated by impressions, but the bound
+      // keeps the displayed rate honest under the same multi-click
+      // reality.
+      var rawCtr = impressions > 0 ? clicks    / impressions : null;
+      var rawConv = impressions > 0 ? purchases / impressions : null;
       return {
         weights_slug:      weightsSlug,
         from:              from,
@@ -764,8 +820,8 @@ function create(opts) {
         impressions:       impressions,
         clicks:            clicks,
         purchases:         purchases,
-        ctr:               impressions > 0 ? clicks    / impressions : null,
-        conversion_rate:   impressions > 0 ? purchases / impressions : null,
+        ctr:               rawCtr == null  ? null : Math.min(1, rawCtr),
+        conversion_rate:   rawConv == null ? null : Math.min(1, rawConv),
         click_to_purchase: clicks > 0      ? purchases / clicks      : null,
       };
     },