# ADR-17: Feature flag / cutover / rollback

**Status**: accepted (2026-05-29)
**Blocks**: workstream E (bridge), workstream F (parity)

## Context

Switching nirs4all's backend from the legacy `PipelineRunner` to dag-ml is a high-blast-radius change. It must be reversible without reinstalls or data migration, and users must be able to validate parity on their own data before trusting the switch.

## Decision

1. **Backend selector** — `nirs4all.run(..., backend="legacy" | "dag-ml" | "dual")`. Default is `"legacy"` until the G6 cutover gate, then the default flips to `"dag-ml"` in a minor release. The selector is also a workspace-level and env-level setting (`NIRS4ALL_BACKEND`).
2. **Dual-run mode** — `backend="dual"` runs **both** backends on the same input and diffs results within the ADR-01 tolerance ledger (per model class × metric). Mismatches beyond tolerance are **reported**, never silently reconciled. Dual mode ships for one release around cutover so users can validate on their own corpora.
3. **Legacy retention** — the legacy backend stays available behind `backend="legacy"` for **two releases** past the default flip, then is removed under the ADR-14 managed-debt policy (removal version recorded in the CHANGELOG).
4. **Rollback** — a user hitting a regression sets `backend="legacy"`: no reinstall, no data migration, no bundle rebuild. Bundles produced by either backend stay loadable for predict for the retention window (ties to ADR-02's bundle-readability SLA).
5. **Release notes** — the default-flip release links the compatibility ledger (ADR-01) and the migration guide.

## Consequences

- `nirs4all/api/run.py` gains the `backend` parameter and dispatches to the legacy runner or the bridge.
- Workstream F implements the dual-run diff against the tolerance ledger; the parity oracle (`tests/integration/parity/`) is the offline analogue.
- The migration guide (G6 deliverable) documents the flag, dual-run validation, and the rollback procedure.

## Risk

- Dual-run doubles compute for the validation release. It is opt-in and intended for a one-release validation window, not steady state. The docs say so explicitly.