Add A2ML Record Dialect specification + conformance vectors

[hyperpolymath]

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.ai/code/session_0112RkdER2wtwHdNmbEhThUz

---

Generated by Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud