PAYG bundle: server-authoritative price (inline amount_off coupon) + Stirling-Tools#7032 review nits (Stirling-Tools#7156)

## What

Follow-up to Stirling-Tools#7032. Makes the prepaid-bundle price
**server-authoritative** and removes the percent-coupon rounding drift,
by switching the 12-for-10 discount from a pre-made `percent_off` Stripe
coupon to an **edge-function-computed inline `amount_off` coupon**. Also
folds in Ethan's Stirling-Tools#7032 review nits.

This is a money-mechanism change, so it was verified against the Deno
tests and is ready for a V2-preview check before rollout.

## SaaS side — already on `v3` (purely additive)

The edge fn + migration were pushed **directly to `v3`** (commit
`4534ff1c1`), since the DB change is purely additive (a
backward-compatible function replacement — no table/column/data
changes):

- `create-payg-bundle-quote`: retrieves the Stripe Price for the bundle,
computes `subtotal = unit_amount x pool_credits` (falls back to
`round(unit_amount_decimal x pool_credits)`), `discount = round(subtotal
x 2 / 12)`, `total = subtotal - discount`; mints a single-use
fixed-amount coupon (`amount_off`, `duration: once`, `max_redemptions:
1`, `redeem_by = valid_until`) and applies it instead of the stored
percent coupon; persists `total` via `p_price_minor`.
- Migration `20260803000000_payg_bundle_quote_stripe_price_minor.sql`:
`payg_set_bundle_quote_stripe` gains `p_price_minor BIGINT DEFAULT NULL`
→ `price_minor = COALESCE(p_price_minor, price_minor)`.

**Deploy choreography (important):** the migration must apply **before**
the edge fn is deployed — the fn now calls the 4-arg
`payg_set_bundle_quote_stripe`. Stirling-Tools#7032's own Supabase migration is
already on `main`/`v3`.

## This PR (FE)

- **Server-authoritative price:** `bundlePriceMinor` now computes
`subtotal - round(subtotal x (granted-paid)/granted)` (round the
discount, then subtract) — identical to the edge fn — so the pre-mint
estimate matches the `amount_off` charged, and the persisted/frozen
total, to the penny (they previously diverged by a minor unit on
exact-half ties). Tie-case test added.

### Ethan's Stirling-Tools#7032 review nits

- **1** — comments in `ActivationChoiceModal` / `FreePlanView` no longer
assert the metered subscription is auto-provisioned off the saved card;
they describe it as a known, not-yet-wired follow-up.
- **2** — corrected the price-authority narrative (`stripe.ts`,
`BundleCheckoutModal`): the client-sent `p_price_minor` is a pre-mint
**display estimate only**; the edge fn overwrites `price_minor` with the
server total once the quote is minted. **Verified** the edge fn builds
the Stripe line from `bundle_price_id x pool_credits` with `amount_off`
from the retrieved Price — it never uses the client price.
- **4** — `ensureStripeQuote`'s reuse key now includes the
posture/size/pipeline ids (`buildStripeQuoteSig`), not just pool+PO, so
a same-pool sizing edit re-mints and re-persists instead of leaving
stale sizing on the row.
- **5** — `SpendLimitPicker`: a cleared field (maps to `0`) can no
longer proceed as a `$0` cap — the cap-step Continue is disabled and
`handleContinue` guards on it (empty = incomplete, distinct from the
explicit `null` "No limit").
- **6** — `"prepaid PDFs"` code fallbacks aligned to the `"prepaid
credits"` TOML (`usageMeters`, `PrepaidCapacityCard`).

## Testing

- SaaS Deno: **25/25** (coupon `amount_off == round(subtotal*2/12)`,
`p_price_minor == total` persisted, `unit_amount_decimal` fallback,
exact-half tie, zero-discount path, price/coupon failure paths).
- FE vitest: **50** billing/format tests pass; prettier + eslint clean;
tsc clean for all changed files.
- Pending: manual V2-preview check that the invoice shows a concrete
`-$X.00` discount line (labelled "12 months for the price of 10") equal
to the in-app total.

