// SPDX-License-Identifier: CC-BY-SA-4.0
= A2ML Specification Lineage
:toc:
:icons: font

This file is the *single source of truth* for which A2ML specification is
current and how prior versions relate. It implements the estate lineage
convention: one `SPEC.adoc` (current normative) + `archive/` (frozen prior
versions) + this `VERSIONS.adoc` (lineage + era).

== Current Normative Spec

[cols="1,3"]
|===
| Spec     | `SPEC.adoc`
| Version  | *1.1.0*
| Status   | Stable
| Era      | v1
| Date     | 2026-06-03
|===

`SPEC.adoc` is the *only* normative A2ML specification. Any other spec-shaped
file in this directory tree is either a frozen archive (under `archive/`) or a
supporting document (under `docs/`).

== Era Labels

An *era* is a major lineage band. Additive changes stay within an era and bump
the MINOR version; an era change is a breaking MAJOR bump.

[cols="1,1,3",options="header"]
|===
| Era | Versions | Meaning
| v0  | 0.x      | Pre-stable drafts. Surface grammar and typed-core outline only.
| v1  | 1.x      | Stable. Typed core with decidable proofs, modes, profiles, base
                   record vocabulary, citation primitives, canonical hashing.
| v2  | —        | *Roadmap heading only.* Reserved for a future breaking change
                   (e.g. surface-grammar incompatibility). No v2 work is planned.
|===

== Lineage

[cols="1,1,2,3",options="header"]
|===
| Version | Era | Location | Notes

| 0.x draft | v0 | `archive/SPEC-v0-draft.adoc` (+ `.a2ml`) | Original draft. Frozen.
| 1.0.0     | v1 | `archive/SPEC-v1.0.0.adoc`               | First stable. Frozen.
| *1.1.0*   | v1 | `SPEC.adoc`                              | *Current normative.* Additive over 1.0.0.
|===

=== 1.0.0 → 1.1.0 (additive, same era)

A2ML 1.1.0 is strictly additive: every 1.0-conforming document is a
1.1-conforming document. New surface introduced in 1.1 is inert until a profile
selects it. The additions are:

* Profile mechanism (`@profile`, `@profile-def`, registry).
* Base record vocabulary (`@record`) — the anti-desync primitive.
* Citation primitives (`@cite`, `@rationale`, `@origin`, `@source_span`,
  `@canonical_node`).
* Canonical hash form; reserved signing.

See `SPEC.adoc` Appendix B for the precise change log.

== Versioning Rules

* *SemVer for specs.* Additive surface, new profiles, and new invariants that do
  not invalidate prior-conforming documents are MINOR bumps. Breaking changes are
  MAJOR (and an era change).
* *One home per spec.* The current spec is always `SPEC.adoc`. Superseding a
  version means: copy the outgoing `SPEC.adoc` to `archive/SPEC-vX.Y.Z.adoc`, add
  a FROZEN banner, write the new `SPEC.adoc`, and add a row to the Lineage table
  above.
* *No duplicated normative text.* Archived specs are frozen and non-normative;
  they exist for lineage and diffing only.

== Release Notes

Per-version release notes live alongside this file:

* `RELEASE-NOTES-v0.1.0.adoc`, `-v0.5.0.adoc`, `-v0.6.0.adoc`
* `RELEASE-NOTES-v1.0.0.adoc`
* `RELEASE-NOTES-v1.1.0.adoc`
