economics.summary

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "suite": {
      "type": [
        "string",
        "null"
      ],
      "description": "Only this suite."
    },
    "category": {
      "type": [
        "string",
        "null"
      ],
      "description": "Only tasks of this category."
    },
    "task": {
      "type": [
        "string",
        "null"
      ],
      "description": "Only this task."
    },
    "model": {
      "type": [
        "string",
        "null"
      ],
      "description": "Only runs that asked for this model."
    }
  },
  "description": "The input of `economics.summary`: optional narrowing of the pairs and metrics. The\nverdict is always about all the evidence, whatever is narrowed, and a narrowed metric\nis never verified: the publication rule was evaluated over all of it, not over a slice.\n\n```\nuse majordomus_cli::economics::model::EconomicsQuery;\nlet all: EconomicsQuery = serde_json::from_value(serde_json::json!({})).unwrap();\nassert_eq!(all, EconomicsQuery::default());\nlet q: EconomicsQuery =\n    serde_json::from_value(serde_json::json!({ \"suite\": \"pilot\", \"category\": \"bugfix\" }))\n        .unwrap();\nassert_eq!(q.suite.as_deref(), Some(\"pilot\"));\nlet typo = serde_json::json!({ \"suites\": \"pilot\" });\nlet refused = serde_json::from_value::<EconomicsQuery>(typo);\nassert!(refused.is_err(), \"a misspelt filter is refused\");\n```",
  "title": "EconomicsQuery"
}

