Raise helper coverage floor

[den-sq]

Fixes #61.

Summary

• Adds targeted helper tests for uncovered pure-logic branches in bounding boxes, files, models, parse, shapes, spline, and volume cache.
• Excludes narrow integration-only paths with # pragma: no cover: SharedMemoryManager IPC lifecycle, live shared-memory cache connections, and the unreachable parsed image-source fallback.
• Enables branch coverage for ouroboros/helpers in pyproject.toml, sets fail_under = 98, updates the coverage workflow to use that config, and regenerates python/coverage.svg.
• Fixes the z-axis initial tangent branch in rotation-minimizing spline frames by using floating-point normal vectors before in-place normalization.

Verification

cd python
poetry run coverage run -m pytest
168 passed, 2 warnings in 10.02s

poetry run coverage report --fail-under=98
TOTAL  1434 statements, 0 missed, 282 branches, 12 partial, 99%

poetry run coverage xml
poetry run genbadge coverage -i coverage.xml -o coverage.svg
coverage.svg regenerated at 99.30%

Known warnings remain unchanged and are out of scope for this issue:

• SharedNPArray.__del__ unraisable AttributeError warning from mem.py:76.
• Pydantic v2.11 deprecation warning from models.py:117.

[tavateva]

Review — Draft Promotion Criteria PASS ✅

362 additions across 15 files, closes #61. All 7 criteria hold.

1. CI & mergeability — all 3 required checks green (`coverage`, `server-image`, `test-coverage`); `mergeable: MERGEABLE`, `mergeStateStatus: CLEAN`. ✓

2. Issue Acceptance Criteria — issue #61 body is title-only ("Hit 100% Test Coverage on Helpers"), so the discriminator is the implicit goal: effectively-full helper coverage. Delivered:

   • New tests covering every gap from the previously-uncovered set: bounding_boxes (+26 lines — vol_slice/get_min/get_max, unsplittable BSP partition); files (+137 — TIFF error paths, np_convert preset/zero-range/shifted branches, volume_from_intermediates single-file + chunk-dir + discrete, write_conv_vol scaled + non-scaled paths with captured writer); mem (+5 — get_termed_mem global identity); models (+21 — three generic-exception branches via monkeypatch of model_validate / model_validate_json and a real bad-encoding file); parse (+8 — CV_FORMAT.get unknown-suffix ValueError); shape (+53 — merge retain/overwrite, bool, param_max, TFIter.__call__ abstract return, IntIter/MemAddressIter/SliceIter, ContigMemIter contig_stride + cached-value branch + IndexError for break-fields-include-last); spline (+19 — z-axis initial tangent path); volume_cache (+63 — flush_local_cache disabled path, docker localhost rewrite, get_resolution_um mip forwarding, uncached-eviction path in request_volume_for_slice, three remove_volume variants including shared+destroy_shared, get_slice_indices).
   • # pragma: no cover on integration-only paths: mem.py TermedNPArray/clear_queue/remove_termed/shutdown/start/connect/__enter__/__exit__/mem_monitor (IPC lifecycle); volume_cache.py:connect_shm and the download_volume use_shared branch (live SharedNPManager); parse.py:170 (unreachable). Each carries an inline justification comment.
   • Coverage config locked in pyproject.toml: [tool.coverage.run] source=[\"ouroboros/helpers\"] branch=true and [tool.coverage.report] fail_under=98 show_missing=true skip_covered=false exclude_also=[...].
   • Workflow uses pyproject config: python-coverage.yml drops --source=ouroboros/helpers from coverage run (config-driven now).
   • Badge regenerated: python/coverage.svg moves from 91.30% → 99.30%. ✓

3. PR Test Plan checkboxes — no checkbox section. N/A.

4. Tests run, not just present — Verification block reports concrete counts:

   • pytest: 168 passed, 2 warnings, 10.02s (up from the 151-passed baseline — 17 new tests all executed)
   • coverage report --fail-under=98: 1434 statements, 0 missed, 282 branches, 12 partial, 99%
   • Badge regenerated at 99.30%
     Voluntary test additions covered by the reported count. ✓

5. Scope — production-code touches are:

   • mem.py +9/-9 (pragma-only)
   • parse.py +1/-1 (pragma-only)
   • spline.py +2/-2 (real bug fix — see judgement calls)
   • volume_cache.py +2/-2 (pragma-only)
   • pyproject.toml +14 (coverage config)
   • .github/workflows/python-coverage.yml -1/+1 (drop redundant --source)
   • coverage.svg regen
     All within scope of "raise helper coverage floor" and each ≤~20 lines to a file already touched for the issue. ✓

6. Regressions & patterns — 168 passed matches the claimed pass count; existing 151 tests still pass; no pattern violations (pragmas follow standard # pragma: no cover - <reason> form; fixture patterns match existing tests). ✓

7. Judgement calls — three, all reasoned inline in the PR body:

   • 99.30% target vs. literal 100%: the pragma set (IPC lifecycle, live SharedNPManager, one comment-flagged unreachable line) matches what a unit-only suite can honestly claim; PR Summary calls these out as "narrow integration-only paths" and "unreachable parsed image-source fallback." Reasonable.
   • Spline z-axis fix bundled with coverage work: initial_normal = np.array([0, 1, 0]) was integer-valued; the following initial_normal /= np.linalg.norm(...) did in-place division on an integer array — the bug surfaces precisely when trying to test the z-axis initial-tangent branch. Fix (change to [0.0, 1.0, 0.0]) is 2 lines and clearly explained in Summary. Legitimate scope-adjacent bug fix, well within the ≤~20 line allowance.
   • Known warnings out of scope: SharedNPArray.__del__ unraisable AttributeError (mem.py:76) and Pydantic v2.11 model_fields-on-instance deprecation (models.py:117) are explicitly deferred. Both are pre-existing issues that predate this PR and are genuine bugs deserving their own tracking. Reasonable deferral.
     ✓

All seven criteria hold. Approving. Safe to promote from draft.

One follow-up worth filing before merge: the two known warnings (SharedNPArray.__del__ and the Pydantic deprecation) as separate tracking issues — they're real bugs, and the pragmas on mem.py lifecycle mean neither is unit-covered.