@blamejs/blamejs-shop 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.5.x
 
+- v0.5.5 (2026-06-27) — **Customers can change their subscription plan — proration-aware upgrades and downgrades from the account portal.** Adds a self-serve plan-change surface to the customer subscription portal. From /account/subscriptions a customer can switch an active subscription to any other plan in the same currency: the page previews the proration for each candidate plan and offers two timings. An immediate change applies now and prorates the rest of the current period — an upgrade is charged the prorated difference (recorded on the subscription invoice ledger), and a downgrade is issued the unused remainder as store credit. A next-billing-cycle change is queued and applied automatically when the period rolls over, with the new plan starting clean and no proration. The transition is exactly-once: the immediate path claims the plan switch atomically before recording the charge or credit, and the scheduled path claims each due change with a single guarded update, so a retry or an overlapping scheduler run cannot double-charge or double-credit. A downgrade that owes a credit is never applied without paying it — if the credit write fails the change rolls back and retries. The surface mounts automatically when subscriptions and store credit are composed (the default for a configured storefront); the scheduler runs on the existing cron, and the tables it uses already shipped, so there are no schema changes and no operator action is required. **Added:** *Self-serve subscription plan changes with proration* — Customers can change the plan on an active subscription from /account/subscriptions/:id/change. The page lists every plan in the subscription's currency (excluding the current and archived plans) with a proration preview, and offers an immediate switch or a switch at the next billing date. An immediate upgrade charges the prorated difference for the rest of the period and records it on the subscription invoice ledger; an immediate downgrade issues the unused remainder of the outgoing plan as store credit. A still-pending change is shown on the subscription with a one-click cancel. Cross-currency, same-plan, and archived-plan requests are refused server-side, and the surface enforces subscription ownership before any read or write. · *Scheduler applies next-billing-cycle changes automatically* — A change queued for the next billing cycle is applied without operator involvement: a minute-cadence tick flips every due change to its new plan, records the proration, and issues any owed credit. Each due change is claimed with a single guarded update so an overlapping or retried run cannot apply it twice, and a change that owes a credit is left queued rather than applied if no credit can be issued — the credit is never dropped. The scheduler is inert on a deploy without subscriptions or store credit composed. **Changed:** *Dunning step failures are logged with their cause* — When a dunning step (reminder send, retry-charge record, pause, or cancel) fails, the schedule still advances and the step is recorded as failed — but the underlying error is now written to the server log instead of being discarded, so an operator can see why a step failed rather than only that it did.
+
 - v0.5.4 (2026-06-27) — **Vendored framework refreshed to 0.15.38 — caller-supplied regexes are screened for ReDoS before they run on request data.** Updates the vendored blamejs framework to 0.15.38. The upstream release closes two ReDoS exposures and strengthens the framework's regex guard: a feature-flag targeting condition (`op: regex`) and an MCP tool's input-schema `pattern` each compiled a caller-supplied regex and matched it against request-controlled input behind only a length cap — which does not bound catastrophic backtracking, so a six-character pattern like `(a+)+$` could pin a CPU. Both now pass through `b.guardRegex` (strict) before compilation, and the nested-quantifier detector was hardened to also catch wrapped forms (`((a)+)+`, `(([a-z]+)*)*`) that previously slipped past — which strengthens every guardRegex caller. This storefront exposes neither MCP tools nor operator-authored regex flag rules on its request path, and its own patterns are static and ReDoS-clean, so there is no runtime or behavior change for it; the hardened framework rides along and no operator action is required. **Changed:** *Vendored framework refreshed to 0.15.38 (caller-supplied regexes screened for ReDoS)* — Refreshes the vendored blamejs framework to 0.15.38. The upstream fix screens an operator-supplied feature-flag targeting regex and an MCP tool input-schema `pattern` through `b.guardRegex` (strict) before they are compiled and matched against request input, so a catastrophic-backtracking shape is refused at validation time instead of pinning a CPU; the nested-quantifier detector also now catches wrapped forms at any group depth, strengthening every guardRegex caller. The shipped storefront does not expose those caller-supplied-regex surfaces and its own patterns are static, so its runtime, public API, and wire format are unchanged; the hardened framework simply rides along.
 
 - v0.5.3 (2026-06-27) — **Vendored framework refreshed to 0.15.37 — non-finite numeric options can no longer silently disable a security check.** Updates the vendored blamejs framework to 0.15.37. The upstream release closes a class of fail-open configuration bugs: several numeric options validated a value only as `typeof === number && >= 0`, which accepts `Infinity`. Where the value is a clock-skew tolerance or a resource cap, an `Infinity` (or `NaN`) silently turned off the very protection it tunes — an `Infinity` CWT / OCSP-staple / ARC clock-skew made the expiry and freshness comparisons unsatisfiable (so an expired token, a replayed pre-revocation OCSP `good` response, or an expired ARC seal would be accepted), and an `Infinity` WebSocket message/frame cap, inbox/flag-cache size cap, or audit-chain fan-out cap disabled the bound. These options now route through the framework's finite-bounds validator, refusing a non-finite value at the entry point (or falling back to the safe default), while options where unbounded is deliberate (reconnect-indefinitely, retain-indefinitely) still accept it. This storefront configures these options with finite values, so there is no runtime or behavior change for it; the hardened framework rides along and no operator action is required. **Changed:** *Vendored framework refreshed to 0.15.37 (non-finite option values rejected)* — Refreshes the vendored blamejs framework to 0.15.37. The upstream fix makes a clock-skew tolerance or resource cap of `Infinity` / `NaN` a rejected value rather than one that silently disables the check it configures — covering the CWT / OCSP-staple / ARC time checks, the WebSocket-client inbound size and handshake caps, and the inbox / flag-cache / audit-chain size and count caps, with deliberately-unbounded options (reconnect/retain indefinitely) unaffected. The shipped storefront passes finite values to these options, so its runtime, public API, and wire format are unchanged; the hardened framework simply rides along.

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.5.4",
+  "version": "0.5.5",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-imfe0otYErcB8rr2h6KLSGTtStirysptpXETSPY4zLv3bZoIT75Lo1dOvkOav+xL",

package/lib/dunning.js

@@ -108,6 +108,11 @@ var b = require("./vendor/blamejs");
 // Framework constants (C.TIME duration helpers). Safe at module-eval —
 // the index entry point exposes `framework` before the require cascade.
 var C = b.constants;
+// Observability sink for best-effort step failures: a dunning step that
+// throws still returns the "failed" status so the schedule advances, but
+// the CAUSE is logged here rather than discarded — a swallowed exception
+// is a bug deferred to a later patch, not a clean degrade.
+var _log = b.log.create({});
 
 // ---- constants ----------------------------------------------------------
 
@@ -322,7 +327,12 @@ function create(opts) {
           });
         }
         return "ok";
