@ssheleg/sheleg-dev 0.11.8 → 0.13.0

package/plugins/sheleg-dev/skills/google-signin/references/full-guide.md

@@ -41,21 +41,25 @@ secrets, no redirect URIs, no token storage for Google APIs.
  Browser                       Google                        Your backend
  ───────                       ──────                        ────────────
  1. load gsi/client script
- 2. google.accounts.id.initialize({client_id, callback, nonce})
+ 0. GET /api/auth/google/nonce ────────────────────────────► server issues nonce,
+    (pre-auth HttpOnly cookie set)                              stores it w/ TTL
+ 2. google.accounts.id.initialize({client_id, callback, nonce: serverIssued})
  3. renderButton(#container)
  4. user clicks button ──────► account-chooser popup
                                (user picks account,
                                 consents on first use)
  5. callback receives  ◄────── ID token (JWT, RS256-signed
     {credential: "<jwt>"}       by Google's private key)
- 6. POST /api/auth/google {credential, nonce} ─────────────► 7. verify ID token:
+ 6. POST /api/auth/google {credential} ────────────────────► 7. verify ID token:
                                                                 - signature vs Google JWKS
                                                                   (https://www.googleapis.com/oauth2/v3/certs)
                                                                 - aud == YOUR client_id
                                                                 - iss == accounts.google.com
                                                                 - exp not passed
                                                                 - email_verified == true
-                                                                - nonce matches
+                                                                - nonce claim == server
+                                                                  expectation (popped:
+                                                                  one-time consume)
                                                              8. find-or-create user,
                                                                 link accounts
                                                              9. issue YOUR OWN session
@@ -81,7 +85,7 @@ Payload claims you care about:
   "email_verified": true,
   "name": "Ada Lovelace",
   "picture": "https://lh3.googleusercontent.com/…",
-  "nonce": "d9b2d63d-…",       // echoed from initialize() — replay defense
+  "nonce": "d9b2d63d-…",       // the SERVER-issued value passed to initialize()
   "iat": 1719410000,
   "exp": 1719413600            // ~1 hour lifetime
 }
@@ -107,7 +111,7 @@ Payload claims you care about:
 // app.js (essentials)
 var _googleNonce = '';
 
-function _renderGoogleButton() {
+async function _renderGoogleButton() {
   var clientId = _getGoogleClientId();          // read from the <meta> tag
   if (!clientId) return;                        // Google auth not configured → hide, degrade honestly
   if (typeof google === 'undefined' || !google.accounts) {
@@ -115,7 +119,10 @@ function _renderGoogleButton() {
     if (_googleRenderRetries++ < 20) setTimeout(_renderGoogleButton, 150);
     return;
   }
-  _googleNonce = crypto.randomUUID();           // fresh nonce per render — replay defense
+  // SERVER-issued nonce: the backend stores it (TTL, pre-auth HttpOnly cookie)
+  // and will pop it on the callback — the client never invents the value.
+  var nr = await fetch('/api/auth/google/nonce');
+  _googleNonce = (await nr.json()).nonce;
 
   google.accounts.id.initialize({
     client_id: clientId,
@@ -135,7 +142,7 @@ async function handleGoogleCredential(response) {
   var resp = await fetch('/api/auth/google', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ credential: response.credential, nonce: _googleNonce }),
+    body: JSON.stringify({ credential: response.credential }),
   });
   var data = await resp.json();
   if (!resp.ok) { showError(data.detail); return; }
@@ -185,14 +192,21 @@ Every Google login resolves to exactly one of three cases:
 
 1. **Returning Google user** — a record with this `google_id` (`sub`) exists
    → issue session. Refresh `name`/`picture` if they changed.
-2. **Existing email/password account, no `google_id`** — link Google to it
-   (set `google_id`, mark `email_verified=True`) → issue session.
-   ⚠️ **Pre-hijacking guard** (see §4.3): only auto-link if the existing
-   account's email ownership was verified. Otherwise refuse with "sign in
-   with your password".
-3. **Brand-new user** — create the account with `email_verified=True` (the
-   Google token already proved inbox ownership), empty password hash → issue
-   session.
+2. **Existing account, no `google_id`** — `email_verified` is NOT authority to
+   attach Google to it. It means Google verified the inbox once; it does not
+   mean this person owns the LOCAL account, and for a third-party address it
+   does not even mean they still own the inbox. Default: link only after a
+   **fresh re-auth of the existing local account** (§4.3). Auto-link without
+   re-auth is permitted only when `google_authoritative(payload)` — the address
+   is `@gmail.com` or the token carries an `hd` Workspace claim — AND the
+   existing record's own email ownership was proven; for any other address run
+   an **independent inbox challenge** first. If the existing account is a
+   password account whose email was **never verified**, route to **safe
+   account recovery** (§4.3), never to the existing password.
+3. **Brand-new user** — create the account, empty password hash. Mark
+   `email_verified=True` only when `google_authoritative(payload)`; for a
+   third-party address (non-Gmail, no `hd`) create it UNVERIFIED and challenge
+   the inbox before anything trusts the email → issue session.
 
 Then issue your own session. Prowl issues an HS256 app JWT (72 h, `ver` claim
 for global revocation) delivered as an **HttpOnly, Secure, SameSite=Strict
@@ -261,11 +275,17 @@ npm i google-auth-library      # Node
 
 ### 4.2 Nonce — replay defense
 
-Generate a fresh random nonce per button render, pass it to
-`google.accounts.id.initialize({nonce})`, send it alongside the credential,
-compare server-side with the token's `nonce` claim
-(`web/auth.py:375-376`). A stolen/logged ID token can't be replayed later
-because the nonce won't match the new session's nonce.
+**The server issues the nonce; the client never invents one.** A
+client-generated nonce POSTed back beside the credential proves nothing — the
+"expected" value would be read out of the very JWT it is meant to check, so a
+stolen token replays with its own nonce forever. Fetch the nonce from
+`GET /api/auth/google/nonce` (the server stores it with a TTL, bound to a
+pre-auth HttpOnly session cookie), pass it to
+`google.accounts.id.initialize({nonce})`, and on the callback the server POPs
+the expectation (one-time consume) and requires the token's `nonce` claim to
+equal it exactly. Missing claim, missing expectation, expiry and re-use all
+reject. First sign-in passes; a replay from a new session meets a different
+expectation; a replay in the same session meets a consumed one.
 
 ### 4.3 Account pre-hijacking guard (P3-01 in Prowl)
 
@@ -274,10 +294,31 @@ victim ever visits. Later the victim clicks "Sign in with Google". Naïve
 auto-linking attaches victim's Google to the **attacker's** record — attacker
 keeps password access to the merged account (its data and wallet).
 
-Defense (`web/auth.py:392-417`): when a Google login matches an existing
-**password** account whose email was **never verified**, refuse to auto-link;
-tell the user to sign in with the password. Link only when email ownership of
-the existing record is proven.
+Defense: `email_verified` is not proof of ownership OF THE LOCAL ACCOUNT, and
+Google is only authoritative for the *address* when it is Gmail or carries an
+`hd` Workspace claim — for a third-party email, ownership can have changed
+since Google verified it (Google's own guidance excludes non-Gmail without
+`hd`). So:
+
+```python
+def google_authoritative(payload):
+    email = (payload.get("email") or "").lower()
+    return bool(payload.get("email_verified")
+                and (email.endswith("@gmail.com") or payload.get("hd")))
+```
+
+- **Default** — link only after a **fresh re-auth of the existing local
+  account** (its password or existing factor). Proving you hold the account is
+  the only thing that authorizes attaching a new identity to it.
+- **Auto-link without re-auth** — permitted only when
+  `google_authoritative(payload)` AND the existing record's email ownership was
+  already proven. For any other address, run an **independent challenge** (a
+  verification link to that inbox) first.
+- **Unverified pre-registration** — when the existing password account's email
+  was never verified, DO NOT tell the victim to "sign in with the password":
+  that password may be the attacker's. Route them into a **safe
+  account-recovery flow** (reset via a fresh inbox challenge), which takes the
+  account away from whoever pre-registered it rather than handing it over.
 
 ### 4.4 Login-CSRF (P3-03 in Prowl)
 
@@ -287,12 +328,22 @@ attacker's account (victim then unknowingly feeds data/payments into it).
 
 Defense (`web/server.py:1657-1686`), covering both possible delivery flows:
 
-- **Form-POST flow** (GIS `login_uri` auto-POST): GIS double-submits
-  `g_csrf_token` in body *and* cookie — compare both, constant-time
-  (`hmac.compare_digest`). Reject if either is missing.
-- **JS-fetch flow** (this app): no `g_csrf_token`, so enforce same-origin via
-  **Fetch-Metadata** (`Sec-Fetch-Site: same-origin`) with an Origin-allowlist
-  fallback. These headers are browser-set and unforgeable by page script.
+The two flows are SEPARATE, explicitly typed paths chosen by Content-Type. A
+handler that claims form support but binds only a JSON body never runs the form
+contract — the CSRF check for the form flow (`g_csrf_token`) is on a request
+shape that flow never sends.
+
+- **Form-POST flow** (`login_uri` auto-POST, `application/x-www-form-urlencoded`):
+  GIS double-submits `g_csrf_token` in the FORM BODY and the cookie — require
+  BOTH present and equal, constant-time (`hmac.compare_digest`). Reject if
+  either is missing.
+- **JS-fetch flow** (`application/json`): no `g_csrf_token`, so require a
+  trusted same-origin signal — `Sec-Fetch-Site: same-origin`, OR (only when
+  that header is ABSENT) an exact `Origin` in an allowlist. A **missing
+  `Sec-Fetch-Site` is NOT assumed same-origin**; `cross-site` and `none` are
+  rejected; with neither a trusted metadata value nor an allowed Origin the
+  request **fails closed**. These headers are browser-set and unforgeable by
+  page script. The CSRF decision runs BEFORE token verification.
 
 ### 4.5 Session hygiene
 
@@ -346,8 +397,8 @@ Defense (`web/server.py:1657-1686`), covering both possible delivery flows:
 
 ```python
 # --- backend ---
-import os, hmac
-from fastapi import FastAPI, HTTPException, Request, Response
+import os, hmac, secrets, time
+from fastapi import FastAPI, Form, HTTPException, Request, Response
 from pydantic import BaseModel
 from google.oauth2 import id_token
 from google.auth.transport import requests as google_requests
@@ -356,29 +407,79 @@ GOOGLE_CLIENT_ID = os.environ["GOOGLE_CLIENT_ID"]
 _transport = google_requests.Request()
 app = FastAPI()
 
+NONCE_TTL = 600
+_nonce_store: dict[str, tuple[str, float]] = {}   # sid -> (nonce, expires); use Redis in prod
+
+ALLOWED_ORIGINS = {"https://app.example.com"}   # your own origin(s)
+
+
 class GoogleAuthRequest(BaseModel):
     credential: str
-    nonce: str | None = None
-    g_csrf_token: str | None = None
-
-@app.post("/api/auth/google")
+    g_csrf_token: str | None = None               # no nonce in the body — the server holds it
+
+
+def _csrf_ok_form(cookie_token, form_token):
+    # The form flow's whole authorization: both present and equal, constant-time.
+    if not form_token or not cookie_token:
+        return False
+    return hmac.compare_digest(cookie_token, form_token)
+
+
+def _csrf_ok_json(sec_fetch_site, origin):
+    # Trusted metadata first; Origin allowlist ONLY as an explicit fallback when
+    # the header is absent. A missing Sec-Fetch-Site is not same-origin, and
+    # `none`/`cross-site` are rejected — fail closed when neither proves origin.
+    if sec_fetch_site == "same-origin":
+        return True
+    if sec_fetch_site in ("cross-site", "same-site", "none"):
+        return False
+    if sec_fetch_site is None:                     # header absent → exact Origin, allowlisted
+        return bool(origin) and origin in ALLOWED_ORIGINS
+    return False
+
+@app.get("/api/auth/google/nonce")
+async def google_nonce(req: Request, response: Response):
+    sid = req.cookies.get("preauth") or secrets.token_urlsafe(32)
+    nonce = secrets.token_urlsafe(32)
+    _nonce_store[sid] = (nonce, time.time() + NONCE_TTL)
+    response.set_cookie("preauth", sid, httponly=True, secure=True,
+                        samesite="lax", max_age=NONCE_TTL, path="/")
+    return {"nonce": nonce}
+
+# Two explicitly typed routes. Content-Type picks the flow; each runs ONLY its
+# own CSRF contract; both fail closed; the check is before any token call.
+
+@app.post("/api/auth/google/form")             # application/x-www-form-urlencoded
+async def google_auth_form(req: Request, response: Response,
+                           credential: str = Form(...),
+                           g_csrf_token: str = Form(None)):
+    if not _csrf_ok_form(req.cookies.get("g_csrf_token"), g_csrf_token):
+        raise HTTPException(403, "CSRF: g_csrf_token missing or mismatched")
+    return await _finish_google_auth(req, response, credential)
+
+
+@app.post("/api/auth/google")                  # application/json (JS fetch)
 async def google_auth(req: Request, data: GoogleAuthRequest, response: Response):
-    # CSRF: double-submit for form-POST flow, Fetch-Metadata for JS flow
-    if data.g_csrf_token:
-        cookie = req.cookies.get("g_csrf_token") or ""
-        if not hmac.compare_digest(cookie, data.g_csrf_token):
-            raise HTTPException(403, "CSRF token mismatch")
-    elif req.headers.get("sec-fetch-site", "same-origin") not in ("same-origin", "none"):
-        raise HTTPException(403, "Cross-site request rejected")
+    sec = req.headers.get("sec-fetch-site")    # None when the header is absent
+    if not _csrf_ok_json(sec, req.headers.get("origin")):
+        raise HTTPException(403, "CSRF: request origin not proven (fail closed)")
+    return await _finish_google_auth(req, response, data.credential)
 
+
+async def _finish_google_auth(req: Request, response: Response, credential: str):
     try:
-        payload = id_token.verify_oauth2_token(data.credential, _transport, GOOGLE_CLIENT_ID)
+        payload = id_token.verify_oauth2_token(credential, _transport, GOOGLE_CLIENT_ID)
     except Exception as exc:
         raise HTTPException(401, f"Invalid Google token: {exc}")
     if not payload.get("email_verified"):
         raise HTTPException(401, "Google account email is not verified")
-    if data.nonce and payload.get("nonce") != data.nonce:
-        raise HTTPException(401, "Nonce mismatch")
+    # One-time consume BEFORE any account work: pop() removes the expectation
+    # in the same step, so a replayed callback finds nothing. Mandatory — a
+    # missing claim or a missing expectation rejects; the body carries no nonce.
+    sid = req.cookies.get("preauth") or ""
+    expected, expires = _nonce_store.pop(sid, (None, 0.0))
+    if not expected or time.time() > expires or payload.get("nonce") != expected:
+        raise HTTPException(401, "Nonce missing, expired, replayed or not server-issued")
 
     user = await find_or_create_user(          # your 3-way linking here (§2.4, §4.3)
         google_id=payload["sub"], email=payload["email"].lower().strip(),
@@ -395,8 +496,8 @@ async def google_auth(req: Request, data: GoogleAuthRequest, response: Response)
 <script src="https://accounts.google.com/gsi/client" async defer></script>
 <div id="gbtn"></div>
 <script>
-  const NONCE = crypto.randomUUID();
-  window.onload = () => {
+  window.onload = async () => {
+    const NONCE = (await (await fetch("/api/auth/google/nonce")).json()).nonce;
     google.accounts.id.initialize({
       client_id: "YOUR_CLIENT_ID.apps.googleusercontent.com",
       nonce: NONCE,
@@ -404,7 +505,7 @@ async def google_auth(req: Request, data: GoogleAuthRequest, response: Response)
         const r = await fetch("/api/auth/google", {
           method: "POST",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ credential, nonce: NONCE }),
+          body: JSON.stringify({ credential }),
         });
         if (r.ok) location.href = "/app";
       },

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

@@ -6,14 +6,14 @@ description: >-
   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
+  resolution, 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", "refund", "cancel subscription", "retention
   coupon", "подключить Stripe", "оплата подпиской", "вебхук Stripe",
-  "скидка при отмене", "биллинг". Not for choosing between Stripe products
+  "скидка при отмене", "биллинг подписок". Not for choosing between Stripe products
   (stripe-best-practices) or reading Stripe docs (stripe-docs).
 license: MIT
 ---
@@ -198,7 +198,8 @@ export async function POST(request: Request) {
   }
 
   const claim = await claimEvent(event.id);              // INSERT on a primary key
-  if (claim === "duplicate") return json({ received: true, duplicate: true });
+  if (claim === "completed") return json({ received: true, duplicate: true });
+  if (claim === "in_flight") return json({ error: "in flight" }, 500); // retry later
 
   try {
     await handle(event);
@@ -215,16 +216,17 @@ export async function POST(request: Request) {
 - **Exempt this path — and only this path — from CSRF and session auth**, by
   exact match: a prefix match over `/api/billing` exempts checkout too, which is
   where the money is.
-- **Claim before working.** `SELECT` then `INSERT` is a race; two deliveries
-  40 ms apart both pass the read and both credit. Release the claim if
-  processing throws, or the retry finds the event "processed" and the work is
-  lost forever.
+- **Claim before working — a claim is a receipt, not completion.** `SELECT`
+  then `INSERT` is a race; two deliveries 40 ms apart both credit. The row
+  stays `processing` until the grant's transaction marks it `completed` —
+  states, expiry, takeover and release:
+  [`references/webhook-events.md`](references/webhook-events.md).
 - **Answer honestly.** 200 handled or duplicate, 400 bad signature, 5xx try
   again, 200 for types you do not handle. Never 200 on failure to stop retries —
   that discards a payment quietly.
 - **Order inside a handler:** fallible external calls first, then one
-  transaction, then side effects that must not run twice (emails, provisioning)
-  after it commits.
+  transaction — entitlement, dedup marker, completion, outbox rows — then side
+  effects drain from the outbox, each under its own consumer key.
 
 Per-event detail: [`references/webhook-events.md`](references/webhook-events.md).
 
@@ -377,6 +379,21 @@ renewal and proration. The one thing to know before you get there: the signing
 secret `stripe listen` prints is **not** the dashboard's, and using the wrong one
 fails verification in a way that reads like a key problem.
 
+## Degradation
+
+- **Not Claude Code** (Cursor, Codex, the skills CLI, the API container): the
+  `PreToolUse` money gate this pack ships does not exist there — nothing refuses a
+  refund, a payout, a dispute close or a live `sk_live_…` key on your behalf. Every
+  rule below still holds; it is advice again rather than a precondition, so the
+  authorisation step becomes a human one. Say which you are on before acting on money.
+- **Installed by copy rather than as a plugin**: same loss, same remedy — a plain
+  `~/.claude/skills/` copy carries the doctrine and not `hooks/money-gate.js`. The
+  README names the categories and how one is signed off; without the hook, that
+  sign-off is a sentence somebody has to actually say.
+- **No Stripe CLI, no network, or test keys only**: webhook signature verification and
+  the local replay loop are the parts that need the binary. State which is missing
+  once, do the rest, and record what could not be verified rather than implying it was.
+
 ## Before you ship
 
 Not a second checklist — every rule below already has a section above, and a rule

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

@@ -62,7 +62,17 @@ Run `node assert-money-invariants.mjs` and each line names the invariant it hold
 | `proration-invoice-grants-nothing` | cycle + proration | gives a month of product for a $40 proration invoice |
 | `sequential-redelivery-grants-once` | cycle + redelivery | answers `received` twice and sends the renewal notice and the server-side conversion twice |
 | `concurrent-redelivery-grants-once` | cycle + redelivery, in flight together | both deliveries pass the marker's `SELECT` and both credit |
+| `crash-after-receipt-is-retryable` | cycle (worker dies) + redelivery | tells the retry "duplicate" about work that never finished — the payment is swallowed forever |
+| `in-flight-claim-answers-retry-later` | cycle (worker dies) + redelivery | answers `duplicate` to a retry while the first worker may still be mid-grant |
+| `completion-is-recorded-with-the-grant` | cycle | leaves the claim row saying `processing` after answering done — every later retry reads it as a corpse |
+| `duplicate-of-completed-never-regrants` | cycle + redelivery, aged past the claim expiry | takes the completed row over as if the worker had died, and grants again |
+| `transaction-rolls-back-whole` | cycle (crash inside the transaction) | leaves the grant applied with no completion — half a payment no retry can see |
+| `crash-before-commit-applies-nothing` | cycle (crash) + redelivery | the retry double-applies or never applies what the crash interrupted |
+| `committed-retry-sends-once` | cycle, outbox redelivered | sends "your renewal" twice and counts the revenue twice |
 | `sequential-redelivery-grants-once-by-count-alone` | cycle + redelivery | *nothing* — kept because that is the finding; see below |
+| `concurrent-entry-points-grant-once` | cycle, webhook + reconciler in flight together | both pass the marker's read and one period is granted twice |
+| `serialization-conflict-does-not-lose-the-renewal` | cycle, one injected conflict | drops the conflicted transaction and answers 200 — the renewal silently never lands |
+| `exhausted-retries-answer-5xx-and-the-redelivery-lands` | cycle + redelivery, conflicts past the bound | swallows the conflict instead of answering 5xx, so nothing ever retries |
 | `reconciliation-does-not-regrant` | cycle | the nightly repair grants a period the webhook already granted |
 | `out-of-order-pair-does-not-rewind-state` | February then January | stores the older period, so the renewal date points at a period that ended |
 | `refund-total-is-cumulative` | both refunds | claws back $130 against a $90 charge |
@@ -80,7 +90,13 @@ a line a generated handler routinely omits:
 
 | Rule | The code it removes | The generated handler that ships without it |
 |---|---|---|
-| `claim` | `if (!store.claimEvent(event.id)) return duplicate` | reads the processed table, then writes it — two deliveries 40 ms apart both pass the read |
+| `claim` | the whole claim block at the top of `deliver` | reads the processed table, then writes it — two deliveries 40 ms apart both pass the read |
+| `claim-completion` | `store.completeEvent(event.id)` after the grant commits | leaves every row at `processing`, so a retry past the claim expiry reprocesses a completed event |
+| `claim-expiry` | the takeover of a `processing` row older than `CLAIM_TTL_MS` | answers "in flight" forever for a worker that died — received quietly read as completed |
+| `atomic-application` | the snapshot/restore around the business application | applies the grant and loses the completion when a crash lands mid-way |
+| `outbox-consumer-key` | the consumer's own dedup across redelivered rows | sends every redelivered outbox row again |
+| `grant-key-atomic` | the keyed INSERT claim on the period grant | falls back to read-then-mark — two concurrent grants of one period both pass the read |
+| `tx-retry-bounded` | the bounded serialization-retry loop | a conflicted transaction is dropped and the route answers 200 |
 | `billing-reason` | `if (invoice.billing_reason !== 'subscription_cycle') return` | handles `invoice.paid` as "a payment arrived" |
 | `grant-marker` | `if (granted.has(period.start)) return` | grants whenever an event says paid, including from the reconciliation job |
 | `ordering` | `if (period.start > mirror.periodStart)` around the mirror write | writes whatever arrived last |

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

@@ -28,7 +28,8 @@ import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import assert from 'node:assert/strict';
 import {
-  createStore, createHandler, subscriptionIdOf, RULES, CREDITS_PER_PERIOD,
+  createStore, createHandler, subscriptionIdOf, RULES, CREDITS_PER_PERIOD, CLAIM_TTL_MS,
+  TX_RETRIES,
 } from './reference-handler.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -117,7 +118,9 @@ export const INVARIANTS = [
     id: 'sequential-redelivery-grants-once',
     fixtures: [CYCLE_JAN, CYCLE_JAN_REDELIVERY],
     states: 'the same evt_ delivered twice grants once AND runs its side effects once',
-    breaks: ['claim', 'grant-on-renewal'],
+    // `claim-completion` is here because "duplicate" is an answer about a COMPLETED row:
+    // a handler that never marks completion answers the redelivery in-flight instead.
+    breaks: ['claim', 'claim-completion', 'grant-on-renewal'],
     async run({ store, handler, assert }) {
       const first = await handler.deliver(fixture(CYCLE_JAN));
       const second = await handler.deliver(fixture(CYCLE_JAN_REDELIVERY));
@@ -143,13 +146,176 @@ export const INVARIANTS = [
         handler.deliver(fixture(CYCLE_JAN)),
         handler.deliver(fixture(CYCLE_JAN_REDELIVERY)),
       ]);
-      const bodies = [a.body, b.body];
       assert.equal(store.grants.length, 1, 'both deliveries granted');
       assert.equal(store.credits.get('usr_PLACEHOLDER_alice'), CREDITS_PER_PERIOD,
         'the user was credited twice for one renewal');
       assert.equal(store.conversions.length, 1, 'the conversion fired twice');
-      assert.equal(bodies.filter((x) => x.duplicate === true).length, 1,
-        'exactly one of the two deliveries must answer duplicate');
+      // "duplicate" is an answer about a COMPLETED row. Mid-flight the loser answers 5xx
+      // so its own retry keeps the event alive if the winner dies before completing.
+      const winners = [a, b].filter((r) => r.status === 200 && r.body.duplicate !== true);
+      const loser = [a, b].find((r) => !winners.includes(r));
+      assert.ok(winners.length === 1 && loser
+        && ((loser.status === 200 && loser.body.duplicate === true)
+          || (loser.status === 500 && loser.body.error === 'in flight')),
+      'exactly one delivery processes; the other answers duplicate or in-flight, never grants');
+    },
+  },
+  {
+    id: 'crash-after-receipt-is-retryable',
+    fixtures: [CYCLE_JAN, CYCLE_JAN_REDELIVERY],
+    states: 'a worker that dies after claiming leaves a claim a later retry takes over — receipt is not completion',
+    breaks: ['claim-expiry', 'grant-on-renewal'],
+    async run({ store, handler, assert }) {
+      const dead = await handler.deliver(fixture(CYCLE_JAN), { crashAfterClaim: true });
+      assert.unmutated.equal(dead.status, 0, 'the crash simulation must not answer'); // the worker is gone
+      store.advanceClock(CLAIM_TTL_MS + 1);
+      const late = await handler.deliver(fixture(CYCLE_JAN_REDELIVERY));
+      assert.deepEqual(late.body, { received: true },
+        'the retry after the claim expiry was not let in — the payment is swallowed forever');
+      assert.equal(store.grants.length, 1, 'the recovered event did not grant');
+    },
+  },
+  {
+    id: 'in-flight-claim-answers-retry-later',
+    fixtures: [CYCLE_JAN, CYCLE_JAN_REDELIVERY],
+    states: 'a retry inside the claim window is told to come back — "duplicate" is an answer about a completed row',
+    breaks: ['claim'],
+    async run({ store, handler, assert }) {
+      await handler.deliver(fixture(CYCLE_JAN), { crashAfterClaim: true });
+      const early = await handler.deliver(fixture(CYCLE_JAN_REDELIVERY));
+      assert.ok(early.status === 500 && store.grants.length === 0,
+        'a retry inside the claim window must wait out a possibly live worker, not process or be told duplicate');
+    },
+  },
+  {
+    id: 'completion-is-recorded-with-the-grant',
+    fixtures: [CYCLE_JAN],
+    states: 'the claim row leaves processing the moment the grant commits — received and completed are different states',
+    breaks: ['claim-completion'],
+    async run({ store, handler, assert }) {
+      const event = fixture(CYCLE_JAN);
+      await handler.deliver(event);
+      const row = store.processedEvents.get(event.id);
+      // Conditional on the row existing so this isolates the completion mark: with no
+      // claim at all there is no row to leave in the wrong state.
+      assert.ok(!row || row.state === 'completed',
+        'the delivery answered done and its claim row still says processing — a crash-shaped lie');
+    },
+  },
+  {
+    id: 'duplicate-of-completed-never-regrants',
+    fixtures: [CYCLE_JAN, CYCLE_JAN_REDELIVERY],
+    states: 'a completed row stays completed: a retry arriving after the claim expiry answers duplicate and grants nothing',
+    breaks: ['claim', 'claim-completion', 'grant-on-renewal'],
+    async run({ store, handler, assert }) {
+      const first = await handler.deliver(fixture(CYCLE_JAN));
+      assert.unmutated.deepEqual(first.body, { received: true });
+      store.advanceClock(CLAIM_TTL_MS + 1);
+      const late = await handler.deliver(fixture(CYCLE_JAN_REDELIVERY));
+      assert.deepEqual(late.body, { received: true, duplicate: true },
+        'a completed event aged past the claim expiry was reprocessed — completion was never recorded');
+      assert.equal(store.grants.length, 1, 'a completed event was granted again');
+      assert.equal(store.notifications.length, 1, '"your renewal" was sent twice');
+    },
+  },
+  {
+    id: 'transaction-rolls-back-whole',
+    fixtures: [CYCLE_JAN],
+    states: 'a crash inside the transaction leaves nothing: no grant, no marker, no outbox row, no completion',
+    breaks: ['atomic-application'],
+    async run({ store, handler, assert }) {
+      const dead = await handler.deliver(fixture(CYCLE_JAN), { crashBeforeCommit: true });
+      assert.unmutated.equal(dead.status, 0, 'the crash simulation must not answer');
+      assert.ok(store.grants.length === 0 && store.grantedPeriods.size === 0
+        && store.outbox.length === 0
+        && ![...store.processedEvents.values()].some((r) => r.state === 'completed'),
+      'a crash before the commit left part of the application behind — half a payment no retry can see');
+    },
+  },
+  {
+    id: 'crash-before-commit-applies-nothing',
+    fixtures: [CYCLE_JAN, CYCLE_JAN_REDELIVERY],
+    states: 'after a mid-transaction crash, the retry applies everything exactly once',
+    // `claim-expiry` is here because the retry enters through the expired-claim door.
+    breaks: ['atomic-application', 'claim-expiry', 'grant-on-renewal'],
+    async run({ store, handler, assert }) {
+      const dead = await handler.deliver(fixture(CYCLE_JAN), { crashBeforeCommit: true });
+      assert.unmutated.equal(dead.status, 0, 'the crash simulation must not answer');
+      store.advanceClock(CLAIM_TTL_MS + 1);
+      const retry = await handler.deliver(fixture(CYCLE_JAN_REDELIVERY));
+      assert.deepEqual(retry.body, { received: true },
+        'the retry after the crash was not let in');
+      assert.equal(store.grants.length, 1, 'the retry did not apply the payment exactly once');
+      assert.equal(store.notifications.length, 1, 'the renewal notice did not go out exactly once');
+    },
+  },
+  {
+    id: 'committed-retry-sends-once',
+    fixtures: [CYCLE_JAN],
+    states: 'after the commit, a redelivered outbox row sends nothing twice — the consumer holds its own key',
+    breaks: ['outbox-consumer-key', 'grant-on-renewal'],
+    async run({ store, handler, assert }) {
+      await handler.deliver(fixture(CYCLE_JAN));
+      assert.equal(store.notifications.length, 1, 'the first drain did not send');
+      // The queue redelivers: every sent row comes back pending. At-least-once is
+      // the outbox's contract, so this is the normal case, not the weird one.
+      for (const row of store.outbox) row.state = 'pending';
+      handler.drainOutbox();
+      assert.equal(store.notifications.length, 1, '"your renewal" was sent twice');
+      assert.equal(store.conversions.length, 1,
+        'the conversion fired twice — the revenue is counted twice');
+    },
+  },
+  {
+    id: 'concurrent-entry-points-grant-once',
+    fixtures: [CYCLE_JAN],
+    states: 'a webhook and the reconciler racing for one period leave exactly one keyed ledger row — the claim is an INSERT, and a read is a round trip',
+    breaks: ['grant-key-atomic'],
+    async run({ store, handler, assert }) {
+      const event = fixture(CYCLE_JAN);
+      const subId = subscriptionIdOf(event.data.object);
+      await Promise.all([
+        handler.deliver(event),
+        handler.reconcile(subId, periodOfCycle(event), { userId: 'usr_PLACEHOLDER_alice' }),
+      ]);
+      // Judged on the LEDGER, deliberately: the keyed row is the atomic claim's own
+      // axis. Grant counts belong to the marker invariants; measuring them here would
+      // blur the two rules this pack keeps isolated.
+      assert.equal(store.grantLedger.length, 1,
+        `the race left ${store.grantLedger.length} keyed ledger rows for one period`);
+    },
+  },
+  {
+    id: 'serialization-conflict-does-not-lose-the-renewal',
+    fixtures: [CYCLE_JAN],
+    states: 'a conflicted transaction retries inside the same claim and the renewal lands — a conflict delays a grant, never loses it',
+    breaks: ['tx-retry-bounded', 'grant-on-renewal'],
+    async run({ store, handler, assert }) {
+      store.failNextTransactions = 1;
+      const r = await handler.deliver(fixture(CYCLE_JAN));
+      assert.unmutated.equal(r.status, 200);
+      assert.equal(store.grants.length, 1,
+        'the conflicted transaction was dropped and the renewal never landed');
+      assert.equal(store.txAttempts, 2, 'the retry did not actually run a second attempt');
+    },
+  },
+  {
+    id: 'exhausted-retries-answer-5xx-and-the-redelivery-lands',
+    fixtures: [CYCLE_JAN, CYCLE_JAN_REDELIVERY],
+    states: 'past the bound the route answers 5xx with the claim released, and the redelivery grants exactly once',
+    // atomic-application is here because without the rollback, the conflicted
+    // attempts leave their halves behind and every count below drifts.
+    breaks: ['atomic-application', 'tx-retry-bounded', 'grant-on-renewal'],
+    async run({ store, handler, assert }) {
+      store.failNextTransactions = TX_RETRIES + 1;
+      const first = await handler.deliver(fixture(CYCLE_JAN));
+      assert.equal(first.status, 500,
+        `exhausted retries answered ${first.status} — a swallowed conflict lies "done"`);
+      assert.equal(store.grants.length, 0,
+        'grants landed from attempts that were supposed to roll back');
+      const retry = await handler.deliver(fixture(CYCLE_JAN_REDELIVERY));
+      assert.equal(retry.status, 200, 'the redelivery was not let back in');
+      assert.equal(store.grants.length, 1, 'the redelivery did not land the renewal exactly once');
     },
   },
   {