treeboot-spec 0.16.0

Executable language-agnostic conformance specification for Treeboot.
Documentation

treeboot-spec

treeboot-spec is the executable, language-agnostic compatibility contract for Treeboot implementations. It packages the canonical specification, config JSON Schema, and black-box conformance cases.

The suite invokes a candidate executable directly. Build the candidate once and pass its path rather than using cargo run for each of the hundreds of case invocations.

treeboot-spec test -- /path/to/treeboot
treeboot-spec test --profile functional -- /path/to/treeboot
treeboot-spec test --format json -- /path/to/treeboot
treeboot-spec test --filter run.sync -- /path/to/treeboot
treeboot-spec list
treeboot-spec show
treeboot-spec schema

The default full profile verifies functional behavior plus the candidate's declared specification version and exact canonical schema bytes. The functional profile checks portable behavior while allowing those identities to differ. A functional-profile pass covers only the selected cases and preserves explicit capability skips for the caller to assess. It does not establish full conformance with this crate's specification release.

Human output is concise by default. It prints a summary, skips, failing case identifiers, then numbered failure details. Add --verbose to list passing cases too. When stderr is a terminal, the CLI displays one live progress line; --no-progress disables it. JSON reports never write progress to stderr and retain the same serialized fields across profiles.

Rust callers use the same registry:

use treeboot_spec::{CommandTemplate, ConformanceProfile, RunOptions, Suite};

let implementation = CommandTemplate::new("/path/to/treeboot");
let report = Suite::current().run(
    &implementation,
    RunOptions::new().with_profile(ConformanceProfile::Full),
)?;
assert!(report.passed());
# Ok::<(), treeboot_spec::SuiteError>(())

Suite execution is serial by default. Call RunOptions::with_concurrency to opt into bounded case-level concurrency; reports retain stable registry order. Progress events from different cases may interleave, but observers still run on the suite thread.

Use Suite::run_observed or Suite::run_with_observer to receive synchronous suite-start, case-start, and case-finish events. Observers can render progress or collect telemetry without coupling the suite to a terminal.

Custom Runner implementations can execute the same cases in another process environment. A complete adapter must expose each temporary fixture filesystem to the candidate and honor native arguments, working directories, environment changes, stdin mode, deadlines, and per-stream output capture limits. A runner must tolerate concurrent run calls when callers opt into suite concurrency. It must also continue draining output after a limit is reached, then return RunnerError::OutputLimitExceeded.

The default local runner captures output through pipes, so terminal-input cases report an explicit capability skip. A custom adapter can provide terminal input for those cases. Installed completion-script cases likewise run only when the adapter reports that generated scripts can reinvoke its candidate from the fixture host.

treeboot-spec does not specify Treeboot's Rust library API and has no dependency on the official treeboot or treeboot-core crates.