Preserve evidence context and uncertainty at scalar model boundaries

README.md

@@ -187,7 +187,7 @@ research tracks, and how to publish work under [`auto-research/`](auto-research/
 
 - **Rohan Arun** ([@rohanarun](https://github.com/rohanarun)) — creator and maintainer; direction and design.
 - **Claude** (Anthropic) — implemented and validated the engines under the above direction, in pair with the maintainer.
-- **OpenAI Codex** — graph interface contracts, clearance reference validation, and conserved reaction/intervention experiments, under the direction of [@ahrazzle](https://github.com/ahrazzle).
+- **OpenAI Codex** — graph interface contracts, clearance reference validation, conserved reaction/intervention experiments, and explicit evidence bindings, under the direction of [@ahrazzle](https://github.com/ahrazzle).
 - **Claude** (Anthropic), Foundation-0 fork — SBML import with exact conservation and positive-mass consistency invariants.
 
 New contributors (human or agent): add yourself here in your pull request. See

auto-research/2026-11-06-E-evidence-bindings/report.md

@@ -0,0 +1,94 @@
+# Explicit evidence bindings for nominal scalar experiments
+
+- **Track:** E, reusable graph/model interfaces
+- **Author:** gpt-forge (OpenAI Codex, Astra), under @ahrazzle's direction
+- **Date:** 2026-11-06
+- **Branch:** `research/evidence-bindings-20261106`
+- **Code:** `vh/graph/evidence.py`, `scripts/validate_evidence_bindings.py`, `tests/test_evidence_bindings.py`
+
+## Question
+
+Can a scalar experiment retain the evidence's complete context, source locator,
+limits, and uncertainty while refusing unsupported inputs before model execution?
+Can the same path perform an independently checkable positive synthetic example?
+
+## Method
+
+An opt-in immutable evidence record binds a fully specified Quantity to a
+PortSpec. Recorded estimates and explicitly enabled synthetic fixtures can bind;
+conjectures, unresolved conflicts and missing values cannot. Every supplied
+quantity/unit/basis/context must match exactly. No conversions, semantic aliases,
+parameter inference or evidence joins are implemented. The model registry checks
+its own contract again before dispatch. Structured input audit records travel
+through the registry's existing provenance lineage.
+
+Uncertainty descriptions and optional paired endpoints are preserved. They are
+not sampled or propagated. Outputs are nominal values; no confidence or
+prediction interval is claimed. Synthetic fixtures remain artificial. No
+parameters were fitted and no biological observations were used as a referee.
+
+## Validation
+
+The independent mathematical authority is the exact rational identity relating
+elimination rate, plasma concentration and clearance. Three synthetic cases use
+rate/concentration pairs (3, 1/2), (7, 1/4), and (9, 3/4) in mg/h and mg/L.
+The executable floating-point model produces 6, 28 and 12 L/h respectively.
+
+| Check | Result | Authority | Error / tolerance |
+| --- | --- | --- | --- |
+| Three nominal clearances | 6, 28, 12 L/h | Exact rational rate / concentration | Maximum 0 L/h; tolerance 1e-12 L/h |
+| Missing kinetic inputs | Four refused | Checked-in ledger P015, P016, P019, P020 | All four lack estimates; software consistency check only |
+| Interface tests | 33 new passing cases | Explicit boundary examples and exact arithmetic | No statistical accuracy claim |
+
+The arithmetic error has no statistical error bar: these are fixed synthetic
+fixtures, not sampled observations. Source uncertainty remains attached to the
+inputs. Tests also check refusal before callback execution, incompatible
+contexts/units/bases, immutable context snapshots, complete audit retention,
+explicit synthetic permission, and inability to weaken registered contracts.
+
+The CLI output in `results.json` pins the exact ledger bytes with SHA-256 and
+preserves the full selected source rows. Those rows have not been re-verified
+against literature in this contribution. The result is a reproducible missing
+input finding, not an independent scientific validation of their content.
+
+## Limits
+
+A caller can mislabel an input or omit a relevant context field. This interface
+cannot discover that mistake or certify scientific adequacy. It is opt-in and
+does not prevent use of the underlying registry. CI/IQR endpoints are preserved
+metadata, not hard bounds; only nominal values are checked against port bounds.
+No output uncertainty or probability distribution is produced. Asma's qualitative
+presence, presentation, recognition and injury assertions remain domain-owned;
+they cannot be coerced to scalars through this interface.
+
+The four ovarian requirements are necessary examples, not a sufficient model
+specification. A future non-null ledger row still needs reviewed explicit semantic
+binding; the readiness script deliberately never authorizes execution. There is
+no patient simulation, clinical inference, data acquisition, or treatment advice.
+Independent scientific review and held-out biological outcomes remain absent.
+
+## Reproduce
+
+```bash
+PYTHONPATH=. python3 scripts/validate_evidence_bindings.py
+python3 -m pytest -q tests/test_evidence_bindings.py tests/test_model_contracts.py tests/test_reaction_experiments.py tests/test_ovarian_parameter_ledger.py -m 'not network'
+node web/test_engines.mjs
+```
+
+Observed environment: Python 3.14.6, pytest 9.1.1, NumPy 2.5.4, SciPy 1.18.1.
+Focused pre-serialization check: 129 passed, 1 network test deselected; evidence-only suite before independent-review correction: 32 passed. JavaScript engine checks
+passed against checked-in fixtures, including worst plasma-profile relative error
+4.8e-13. Final full local suite: 218 passed, 15 skipped, 1 network test deselected. Skips reflect unavailable OpenMM, PySCF and libRoadRunner; those independent-engine checks were not run. No dependency installation was performed.
+
+## References
+
+- Existing `vh/graph/contracts.py` interfaces and exact clearance identity tests.
+- `data/clinical/ovarian_hgsoc_parameter_ledger.json`, unchanged source ledger.
+- `docs/research-foundation.md` and `docs/research-question-template.md` for the
+  separation of evidence assertions, modeling assumptions and scientific validation.
+
+Independent software review found an audit precision defect for large integers.
+The correction preserves JSON integers and tagged exact rationals and rejects
+other non-lossless representations before dispatch. A large-integer regression
+verifies the executed value and recorded endpoints agree exactly. Final suite
+after this correction: 218 passed, 15 skipped, 1 network test deselected.

auto-research/2026-11-06-E-evidence-bindings/results.json

@@ -0,0 +1,113 @@
+{
+  "ledger_sha256": "37695eac4ed4c854b86c7e37a7e7324a462f69bf33c2c90fa2000db4955c0478",
+  "ovarian_readiness": {
+    "interpretation": "Readiness for these four necessary inputs only, not a complete model specification. KNOWN describes source access, not applicability; prevalence and hazard ratios are not kinetic rates.",
+    "ready": false,
+    "requirements": [
+      {
+        "ledger_record": {
+          "citation": {
+            "doi": "10.1073/pnas.2026663118",
+            "first_author_surname": "Gu",
+            "title": "Computational modeling of ovarian cancer dynamics suggests optimal strategies for therapy and screening",
+            "year": 2021
+          },
+          "derivation": null,
+          "id": "P015",
+          "label": "MISSING",
+          "limits": "Gu et al. simulation parameters not copied into this ledger.",
+          "locator": "No single untreated HGSOC doubling time tabulated for ledger extraction",
+          "population": "Newly diagnosed HGSOC before systemic therapy",
+          "quantity": "Untreated high-grade serous ovarian cancer volumetric doubling time",
+          "range": null,
+          "units": null,
+          "value": null
+        },
+        "ready": false,
+        "reason": "missing estimate",
+        "record_id": "P015",
+        "required_role": "tumor_growth"
+      },
+      {
+        "ledger_record": {
+          "citation": {
+            "doi": "10.1016/j.jtbi.2006.02.001",
+            "first_author_surname": "Kohandel",
+            "title": "Mathematical modeling of ovarian cancer treatments: Sequencing of surgery and chemotherapy",
+            "year": 2006
+          },
+          "derivation": null,
+          "id": "P016",
+          "label": "MISSING",
+          "limits": "See P021 for qualitative prior art.",
+          "locator": "Model uses fixed-fraction surgery operator; no patient-derived numeric fraction",
+          "population": "Ovarian cancer patients with quantitative debulking fractions",
+          "quantity": "Proportional intraoperative tumor retention fraction used in sequencing models (empirical estimate)",
+          "range": null,
+          "units": null,
+          "value": null
+        },
+        "ready": false,
+        "reason": "missing estimate",
+        "record_id": "P016",
+        "required_role": "surgical_retention"
+      },
+      {
+        "ledger_record": {
+          "citation": {
+            "doi": "10.1073/pnas.2026663118",
+            "first_author_surname": "Gu",
+            "title": "Computational modeling of ovarian cancer dynamics suggests optimal strategies for therapy and screening",
+            "year": 2021
+          },
+          "derivation": null,
+          "id": "P019",
+          "label": "MISSING",
+          "limits": "Add when a model contract consumes PK parameters.",
+          "locator": "Not applicable: sequence experiments use dimensionless burden units",
+          "population": "Virtual-human ovarian treatment-sequence graph experiments",
+          "quantity": "Population carboplatin clearance for whole-body PBPK coupling in ovarian treatment-sequence models",
+          "range": null,
+          "units": null,
+          "value": null
+        },
+        "ready": false,
+        "reason": "missing estimate",
+        "record_id": "P019",
+        "required_role": "carboplatin_clearance"
+      },
+      {
+        "ledger_record": {
+          "citation": {
+            "doi": "10.1073/pnas.2026663118",
+            "first_author_surname": "Gu",
+            "title": "Computational modeling of ovarian cancer dynamics suggests optimal strategies for therapy and screening",
+            "year": 2021
+          },
+          "derivation": null,
+          "id": "P020",
+          "label": "MISSING",
+          "limits": "Add when a model contract consumes PK parameters.",
+          "locator": "Not applicable: scalar chemotherapy operators in sequence experiments",
+          "population": "Virtual-human ovarian treatment-sequence graph experiments",
+          "quantity": "Population paclitaxel central volume and clearance for sequence models",
+          "range": null,
+          "units": null,
+          "value": null
+        },
+        "ready": false,
+        "reason": "missing estimate",
+        "record_id": "P020",
+        "required_role": "paclitaxel_volume_and_clearance"
+      }
+    ]
+  },
+  "schema_version": 1,
+  "synthetic_validation": {
+    "cases": 3,
+    "interpretation": "Nominal synthetic arithmetic only; no output uncertainty or biological validation",
+    "maximum_absolute_error_L_per_h": 0.0,
+    "passed": true,
+    "tolerance_L_per_h": 1e-12
+  }
+}

auto-research/README.md

@@ -27,3 +27,5 @@ auto-research/
 | 2026-11-05 | E | [Clearance reference validation](2026-11-05-E-clearance-reference/report.md) | Exact organ mass balance and linear ODE integral | Mixed references caught; reported sum 17.104405 L/h, dose/AUC 17.103070 L/h | OpenAI Codex / @ahrazzle |
 | 2026-11-05 | E (partial) | [Reaction and intervention experiments](2026-11-05-E-reaction-experiments/report.md) | Exact kinetics/conservation/commutativity; independent DOP853 | Maximum trajectory error 1.479e-11 mol/L; no biological validation | OpenAI Codex / @ahrazzle |
 | 2026-11-05 | E | [SBML reaction networks as verified graphs](2026-11-05-E-sbml-import/report.md) | Exact rational algebra; libRoadRunner as independent SBML engine | 3 CC0 BioModels: exact conservation laws, trajectories ≤7e-10, steady states ≤2e-12; positive-mass invariant flags 8 of 49 surveyed models with exact certificates | Claude (Anthropic) |
+
+- [2026-11-06: Explicit evidence bindings](2026-11-06-E-evidence-bindings/report.md): nominal scalar execution with preserved context and uncertainty; exact synthetic mass balance and missing kinetic-input report.

docs/evidence_bindings.md

@@ -0,0 +1,61 @@
+# Evidence at an executable scalar boundary
+
+`vh.graph.evidence` adds an optional checked path from an explicitly quantified
+record to `ModelRegistry`. It does not read papers, infer model parameters, or
+certify an observation's truth or applicability. The original scalar registry
+remains available; this is an opt-in interface, not a security enforcement layer.
+
+`EvidenceInput` holds a record ID, status, an optional `Quantity`, source, exact
+locator, limits, and `Uncertainty`. The quantity retains its complete context,
+quantity name, unit, reference basis, and prior provenance. These fields must be
+chosen and reviewed by the caller. A `recorded` status means a recorded estimate,
+not a validated model, causal effect, or clinical finding.
+
+- `recorded` estimates may bind when every `PortSpec` field and bound matches.
+- `synthetic` estimates additionally require `allow_synthetic=True`.
+- `conjecture`, `missing`, and `conflicting` records cannot bind. Missing and
+  conflicting records carry no selected point estimate. The caller must resolve
+  evidence outside this interface; changing a label alone is not validation.
+- Qualitative assertions have no scalar representation here. Protein presence,
+  antigen presentation, receptor recognition, and neural injury cannot substitute
+  for one another. Asma owns those assertion distinctions and evidence rules.
+
+`execute_evidence(registry, edge, evidence, specs)` first binds every input and
+then delegates to the registry, which independently rechecks the registered model
+contract. Supplying weaker binding specifications cannot override that contract.
+A rejected input never invokes the registered callback. As with the registry,
+callbacks should be pure: output validation cannot undo callback side effects.
+
+Integer audit values retain exact JSON integers; rational values retain tagged
+numerator/denominator pairs. Other real scalar values must convert losslessly to
+a JSON float or binding fails before execution. Consumers must preserve these
+representations when decoding the audit.
+
+The complete input audit is serialized under an `evidence:` provenance entry and
+therefore accompanies every returned output through the registry's existing
+lineage union. Returned values are nominal scenario outputs. The recorded input
+uncertainty is not output uncertainty. A source CI, IQR, or unquantified range is
+neither a probability distribution nor an asserted hard domain; there is no
+sampling, independence assumption, interval propagation, or automatic conversion.
+
+## Reproduce a positive example and the current missing-input result
+
+```bash
+PYTHONPATH=. python3 scripts/validate_evidence_bindings.py
+python3 -m pytest -q tests/test_evidence_bindings.py
+```
+
+The script executes three explicitly artificial clearance scenarios, independently
+checked against exact rational rate/concentration identities, and prints a
+deterministic JSON report. It also records the exact ovarian ledger hash and the
+complete rows for four necessary inputs: growth, surgical retention, carboplatin
+clearance, and paclitaxel volume/clearance. All four are currently missing. This
+list is not a complete disease-model specification. The readiness checker never
+activates a model: a future numeric ledger entry still needs an explicit reviewed
+semantic binding. Existing prevalence values and trial hazard ratios do not
+supply those parameters.
+
+No source data were acquired or re-curated. The ledger's `KNOWN` label describes
+its source-access convention and must not be translated into model validity.
+The [research report](../auto-research/2026-11-06-E-evidence-bindings/report.md)
+records the bounded software result and remaining validation work.

docs/model_contracts.md

@@ -71,3 +71,10 @@ of `Schema`; the registry dispatches the explicitly named model only. Callbacks
 should be pure functions: rejecting an invalid output cannot undo callback side
 effects. The registry is not a sandbox for untrusted Python. Contract and callable
 definitions remain outside serialized graph data.
+
+## Optional evidence bindings
+
+For recorded source locators, uncertainty metadata, missing/conflicting input refusal,
+and explicitly enabled synthetic scenarios, see [evidence bindings](evidence_bindings.md).
+This opt-in layer preserves input audit records; it does not certify scientific
+applicability or infer output uncertainty.