Skip to main content

provable_contracts/schema/
parser.rs

1use std::path::Path;
2
3use crate::error::ContractError;
4use crate::schema::types::{Contract, ContractKind, KaizenRecord, CONTRACT_TOP_LEVEL_FIELDS};
5
6/// Parse a YAML contract file into a [`Contract`] struct.
7///
8/// This is the entry point for Phase 2 validation. The parser
9/// deserializes the YAML and performs structural checks.
10///
11/// # Errors
12///
13/// Returns [`ContractError::Io`] if the file cannot be read,
14/// or [`ContractError::Yaml`] if the YAML is malformed.
15pub fn parse_contract(path: &Path) -> Result<Contract, ContractError> {
16    let content = std::fs::read_to_string(path)?;
17    parse_contract_str(&content)
18}
19
20/// Files under `contracts/` that are NOT `Contract` documents.
21///
22/// `contracts/binding.yaml` is a `BindingRegistry` (equation → implementing
23/// function), not a contract. It has no `metadata:` block, so parsing it as a
24/// `Contract` fails with ``missing field `metadata` `` — which is exactly how
25/// `cargo test -p aprender-contracts --test validate_contracts` failed 3 of its
26/// 10 tests on `main` while `pv lint contracts/` reported zero errors: the two
27/// walkers disagreed about what a contract file is.
28/// Files under `contracts/` that are NOT contracts, and would fail to parse as
29/// one: the binding registry, and ONT-001 ONT-1's declaration of corpora this
30/// tree does NOT hold (`contracts/external-corpora.yaml`). Adding a file here is
31/// how the corpus keeps ONE definition of "a contract file" — the census, the
32/// linter and the validator all read this list.
33const NON_CONTRACT_FILENAMES: [&str; 4] = [
34    "binding.yaml",
35    "binding.yml",
36    "external-corpora.yaml",
37    // ONT-2b: Σ (`contracts/ontology.yaml`) declares what contracts may SAY; it is not one of them and has
38    // no `metadata:`. Measured before this line existed: adding Σ took `pv lint contracts/` from 1792
39    // contracts / 0 errors to 1793 / 1, i.e. the corpus failed because its own vocabulary was parsed as a
40    // member of it.
41    "ontology.yaml",
42];
43
44/// Is `path` a `.yaml` file the contract schema owns?
45///
46/// The single source of truth for "which files under `contracts/` are
47/// contracts". `pv lint`'s directory walker and the `validate_contracts`
48/// integration test both call it, so neither can drift into walking a file the
49/// other skips. Directory-level exclusions (`kaizen/`, `legacy/`,
50/// `pipelines/`, `publish-manifests/`) are a separate concern and stay with the
51/// recursive walker in `lint::gates`.
52#[must_use]
53pub fn is_contract_yaml(path: &Path) -> bool {
54    if path.extension().and_then(|e| e.to_str()) != Some("yaml") {
55        return false;
56    }
57    let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
58        return false;
59    };
60    !name.starts_with('.') && !NON_CONTRACT_FILENAMES.contains(&name)
61}
62
63/// Parse a YAML contract from a string.
64///
65/// Two passes on purpose. `Contract` is intentionally NOT
66/// `#[serde(deny_unknown_fields)]` — 1224 of the 1726 contracts `pv lint`
67/// walks carry a downstream-owned top-level block (`family:`, `sections:`,
68/// `surface:`, …) and denying them would stop ~71% of the corpus from parsing
69/// in one commit. But serde's tolerance is also what let a top-level `kind:`
70/// (119 contracts) and a misspelled `falsification:` block vanish without a
71/// sound. So the second pass reads the raw mapping and records which top-level
72/// keys serde did not consume, in [`Contract::unknown_top_level_keys`]; the
73/// validator turns the never-legitimate ones into errors (SCHEMA-018 /
74/// SCHEMA-019) and leaves the rest alone.
75///
76/// # Errors
77///
78/// Returns [`ContractError::Yaml`] if the YAML is malformed or does not match
79/// the contract schema.
80pub fn parse_contract_str(yaml: &str) -> Result<Contract, ContractError> {
81    let mut contract: Contract = serde_yaml::from_str(yaml)?;
82    contract.unknown_top_level_keys = unknown_top_level_keys(yaml);
83    contract.kind_declared = kind_is_declared(yaml);
84    contract.strict_yaml_error = strict_yaml_error(yaml);
85    contract.falsification_tests_declared = top_level_key_written(yaml, "falsification_tests");
86    contract.kaizen_record = kaizen_record(yaml, contract.kind())?;
87    Ok(contract)
88}
89
90/// Third pass, run ONLY for `metadata.kind: kaizen`: read the top-level blocks
91/// a kaizen improvement record carries (`contract:`, `kaizen:`, `status:`,
92/// `baseline:`, `target:`, …) that `Contract` deliberately does not model.
93///
94/// Gated on the kind rather than run unconditionally because those key names
95/// are not owned by the kaizen schema: `status:`, `version:` and `invariants:`
96/// appear at top level across the corpus with shapes that would make this
97/// deserialize fail. On a non-kaizen contract that failure would turn a
98/// perfectly good contract into a parse error; scoping the pass means it can
99/// only ever be reached by a document that has declared itself a kaizen record.
100///
101/// When it IS reached, a type error is returned rather than swallowed — a
102/// kaizen record whose `baseline:` is unreadable must be REPORTED, not
103/// silently validated as if it had none.
104fn kaizen_record(yaml: &str, kind: ContractKind) -> Result<Option<KaizenRecord>, ContractError> {
105    if kind != ContractKind::Kaizen {
106        return Ok(None);
107    }
108    Ok(Some(serde_yaml::from_str::<KaizenRecord>(yaml)?))
109}
110
111/// Top-level mapping keys of `yaml` that are not fields of [`Contract`].
112///
113/// Deliberately deserializes into `BTreeMap<String, IgnoredAny>` rather than
114/// `serde_yaml::Value`: `IgnoredAny` drains each value without building it, so
115/// this pass reads ONLY the top-level key names and cannot be derailed by
116/// anything nested. That matters — `contracts/apr-cli-commands-v1.yaml` defines
117/// `subcommands:` twice inside `commands:`, which makes a strict
118/// `serde_yaml::Value` parse fail; capturing keys through `Value` silently
119/// returned "no unknown keys" for that file and its top-level
120/// `kind: CLICommandContract` went unreported. A `BTreeMap` also just
121/// overwrites a duplicate top-level key instead of erroring.
122///
123/// Returns an empty list when the document is not a mapping at all — that case
124/// is already a hard parse error above, so this never masks one.
125fn unknown_top_level_keys(yaml: &str) -> Vec<String> {
126    use serde::de::IgnoredAny;
127    use std::collections::BTreeMap;
128
129    let Ok(map) = serde_yaml::from_str::<BTreeMap<String, IgnoredAny>>(yaml) else {
130        return Vec::new();
131    };
132    map.into_keys()
133        .filter(|k| !CONTRACT_TOP_LEVEL_FIELDS.contains(&k.as_str()))
134        .collect()
135}
136
137/// Was `metadata.kind:` written in the document? (ONT-6b, infra#751)
138///
139/// Read from the raw mapping, not from the deserialized `Contract`: serde has
140/// already replaced an absent `kind` with [`ContractKind::Kernel`] by then, and
141/// that substitution is precisely what this has to observe.
142///
143/// Only `metadata`'s KEYS are built; every other top-level value is drained
144/// into `IgnoredAny` by the derived deserializer. This is not a style choice —
145/// the reasons `unknown_top_level_keys` gives above apply here with teeth.
146/// Deserializing the whole document into a `BTreeMap<String, serde_yaml::Value>`
147/// would FAIL on `contracts/apr-cli-commands-v1.yaml`, which defines
148/// `subcommands:` twice inside `commands:`, and the `false` returned for that
149/// reason would be this function silently reporting "no kind declared" about a
150/// file that declares one — the same shape of wrong answer ONT-6b exists to
151/// remove. Draining unknown top-level values means a duplicate key nested under
152/// one is never built and cannot derail the probe.
153///
154/// A document whose `metadata` is absent or is not a mapping answers `false` —
155/// it declared no kind, which is the truth, and the missing-`metadata` case is
156/// a parse error the caller has already surfaced.
157fn kind_is_declared(yaml: &str) -> bool {
158    use serde::de::IgnoredAny;
159    use std::collections::BTreeMap;
160
161    #[derive(serde::Deserialize)]
162    struct KindProbe {
163        metadata: BTreeMap<String, IgnoredAny>,
164    }
165
166    serde_yaml::from_str::<KindProbe>(yaml).is_ok_and(|probe| probe.metadata.contains_key("kind"))
167}
168
169/// Was the top-level `key:` written in the document? (#5291)
170///
171/// Same probe shape as [`unknown_top_level_keys`], for the same reason: values
172/// are drained into `IgnoredAny`, so a duplicate key nested anywhere below
173/// cannot derail it. A document that is not a mapping answers `false`; that
174/// case is already a hard parse error in the caller.
175fn top_level_key_written(yaml: &str, key: &str) -> bool {
176    use serde::de::IgnoredAny;
177    use std::collections::BTreeMap;
178
179    serde_yaml::from_str::<BTreeMap<String, IgnoredAny>>(yaml)
180        .is_ok_and(|map| map.contains_key(key))
181}
182
183/// The error a STRICT reader gets on YAML the contract schema accepted.
184///
185/// `Contract`'s derived deserializer walks only the fields it knows and skips
186/// the rest, so a document can be well-formed to it and malformed to anyone
187/// else. The one shape this catches today is a duplicate mapping key: YAML
188/// requires keys to be unique, and every consumer that builds a real map (a
189/// `serde_yaml::Value`, `yq`, a Python `dict`) keeps exactly one of them and
190/// throws the other away without a word.
191///
192/// `None` means the document round-trips through a strict reader.
193fn strict_yaml_error(yaml: &str) -> Option<String> {
194    serde_yaml::from_str::<serde_yaml::Value>(yaml)
195        .err()
196        .map(|e| e.to_string())
197}
198
199#[cfg(test)]
200mod tests {
201    use super::*;
202
203    const MINIMAL_CONTRACT: &str = r#"
204metadata:
205  version: "1.0.0"
206  description: "Test contract"
207  references:
208    - "Test paper (2024)"
209equations:
210  test_eq:
211    formula: "f(x) = x + 1"
212proof_obligations: []
213falsification_tests: []
214"#;
215
216    /// ONT-6b: the probe answers about `metadata.kind` and nothing else.
217    ///
218    /// The three cases that decide it, including the one that is a trap: a
219    /// document carrying a DUPLICATE key nested under an unknown top-level
220    /// block. `contracts/apr-cli-commands-v1.yaml` is that shape in the real
221    /// corpus (`subcommands:` appears 20 times under `commands:`), and a probe
222    /// that deserialized the whole document into `serde_yaml::Value` would fail
223    /// on it and report "no kind declared" about a file that declares one.
224    /// `KindProbe` drains unknown top-level values instead of building them, so
225    /// the duplicate is never constructed.
226    #[test]
227    fn kind_is_declared_reads_metadata_and_survives_a_duplicate_nested_key() {
228        assert!(
229            !kind_is_declared(MINIMAL_CONTRACT),
230            "no metadata.kind is written, so none was declared"
231        );
232        let declared = MINIMAL_CONTRACT.replace(
233            "  description: \"Test contract\"",
234            "  description: \"Test contract\"\n  kind: pattern",
235        );
236        assert!(
237            kind_is_declared(&declared),
238            "metadata.kind is written, whatever its value"
239        );
240
241        let with_duplicate =
242            format!("{declared}commands:\n  root:\n    subcommands: [a]\n    subcommands: [b]\n");
243        assert!(
244            serde_yaml::from_str::<std::collections::BTreeMap<String, serde_yaml::Value>>(
245                &with_duplicate
246            )
247            .is_err(),
248            "anti-vacuity: this fixture must be a document a whole-file Value parse REFUSES, \
249             otherwise the next assertion proves nothing"
250        );
251        assert!(
252            kind_is_declared(&with_duplicate),
253            "a duplicate key under an unknown top-level block must not make a declared kind \
254             read as absent"
255        );
256
257        assert!(
258            !kind_is_declared("not: a contract\n"),
259            "a document with no metadata declared no kind"
260        );
261    }
262
263    #[test]
264    fn parse_minimal_contract() {
265        let contract = parse_contract_str(MINIMAL_CONTRACT).unwrap();
266        assert_eq!(contract.metadata.version, "1.0.0");
267        assert_eq!(contract.metadata.description, "Test contract");
268        assert_eq!(contract.equations.len(), 1);
269        assert!(contract.equations.contains_key("test_eq"));
270    }
271
272    #[test]
273    fn parse_contract_with_all_fields() {
274        let yaml = r#"
275metadata:
276  version: "1.0.0"
277  created: "2026-02-18"
278  author: "Test Author"
279  description: "Full contract"
280  references:
281    - "Paper A (2024)"
282    - "Paper B (2025)"
283equations:
284  softmax:
285    formula: "σ(x)_i = exp(x_i - max(x)) / Σ exp(x_j - max(x))"
286    domain: "x ∈ ℝ^n, n ≥ 1"
287    codomain: "σ(x) ∈ (0,1)^n"
288    invariants:
289      - "sum(output) = 1.0"
290      - "output_i > 0"
291proof_obligations:
292  - type: invariant
293    property: "Output sums to 1"
294    formal: "|sum(softmax(x)) - 1.0| < ε"
295    tolerance: 1.0e-6
296    applies_to: all
297  - type: equivalence
298    property: "SIMD matches scalar"
299    tolerance: 8.0
300    applies_to: simd
301kernel_structure:
302  phases:
303    - name: find_max
304      description: "Find max element"
305      invariant: "max >= all elements"
306    - name: exp_subtract
307      description: "Compute exp(x_i - max)"
308      invariant: "all values in (0, 1]"
309simd_dispatch:
310  softmax:
311    scalar: "softmax_scalar"
312    avx2: "softmax_avx2"
313enforcement:
314  normalization:
315    description: "Output sums to 1.0"
316    check: "contract_tests::FALSIFY-SM-001"
317    severity: "ERROR"
318falsification_tests:
319  - id: FALSIFY-SM-001
320    rule: "Normalization"
321    prediction: "sum(output) ≈ 1.0"
322    test: "proptest with random vectors"
323    if_fails: "Missing max-subtraction trick"
324kani_harnesses:
325  - id: KANI-SM-001
326    obligation: SM-INV-001
327    property: "Softmax sums to 1.0"
328    bound: 16
329    strategy: stub_float
330    solver: cadical
331    harness: verify_softmax_normalization
332qa_gate:
333  id: F-SM-001
334  name: "Softmax Contract"
335  checks:
336    - "normalization"
337  pass_criteria: "All falsification tests pass"
338  falsification: "Introduce off-by-one in max reduction"
339"#;
340
341        let contract = parse_contract_str(yaml).unwrap();
342        assert_eq!(contract.metadata.version, "1.0.0");
343        assert_eq!(contract.metadata.references.len(), 2);
344        assert_eq!(contract.equations.len(), 1);
345        assert_eq!(contract.proof_obligations.len(), 2);
346        assert!(contract.kernel_structure.is_some());
347        let ks = contract.kernel_structure.unwrap();
348        assert_eq!(ks.phases.len(), 2);
349        assert_eq!(contract.simd_dispatch.len(), 1);
350        assert_eq!(contract.enforcement.len(), 1);
351        assert_eq!(contract.falsification_tests.len(), 1);
352        assert_eq!(contract.falsification_tests[0].id, "FALSIFY-SM-001");
353        assert_eq!(contract.kani_harnesses.len(), 1);
354        assert_eq!(contract.kani_harnesses[0].bound, Some(16));
355        assert!(contract.qa_gate.is_some());
356    }
357
358    #[test]
359    fn parse_invalid_yaml_returns_error() {
360        let result = parse_contract_str("not: [valid: yaml: {{");
361        assert!(result.is_err());
362    }
363
364    #[test]
365    fn parse_missing_metadata_returns_error() {
366        let yaml = r#"
367equations:
368  test:
369    formula: "f(x) = x"
370"#;
371        let result = parse_contract_str(yaml);
372        assert!(result.is_err());
373    }
374
375    #[test]
376    fn parse_obligation_types() {
377        let yaml = r#"
378metadata:
379  version: "1.0.0"
380  description: "type test"
381equations:
382  f:
383    formula: "f(x) = x"
384proof_obligations:
385  - type: invariant
386    property: "test"
387    if_fails: ""
388  - type: equivalence
389    property: "test"
390  - type: bound
391    property: "test"
392  - type: monotonicity
393    property: "test"
394  - type: idempotency
395    property: "test"
396  - type: linearity
397    property: "test"
398  - type: symmetry
399    property: "test"
400  - type: associativity
401    property: "test"
402  - type: conservation
403    property: "test"
404falsification_tests: []
405"#;
406        let contract = parse_contract_str(yaml).unwrap();
407        assert_eq!(contract.proof_obligations.len(), 9);
408    }
409
410    #[test]
411    fn parse_dbc_obligation_types() {
412        use crate::schema::types::ObligationType;
413
414        let yaml = r#"
415metadata:
416  version: "1.0.0"
417  description: "DbC type test"
418  depends_on: ["parent-v1"]
419equations:
420  f:
421    formula: "f(x) = x"
422proof_obligations:
423  - type: precondition
424    property: "input finite"
425    formal: "isFinite(x)"
426  - type: postcondition
427    property: "output bounded"
428    requires: "PRE-001"
429  - type: frame
430    property: "input unchanged"
431  - type: loop_invariant
432    property: "max tracks true max"
433    applies_to_phase: "find_max"
434  - type: loop_variant
435    property: "remaining decreasing"
436    applies_to_phase: "accumulate"
437  - type: old_state
438    property: "cache grows"
439  - type: subcontract
440    property: "refines parent"
441    parent_contract: "parent-v1"
442falsification_tests: []
443"#;
444        let contract = parse_contract_str(yaml).unwrap();
445        assert_eq!(contract.proof_obligations.len(), 7);
446        assert_eq!(
447            contract.proof_obligations[0].obligation_type,
448            ObligationType::Precondition
449        );
450        assert_eq!(
451            contract.proof_obligations[1].obligation_type,
452            ObligationType::Postcondition
453        );
454        assert_eq!(
455            contract.proof_obligations[1].requires.as_deref(),
456            Some("PRE-001")
457        );
458        assert_eq!(
459            contract.proof_obligations[2].obligation_type,
460            ObligationType::Frame
461        );
462        assert_eq!(
463            contract.proof_obligations[3].obligation_type,
464            ObligationType::LoopInvariant
465        );
466        assert_eq!(
467            contract.proof_obligations[3].applies_to_phase.as_deref(),
468            Some("find_max")
469        );
470        assert_eq!(
471            contract.proof_obligations[4].obligation_type,
472            ObligationType::LoopVariant
473        );
474        assert_eq!(
475            contract.proof_obligations[5].obligation_type,
476            ObligationType::OldState
477        );
478        assert_eq!(
479            contract.proof_obligations[6].obligation_type,
480            ObligationType::Subcontract
481        );
482        assert_eq!(
483            contract.proof_obligations[6].parent_contract.as_deref(),
484            Some("parent-v1")
485        );
486    }
487
488    #[test]
489    fn parse_contract_with_kind_model_family() {
490        use crate::schema::types::ContractKind;
491
492        // A realistic aprender model-family YAML: metadata + custom
493        // top-level fields. No equations, no proof obligations — should
494        // parse and validate cleanly as kind: model-family.
495        let yaml = r#"
496metadata:
497  version: "1.0.0"
498  description: "Google BERT architecture family metadata"
499  kind: model-family
500  references:
501    - "https://arxiv.org/abs/1810.04805"
502    - "https://huggingface.co/google-bert"
503# Custom top-level fields ignored by the kernel schema,
504# consumed by the downstream crate that owns the file.
505family: bert
506display_name: "Google BERT"
507vendor: Google
508architectures:
509  - BertModel
510  - BertForMaskedLM
511size_variants:
512  base:
513    parameters: "110M"
514    hidden_dim: 768
515"#;
516        let contract = parse_contract_str(yaml).unwrap();
517        assert_eq!(contract.kind(), ContractKind::ModelFamily);
518        assert!(!contract.requires_proofs());
519        assert!(!contract.is_registry());
520        // Validates cleanly — no kernel-specific checks fire.
521        let violations = crate::schema::validate_contract(&contract);
522        let errors: Vec<_> = violations
523            .iter()
524            .filter(|v| v.severity == crate::error::Severity::Error)
525            .collect();
526        assert!(
527            errors.is_empty(),
528            "model-family YAML should validate with no errors, got: {errors:?}",
529        );
530    }
531
532    #[test]
533    fn parse_contract_defaults_to_kernel_kind() {
534        use crate::schema::types::ContractKind;
535
536        let contract = parse_contract_str(MINIMAL_CONTRACT).unwrap();
537        assert_eq!(contract.kind(), ContractKind::Kernel);
538        assert!(contract.requires_proofs());
539    }
540
541    #[test]
542    fn parse_kani_strategies() {
543        use crate::schema::types::KaniStrategy;
544
545        let yaml = r#"
546metadata:
547  version: "1.0.0"
548  description: "kani test"
549equations:
550  f:
551    formula: "f(x) = x"
552kani_harnesses:
553  - id: K1
554    obligation: OBL-1
555    strategy: exhaustive
556  - id: K2
557    obligation: OBL-2
558    strategy: stub_float
559  - id: K3
560    obligation: OBL-3
561    strategy: compositional
562falsification_tests: []
563"#;
564        let contract = parse_contract_str(yaml).unwrap();
565        assert_eq!(contract.kani_harnesses.len(), 3);
566        assert_eq!(
567            contract.kani_harnesses[0].strategy,
568            Some(KaniStrategy::Exhaustive)
569        );
570        assert_eq!(
571            contract.kani_harnesses[1].strategy,
572            Some(KaniStrategy::StubFloat)
573        );
574        assert_eq!(
575            contract.kani_harnesses[2].strategy,
576            Some(KaniStrategy::Compositional)
577        );
578    }
579}