Skip to content

Commit d7f9b17

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
authored
Base camp: fold in the AOLD/iSOS/-iser-Atlas coordination layer + scaffold emits Mustfile (#60)
* feat: emit Mustfile in scaffold + add AOLD/iSOS/-iser-Atlas coordination layer - scaffold.rs: emit a root Mustfile so freshly generated -isers are RSR-compliant (REQUIRED-FILES.adoc mandates a root Mustfile). Verified: generated newlangiser now includes Mustfile; cargo test 57/57 green. - docs/ATLAS.adoc: the "right place" routing index (need -> -iser). - docs/theory/AOLD.adoc: Aspect-Oriented Language Design (languages as bolt-on aspects; the mech-suit model; the dual of aggregate-library). - docs/theory/iSOS.adoc: Integrated Stack of Stacks (composition over the shared Idris2-ABI/Zig-FFI seam; invariant-path as conscience). - README.adoc: link the coordination layer up front. - Add a root Mustfile to this repo too. Flag (not changed): scaffold.rs generate_license() emits Palimpsest/PMPL text, which conflicts with the MPL-2.0 classification for these sole-owner repos. Licence edits are owner-only/flag-only per standards; surfaced only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Mbq6yKF9RhFai6EQ7WqKhQ * chore: port examples/SafeDOMExample.res → .affine (banned-ReScript removal) Replaces the banned ReScript example with the canonical estate-wide AffineScript port (gitbot-fleet#208 sweep; identical to otpiser). Clears the `governance / Language / package anti-pattern policy` gate (cicd_rules/banned_language_file), which hard-fails on any tracked *.res. Documented resolution per the k9iser HANDOFF (port → AffineScript). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Mbq6yKF9RhFai6EQ7WqKhQ * ci: switch CodeQL matrix javascript-typescript -> actions (Hypatia-prescribed) The repo has no JS/TS source, so `analyze (javascript-typescript, none)` exited "no source files" and failed on every run. Switch the CodeQL matrix to `actions` (scans the GitHub Actions workflows every repo has), per Hypatia's `switch_codeql_matrix_to_actions` recommendation. build-mode none is correct for the actions language; init/analyze read the matrix var, so no other edits are needed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Mbq6yKF9RhFai6EQ7WqKhQ * docs: de-dup CHANGELOG/README per RSR standard (keep .adoc; port sponsor badge) Keeps the maintained CHANGELOG.adoc, removes the stale v0.1.0 CHANGELOG.md stub (verisimiser reversed — its .md is the richer/canonical one). Removes the duplicate README.md, porting its sponsor badge into README.adoc so the rendered GitHub page keeps it. RSR: no duplicate doc formats. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Mbq6yKF9RhFai6EQ7WqKhQ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 1d3aac7 commit d7f9b17

10 files changed

Lines changed: 561 additions & 140 deletions

File tree

‎.github/workflows/codeql.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ jobs:
3030
fail-fast: false
3131
matrix:
3232
include:
33-
- language: javascript-typescript
33+
- language: actions
3434
build-mode: none
3535

3636
steps:

‎CHANGELOG.md‎

Lines changed: 0 additions & 30 deletions
This file was deleted.

‎Mustfile‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# SPDX-License-Identifier: MPL-2.0
2+
# Mustfile — hyperpolymath mandatory checks
3+
# See: https://github.com/hyperpolymath/mustfile
4+
#
5+
# Declarative contract of checks that MUST pass. Each maps to a recipe
6+
# that already exists in this repo's Justfile.
7+
version: 1
8+
9+
checks:
10+
- name: security
11+
run: just lint
12+
- name: tests
13+
run: just test
14+
- name: format
15+
run: just fmt

‎README.adoc‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,20 @@ image:https://img.shields.io/badge/FFI-Zig-orange[Zig FFI]
2222

2323
'''
2424

25+
[TIP]
26+
====
27+
**New here? Start with the coordination layer:**
28+
29+
* link:docs/ATLAS.adoc[**The -iser Atlas**] — route a need straight to the right
30+
-iser ("I want to… → use…").
31+
* link:docs/theory/AOLD.adoc[**Aspect-Oriented Language Design**] — the design
32+
philosophy (each language's superpower as a bolt-on _aspect_; the "mech suit"
33+
model; why this is the _dual_ of aggregate-library).
34+
* link:docs/theory/iSOS.adoc[**Integrated Stack of Stacks**] — how aspects
35+
_compose_ over one shared Idris2-ABI/Zig-FFI seam, kept honest by
36+
invariant-path.
37+
====
38+
2539
== What is the -iser Pattern?
2640

2741
An **-iser** is a Rust CLI that bridges the gap between a _specialist language_

‎docs/ATLAS.adoc‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
// SPDX-License-Identifier: MPL-2.0
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
= The -iser Atlas — find the right -iser
4+
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
5+
:toc: left
6+
:toclevels: 2
7+
:icons: font
8+
:url-org: https://github.com/hyperpolymath
9+
10+
[.lead]
11+
**This is the map.** If you have a codebase and a need, this page routes you to
12+
the -iser that grants it — the "right place" index for the augmentation family.
13+
It is the coordination layer for Aspect-Oriented Language Design (see
14+
`theory/AOLD.adoc`) and the Integrated Stack of Stacks (`theory/iSOS.adoc`).
15+
16+
== How to read this
17+
18+
Every -iser injects _one_ specialist language's superpower into the code you
19+
already have, via `manifest → Idris2 ABI → Zig FFI → codegen → build/run`. You
20+
do not learn the language. Find your need in the left column; go to the -iser in
21+
the middle.
22+
23+
== Route by need
24+
25+
[cols="3,2,3",options="header"]
26+
|===
27+
| I want to… | Use | Aspect / language essence
28+
29+
| …distribute a single-machine workload across a cluster | {url-org}/chapeliser[chapeliser] | Chapel data-parallelism
30+
| …push array/number crunching onto the GPU | {url-org}/futharkiser[futharkiser] | Futhark kernels
31+
| …make a Python/R pipeline ~100× faster | {url-org}/julianiser[julianiser] | Julia
32+
| …add fault tolerance / supervision to concurrent code | {url-org}/otpiser[otpiser] | OTP/BEAM
33+
| …get data-race freedom for concurrency | {url-org}/ponyiser[ponyiser] | Pony reference capabilities
34+
| …optimise an image/video pipeline | {url-org}/halideiser[halideiser] | Halide schedules
35+
| …rewrite array patterns as optimised primitives | {url-org}/bqniser[bqniser] | BQN
36+
| …generate high-performance C libraries | {url-org}/nimiser[nimiser] | Nim metaprogramming
37+
| …prove critical functions correct-by-construction | {url-org}/dafniser[dafniser] | Dafny
38+
| …model-check a state machine | {url-org}/tlaiser[tlaiser] | TLA+/PlusCal
39+
| …find counterexamples in an API model | {url-org}/alloyiser[alloyiser] | Alloy
40+
| …get proven-correct wrappers from interfaces | {url-org}/idrisiser[idrisiser] | Idris2 dependent types
41+
| …verify real-time embedded logic | {url-org}/lustreiser[lustreiser] | Lustre
42+
| …add formal type safety to a query language | {url-org}/typedqliser[typedqliser] | graded type systems
43+
| …wrap C in zero-cost memory safety | {url-org}/atsiser[atsiser] | ATS linear types
44+
| …enforce use-exactly-once on resources | {url-org}/ephapaxiser[ephapaxiser] | Ephapax linear semantics
45+
| …target WASM with affine + dependent types | {url-org}/affinescriptiser[affinescriptiser] | AffineScript
46+
| …augment any database (drift/provenance/temporal) | {url-org}/verisimiser[verisimiser] | VeriSimDB octad
47+
| …make configs self-validating | {url-org}/k9iser[k9iser] | K9 contracts
48+
| …add cryptographic attestation to markup/config | {url-org}/a2mliser[a2mliser] | A2ML
49+
| …make operations reversible + auditable | {url-org}/oblibeniser[oblibeniser] | Oblíbený
50+
| …add energy/carbon/cost awareness | {url-org}/eclexiaiser[eclexiaiser] | Eclexia
51+
| …put provably-safe ethical guardrails on an AI agent | {url-org}/phronesiser[phronesiser] | Phronesis
52+
| …add consent flows + accessibility | {url-org}/wokelangiser[wokelangiser] | WokeLang
53+
| …model uncertainty over deterministic code | {url-org}/betlangiser[betlangiser] | Betlang ternary probability
54+
| …expose a complex API progressively | {url-org}/mylangiser[mylangiser] | My-Lang
55+
| …formalise ISU figure-skating notation | {url-org}/anvomidaviser[anvomidaviser] | Anvomidav
56+
| …scaffold a brand-new -iser for another language | {url-org}/iseriser[iseriser] | the meta-framework
57+
|===
58+
59+
NOTE: Status across the family is _scaffold → pre-alpha_; `chapeliser`,
60+
`verisimiser`, and `typedqliser` are the most developed. Each -iser's own
61+
`ROADMAP.adoc` is the source of truth for its maturity. (The family READMEs
62+
historically over-stated test counts; trust the per-repo `cargo test` output.)
63+
64+
== What -iserisation is — and is not
65+
66+
[cols="1,3",options="header"]
67+
|===
68+
| -iserisation is… | …and it is _not_
69+
70+
| **augmentation**: bolt one specialist language's power onto a foreign host
71+
| **aggregate-library**: aLib is the _dual_ — the minimal _overlap_ common to all
72+
systems. -isers add the exotic edge; aLib distils the shared core.
73+
74+
| a **coordination atlas**: the index that sends you to the right capability
75+
| nextgen-language-evangeliser: that advocates adopting whole next-gen languages;
76+
the atlas routes you to a _capability_, no adoption required.
77+
78+
| a family of **proof-carrying seams** (Idris2 ABI + Zig FFI)
79+
| the dyadic language/toolchain design of Ephapax, or an AffineScript "face".
80+
|===
81+
82+
== The pattern in one diagram
83+
84+
[literal]
85+
....
86+
your app ──► <name>.toml ──► the -iser CLI
87+
│
88+
┌─────────────────┼─────────────────┐
89+
▼ ▼ ▼
90+
Idris2 ABI Zig FFI target codegen
91+
(prove interface) (C-ABI bridge) (specialist lang)
92+
└─────────────────┴─────────────────┘
93+
▼
94+
your app, now wearing the aspect
95+
....
96+
97+
== Getting started
98+
99+
[source,bash]
100+
----
101+
# install any -iser (standalone Rust binary)
102+
cargo install chapeliser # …or any name above
103+
104+
# the shared five-command interface
105+
<iser> init # write a manifest for your project
106+
<iser> validate # check it against the Idris2 ABI spec
107+
<iser> generate # emit the specialist-language code
108+
<iser> build # build the generated output
109+
<iser> run # run it
110+
----
111+
112+
To create an aspect for a language that has no -iser yet, use the meta-framework:
113+
`iseriser generate -m <language>.toml -o ./<name>iser` (see
114+
`examples/newlang/iseriser.toml`).
115+
116+
== See also
117+
118+
* `theory/AOLD.adoc` — the design philosophy (languages as aspects).
119+
* `theory/iSOS.adoc` — the architecture (composing aspects).
120+
* `../README.adoc` — family overview, architecture diagram, full install/usage.

‎docs/theory/AOLD.adoc‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
// SPDX-License-Identifier: MPL-2.0
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
= Aspect-Oriented Language Design (AOLD)
4+
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
5+
:toc: left
6+
:toclevels: 3
7+
:icons: font
8+
9+
[.lead]
10+
**AOLD is the design philosophy behind the -iser family.** Instead of choosing
11+
one general-purpose language and living with its global trade-offs, AOLD treats
12+
each specialist language's _unique strength_ as a weavable **aspect** that you
13+
can bolt onto an existing codebase on demand — and remove just as easily.
14+
15+
== The problem AOLD answers
16+
17+
Every language makes one global bet. Chapel bets everything on distributed
18+
data-parallelism; Pony on data-race-free actors; Dafny on
19+
correct-by-construction proof; Futhark on GPU array kernels; OTP on
20+
fault-tolerant supervision. Each is _extraordinary_ at its one thing and
21+
ordinary (or absent) at everything else.
22+
23+
In practice that bet is hard to take:
24+
25+
. **Steep learning curve** — to get the superpower you must rewrite in, or deeply
26+
learn, the specialist language.
27+
. **All-or-nothing adoption** — there is rarely an incremental path; you commit
28+
the whole system or none of it.
29+
. **Integration tax** — wiring the specialist runtime into your existing
30+
Rust/C/Zig project is non-trivial and easy to get subtly wrong.
31+
32+
So the superpowers stay locked behind their languages, and most projects never
33+
touch them.
34+
35+
== The core idea: languages as aspects
36+
37+
AOLD unlocks the superpower _without_ taking the global bet. An **-iser** is a
38+
Rust CLI that injects exactly one specialist language's capability into the code
39+
you already write, through a uniform, proof-carrying pipeline:
40+
41+
[literal]
42+
....
43+
your manifest ──► Idris2 ABI ──► Zig FFI ──► target-language codegen ──► build / run
44+
(what you want) (prove the (C-ABI (emit the specialist (you never
45+
interface) bridge) language's code) wrote any)
46+
....
47+
48+
You describe _what_ you want in a declarative TOML manifest. The -iser validates
49+
it against a formally verified **Idris2 ABI**, bridges to your application across
50+
a **Zig FFI** seam, generates the specialist-language code, and builds it. You
51+
get the aspect; you never learn the language.
52+
53+
== The "mech suit" mental model
54+
55+
The cleanest way to think about an -iser is as a **mech suit for your
56+
application**. Your program/database/tool stays exactly what it is — its own
57+
language, its own logic. The -iser is an _exoskeleton_ that grants it one exotic
58+
capability it did not have: distribution, GPU acceleration, data-race freedom,
59+
fault tolerance, machine-checked correctness, energy-awareness, reversibility.
60+
61+
Three properties make it a suit rather than a rewrite:
62+
63+
* **Addable** — you bolt it on around the existing code, at the boundary.
64+
* **Removable / reversible** — take the suit off and the original program is
65+
unchanged. Nothing is load-bearing on the aspect that cannot be unwound.
66+
* **Composable** — suits stack. See `iSOS.adoc` for how multiple aspects layer
67+
on one host (the _Integrated Stack of Stacks_).
68+
69+
== What AOLD is _not_
70+
71+
[cols="1,3",options="header"]
72+
|===
73+
| It is not… | …because
74+
75+
| aggregate-library (aLib)
76+
| aLib is the **dual** of AOLD. aLib finds the minimal _overlap_ common to all
77+
systems (subtractive: the greatest common denominator, conformance-tested).
78+
AOLD adds the exotic _differentiator_ of one system (additive: the specialist
79+
edge). aLib reduces to the shared core; -isers extend with the rare capability.
80+
81+
| the dyadic toolchain/language design of Ephapax
82+
| Ephapax is about the design of a single language and its paired toolchain.
83+
AOLD is about _weaving many languages' aspects_ onto a foreign host.
84+
85+
| an AffineScript-style "face"
86+
| A "face" is a uniform surface over a substrate. An aspect is a _capability
87+
injection_ at a proof-carrying seam, not a presentation layer.
88+
89+
| nextgen-language-evangeliser
90+
| That project advocates for next-generation languages as wholes. The -iser
91+
atlas (`ATLAS.adoc`) routes you to a _capability_, not to a language to adopt.
92+
|===
93+
94+
== The aspect taxonomy
95+
96+
Each -iser is one aspect. The family is the palette.
97+
98+
[cols="2,3,2",options="header"]
99+
|===
100+
| -iser | Aspect (the superpower it weaves in) | Host gains
101+
102+
| typedqliser | Formal type safety (10 graded levels) over a query language | injection-/null-/schema-safe queries
103+
| chapeliser | Chapel distributed data-parallelism | single-machine workload → cluster
104+
| verisimiser | VeriSimDB octad capabilities | drift / provenance / temporal over any DB
105+
| julianiser | Julia numerical performance | 100× speedups for Python/R pipelines
106+
| futharkiser | Futhark GPU array kernels | data-parallel ops → GPU
107+
| idrisiser | Idris2 dependent-type proofs | proven-correct wrappers from interfaces
108+
| dafniser | Dafny correct-by-construction | verified critical functions
109+
| tlaiser | TLA+/PlusCal model checking | state machines checked for safety/liveness
110+
| alloyiser | Alloy relational model finding | formal models from API specs
111+
| lustreiser | Lustre synchronous dataflow | verified real-time embedded code
112+
| ponyiser | Pony reference capabilities | data-race freedom for concurrent code
113+
| otpiser | OTP/BEAM supervision | fault-tolerance trees, let-it-crash resilience
114+
| halideiser | Halide schedule optimisation | optimised image/video pipelines
115+
| bqniser | BQN array primitives | array patterns rewritten as optimised idioms
116+
| nimiser | Nim metaprogramming | high-performance C libraries
117+
| atsiser | ATS linear types | zero-cost memory safety wrapping C
118+
| affinescriptiser | AffineScript affine + dependent types | WASM-targeted resource safety
119+
| a2mliser | A2ML cryptographic attestation | tamper-evident markup / configuration
120+
| ephapaxiser | Ephapax single-use linear semantics | enforce use-exactly-once on resources
121+
| eclexiaiser | Eclexia cost modelling | energy / carbon / resource-cost awareness
122+
| k9iser | K9 contracts | configs become self-validating
123+
| oblibeniser | Oblíbený reversibility | operations made reversible + auditable
124+
| phronesiser | Phronesis ethical constraints | provably-safe guardrails for AI agents
125+
| wokelangiser | WokeLang consent + a11y patterns | consent flows and accessibility
126+
| betlangiser | Betlang ternary probabilistic modelling | uncertainty over deterministic code
127+
| mylangiser | My-Lang progressive disclosure | layered interfaces over complex APIs
128+
| anvomidaviser | Anvomidav ISU notation | figure-skating programs as formal artefacts
129+
|===
130+
131+
`iseriser` is the meta-framework that scaffolds new aspects into this palette.
132+
133+
== The proof-carrying seam
134+
135+
An aspect is only worth bolting on if its guarantee survives the journey into
136+
your host. AOLD makes that survivable by construction:
137+
138+
* The **Idris2 ABI** is where the aspect's invariant is _proven_ — e.g.
139+
chapeliser proves `PartitionComplete` (every item is placed) and
140+
`PartitionDisjoint` (no item is placed twice) and `GatherConservation`
141+
(no result is lost).
142+
* The **Zig FFI** is the zero-overhead C-ABI bridge that carries data across the
143+
boundary without re-introducing unsafety.
144+
* **invariant-path** is the conscience: it _traces the proven invariant across
145+
the seam into the host_ and flags any point where the guarantee is silently
146+
over-generalised (the classic `theorem → guarantee → "universal claim"`
147+
slide). See `iSOS.adoc`.
148+
149+
== See also
150+
151+
* `iSOS.adoc` — how aspects compose into an Integrated Stack of Stacks.
152+
* `../ATLAS.adoc` — the routing map: pick the -iser for your need.
153+
* `../../README.adoc` — the family overview and install/usage.

0 commit comments

Comments
 (0)