From 18bdb5f4c9abb236daa09c90d424f700b4658e66 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 20:34:18 +0100 Subject: [PATCH] docs(readme): convert README.adoc -> Markdown README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README must be real Markdown to render in GitHub community-health, the GitHub profile, and external MCP directories (Glama) — AsciiDoc shows as raw markup there. pandoc asciidoc->GFM, badges fixed to clickable, SPDX header kept as an HTML comment, duplicate README.adoc removed. Co-Authored-By: Claude Opus 4.8 --- README.adoc | 429 ---------------------------------------------------- README.md | 311 +++++++++++++++++++++++++++++++++++++ 2 files changed, 311 insertions(+), 429 deletions(-) delete mode 100644 README.adoc create mode 100644 README.md diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 808f4c7..0000000 --- a/README.adoc +++ /dev/null @@ -1,429 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -= The -iser Ecosystem -Jonathan D.A. Jewell -:toc: left -:toclevels: 3 -:icons: font -:source-highlighter: rouge -:url-hub: https://hyperpolymath.github.io/iseriser/ -:url-org: https://github.com/hyperpolymath - -image:https://img.shields.io/badge/license-PMPL--1.0--or--later-blue[License: MPL-2.0,link=LICENSE] -image:https://img.shields.io/badge/Palimpsest-Covenant-purple[Palimpsest Covenant] -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] - -[.lead] -**29 Rust CLI tools that inject superpowers from specialist languages into your existing codebase -- without you ever learning those languages.** - -{url-hub}[Browse the Hub] | <> | <> - -''' - -[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: - -. **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: - -[literal] -.... - +---------------------------+ - | 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) - -[cols="3,5,1,1",options="header"] -|=== -| Name | Description | Tests | Status - -| {url-org}/typedqliser[**TypedQLiser**] -| Add formal type safety (10 levels, dependent/linear/session types) to any query language -| 0 -| scaffold - -| {url-org}/chapeliser[**Chapeliser**] -| General-purpose Chapel acceleration -- distribute any workload without learning Chapel -| 22 -| scaffold - -| {url-org}/verisimiser[**Verisimiser**] -| Augment any database with VeriSimDB octad capabilities -- drift, provenance, temporal -| 26 -| scaffold - -| {url-org}/julianiser[**Julianiser**] -| Auto-wrap Python/R data pipelines into Julia for 100x speedups -| 25 -| scaffold - -| {url-org}/futharkiser[**Futharkiser**] -| Compile annotated array operations to GPU kernels via Futhark -| 42 -| scaffold - -| {url-org}/idrisiser[**Idrisiser**] -| Generate proven-correct wrappers from interfaces using Idris2 dependent types -| 6 -| scaffold - -| {url-org}/tlaiser[**TLAiser**] -| Extract state machines from code and model-check with TLA+/PlusCal -| 32 -| scaffold - -| {url-org}/dafniser[**Dafniser**] -| Generate correct-by-construction code for critical functions using Dafny -| 28 -| scaffold - -| {url-org}/ponyiser[**Ponyiser**] -| Wrap concurrent code in Pony reference capabilities for data-race freedom -| 27 -| scaffold - -| {url-org}/otpiser[**OTPiser**] -| Generate OTP supervision trees and fault-tolerance scaffolding -| 1 -| scaffold - -| {url-org}/halideiser[**Halideiser**] -| Compile image/video pipelines to optimised Halide schedules -| 24 -| scaffold - -| {url-org}/lustreiser[**Lustreiser**] -| Generate formally verified real-time embedded code via Lustre -| 36 -| scaffold - -| {url-org}/bqniser[**BQNiser**] -| Detect array patterns and rewrite as optimised BQN primitives -| 0 -| scaffold - -| {url-org}/alloyiser[**Alloyiser**] -| Extract formal models from API specs and verify with Alloy -| 25 -| scaffold - -| {url-org}/atsiser[**ATSiser**] -| Wrap C codebases in ATS linear types for zero-cost memory safety -| 32 -| scaffold - -| {url-org}/nimiser[**Nimiser**] -| Generate high-performance C libraries via Nim metaprogramming -| 28 -| scaffold - -| {url-org}/a2mliser[**A2MLiser**] -| Add cryptographic attestation to any markup or configuration via A2ML -| 0 -| scaffold - -| {url-org}/affinescriptiser[**AffineScriptiser**] -| Wrap code in affine + dependent types targeting WASM via AffineScript -| 36 -| scaffold - -| {url-org}/anvomidaviser[**Anvomidaviser**] -| Convert ISU notation to formal figure skating programs via Anvomidav -| 36 -| scaffold - -| {url-org}/betlangiser[**BetLangiser**] -| Add ternary probabilistic modelling to deterministic code via Betlang -| 36 -| scaffold - -| {url-org}/eclexiaiser[**Eclexiaiser**] -| Add energy/carbon/resource-cost awareness to software via Eclexia -| 23 -| scaffold - -| {url-org}/ephapaxiser[**Ephapaxiser**] -| Enforce single-use linear type semantics on resources via Ephapax -| 17 -| scaffold - -| {url-org}/k9iser[**K9iser**] -| Wrap configs into self-validating K9 contracts -| 19 -| scaffold - -| {url-org}/mylangiser[**MyLangiser**] -| Generate progressive-disclosure interfaces from complex APIs via My-Lang -| 20 -| scaffold - -| {url-org}/oblibeniser[**Oblibeniser**] -| Make operations reversible and auditable via Oblibeny -| 27 -| scaffold - -| {url-org}/phronesiser[**Phronesiser**] -| Add provably safe ethical constraints to AI agents via Phronesis -| 31 -| scaffold - -| {url-org}/wokelangiser[**WokeLangiser**] -| Add consent patterns and accessibility to existing code via WokeLang -| 44 -| scaffold - -| {url-org}/squeakwell[**SqueakWell**] -| Database recovery through cross-modal constraint propagation -- 8 modalities -| 0 -| scaffold - -| {url-org}/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: - -[cols="1,3"] -|=== -| `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 -https://github.com/hyperpolymath/standards/issues/92[standards#92] -(Phase 1 + 1b); see -`examples/abi-manifests/README.adoc` for the schema, the drift -taxonomy, and end-to-end usage. - -The `cartridge` subcommand implements -https://github.com/hyperpolymath/standards/issues/89[standards#89] -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 -https://github.com/hyperpolymath/standards/issues/91[standards#91] -(http-capability-gateway tier-2 production-wiring). - -== Generated Repo Structure - -When iseriser generates a new -iser, it produces: - -[source] ----- -/ -+-- 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: - -**{url-hub}** - -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 link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for guidelines. All contributions -must pass the full CI suite including Hypatia neurosymbolic scanning. - -== License - -SPDX-License-Identifier: `MPL-2.0` - -Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -Licensed under the https://github.com/hyperpolymath/palimpsest-license[Palimpsest License]. diff --git a/README.md b/README.md new file mode 100644 index 0000000..3eac4f4 --- /dev/null +++ b/README.md @@ -0,0 +1,311 @@ + + +[![License: MPL-2.0](https://img.shields.io/badge/license-PMPL--1.0--or--later-blue)](LICENSE) ![Palimpsest +Covenant](https://img.shields.io/badge/Palimpsest-Covenant-purple) ![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 + +SPDX-License-Identifier: `MPL-2.0` + +Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +Licensed under the [Palimpsest +License](https://github.com/hyperpolymath/palimpsest-license).