# Release readiness — v0.1.0-alpha

**Target:** snapshot `origin/develop` as a publishable, merge-ready baseline.
**Version:** v0.1.0-alpha (unless JFW changes it).

## Stable APIs (semver — no breaking changes in patch/minor)

These are the validated production paths.  A user following the tutorial
(`docs/TUTORIAL.md`) stays entirely inside this surface.

| API surface | Entry point | Validated |
|---|---|---|
| OpenCV stereo path | `api.calibration.fit_opencv_stereo_from_image_dirs` | ✅ slow tests |
| Ray2D corner refinement | `eval.predictors.predict_charuco_points` | ✅ benchmark |
| Central stereo rayfield | `api.calibration.fit_stereo_central_rayfield_from_image_dirs` | ✅ slow tests |
| Non-central Zernike origin field | `calibration.fit_stereo_zernike_origin_field` | ✅ benchmark |
| Model import / export | `api.model_io.{save,load}_stereo_central_rayfield` | ✅ round-trip test |
| Reconstruction diagnostics | `metrics.reconstruction_metrics.reconstruct_points_central_stereo` | ✅ benchmark |

## Advanced APIs (stable interface, expert use)

These are validated but require domain knowledge (optical models, gauge
conventions, parameter layout).  Breaking changes may happen after deprecation
notice.

| API surface | Entry point |
|---|---|
| Physical model selection | `physics.model_selection.fit_physical_model_to_rayfield` |
| CMO physical model | `physics.cmo_physical.fit_cmo_physical_stereo_model_to_rayfields` |
| CMO telecentric model | `physics.cmo_physical.fit_cmo_telecentric_model_to_rayfields` |
| CMO warped model | `physics.cmo_physical.fit_cmo_warped_model_to_rayfields` |
| Schur diagnostics | `optical_ba.regularized_ba` |
| Paper reproduction helpers | `benchmarks/`, `synthetic/` |

## Experimental APIs (no stability promise)

These exist as scaffolding for future work.  Signatures, parameter layouts,
and return types will change without notice.

| API surface | Status |
|---|---|
| N-camera facades (`api.calibration.calibrate(cameras=...)`) | Routes only `("left","right")`; other topologies raise `NotImplementedError` |
| `MultiCameraCharucoObservationSet` | Container only; real N-rayfield BA not implemented |
| `MultiCameraZernikeRayField` | Container only |
| `CMOTelecentricNModel` | Wraps stereo model via `from_stereo()` |
| `fit_zernike_rayfields_from_multi_camera_observations` | Routes only `("left","right")` |
| N-camera oracles / simulators | Benchmark scaffolding only |
| `optical_ba/` scripts | Paper-specific, not general-purpose |

**Explicit non-goals for v0.1.0-alpha:**
- True N-camera bundle adjustment (Phase 2 — specification exists, not implemented)
- Shared-rig SE(3) constraints across >2 channels
- Production-grade multi-camera calibration from real images
- GUI / web dashboard

## Paper-only code

This code exists to reproduce the CMO paper.  It is not part of the library
API and may use hard-coded paths, deprecated helpers, or paper-specific
conventions.

| Location | Purpose |
|---|---|
| `paper/cmo/` | Manuscript source, build scripts, standalone figure generators |
| `docs/assets/pycaso_real_data/` | JSON/NPZ artefacts for paper figures |
| `examples/notebooks/09_pycaso_real_data.py` | Full paper analysis walkthrough |
| `examples/notebooks/generate_fig_*.py` | Standalone figure generators |

## Quality gates (all passing @ 2026-05-24)

| Gate | Command | Status |
|---|---|---|
| Lint | `rtk .venv/bin/python -m ruff check src/` | 0 errors |
| Docstring contract | `rtk .venv/bin/python examples/notebooks/check_docstring_params.py` | 0 alarms, 88 files, wired into CI |
| Fast tests | `rtk .venv/bin/python -m pytest` | 159 passed, 39 deselected |
| Slow tests | `rtk .venv/bin/python -m pytest -m slow` | 39 passed, 0 failures |
| Doc coverage | `100%` (425/425 public functions) | ✅ |

## Known heavy artefacts (audit 2026-05-24 — 234 MB total)

| Artefact | Size | Strategy |
|---|---|---|
| `docs/assets/pycaso_real_data/schur_ba/*.npz` (available on Zenodo: https://doi.org/10.5281/zenodo.20369312) | 140 MB (6 files × ~24 MB) | Archived on Zenodo — DOI: 10.5281/zenodo.20369312 — regeneration artefacts, not primary data |
| `docs/assets/pycaso_real_data/specimen_*.npz` | 51 MB (3 files) | Keep (needed for paper figure reproduction) |
| `paper/cmo/figures/` | 15 MB | Keep (vector PDF versions are 2 MB, PNGs are paper legacy) |
| `paper/cmo/manuscript.pdf` | 8 MB | Keep (submission artefact) |
| `Biblio/*.pdf` | 6 MB (2 files) | Already local bibliography — keep |
| `examples/notebooks/*.ipynb` | 5 MB | Keep (Colab badges point to develop) |
| `dataset/` | 2 MB | Keep (needed for notebook walkthroughs) |
| `src/` | <1 MB | Keep |

**Recommendation:** move `docs/assets/pycaso_real_data/schur_ba/` (available on Zenodo: https://doi.org/10.5281/zenodo.20369312) to Zenodo
(140 MB would be removed) and add the DOI to the paper's data-availability
statement.  The 6 large NPZ files are Schur-BA snapshots reproducible from the
smaller `specimen_correspondences.npz` (12 MB) + the fitting code.  After
removal, the repo would be ~94 MB (after Zenodo archival).

## Pending before merge to main

1. Switch Colab links from `blob/develop/` to `blob/main/` (see CLAUDE.md § Colab branch hack)
2. Tag `v0.1.0-alpha` on the merge commit
3. Update `docs/START_HERE.md` to reflect that `develop` → `main` has happened
4. Archive paper artefacts on Zenodo and link from README