docs: bespoke architecture, roadmap, topology, and ABI definitions for a2mliser

Replace all template placeholders with a2mliser-specific content.
Architecture: A2ML attestation engine for markup/config signing.
Update STATE/META/ECOSYSTEM with attestation-specific project state.
Replace generic FFI integration tests with attestation operation tests.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -5,34 +5,37 @@
 (ecosystem
   (version "0.1.0")
   (name "a2mliser")
-  (type "tool")
-  (purpose "Add cryptographic attestation to any markup via A2ML")
+  (type "attestation-tool")
+  (purpose "Cryptographic attestation engine — signs markup and config files with A2ML envelopes, providing provenance chains and tamper detection")
 
   (position-in-ecosystem
     (family "-iser acceleration frameworks")
     (meta-framework "iseriser")
-    (relationship "sibling")
-    (top-3 ("typedqliser" "chapeliser" "verisimiser")))
+    (relationship "sibling — unique role as the attestation/trust layer")
+    (distinguishing-trait "Other -isers generate code; a2mliser generates cryptographic trust. It can attest the output of any other -iser."))
 
   (related-projects
     (project "iseriser"
       (relationship "meta-framework")
       (description "Generates new -iser project scaffolding"))
+    (project "k9iser"
+      (relationship "upstream-consumer")
+      (description "K9 contract validation. a2mliser attests files after K9 validation passes, proving both conformance and integrity."))
     (project "typedqliser"
-      (relationship "sibling-priority-1")
-      (description "Formal type safety for any query language"))
-    (project "chapeliser"
-      (relationship "sibling-priority-2")
-      (description "Chapel distributed computing acceleration"))
+      (relationship "upstream-consumer")
+      (description "Type-safe query generation. a2mliser attests generated query wrappers, proving they came from a specific schema version."))
     (project "verisimiser"
-      (relationship "sibling-priority-3")
-      (description "VeriSimDB octad database augmentation"))
-    (project "squeakwell"
-      (relationship "sibling")
-      (description "Database recovery via constraint propagation"))
+      (relationship "downstream-store")
+      (description "VeriSimDB augmentation. Attestation records can be persisted as octads for tamper-evident audit trails."))
     (project "proven"
       (relationship "dependency")
-      (description "Shared Idris2 verified library"))
+      (description "Shared Idris2 verified library — provides common proof infrastructure used by a2mliser's ABI layer."))
     (project "typell"
       (relationship "dependency")
-      (description "Type theory engine"))))
+      (description "Type theory engine — potential future integration for typed attestation predicates."))
+    (project "boj-server"
+      (relationship "distribution")
+      (description "BoJ cartridge for a2mliser exposes attestation as an MCP tool."))
+    (project "panll"
+      (relationship "visualisation")
+      (description "PanLL panel for attestation status dashboard — shows chain health, recent attestations, key expiry."))))

.machine_readable/6a2/META.a2ml

