HTTP API: economics

Verdikt jedné kontroly úspěchu nad během.

use majordomus_cli::economics::model::EconomicsCheck;
let c = EconomicsCheck { id: "tests_kept".into(), passed: true, detail: "0 deleted".into() };
let back: EconomicsCheck = serde_json::from_value(serde_json::to_value(&c).unwrap()).unwrap();
assert_eq!(back, c);

Odpověď economics.check, stejná přes CLI, HTTP i MCP: kolik se přečetlo a každé odmítnutí. ok je pravda přesně tehdy, když je findings prázdné. scanned počítá přečtené ručně psané soubory, docs/CLAIMS.yaml zahrnuté a generované soubory vyloučené; claims_checked počítá vazby tvrzení metodiky, ať je jejich stav jakýkoli.

use majordomus_cli::economics::claims::{check, EconomicsCheckReport};
let dir = tempfile::tempdir().unwrap();
let git = std::process::Command::new("git")
    .env_remove("GIT_DIR").env_remove("GIT_WORK_TREE").env_remove("GIT_INDEX_FILE")
    .arg("-C").arg(dir.path()).args(["init", "-q"]).status().unwrap();
assert!(git.success());
let report: EconomicsCheckReport = check(dir.path());
assert!(report.ok && report.findings.is_empty(), "an empty repository claims nothing");
let json = serde_json::to_value(&report).unwrap();
assert_eq!(json["claims_checked"], 0);
assert_eq!(serde_json::from_value::<EconomicsCheckReport>(json).unwrap(), report);

Jak číslo vzniklo. Třídy jsou seřazeny od nejsilnější po nejslabší a hodnota vypočtená z několika vstupů není nikdy silnější než nejslabší z nich.

use majordomus_cli::economics::model::EconomicsClass;
assert_eq!(serde_json::to_value(EconomicsClass::Counterfactual).unwrap(), "counterfactual");
let parsed: EconomicsClass = serde_json::from_value("observed".into()).unwrap();
assert!(parsed < EconomicsClass::Estimated, "a stronger class sorts first");

Nejnovější měření sady kontextu, stručně.

use std::collections::BTreeMap;
use majordomus_cli::economics::model::{EconomicsContextView, EconomicsTokenizer};
let v = EconomicsContextView {
    revision: "8d37d011ef".into(), measured_at: "2026-09-24T10:00:00Z".into(),
    tokenizer: EconomicsTokenizer {
        encoding: "o200k_base".into(), implementation: "tiktoken-rs 0.12.0".into(),
    },
    seeds: 2, candidate_tokens: 20_000, considered_tokens: 300_000, selected_tokens: 15_000,
    estimated_selected_tokens: 16_000,
    excluded_tokens: BTreeMap::from([("budget".into(), 5_000)]),
    seeds_over_budget_counted: 0, budget_tokens: 8_000,
};
assert_eq!(v.selected_tokens + v.excluded_tokens["budget"], v.candidate_tokens);
assert_eq!(serde_json::to_value(&v).unwrap()["tokenizer"]["encoding"], "o200k_base");

Tvar množiny hodnot po dvojicích.

use majordomus_cli::economics::model::EconomicsDistribution;
let d: EconomicsDistribution = serde_json::from_value(serde_json::json!({
    "n": 1, "mean": 0.4, "median": 0.4, "p25": 0.4, "p75": 0.4, "p95": 0.4,
    "min": 0.4, "max": 0.4
}))
.unwrap();
assert!(d.sd.is_none(), "one value has no sample standard deviation");
assert!(d.min <= d.p25 && d.p25 <= d.median && d.median <= d.p75 && d.p75 <= d.max);

Jeden běh vyloučený podle pravidla odlehlých hodnot.

use majordomus_cli::economics::model::{EconomicsExclusion, EconomicsOutlierPolicy};
let o: EconomicsOutlierPolicy = serde_json::from_value(serde_json::json!({
    "rule": "A run is excluded only by naming it here with a reason.",
    "excluded": [{ "run": "vat-rounding--baseline--r2", "reason": "provider outage" }]
}))
.unwrap();
let first: &EconomicsExclusion = &o.excluded[0];
assert_eq!(first.run, "vat-rounding--baseline--r2");
let unexplained = serde_json::json!({ "run": "vat-rounding--baseline--r1" });
assert!(serde_json::from_value::<EconomicsExclusion>(unexplained).is_err());

Odpověď economics.explain: jedna metrika a vše, na čem stojí.

Repozitář, který nedeklaruje metodiku měření výkonu, nic nemě­ří, takže nemá metriku k vysvětlení: odpovídá se mu tak, jak odpovídá economics.summary — present: false, tvrzení proč, žádná metrika a žádné číslo — a neodmítá se, protože repozitář, který sám sebe neměří, není chybný požadavek. Id metriky, které deklarovaná metodika nemá, se stále odmítá.

use majordomus_cli::economics::model::{EconomicsClass, EconomicsExplanation};
let e: EconomicsExplanation = serde_json::from_value(serde_json::json!({
    "present": true,
    "metric": { "id": "context_reduction_ratio", "title": "Context reduction",
        "class": "derived", "inputs": "counted", "unit": "ratio",
        "formula": "median over seeds of 1 - selected_tokens / candidate_tokens",
        "status": "not_measured", "n": 0, "suite": "context" },
    "class_meaning": "Arithmetic over observed or counted values.", "methodology": 1,
    "suites": [], "pairs": [], "excluded": [], "variants": [],
    "reproduce": ["majordomus economics measure --suite context"]
}))
.unwrap();
assert_eq!(e.metric.unwrap().inputs, Some(EconomicsClass::Counted));
assert!(e.pairs.is_empty(), "a counted metric rests on seeds, not on pairs");

let none: EconomicsExplanation = serde_json::from_value(serde_json::json!({
    "present": false, "statement": "No verified total-token-savings claim is available",
    "class_meaning": "", "suites": [], "pairs": [], "excluded": [], "variants": [],
    "reproduce": []
}))
.unwrap();
assert!(none.metric.is_none() && none.methodology.is_none(), "nothing declared, no number");

Jedna věc, kterou kontrola odmítá. detail jmenuje nápravu, takže se podle nálezu dá jednat bez čtení metodiky. Nález o tvrzení nebo souboru, ne o řádku, nenese line a jeho JSON klíč vynechává. Druhy:

• unsupported_quantity: číslo napsané do ručně psané prózy vedle slovníku ekonomiky.
• claim_unsupported: vazba na tvrzení, která neplatí — vázané tvrzení chybí v docs/CLAIMS.yaml, nebo je guaranteed, zatímco jeho metrika nestojí tam, kde vazba říká, nebo jeho důkazy nejsou aktuální.
• claim_unbound: tvrzení guaranteed říká, že tokeny, kontext nebo cena klesají, a žádná vazba ho nespojuje s metrikou.
• claim_duplicate: jedno id tvrzení se v docs/CLAIMS.yaml vyskytuje více než jednou.
• declarations_unreadable: deklarace měření výkonu nelze přečíst, takže nelze ukázat, že platí jakákoli vazba.
• claims_unreadable: docs/CLAIMS.yaml existuje a nelze ho přečíst ani parsovat.
• scan_failed: próza nešla vypsat nebo se soubor v ní nedal přečíst, takže nelze říct, že je čistá.

use majordomus_cli::economics::claims::EconomicsFinding;
let finding = EconomicsFinding {
    kind: "claim_unsupported".into(),
    path: "docs/CLAIMS.yaml".into(),
    line: None,
    detail: "set the claim to planned, or record the evidence".into(),
};
let json = serde_json::to_value(&finding).unwrap();
assert!(json.get("line").is_none(), "no line, no key");
assert_eq!(serde_json::from_value::<EconomicsFinding>(json).unwrap(), finding);

Jak zaznamenané důkazy obstojí proti repozitáři, jaký je nyní.

use majordomus_cli::economics::model::EconomicsFreshness;
assert_eq!(serde_json::to_value(EconomicsFreshness::NoEvidence).unwrap(), "no_evidence");
let f: EconomicsFreshness = serde_json::from_value("incompatible".into()).unwrap();
assert_eq!(f, EconomicsFreshness::Incompatible);

Zaznamenané měření v čase: jeden záznam na zaznamenaný běh kontextu.

use majordomus_cli::economics::model::EconomicsHistoryPoint;
let p: EconomicsHistoryPoint = serde_json::from_value(serde_json::json!({
    "suite": "context", "methodology": 1, "revision": "8d37d011ef",
    "at": "2026-09-24T10:00:00Z", "metric": "context_reduction_ratio", "value": 0.62, "n": 40
}))
.unwrap();
assert_eq!((p.methodology, p.n), (1, 40));
assert_eq!(serde_json::to_value(&p).unwrap()["metric"], "context_reduction_ratio");

Tvrzení, které měření existuje, aby otestovalo. Nikdy výsledek.

use majordomus_cli::economics::model::EconomicsHypothesis;
let h: EconomicsHypothesis = serde_json::from_value(serde_json::json!({
    "id": "continuity",
    "statement": "Work that spans sessions gains the most.",
    "status": "untested"
}))
.unwrap();
assert_eq!(h.status, "untested");
assert_eq!(serde_json::to_value(&h).unwrap()["id"], "continuity");

Bootstrap interval se vším, co je třeba k jeho reprodukci.