-      } catch (_e) {
+      } catch (e) {
+        _log.error("dunning step failed", {
+          action:     action,
+          invoice_id: enrollment.invoice_id,
+          err:        (e && e.message) || String(e),
+        });
         return "failed";
       }
     }
@@ -342,7 +352,12 @@ function create(opts) {
           failure_code:   "dunning_retry",
         });
         return "ok";
-      } catch (_e) {
+      } catch (e) {
+        _log.error("dunning step failed", {
+          action:     action,
+          invoice_id: enrollment.invoice_id,
+          err:        (e && e.message) || String(e),
+        });
         return "failed";
       }
     }
@@ -362,7 +377,12 @@ function create(opts) {
           reason:          "dunning: pause_subscription step",
         });
         return "ok";
-      } catch (_e) {
+      } catch (e) {
+        _log.error("dunning step failed", {
+          action:     action,
+          invoice_id: enrollment.invoice_id,
+          err:        (e && e.message) || String(e),
+        });
         return "failed";
       }
     }
@@ -379,7 +399,12 @@ function create(opts) {
           outcome:         "cancelled",
         });
         return "ok";
-      } catch (_e) {
+      } catch (e) {
+        _log.error("dunning step failed", {
+          action:     action,
+          invoice_id: enrollment.invoice_id,
+          err:        (e && e.message) || String(e),
+        });
         return "failed";
       }
     }

package/lib/plan-changes.js

@@ -62,6 +62,12 @@
 
 var b = require("./vendor/blamejs");
 
+// Observability sink for batch-path settlement failures: the scheduler
+// reverts a due row to 'pending' and carries on when a Stripe push or a
+// credit write throws, but the CAUSE is logged here rather than discarded
+// so an operator can see why scheduled plan changes aren't landing.
+var _log = b.log.create({});
+
 // ---- constants ----------------------------------------------------------
 
 var CHANGE_KINDS  = ["immediate", "next_billing_cycle"];
