@ssheleg/sheleg-dev 0.11.8 → 0.13.0

package/CHANGELOG.md

@@ -1,3 +1,50 @@
+## v0.13.0 — the gate exists on one surface, and every skill now says so
+
+This pack ships a `PreToolUse` money gate (`hooks/money-gate.js`) that refuses a refund,
+a payout, a dispute close, a live `sk_live_…` key and `SKIP_BILLING=true` in production
+until the authorised person has signed that category off. It runs on Claude Code and
+nowhere else. Measured 2026-09-14: of the seven skills, **one** (`error-tracking`) wrote
+a degradation contract; `stripe-billing` never mentioned the gate at all and
+`crypto-payments` named it and sent the consequences to the README — so the two skills
+the gate exists FOR were the two that did not say what happens without it.
+
+- **`## Degradation` in all seven skill bodies**, one line per axis, in the shape
+  `references/host-capabilities.md` requires: not-Claude-Code, installed-by-copy, and the
+  capability each skill's own work needs (Stripe CLI, node fixtures, a browser channel, a
+  console login).
+- **`check_degradation_is_written_where_a_host_capability_ships`** — a pack that ships
+  `hooks/hooks.json` requires the section in every skill body. Watched failing on four
+  skills before they were written.
+- **The body budget is MEASURED, not estimated.** This gate divided by 3.9 chars/token
+  while the family's CI auditor measures with tiktoken, and the two disagree by up to 8%
+  in the same direction: `crypto-payments` estimated **4986** and measured **4618** — a
+  verdict of *past the working limit* over 132 tokens of real headroom, which is what
+  blocked this change from landing. With no tokenizer installed the check now DISCLOSES
+  that it could not measure instead of failing a file it never counted. make-skill
+  v0.28.0 closed exactly this for the family auditor; this repo kept the estimate and so
+  kept the defect.
+- **The `биллинг` trigger is now `биллинг подписок`.** Bare `биллинг` collided with
+  `agent-orchestrator`'s `биллинг LLM` across packs, where no per-repo validator can see
+  it: this one meters what an agent burned, that one charges a card.
+- `docs/evals/stripe-billing.md` restates a measured figure (4521 tokens, tiktoken)
+  rather than a heuristic one, and the validator compares it to a measurement.
+
+## v0.12.0 — the integration doctrine closes its audit, and a crypto reference gains its map
+
+Sherlock external-v3 (43 findings) — the largest share in the family — each with
+its own executable regression.
+
+- Offline fault-injection corpora for every integration surface: card money,
+  crypto, ad tracking, error tracking, sign-in and page speed. Each case injects a
+  fault and judges it with a STATE or OUTPUT oracle rather than a provider stub
+  judging itself, and each counterexample fails before the fix and passes after.
+- `test/negatives.py` stops reading an environment failure as a proven validation
+  gap: explicit stages, a resource preflight, a per-step timeout, and cleanup in a
+  `finally`. A full disk once printed forty "the guard does not actually fire"
+  findings; it now prints TEST_ERROR and zero guard-bypass findings.
+- `crypto-payments/references/callback-route-hardening.md` gained a `## Contents`.
+- CI now MEASURES the token budget with a real tokenizer instead of estimating it.
+
 ## v0.11.8 — a Contents entry pointing nowhere is depth the file does not have
 
 The family audit's second round (2026-09-07) read the eight reference files that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/sheleg-dev",
-  "version": "0.11.8",
+  "version": "0.13.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"
@@ -43,9 +43,10 @@
     "skill"
   ],
   "scripts": {
-    "test": "python3 test/validate.py && node test/moneygate_test.js && node test/fixtures_test.js && node test/installer_test.js",
+    "test": "python3 test/validate.py && node test/moneygate_test.js && node test/fixtures_test.js && node test/installer_test.js && npm run test:audit",
     "test:negatives": "python3 test/negatives.py",
     "test:schemas": "python3 test/check_schemas.py",
-    "test:all": "python3 test/validate.py && node test/moneygate_test.js && node test/fixtures_test.js && node test/installer_test.js && python3 test/negatives.py"
+    "test:all": "python3 test/validate.py && node test/moneygate_test.js && node test/fixtures_test.js && node test/installer_test.js && python3 test/negatives.py && npm run test:audit",
+    "test:audit": "for t in test/audit_regressions/*.py; do python3 \"$t\" || exit 1; done"
   }
 }

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.11.8",
+  "version": "0.13.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/sheleg-dev/skills/ad-tracking/SKILL.md

@@ -75,8 +75,10 @@ defaults after the script has loaded looks correct in every test that begins by
 accepting consent, and loses the denied population entirely.
 
 **Denied is not off.** With Advanced mode Google still receives cookieless
-pings and models conversions from them — roughly two thirds of the otherwise
-lost data. Blocking the script instead throws that away.
+pings and models conversions from them (Google's own dated case studies cite
+~65–70%; yours is unknown until measured). Whether pre-consent pings are
+lawful in your jurisdiction is counsel's call — Basic is the conservative
+mode, and it still gets Google's general modeling.
 ## Google Analytics 4
 
 ### Setup
@@ -112,7 +114,10 @@ lost data. Blocking the script instead throws that away.
 <!-- 3. Configure -->
 <script>
   gtag('js', new Date());
-  gtag('config', 'G-XXXXXXXXXX', { allow_enhanced_conversions: true });
+  // GA4 config carries NO allow_enhanced_conversions — that flag belongs on the
+  // Google Ads `AW-` tag only (see the Enhanced-conversions section); on a `G-`
+  // tag it enables nothing and contradicts this skill's own rule.
+  gtag('config', 'G-XXXXXXXXXX');
 </script>
 ```
 
@@ -230,15 +235,26 @@ fbq('init', 'PIXEL_ID');
 fbq('track', 'PageView');
 ```
 
-**noscript fallback (required for pixel verification):**
+**noscript fallback — consent-gated, or omitted.** A bare `<noscript>` Meta
+pixel FIRES on every JS-disabled page view — no banner, no `fbq`, no consent —
+contradicting this stack's rule that Meta is *not rendered until consent*. So
+emit it from the SERVER, only when a **server-verifiable consent** (a signed
+HttpOnly cookie the server reads before writing the HTML) already exists. Cannot
+verify consent server-side? **Omit it** — Meta's verification does not need it,
+and a request that fired cannot be taken back:
 
 ```html
-<noscript>
-  <img height="1" width="1" style="display:none"
-    src="https://www.facebook.com/tr?id=PIXEL_ID&ev=PageView&noscript=1"/>
-</noscript>
+<!-- server-side: render ONLY when consent is proven -->
+{% if consent_cookie_verified and consent.ad_storage == "granted" %}
+<noscript><img height="1" width="1" style="display:none"
+  src="https://www.facebook.com/tr?id=PIXEL_ID&ev=PageView&noscript=1"/></noscript>
+{% endif %}
 ```
 
+Snippets here come from EXECUTABLE templates, so a static check refuses the two
+mistakes this section prevents: `allow_enhanced_conversions` on a `G-` tag, and
+a `noscript` Meta pixel not behind a server-verified consent condition.
+
 ### Standard Events
 
 Meta defines 17 standard events. The four that carry a SaaS funnel are
@@ -398,3 +414,14 @@ when** line, so the trigger has one home and this table stays an index.
 
 For the page-speed side of the same problem — what the tag does to LCP and TBT,
 and what to do about it — see the `frontend-performance` skill in this pack.
+
+## Degradation
+
+- **Not Claude Code** (Cursor, Codex, the skills CLI, the API container): the pack's
+  `PreToolUse` gate does not run. It is the thing that refuses a live key or an
+  irreversible action in this pack; elsewhere those rules are advice you follow by hand.
+- **Installed by copy rather than as a plugin**: the doctrine arrives, `hooks/` does not
+  — same loss, same remedy.
+- **No network, or the ad platform's API unreachable**: server-side events cannot be
+  verified end to end. Say the dedup check did not run rather than reporting it held;
+  a browser pixel firing proves the browser, never the conversion.

package/plugins/sheleg-dev/skills/ad-tracking/references/consent-mode.md

@@ -20,24 +20,67 @@
 ## Status check — 2026
 
 Consent Mode v2 has been required since **March 2024** for anyone using Google
