// SPDX-License-Identifier: CC-BY-SA-4.0
= A2ML v1.1.0 Release Notes
:toc:
:toclevels: 2
:icons: font

== Overview

A2ML v1.1.0 is a *stable, additive* release in era v1. Every v1.0-conforming
document is a v1.1-conforming document. The new surface introduced in v1.1 is
*inert under the base modes* and acquires meaning only when a profile selects it.

*Release Date:* 2026-06-03 +
*Era:* v1 +
*Supersedes:* v1.0.0 (now frozen under `archive/SPEC-v1.0.0.adoc`)

== Highlights

=== Profile Mechanism

A2ML now has a first-class, non-executable *profile* system.

* Declare a profile in a document with `@profile(id=ns/name)`.
* Define a profile with `@profile-def`, constraining exactly five axes: required
  sections, allowed/required directives, reference classes, and minimum
  attestation level.
* Profiles are resolved *offline and deterministically* against a hash-pinned
  registry (`profiles/REGISTRY.a2ml`) — SSOT + verifiable index, one home per
  profile, no duplicated normative text.
* Profiles can only *raise* the validation bar. They never grant execution,
  network, or filesystem capability.

See `SPEC.adoc` §8.

=== Base Record Vocabulary — the anti-desync primitive

One neutral shape, `@record`, for "a thing that can be identified, located,
attributed, and integrity-checked": `id`, `source_span`, `canonical_node`
(OPTIONAL), `hash` (sha256), `provenance{author, tool, kind∈{human,ai,mechanical},
agent?}`, `timestamp`, `artefact_ref`, `profile_decl` (OPTIONAL).

Downstream record formats reuse this vocabulary *verbatim* instead of
re-inventing identity/provenance/integrity — which is how artefacts stay in sync.
A2ML core defines the shape and names no consumer.

See `SPEC.adoc` §7.

=== Citation Primitives

`@cite`, `@rationale`, `@origin`, `@source_span`, `@canonical_node` are now
representable in base A2ML — but carry *no semantics by default*. They are
required and validated only under a citation profile, which A2ML core does not
ship (consumers define their own).

See `SPEC.adoc` §10.

=== Canonical Hash Form (hashing now, signing later)

* Opaque payload hash: `sha256:` over the exact preserved bytes, no normalisation.
* Document hash: `sha256:` over an RFC 8785 (JCS) canonical serialization of the
  typed core, with opaque payloads committed by reference. Stable under surface
  reformatting; sensitive to any structural change.
* Signing is *reserved and inert* in v1.1. What will be signed is already pinned:
  a `doc_hash`.

See `SPEC.adoc` §9.

=== Surface Additions

* Self-closing (inline) directive form: `@name(attrs)` on one line, no `@end`.
* `QualifiedId` (`ns/name`) for profile ids and reference classes.

== Lineage

This release applies the estate lineage convention to the `a2ml/` tree:

* `SPEC.adoc` — current normative spec (v1.1.0).
* `archive/SPEC-v1.0.0.adoc`, `archive/SPEC-v0-draft.adoc(.a2ml)` — frozen.
* `VERSIONS.adoc` — lineage + era (single source of truth for "what is current").

The README status line (previously "Draft, v0.6.0") is reconciled to
"Stable, v1.1.0".

== Compatibility

* *No breaking changes.* v1.1.0 is additive over v1.0.0.
* Implementations that do not resolve profiles MUST treat `@profile` as an inert
  annotation and MUST accept the v1.1 directives without error.

== Idris2 Core

The typed core gains decidable checks for the new surface:

* `src/A2ML/Profiles.idr` — profile ids, profile definitions, and decidable
  conformance of a document against an active profile.
* `src/A2ML/BaseVocab.idr` — base record vocabulary, the closed `provenance.kind`
  enum, and decidable base-record validity.

== What's Next

* A citation profile reference (authored by consumers, in their own repos).
* Signing semantics (trust roots, rotation) in a later minor version.

== License

See `LICENSE`.

---

*Released:* 2026-06-03 +
*Author:* Jonathan D.A. Jewell
