JSON report schema reference

mutineer run --format json emits a single JSON object (one line, newline-terminated) describing the whole run. It is the machine-readable contract for tooling — CI gates, dashboards, and AI coding agents. Output is deterministic: arrays are sorted by (file, line, operator) regardless of --jobs worker finish order, so two runs of the same inputs produce byte-identical output.

Versioning contract

The top-level schema_version (a string, e.g. "1.4") follows these rules:

• Additive changes (new keys on existing objects, new top-level keys) bump the minor version (1.0 → 1.1). Existing keys keep their meaning. Consumers MUST ignore unknown keys.
• Breaking changes (renaming/removing a key, changing a value's type or meaning) bump the major version (1.x → 2.0).

Mutant id values are opaque identifiers. How an id is derived is versioned by summary.id_format, not by schema_version: when id_format changes, every id value can change while the key keeps its type and meaning. Compare ids only between reports with the same id_format (a missing key is the old format).

Top-level shape

{
  "schema_version": "1.4",
  "summary":      { /* run totals, see below */ },
  "survivors":    [ /* mutants the suite failed to catch — the actionable gaps */ ],
  "no_coverage":  [ /* mutants on lines no test exercises */ ],
  "uncapturable": [ /* mutants whose would-be test errored during coverage capture */ ],
  "no_verdict":   [ /* mutants that were attempted and produced no verdict */ ],
  "ignored":      [ /* mutants the user suppressed (equivalent mutants) */ ],
  "per_source":   [ /* per-file roll-up */ ],
  "baseline":     { /* present ONLY with --baseline: the delta vs a prior run */ }
}

summary (object)

survivors[] (array of object)

Each surviving mutant — the records an agent or reviewer acts on:

no_coverage[] and uncapturable[] (array of object)

Both use the lean shape { subject, file, line }. no_coverage is a genuine coverage gap; uncapturable means the test that should cover the line errored while capturing coverage (fix the harness, not the test).

no_verdict[] (array of object)

Every mutant that was attempted and produced no verdict: { subject, file, line, id, status, details }. status is "error", "timeout" or "uncapturable", and its length equals summary.no_verdict.

details carries the cause where there is one. For "error" that is the failure (a daemon crash, say); for "timeout" and "uncapturable" it is null, because the status is the whole story.

A failure before the mutant could be forked has no subject or mutation, so subject, file, line and id are null on that entry. It still appears, because the counts must reconcile — but that means id is not a reliable join key here, unlike in survivors[] and ignored[].

Uncapturable mutants appear both here and in uncapturable[], which keeps its lean shape for consumers that already read it.

Read this array when the score looks better than you expect: these mutants are excluded from the score's denominator, so a broken harness raises the score rather than lowering it. That is why --threshold gates on completeness as well (see Exit codes).

ignored[] (array of object)

Suppressed (equivalent) mutants, so you can audit what's silenced: { subject, file, line, operator, token, id }.

per_source[] (array of object)

Per-file roll-up: { file, total, killed, survived, no_coverage, score } (score is float | null as above). total counts classified results for that file. A --fail-fast report is partial: unscheduled candidates are omitted from these counts and from the top-level totals.

baseline (object, only with --baseline)

The delta versus the prior --format json report, matched by id. A baseline without summary.id_format also matches on old-format ids (counted in summary.legacy_id_matches.baseline):

Exit codes

Under a positive --threshold, a run is gated on being complete as well as on its score. Mutants with no verdict are excluded from the score's denominator, so a broken harness inflates the score instead of lowering it. Past 10% of attempted mutants — and never for a single one, however small the run — the score is treated as covering too little of the run to gate on. The floor applies only when there is a score: a run where nothing could be scored at all fails on a single broken mutant, because there is no score to weigh it against. Read no_verdict[] to see what failed. A run where nothing was scored and something broke already exits 1.

--threshold and --baseline are independent gates OR'd together (the worse code wins); usage errors (2) always win. Exit 2 still means "you invoked me wrong". Exit 1 now covers three distinct situations — tests too weak, the run did not complete, or a baseline regression — and they are not distinguishable from the exit code alone. Tell them apart from the JSON: compare summary.score against your threshold, summary.no_verdict / summary.attempted against 10%, and baseline.regressed. A run that failed only on completeness is the one worth retrying rather than blaming on the tests.