diff --git a/README.md b/README.md
index 84f043f..e858033 100644
--- a/README.md
+++ b/README.md
@@ -149,6 +149,32 @@ changes nothing; `mode=send` performs renewals and sends the reminder and
requires `ALLOWANCE_POLICY=on`. Deactivation additionally requires
`ALLOWANCE_DEACTIVATE=on`.
+### Allowance shortfall (a paid cycle OC truncated)
+
+Open Collective aligns every recurring charge onto the collective's common
+billing day, so a member who joins mid-month is charged again well before a full
+month has elapsed — they pay for a full month and receive less than one. The
+co-op's remedy: credit the missing **allowance** (the flat `MEMBER_BUDGET`
+pro-rated for the days lost, `FULL_PAID_MONTH_DAYS = 30`, unrounded) as
+non-expiring credits — the same balance that extends the allowance and is spent
+only after it. It is never a share of what they paid.
+
+The set is derived FROM DATA, on every sweep (`POST /admin/sweep` calls
+`reconcile_allowance_shortfalls`, as does `POST /admin/shortfall-credits`):
+each MONTHLY order's real charge history is read from Open Collective, and any
+consecutive pair on the SAME order less than a full month apart is a truncated
+cycle. Two subscriptions a member happens to hold are judged separately; a gap
+whose dates cannot be determined is skipped and logged. Each credit is keyed to
+the specific OC charge that caused it (`credit_ledger.reference` = the charge
+`publicId`), so a re-run credits nothing twice — dedupe is on the charge, not
+the member — and the ledger `reason` names the cycle so a member's question is
+answerable from it.
+
+Member notices ride the same pass, but default OFF
+(`ALLOWANCE_SHORTFALL_EMAILS=off`); set it to `on` to send the staged notice,
+at most once per charge (`shortfall_notices`). `mode=report` on
+`/admin/shortfall-credits` previews the affected set and changes nothing.
+
### Energy & carbon metrics
The daily snapshot also computes energy (Wh) and carbon (gCO₂e) from output tokens,
diff --git a/app/main.py b/app/main.py
index ad69320..0204dfd 100644
--- a/app/main.py
+++ b/app/main.py
@@ -4791,6 +4791,383 @@ async def reconcile_allowances(send: bool = False) -> dict:
}
+# --------------------------------------------------------------------------- #
+# Allowance shortfall — OC's billing-day alignment truncates a paid cycle. #
+# --------------------------------------------------------------------------- #
+# Open Collective aligns every recurring charge onto the collective's COMMON
+# billing day, so a member who joins mid-month is charged again well before a
+# full month has elapsed: they pay for a full month and receive less than one.
+# Operator decision (2026-11-04): make the member whole by crediting the missing
+# ALLOWANCE — the flat MEMBER_BUDGET pro-rated for the days lost — as
+# non-expiring credits (the same balance that extends the allowance and is spent
+# only after it). It is NOT a share of what they paid, and it is NOT rounded.
+#
+# Scope: EVERY monthly paid cycle shorter than a full month, for any member and
+# any cycle (not only the first — OC can re-align an existing charge date too).
+# Derived FROM DATA (each recurring order's real charge history); members are
+# never asked to claim it. Idempotent: each credit is keyed to the specific OC
+# charge that caused it, so a re-run credits nothing twice. A charge whose date
+# cannot be determined is SKIPPED and logged — paying a credit that is not owed
+# is worse than paying one late.
+#
+# Member notices go out automatically (the sweep does both in one pass), but they
+# default OFF (ALLOWANCE_SHORTFALL_EMAILS=off) so the wording can be reviewed
+# before any member is written to about billing. Setting it to `on` sends the
+# staged notice on the next sweep; nothing is re-sent per charge.
+FULL_PAID_MONTH_DAYS = 30 # the allowance is a flat monthly amount => "a month" = 30 days
+ALLOWANCE_SHORTFALL_EMAILS = (os.environ.get("ALLOWANCE_SHORTFALL_EMAILS", "off") or "off").strip().lower()
+
+
+def shortfall_reason(prev: str, cur: str) -> str:
+ """Human-readable ledger reason — a member's question is answerable from it."""
+ return f"allowance shortfall, truncated paid cycle {prev}→{cur} (OC billing alignment)"
+
+
+# Members already made whole OUTSIDE this mechanism, keyed by (email, OC charge
+# reference). [redacted member reference] received a manual allowance reset
+# on 2026-11-04 for the cycle OC truncated ([redacted timeline]); that
+# specific charge is excluded so a re-run never credits it again. Later charges
+# form new cycles and are credited normally.
+SHORTFALL_REMEDIATED: set[tuple[str, str]] = {
+ ("[redacted member reference]", "[redacted member reference]"),
+}
+
+
+def _usd(x: float) -> str:
+ """Format a credit amount for a member without inventing cents (2 -> $2)."""
+ return f"${x:g}"
+
+
+def _ensure_shortfall_tables(conn) -> None:
+ """Records which charge-triggered notices have actually been sent.
+
+ Kept apart from the credit ledger on purpose: the ledger answers "what did we
+ credit, and why", this answers "what left the building". A notice is sent at
+ most once per charge reference.
+ """
+ conn.execute(
+ "CREATE TABLE IF NOT EXISTS shortfall_notices ("
+ " reference TEXT PRIMARY KEY, email TEXT NOT NULL, amount REAL NOT NULL,"
+ " sent_at TEXT NOT NULL DEFAULT (datetime('now')))"
+ )
+ conn.commit()
+
+
+def credit_reference_exists(reference: str) -> bool:
+ """Has a credit already been recorded against this OC charge reference?"""
+ conn = get_db()
+ row = conn.execute(
+ "SELECT 1 FROM credit_ledger WHERE reference = ? LIMIT 1", (reference,)
+ ).fetchone()
+ conn.close()
+ return bool(row)
+
+
+def shortfall_notice_sent(reference: str) -> bool:
+ conn = get_db()
+ row = conn.execute(
+ "SELECT 1 FROM shortfall_notices WHERE reference = ? LIMIT 1", (reference,)
+ ).fetchone()
+ conn.close()
+ return bool(row)
+
+
+def mark_shortfall_notice_sent(reference: str, email: str, amount: float) -> None:
+ conn = get_db()
+ _ensure_shortfall_tables(conn)
+ conn.execute(
+ "INSERT OR REPLACE INTO shortfall_notices (reference, email, amount, sent_at)"
+ " VALUES (?, ?, ?, datetime('now'))",
+ (reference, email, amount),
+ )
+ conn.commit()
+ conn.close()
+
+
+async def fetch_oc_monthly_order_charges() -> list[dict]:
+ """Every MONTHLY order's real contribution charges — one record per order.
+
+ A record is {"slug", "order_id", "charges": [(datetime, publicId), ...]} from
+ ONE order. Truncation is judged per order: merging the charges of two
+ DIFFERENT subscriptions a member happens to hold invents a short gap that is
+ not a truncated cycle (one member started a second monthly order six days
+ after the first; that is not OC re-aligning a charge). Raises on failure so
+ the caller skips rather than mis-decides. Charges are the CONTRIBUTION
+ amounts INTO the collective (a non-refund CREDIT), one per charge.
+ """
+ if not OC_PERSONAL_TOKEN:
+ raise RuntimeError("OC_PERSONAL_TOKEN not set; cannot fetch order charges")
+ query = (
+ '{ collective(slug: "%s") { orders(limit: 200) { totalCount nodes { '
+ "id frequency fromAccount { slug } "
+ "transactions { publicId createdAt type kind isRefund } } } } }"
+ % OC_COLLECTIVE_SLUG
+ )
+ async with httpx.AsyncClient(timeout=30.0) as client:
+ r = await client.post(
+ OC_GRAPHQL_URL,
+ headers={"Content-Type": "application/json",
+ "Authorization": f"Bearer {OC_PERSONAL_TOKEN}",
+ "Api-Version": "2022-01-01",
+ "User-Agent": "Mozilla/5.0 (X11; Linux x86_64)"},
+ json={"query": query},
+ )
+ if r.status_code != 200:
+ raise RuntimeError(f"OC order-charge fetch failed: HTTP {r.status_code}")
+ body = r.json()
+ if body.get("errors"):
+ raise RuntimeError(f"OC order-charge fetch errors: {str(body['errors'])[:200]}")
+ nodes = (((body.get("data") or {}).get("collective") or {}).get("orders") or {}).get("nodes") or []
+ out: list[dict] = []
+ for o in nodes:
+ if (o.get("frequency") or "").upper() != "MONTHLY":
+ continue
+ slug = ((o.get("fromAccount") or {}).get("slug") or "").strip()
+ if not slug:
+ continue
+ charges = []
+ for t in o.get("transactions") or []:
+ if t.get("kind") != "CONTRIBUTION" or t.get("isRefund"):
+ continue
+ if (t.get("type") or "").upper() != "CREDIT":
+ continue
+ dt = _parse_oc_dt(t.get("createdAt"))
+ if dt and t.get("publicId"):
+ charges.append((dt, t["publicId"]))
+ charges.sort()
+ if charges:
+ out.append({"slug": slug, "order_id": o.get("id"), "charges": charges})
+ return out
+
+
+def derive_shortfalls(order_records: list[dict], budget: float | None = None,
+ full_month_days: int = FULL_PAID_MONTH_DAYS) -> list[dict]:
+ """Pure: truncated paid cycles from per-order monthly charge ladders.
+
+ For each consecutive pair of charges on the SAME order, a gap shorter than a
+ full month means the member paid for a full month and received fewer days of
+ allowance. Credit = budget * days_lost / full_month_days (no rounding). One
+ record per truncated cycle; `reference` is the early charge that truncated it
+ (globally unique, so it is the idempotence key).
+ """
+ budget = MEMBER_BUDGET if budget is None else budget
+ out: list[dict] = []
+ for rec in order_records:
+ charges = rec.get("charges") or []
+ for i in range(1, len(charges)):
+ prev_dt, _ = charges[i - 1]
+ cur_dt, cur_id = charges[i]
+ gap = (cur_dt - prev_dt).days
+ if gap >= full_month_days:
+ continue
+ lost = full_month_days - gap
+ out.append({
+ "slug": rec.get("slug"), "order_id": rec.get("order_id"),
+ "prev": prev_dt.date().isoformat(), "cur": cur_dt.date().isoformat(),
+ "gap_days": gap, "days_lost": lost,
+ "amount": budget * lost / full_month_days, "reference": cur_id,
+ })
+ return out
+
+
+def shortfall_email(name: str, amount: float, prev: str, cur: str,
+ gap_days: int, days_lost: int, pack_url: str) -> tuple[str, str, str]:
+ """Build the shortfall credit notice (subject, text, html).
+
+ Same shell as welcome_email()/budget_notice_email(): cream background, white
+ card, forest-green button, inline pine-tree mark, table-based, no external
+ assets. Plain and direct — says what happened, why, the amount, and how to get
+ more. No filler, no apology theatre.
+ """
+ subject = "A credit for a short allowance cycle"
+ text = (
+ f"Hi {name},\n\n"
+ "Your Open Collective contribution is charged on the collective's billing "
+ "day, not on the day you joined. That can make a charge arrive less than a "
+ "month after the one before it, so a month you paid for turns out shorter "
+ "than a month of allowance.\n\n"
+ f"That happened on your account: charges on {prev} and {cur} were only "
+ f"{gap_days} days apart, so you paid for a full month and received "
+ f"{days_lost} days less than one.\n\n"
+ f"To make that up, we've added {_usd(amount)} to your account as credits. "
+ "Credits don't expire, and they're used after your monthly allowance.\n\n"
+ "If you'd like to add more, you can buy credit packs here:\n\n"
+ f"{pack_url}\n\n"
+ "Questions? Reply to this email or write to info@inference.coop.\n\n"
+ "— The Inference Cooperative\n"
+ )
+ html = f"""
+
+
+
+
+
+
+
+
+ |
+ {PINE_LOGO_SVG}
+ |
+
+
+
+ A credit for a short allowance cycle
+ Your Open Collective contribution is charged on the collective's billing day, not on the day you joined. That can make a charge arrive less than a month after the one before it, so a month you paid for turns out shorter than a month of allowance.
+ That happened on your account: charges on {prev} and {cur} were only {gap_days} days apart, so you paid for a full month and received {days_lost} days less than one.
+ We've added {_usd(amount)} to your account as credits. Credits don't expire, and they're used after your monthly allowance.
+ Buy credit packs
+ If you'd like to add more, you can buy credit packs at the button above.
+ |
+
+
+
+ Questions? Reply to this email or write to info@inference.coop.
+ The Inference Cooperative · inference.coop
+ |
+
+
+ |
+
+
+
+"""
+ return subject, text, html
+
+
+async def reconcile_allowance_shortfalls(send: bool = False) -> dict:
+ """Credit members whose PAID cycle Open Collective's billing-day alignment truncated.
+
+ `send=False` (report) computes the set and changes NOTHING. `send=True`
+ (honoured only when ALLOWANCE_POLICY == "on") applies one credit per truncated
+ charge — idempotent on the charge reference — and, when
+ ALLOWANCE_SHORTFALL_EMAILS == "on", sends the member notice (once per charge).
+ Emails default OFF so the wording is reviewed before any member is written to.
+ """
+ try:
+ records = await fetch_oc_monthly_order_charges()
+ except Exception as e:
+ logger.warning("Allowance shortfall: charge fetch failed; skipping (fail-safe): %s", e)
+ return {"status": "skipped", "reason": "charge_fetch_failed", "detail": str(e)[:200]}
+ try:
+ index = await fetch_member_index()
+ except Exception as e:
+ logger.warning("Allowance shortfall: member index fetch failed; skipping (fail-safe): %s", e)
+ return {"status": "skipped", "reason": "member_index_failed", "detail": str(e)[:200]}
+
+ cycles = derive_shortfalls(records)
+
+ # slug -> email from the LIVE OC member list; only provisioned, active members
+ # are credited. Orders are matched by the slug resolved from the member's email
+ # (the stored column can hold a stale guest-… slug from first provisioning).
+ slug2email: dict[str, str] = {}
+ for e, rec in index.items():
+ s = rec.get("slug") or ""
+ if s:
+ slug2email.setdefault(s, e)
+
+ conn = get_db()
+ _ensure_shortfall_tables(conn)
+ active = {r[0].strip().lower() for r in conn.execute("SELECT email FROM members WHERE active = 1")}
+ meta = {r[0].strip().lower(): {"slug": r[1], "org_slug": r[2]}
+ for r in conn.execute("SELECT email, slug, org_slug FROM members")}
+ conn.close()
+
+ acting = bool(send and ALLOWANCE_POLICY == "on")
+ mail_on = ALLOWANCE_SHORTFALL_EMAILS == "on"
+ pack_url = credit_pack_url()
+ credited, staged, skipped = [], [], []
+ seen: set[str] = set()
+
+ for c in cycles:
+ if c["reference"] in seen: # a charge truncates exactly one cycle
+ continue
+ email = slug2email.get(c["slug"])
+ if not email:
+ skipped.append({**c, "why": "no Open Collective account email for this charge's slug"})
+ continue
+ if email not in active:
+ skipped.append({**c, "email": email, "why": "not an active portal member"})
+ continue
+ m = meta.get(email) or {}
+ if email in MANUAL_MEMBERS or m.get("org_slug"):
+ skipped.append({**c, "email": email, "why": "exempt member (manual / organization-backed)"})
+ continue
+ rec = index.get(email)
+ if rec and rec.get("role") == "ADMIN":
+ skipped.append({**c, "email": email, "why": "operator account"})
+ continue
+ if (email, c["reference"]) in SHORTFALL_REMEDIATED:
+ skipped.append({**c, "email": email,
+ "why": "already remediated by a manual allowance reset (2026-11-04)"})
+ continue
+ seen.add(c["reference"])
+
+ entry = {**c, "email": email, "name": (m.get("slug") or "there")}
+ already = credit_reference_exists(c["reference"])
+ entry["already_credited"] = already
+ if not already and acting:
+ add_credits(email, c["amount"],
+ reason=shortfall_reason(c["prev"], c["cur"]),
+ reference=c["reference"])
+ try:
+ await sync_team_budget_from_balance(email)
+ except Exception as e: # budget push is best-effort
+ logger.warning("Shortfall: team budget sync failed for %s: %s", email, e)
+ entry["credited"] = True
+ elif not already:
+ entry["credited"] = False # would-credit (report mode / policy off)
+
+ if mail_on and not shortfall_notice_sent(c["reference"]):
+ subject, text_body, html_body = shortfall_email(
+ entry["name"], c["amount"], c["prev"], c["cur"], c["gap_days"],
+ c["days_lost"], pack_url)
+ if send_email(email, subject, text_body, html_body):
+ mark_shortfall_notice_sent(c["reference"], email, c["amount"])
+ entry["notified"] = True
+ else:
+ entry["notified"] = False
+ elif not mail_on:
+ entry["notice"] = "staged (ALLOWANCE_SHORTFALL_EMAILS is off)"
+
+ (credited if entry.get("credited") or entry.get("already_credited") else staged).append(entry)
+
+ newly = sum(e["amount"] for e in credited if e.get("credited"))
+ total = sum(e["amount"] for e in credited)
+ return {
+ "status": "ok",
+ "mode": ALLOWANCE_POLICY,
+ "acting": acting,
+ "emails": ALLOWANCE_SHORTFALL_EMAILS,
+ "full_month_days": FULL_PAID_MONTH_DAYS,
+ "affected": len(credited),
+ "newly_credited": sum(1 for e in credited if e.get("credited")),
+ "already_credited": sum(1 for e in credited if e.get("already_credited")),
+ "new_credit_total": round(newly, 10),
+ "affected_credit_total": round(total, 10),
+ "credits": credited,
+ "would_credit": staged,
+ "skipped": skipped,
+ }
+
+
+@app.post("/admin/shortfall-credits")
+@limiter.limit("10/minute")
+async def admin_shortfall_credits(request: Request, mode: str = "report"):
+ """Preview (default) or apply allowance-shortfall credits.
+
+ `mode=report` computes the affected set and changes nothing. `mode=send`
+ applies the credits (requires ALLOWANCE_POLICY=on) — idempotent on the OC
+ charge reference, so a second call credits nothing again. Member notices are
+ sent only when ALLOWANCE_SHORTFALL_EMAILS=on.
+ """
+ _verify_admin_token(request)
+ if mode == "send":
+ if ALLOWANCE_POLICY != "on":
+ return {"refused": f"ALLOWANCE_POLICY is '{ALLOWANCE_POLICY}', not 'on'"}
+ return await reconcile_allowance_shortfalls(send=True)
+ return await reconcile_allowance_shortfalls(send=False)
+
+
@app.post("/admin/allowance")
@limiter.limit("10/minute")
async def admin_allowance(request: Request, mode: str = "report", to: str | None = None):
@@ -4846,6 +5223,16 @@ async def admin_sweep(request: Request):
except Exception as exc: # noqa: BLE001
result["allowances"] = {"error": str(exc)[:200]}
+ # Allowance-shortfall credits: OC's billing-day alignment truncates some paid
+ # cycles. Rides the same sweep so a new member is compensated automatically;
+ # credits are idempotent on the OC charge reference. Wrapped so it can never
+ # break reconciliation; notices only go out when ALLOWANCE_SHORTFALL_EMAILS=on.
+ try:
+ result["shortfall_credits"] = await reconcile_allowance_shortfalls(
+ send=(ALLOWANCE_POLICY == "on"))
+ except Exception as exc: # noqa: BLE001
+ result["shortfall_credits"] = {"error": str(exc)[:200]}
+
return result
diff --git a/tests/test_allowance_shortfall.py b/tests/test_allowance_shortfall.py
new file mode 100644
index 0000000..d511952
--- /dev/null
+++ b/tests/test_allowance_shortfall.py
@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Regression tests for the allowance-shortfall derivation (OC billing alignment).
+
+Runnable:
+ * from the repo root: python3 tests/test_allowance_shortfall.py
+ * inside the portal app: PORTAL_CODE_DIR=/app/code python3 /tmp/test_allowance_shortfall.py
+ (the container has the app's own dependencies; the host usually does not)
+
+WHY THIS EXISTS
+ The shortfall credit must be derived FROM DATA and must never be paid twice.
+ `derive_shortfalls` is pure (no DB, no network, no clock), so the arithmetic,
+ the per-order boundary, the month-length boundary and the idempotence key are
+ all exercised directly on synthetic charge ladders.
+
+ Covered:
+ - a truncated first cycle -> one credit, pro-rated to the days lost
+ - a gap of exactly a full month -> NOT truncated (boundary)
+ - a gap LONGER than a full month -> NOT truncated (OC deferred a charge)
+ - credits are NEVER rounded -> 4.5 and 1.5 come out exact
+ - two orders are judged separately -> a cross-subscription pair is not
+ mistaken for one truncated cycle
+ - the reference is the EARLY charge -> it is the idempotence key
+"""
+import os
+import sys
+
+# Locate the app package: explicit env, the deployed path, or the repo root.
+for _cand in (os.environ.get("PORTAL_CODE_DIR"), "/app/code",
+ os.path.dirname(os.path.dirname(os.path.abspath(__file__)))):
+ if _cand and os.path.isfile(os.path.join(_cand, "app", "main.py")):
+ sys.path.insert(0, _cand)
+ break
+
+from datetime import datetime, timezone # noqa: E402
+from app.main import ( # noqa: E402
+ derive_shortfalls, shortfall_reason, _usd, SHORTFALL_REMEDIATED,
+)
+
+
+def dt(s):
+ return datetime.fromisoformat(s + "T00:00:00+00:00")
+
+
+failures = 0
+
+
+def check(name, got, want):
+ global failures
+ ok = got == want
+ if not ok:
+ failures += 1
+ print(f"[{'PASS' if ok else 'FAIL'}] {name}")
+ if not ok:
+ print(f" got {got!r}\n want {want!r}")
+
+
+# --- one truncated first cycle: joined/charged 11 Sep, re-aligned to 2 Oct (21d)
+recs = [{"slug": "member-a", "order_id": "or_1",
+ "charges": [(dt("2026-09-11"), "tx_a1"), (dt("2026-10-02"), "tx_a2")]}]
+got = derive_shortfalls(recs, budget=15.0)
+check("truncated first cycle -> one credit",
+ [(g["prev"], g["cur"], g["gap_days"], g["days_lost"], g["amount"], g["reference"]) for g in got],
+ [("2026-09-11", "2026-10-02", 21, 9, 4.5, "tx_a2")])
+
+# --- boundary: a gap of exactly 30 days is a full month -> nothing
+recs = [{"slug": "member-b", "order_id": "or_2",
+ "charges": [(dt("2026-10-02"), "tx_b1"), (dt("2026-11-01"), "tx_b2")]}]
+check("gap == full month -> no credit", derive_shortfalls(recs, budget=15.0), [])
+
+# --- a gap LONGER than a month (OC deferred a charge) -> nothing
+recs = [{"slug": "member-c", "order_id": "or_3",
+ "charges": [(dt("2026-09-28"), "tx_c1"), (dt("2026-11-02"), "tx_c2")]}]
+check("gap > full month -> no credit", derive_shortfalls(recs, budget=15.0), [])
+
+# --- no rounding: 24-day gap -> 6 days lost -> exact 3.0; 27-day -> 1.5
+recs = [{"slug": "member-d", "order_id": "or_4",
+ "charges": [(dt("2026-10-09"), "tx_d1"), (dt("2026-11-02"), "tx_d2")]}]
+check("exact pro-rate, no rounding", [g["amount"] for g in derive_shortfalls(recs, 15.0)], [3.0])
+recs = [{"slug": "member-e", "order_id": "or_5",
+ "charges": [(dt("2026-10-06"), "tx_e1"), (dt("2026-11-02"), "tx_e2")]}]
+check("half-dollar stays exact", [g["amount"] for g in derive_shortfalls(recs, 15.0)], [1.5])
+
+# --- per-order boundary: two orders six days apart are NOT one truncated cycle
+recs = [
+ {"slug": "member-f", "order_id": "or_6a", "charges": [(dt("2026-10-16"), "tx_f1")]},
+ {"slug": "member-f", "order_id": "or_6b", "charges": [(dt("2026-10-22"), "tx_f2")]},
+]
+check("two subscriptions are judged separately (no cross-order pair)",
+ derive_shortfalls(recs, budget=15.0), [])
+
+# --- a later (non-first) cycle can be truncated too
+recs = [{"slug": "member-g", "order_id": "or_7",
+ "charges": [(dt("2026-09-02"), "tx_g1"), (dt("2026-10-02"), "tx_g2"),
+ (dt("2026-10-20"), "tx_g3")]}]
+check("a later cycle is caught too",
+ [(g["prev"], g["cur"], g["reference"]) for g in derive_shortfalls(recs, 15.0)],
+ [("2026-10-02", "2026-10-20", "tx_g3")])
+
+# --- the reference is the EARLY charge (the idempotence key)
+recs = [{"slug": "member-h", "order_id": "or_8",
+ "charges": [(dt("2026-10-15"), "tx_h1"), (dt("2026-11-02"), "tx_h2")]}]
+check("reference is the truncating (second) charge",
+ [g["reference"] for g in derive_shortfalls(recs, 15.0)], ["tx_h2"])
+
+# --- formatting and reason helpers
+check("_usd keeps exact amounts", [_usd(2.0), _usd(4.5), _usd(1.5)], ["$2", "$4.5", "$1.5"])
+check("reason names the cycle",
+ shortfall_reason("2026-10-07", "2026-11-02"),
+ "allowance shortfall, truncated paid cycle 2026-10-07→2026-11-02 (OC billing alignment)")
+
+# --- the manual-remediation exclusion is keyed on (email, charge ref)
+check("remediated member/charge excluded",
+ ("[redacted member reference]", "[redacted member reference]") in SHORTFALL_REMEDIATED, True)
+
+print(f"\n{'FAILED' if failures else 'OK'} — {failures} failure(s)")
+sys.exit(1 if failures else 0)