-advertising products with EEA or UK traffic, and by 2026 Google additionally
-expects a **certified CMP** from the Consent Management Platform programme —
-a hand-rolled banner that sets the signals correctly is no longer sufficient on
-its own for Google's ad products. Verify your CMP's certification status before
-treating this box as ticked. *(Checked 2026-08-06.)*
+advertising products with EEA or UK traffic. The **certified CMP** requirement
+(Consent Management Platform programme) is scoped to Google's **publisher**
+products — AdSense, Ad Manager, AdMob — where a hand-rolled banner is no longer
+sufficient; on the advertiser side (Google Ads, GA4) a certified CMP is
+Google's recommendation, not a stated requirement. Verify the programme's
+current scope and your CMP's certification before treating either box as
+ticked. *(Checked 2026-08-06; scope per Google's CMP programme pages.)*
 
 ## Advanced vs Basic Mode
 
 | Mode | Tags load before consent? | Cookieless pings? | Conversion modeling? |
 |------|--------------------------|-------------------|---------------------|
-| **Basic** | No — tags blocked until consent granted | No | No |
-| **Advanced** | Yes — tags load with denied defaults | Yes | Yes (recovers ~65-70% of lost data) |
+| **Basic** | No — tags blocked until consent granted | No | **General** modeling only — Google models from aggregate patterns, less accurately; "no modeling" was never true |
+| **Advanced** | Yes — tags load with denied defaults | Yes | **Advertiser-specific** modeling from your own cookieless pings |
+
+**Which mode is three separate questions, not one default.** *Provider policy:*
+Google's modeling is stronger under Advanced (advertiser-specific vs general).
+*Business choice:* Advanced sends cookieless pings BEFORE consent — how much
+recovered attribution is worth that is yours to decide. *Jurisdiction:* whether
+pre-consent pings are lawful where your users are is counsel's question — some
+EEA regulators read them restrictively, and Basic is the conservative answer.
+The recovery figures Google has cited (~65–70%) come from its own dated,
+campaign-specific case studies — **your recovery is unknown until measured on
+your traffic**; an unmeasured percentage is not a promise.
+
+**Two different technical contracts — never one snippet with a policy flag.**
+Each mode has its own wiring and its own pre-consent behaviour, and mixing
+their halves produces a page that behaves as neither:
+
+```html
+<!-- ADVANCED contract: denied defaults set synchronously, tags load at once.
+     Pre-consent behaviour: cookieless pings go out, no cookies are written. -->
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag(){dataLayer.push(arguments);}
+  gtag('consent', 'default', { 'ad_storage': 'denied', 'ad_user_data': 'denied',
+    'ad_personalization': 'denied', 'analytics_storage': 'denied',
+    'wait_for_update': 500 });
+</script>
+<script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
+```
 
-**Always prefer Advanced mode** — it allows Google to model conversions from users who deny
-consent without storing any cookies or identifying individuals.
+```html
+<!-- BASIC contract: NO tag bytes reach the page before consent.
+     Pre-consent behaviour: zero requests to Google — nothing loads, nothing pings. -->
+<script>
+  function loadTagsAfterConsent() {           // called by the CMP's grant callback
+    const s = document.createElement('script');
+    s.async = true; s.src = 'https://www.googletagmanager.com/gtag/js?id=TAG_ID';
+    document.head.appendChild(s);
+    gtag('js', new Date()); gtag('config', 'TAG_ID');
+  }
+</script>
+```
 
-Advanced mode = `gtag('consent', 'default', { ... 'denied' ... })` then load tags normally.
-Basic mode = physically block `<script>` tags until consent granted.
+**The mixed waterfall is the defect to test for**: gtag.js loaded eagerly (the
+Advanced half) while the config call waits for consent (the Basic half) sends
+requests the Basic policy said never happen and models nothing the Advanced
+policy promised. A fixture for each mode asserts ITS pre-consent behaviour —
+Advanced: pings without cookies; Basic: zero Google requests — and a page
+failing both assertions is running the mix.
 
 ## All Consent Types
 
@@ -71,7 +114,9 @@ gtag('consent', 'default', {
   'wait_for_update': 500
 });
 
-// Grant by default everywhere else (no banner needed)
+// Granted by default everywhere else — a recorded BUSINESS choice, not legal
+// advice: whether a banner is needed outside the listed regions is a
+// jurisdiction question (ePrivacy transpositions, US state laws, LGPD…).
 gtag('consent', 'default', {
   'ad_storage': 'granted',
   'ad_user_data': 'granted',

package/plugins/sheleg-dev/skills/crypto-payments/SKILL.md

@@ -179,26 +179,16 @@ Verify the signature **before** parsing anything into your domain, and return
 
 Do not read-then-write. Make the database refuse the second delivery:
 
-```ts
-const { count } = await db.payment.updateMany({
-  where: {
-    invoiceId,
-    status: { notIn: FINAL_STATUSES },   // ← the guard: a settled payment cannot re-settle
-  },
-  data: { status: mapped, paidAmount, txid, network, settledAt: new Date() },
-});
-
-if (count === 0) {
-  // already final: a retry, or a late duplicate. Acknowledge and do nothing.
-  return res.status(200).json({ ok: true, duplicate: true });
-}
-
-await creditUser(...);   // only reachable once per invoice
-```
-
-`updateMany` + a status guard is a compare-and-swap. `findFirst` followed by
-`update` is a race, and the two deliveries that arrive 40ms apart will both pass
-the read.
+Three things are separate — the payment's LIFECYCLE status, the immutable
+GRANT a confirmed settlement earns, and any refund/hold — and conflating them
+credits money that never settled. The CAS (`updateMany` with a `status notIn
+FINAL_STATUSES` guard) advances the LIFECYCLE only: it returns `count: 1` for
+a transition to FAILED exactly as it does for PAID, so it is not permission to
+credit. **Credit only a confirmed settlement (`mapped === 'PAID'`), once,
+behind a UNIQUE per-invoice grant-ledger row atomic with the credit; refunds
+and holds take their own path and are never swallowed as a duplicate.** The
+worked handler is in
+[`references/callback-route-hardening.md`](references/callback-route-hardening.md).
 
 **Always return 200 for a duplicate.** A 409 makes the provider retry forever.
 
@@ -265,18 +255,26 @@ Write them on the settling webhook, in the same update that flips the status.
 
 ## Crediting: the amount waterfall
 
-What do you credit when the numbers disagree? Prefer the most authoritative,
-fall back in a fixed order, and log which one won:
+Four dimensions, and they never mix implicitly: **Money** (currency + minor
+units — never floats), **Asset** (network + token + decimal amount),
+**Entitlement** (plan units) and a **dated FX quote** (rate + source + time).
+`paidAmountUsd` and `amountUsd` are Money; `tokenAmount` is an **Asset amount**
+(the invoiced base + buffer — NOT plan units). A `??` across dimensions is an implicit
+conversion, so first bring each candidate to USD minor — an Asset amount
+converts only via a dated quote from a known source; an unknown or missing
+quote **blocks** the conversion rather than guessing:
 
 ```ts
-const credit = payment.paidAmountUsd     // gateway's valuation of what arrived
-            ?? payment.tokenAmount        // what the plan says this purchase grants
-            ?? payment.amountUsd;         // the original intent — last resort
+const usd = [payment.paidAmountUsd            // Money: gateway's valuation
+  , toUsdMinor(payment.tokenAmount, quote)    // Asset -> Money, dated quote or BLOCKED
+  , payment.amountUsd];                       // Money: the intent — last resort
+const credit = usd.find(v => v != null);
 ```
 
 The order matters: valuing an over-payment at the intent silently keeps the
 excess, and valuing an under-payment at the intent gives away product. Write an
-audit row naming the source, or the first disputed balance is unprovable.
+audit row naming the source AND the quote used, or the first disputed balance
+is unprovable.
 
 ---
 
@@ -401,3 +399,18 @@ a green suite, each with the defect it catches:
 | Cannot answer "how much did we net" | commission and `merchantAmount` never stored |
 | A dev machine, a CI job or an agent run is holding the production key | no separate credential, and no assertion binding the key to a declared environment |
 | Real invoices in a merchant dashboard nobody watches | a staging credential declared live — the mismatch nothing refused |
+
+## Degradation
+
+- **Not Claude Code** (Cursor, Codex, the skills CLI, the API container): the
+  `PreToolUse` gate named above — `plugins/sheleg-dev/hooks/money-gate.js` — does not
+  run there. Nothing refuses a payout, a refund, an exported `HELEKET_API_KEY` in a
+  `test` run, or `SKIP_BILLING=true` in production. The three lines are advice again,
+  which is exactly the state that made them ineffective for four releases: name the
+  surface you are on, and make the authorisation a human step out loud.
+- **Installed by copy rather than as a plugin**: the doctrine arrives, the hook does
+  not. The README carries the categories and how one is authorised for a session.
+- **No node, or the fixtures cannot run**: the invariant fixtures are the executable
+  half of this skill. Say the check did not run rather than reporting the invariant as
+  held — an unrun check and a passing one are indistinguishable from the exit code
+  nobody looked at.

package/plugins/sheleg-dev/skills/crypto-payments/references/callback-route-hardening.md

@@ -9,6 +9,12 @@ mode that looks like "webhooks stopped working" rather than like a security even
 
 ---
 
+## Contents
+
+- [IP allowlisting behind a proxy](#ip-allowlisting-behind-a-proxy)
+- [CSRF exemption for callback routes](#csrf-exemption-for-callback-routes)
+- [Crediting: lifecycle, grant and refund are separate (DV-05)](#crediting-lifecycle-grant-and-refund-are-separate-dv-05)
+
 ## IP allowlisting behind a proxy
 
 Signature verification is the real gate; the allowlist is defence in depth and
@@ -53,3 +59,49 @@ too, which is where the money is.
 Back to [`SKILL.md`](../SKILL.md) — *Webhook signature verification* is the gate these two
 sit behind, and *Test matrix* in
 [`testing-and-local-dev.md`](testing-and-local-dev.md) carries the non-allowlisted-IP case.
+
+
+## Crediting: lifecycle, grant and refund are separate (DV-05)
+
+The CAS advances the payment's lifecycle; the GRANT is a second, independent
+step gated on a confirmed settlement; refunds and holds have their own path.
+Conflating them credits money that never settled — a webhook that transitions
+a payment to FAILED passes the CAS (`count: 1`) exactly as PAID does.
+
+```ts
+// 1. Advance the lifecycle by compare-and-swap. Fires for ANY non-final
+//    transition — PAID, FAILED, UNDERPAID, REFUNDED alike — so it is NOT
+//    permission to credit. It only records what the provider said.
+const { count } = await db.payment.updateMany({
+  where: { invoiceId, status: { notIn: FINAL_STATUSES } },
+  data: { status: mapped, paidAmount, txid, network, settledAt: new Date() },
+});
+
+// 2. Refunds and holds are their own path — never swallowed as a duplicate.
+if (mapped === 'REFUNDED' || mapped === 'ON_HOLD') {
+  await recordRefundOrHold(invoiceId, mapped);         // own ledger, own rules
+  return res.status(200).json({ ok: true });
+}
+if (count === 0) {
+  return res.status(200).json({ ok: true, duplicate: true });  // already advanced
+}
+
+// 3. CREDIT ONLY A CONFIRMED SETTLEMENT, and only once — an immutable grant
+//    row keyed by invoice is the business dedup, atomic with the credit.
+//    FAILED/UNDERPAID/pending advance the lifecycle above and grant NOTHING.
+if (mapped === 'PAID') {
+  await db.$transaction(async (tx) => {
+    try {
+      await tx.grantLedger.create({ data: { invoiceId, amount: creditFor(invoiceId) } });
+    } catch (e) {
+      if (isUniqueViolation(e)) return;                // this settlement already granted
+      throw e;
+    }
+    await creditUser(tx, invoiceId);
+  });
+}
+```
+
+`updateMany` + a status guard is a compare-and-swap for the LIFECYCLE, not the
+grant: a CAS that advanced a payment to FAILED returns `count: 1` too, so the
+credit hangs off `mapped === 'PAID'` and a UNIQUE grant row, never off the CAS.

package/plugins/sheleg-dev/skills/crypto-payments/references/heleket-provider.md

@@ -111,7 +111,7 @@ sequenceDiagram
   H->>W: POST { type:"payment", status:"paid", uuid, sign, ... }
   W->>W: Verify caller IP + MD5 signature
   W->>W: Type guard, idempotency check
-  W->>DB: $transaction:<br/>  updateMany(status notIn final)<br/>  creditAccountPurchasedTokens<br/>  logTokenAudit(action:"crypto_topup")<br/>  optional createBalanceSubscription / seat upgrade
+  W->>DB: $transaction (only if status==paid):<br/>  updateMany(status notIn final)<br/>  INSERT grantLedger(invoiceId) UNIQUE<br/>  creditAccountPurchasedTokens<br/>  logTokenAudit(action:"crypto_topup")<br/>  optional createBalanceSubscription / seat upgrade
   W-->>H: 200 { status: "ok" }
   H-->>U: Redirect to url_success
   U->>FE: Polls /api/billing/crypto/status?orderId=...
@@ -394,7 +394,7 @@ model CryptoPayment {
   heleketuuid      String              @unique @map("heleket_uuid")
   orderId          String              @unique @map("order_id")
   amountUsd        Float               @map("amount_usd")          // base amount user requested
-  tokenAmount      Float               @map("token_amount")        // base + buffer = amount sent to Heleket
+  tokenAmount      Float               @map("token_amount")        // ASSET amount (invoice token): base + buffer sent to Heleket — never plan units, never added to USD fields without a dated FX quote
   status           CryptoPaymentStatus @default(pending)
   paymentUrl       String?             @map("payment_url")
   currency         String?                                          // pricing currency, "USD"
@@ -1248,27 +1248,36 @@ Without a buffer, a $30 invoice frequently lands as `payment_amount_usd: 29.97`,
 your balance is debited at $30 to provision a subscription, the user gets stuck on a
 "insufficient balance" error 30 seconds after paying.
 
-**The fix**: add 1% on the invoice side, credit the **full invoice amount** (not the
-base) to the user's balance.
+**The fix**: add 1% on the invoice side — and then WHAT HAPPENS TO THE EXCESS is a
+**required business policy, not a template default**. The template carries the enum and
+no preselected price:
 
 ```ts
-const bufferAmount  = Math.ceil(amountUsd * 0.01 * 100) / 100;   // 0.30 for $30
-const invoiceAmount = Math.round((amountUsd + bufferAmount) * 100) / 100;  // 30.30
-const tokenAmount   = invoiceAmount;       // user gets the buffer back as balance
+// REQUIRED — the template does not choose for you. A missing policy BLOCKS
+// invoice creation and asks; it never silently invents a fee.
+type ExcessPolicy = 'refund_excess' | 'credit_excess' | 'buffer_fee';
 ```
 
-Show the breakdown in the UI:
+One unit-safe example per variant (all Money in USD minor, per the dimensional
+contract — the buffer never mixes with Asset amounts):
 
-```
-Subscription:    $30.00
-Crypto buffer:   +$0.30  (covers conversion losses, credited to your balance)
-Invoice total:   $30.30
+- **`refund_excess`** — pay 3030¢ against a 3000¢ subscription → 30¢ goes BACK to the
+  payer (an on-chain or balance refund row with its own audit line).
+- **`credit_excess`** — the 30¢ lands as 30¢ of BALANCE after provisioning; the UI
+  breakdown says "credited to your balance", and the user keeps it.
+- **`buffer_fee`** — the 30¢ is retained as a disclosed fee: it appears as "buffer
+  fee: 30¢" on the invoice BEFORE payment, never discovered afterwards.
+
+```ts
+const bufferAmount  = Math.ceil(amountUsd * 0.01 * 100) / 100;   // 0.30 for $30
+const invoiceAmount = Math.round((amountUsd + bufferAmount) * 100) / 100;  // 30.30
+// tokenAmount = invoiceAmount is the ASSET amount sent to Heleket either way;
+// the ExcessPolicy decides the LEDGER, not the invoice.
 ```
 
-Why credit the full invoice (not just `paymentAmountUsd`)? Because if the user pays
-exactly $30.30, they should keep $0.30 in balance after the subscription is provisioned.
-If Heleket reports `payment_amount_usd: 30.27` (a 0.1% loss), use that instead — the
-credit waterfall `paymentAmountUsd ?? tokenAmount ?? amountUsd` does this automatically.
+If Heleket reports `payment_amount_usd: 30.27` (a 0.1% loss), the waterfall values the
+payment at that figure — and the excess policy then applies to whatever remains above
+the base, in USD minor.
 
 ---
 
@@ -1301,16 +1310,26 @@ Heleket refunds are **merchant-initiated only** (user cannot self-refund). They
    manually via the dashboard).
 2. The user's destination wallet address (you have it as `fromAddress`).
 
-Webhook handling:
+Webhook handling — refunds and holds are a SEPARATE ledger, not a branch of the
+paid path, and they are never dropped as a "duplicate" just because the invoice
+already reached `paid` (DV-05). A refund event arriving after `paid` is the
+NORMAL case, not a replay: the CAS that guards the paid→credit transition
+treats an already-final invoice as a duplicate, so the refund/hold statuses
+take their own path BEFORE that guard.
 
 | Status | Action |
 |--------|--------|
-| `refund_process` | Update DB row to `refund_process`, no balance change. |
-| `refund_paid` | Update DB row to `refund_paid`. **Optionally** debit the user's balance manually if you previously credited them — the reference implementation leaves this to ops to avoid accidental negative balances. |
-| `refund_fail` | Update DB row to `failed`, alert ops. |
-
-There is no chargeback mechanism in crypto — once `paid` is on-chain, the only path back
-is a refund initiated by you. Set up a financial alarm at, e.g., $500/month of refunds.
+| `refund_process` | Record a `refund_ledger` row `(paymentId, "refund_process")`, no balance change. |
+| `refund_paid` | Record `refund_ledger` `(paymentId, "refund_paid")` and, if the invoice was credited, debit the credited amount — **inside one transaction, keyed by `(paymentId, "refund_paid")`** so a redelivered refund webhook debits ONCE, never twice. A negative-balance clamp and its ops decision are DV-04's rule. |
+| `refund_hold` / `on_hold` | Record `refund_ledger` `(paymentId, status)`; pause downstream side effects, no debit yet. |
+| `refund_fail` | Record `refund_ledger` `(paymentId, "refund_fail")`, alert ops. |
+
+The refund ledger is keyed by `(paymentId, status)` and its writes are
+idempotent: a repeated refund webhook finds the row and stops, so a
+paid→refund sequence adjusts the balance exactly once and a redelivery adds
+nothing. There is no chargeback mechanism in crypto — once `paid` is on-chain,
+the only path back is a refund initiated by you. Set up a financial alarm at,
+e.g., $500/month of refunds.
 
 ---
 

package/plugins/sheleg-dev/skills/error-tracking/SKILL.md

@@ -220,12 +220,40 @@ Observed 2026-08-24: a bot token was rotated, and for ten minutes the platform
 reported the dyno `up` with a clean log while the API returned `401` to every
 call and no user was served. Nothing in the system could tell the difference.
 
-**Liveness must assert the thing the service exists to do**, not that a process
-exists. For anything holding a long-lived authenticated connection, check the
-credential periodically and exit non-zero when it fails — a crash loop is
-visible, a silent zombie is not. Sentry helps only if something raises; a
-connection that stopped working without raising produces no event at all. Cron
-monitors (`sentry monitor`) cover the shape where a job stops running.
+**Three health states, because "up" is not one question.** *Liveness* — the
+process exists and its loop runs. *Readiness* — it can do its job right now
+(the credential works); a live process with a dead credential is **live but
+NOT ready**, and a load balancer or supervisor reads readiness, not liveness.
+*degraded_auth* — auth is failing, and its two sub-cases take OPPOSITE actions:
+
+- **transient** (a rotated token, a network blip, a `401` a fresh connect
+  fixes): bounded retry with backoff, and a restart is legitimate because the
+  next start picks up the new credential — this is where "exit non-zero, a
+  crash loop is visible" is right.
+- **terminal / revoked** (the session was killed server-side): a restart just
+  re-loops a login that can never succeed. **Stop work, go NOT ready, alert
+  with the account named, and wait for FRESH auth** — never a restart loop. A
+  bounded retry count separates the two: retries exhausted against the same
+  auth error is terminal, not "try harder".
+
+**The recovery contract — one decision table both skills obey.** A supervisor
+RESTART is applied only where the policy is `recoverable`; a `terminal` event
+is never restarted, whichever skill saw it first:
+
+| Event | Policy | Supervisor action | Readiness |
+|---|---|---|---|
+| transient auth failure (rotated token, network 401) | recoverable | restart / bounded retry | not ready → ready on success |
+| retries exhausted on the same auth error | terminal | STOP, alert, wait for fresh auth | not ready until re-auth |
+| revoked / killed session (MTProto or bearer) | terminal | STOP, alert, wait for fresh auth | not ready until re-auth |
+
+The row a revoked session lands on is the SAME in both packs, so the identical
+event cannot get opposite actions: error-tracking and `telegram-userbots` name
+this one contract, and a supervisor that restarts a `terminal` policy is the
+bug the table exists to forbid.
+
+Sentry helps only if something raises; a connection that stopped working
+without raising produces no event at all. Cron monitors (`sentry monitor`)
+cover the shape where a job stops running.
 
 ## Degradation