Add measured, reported, floor-gated code coverage

[adowling2]

Summary

Adds measured, reported, and floor-gated code coverage for src/bits_for_gaps (the
shipped package only). This was not a "coverage is bad" task — the established
baseline was already 97% (608 stmts, 18 missed). The work here is: configure
coverage properly, triage every one of those 18 gaps individually (test it for real,
or pragma it with a documented reason), enable branch coverage (which surfaced one
more gap statement coverage couldn't see), add a regression floor, and wire up CI
reporting.

Before / after

	Before	After
Statement coverage	97% (608 stmts, 18 missed)	100% (605 stmts, 0 missed)
Branch coverage	not measured	100% (134 branches, 0 partial)
Tests	204 passed, 2 deselected	218 passed, 2 deselected
--cov-fail-under	none	99

(605 vs 608 statements: branch=true + the exclude_lines change how a couple of
lines are counted; not a scope change — source = ["bits_for_gaps"] is unchanged.)

Per-gap triage

Tested (15 statements — real behavior, not line-execution-only):

Location	What was untested	Test added
__init__.py:39-40	PEP 562 __getattr__'s lazy-resolution branch	tests/unit/test_init.py: bits_for_gaps.AnisotropicSE (etc.) resolves to the same object as the direct submodule import; from bits_for_gaps import BitsForGaps works too
__init__.py:45	__dir__	same file: dir(bits_for_gaps) lists both lazy and eager names, no duplicates
design.py:75-76	full_factorial_design's grid-overshoot trim (rng.choice)	The existing test picked a perfect-square case (9 = 3×3, no trim needed). New test uses n_train=10 (d=2 → a 16-point grid) and checks no duplicate points + seed-dependent selection
entropy.py:134-136	cholesky()'s Cholesky-based matrix inverse	Finding, not a bug: this function is never actually called elsewhere — its own docstring claimed it was used by second_order_entropy's multivariate branch, but that branch uses np.linalg.inv directly. Docstring corrected; function kept (public, correct, documented) with a real correctness test (cholesky(C) == np.linalg.inv(C), C @ cholesky(C) == I)
sampler.py:199-201	adaptiveEntropy.sample_gp_posterior_mixture (instance wrapper)	Nothing in the codebase calls this — run() and every other test reach mixture.sample_gp_posterior_mixture directly. It draws from TF's ambient RNG so two calls can't be compared by value; test monkeypatches the delegated call and asserts seed/size are forwarded correctly
sampler.py:224	adaptiveEntropy.entropy_objective (instance wrapper)	Same situation, but this one is deterministic (predict_f, not predict_f_samples) — compared value-for-value against calling acquisition.entropy_objective directly with the same config
sampler.py:380-381	showLMLres=True's diagnostic-printing branch	The existing initalLML=True test doesn't also set showLMLres. New test sets both and checks capsys output
sampler.py:431-432	run_model(), the deprecated zero-argument entry point	read_data alone was tested; nothing chained it through run_model (read_data + run(checkpoint_dir=...)) end to end. New test writes a fake activity_data_1, calls run_model(), checks the returned history and the checkpoint written
sampler.py:462→464 (a branch, found once branch=true was enabled — statement coverage couldn't see this)	_write_checkpoint's if entropy_field is not None False path (non-2-D runs)	Every existing checkpoint test uses 2-D bounds, so entropy_field is always non-None there. New test in test_nd_synthetic.py runs the existing 1-D/3-D cases with checkpoint_dir set and confirms entropy_{it} is correctly not written

Pragma'd (3 statements — genuinely unreachable or untraceable, not faked):

Location	Reason
design.py:72-73	The "grid too small" ValueError. Mathematically unreachable for any (bounds, n_train, n_test): levels = ceil(n_total**(1/d)) guarantees levels**d >= n_total. Already documented as such in tests/unit/test_design.py's NOTE (kept, with its stale line-number reference fixed)
gp.py:177	return tfp.mcmc.sample_chain(...) inside run_mcmc's @tf.function-decorated closure. Confirmed genuinely exercised, not skipped: ran the integration suite (which calls run(), which calls this, repeatedly) with --cov=bits_for_gaps and the line stayed "missing" regardless — @tf.function's AutoGraph compiles this body into a TF graph that executes outside CPython's per-line trace hooks coverage.py relies on. A tooling blind spot, not an untested path

No paper/data/, paper/reference/, tolerance, or algorithm was touched anywhere in this triage. The one non-test source change beyond pragmas/comments is entropy.py's cholesky() docstring correction (removing the false "used by second_order_entropy" claim) — a documentation fix, not a behavior change.

The floor: fail_under = 99

Set in pyproject.toml's [tool.coverage.report]. Currently at 100%; the 1-point
slack is for legitimate small variation (e.g. branch-counting differences coverage.py
might show across the four supported Python versions), not to paper over a real
regression — the codebase is small enough (605 statements) that any meaningfully
untested new function will drop well below 99%, not hover just under it.

pytest -q (no flags) is not affected — it stays exactly as fast and unchanged
as before. Coverage is opt-in via pytest --cov=bits_for_gaps --cov-report=term-missing
(now documented in README.md and docs/installation.md); CI wires that exact
invocation into one job (see below), where fail_under actually gates something.

CI reporting: Codecov (not the artifact alternative)

Chose Codecov (codecov/codecov-action@v5) over the job-summary + HTML-artifact
alternative:

• This is a public repo, so Codecov's tokenless upload has genuinely zero setup
  burden — no secret to create or rotate, nothing for the maintainer to configure
  beyond the (optional, cosmetic) act of connecting the repo on codecov.io.
• A repo-topline badge is more discoverable to a visitor or reviewer than an artifact
  buried inside a specific workflow run.
• The real coverage gate is pytest-cov's own fail_under (enforced locally in the
  same step, on every matrix leg) — Codecov's upload is reporting/visibility on top
  of that, not a second gate, so fail_ci_if_error: false means a transient
  codecov.io outage can't fail CI.

Uploads from the 3.12 matrix leg only (if: matrix.python-version == '3.12') —
uploading from all four would just repeat the same numbers four times.

Hard rules confirmed

• No dependency version changed. git diff main -- pyproject.toml touches only
  [tool.coverage.*]/[tool.pytest.ini_options] comments; dependencies/
  optional-dependencies are untouched (pytest-cov was already present).
• No tolerance, reference/baseline file, or algorithm touched. git diff main -- tests/integration/data paper/data paper/reference is empty. Every new/changed test
  passed against existing behavior; nothing needed re-pinning.
• Green at every commit: pytest -q (218 passed, 2 deselected — up from 204 because
  of the new gap-closing tests, not because anything was loosened), pytest -m vle
  (2 passed), ruff check . (clean), sphinx-build -W docs docs/_build/html (clean),
  and the lazy-import contract (import bits_for_gaps loads neither juliacall nor
  tensorflow).
• Rebased cleanly onto the current origin/main (after PRs docs: move the VLE physics equations to the example page; fix a grammar slip #3 and docs: add the paper's graphical abstract to the README and docs landing page #4 merged) — no
  conflicts; branch is left in a clean, mergeable state.

---

🤖 Generated with Claude Code