ADR-0016: Keep public contracts versioned and integrations optional¶

• 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¶

Internal refactors and dependency updates can change external behavior without changing command names. Users should not install every integration to use deterministic CSV/JSON workflows.

Decision¶

Document supported top-level Python exports, CLI/MCP schemas, artifact layouts and DatasetSpec versions. Protect them with reviewed golden catalogs and immutable prior-release fixtures; do not regenerate fixtures merely to hide a regression.

Keep base deterministic CSV/JSON installation separate from optional Parquet, MCP, database and provider extras. Test installed wheels and minimum/latest dependency profiles on supported CPython versions. A declared version range alone is not support evidence; provider adapter maturity is separate from the stability of its neutral contract.

Alternatives and consequences¶

Treating every internal module as public prevents refactoring. Bundling all SDKs enlarges installation/security cost. A lockfile is tested-environment evidence, not a future-version guarantee. Speculative dependency caps are not justified without a reproduced incompatibility.

Evidence¶

Sources: stability, runtime support, dependency compatibility. Executable anchors: contract fixtures, previous release, installed package.

Revisit when¶

Removing an extra/runtime/export or changing defaults requires the documented compatibility/migration process.