@ssheleg/sheleg-dev 0.9.2 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,75 @@ All notable changes to this project are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## v0.10.0 — the cancel flow that offers a discount, and the two ways it leaks money
+
+Cursor's cancel page — "Before you go… 50% off your next invoice" — is Stripe's
+customer portal with `flow_data[subscription_cancel][retention]`, and `stripe-billing`
+said nothing about it. Verified against the Stripe OpenAPI spec at `2026-07-29.dahlia`
+and `docs.stripe.com` on 2026-08-25.
+
+### Two defects that no screen shows
+
+**A `duration=once` discount deletes itself, so the offer can be taken forever.** From
+Stripe's own coupon documentation: once the discounted invoice finalizes, the discount is
+**removed from the subscription's `discounts` array** — "a subscription may appear to have
+no discount even though a coupon was applied". So the obvious eligibility check, asking
+Stripe whether this customer was already discounted, answers no every cycle. A monthly
+subscriber who reopens the cancel flow rides half price indefinitely, and every renewal
+looks ordinary in the logs. Compounding it: `retention.coupon_offer` takes a **coupon**,
+and a coupon cannot be restricted to a customer, capped per customer, or deactivated —
+`max_redemptions` is a total across all customers and reading it is a race. Eligibility
+is a row in your database or it does not exist.
+
+**Under flexible `billing_mode`, a portal cancellation does not set
+`cancel_at_period_end`.** It sets `cancel_at` and leaves the flag `false`, so a billing
+page whose banner reads the boolean tells a customer who cancelled ten seconds ago that
+their plan renews. Nothing errors. Because `billing_mode` is fixed at creation, an
+established account holds both kinds of row at once.
+
+Both are now invariants with fixtures and a mutant each —
+`retention-offer-is-consumed-once` (mutant: no ledger, eligibility read from
+`subscription.discounts`) and `scheduled-cancellation-survives-billing-mode` (mutant:
+the flag alone). The pack goes 12 → 14 invariants, 45 → 57 assertions, 9 → 13 event
+bodies, 9 → 11 mutants, each still isolated by a fixture.
+
+### New: `references/cancellation-and-retention.md`
+
+The single home for cancellation and the save offer: the exact `flow_data` shape and why
+there is **no** `retention` field on the portal *configuration* (so a targeted offer
+exists only per session); the Dashboard "Retention Coupon" switch that offers every
+cancelling customer a discount with no code review and no test; the eligibility ledger
+and its four conditions; the absent event (`billing_portal.session.created` exists,
+`…completed` does not — absence of a cancellation is not a save); `discounts` on an
+update being a **replacement**, which silently deletes a negotiated discount; the five
+conditions under which the portal cancel page is not available at all, including a
+subscription schedule, which is how a downgrade-at-period-end implementation removes its
+own cancel page.
+
+Also recorded: discounts read through one more level since `2025-09-30.clover` —
+`discount.coupon` → `discount.source.coupon`, `promotion_code.coupon` →
+`promotion_code.promotion.coupon`, `subscription.discount` → `subscription.discounts[]`.
+All three fail as `undefined` rather than as an error.
+
+### The split behind it
+
+`stripe-billing/SKILL.md` was at ~4747 tokens against a 4750 working limit — three tokens
+of headroom, stated in the gate for exactly this moment. Cancellation moved into the new
+reference and three body code blocks that had a second home in
+`references/subscription-lifecycle.md` (get-or-create, the seat update, the refund
+compare-and-swap) now live only there: 4747 → 4683 tokens, 409 → 381 lines. The rule with
+two homes is the one that drifts at one of them.
+
+`references/stripe-agent-toolchain.md` re-read against plugin 0.6.1: Stripe ships **eight**
+agent skills now, not the seven this file listed, and a grep for `retention`, `coupon` and
+`churn` across all eight returns nothing about cancellation deflection — so the save offer
+is this skill's ground by absence rather than by preference, and that is now stated where
+the division of labour is.
+
+`package.json` also stopped describing six skills. There have been seven since v0.9.0, and
+`error-tracking` was missing from the sentence npm shows.
+
+
 ## v0.9.2 — the README stops claiming a command the package cannot run
 
 The README told a reader to run commands the published package cannot run: it ships no

package/README.md

@@ -1,5 +1,12 @@
 # sheleg-dev
 
