ADR-0010: Semver and Compatibility Matrix Versioning
Date: 2026-06-10
Context
The platform has many versioned entities: Adapters, Modules, Archetypes, scaffolders, Capabilities, Contracts, Manifest schemas, the platform itself. Versioning strategy affects reproducibility, upgrades, compatibility checking, and customer trust.
A central monolithic compatibility matrix is brittle (one file, one maintainer). A distributed matrix where each Adapter declares its own compatibility is more maintainable.
Decision
Versioning style by entity:
| Entity | Style | Reason |
|---|---|---|
| Adapter | semver | matches the underlying library’s versioning |
| Module | semver | platform-managed, can have patch/minor/major changes |
| Archetype | semver | platform-managed templates |
| Scaffolder | semver | external tool’s own versioning |
| Capability | integer (v1, v2) | interface — major changes only |
| Contract | integer (v1, v2) | interface — major changes only |
| Manifest schema | integer (v1, v2) | structure — major changes only |
| Archetype Spec schema | integer (v1, v2) | structure — major changes only |
| Platform | semver | overall release |
Compatibility is a distributed matrix. Each Adapter and Module Manifest declares its compatibility block: language runtime versions, scaffolder versions, required Adapters, compatible Adapters with version ranges, incompatible Adapters, and known-good combinations. The Compatibility Validator walks these collectively.
Rationale
- Distributed matrix scales: as Adapters are added, each contributes its piece of compatibility data.
- Interface entities (Capabilities, Contracts) use integer versions because there is no concept of a minor or patch change to an interface — any change is breaking.
- Generated apps record exact versions used (Cargo.lock-style), enabling reproducible regeneration.
- The Manifest schema version is separate from the Adapter version: schema and library evolve independently.
Consequences
- Manifest authoring includes compatibility declaration as a required task.
- The Compatibility Validator’s logic walks a graph of declarations.
- Conflict resolution may require surfacing known-good combinations from one Adapter to influence another’s declared compatibility.