Expand description
TermProof: evidence-first verification for TUI and terminal applications.
§Layout
This crate was merged from three (termproof-core, termproof-terminal,
termproof-evidence) before any of them was published, so the shape below
is the only one that has ever existed on crates.io.
- The crate root is what was
termproof-core: the recipe model, config, schema, validation, the built-instepsandassertions,planner/runner/execution,store/cache, and thepy*compatibility shims that keep this port close to the Python oracle. It is flat rather than under acoremodule, both because it is the crate’s primary surface and because a module namedcoreshadows thecorecrate for every path in its scope. terminalis what wastermproof-terminal: PTY, tmux and process sessions, plain and attributed screen state, asciicast recording, idle detection and theterminal::SessionBackendimplementations.evidenceis what wastermproof-evidence: screenshot and video rendering, Markdown reports, visual baselines, diff and upload.junitis the JUnit XML writer. It was intermproof-evidencetoo, andevidence::reportstill re-exports it, but it reads aRunResultand renders nothing, so #34 moved it out to where it can be compiled without the renderers.
The two nested modules keep their own re-exports rather than flattening
into the root. error is defined by both the root and terminal, so
nesting is what keeps crate::error and terminal::error apart; the
same nesting keeps crate::result clear of evidence::report, and
keeps the reader’s sense of which layer a name comes from.
Original module notes: models, config, schema, registries, planning, orchestration and execution (RUST-004 + RUST-010 + RUST-016); PTY/process ownership, terminal screen, cast recording, idle and session backends (RUST-005/006 + RUST-012 + RUST-016); and the evidence pipeline.
§Features
The first four are on by default, so a consumer that does not name features
gets the crate as it has always been published. clap is the exception: it
is off by default, so --all-features and default are no longer the same
set.
evidence— theevidencemodule. Off, the crate does not compileimageoravt.junit— thejunitmodule and thegenerate_junitre-exports inevidence. Off, the crate does not compilequick-junit. It does not implyevidenceand is not implied by it: JUnit is written from aRunResult, so the two are independent in both directions (#34).json-schema—validation,pyschemaand thejson_schemabuilt-in assertion. Off, the crate does not compilejsonschema, andjson_schemais absent fromassertions::BUILTIN_TYPESrather than present and failing. Impliesschema, which is where the schema it validates against comes from.schema— theschemamodule and theJsonSchemaimpls derived onRecipe,config::VerifierConfigand the types they contain. Off, the crate does not compileschemars. It is the only dependency left in the public API (below), and the only one that could not be wrapped out of it, because the derives putJsonSchemaon the published types themselves rather than in a signature; turning it off is how a consumer on a differentschemarsmajor stops carrying two.clap(off) —run_config’sclisubmodule: aclap::Commandcarrying the standard flags for arun_config::RunConfig, and the parse back into one withrun_config::pickapplied once rather than per flag. Off, the crate does not compileclap. It is the only default-off feature of the published API, and for the mirror image of the other four’s reason: they subtract from a shape that was already published, so default-on is what keeps turning one off from being a break; this adds a shape that never was, so default-off is what keeps it from being a change (#197)._test-harness(off) — not part of the published API. It exists for this repository’s own conformance tests, adds no module and no dependency, and carries no stability guarantee; do not enable it.
terminal has no feature of its own: the crate root is built on it, and
every build drives a terminal, so there is nothing to save.
§Dependencies in the public API
A third-party type in a public signature makes that dependency’s version requirement a source-compatibility surface, and not just a question of how many copies the graph carries: two copies of a crate are two unrelated types, so a consumer that names one compiles only when its copy is the copy cargo handed us. Cargo resolves a requirement to the top of its range, so the window of versions a consumer can unify with is one version wide however the range is written — widening it moves the window rather than enlarging it (#177).
A signature is not the only door. A re-exported crate is public API too —
termproof::dep::Type names the same type as dep::Type and carries the
same requirement — and so is anything a public trait impl renders, since a
derived Debug over a private field publishes that field’s formatting.
0.4.0 closed all three:
| Door | Was | Now |
|---|---|---|
| return type | pyregex::compile gave a fancy_regex::Regex | pyregex::PyRegex, with pyregex::PyCaptures and pyregex::PyMatch so reading a match does not re-leak |
| return type | pyschema::compile gave a jsonschema::Validator | pyschema::PySchema |
| argument | terminal::attributed::from_vt100 took a vt100::Screen | crate-internal. Nothing public accepts a caller-built vt100 value; terminal::screen::TerminalScreen takes bytes and owns its own parser |
| re-export | pub use fancy_regex, jsonschema, vt100 | removed |
| trait impl | PyRegex’s derived Debug rendered the engine | written out, and does not format it |
schemars is the one that could not be closed: the JsonSchema derives sit
on Recipe and the types it holds, so the trait is on the published types
themselves rather than in a signature there is a return value to change.
Turning the schema feature off is the only way out of carrying two copies,
which is why that feature exists.
What this does and does not claim. It claims that the declared
requirement on these crates is no longer a source-compatibility surface: a
consumer can depend on any version of fancy-regex it likes, and ours is an
implementation detail of the graph. It does not claim the engine is
interchangeable — a backtracking engine’s accepted language moves between
releases, and (?<=a+)b is rejected at 0.16 and accepted at 0.19 — which is
why the requirement is pinned to one minor and the differential harnesses
are run against it rather than assumed.
serde, serde_json and serde_yaml do appear in public signatures and
are deliberately left alone: they are 1.x, so cargo unifies every consumer
onto one copy and the hazard cannot arise.
Re-exports§
pub use config::VerifierConfig;pub use recipe::Assertion;pub use recipe::CommandSpec as RecipeCommandSpec;pub use recipe::Recipe;pub use recipe::RecipeMeta;pub use recipe::Step;pub use recipe::RECIPE_VERSION;pub use validation::has_errors;pub use validation::Severity;pub use validation::ValidationIssue;pub use models::Recipe as ModelRecipe;pub use models::AssertionResult as ModelAssertionResult;pub use models::CommandSpec as ModelCommandSpec;pub use models::RunResult as ModelRunResult;pub use models::StepResult as ModelStepResult;pub use result::AssertionResult;pub use result::RunResult;pub use result::StepResult;pub use store::atomic_write;pub use store::atomic_write_text;pub use store::ensure_within_base;pub use store::new_run_dir;pub use store::sanitize_component;pub use agent::build_agent_prompt;pub use agent::parse_agent_output;pub use agent::ParsedAgentOutput;pub use agent::MAX_AGENT_OUTPUT_BYTES;pub use agent::MAX_PROMPT_CONTEXT_CHARS;pub use error::CoreError;pub use execution::AgentDrivenMode;pub use execution::ExecutionContext;pub use execution::ExecutionError;pub use execution::ExecutionMode;pub use execution::ExecutionResult;pub use execution::ScriptedProcessMode;pub use execution::ScriptedPtyMode;pub use runner::LoadedRecipe;pub use runner::Runner;
Modules§
- agent
- Agent-driven execution: prompt building and bounded JSON parsing.
- assertions
- The eight built-in assertions (spec 003).
- before_
after - What changed between two runs of the same suite.
- build_
info - Provenance for the binary under test.
- cache
- Run cache — content-addressed by recipe file hash + run options.
- config
- Typed configuration with cascading precedence and extension preservation.
- error
- Typed internal errors for the crate root.
- evidence
- Evidence pipeline: rendering, reports, video, baselines, diff, and cache.
- execution
- ExecutionContext and ExecutionMode public traits (RUST-016).
- junit
- JUnit XML reports — one
<testcase>perRunResult. - models
- Canonical data models — Recipe, results, and related types.
- parity
- Compare two verification runs and report where they disagree.
- planner
- Parallel planner — deterministic ordering with bounded concurrency.
- pypath
pathlib.PurePosixPath’s lexical joining and rendering.- pyregex
- Python 3
redialect forwait_for_regex. - pyrepr
- One Python
reprformatter, shared by every diagnostic. - pyschema
- JSON Schema validation for the
json_schemaassertion. - recipe
- Typed recipe models with flattened extension maps and legacy loading.
- result
- Canonical result model — mirrors
termproof/models.py. - run_
config - A run described by a file rather than by a command line.
- runner
- The concrete
ExecutionContext— what actually runs a recipe. - schema
- JSON Schema generation for recipes (Draft 2020-12).
- selection
- Choosing which recipes to run for a set of changed files.
- steps
- Seven built-in steps with corpus parity, ported to the
InMemorySession-styleSessiontrait. - store
- Canonical artifact storage.
- terminal
- Terminal layer: PTY/process ownership, terminal screen, cast recording, idle, and session backends (RUST-005/006 + RUST-012 + RUST-016).
- validation
- Validation of recipe values before execution.
- vocabulary
- Screen predicates for asserting on terminal output.
Constants§
- NAME
- Canonical product name used by the CLI and diagnostics.
- VERSION
- Canonical crate/product version, inherited from the workspace manifest.
Functions§
- banner
- Render the canonical
name versionbanner used by the CLI greeting.