Public JSON contract

marginci test ... --json writes exactly one JSON document to stdout, followed by newline, including errors. Application output is saved in attempt log files; --verbose progress uses stderr. Human verdict, JSON verdict and process status agree.

Schema version 2, scope declared_workload. Additive comparison_identity records comparison inputs without changing finite-workload semantics. Consumers should accept additive fields; changing meaning/removing fields requires a version change.

Completed run fields: schema_version, scope, run_id, operation, verdict, exit_code, baseline_revision, candidate_revision, comparison_identity, baseline, candidate, measured_regression, max_regression, providers, coverage, comparison, reasons, artifacts and pairs.

• verdict: lowercase pass/fail/inconclusive/error. Exit codes 0/1/2/3 respectively.
• baseline_revision: immutable baseline commit. candidate_revision: immutable HEAD plus working content hash; see comparison_identity.candidate_commit and candidate_snapshot_sha256.
• comparison_identity: frozen effective config SHA-256, immutable commits, snapshot digest/dirty flag, resolved argv, frozen file SHA-256 values, success protocol and environment policy.
• Side economics: operations, attempts, successful_operations, known_economic_value_usd (subtotal), its exact decimal string, total_economic_value_usd, cost_per_success, unit_cost_status, provider/provenance totals.
• measured_regression: fraction (0.20 means +20%), computed from unrounded exact underlying values. Null if undefined/incomplete. max_regression is the configured fraction.
• coverage: complete, declared_cases, completed_pairs, selected case_ids. Complete failed operations can contribute known spend and zero successes. Coverage alone does not establish a defined ratio.
• comparison.method: observed_cost_per_success. No confidence interval or population estimate.
• reasons: objects with stable code and human detail; consumers branch on codes, not text. Examples: OPERATION_TIMEOUT, OPERATION_CANCELLED, INCONCLUSIVE_BUDGET_LIMIT, INCOMPLETE_MEASUREMENT, NO_SUCCESSFUL_OPERATIONS, ZERO_BASELINE_VALUE, UNREPRESENTABLE_RATIO, INCONCLUSIVE_PROVIDER_USAGE.
• artifacts: local run-directory path. Stable file names: report.json, config.json, revisions.json, comparison-identity.json and source-files.json. Internal ledger/attempt layout may add data.
• pairs: completed case pairs and attempts; partial/unpaired attempt evidence remains in artifacts and side subtotals.

Unknown/nonfinite economic results use explicit null, never NaN/Infinity or a fabricated zero. ERROR keeps the existing smaller envelope: schema_version, scope, verdict, exit_code and reasons. No revisions/economics are invented if preconditions prevented construction.

init, doctor, help and version with --json also produce one JSON document but are setup interfaces, not this economic-report schema. A successful doctor response explicitly says it is not PASS and does not perform dependency installs or paid operations.