Fix BDV N5 setup over-allocation

[AdvancedImagingUTSW]

Motivation

• N5 writer was creating an extra, unwritten position worth of setup groups at the end of a complete acquisition because setup expansion was performed after advancing the frame index.
• Copilot also pointed out that simply moving expansion before the write exposed a second issue for dynamic growth: c * positions + p changes existing setup IDs when positions grows, which can overwrite an existing channel/position setup.

Description

• Move dynamic N5/HDF5 setup expansion in BigDataViewerDataSource.write() to happen before the write, and only when the current frame actually targets a new position (if pos >= self.positions: ...).
• Use an append-friendly setup ID mapping, position * channel_count + channel, for HDF5/N5 dataset names and BDV XML metadata.
• Keep metadata.positions synchronized when dynamic growth occurs so the XML includes positions that were actually written.
• Make the BDV data source tests deterministic by using explicit z/time dimensions, deterministic image and stage data, and deterministic stop-early behavior instead of random shape choices.
• Update the BDV metadata test expectation to the append-friendly setup ordering.

Evidence from 2026-05-21 acquisitions

• Inspected /Users/Dean/Desktop/pr1207/20260521_lung_mv3_488nm_562nm.
• cell_001 (per_stack) has 4 N5 setups, 240 chunk files, 12 MIP files, and 12 XML view registrations.
• cell_002 (per_z) has 4 N5 setups, 240 chunk files, 12 MIP files, and 12 XML view registrations.
• Logs for both acquisitions report 240 total received frames and include the final expected frame C=1, Z=19, T=2, P=1.

Testing

• uv run --python 3.9 --extra dev python -m pytest -p no:cov -o addopts= test/model/data_sources/test_bdv_data_source.py::test_bdv_getitem -vv
  • Result: 24 passed in 36.89s.
• uv run --python 3.9 --extra dev python -m pytest -p no:cov -o addopts= test/model/data_sources/test_bdv_data_source.py
  • Result: 122 passed, 196 warnings in 130.29s.
• uv run --python 3.9 --extra dev python -m pytest -p no:cov -o addopts= test/model/metadata_sources/test_bdv_metadata.py::test_bdv_xml_dict -vv
  • Result: 2 passed in 2.56s.
• uv run --python 3.9 --extra dev ruff check test/model/data_sources/test_bdv_data_source.py test/model/metadata_sources/test_bdv_metadata.py
  • Result: All checks passed.

---

Codex Task

[Copilot]

Pull request overview

Adjusts BDV N5/HDF5 writer behavior to prevent creating an extra (unwritten) “position worth” of setup groups at the end of a completed acquisition by changing when dynamic setup expansion occurs in BigDataViewerDataSource.write().

Changes:

• Move dynamic setup expansion to occur immediately before a write that targets a new position.
• Remove the post-write expansion logic that ran after incrementing _current_frame.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 64.41%. Comparing base (3999f2c) to head (7eeeda5).
⚠️ Report is 15 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1207      +/-   ##
===========================================
+ Coverage    63.65%   64.41%   +0.75%     
===========================================
  Files          189      190       +1     
  Lines        26029    26279     +250     
===========================================
+ Hits         16569    16927     +358     
+ Misses        9460     9352     -108     

Flag	Coverage Δ
unittests	64.41% <100.00%> (+0.75%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.