Ultron — Credit System Map

One picture of the three systems that have to align: the credit meter (the wallet + spend), telemetry (the audit layer), and the milestones worker (grants). The economics are inverted by accident — this is the baseline for setting them on purpose.

Baseline from the codebase + Postgres ledger audit · $1 = 1,000 credits

How the three systems connect

flowchart TB
  classDef earn fill:#16241b,stroke:#2e6b4d,color:#cfe9dd;
  classDef wallet fill:#241c10,stroke:#7a5a25,color:#f0d9b0;
  classDef spend fill:#241317,stroke:#7a2e3a,color:#f0c2cb;
  classDef tel fill:#141a26,stroke:#33507a,color:#cdd9f0;
  classDef legacy fill:#1a1313,stroke:#5a2a2a,color:#e0a0a0,stroke-dasharray:5 4;

  TOPUP["Stripe top-up
topup_credits"]:::earn
  SUB["Subscription invoice.paid
refill_plan_credits"]:::earn
  MILE["Milestones worker
grant_credits (FIFO + expiry)"]:::earn

  WALLET["WALLET — single source of truth
credits_paid + credits_granted"]:::wallet

  RATES["Rate engine
roundCredits = tokens x rate
(must derive from real cost x margin)"]:::spend
  SPEND["consume_credits
v2 chat turn · drains grants then paid"]:::spend

  RUNS["chat_runs · per turn
cost_usd_micros + credits + tokens + model + rounds"]:::tel
  DAILY["telemetry_daily · per model/day
cost_usd vs credits"]:::tel
  AE["Analytics Engine (ultron_events)
Stripe · Apify · GitHub · ..."]:::tel

  LEG["LEGACY credit_balance
increment_credits / decrement_credits"]:::legacy

  TOPUP --> WALLET
  SUB --> WALLET
  MILE --> WALLET
  RATES --> SPEND
  WALLET --> SPEND
  SPEND -- writes --> RUNS
  RUNS --> DAILY
  RUNS -. "reconcile: real cost vs charged (NOT WIRED YET)" .-> AE
  MILE -. milestone_achieved event .-> AE

  WELCOME["$5 welcome bonus"]:::legacy --> LEG
  AUTOSUM["auto-summary charge"]:::legacy --> LEG

The economics — what Ultron pays vs what we charge

Model · tier	Real cost in / out	We charge in / out	Markup in	Markup out
DeepSeek · Minuet	$0.27 / $0.87 /M	7.6 / 32 cr/1K	28×	37×
Kimi · Allegro	$0.95 / $4 /M	3 / 15 cr/1K	3.2×	3.8×
Opus · Forte	$15 / $75 /M	15 / 75 cr/1K	1×	1×
Sonnet · Forte fan-out	$3 / $15 /M	charged at deep 15 / 75	5×	5×
GPT-5.4 · fast lane	$1.25 / $10 /M	free (rate-limited)	—	—

Inverted & accidental: ~28× margin on the cheapest model, ~3.5× on the mid, 0× on the most expensive (Opus sold at cost). The fix: charge = real cost × chosen margin, per model that actually ran — not a fixed per-tier rate. Even a deliberate 10× on DeepSeek is 2.7 cr/1K, so $19 (=19,000 cr) still buys ~7M tokens with real margin.

The three systems, today

1 · Credit meter

Wallet + spend

Live wallet = credits_paid + credits_granted. Spend via consume_credits (atomic, FIFO grants then paid). Rates in credits.ts are stale — priced for the old lineup.

2 · Telemetry

The audit layer

chat_runs already records real cost + credits + tokens + model per turn; telemetry_daily rolls it up. The data to verify the meter exists — it's just not surfaced or pushed to the AE dashboard yet.

3 · Milestones

Grants engine

D1 worker evaluates achievements hourly and calls grant_credits → feeds credits_granted, with expiry. Already emits milestone_achieved to telemetry. Cleanly connected.

The wallet — buckets & the legacy stragglers

Live (source of truth)

credits_paid + credits_granted

credits_paid ← top-ups + subscription refill (rollover ≤ 2× cap).
credits_granted ← milestone grants (credit_grants, FIFO + expiry).
Read by display + gating; drained by consume_credits. Consistent.

Legacy — to sweep

credit_balance (dead)

Code says "no longer the source of truth," but two earns still hit it: the $5 welcome bonus (increment_credits) lands here and is never spent/shown, and the auto-summary charges here (decrement_credits) so it effectively bills nothing. Redirect both onto the live wallet, then drop the field + its two RPCs.

What we have to settle

1Set the cost, then the fee Derive each tier's credit rate from the registry's real pricingFor × a chosen margin, charged by the model that actually ran. Decide the margin curve (cheap models carry it; premium stays lean).
2One wallet, one meter Sweep the legacy credit_balance stragglers (welcome bonus, auto-summary) onto credits_paid/consume_credits; retire increment/decrement_credits.
3Wire telemetry ↔ meter Surface chat_runs cost-vs-charged as realized margin per model, and push it to the unified AE dashboard (extend the OnTurnComplete hook, or a daily reconciliation job).
4Make consumption a catalog Per-component metering (main chat, skills, subagents — already folded into the turn) as declarative rows, so future metered things (Apify actors, already in telemetry) are one row, not a rewrite.