From abe0a6a0bd95d89cea814aa455d1c307d3e156d9 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:21:05 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- CODE_OF_CONDUCT.adoc | 24 ++ CODE_OF_CONDUCT.md | 27 -- CONTRIBUTING.adoc | 71 ++++ CONTRIBUTING.md | 66 --- READINESS.adoc | 97 +++++ READINESS.md | 74 ---- README.adoc | 388 ++++++++++++++++++ README.md | 308 -------------- SECURITY.md => SECURITY.adoc | 21 +- TEST-NEEDS.adoc | 51 +++ TEST-NEEDS.md | 41 -- TOPOLOGY.md => TOPOLOGY.adoc | 27 +- .../{TOPOLOGY.md => TOPOLOGY.adoc} | 99 +++-- llm-warmup-dev.adoc | 19 + llm-warmup-dev.md | 16 - llm-warmup-user.adoc | 19 + llm-warmup-user.md | 16 - satellites/a2mliser/ARCHITECTURE.adoc | 48 +++ satellites/a2mliser/ARCHITECTURE.md | 47 --- satellites/a2mliser/CODE_OF_CONDUCT.adoc | 24 ++ satellites/a2mliser/CODE_OF_CONDUCT.md | 27 -- satellites/a2mliser/CONTRIBUTING.adoc | 71 ++++ satellites/a2mliser/CONTRIBUTING.md | 66 --- satellites/a2mliser/GOVERNANCE.adoc | 60 +++ satellites/a2mliser/GOVERNANCE.md | 60 --- satellites/a2mliser/README.adoc | 230 +++++++++++ satellites/a2mliser/README.md | 227 ---------- .../a2mliser/{SECURITY.md => SECURITY.adoc} | 21 +- satellites/a2mliser/TEST-NEEDS.adoc | 34 ++ satellites/a2mliser/TEST-NEEDS.md | 31 -- .../a2mliser/{TOPOLOGY.md => TOPOLOGY.adoc} | 36 +- satellites/a2mliser/llm-warmup-dev.adoc | 19 + satellites/a2mliser/llm-warmup-dev.md | 16 - satellites/a2mliser/llm-warmup-user.adoc | 19 + satellites/a2mliser/llm-warmup-user.md | 16 - 35 files changed, 1289 insertions(+), 1127 deletions(-) create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 READINESS.adoc delete mode 100644 READINESS.md create mode 100644 README.adoc delete mode 100644 README.md rename SECURITY.md => SECURITY.adoc (57%) create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (68%) rename docs/architecture/{TOPOLOGY.md => TOPOLOGY.adoc} (66%) create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md create mode 100644 satellites/a2mliser/ARCHITECTURE.adoc delete mode 100644 satellites/a2mliser/ARCHITECTURE.md create mode 100644 satellites/a2mliser/CODE_OF_CONDUCT.adoc delete mode 100644 satellites/a2mliser/CODE_OF_CONDUCT.md create mode 100644 satellites/a2mliser/CONTRIBUTING.adoc delete mode 100644 satellites/a2mliser/CONTRIBUTING.md create mode 100644 satellites/a2mliser/GOVERNANCE.adoc delete mode 100644 satellites/a2mliser/GOVERNANCE.md create mode 100644 satellites/a2mliser/README.adoc delete mode 100644 satellites/a2mliser/README.md rename satellites/a2mliser/{SECURITY.md => SECURITY.adoc} (57%) create mode 100644 satellites/a2mliser/TEST-NEEDS.adoc delete mode 100644 satellites/a2mliser/TEST-NEEDS.md rename satellites/a2mliser/{TOPOLOGY.md => TOPOLOGY.adoc} (90%) create mode 100644 satellites/a2mliser/llm-warmup-dev.adoc delete mode 100644 satellites/a2mliser/llm-warmup-dev.md create mode 100644 satellites/a2mliser/llm-warmup-user.adoc delete mode 100644 satellites/a2mliser/llm-warmup-user.md diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..858f44f --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+nix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 80ecdac..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `nix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/READINESS.adoc b/READINESS.adoc new file mode 100644 index 0000000..c88e028 --- /dev/null +++ b/READINESS.adoc @@ -0,0 +1,97 @@ +== iseriser Component Readiness Assessment + +*Standard:* +https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades[Component +Readiness Grades (CRG) v2.2] *Current Grade:* B *Assessed:* 2026-04-04 +*Assessor:* Jonathan D.A. Jewell + Claude Sonnet 4.6 + +''''' + +=== Summary + +[width="100%",cols="16%,6%,13%,65%",options="header",] +|=== +|Component |Grade |Release Stage |Evidence Summary +|`+scan+` |B |Beta |Scanned 29 -iser repos across 6 distinct language +stacks + +|`+generate+` |C |Alpha-stable |Generates -iser scaffolding; used to +create iseriser itself + +|`+validate+` |C |Alpha-stable |Validates manifest; CI passing on self + +|CLI / dispatch |C |Alpha-stable |Full command routing; dogfooded on 29 +-iser repos +|=== + +*Overall:* Grade B for the `+scan+` subcommand (primary use case). Grade +C for generator/validator. + +''''' + +=== Grade B Evidence — `+scan+` External Targets + +iseriser `+scan+` has been executed against 29 -iser repos, spanning 6 +distinct language/architecture families: + +[arabic] +. *Rust CLIs* (conflow, a2ml-rs, panic-attack/assemblyline) — Cargo +workspace, multi-crate +. *Elixir/OTP* (hypatia, burble) — mix.exs umbrella, GenServer pattern +. *Gleam/BEAM* (k9_gleam, a2ml_gleam) — gleam.toml, BEAM target +. *Deno/TypeScript tooling* (k9-coordination-protocol generator) — Deno +runtime +. *Julia scientific* (statistease, developer-ecosystem/julia-ecosystem) +— Project.toml +. *Multi-language monorepos* (developer-ecosystem, standards, +nextgen-languages) — mixed roots + +Issues found and fed back during scan development: - Missing +eclexiaiser.toml detection in sub-service dirs (fixed: now uses maxdepth +3) - k9iser path resolution relative to manifest (fixed: +manifest-relative paths) - Groove manifest validation tolerates +`+"type": "custom"+` with warning (deliberate) + +''''' + +=== Grade C Evidence — `+generate+` + +* Successfully scaffolds new -iser repos from template +* Generated: typedqliser, chapeliser, verisimiser, eclexiaiser, +25 +others +* Dogfooded: iseriser was generated using itself (bootstrap complete) +* Known limitation: generated ABI stubs are templates only, not proven +Idris2 + +*Promotion path to B:* Generate on 6 external project types with diverse +requirements and verify the scaffolded code compiles/runs correctly in +each. + +''''' + +=== Grade C Evidence — `+validate+` + +* Validates iseriser.toml manifests (schema, required fields, path +resolution) +* CI passing on own manifest +* Deployed in dogfood-gate on repos with iseriser.toml + +*Promotion path to B:* Deploy and validate against 6+ diverse external +-iser manifests with different language stacks. + +''''' + +=== Concerns and Maintenance Notes + +[arabic] +. *ABI stubs* — Generated Idris2 ABI stubs require manual completion; +only scaffold +. *Zig FFI templates* — Generated FFI templates compile but don’t +implement semantics +. *`+scan+` on non-Rust repos* — Performance impact when traversing +large repos with many files +. *Chapel metalayer* — Planned distributed scan; not yet implemented + +''''' + +=== Run `+just crg-badge+` to generate the shields.io badge for your README. diff --git a/READINESS.md b/READINESS.md deleted file mode 100644 index 1e81056..0000000 --- a/READINESS.md +++ /dev/null @@ -1,74 +0,0 @@ - - - -# iseriser Component Readiness Assessment - -**Standard:** [Component Readiness Grades (CRG) v2.2](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades) -**Current Grade:** B -**Assessed:** 2026-04-04 -**Assessor:** Jonathan D.A. Jewell + Claude Sonnet 4.6 - ---- - -## Summary - -| Component | Grade | Release Stage | Evidence Summary | -|----------------|-------|---------------|-----------------------------------------------------------------------| -| `scan` | B | Beta | Scanned 29 -iser repos across 6 distinct language stacks | -| `generate` | C | Alpha-stable | Generates -iser scaffolding; used to create iseriser itself | -| `validate` | C | Alpha-stable | Validates manifest; CI passing on self | -| CLI / dispatch | C | Alpha-stable | Full command routing; dogfooded on 29 -iser repos | - -**Overall:** Grade B for the `scan` subcommand (primary use case). Grade C for generator/validator. - ---- - -## Grade B Evidence — `scan` External Targets - -iseriser `scan` has been executed against 29 -iser repos, spanning 6 distinct language/architecture families: - -1. **Rust CLIs** (conflow, a2ml-rs, panic-attack/assemblyline) — Cargo workspace, multi-crate -2. **Elixir/OTP** (hypatia, burble) — mix.exs umbrella, GenServer pattern -3. **Gleam/BEAM** (k9_gleam, a2ml_gleam) — gleam.toml, BEAM target -4. **Deno/TypeScript tooling** (k9-coordination-protocol generator) — Deno runtime -5. **Julia scientific** (statistease, developer-ecosystem/julia-ecosystem) — Project.toml -6. **Multi-language monorepos** (developer-ecosystem, standards, nextgen-languages) — mixed roots - -Issues found and fed back during scan development: -- Missing eclexiaiser.toml detection in sub-service dirs (fixed: now uses maxdepth 3) -- k9iser path resolution relative to manifest (fixed: manifest-relative paths) -- Groove manifest validation tolerates `"type": "custom"` with warning (deliberate) - ---- - -## Grade C Evidence — `generate` - -- Successfully scaffolds new -iser repos from template -- Generated: typedqliser, chapeliser, verisimiser, eclexiaiser, +25 others -- Dogfooded: iseriser was generated using itself (bootstrap complete) -- Known limitation: generated ABI stubs are templates only, not proven Idris2 - -**Promotion path to B:** Generate on 6 external project types with diverse requirements and verify the scaffolded code compiles/runs correctly in each. - ---- - -## Grade C Evidence — `validate` - -- Validates iseriser.toml manifests (schema, required fields, path resolution) -- CI passing on own manifest -- Deployed in dogfood-gate on repos with iseriser.toml - -**Promotion path to B:** Deploy and validate against 6+ diverse external -iser manifests with different language stacks. - ---- - -## Concerns and Maintenance Notes - -1. **ABI stubs** — Generated Idris2 ABI stubs require manual completion; only scaffold -2. **Zig FFI templates** — Generated FFI templates compile but don't implement semantics -3. **`scan` on non-Rust repos** — Performance impact when traversing large repos with many files -4. **Chapel metalayer** — Planned distributed scan; not yet implemented - ---- - -## Run `just crg-badge` to generate the shields.io badge for your README. diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..b8c89c3 --- /dev/null +++ b/README.adoc @@ -0,0 +1,388 @@ +link:LICENSE[image:https://img.shields.io/badge/license-MPL--2.0-blue[License: +MPL-2.0]] +link:LICENSES/CC-BY-SA-4.0.txt[image:https://img.shields.io/badge/docs-CC--BY--SA--4.0-blue[Docs: +CC-BY-SA-4.0]] +image:https://img.shields.io/badge/-iser_family-29_repos-brightgreen[29 +repos] image:https://img.shields.io/badge/ABI-Idris2-red[Idris2 ABI] +image:https://img.shields.io/badge/FFI-Zig-orange[Zig FFI] + +*29 Rust CLI tools that inject superpowers from specialist languages +into your existing codebase — without you ever learning those +languages.* + +https://hyperpolymath.github.io/iseriser/[Browse the Hub] | See All 29 +-isers | Install + +''''' + +____ +[!TIP] *New here? Start with the coordination layer:* + +* link:docs/ATLAS.adoc[*The -iser Atlas*] — route a need straight to the +right -iser ("`I want to… → use…`"). +* link:docs/theory/AOLD.adoc[*Aspect-Oriented Language Design*] — the +design philosophy (each language’s superpower as a bolt-on _aspect_; the +"`mech suit`" model; why this is the _dual_ of aggregate-library). +* link:docs/theory/iSOS.adoc[*Integrated Stack of Stacks*] — how aspects +_compose_ over one shared Idris2-ABI/Zig-FFI seam, kept honest by +invariant-path. +____ + +== What is the -iser Pattern? + +An *-iser* is a Rust CLI that bridges the gap between a _specialist +language_ (a language with unique strengths in a narrow domain) and the +code you already write every day. Each -iser: + +[arabic] +. *Reads* a declarative TOML manifest describing what you want. +. *Validates* it against a formally verified Idris2 ABI specification. +. *Generates* wrapper code, bindings, or transformations targeting the +specialist language — via a Zig FFI bridge for C-ABI compatibility. +. *Builds and runs* the result, giving you the specialist language’s +capabilities without leaving your toolchain. + +The pattern lets you tap into GPU kernels (Futhark), formal proofs +(Idris2, Dafny, TLA+), data-race freedom (Pony), fault tolerance (OTP), +distributed computing (Chapel), and 20+ other domains — all through a +consistent `+init+` `+/+` `+validate+` `+/+` `+generate+` `+/+` +`+build+` `+/+` `+run+` workflow. + +*Iseriser is the meta-framework that generates new -iser projects.* +Given a language description, it scaffolds a complete -iser repo in +minutes: manifest parser, codegen engine, Idris2 ABI definitions, Zig +FFI bridge, 17 CI/CD workflows, RSR governance files, and documentation. + +== Architecture: Idris2 ABI + Zig FFI + +Every -iser in the family shares a three-layer architecture that +guarantees interface correctness through formal verification: + +.... + +---------------------------+ + | Rust CLI (cargo) | + | init/validate/gen/build | + +------+----------+---------+ + | | + +------------+ +------------+ + | | + v v + +------------------------+ +------------------------+ + | Idris2 ABI Layer | | Zig FFI Layer | + | (formal verification) | | (C-ABI bridge) | + | | | | + | Types.idr |-------->| build.zig | + | dependent types | gen'd | src/main.zig | + | prove correctness | C | test/integration.zig | + | Layout.idr | headers | | + | memory layout | | zero-cost C interop | + | platform proofs | | cross-compilation | + | Foreign.idr | | no runtime deps | + | FFI declarations | | | + +------------------------+ +------------------------+ + | | + +----------------+-------------------+ + | + v + +------------------------+ + | Target Language | + | (Chapel, Futhark, | + | Idris2, Pony, ...) | + +------------------------+ +.... + +*Why Idris2 for ABI?* + +Dependent types prove interface correctness at compile time. Memory +layouts are verified. Platform-specific ABIs are selected with +compile-time proofs. Backward compatibility is provable. These are +type-level guarantees that no other approach can provide. + +*Why Zig for FFI?* + +Native C ABI compatibility with zero overhead. Memory-safe by default. +Cross-compilation is built in. No runtime dependencies. The ideal bridge +between formal specifications and real-world calling conventions. + +== [#the-iser-family]####The -iser Family (29 repos) + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Name |Description |Tests |Status +|https://github.com/hyperpolymath/typedqliser[*TypedQLiser*] |Add formal +type safety (10 levels, dependent/linear/session types) to any query +language |0 |scaffold + +|https://github.com/hyperpolymath/chapeliser[*Chapeliser*] +|General-purpose Chapel acceleration — distribute any workload without +learning Chapel |22 |scaffold + +|https://github.com/hyperpolymath/verisimiser[*Verisimiser*] |Augment +any database with VeriSimDB octad capabilities — drift, provenance, +temporal |26 |scaffold + +|https://github.com/hyperpolymath/julianiser[*Julianiser*] |Auto-wrap +Python/R data pipelines into Julia for 100x speedups |25 |scaffold + +|https://github.com/hyperpolymath/futharkiser[*Futharkiser*] |Compile +annotated array operations to GPU kernels via Futhark |42 |scaffold + +|https://github.com/hyperpolymath/idrisiser[*Idrisiser*] |Generate +proven-correct wrappers from interfaces using Idris2 dependent types |6 +|scaffold + +|https://github.com/hyperpolymath/tlaiser[*TLAiser*] |Extract state +machines from code and model-check with TLA+/PlusCal |32 |scaffold + +|https://github.com/hyperpolymath/dafniser[*Dafniser*] |Generate +correct-by-construction code for critical functions using Dafny |28 +|scaffold + +|https://github.com/hyperpolymath/ponyiser[*Ponyiser*] |Wrap concurrent +code in Pony reference capabilities for data-race freedom |27 |scaffold + +|https://github.com/hyperpolymath/otpiser[*OTPiser*] |Generate OTP +supervision trees and fault-tolerance scaffolding |1 |scaffold + +|https://github.com/hyperpolymath/halideiser[*Halideiser*] |Compile +image/video pipelines to optimised Halide schedules |24 |scaffold + +|https://github.com/hyperpolymath/lustreiser[*Lustreiser*] |Generate +formally verified real-time embedded code via Lustre |36 |scaffold + +|https://github.com/hyperpolymath/bqniser[*BQNiser*] |Detect array +patterns and rewrite as optimised BQN primitives |0 |scaffold + +|https://github.com/hyperpolymath/alloyiser[*Alloyiser*] |Extract formal +models from API specs and verify with Alloy |25 |scaffold + +|https://github.com/hyperpolymath/atsiser[*ATSiser*] |Wrap C codebases +in ATS linear types for zero-cost memory safety |32 |scaffold + +|https://github.com/hyperpolymath/nimiser[*Nimiser*] |Generate +high-performance C libraries via Nim metaprogramming |28 |scaffold + +|https://github.com/hyperpolymath/a2mliser[*A2MLiser*] |Add +cryptographic attestation to any markup or configuration via A2ML |0 +|scaffold + +|https://github.com/hyperpolymath/affinescriptiser[*AffineScriptiser*] +|Wrap code in affine + dependent types targeting WASM via AffineScript +|36 |scaffold + +|https://github.com/hyperpolymath/anvomidaviser[*Anvomidaviser*] +|Convert ISU notation to formal figure skating programs via Anvomidav +|36 |scaffold + +|https://github.com/hyperpolymath/betlangiser[*BetLangiser*] |Add +ternary probabilistic modelling to deterministic code via Betlang |36 +|scaffold + +|https://github.com/hyperpolymath/eclexiaiser[*Eclexiaiser*] |Add +energy/carbon/resource-cost awareness to software via Eclexia |23 +|scaffold + +|https://github.com/hyperpolymath/ephapaxiser[*Ephapaxiser*] |Enforce +single-use linear type semantics on resources via Ephapax |17 |scaffold + +|https://github.com/hyperpolymath/k9iser[*K9iser*] |Wrap configs into +self-validating K9 contracts |19 |scaffold + +|https://github.com/hyperpolymath/mylangiser[*MyLangiser*] |Generate +progressive-disclosure interfaces from complex APIs via My-Lang |20 +|scaffold + +|https://github.com/hyperpolymath/oblibeniser[*Oblibeniser*] |Make +operations reversible and auditable via Oblibeny |27 |scaffold + +|https://github.com/hyperpolymath/phronesiser[*Phronesiser*] |Add +provably safe ethical constraints to AI agents via Phronesis |31 +|scaffold + +|https://github.com/hyperpolymath/wokelangiser[*WokeLangiser*] |Add +consent patterns and accessibility to existing code via WokeLang |44 +|scaffold + +|https://github.com/hyperpolymath/squeakwell[*SqueakWell*] |Database +recovery through cross-modal constraint propagation — 8 modalities |0 +|scaffold + +|https://github.com/hyperpolymath/iseriser[*Iseriser*] |*This +repo* — the meta-framework that generates all other -isers |24 |scaffold +|=== + +Total tests across the family: *726* + +== [#install]####Installation + +Every -iser is a standalone Rust binary. Install any of them with: + +[source,bash] +---- +# Install a specific -iser +cargo install typedqliser +cargo install futharkiser +cargo install chapeliser +# ... or any other -iser name + +# Install iseriser (the meta-framework) +cargo install iseriser +---- + +Or clone and build from source: + +[source,bash] +---- +git clone https://github.com/hyperpolymath/.git +cd +cargo build --release +---- + +== Usage + +All -isers share the same five-command interface: + +[source,bash] +---- +# Initialise a new manifest for your project + init + +# Validate your manifest against the Idris2 ABI spec + validate + +# Generate target language code from your manifest + generate + +# Build the generated output + build + +# Run the result + run +---- + +== Using Iseriser to Create a New -iser + +[source,bash] +---- +# 1. Create a language description +cat > mylanguage.toml <<'TOML' +[language] +name = "MyLang" +type_system = ["dependent", "linear"] +target = "native" +calling_convention = "c" +TOML + +# 2. Generate the -iser repo +iseriser generate --from mylanguage.toml --output ./mylangiser + +# 3. The result is a complete, functional -iser repo +cd mylangiser +cargo test # tests pass immediately +cargo run -- init +---- + +=== Iseriser CLI subcommands + +In addition to scaffolding new -isers, iseriser itself ships with: + +[width="100%",cols="50%,50%",options="header",] +|=== +|`+init+` |Initialise an `+iseriser.toml+` manifest in the current +directory. +|`+validate+` |Structural + semantic validation of an `+iseriser.toml+`. + +|`+generate+` |Scaffold a complete -iser repo from the manifest. + +|`+cartridge+` |Scaffold a boj-server cartridge skeleton +(`+-mcp/+`) for the manifest’s -iser — adapter + FFI + ABI + +cartridge.json + panels + mod.js. Output goes to +`+/-mcp/+`; place inside `+boj-server/cartridges/+` so the +emitted Zig build files resolve the shared invoke-shim. See +`+examples/cartridge-skeleton/README.adoc+`. + +|`+info+` |Print a summary of a manifest. + +|`+scan+` |Walk a repository and recommend applicable -iser tools. + +|`+abi-verify+` |(Phase 1) Diff a cartridge’s Zig FFI against its +Idris2-derived ABI manifest; exit 0=clean, 2=drift. See +`+examples/abi-manifests/README.adoc+` for the drift taxonomy. + +|`+abi-emit-manifest+` |(Phase 1b) Emit the ABI manifest JSON from a +cartridge’s `+Safe*.idr+` source. The Idris2 source is the single +authority — manifest is derived, not hand-authored. Combine with +`+abi-verify+` to gate Zig FFI drift in CI. +|=== + +The `+abi-*+` pair implements standards (Phase 1 + 1b); see +`+examples/abi-manifests/README.adoc+` for the schema, the drift +taxonomy, and end-to-end usage. + +The `+cartridge+` subcommand implements standards Phase 2b — the +boj-server cartridge skeleton, modelled on the k9iser-mcp pilot +(boj-server#73). Estate-wide fan-out of the regeneration-cartridge +pattern is gated on standards (http-capability-gateway tier-2 +production-wiring). + +== Generated Repo Structure + +When iseriser generates a new -iser, it produces: + +.... +/ ++-- Cargo.toml # Rust CLI project ++-- src/ +| +-- main.rs # CLI: init/validate/generate/build/run +| +-- lib.rs # Library API +| +-- manifest/mod.rs # TOML manifest parser +| +-- codegen/mod.rs # Target-specific code generation +| +-- abi/mod.rs # Rust-side ABI types +| +-- interface/ +| +-- abi/ +| | +-- Types.idr # Idris2 type definitions + proofs +| | +-- Layout.idr # Memory layout verification +| | +-- Foreign.idr # FFI function declarations +| +-- ffi/ +| +-- build.zig # Zig build config +| +-- src/main.zig # Zig FFI implementation +| +-- test/integration.zig # FFI integration tests ++-- .github/workflows/ # 17 CI/CD workflows ++-- .machine_readable/ # RSR governance (STATE, META, ECOSYSTEM) ++-- README.adoc ++-- ROADMAP.adoc ++-- TOPOLOGY.md ++-- LICENSE +.... + +== The Hub + +Browse the full -iser family with interactive search and filtering: + +*https://hyperpolymath.github.io/iseriser/* + +The GitHub Pages hub provides: + +* Searchable catalogue of all 29 -isers +* Architecture diagrams and domain explanations +* Quick-start guides for each -iser +* Links to crates.io, documentation, and source + +== Status + +All 29 -iser repos are scaffolded and functional. The architecture is +defined, CLI commands work, manifest parsers are operational, and test +suites are in place across the family. Domain-specific code generation +logic is the current frontier — each -iser is being deepened with real +codegen for its target language. + +== Contributing + +See CONTRIBUTING for guidelines. All contributions must pass the full CI +suite including Hypatia neurosymbolic scanning. + +== License + +Code is licensed under `+MPL-2.0+`; documentation under +`+CC-BY-SA-4.0+`. Full licence texts are in +link:LICENSES/[`+LICENSES/+`]. + +Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) diff --git a/README.md b/README.md deleted file mode 100644 index 51267dd..0000000 --- a/README.md +++ /dev/null @@ -1,308 +0,0 @@ - - -[![License: MPL-2.0](https://img.shields.io/badge/license-MPL--2.0-blue)](LICENSE) [![Docs: CC-BY-SA-4.0](https://img.shields.io/badge/docs-CC--BY--SA--4.0-blue)](LICENSES/CC-BY-SA-4.0.txt) ![29 -repos](https://img.shields.io/badge/-iser_family-29_repos-brightgreen) -![Idris2 ABI](https://img.shields.io/badge/ABI-Idris2-red) ![Zig -FFI](https://img.shields.io/badge/FFI-Zig-orange) - -
- -**29 Rust CLI tools that inject superpowers from specialist languages -into your existing codebase — without you ever learning those -languages.** - -
- -https://hyperpolymath.github.io/iseriser/\[Browse the Hub\] \| -See All 29 -isers -\| Install - ------------------------------------------------------------------------- - -> [!TIP] -> **New here? Start with the coordination layer:** -> -> - [**The -iser Atlas**](docs/ATLAS.adoc) — route a need straight to -> the right -iser ("I want to… → use…"). -> -> - [**Aspect-Oriented Language Design**](docs/theory/AOLD.adoc) — the -> design philosophy (each language’s superpower as a bolt-on *aspect*; -> the "mech suit" model; why this is the *dual* of aggregate-library). -> -> - [**Integrated Stack of Stacks**](docs/theory/iSOS.adoc) — how -> aspects *compose* over one shared Idris2-ABI/Zig-FFI seam, kept -> honest by invariant-path. - -# What is the -iser Pattern? - -An **-iser** is a Rust CLI that bridges the gap between a *specialist -language* (a language with unique strengths in a narrow domain) and the -code you already write every day. Each -iser: - -1. **Reads** a declarative TOML manifest describing what you want. - -2. **Validates** it against a formally verified Idris2 ABI - specification. - -3. **Generates** wrapper code, bindings, or transformations targeting - the specialist language — via a Zig FFI bridge for C-ABI - compatibility. - -4. **Builds and runs** the result, giving you the specialist language’s - capabilities without leaving your toolchain. - -The pattern lets you tap into GPU kernels (Futhark), formal proofs -(Idris2, Dafny, TLA+), data-race freedom (Pony), fault tolerance (OTP), -distributed computing (Chapel), and 20+ other domains — all through a -consistent `init` `/` `validate` `/` `generate` `/` `build` `/` `run` -workflow. - -**Iseriser is the meta-framework that generates new -iser projects.** -Given a language description, it scaffolds a complete -iser repo in -minutes: manifest parser, codegen engine, Idris2 ABI definitions, Zig -FFI bridge, 17 CI/CD workflows, RSR governance files, and documentation. - -# Architecture: Idris2 ABI + Zig FFI - -Every -iser in the family shares a three-layer architecture that -guarantees interface correctness through formal verification: - - +---------------------------+ - | Rust CLI (cargo) | - | init/validate/gen/build | - +------+----------+---------+ - | | - +------------+ +------------+ - | | - v v - +------------------------+ +------------------------+ - | Idris2 ABI Layer | | Zig FFI Layer | - | (formal verification) | | (C-ABI bridge) | - | | | | - | Types.idr |-------->| build.zig | - | dependent types | gen'd | src/main.zig | - | prove correctness | C | test/integration.zig | - | Layout.idr | headers | | - | memory layout | | zero-cost C interop | - | platform proofs | | cross-compilation | - | Foreign.idr | | no runtime deps | - | FFI declarations | | | - +------------------------+ +------------------------+ - | | - +----------------+-------------------+ - | - v - +------------------------+ - | Target Language | - | (Chapel, Futhark, | - | Idris2, Pony, ...) | - +------------------------+ - -**Why Idris2 for ABI?** -Dependent types prove interface correctness at compile time. Memory -layouts are verified. Platform-specific ABIs are selected with -compile-time proofs. Backward compatibility is provable. These are -type-level guarantees that no other approach can provide. - -**Why Zig for FFI?** -Native C ABI compatibility with zero overhead. Memory-safe by default. -Cross-compilation is built in. No runtime dependencies. The ideal bridge -between formal specifications and real-world calling conventions. - -# The -iser Family (29 repos) - -| Name | Description | Tests | Status | -|----|----|----|----| -| https://github.com/hyperpolymath/typedqliser\[**TypedQLiser**\] | Add formal type safety (10 levels, dependent/linear/session types) to any query language | 0 | scaffold | -| https://github.com/hyperpolymath/chapeliser\[**Chapeliser**\] | General-purpose Chapel acceleration — distribute any workload without learning Chapel | 22 | scaffold | -| https://github.com/hyperpolymath/verisimiser\[**Verisimiser**\] | Augment any database with VeriSimDB octad capabilities — drift, provenance, temporal | 26 | scaffold | -| https://github.com/hyperpolymath/julianiser\[**Julianiser**\] | Auto-wrap Python/R data pipelines into Julia for 100x speedups | 25 | scaffold | -| https://github.com/hyperpolymath/futharkiser\[**Futharkiser**\] | Compile annotated array operations to GPU kernels via Futhark | 42 | scaffold | -| https://github.com/hyperpolymath/idrisiser\[**Idrisiser**\] | Generate proven-correct wrappers from interfaces using Idris2 dependent types | 6 | scaffold | -| https://github.com/hyperpolymath/tlaiser\[**TLAiser**\] | Extract state machines from code and model-check with TLA+/PlusCal | 32 | scaffold | -| https://github.com/hyperpolymath/dafniser\[**Dafniser**\] | Generate correct-by-construction code for critical functions using Dafny | 28 | scaffold | -| https://github.com/hyperpolymath/ponyiser\[**Ponyiser**\] | Wrap concurrent code in Pony reference capabilities for data-race freedom | 27 | scaffold | -| https://github.com/hyperpolymath/otpiser\[**OTPiser**\] | Generate OTP supervision trees and fault-tolerance scaffolding | 1 | scaffold | -| https://github.com/hyperpolymath/halideiser\[**Halideiser**\] | Compile image/video pipelines to optimised Halide schedules | 24 | scaffold | -| https://github.com/hyperpolymath/lustreiser\[**Lustreiser**\] | Generate formally verified real-time embedded code via Lustre | 36 | scaffold | -| https://github.com/hyperpolymath/bqniser\[**BQNiser**\] | Detect array patterns and rewrite as optimised BQN primitives | 0 | scaffold | -| https://github.com/hyperpolymath/alloyiser\[**Alloyiser**\] | Extract formal models from API specs and verify with Alloy | 25 | scaffold | -| https://github.com/hyperpolymath/atsiser\[**ATSiser**\] | Wrap C codebases in ATS linear types for zero-cost memory safety | 32 | scaffold | -| https://github.com/hyperpolymath/nimiser\[**Nimiser**\] | Generate high-performance C libraries via Nim metaprogramming | 28 | scaffold | -| https://github.com/hyperpolymath/a2mliser\[**A2MLiser**\] | Add cryptographic attestation to any markup or configuration via A2ML | 0 | scaffold | -| https://github.com/hyperpolymath/affinescriptiser\[**AffineScriptiser**\] | Wrap code in affine + dependent types targeting WASM via AffineScript | 36 | scaffold | -| https://github.com/hyperpolymath/anvomidaviser\[**Anvomidaviser**\] | Convert ISU notation to formal figure skating programs via Anvomidav | 36 | scaffold | -| https://github.com/hyperpolymath/betlangiser\[**BetLangiser**\] | Add ternary probabilistic modelling to deterministic code via Betlang | 36 | scaffold | -| https://github.com/hyperpolymath/eclexiaiser\[**Eclexiaiser**\] | Add energy/carbon/resource-cost awareness to software via Eclexia | 23 | scaffold | -| https://github.com/hyperpolymath/ephapaxiser\[**Ephapaxiser**\] | Enforce single-use linear type semantics on resources via Ephapax | 17 | scaffold | -| https://github.com/hyperpolymath/k9iser\[**K9iser**\] | Wrap configs into self-validating K9 contracts | 19 | scaffold | -| https://github.com/hyperpolymath/mylangiser\[**MyLangiser**\] | Generate progressive-disclosure interfaces from complex APIs via My-Lang | 20 | scaffold | -| https://github.com/hyperpolymath/oblibeniser\[**Oblibeniser**\] | Make operations reversible and auditable via Oblibeny | 27 | scaffold | -| https://github.com/hyperpolymath/phronesiser\[**Phronesiser**\] | Add provably safe ethical constraints to AI agents via Phronesis | 31 | scaffold | -| https://github.com/hyperpolymath/wokelangiser\[**WokeLangiser**\] | Add consent patterns and accessibility to existing code via WokeLang | 44 | scaffold | -| https://github.com/hyperpolymath/squeakwell\[**SqueakWell**\] | Database recovery through cross-modal constraint propagation — 8 modalities | 0 | scaffold | -| https://github.com/hyperpolymath/iseriser\[**Iseriser**\] | **This repo** — the meta-framework that generates all other -isers | 24 | scaffold | - -Total tests across the family: **726** - -# Installation - -Every -iser is a standalone Rust binary. Install any of them with: - -```bash -# Install a specific -iser -cargo install typedqliser -cargo install futharkiser -cargo install chapeliser -# ... or any other -iser name - -# Install iseriser (the meta-framework) -cargo install iseriser -``` - -Or clone and build from source: - -```bash -git clone https://github.com/hyperpolymath/.git -cd -cargo build --release -``` - -# Usage - -All -isers share the same five-command interface: - -```bash -# Initialise a new manifest for your project - init - -# Validate your manifest against the Idris2 ABI spec - validate - -# Generate target language code from your manifest - generate - -# Build the generated output - build - -# Run the result - run -``` - -# Using Iseriser to Create a New -iser - -```bash -# 1. Create a language description -cat > mylanguage.toml <<'TOML' -[language] -name = "MyLang" -type_system = ["dependent", "linear"] -target = "native" -calling_convention = "c" -TOML - -# 2. Generate the -iser repo -iseriser generate --from mylanguage.toml --output ./mylangiser - -# 3. The result is a complete, functional -iser repo -cd mylangiser -cargo test # tests pass immediately -cargo run -- init -``` - -## Iseriser CLI subcommands - -In addition to scaffolding new -isers, iseriser itself ships with: - -| `init` | Initialise an `iseriser.toml` manifest in the current directory. | -|----|----| -| `validate` | Structural + semantic validation of an `iseriser.toml`. | -| `generate` | Scaffold a complete -iser repo from the manifest. | -| `cartridge` | Scaffold a boj-server cartridge skeleton (`-mcp/`) for the manifest’s -iser — adapter + FFI + ABI + cartridge.json + panels + mod.js. Output goes to `/-mcp/`; place inside `boj-server/cartridges/` so the emitted Zig build files resolve the shared invoke-shim. See `examples/cartridge-skeleton/README.adoc`. | -| `info` | Print a summary of a manifest. | -| `scan` | Walk a repository and recommend applicable -iser tools. | -| `abi-verify` | (Phase 1) Diff a cartridge’s Zig FFI against its Idris2-derived ABI manifest; exit 0=clean, 2=drift. See `examples/abi-manifests/README.adoc` for the drift taxonomy. | -| `abi-emit-manifest` | (Phase 1b) Emit the ABI manifest JSON from a cartridge’s `Safe*.idr` source. The Idris2 source is the single authority — manifest is derived, not hand-authored. Combine with `abi-verify` to gate Zig FFI drift in CI. | - -The `abi-*` pair implements -standards (Phase 1 + 1b); see -`examples/abi-manifests/README.adoc` for the schema, the drift taxonomy, -and end-to-end usage. - -The `cartridge` subcommand implements -standards Phase 2b — the boj-server cartridge skeleton, -modelled on the k9iser-mcp pilot (boj-server#73). Estate-wide fan-out of -the regeneration-cartridge pattern is gated on -standards (http-capability-gateway tier-2 -production-wiring). - -# Generated Repo Structure - -When iseriser generates a new -iser, it produces: - - / - +-- Cargo.toml # Rust CLI project - +-- src/ - | +-- main.rs # CLI: init/validate/generate/build/run - | +-- lib.rs # Library API - | +-- manifest/mod.rs # TOML manifest parser - | +-- codegen/mod.rs # Target-specific code generation - | +-- abi/mod.rs # Rust-side ABI types - | +-- interface/ - | +-- abi/ - | | +-- Types.idr # Idris2 type definitions + proofs - | | +-- Layout.idr # Memory layout verification - | | +-- Foreign.idr # FFI function declarations - | +-- ffi/ - | +-- build.zig # Zig build config - | +-- src/main.zig # Zig FFI implementation - | +-- test/integration.zig # FFI integration tests - +-- .github/workflows/ # 17 CI/CD workflows - +-- .machine_readable/ # RSR governance (STATE, META, ECOSYSTEM) - +-- README.adoc - +-- ROADMAP.adoc - +-- TOPOLOGY.md - +-- LICENSE - -# The Hub - -Browse the full -iser family with interactive search and filtering: - -**https://hyperpolymath.github.io/iseriser/** - -The GitHub Pages hub provides: - -- Searchable catalogue of all 29 -isers - -- Architecture diagrams and domain explanations - -- Quick-start guides for each -iser - -- Links to crates.io, documentation, and source - -# Status - -All 29 -iser repos are scaffolded and functional. The architecture is -defined, CLI commands work, manifest parsers are operational, and test -suites are in place across the family. Domain-specific code generation -logic is the current frontier — each -iser is being deepened with real -codegen for its target language. - -# Contributing - -See CONTRIBUTING for -guidelines. All contributions must pass the full CI suite including -Hypatia neurosymbolic scanning. - -# License - -Code is licensed under `MPL-2.0`; documentation under `CC-BY-SA-4.0`. -Full licence texts are in [`LICENSES/`](LICENSES/). - -Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) diff --git a/SECURITY.md b/SECURITY.adoc similarity index 57% rename from SECURITY.md rename to SECURITY.adoc index 49ad09a..84438bc 100644 --- a/SECURITY.md +++ b/SECURITY.adoc @@ -1,21 +1,24 @@ -# Security Policy +== Security Policy -## Supported Versions +=== Supported Versions -| Version | Supported | -|---------|-----------| -| 0.1.x | ✅ | +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |✅ +|=== -## Reporting a Vulnerability +=== Reporting a Vulnerability Please report security vulnerabilities to: j.d.a.jewell@open.ac.uk Do NOT open a public issue for security vulnerabilities. -## Response Time +=== Response Time -We aim to respond within 48 hours and provide a fix within 7 days for critical issues. +We aim to respond within 48 hours and provide a fix within 7 days for +critical issues. -## Scope +=== Scope This policy covers the iseriser CLI tool and its generated artifacts. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..0fd8595 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,51 @@ +== TEST-NEEDS.md — iseriser + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Test files |2 |Current state +|=== + +=== What’s Covered + +* [x] 2 existing test file(s) +* [x] Rust integration tests + +=== Still Missing (for CRG B+) + +* [ ] Zig FFI tests (if applicable) +* [ ] CI/CD test automation +* [ ] Property-based tests +* [ ] Edge case coverage + +=== Run Tests + +[source,bash] +---- +cargo test --all +---- + +=== Session 9 additions (2026-04-04) + +==== What Was Added + +[width="100%",cols="22%,44%,34%",options="header",] +|=== +|Area |Tests Added |Location +|Benchmarks |8 criterion bench functions across 4 groups: parse +(minimal/rich/gleam manifests), validate (valid/rich), +`+to_language_model+` ABI conversion (chapel/julia), `+scan_repo+` +walking real repo tree |`+benches/iseriser_bench.rs+` +|=== + +==== Updated Test Counts + +[cols=",,",options="header",] +|=== +|Suite |Count |Status +|Benchmarks |8 |All compile and baseline +|=== diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index f7a2152..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,41 +0,0 @@ -# TEST-NEEDS.md — iseriser - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Test files | 2 | Current state | - -## What's Covered - -- [x] 2 existing test file(s) -- [x] Rust integration tests - -## Still Missing (for CRG B+) - -- [ ] Zig FFI tests (if applicable) -- [ ] CI/CD test automation -- [ ] Property-based tests -- [ ] Edge case coverage - -## Run Tests - -```bash -cargo test --all -``` - -## Session 9 additions (2026-04-04) - -### What Was Added - -| Area | Tests Added | Location | -|------|-------------|----------| -| Benchmarks | 8 criterion bench functions across 4 groups: parse (minimal/rich/gleam manifests), validate (valid/rich), `to_language_model` ABI conversion (chapel/julia), `scan_repo` walking real repo tree | `benches/iseriser_bench.rs` | - -### Updated Test Counts - -| Suite | Count | Status | -|-------|-------|--------| -| Benchmarks | 8 | All compile and baseline | diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 68% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 3c02d6c..294f23c 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,14 +1,19 @@ - - -# TOPOLOGY.md — iseriser +== TOPOLOGY.md — iseriser -## Purpose +=== Purpose -iseriser is the meta-iser: it generates complete new -iser project scaffolds from a language description manifest. Given a target language or system name and its characteristics, iseriser emits a fully-structured RSR-compliant repository with the standard Rust CLI skeleton, Idris2 ABI stubs, Zig FFI bridge, manifest parser, codegen module, justfile, and all required workflow files. iseriser is the bootstrap tool for the entire -iser family and is used to create new isers consistently and quickly. +iseriser is the meta-iser: it generates complete new -iser project +scaffolds from a language description manifest. Given a target language +or system name and its characteristics, iseriser emits a +fully-structured RSR-compliant repository with the standard Rust CLI +skeleton, Idris2 ABI stubs, Zig FFI bridge, manifest parser, codegen +module, justfile, and all required workflow files. iseriser is the +bootstrap tool for the entire -iser family and is used to create new +isers consistently and quickly. -## Module Map +=== Module Map -``` +.... iseriser/ ├── src/ │ ├── main.rs # CLI entry point (clap): init, validate, generate, info @@ -20,11 +25,11 @@ iseriser/ ├── verification/ # Proof harnesses ├── container/ # Stapeln container ecosystem └── .machine_readable/ # A2ML metadata -``` +.... -## Data Flow +=== Data Flow -``` +.... iseriser.toml manifest │ ┌────▼────┐ @@ -40,4 +45,4 @@ iseriser.toml manifest │ Codegen │ emit complete iser/ project tree │ │ (src/, ffi/zig/, src/abi/, justfile, workflows, .machine_readable/) └─────────┘ -``` +.... diff --git a/docs/architecture/TOPOLOGY.md b/docs/architecture/TOPOLOGY.adoc similarity index 66% rename from docs/architecture/TOPOLOGY.md rename to docs/architecture/TOPOLOGY.adoc index e3fe96e..40605c0 100644 --- a/docs/architecture/TOPOLOGY.md +++ b/docs/architecture/TOPOLOGY.adoc @@ -1,15 +1,14 @@ - - -# Iseriser — Architectural Topology +== Iseriser — Architectural Topology -## Overview +=== Overview -Iseriser is the meta-framework that generates new -iser projects. It takes a -language description as input and produces a complete -iser repository as output. +Iseriser is the meta-framework that generates new -iser projects. It +takes a language description as input and produces a complete -iser +repository as output. -## Data Flow +=== Data Flow -``` +.... iseriser.toml (language description) | @@ -43,11 +42,11 @@ language description as input and produces a complete -iser repository as output | (complete, ready | | to cargo build) | +------------------+ -``` +.... -## Module Structure +=== Module Structure -``` +.... iseriser/ ├── src/ │ ├── main.rs # CLI: init, validate, generate, build, run, info @@ -80,35 +79,49 @@ iseriser/ │ └── architecture/ │ └── TOPOLOGY.md # This file └── tests/ # Rust integration tests -``` - -## Key Dependencies - -| Dependency | Purpose | -|------------|---------| -| `clap` | CLI argument parsing with derive macros | -| `serde` + `toml` | Manifest deserialization | -| `handlebars` | Template engine for code generation | -| `anyhow` + `thiserror` | Error handling | -| `walkdir` | Directory traversal for template discovery | - -## Integration Points - -| System | Relationship | -|--------|-------------| -| **proven** | Shared Idris2 verified library for ABI proofs | -| **typell** | Type theory engine used in language model analysis | -| **rsr-template-repo** | Source templates for generated RSR governance files | -| **PanLL** | Future: "New -Iser" wizard panel | -| **BoJ-server** | Future: `iseriser.generate` MCP cartridge | -| **VeriSimDB** | Future: persist language models and generation history | -| **Hypatia** | Neurosymbolic scanning of generated repos | - -## Generation Pipeline - -1. **Parse** — `iseriser.toml` -> `LanguageDescription` struct -2. **Model** — `LanguageDescription` -> `LanguageModel` (features, targets, ABI shape) -3. **Verify** — Idris2 ABI checks language model consistency -4. **Expand** — Handlebars templates + language model -> file tree -5. **Write** — file tree -> disk (complete -iser repo) -6. **Validate** — generated repo passes `cargo check` and template completeness +.... + +=== Key Dependencies + +[cols=",",options="header",] +|=== +|Dependency |Purpose +|`+clap+` |CLI argument parsing with derive macros +|`+serde+` + `+toml+` |Manifest deserialization +|`+handlebars+` |Template engine for code generation +|`+anyhow+` + `+thiserror+` |Error handling +|`+walkdir+` |Directory traversal for template discovery +|=== + +=== Integration Points + +[width="100%",cols="39%,61%",options="header",] +|=== +|System |Relationship +|*proven* |Shared Idris2 verified library for ABI proofs + +|*typell* |Type theory engine used in language model analysis + +|*rsr-template-repo* |Source templates for generated RSR governance +files + +|*PanLL* |Future: "`New -Iser`" wizard panel + +|*BoJ-server* |Future: `+iseriser.generate+` MCP cartridge + +|*VeriSimDB* |Future: persist language models and generation history + +|*Hypatia* |Neurosymbolic scanning of generated repos +|=== + +=== Generation Pipeline + +[arabic] +. *Parse* — `+iseriser.toml+` -> `+LanguageDescription+` struct +. *Model* — `+LanguageDescription+` -> `+LanguageModel+` (features, +targets, ABI shape) +. *Verify* — Idris2 ABI checks language model consistency +. *Expand* — Handlebars templates + language model -> file tree +. *Write* — file tree -> disk (complete -iser repo) +. *Validate* — generated repo passes `+cargo check+` and template +completeness diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..9712672 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — iseriser (Developer) + +=== What is iseriser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index ad58343..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — iseriser (Developer) - -## What is iseriser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..4c0f2c0 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — iseriser (User) + +=== What is iseriser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index d3c8cf9..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — iseriser (User) - -## What is iseriser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/satellites/a2mliser/ARCHITECTURE.adoc b/satellites/a2mliser/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/satellites/a2mliser/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/satellites/a2mliser/ARCHITECTURE.md b/satellites/a2mliser/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/satellites/a2mliser/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/satellites/a2mliser/CODE_OF_CONDUCT.adoc b/satellites/a2mliser/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/satellites/a2mliser/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/satellites/a2mliser/CODE_OF_CONDUCT.md b/satellites/a2mliser/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/satellites/a2mliser/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/satellites/a2mliser/CONTRIBUTING.adoc b/satellites/a2mliser/CONTRIBUTING.adoc new file mode 100644 index 0000000..858f44f --- /dev/null +++ b/satellites/a2mliser/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+nix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/satellites/a2mliser/CONTRIBUTING.md b/satellites/a2mliser/CONTRIBUTING.md deleted file mode 100644 index 80ecdac..0000000 --- a/satellites/a2mliser/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `nix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/satellites/a2mliser/GOVERNANCE.adoc b/satellites/a2mliser/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/satellites/a2mliser/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/satellites/a2mliser/GOVERNANCE.md b/satellites/a2mliser/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/satellites/a2mliser/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/satellites/a2mliser/README.adoc b/satellites/a2mliser/README.adoc new file mode 100644 index 0000000..8c40331 --- /dev/null +++ b/satellites/a2mliser/README.adoc @@ -0,0 +1,230 @@ +link:FUNDING[image:https://img.shields.io/badge/Funding-See_FUNDING-brightgreen[Funding]] + +== What Is a2mliser? + +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. + +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. + +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. + +== Key Value Proposition + +* *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. + +== Architecture + +a2mliser follows the hyperpolymath ABI-FFI-codegen architecture: + +.... + 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 + +[width="100%",cols="50%,50%",options="header",] +|=== +|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 + +# 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 (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 ROADMAP for the full development plan. + +See TOPOLOGY for the repository structure map. + +== License + +SPDX-License-Identifier: CC-BY-SA-4.0 + +Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) diff --git a/satellites/a2mliser/README.md b/satellites/a2mliser/README.md deleted file mode 100644 index 9e6df1b..0000000 --- a/satellites/a2mliser/README.md +++ /dev/null @@ -1,227 +0,0 @@ - - -[![Funding](https://img.shields.io/badge/Funding-See_FUNDING-brightgreen)](FUNDING) - -# What Is a2mliser? - -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. - -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. - -a2mliser is part of the [-iser acceleration -family](https://github.com/hyperpolymath/iseriser) — tools that wrap -existing code in a target language’s capabilities via manifest-driven -code generation. - -# Key Value Proposition - -- **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. - -# Architecture - -a2mliser follows the hyperpolymath ABI-FFI-codegen architecture: - - 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 - -| 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 - -```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 - -# 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: - -```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 - -```bash -# Build -cargo build --release - -# Test -cargo test - -# Full quality check (format, lint, test) -just quality - -# Pre-commit scan -just assail -``` - -# Status - -**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 ROADMAP for the full -development plan. - -See TOPOLOGY for the repository -structure map. - -# License - -SPDX-License-Identifier: CC-BY-SA-4.0 - -Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) diff --git a/satellites/a2mliser/SECURITY.md b/satellites/a2mliser/SECURITY.adoc similarity index 57% rename from satellites/a2mliser/SECURITY.md rename to satellites/a2mliser/SECURITY.adoc index d52b676..8e4cb28 100644 --- a/satellites/a2mliser/SECURITY.md +++ b/satellites/a2mliser/SECURITY.adoc @@ -1,21 +1,24 @@ -# Security Policy +== Security Policy -## Supported Versions +=== Supported Versions -| Version | Supported | -|---------|-----------| -| 0.1.x | ✅ | +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |✅ +|=== -## Reporting a Vulnerability +=== Reporting a Vulnerability Please report security vulnerabilities to: j.d.a.jewell@open.ac.uk Do NOT open a public issue for security vulnerabilities. -## Response Time +=== Response Time -We aim to respond within 48 hours and provide a fix within 7 days for critical issues. +We aim to respond within 48 hours and provide a fix within 7 days for +critical issues. -## Scope +=== Scope This policy covers the a2mliser CLI tool and its generated artifacts. diff --git a/satellites/a2mliser/TEST-NEEDS.adoc b/satellites/a2mliser/TEST-NEEDS.adoc new file mode 100644 index 0000000..cd8d225 --- /dev/null +++ b/satellites/a2mliser/TEST-NEEDS.adoc @@ -0,0 +1,34 @@ +== TEST-NEEDS.md — a2mliser + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Test directories |2 |Location(s): /tests, /verification/tests +|CI workflows |22 |Running tests on GitHub Actions +|Unit tests |Built-in |Rust/cargo test framework +|Integration tests |Configured |Via integration/ directory +|=== + +=== What’s Covered + +* [x] Rust unit test suite (cargo test) +* [x] Documentation tests +* [x] Example programs with tests + +=== Still Missing (for CRG B+) + +* [ ] Code coverage reports (codecov integration) +* [ ] Detailed test documentation in CONTRIBUTING.md +* [ ] Integration tests beyond unit tests +* [ ] Performance benchmarking suite + +=== Run Tests + +[source,bash] +---- +cargo test +---- diff --git a/satellites/a2mliser/TEST-NEEDS.md b/satellites/a2mliser/TEST-NEEDS.md deleted file mode 100644 index 1472df3..0000000 --- a/satellites/a2mliser/TEST-NEEDS.md +++ /dev/null @@ -1,31 +0,0 @@ -# TEST-NEEDS.md — a2mliser - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Test directories | 2 | Location(s): /tests, /verification/tests | -| CI workflows | 22 | Running tests on GitHub Actions | -| Unit tests | Built-in | Rust/cargo test framework | -| Integration tests | Configured | Via integration/ directory | - -## What's Covered - -- [x] Rust unit test suite (cargo test) -- [x] Documentation tests -- [x] Example programs with tests - -## Still Missing (for CRG B+) - -- [ ] Code coverage reports (codecov integration) -- [ ] Detailed test documentation in CONTRIBUTING.md -- [ ] Integration tests beyond unit tests -- [ ] Performance benchmarking suite - -## Run Tests - -```bash -cargo test -``` diff --git a/satellites/a2mliser/TOPOLOGY.md b/satellites/a2mliser/TOPOLOGY.adoc similarity index 90% rename from satellites/a2mliser/TOPOLOGY.md rename to satellites/a2mliser/TOPOLOGY.adoc index e70616d..0d4a996 100644 --- a/satellites/a2mliser/TOPOLOGY.md +++ b/satellites/a2mliser/TOPOLOGY.adoc @@ -1,10 +1,8 @@ - - -# a2mliser — Repository Topology +== a2mliser — Repository Topology Map of every directory and its purpose. -``` +.... a2mliser/ ├── 0-AI-MANIFEST.a2ml # AI agent entry point — read first ├── README.adoc # High-level orientation @@ -129,20 +127,24 @@ a2mliser/ │ └── verification/ # Verification scripts │ └── .well-known/ # .well-known metadata (security.txt, etc.) -``` +.... -## Key Relationships +=== Key Relationships -- `src/interface/abi/*.idr` **defines** the formal specification (Idris2) -- `src/interface/ffi/src/main.zig` **implements** the specification (Zig) -- `src/interface/generated/abi/` **bridges** them via C headers -- `src/manifest/mod.rs` **reads** user intent from `a2mliser.toml` -- `src/codegen/mod.rs` **produces** A2ML attestation envelopes -- `src/main.rs` **orchestrates** the pipeline via CLI subcommands +* `+src/interface/abi/*.idr+` *defines* the formal specification +(Idris2) +* `+src/interface/ffi/src/main.zig+` *implements* the specification +(Zig) +* `+src/interface/generated/abi/+` *bridges* them via C headers +* `+src/manifest/mod.rs+` *reads* user intent from `+a2mliser.toml+` +* `+src/codegen/mod.rs+` *produces* A2ML attestation envelopes +* `+src/main.rs+` *orchestrates* the pipeline via CLI subcommands -## Invariants +=== Invariants -1. Machine-readable files live in `.machine_readable/` ONLY — never in root -2. Idris2 ABI is the specification; Zig FFI is the implementation -3. Generated C headers go in `src/interface/generated/abi/` -4. All workflows are SHA-pinned, all code is MPL-2.0 +[arabic] +. Machine-readable files live in `+.machine_readable/+` ONLY — never in +root +. Idris2 ABI is the specification; Zig FFI is the implementation +. Generated C headers go in `+src/interface/generated/abi/+` +. All workflows are SHA-pinned, all code is MPL-2.0 diff --git a/satellites/a2mliser/llm-warmup-dev.adoc b/satellites/a2mliser/llm-warmup-dev.adoc new file mode 100644 index 0000000..72ff95d --- /dev/null +++ b/satellites/a2mliser/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2mliser (Developer) + +=== What is a2mliser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/satellites/a2mliser/llm-warmup-dev.md b/satellites/a2mliser/llm-warmup-dev.md deleted file mode 100644 index d5d0b4c..0000000 --- a/satellites/a2mliser/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2mliser (Developer) - -## What is a2mliser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/satellites/a2mliser/llm-warmup-user.adoc b/satellites/a2mliser/llm-warmup-user.adoc new file mode 100644 index 0000000..a906085 --- /dev/null +++ b/satellites/a2mliser/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — a2mliser (User) + +=== What is a2mliser? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/satellites/a2mliser/llm-warmup-user.md b/satellites/a2mliser/llm-warmup-user.md deleted file mode 100644 index 2255336..0000000 --- a/satellites/a2mliser/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — a2mliser (User) - -## What is a2mliser? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture