chore(floor-raise): add integration files (Phase 2)

Add proven, verisimdb, feedback-o-tron, and vexometer integration
manifests as part of Floor Raise campaign Phase 2.

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

Author: hyperpolymath

README.adoc

@@ -1,45 +1,238 @@
 // SPDX-License-Identifier: PMPL-1.0-or-later
 // Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
-= A2mliser
+= a2mliser — Cryptographic Attestation for Any Markup or Configuration
 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
 :toc: left
+:toclevels: 3
 :icons: font
+:source-highlighter: rouge
 
-== What Is This?
+== What Is a2mliser?
 
-A2MLiser adds **cryptographic attestation and verification** to any markup,
-configuration, or manifest file — proving authenticity and integrity.
+a2mliser wraps any markup, configuration, or manifest file in an
+**A2ML (Attestable Markup Language) envelope** — adding cryptographic signatures,
+provenance chains, and tamper detection without altering the original content.
 
-A2ML (Attested Markup Language) embeds attestation chains in documents.
-A2MLiser wraps existing files in A2ML attestation envelopes.
+Where most signing tools operate on opaque blobs, a2mliser understands
+structure. It parses TOML, YAML, JSON, XML, and INI files, then generates
+attestation wrappers that cover both the content and its schema. A consumer can
+verify not only that a file has not been tampered with, but that its structure
+conforms to the attested schema at the moment of signing.
 
-== How It Works
+a2mliser is part of the
+https://github.com/hyperpolymath/iseriser[-iser acceleration family] — tools
+that wrap existing code in a target language's capabilities via manifest-driven
+code generation.
 
-Configure attestation in `a2mliser.toml`. A2MLiser:
+== Key Value Proposition
 
-1. Analyses existing markup files (YAML, TOML, JSON, XML, Markdown)
-2. Generates A2ML attestation envelopes with cryptographic signatures
-3. Embeds provenance metadata (who created, when, from what source)
-4. Provides verification: any consumer can check authenticity
-5. Supports attestation chains (A attests B attests C)
+* **Any file can be attested** — configs, manifests, CI definitions, lock files,
+  even other A2ML documents.
+* **Cryptographic proof** of authenticity and integrity (SHA-256, BLAKE3).
+* **Provenance chains** — trace any artifact back through its chain of custody.
+  A attests B attests C, forming a directed acyclic graph of trust.
+* **Structure-aware signing** — unlike GPG detached signatures, a2mliser
+  understands the file format and signs individual fields or sections.
+* **Supply chain security** — verify that CI configs, dependency manifests, and
+  deployment descriptors have not been altered since the authorised signer
+  produced them.
+* **Format-preserving** — the original file remains readable; attestation
+  metadata is carried in a sidecar `.a2ml` envelope or embedded as comments.
 
-== Key Value
+== Architecture
 
-* **Any file can be attested** — not just code, any artifact
-* **Cryptographic proof** of authenticity and integrity
-* **Provenance chains** — trace any artifact back to its origin
-* **Supply chain security** — verify configs haven't been tampered with
+a2mliser follows the hyperpolymath ABI-FFI-codegen architecture:
 
-== Architecture
+[source]
+----
+                          a2mliser.toml (user manifest)
+                                |
+                                v
+                    +------------------------+
+                    |  Manifest Parser (Rust) |  <-- reads user intent
+                    +------------------------+
+                                |
+                  +-------------+-------------+
+                  |                           |
+                  v                           v
+    +---------------------+     +-----------------------+
+    | Idris2 ABI Proofs   |     | Format Handlers       |
+    | (signature correct- |     | (TOML, YAML, JSON,    |
+    |  ness, non-repudia- |     |  XML, INI parsers)    |
+    |  tion, chain valid- |     +-----------------------+
+    |  ity)               |                |
+    +---------------------+                v
+              |               +-----------------------+
+              v               | Attestation Engine    |
+    +---------------------+   | (hash, sign, embed)   |
+    | Zig FFI Bridge      |   +-----------------------+
+    | (crypto primitives: |                |
+    |  BLAKE3, Ed25519,   |                v
+    |  SHA-256)           |   +-----------------------+
+    +---------------------+   | Codegen (A2ML wrapper |
+              |               |  generation)          |
+              v               +-----------------------+
+    +---------------------+                |
+    | C Headers (generated|                v
+    |  from ABI)          |     attested output files
+    +---------------------+     (.a2ml envelopes)
+----
+
+=== Layer Responsibilities
+
+Manifest Parser (Rust)::
+  Reads `a2mliser.toml`, validates user intent, dispatches to format handlers
+  and the attestation engine.
+
+Idris2 ABI (`src/interface/abi/`)::
+  Formally proves that signature operations are correct: signing a document and
+  verifying the same document always agree; provenance chains form a valid DAG;
+  attestation envelopes are non-repudiable.
+
+Zig FFI (`src/interface/ffi/`)::
+  Implements the actual cryptographic primitives (BLAKE3 hashing, Ed25519
+  signing, SHA-256 digests) as a C-compatible shared library. Zero runtime
+  overhead from the proof layer — Idris2 proofs are erased at compile time.
+
+Format Handlers (`src/codegen/`)::
+  Parse each supported format while preserving structure, identify attestable
+  regions, and generate the A2ML envelope that wraps the original content.
+
+== Supported Formats
+
+[cols="1,3"]
+|===
+| Format | Notes
+
+| TOML
+| Full structural attestation. Individual tables and key-value pairs can be
+  signed independently.
+
+| YAML
+| Document and sub-document attestation. Anchors and aliases are resolved
+  before signing.
+
+| JSON
+| Object-level and array-level attestation. JSON Schema can be co-attested.
+
+| XML
+| Element-level signing with XPath selectors. Namespace-aware.
+
+| INI
+| Section-level attestation. Comments are preserved but excluded from
+  signatures by default.
+
+| Custom
+| Plugin system (Phase 3+) for arbitrary formats via a trait-based handler
+  interface.
+|===
+
+== CLI Commands
+
+[source,bash]
+----
+# Create a new a2mliser.toml in the current directory
+a2mliser init
+
+# Validate an existing manifest
+a2mliser validate --manifest a2mliser.toml
+
+# Generate A2ML attestation envelopes for all declared files
+a2mliser generate --manifest a2mliser.toml --output attested/
+
+# Build the generated artifacts (compile Zig FFI, link)
+a2mliser build --manifest a2mliser.toml [--release]
+
+# Run the attestation workload end-to-end
+a2mliser run --manifest a2mliser.toml
 
