Singularity

Concepts

Every model call is debited at its catalog price; no tool output credits the budget.

Earning and cost record

Every model call costs money, and the accounting is the being's most load-bearing state. The record is the budget object in state.json plus the paired journal events, written once per event in exact decimal arithmetic, never floating point.

The budget object

| Field | Meaning | |---|---| | starting | Explicitly declared SINGULARITY_STARTING_BALANCE_USD; required and refused if negative. | | remaining | Current balance; the [solvency](/docs/concepts/solvency) gate reads only this. | | api_spent | Cumulative model cost. | | instance_spent | Cumulative host cost for the time model calls took. | | total_tokens | Lifetime token count (saturating). | | earned | Credited revenue. Nothing credits it today, so it stays at zero. |

Net profit is derived, never stored: earned − api_spent − instance_spent.

Cost: debited once per completion

Immediately after every Brama completion:

api      = cost of the reported usage at Brama's catalog price for the served model
instance = elapsed call time in hours × SINGULARITY_INSTANCE_USD_PER_HOUR
remaining -= api + instance

The catalog price includes cache reads and writes. A missing model price is a refusal, not a zero-cost call. The host's hourly price is also required; a free host declares zero. Two journal events are appended: model_completed (the usage block) and cost_debited (the amount).

Revenue: no tool output credits the budget

The model cannot talk itself richer, and neither can a tool's answer. Whatever a tool returns, whatever its name and whatever fields its answer carries (a revenue_usd or realized_profit_usd included), earned and remaining are unchanged by it. The only thing that may credit the budget is a typed settlement record that the finance surface itself issues and verifies against its own state; no finance surface issues one yet, so no revenue is credited. What the finance surface does today is [the finance boundary](/docs/finance).

Journals written by older releases may still hold revenue_credited events; current releases write none.

Where it lives

  • state.json → budget — the current record, saved atomically with the rest of the being;
  • activity.jsonl — the history: model_completed and cost_debited per completion, fsynced on append;
  • every once report repeats the headline numbers: balance_usd, earned_usd, net_profit_usd, total_tokens.
jq .budget .singularity/state.json
grep -E '"cost_debited"' .singularity/activity.jsonl

Not to be confused with

  • [Solvency](/docs/concepts/solvency) — the gate that reads remaining; this page is the ledger it reads.
  • The finance transaction ledger — singularity-finance-mcp keeps its own hash-chained audit of money moving in the world; the budget records what existence costs.
  • Brama's own billing — Singularity records the cost quoted by Brama's caller-scoped model catalog; its local budget is not a funds transfer.

Settings