Add source-backed numerical QA projects

.github/pull_request_template.md

@@ -8,11 +8,11 @@
 - [ ] I performed a human privacy review and found no private project names, paths, source text, inputs, or results.
 - [ ] I confirmed that all included material may be redistributed.
 - [ ] I classified each expectation as reference-backed, stability-baseline, or health-only.
-- [ ] I independently verified reference-backed assertions without relying solely on Graphcal output.
+- [ ] I mapped every reference-backed expected value directly to a value reported by a reliable public source.
 - [ ] I recorded producing revisions, comparison rules, and repeated-run determinism for stability baselines.
 - [ ] I recorded candidate-generation and human-review provenance.
 - [ ] I ran `uv run validate-corpus` and `uv run -m pytest`.
 
 ## Evidence
 
-<!-- Link supporting citations or independent calculations for corpus-project changes. For documentation, policy, or tooling changes where these do not apply, briefly state why. -->
+<!-- Link source-to-assertion mappings for reference-backed cases and generation records for stability baselines. For documentation, policy, or tooling changes where these do not apply, briefly state why. -->

CONTRIBUTING.md

@@ -1,14 +1,16 @@
 # Contributing to the Graphcal QA Corpus
 
-Contributions are welcome when they add independently traceable correctness evidence or original, realistic Graphcal complexity without exposing private material.
+Contributions are welcome when they add directly source-traceable correctness evidence or original, realistic Graphcal complexity without exposing private material.
 
 ## Candidate requirements
 
 A candidate must be either:
 
-1. a **source-backed reproduction** reimplemented from a reliable, redistributable published or well-known analysis; or
+1. a **source-backed reproduction** for which a reliable, redistributable public source supplies both the reproduced inputs and the expected output values; or
 2. an **original synthetic complexity project** created without copying or transforming a private user project.
 
+A project that applies a published equation to original or adapted inputs is original synthetic unless the source also reports the corresponding output. Such a case may cite the equation, but its Graphcal-produced output must be classified as a stability baseline.
+
 Do not submit a candidate merely because the current Graphcal implementation accepts it. Each project must answer a stated engineering question, exercise a documented feature or domain gap, and use deterministic checked-in inputs.
 
 Initial corpus projects must not require network access, private or unpinned dependencies, native or WASM plugins, current time, randomness, or project-provided executable hooks.
@@ -19,7 +21,7 @@ Initial corpus projects must not require network access, private or unpinned dep
 2. **Perform privacy review.** Apply [PRIVACY.md](PRIVACY.md) to names, paths, comments, source, inputs, expected outputs, references, and history. Agent generation and automated scanning do not replace human inspection.
 3. **Check structure.** Put the project at `projects/<project-id>/`, add `graphcal.toml`, declare the project and all QA cases in `corpus.toml`, and run `uv run validate-corpus`.
 4. **Classify every expectation.** Use `reference-backed`, `stability-baseline`, or `health-only` according to the evidence described below. Do not present stability output as a correctness oracle.
-5. **Verify evidence.** Independently check reference-backed assertions. Capture provenance and repeated-run determinism for stability baselines.
+5. **Verify evidence.** Trace every reference-backed expected value to the exact public source location that reports it. Capture producing revisions and repeated-run determinism for stability baselines.
 6. **Submit a pull request.** Explain the project's origin, purpose, coverage, evidence, licensing, and privacy review.
 7. **Obtain human review.** At least one human other than the latest contributor must review the structural, technical, provenance, expectation, and privacy evidence before merge.
 
@@ -29,20 +31,20 @@ Coding-agent output remains an untrusted candidate until this process is complet
 
 ### Reference-backed
 
-A reference-backed assertion must be supported by at least one of:
+A reference-backed assertion requires a reliable public source that reports both:
+
+- the inputs and assumptions reproduced by the case; and
+- the expected numerical or scalar output asserted by the manifest.
 