use majordomus_cli::economics::model::EconomicsInterval;
let i: EconomicsInterval = serde_json::from_value(serde_json::json!({
    "level_bp": 9500, "low": 0.21, "high": 0.38,
    "method": "bootstrap percentile of the median", "resamples": 10000, "seed": 20260924
}))
.unwrap();
assert!(i.low <= i.high);
assert_eq!(serde_json::to_value(&i).unwrap()["seed"], 20260924, "the seed travels with it");

Jedna metrika: její hodnota, odkud pochází a kolik unese.

use majordomus_cli::economics::model::{EconomicsClass, EconomicsMetric, EconomicsMetricStatus};
let m: EconomicsMetric = serde_json::from_value(serde_json::json!({
    "id": "effective_token_reduction", "title": "Effective token reduction",
    "class": "derived", "inputs": "observed", "unit": "ratio",
    "formula": "median of 1 - treatment / control", "status": "not_measured", "n": 0,
    "suite": "pilot"
}))
.unwrap();
assert_eq!(m.inputs, Some(EconomicsClass::Observed));
assert!(m.value.is_none() && m.status == EconomicsMetricStatus::NotMeasured);
assert!(serde_json::to_value(&m).unwrap().get("value").is_none(), "no value, not a zero");

Jak si metrika stojí vůči pravidlu publikace: zda její hodnota smí podpořit tvrzení, je příliš chabým výsledkem na jakékoli tvrzení, nebo nebyla vůbec změřena.

use majordomus_cli::economics::model::EconomicsMetricStatus;
assert_eq!(serde_json::to_value(EconomicsMetricStatus::NotMeasured).unwrap(), "not_measured");
let s: EconomicsMetricStatus = serde_json::from_value("preliminary".into()).unwrap();
assert_ne!(s, EconomicsMetricStatus::Verified, "a preliminary result is not a claim");

Kontrolní běh a jeho experimentální běh a co z nich plyne.

use majordomus_cli::economics::model::{EconomicsPair, EconomicsPairStatus};
let p: EconomicsPair = serde_json::from_value(serde_json::json!({
    "suite": "pilot", "task": "vat-rounding", "category": "bugfix", "sessions": 1,
    "repetition": 2, "control": "vat-rounding--baseline--r2", "status": "missing",
    "reasons": ["no treatment run recorded"]
}))
.unwrap();
assert_eq!(p.status, EconomicsPairStatus::Missing);
assert!(p.treatment.is_none() && p.token_reduction.is_none(), "no side, no reduction");

Počty párů sady, aby nic nevypadlo z dohledu.

use majordomus_cli::economics::model::EconomicsPairCounts;
let c = EconomicsPairCounts {
    declared: 14, attempted: 12, valid: 9, control_failed: 1,
    treatment_failed: 1, both_failed: 0, other: 1,
};
let accounted = c.valid + c.control_failed + c.treatment_failed + c.both_failed + c.other;
assert_eq!(accounted, c.attempted, "every attempted pair is in exactly one bucket");
assert_eq!(EconomicsPairCounts::default().declared, 0);

Proč se dvojice počítá, nebo nepočítá.

use majordomus_cli::economics::model::EconomicsPairStatus;
assert_eq!(serde_json::to_value(EconomicsPairStatus::ControlFailed).unwrap(), "control_failed");
let s: EconomicsPairStatus = serde_json::from_value("usage_unavailable".into()).unwrap();
assert_ne!(s, EconomicsPairStatus::Valid);

Kdy lze publikovat kvantitativní tvrzení o celkových tokenech. Musí platit každý práh.

use majordomus_cli::economics::model::EconomicsPublicationPolicy;
let rule = serde_json::json!({
    "min_valid_pairs": 30, "min_categories": 4, "min_pairs_per_category": 5,
    "min_repetitions": 3, "min_valid_pair_rate_bp": 8000, "max_interval_width_bp": 2000,
    "require_current": true
});
let p: EconomicsPublicationPolicy = serde_json::from_value(rule.clone()).unwrap();
assert!(p.require_current && p.min_valid_pairs == 30);
let mut lax = rule;
lax.as_object_mut().unwrap().remove("require_current");
assert!(serde_json::from_value::<EconomicsPublicationPolicy>(lax).is_err(), "no default");

Odpověď economics.runs: surová fakta, z nichž se počítá každá metrika.

use majordomus_cli::economics::model::EconomicsRunList;
let l: EconomicsRunList =
    serde_json::from_value(serde_json::json!({ "count": 0, "runs": [] })).unwrap();
assert_eq!(l.count, l.runs.len());
assert!(l.diagnostics.is_empty(), "no diagnostics listed means none");

Jeden běh stručně, s jeho odvozenými součty.

