ADR-0004: Separate observations, hypotheses and executable DatasetSpec¶

• Status: Accepted — retrospective baseline.
• Recorded: 2026-09-29. This is the recording date, not an invented original approval date.
• Authority and implementation boundaries: see Evidence below and the register conventions.

Context¶

An observed pattern is not a universal business rule or authorization. Persisted contracts also outlive the package version that created them.

Decision¶

DatasetProfile carries safe evidence; inferred relationships/rules retain confidence and review status. DatasetSpec is the reviewed executable generation contract. A model proposal cannot promote its own evidence or approval.

Version DatasetSpec separately from the package. Missing legacy version means 1.0; explicitly support tested versions and reject unknown versions instead of guessing. Candidate 1.1 adds exact DECIMAL; do not silently downgrade it to FLOAT. Migrations produce newly reviewed specs, not in-place rewrites of old bundles.

Alternatives and consequences¶

Generating directly from arbitrary samples or free-form hypotheses collapses evidence and authority. Automatic forward-version interpretation hides incompatible semantics. Schema compatibility does not promise identical generated bytes.

Evidence¶

Sources: profiles and specs, schema compatibility, relational evidence contract. Executable anchors: DatasetSpec tests, profile/spec diagnostics.

Revisit when¶

New required fields, changed meanings or narrowed values require the documented schema and migration decision, not a fixture refresh alone.