Skip to content

Commit 7441db6

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
docs: replace template README with a2ml-rs project content
Describes the Rust parser/renderer for A2ML: line-oriented state machine, Attestation/TrustLevel types, #![forbid(unsafe_code)], and relationship to pandoc-a2ml and a2ml-haskell sibling implementations. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 655bf56 commit 7441db6

1 file changed

Lines changed: 43 additions & 142 deletions

File tree

‎README.adoc‎

Lines changed: 43 additions & 142 deletions
Original file line numberDiff line numberDiff line change
@@ -1,165 +1,66 @@
1-
= RSR Template Repository
2-
:toc: preamble
3-
:icons: font
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
= a2ml-rs
3+
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
4+
:toc:
5+
:toc-placement: preamble
46

5-
[TIP]
6-
====
7-
**AI-Assisted Install:** Just tell any AI assistant: +
8-
`Set up {{PROJECT_NAME}} from https://{{FORGE}}/{{OWNER}}/{{REPO}}` +
9-
The AI reads the manifest, asks you a few questions, and handles everything.
10-
====
7+
Rust parser and renderer for A2ML (Attested Markup Language) — the
8+
structured markup format used across the hyperpolymath estate for AI-agent
9+
communication, machine state files, and provenance-tracked documentation.
1110

1211
== Overview
1312

14-
**The canonical template for RSR (Rhodium Standard Repository) projects.**
13+
A2ML extends a Markdown-like surface syntax with two first-class constructs:
1514

16-
This project follows a **Dual-Track** architecture:
17-
* **Root:** High-level orientation and rich documentation for humans.
18-
* **Sub-directories:** Machine-readable metadata and technical implementation.
15+
* `@directives` — single-line machine-readable metadata prefixed with `@`
16+
* `!attest` blocks — record identity, role, and trust-level on any piece
17+
of content, enabling provenance tracking across AI-agent and human review chains
1918

20-
== ABI/FFI Standard (Verified Interface Seams)
19+
`a2ml-rs` implements:
2120

22-
All projects with foreign function interfaces MUST follow this consolidated standard:
21+
* `src/parser.rs` — line-oriented state machine: headings, directives,
22+
attestation blocks, fenced code, block quotes, ordered/unordered lists.
23+
Entry points: `parse()` and `parse_file()`.
24+
* `src/renderer.rs` — serialises a `Document` AST back to canonical A2ML,
25+
making round-trips deterministic.
26+
* `src/types.rs` — core types: `Document`, `Block`, `Inline`, `Directive`,
27+
`Attestation`, `TrustLevel` (Unverified → Automated → Reviewed → Verified),
28+
`Manifest`.
29+
* `src/error.rs` — `A2mlError`: `ParseError`, `Io`, `RenderError`.
2330

24-
* **ABI (Idris2):** `src/interface/abi/*.idr` (The Specification)
25-
* **FFI (Zig):** `src/interface/ffi/src/*.zig` (The Implementation)
26-
* **Generated:** `src/interface/generated/*.h` (The Artifacts)
31+
The crate root is `#![forbid(unsafe_code)]`. Dependencies: `serde`/`serde_derive`
32+
for serialisation, `thiserror` for error types, `criterion` for benchmarks only.
2733

28-
This unification ensures that the "Truth," the "Bridge," and the "Result" are managed as a single architectural unit.
34+
== Usage
2935

30-
== AI Gatekeeper Protocol
31-
32-
All projects MUST include a root `0-AI-MANIFEST.a2ml`. This is the mandatory entry point for all AI agents. It prevents duplicate file errors and preserves architectural invariants across sessions.
33-
34-
== Repository Structure
35-
36-
[cols="1,3"]
37-
|===
38-
|Directory |Purpose
39-
40-
|`.github/`
41-
|Forge-specific metadata (CODEOWNERS, SECURITY.md, workflows).
42-
43-
|`.machine_readable/`
44-
|Canonical project state (6 a2ml files), bot directives, and AI guides.
45-
46-
|`container/`
47-
|Stapeln container ecosystem (selur-compose, vordr, rokur).
48-
49-
|`docs/`
50-
|Technical documentation sorted by tracks (Theory, Practice, Architecture).
51-
52-
|`docs/legal/`
53-
|Consolidated legal exhibits and full license texts.
54-
55-
|`src/interface/`
56-
|Unified ABI/FFI/Generated interface unit.
57-
|===
58-
59-
== Container Ecosystem (Stapeln)
60-
61-
This template includes a complete `container/` directory for the **Stapeln Six** tools:
62-
1. **selur** (Orchestration)
63-
2. **cerro-torre** (Verified Packaging)
64-
3. **svalinn** (Edge Gateway)
65-
4. **vordr** (Monitoring)
66-
5. **rokur** (Secrets)
67-
6. **k9-svc** (Deployment Contracts)
68-
69-
== Quick Start
70-
71-
[source,bash]
72-
----
73-
just init # Interactive bootstrap
74-
just build # Unified build
75-
just test # Unified test
76-
just container-build # Build verified OCI image
36+
[source,rust]
7737
----
38+
use a2ml::{parse, render};
7839
79-
== Contractile System
40+
let doc = parse(input_str)?;
41+
let output = render(&doc)?;
42+
----
8043