Closes the residual half of Stirling-Tools#7032 review finding #2 — once
merged/deployed, the in-app total, the persisted value, and the Stripe
invoice all agree.

---------

Co-authored-by: Reece Browne <74901996+reecebrowne@users.noreply.github.com>

Author: ConnorYoh

app/saas/src/main/java/stirling/software/saas/payg/api/PaygWalletController.java

@@ -1,5 +1,6 @@
 package stirling.software.saas.payg.api;
 
+import java.math.BigDecimal;
 import java.time.LocalDateTime;
 import java.time.format.DateTimeFormatter;
 import java.util.ArrayList;
@@ -206,6 +207,12 @@ public ResponseEntity<WalletSnapshotResponse> getWallet(Authentication auth) {
         // Prepaid while pools still have units to draw; once exhausted the meter is live again.
         String billingMode = prepaidRemaining > 0 ? BILLING_MODE_PREPAID : BILLING_MODE_PAYG;
 
+        // Per-credit rate for the bundle calculator — the bundle:processor price, NOT the metered
+        // per-doc rate. Resolved in the team's currency (USD fallback), null when the price is
+        // unsynced.
+        BigDecimal bundleRatePerCreditMinor =
+                billingService.resolveBundleRatePerCreditMinor(billing.currency());
+
         WalletSnapshotResponse body =
                 new WalletSnapshotResponse(
                         teamId,
@@ -234,7 +241,8 @@ public ResponseEntity<WalletSnapshotResponse> getWallet(Authentication auth) {
                         prepaidRemaining,
                         prepaidTotal,
                         prepaidExpiresAt,
-                        billingMode);
+                        billingMode,
+                        bundleRatePerCreditMinor);
         return ResponseEntity.ok(body);
     }
 
@@ -512,6 +520,7 @@ private WalletSnapshotResponse emptySnapshot() {
                 0L,
                 0L,
                 null,
-                BILLING_MODE_PAYG);
+                BILLING_MODE_PAYG,
+                null);
     }
 }

app/saas/src/main/java/stirling/software/saas/payg/api/WalletSnapshotResponse.java

@@ -55,6 +55,11 @@
  * @param members leader-only roster of team members + their per-member sub-caps. Empty for member
  *     callers.
  * @param recent latest wallet-ledger entries (newest first) for the activity feed.
