Module economics 

Token economics, measured rather than claimed.

The question is the one .ai/repo/benchmarks/economics/methodology.yaml states: for the same task, from the same repository state, with the same model and the same acceptance tests, how many tokens does a coding session consume with Majordomus installed and without it? This module is the one calculator that answers it. The CLI, the HTTP API, MCP, the Cockpit, the generated report and the public site are projections of summarize; none of them computes a number of its own.

The data flow:

methodology.yaml, suites/*.yaml, tasks/*/task.yaml    declared
         │
  runner (live sessions) ─► runs/<suite>/<run>.json   raw facts: provider usage, gates
  context (no model)     ─► runs/context/<rev>.json   raw facts: counted tokens
         │
  summarize ─► pairs ─► per-pair reductions ─► distributions, intervals ─► verdict

Nothing derived is stored. A pair, a metric and a verdict are recomputed from the raw records on every read, so the records never need rewriting when the derivation changes, and a changed derivation is a methodology version, not an edit to history.

What the verdict may say is decided by the methodology’s publication rule, not by the caller: below it, the statement is that no verified total-token claim exists, with the preliminary observation labelled as such. The rule is evaluated for the primary metric over all the evidence and for nothing else, so only that metric, unnarrowed, can ever be verified.

What a generated artifact publishes comes from summarize_tracked, which reads only the records git tracks, so that two checkouts of one commit generate the same bytes.

use majordomus_cli::economics::{summarize, model::EconomicsQuery};
let dir = tempfile::tempdir().unwrap();
let s = summarize(dir.path(), &EconomicsQuery::default());
assert!(!s.present);
assert!(!s.verdict.publishable);
assert!(s.verdict.statement.starts_with("No verified total-token-savings claim"));

Modules

claims

Claim governance for token economics: no number about tokens, context or cost reaches a reader unless the evidence produced it.

context

The deterministic suite: what the context compiler considers and what it selects, counted.

model

The typed records of the economics subsystem: the declarations it reads (methodology, suites, tasks), the raw facts it records (runs), and the answer it derives (summary).

report

The human-readable benchmark report, docs/generated/economics.md: a rendering of one EconomicsSummary and nothing else. Every number in it is a field of the summary, spelled for a reader; the report computes none, so it cannot disagree with the CLI, the API, MCP, the Cockpit or the site, which render the same summary.

runner

The live runner: a task, run by a real coding harness, once without Majordomus and once with it, from the same fixture, with the same model, judged by the same hidden tests.

stats

The arithmetic of the economics subsystem, and nothing else: the reduction formula, order statistics, a seeded bootstrap (over independent values, or over clusters when the values are repetitions of the same task), and the two ways a number is printed. Every surface that shows a number gets it from here through super::summarize; nothing downstream recomputes one, and nothing downstream formats a percentage its own way.

usage

Provider usage, read as the provider reported it, and the one normalisation every comparison uses.

Structs

Declarations

Every declaration of the economics subsystem, read from DIR.

Constants

CONTEXT_REDUCTION

Context selection, counted: never total savings.

CONTEXT_RUN_SCHEMA

The schema a context run record carries.

DIR

Where the declarations and the recorded evidence live, relative to the repository root.

EFFECTIVE_TOKEN_REDUCTION

The metric every headline is about.

EFFECTIVE_TOKEN_REDUCTION_INCLUDING_EXCLUDED

The primary metric with the outlier rule’s exclusions put back: reported beside it when the methodology excludes a run, never instead of it, and never verified.

NARROWED

The warning the primary metric carries when a query narrowed it.

NO_CLAIM

The statement made when there is nothing to make one from.

RUN_SCHEMA

The schema a live run record carries.

Functions

explain

Explain one metric: its value, formula and class, and every pair, run, suite and exclusion it rests on, with the commands that reproduce it. Err names the metrics that exist when metric is not one of them. A repository that declares no methodology has no metric at all, and is answered with present: false and the statement the summary makes, for any id: never an error, and never a number.

inputs_digest

A digest of the tracked files under pathspecs: each file’s path and the SHA-256 of its content as it is on disk now, in git’s index order. Recorded with every run, and recomputed on every read, it is what makes evidence current or stale.

load

Read every declaration under root. Ok(None) when no methodology is declared, which is the ordinary state of a repository that does not benchmark itself; an error names every file that could not be read, because a benchmark with a silently missing task is a different benchmark.

load_context_runs

Every context measurement recorded under root for suite, oldest first.

load_runs

Every live run recorded under root for suite, sorted by id, with the files that could not be read named.

pairs

Form every pair a live suite declares (each task, each repetition) from the runs recorded for it, and judge each. A declared pair nobody ran is missing, not absent.

revision

The revision evidence is recorded at: HEAD, and whether the working tree differs from it anywhere outside the evidence directory. The records a suite writes are changes to the working tree too, and a measurement must not call its own output a dirty tree.

runs

Every recorded live run, narrowed by the query, with its derived totals: the raw facts behind every number, one call away.

summarize

The one calculator. Reads the declarations and every recorded run under root, forms and judges the pairs, derives every metric with its class, distribution and interval, and states the strongest thing the publication rule allows. Never fails: what cannot be read is a diagnostic, and a repository with no methodology gets present: false.

summarize_tracked

summarize over the run records git tracks and nothing else: what majordomus generate publishes. A generated artifact must be the same on every checkout of one commit, and a record someone ran locally and never committed would make it depend on whose checkout generated it. Tracked records are read from the working tree; a record that is on disk and untracked is not read at all, not even to report it.

wire

The string a value serialises to, as every JSON surface spells it: EconomicsMetricStatus::NotMeasured is not_measured. A renderer that prints an enum uses this rather than Debug, so that a page and the API never spell one state two ways. A value that does not serialise to a string is given as its JSON text.