Node Preflight

1. toolchain

Shells out to cargo --version, parses the semver from the second whitespace-delimited field, and compares major and minor only. It then line-scans the root Cargo.toml for rust-version and rust-toolchain.toml for channel. Below the MSRV is an error; a pinned channel whose major and minor differ from the active Cargo is an error. All four failure paths carry urn:chio:error:cli:doctor-toolchain-mismatch.

No Cargo on PATH, a cargo --version that exits nonzero, and output the parser cannot read collapse to one error. The first two report Failed to invoke `cargo --version`. and exit 1. Run against the Chio workspace root, the probe finds rust-version = "1.94" and channel = "1.94.1", so a Cargo outside 1.94 fails the pin comparison and one below 1.94 fails the MSRV comparison.

channel = "stable" yields no numeric pair, so the pin comparison is skipped. Both file reads root at the working directory: from a subdirectory the probe finds neither file and passes on the active toolchain alone, which is the captured run, whose only context key is cargo_version. Read the msrv and pinned_channel keys to know whether a comparison happened; the unparseable-output branch attaches neither help nor context.

2. oci

Resolves a registry from CHIO_GUARD_REGISTRY, then CHIO_GUARD_REGISTRY_REFERENCE, then a registry: line in chio.yaml. An empty variable counts as unset. The file fallback is a line scan: the first line whose trimmed text starts with registry:, at any nesting depth. With nothing resolved it reports info.

Otherwise it sends one HEAD with a 5-second timeout, to the reference itself when it starts with http and to https://{registry}/v2/ otherwise, and accepts 2xx, 401, or 404. It sends no credential, which is why 401 counts. A pass establishes that the host resolves, terminates TLS, and answers. A reference with a repository path (ghcr.io/example/chio) gains /v2/ after the path, which is not the registry API root. Every failure is a warning.

The guard pull path reads its own variables, such as CHIO_GUARD_REGISTRY_PASSWORD in cli/types/runtime.rs, and registry is not a key in the runtime schema.

3. cosign

Resolves a bundle path from CHIO_GUARD_BUNDLE or, failing that, .chio/guard-bundle.sigstore.json under the working directory if it exists. A CHIO_GUARD_BUNDLE pointing at a missing file is a warning, Cannot read guard bundle {path}: {err}, under doctor-cosign-stale. Once a path resolves, the probe reads modified() with a created() fallback, converts the elapsed time to whole days, and warns above 90. Exactly 90 days passes.

The probe stats the file and reads its age; it checks no signature. When the elapsed time cannot be computed, from a future mtime, a clock moved backwards, or a filesystem with neither timestamp, age_days is 0 and the probe passes. Signature, identity, and inclusion checks run in chio-attest-verify’s verify_bundle, reached through chio attest and the bundle checks on chio bind; Guard Supply Chain covers them at load time.

4. otel

Reads CHIO_OTEL_RECEIPT_EXPORTER_ENDPOINT, then OTEL_EXPORTER_OTLP_ENDPOINT, records which won in a source context key, and parses the value as a URL, prefixing http:// when it carries no http:// or https:// scheme. Surrounding whitespace is rejected, which catches a pasted trailing space. An empty value counts as unset and reports info.

It sends no span and opens no socket, so --skip-network leaves it unchanged; its parameter is named _config. Anything url::Url::parse accepts passes, so a typo that still parses passes here. Both variables are doctor-only; a node’s OTLP destination is telemetry.endpoint in the runtime chio.yaml schema.

5. kernel_runtime

With CHIO_KERNEL_METRICS_URL unset, the probe reports info and names the variable. With it set, the probe sends one GET with a 5-second timeout and substring-matches the body for chio_kernel_dispatch_inflight, without reading the HTTP status. A 401, 404, or 500 whose body lacks the string, a connection failure, and an unreadable body all report the warning Metrics endpoint did not expose the chio_kernel_dispatch_inflight gauge.

The kernel’s metric families are served at /metrics on the chio api protect router and on the control plane. That route sits behind require_sidecar_control_middleware, the admin gate the approval routes use, and the probe sends no credential. handle_metrics composes the body from the guard families (chio_guard_verdict_total, chio_guard_deny_total, and the rest), the OTEL-drop, signing-queue-block, settlement-unresolved, and ambiguous-dispatch families, the receipt watchdog gauges, the HTTP mediation-edge families, and the alert pack. Node Observability lists them.