+[![validate](https://github.com/ssheleg/sheleg-dev/actions/workflows/validate.yml/badge.svg)](https://github.com/ssheleg/sheleg-dev/actions/workflows/validate.yml)
+[![npm](https://img.shields.io/npm/v/%40ssheleg%2Fsheleg-dev)](https://www.npmjs.com/package/@ssheleg/sheleg-dev)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![site](https://img.shields.io/badge/docs-ssheleg.github.io-8ab0ff)](https://ssheleg.github.io/sshlg-skills/skills/sheleg-dev/)
+
+**[Docs, and all 8 skills →](https://ssheleg.github.io/sshlg-skills/)** · [this skill's page](https://ssheleg.github.io/sshlg-skills/skills/sheleg-dev/) · [follow @sshlg93 on X](https://x.com/intent/follow?screen_name=sshlg93)
+
 The integration layer a product reaches once it has users: **money in, tracking,
 sign-in, and speed.**
 

package/SECURITY.md

@@ -17,8 +17,8 @@ documents name that does not exist here.
 
 ## What ships, and what of it executes
 
-`git ls-files plugins` returns **56 files: 34 markdown, one plugin manifest, three
-files of the manual gate, and 18 files of money fixtures.** Two of the seven skills now
+`git ls-files plugins` returns **61 files: 35 markdown, one plugin manifest, three
+files of the manual gate, and 22 files of money fixtures.** Two of the seven skills now
 ship code you can run — the assertion packs under `fixtures/` — and that is a change
 from every release before v0.7.0, so it is stated here rather than left to be noticed.
 They run only when you invoke them, read only the JSON fixtures beside them, and open
@@ -26,20 +26,20 @@ no socket; the greps below prove all three.
 
 | Component | Count | Runtime behavior |
 |---|---|---|
-| `SKILL.md`, one per skill | 6 | Text. Read by the agent, executes nothing. |
-| `references/` files, loaded on demand | 25 | Text. Same. |
+| `SKILL.md`, one per skill | 7 | Text. Read by the agent, executes nothing. |
+| `references/` files, loaded on demand | 26 | Text. Same. |
 | `plugins/sheleg-dev/.claude-plugin/plugin.json` | 1 | Manifest read by Claude Code. |
 | `plugins/sheleg-dev/hooks/hooks.json` | 1 | Hook manifest read by Claude Code. Declares one `PreToolUse` hook and no `if` filter. |
 | `plugins/sheleg-dev/hooks/money-gate.js` | 1 | Runs on a tool call, when the plugin is enabled. Requires `path` and its own decision module — nothing else. Reads stdin, writes one JSON line, exits 0 on every path. |
 | `plugins/sheleg-dev/hooks/lib/moneygate.js` | 1 | Pure. Payload and environment in, verdict out. No `require` at all, no filesystem, no clock. |
 | `bin/sheleg-dev.js` — the npm installer | 1 | Runs only when you invoke it. Node built-ins only: `fs`, `path`, `os`. |
 | `install.sh` — the shell installer | 1 | **Not in the tarball** — `files` ships `bin/` and `plugins/`, so this one reaches you only through a clone. Runs when you invoke it. Coreutils only: `cd`, `pwd`, `dirname`, `basename`, `mkdir`, `rm`, `cp`, `echo`. It is the destructive channel: `rm -rf` per skill, then `cp -R`. |
-| `plugins/sheleg-dev/skills/*/fixtures/*.json` — webhook payloads | 12 | Data. Placeholder ids only; no key, token, signing secret or real customer id. |
+| `plugins/sheleg-dev/skills/*/fixtures/*.json` — webhook payloads | 16 | Data. Placeholder ids only; no key, token, signing secret or real customer id. |
 | `plugins/sheleg-dev/skills/*/fixtures/*.mjs` — the assertion packs and their reference implementations | 4 | Runs only when you invoke it. Reads the JSON beside it with `readFileSync` and nothing else: no `child_process`, no `fetch`, no write, no `process.env`. |
 | `plugins/sheleg-dev/skills/*/fixtures/manifest.json` and its `README.md` | 4 | Text. The invariant-to-fixture-to-document map, which `test/validate.py` reads. |
 
 The published tarball is `bin/` and `plugins/` plus `README.md`, `CHANGELOG.md`,
-`SECURITY.md`, `LICENSE` and `package.json` — 62 files, listed by
+`SECURITY.md`, `LICENSE` and `package.json` — 67 files, listed by
 `npm pack --dry-run`. `install.sh`, `test/`, `docs/` and `CONTRIBUTING.md` are **not**
 in it; `test/validate.py` now refuses a path these shipped documents name that the
 tarball does not carry, because resolving in a clone is the wrong question for a
@@ -169,10 +169,10 @@ git clone https://github.com/ssheleg/sheleg-dev && cd sheleg-dev
 # self-describing documents name -- this file included.
 python3 test/validate.py
 
-# The shipped payload: 56 files.
+# The shipped payload: 61 files.
 git ls-files plugins
 
-# 22 lines: the plugin manifest, the three files of the manual gate, and the 18
+# 26 lines: the plugin manifest, the three files of the manual gate, and the 22
 # files of money fixtures. Everything else in the payload is markdown.
 git ls-files plugins | grep -v '\.md$'
 
@@ -206,6 +206,6 @@ grep -nE "require|child_process|exec|spawn|fetch|socket|rm -rf|cp -R|copyFileSyn
 # Live-key shapes across the skill payload: one line, and it is a placeholder.
 grep -rnE "sk_live_[A-Za-z0-9]|rk_live_[A-Za-z0-9]|whsec_[A-Za-z0-9]{8}|BEGIN [A-Z ]*PRIVATE KEY" plugins
 
-# What npm publishes, and nothing else: 62 files.
+# What npm publishes, and nothing else: 67 files.
 npm pack --dry-run
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ssheleg/sheleg-dev",
-  "version": "0.9.2",
-  "description": "Six integration skills for the layer a product reaches once it has users: Stripe subscription billing, crypto payments, ad and conversion tracking under Consent Mode v2, Google sign-in and the wider Google auth surface, and Core Web Vitals. This package is the installer CLI.",
+  "version": "0.10.0",
+  "description": "Seven integration skills for the layer a product reaches once it has users: Stripe subscription billing and cancellation retention, crypto payments, ad and conversion tracking under Consent Mode v2, Google sign-in and the wider Google auth surface, error tracking, and Core Web Vitals. This package is the installer CLI.",
   "bin": {
     "sheleg-dev": "bin/sheleg-dev.js"
   },

package/plugins/sheleg-dev/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "sheleg-dev",
   "displayName": "Sheleg Dev",
   "description": "The integration layer a product needs once it has users: Stripe subscription billing reconciled into your own database, crypto payments that survive over-payment and duplicate webhooks, ad and conversion tracking under Consent Mode v2, Google sign-in with the account-linking guards, the wider Google auth surface, and Core Web Vitals work that moves the score, and Sentry error tracking wired so it does not forward your own credentials to a third party and so a stack trace names the commit that caused it.",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/sheleg-dev/skills/stripe-billing/SKILL.md

@@ -2,18 +2,19 @@
 name: stripe-billing
 description: >-
   Use when connecting a product to Stripe, or auditing a live integration:
-  checkout sessions, subscriptions and renewals, seats, proration, refunds, the
-  portal, and the webhook that turns a payment into an entitlement in the
-  application's own database. Covers Stripe's agent toolchain (CLI, MCP,
-  skills), the pinned API version and SDK retries, product-to-price resolution
-  across test and live, the get-or-create customer race, metadata written
-  twice, claim-first webhook idempotency, what invoice billing_reason decides,
-  cumulative refund totals, write ordering across two systems with compensating
-  reverts, reconciliation, and price drift only customers see. Triggers - "add
+  checkout, renewals, seats, proration, refunds, cancellation and the
+  coupon offered at the cancel step, the portal, and the webhook that
+  turns a payment into an entitlement in your database. Covers Stripe's
+  agent toolchain, the pinned API version and SDK retries, price
+  resolution across modes, claim-first webhook idempotency, what invoice
+  billing_reason decides, cumulative refunds, the cancellation field
+  flexible billing_mode moved, retention eligibility Stripe cannot
+  express, and write ordering with compensating reverts. Triggers - "add
   Stripe", "Stripe checkout", "subscription billing", "webhook signature",
-  "invoice.paid", "proration", "seats", "refund", "подключить Stripe", "оплата
-  подпиской", "вебхук Stripe", "биллинг". Not for choosing between Stripe
-  products (stripe-best-practices) or reading Stripe docs (stripe-docs).
+  "invoice.paid", "proration", "refund", "cancel subscription", "retention
+  coupon", "подключить Stripe", "оплата подпиской", "вебхук Stripe",
+  "скидка при отмене", "биллинг". Not for choosing between Stripe products
+  (stripe-best-practices) or reading Stripe docs (stripe-docs).
 license: MIT
 ---
 
@@ -28,8 +29,7 @@ callback that arrived twice, the renewal that granted a month of product for a
 $0.40 proration invoice, the upgrade that charged the card and then failed to
 write the row.
 
-This skill is that seam. For **which** Stripe primitive to use (Checkout vs
-PaymentIntents, Connect, Tax, usage-based billing) the official
+This skill is that seam. For **which** Stripe primitive to use, the official
 `stripe-best-practices` skill is the authority and wins any disagreement; for
 lookups, `stripe-docs`. Examples are TypeScript; the rules are
 language-neutral.
@@ -38,12 +38,13 @@ Deep material, loaded on demand:
 
 | Read | When |
 |---|---|
-| [`references/stripe-agent-toolchain.md`](references/stripe-agent-toolchain.md) | starting from nothing, or about to guess an API shape — CLI, MCP tools, skills index, key handling |
+| [`references/stripe-agent-toolchain.md`](references/stripe-agent-toolchain.md) | starting from nothing, or about to guess an API shape — CLI, MCP, skills index, key handling |
 | [`references/webhook-events.md`](references/webhook-events.md) | writing or reviewing the handler — event catalogue, payload shapes, ordering, failure semantics |
-| [`references/subscription-lifecycle.md`](references/subscription-lifecycle.md) | implementing checkout, verify, renewal, seats, plan change, trials, cancellation, clawback |
+| [`references/subscription-lifecycle.md`](references/subscription-lifecycle.md) | implementing checkout, verify, renewal, seats, plan change, trials, clawback |
+| [`references/cancellation-and-retention.md`](references/cancellation-and-retention.md) | implementing cancel or reactivation, or offering a coupon at the cancel step |
 | [`references/price-integrity.md`](references/price-integrity.md) | pricing lives in more than one file, or an advertised price must be proved against Stripe |
 | [`references/testing-and-local-dev.md`](references/testing-and-local-dev.md) | local webhooks and mocks, and the shipped `fixtures/` — the suite, already written |
-| [`references/provider-concentration.md`](references/provider-concentration.md) | growing revenue, opening a second market, separating involuntary churn, or asking what happens if the payment account is limited |
+| [`references/provider-concentration.md`](references/provider-concentration.md) | growing revenue, opening a second market, separating involuntary churn, or if the payment account is limited |
 
 ---
 
@@ -130,25 +131,12 @@ replaced when you reprice; products are stable.
 ## Get-or-create customer is a race
 
 Two tabs, two requests, two customers, and the second silently owns the
-subscription the first is charging.
-
-```ts
-const customer = await stripe.customers.create({ email, metadata: { userId } });
-
-const { count } = await db.user.updateMany({          // write only if nobody did
-  where: { id: userId, stripeCustomerId: null },
-  data: { stripeCustomerId: customer.id },
-});
-
-if (count === 0) {                                    // lost the race
-  await stripe.customers.del(customer.id).catch(log); // delete the orphan
-  return (await db.user.findUnique({ where: { id: userId } }))!.stripeCustomerId!;
-}
-return customer.id;
-```
-
-Before creating, retrieve the stored id and treat `resource_missing` or
-`deleted: true` as "create a new one" — the normal state after a key rotation.
+subscription the first is charging. Create, then claim the id with a conditional
+update; if the update matched no row you lost the race, so delete the orphan
+customer and read the winner's id. Before creating, retrieve the stored id and
+treat `resource_missing` or `deleted: true` as "create a new one" — the normal
+state after a key rotation. The code is in
+[`references/subscription-lifecycle.md`](references/subscription-lifecycle.md).
 
 ---
 
@@ -291,28 +279,22 @@ Stripe creates every subscription in one of two billing modes. The choice is mad
 at `subscriptions.create` (or `subscription_data` on a Checkout session), **cannot
 be reversed**, and Stripe recommends **flexible** for new subscriptions.
 
-It is in the body rather than a reference because it changes the arithmetic the
-next two sections teach: under flexible mode a credit proration is computed from
-the amount **originally debited**, so one change can emit **several** credit
-prorations where classic emitted one. Code that takes `[0]` of the proration lines,
-or assumes one credit per change, breaks quietly in the refund clawback path — the
-one place here where a wrong number is money. The detail is in
-`references/subscription-lifecycle.md`; choosing between the modes is a product
-decision that `stripe-best-practices` owns.
+It is in the body because it changes arithmetic the next sections teach: under
+flexible mode a credit proration is computed from the amount **originally
+debited**, so one change can emit **several** credit prorations where classic
+emitted one. Code that takes `[0]` of the proration lines breaks quietly in the
+clawback path — the one place here where a wrong number is money. It also decides
+which field records a scheduled cancellation. Choosing between the modes is a
+product decision `stripe-best-practices` owns.
 
 ## Seats and proration
 
-```ts
-await stripe.subscriptions.update(subId, {
-  items: [{ id: itemId, quantity: newQuantity }],
-  proration_behavior: "always_invoice",     // charge the difference now
-  payment_behavior: "error_if_incomplete",  // a declined card FAILS this call
-});
-```
 
 - `proration_behavior`: `always_invoice` bills now, `create_prorations` defers
   to the next invoice, `none` adjusts nothing — the right choice for a *revert*.
-- **`error_if_incomplete` on upgrades.** Without it a declined card leaves the
+  The call, with its compensating revert, is in
+  [`references/subscription-lifecycle.md`](references/subscription-lifecycle.md).
+- **`payment_behavior: "error_if_incomplete"` on upgrades.** Without it a declined card leaves the
   subscription upgraded and unpaid while your database agrees with the upgrade.
   Catch `StripeCardError` and answer 402.
 - **Write ordering:** Stripe first, then your database. If the database write
@@ -326,65 +308,56 @@ await stripe.subscriptions.update(subId, {
 
 ---
 
-## Cancellation
+## Cancellation, and the offer that deflects it
 
-- **`cancel_at_period_end: true`** is the default — the user keeps what they
-  paid for. `status` stays `active`; a separate flag drives the UI.
+- **At period end is the default** — the user keeps what they paid for and
+  `status` stays `active`. Under **flexible** `billing_mode` a portal
+  cancellation sets `cancel_at` and leaves `cancel_at_period_end` **false**, so a
+  banner reading that boolean tells a customer who cancelled ten seconds ago that
+  their plan renews. Store the timestamp, derived from both fields.
 - **Do the teardown in `customer.subscription.deleted`**, never beside the API
   call, so one path serves your UI, the portal and dunning alike.
-- **The portal is a second writer.** Everything a user does there reaches you
-  only as a webhook; a billing page that assumes otherwise goes stale in a week.
 - On `invoice.payment_failed`, mark `past_due` and notify — do not cancel.
-  Stripe's dunning decides the retries and the terminal state; cancelling early
-  cancels customers whose next attempt would have cleared.
+  Stripe's dunning decides the retries and the terminal state.
+- **A save offer's eligibility is yours.** Stripe's cancel page shows a coupon
+  card when you pass `flow_data.subscription_cancel.retention`, but a coupon
+  cannot be restricted to one customer and a `duration=once` discount leaves
+  `subscription.discounts` once its invoice finalizes. Ask Stripe whether this
+  customer was already discounted and the answer is no, every month, forever.
 
----
+Both, with the code:
+[`references/cancellation-and-retention.md`](references/cancellation-and-retention.md).
 
 ## Refunds arrive cumulative
 
 `charge.amount_refunded` is **the total refunded so far**, not this refund. Two
-partial refunds deliver `4000` then `9000`; read as an increment, that claws
-back $130 against a $90 charge.
-
-```ts
-const totalRefunded = charge.amount_refunded / 100;
-const increment = totalRefunded - stored.refundedTotal;
-if (increment <= 0) return;                     // replay or reorder
-
-const { count } = await db.purchase.updateMany({
-  where: { id: stored.id, refundedTotal: stored.refundedTotal },   // compare-and-swap
-  data:  { refundedTotal: totalRefunded },
-});
-if (count === 0) return;                        // a concurrent delivery won
-await clawBack(increment);                      // clamp at zero; log if it would go negative
-```
+partial refunds deliver `4000` then `9000`; read as an increment, that claws back
+$130 against a $90 charge. Compute the increment against a stored total and write
+it with a compare-and-swap, so a concurrent delivery loses rather than clawing
+back twice — the code is in
+[`references/subscription-lifecycle.md`](references/subscription-lifecycle.md).
 
 A refund belongs either to a one-off payment (find it by `payment_intent`) or to
 a subscription invoice (no purchase row — resolve `charge.invoice` → invoice →
 subscription). Handle both, or subscription refunds silently leave the customer
 holding the product.
 
----
-
 ## Reconciliation
 
-Webhooks are best-effort and outages are not hypothetical. Run a job that asks
-Stripe what is true and repairs the difference:
+Webhooks are best-effort and outages are not hypothetical. Run a job that lists
+subscriptions with `status: "all"`, creates what is missing, and updates status,
+period, quantity and price where they differ — sequentially, because each
+iteration opens a transaction and may call an external API. Any grant it performs
+reuses the webhook's idempotency marker, or a nightly job becomes a nightly gift.
 
-- list subscriptions with `status: "all"`; create what is missing, update
-  status, period, quantity and price where they differ;
-- mark local rows canceled when Stripe has no such subscription — **excluding
-  rows that were never Stripe's**. Comped, manual and other-provider plans carry
-  synthetic ids, and cancelling them is a self-inflicted outage;
-- keep the loop **sequential**: each iteration opens a transaction and may call
-  an external API, and `Promise.all` exhausts the connection pool under exactly
-  the conditions you wrote the job for;
-- any grant it performs reuses the webhook's idempotency marker, or a nightly
-  job becomes a nightly gift.
+The guard that matters: mark local rows canceled when Stripe has no such
+subscription, **excluding rows that were never Stripe's**. Comped, manual and
+other-provider plans carry synthetic ids, and cancelling them is a self-inflicted
+outage. The code, and the "Sync now" button it doubles as, are in
+[`references/subscription-lifecycle.md`](references/subscription-lifecycle.md).
 
-The same function is the "Sync now" button on the billing page. Money is minor
-units: convert once, at the boundary, and compare in integer cents —
-`Math.abs(20.83 - 20.84) > 0.01` is `true` in floating point.
+Money is minor units: convert once, at the boundary, and compare in integer cents
+— `Math.abs(20.83 - 20.84) > 0.01` is `true` in floating point.
 
 ---
 
@@ -392,10 +365,10 @@ units: convert once, at the boundary, and compare in integer cents —
 
 One provider for card payments is a single point of failure for revenue, and the
 decision belongs to the business rather than to this skill. What the code owes it
-is a seam: keep the charge behind an interface, keep the customer id yours rather
-than Stripe's, and never let a Stripe object id be the only key to a paying
-account. The full argument, the migration shapes and what a second provider costs
-are in `references/provider-concentration.md`.
+is a seam: keep the charge behind an interface, keep the customer id yours, and
+never let a Stripe object id be the only key to a paying account. The argument,
+the migration shapes and the cost are in
+[`references/provider-concentration.md`](references/provider-concentration.md).
 
 ## Local development and the test matrix
 

package/plugins/sheleg-dev/skills/stripe-billing/fixtures/README.md

@@ -1,15 +1,16 @@
 # Money fixtures and the assertion pack
 
 **Copy this whole directory into your repository.** It is the executable half of what
-`SKILL.md` and `references/webhook-events.md` state in prose: nine real Stripe event
-bodies, twelve invariants a correct webhook handler must hold — 45 assertions between
+`SKILL.md`, `references/webhook-events.md` and
+`references/cancellation-and-retention.md` state in prose: thirteen real Stripe event
+bodies, fourteen invariants a correct webhook handler must hold — 57 assertions between
 them — and a self-test that breaks the handler one rule at a time so you can watch each
 assertion fail on its own.
 
 Two commands, no dependencies, no network, no key:
 
 ```bash
-node assert-money-invariants.mjs              # 12 invariants / 45 assertions
+node assert-money-invariants.mjs              # 14 invariants / 57 assertions
 node assert-money-invariants.mjs --self-test  # break one rule at a time; EACH ASSERTION must go red
 ```
 
@@ -42,6 +43,10 @@ Every file is a webhook event body shaped the way Stripe sends it on
 | `checkout-session-completed-async-unpaid.json` | a bank-debit session, `payment_status: "unpaid"` | the session completed and the money has not moved |
 | `checkout-session-async-payment-failed.json` | days later: it never cleared | the redirect proved a browser and nothing else |
 | `checkout-session-completed-paid.json` | a card session that did clear | the positive control: without it, a handler refusing every session would pass the two above |
+| `customer-discount-created-retention.json` | the save offer redeemed: a `duration=once`, 50%-off coupon read through `source.coupon` | there is no portal event for a completed flow, so this is the ONLY signal that a cancellation was deflected rather than abandoned |
+| `customer-subscription-updated-discount-consumed.json` | the discounted invoice has finalized and `discounts` is `[]` again, with the old value in `previous_attributes` | Stripe's answer to "was this customer already discounted" is now no — the fixture that makes the re-offer loop visible |
+| `customer-subscription-updated-cancel-flexible.json` | a portal cancellation under **flexible** `billing_mode`: `cancel_at` set, `cancel_at_period_end` **false** | the flag alone reads as "renews" on a subscription Stripe will end |
+| `customer-subscription-updated-cancel-classic.json` | the same cancellation under **classic**: both fields set | the control — both readings agree here, which is why the flag alone survived until flexible mode |
 
 The refund pair resolves to a **purchase row**, not a Stripe object: a $90 credit pack with
 `refundedTotal: 0`, seeded by the assertion pack because it is your database's, not
@@ -65,6 +70,8 @@ Run `node assert-money-invariants.mjs` and each line names the invariant it hold
 | `unpaid-session-grants-nothing` | unpaid + failed | grants the product and reports a purchase for a charge that failed |
 | `paid-session-grants-once` | `checkout-session-completed-paid.json` | answers 200 and writes nothing — the positive control, without which refusing every session would pass the row above |
 | `conversion-id-survives-the-session` | cycle | generates its own conversion id, and the browser event never deduplicates against it |
+| `retention-offer-is-consumed-once` | discount created + discount consumed | offers 50% off again every cycle, because it asked Stripe instead of its own ledger |
+| `scheduled-cancellation-survives-billing-mode` | cancel flexible + cancel classic | tells a customer who cancelled ten seconds ago that their plan renews |
 
 ## What each mutant deletes
 
@@ -82,6 +89,8 @@ a line a generated handler routinely omits:
 | `conversion-id-from-metadata` | reading `conversionEventId` out of the subscription metadata | generates an id at emission time |
 | `grant-on-renewal` | the grant itself | treats `invoice.paid` as information |
 | `grant-on-checkout` | the first grant | answers 200 to `checkout.session.completed` and writes nothing |
+| `retention-eligibility` | the whole offer ledger — the row written before the session, the history read, and the redemption mark | asks `subscription.discounts` whether this customer was already discounted, which a `duration=once` discount empties as soon as its invoice finalizes |
+| `cancellation-timestamp` | `if (sub.cancel_at) return sub.cancel_at` ahead of the flag | reads `cancel_at_period_end` alone, correct for classic rows and wrong for every flexible one |
 
 ## What masks what
 
@@ -105,7 +114,7 @@ separate them are here because of it rather than by design.
 ## Placeholders
 
 Every id spells `PLACEHOLDER`: `sub_PLACEHOLDER_alice`, `ch_PLACEHOLDER_creditpack`,
-`cus_PLACEHOLDER_bob`. There is no key, token, signing secret or real customer id anywhere
+`cus_PLACEHOLDER_bob`, `cpn_PLACEHOLDER_save50`. There is no key, token, signing secret or real customer id anywhere
 in this directory — signature verification happens before any of this and is
 `SKILL.md`'s subject, not these fixtures'. The email is `placeholder@example.invalid` and
 the one 64-hex string is its SHA-256.

package/plugins/sheleg-dev/skills/stripe-billing/fixtures/assert-money-invariants.mjs

@@ -43,6 +43,10 @@ const REFUND_REMAINDER = 'charge-refunded-remainder.json';
 const SESSION_UNPAID = 'checkout-session-completed-async-unpaid.json';
 const SESSION_FAILED = 'checkout-session-async-payment-failed.json';
 const SESSION_PAID = 'checkout-session-completed-paid.json';
+const DISCOUNT_CREATED = 'customer-discount-created-retention.json';
+const DISCOUNT_CONSUMED = 'customer-subscription-updated-discount-consumed.json';
+const CANCEL_FLEXIBLE = 'customer-subscription-updated-cancel-flexible.json';
+const CANCEL_CLASSIC = 'customer-subscription-updated-cancel-classic.json';
 
 /** A fresh store and handler per invariant: no assertion inherits another's state. */
 function harness(without = []) {
@@ -285,6 +289,68 @@ export const INVARIANTS = [
       assert.equal(conversion.currency, 'USD');
     },
   },
+  {
+    id: 'retention-offer-is-consumed-once',
+    fixtures: [DISCOUNT_CREATED, DISCOUNT_CONSUMED],
+    states: 'a customer who took the save offer is not offered it again after the '
+      + 'duration=once discount has left subscription.discounts',
+    breaks: ['retention-eligibility'],
+    async run({ store, handler, assert }) {
+      const before = { id: 'sub_PLACEHOLDER_alice', status: 'active', discounts: [] };
+
+      const first = await handler.offerRetention('cus_PLACEHOLDER_alice', before);
+      // unmutated, and the positive control: every mutant here still makes the FIRST
+      // offer. Without it, a handler that offers nobody anything would pass the rest.
+      assert.unmutated.equal((first || {}).offerId, 'cancel-50-once');
+      assert.equal(store.retentionOffers.length, 1,
+        'the offer was shown and no row recorded it — an offer nobody wrote down cannot '
+        + 'be counted, and the count is the only thing that stops the loop');
+
+      await handler.deliver(fixture(DISCOUNT_CREATED));
+      assert.equal(store.saves.length, 1,
+        'the redemption was not recorded as a save — there is no portal event for a '
+        + 'completed flow, so nothing else will ever say the cancellation was deflected');
+      assert.equal((store.retentionOffers[0] || {}).redeemedAt, 1767225000);
+
+      // The discounted invoice finalizes and Stripe REMOVES the discount from the array.
+      const consumed = fixture(DISCOUNT_CONSUMED);
+      await handler.deliver(consumed);
+      const mirror = store.subscriptions.get('sub_PLACEHOLDER_alice') || {};
+      assert.unmutated.deepEqual(mirror.discountIds, [],
+        'the fixture is the moment the duration=once discount leaves the subscription');
+
+      const second = await handler.offerRetention('cus_PLACEHOLDER_alice', consumed.data.object);
+      assert.equal(second, null,
+        'the offer was made a second time — one cancel-flow visit per cycle then rides '
+        + 'half price forever, and every renewal looks ordinary in the logs');
+      assert.equal(store.retentionOffers.length, 1, 'a second offer row was opened');
+    },
+  },
+  {
+    id: 'scheduled-cancellation-survives-billing-mode',
+    fixtures: [CANCEL_FLEXIBLE, CANCEL_CLASSIC],
+    states: 'a portal cancellation is stored under BOTH billing modes — flexible sets '
+      + 'cancel_at and leaves cancel_at_period_end false',
+    breaks: ['cancellation-timestamp'],
+    async run({ store, handler, assert }) {
+      await handler.deliver(fixture(CANCEL_FLEXIBLE));
+      const flexible = store.subscriptions.get('sub_PLACEHOLDER_alice') || {};
+      // unmutated: no rule here varies the mode or the reason the customer gave.
+      assert.unmutated.equal(flexible.billingMode, 'flexible');
+      assert.unmutated.equal(flexible.cancellationFeedback, 'too_expensive');
+      assert.equal(flexible.cancelAt, 1769904000,
+        'a cancellation scheduled under flexible billing_mode was stored as "not '
+        + 'cancelling": the banner tells a customer who cancelled ten seconds ago that '
+        + 'their plan renews, and nothing errors');
+
+      await handler.deliver(fixture(CANCEL_CLASSIC));
+      const classic = store.subscriptions.get('sub_PLACEHOLDER_bob') || {};
+      // unmutated, and deliberately so: this is the control. Both readings agree on a
+      // classic row, which is exactly why the flag alone survived until flexible mode.
+      assert.unmutated.equal(classic.billingMode, 'classic');
+      assert.unmutated.equal(classic.cancelAt, 1769904000);
+    },
+  },
 ];
 
 // ------------------------------------------------- one assertion, one measurement

package/plugins/sheleg-dev/skills/stripe-billing/fixtures/customer-discount-created-retention.json

@@ -0,0 +1,47 @@
+{
+  "id": "evt_PLACEHOLDER_discount_created",
+  "object": "event",
+  "api_version": "2026-07-29.dahlia",
+  "created": 1767225000,
+  "livemode": false,
+  "pending_webhooks": 1,
+  "request": { "id": null, "idempotency_key": null },
+  "type": "customer.discount.created",
+  "data": {
+    "object": {
+      "id": "di_PLACEHOLDER_save50",
+      "object": "discount",
+      "customer": "cus_PLACEHOLDER_alice",
+      "customer_account": null,
+      "subscription": "sub_PLACEHOLDER_alice",
+      "subscription_item": null,
+      "invoice": null,
+      "invoice_item": null,
+      "checkout_session": null,
+      "promotion_code": null,
+      "start": 1767225000,
+      "end": null,
+      "source": {
+        "type": "coupon",
+        "coupon": {
+          "id": "cpn_PLACEHOLDER_save50",
+          "object": "coupon",
+          "name": "50% off your next invoice",
+          "percent_off": 50,
+          "amount_off": null,
+          "currency": null,
+          "duration": "once",
+          "duration_in_months": null,
+          "max_redemptions": null,
+          "times_redeemed": 1,
+          "redeem_by": null,
+          "applies_to": null,
+          "valid": true,
+          "livemode": false,
+          "created": 1767224000,
+          "metadata": {}
+        }
+      }
+    }
+  }
+}