1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
//! 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-in [`steps`] and [`assertions`],
//! [`planner`]/[`runner`]/[`execution`], [`store`]/[`cache`], and the
//! `py*` compatibility shims that keep this port close to the Python
//! oracle. It is flat rather than under a `core` module, both because it is
//! the crate's primary surface and because a module named `core` shadows the
//! `core` crate for every path in its scope.
//! - **[`terminal`]** is what was `termproof-terminal`: PTY, tmux and process
//! sessions, plain and attributed screen state, asciicast recording, idle
//! detection and the [`terminal::SessionBackend`] implementations.
//! - **[`evidence`]** is what was `termproof-evidence`: screenshot and video
//! rendering, Markdown reports, visual baselines, diff and upload.
//! - **[`junit`]** is the JUnit XML writer. It was in `termproof-evidence` too,
//! and [`evidence::report`] still re-exports it, but it reads a [`RunResult`]
//! and 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`** — the [`evidence`] module. Off, the crate does not compile
//! `image` or `avt`.
//! - **`junit`** — the [`junit`] module and the `generate_junit` re-exports in
//! [`evidence`]. Off, the crate does not compile `quick-junit`. It does not
//! imply `evidence` and is not implied by it: JUnit is written from a
//! [`RunResult`], so the two are independent in both directions (#34).
//! - **`json-schema`** — [`validation`], [`pyschema`] and the `json_schema`
//! built-in assertion. Off, the crate does not compile `jsonschema`, and
//! `json_schema` is absent from [`assertions::BUILTIN_TYPES`] rather than
//! present and failing. Implies `schema`, which is where the schema it
//! validates against comes from.
//! - **`schema`** — the [`schema`] module and the `JsonSchema` impls derived on
//! [`Recipe`], [`config::VerifierConfig`] and the types they contain. Off,
//! the crate does not compile `schemars`. 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 put `JsonSchema` on the published types themselves
//! rather than in a signature; turning it off is how a consumer on a
//! different `schemars` major stops carrying two.
//! - **`clap`** (off) — [`run_config`]'s `cli` submodule: a `clap::Command`
//! carrying the standard flags for a [`run_config::RunConfig`], and the parse
//! back into one with [`run_config::pick`] applied once rather than per flag.
//! Off, the crate does not compile `clap`. 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.
// There is deliberately no `pub use fancy_regex;` / `jsonschema` / `vt100`
// here. An earlier step in this release added all three, as an escape hatch
// while those crates' types were still in our signatures: a consumer could
// name our copy and stop betting on the resolver. Wrapping the signatures
// removed the thing they were an escape from, and left them as the last way a
// dependency's version could still reach a consumer through us — a re-exported
// crate is public API, so its own breaking changes become ours. See
// "Dependencies in the public API" above (#177).
// Re-exports: config + recipe/schema/validation (RUST-004)
pub use VerifierConfig;
pub use ;
pub use ;
// Re-exports: models/result/store (RUST-010) — models is legacy, result is canonical
// Canonical Recipe is from recipe.rs (serde, plus schemars under `schema`);
// models::Recipe retained as ModelRecipe for back-compat
pub use Recipe as ModelRecipe;
pub use ;
// Canonical RunResult/AssertionResult/StepResult from result.rs (score_from_assertions, BTreeMap artifacts)
pub use ;
pub use ;
// Re-exports: execution/agent (RUST-016/017)
pub use ;
pub use CoreError;
pub use ;
pub use ;
/// Canonical product name used by the CLI and diagnostics.
pub const NAME: &str = "termproof";
/// Canonical crate/product version, inherited from the workspace manifest.
pub const VERSION: &str = env!;
/// Render the canonical `name version` banner used by the CLI greeting.