use majordomus_cli::economics::model::EconomicsRunView;
let v: EconomicsRunView = serde_json::from_value(serde_json::json!({
    "id": "vat-rounding--majordomus--r1", "suite": "pilot", "task": "vat-rounding",
    "variant": "majordomus", "repetition": 1, "model": "claude-sonnet-5",
    "revision": "8d37d011ef", "completed": false, "checks": [], "sessions": 1,
    "path": ".ai/repo/benchmarks/economics/runs/pilot/vat-rounding--majordomus--r1.json"
}))
.unwrap();
assert!(v.usage.is_none(), "a run whose provider reported no usage has no totals");
assert!(v.path.ends_with(&format!("{}.json", v.id)));

Hodnota metriky v jednom segmentu dvojic.

use majordomus_cli::economics::model::EconomicsSegment;
let s: EconomicsSegment = serde_json::from_value(serde_json::json!({
    "dimension": "category", "value": "multi-session", "n": 0
}))
.unwrap();
assert!(s.token_reduction.is_none(), "a segment with no valid pair has no distribution");

Sada a stav jejích důkazů.

use majordomus_cli::economics::model::{
    EconomicsFreshness, EconomicsPairCounts, EconomicsSuiteView,
};
let v = EconomicsSuiteView {
    id: "pilot".into(), kind: "live".into(), version: 1, title: "Pilot".into(),
    model: Some("claude-sonnet-5".into()), freshness: EconomicsFreshness::NoEvidence,
    freshness_detail: Some("no run recorded".into()), runs: 0,
    pairs: EconomicsPairCounts { declared: 14, ..EconomicsPairCounts::default() },
    revisions: vec![], harnesses: vec![], models_reported: vec![],
};
let json = serde_json::to_value(&v).unwrap();
assert_eq!(json["freshness"], "no_evidence");
assert_eq!(json["pairs"]["declared"], 14, "declared pairs show even when none ran");

Odpověď economics.summary: každá metrika, odkud pochází, a jediné tvrzení, které důkazy dovolují.

use majordomus_cli::economics::model::EconomicsSummary;
let s: EconomicsSummary = serde_json::from_value(serde_json::json!({
    "present": false,
    "verdict": { "publishable": false, "statement": "No methodology is declared." },
    "metrics": [], "suites": [], "pairs": [], "segments": [], "history": [],
    "variants": [], "hypotheses": []
}))
.unwrap();
assert!(s.methodology.is_none() && s.publication.is_none() && s.diagnostics.is_empty());
let json = serde_json::to_value(&s).unwrap();
assert!(json.get("methodology").is_none(), "an absent methodology is absent, not null");

Identita tokenizeru, zaznamenaná s každým počtem, který vytvořil.

use majordomus_cli::economics::model::EconomicsTokenizer;
let t: EconomicsTokenizer = serde_json::from_value(serde_json::json!({
    "encoding": "o200k_base", "implementation": "tiktoken-rs 0.12.0"
}))
.unwrap();
let other = EconomicsTokenizer { implementation: "tiktoken-rs 0.13.0".into(), ..t.clone() };
assert_ne!(t, other, "the same encoding from another implementation is another tokenizer");

Součty běhu, odvozené z jeho surového využití.

use majordomus_cli::economics::model::EconomicsUsage;
let u = EconomicsUsage {
    input_uncached: 10, cache_write: 90, cache_read: 900, output: 50,
    total_input: 1000, total: 1050, requests: 3, ..EconomicsUsage::default()
};
assert_eq!(u.total_input, u.input_uncached + u.cache_write + u.cache_read);
let json = serde_json::to_value(&u).unwrap();
assert!(json.get("reasoning").is_none() && json.get("cost_microusd").is_none());

Jedna větev experimentu: s čím relace běží a s čím běží bez.

use majordomus_cli::economics::model::EconomicsVariant;
let v: EconomicsVariant = serde_json::from_value(serde_json::json!({
    "id": "baseline", "role": "control", "title": "Without Majordomus",
    "description": "The fixture repository as a competent team keeps it."
}))
.unwrap();
assert_eq!(v.role, "control");
assert!(v.excludes.is_empty(), "an arm that names no exclusion excludes nothing");

Jediná věta, kterou důkazy dovolují, a proč nedovolují silnější.

use majordomus_cli::economics::model::EconomicsVerdict;
let v: EconomicsVerdict = serde_json::from_value(serde_json::json!({
    "publishable": false,
    "statement": "No quantitative token claim: 9 valid pairs of the 30 the rule requires.",
    "unmet": ["min_valid_pairs: 9 < 30"]
}))
.unwrap();
assert!(!v.publishable);
assert_eq!(v.unmet.len(), 1, "every threshold not met is named");