81-
This template includes five **contractile files** in `.machine_readable/contractiles/` that make your repository's rules executable:
44+
== Attestation Trust Levels
8245

83-
[cols="1,2,3"]
46+
[cols="1,3"]
8447
|===
85-
| Tool | File | Purpose
86-
87-
| `must check`
88-
| `Mustfile.a2ml`
89-
| Physical state invariants (files exist, code compiles, no secrets)
48+
| Level | Meaning
9049

91-
| `trust verify`
92-
| `Trustfile.a2ml`
93-
| Integrity verification (hashes valid, signatures correct, provenance traceable)
94-
95-
| `dust status`
96-
| `Dustfile.a2ml`
97-
| Cleanup tasks (stale files, build artifacts, expired tokens)
98-
99-
| `intend list`
100-
| `Intentfile.a2ml`
101-
| Design intent and roadmap tracking
102-
103-
| `k9 eval`
104-
| `*.k9.ncl`
105-
| Nickel-based deployment validation
50+
| `Unverified` | No review — raw agent or tool output
51+
| `Automated` | Processed by a pipeline without human review
52+
| `Reviewed` | Human-reviewed (claimed, not cryptographically proved)
53+
| `Verified` | Formally verified or cryptographically attested
10654
|===
10755

108-
=== Installation
109-
110-
[source,bash]
111-
----
112-
cargo install contractile
113-
114-
# Create symlinks for individual commands
115-
for cmd in must trust dust intend k9; do
116-
ln -sf $(which contractile) ~/.local/bin/$cmd
117-
done
118-
----
119-
120-
=== Usage
121-
122-
[source,bash]
123-
----
124-
# Symlink contractiles to project root (CLI searches ./contractiles/)
125-
ln -sf .machine_readable/contractiles contractiles
126-
127-
# Run checks
128-
must check # Verify physical state (23 checks in typical RSR project)
129-
trust verify # Verify integrity and provenance
130-
dust status # Show cleanup items
131-
intend list # Show design intents and roadmap
132-
133-
# Generate Just recipes from contractile files
134-
contractile gen-just # Creates contractile.just (already imported by Justfile)
135-
136-
# Then use via Just:
137-
just must-check
138-
just trust-verify
139-
----
140-
141-
=== Writing Checks
142-
143-
Contractile files use A2ML format — simple, line-oriented:
144-
145-
[source]
146-
----
147-
### check-name
148-
- description: Human-readable description
149-
- run: shell command (exit 0 = pass, non-zero = fail)
150-
- severity: critical | warning | info
151-
----
152-
153-
See link:https://github.com/hyperpolymath/contractiles[contractiles documentation] for the full specification.
56+
Attestations are syntactic declarations, not cryptographic signatures.
57+
Signature verification belongs in the Groove protocol stack.
15458

155-
== Documentation
59+
== Related
15660

157-
* link:CONTRIBUTING.adoc[Contributing Guide]
158-
* link:GOVERNANCE.adoc[Governance Model]
159-
* link:docs/attribution/MAINTAINERS.adoc[Maintainers & Citations]
160-
* link:SECURITY.adoc[Security Policy]
61+
* link:https://github.com/hyperpolymath/pandoc-a2ml[pandoc-a2ml] — Pandoc reader/writer for A2ML
62+
* link:https://github.com/hyperpolymath/a2ml-haskell[a2ml-haskell] — Haskell implementation
16163

16264
== License
16365

164-
SPDX-License-Identifier: PMPL-1.0-or-later
165-
See link:LICENSE[LICENSE] and link:docs/legal/[docs/legal/] for details.
66+
PMPL-1.0-or-later. See link:LICENSE[LICENSE].

0 commit comments

Comments
 (0)