@@ -4,38 +4,56 @@
 
 (meta
   (version "0.1.0")
-  (last-updated "2026-03-20")
+  (last-updated "2026-03-21")
 
   (architecture-decisions
-    (adr "001-iser-pattern"
+    (adr "001-attestation-envelope"
       (status "accepted")
-      (context "Need to make powerful languages accessible without steep learning curves")
-      (decision "Use manifest-driven code generation: user describes WHAT, tool generates HOW")
-      (consequences "Users write zero target language code; all complexity in the -iser"))
+      (context "Need a standard format for cryptographic attestation of arbitrary files")
+      (decision "A2ML envelope: sidecar .a2ml file containing hash algorithm, digest, signature, timestamp, and optional parent reference for provenance chains")
+      (consequences "Any file format can be attested without modification; verification is independent of file type"))
 
-    (adr "002-abi-ffi-standard"
+    (adr "002-hash-algorithms"
       (status "accepted")
-      (context "Need verified interop between Rust CLI, target language, and user code")
-      (decision "Idris2 ABI for formal proofs, Zig FFI for C-ABI bridge")
-      (consequences "Compile-time correctness guarantees; zero runtime overhead from proofs"))
+      (context "Need fast and secure digest computation for attestation")
+      (decision "Support BLAKE3 (default, faster) and SHA-256 (widely trusted). Both produce 32-byte digests.")
+      (consequences "Uniform digest size simplifies envelope layout; BLAKE3 gives 3-10x speedup over SHA-256"))
 
-    (adr "003-rsr-template"
+    (adr "003-signature-algorithm"
       (status "accepted")
-      (context "Need consistent project structure across 29+ -iser repos")
-      (decision "All repos cloned from rsr-template-repo with full CI/CD and governance")
-      (consequences "17 workflows, SECURITY.md, CONTRIBUTING, bot directives from day one")))
+      (context "Need a modern, secure signing algorithm for attestation envelopes")
+      (decision "Ed25519 as primary (32-byte keys, 64-byte signatures). Ed448 reserved for future high-security mode.")
+      (consequences "Small keys and signatures keep envelopes compact; Ed25519 is widely supported"))
+
+    (adr "004-abi-ffi-standard"
+      (status "accepted")
+      (context "Need verified interop between Rust CLI and crypto primitives")
+      (decision "Idris2 ABI for formal proofs of signature correctness and chain validity; Zig FFI for C-ABI crypto implementation")
+      (consequences "Compile-time correctness guarantees; zero runtime overhead from proofs; Zig gives access to std.crypto"))
+
+    (adr "005-structure-aware-signing"
+      (status "proposed")
+      (context "Opaque-blob signing loses granularity — cannot attest individual config sections")
+      (decision "Parse files into structural units (TOML tables, YAML documents, JSON objects) and sign at chosen granularity")
+      (consequences "More complex implementation but enables partial verification and selective re-attestation"))
+
+    (adr "006-provenance-chains"
+      (status "proposed")
+      (context "Single attestations cannot express chain-of-custody or successive modifications")
+      (decision "Each envelope may reference a parent envelope hash, forming a DAG of trust from leaf to root")
+      (consequences "Full audit trail for config evolution; can verify entire history or just latest state")))
 
   (development-practices
-    (language "Rust" (purpose "CLI and orchestration"))
-    (language "Idris2" (purpose "ABI formal proofs"))
-    (language "Zig" (purpose "FFI C-ABI bridge"))
+    (language "Rust" (purpose "CLI orchestration, manifest parsing, codegen"))
+    (language "Idris2" (purpose "ABI formal proofs — signature correctness, chain validity, memory layout"))
+    (language "Zig" (purpose "FFI C-ABI bridge — crypto primitives (BLAKE3, SHA-256, Ed25519)"))
     (build-tool "cargo")
     (ci "GitHub Actions (17 workflows)"))
 
   (design-rationale
-    (principle "Manifest-driven"
-      (explanation "User intent captured in TOML; all generation is deterministic and reproducible"))
-    (principle "Formally verified bridges"
-      (explanation "Idris2 dependent types prove interface correctness at compile time"))
-    (principle "Zero target language exposure"
-      (explanation "Users never write Chapel/Julia/Futhark/etc. — the -iser handles everything"))))
+    (principle "Attestation is orthogonal to format"
+      (explanation "Any file type can be attested. Format handlers parse structure; the attestation engine is format-agnostic."))
+    (principle "Formally verified crypto boundary"
+      (explanation "Idris2 dependent types prove that signing and verification are consistent. The proof is erased at runtime."))
+    (principle "Provenance over point-in-time"
+      (explanation "A single signature proves current state. A provenance chain proves history. Both are first-class."))))

.machine_readable/6a2/STATE.a2ml

@@ -5,31 +5,35 @@
 (state
   (metadata
     (version "0.1.0")
-    (last-updated "2026-03-20")
+    (last-updated "2026-03-21")
     (author "Jonathan D.A. Jewell"))
 
   (project-context
     (name "a2mliser")
-    (description "Add cryptographic attestation to any markup via A2ML")
-    (status "scaffold")
-    (priority "—")
+    (description "Cryptographic attestation engine for markup and configuration files via A2ML envelopes")
+    (status "scaffold-documented")
+    (priority "mid-tier -iser — foundational for supply chain security")
     (ecosystem "-iser family (https://github.com/hyperpolymath/iseriser)"))
 
   (current-position
-    (phase "initial-scaffold")
-    (completion-percentage 5)
-    (milestone "Architecture defined, CLI scaffolded, RSR template complete"))
+    (phase "phase-0-complete")
+    (completion-percentage 10)
+    (milestone "Architecture documented, CLI scaffolded, ABI/FFI definitions written with attestation-specific types"))
 
   (route-to-mvp
-    (step 1 "Replace codegen stubs with target-language-specific generation")
-    (step 2 "Implement Idris2 ABI proofs for core invariants")
-    (step 3 "Build Zig FFI bridge")
-    (step 4 "Integration tests with real-world examples")
-    (step 5 "Documentation and examples"))
+    (step 1 "Implement BLAKE3 and SHA-256 hashing in Zig FFI (crypto primitives)")
+    (step 2 "Implement Ed25519 signing/verification in Zig FFI")
+    (step 3 "Wire Rust codegen to call Zig FFI via generated C headers")
+    (step 4 "Produce .a2ml sidecar attestation envelopes for TOML files")
+    (step 5 "Implement envelope verification (recompute digest, verify signature)")
+    (step 6 "Add provenance chain support (parent references, chain walking)")
+    (step 7 "YAML and JSON format handlers")
+    (step 8 "Idris2 formal proofs for signature correctness and chain validity"))
 
   (blockers-and-issues
-    (none "Project is in scaffold phase — no blockers yet"))
+    (none "Project is in scaffold phase with documentation complete — no blockers"))
 
   (critical-next-actions
-    (action "Implement codegen for primary use case")
-    (action "Write first working example end-to-end")))
+    (action "Implement BLAKE3 hashing in Zig FFI src/interface/ffi/src/main.zig")
+    (action "Implement Ed25519 signing in Zig FFI")
+    (action "Wire a2mliser generate command to produce real .a2ml envelopes")))