+ * @param bundleRatePerCreditMinor per-credit rate of the prepaid-bundle Stripe Price (lookup key
+ *     {@code bundle:processor}) in minor units of {@code currency} (may be fractional); {@code
+ *     null} when unresolved. The in-app bundle calculator multiplies its pool by this so its
+ *     estimate matches the checkout edge fn's charge. Distinct from {@code pricePerDocMinor} (the
+ *     metered per-document rate) — the two must not be conflated.
  */
 public record WalletSnapshotResponse(
         Long teamId,
@@ -83,7 +88,8 @@ public record WalletSnapshotResponse(
         long prepaidUnitsRemaining,
         long prepaidUnitsTotal,
         String prepaidExpiresAt,
-        String billingMode) {
+        String billingMode,
+        BigDecimal bundleRatePerCreditMinor) {
 
     // Prepaid usage bundles, aggregated across the team's in-term pools (drawn ahead of the meter,
     // outside the spend cap):

app/saas/src/main/java/stirling/software/saas/payg/billing/TeamBillingService.java

@@ -68,6 +68,14 @@ public class TeamBillingService {
      */
     private static final String PAYG_LOOKUP_KEY = "plan:processor";
 
+    /**
+     * Stripe Price {@code lookup_key} for the prepaid-bundle price — the per-credit rate the bundle
+     * calculator prices its pool at. A DIFFERENT price from {@link #PAYG_LOOKUP_KEY} (the metered
+     * per-document rate); the two must not be conflated, or the in-app estimate diverges from the
+     * amount the checkout edge fn actually charges (which bills against this same price).
+     */
+    private static final String BUNDLE_LOOKUP_KEY = "bundle:processor";
+
     private final PaygTeamExtensionsRepository extensionsRepository;
     private final WalletPolicyRepository walletPolicyRepository;
     private final PricingPolicyService pricingPolicyService;
@@ -254,6 +262,23 @@ public Optional<Long> docCapForMoney(TeamBillingContext ctx, long capMinor) {
                         .longValue());
     }
 
+    /**
+     * Per-credit rate of the prepaid-bundle Stripe Price (lookup key {@code bundle:processor}) in
+     * {@code currency} (USD fallback) — the rate the in-app bundle calculator multiplies its pool
+     * by, so its estimate matches the amount the checkout edge fn charges (which bills the pool
+     * against this same price). Distinct from the metered {@code perDocMinor}; a bundle credit is
+     * one size-scaled run, priced per {@code unit_amount} of the bundle price. {@code null} when
+     * the rate can't be resolved (stripe schema absent, price unsynced) — the calculator then hides
+     * the figure and defers to the server total.
+     */
+    public BigDecimal resolveBundleRatePerCreditMinor(String currency) {
+        return subscriptionDao
+                .findRateByLookupKey(
+                        BUNDLE_LOOKUP_KEY, currency != null ? currency : DISPLAY_CURRENCY)
+                .map(StripeSubscriptionDao.PriceRate::perDocMinor)
+                .orElse(null);
+    }
+
     /**
      * Inclusive-start / exclusive-end window for the calendar month — the monthly billing window
      * used when there's no Stripe subscription period to anchor on.

app/saas/src/main/java/stirling/software/saas/payg/policy/PricingPolicy.java

@@ -123,9 +123,11 @@ public class PricingPolicy implements Serializable {
     @Column(name = "bundle_stripe_price_id", length = 128)
     private String bundleStripePriceId;
 
-    /** Stripe coupon id applying the 12-for-10 prepaid discount. Null = bundles not offered. */
-    @Column(name = "bundle_coupon_id", length = 128)
-    private String bundleCouponId;
+    // No bundle_coupon_id field: the 12-for-10 discount is minted per-quote as an inline amount_off
+    // coupon by the create-payg-bundle-quote edge fn (computed from the bundle Price), so the
+    // pre-made percent coupon this policy used to carry is no longer consulted by anything. The
+    // column still exists (payg_get_bundle_pricing returns it) and is dropped in a later cleanup;
+    // ddl-auto=update never drops columns, so removing the mapping here is safe.
 
     /**
      * Exactly one row in the table has {@code is_default = true}; enforced by partial unique idx.

app/saas/src/test/java/stirling/software/saas/payg/api/WalletSnapshotResponseTest.java

@@ -43,7 +43,8 @@ private static WalletSnapshotResponse sample() {
                 /* prepaidUnitsRemaining= */ 40_000L,
                 /* prepaidUnitsTotal= */ 120_000L,
                 /* prepaidExpiresAt= */ "2027-06-01",
-                /* billingMode= */ "prepaid");
+                /* billingMode= */ "prepaid",
+                /* bundleRatePerCreditMinor= */ new BigDecimal("1"));
     }
 
     @Test
@@ -123,10 +124,12 @@ void nullableFields() {
                         0L,
                         0L,
                         null,
-                        "payg");
+                        "payg",
+                        null);
 
         assertThat(free.billableLimit()).isNull();
         assertThat(free.pricePerDocMinor()).isNull();
+        assertThat(free.bundleRatePerCreditMinor()).isNull();
         assertThat(free.currency()).isNull();
         assertThat(free.estimatedBillMinor()).isNull();
         assertThat(free.capUsd()).isNull();

frontend/editor/src/cloud/components/shared/config/configSections/usageMeters.tsx

