diff --git a/README.adoc b/README.adoc index 34449f7..cb510da 100644 --- a/README.adoc +++ b/README.adoc @@ -5,6 +5,33 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 for documentation // SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell +[IMPORTANT] +==== +*The DEED format name and `.deed` extension are final, not A2ML.* Renamed +2026-09-03, ruled final. Its proposed grammar — syntax, semantics and +typechecking — is `deed/spec/DEED-GRAMMAR-SPEC.adoc` in +`hyperpolymath/standards` +(https://github.com/hyperpolymath/standards/pull/752[standards#752]). After it +merges, it will be the single normative source; this hub holds a pointer to it, +never a copy. + +DEED `.deed` documents use an *s-expression* format. There is no `key = value` +production and no `[section]` production; the only bracket is `(`. This syntax +statement does not apply to retained A2ML v1 material. The stale "TOML-like +key-value" wording is superseded for DEED — see +https://github.com/hyperpolymath/standards/pull/753[standards#753]. + +*This repository is to be renamed `deed-ecosystem`* and restructured to match +`k9-ecosystem` (tracked as estate task #77). That rename is the owner's trigger +and has deliberately not been performed here. + +*Naming discrepancy, unresolved:* this repository expands A2ML as "Attestation +Markup Language" (4 occurrences); `hyperpolymath/standards` expands it as +"Annotated Markup Language" (6 occurrences). Both are in current text. The +rename to DEED makes the question moot going forward, but the historical record +should settle on one expansion. +==== + `hyperpolymath/a2ml-ecosystem` coordinates implementations, tooling, CI integrations, examples, and conformance fixtures for A2ML. @@ -24,9 +51,15 @@ governance authority are pinned in the https://github.com/hyperpolymath/standard == Not Owned Here -The A2ML specification is owned by `hyperpolymath/standards`. This hub points -to `a2ml/SPEC.adoc` there; until the first standards tag is cut, the pin -is intentionally `TODO-tag`. +The format specification is owned by `hyperpolymath/standards` and is pending +until https://github.com/hyperpolymath/standards/pull/752[standards#752] merges. +This hub will then point to `deed/spec/DEED-GRAMMAR-SPEC.adoc` there -- see +link:spec/README.adoc[spec/README.adoc] for the pin and its history. + +The previous pointer, `a2ml/SPEC.adoc`, was correct when written but went stale +on 2026-08-28 when commit `24a12d6f` carved `a2ml/` out of `standards` into the +standalone `hyperpolymath/a2ml` repository. No release tag has been cut, so the +pin stays unset rather than pointing at a path that no longer exists. == Machine-Readable Layout diff --git a/deno/.machine_readable/ai/AI.a2ml b/deno/.machine_readable/ai/AI.a2ml index c683d30..58a9091 100644 --- a/deno/.machine_readable/ai/AI.a2ml +++ b/deno/.machine_readable/ai/AI.a2ml @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MPL-2.0 # AI Assistant Instructions diff --git a/deno/0-AI-MANIFEST.a2ml b/deno/0-AI-MANIFEST.a2ml index 41614b2..a96fb11 100644 --- a/deno/0-AI-MANIFEST.a2ml +++ b/deno/0-AI-MANIFEST.a2ml @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MPL-2.0 # ⚠️ STOP - CRITICAL READING REQUIRED **THIS FILE MUST BE READ FIRST BY ALL AI AGENTS** diff --git a/deno/examples/0.1-AI-MANIFEST.a2ml b/deno/examples/0.1-AI-MANIFEST.a2ml index 0d69c90..96399a0 100644 --- a/deno/examples/0.1-AI-MANIFEST.a2ml +++ b/deno/examples/0.1-AI-MANIFEST.a2ml @@ -1 +1,2 @@ +# SPDX-License-Identifier: MPL-2.0 # AI Manifest - Level 1: examples diff --git a/deno/verification/tests/0.2-AI-MANIFEST.a2ml b/deno/verification/tests/0.2-AI-MANIFEST.a2ml index 0008fcf..01e9a01 100644 --- a/deno/verification/tests/0.2-AI-MANIFEST.a2ml +++ b/deno/verification/tests/0.2-AI-MANIFEST.a2ml @@ -1 +1,2 @@ +# SPDX-License-Identifier: MPL-2.0 # AI Manifest - Level 1: tests diff --git a/ex/.machine_readable/anchors/ANCHOR.a2ml b/ex/.machine_readable/anchors/ANCHOR.a2ml index 7515b81..91f07d0 100644 --- a/ex/.machine_readable/anchors/ANCHOR.a2ml +++ b/ex/.machine_readable/anchors/ANCHOR.a2ml @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MPL-2.0 # ⚓ ANCHOR: a2ml_ex # This is the canonical authority for the a2ml_ex repository. diff --git a/gleam/.machine_readable/anchors/ANCHOR.a2ml b/gleam/.machine_readable/anchors/ANCHOR.a2ml index 7d03160..77b3560 100644 --- a/gleam/.machine_readable/anchors/ANCHOR.a2ml +++ b/gleam/.machine_readable/anchors/ANCHOR.a2ml @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MPL-2.0 # ⚓ ANCHOR: a2ml_gleam # This is the canonical authority for the a2ml_gleam repository. diff --git a/haskell/.machine_readable/ai/AI.a2ml b/haskell/.machine_readable/ai/AI.a2ml index c683d30..58a9091 100644 --- a/haskell/.machine_readable/ai/AI.a2ml +++ b/haskell/.machine_readable/ai/AI.a2ml @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MPL-2.0 # AI Assistant Instructions diff --git a/haskell/0-AI-MANIFEST.a2ml b/haskell/0-AI-MANIFEST.a2ml index c0d4864..afb753b 100644 --- a/haskell/0-AI-MANIFEST.a2ml +++ b/haskell/0-AI-MANIFEST.a2ml @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MPL-2.0 # ⚠️ STOP - CRITICAL READING REQUIRED **THIS FILE MUST BE READ FIRST BY ALL AI AGENTS** diff --git a/haskell/examples/0.1-AI-MANIFEST.a2ml b/haskell/examples/0.1-AI-MANIFEST.a2ml index 0d69c90..96399a0 100644 --- a/haskell/examples/0.1-AI-MANIFEST.a2ml +++ b/haskell/examples/0.1-AI-MANIFEST.a2ml @@ -1 +1,2 @@ +# SPDX-License-Identifier: MPL-2.0 # AI Manifest - Level 1: examples diff --git a/haskell/verification/tests/0.2-AI-MANIFEST.a2ml b/haskell/verification/tests/0.2-AI-MANIFEST.a2ml index 0008fcf..01e9a01 100644 --- a/haskell/verification/tests/0.2-AI-MANIFEST.a2ml +++ b/haskell/verification/tests/0.2-AI-MANIFEST.a2ml @@ -1 +1,2 @@ +# SPDX-License-Identifier: MPL-2.0 # AI Manifest - Level 1: tests diff --git a/rs/.machine_readable/ai/AI.a2ml b/rs/.machine_readable/ai/AI.a2ml index c683d30..58a9091 100644 --- a/rs/.machine_readable/ai/AI.a2ml +++ b/rs/.machine_readable/ai/AI.a2ml @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MPL-2.0 # AI Assistant Instructions diff --git a/rs/0-AI-MANIFEST.a2ml b/rs/0-AI-MANIFEST.a2ml index e1d3aa0..b994b38 100644 --- a/rs/0-AI-MANIFEST.a2ml +++ b/rs/0-AI-MANIFEST.a2ml @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MPL-2.0 # ⚠️ STOP - CRITICAL READING REQUIRED **THIS FILE MUST BE READ FIRST BY ALL AI AGENTS** diff --git a/rs/examples/0.1-AI-MANIFEST.a2ml b/rs/examples/0.1-AI-MANIFEST.a2ml index 0d69c90..96399a0 100644 --- a/rs/examples/0.1-AI-MANIFEST.a2ml +++ b/rs/examples/0.1-AI-MANIFEST.a2ml @@ -1 +1,2 @@ +# SPDX-License-Identifier: MPL-2.0 # AI Manifest - Level 1: examples diff --git a/rs/verification/tests/0.2-AI-MANIFEST.a2ml b/rs/verification/tests/0.2-AI-MANIFEST.a2ml index 0008fcf..01e9a01 100644 --- a/rs/verification/tests/0.2-AI-MANIFEST.a2ml +++ b/rs/verification/tests/0.2-AI-MANIFEST.a2ml @@ -1 +1,2 @@ +# SPDX-License-Identifier: MPL-2.0 # AI Manifest - Level 1: tests diff --git a/showcase/.machine_readable/6a2/STATE.a2ml b/showcase/.machine_readable/6a2/STATE.a2ml index c2a56fe..7f806e6 100644 --- a/showcase/.machine_readable/6a2/STATE.a2ml +++ b/showcase/.machine_readable/6a2/STATE.a2ml @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MPL-2.0 # STATE.a2ml — a2ml-showcase project = "a2ml-showcase" version = "0.1.0" diff --git a/showcase/.machine_readable/anchors/ANCHOR.a2ml b/showcase/.machine_readable/anchors/ANCHOR.a2ml index a622921..121e7cb 100644 --- a/showcase/.machine_readable/anchors/ANCHOR.a2ml +++ b/showcase/.machine_readable/anchors/ANCHOR.a2ml @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MPL-2.0 # ⚓ ANCHOR: a2ml-showcase # This is the canonical authority for the a2ml-showcase repository. diff --git a/spec/README.adoc b/spec/README.adoc index 53b9a6f..3e67efa 100644 --- a/spec/README.adoc +++ b/spec/README.adoc @@ -1,15 +1,62 @@ -= A2ML Specification Pointer += DEED Specification Pointer (formerly A2ML) // SPDX-License-Identifier: CC-BY-SA-4.0 -The A2ML specification is not owned in this coordination hub. +The format specification is not owned in this coordination hub. -Canonical upstream: +[IMPORTANT] +==== +*The DEED format name and `.deed` extension are final* — renamed from A2ML, +ruled final 2026-09-03. The proposed DEED grammar uses an *s-expression* +format: there is no `key = value` production and no `[section]` production; the +only bracket is `(`. This syntax statement does not apply to historical A2ML v1 +inputs. The stale "TOML-like key-value" wording is superseded for DEED. +==== + +== Canonical upstream * Repository: `hyperpolymath/standards` -* Path: `a2ml/SPEC.adoc` (typed core + markup surface, v1.1.0) -* Companion: `a2ml/RECORD-DIALECT-SPEC.adoc` (record surface for descriptiles, v1.0.0) -* Pin: `891b1ed6164478616cb3375f328c6487ccb13f80` (commit pin; no A2ML release tag cut yet) +* Path: `deed/spec/DEED-GRAMMAR-SPEC.adoc` — the proposed grammar (syntax, + semantics, typechecking), v0.1.0. Companion ABNF at `deed/spec/abnf/deed.abnf`. +* Status: landing in https://github.com/hyperpolymath/standards/pull/752[standards#752]. + Until that merges this path does not yet exist on `main`; the pin below is + deliberately left unset rather than pointed at a stale commit. + +== Why the previous pin was stale + +This file previously pinned: + + Repository: hyperpolymath/standards + Path: a2ml/SPEC.adoc (typed core + markup surface, v1.1.0) + Companion: a2ml/RECORD-DIALECT-SPEC.adoc + Pin: 891b1ed6164478616cb3375f328c6487ccb13f80 + +That pointer was *correct when written* — `a2ml/` did exist in `standards` at +commit `891b1ed6`. It was removed by `24a12d6f` (2026-08-28), *"carve-out: evict +a2ml, lol and the repo-guardian pair"*, which moved the v1 material into the +standalone `hyperpolymath/a2ml` repository. The satellite pointer was never +updated, so from that date this hub pointed at a path that no longer existed. + +The measured 0.2% descriptile conformance came from stale "TOML-like" wording +and files generated from it. A dangling upstream pointer is a separate +verification risk: while it dangles, nothing downstream can check itself +against the specification, and each consumer is free to invent its own idea of +the format. + +== Where the v1 material now lives + +* `hyperpolymath/a2ml` — the typed core (Idris2), `SPEC.adoc`, and the dialect + specifications. +* `RECORD-DIALECT-SPEC.adoc` retains its current status until + https://github.com/hyperpolymath/a2ml/pull/2[a2ml#2] merges; it is not yet + marked *SUPERSEDED*. +* `MANIFEST-DIALECT-SPEC.adoc` in that repository describes the `---`-delimited + frontmatter surface of `0-AI-MANIFEST.a2ml` (894 files, 100% conformant). Its + disposition under DEED is an *open question* for the owner — it is + deliberately not stamped. +* The existing `.a2ml` validator (`validate-action/validate-a2ml.sh`) and the + positive fixtures in `conformance/valid/` are historical v1 inputs, explicitly + non-DEED. No migration is required to make that distinction accurate. The corresponding governance authority is pinned in link:../.machine_readable/anchors/ANCHOR.a2ml[ANCHOR.a2ml]. diff --git a/validate-action/.machine_readable/ai/AI.a2ml b/validate-action/.machine_readable/ai/AI.a2ml index c683d30..58a9091 100644 --- a/validate-action/.machine_readable/ai/AI.a2ml +++ b/validate-action/.machine_readable/ai/AI.a2ml @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MPL-2.0 # AI Assistant Instructions diff --git a/validate-action/0-AI-MANIFEST.a2ml b/validate-action/0-AI-MANIFEST.a2ml index 9b64bd8..bb07fb4 100644 --- a/validate-action/0-AI-MANIFEST.a2ml +++ b/validate-action/0-AI-MANIFEST.a2ml @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: MPL-2.0 # ⚠️ STOP - CRITICAL READING REQUIRED **THIS FILE MUST BE READ FIRST BY ALL AI AGENTS** diff --git a/validate-action/examples/0.1-AI-MANIFEST.a2ml b/validate-action/examples/0.1-AI-MANIFEST.a2ml index 0d69c90..96399a0 100644 --- a/validate-action/examples/0.1-AI-MANIFEST.a2ml +++ b/validate-action/examples/0.1-AI-MANIFEST.a2ml @@ -1 +1,2 @@ +# SPDX-License-Identifier: MPL-2.0 # AI Manifest - Level 1: examples diff --git a/validate-action/verification/tests/0.2-AI-MANIFEST.a2ml b/validate-action/verification/tests/0.2-AI-MANIFEST.a2ml index 0008fcf..01e9a01 100644 --- a/validate-action/verification/tests/0.2-AI-MANIFEST.a2ml +++ b/validate-action/verification/tests/0.2-AI-MANIFEST.a2ml @@ -1 +1,2 @@ +# SPDX-License-Identifier: MPL-2.0 # AI Manifest - Level 1: tests