-Follows the hyperpolymath -iser pattern:
-manifest -> Idris2 ABI proof -> Zig FFI bridge -> target language codegen.
-Part of the https://github.com/hyperpolymath/iseriser[-iser family].
+# Show manifest information and attestation summary
+a2mliser info --manifest a2mliser.toml
+----
+
+== Example Manifest
+
+An `a2mliser.toml` that attests a Cargo.toml and a CI workflow:
+
+[source,toml]
+----
+# a2mliser manifest — declare which files to attest
+[workload]
+name = "my-project-attestation"
+entry = "Cargo.toml"
+strategy = "structure-aware"
+
+[data]
+input-type = "toml"
+output-type = "a2ml-envelope"
+
+[options]
+flags = ["sign-sections", "provenance-chain"]
+
+# Files to attest
+[[targets]]
+path = "Cargo.toml"
+format = "toml"
+granularity = "table"          # sign each [section] independently
+
+[[targets]]
+path = ".github/workflows/ci.yml"
+format = "yaml"
+granularity = "document"       # sign the entire document
+
+[signing]
+algorithm = "ed25519"
+hash = "blake3"
+key-source = "env:A2ML_SIGNING_KEY"  # or "file:keys/signing.pem"
+----
+
+== Integration With Other -isers
+
+k9iser::
+  Contract validation. k9iser validates that configuration files satisfy K9
+  contracts; a2mliser then attests the validated result, proving that the file
+  both conforms to its contract and has not been modified since validation.
+
+typedqliser::
+  Query attestation. When typedqliser generates type-safe query wrappers,
+  a2mliser can attest the generated code, proving it was produced by a specific
+  version of typedqliser from a specific schema.
+
+verisimiser::
+  Database augmentation. Attestation records (who signed what, when) can be
+  stored in VeriSimDB octads via verisimiser, providing a tamper-evident
+  audit trail.
+
+== Build and Test
+
+[source,bash]
+----
+# Build
+cargo build --release
+
+# Test
+cargo test
+
+# Full quality check (format, lint, test)
+just quality
+
+# Pre-commit scan
+just assail
+----
 
 == Status
 
-**Pre-alpha.** Architecture defined, scaffolding in place, codegen pending.
+**Pre-alpha (Phase 0 complete).**
+
+The CLI skeleton, manifest parser, and ABI/FFI scaffolding are in place.
+Codegen stubs exist but do not yet produce real attestation envelopes.
+
+See link:ROADMAP.adoc[ROADMAP.adoc] for the full development plan.
+
+See link:TOPOLOGY.md[TOPOLOGY.md] for the repository structure map.
 
 == License
 
 SPDX-License-Identifier: PMPL-1.0-or-later
+
+Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)

ROADMAP.adoc

@@ -1,32 +1,92 @@
 // SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 = a2mliser Roadmap
-:toc:
+:toc: left
 :icons: font
 