-- an analytical calculation;
-- a separately implemented reference calculation;
-- a reliable published example with compatible assumptions; or
-- manual verification by a domain expert.
+The evidence must map each JSON Pointer and expected value to an exact source location such as a worked example, report table, published test vector, or source-maintained reference output. Assert only the precision the source reports. Document any source-prescribed rounding and any lossless unit or representation conversion.
 
-Do not bless a value solely because `graphcal eval` produced it. Document formulas, assumptions, constants, sign and unit conventions, copied input data, adaptations, tolerances, and the independent result in `reference/calculation.md` or an equivalent non-executable record.
+An analytical calculation, separately implemented calculation, domain-expert review, or agreement with `graphcal eval` may corroborate a published value, but none is sufficient as the sole oracle. If a source publishes an equation but no output for the case's inputs, classify the case as `stability-baseline`, not `reference-backed`.
 
-For a published source, include enough bibliographic detail to identify the exact example: author or organization, title, edition or version, page or section, DOI or stable URL when available, and access date where useful. Reimplement the analysis; do not copy copyrighted prose, figures, or substantial tables. Record the license and origin of any included third-party data.
+Include enough bibliographic detail to identify the exact example: author or organization, title, edition or version, page, table, equation, or section, DOI or stable URL when available, and access date where useful. Reimplement the analysis; do not copy copyrighted prose, figures, or substantial tables. Record the license and origin of any included third-party data.
 
 ### Stability baseline
 
-A stability baseline detects behavioral drift and does not establish engineering correctness. Record:
+A stability baseline detects behavioral drift and does not establish engineering correctness. Use it for original synthetic cases and source-informed cases whose references provide equations or methods but no expected values for the reproduced inputs. Record:
 
 - the exact Graphcal commit that produced it;
 - the corpus candidate commit and case inputs;
@@ -78,7 +80,7 @@ A project pull request must confirm that:
 - [ ] all included source material and data may be redistributed;
 - [ ] the project is explicitly declared and structural validation passes;
 - [ ] every expectation has the correct evidence class;
-- [ ] every reference-backed assertion was independently verified;
+- [ ] every reference-backed assertion maps directly to a value reported by a reliable public source;
 - [ ] every stability baseline records producing revisions, comparison rules, and repeated-run determinism;
 - [ ] generation and human review provenance are documented; and
 - [ ] the project requires no network, plugin, randomness, clock, private dependency, or executable project hook.

README.md

@@ -6,16 +6,16 @@
 
 Every project has one of two origins:
 
-- **Source-backed reproduction:** a reimplementation of a reliable published or well-known engineering analysis. Independently verified assertions may make correctness claims. Citations, assumptions, adaptations, and redistributable inputs must be recorded.
-- **Original synthetic complexity:** a new, imaginary engineering project designed to exercise realistic combinations of Graphcal features. Graphcal-produced expected output is a stability baseline, not proof that the engineering result is correct.
+- **Source-backed reproduction:** a reliable public source supplies both the reproduced inputs and the correct output values. Reference-backed assertions must trace directly to values reported by that source, including any explicit source rounding or documented unit conversion.
+- **Original synthetic complexity:** a new scenario designed to exercise realistic combinations of Graphcal features. This includes source-informed models that reuse a published equation with original or adapted inputs when the source does not report the corresponding outputs. Graphcal-produced expected output is a stability baseline, not proof that the engineering result is correct.
 
-A project may combine independently verified reference assertions with stability baselines for other outputs. Each expectation must state which class it belongs to.
+A published equation alone does not make a case source-backed. A local analytical calculation, separate implementation, or domain review may corroborate a source value, but it cannot be the sole oracle for a reference-backed assertion. Each case has one expectation class; a project with multiple entrypoints may use different classes only when each case independently satisfies its evidence contract.
 
 Private project names, paths, source text, inputs, outputs, and results are prohibited, even when edited or anonymized. See [PRIVACY.md](PRIVACY.md).
 
 ## Trust model
 