{
  "type": "object",
  "properties": {
    "present": {
      "type": "boolean",
      "description": "Whether a methodology is declared here at all."
    },
    "methodology": {
      "type": [
        "integer",
        "null"
      ],
      "format": "uint32",
      "minimum": 0,
      "description": "The methodology version."
    },
    "question": {
      "type": [
        "string",
        "null"
      ],
      "description": "The question."
    },
    "primary_metric": {
      "type": [
        "string",
        "null"
      ],
      "description": "The primary metric's id."
    },
    "verdict": {
      "$ref": "#/$defs/EconomicsVerdict",
      "description": "What the total-token evidence allows to be said."
    },
    "metrics": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/EconomicsMetric"
      },
      "description": "Every metric."
    },
    "suites": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/EconomicsSuiteView"
      },
      "description": "Every suite and its evidence."
    },
    "pairs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/EconomicsPair"
      },
      "description": "Every pair, valid or not."
    },
    "segments": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/EconomicsSegment"
      },
      "description": "Token reduction by segment."
    },
    "context": {
      "anyOf": [
        {
          "$ref": "#/$defs/EconomicsContextView"
        },
        {
          "type": "null"
        }
      ],
      "description": "The context suite in brief."
    },
    "history": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/EconomicsHistoryPoint"
      },
      "description": "The metric over recorded measurements."
    },
    "variants": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/EconomicsVariant"
      },
      "description": "The arms of the experiment."
    },
    "hypotheses": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/EconomicsHypothesis"
      },
      "description": "The hypotheses, as hypotheses."
    },
    "publication": {
      "anyOf": [
        {
          "$ref": "#/$defs/EconomicsPublicationPolicy"
        },
        {
          "type": "null"
        }
      ],
      "description": "The publication rule."
    },
    "diagnostics": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Problems reading the declarations or the evidence.",
      "default": []
    }
  },
  "required": [
    "present",
    "verdict",
    "metrics",
    "suites",
    "pairs",
    "segments",
    "history",
    "variants",
    "hypotheses"
  ],
  "description": "The answer of `economics.summary`: every metric, where each comes from, and the one\nstatement the evidence allows.\n\n```\nuse majordomus_cli::economics::model::EconomicsSummary;\nlet s: EconomicsSummary = serde_json::from_value(serde_json::json!({\n    \"present\": false,\n    \"verdict\": { \"publishable\": false, \"statement\": \"No methodology is declared.\" },\n    \"metrics\": [], \"suites\": [], \"pairs\": [], \"segments\": [], \"history\": [],\n    \"variants\": [], \"hypotheses\": []\n}))\n.unwrap();\nassert!(s.methodology.is_none() && s.publication.is_none() && s.diagnostics.is_empty());\nlet json = serde_json::to_value(&s).unwrap();\nassert!(json.get(\"methodology\").is_none(), \"an absent methodology is absent, not null\");\n```",
  "title": "EconomicsSummary",
  "$defs": {
    "EconomicsVerdict": {
      "type": "object",
      "properties": {
        "publishable": {
          "type": "boolean",
          "description": "Whether a quantitative total-token claim meets the publication rule."
        },
        "statement": {
          "type": "string",
          "description": "The strongest statement the evidence supports, generated, never typed."
        },
        "unmet": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Every publication threshold not met.",
          "default": []
        }
      },
      "required": [
        "publishable",
        "statement"
      ],
      "description": "The one sentence the evidence allows, and why it allows no stronger one.\n\n```\nuse majordomus_cli::economics::model::EconomicsVerdict;\nlet v: EconomicsVerdict = serde_json::from_value(serde_json::json!({\n    \"publishable\": false,\n    \"statement\": \"No quantitative token claim: 9 valid pairs of the 30 the rule requires.\",\n    \"unmet\": [\"min_valid_pairs: 9 < 30\"]\n}))\n.unwrap();\nassert!(!v.publishable);\nassert_eq!(v.unmet.len(), 1, \"every threshold not met is named\");\n```"
    },
    "EconomicsMetric": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The metric's id."
        },
        "title": {
          "type": "string",
          "description": "A name."
        },
        "class": {
          "$ref": "#/$defs/EconomicsClass",
          "description": "The measurement class."
        },
        "inputs": {
          "anyOf": [
            {
              "$ref": "#/$defs/EconomicsClass"
            },
            {
              "type": "null"
            }
          ],
          "description": "For a derived metric, the class of what it was derived from: a reduction derived from\nobserved usage is not the same evidence as one derived from counted bytes."
        },
        "unit": {
          "type": "string",
          "description": "`ratio`, `tokens`, `calls`."
        },
        "formula": {
          "type": "string",
          "description": "The formula, in words."
        },
        "not": {
          "type": [
            "string",
            "null"
          ],
          "description": "What the metric is not, where it is easily mistaken for something else."
        },
        "value": {
          "type": [
            "number",
            "null"
          ],
          "format": "double",
          "description": "The headline value; absent when nothing was measured."
        },
        "status": {
          "$ref": "#/$defs/EconomicsMetricStatus",
          "description": "Where it stands."
        },
        "n": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "How many values it rests on."
        },
        "distribution": {
          "anyOf": [
            {
              "$ref": "#/$defs/EconomicsDistribution"
            },
            {
              "type": "null"
            }
          ],
          "description": "Their distribution."
        },
        "interval": {
          "anyOf": [
            {
              "$ref": "#/$defs/EconomicsInterval"
            },
            {
              "type": "null"
            }
          ],
          "description": "The interval, when enough values exist."
        },
        "suite": {
          "type": "string",
          "description": "The suite."
        },
        "evidence": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The runs, pairs or seeds it rests on.",
          "default": []
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "What a reader must know before using it.",
          "default": []
        }
      },
      "required": [
        "id",
        "title",
        "class",
        "unit",
        "formula",
        "status",
        "n",
        "suite"
      ],
      "description": "One metric: its value, where it comes from, and how much it can bear.\n\n```\nuse majordomus_cli::economics::model::{EconomicsClass, EconomicsMetric, EconomicsMetricStatus};\nlet m: EconomicsMetric = serde_json::from_value(serde_json::json!({\n    \"id\": \"effective_token_reduction\", \"title\": \"Effective token reduction\",\n    \"class\": \"derived\", \"inputs\": \"observed\", \"unit\": \"ratio\",\n    \"formula\": \"median of 1 - treatment / control\", \"status\": \"not_measured\", \"n\": 0,\n    \"suite\": \"pilot\"\n}))\n.unwrap();\nassert_eq!(m.inputs, Some(EconomicsClass::Observed));\nassert!(m.value.is_none() && m.status == EconomicsMetricStatus::NotMeasured);\nassert!(serde_json::to_value(&m).unwrap().get(\"value\").is_none(), \"no value, not a zero\");\n```"
    },
    "EconomicsClass": {
      "oneOf": [
        {
          "type": "string",
          "const": "observed",
          "description": "Returned by the provider or its harness at run time and recorded unmodified."
        },
        {
          "type": "string",
          "const": "counted",
          "description": "Computed deterministically from bytes on disk with a named, pinned tokenizer."
        },
        {
          "type": "string",
          "const": "derived",
          "description": "Arithmetic over observed or counted values."
        },
        {
          "type": "string",
          "const": "estimated",
          "description": "A number standing in for one nobody measured. Never compared, never published."
        },
        {
          "type": "string",
          "const": "counterfactual",
          "description": "What a mechanism would have avoided, modelled rather than observed."
        }
      ],
      "description": "How a number came to be. The classes are ordered from strongest to weakest, and a value\ncomputed from several inputs is never stronger than the weakest of them.\n\n```\nuse majordomus_cli::economics::model::EconomicsClass;\nassert_eq!(serde_json::to_value(EconomicsClass::Counterfactual).unwrap(), \"counterfactual\");\nlet parsed: EconomicsClass = serde_json::from_value(\"observed\".into()).unwrap();\nassert!(parsed < EconomicsClass::Estimated, \"a stronger class sorts first\");\n```"
    },
    "EconomicsMetricStatus": {
      "oneOf": [
        {
          "type": "string",
          "const": "verified",
          "description": "Measured, and meets the publication rule. Only the primary metric over all the\nevidence can be: the rule is evaluated for it and for nothing else, so no secondary\nmetric and no narrowed slice is ever verified."
        },
        {
          "type": "string",
          "const": "preliminary",
          "description": "Measured, but no claim may rest on it: below the publication rule, narrowed by a\nquery, or a metric the rule was never evaluated for. A result, not a claim."
        },
        {
          "type": "string",
          "const": "measured",
          "description": "Measured deterministically; the publication rule for sampled data does not apply."
        },
        {
          "type": "string",
          "const": "not_measured",
          "description": "Nothing recorded to compute it from."
        }
      ],
      "description": "Where a metric stands against the publication rule: whether its value may back a claim,\nis a result too thin to claim anything, or was never measured at all.\n\n```\nuse majordomus_cli::economics::model::EconomicsMetricStatus;\nassert_eq!(serde_json::to_value(EconomicsMetricStatus::NotMeasured).unwrap(), \"not_measured\");\nlet s: EconomicsMetricStatus = serde_json::from_value(\"preliminary\".into()).unwrap();\nassert_ne!(s, EconomicsMetricStatus::Verified, \"a preliminary result is not a claim\");\n```"
    },
    "EconomicsDistribution": {
      "type": "object",
      "properties": {
        "n": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "How many values."
        },
        "mean": {
          "type": "number",
          "format": "double",
          "description": "Arithmetic mean."
        },
        "median": {
          "type": "number",
          "format": "double",
          "description": "Median."
        },
        "p25": {
          "type": "number",
          "format": "double",
          "description": "25th percentile."
        },
        "p75": {
          "type": "number",
          "format": "double",
          "description": "75th percentile."
        },
        "p95": {
          "type": "number",
          "format": "double",
          "description": "95th percentile."
        },
        "min": {
          "type": "number",
          "format": "double",
          "description": "Smallest."
        },
        "max": {
          "type": "number",
          "format": "double",
          "description": "Largest."
        },
        "sd": {
          "type": [
            "number",
            "null"
          ],
          "format": "double",
          "description": "Sample standard deviation; absent for one value."
        }
      },
      "required": [
        "n",
        "mean",
        "median",
        "p25",
        "p75",
        "p95",
        "min",
        "max"
      ],
      "description": "The shape of a set of per-pair values.\n\n```\nuse majordomus_cli::economics::model::EconomicsDistribution;\nlet d: EconomicsDistribution = serde_json::from_value(serde_json::json!({\n    \"n\": 1, \"mean\": 0.4, \"median\": 0.4, \"p25\": 0.4, \"p75\": 0.4, \"p95\": 0.4,\n    \"min\": 0.4, \"max\": 0.4\n}))\n.unwrap();\nassert!(d.sd.is_none(), \"one value has no sample standard deviation\");\nassert!(d.min <= d.p25 && d.p25 <= d.median && d.median <= d.p75 && d.p75 <= d.max);\n```"
    },
    "EconomicsInterval": {
      "type": "object",
      "properties": {
        "level_bp": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "Confidence in basis points."
        },
        "low": {
          "type": "number",
          "format": "double",
          "description": "Lower bound."
        },
        "high": {
          "type": "number",
          "format": "double",
          "description": "Upper bound."
        },
        "method": {
          "type": "string",
          "description": "How it was computed: a cluster bootstrap over tasks for every metric over pairs or\nruns, whose repetitions of one task are not independent, and an independent\nbootstrap over seeds for the context suite."
        },
        "resamples": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "Resamples."
        },
        "seed": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Generator seed."
        }
      },
      "required": [
        "level_bp",
        "low",
        "high",
        "method",
        "resamples",
        "seed"
      ],
      "description": "A bootstrap interval, with everything needed to reproduce it.\n\n```\nuse majordomus_cli::economics::model::EconomicsInterval;\nlet i: EconomicsInterval = serde_json::from_value(serde_json::json!({\n    \"level_bp\": 9500, \"low\": 0.21, \"high\": 0.38,\n    \"method\": \"bootstrap percentile of the median\", \"resamples\": 10000, \"seed\": 20260924\n}))\n.unwrap();\nassert!(i.low <= i.high);\nassert_eq!(serde_json::to_value(&i).unwrap()[\"seed\"], 20260924, \"the seed travels with it\");\n```"
    },
    "EconomicsSuiteView": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The suite."
        },
        "kind": {
          "type": "string",
          "description": "`live` or `context`."
        },
        "version": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "Its version."
        },
        "title": {
          "type": "string",
          "description": "A name."
        },
        "model": {
          "type": [
            "string",
            "null"
          ],
          "description": "The model, for a live suite."
        },
        "freshness": {
          "$ref": "#/$defs/EconomicsFreshness",
          "description": "Where its evidence stands."
        },
        "freshness_detail": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why, when not current."
        },
        "runs": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Runs recorded."
        },
        "pairs": {
          "$ref": "#/$defs/EconomicsPairCounts",
          "description": "Pair counts."
        },
        "revisions": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The revisions the evidence was recorded at.",
          "default": []
        },
        "harnesses": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The harness versions that ran it.",
          "default": []
        },
        "models_reported": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The models the harness reported.",
          "default": []
        }
      },
      "required": [
        "id",
        "kind",
        "version",
        "title",
        "freshness",
        "runs",
        "pairs"
      ],
      "description": "A suite and the state of its evidence.\n\n```\nuse majordomus_cli::economics::model::{\n    EconomicsFreshness, EconomicsPairCounts, EconomicsSuiteView,\n};\nlet v = EconomicsSuiteView {\n    id: \"pilot\".into(), kind: \"live\".into(), version: 1, title: \"Pilot\".into(),\n    model: Some(\"claude-sonnet-5\".into()), freshness: EconomicsFreshness::NoEvidence,\n    freshness_detail: Some(\"no run recorded\".into()), runs: 0,\n    pairs: EconomicsPairCounts { declared: 14, ..EconomicsPairCounts::default() },\n    revisions: vec![], harnesses: vec![], models_reported: vec![],\n};\nlet json = serde_json::to_value(&v).unwrap();\nassert_eq!(json[\"freshness\"], \"no_evidence\");\nassert_eq!(json[\"pairs\"][\"declared\"], 14, \"declared pairs show even when none ran\");\n```"
    },
    "EconomicsFreshness": {
      "oneOf": [
        {
          "type": "string",
          "const": "current",
          "description": "Recorded under this methodology, and nothing it depends on changed since."
        },
        {
          "type": "string",
          "const": "stale",
          "description": "Recorded under this methodology, but a mechanism it measured changed since."
        },
        {
          "type": "string",
          "const": "incompatible",
          "description": "Recorded under another methodology version: not comparable at all."
        },
        {
          "type": "string",
          "const": "no_evidence",
          "description": "Nothing recorded."
        }
      ],
      "description": "How recorded evidence stands against the repository as it is now.\n\n```\nuse majordomus_cli::economics::model::EconomicsFreshness;\nassert_eq!(serde_json::to_value(EconomicsFreshness::NoEvidence).unwrap(), \"no_evidence\");\nlet f: EconomicsFreshness = serde_json::from_value(\"incompatible\".into()).unwrap();\nassert_eq!(f, EconomicsFreshness::Incompatible);\n```"
    },
    "EconomicsPairCounts": {
      "type": "object",
      "properties": {
        "declared": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Pairs the suite declares."
        },
        "attempted": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Pairs with at least one run recorded."
        },
        "valid": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Pairs that count."
        },
        "control_failed": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Pairs whose control failed."
        },
        "treatment_failed": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Pairs whose treatment failed."
        },
        "both_failed": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Pairs where both failed."
        },
        "other": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Pairs not comparable, missing a side, lacking usage, or excluded."
        }
      },
      "required": [
        "declared",
        "attempted",
        "valid",
        "control_failed",
        "treatment_failed",
        "both_failed",
        "other"
      ],
      "description": "Pair counts of a suite, so that nothing is dropped out of sight.\n\n```\nuse majordomus_cli::economics::model::EconomicsPairCounts;\nlet c = EconomicsPairCounts {\n    declared: 14, attempted: 12, valid: 9, control_failed: 1,\n    treatment_failed: 1, both_failed: 0, other: 1,\n};\nlet accounted = c.valid + c.control_failed + c.treatment_failed + c.both_failed + c.other;\nassert_eq!(accounted, c.attempted, \"every attempted pair is in exactly one bucket\");\nassert_eq!(EconomicsPairCounts::default().declared, 0);\n```"
    },
    "EconomicsPair": {
      "type": "object",
      "properties": {
        "suite": {
          "type": "string",
          "description": "The suite."
        },
        "task": {
          "type": "string",
          "description": "The task."
        },
        "category": {
          "type": "string",
          "description": "The task's category."
        },
        "sessions": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Sessions the task spans."
        },
        "repetition": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "The repetition."
        },
        "control": {
          "type": [
            "string",
            "null"
          ],
          "description": "The control run's id, when recorded."
        },
        "treatment": {
          "type": [
            "string",
            "null"
          ],
          "description": "The treatment run's id, when recorded."
        },
        "status": {
          "$ref": "#/$defs/EconomicsPairStatus",
          "description": "Whether it counts."
        },
        "reasons": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Why not, when it does not.",
          "default": []
        },
        "control_usage": {
          "anyOf": [
            {
              "$ref": "#/$defs/EconomicsUsage"
            },
            {
              "type": "null"
            }
          ],
          "description": "The control's totals."
        },
        "treatment_usage": {
          "anyOf": [
            {
              "$ref": "#/$defs/EconomicsUsage"
            },
            {
              "type": "null"
            }
          ],
          "description": "The treatment's totals."
        },
        "token_reduction": {
          "type": [
            "number",
            "null"
          ],
          "format": "double",
          "description": "`1 - treatment / control` on total tokens. Negative: the treatment cost more.\nPresent on a valid pair, and on an excluded pair that would otherwise be valid, so\nthat the outlier rule's effect can be shown both ways; only valid pairs enter a\nmetric other than `effective_token_reduction.including_excluded`. The same holds for\nevery reduction and overhead below."
        },
        "cost_reduction": {
          "type": [
            "number",
            "null"
          ],
          "format": "double",
          "description": "The same on the harness's cost projection."
        },
        "tool_call_reduction": {
          "type": [
            "number",
            "null"
          ],
          "format": "double",
          "description": "The same on tool calls."
        },
        "continuation_reduction": {
          "type": [
            "number",
            "null"
          ],
          "format": "double",
          "description": "The same on the tokens of the last session only: what continuing cost."
        },
        "first_request_overhead": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "description": "First-request input of the treatment minus that of the control: what the treatment\nadds before the model has done anything."
        }
      },
      "required": [
        "suite",
        "task",
        "category",
        "sessions",
        "repetition",
        "status"
      ],
      "description": "A control run and its treatment run, and what follows from them.\n\n```\nuse majordomus_cli::economics::model::{EconomicsPair, EconomicsPairStatus};\nlet p: EconomicsPair = serde_json::from_value(serde_json::json!({\n    \"suite\": \"pilot\", \"task\": \"vat-rounding\", \"category\": \"bugfix\", \"sessions\": 1,\n    \"repetition\": 2, \"control\": \"vat-rounding--baseline--r2\", \"status\": \"missing\",\n    \"reasons\": [\"no treatment run recorded\"]\n}))\n.unwrap();\nassert_eq!(p.status, EconomicsPairStatus::Missing);\nassert!(p.treatment.is_none() && p.token_reduction.is_none(), \"no side, no reduction\");\n```"
    },
    "EconomicsPairStatus": {
      "oneOf": [
        {
          "type": "string",
          "const": "valid",
          "description": "Both runs succeeded, are comparable and report usage."
        },
        {
          "type": "string",
          "const": "control_failed",
          "description": "The control run failed a success gate."
        },
        {
          "type": "string",
          "const": "treatment_failed",
          "description": "The treatment run failed a success gate."
        },
        {
          "type": "string",
          "const": "both_failed",
          "description": "Both failed."
        },
        {
          "type": "string",
          "const": "usage_unavailable",
          "description": "A run reports no usage to compare."
        },
        {
          "type": "string",
          "const": "incomparable",
          "description": "The runs differ in something the methodology requires them to share."
        },
        {
          "type": "string",
          "const": "missing",
          "description": "One side was never recorded."
        },
        {
          "type": "string",
          "const": "excluded",
          "description": "A run is excluded under the outlier rule."
        }
      ],
      "description": "Why a pair does or does not count.\n\n```\nuse majordomus_cli::economics::model::EconomicsPairStatus;\nassert_eq!(serde_json::to_value(EconomicsPairStatus::ControlFailed).unwrap(), \"control_failed\");\nlet s: EconomicsPairStatus = serde_json::from_value(\"usage_unavailable\".into()).unwrap();\nassert_ne!(s, EconomicsPairStatus::Valid);\n```"
    },
    "EconomicsUsage": {
      "type": "object",
      "properties": {
        "input_uncached": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Input neither read from nor written to the cache."
        },
        "cache_write": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Input written to the cache."
        },
        "cache_read": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Input read from the cache."
        },
        "output": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Output, reasoning included."
        },
        "reasoning": {
          "type": [
            "integer",
            "null"
          ],
          "format": "uint64",
          "minimum": 0,
          "description": "Reasoning tokens, when every request reported them."
        },
        "total_input": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "All input."
        },
        "total": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "All input and output."
        },
        "requests": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Provider requests."
        },
        "tool_calls": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Tool calls."
        },
        "cost_microusd": {
          "type": [
            "integer",
            "null"
          ],
          "format": "uint64",
          "minimum": 0,
          "description": "The harness's cost projection, in millionths of a dollar, when every session had one."
        }
      },
      "required": [
        "input_uncached",
        "cache_write",
        "cache_read",
        "output",
        "total_input",
        "total",
        "requests",
        "tool_calls"
      ],
      "description": "A run's totals, derived from its raw usage.\n\n```\nuse majordomus_cli::economics::model::EconomicsUsage;\nlet u = EconomicsUsage {\n    input_uncached: 10, cache_write: 90, cache_read: 900, output: 50,\n    total_input: 1000, total: 1050, requests: 3, ..EconomicsUsage::default()\n};\nassert_eq!(u.total_input, u.input_uncached + u.cache_write + u.cache_read);\nlet json = serde_json::to_value(&u).unwrap();\nassert!(json.get(\"reasoning\").is_none() && json.get(\"cost_microusd\").is_none());\n```"
    },
    "EconomicsSegment": {
      "type": "object",
      "properties": {
        "dimension": {
          "type": "string",
          "description": "`category`, `sessions`, `complexity`."
        },
        "value": {
          "type": "string",
          "description": "The segment."
        },
        "n": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Valid pairs in it."
        },
        "token_reduction": {
          "anyOf": [
            {
              "$ref": "#/$defs/EconomicsDistribution"
            },
            {
              "type": "null"
            }
          ],
          "description": "Distribution of per-pair token reduction."
        }
      },
      "required": [
        "dimension",
        "value",
        "n"
      ],
      "description": "A metric's value within one segment of the pairs.\n\n```\nuse majordomus_cli::economics::model::EconomicsSegment;\nlet s: EconomicsSegment = serde_json::from_value(serde_json::json!({\n    \"dimension\": \"category\", \"value\": \"multi-session\", \"n\": 0\n}))\n.unwrap();\nassert!(s.token_reduction.is_none(), \"a segment with no valid pair has no distribution\");\n```"
    },
    "EconomicsContextView": {
      "type": "object",
      "properties": {
        "revision": {
          "type": "string",
          "description": "The revision measured."
        },
        "measured_at": {
          "type": "string",
          "description": "When."
        },
        "tokenizer": {
          "$ref": "#/$defs/EconomicsTokenizer",
          "description": "The tokenizer."
        },
        "seeds": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Seeds measured."
        },
        "candidate_tokens": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Counted candidate tokens (relevant: selected or cut by the budget), all seeds."
        },
        "considered_tokens": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Counted tokens of everything the compiler reached, all seeds."
        },
        "selected_tokens": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Counted selected tokens, all seeds."
        },
        "estimated_selected_tokens": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "The compiler's own estimate of the selected tokens, all seeds."
        },
        "excluded_tokens": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "format": "uint64",
            "minimum": 0
          },
          "description": "Counted tokens left out, by reason, all seeds."
        },
        "seeds_over_budget_counted": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Seeds whose counted selection exceeds the compiler's budget."
        },
        "budget_tokens": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "The compiler's budget."
        }
      },
      "required": [
        "revision",
        "measured_at",
        "tokenizer",
        "seeds",
        "candidate_tokens",
        "considered_tokens",
        "selected_tokens",
        "estimated_selected_tokens",
        "excluded_tokens",
        "seeds_over_budget_counted",
        "budget_tokens"
      ],
      "description": "The context suite's latest measurement, in brief.\n\n```\nuse std::collections::BTreeMap;\nuse majordomus_cli::economics::model::{EconomicsContextView, EconomicsTokenizer};\nlet v = EconomicsContextView {\n    revision: \"8d37d011ef\".into(), measured_at: \"2026-09-24T10:00:00Z\".into(),\n    tokenizer: EconomicsTokenizer {\n        encoding: \"o200k_base\".into(), implementation: \"tiktoken-rs 0.12.0\".into(),\n    },\n    seeds: 2, candidate_tokens: 20_000, considered_tokens: 300_000, selected_tokens: 15_000,\n    estimated_selected_tokens: 16_000,\n    excluded_tokens: BTreeMap::from([(\"budget\".into(), 5_000)]),\n    seeds_over_budget_counted: 0, budget_tokens: 8_000,\n};\nassert_eq!(v.selected_tokens + v.excluded_tokens[\"budget\"], v.candidate_tokens);\nassert_eq!(serde_json::to_value(&v).unwrap()[\"tokenizer\"][\"encoding\"], \"o200k_base\");\n```"
    },
    "EconomicsTokenizer": {
      "type": "object",
      "properties": {
        "encoding": {
          "type": "string",
          "description": "The encoding: `o200k_base`."
        },
        "implementation": {
          "type": "string",
          "description": "The implementation and its pinned version."
        }
      },
      "required": [
        "encoding",
        "implementation"
      ],
      "description": "The identity of a tokenizer, recorded with every count it produced.\n\n```\nuse majordomus_cli::economics::model::EconomicsTokenizer;\nlet t: EconomicsTokenizer = serde_json::from_value(serde_json::json!({\n    \"encoding\": \"o200k_base\", \"implementation\": \"tiktoken-rs 0.12.0\"\n}))\n.unwrap();\nlet other = EconomicsTokenizer { implementation: \"tiktoken-rs 0.13.0\".into(), ..t.clone() };\nassert_ne!(t, other, \"the same encoding from another implementation is another tokenizer\");\n```"
    },
    "EconomicsHistoryPoint": {
      "type": "object",
      "properties": {
        "suite": {
          "type": "string",
          "description": "The suite."
        },
        "methodology": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "The methodology version, so that incompatible versions are never drawn as one line."
        },
        "revision": {
          "type": "string",
          "description": "The revision."
        },
        "at": {
          "type": "string",
          "description": "When."
        },
        "metric": {
          "type": "string",
          "description": "The metric."
        },
        "value": {
          "type": "number",
          "format": "double",
          "description": "Its value."
        },
        "n": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "How many values it rests on."
        }
      },
      "required": [
        "suite",
        "methodology",
        "revision",
        "at",
        "metric",
        "value",
        "n"
      ],
      "description": "A recorded measurement over time: one entry per recorded context run.\n\n```\nuse majordomus_cli::economics::model::EconomicsHistoryPoint;\nlet p: EconomicsHistoryPoint = serde_json::from_value(serde_json::json!({\n    \"suite\": \"context\", \"methodology\": 1, \"revision\": \"8d37d011ef\",\n    \"at\": \"2026-09-24T10:00:00Z\", \"metric\": \"context_reduction_ratio\", \"value\": 0.62, \"n\": 40\n}))\n.unwrap();\nassert_eq!((p.methodology, p.n), (1, 40));\nassert_eq!(serde_json::to_value(&p).unwrap()[\"metric\"], \"context_reduction_ratio\");\n```"
    },
    "EconomicsVariant": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "`baseline`, `majordomus`, ..."
        },
        "role": {
          "type": "string",
          "description": "`control` or `treatment`."
        },
        "title": {
          "type": "string",
          "description": "A short name."
        },
        "description": {
          "type": "string",
          "description": "Exactly what the arm consists of."
        },
        "excludes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "What the arm deliberately does not include.",
          "default": []
        }
      },
      "required": [
        "id",
        "role",
        "title",
        "description"
      ],
      "description": "One arm of the experiment: what the session runs with, and what it runs without.\n\n```\nuse majordomus_cli::economics::model::EconomicsVariant;\nlet v: EconomicsVariant = serde_json::from_value(serde_json::json!({\n    \"id\": \"baseline\", \"role\": \"control\", \"title\": \"Without Majordomus\",\n    \"description\": \"The fixture repository as a competent team keeps it.\"\n}))\n.unwrap();\nassert_eq!(v.role, \"control\");\nassert!(v.excludes.is_empty(), \"an arm that names no exclusion excludes nothing\");\n```"
    },
    "EconomicsHypothesis": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "A slug."
        },
        "statement": {
          "type": "string",
          "description": "What is hypothesised."
        },
        "status": {
          "type": "string",
          "description": "`untested`, `supported`, `refuted` — set by a person reading the evidence."
        }
      },
      "required": [
        "id",
        "statement",
        "status"
      ],
      "description": "A statement the benchmark exists to test. Never a result.\n\n```\nuse majordomus_cli::economics::model::EconomicsHypothesis;\nlet h: EconomicsHypothesis = serde_json::from_value(serde_json::json!({\n    \"id\": \"continuity\",\n    \"statement\": \"Work that spans sessions gains the most.\",\n    \"status\": \"untested\"\n}))\n.unwrap();\nassert_eq!(h.status, \"untested\");\nassert_eq!(serde_json::to_value(&h).unwrap()[\"id\"], \"continuity\");\n```"
    },
    "EconomicsPublicationPolicy": {
      "type": "object",
      "properties": {
        "min_valid_pairs": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Valid matched pairs, at least."
        },
        "min_categories": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Task categories with enough pairs, at least."
        },
        "min_pairs_per_category": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Pairs a category needs to count towards `min_categories`."
        },
        "min_repetitions": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "Repetitions of every task and variant, at least."
        },
        "min_valid_pair_rate_bp": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "Valid pairs over attempted pairs, in basis points, at least."
        },
        "max_interval_width_bp": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "Width of the interval, in basis points of reduction, at most."
        },
        "require_current": {
          "type": "boolean",
          "description": "Whether the evidence must be current (its mechanism unchanged since it was recorded)."
        }
      },
      "required": [
        "min_valid_pairs",
        "min_categories",
        "min_pairs_per_category",
        "min_repetitions",
        "min_valid_pair_rate_bp",
        "max_interval_width_bp",
        "require_current"
      ],
      "description": "When a quantitative total-token claim may be published. Every threshold must hold.\n\n```\nuse majordomus_cli::economics::model::EconomicsPublicationPolicy;\nlet rule = serde_json::json!({\n    \"min_valid_pairs\": 30, \"min_categories\": 4, \"min_pairs_per_category\": 5,\n    \"min_repetitions\": 3, \"min_valid_pair_rate_bp\": 8000, \"max_interval_width_bp\": 2000,\n    \"require_current\": true\n});\nlet p: EconomicsPublicationPolicy = serde_json::from_value(rule.clone()).unwrap();\nassert!(p.require_current && p.min_valid_pairs == 30);\nlet mut lax = rule;\nlax.as_object_mut().unwrap().remove(\"require_current\");\nassert!(serde_json::from_value::<EconomicsPublicationPolicy>(lax).is_err(), \"no default\");\n```"
    }
  }
}