@@ -180,8 +186,92 @@ function create(opts) {
   // ledger; if the handle is absent the change is refused (executeChange
   // throws) or left pending (applyScheduledChanges) rather than applied
   // with the credit lost.
+  //
+  // NOTE: the store-credit / invoice path is the model for NON-Stripe
+  // subscriptions only. A Stripe-backed subscription (below) lets Stripe
+  // own the proration — Stripe invoices the difference (upgrade) or
+  // carries the balance forward as a credit (downgrade), so this primitive
+  // must NOT also issue a local credit / invoice for those rows, or the
+  // customer would be settled twice.
   var storeCreditHandle = opts.storeCredit || null;
 
+  // Optional payment handle (the shared Stripe adapter). When wired, a
+  // plan change on a Stripe-backed subscription swaps the subscription
+  // item's price at Stripe BEFORE the local plan_id is touched, so the
+  // plan the shop shows and the plan Stripe actually bills never diverge.
+  // Without it (a deploy with no payment processor, or a non-Stripe row),
+  // the change stays local-only and the store-credit / invoice proration
+  // model applies. The handle must expose `subscriptions.retrieve(id)` +
+  // `subscriptions.update(id, body, idempotencyKey)` — the same shape
+  // subscriptionControls composes.
+  var payment = opts.payment || null;
+  var hasStripe = !!(payment && payment.subscriptions &&
+    typeof payment.subscriptions.update === "function" &&
+    typeof payment.subscriptions.retrieve === "function");
+
+  // A subscription is Stripe-backed when the processor adapter is wired
+  // AND the row carries the upstream subscription id the webhook + billing
+  // mirror key on. Rows without one are shop-local (e.g. a manually seeded
+  // subscription on a deploy that never reached Stripe) and the local
+  // store-credit / invoice proration model applies to them.
+  function _isStripeBacked(sub) {
+    return hasStripe && sub && typeof sub.stripe_subscription_id === "string" && sub.stripe_subscription_id.length > 0;
+  }
+
+  // Swap the subscription item's price at Stripe for a Stripe-backed
+  // subscription. Stripe models the price on the subscription ITEM, not
+  // the subscription, so we retrieve the live subscription to find its
+  // (single) item id, then update that item's price. Every subscription
+  // this shop creates binds exactly one price (`items: [{ price }]`), so
+  // the first item is authoritative; if a subscription somehow carries no
+  // item we surface a structured error rather than silently writing a
+  // local-only change that diverges from Stripe.
+  //
+  // `prorationBehavior` selects who owns the money: "always_invoice"
+  // (immediate change) has Stripe invoice the proration delta now;
+  // "none" (next-cycle change) applies the new price cleanly from the
+  // next invoice with no mid-cycle adjustment. The idempotency key folds
+  // in the plan-change id so a retried call is a safe no-op at Stripe.
+  async function _pushPlanToStripe(stripeSubscriptionId, newStripePriceId, prorationBehavior, planChangeId) {
+    var live;
+    try {
+      live = await payment.subscriptions.retrieve(stripeSubscriptionId);
+    } catch (e) {
+      var rErr = new Error(
+        "planChanges: could not reach Stripe to swap the subscription plan — " + (e && e.message || e),
+      );
+      rErr.code = "PLAN_CHANGE_STRIPE_PUSH_FAILED";
+      rErr.cause = e;
+      throw rErr;
+    }
+    var items = live && live.items && Array.isArray(live.items.data) ? live.items.data : [];
+    if (!items.length || !items[0] || !items[0].id) {
+      var noItem = new Error(
+        "planChanges: Stripe subscription " + stripeSubscriptionId + " has no billable item to reprice",
+      );
+      noItem.code = "PLAN_CHANGE_STRIPE_NO_ITEM";
+      throw noItem;
+    }
+    var idemKey = "planchange:" + planChangeId;
+    try {
+      return await payment.subscriptions.update(
+        stripeSubscriptionId,
+        { items: [{ id: items[0].id, price: newStripePriceId }], proration_behavior: prorationBehavior },
+        idemKey,
+      );
+    } catch (e2) {
+      // The processor rejected or failed the plan swap. Wrap it in a stable
+      // code so the route can surface a "nothing changed, retry" notice; the
+      // local row is still untouched (this runs before the local write).
+      var uErr = new Error(
+        "planChanges: Stripe rejected the plan swap — " + (e2 && e2.message || e2),
+      );
+      uErr.code = "PLAN_CHANGE_STRIPE_PUSH_FAILED";
+      uErr.cause = e2;
+      throw uErr;
+    }
+  }
+
   async function _getSubscription(subscriptionId) {
     // Prefer the injected handle (production composition); fall back
     // to a direct read so tests that pass a minimal handle
@@ -399,6 +489,9 @@ function create(opts) {
       // ledger) and the credit (owed to the customer). Exactly one is
       // non-zero: an upgrade charges the difference, a downgrade leaves
       // the customer in credit for the outgoing plan's unused remainder.
+      // For a Stripe-backed subscription these are informational only —
+      // Stripe owns the money — but they're still recorded on the row for
+      // history / display.
       var chargeMinor = _max0(proposed.first_charge_minor - proposed.proration_credit_minor);
       var creditMinor = _max0(proposed.proration_credit_minor - proposed.first_charge_minor);
       // Status: `executed` when the effective clock is now-or-past,
@@ -409,12 +502,37 @@ function create(opts) {
       var status      = proposed.effective_at <= ts ? "executed" : "pending";
       var executedAt  = status === "executed" ? ts : null;
 
-      // Fail closed: a downgrade taking effect now owes the customer a
-      // credit, and the store-credit ledger is the only vehicle for it.
-      // Refuse before any row is written rather than apply the transition
-      // and silently drop the credit. (A future-dated downgrade is left
-      // pending; applyScheduledChanges re-checks at execution time.)
-      if (status === "executed") _assertCreditable(creditMinor);
+      var stripeBacked = _isStripeBacked(sub);
+
+      // Stripe owns the proration for a Stripe-backed subscription: it
+      // invoices the upgrade delta now (always_invoice) or carries a
+      // downgrade balance forward. So the local store-credit / invoice
+      // settlement MUST NOT also run for these rows — that would settle the
+      // customer twice. Conversely, a non-Stripe row's only settlement
+      // vehicle is the local store-credit ledger, so the credit-vehicle
+      // gate still applies there.
+      if (status === "executed" && stripeBacked) {
+        // Confirm the target plan carries a Stripe price to swap to. A plan
+        // with no `stripe_price_id` can't be expressed at Stripe; refuse
+        // before any local row is written rather than diverge the local plan
+        // from what Stripe bills.
+        var toPlanImmediate = await _getPlan(newPlanId);
+        if (!toPlanImmediate || !toPlanImmediate.stripe_price_id) {
+          var mErr = new Error(
+            "planChanges.executeChange: target plan " + newPlanId +
+            " has no stripe_price_id — cannot reprice a Stripe-backed subscription"
+          );
+          mErr.code = "PLAN_CHANGE_STRIPE_PRICE_MISSING";
+          throw mErr;
+        }
+      } else if (status === "executed") {
+        // Fail closed: a downgrade taking effect now owes the customer a
+        // credit, and the store-credit ledger is the only vehicle for it.
+        // Refuse before any row is written rather than apply the transition
+        // and silently drop the credit. (A future-dated downgrade is left
+        // pending; applyScheduledChanges re-checks at execution time.)
+        _assertCreditable(creditMinor);
+      }
 
       await query(
         "INSERT INTO subscription_plan_changes " +
@@ -429,56 +547,94 @@ function create(opts) {
         ],
       );
 
-      if (status === "executed") {
-        // Atomic transition claim. The plan update is conditional on the
-        // CURRENT plan id, so two concurrent executeChange calls for the same
-        // immediate change can't both apply it — only the call that observes
-        // the pre-change plan id transitions the row (rowCount 1); a racing
-        // second call sees rowCount 0. The _pendingFor guard above only blocks
-        // PENDING changes, so without this an immediate change executed twice
-        // (a double-submit or retry) would record the proration invoice twice
-        // and double-charge. The proration below is gated on winning the claim.
-        var planUpd = await query(
+      // A pending (future / next-cycle) change is NOT applied here, whether
+      // Stripe-backed or not — applyScheduledChanges pushes it to Stripe (or
+      // settles the local credit/invoice) once its clock matures.
+      if (status !== "executed") return await _getById(id);
+
+      if (stripeBacked) {
+        // STRIPE-FIRST: swap the price at Stripe with always_invoice (Stripe
+        // invoices the proration delta now) BEFORE the local plan_id write.
+        // If Stripe rejects, throw and leave the local row on the outgoing
+        // plan — the row the shop shows never diverges from what Stripe bills.
+        // (toPlanImmediate is resolved above and is guaranteed to carry a
+        // stripe_price_id.)
+        try {
+          await _pushPlanToStripe(sub.stripe_subscription_id, toPlanImmediate.stripe_price_id, "always_invoice", id);
+        } catch (e) {
+          // The Stripe swap failed. The row was inserted 'executed' above but
+          // the subscription was NOT repriced and its plan_id is untouched —
+          // void the row so history never shows a phantom-executed change that
+          // didn't happen, then rethrow so the route surfaces a clean retry.
+          await query(
+            "UPDATE subscription_plan_changes SET status = 'cancelled', cancelled_at = ?1, " +
+            "cancel_reason = ?2 WHERE id = ?3",
+            [_now(), "stripe-push-failed", id],
+          );
+          throw e;
+        }
+
+        // Atomic transition claim — same CAS as the local path. Stripe owns
+        // the money, so on a lost race (a concurrent executeChange already
+        // flipped the plan) there is no local credit/invoice to undo; we just
+        // skip. The Stripe push is idempotent (idempotencyKey folds in this
+        // change id), so a racing duplicate is a Stripe no-op.
+        await query(
           "UPDATE subscriptions SET plan_id = ?1, updated_at = ?2 WHERE id = ?3 AND plan_id = ?4",
           [newPlanId, ts, subscriptionId, sub.plan_id],
         );
-        var wonTransition = Number((planUpd && planUpd.rowCount) || 0) > 0;
-        if (wonTransition) {
-          if (creditMinor > 0) {
-            try {
-              await _issueDowngradeCredit({
-                customerId:   sub.customer_id,
-                creditMinor:  creditMinor,
-                planChangeId: id,
-              });
-            } catch (e) {
-              // Revert-on-throw: the credit is the customer's money, so a
-              // transient write failure must not finalize a downgrade it
-              // was never paid for. Roll the subscription back to the
-              // outgoing plan (guarded on the just-applied plan id so a
-              // concurrent change isn't clobbered) and void this change,
-              // then rethrow so the caller retries from a clean state.
-              await query(
-                "UPDATE subscriptions SET plan_id = ?1, updated_at = ?2 WHERE id = ?3 AND plan_id = ?4",
-                [sub.plan_id, _now(), subscriptionId, newPlanId],
-              );
-              await query(
-                "UPDATE subscription_plan_changes SET status = 'cancelled', cancelled_at = ?1, " +
-                "cancel_reason = ?2 WHERE id = ?3",
-                [_now(), "credit-settlement-failed", id],
-              );
-              throw e;
-            }
+        return await _getById(id);
+      }
+
+      // NON-STRIPE — today's local settlement path, unchanged.
+      // Atomic transition claim. The plan update is conditional on the
+      // CURRENT plan id, so two concurrent executeChange calls for the same
+      // immediate change can't both apply it — only the call that observes
+      // the pre-change plan id transitions the row (rowCount 1); a racing
+      // second call sees rowCount 0. The _pendingFor guard above only blocks
+      // PENDING changes, so without this an immediate change executed twice
+      // (a double-submit or retry) would record the proration invoice twice
+      // and double-charge. The proration below is gated on winning the claim.
+      var planUpd = await query(
+        "UPDATE subscriptions SET plan_id = ?1, updated_at = ?2 WHERE id = ?3 AND plan_id = ?4",
+        [newPlanId, ts, subscriptionId, sub.plan_id],
+      );
+      var wonTransition = Number((planUpd && planUpd.rowCount) || 0) > 0;
+      if (wonTransition) {
+        if (creditMinor > 0) {
+          try {
+            await _issueDowngradeCredit({
+              customerId:   sub.customer_id,
+              creditMinor:  creditMinor,
+              planChangeId: id,
+            });
+          } catch (e) {
+            // Revert-on-throw: the credit is the customer's money, so a
+            // transient write failure must not finalize a downgrade it
+            // was never paid for. Roll the subscription back to the
+            // outgoing plan (guarded on the just-applied plan id so a
+            // concurrent change isn't clobbered) and void this change,
+            // then rethrow so the caller retries from a clean state.
+            await query(
+              "UPDATE subscriptions SET plan_id = ?1, updated_at = ?2 WHERE id = ?3 AND plan_id = ?4",
+              [sub.plan_id, _now(), subscriptionId, newPlanId],
+            );
+            await query(
+              "UPDATE subscription_plan_changes SET status = 'cancelled', cancelled_at = ?1, " +
+              "cancel_reason = ?2 WHERE id = ?3",
+              [_now(), "credit-settlement-failed", id],
+            );
+            throw e;
           }
-          await _recordProrationInvoice({
-            subscriptionId: subscriptionId,
-            chargeMinor:    chargeMinor,
-            currency:       proposed.currency,
-            periodStart:    proposed.effective_at,
-            periodEnd:      sub.current_period_end,
-            planChangeId:   id,
-          });
         }
+        await _recordProrationInvoice({
+          subscriptionId: subscriptionId,
+          chargeMinor:    chargeMinor,
+          currency:       proposed.currency,
+          periodStart:    proposed.effective_at,
+          periodEnd:      sub.current_period_end,
+          planChangeId:   id,
+        });
       }
 
       return await _getById(id);
@@ -558,20 +714,34 @@ function create(opts) {
         var row = due.rows[i];
         var chargeMinor = _max0(row.first_charge_minor - row.proration_credit_minor);
         var creditMinor = _max0(row.proration_credit_minor - row.first_charge_minor);
-        // Fail closed: a due downgrade owes the customer a credit. If no
-        // store-credit vehicle is wired, leave the row PENDING (skip
-        // before claiming) so it applies on a later sweep once the handle
-        // exists — never transition it and drop the credit.
-        if (creditMinor > 0 && !storeCreditHandle) continue;
+
+        // Read the subscription up front to decide the settlement model.
+        // A Stripe-backed row lets Stripe own the proration (the new price
+        // applies cleanly from the next invoice — next-cycle semantics), so
+        // the local store-credit / invoice path is skipped for it entirely,
+        // INCLUDING the credit-vehicle skip guard below (that guard only
+        // gates the local store-credit path; Stripe carries a downgrade
+        // balance forward without one).
+        var dueSub = await _getSubscription(row.subscription_id);
+        var rowStripeBacked = _isStripeBacked(dueSub);
+
+        if (!rowStripeBacked) {
+          // Fail closed: a due downgrade owes the customer a credit. If no
+          // store-credit vehicle is wired, leave the row PENDING (skip
+          // before claiming) so it applies on a later sweep once the handle
+          // exists — never transition it and drop the credit.
+          if (creditMinor > 0 && !storeCreditHandle) continue;
+        }
 
         // Atomic claim: flip pending -> executed gated on the status.
         // Two overlapping scheduler runs (cron overrun, retry, two
         // workers) both SELECT the same due row; WITHOUT this guard both
         // would update the subscription plan AND record a proration
-        // invoice — billing the customer twice for one change. Only the
-        // caller whose UPDATE matches one row proceeds; the loser skips.
-        // (The synchronous executeChange path is already protected by its
-        // plan_id claim; this is the batch path's equivalent.)
+        // invoice / push to Stripe — settling the customer twice for one
+        // change. Only the caller whose UPDATE matches one row proceeds;
+        // the loser skips. (The synchronous executeChange path is already
+        // protected by its plan_id claim; this is the batch path's
+        // equivalent.) Both settlement models claim the same way.
         var claim = await query(
           "UPDATE subscription_plan_changes SET status = 'executed', executed_at = ?1 " +
           "WHERE id = ?2 AND status = 'pending'",
@@ -579,6 +749,52 @@ function create(opts) {
         );
         if (!b.sql.casWon(claim).won) continue;   // another run claimed it
 
+        if (rowStripeBacked) {
+          // STRIPE-FIRST: swap the price at Stripe with proration_behavior
+          // "none" — the new price applies from the next invoice cleanly
+          // (next-cycle semantics), no mid-cycle adjustment. On any Stripe
+          // failure, roll the claim back to 'pending' (guarded on the
+          // just-claimed state) so a later sweep retries it; the local
+          // plan_id was NOT touched yet, so there's nothing else to undo.
+          // One bad row must not abort the run.
+          var toPlan = await _getPlan(row.to_plan_id);
+          if (!toPlan || !toPlan.stripe_price_id) {
+            await query(
+              "UPDATE subscription_plan_changes SET status = 'pending', executed_at = NULL " +
+              "WHERE id = ?1 AND status = 'executed'",
+              [row.id],
+            );
+            continue;
+          }
+          try {
+            await _pushPlanToStripe(dueSub.stripe_subscription_id, toPlan.stripe_price_id, "none", row.id);
+          } catch (e) {
+            // Observe the cause (don't discard it), then roll the claim back
+            // to 'pending' so a later sweep retries this row; the local
+            // plan_id was not touched. One bad row never aborts the run.
+            _log.error("planChanges: scheduled Stripe plan swap failed", {
+              plan_change_id:  row.id,
+              subscription_id: row.subscription_id,
+              err:             (e && e.message) || String(e),
+            });
+            await query(
+              "UPDATE subscription_plan_changes SET status = 'pending', executed_at = NULL " +
+              "WHERE id = ?1 AND status = 'executed'",
+              [row.id],
+            );
+            continue;
+          }
+          // Stripe accepted — land the local plan_id transition. No local
+          // credit / invoice for a Stripe-backed row: Stripe owns the money.
+          await query(
+            "UPDATE subscriptions SET plan_id = ?1, updated_at = ?2 WHERE id = ?3",
+            [row.to_plan_id, now, row.subscription_id],
+          );
+          executed.push(await _getById(row.id));
+          continue;
+        }
+
+        // NON-STRIPE — today's local settlement path, unchanged.
         await query(
           "UPDATE subscriptions SET plan_id = ?1, updated_at = ?2 WHERE id = ?3",
           [row.to_plan_id, now, row.subscription_id],
@@ -593,12 +809,18 @@ function create(opts) {
               creditMinor:  creditMinor,
               planChangeId: row.id,
             });
-          } catch (_e) {
-            // Revert-on-throw, then carry on with the batch: the credit is
-            // the customer's money, so a transient write failure must not
-            // finalize this downgrade. Roll the plan back and return the row
-            // to 'pending' (guarded on the just-applied state) so a later
-            // sweep retries it cleanly; one bad row must not abort the run.
+          } catch (e) {
+            // Observe the cause, then revert-on-throw and carry on with the
+            // batch: the credit is the customer's money, so a transient write
+            // failure must not finalize this downgrade. Roll the plan back and
+            // return the row to 'pending' (guarded on the just-applied state)
+            // so a later sweep retries it cleanly; one bad row must not abort
+            // the run.
+            _log.error("planChanges: scheduled downgrade credit failed", {
+              plan_change_id:  row.id,
+              subscription_id: row.subscription_id,
+              err:             (e && e.message) || String(e),
+            });
             await query(
               "UPDATE subscriptions SET plan_id = ?1, updated_at = ?2 WHERE id = ?3 AND plan_id = ?4",
               [row.from_plan_id, now, row.subscription_id, row.to_plan_id],

package/lib/storefront.js

@@ -6230,6 +6230,8 @@ var SUBSCRIPTION_OK = {
   quantity:  "Quantity updated.",
   frequency: "Delivery frequency updated.",
   reactivated: "Your subscription has been reactivated.",
+  plan_changed:   "Your plan change is set.",
+  change_canceled: "Your scheduled plan change was canceled.",
 };
 function _subscriptionOkCopy(kind) {
   return Object.prototype.hasOwnProperty.call(SUBSCRIPTION_OK, kind) ? SUBSCRIPTION_OK[kind] : null;
@@ -6250,6 +6252,12 @@ var SUBSCRIPTION_ERR = {
   // 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.",
+  // A plan change already scheduled — the customer must cancel the
+  // pending one before queuing another.
+  pending_exists: "You already have a plan change scheduled. Cancel it before choosing another.",
+  // The requested plan can't be switched to (same plan / different
+  // currency / no longer offered).
+  plan:        "That plan isn't available to switch to. Pick another.",
 };
 function _subscriptionErrorCopy(code) {
   if (code == null) return null;
@@ -6279,6 +6287,12 @@ function renderAccountSubscriptions(opts) {
   // frequency control suppressed; a local-only controls instance keeps
   // offering it even on a Stripe-shaped row.
   var stripeAware = opts.stripe_backed === true;
+  // When the plan-change surface is wired, each active subscription gains a
+  // "Change plan" link, and any open (proposed/pending) change renders a
+  // banner with a cancel control. `opts.pending_changes` maps subscription
+  // id → the open change row (joined to its `to_plan`).
+  var canChange = opts.can_change === true;
+  var pendingChanges = opts.pending_changes || {};
   var rowsHtml = "";
   for (var i = 0; i < subs.length; i += 1) {
     var s = subs[i];
@@ -6332,6 +6346,38 @@ function renderAccountSubscriptions(opts) {
       cancelControl =
         "<a class=\"btn-ghost btn-ghost--sm subscription-card__cancel-link\" href=\"/account/subscriptions/" + esc(s.id) + "/cancel\">Cancel subscription</a>";
     }
+    // Change-plan link — offered only on a live (self-manageable, non-
+    // terminal) subscription with an active billing period, mirroring the
+    // change route's own preconditions. The proration preview + timing
+    // choice lives on the dedicated /change page.
+    var changeControl = "";
+    if (canChange && _subscriptionSelfManageable(s) && _subscriptionControlState(s) === "active" &&
+        s.current_period_start != null && s.current_period_end != null) {
+      changeControl =
+        "<a class=\"btn-ghost btn-ghost--sm subscription-card__change-link\" href=\"/account/subscriptions/" + esc(s.id) + "/change\">Change plan</a>";
+    }
+    // Pending plan-change banner — when an open change is scheduled for this
+    // row, show the target plan + timing and a cancel control. The cancel
+    // posts to the /change/cancel route; the change page also surfaces it.
+    var pendingBanner = "";
+    var pcRow = Object.prototype.hasOwnProperty.call(pendingChanges, s.id) ? pendingChanges[s.id] : null;
+    if (pcRow) {
+      var pcTo = pcRow.to_plan ? _planPriceCadence(pcRow.to_plan) : "a new plan";
+      var pcWhen = pcRow.change_kind === "next_billing_cycle"
+        ? "at your next billing date"
+        : "shortly";
+      var pcEff = pcRow.effective_at
+        ? new Date(Number(pcRow.effective_at)).toISOString().slice(0, 10)
+        : "";
+      pendingBanner =
+        "<div class=\"subscription-card__pending-change\" role=\"status\">" +
+          "<span class=\"subscription-card__pending-copy\">Plan change to " + pcTo + " scheduled " + esc(pcWhen) +
+            (pcEff ? " (<time datetime=\"" + esc(pcEff) + "\">" + esc(pcEff) + "</time>)" : "") + ".</span>" +
+          "<form class=\"subscription-card__control\" method=\"post\" action=\"/account/subscriptions/" + esc(s.id) + "/change/cancel\">" +
+            "<button type=\"submit\" class=\"btn-ghost btn-ghost--sm\">Cancel change</button>" +
+          "</form>" +
+        "</div>";
+    }
     // Self-manage controls — state-gated, mirroring the primitive's FSM
     // (active ⇒ pause / skip / change-qty / change-freq; paused ⇒ resume;
     // cancelled-within-grace ⇒ reactivate). Pause is confirm-gated like
@@ -6408,7 +6454,9 @@ function renderAccountSubscriptions(opts) {
         "</div>" +
         (renewalNote ? "<p class=\"subscription-card__meta\">" + renewalNote + "</p>" : "") +
         (stateNote ? "<p class=\"subscription-card__state\">" + stateNote + "</p>" : "") +
+        pendingBanner +
         manageControls +
+        changeControl +
         cancelControl +
       "</li>";
   }
@@ -6639,6 +6687,162 @@ function renderSubscriptionPauseConfirm(opts) {
   });
 }
 
+// Render a plan's "price + cadence" one-liner (e.g. "$24.99 per month").
+// Returns an already-escaped string. The price is formatted only when the
+// amount + currency are well-formed (a validated plan row always is); a
+// malformed row degrades to the cadence-only phrase by an EXPLICIT check
+// rather than by swallowing a thrown pricing.format error — so bad data
+// degrades visibly-by-design and never hides a defect behind a catch.
+function _planPriceCadence(plan) {
+  var esc = b.template.escapeHtml;
+  if (!plan) return "Plan unavailable";
+  var ccy = String(plan.currency || "").toUpperCase();
+  var amount = Number(plan.amount_minor);
+  var every = Number(plan.interval_count) > 1
+    ? "every " + Number(plan.interval_count) + " " + esc(String(plan.interval)) + "s"
+    : "per " + esc(String(plan.interval));
+  // pricing.format throws on a non-integer/negative amount or a non-ISO-4217
+  // currency; gate on exactly those preconditions so it is only ever called
+  // with input it accepts (no try/catch needed).
+  if (Number.isInteger(amount) && amount >= 0 && /^[A-Z]{3}$/.test(ccy)) {
+    return esc(pricing.format(amount, ccy)) + " " + every;
+  }
+  return every;
+}
+
+// Customer-facing plan-change page. `opts.subscription` carries the
+// resolved current `plan`; `opts.candidates` is an array of
+// { plan, preview } where preview is the proposeChange result for the
+// IMMEDIATE timing (proration_credit_minor + first_charge_minor +
+// currency). `opts.pending` is the open change to offer a cancel for, or
+// null. Confirm-gated: a single form, one radio per candidate plan, an
+// immediate-vs-next-cycle timing choice, and a submit. CSP forbids
+// inline script, so the proration math is server-rendered as static copy
+// — there's no client recompute. The CSRF field is spliced into the POST
+// form by `_injectCsrfFields` at send time. Everything dynamic is esc()'d.
+function renderSubscriptionPlanChange(opts) {
+  var esc = b.template.escapeHtml;
+  var s = opts.subscription || {};
+  var candidates = opts.candidates || [];
+  var pending = opts.pending || null;
+  var currentSummary = _planPriceCadence(s.plan || null);
+
+  var noticeHtml = opts.error
+    ? "<p class=\"form-notice form-notice--error\" role=\"alert\">" + esc(String(opts.error)) + "</p>"
+    : "";
+
+  // A pending change blocks queuing a new one (the primitive refuses a
+  // second). Render the standing change + a cancel control instead of the
+  // candidate picker.
+  var pendingHtml = "";
+  if (pending) {
+    var toSummary = _planPriceCadence(pending.to_plan || null);
+    var kindCopy = pending.change_kind === "next_billing_cycle"
+      ? "at your next billing date"
+      : "immediately";
+    var effDate = pending.effective_at
+      ? new Date(Number(pending.effective_at)).toISOString().slice(0, 10)
+      : "";
+    pendingHtml =
+      "<div class=\"plan-change-pending\">" +
+        "<p class=\"plan-change-pending__lede\">A change to " + toSummary + " is scheduled " + esc(kindCopy) +
+          (effDate ? " (<time datetime=\"" + esc(effDate) + "\">" + esc(effDate) + "</time>)" : "") + ".</p>" +
+        "<form method=\"post\" action=\"/account/subscriptions/" + esc(s.id) + "/change/cancel\">" +
+          "<button type=\"submit\" class=\"btn-ghost\">Cancel scheduled change</button>" +
+        "</form>" +
+      "</div>";
+  }
+
+  // Candidate picker — only when there's no pending change to clear first.
+  var pickerHtml = "";
+  if (!pending) {
+    if (!candidates.length) {
+      pickerHtml = "<p class=\"plan-change__empty\">There are no other plans to switch to right now.</p>";
+    } else {
+      var optionsHtml = "";
+      for (var i = 0; i < candidates.length; i += 1) {
+        var c = candidates[i];
+        var plan = c.plan;
+        var preview = c.preview || {};
+        var prevCcy = String(preview.currency || (plan && plan.currency) || "usd").toUpperCase();
+        var creditMinor = Number(preview.proration_credit_minor) || 0;
+        var chargeMinor = Number(preview.first_charge_minor) || 0;
+        // Net the proration into the single number the customer cares about:
+        // an upgrade charges (charge − credit) now; a downgrade leaves them
+        // (credit − charge) in store credit. Exactly one is non-zero, both
+        // floored at 0. Mirrors the primitive's executeChange split.
+        var netCharge = chargeMinor - creditMinor > 0 ? chargeMinor - creditMinor : 0;
+        var netCredit = creditMinor - chargeMinor > 0 ? creditMinor - chargeMinor : 0;
+        // netCharge/netCredit are non-negative integers by construction; the
+        // only value that could make pricing.format throw is a malformed
+        // currency, so gate the formatted copy on a valid ISO-4217 code by an
+        // EXPLICIT check rather than catching a thrown format error. A bad
+        // currency degrades to the amount-free phrase, visibly-by-design.
+        var validCcy = /^[A-Z]{3}$/.test(prevCcy);
+        var prorationCopy;
+        if (validCcy && netCharge > 0) {
+          prorationCopy = "Switch now and you'll be charged " + esc(pricing.format(netCharge, prevCcy)) + " for the rest of this period.";
+        } else if (validCcy && netCredit > 0) {
+          prorationCopy = "Switch now and you'll get " + esc(pricing.format(netCredit, prevCcy)) + " in store credit for the unused part of this period.";
+        } else if (validCcy) {
+          prorationCopy = "Switch now at no extra charge for the rest of this period.";
+        } else {
+          prorationCopy = "Switch now — proration applies for the rest of this period.";
+        }
+        optionsHtml +=
+          "<li class=\"plan-change-option\">" +
+            "<label class=\"plan-change-option__label\">" +
+              "<input type=\"radio\" name=\"new_plan_id\" value=\"" + esc(String(plan.id)) + "\"" + (i === 0 ? " checked" : "") + " required>" +
+              "<span class=\"plan-change-option__plan\">" + _planPriceCadence(plan) + "</span>" +
+              "<span class=\"plan-change-option__proration\">" + prorationCopy + "</span>" +
+            "</label>" +
+          "</li>";
+      }
+      pickerHtml =
+        "<form method=\"post\" action=\"/account/subscriptions/" + esc(s.id) + "/change\">" +
+          "<fieldset class=\"plan-change__plans\">" +
+            "<legend class=\"plan-change__legend\">Choose a new plan</legend>" +
+            "<ul class=\"plan-change-options\">" + optionsHtml + "</ul>" +
+          "</fieldset>" +
+          "<fieldset class=\"plan-change__timing\">" +
+            "<legend class=\"plan-change__legend\">When should it take effect?</legend>" +
+            "<label class=\"plan-change-timing__option\">" +
+              "<input type=\"radio\" name=\"timing\" value=\"immediate\" checked>" +
+              "<span>Now — with proration for the rest of this period</span>" +
+            "</label>" +
+            "<label class=\"plan-change-timing__option\">" +
+              "<input type=\"radio\" name=\"timing\" value=\"next_cycle\">" +
+              "<span>At my next billing date — no proration, the new plan starts clean</span>" +
+            "</label>" +
+          "</fieldset>" +
+          "<button type=\"submit\" class=\"btn-primary\">Change plan</button>" +
+        "</form>";
+    }
+  }
+
+  var body =
+    "<section class=\"account-confirm plan-change\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li><a href=\"/account/subscriptions\">Subscriptions</a></li>" +
+        "<li aria-current=\"page\">Change plan</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"account-confirm__title\">Change your plan</h1>" +
+      "<p class=\"plan-change__current\">You're currently on " + currentSummary + ".</p>" +
+      noticeHtml +
+      pendingHtml +
+      pickerHtml +
+      "<a class=\"btn-ghost\" href=\"/account/subscriptions\">Back to subscriptions</a>" +
+    "</section>";
+  return _wrap({
+    title:      "Change plan",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
 // Product-level "Save to wishlist" control + social-proof count.
 // Byte-compatible with the edge renderer (`worker/render/product.js`)
 // so both paths emit identical markup. Action-only label — the toggle
@@ -18865,6 +19069,14 @@ function mount(router, deps) {
       // state — so they're available even on a deploy with no payment
       // handle. The list above stays a read-only view when this is absent.
       var subControls = deps.subscriptionControls || null;
+      // Proration-aware plan upgrade / downgrade. Mounts the
+      // /account/subscriptions/:id/change confirm-gated surface (preview the
+      // proration credit / first charge per candidate plan + pick immediate
+      // vs next-cycle timing) plus the cancel-pending POST. Wired only when
+      // server.js composed it (needs subscriptions + store credit — the
+      // vehicle a mid-cycle downgrade's owed credit pays into). Absent it,
+      // the list stays the lifecycle-only view above.
+      var planChanges = deps.planChanges || null;
 
       async function _subsAuth(req, res) {
         var auth;
@@ -18939,6 +19151,33 @@ function mount(router, deps) {
           ? "Your subscription has been canceled."
           : _subscriptionOkCopy(okKind);
         var errKind = url ? url.searchParams.get("error") : null;
+        // Pending plan changes — when the plan-change surface is wired, look
+        // up the open (proposed/pending) change per subscription so the list
+        // can show a "change scheduled" banner with a cancel control. The
+        // banner is an enhancement to a critical page (the list must render),
+        // so a read failure is OBSERVED via _log.error and the banners are
+        // dropped for this render — degrade-with-observability, never a silent
+        // swallow. plans.get returns null for a deleted target plan (handled
+        // by the renderer); only a genuine failure reaches the catch.
+        var pendingChanges = {};
+        if (planChanges) {
+          try {
+            for (var pci = 0; pci < rows.length; pci += 1) {
+              var pcSub = rows[pci];
+              var pcRow = await planChanges.pendingChangeFor(pcSub.id);
+              if (pcRow) {
+                pcRow.to_plan = await subscriptions.plans.get(pcRow.to_plan_id);
+                pendingChanges[pcSub.id] = pcRow;
+              }
+            }
+          } catch (e) {
+            _log.error("subscription list: pending plan-change lookup failed", {
+              request_id: (req && req.requestId) || null,
+              err:        (e && e.message) || String(e),
+            });
+            pendingChanges = {};
+          }
+        }
         _send(res, 200, renderAccountSubscriptions({
           subscriptions: rows,
           can_cancel:    subsCanCancel,
@@ -18948,6 +19187,10 @@ function mount(router, deps) {
           // handle with retrieve + update was wired) — otherwise the
           // controls are local-only and the cadence is still editable.
           stripe_backed: !!(subControls && subControls.stripeBacked),
+          // Plan-change link + pending-change banner render only when the
+          // surface is wired.
+          can_change:      !!planChanges,
+          pending_changes: pendingChanges,
           notice:        notice,
           error:         _subscriptionErrorCopy(errKind),
           shop_name:     shopName,
@@ -19172,6 +19415,183 @@ function mount(router, deps) {
           return res.end ? res.end() : res.send("");
         });
       }
+
+      // Plan change — proration-aware self-serve upgrade / downgrade. Mounts
+      // only when the plan-change primitive is wired (server.js composes it
+      // from subscriptions + store credit). The GET renders a confirm-gated
+      // page listing every candidate plan with its proration preview; the
+      // POST executes the chosen change (immediate or next-cycle); a third
+      // POST cancels a still-pending change. Every route owns its
+      // subscription through the same `_ownedSubscription` IDOR check the
+      // cancel flow uses (a forged/foreign id 404s before any read), and
+      // every primitive refusal maps to a fixed ?error code rather than a
+      // 500.
+      if (planChanges) {
+        function _pcRedirect(res, suffix) {
+          res.status(303);
+          res.setHeader && res.setHeader("location", "/account/subscriptions" + suffix);
+          return res.end ? res.end() : res.send("");
+        }
+
+        // Translate a planChanges rejection into a fixed ?error code. A
+        // pending-change collision, an unknown subscription/plan, and a
+        // validation TypeError (cross-currency / same-plan / archived plan)
+        // each map to a stable code; a Stripe-backed change whose target
+        // plan has no Stripe price (PLAN_CHANGE_STRIPE_PRICE_MISSING) is a
+        // misconfiguration the customer can't act on but must not 500;
+        // a transient Stripe push failure (PLAN_CHANGE_STRIPE_PUSH_FAILED /
+        // _NO_ITEM) leaves the local plan untouched and surfaces a "nothing
+        // changed, retry" notice rather than a 500. Anything else rethrows
+        // (a real 500, e.g. an unmigrated table on a misconfigured deploy).
+        function _planChangeError(e) {
+          if (e && e.code === "PLAN_CHANGE_REFUSED")              return "pending_exists";
+          if (e && e.code === "SUBSCRIPTION_NOT_FOUND")           return "state";
+          if (e && e.code === "PLAN_NOT_FOUND")                   return "state";
+          if (e && e.code === "NO_PENDING_CHANGE")                return "state";
+          if (e && e.code === "PLAN_CHANGE_STRIPE_PRICE_MISSING") return "plan";
+          if (e && e.code === "PLAN_CHANGE_STRIPE_PUSH_FAILED")   return "processor";
+          if (e && e.code === "PLAN_CHANGE_STRIPE_NO_ITEM")       return "processor";
+          if (e instanceof TypeError)                              return "plan";
+          return null;
+        }
+
+        // Resolve every plan a subscription can switch TO: every active plan
+        // sharing the current plan's currency, minus the current plan
+        // itself. A cross-currency or archived plan is excluded here so the
+        // confirm page never offers a candidate the primitive would refuse.
+        // For each candidate, compute the immediate-timing proration preview
+        // (credit + first charge) — the page shows both timings, but only
+        // the immediate one prorates, so a single proposeChange per candidate
+        // covers the preview. proposeChange persists nothing.
+        async function _changeCandidates(sub) {
+          // A read failure here is a real error, not a "no candidates" state —
+          // let it propagate to the route's _routeError (logged + generic),
+          // never mask it. The current-plan lookup returns null for a deleted
+          // plan (a legitimate value handled below), and only throws on a real
+          // DB failure (which also propagates).
+          var allPlans = await subscriptions.plans.list({ active: true });
+          var fromPlan = sub.plan_id != null ? await subscriptions.plans.get(sub.plan_id) : null;
+          if (!fromPlan) return [];   // no resolvable current plan → nothing to prorate a switch against
+          var fromCcy     = String(fromPlan.currency);
+          var fromAmount  = Number(fromPlan.amount_minor);
+          var periodStart = Number(sub.current_period_start);
+          var periodEnd   = Number(sub.current_period_end);
+          var nowMs       = Date.now();
+          var out = [];
+          for (var i = 0; i < allPlans.length; i += 1) {
+            var p = allPlans[i];
+            if (p.id === sub.plan_id) continue;             // never the current plan
+            if (!p.active) continue;                        // archived → executeChange refuses
+            if (String(p.currency) !== fromCcy) continue;   // cross-currency → executeChange refuses
+            // Immediate-timing proration preview via the primitive's exported
+            // PURE math — no DB round-trip and no throw for valid integers, so
+            // there is no error to swallow. The actual switch re-validates the
+            // full shape through executeChange on POST.
+            var pr = planChanges.prorate(fromAmount, Number(p.amount_minor), periodStart, periodEnd, nowMs);
+            out.push({
+              plan: p,
+              preview: {
+                proration_credit_minor: pr.proration_credit_minor,
+                first_charge_minor:     pr.first_charge_minor,
+                currency:               fromCcy,
+              },
+            });
+          }
+          return out;
+        }
+
+        router.get("/account/subscriptions/:id/change", async function (req, res) {
+          var auth = await _subsAuth(req, res); if (!auth) return;
+          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          // Only an active, self-manageable subscription can change plans — a
+          // terminal / paused / cancelled row (even one that still carries
+          // period columns) is refused here, matching the display gate that
+          // decides whether to show the "Change plan" link.
+          if (!_subscriptionSelfManageable(sub) || _subscriptionControlState(sub) !== "active") {
+            return _pcRedirect(res, "?error=state");
+          }
+          // A subscription with no live billing period can't be prorated;
+          // bounce to the list rather than render an empty change page.
+          if (sub.current_period_start == null || sub.current_period_end == null) {
+            return _pcRedirect(res, "?error=state");
+          }
+          try {
+            // A read failure on any of these is a real error — route it
+            // through _routeError (logs server-side + returns a generic,
+            // leak-free message) rather than masking it with a per-read
+            // catch. plans.get returns null for a deleted plan (a value the
+            // renderer handles); only a genuine failure throws here.
+            if (sub.plan_id != null) sub.plan = await subscriptions.plans.get(sub.plan_id);
+            var candidates = await _changeCandidates(sub);
+            var pending = await planChanges.pendingChangeFor(sub.id);
+            if (pending) pending.to_plan = await subscriptions.plans.get(pending.to_plan_id);
+            var url = req.url ? new URL(req.url, "http://localhost") : null;
+            var errKind = url ? url.searchParams.get("error") : null;
+            var cartCount = await _cartCountForReq(req);
+            _send(res, 200, renderSubscriptionPlanChange({
+              subscription: sub,
+              candidates:   candidates,
+              pending:      pending,
+              error:        _subscriptionErrorCopy(errKind),
+              shop_name:    shopName,
+              cart_count:   cartCount,
+            }));
+          } catch (e) {
+            return _routeError(req, res, e);
+          }
+        });
+
+        router.post("/account/subscriptions/:id/change", async function (req, res) {
+          var auth = await _subsAuth(req, res); if (!auth) return;
+          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          // Reject a plan change on a non-active subscription (terminal /
+          // paused / cancelled) before any write — the same gate the display
+          // and GET enforce, so a forged POST can't re-plan a wound-down row.
+          if (!_subscriptionSelfManageable(sub) || _subscriptionControlState(sub) !== "active") {
+            return _pcRedirect(res, "?error=state");
+          }
+          var body = req.body || {};
+          var newPlanId = String(body.new_plan_id || "");
+          // Backend validates: an empty / missing plan id is a client error
+          // → bounce with the plan code rather than handing garbage to the
+          // primitive.
+          if (!newPlanId) return _pcRedirect(res, "/" + encodeURIComponent(sub.id) + "/change?error=plan");
+          var timing = String(body.timing || "immediate");
+          if (timing !== "immediate" && timing !== "next_cycle") {
+            return _pcRedirect(res, "/" + encodeURIComponent(sub.id) + "/change?error=state");
+          }
+          // next_cycle defers the change to the period boundary: the
+          // primitive derives `next_billing_cycle` (and zero proration) when
+          // change_at >= current_period_end. Immediate omits change_at, so
+          // the primitive applies it at Date.now() with full proration.
+          var changeArgs = { subscription_id: sub.id, new_plan_id: newPlanId };
+          if (timing === "next_cycle") {
+            if (sub.current_period_end == null) {
+              return _pcRedirect(res, "/" + encodeURIComponent(sub.id) + "/change?error=state");
+            }
+            changeArgs.change_at = Number(sub.current_period_end);
+          }
+          try {
+            await planChanges.executeChange(changeArgs);
+          } catch (e) {
+            var code = _planChangeError(e); if (code == null) throw e;
+            return _pcRedirect(res, "/" + encodeURIComponent(sub.id) + "/change?error=" + code);
+          }
+          return _pcRedirect(res, "?ok=plan_changed");
+        });
+
+        router.post("/account/subscriptions/:id/change/cancel", async function (req, res) {
+          var auth = await _subsAuth(req, res); if (!auth) return;
+          var sub = await _ownedSubscription(req, res, auth); if (!sub) return;
+          try {
+            await planChanges.cancelPendingChange({ subscription_id: sub.id });
+          } catch (e) {
+            var code = _planChangeError(e); if (code == null) throw e;
+            return _pcRedirect(res, "?error=" + code);
+          }
+          return _pcRedirect(res, "?ok=change_canceled");
+        });
+      }
     }
 
     // Pre-order reservations — the PDP reserve POST + the customer's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {