@blamejs/blamejs-shop 0.4.20 → 0.4.21

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

@@ -587,6 +587,30 @@ function create(opts) {
       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/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,
       };
     },

package/lib/store-credit.js

@@ -67,6 +67,14 @@ var C = b.constants;
 var KINDS   = ["credit", "debit", "expire"];
 var SOURCES = ["refund", "goodwill", "promotional", "manual", "loyalty_redemption"];
 
+// Reserved source_ref stamped on every expire row the scheduled sweep
+// writes. `cleanupExpired` keys its "already swept" idempotency on this
+// marker SO THAT operator-initiated `expire()` rows (which carry the
+// operator's own reason) don't masquerade as prior sweep output and
+// suppress a legitimate expiry. The marker is short + control-byte-free
+// so it passes `_sourceRef` validation when written.
+var SWEEP_SOURCE_REF = "scheduled-expiry-sweep";
+
 var MAX_SOURCE_REF_LEN = 128;
 // source_ref / reason are short correlation handles. Refuse all
 // control bytes (including CR/LF and tab) — log-injection cover has
@@ -488,20 +496,25 @@ function create(opts) {
       var now = _epochMs(input.now, "now");
       if (now == null) now = _now();
 
-      // Walk every credit row whose deadline has passed. For each,
-      // check whether a later `expire` row has already offset it —
-      // if so, skip (idempotent re-run produces no duplicates).
-      // Otherwise write an offsetting expire row capped at the
-      // wallet's current balance.
+      // Walk every credit row whose deadline has passed. For each
+      // customer, expire the still-unburned portion of their expired
+      // credit, capped at the wallet's current balance.
       //
-      // The "already offset" check is per-customer rather than
-      // per-credit-row because expire rows have no parent pointer
-      // at the schema level. We sum the customer's expired-credit
-      // amounts (kind=credit AND expires_at <= now) and the
-      // customer's burn-expire amounts (kind=expire) — the delta
-      // is the still-unburned expiring credit for that customer.
-      // When the delta is zero, the sweep is a no-op for that
-      // customer.
+      // The "already swept" check is per-customer rather than
+      // per-credit-row because expire rows have no parent pointer at
+      // the schema level. The idempotency key is the SWEEP's OWN prior
+      // output — expire rows stamped with `SWEEP_SOURCE_REF` — NOT
+      // every expire row. Counting all expire rows here was the bug:
+      // an operator-initiated `expire()` (a clawback, a goodwill burn)
+      // or any non-sweep expire would be subtracted from the expired-
+      // credit total, shrinking `pendingBurn` and leaving genuinely
+      // expired credit un-swept. Operator expires + debits already
+      // reduced the BALANCE; the `min(pendingBurn, balance)` cap below
+      // is what keeps the sweep from over-burning when the wallet was
+      // partly drained — so they must not also be netted out of the
+      // expired pool, or the reduction is double-counted. When the
+      // unburned remainder is zero, the sweep is a no-op for that
+      // customer (idempotent re-run produces no duplicates).
       var expiredByCustomer = (await query(
         "SELECT customer_id, SUM(amount_minor) AS total " +
         "FROM store_credit_ledger " +
@@ -519,16 +532,15 @@ function create(opts) {
         var burnRow = (await query(
           "SELECT COALESCE(SUM(amount_minor), 0) AS total " +
           "FROM store_credit_ledger " +
-          "WHERE customer_id = ?1 AND kind = 'expire'",
-          [customerId],
+          "WHERE customer_id = ?1 AND kind = 'expire' AND source_ref = ?2",
+          [customerId, SWEEP_SOURCE_REF],
         )).rows[0];
         var alreadyBurned = burnRow ? burnRow.total : 0;
         var pendingBurn   = expiredTotal - alreadyBurned;
 
         if (pendingBurn <= 0) {
-          // Already fully offset by prior expire rows (or by
-          // debits that drained the wallet below the expired
-          // amount — see cap below). Idempotent skip.
+          // The sweep already burned this customer's expired credit on
+          // a prior run. Idempotent skip.
           continue;
         }
 
@@ -548,7 +560,7 @@ function create(opts) {
         }
         var ts    = _resolveOccurredAt(now, latest.occurred_at);
         var after = latest.balance - toBurn;
-        var id    = await _writeRow(customerId, "expire", toBurn, null, "scheduled-expiry-sweep", null, after, null, ts);
+        var id    = await _writeRow(customerId, "expire", toBurn, null, SWEEP_SOURCE_REF, null, after, null, ts);
         processed.push({
           id:                  id,
           customer_id:         customerId,

package/lib/storefront.js

@@ -5795,6 +5795,21 @@ function _subscriptionControlState(sub) {
   return "active";
 }
 
+// Stripe statuses that wind a subscription down for good. A subscription
+// the customer cancelled at Stripe (or that lapsed unpaid) syncs to one
+// of these via the `customer.subscription.*` webhook, which writes
+// `status` but NOT the local `cancelled_at`. Without checking the synced
+// status, a Stripe-cancelled subscription whose local control-state is
+// still "active" would render live pause / skip / quantity / frequency
+// controls that mutate a row Stripe no longer bills — a customer would
+// "pause" or "change the quantity" of a subscription that's already
+// dead. So the self-manage controls are gated on the synced status: a
+// terminally-wound-down subscription shows its state, not live controls.
+var TERMINAL_SUB_STATUSES = ["canceled", "incomplete_expired", "unpaid"];
+function _subscriptionSelfManageable(sub) {
+  return TERMINAL_SUB_STATUSES.indexOf(sub.status) === -1;
+}
+
 // The 90-day reactivation grace mirrors subscriptionControls.REACTIVATE_
 // GRACE_MS. A cancelled row is reactivatable from the storefront while
 // the cancellation is inside that window; past it, the primitive refuses
@@ -5841,6 +5856,13 @@ var SUBSCRIPTION_ERR = {
   frequency:   "Choose a valid delivery frequency.",
   state:       "That change isn't available for this subscription right now.",
   grace:       "This subscription was cancelled too long ago to reactivate. Start a new one instead.",
+  // Stripe doesn't let an active subscription's billing cadence change in
+  // place; the customer cancels + re-subscribes on a plan with the
+  // cadence they want.
+  freq_locked: "Delivery frequency can't be changed on this subscription. Cancel it and start a new one on the cadence you want.",
+  // A Stripe-side quantity push failed; the local quantity was NOT
+  // changed, so the customer sees the unchanged value and can retry.
+  processor:   "We couldn't update your subscription with the payment processor. Nothing changed — please try again.",
 };
 function _subscriptionErrorCopy(code) {
   if (code == null) return null;
@@ -5853,14 +5875,23 @@ function _subscriptionErrorCopy(code) {
 // payment handle wired — the list renders read-only with a note, since
 // cancel composes Stripe. `opts.self_manage` adds the pause / resume /
 // skip / change-quantity / change-frequency / reactivate controls (wired
-// only when the subscriptionControls primitive is available). Empty state
-// points at the catalog (creation is a separate Stripe-subscription-
-// checkout surface, not built here).
+// only when the subscriptionControls primitive is available).
+// `opts.stripe_backed` is true when those controls can reach Stripe — it
+// suppresses the change-frequency form on a Stripe-backed row (the
+// billing interval is immutable at Stripe) and gates the whole control
+// block on the synced status so a Stripe-cancelled subscription shows its
+// state, not live controls. Empty state points at the catalog (creation
+// is a separate Stripe-subscription-checkout surface, not built here).
 function renderAccountSubscriptions(opts) {
   var esc = b.template.escapeHtml;
   var subs = opts.subscriptions || [];
   var canCancel = opts.can_cancel !== false;
   var selfManage = opts.self_manage === true;
+  // True when the controls can actually reach Stripe (retrieve+update
+  // wired). Only then is a row's billing cadence processor-locked and the
+  // frequency control suppressed; a local-only controls instance keeps
+  // offering it even on a Stripe-shaped row.
+  var stripeAware = opts.stripe_backed === true;
   var rowsHtml = "";
   for (var i = 0; i < subs.length; i += 1) {
     var s = subs[i];
@@ -5920,11 +5951,22 @@ function renderAccountSubscriptions(opts) {
     // cancel (a second server-rendered screen, no inline confirm()); the
     // reversible controls post directly. Quantity / frequency take input
     // validated server-side.
+    //
+    // The active + paused control sets are additionally gated on the
+    // SYNCED Stripe status: a subscription Stripe has wound down
+    // (canceled / incomplete_expired / unpaid via webhook) but whose
+    // LOCAL control-state still reads "active"/"paused" must NOT offer
+    // pause / skip / quantity / frequency / resume — those would mutate a
+    // row Stripe no longer bills. The cancelled-within-grace REACTIVATE
+    // path is intentionally NOT gated this way: a Stripe-canceled status
+    // is the normal state of a row the customer is reactivating, and
+    // reactivate is the recovery action for exactly that case.
     var manageControls = "";
+    var liveManageable = _subscriptionSelfManageable(s);
     if (selfManage) {
       var actId = esc(s.id);
       var ctrls = "";
-      if (controlState === "active") {
+      if (controlState === "active" && liveManageable) {
         ctrls +=
           "<a class=\"btn-ghost btn-ghost--sm\" href=\"/account/subscriptions/" + actId + "/pause\">Pause</a>";
         ctrls +=
@@ -5939,15 +5981,26 @@ function renderAccountSubscriptions(opts) {
             "</label>" +
             "<button type=\"submit\" class=\"btn-ghost btn-ghost--sm\">Update quantity</button>" +
           "</form>";
-        ctrls +=
-          "<form class=\"subscription-card__control subscription-card__control--freq\" method=\"post\" action=\"/account/subscriptions/" + actId + "/frequency\">" +
-            "<label class=\"form-field form-field--inline\">" +
-              "<span class=\"form-field__label\">Frequency</span>" +
-              "<select name=\"frequency\" required>" + _frequencyOptions(s.frequency || null) + "</select>" +
-            "</label>" +
-            "<button type=\"submit\" class=\"btn-ghost btn-ghost--sm\">Update frequency</button>" +
-          "</form>";
-      } else if (controlState === "paused") {
+        // The frequency control only renders for a shop-local (non-
+        // Stripe) subscription. A Stripe-backed subscription's billing
+        // cadence is fixed by its Stripe Price (interval is immutable),
+        // so there's nothing for this form to change — offering it would
+        // be a button that always errors. `stripeAware` is set only when
+        // the controls can reach Stripe; combined with the row's
+        // `stripe_subscription_id` it identifies a genuinely Stripe-
+        // backed row.
+        var stripeBacked = stripeAware && s.stripe_subscription_id != null && String(s.stripe_subscription_id).length > 0;
+        if (!stripeBacked) {
+          ctrls +=
+            "<form class=\"subscription-card__control subscription-card__control--freq\" method=\"post\" action=\"/account/subscriptions/" + actId + "/frequency\">" +
+              "<label class=\"form-field form-field--inline\">" +
+                "<span class=\"form-field__label\">Frequency</span>" +
+                "<select name=\"frequency\" required>" + _frequencyOptions(s.frequency || null) + "</select>" +
+              "</label>" +
+              "<button type=\"submit\" class=\"btn-ghost btn-ghost--sm\">Update frequency</button>" +
+            "</form>";
+        }
+      } else if (controlState === "paused" && liveManageable) {
         ctrls +=
           "<form class=\"subscription-card__control\" method=\"post\" action=\"/account/subscriptions/" + actId + "/resume\">" +
             "<button type=\"submit\" class=\"btn-primary btn-primary--sm\">Resume</button>" +
@@ -17487,6 +17540,11 @@ function mount(router, deps) {
           subscriptions: rows,
           can_cancel:    subsCanCancel,
           self_manage:   !!subControls,
+          // The frequency control is suppressed for Stripe-backed rows
+          // ONLY when the controls can actually reach Stripe (a payment
+          // handle with retrieve + update was wired) — otherwise the
+          // controls are local-only and the cadence is still editable.
+          stripe_backed: !!(subControls && subControls.stripeBacked),
           notice:        notice,
           error:         _subscriptionErrorCopy(errKind),
           shop_name:     shopName,
@@ -17513,6 +17571,7 @@ function mount(router, deps) {
           if (e && e.code === "SUBSCRIPTION_REACTIVATE_GRACE_EXPIRED") return "grace";
           if (e && e.code === "SUBSCRIPTION_STATE_REFUSED")            return "state";
           if (e && e.code === "SUBSCRIPTION_NOT_FOUND")                return "state";
+          if (e && e.code === "SUBSCRIPTION_FREQUENCY_IMMUTABLE")      return "freq_locked";
           if (e instanceof TypeError)                                   return "state";
           return null;
         }
@@ -17522,13 +17581,32 @@ function mount(router, deps) {
           return res.end ? res.end() : res.send("");
         }
 
+        // Resolve an owned subscription AND refuse the self-manage action
+        // when the synced Stripe status is terminal (canceled /
+        // incomplete_expired / unpaid). The display gates the controls on
+        // the same status, but the backend validates independently — a
+        // forged POST to a wound-down subscription's pause / skip /
+        // quantity / frequency endpoint bounces to the list with the
+        // generic state error rather than mutating a row Stripe no longer
+        // bills. Returns null (after redirecting) when ownership fails or
+        // the status is terminal; the caller bails on null.
+        async function _ownedManageableSubscription(req, res, auth) {
+          var sub = await _ownedSubscription(req, res, auth);
+          if (!sub) return null;
+          if (!_subscriptionSelfManageable(sub)) {
+            _redirect(res, "?error=state");
+            return null;
+          }
+          return sub;
+        }
+
         // Pause is confirm-gated (GET → POST), mirroring cancel — a
         // deliberate, reversible hold. The confirm page only renders for a
         // currently-active subscription; a paused/cancelled row bounces
         // back to the list.
         router.get("/account/subscriptions/:id/pause", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           if (_subscriptionControlState(sub) !== "active") return _redirect(res, "");
           if (sub.plan_id != null) {
             try { sub.plan = await subscriptions.plans.get(sub.plan_id); }
@@ -17544,7 +17622,7 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/pause", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           try {
             await subControls.pause({ subscription_id: sub.id, reason: "customer self-service pause", actor: SELF_ACTOR });
           } catch (e) {
@@ -17556,7 +17634,7 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/resume", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           try {
             await subControls.resume({ subscription_id: sub.id, reason: "customer self-service resume", actor: SELF_ACTOR });
           } catch (e) {
@@ -17568,7 +17646,7 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/skip", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           try {
             await subControls.skipNext({ subscription_id: sub.id, count: 1, reason: "customer self-service skip", actor: SELF_ACTOR });
           } catch (e) {
@@ -17580,7 +17658,7 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/quantity", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           // Backend validates: a non-positive / non-integer / missing value
           // is a client error → bounce with the quantity error code rather
           // than handing garbage to the primitive (which would throw a
@@ -17591,6 +17669,14 @@ function mount(router, deps) {
             await subControls.changeQuantity({ subscription_id: sub.id, new_quantity: qty, reason: "customer self-service quantity change", actor: SELF_ACTOR });
           } catch (e) {
             if (e instanceof TypeError) return _redirect(res, "?error=quantity");
+            // A Stripe-side push failure (no billable item, or the
+            // processor rejected/timed out the update) left the local
+            // quantity unchanged. Surface a clean "nothing changed, retry"
+            // notice instead of 500-ing — the customer's row still shows
+            // the old quantity, which is the truth.
+            if (e && (e.code === "SUBSCRIPTION_STRIPE_NO_ITEM" || e.code === "SUBSCRIPTION_STRIPE_PUSH_FAILED")) {
+              return _redirect(res, "?error=processor");
+            }
             var code = _controlError(e); if (code == null) throw e;
             return _redirect(res, "?error=" + code);
           }
@@ -17599,7 +17685,7 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/frequency", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
-          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          var sub = await _ownedManageableSubscription(req, res, auth); if (!sub) return;
           // Backend validates: reject anything outside the allowed cadence
           // enum before composing the primitive.
           var freq = String((req.body || {}).frequency || "");
@@ -17616,6 +17702,11 @@ function mount(router, deps) {
 
         router.post("/account/subscriptions/:id/reactivate", async function (req, res) {
           var auth = _subsAuth(req, res); if (!auth) return;
+          // Reactivate is the recovery path for a cancelled subscription,
+          // so it is NOT gated on the terminal-status guard (a Stripe-
+          // canceled status is the normal state of a row being
+          // reactivated). The primitive enforces the cancelled-state +
+          // grace-window FSM.
           var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
           try {
             await subControls.reactivate({ subscription_id: sub.id, reason: "customer self-service reactivate", actor: SELF_ACTOR });