driftless-bundle-photometry 0.2.1__tar.gz

driftless_bundle_photometry-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,83 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Quality checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+      - name: Install development dependencies
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[dev]"
+      - name: Lint
+        run: python -m ruff check .
+      - name: Check formatting
+        run: python -m ruff format --check .
+      - name: Verify synchronized agent contracts
+        run: >-
+          python -c "from pathlib import Path;
+          assert Path('AGENTS.md').read_bytes() == Path('CLAUDE.md').read_bytes(),
+          'AGENTS.md and CLAUDE.md differ'"
+
+  tests:
+    name: Tests (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    env:
+      PYTHONUTF8: "1"
+      QT_QPA_PLATFORM: offscreen
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install exact project constraints
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[dev]"
+      - name: Run full test suite
+        run: python -m pytest -q
+
+  wheel-smoke:
+    name: Wheel smoke (${{ matrix.os }}, ${{ matrix.mode }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, macos-latest]
+        mode: [core, gui]
+    env:
+      PYTHONUTF8: "1"
+      QT_QPA_PLATFORM: offscreen
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+      - name: Build wheel
+        run: python -m pip install --upgrade pip && python -m pip wheel . --no-deps --wheel-dir wheelhouse
+      - name: Test wheel from an isolated environment
+        run: >-
+          python tools/wheel_smoke.py
+          --wheel-dir wheelhouse
+          --mode ${{ matrix.mode }}
+          --expected-version $(python tools/release.py version)

driftless_bundle_photometry-0.2.1/.github/workflows/release.yml

@@ -0,0 +1,192 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+env:
+  PYTHONUTF8: "1"
+  RELEASE_TAG: ${{ github.event.release.tag_name }}
+
+jobs:
+  python-distributions:
+    name: Build and verify Python distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+      - name: Validate synchronized release metadata
+        run: python tools/release.py check "$RELEASE_TAG"
+      - name: Install Linux GUI runtime libraries
+        run: sudo apt-get update && sudo apt-get install --yes libegl1
+      - name: Install release tooling
+        run: python -m pip install --upgrade pip && python -m pip install ".[dev,release]"
+      - name: Run release quality gates
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: |
+          python -m ruff check .
+          python -m ruff format --check .
+          python -m pytest -q
+      - name: Build wheel and source distribution
+        run: python -m build
+      - name: Validate distribution metadata
+        run: python -m twine check --strict dist/*
+      - name: Smoke-test the built wheel outside the checkout
+        run: >-
+          python tools/wheel_smoke.py
+          --wheel-dir dist
+          --mode gui
+          --expected-version "${RELEASE_TAG#v}"
+      - name: Upload exact Python release artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-distributions
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+
+  windows-installer:
+    name: Build and verify Windows installer
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+      - name: Validate synchronized release metadata
+        run: python tools/release.py check "$env:RELEASE_TAG"
+      - name: Install application and freezer
+        run: python -m pip install --upgrade pip && python -m pip install ".[gui,release]"
+      - name: Create multi-resolution Windows icon
+        run: >-
+          python tools/make_windows_icon.py
+          src/driftless_photometry/gui/assets/driftless-photometry.png
+          build/windows/driftless-photometry.ico
+      - name: Freeze the self-contained desktop application
+        run: python -m PyInstaller --noconfirm --clean packaging/windows/DriftlessBundlePhotometry.spec
+      - name: Smoke-test the frozen application
+        shell: pwsh
+        run: |
+          $desktop = Start-Process `
+            -FilePath "dist/DriftlessBundlePhotometry/DriftlessBundlePhotometry.exe" `
+            -ArgumentList "--desktop-smoke" `
+            -Wait -PassThru
+          if ($desktop.ExitCode -ne 0) {
+            throw "Frozen desktop smoke exited with code $($desktop.ExitCode)"
+          }
+          $outputDir = Join-Path $env:RUNNER_TEMP "dbf-frozen-acquisition"
+          $headless = Start-Process `
+            -FilePath "dist/DriftlessBundlePhotometry/DriftlessBundlePhotometry.exe" `
+            -ArgumentList "--headless", "--duration", "0.04", "--fibers", "1", "--output", $outputDir `
+            -Wait -PassThru
+          if ($headless.ExitCode -ne 0) {
+            throw "Frozen acquisition smoke exited with code $($headless.ExitCode)"
+          }
+          if ((Get-ChildItem $outputDir -Filter "*.nwb").Count -ne 1) {
+            throw "Frozen acquisition smoke did not create exactly one NWB file"
+          }
+      - name: Compile the per-user installer
+        shell: pwsh
+        run: |
+          $version = $env:RELEASE_TAG.TrimStart("v")
+          $compiler = Join-Path ${env:ProgramFiles(x86)} "Inno Setup 6/ISCC.exe"
+          & $compiler `
+            "/DAppVersion=$version" `
+            "/DSourceDir=$((Resolve-Path 'dist/DriftlessBundlePhotometry').Path)" `
+            "/DOutputDir=$((New-Item -ItemType Directory -Force 'release-assets').FullName)" `
+            "/DIconFile=$((Resolve-Path 'build/windows/driftless-photometry.ico').Path)" `
+            "packaging/windows/DriftlessBundlePhotometry.iss"
+          if ($LASTEXITCODE -ne 0) { throw "Inno Setup failed with code $LASTEXITCODE" }
+      - name: Test silent install, launch, and uninstall
+        shell: pwsh
+        run: |
+          $installer = Get-Item "release-assets/*.exe"
+          $installDir = Join-Path $env:RUNNER_TEMP "dbf-installer-smoke"
+          $install = Start-Process $installer.FullName `
+            -ArgumentList "/VERYSILENT", "/SUPPRESSMSGBOXES", "/NORESTART", "/DIR=$installDir" `
+            -Wait -PassThru
+          if ($install.ExitCode -ne 0) { throw "Installer exited with code $($install.ExitCode)" }
+          $app = Start-Process (Join-Path $installDir "DriftlessBundlePhotometry.exe") `
+            -ArgumentList "--desktop-smoke" -Wait -PassThru
+          if ($app.ExitCode -ne 0) { throw "Installed application exited with code $($app.ExitCode)" }
+          $uninstall = Start-Process (Join-Path $installDir "unins000.exe") `
+            -ArgumentList "/VERYSILENT", "/SUPPRESSMSGBOXES", "/NORESTART" `
+            -Wait -PassThru
+          if ($uninstall.ExitCode -ne 0) { throw "Uninstaller exited with code $($uninstall.ExitCode)" }
+      - name: Upload Windows installer
+        uses: actions/upload-artifact@v7
+        with:
+          name: windows-installer
+          path: release-assets/*.exe
+          if-no-files-found: error
+
+  pypi:
+    name: Publish to PyPI
+    needs: [python-distributions, windows-installer]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/driftless-bundle-photometry
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: python-distributions
+          path: dist
+      - name: Publish the verified distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.14.2
+
+  github-assets:
+    name: Attach synchronized release assets
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+      - uses: actions/download-artifact@v8
+        with:
+          path: release-assets
+          merge-multiple: true
+      - name: Generate SHA-256 manifest
+        shell: bash
+        run: >-
+          python tools/release.py checksums
+          release-assets/SHA256SUMS.txt
+          release-assets/*.whl
+          release-assets/*.tar.gz
+          release-assets/*.exe
+      - name: Attest release artifacts
+        uses: actions/attest-build-provenance@v4.2.2
+        with:
+          subject-path: |
+            release-assets/*.whl
+            release-assets/*.tar.gz
+            release-assets/*.exe
+            release-assets/SHA256SUMS.txt
+      - name: Upload assets to the matching GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "$RELEASE_TAG" release-assets/* --clobber

driftless_bundle_photometry-0.2.1/.gitignore

@@ -0,0 +1,19 @@
+.DS_Store
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+build/
+dist/
+*.egg-info/
+*.nwb
+*.partial.nwb
+*.photometry-spool/
+*.rwd-spool/
+*.rwd-wire
+*.rwd-wire.partial
+demo-output/
+old mescoscope/averages.dat

driftless_bundle_photometry-0.2.1/AGENTS.md

@@ -0,0 +1,185 @@
+# Driftless Bundle Photometry — Agent Contract
+
+`AGENTS.md` and `CLAUDE.md` must remain byte-for-byte identical. Any change to one
+must be copied to the other in the same commit. The test suite enforces this.
+
+## Mission
+
+Build a reliable, Python-based multichannel fiber-photometry acquisition system.
+The supported hardware target is Windows. macOS must support the simulator,
+replay, NWB writing/reading, analysis, and GUI demo; physical camera operation on
+macOS is best-effort only.
+
+The MATLAB applications, Arduino firmware, Bonsai files, and manual are historical
+design evidence. They are not specifications to port verbatim.
+
+## Scientific and product invariants
+
+- The primary workflow is photometry traces, not an imaging dashboard.
+- Camera imagery is used for calibration, focus, ROI placement, and diagnostics.
+- Support 1–9 circular fiber ROIs with stable IDs, labels, positions, and radii.
+  Each ROI maps to one animal/subject and one independently valid NWB file.
+- Support up to three configured excitation wavelengths: 405, 470, and 565 nm.
+- Normal acquisition interleaves exactly one excitation wavelength per exposure.
+  Do not combine wavelengths in one monochrome exposure unless a future hardware
+  design provides a validated unmixing mechanism.
+- The total camera frame rate is shared across enabled wavelengths.
+- Raw camera frames are optional. When retained, preserve original `uint16` values;
+  never normalize them per frame.
+- Preserve one original `uint16` camera reference for every wavelength observed,
+  even when full raw-frame retention is disabled. ROI-annotated display copies are
+  derived diagnostic images with fixed bit-depth scaling and never replace raw data.
+- Support four behavior TTL inputs and retain both rising and falling edges.
+- Never infer wavelength solely from frame parity/modulo. Persist an explicit
+  controller sequence and excitation identity for every camera exposure.
+- Preserve raw data. Corrections, fitted controls, dF/F, z-scores, and QC outputs
+  are separate derived datasets.
+- Live Absolute/dF/F views and per-wavelength visibility are presentation state.
+  Calculate dF/F baselines independently per ROI and wavelength, keep their window
+  explicit, and never overwrite raw samples with a display transformation.
+- Never silently drop data. Queue pressure, dropped frames, malformed device
+  messages, clock discontinuities, and writer failures must be observable.
+
+## Timing and controller contract
+
+The hardware controller is the deterministic timing authority. The intended design
+uses one clock for camera trigger/exposure records, excitation gates, and all TTL
+edges. Each exposure record includes a monotonic sequence number, wavelength,
+controller tick, and commanded intensity.
+
+The GUI must not directly bit-bang LEDs or use host scheduling for exposure-critical
+timing. The legacy Arduino Uno and firmware may be reused only after electrical and
+timing characterization. Prefer true DAC outputs (or a validated external DAC) for
+0–5 V intensity commands and separate digital LED gates.
+
+Every hardware command protocol must be versioned and include explicit HELLO/READY,
+configuration acknowledgement, ARM/START/STOP, error reporting, and safe LED-off
+behavior on disconnect or watchdog timeout.
+
+## Canonical data contract
+
+The final scientific artifacts are one self-contained NWB-HDF5 file per configured
+ROI/animal for each acquisition session. Temporary recovery journals/spools may be
+used during acquisition, but they are not the canonical deliverables. Shared timing,
+TTL, exposure, system-event, calibration, and optional raw-frame records are copied
+into every ROI file so each file is independently interpretable.
+
+Use a hybrid of core NWB and `ndx-fiber-photometry`:
+
+- `NWBFile`, per-ROI `Subject`, `DeviceModel`, and `Device`: subject, session, and
+  hardware provenance.
+- `ndx-fiber-photometry`/`ndx-ophys-devices`: fibers, indicators, excitation
+  sources, photodetector, filters, commanded voltage, and per-wavelength response
+  series.
+- One raw `FiberPhotometryResponseSeries` per enabled wavelength in each file,
+  shaped `[time, 1]`, with explicit timestamps.
+- Core ROI table, calibration image, and per-wavelength camera references: the
+  authoritative circular camera-space ROI represented by that file, plus derived
+  fixed-scale RGB views with the ROI outlined.
+- Core `ImageSeries`: optional embedded lossless chronological `uint16` frames.
+- Core `EventsTable`: TTL edges, camera exposures, excitation events, dropped frames,
+  and system events.
+- `invalid_times`/`TimeIntervals`: bad continuous spans.
+- Processing modules: immutable derived traces and QC.
+- A versioned complete settings snapshot: session metadata, camera/controller and
+  channel settings, display preferences, and all configured ROIs. Embed the snapshot
+  in every per-ROI file so any one current-format NWB can restore the whole setup;
+  legacy imports must identify fields that were not historically persisted.
+
+Use NWB seconds on a shared session time base and preserve raw camera frame IDs and
+controller ticks for forensic reconstruction. Use stable `fiber_id` values to map
+camera ROIs to fiber-photometry table rows.
+
+Write every output to a partial path, drain and close all writers, validate, reopen
+and verify counts, then atomically promote each partial only after the complete ROI
+file set passes validation. Never label an unvalidated partial file as complete.
+
+## Architecture boundaries
+
+- `config`: validated immutable session/camera/channel/ROI/TTL configuration.
+- `domain`: typed frames, events, samples, and result records.
+- `timing`: wavelength schedules, tick unwrapping, and clock mapping.
+- `roi`: circular masks, hardware crop calculation, and signal extraction.
+- `hardware.camera`: camera interface; simulator and Thorlabs implementations.
+- `hardware.controller`: controller interface, protocol, and serial implementation.
+- `acquisition`: explicit state machine and coordination; no GUI dependencies.
+- `storage`: append-safe spool/recovery and NWB finalization/validation.
+- `gui`: PySide6/pyqtgraph presentation; communicates with workers through signals.
+
+Device-owning objects have one owner thread. HDF5/NWB writes have one writer owner.
+Use bounded queues. The GUI thread must never poll hardware, write frames, or block on
+acquisition loops.
+Live plots may window and aggregate for display, but this must be explicitly
+display-only. Point count must remain bounded by screen resolution rather than session
+duration, brief extrema must remain visible, and acquired or stored samples must never
+be discarded by a rendering optimization.
+
+State transitions are explicit:
+
+`DISCONNECTED -> READY -> CALIBRATING -> ARMED -> RECORDING -> DRAINING -> READY`
+
+`ERROR` is reachable from every active state, with deterministic cleanup and LEDs
+off. Invalid transitions raise errors rather than being ignored.
+
+## Development gates
+
+Work in order and do not advance past a failing gate:
+
+1. Domain/config/timing/ROI unit tests.
+2. Tiny golden NWB fixture: round-trip, PyNWB validation, NWB Inspector, and exact
+   frame/trace/event count checks.
+3. Headless simulator and acquisition pipeline with bounded queues and recovery.
+4. Fault tests: stop, queue full, disk error, malformed controller data, dropped
+   frame, camera loss, and clock rollover.
+5. GUI demo backed by the same headless services.
+6. Windows camera/controller integration and bench characterization.
+7. Packaging and clean-machine smoke tests.
+
+Hardware-dependent work must have a simulator/replay test path. Do not claim camera
+or electrical validation without the physical hardware and measurements.
+
+## Code and repository rules
+
+- Target Python 3.11–3.13 and use type annotations throughout.
+- Prefer small pure functions and dependency-injected interfaces.
+- Use Pydantic for persisted user/session configuration and dataclasses for hot-path
+  runtime records.
+- Use NumPy arrays with explicit dtype and documented axis order `[y, x]` or
+  `[time, y, x]`.
+- Use `pathlib.Path`; never add machine-specific absolute paths.
+- Public behavior changes require tests. Bugs receive regression tests.
+- Keep optional hardware imports lazy so simulator mode works without vendor SDKs.
+- Before implementing or changing the Thorlabs camera adapter, read
+  `docs/thorlabs-camera-python-api.md`; it records the vendor API lifecycle, DBF
+  integration decisions, and the boundary between documented behavior and required
+  CS505MU bench validation.
+- Do not edit generated/vendor/legacy files unless the task explicitly targets them.
+- Do not commit recordings, build outputs, virtual environments, or secrets.
+- Keep `WHATS_NEW.md` current for every user-visible change. Record work under
+  `Unreleased` as it lands, including changes that have not shipped, and move those
+  entries into the matching version section when a version is released.
+- Use `roadmap.md` as the living development sequence. Update it when phase scope,
+  dependencies, status, or exit criteria change, and never mark a phase complete
+  without the evidence required by its exit criteria.
+- Use `ruff` for lint/format and `pytest` for tests.
+- Keep dependency versions bounded and test the exact NWB/PyNWB/NDX combination.
+
+## Standard commands
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e '.[dev]'
+.venv/bin/python -m pytest
+.venv/bin/python -m ruff check .
+.venv/bin/python -m ruff format --check .
+.venv/bin/python -m driftless_photometry --demo
+```
+
+On Windows, replace `.venv/bin/python` with `.venv\Scripts\python.exe`.
+
+## Definition of done
+
+A step is complete only when its automated tests pass, relevant validation succeeds,
+failure behavior is surfaced, documentation reflects the behavior, and no unrelated
+user files were changed. A simulator passing is not proof that physical hardware has
+been validated.

driftless_bundle_photometry-0.2.1/CLAUDE.md

@@ -0,0 +1,185 @@
+# Driftless Bundle Photometry — Agent Contract
+
+`AGENTS.md` and `CLAUDE.md` must remain byte-for-byte identical. Any change to one
+must be copied to the other in the same commit. The test suite enforces this.
+
+## Mission
+
+Build a reliable, Python-based multichannel fiber-photometry acquisition system.
+The supported hardware target is Windows. macOS must support the simulator,
+replay, NWB writing/reading, analysis, and GUI demo; physical camera operation on
+macOS is best-effort only.
+
+The MATLAB applications, Arduino firmware, Bonsai files, and manual are historical
+design evidence. They are not specifications to port verbatim.
+
+## Scientific and product invariants
+
+- The primary workflow is photometry traces, not an imaging dashboard.
+- Camera imagery is used for calibration, focus, ROI placement, and diagnostics.
+- Support 1–9 circular fiber ROIs with stable IDs, labels, positions, and radii.
+  Each ROI maps to one animal/subject and one independently valid NWB file.
+- Support up to three configured excitation wavelengths: 405, 470, and 565 nm.
+- Normal acquisition interleaves exactly one excitation wavelength per exposure.
+  Do not combine wavelengths in one monochrome exposure unless a future hardware
+  design provides a validated unmixing mechanism.
+- The total camera frame rate is shared across enabled wavelengths.
+- Raw camera frames are optional. When retained, preserve original `uint16` values;
+  never normalize them per frame.
+- Preserve one original `uint16` camera reference for every wavelength observed,
+  even when full raw-frame retention is disabled. ROI-annotated display copies are
+  derived diagnostic images with fixed bit-depth scaling and never replace raw data.
+- Support four behavior TTL inputs and retain both rising and falling edges.
+- Never infer wavelength solely from frame parity/modulo. Persist an explicit
+  controller sequence and excitation identity for every camera exposure.
+- Preserve raw data. Corrections, fitted controls, dF/F, z-scores, and QC outputs
+  are separate derived datasets.
+- Live Absolute/dF/F views and per-wavelength visibility are presentation state.
+  Calculate dF/F baselines independently per ROI and wavelength, keep their window
+  explicit, and never overwrite raw samples with a display transformation.
+- Never silently drop data. Queue pressure, dropped frames, malformed device
+  messages, clock discontinuities, and writer failures must be observable.
+
+## Timing and controller contract
+
+The hardware controller is the deterministic timing authority. The intended design
+uses one clock for camera trigger/exposure records, excitation gates, and all TTL
+edges. Each exposure record includes a monotonic sequence number, wavelength,
+controller tick, and commanded intensity.
+
+The GUI must not directly bit-bang LEDs or use host scheduling for exposure-critical
+timing. The legacy Arduino Uno and firmware may be reused only after electrical and
+timing characterization. Prefer true DAC outputs (or a validated external DAC) for
+0–5 V intensity commands and separate digital LED gates.
+
+Every hardware command protocol must be versioned and include explicit HELLO/READY,
+configuration acknowledgement, ARM/START/STOP, error reporting, and safe LED-off
+behavior on disconnect or watchdog timeout.
+
+## Canonical data contract
+
+The final scientific artifacts are one self-contained NWB-HDF5 file per configured
+ROI/animal for each acquisition session. Temporary recovery journals/spools may be
+used during acquisition, but they are not the canonical deliverables. Shared timing,
+TTL, exposure, system-event, calibration, and optional raw-frame records are copied
+into every ROI file so each file is independently interpretable.
+
+Use a hybrid of core NWB and `ndx-fiber-photometry`:
+
+- `NWBFile`, per-ROI `Subject`, `DeviceModel`, and `Device`: subject, session, and
+  hardware provenance.
+- `ndx-fiber-photometry`/`ndx-ophys-devices`: fibers, indicators, excitation
+  sources, photodetector, filters, commanded voltage, and per-wavelength response
+  series.
+- One raw `FiberPhotometryResponseSeries` per enabled wavelength in each file,
+  shaped `[time, 1]`, with explicit timestamps.
+- Core ROI table, calibration image, and per-wavelength camera references: the
+  authoritative circular camera-space ROI represented by that file, plus derived
+  fixed-scale RGB views with the ROI outlined.
+- Core `ImageSeries`: optional embedded lossless chronological `uint16` frames.
+- Core `EventsTable`: TTL edges, camera exposures, excitation events, dropped frames,
+  and system events.
+- `invalid_times`/`TimeIntervals`: bad continuous spans.
+- Processing modules: immutable derived traces and QC.
+- A versioned complete settings snapshot: session metadata, camera/controller and
+  channel settings, display preferences, and all configured ROIs. Embed the snapshot
+  in every per-ROI file so any one current-format NWB can restore the whole setup;
+  legacy imports must identify fields that were not historically persisted.
+
+Use NWB seconds on a shared session time base and preserve raw camera frame IDs and
+controller ticks for forensic reconstruction. Use stable `fiber_id` values to map
+camera ROIs to fiber-photometry table rows.
+
+Write every output to a partial path, drain and close all writers, validate, reopen
+and verify counts, then atomically promote each partial only after the complete ROI
+file set passes validation. Never label an unvalidated partial file as complete.
+
+## Architecture boundaries
+
+- `config`: validated immutable session/camera/channel/ROI/TTL configuration.
+- `domain`: typed frames, events, samples, and result records.
+- `timing`: wavelength schedules, tick unwrapping, and clock mapping.
+- `roi`: circular masks, hardware crop calculation, and signal extraction.
+- `hardware.camera`: camera interface; simulator and Thorlabs implementations.
+- `hardware.controller`: controller interface, protocol, and serial implementation.
+- `acquisition`: explicit state machine and coordination; no GUI dependencies.
+- `storage`: append-safe spool/recovery and NWB finalization/validation.
+- `gui`: PySide6/pyqtgraph presentation; communicates with workers through signals.
+
+Device-owning objects have one owner thread. HDF5/NWB writes have one writer owner.
+Use bounded queues. The GUI thread must never poll hardware, write frames, or block on
+acquisition loops.
+Live plots may window and aggregate for display, but this must be explicitly
+display-only. Point count must remain bounded by screen resolution rather than session
+duration, brief extrema must remain visible, and acquired or stored samples must never
+be discarded by a rendering optimization.
+
+State transitions are explicit:
+
+`DISCONNECTED -> READY -> CALIBRATING -> ARMED -> RECORDING -> DRAINING -> READY`
+
+`ERROR` is reachable from every active state, with deterministic cleanup and LEDs
+off. Invalid transitions raise errors rather than being ignored.
+
+## Development gates
+
+Work in order and do not advance past a failing gate:
+
+1. Domain/config/timing/ROI unit tests.
+2. Tiny golden NWB fixture: round-trip, PyNWB validation, NWB Inspector, and exact
+   frame/trace/event count checks.
+3. Headless simulator and acquisition pipeline with bounded queues and recovery.
+4. Fault tests: stop, queue full, disk error, malformed controller data, dropped
+   frame, camera loss, and clock rollover.
+5. GUI demo backed by the same headless services.
+6. Windows camera/controller integration and bench characterization.
+7. Packaging and clean-machine smoke tests.
+
+Hardware-dependent work must have a simulator/replay test path. Do not claim camera
+or electrical validation without the physical hardware and measurements.
+
+## Code and repository rules
+
+- Target Python 3.11–3.13 and use type annotations throughout.
+- Prefer small pure functions and dependency-injected interfaces.
+- Use Pydantic for persisted user/session configuration and dataclasses for hot-path
+  runtime records.
+- Use NumPy arrays with explicit dtype and documented axis order `[y, x]` or
+  `[time, y, x]`.
+- Use `pathlib.Path`; never add machine-specific absolute paths.
+- Public behavior changes require tests. Bugs receive regression tests.
+- Keep optional hardware imports lazy so simulator mode works without vendor SDKs.
+- Before implementing or changing the Thorlabs camera adapter, read
+  `docs/thorlabs-camera-python-api.md`; it records the vendor API lifecycle, DBF
+  integration decisions, and the boundary between documented behavior and required
+  CS505MU bench validation.
+- Do not edit generated/vendor/legacy files unless the task explicitly targets them.
+- Do not commit recordings, build outputs, virtual environments, or secrets.
+- Keep `WHATS_NEW.md` current for every user-visible change. Record work under
+  `Unreleased` as it lands, including changes that have not shipped, and move those
+  entries into the matching version section when a version is released.
+- Use `roadmap.md` as the living development sequence. Update it when phase scope,
+  dependencies, status, or exit criteria change, and never mark a phase complete
+  without the evidence required by its exit criteria.
+- Use `ruff` for lint/format and `pytest` for tests.
+- Keep dependency versions bounded and test the exact NWB/PyNWB/NDX combination.
+
+## Standard commands
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e '.[dev]'
+.venv/bin/python -m pytest
+.venv/bin/python -m ruff check .
+.venv/bin/python -m ruff format --check .
+.venv/bin/python -m driftless_photometry --demo
+```
+
+On Windows, replace `.venv/bin/python` with `.venv\Scripts\python.exe`.
+
+## Definition of done
+
+A step is complete only when its automated tests pass, relevant validation succeeds,
+failure behavior is surfaced, documentation reflects the behavior, and no unrelated
+user files were changed. A simulator passing is not proof that physical hardware has
+been validated.