@@ -196,7 +196,7 @@ export function PrepaidCapacityMeterPanel({ snap }: { snap: PrepaidSnapshot }) {
       figure={snap.remaining.toLocaleString()}
       capSuffix={t(
         "payg.prepaid.meter.capSuffix",
-        "of {{total}} prepaid PDFs",
+        "of {{total}} prepaid credits",
         {
           total: snap.total.toLocaleString(),
         },

frontend/editor/src/cloud/hooks/useWallet.ts

@@ -128,6 +128,7 @@ function reuseIfEqual(prev: Wallet | null, next: Wallet): Wallet {
     prev.freeAllowance !== next.freeAllowance ||
     prev.freeRemaining !== next.freeRemaining ||
     prev.pricePerDocMinor !== next.pricePerDocMinor ||
+    prev.bundleRatePerCreditMinor !== next.bundleRatePerCreditMinor ||
     prev.currency !== next.currency ||
     prev.estimatedBillMinor !== next.estimatedBillMinor ||
     prev.capUsd !== next.capUsd ||

frontend/editor/src/portal/billing/stripe.ts

@@ -117,7 +117,12 @@ export interface BundleQuoteInput {
   provisionedMonthlyVolume: number;
   /** Size-folded run-credits = the Stripe line quantity when this quote is paid. */
   poolCredits: number;
-  /** Discounted total in minor units; null when the per-run rate is unknown. */
+  /**
+   * Client-estimated discounted total in minor units, persisted for the pre-mint display only; null
+   * when the per-run rate is unknown. NOT authoritative: once the Stripe quote is minted,
+   * create-payg-bundle-quote overwrites the row's price_minor with the server-derived total
+   * (Price x qty - amount_off), and the Stripe quote/invoice amount is server-derived regardless.
+   */
   priceMinor: number | null;
   currency: string;
   /** Affirmative consent to the prepaid→metered auto-transition (ARL/EULA §7.2). */

frontend/editor/src/portal/components/billing/ActivationChoiceModal.tsx

@@ -50,11 +50,14 @@ function DoorCard({
  * before any card is entered. Two door-cards, matching the demo —
  *
  *   - Pay as you go → the metered subscription checkout (spend limit + card).
- *   - Prepay a year → the discounted bundle (calculator + one-time payment); the
- *     backend silently stands up the metered subscription off the saved card so
- *     metering resumes when the pool empties, so no spend-limit step is needed.
+ *   - Prepay a year → the discounted bundle (calculator + one-time payment); no
+ *     spend-limit step, since the buyer commits to a fixed pool up front.
  *
  * Same per-PDF rate on both paths — prepay just front-loads two free months.
+ *
+ * Note: auto-standing-up the metered subscription off the saved card so metering
+ * resumes once a prepaid pool empties is a known follow-up, NOT yet wired — a
+ * prepay-only team isn't metered past its pool today.
  */
 export function ActivationChoiceModal({
   open,

frontend/editor/src/portal/components/billing/BundleCheckoutModal.tsx

@@ -100,6 +100,23 @@ function pipelineIdFor(mult: number): string {
   );
 }
 
+/**
+ * Reuse key for the minted Stripe quote. Includes the sizing MULTIPLIER ids alongside the pool + PO,
+ * not just the pool: different posture/size/pipeline combos can yield the same poolCredits (identical
+ * Stripe amount), and keying on the pool alone would skip the re-mint on such an edit and leave the
+ * persisted quote row with stale sizing fields. Keying on the ids re-mints (and re-persists) whenever
+ * the buyer actually changes the config.
+ */
+function buildStripeQuoteSig(
+  poolCredits: number,
+  postureId: string,
+  sizeId: string,
+  pipelineId: string,
+  poNumber: string,
+): string {
+  return `${poolCredits}|${postureId}|${sizeId}|${pipelineId}|${poNumber.trim()}`;
+}
+
 /**
  * Pre-quote calculator progress, persisted per team so closing the modal / reloading doesn't lose the
  * buyer's place. Once a real quote exists it's the source of truth (loaded server-side), so this is
@@ -189,7 +206,9 @@ export function BundleCheckoutModal({
   const { t } = useTranslation();
   const teamId = wallet.teamId;
   const currency = wallet.currency ?? "usd";
-  const pricePerDocMinor = wallet.pricePerDocMinor;
+  // The pool is priced per size-scaled RUN at the prepaid-bundle rate (bundle:processor), NOT the
+  // metered per-document rate — so the estimate matches the amount the checkout edge fn charges.
+  const ratePerRunMinor = wallet.bundleRatePerCreditMinor;
 
   const [phase, setPhase] = useState<Phase>("calc");
   const [users, setUsers] = useState(DEFAULT_USERS);
@@ -218,10 +237,12 @@ export function BundleCheckoutModal({
   const [stripeQuoteSig, setStripeQuoteSig] = useState<string | null>(null);
   // The invoice generated when the quote is accepted (awaiting payment); null when simulated.
   const [invoice, setInvoice] = useState<BundleInvoice | null>(null);
-  // On resume, the total the quote was persisted at (server value), frozen so the receipt shows what
-  // the buyer actually quoted rather than a figure recomputed from a since-changed rate. Paired with
-  // the pool size it was persisted at — once the buyer edits the sizing (pool changes) we drop back to
-  // the live estimate, since editing re-mints and re-persists anyway.
+  // On resume, the total the quote was persisted at, frozen so the receipt shows what the buyer
+  // actually quoted rather than a figure recomputed from a since-changed rate. Once the Stripe quote
+  // has been minted this is the server-derived total (create-payg-bundle-quote overwrites price_minor
+  // with Price x qty - amount_off); before that it's the client estimate persisted at upsert. Paired
+  // with the pool size it was persisted at — once the buyer edits the sizing (pool changes) we drop
+  // back to the live estimate, since editing re-mints and re-persists anyway.
   const [persistedPriceMinor, setPersistedPriceMinor] = useState<number | null>(
     null,
   );
@@ -302,7 +323,13 @@ export function BundleCheckoutModal({
           });
           // Match the reuse signature so resuming doesn't immediately re-mint the Stripe quote.
           setStripeQuoteSig(
-            `${latest.poolCredits}|${(saved?.poNumber ?? "").trim()}`,
+            buildStripeQuoteSig(
+              latest.poolCredits,
+              postureIdFor(latest.posturePolicies),
+              sizeIdFor(latest.sizeMult),
+              pipelineIdFor(latest.pipelineMult),
+              saved?.poNumber ?? "",
+            ),
           );
         }
         // Already accepted (an invoice exists) → resume straight to the payment step rather than the
@@ -374,9 +401,9 @@ export function BundleCheckoutModal({
         posturePolicies: policiesFor(postureId),
         sizeMult: sizeMultFor(sizeId),
         pipelineMult: pipelineMultFor(pipelineId),
-        ratePerRunMinor: pricePerDocMinor,
+        ratePerRunMinor,
       }),
-    [users, postureId, sizeId, pipelineId, pricePerDocMinor],
+    [users, postureId, sizeId, pipelineId, ratePerRunMinor],
   );
 
   // The receipt shows the persisted (server) total on resume so it matches the quote the buyer
@@ -459,7 +486,13 @@ export function BundleCheckoutModal({
     stripeQuote: BundleStripeQuote;
   } | null> {
     if (teamId == null) return null;
-    const sig = `${quote.poolCredits}|${poNumber.trim()}`;
+    const sig = buildStripeQuoteSig(
+      quote.poolCredits,
+      postureId,
+      sizeId,
+      pipelineId,
+      poNumber,
+    );
     if (stripeQuote && stripeQuoteSig === sig && quoteId != null) {
       return { quoteId, stripeQuote }; // unchanged since last mint — reuse, no new quote
     }