-== Phase 0: Scaffold (COMPLETE)
-* [x] RSR template with full CI/CD
-* [x] CLI with subcommands
-* [x] Manifest parser
-* [x] Codegen stubs
-* [x] ABI module stubs
-* [x] README with architecture
-
-== Phase 1: Core Implementation
-* [ ] Implement target-language-specific code generation
-* [ ] Write Idris2 ABI proofs for core invariants
-* [ ] Build Zig FFI bridge
-* [ ] First working end-to-end example
-* [ ] Integration tests
-
-== Phase 2: Polish
-* [ ] Error messages and diagnostics
+== Phase 0: Scaffold [COMPLETE]
+
+* [x] RSR template with 17 CI/CD workflows
+* [x] Rust CLI with `init`, `validate`, `generate`, `build`, `run`, `info` subcommands
+* [x] Manifest parser (`a2mliser.toml` — TOML-based workload description)
+* [x] Codegen module stubs
+* [x] ABI module stubs (Rust side)
+* [x] Idris2 ABI type definitions (Types.idr, Layout.idr, Foreign.idr) — template placeholders
+* [x] Zig FFI scaffold (build.zig, main.zig, integration tests)
+* [x] README with architecture overview
+* [x] Machine-readable state files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml)
+* [x] Contractile system (K9, Must, Trust, Dust, Lust)
+* [x] Bot directives for gitbot-fleet
+
+== Phase 1: Core Attestation Engine
+
+The minimum viable attestation pipeline: hash a file, sign the hash, embed
+the signature in an A2ML envelope.
+
+* [ ] Implement SHA-256 and BLAKE3 digest computation in Zig FFI
+* [ ] Implement Ed25519 signing and verification in Zig FFI
+* [ ] Define `AttestationEnvelope` structure (hash algorithm, signature bytes,
+      signer identity, timestamp, target file path, target file digest)
+* [ ] Wire Rust CLI `generate` command to call Zig FFI via C headers
+* [ ] Produce `.a2ml` sidecar files containing the attestation envelope
+* [ ] Implement `validate` command: read `.a2ml` envelope, recompute digest,
+      verify signature
+* [ ] First end-to-end test: attest a TOML file, verify the attestation
+* [ ] Replace Idris2 ABI template placeholders with attestation-specific types
+
+== Phase 2: Format Handlers
+
+Structure-aware parsing so that attestation can target individual sections
+of a document rather than treating it as an opaque blob.
+
+* [ ] TOML handler: parse into tables, attest individual `[section]` blocks
+* [ ] YAML handler: parse documents, resolve anchors/aliases before signing
+* [ ] JSON handler: object-level and array-level attestation
+* [ ] XML handler: element-level signing with XPath selectors
+* [ ] INI handler: section-level attestation, comment preservation
+* [ ] Granularity control in `a2mliser.toml`: `document`, `section`, `field`
+* [ ] Envelope embedding modes: sidecar (`.a2ml` file) vs inline (comments)
+* [ ] Schema co-attestation: sign both the data and its expected schema
+
+== Phase 3: Provenance Chains
+
+Chain-of-custody tracking — an attestation can reference a previous
+attestation, forming a directed acyclic graph of trust.
+
+* [ ] `ProvenanceChain` data structure: ordered list of attestation records
+* [ ] Parent reference: each envelope can cite the hash of its predecessor
+* [ ] Timestamp authority integration (RFC 3161 or custom TSA)
+* [ ] Chain validation: verify the full chain from leaf to root
+* [ ] Merge detection: identify when two chains diverge and re-converge
+* [ ] Export: provenance chain as Graphviz DOT for visualisation
+* [ ] Key rotation: support multiple signing keys with validity periods
+
+== Phase 4: Idris2 Formal Proofs
+
+Replace the template ABI with attestation-specific formal verification.
+
+* [ ] `SignatureAlgorithm` type with exhaustive case coverage
+* [ ] Proof: `sign(key, data) |> verify(pubkey, data)` always succeeds for
+      matching key pairs
+* [ ] Proof: provenance chains form a valid DAG (no cycles)
+* [ ] Proof: attestation envelopes are non-repudiable (signature binds signer
+      identity to content)
+* [ ] Proof: hash collision resistance properties (type-level bounds)
+* [ ] Memory layout proofs for all FFI-crossing structs
+* [ ] Platform-specific ABI compliance verification (Linux, macOS, Windows, WASM)
+
+== Phase 5: Ecosystem Integration
+
+Packaging, distribution, and integration with the broader hyperpolymath
+toolchain.
+
+* [ ] BoJ-server cartridge: expose a2mliser as an MCP tool
+* [ ] PanLL panel: visual attestation status dashboard
+* [ ] CI/CD action: GitHub Action that runs `a2mliser validate` on PRs
+* [ ] VeriSimDB storage: persist attestation records in octad database
+* [ ] k9iser bridge: attest files after K9 contract validation passes
+* [ ] typedqliser bridge: attest generated query wrappers
+* [ ] Plugin system: trait-based handler interface for custom formats
+* [ ] crates.io publication
 * [ ] Shell completions (bash, zsh, fish)
-* [ ] CI/CD for the generated artifacts
-* [ ] Performance benchmarks
-* [ ] Additional examples
-
-== Phase 3: Ecosystem
-* [ ] PanLL panel integration
-* [ ] BoJ-server cartridge
-* [ ] VeriSimDB backing store for results
-* [ ] Publish to crates.io
+* [ ] Performance benchmarks and optimisation pass