# HBF external-validation package — v0.6.11

Everything an independent institution needs to reproduce and challenge the
numerical claims in this repository, without contacting HBF Network. A passing
software run is reproducibility evidence, **not** experimental validation and
not proof of institutional independence.

## What is being offered for validation

The following scoped kernels are ready for independent reproduction. Do not
accept a broader device or reactor-performance claim.

| Claim | Status | Where |
|---|---|---|
| Maxwellian ⟨σv⟩ integral of the Sikora–Weller (2016) tabulation, 150–300 keV | `BENCHMARK_REPRODUCED` | `packages/reactivity/maxwellian.py` |
| Grad–Shafranov solver, Solov'ev equilibrium | `VERIFIED_KERNEL` | `scientific-core/equilibrium/grad_shafranov.py` |
| Assumption-derived covariance propagation | `VERIFIED_KERNEL` | `packages/reactivity/covariance.py` |
| Isotropic kinetic-distribution integral | `VERIFIED_KERNEL` | `scientific-core/kinetics/isotropic_distributions.py` |
| Relativistic radiation-channel kernels | `VERIFIED_KERNEL` | `scientific-core/radiation/radiation_models.py` |
| Canonical ideal-MHD interface stability | `VERIFIED_KERNEL` | `scientific-core/stability/ideal_mhd_interface.py` |

These maturity labels apply only to the equations and declared domains. The
stability benchmark is not a stability result for any confinement device; the
synchrotron value is optically-thin emitted power, not net escaping loss; the
kinetic framework does not include sustaining power.

## One-command run

```bash
python3 external-validation/run_validation.py \
  --institution "YOUR INSTITUTION" \
  --operator "NAMED OPERATOR" \
  --output external-validation/validation-run.json
```

The runner captures environment details, pinned artifact hashes, raw command
outputs, durations and the source-tree digest. Identity and independence remain
`false` by construction: a second named human must review and sign separately.
The source-tree digest covers all shipped files except the self-referential
release manifest, generated release-check/run records, caches, archives and
`api/.data`; the exact scope is also recorded in every run result.

## Reproduce in one command each

```bash
python3 packages/reactivity/maxwellian.py            # reactivity table
python3 packages/reactivity/test_reactivity_kernel.py # 18 assertions
python3 scientific-core/equilibrium/grad_shafranov.py # convergence table
python3 tests/test_phase3_physics.py                  # 20 assertions
python3 tests/cross-language/compare.py               # Python vs JS
python3 tests/test_phase2_covariance.py                # covariance gate
python3 tests/test_phase3_complete.py                  # kinetic/radiation/MHD
node tests/browser_core.test.mjs                       # browser adapter
python3 tests/test_phase4_readiness.py                 # 8 handoff checks
```

Requirements: Python ≥ 3.10 with NumPy, Node ≥ 18. No network.
SciPy is optional — the solver falls back to red-black SOR without it.

## Expected outputs

**Reactivity** (publishable band only; outside it the model abstains):

| T (keV) | ⟨σv⟩ (m³/s) |
|---|---|
| 150 | 1.8618e-22 |
| 200 | 2.9401e-22 |
| 300 | 4.3535e-22 |

**Grad–Shafranov**, Solov'ev `A=1, B=1, c=0.1` on `R∈[0.6,1.4], z∈[-0.4,0.4]`:

| n | L2 rel err | observed order |
|---|---|---|
| 21 | 2.55e-05 | — |
| 41 | 5.86e-06 | 2.120 |
| 81 | 1.41e-06 | 2.060 |
| 161 | 3.44e-07 | 2.030 |

The order must approach 2. If it does not, the solver is wrong.

## How to challenge it

The most valuable things you can do, in order:

1. **Integrate the same CSV with your own code.** If you disagree by more than ~1e-6 relative, one of us has a bug and we want to know.
2. **Run the Solov'ev case in an established equilibrium code** (FreeGS, CHEASE, or your own) and compare ψ on the same grid.
3. **Supply a source-released covariance matrix** for the Sikora–Weller cross section if you have access to it. The shipped matrix is explicitly assumption-derived from independent statistical errors plus a fully correlated 3.4% normalization systematic; it is not the missing source covariance.
4. **Tell us where the domain gating is wrong.** The abstention band (150–300 keV) is our judgment; challenge it.

## Data licence

`content/sources/sikora-weller-2016/` is derived from an open-access CC BY 4.0
article (DOI 10.1007/s10894-016-0069-y). That licence is why it can be
redistributed here. Attribution is in `source.json`.

## Reporting

Preregister with `PREREGISTRATION-TEMPLATE.md`, preserve the runner's complete
JSON, then submit a result matching
`platform/science/validation-evidence.schema.json`. That schema requires two
distinct named humans, a review state, published failures/residuals, and
model/code/data hashes frozen before reveal. No maturity level is raised
automatically. Follow `REPORTING.md` for the public discrepancy/evidence record
and the minimum information required for triage.