-Coding agents and other generators may prepare **candidates**, but generated content is untrusted. A human promotes a candidate only after reviewing its privacy, structure, provenance, expectation classification, independent calculations, and determinism evidence. The complete process is in [CONTRIBUTING.md](CONTRIBUTING.md).
+Coding agents and other generators may prepare **candidates**, but generated content is untrusted. A human promotes a candidate only after reviewing its privacy, structure, provenance, expectation classification, source-to-assertion traceability, and determinism evidence. The complete process is in [CONTRIBUTING.md](CONTRIBUTING.md).
 
 Corpus projects are data-only and must not contain executable test hooks. This repository provides an opt-in local runner for a caller-supplied Graphcal executable; it never invokes project-provided programs. Repository CI performs structural validation only and does not run Graphcal.
 

corpus.toml

@@ -55,3 +55,235 @@ evidence = "reference/calculation.md"
 pointer = "/node/mass_ratio/si_value"
 expected = 10.0
 absolute_tolerance = 1.0
+[[projects]]
+id = "nasa-lift-sweep"
+path = "projects/nasa-lift-sweep"
+status = "active"
+domain = "aerodynamics"
+origin = "original-synthetic"
+purpose = "Detect semantic drift in a source-informed lift sweep with original inputs."
+
+[[projects.cases]]
+id = "three-flight-points"
+entry = "src/nasa_lift_sweep/main.gcl"
+
+[projects.cases.expectation]
+kind = "stability-baseline"
+expected = "expected/three-flight-points.json"
+evidence = "reference/baseline.md"
+
+[projects.cases.expectation.comparison]
+mode = "semantic-json"
+tolerances = []
+
+[[projects]]
+id = "pvwatts-hourly-dc-energy"
+path = "projects/pvwatts-hourly-dc-energy"
+status = "active"
+domain = "solar-energy"
+origin = "original-synthetic"
+purpose = "Detect semantic drift in a source-informed PVWatts profile with original inputs."
+
+[[projects.cases]]
+id = "four-hour-profile"
+entry = "src/pvwatts_hourly_dc_energy/main.gcl"
+
+[projects.cases.expectation]
+kind = "stability-baseline"
+expected = "expected/four-hour-profile.json"
+evidence = "reference/baseline.md"
+
+[projects.cases.expectation.comparison]
+mode = "semantic-json"
+tolerances = []
+
+[[projects]]
+id = "fao56-reference-evapotranspiration"
+path = "projects/fao56-reference-evapotranspiration"
+status = "active"
+domain = "agricultural-water-management"
+origin = "source-backed"
+purpose = "Reproduce the FAO-56 Example 18 daily reference evapotranspiration result."
+
+[[projects.cases]]
+id = "example-18"
+entry = "src/fao56_reference_evapotranspiration/main.gcl"
+
+[projects.cases.expectation]
+kind = "reference-backed"
+evidence = "reference/calculation.md"
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_radiation_component/display_value"
+expected = 2.81
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_aerodynamic_component/display_value"
+expected = 1.07
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_equation_reference_evapotranspiration/display_value"
+expected = 3.88
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_reference_evapotranspiration/display_value"
+expected = 3.9
+absolute_tolerance = 1e-12
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_reference_evapotranspiration/unit"
+expected = "mm_per_day"
+
+[[projects]]
+id = "nws-heat-index-examples"
+path = "projects/nws-heat-index-examples"
+status = "active"
+domain = "weather-safety"
+origin = "source-backed"
+purpose = "Reproduce two heat-index values explicitly reported by the National Weather Service."
+
+[[projects.cases]]
+id = "published-examples"
+entry = "src/nws_heat_index_examples/main.gcl"
+
+[projects.cases.expectation]
+kind = "reference-backed"
+evidence = "reference/calculation.md"
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/humid_example_heat_index_fahrenheit_value/si_value"
+expected = 124.0
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/dry_example_heat_index_fahrenheit_value/si_value"
+expected = 96.0
+
+[[projects]]
+id = "epa-chp-savings-example"
+path = "projects/epa-chp-savings-example"
+status = "active"
+domain = "energy-and-emissions"
+origin = "source-backed"
+purpose = "Reproduce fuel and carbon-dioxide savings reported in a U.S. EPA CHP example."
+
+[[projects.cases]]
+id = "appendix-a"
+entry = "src/epa_chp_savings_example/main.gcl"
+
+[projects.cases.expectation]
+kind = "reference-backed"
+evidence = "reference/calculation.md"
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/total_fuel_savings/display_value"
+expected = 115546.0
+absolute_tolerance = 1e-6
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/total_fuel_savings/unit"
+expected = "MMBtu"
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_fuel_savings_percent/si_value"
+expected = 21.0
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/total_co2_savings/display_value"
+expected = 18065.0
+absolute_tolerance = 1e-9
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/total_co2_savings/unit"
+expected = "short_ton"
+
+[[projects]]
+id = "nws-wind-chill-example"
+path = "projects/nws-wind-chill-example"
+status = "active"
+domain = "weather-safety"
+origin = "source-backed"
+purpose = "Reproduce a wind-chill value explicitly reported by the National Weather Service."
+
+[[projects.cases]]
+id = "zero-fifteen"
+entry = "src/nws_wind_chill_example/main.gcl"
+
+[projects.cases.expectation]
+kind = "reference-backed"
+evidence = "reference/calculation.md"
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_wind_chill_fahrenheit_value/si_value"
+expected = -19.0
+
+[[projects]]
+id = "osha-noise-examples"
+path = "projects/osha-noise-examples"
+status = "active"
+domain = "occupational-safety"
+origin = "source-backed"
+purpose = "Reproduce free-field sound-level and noise-dose results reported by OSHA."
+
+[[projects.cases]]
+id = "manual-examples"
+entry = "src/osha_noise_examples/main.gcl"
+
+[projects.cases.expectation]
+kind = "reference-backed"
+evidence = "reference/calculation.md"
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_target_sound_level_dba_value/si_value"
+expected = 116.0
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_eight_hour_twa_dba_value/si_value"
+expected = 94.4
+absolute_tolerance = 1e-12
+
+[[projects]]
+id = "epa-cutback-asphalt-voc-example"
+path = "projects/epa-cutback-asphalt-voc-example"
+status = "active"
+domain = "air-emissions"
+origin = "source-backed"
+purpose = "Reproduce diluent and VOC values reported in an EPA cutback-asphalt example."
+
+[[projects.cases]]
+id = "ap-42-example"
+entry = "src/epa_cutback_asphalt_voc_example/main.gcl"
+
+[projects.cases.expectation]
+kind = "reference-backed"
+evidence = "reference/calculation.md"
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_diluent_volume/display_value"
+expected = 4900.0
+absolute_tolerance = 1e-9
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_diluent_volume/unit"
+expected = "L"
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_diluent_mass/display_value"
+expected = 3400.0
+absolute_tolerance = 1e-9
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_diluent_mass/unit"
+expected = "kg"
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_voc_mass/display_value"
+expected = 3200.0
+absolute_tolerance = 1e-9
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_voc_mass/unit"
+expected = "kg"
+
+[[projects.cases.expectation.assertions]]
+pointer = "/node/reported_voc_percent_by_mass/si_value"
+expected = 32.0

projects/epa-chp-savings-example/README.md

@@ -0,0 +1,5 @@
+# EPA combined-heat-and-power savings example
+
+This source-backed reproduction asks: **Do the U.S. EPA's published combined-heat-and-power fuel and carbon-dioxide savings equations reproduce the results in its CEESC worked example?**
+
+The project uses the rounded annual fuel-use and CO₂ values printed in Appendix A of the EPA methodology and evaluates the report's total-savings equations. The manifest checks only values explicitly reported by EPA. Source locations, unit adaptations, and assertion mappings are documented in [`reference/calculation.md`](reference/calculation.md).

projects/epa-chp-savings-example/graphcal.toml

@@ -0,0 +1,2 @@
+[package]
+name = "epa_chp_savings_example"