claude-multiacc 2.0.50 → 2.0.52

package/lib/selector_credits.py

@@ -0,0 +1,105 @@
+"""Pure, fail-closed credit telemetry normalization; no files or provider calls."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal, InvalidOperation
+
+from selector_primitives import DECIMAL_RE, timestamp
+
+CAPABILITY = "codex_credits_v1"
+HARD_CREDIT_ERRORS = {"account_mismatch", "unauthenticated", "refusal_read_failed"}
+CREDIT_FIELDS = {
+    "has_credits", "unlimited", "balance", "fetched_at", "account_id", "ordinary_usage_allowed",
+    "spend_control_reached", "limit_reached_type", "last_error", "last_error_at", "stale", "age_seconds"}
+OPTIONAL_CANDIDATE_FIELDS = {
+    "credits", "credit_capable", "credit_active_holders", "credit_blocked_at", "credit_blocked_balance",
+    "limited_reason", "credit_actor_email"}
+
+
+def balance_value(value: object) -> str | None:
+    """Credits are arbitrary nonnegative decimals, never percentages or money."""
+    if not isinstance(value, str) or len(value) > 100 or not DECIMAL_RE.fullmatch(value):
+        return None
+    try:
+        number = Decimal(value)
+        if number < 0 or not number.is_finite():
+            return None
+        plain = format(number, "f")
+        return plain.rstrip("0").rstrip(".") if "." in plain else plain
+    except (InvalidOperation, ValueError):
+        return None
+
+
+def credit_candidate_error(raw: dict, field: str) -> str | None:
+    if "credit_capable" in raw and not isinstance(raw["credit_capable"], bool):
+        return f"{field}.credit_capable"
+    holders = raw.get("credit_active_holders", 0)
+    if isinstance(holders, bool) or not isinstance(holders, int) or not 0 <= holders <= 1_000_000:
+        return f"{field}.credit_active_holders"
+    for name in ("credit_blocked_at", "credit_blocked_balance", "limited_reason", "credit_actor_email"):
+        if raw.get(name) is not None and not isinstance(raw[name], str):
+            return f"{field}.{name}"
+    actor = raw.get("credit_actor_email")
+    if actor is not None and (len(actor) > 320 or any(c in actor for c in "\r\n\0")):
+        return f"{field}.credit_actor_email"
+    credits = raw.get("credits")
+    if credits is None:
+        return None
+    if not isinstance(credits, dict) or set(credits) - CREDIT_FIELDS:
+        return f"{field}.credits"
+    for name in ("balance", "fetched_at", "account_id", "limit_reached_type", "last_error", "last_error_at"):
+        if credits.get(name) is not None and not isinstance(credits[name], str):
+            return f"{field}.credits.{name}"
+    for name in ("has_credits", "unlimited", "ordinary_usage_allowed", "spend_control_reached", "stale"):
+        if credits.get(name) is not None and not isinstance(credits[name], bool):
+            return f"{field}.credits.{name}"
+    return None
+
+
+def normalize_credits(raw: object, now: datetime, max_age: int = 900) -> dict:
+    raw = raw if isinstance(raw, dict) else {}
+    balance = balance_value(raw.get("balance"))
+    account = raw.get("account_id")
+    account = account.strip() if isinstance(account, str) and len(account) <= 256 else None
+    try:
+        observed, fetched_at = timestamp(raw.get("fetched_at"))
+        age = (now - observed).total_seconds()
+        fresh = -30 <= age <= max_age and raw.get("stale") is not True
+        if age < -30:
+            fetched_at = None
+    except (ValueError, TypeError):
+        fetched_at, fresh = None, False
+    reached = raw.get("limit_reached_type")
+    reached = reached.lower() if isinstance(reached, str) else None
+    restricted = raw.get("spend_control_reached") is True or reached not in {
+        None, "", "rate_limit_reached", "usage_limit_reached", "weekly_limit_reached", "session_limit_reached"}
+    available = (raw.get("unlimited") is True or
+                 (raw.get("has_credits") is True and balance is not None and Decimal(balance) > 0))
+    return {
+        "has_credits": raw.get("has_credits") is True, "unlimited": raw.get("unlimited") is True,
+        "balance": balance, "account_id": account or None, "fetched_at": fetched_at,
+        "ordinary_usage_allowed": raw.get("ordinary_usage_allowed")
+        if isinstance(raw.get("ordinary_usage_allowed"), bool) else None,
+        "spend_control_reached": restricted, "limit_reached_type": reached,
+        "last_error": raw.get("last_error") or False, "fresh": fresh,
+        "available": bool(fetched_at and account and available and not restricted
+                          and raw.get("last_error") not in HARD_CREDIT_ERRORS)}
+
+
+def refusal_recovered(raw: dict, credits: dict, now: datetime) -> bool:
+    """Retry a funded wallet only after cooldown and a newer successful observation."""
+    blocked = raw.get("credit_blocked_at")
+    if not blocked:
+        return raw.get("limited_reason") != "credits"
+    try:
+        blocked_time, _ = timestamp(blocked)
+        fetched, _ = timestamp(credits.get("fetched_at"))
+    except (ValueError, TypeError):
+        return False
+    old = balance_value(raw.get("credit_blocked_balance"))
+    current = credits.get("balance")
+    increased = old is not None and current is not None and Decimal(current) > Decimal(old)
+    cooled = (now - blocked_time).total_seconds() >= 600
+    return bool(fetched > blocked_time and credits["available"] and credits["fresh"]
+                and not credits["last_error"] and (increased or cooled))

package/lib/selector_funding.py

@@ -0,0 +1,113 @@
+"""Opted-in funding tiers preserve the legacy session gate and weekly band."""
+
+from __future__ import annotations
+
+from decimal import Decimal, localcontext
+
+from selector_credits import CAPABILITY, normalize_credits, refusal_recovered
+from selector_credit_scope import (
+    actor_email, actor_key, actor_observations, actor_refusals, merge_actor, merge_wallet, wallet_available,
+)
+
+
+def wallet_snapshots(candidates: list[dict], now, max_age: int) -> dict:
+    wallets = {}
+    for raw in candidates:
+        credits = normalize_credits(raw.get("credits"), now, max_age)
+        key = credits["account_id"]
+        if not key:
+            continue
+        # The snapshot predates a failed refresh: its confirmed money remains true
+        # even when this slot's current credentials no longer authenticate.
+        credits["available"] = wallet_available(dict(credits, last_error=False))
+        observed = credits["fetched_at"] or ""
+        confirmed = bool(observed) and (credits["unlimited"]
+            or (raw.get("credits") or {}).get("has_credits") is False
+            or (credits["has_credits"] and credits["balance"] is not None))
+        credits["wallet_observed_at"], credits["wallet_confirmed"] = observed, confirmed
+        previous = wallets.get(key)
+        rank = (confirmed, observed, not credits["available"])
+        if previous is None or rank > (previous["wallet_confirmed"], previous["wallet_observed_at"],
+                                       not previous["available"]):
+            wallets[key] = credits
+    return wallets
+
+
+def apply_funding(rows: list[dict], candidates: list[dict], now, request: dict) -> None:
+    max_age = request.get("credit_max_age_seconds", 900)
+    wallets = wallet_snapshots(candidates, now, max_age)
+    refusals = actor_refusals(candidates)
+    observations = actor_observations(candidates, now, max_age)
+    holders = {}
+    for raw in candidates:
+        account = (raw.get("credits") or {}).get("account_id")
+        holders[account] = max(holders.get(account, 0), raw.get("credit_active_holders", 0))
+    for row, raw in zip(rows, candidates):
+        credits = normalize_credits(raw.get("credits"), now, max_age)
+        credits = merge_actor(credits, observations.get(actor_key(raw)))
+        credits = merge_wallet(credits, wallets.get(credits["account_id"]))
+        receipt = dict(raw, **refusals.get(actor_key(raw), {}))
+        known = row["quota_known"]
+        measured = [Decimal(row[key]) for key in ("weekly_pct", "session_pct") if row[key] is not None]
+        peak = max(measured) if measured else None
+        exhausted = peak is not None and peak >= 100
+        exhausted |= row["engine"] == "codex" and credits["ordinary_usage_allowed"] is False
+        reserve = peak is not None and 90 <= peak < 100
+        tier = "credits" if exhausted else "reserve" if reserve else "included"
+        recovered = refusal_recovered(receipt, credits, now)
+        reason = raw.get("limited_reason")
+        usage_park = reason == "usage" or (reason == "credits" and recovered)
+        park = row["exclusion_code"] in {"status_not_active", "account_limited"}
+        safe = row["status"] in {"active", "limited"} and (not park or usage_park)
+        paid = (row["engine"] == "codex" and raw.get("credit_capable") is True
+                and credits["available"] and recovered and safe)
+        # Retry normalization with just usage parks removed; independent auth, stale
+        # heartbeat, incapable provider and active reservations retain their exclusions.
+        if park and safe and ((tier == "credits" and paid) or (tier == "reserve" and known)):
+            from selector_policy import normalize_candidate
+            unparked = dict(raw, status="active", limited_until=None)
+            refreshed = normalize_candidate(unparked, now, row["input_ordinal"])
+            row["eligible"], row["exclusion_code"] = refreshed["eligible"], refreshed["exclusion_code"]
+        if row["eligible"] and tier == "credits" and not paid:
+            row["eligible"], row["exclusion_code"] = False, "credits_unavailable"
+        required = request.get("required_funding_tier")
+        if row["eligible"] and required and required != tier:
+            row["eligible"], row["exclusion_code"] = False, "funding_tier_excluded"
+        row.update(funding_tier=tier, credits=credits, credit_capable=raw.get("credit_capable") is True,
+                   credit_active_holders=holders.get(credits["account_id"], 0),
+                   credit_blocked_at=receipt.get("credit_blocked_at"),
+                   credit_blocked_balance=receipt.get("credit_blocked_balance"), limited_reason=reason)
+        if "credit_actor_email" in raw:
+            row["credit_actor_email"] = actor_email(raw)
+
+
+def best_funding_tier(rows: list[dict]) -> list[dict]:
+    order = {"included": 0, "reserve": 1, "credits": 2}
+    best = min(order[row["funding_tier"]] for row in rows)
+    return [row for row in rows if order[row["funding_tier"]] == best]
+
+
+def credit_rank(row: dict) -> tuple:
+    credits, holders = row["credits"], row["credit_active_holders"]
+    with localcontext() as context:
+        context.prec = 110
+        share = Decimal(credits["balance"] or "0") / (holders + 1)
+    return (not credits["unlimited"], holders if credits["unlimited"] else -share)
+
+
+def funding_proof(request: dict, winner: dict) -> dict:
+    return {"credit_capability": CAPABILITY, "credit_fallback": True,
+            "required_funding_tier": request.get("required_funding_tier"),
+            "credit_max_age_seconds": request.get("credit_max_age_seconds", 900),
+            "funding_tier": winner["funding_tier"]}
+
+
+def funding_score(winner: dict) -> dict:
+    score = {"funding_tier": winner["funding_tier"],
+            "credit_balance": winner["credits"]["balance"],
+            "credit_account_id": winner["credits"]["account_id"],
+            "credit_active_holders": winner["credit_active_holders"],
+            "credit_unlimited": winner["credits"]["unlimited"]}
+    if "credit_actor_email" in winner:
+        score["credit_actor_email"] = winner["credit_actor_email"]
+    return score

package/lib/selector_policy.py

@@ -5,6 +5,9 @@ from __future__ import annotations
 from datetime import datetime
 from decimal import Decimal, localcontext
 
+from selector_funding import (
+    apply_funding, best_funding_tier, credit_rank, funding_proof, funding_score,
+)
 from selector_primitives import (
     DEFAULT_HEADROOM_BAND,
     DEFAULT_SESSION_GATE,
@@ -207,25 +210,35 @@ def select(request: object) -> dict:
     duplicate = next((items for items in identities.values() if len(items) > 1), None)
     if duplicate:
         return _error("duplicate_candidate_identity", {"input_ordinals": duplicate})
+    credit_mode = request.get("credit_fallback") is True
+    if credit_mode:
+        apply_funding(rows, request["candidates"], now, request)
     producer, alternatives = _apply_policy(request, rows)
     eligible = [row for row in rows if row["eligible"]]
     if not eligible:
         return _error("no_candidate", {"eligible_count": 0})
+    funded = best_funding_tier(eligible) if credit_mode else eligible
     band, band_text = decimal_value(request.get("headroom_band", DEFAULT_HEADROOM_BAND))
     gate, gate_text = decimal_value(request.get("session_gate", DEFAULT_SESSION_GATE))
     # Two cuts, in this order (operator's 2026-09-03 decision): the session gate says
     # WHO may be considered, the weekly band says which of those count as equally
     # good. "healthy or known" is the gate stepping aside when nobody clears it.
-    known = [row for row in eligible if row["quota_known"]]
+    known = [row for row in funded if row["quota_known"]]
     healthy = _session_gate(known, gate)
     ranked = healthy or known
     floor = _band_floor(ranked, band) if band is not None else None
     if floor is None:
         # No usable quota anywhere: every eligible row is an unknown peer.
         # Keep LRU and the request spread instead of preferring a fixed identity.
-        banded = eligible
+        banded = funded
     else:
         banded = [row for row in ranked if Decimal(row["weekly_remaining"]) >= floor]
+    if credit_mode and funded[0]["funding_tier"] == "credits":
+        # Subscription windows cannot rank credit-funded work. Credit capacity per
+        # identity holder decides, with the same deterministic LRU/spread for ties.
+        best_credit = min(credit_rank(row) for row in funded)
+        banded = [row for row in funded if credit_rank(row) == best_credit]
+        floor, healthy = None, []
     winner = min(banded, key=_band_key(request["reservation_key"]))
     rows.sort(key=_snapshot_key)
     snapshot = canonical_sha256(rows)
@@ -239,6 +252,8 @@ def select(request: object) -> dict:
         "headroom_band": band_text,
         "session_gate": gate_text,
         "candidate_snapshot_digest": snapshot, "selected_identity": chosen}
+    if credit_mode:
+        digest_input.update(funding_proof(request, winner))
     score_fields = ("quota_known", "weekly_pct", "session_pct", "weekly_remaining",
                     "session_remaining", "effective_headroom", "last_selected_at")
     response = {"schema": SCHEMA, "selector_version": SELECTOR_VERSION, "ok": True, **chosen,
@@ -256,6 +271,9 @@ def select(request: object) -> dict:
                 "session_ok_count": len(healthy),
                 "candidate_snapshot_digest": snapshot,
                 "selection_digest": canonical_sha256(digest_input)}
+    if credit_mode:
+        response.update(funding_proof(request, winner))
+        response["score_basis"].update(funding_score(winner))
     if request["policy"] == "reviewer" and not alternatives and _row_identity(winner) == producer:
         response["fallback_reason"] = "sole_eligible_account"
     return response

package/lib/selector_primitives.py

@@ -39,7 +39,8 @@ REQUEST_KEYS = {
 # headroom_band from its own setting and never sends session_gate, so the gate default
 # below is what every panel launch gets (operator's 2026-09-03 decision: session
 # headroom gates FIRST, then the weekly band picks among the survivors).
-OPTIONAL_REQUEST_KEYS = {"headroom_band", "session_gate"}
+OPTIONAL_REQUEST_KEYS = {"headroom_band", "session_gate", "credit_fallback",
+                         "required_funding_tier", "credit_max_age_seconds"}
 DEFAULT_HEADROOM_BAND = "30"
 DEFAULT_SESSION_GATE = "50"
 POLICIES = {
@@ -144,8 +145,12 @@ def _identity_error(value: object, field: str) -> str | None:
 
 def _candidate_error(value: object, index: int) -> str | None:
     field = f"candidates[{index}]"
-    if not isinstance(value, dict) or set(value) != CANDIDATE_KEYS:
+    from selector_credits import OPTIONAL_CANDIDATE_FIELDS, credit_candidate_error
+    if not isinstance(value, dict) or not CANDIDATE_KEYS <= set(value) \
+            or set(value) - CANDIDATE_KEYS - OPTIONAL_CANDIDATE_FIELDS:
         return field
+    if error := credit_candidate_error(value, field):
+        return error
     for name in ("runner_id", "runner_generation"):
         item = value[name]
         if not isinstance(item, int) or isinstance(item, bool) or not 0 < item <= SAFE_INTEGER:
@@ -186,6 +191,16 @@ def request_error(request: object) -> tuple[str, dict] | None:
     keys = set(request)
     if not REQUEST_KEYS <= keys or keys - REQUEST_KEYS - OPTIONAL_REQUEST_KEYS:
         return "invalid_request", {"field": "$"}
+    if "credit_fallback" in request and not isinstance(request["credit_fallback"], bool):
+        return "invalid_request", {"field": "credit_fallback"}
+    if "required_funding_tier" in request and (not isinstance(request["required_funding_tier"], str)
+            or request["required_funding_tier"] not in {"included", "reserve", "credits"}):
+        return "invalid_request", {"field": "required_funding_tier"}
+    if "required_funding_tier" in request and request.get("credit_fallback") is not True:
+        return "invalid_request", {"field": "required_funding_tier"}
+    age = request.get("credit_max_age_seconds", 900)
+    if isinstance(age, bool) or not isinstance(age, int) or not 30 <= age <= 3600:
+        return "invalid_request", {"field": "credit_max_age_seconds"}
     for knob in ("headroom_band", "session_gate"):
         if knob not in request:
             continue
@@ -224,6 +239,9 @@ def request_error(request: object) -> tuple[str, dict] | None:
     if not isinstance(request["candidates"], list):
         return "invalid_request", {"field": "candidates"}
     for index, value in enumerate(request["candidates"]):
+        if isinstance(value, dict) and set(value) - CANDIDATE_KEYS \
+                and request.get("credit_fallback") is not True:
+            return "invalid_request", {"field": f"candidates[{index}]"}
         if error := _candidate_error(value, index):
             return "invalid_request", {"field": error}
     return None

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multiacc",
-  "version": "2.0.50",
+  "version": "2.0.52",
   "description": "Unified Claude Code and OpenAI Codex subscription pooling with quota-aware selection.",
   "type": "module",
   "bin": {

package/tests/test_codex_reset_credits.py

@@ -0,0 +1,154 @@
+"""Pure contract checks for spendable credit telemetry, separate from earned resets."""
+
+from pathlib import Path
+import sys
+import unittest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "lib"))
+from codex_credits import collect_credits, credit_view, failed_credits, snapshot_from_usage
+
+NOW = 1791115200
+
+
+def payload(**updates):
+    return {"account_id": "account-test", "credits": {
+        "has_credits": True, "unlimited": False, "balance": "1234.5000"},
+        "rate_limit": {"allowed": False}, "spend_control_reached": False, **updates}
+
+
+class SpendableCreditsTest(unittest.TestCase):
+    def test_provider_balance_and_identity_are_preserved_without_float_rounding(self):
+        raw = payload()
+        raw["credits"]["balance"] = "12345678901234567890.123456789"
+        result = snapshot_from_usage(raw, "account-test", NOW)
+        self.assertEqual(result["balance"], "12345678901234567890.123456789")
+        self.assertEqual(result["account_id"], "account-test")
+        self.assertEqual(result["fetched_at"], "2026-10-04T12:00:00Z")
+        self.assertIs(result["ordinary_usage_allowed"], False)
+        self.assertIs(result["spend_control_reached"], False)
+
+    def test_measured_zero_unlimited_and_unknown_balance_remain_distinct(self):
+        for raw, expected in (({"has_credits": False, "unlimited": False, "balance": "0.00"}, "0"),
+                              ({"has_credits": True, "unlimited": True, "balance": None}, None),
+                              ({"has_credits": True, "unlimited": False}, None)):
+            with self.subTest(raw=raw):
+                result = snapshot_from_usage(payload(credits=raw), "account-test", NOW)
+                self.assertEqual(result["balance"], expected)
+                self.assertEqual(result["unlimited"], raw["unlimited"])
+
+    def test_earned_resets_never_become_a_spendable_balance(self):
+        self.assertIsNone(collect_credits({"rate_limit_reset_credits": {"available_count": 3}},
+                                          "account-test", NOW))
+        self.assertIsNone(collect_credits({"credits": None}, "account-test", NOW))
+
+    def test_malformed_balances_and_truthy_flags_do_not_claim_available_credit(self):
+        for invalid in (True, 12.34, -1, "-1", "NaN", "Infinity", "1e3", "1,000", "9" * 129):
+            with self.subTest(invalid=invalid):
+                raw = payload()
+                raw["credits"]["balance"] = invalid
+                self.assertIsNone(collect_credits(raw, "account-test", NOW))
+        raw = payload()
+        raw["credits"]["has_credits"] = "true"
+        self.assertIsNone(collect_credits(raw, "account-test", NOW))
+
+    def test_response_identity_must_agree_with_authenticated_account(self):
+        previous = snapshot_from_usage(payload(), "account-test", NOW)
+        bad = collect_credits(payload(account_id="other-account"), "account-test", NOW + 10, previous)
+        self.assertEqual(bad["account_id"], "account-test")
+        self.assertEqual(bad["last_error"], "account_mismatch")
+        self.assertEqual(bad["fetched_at"], previous["fetched_at"])
+        no_response_id = snapshot_from_usage(payload(account_id=None), "account-test", NOW)
+        self.assertEqual(no_response_id["account_id"], "account-test")
+
+    def test_failure_preserves_last_observation_then_success_clears_it(self):
+        previous = snapshot_from_usage(payload(), "account-test", NOW)
+        failed = failed_credits(previous, "http_429", NOW + 10)
+        self.assertEqual(failed["balance"], "1234.5")
+        self.assertEqual(failed["fetched_at"], previous["fetched_at"])
+        self.assertTrue(failed["stale"])
+        self.assertEqual(failed["last_error"], "http_429")
+        missing = collect_credits({}, "account-test", NOW + 20, previous)
+        self.assertEqual(missing["last_error"], "missing_credits")
+        recovered = collect_credits(payload(), "account-test", NOW + 30, failed)
+        self.assertNotIn("last_error", recovered)
+        self.assertFalse(credit_view(recovered, NOW + 30)["stale"])
+
+    def test_staleness_uses_credit_timestamp_and_rejects_future_or_invalid_time(self):
+        value = snapshot_from_usage(payload(), "account-test", NOW)
+        self.assertFalse(credit_view(value, NOW + 900)["stale"])
+        self.assertTrue(credit_view(value, NOW + 901)["stale"])
+        self.assertTrue(credit_view(value, NOW - 31)["stale"])
+        self.assertIsNone(credit_view({**value, "fetched_at": "2026-10-04T12:00:00"}, NOW))
+        self.assertIsNone(credit_view({**value, "fetched_at": {}}, NOW))
+
+    def test_soft_failure_never_erases_a_known_auth_or_identity_failure(self):
+        previous = snapshot_from_usage(payload(), "account-test", NOW)
+        for error in ("unauthenticated", "account_mismatch"):
+            failed = failed_credits(previous, error, NOW + 10)
+            retry = failed_credits(failed, "network_unreachable", NOW + 20)
+            self.assertEqual(retry["last_error"], error)
+            self.assertEqual(retry["last_error_at"], failed["last_error_at"])
+            self.assertNotIn("last_error", collect_credits(payload(), "account-test", NOW + 30, retry))
+
+    def test_transport_failure_diagnostics_preserve_paid_balance_and_its_timestamp(self):
+        previous = snapshot_from_usage(payload(), "account-test", NOW)
+        for error in ("network_unreachable", "dns_unavailable", "usage_timeout", "http_401", "http_403"):
+            failed = failed_credits(previous, error, NOW + 10)
+            self.assertEqual(failed["last_error"], error)
+            self.assertEqual(failed["balance"], previous["balance"])
+            self.assertEqual(failed["fetched_at"], previous["fetched_at"])
+
+    def test_missing_credit_schema_does_not_hide_identity_mismatch(self):
+        previous = snapshot_from_usage(payload(), "account-test", NOW)
+        result = collect_credits({"account_id": "other"}, "account-test", NOW + 10, previous)
+        self.assertEqual(result["last_error"], "account_mismatch")
+
+    def test_missing_balance_keeps_money_but_obeys_new_spend_control(self):
+        previous = snapshot_from_usage(payload(), "account-test", NOW)
+        for raw in (payload(credits={"has_credits": True, "unlimited": False, "balance": None}),
+                    payload(credits=None)):
+            raw["spend_control_reached"] = True
+            result = collect_credits(raw, "account-test", NOW + 10, previous)
+            self.assertEqual(result["balance"], previous["balance"])
+            self.assertEqual(result["fetched_at"], previous["fetched_at"])
+            self.assertTrue(result["spend_control_reached"])
+            self.assertIn(result["last_error"], ("invalid_credits", "missing_credits"))
+
+    def test_partial_read_never_clears_previous_spending_restrictions(self):
+        previous = snapshot_from_usage(payload(spend_control_reached=True,
+            rate_limit_reached_type="workspace_member_usage_limit_reached"), "account-test", NOW)
+        raw = payload(credits=None, spend_control_reached=False, rate_limit_reached_type="rate_limit_reached")
+        result = collect_credits(raw, "account-test", NOW + 10, previous)
+        self.assertTrue(result["spend_control_reached"])
+        self.assertEqual(result["limit_reached_type"], "workspace_member_usage_limit_reached")
+        self.assertFalse(collect_credits(payload(), "account-test", NOW + 20, result)["spend_control_reached"])
+
+    def test_admission_facts_are_never_inferred_from_percentages(self):
+        raw = payload(rate_limit={"primary_window": {"used_percent": 0}})
+        snapshot = snapshot_from_usage(raw, "account-test", NOW)
+        self.assertIsNone(snapshot["ordinary_usage_allowed"])
+        raw["spend_control_reached"] = "false"
+        raw["rate_limit_reached_type"] = {"unexpected": "shape"}
+        snapshot = snapshot_from_usage(raw, "account-test", NOW)
+        self.assertIsNone(snapshot["spend_control_reached"])
+        self.assertEqual(snapshot["limit_reached_type"], "unknown")
+
+    def test_documented_raw_and_app_server_nested_admission_fields(self):
+        raw = payload(spend_control={"reached": True},
+                      rate_limit_reached_type={"type": "workspace_member_usage_limit_reached"})
+        raw.pop("spend_control_reached")
+        snapshot = snapshot_from_usage(raw, "account-test", NOW)
+        self.assertTrue(snapshot["spend_control_reached"])
+        self.assertEqual(snapshot["limit_reached_type"], "workspace_member_usage_limit_reached")
+        app_server = {"accountId": "account-test", "ordinaryUsageAllowed": False, "rateLimits": {
+            "credits": {"hasCredits": True, "unlimited": False, "balance": "12.34"},
+            "rateLimitReachedType": "rate_limit_reached", "spendControlReached": False}}
+        snapshot = snapshot_from_usage(app_server, "account-test", NOW)
+        self.assertEqual(snapshot["limit_reached_type"], "rate_limit_reached")
+        self.assertEqual(snapshot["balance"], "12.34")
+        self.assertIs(snapshot["ordinary_usage_allowed"], False)
+        self.assertIs(snapshot["spend_control_reached"], False)
+
+
+if __name__ == "__main__":
+    unittest.main()