Add A2ML Record Dialect specification + conformance vectors (#456)

## What & why

The seven canonical descriptile files that every estate repo deploys —
`STATE`, `META`, `ECOSYSTEM`, `AGENTIC`, `NEUROSYM`, `PLAYBOOK`,
`ANCHOR` — are written in a TOML-like `[section]` / `key = value`
surface. Until now that surface was **used but never specified**: ~435
files across the estate conformed to a grammar that existed only by
imitation. The existing `a2ml/SPEC.adoc` v1.1.0 specifies the *markup*
dialect (`@directive:` blocks) and an `@record`/`key: value` form, but
never the `[section]`/`key = value` record surface those files actually
use.

This PR fills that gap with a normative spec grounded in a **measured
survey of the deployed corpus** (1,798 `.a2ml` files), not the abandoned
`.scm`-era specs.

## Key design decision

The Record Dialect is **not a rival format** — it is a *second concrete
surface over the same typed core* as the markup dialect (`SPEC.adoc`
§3). It reuses, unchanged:

- validation modes (§4) → conformance classes R0/R1/R2
- base invariants (§6)
- the Base Record vocabulary (§7) — a base record can be written in
either surface and denotes the identical core structure
- the profile mechanism (§8) — the shipped `a2ml/*` profiles already
target this dialect
- the canonical hash form (§9)

One abstract model, two surfaces, **no third generation**. This is a
structural fix for the audit finding that three format generations
(`.scm` → TOML-like → A2ML profiles) coexist with no deprecation story.

## Contents

- **`a2ml/RECORD-DIALECT-SPEC.adoc`** — normative spec: RFC-2119
language, EBNF surface grammar (every production grounded in the
corpus), the record-tree data model, translation to the A2ML core,
R0/R1/R2 conformance classes, a **normative "Divergences from TOML"
table** (so an implementer can't conform by piping input through a stock
TOML parser), security considerations, IANA note, versioning, and a
worked example annotating a real deployed `STATE.a2ml`.
- **`a2ml/tests/record-dialect/`** — an executable conformance-vector
suite: **8 valid + 12 invalid** vectors, each minimal and mapped to one
spec clause + the class at which rejection is required; a **dogfooded**
record-dialect `MANIFEST.a2ml` indexing them; and a `README.adoc`.

## Status: Draft (deliberately)

Per the no-overclaim doctrine, the spec is marked `Draft` and states it
MUST NOT be cited as ratified until a reference reader greens the
vectors and a corpus conformance run is published. The path to `Stable`
is in the spec's **Appendix D**:

1. Reference reader — a second front-end over the existing core (not a
second core).
2. Green the vectors in real CI (no `|| echo SKIP`).
3. Corpus conformance run over all ~435 files; publish the residual
non-conforming set (e.g. the observed malformed timestamp
`"…ZT00:00:00Z"`) as findings.
4. Registry: the spec lives under the already-registered `a2ml/` home.
5. Owner ratification → bump `Status` to `Stable`.

## Registry regeneration — note for the reviewer

`.machine_readable/REGISTRY.a2ml` was regenerated with
`scripts/build-registry.sh` (the sanctioned generator — **not**
hand-edited). This updates the `a2ml/` home `source_hash` for the new
files and **incidentally re-pins the `k9-svc/` home hash**, which was
already drifted on `main` since `6df21b1` (the registry wasn't
regenerated after that commit changed `k9-svc` files).
`build-registry.sh --check` passes after regeneration. Flagging the
k9-svc rehash explicitly since it's unrelated to the spec itself.

## Guardrails respected

No licence content touched; no SPDX sweeps; new files carry correct SPDX
from birth per the repo's MPL-2.0 / CC-BY-SA-4.0 classification.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_0112RkdER2wtwHdNmbEhThUz

---
_Generated by [Claude
Code](https://claude.ai/code/session_0112RkdER2wtwHdNmbEhThUz)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/REGISTRY.a2ml

@@ -36,7 +36,7 @@ name = "A2ML — Attested Markup Language"
 stream = "foundation"
 home = "a2ml/"
 canonical_doc = "a2ml/README.adoc"
-source_hash = "sha256:9ed18e704be7f0f8f991edf9dcced013691e8b62c8d7cd5a27a3d7a91c0f27dd"
+source_hash = "sha256:7c51aab6fe43b04bc795647ae9b3d4813ca82f6182399c2987e17edfd50b36f5"
 route = "the typed/verified machine-readable document format"
 
 [[spec]]

a2ml/RECORD-DIALECT-SPEC.adoc

@@ -0,0 +1,166 @@
+# SPDX-License-Identifier: CC-BY-SA-4.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# MANIFEST.a2ml — conformance-vector index for the A2ML Record Dialect.
+# This file is itself a record-dialect document (spec RECORD-DIALECT-SPEC.adoc):
+# it dogfoods the format it indexes and MUST parse at R0.
+
+[metadata]
+suite = "a2ml-record-dialect"
+spec = "RECORD-DIALECT-SPEC.adoc"
+spec-version = "1.0.0"
+generated-by = "authored"
+last-updated = "2026-07-03"
+
+[legend]
+expect = "one of: parse | validate | reject"
+class = "lowest conformance class at which the expectation is REQUIRED (R0|R1|R2)"
+note = "spec section(s) the vector exercises"
+
+# ----------------------------------------------------------------------------
+# VALID vectors — MUST parse (R0); MUST validate (R1) where a profile is declared.
+# ----------------------------------------------------------------------------
+
+[[vector]]
+name = "valid/minimal.a2ml"
+expect = "parse"
+class = "R0"
+spec_section = "5.3, 4.1"
+note = "One section, one quoted-string entry — the smallest well-formed document."
+
+[[vector]]
+name = "valid/all-scalar-forms.a2ml"
+expect = "parse"
+class = "R0"
+spec_section = "4.1-4.5, D-3"
+note = "String, multi-line string, integer with _ separator, float with exponent, booleans."
+
+[[vector]]
+name = "valid/arrays-and-inline-tables.a2ml"
+expect = "parse"
+class = "R0"
+spec_section = "4.6, 4.7, 2.3"
+note = "Multi-line array with interior comment and trailing comma; array of inline tables."
+
+[[vector]]
+name = "valid/dotted-sections.a2ml"
+expect = "parse"
+class = "R0"
+spec_section = "5.4, 6, 7.1"
+note = "Dotted key-paths up to four segments; uppercase segment (categories.CHS)."
+
+[[vector]]
+name = "valid/array-of-tables.a2ml"
+expect = "parse"
+class = "R0"
+spec_section = "5.3, 6"
+note = "Repeated [[entry]] headers build an ordered array of tables."
+
+[[vector]]
+name = "valid/quoted-keys.a2ml"
+expect = "parse"
+class = "R0"
+spec_section = "5.5, 3"
+note = "Quoted key required for a key containing '-' as first char (\"--browser\")."
+
+[[vector]]
+name = "valid/comments-and-preamble.a2ml"
+expect = "parse"
+class = "R0"
+spec_section = "5.1, 2.3"
+note = "SPDX/copyright preamble comments; trailing comments after values and headers."
+
+[[vector]]
+name = "valid/state-profile.a2ml"
+expect = "validate"
+class = "R1"
+spec_section = "5.2, 9.5, 10"
+note = "Declares @profile(id=a2ml/state); carries the three required sections — validates."
+
+# ----------------------------------------------------------------------------
+# INVALID vectors — MUST be rejected at the stated class (and every class above).
+# ----------------------------------------------------------------------------
+
+[[vector]]
+name = "invalid/bare-string-value.a2ml"
+expect = "reject"
+class = "R0"
+spec_section = "4.8, D-2"
+note = "Unquoted non-numeric, non-boolean scalar (x = hello) — no bare strings."
+
+[[vector]]
+name = "invalid/single-quoted-string.a2ml"
+expect = "reject"
+class = "R0"
+spec_section = "D-5"
+note = "Single-quoted 'literal string' does not exist in the record dialect."
+
+[[vector]]
+name = "invalid/native-date.a2ml"
+expect = "reject"
+class = "R0"
+spec_section = "D-1, 4.8"
+note = "Unquoted date literal — dates are quoted strings, no native date-time."
+
+[[vector]]
+name = "invalid/hex-integer.a2ml"
+expect = "reject"
+class = "R0"
+spec_section = "D-3, 4.3"
+note = "0x/0o/0b integer bases are not part of the reduced number grammar."
+
+[[vector]]
+name = "invalid/leading-dot-float.a2ml"
+expect = "reject"
+class = "R0"
+spec_section = "D-3, 4.4"
+note = "Leading-dot float (.5) is not valid; a float MUST have a leading digit."
+
+[[vector]]
+name = "invalid/triple-single-quote.a2ml"
+expect = "reject"
+class = "R0"
+spec_section = "D-5, 4.2"
+note = "'''…''' multi-line literal string does not exist; only \"\"\"…\"\"\"."
+
+[[vector]]
+name = "invalid/unterminated-string.a2ml"
+expect = "reject"
+class = "R0"
+spec_section = "4.1"
+note = "String value with no closing quote before end of line."
+
+[[vector]]
+name = "invalid/profile-after-section.a2ml"
+expect = "reject"
+class = "R1"
+spec_section = "5.1, 5.2"
+note = "@profile declared after a section header — all declarations MUST precede sections."
+
+[[vector]]
+name = "invalid/duplicate-key.a2ml"
+expect = "reject"
+class = "R1"
+spec_section = "9.1, D-7"
+note = "Same key twice in one table — warning at R0, error at R1."
+
+[[vector]]
+name = "invalid/reopened-section.a2ml"
+expect = "reject"
+class = "R1"
+spec_section = "9.2, D-7"
+note = "A standard section path opened twice ([a] … [a])."
+
+[[vector]]
+name = "invalid/unknown-directive.a2ml"
+expect = "reject"
+class = "R1"
+spec_section = "10"
+note = "A base document permits no directive but @profile; @frobnicate is rejected."
+
+[[vector]]
+name = "invalid/state-missing-required-section.a2ml"
+expect = "reject"
+class = "R1"
+spec_section = "9.5, 10"
+note = "Declares a2ml/state but omits the required maintenance-status section."

a2ml/tests/record-dialect/MANIFEST.a2ml

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+= A2ML Record Dialect — Conformance Vectors
+:icons: font
+:toc: macro
+
+toc::[]
+
+This directory is the *normative test* for
+link:../../RECORD-DIALECT-SPEC.adoc[the A2ML Record Dialect specification]. A
+reference validator conforms to a class (R0/R1/R2, spec §1.4) if and only if it
+produces the expected verdict for every vector whose required class is at or below
+the class under test.
+
+== Layout
+
+[cols="1,3",options="header"]
+|===
+| Path | Contents
+
+| `vectors/valid/`
+| Documents that MUST parse (R0) and, where they declare a profile, MUST validate
+  (R1) against the definitions in `a2ml/profiles/`.
+
+| `vectors/invalid/`
+| Documents that MUST be rejected. Each is paired in `MANIFEST.a2ml` with the spec
+  clause it violates and the lowest class (R0/R1/R2) at which rejection is
+  REQUIRED.
+
+| `MANIFEST.a2ml`
+| The machine-readable index of every vector: expected verdict, required class,
+  and the spec section exercised. It is itself a record-dialect document, so it
+  doubles as a valid vector (the suite dogfoods the dialect).
+|===
+
+== Expected-verdict model
+
+Each vector has an `expect` of `parse`, `validate`, or `reject`:
+
+* `parse` — R0 MUST build a record tree without error. (Profile-free or
+  profile-inert.)
+* `validate` — R0 MUST parse AND R1 MUST validate against the declared profile.
+* `reject` — the validator MUST error at or below `class`; a validator at a higher
+  class MUST also reject (obligations accumulate downward, spec §1.4).
+
+A vector marked `reject` at `class = R0` is a *syntax* error every conforming
+implementation catches. A vector marked `reject` at `class = R1` is a
+*well-formedness / profile* error that a pure R0 reader is permitted to accept
+(with a warning where the spec says so).
+
+== Running the suite (once a reference validator exists)
+
+The validator is not yet wired (spec Appendix D). The intended contract, so the
+suite is runnable the moment the reader lands:
+
+[source,sh]
+----
+# For each valid vector: exit 0, tree emitted.
+# For each invalid vector: non-zero exit, error cites the manifest's clause.
+a2ml validate --dialect record --class R1 vectors/valid/<name>.a2ml     # → 0
+a2ml validate --dialect record --class R1 vectors/invalid/<name>.a2ml   # → non-0
+----
+
+The CI job that drives this MUST fail loudly on any mismatch — never the
+`|| echo SKIP` pattern. A green run of this suite is the precondition (spec §15,
+Appendix D) for moving the specification from `Draft` to `Stable`.
+
+== Adding a vector
+
+. Add the `.a2ml` file under `valid/` or `invalid/`.
+. Add a matching `[[vector]]` block to `MANIFEST.a2ml` with `name`, `expect`,
+  `class`, `spec_section`, and a one-line `note`.
+. Keep each vector minimal — it should exercise exactly one clause so a failure
+  localises to one rule.

a2ml/tests/record-dialect/README.adoc

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
+# INVALID (R0): bare (unquoted) string value. Spec 4.8 / D-2 — no bare strings.
+[metadata]
+name = hello

a2ml/tests/record-dialect/vectors/invalid/bare-string-value.a2ml

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: MPL-2.0
+# INVALID (R1): duplicate key in one table. Spec 9.1 / D-7 — warn at R0, error at R1.
+[metadata]
+version = "1.0.0"
+version = "2.0.0"

a2ml/tests/record-dialect/vectors/invalid/duplicate-key.a2ml

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
+# INVALID (R0): hexadecimal integer. Spec D-3 / 4.3 — decimal only, no 0x/0o/0b.
+[metadata]
+mask = 0xFF

a2ml/tests/record-dialect/vectors/invalid/hex-integer.a2ml

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
+# INVALID (R0): leading-dot float. Spec D-3 / 4.4 — a float MUST have a leading digit.
+[metadata]
+ratio = .5

a2ml/tests/record-dialect/vectors/invalid/leading-dot-float.a2ml

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
+# INVALID (R0): unquoted native date literal. Spec D-1 / 4.8 — dates are quoted strings.
+[metadata]
+last-updated = 2026-05-15

a2ml/tests/record-dialect/vectors/invalid/native-date.a2ml

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MPL-2.0
+# INVALID (R1): @profile declared after a section header. Spec 5.1 / 5.2 —
+# all profile declarations MUST precede the first section.
+[metadata]
+name = "example"
+
+@profile(id=a2ml/state)