ADR-19: Multi-source unit vocabulary and derived-combo decision¶

Status: accepted (2026-06-13) Blocks: heterogeneous multi-source repetitions roadmap, phases D1–D8. Land BEFORE any D1–D8 schema change; gates the deferred public prediction-level decision.

Context¶

docs/HETEROGENEOUS_MULTISOURCE_REPETITIONS_ROADMAP.md extends the coordinator to pipelines where one physical sample carries several observations per source with asymmetric cardinalities across sources (e.g. A=2/B=3/C=2). Before any schema work (D1–D8), the unit vocabulary and the migration posture must be frozen so downstream phases share one set of terms and none of them silently promotes a breaking public prediction level. The core stays a coordinator: no feature-buffer materialization, no fitted-model internals; identities, relations, reducers, OOF/fold safety, selection, lineage and replay only.

Decision¶

Frozen vocabulary¶

These names are canonical for D1–D8 and follow-up work. Renames require an ADR-superseder.

Term	Meaning
`physical_sample`	Logical sample requested by the user; the leakage, target and default output unit. Owns all its source observations and repetitions. Aligns with `SampleId`.
`source_sample`	Per-source view of one physical sample (its observations within a single source). Intermediate domain for source-aware models/late fusion; not a public prediction level in the mainline.
`observation`	One physical row/acquisition in one source. Aligns with `ObservationId`; many observations may share one `physical_sample`.
`combo`	Derived observation/unit built by combining one observation (or aligned tuple) per source for the same physical sample. Stored relation-backed with `component_observation_ids` and `origin_sample_id`.
`EntityUnitLevel`	Internal enum naming the unit domain of a relation row, port, reducer or view: `physical_sample`, `source_sample`, `observation`, `combo`. Additive Rust type and schema vocabulary; distinct from the public `PredictionLevel`.
`PredictionUnitId`	Stable identity of a non-sample prediction row (already used for target/group caches). Carries derived/relation unit ids for combos without adding a public combo prediction level.
`ReductionPlan`	Contract for moving values across unit levels/axes (`role`, `axis`, `input_unit_level`, `output_unit_level`, `method`, `weight_source`). A `combo`/`observation -> physical_sample` reduction is mandatory for any row-multiplying representation to yield sample output.
`RepresentationPlan`	Contract for a host-built feature representation (aggregate, cartesian, Monte-Carlo cartesian, stack fixed, stack padded/masked) plus the relation delta, replay manifest, cardinality contract and missing-source policy it emits. Core plans contracts and host handles only.
`FitInfluencePolicy`	Contract for how per-sample influence is enforced at fit time (`auto`, `uniform_rows`, `equal_sample_influence`, `resample_equalized`, `backend_loss_weight`, `scorer_only`, `strict_weight_support`). Distinct from `AggregationWeights`: influence is a fit contract, not an aggregation weight.

Mainline: combo is a derived observation, not a public prediction level¶

In the mainline implementation (D1–D8) a combo is a relation-backed derived observation/unit. The public prediction-cache levels stay observation, sample, target, group; policy::PredictionLevel gains no combo or source_sample variant. Cartesian/Monte-Carlo training, combo-to-sample reducers, replay and audit operate through the relation table (component_observation_ids, origin_sample_id) and the existing sample-level OOF/aggregation paths. Final public output remains sample-level.

Deferred gate: first-class public combo / source_sample levels¶

Promoting combo and/or source_sample to first-class public PredictionLevel / PredictionUnitId values is deferred until a separate ADR explicitly approves the public-contract change. It is needed only when a downstream public prediction cache, selector or meta-model consumes combo/source rows directly. Approval must carry: cache/schema migration notes; an ABI/binding impact review across prediction-cache metadata schemas, PredictionBlock, JSON fixtures, CLI/Wasm validation, Python bindings and the C ABI snapshot; and compliance with ADR-02 and ADR-14 (versioning, dual-read or migration edge, CHANGELOG, negative fixtures). Until then the relation-backed meta_row_domain=combo path covers combo meta-models without a public combo cache.

ADR-02 migration checklist (this feature)¶

Every D1–D7 phase that changes a public type applies ADR-02 in that same phase (D8 audits coherence; it is not a catch-up phase):

Optional fields first — new relation/port/edge/reducer/selection/cache fields land as Option<T> with a documented default; v1 readers ignore unknown fields per additionalProperties.
Defaults / dual-read — defaults reproduce current sample-level behavior; relation-aware validation is stricter only when relation metadata is present; old fixtures still validate or are dual-read migrated.
Fixture update — the schema JSON, local fixture and conformance pack move with the Rust type; cross-repo parity is re-checked with DAG_ML_DATA_REPO when shared contracts change.
CHANGELOG entry — every wire-shape change is recorded under ADR-02 (and ADR-14 for any deprecation).
C ABI decision — each phase explicitly records “ABI touched (bump abi_snapshot.v1.json + dag_ml.h + tests)” or “ABI not touched”; relation/prediction-unit tables cross the ABI only if the deferred first-class-combo gate is later approved.

Consequences¶

Downstream phases use derived-observation combos by default; the first-class public combo level is isolated as one deferred public-contract decision.
The vocabulary is surfaced in docs/COORDINATOR_SPEC.md, docs/ARCHITECTURE.md and docs/contracts/README.md so schema and Rust work share one glossary.
The roadmap’s public-contract matrix plus this per-phase ADR-02 checklist are the audit basis for D8.

Risk¶

A premature first-class combo level would force a breaking prediction-cache/ABI migration. Mitigation: the relation-backed mainline plus the explicit deferred gate keep that change opt-in and reviewed.