// SPDX-License-Identifier: CC-BY-SA-4.0 = a2ml-rs Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk :toc: :toc-placement: preamble
Rust parser and renderer for A2ML (Attested Markup Language) — the structured markup format used across the hyperpolymath estate for AI-agent communication, machine state files, and provenance-tracked documentation.
== Overview
A2ML extends a Markdown-like surface syntax with two first-class constructs:
@directives— single-line machine-readable metadata prefixed with@!attestblocks — record identity, role, and trust-level on any piece of content, enabling provenance tracking across AI-agent and human review chains
a2ml-rs implements:
src/parser.rs— line-oriented state machine: headings, directives, attestation blocks, fenced code, block quotes, ordered/unordered lists. Entry points:parse()andparse_file().src/renderer.rs— serialises aDocumentAST back to canonical A2ML, making round-trips deterministic.src/types.rs— core types:Document,Block,Inline,Directive,Attestation,TrustLevel(Unverified → Automated → Reviewed → Verified),Manifest.src/error.rs—A2mlError:ParseError,Io,RenderError.
The crate root is #![forbid(unsafe_code)]. Dependencies: serde/serde_derive
for serialisation, thiserror for error types, criterion for benchmarks only.
== Usage
use a2ml::{parse, render};
== Attestation Trust Levels
[cols="1,3"] |=== | Level | Meaning
| Unverified | No review — raw agent or tool output
| Automated | Processed by a pipeline without human review
| Reviewed | Human-reviewed (claimed, not cryptographically proved)
| Verified | Formally verified or cryptographically attested
|===
Attestations are syntactic declarations, not cryptographic signatures. Signature verification belongs in the Groove protocol stack.
== Related
- link:https://github.com/hyperpolymath/pandoc-a2ml[pandoc-a2ml] — Pandoc reader/writer for A2ML
- link:https://github.com/hyperpolymath/a2ml-haskell[a2ml-haskell] — Haskell implementation
== License
MPL-2.0. See link:LICENSE[LICENSE].