Module cli 

CLI surfaces for the firstpass binary (SPEC §7.3/§7.4): doctor validates a setup before you route real traffic through it, and trace reads recent audit records from the store. Both are kept here (not in the binary) so the judgment is unit-tested.

Structs

AttemptExplanation

Per-attempt slice of a RouteExplanation.

Check

One line of the doctor report.

DoctorReport

The result of firstpass doctor.

EvalsSummary

Per-gate and per-rung evaluation summary computed from receipts — the operator’s live eval suite: how each gate is verdict-ing, how often routing escalates, where serves land.

PredictorEval

Aggregate gate verdicts + routing behavior over traces (enforce only). Prequential evaluation of the per-query gate-pass predictor (ADR 0008 Phase 2) — the honest “is it any good yet” check before the predictor is ever allowed to act. Replays the receipts in order through a fresh predictor: for each attempt with a clear Pass/Fail verdict, predict before update (so every prediction is on data the model has not trained on), then update. Reports AUC (predicted -> passed) and Brier score over those pairs.

RouteExplanation

A structured, agent-readable explanation of a single routing decision — why the ladder went where it did, built purely from a sealed Trace.

SavingsSummary

Aggregated spend/savings over a set of traces — the number the operator screenshots. Pure so it’s unit-testable; firstpass savings feeds it the trace store.

VerifyReport

Outcome of an independent receipt-chain verification — the compliance artifact.

Enums

Channel

How this binary got onto the machine. Upgrading is channel-specific — running the wrong updater either does nothing or fights the package manager that owns the file — so firstpass upgrade detects the channel instead of guessing one.

CheckStatus

A single doctor check outcome.

Functions

command_on_path

Whether program is runnable: an explicit path (contains a separator) that exists, or a bare name found in one of PATH’s directories.

detect_channel

Work out how this binary was installed from the path it runs as. Pure: the executable path, the updater probe and the container check are all injected, so every branch is unit-tested without installing anything.

doctor

Validate a loaded config against the environment: routing sanity, provider key presence, and that every configured gate’s command actually exists. env looks up environment variables (injected so this is testable).

evaluate_predictor

Run the prequential predictor evaluation over traces with the given lr/l2.

explain_trace

Explain one routing decision from its sealed receipt — the “why this model” answer, as structured data an agent can act on (and the backing for the MCP explain_route tool).

export_receipts_jsonl

Render traces as a JSONL receipt export — one sealed receipt per line, in chain order. This is the artifact an operator hands an auditor; the deferred-verdict side table is never included (it is not part of the hashed body).

format_evals

Render an EvalsSummary for humans (--json callers serialize the struct instead).

format_savings

Render a SavingsSummary for humans (--json callers serialize the struct instead).

format_traces

Render the most recent limit traces as JSON lines — machine-first (SPEC §0.2): each line is a full Trace, newest last.

parse_receipt_jsonl

Parse a JSONL receipt export (one Trace per line) back into traces, for offline verification. Blank lines are skipped; a malformed line fails loudly with its line number.

summarize_evals

summarize_savings

Aggregate spend vs the always-top counterfactual over traces.

upgrade_report

The text firstpass upgrade prints. Separated from the doing so the wording is testable.

verify_receipts

Independently re-derive the hash chain over traces from genesis — the same computation an external auditor runs, with no trust in the proxy or the database. A single altered or reordered receipt breaks the chain at its index.