Skip to content

Commit 51306ea

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
authored
Feat/panel clades pivot (#38)
* docs(adr): ADR-0001 panel-clades pivot + freeze src-gossamer legacy (P0) Pin down decisions surfaced during tech-debt remediation: - SoT = panel-clades (Idris2 ABI + Zig FFI + a2ml clades); estate-conformant - src-gossamer Rust = FROZEN LEGACY (STATUS.adoc marker); PR #37 = interim legacy-stabilisation only - Reference = Axiom.jl's backend-organisation APPROACH (the pattern, not its coprocessor code); oo7/jtv experimental, out of scope - Backend set (11): FPGA DSP math physics tensor vector I/O audio neural crypto quantum - panel-clades found to be a spec-complete but UNINSTANTIATED template shell (rsr {{placeholders}}, just init never run) - GATE: characterise + re-validate Axiom.jl's approach before any downstream clade/backend build (no speculative work) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(adr): trust only Axiom.jl general form; non-conforming code = presumed mess Per owner guidance: do not look at oo7/jtv at all; any coprocessor/ backend code not resembling the Axiom.jl general form is presumed bot-mess / interference / incomplete and is NOT reference material. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: characterise Axiom.jl general form + gate re-validation verdict Cloned hyperpolymath/Axiom.jl; characterised the standard backend- organisation approach in docs/architecture/AXIOM-GENERAL-FORM.adoc (AbstractBackend taxonomy + SmartBackend per-op dispatch + AcceleratorGate device selection + Idris2-spec/Zig-authoritative split + bidirectional host bridge + parity/smoke CI). Re-validation: Idris2 ABI typechecks clean (0.8.0); Zig FFI main.zig FAILS — 17 'Axiom.jl_*' invalid identifiers from a bad token-substitution bot (should be 'axiom_*'; header/tests/README clean; design sound; trivial repair). Same corruption class also in panel-clades/ffi/zig/. ADR-0001 gate: PASSED with caveat (pattern+spec trusted; P2 build gated on the Axiom.jl de-corruption landing). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 7ebf0fd commit 51306ea

4 files changed

Lines changed: 238 additions & 0 deletions

File tree

‎docs/architecture/AXIOM-GENERAL-FORM.adoc‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
= The Axiom.jl General Form — reference for PanLL coprocessor / backend organisation
4+
:toc: left
5+
:sectnums:
6+
7+
Characterised 2026-05-17 from `hyperpolymath/Axiom.jl` @ HEAD (cloned to
8+
`~/dev/repos/Axiom.jl`). This is the *approach* PanLL's `panel-clades`
9+
coprocessor must follow (per ADR-0001) — the pattern, not Axiom.jl's code.
10+
11+
NOTE: Axiom.jl is the single estate instance where the standard route
12+
reached completion. Treat **only** code resembling this form as reference;
13+
everything else (incl. `src-gossamer/src/coprocessor/`) is presumed mess.
14+
15+
== The seven elements of the general form
16+
17+
. **One abstract supertype.** `abstract type AbstractBackend end`
18+
(`src/backends/abstract.jl`). Every processor class is a concrete subtype.
19+
20+
. **One concrete backend struct per processor class.** Observed taxonomy:
21+
+
22+
[cols="1,3"]
23+
|===
24+
| Reference / impl | `JuliaBackend` (default, debug/reference), `ZigBackend{lib_path}` (high-perf native)
25+
| GPU | `CUDABackend`, `MetalBackend`, `ROCmBackend` — each `{device::Int}`
26+
| Accelerators | `TPUBackend` (tensor), `NPUBackend` (neural), `DSPBackend`, `PPUBackend` (physics), `MathBackend`, `FPGABackend`, `VPUBackend` (vector/vision), `QPUBackend` (quantum), `CryptoBackend` — each `{device::Int}`
27+
|===
28+
+
29+
Maps to PanLL's 11-backend set: FPGA→FPGA, DSP→DSP, math→Math, physics→PPU,
30+
tensor→TPU, vector→VPU, neural→NPU, crypto→Crypto, quantum→QPU. *Gap to
31+
close:* Axiom.jl has no explicit `I/O` or `audio` backend — the form is
32+
extended by adding subtypes following the identical pattern.
33+
34+
. **A `SmartBackend` per-operation dispatcher.** Routes each kernel to its
35+
fastest backend from *recorded benchmark data*, with **graceful fallback
36+
to the Julia/reference backend** when the preferred native backend is
37+
unavailable. Holds references to candidate backends; dispatch is
38+
per-operation (e.g. matmul→BLAS/Julia, gelu→Zig-SIMD), not global.
39+
40+
. **Device selection delegated to `AcceleratorGate`.** Not inline:
41+
`select_backend`, `fits_on_device`, `estimate_cost`, `device_capabilities`,
42+
`detect_platform`, `DeviceCapabilities`, `PlatformInfo`. Capability- and
43+
cost-based selection + platform detection live in a separate registered
44+
package (`hyperpolymath/AcceleratorGate`, already in the Julia
45+
registration chain). PanLL should consume this, not reinvent it.
46+
47+
. **ABI/FFI split = the estate language architecture.**
48+
* **Idris2 ABI = formal spec/scaffold:** `src/Abi/{Types,Layout,Foreign}.idr`,
49+
concrete `axiom_*` symbols (no template placeholders), typechecks via
50+
`idris2 --source-dir src --check`.
51+
* **Zig FFI = authoritative production runtime:**
52+
`ffi/zig/{src/main.zig,build.zig,include/axiom.h,test/integration_test.zig}`,
53+
exports concrete `axiom_*` C ABI symbols. *"For release/readiness
54+
decisions, treat the Zig FFI path as authoritative."*
55+
* **Host bridge:** `src/backends/zig_ffi.jl`. Bidirectional —
56+
host→runtime (`axiom_process`, `axiom_process_array`) and runtime→host
57+
callbacks (`axiom_register_callback`, `axiom_invoke_callback`).
58+
59+
. **Concrete symbol naming.** C ABI symbols are `<project>_*` (here
60+
`axiom_*`) — concrete, no `{{placeholders}}`. PanLL clades use a concrete
61+
`panll_*` / clade-scoped scheme; placeholder-only files are not done.
62+
63+
. **Honest status precedence.** Julia = reference/fallback; Idris2 ABI =
64+
formal scaffold (must typecheck); Zig FFI = authoritative for release.
65+
Plus CI: backend-parity + runtime-smoke checks gate readiness.
66+
67+
== Re-validation status (the ADR-0001 gate)
68+
69+
* **Characterised:** ✅ (this document, from the cloned repo).
70+
* **Self-attested validation (per `Axiom.jl/ABI-FFI-README.md`):** Idris2
71+
ABI typechecks; `cd ffi/zig && zig build test` passes; Julia↔Zig path is
72+
CI-covered (backend parity + runtime smoke). The repo's `EXPLAINME.adoc`
73+
is explicit about caveats (e.g. `@axiom` shape-check is macro-expansion
74+
time, not dependent-type).
75+
* **Independent re-validation (done 2026-05-17):**
76+
** **Idris2 ABI: ✅ PASSES.** `src/Abi/{Types,Layout,Foreign}.idr` all
77+
typecheck clean with Idris2 0.8.0 (`/dev/tools/provers/idris2/0.8.0`).
78+
The formal contract is sound.
79+
** **Zig FFI: ❌ FAILS — mechanical bot corruption.**
80+
`ffi/zig/src/main.zig` has **17** invalid identifiers of the form
81+
`Axiom.jl_init`, `Axiom.jl_process`, … — a bad token substitution put
82+
the *repo name with the `.jl` extension* where the project token
83+
belongs (should be `axiom_init`, `axiom_process`, …). `.` is illegal
84+
in a Zig identifier, so `zig build test` (Zig 0.15.2) does not compile.
85+
** **Damage is localised:** `ffi/zig/include/axiom.h`, the integration
86+
test, and `ABI-FFI-README.md` are **clean** and correctly use
87+
`axiom_*`. Only the implementation file `main.zig` was mangled. The
88+
*design* is intact; this is exactly the "bot/interference mess" class
89+
ADR-0001 warns about, and is a trivial `s/Axiom\.jl_/axiom_/` repair.
90+
** **Estate spread:** the same corruption/placeholder class is present in
91+
`panll/panel-clades/ffi/zig/{build.zig,test/integration_test.zig}`.
92+
93+
=== Gate verdict
94+
95+
**PASSED with caveat.** The architectural general form is characterised and
96+
the formal Idris2 contract re-validates clean — this document is a
97+
trustworthy reference for P2 *design*. The reference *Zig implementation*
98+
needs a trivial de-corruption (Axiom.jl repo, separate from this work)
99+
before it is a runnable exemplar. P2 build (not design) is gated on that
100+
repair landing.
101+
102+
== Implication for PanLL panel-clades
103+
104+
`panel-clades/` already mirrors this skeleton (Idris2 `src/abi/*.idr`, Zig
105+
`ffi/zig/`, a2ml clade specs) but is an *uninstantiated template*. The work
106+
is to instantiate it *to this exact form*: AbstractBackend supertype + 11
107+
backend subtypes + Smart dispatcher + AcceleratorGate consumption + concrete
108+
Idris2 ABI + authoritative Zig FFI + bidirectional host bridge + parity/smoke
109+
CI. No deviation from the Axiom.jl form.

‎docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
= ADR-0001: Panel backend source-of-truth, coprocessor model, and the panel-clades pivot
4+
:toc: left
5+
:sectnums:
6+
7+
[cols="1,3"]
8+
|===
9+
| Status | Accepted (2026-05-17)
10+
| Deciders | Jonathan Jewell (owner)
11+
| Context | PanLL tech-debt remediation surfaced two divergent panel backends and an unverified coprocessor story
12+
|===
13+
14+
== Context
15+
16+
A tech-debt remediation pass on `src-gossamer/` (D1–D5, lib/bin split,
17+
coprocessor FFI — see `docs/TECHNICAL_DEBT.md`, PR #37) uncovered structural
18+
divergence ("rot"):
19+
20+
. **Two parallel panel backends.** `src-gossamer/` is a pure-Rust monolith
21+
(112 `.rs`, raw C ABI) — it is what the binary builds. `panel-clades/` is
22+
the estate-conformant design (Idris2 ABI with safety proofs + Zig FFI +
23+
131 `.a2ml` clade specs). They have diverged; `src-gossamer/` had ~38
24+
panel backends orphaned (declared by no crate root → never compiled).
25+
. **`panel-clades/` is spec-complete but implementation-incomplete.** Its
26+
container/, `ffi/zig/`, `.devcontainer/` are uninstantiated rsr-template
27+
shells (`{{PROJECT_NAME}}`/`{{project}}` placeholders, `just init` never
28+
run). The a2ml clade specs and Idris2 ABI declarations are real; the Zig
29+
FFI implementation and concrete build/container are not.
30+
. **Coprocessor support is mostly unverified.** Across the estate, coprocessor
31+
support was attempted via a "standard approach"; *only Axiom.jl actually
32+
completed it*. `oo7-toolchain` ("007") and `jtv` are experimental designs
33+
that diverge substantially and are **not** reusable as the model.
34+
35+
== Decision
36+
37+
. **Source of truth = `panel-clades/`** (Idris2 ABI + Zig FFI + a2ml clades).
38+
This is the estate-conformant target (API=Zig, FFI=Zig, ABI=Idris2).
39+
. **`src-gossamer/` (Rust) is frozen legacy.** No new feature work. PR #37 is
40+
*interim legacy-stabilisation only* (keeps the legacy buildable during
41+
migration); it is not the go-forward.
42+
. **Reference = Axiom.jl's _architectural approach_, not its code.** We adopt
43+
the *pattern* Axiom.jl uses to make use of many heterogeneous processors
44+
and organise the compute backend — not its coprocessor implementation.
45+
It is the single estate instance where the standard approach reached
46+
completion. `oo7-toolchain` ("007") and `jtv` are explicitly **out of
47+
scope** for reuse (too experimental; substantial design change) and are
48+
tracked separately, untouched by the standard pattern.
49+
. **Axiom.jl's approach must be re-characterised before it is treated as
50+
the reference.** "Only Axiom.jl made it to the end, and it likely needs
51+
looking at again." No downstream clade/backend implementation proceeds
52+
until that approach is documented and re-validated.
53+
. **Coprocessor clade backend set (11):** FPGA, DSP, math, physics, tensor,
54+
vector, I/O, audio, neural, crypto, **quantum**. (Supersedes the legacy
55+
Rust enum, which lacked FPGA/DSP; Graphics dropped.)
56+
57+
== Anti-goals (explicit "do not get excited")
58+
59+
* Do **not** instantiate the `panel-clades/` template, write Zig FFI, or
60+
build speculative containers/coprocessor code **before** Axiom.jl is
61+
obtained and re-audited. Building on an unverified model is the failure
62+
mode this ADR exists to prevent.
63+
* Do **not** delete the 38 legacy Rust panel dirs — they are port-reference
64+
until clade parity, then removed (git history preserves them regardless).
65+
* Do **not** look at `oo7-toolchain` ("007") or `jtv` at all — they are
66+
done separately, are substantially different, and will confuse the
67+
standard route.
68+
* **Trust only the Axiom.jl general form.** Any coprocessor/backend code
69+
in the estate that does *not* resemble the Axiom.jl general form
70+
(including `src-gossamer/src/coprocessor/`, panel-clades clade drafts,
71+
and the 38 legacy panel dirs) is presumed bot-generated mess, third-party
72+
interference, a major failure, or nowhere near complete. It is **not**
73+
reference material and must not be used to infer the design. When in
74+
doubt, defer to the re-validated Axiom.jl approach, not to in-repo code.
75+
76+
== Consequences
77+
78+
* The F1 plan in `docs/TECHNICAL_DEBT.md` ("wire the 38 Rust panels") is
79+
**void** — replaced by: regenerate panels as clades, modelled on the
80+
re-audited Axiom.jl standard route.
81+
* Critical path is gated on **characterising + re-validating Axiom.jl's
82+
backend-organisation approach** (the pattern, not the code). Axiom.jl is
83+
not present in `~/dev/repos`; obtaining it (or an authoritative write-up
84+
of its approach) is the unblock. `jtv` is unlocated and off the standard
85+
route anyway.
86+
* Phasing: P0 record+freeze (this ADR) → **GATE: characterise + re-validate
87+
Axiom.jl's approach** → P1 minimal non-speculative dev-env/`/dev/tools`
88+
provisioning → P2 coprocessor clade exemplar (Axiom.jl-pattern, 11
89+
backends) → P3 bulk panel→clade.
90+
91+
== Gate outcome (2026-05-17)
92+
93+
Axiom.jl cloned to `~/dev/repos/Axiom.jl`; approach characterised in
94+
`docs/architecture/AXIOM-GENERAL-FORM.adoc`. Re-validation:
95+
96+
* Idris2 ABI (`src/Abi/*.idr`) — **typechecks clean** (Idris2 0.8.0).
97+
* Zig FFI (`ffi/zig/src/main.zig`) — **fails to build**: 17 `Axiom.jl_*`
98+
invalid identifiers from a bad token substitution (bot/interference
99+
mess, per the anti-goals above). Header/tests/README are clean; design
100+
is sound; trivial `s/Axiom\.jl_/axiom_/` repair in the Axiom.jl repo.
101+
* Same corruption class also present in `panel-clades/ffi/zig/`.
102+
103+
**Verdict: gate PASSED with caveat.** Pattern + formal contract trusted →
104+
P2 *design* may proceed. P2 *build* is gated on the Axiom.jl `main.zig`
105+
de-corruption landing (separate repo; owner decision pending).
106+
107+
== Status of related artefacts
108+
109+
* PR #37 (`fix/tech-debt-remediation`): merge as legacy-stabilisation or shelve.
110+
* `feat/panel-clades-pivot`: carries this ADR + legacy freeze marker only.
111+
* `docs/TECHNICAL_DEBT.md`: F1 section superseded by this ADR.

‎docs/decisions/DESIGN-DECISIONS.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -477,3 +477,7 @@ PMPL (based on MPL) requires source attribution. Blake3 provenance chains auto-g
477477
---
478478

479479
*Design decisions are numbered sequentially. DD-019 through DD-021 and DD-023 are reserved (not yet assigned). Superseded decisions retain their number with status changed to "Superseded by DD-XXX".*
480+
481+
## ADR-0001 (2026-05-17): panel-clades pivot
482+
483+
SoT = `panel-clades/` (Idris2 ABI + Zig FFI + a2ml clades). `src-gossamer/` Rust = frozen legacy. Coprocessor = Axiom.jl 's organising **approach** (not code); backends: FPGA, DSP, math, physics, tensor, vector, I/O, audio, neural, crypto, quantum. oo7/jtv experimental, out of scope. See `docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc`.

‎src-gossamer/STATUS.adoc‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
= src-gossamer — FROZEN LEGACY
3+
4+
*Status: FROZEN LEGACY (2026-05-17).* Do not add features here.
5+
6+
This pure-Rust Gossamer backend is the *legacy* panel backend. The
7+
source of truth going forward is `panel-clades/` (Idris2 ABI + Zig FFI +
8+
a2ml clades) — see `docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc`.
9+
10+
Permitted changes: security fixes and build-keep-alive only (interim
11+
legacy-stabilisation, e.g. PR #37). All new panel/coprocessor work
12+
happens in `panel-clades/`, modelled on Axiom.jl's standard
13+
backend-organisation approach. The ~38 panel dirs here are
14+
port-reference until clade parity, then removed.

0 commit comments

Comments
 (0)