@blamejs/blamejs-shop 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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.
 
 - v0.5.2 (2026-06-27) — **Vendored framework refreshed to 0.15.36.** Updates the vendored blamejs framework to 0.15.36. The upstream release is internal test-suite tooling only: it re-verifies the guard-suite class that allows a bare comma/semicolon split on token-only RFC header grammars (RRULE, RFC 9421 signature components, TLS-RPT rua, SCIM attribute paths), renames its marker to a descriptive token, and prunes five inert marker comments. No runtime code, public API, or wire format changed upstream, so there is no runtime or behavior change for this storefront and no operator action is required. **Changed:** *Vendored framework refreshed to 0.15.36* — Refreshes the vendored blamejs framework to 0.15.36, an upstream release scoped to test-suite tooling — a guard-suite class re-verified and its marker renamed, plus five inert marker comments removed. The shipped framework runtime, public API, and wire format are unchanged, so no operator action is required.

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.5.3",
+  "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],