# ADR-0001 — nirs4all connector ownership

- Status: **Accepted**
- Date: 2026-05-28
- Tags: `connectors`, `nirs4all`, `nirs4all-io`, `scope`, `phase-2-gate`

## Context

Three documents currently claim ownership of the bridge between
`nirs4all`'s `SpectroDataset` and `dag-ml-data`'s
`CoordinatorDataPlanEnvelope`:

1. **`dag-ml-data/docs/ROADMAP.md` Phase 4 "nirs4all Connector"** — declares
   a `SpectroDataset` connector, dense signal representations and
   compatibility tests as part of `dag-ml-data`.
2. **`nirs4all-io/docs/REDESIGN_FORMATS_AND_IO.md` Appendix I** — describes
   `nirs4all-io` as the dataset-assembly bridge that materializes
   `SpectroDataset` from heterogeneous inputs and ultimately produces a
   `CoordinatorDataPlanEnvelope`.
3. **`dag-ml/docs/design/source/dag_ml_synthese.md`** — refers to
   `dag-ml-data` envelopes as the host-emitted contract that `dag-ml`
   consumes.

`nirs4all-io/docs/PHASE2_GATE.md` item 7 records the resulting blocker:
nobody knows who owns the conversion, so the connector is not buildable.

`dag-ml-data`'s `AGENTS.md` is unambiguous on what `dag-ml-data` does NOT
do: "Do not add NIRS-specific assumptions to core types." A
`SpectroDataset` connector that inspects NIRS-specific axes, source
descriptors or signal types would be exactly that violation.

## Decision

**`nirs4all-io` owns the bridge.**

- `nirs4all-io` is the only crate allowed to consume `SpectroDataset` and
  emit a `CoordinatorDataPlanEnvelope`. It depends on `dag-ml-data` for
  the envelope shape; it does not modify `dag-ml-data`'s core types.
- `dag-ml-data` accepts io-emitted envelopes through the existing C ABI
  and JSON surfaces. It treats them as opaque, schema-validated contract
  artifacts — no NIRS-specific code paths, no `SpectroDataset` awareness.
- `dag-ml-data` ROADMAP Phase 4 is **descoped**. The "nirs4all connector"
  bullet is reclassified as out-of-scope for `dag-ml-data` and moved into
  `nirs4all-io`'s Phase 2 deliverables.
- `dag-ml` continues to consume envelopes through its `dag-ml-data`
  C ABI binding without knowing about `nirs4all`.

## Consequences

### Positive

- `dag-ml-data` retains its NIRS-agnostic invariant. Every other ML
  domain (omics, audio, time series, finance) can target the same
  envelope contract without seeing spectroscopy-shaped APIs.
- `nirs4all-io` becomes the natural home for `SpectroDataset`-aware
  knowledge: signal types, repetition handling, augmentation origin,
  fold layout. That knowledge already exists there.
- The PHASE2_GATE blocker is removed: `nirs4all-io` can implement
  the bridge against the (now public) `dag-ml-data` contract surface
  without coordination on `dag-ml-data` core changes.

### Negative / mitigations

- `nirs4all-io` carries the maintenance burden of cross-crate version
  alignment with `dag-ml-data`. Mitigation: the existing
  `scripts/validate_contracts.py` runs against the published envelope
  schema digest in both repos, catching wire-shape drift before it
  reaches `nirs4all-io`.
- A NIRS-specific axis kind that has no parallel in other domains would
  still need a `dag-ml-data` core change to be representable. This ADR
  does not block such changes — it forbids `nirs4all-io`-specific
  business logic from leaking into `dag-ml-data`. The
  `AxisKind::Wavenumber` addition shipped alongside this ADR is the
  canonical example: it's a generic spectroscopy axis (used in IR
  spectroscopy, Raman, etc.), not a `SpectroDataset` representation
  detail, so it belongs in core.

## Implementation notes

This ADR is paired with:

- `AxisKind::Wavenumber` added to `crates/dag-ml-data-core/src/model.rs`
  — closes the structural blocker on `PHASE2_GATE` item 2 (`cm⁻¹` axis
  missing for IR/Raman spectroscopy).
- `docs/ROADMAP.md` Phase 4 status updated to "descoped, owned by
  `nirs4all-io`".

No `dag-ml-data` API change beyond `AxisKind::Wavenumber`. No
`dag-ml` change required. `nirs4all-io` should reference this ADR in
its own Phase 2 design when picking up the bridge.

## References

- `dag-ml-data/AGENTS.md` — `dag-ml-data` boundary (do not add
  NIRS-specific assumptions).
- `nirs4all-io/docs/REDESIGN_FORMATS_AND_IO.md` Appendix I — bridge
  scope.
- `nirs4all-io/docs/PHASE2_GATE.md` item 7 — blocker this ADR resolves.
- `dag-ml-data/docs/contracts/coordinator_data_plan_envelope.schema.json`
  — the v1 envelope contract `nirs4all-io` targets.