@ssheleg/sheleg-dev 0.11.8 → 0.13.0

package/plugins/sheleg-dev/skills/stripe-billing/fixtures/reference-handler.mjs

@@ -21,6 +21,32 @@
 
 export const RULES = Object.freeze([
   'claim',
+  // A claim records RECEIPT, and only `completeEvent` records completion. Without this
+  // rule the row never leaves 'processing', so a retry arriving after the claim expiry
+  // takes the event over and grants a second time — received quietly read as completed.
+  'claim-completion',
+  // The recovery half of the same split: a 'processing' claim older than CLAIM_TTL_MS
+  // belonged to a worker that died between receipt and completion, and a retry may take
+  // it over. Without this rule the crashed claim answers "in flight" forever and the
+  // payment is swallowed.
+  'claim-expiry',
+  // Entitlement, dedup marker, completion and the outbox rows commit TOGETHER.
+  // Without this rule a crash mid-application leaves the grant applied and the
+  // completion missing — half a payment, which no retry can see or repair.
+  'atomic-application',
+  // The outbox delivers at least once, so the CONSUMER dedups on its own key
+  // (event id + effect kind). Without this rule a redelivered outbox row sends
+  // the renewal notice and fires the conversion a second time.
+  'outbox-consumer-key',
+  // The period grant is claimed by an ATOMIC keyed insert (subscription + item
+  // + period), not a read-then-mark. Without this rule two concurrent grants of
+  // one period — a webhook and the reconciler, say — both pass the read and
+  // both credit: the read is a round trip, and a round trip is a race.
+  'grant-key-atomic',
+  // A serialization conflict retries, BOUNDED, inside the same claim. Without
+  // this rule a conflicted transaction is dropped and the route still answers
+  // 200 — the renewal silently never lands, and Stripe was told it did.
+  'tx-retry-bounded',
   'billing-reason',
   'grant-marker',
   'ordering',
@@ -50,6 +76,11 @@ export const RULES = Object.freeze([
 /** Credits one paid period is worth. Arbitrary; the assertions count grants, not credits. */
 export const CREDITS_PER_PERIOD = 500;
 
+/** How long a 'processing' claim may sit before a retry may take it over. In production:
+ *  comfortably longer than your slowest handler run (say, twice the route timeout). The
+ *  store keeps a logical clock, so the assertions can age a claim without waiting. */
+export const CLAIM_TTL_MS = 5 * 60 * 1000;
+
 /** The save offer this handler is willing to make. Yours, not Stripe's -- a coupon cannot
  *  be restricted to one customer, so the identity of the offer has to live on your side. */
 export const RETENTION_OFFER_ID = 'cancel-50-once';
@@ -59,29 +90,123 @@ export const RETENTION_DECLINE_LIMIT = 2;
 
 const tick = () => new Promise((resolve) => setImmediate(resolve));
 
+/** The crash simulation's marker: a process death, not a thrown handler error. */
+class SystemError_ extends Error {}
+
+/** A database serialization failure — retryable by definition, never a verdict. */
+class SerializationConflict_ extends Error {}
+
+/** How many serialization conflicts one delivery absorbs before answering 5xx. */
+export const TX_RETRIES = 3;
+
 export function createStore() {
   return {
-    processedEvents: new Set(),
+    processedEvents: new Map(), // event id -> { state: 'processing'|'completed', claimedAt }
+    clock: 0, // logical ms; advanced by tests, never read from the wall
+    advanceClock(ms) {
+      this.clock += ms;
+    },
     grantedPeriods: new Map(), // subscription id -> Set of period starts already granted
+    grantKeys: new Set(), // atomic per-period claim keys: sub:item:period
+    grantLedger: [], // one row per granted period: { key, subId, itemId, invoiceId, periodStart }
     subscriptions: new Map(), // the mirrored row: period, status, quantity, price
     purchases: new Map(), // payment intent -> { amount, refundedTotal } (minor units)
     credits: new Map(), // user id -> integer
     grants: [], // one row per grant actually applied
     clawbacks: [], // { paymentIntent, amount } in minor units
     conversions: [], // what the server sent to the ad platforms
+    outbox: [], // side-effect rows written IN the grant transaction: { key, apply, state }
+    failNextTransactions: 0, // test hook: how many commits raise a serialization conflict
+    txAttempts: 0, // how many transaction attempts actually ran
+    sentKeys: new Set(), // the consumer's own dedup — survives a redelivered row
     retentionOffers: [], // { customerId, offerId, couponId, subscriptionId, redeemedAt }
     saves: [], // one row per cancellation deflected, recorded from the discount event
     notifications: [], // side effects that must not run twice
     log: [],
 
-    /** An INSERT on a primary key: atomic, and the only claim that survives a race. */
+    /** All-or-nothing for the business application: what the fixture calls a
+     *  transaction. A crash inside the callback restores every collection, so a
+     *  half-applied grant cannot exist — which is the property the retry relies on. */
+    snapshot() {
+      return {
+        processedEvents: new Map([...this.processedEvents]
+          .map(([k, v]) => [k, { ...v }])),
+        grantedPeriods: new Map([...this.grantedPeriods].map(([k, v]) => [k, new Set(v)])),
+        grantKeys: new Set(this.grantKeys),
+        grantLedger: this.grantLedger.map((r) => ({ ...r })),
+        subscriptions: new Map([...this.subscriptions].map(([k, v]) => [k, { ...v }])),
+        purchases: new Map([...this.purchases].map(([k, v]) => [k, { ...v }])),
+        credits: new Map(this.credits),
+        grants: this.grants.slice(),
+        clawbacks: this.clawbacks.slice(),
+        conversions: this.conversions.slice(),
+        retentionOffers: this.retentionOffers.map((o) => ({ ...o })),
+        saves: this.saves.slice(),
+        notifications: this.notifications.slice(),
+        outbox: this.outbox.map((r) => ({ ...r })),
+        sentKeys: new Set(this.sentKeys),
+        log: this.log.slice(),
+      };
+    },
+    restore(snap) {
+      Object.assign(this, snap);
+    },
+
+    /** An INSERT on a primary key: atomic, and the only claim that survives a race.
+     *  The row it writes says 'processing' — a RECEIPT. What the caller does with an
+     *  existing row is a decision about states, so this returns one:
+     *  'claimed' (new row), 'completed' (real duplicate), 'expired' (a worker died
+     *  holding it), 'in_flight' (someone fresh is on it — answer retry-later). */
     claimEvent(id) {
-      if (this.processedEvents.has(id)) return false;
-      this.processedEvents.add(id);
+      const row = this.processedEvents.get(id);
+      if (!row) {
+        this.processedEvents.set(id, { state: 'processing', claimedAt: this.clock });
+        return 'claimed';
+      }
+      if (row.state === 'completed') return 'completed';
+      return this.clock - row.claimedAt >= CLAIM_TTL_MS ? 'expired' : 'in_flight';
+    },
+    /** The takeover: an UPDATE guarded by the same staleness test it was granted for —
+     *  atomic, so two retries racing for one corpse cannot both win. */
+    reclaimEvent(id) {
+      const row = this.processedEvents.get(id);
+      if (!row || row.state !== 'processing'
+          || this.clock - row.claimedAt < CLAIM_TTL_MS) return false;
+      row.claimedAt = this.clock;
       return true;
     },
+    /** Receipt becomes completion, explicitly — inside the grant transaction, so a row
+     *  that says 'completed' is one whose business write committed. */
+    completeEvent(id) {
+      const row = this.processedEvents.get(id);
+      if (row && row.state === 'processing') {
+        row.state = 'completed';
+        row.completedAt = this.clock;
+      }
+    },
+    /** Only for a handler that THREW and answered 5xx: the claim goes back so the retry
+     *  need not wait out the expiry. A crashed worker never reaches this line — that is
+     *  what the expiry is for. */
     releaseEventClaim(id) {
-      this.processedEvents.delete(id);
+      const row = this.processedEvents.get(id);
+      if (row && row.state === 'processing') this.processedEvents.delete(id);
+    },
+
+    /** The DATABASE arbitrates: an INSERT on a UNIQUE period-grant key.
+     *  Synchronous — no round trip between the check and the write, which is the
+     *  whole difference from readGrantedPeriods-then-mark. The ledger row carries
+     *  subscription, item, invoice and period; UNIQUENESS is (subscription,
+     *  period) — this reference models one plan item per subscription, and a
+     *  multi-item subscription widens the key with the item. The invoice is
+     *  provenance, never part of the uniqueness: a second invoice for one period
+     *  must not grant the period twice. */
+    claimPeriodGrant(subId, itemId, invoiceId, periodStart) {
+      const key = `${subId}:${periodStart}`;
+      if (this.grantKeys.has(key)) return false;
+      this.grantKeys.add(key);
+      this.grantLedger.push({ key, subId, itemId, invoiceId, periodStart });
+      this.markPeriodGranted(subId, periodStart);   // the view existing readers use
+      return true;
     },
 
     async readGrantedPeriods(subId) {
@@ -211,12 +336,23 @@ export function createHandler(store, options = {}) {
     const metadata = invoiceMetadata(invoice);
     const userId = metadata.userId;
 
-    const granted = await store.readGrantedPeriods(subId);
-    if (has('grant-marker') && granted.has(period.start)) {
-      store.log.push({ event: event.id, decision: 'skipped: period already granted' });
-      return [];
+    const itemId = (period.line && period.line.id) || 'item';
+    if (has('grant-key-atomic')) {
+      if (has('grant-marker')
+          && !store.claimPeriodGrant(subId, itemId, invoice.id, period.start)) {
+        store.log.push({ event: event.id, decision: 'skipped: period already granted' });
+        return [];
+      }
+      if (!has('grant-marker')) store.claimPeriodGrant(subId, itemId, invoice.id, period.start);
+    } else {
+      // The pre-fix shape: a SELECT (a round trip), then a mark. Kept as the mutant.
+      const granted = await store.readGrantedPeriods(subId);
+      if (has('grant-marker') && granted.has(period.start)) {
+        store.log.push({ event: event.id, decision: 'skipped: period already granted' });
+        return [];
+      }
+      store.markPeriodGranted(subId, period.start);
     }
-    store.markPeriodGranted(subId, period.start);
     store.addCredits(userId, CREDITS_PER_PERIOD);
     store.grants.push({
       subscription: subId, userId, periodStart: period.start, source: 'webhook', event: event.id,
@@ -239,14 +375,20 @@ export function createHandler(store, options = {}) {
     const conversionId = conversionIdFor(invoice);
     store.log.push({ event: event.id, decision: 'granted' });
     return [
-      () => store.notifications.push({ userId, kind: 'renewal', periodStart: period.start }),
-      () => store.conversions.push({
-        eventId: conversionId,
-        eventName: 'Purchase',
-        source: 'webhook',
-        value: invoice.amount_paid / 100,
-        currency: (invoice.currency || '').toUpperCase(),
-      }),
+      {
+        key: `${event.id}:renewal-notice`,
+        apply: () => store.notifications.push({ userId, kind: 'renewal', periodStart: period.start }),
+      },
+      {
+        key: `${event.id}:conversion`,
+        apply: () => store.conversions.push({
+          eventId: conversionId,
+          eventName: 'Purchase',
+          source: 'webhook',
+          value: invoice.amount_paid / 100,
+          currency: (invoice.currency || '').toUpperCase(),
+        }),
+      },
     ];
   }
 
@@ -393,34 +535,116 @@ export function createHandler(store, options = {}) {
     }
   }
 
-  /** The route Stripe posts to. Signature verification is the caller's; see SKILL.md. */
-  async function deliver(event) {
-    if (has('claim') && !store.claimEvent(event.id)) {
-      return { status: 200, body: { received: true, duplicate: true } };
+  /** The route Stripe posts to. Signature verification is the caller's; see SKILL.md.
+   *  `opts.crashAfterClaim` simulates the process dying between receipt and completion:
+   *  no release, no completion, no answer — the case a boolean claim turns into a
+   *  swallowed payment, because the row already says "seen". */
+  async function deliver(event, opts = {}) {
+    if (has('claim')) {
+      let claim = store.claimEvent(event.id);
+      if (claim === 'expired') {
+        claim = has('claim-expiry') && store.reclaimEvent(event.id) ? 'claimed' : 'in_flight';
+      }
+      if (claim === 'completed') {
+        return { status: 200, body: { received: true, duplicate: true } };
+      }
+      if (claim === 'in_flight') {
+        // Honest answer: somebody is (or may still be) working this event. 5xx makes
+        // Stripe retry THIS delivery too, so whichever worker dies, the event survives.
+        return { status: 500, body: { error: 'in flight' } };
+      }
     }
-    let afterCommit = [];
-    try {
-      afterCommit = await handle(event);
-    } catch (error) {
-      if (has('claim')) store.releaseEventClaim(event.id);
-      return { status: 500, body: { error: 'handler error' } };
+    if (opts.crashAfterClaim) return { status: 0, body: null }; // the worker is gone
+    // ONE transaction: entitlement, dedup marker, completion mark and the outbox rows
+    // commit together, or none of them exist. A crash inside leaves nothing applied —
+    // the claim row still says 'processing', and the retry runs the whole thing again.
+    // A serialization conflict aborts THIS attempt and retries inside the same
+    // claim — bounded at TX_RETRIES, because a database under real contention
+    // conflicts more than once and a loop with no bound is an outage. Beyond the
+    // bound the route answers 5xx with the claim released, so Stripe's redelivery
+    // brings the renewal back: a conflict may DELAY a grant, never lose it.
+    let attempts = 0;
+    for (;;) {
+      const snap = has('atomic-application') ? store.snapshot() : null;
+      try {
+        store.txAttempts += 1;
+        attempts += 1;
+        const effects = await handle(event);
+        // Receipt becomes completion in the same commit as the grant. A handler that
+        // answers 200 without this line has told Stripe "done" about work only received.
+        if (has('claim') && has('claim-completion')) store.completeEvent(event.id);
+        for (const e of effects) {
+          store.outbox.push({ key: e.key, apply: e.apply, state: 'pending' });
+        }
+        if (store.failNextTransactions > 0) {
+          store.failNextTransactions -= 1;
+          throw new SerializationConflict_();
+        }
+        if (opts.crashBeforeCommit) throw new SystemError_('killed inside the transaction');
+        break;
+      } catch (error) {
+        if (snap) store.restore(snap);
+        if (error instanceof SerializationConflict_) {
+          if (has('tx-retry-bounded') && attempts <= TX_RETRIES) continue; // same claim, fresh attempt
+          if (!has('tx-retry-bounded')) {
+            // The mutant: the conflict is swallowed and the route lies "done".
+            return { status: 200, body: { received: true } };
+          }
+          if (has('claim')) store.releaseEventClaim(event.id);
+          return { status: 500, body: { error: 'serialization conflict — retry' } };
+        }
+        if (error instanceof SystemError_) return { status: 0, body: null }; // process died
+        if (has('claim')) store.releaseEventClaim(event.id);
+        return { status: 500, body: { error: 'handler error' } };
+      }
     }
-    for (const effect of afterCommit) effect(); // side effects run after the commit
+    // After the commit the outbox drains — inline here; a worker in production, with
+    // the same at-least-once semantics and therefore the same need for a consumer key.
+    drainOutbox();
     return { status: 200, body: { received: true } };
   }
 
+  /** The outbox consumer. The queue redelivers, so the consumer carries its OWN
+   *  dedup key — the row's `key` (event id + effect kind), remembered across rows. */
+  function drainOutbox() {
+    for (const row of store.outbox) {
+      if (row.state === 'sent') continue;
+      if (has('outbox-consumer-key') && store.sentKeys.has(row.key)) {
+        row.state = 'sent';
+        continue;
+      }
+      row.apply();
+      if (has('outbox-consumer-key')) store.sentKeys.add(row.key);
+      row.state = 'sent';
+    }
+  }
+
   /**
    * The nightly repair, and the "Sync now" button. It has NO event id, so the event
    * claim cannot protect it -- only the per-period grant marker can. This is the entry
    * point that separates the two.
    */
   async function reconcile(subId, period, metadata) {
-    const granted = await store.readGrantedPeriods(subId);
-    if (has('grant-marker') && granted.has(period.start)) {
-      store.log.push({ event: 'reconcile', decision: 'skipped: period already granted' });
-      return { granted: false };
+    // The SAME key derivation as the webhook path — a reconciler keying the item
+    // differently is two ledgers for one period, i.e. the double grant back again.
+    const reconcileItemId = (period.line && period.line.id) || 'item';
+    if (has('grant-key-atomic')) {
+      if (has('grant-marker')
+          && !store.claimPeriodGrant(subId, reconcileItemId, 'reconcile', period.start)) {
+        store.log.push({ event: 'reconcile', decision: 'skipped: period already granted' });
+        return { granted: false };
+      }
+      if (!has('grant-marker')) {
+        store.claimPeriodGrant(subId, reconcileItemId, 'reconcile', period.start);
+      }
+    } else {
+      const granted = await store.readGrantedPeriods(subId);
+      if (has('grant-marker') && granted.has(period.start)) {
+        store.log.push({ event: 'reconcile', decision: 'skipped: period already granted' });
+        return { granted: false };
+      }
+      store.markPeriodGranted(subId, period.start);
     }
-    store.markPeriodGranted(subId, period.start);
     store.addCredits(metadata.userId, CREDITS_PER_PERIOD);
     store.grants.push({
       subscription: subId, userId: metadata.userId, periodStart: period.start,
@@ -453,5 +677,5 @@ export function createHandler(store, options = {}) {
     return offer;
   }
 
-  return { deliver, reconcile, offerRetention };
+  return { deliver, reconcile, offerRetention, drainOutbox };
 }

package/plugins/sheleg-dev/skills/stripe-billing/references/subscription-lifecycle.md

@@ -143,49 +143,105 @@ user back to the plan chooser shows a paywall to somebody who just paid.
 ```ts
 if (invoice.billing_reason !== "subscription_cycle") return;   // see webhook-events.md
 
+// One LEDGER ROW per granted period, arbitrated by the database:
+//   grant_ledger: UNIQUE (subscriptionId, periodStart)
+// The row carries the item and the invoice as provenance; they are not part of
+// the uniqueness (a second invoice for one period must not grant it twice; a
+// multi-item subscription widens the key with the item).
 await db.$transaction(async (tx) => {
-  const sub = await tx.subscription.findUnique({ where: { id }, select: { lastGrantedPeriodStart: true } });
-  if (sub?.lastGrantedPeriodStart && sub.lastGrantedPeriodStart >= periodStart) return;  // replay
-
-  await tx.subscription.update({ where: { id }, data: { lastGrantedPeriodStart: periodStart } });
+  try {
+    await tx.grantLedger.create({ data: { subscriptionId: id, itemId, invoiceId: invoice.id,
+      periodStart, amount: allowance } });
+  } catch (e) {
+    if (isUniqueViolation(e)) return;               // this period is already granted
+    throw e;
+  }
   await tx.wallet.update({ where: { userId }, data: { credit: { increment: allowance } } });
   await tx.auditLog.create({ data: { userId, action: "grant", amount: allowance,
     source: "subscription-renewal", metadata: { invoiceId: invoice.id } } });
 });
 ```
 
-Marker and grant in **one** transaction. Two statements outside a transaction is
-the same bug as read-then-write, one level up.
+Key write and grant in **one** transaction, and the KEY is per period — never a
+high-water mark. `lastGrantedPeriodStart >= periodStart` looks like the same
+guard and is a different rule: events arrive out of order, and a January
+invoice landing after February's would read as a replay and be suppressed —
+the reordered-periods fixture (`out-of-order-pair-does-not-rewind-state`)
+forbids exactly that. And the guard must be the INSERT itself: a SELECT before
+the write is a round trip, and two concurrent grants of one period — the
+webhook and the reconciler, say — both pass the read and both credit
+(`concurrent-entry-points-grant-once` in
+[`fixtures/assert-money-invariants.mjs`](../fixtures/assert-money-invariants.mjs)
+is the assertion that measures it, against
+`fixtures/invoice-paid-subscription-cycle.json`).
 
 ## Seat and quantity changes
 
+A quantity upgrade with `always_invoice` CHARGES the customer at the moment
+Stripe accepts it. Everything below follows from that: a revert of the
+quantity does not return the money — the proration invoice already settled —
+so "compensate by putting the number back" compensates the count and keeps
+the charge. The operation is recorded BEFORE the effect, an ambiguous outcome
+stays `unknown`, and the database repairs itself FROM Stripe rather than
+reverting Stripe to match a failed local write.
+
 ```ts
 const item = (await stripe.subscriptions.retrieve(subId)).items.data[0];
 
+// 1. Durable intent, BEFORE the effect: an operation row with its own
+//    idempotency key. If we crash past this point, reconciliation finds the
+//    row and asks Stripe what actually happened — the key makes the retry
+//    safe and the answer attributable.
+const op = await db.operation.create({ data: { kind: "quantity-change", subId,
+  from: item.quantity, to: newQuantity, state: "pending",
+  idempotencyKey: crypto.randomUUID() } });
+
+let updated;
 try {
-  await stripe.subscriptions.update(subId, {
+  updated = await stripe.subscriptions.update(subId, {
     items: [{ id: item.id, quantity: newQuantity }],
     proration_behavior: "always_invoice",
     payment_behavior: "error_if_incomplete",     // upgrades only
-  });
+  }, { idempotencyKey: op.idempotencyKey });
 } catch (err) {
   if (err.type === "StripeCardError" || err.code === "invoice_payment_intent_requires_action") {
+    await db.operation.update({ where: { id: op.id }, data: { state: "failed" } });
     return json({ error: "payment failed", code: "payment_failed" }, 402);
   }
+  if (err.type === "StripeConnectionError" || err.type === "StripeAPIError") {
+    // 2. A timeout after Stripe may have ACCEPTED the effect is not a
+    //    failure. Mark it unknown and leave it for reconciliation, which
+    //    retrieves the subscription (or replays the key) and settles the
+    //    row either way. Declaring it failed here is how a charged
+    //    customer keeps the old quantity.
+    await db.operation.update({ where: { id: op.id }, data: { state: "unknown" } });
+    return json({ error: "outcome unknown, reconciling", code: "pending" }, 202);
+  }
   throw err;
 }
 
 try {
   await db.subscription.update({ where: { id }, data: { quantity: newQuantity } });
+  await db.operation.update({ where: { id: op.id }, data: { state: "applied" } });
 } catch (dbErr) {
-  await stripe.subscriptions.update(subId, {                  // compensating revert
-    items: [{ id: item.id, quantity: oldQuantity }],
-    proration_behavior: "none",                               // do not re-bill the revert
-  }).catch((e) => log.error("CRITICAL: revert failed, Stripe and DB disagree", { subId, e }));
+  // 3. Stripe CONFIRMED the new quantity and invoiced it. The database is
+  //    what failed — so the database is what gets repaired, from the
+  //    confirmed Stripe state, by reconciliation reading the op row. Do NOT
+  //    revert Stripe to match a broken local write: the proration invoice
+  //    has already charged, and quantity:oldQuantity with proration "none"
+  //    returns none of it.
+  await db.operation.update({ where: { id: op.id }, data: { state: "apply-pending" } })
+    .catch(() => log.error("CRITICAL: op row unreachable", { opId: op.id }));
   throw dbErr;
 }
 ```
 
+- **If the business genuinely wants a rollback** (the product decides the
+  change must not stand), that is a SECOND financial operation, not a flag:
+  revert the quantity AND issue the credit note for the settled proration
+  invoice (`stripe.creditNotes.create`), each with its own op row and state —
+  the money's return is tracked to `applied`, never assumed from the
+  quantity's.
 - **Downgrades** need no `payment_behavior`; they produce a credit.
 - **Reducing below what is in use** is a business decision, not an API call.
   Answer 409 with the list of things that must be released first, and let the
@@ -196,6 +252,51 @@ try {
 - Do not add seats to a subscription flagged `cancel_at_period_end` — reactivate
   first, or the seats vanish at period end.
 
+## Reconciliation — repair the record, and money moves only by policy
+
+The reconciler walks every operation row in `unknown` or `apply-pending` and
+asks Stripe what actually happened — the op's idempotency key makes the
+question safe to repeat and the answer attributable:
+
+```ts
+for (const op of await db.operation.findMany({ where: { state: { in: ["unknown", "apply-pending"] } } })) {
+  const sub = await stripe.subscriptions.retrieve(op.subId);
+  const applied = sub.items.data[0].quantity === op.to;
+  if (applied) {
+    // RECONCILE-FIRST, the default: the database is repaired FROM the
+    // confirmed Stripe state. This is a record repair — updating the local
+    // count is never called a refund, because no money moved.
+    await db.subscription.update({ where: { id: op.subId }, data: { quantity: op.to } });
+    await db.operation.update({ where: { id: op.id }, data: { state: "applied" } });
+  } else {
+    await db.operation.update({ where: { id: op.id }, data: { state: "failed" } });
+  }
+}
+```
+
+Two rules the loop must keep:
+
+- **Idempotent by construction.** Every transition above is absorbing —
+  `applied` and `failed` are terminal, and re-running the loop over settled
+  rows changes nothing and charges nothing. A reconciler that can move money
+  on a replay is a billing bug wearing a repair's name.
+- **A refund is a POLICY, never a reflex.** The reconciler repairs records;
+  it does not decide that money should come back. Only an explicitly
+  configured business policy (`rollbackPolicy: "revert-and-credit"` on the
+  operation's kind) triggers the credit-note flow from the section above —
+  and that flow issues AT MOST ONCE per operation: the credit note is keyed
+  by op id, so a repeated reconciliation finds the existing note and stops.
+
+```ts
+if (policy(op.kind) === "revert-and-credit" && !op.creditNoteId) {
+  const note = await stripe.creditNotes.create(
+    { invoice: op.invoiceId, amount: op.chargedAmount },
+    { idempotencyKey: `${op.idempotencyKey}:credit` });
+  await db.operation.update({ where: { id: op.id },
+    data: { creditNoteId: note.id, state: "compensated" } });
+}
+```
+
 ## Plan changes
 
 Same shape as a quantity change, with `items: [{ id: item.id, price: newPriceId }]`.
@@ -253,26 +354,46 @@ expires 5 minutes after creation if unused, so mint it in the request that redir
 
 ## Refund clawback
 
-```ts
-const totalRefunded = charge.amount_refunded / 100;
-const increment = totalRefunded - stored.refundedTotal;
-if (increment <= 0) return;
-
-const { count } = await db.purchase.updateMany({
-  where: { id: stored.id, refundedTotal: stored.refundedTotal },
-  data:  { refundedTotal: totalRefunded },
-});
-if (count === 0) return;                       // concurrent delivery won
+`charge.amount_refunded` is CUMULATIVE and delivered out of order: a 4000 and
+a 9000 refund of one charge can arrive in either order, and two handlers can
+read the SAME `stored.refundedTotal` at once. The whole clawback — read,
+delta, marker AND ledger — happens inside ONE serializable transaction, and a
+CAS loser RE-READS and retries rather than returning: the old code's loser
+went home, so the second refund clawed back nothing.
 
-try {
-  await clawBack(stored.userId, increment);    // idempotent, keyed on charge id + total
-} catch (err) {
-  await db.purchase.update({ where: { id: stored.id },
-    data: { refundedTotal: stored.refundedTotal } });   // put the marker back
-  throw err;
+```ts
+// Money in MINOR UNITS end to end. `amount_refunded` is already integer cents;
+// `/ 100` turns 995 into 9.95 and reintroduces the float error the integer
+// avoids — never divide until you format for a human.
+const totalRefunded = charge.amount_refunded;          // cents, integer
+
+for (let attempt = 0; attempt < RETRIES; attempt++) {
+  try {
+    await db.$transaction(async (tx) => {
+      const row = await tx.purchase.findUnique({
+        where: { id: stored.id }, ...forUpdate });      // row lock
+      const seen = Math.max(row.refundedTotal, totalRefunded);  // monotone: never rewind
+      const increment = seen - row.refundedTotal;
+      if (increment <= 0) return;                       // this delta already counted
+      // Marker and ledger move TOGETHER — a marker written without its
+      // clawback (or the reverse) is the split the old code shipped.
+      await tx.purchase.update({ where: { id: stored.id },
+        data: { refundedTotal: seen } });
+      await clawBack(tx, stored.userId, increment,
+        { key: `${charge.id}:${seen}` });               // idempotent per (charge,total)
+    }, { isolation: "Serializable" });
+    return;
+  } catch (err) {
+    if (isSerializationConflict(err) && attempt < RETRIES - 1) continue;  // re-read, retry
+    throw err;
+  }
 }
 ```
 
+The invariant the fixtures pin: cumulative 4000 then 9000 (or 9000 then 4000),
+a crash after the marker, and a retry of the old event all converge on
+`refundedTotal = 9000` and a summed clawback of exactly 9000 — once.
+
 Clamp the deduction at zero. A user who already spent the credit goes to a
 negative balance or to a collections decision — pick one deliberately and log
 which. Silently deducting into negative is how a support ticket becomes a