# ADR-01: Compatibility ledger semantics

**Status**: accepted (2026-05-28)
**Blocks**: workstream B (schema additions), workstream E (bridge), workstream F (parity validation)

## Context

The integration replaces nirs4all's `PipelineRunner` + `SpectroDataset` backend with `dag-ml` + `dag-ml-data`. "No regression" must be enforceable, not aspirational. Without a written ledger, every B/D/E task can succeed locally and still miss a public behavior — Codex's #1 pushback on roadmap v1.

## Decision

A `nirs4all/docs/compatibility.md` ledger is the single source of truth for what counts as parity. It enumerates every public API surface with one of the following states:

- **supported** — the bridge reproduces the behavior byte-identical (categorical) or within ADR-declared tolerance (numeric).
- **changed** — the behavior changes; an entry documents the diff, why, and the migration path.
- **deprecated** — kept working for two releases past G6; emits a deprecation warning carrying the target removal version per ADR-14.
- **refused-with-error** — explicitly unsupported; the bridge raises a typed error pointing at the migration ADR.
- **migration-path** — documented procedure to move a workspace / bundle / pipeline from legacy to dag-ml.

### Tolerance ledger

Numeric comparison tolerances are **per model class × per metric**:

| Model class | RMSE / MAE | R² | Notes |
|---|---|---|---|
| Linear (PLS, Ridge, OLS) | 1e-6 | 1e-6 | deterministic under fixed seed |
| Tree ensembles (RF, GBR) | 1e-3 | 1e-3 | seed-respecting but library-version-sensitive |
| Neural networks (NICON, custom TF/PT) | 1e-2 | 1e-2 | mini-batch shuffle + numerical reductions |

Bit-identical parity is **not a goal** (Codex hidden risk #4). Tolerance is set per (model class, metric) and pinned in the ledger.

### What counts as public API

- `nirs4all.run / predict / explain / retrain / session / generate` and their result objects (frozen since 0.9.0 per `nirs4all/CLAUDE.md`).
- The pipeline DSL keyword table in `nirs4all/CLAUDE.md`.
- Workspace SQLite/Parquet schemas, run manifest layout, `.n4a` bundle format.
- The `examples/reference/*.py` set — examples are API; a broken example is a user-visible regression (Codex hidden risk #5).
- The CLI subcommand surface (`nirs4all workspace | dataset | artifacts | config`).

## Consequences

- Every entry in `nirs4all/CLAUDE.md`'s keyword table needs a ledger row before workstream E (bridge) can ship.
- The parity oracle test set (`nirs4all/tests/integration/parity/`) is the executable arm of the ledger — keyword coverage is asserted in `test_parity_compiles.py`.
- The bridge raises a typed error referencing this ledger when called on a `refused-with-error` shape.
- The compatibility ledger is checked into nirs4all (not dag-ml) so it follows the consumer's release cycle.

## Open follow-ups

- Generate per-case "legacy-observed" parity manifests (Codex Phase-3 review actionable). A scripted run of every runnable parity case captures exact prediction count / variant count / fold-partition shape / best metric / score keys per case, committed alongside the ledger.