# HDF5 checksum coverage: reproduce the bounded observations
Original code and observations: CC0-1.0. Upstream sources retain their licenses.

## Files
Download these adjacent files into one directory:
- [coverage runner](hdf5_filter_coverage.py)
- [reader-policy runner](hdf5_reader_policy.py)
- [coverage tests](test_hdf5_filter_coverage.py)
- [reader-policy tests](test_hdf5_reader_policy.py)
- [coverage replay](verify_evidence.py)
- [reader replay](verify_reader_policy.py)
- [pinned requirements](requirements.txt)
- [coverage observations](observations.json)
- [reader observations](reader-policy-observations.json)
- [source matrix](sources.json)
- [reader source matrix](reader-policy-sources.json)

Use an isolated environment. Recorded: Linux x86_64, Python 3.12.3,
h5py 3.15.0, HDF5 1.14.6 and NumPy 2.3.3. A package version alone does
not guarantee the same native HDF5 build on every platform.

```sh
python3 -m venv .venv
.venv/bin/pip install --only-binary=:all: -r requirements.txt
.venv/bin/python -B -m unittest -v test_hdf5_filter_coverage.py test_hdf5_reader_policy.py
.venv/bin/python -B verify_evidence.py
.venv/bin/python -B verify_reader_policy.py
.venv/bin/python -B -OO -m unittest -v test_hdf5_filter_coverage.py test_hdf5_reader_policy.py
```

Replay compares every saved field except generation time, including environment
and runner hashes. Investigate differences; do not overwrite reference observations
to make another build pass. The fixture accepts no production input path. Native
calls resolve through the already-loaded h5py extension, with library-version and
object-ID checks and h5py's library lock.

## Interpretation
21 coverage runs, three growth sequences and a fill control; 24 reader-policy
reads and 12 cache sequences. These are designed cases, not a prevalence sample.
The raw JSON retains array values, masks, settings, callback events, exceptions
and hashes. Raw-read success and an empty coverage-exclusion list are not integrity
verdicts. Edge skipping and permissive reads are explicit opt-outs.

The [dataset](https://hesela.dev/datasets/hdf5-checksum-coverage/) and
[analysis](https://hesela.com/analyses/checksums-identity-and-lost-writes/#hdf5-coverage)
explain the coverage boundary. Cache-state conclusions are scoped to the recorded
build and clean fresh-open controls. Unresolved later refresh/alias observations
are not included here.

## Derived data
[build-dataset.mjs](build-dataset.mjs) generates metadata and CSV from saved
observations after verifying runner hashes. In the website tree run:
`node public/research/hdf5-verification/build-dataset.mjs`.
It expects the existing public/data/datasets directory. Generation is not replay;
the two Python verifiers actually rerun the native-library experiments.