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
//! JSON Schema generation for recipes (Draft 2020-12).
//!
//! Uses `schemars` as the source-to-schema generator. The generated schema is
//! Draft 2020-12 (spec §5.3).
//!
//! The crate's own generated schema is pinned by a checked-in parsed-JSON
//! snapshot (`crates/termproof/tests/schema_snapshot.rs` + its snapshot
//! file). The snapshot is compared as `serde_json::Value` trees, so object
//! key order is ignored but every structural difference — keywords, numbers,
//! array order, `$ref` targets — fails the test. Re-blessing is deliberate
//! and non-default: `TERM_PROOF_BLESS_SCHEMA=1 cargo test -p termproof
//! --test schema_snapshot` (see `docs/engineering-baseline.md` §10).
//!
//! The snapshot proves only that this crate's own output does not drift; it
//! does not establish agreement with the canonical schema. That schema is
//! owned by the Python implementation; this crate carries its own copy at
//! `resources/recipe-schema-v1.json`, embedded by [`CANONICAL_SCHEMA_JSON`],
//! and CI holds that copy byte-identical to the Python package's
//! (`python/scripts/check_schema_copies.py`). Comparing the two *schemas* —
//! generated against canonical — is still parity-gate work; having the file
//! reachable is the precondition, not the gate.
use ;
use crateRecipe;
/// Generate the Draft 2020-12 JSON Schema for [`Recipe`].
///
/// The schema includes `additionalProperties: true` at the recipe, command,
/// step, and assertion levels via the flattened extension maps.
/// The canonical recipe schema, embedded from this crate's own copy.
///
/// The schema is owned by the Python implementation, but a crate that has to
/// look outside itself to find it does not have it: a registry checkout has no
/// repository above it, so the previous manifest-relative
/// `../../../python/docs/recipe-schema-v1.json` resolved for this repository
/// and for nobody else (#174). The crate now carries the file, and
/// `python/scripts/check_schema_copies.py` holds it byte-identical to
/// `python/termproof/_resources/recipe-schema-v1.json` in CI.
///
/// This is the text, exactly as shipped. [`load_canonical_schema`] parses it.
pub const CANONICAL_SCHEMA_JSON: &str = include_str!;
/// Load the canonical recipe schema.
///
/// This is the seam the parity gate will compare `generate_recipe_schema()`
/// against. Reaching the schema is the precondition; agreeing with it is the
/// gate, and that is still open work.
///
/// Reads **only** [`CANONICAL_SCHEMA_JSON`] — no filesystem access, so no
/// working directory and no path outside this crate can influence the answer.
/// That is a correctness property, not a tidiness one. This function once had
/// a `docs/recipe-schema-v1.json` cwd fallback, and in a published crate —
/// where the manifest-relative path landed in the registry checkout and missed
/// — it would have read whatever file of that name happened to sit in the
/// consumer's working directory and returned it as the canonical TermProof
/// schema. A wrong schema presented as canonical is worse than no schema.
///
/// The `Option` is vestigial: the schema is embedded at compile time and
/// `canonical_schema_is_the_recipe_schema` below holds it to being valid JSON,
/// so the result is always `Some`. `serde_json::Value` is the honest return
/// type and the right shape for the next minor bump. It is kept as-is here by
/// choice, not by constraint: narrowing it breaks every caller that matches on
/// the result, which is a minor bump under the pre-1.0 convention
/// (`docs/publishing.md`), and a packaging fix is the wrong change to carry
/// one.
///
/// Do not read the green `cargo semver-checks` gate as agreement. It was
/// measured: narrowing this return type passes it. (Making the function
/// private fails, so the gate is wired — it just has no lint for this.) The
/// compatibility argument above is the whole reason; the tooling is not
/// enforcing it.