|
1 | | -;; SPDX-License-Identifier: PMPL-1.0-or-later |
2 | | -;; Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> |
3 | | -;; META.a2ml — Meta-level information for a2mliser |
4 | | - |
5 | | -(meta |
6 | | - (version "0.1.0") |
7 | | - (last-updated "2026-03-21") |
8 | | - |
9 | | - (architecture-decisions |
10 | | - (adr "001-attestation-envelope" |
11 | | - (status "accepted") |
12 | | - (context "Need a standard format for cryptographic attestation of arbitrary files") |
13 | | - (decision "A2ML envelope: sidecar .a2ml file containing hash algorithm, digest, signature, timestamp, and optional parent reference for provenance chains") |
14 | | - (consequences "Any file format can be attested without modification; verification is independent of file type")) |
15 | | - |
16 | | - (adr "002-hash-algorithms" |
17 | | - (status "accepted") |
18 | | - (context "Need fast and secure digest computation for attestation") |
19 | | - (decision "Support BLAKE3 (default, faster) and SHA-256 (widely trusted). Both produce 32-byte digests.") |
20 | | - (consequences "Uniform digest size simplifies envelope layout; BLAKE3 gives 3-10x speedup over SHA-256")) |
21 | | - |
22 | | - (adr "003-signature-algorithm" |
23 | | - (status "accepted") |
24 | | - (context "Need a modern, secure signing algorithm for attestation envelopes") |
25 | | - (decision "Ed25519 as primary (32-byte keys, 64-byte signatures). Ed448 reserved for future high-security mode.") |
26 | | - (consequences "Small keys and signatures keep envelopes compact; Ed25519 is widely supported")) |
27 | | - |
28 | | - (adr "004-abi-ffi-standard" |
29 | | - (status "accepted") |
30 | | - (context "Need verified interop between Rust CLI and crypto primitives") |
31 | | - (decision "Idris2 ABI for formal proofs of signature correctness and chain validity; Zig FFI for C-ABI crypto implementation") |
32 | | - (consequences "Compile-time correctness guarantees; zero runtime overhead from proofs; Zig gives access to std.crypto")) |
33 | | - |
34 | | - (adr "005-structure-aware-signing" |
35 | | - (status "proposed") |
36 | | - (context "Opaque-blob signing loses granularity — cannot attest individual config sections") |
37 | | - (decision "Parse files into structural units (TOML tables, YAML documents, JSON objects) and sign at chosen granularity") |
38 | | - (consequences "More complex implementation but enables partial verification and selective re-attestation")) |
39 | | - |
40 | | - (adr "006-provenance-chains" |
41 | | - (status "proposed") |
42 | | - (context "Single attestations cannot express chain-of-custody or successive modifications") |
43 | | - (decision "Each envelope may reference a parent envelope hash, forming a DAG of trust from leaf to root") |
44 | | - (consequences "Full audit trail for config evolution; can verify entire history or just latest state"))) |
45 | | - |
46 | | - (development-practices |
47 | | - (language "Rust" (purpose "CLI orchestration, manifest parsing, codegen")) |
48 | | - (language "Idris2" (purpose "ABI formal proofs — signature correctness, chain validity, memory layout")) |
49 | | - (language "Zig" (purpose "FFI C-ABI bridge — crypto primitives (BLAKE3, SHA-256, Ed25519)")) |
50 | | - (build-tool "cargo") |
51 | | - (ci "GitHub Actions (17 workflows)")) |
52 | | - |
53 | | - (design-rationale |
54 | | - (principle "Attestation is orthogonal to format" |
55 | | - (explanation "Any file type can be attested. Format handlers parse structure; the attestation engine is format-agnostic.")) |
56 | | - (principle "Formally verified crypto boundary" |
57 | | - (explanation "Idris2 dependent types prove that signing and verification are consistent. The proof is erased at runtime.")) |
58 | | - (principle "Provenance over point-in-time" |
59 | | - (explanation "A single signature proves current state. A provenance chain proves history. Both are first-class.")))) |
| 1 | +# SPDX-License-Identifier: PMPL-1.0-or-later |
| 2 | +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> |
| 3 | +# |
| 4 | +# META.a2ml — A2mliser meta-level information |
| 5 | +[metadata] |
| 6 | +version = "0.1.0" |
| 7 | +last-updated = "2026-03-21" |
| 8 | + |
| 9 | +[project-info] |
| 10 | +license = "PMPL-1.0-or-later" |
| 11 | +author = "Jonathan D.A. Jewell (hyperpolymath)" |
| 12 | + |
| 13 | +[architecture-decisions] |
| 14 | +decisions = [ |
| 15 | + # No ADRs recorded |
| 16 | +] |
| 17 | + |
| 18 | +[development-practices] |
| 19 | +versioning = "SemVer" |
| 20 | +documentation = "AsciiDoc" |
| 21 | +build-tool = "just" |
| 22 | + |
| 23 | +[maintenance-axes] |
| 24 | +scoping-first = true |
| 25 | +axis-1 = "must > intend > like" |
| 26 | +axis-2 = "corrective > adaptive > perfective" |
| 27 | +axis-3 = "systems > compliance > effects" |
0 commit comments