[Audit & Plan] Billing Architecture Alignment: CEP-8 Payment Waiving, Top-Up & Capping Fixes

[1amKhush]

@ContextVM-org

Key Findings

1. CEP-8 Payment Waiving vs. Top-Up Alignment

Currently, chat.complete hardcodes a balance check inside the tool handler and throws a raw Error("insufficient balance"). Per design/billing.md:

• chat.complete is a waived capability: resolvePrice handles authorization. If funded (balanceUsd >= floor), it returns waivePrice(). Output is capped by balance and usage is debited post-generation. If unfunded, resolvePrice returns rejectPrice("insufficient balance") (-32000 RPC rejection).
• balance.topup is a priced capability: resolvePrice returns quotePrice(sats) emitting a CEP-8 -32042 Payment Required Lightning invoice. Paid invoices credit the USD ledger.

2. Free Model Output Capping Bug

In pricing.ts (computeOutputCap), when rates.outputPerToken <= 0 (free model), omitting explicit user/model max tokens causes cap to evaluate to Infinity. Because Number.isFinite(Infinity) is false, it falls back to { maxTokens: 1 }, abruptly terminating free streams after a single token.

[ContextVM-org]

Great catch! Please proceed with the plan

[ContextVM-org]

Reviewed the whole branch against design/billing.md. Really clean work. The gate-vs-settle split is exactly right, the CEP-8 -32000 rejection on zero balance is canonical (matches rejectPrice() + the CEP-8 explicit-gating spec), the free-model maxTokens fix is correct, and the stream-hangs-on-rejection fix in MuxllClient.stream() (racing call.result against the iterator) is a nice catch. Tests + typecheck are green on my end too (79 pass / 2 skip / 0 fail). Branches cleanly off our feat/billing with no regressions.

Approving — two non-blocking things worth a follow-up, plus a dep bump:

1. MUXLL_USD_PER_SAT is a static, operator-managed value (money risk).
payments.ts takes a fixed usdPerSat and .env.example even says "refresh this operator-side." The design calls for a live Fx.usdPerSat() (Kraken→Coinbase→Binance, ~60s cache, in reallity we don't need such short time to declare cache state. ~1h would be good already). Because the user is always credited exactly amountUsd and sats = amountUsd / usdPerSat, a stale rate is worn entirely by the operator — stale-high = undercharge (loss), stale-low = overcharge. The topupBufferPct only cushions one direction. Fine to ship as-is for the POC, but want to ticket the live FX feed so it doesn't get forgotten — it's the one piece with real money exposure.

2. Ledger integer scale is only half-applied.
Only balances.credit_nusd is integer nano-USD (the money-critical one — good); usage.cost_usd / usage.charge_usd / credits.amount_usd are REAL floats (ledger.ts). The design specifies integer nano-USD throughout, and AGENTS.md currently claims "USD stored as integer nano-dollars" — which is only true for the balance column. Either finish the integer scale on the history tables, or tighten the AGENTS.md / ledger.ts doc to "balances integer, history float." Minor, just don't want the doc overstating it.

3. @earendil-works/pi-ai is behind — worth a bump.
We're pinned ^0.80.3 across all five packages; latest is 0.83.0. Since it's 0.x, the caret won't auto-resolve past 0.81.0, so the pin needs raising explicitly. One thing to check first: 0.83 makes the root entrypoint core-only/side-effect-free and moves the old global API to @earendil-works/pi-ai/compat. Muxll imports from subpaths (/providers/all, types, calculateCost, clampThinkingLevel), so it's probably unaffected, but skim the 0.81→0.83 changelog and re-run the suite after bumping.

Fixed-rate pricing + byModel/byPubkey overrides are intentionally deferred (design Phase 2) — not raising those here.

How would you like to proceed, follo-up pr bundle or continue over here?

[1amKhush]

@ContextVM-org Thanks for the thorough review!

Since the current PR is approved and cleanly completes the Phase 1 scope, I’d prefer to merge it as-is and handle these as focused follow-ups.

I’ll open a tracking issue and split the work into:

1. Live Fx.usdPerSat() pricing with provider fallback, approximately one-hour caching, and explicit stale/failure behavior.
2. Full nano-USD storage for usage and credit history, including any required SQLite migration and documentation corrections.
3. A separate @earendil-works/pi-ai 0.83.0 dependency bump after reviewing the 0.81–0.83 changes and verifying the existing subpath imports.

Keeping the dependency bump separate should make any compatibility regressions easier to isolate. I’ll link all three follow-ups back to #1.