All four failure branches carry urn:chio:error:cli:doctor-otel-unresolved, which the registry scopes to the OTLP endpoint or kernel runtime metrics, so a code-based alert cannot tell probe 4 from probe 5. Split on the probe field.

6. chio_yaml

Reads ./chio.yaml, parses it with serde_yml, requires a top-level mapping, and requires the keys version and policy to be present. Values are not inspected, extra top-level keys are ignored, and the file policy names is not opened.

A parse failure carries the parser’s line and column into line and column, falling back to 0, 0; missing keys report line: 1, column: 1 and list the names in missing. Only ErrorKind::NotFound is info. Any other read failure, a directory at that path or a permission denial, is an error and exits 1.

The runtime loader chio_config::load_from_file parses a different contract under the same filename. ChioConfig knows kernel, adapters, edges, receipts, logging, telemetry, guards, and wasm_guards, and the eleven structs in chio-config/src/schema.rs carry deny_unknown_fields. Where a runtime configuration lives at ./chio.yaml, gate CI on the other five probes.

Probe contract and report fields

A probe has a stable lowercase name and one method that consumes a read-only config and returns one report. Probes must not panic: a failure comes back as a report carrying a registry code.

pub trait Probe {
    /// Stable probe identifier. Must be lowercase ASCII, no spaces.
    fn name(&self) -> &'static str;

    /// Execute the probe.
    fn run(&self, config: &ProbeConfig) -> ProbeReport;
}

ProbeConfig has three fields, the same for every probe: skip_network from --skip-network or the environment, fix_enabled from --fix, and workdir, a test-only override the binary leaves as None, so every path-resolving probe roots at the working directory. DoctorRunner::standard fixes the probe set and order, DoctorArgs is three booleans, and the doctor never opens a receipt or authority database or reads a HealthFlag.

worst_severity_drives_exit_code and warnings_do_not_drive_non_zero_exit test the aggregate, and doctor_json_envelope_carries_schema_and_reports in tests/doctor_skeleton.rs tests the envelope. Each doctor environment variable, CHIO_GUARD_REGISTRY, CHIO_GUARD_REGISTRY_REFERENCE, CHIO_GUARD_BUNDLE, CHIO_KERNEL_METRICS_URL, and both OTLP variables, has the doctor as its only reader.

Envelope and rendering

--json, or the global --json or --format json, prints one compact line on stdout. cmd_doctor calls std::process::exit directly, so exit_code and the process status agree.

let payload = serde_json::json!({
    "schema": "chio.doctor.v1",
    "worst": run.worst,
    "exit_code": run.exit_code(),
    "reports": run.reports,
});

Keys come out alphabetical: the workspace leaves serde_json’s preserve_order feature off, so serde_json::Map is a BTreeMap. Parse the payload. context is omitted on reports with none; help is null on passing reports.

The human renderer prints a leading chio doctor line, one [ok] probe (code): message line per report with indented help: and context lines, a repaired: yes line where it applies, and summary: worst severity = ..., exit code = .... Its warning marker is [warn], where JSON says warning.

Repair behavior

One probe reads fix_enabled, in one branch: chio_yaml, on ErrorKind::NotFound. scaffold_missing writes with create_new(true), and if the file appeared between the read and the create, the AlreadyExists arm re-reads and validates it. On success the report is ok with repaired: true and a created: true context key.

The repair runs inline, inside the sixth probe, in place of the report it would have emitted. An existing chio.yaml with missing keys never consults the flag, and on a host where every probe passes the flag does nothing.

Network skip resolution

The environment check is presence-only (std::env::var(...).is_ok()), so an exported empty value counts. cmd_doctor folds both switches into ProbeConfig::skip_network before building the runner, and the two network probes re-check the variable, so a library caller passing skip_network: false still gets the skip. Only oci and kernel_runtime build an HTTP client, each with a 5-second timeout and an egress allowance comment marking it a diagnostic probe against a configured endpoint. tests/doctor_oci.rs and tests/doctor_otel.rs assert the skipped and unconfigured signals.