From b9357273717308ea1b990dfb4037ef567e44fda0 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 17 May 2026 13:36:46 +0100 Subject: [PATCH 1/3] 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) --- ...01-coprocessor-and-panel-clades-pivot.adoc | 86 +++++++++++++++++++ docs/decisions/DESIGN-DECISIONS.md | 4 + src-gossamer/STATUS.adoc | 14 +++ 3 files changed, 104 insertions(+) create mode 100644 docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc create mode 100644 src-gossamer/STATUS.adoc diff --git a/docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc b/docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc new file mode 100644 index 00000000..826a55d6 --- /dev/null +++ b/docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc @@ -0,0 +1,86 @@ +// SPDX-License-Identifier: PMPL-1.0-or-later +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) += ADR-0001: Panel backend source-of-truth, coprocessor model, and the panel-clades pivot +:toc: left +:sectnums: + +[cols="1,3"] +|=== +| Status | Accepted (2026-05-17) +| Deciders | Jonathan Jewell (owner) +| Context | PanLL tech-debt remediation surfaced two divergent panel backends and an unverified coprocessor story +|=== + +== Context + +A tech-debt remediation pass on `src-gossamer/` (D1–D5, lib/bin split, +coprocessor FFI — see `docs/TECHNICAL_DEBT.md`, PR #37) uncovered structural +divergence ("rot"): + +. **Two parallel panel backends.** `src-gossamer/` is a pure-Rust monolith + (112 `.rs`, raw C ABI) — it is what the binary builds. `panel-clades/` is + the estate-conformant design (Idris2 ABI with safety proofs + Zig FFI + + 131 `.a2ml` clade specs). They have diverged; `src-gossamer/` had ~38 + panel backends orphaned (declared by no crate root → never compiled). +. **`panel-clades/` is spec-complete but implementation-incomplete.** Its + container/, `ffi/zig/`, `.devcontainer/` are uninstantiated rsr-template + shells (`{{PROJECT_NAME}}`/`{{project}}` placeholders, `just init` never + run). The a2ml clade specs and Idris2 ABI declarations are real; the Zig + FFI implementation and concrete build/container are not. +. **Coprocessor support is mostly unverified.** Across the estate, coprocessor + support was attempted via a "standard approach"; *only Axiom.jl actually + completed it*. `oo7-toolchain` ("007") and `jtv` are experimental designs + that diverge substantially and are **not** reusable as the model. + +== Decision + +. **Source of truth = `panel-clades/`** (Idris2 ABI + Zig FFI + a2ml clades). + This is the estate-conformant target (API=Zig, FFI=Zig, ABI=Idris2). +. **`src-gossamer/` (Rust) is frozen legacy.** No new feature work. PR #37 is + *interim legacy-stabilisation only* (keeps the legacy buildable during + migration); it is not the go-forward. +. **Reference = Axiom.jl's _architectural approach_, not its code.** We adopt + the *pattern* Axiom.jl uses to make use of many heterogeneous processors + and organise the compute backend — not its coprocessor implementation. + It is the single estate instance where the standard approach reached + completion. `oo7-toolchain` ("007") and `jtv` are explicitly **out of + scope** for reuse (too experimental; substantial design change) and are + tracked separately, untouched by the standard pattern. +. **Axiom.jl's approach must be re-characterised before it is treated as + the reference.** "Only Axiom.jl made it to the end, and it likely needs + looking at again." No downstream clade/backend implementation proceeds + until that approach is documented and re-validated. +. **Coprocessor clade backend set (11):** FPGA, DSP, math, physics, tensor, + vector, I/O, audio, neural, crypto, **quantum**. (Supersedes the legacy + Rust enum, which lacked FPGA/DSP; Graphics dropped.) + +== Anti-goals (explicit "do not get excited") + +* Do **not** instantiate the `panel-clades/` template, write Zig FFI, or + build speculative containers/coprocessor code **before** Axiom.jl is + obtained and re-audited. Building on an unverified model is the failure + mode this ADR exists to prevent. +* Do **not** delete the 38 legacy Rust panel dirs — they are port-reference + until clade parity, then removed (git history preserves them regardless). +* Do **not** follow `oo7`/`jtv` patterns anywhere in the standard route. + +== Consequences + +* The F1 plan in `docs/TECHNICAL_DEBT.md` ("wire the 38 Rust panels") is + **void** — replaced by: regenerate panels as clades, modelled on the + re-audited Axiom.jl standard route. +* Critical path is gated on **characterising + re-validating Axiom.jl's + backend-organisation approach** (the pattern, not the code). Axiom.jl is + not present in `~/dev/repos`; obtaining it (or an authoritative write-up + of its approach) is the unblock. `jtv` is unlocated and off the standard + route anyway. +* Phasing: P0 record+freeze (this ADR) → **GATE: characterise + re-validate + Axiom.jl's approach** → P1 minimal non-speculative dev-env/`/dev/tools` + provisioning → P2 coprocessor clade exemplar (Axiom.jl-pattern, 11 + backends) → P3 bulk panel→clade. + +== Status of related artefacts + +* PR #37 (`fix/tech-debt-remediation`): merge as legacy-stabilisation or shelve. +* `feat/panel-clades-pivot`: carries this ADR + legacy freeze marker only. +* `docs/TECHNICAL_DEBT.md`: F1 section superseded by this ADR. diff --git a/docs/decisions/DESIGN-DECISIONS.md b/docs/decisions/DESIGN-DECISIONS.md index ddf0900c..289cebba 100644 --- a/docs/decisions/DESIGN-DECISIONS.md +++ b/docs/decisions/DESIGN-DECISIONS.md @@ -477,3 +477,7 @@ PMPL (based on MPL) requires source attribution. Blake3 provenance chains auto-g --- *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".* + +## ADR-0001 (2026-05-17): panel-clades pivot + +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`. diff --git a/src-gossamer/STATUS.adoc b/src-gossamer/STATUS.adoc new file mode 100644 index 00000000..65e14dc9 --- /dev/null +++ b/src-gossamer/STATUS.adoc @@ -0,0 +1,14 @@ +// SPDX-License-Identifier: PMPL-1.0-or-later += src-gossamer — FROZEN LEGACY + +*Status: FROZEN LEGACY (2026-05-17).* Do not add features here. + +This pure-Rust Gossamer backend is the *legacy* panel backend. The +source of truth going forward is `panel-clades/` (Idris2 ABI + Zig FFI + +a2ml clades) — see `docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc`. + +Permitted changes: security fixes and build-keep-alive only (interim +legacy-stabilisation, e.g. PR #37). All new panel/coprocessor work +happens in `panel-clades/`, modelled on Axiom.jl's standard +backend-organisation approach. The ~38 panel dirs here are +port-reference until clade parity, then removed. From 408e4f98f0dda16930ddac2c6ff3d40da4503a27 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 17 May 2026 13:37:14 +0100 Subject: [PATCH 2/3] 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) --- .../ADR-0001-coprocessor-and-panel-clades-pivot.adoc | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc b/docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc index 826a55d6..bfd351b4 100644 --- a/docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc +++ b/docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc @@ -62,7 +62,16 @@ divergence ("rot"): mode this ADR exists to prevent. * Do **not** delete the 38 legacy Rust panel dirs — they are port-reference until clade parity, then removed (git history preserves them regardless). -* Do **not** follow `oo7`/`jtv` patterns anywhere in the standard route. +* Do **not** look at `oo7-toolchain` ("007") or `jtv` at all — they are + done separately, are substantially different, and will confuse the + standard route. +* **Trust only the Axiom.jl general form.** Any coprocessor/backend code + in the estate that does *not* resemble the Axiom.jl general form + (including `src-gossamer/src/coprocessor/`, panel-clades clade drafts, + and the 38 legacy panel dirs) is presumed bot-generated mess, third-party + interference, a major failure, or nowhere near complete. It is **not** + reference material and must not be used to infer the design. When in + doubt, defer to the re-validated Axiom.jl approach, not to in-repo code. == Consequences From 2f91fa6975fae334c5758b52e4e09e2dd4d9fe2a Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 17 May 2026 13:52:44 +0100 Subject: [PATCH 3/3] docs: characterise Axiom.jl general form + gate re-validation verdict MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- docs/architecture/AXIOM-GENERAL-FORM.adoc | 109 ++++++++++++++++++ ...01-coprocessor-and-panel-clades-pivot.adoc | 16 +++ 2 files changed, 125 insertions(+) create mode 100644 docs/architecture/AXIOM-GENERAL-FORM.adoc diff --git a/docs/architecture/AXIOM-GENERAL-FORM.adoc b/docs/architecture/AXIOM-GENERAL-FORM.adoc new file mode 100644 index 00000000..4af938bd --- /dev/null +++ b/docs/architecture/AXIOM-GENERAL-FORM.adoc @@ -0,0 +1,109 @@ +// SPDX-License-Identifier: PMPL-1.0-or-later +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) += The Axiom.jl General Form — reference for PanLL coprocessor / backend organisation +:toc: left +:sectnums: + +Characterised 2026-05-17 from `hyperpolymath/Axiom.jl` @ HEAD (cloned to +`~/dev/repos/Axiom.jl`). This is the *approach* PanLL's `panel-clades` +coprocessor must follow (per ADR-0001) — the pattern, not Axiom.jl's code. + +NOTE: Axiom.jl is the single estate instance where the standard route +reached completion. Treat **only** code resembling this form as reference; +everything else (incl. `src-gossamer/src/coprocessor/`) is presumed mess. + +== The seven elements of the general form + +. **One abstract supertype.** `abstract type AbstractBackend end` + (`src/backends/abstract.jl`). Every processor class is a concrete subtype. + +. **One concrete backend struct per processor class.** Observed taxonomy: ++ +[cols="1,3"] +|=== +| Reference / impl | `JuliaBackend` (default, debug/reference), `ZigBackend{lib_path}` (high-perf native) +| GPU | `CUDABackend`, `MetalBackend`, `ROCmBackend` — each `{device::Int}` +| Accelerators | `TPUBackend` (tensor), `NPUBackend` (neural), `DSPBackend`, `PPUBackend` (physics), `MathBackend`, `FPGABackend`, `VPUBackend` (vector/vision), `QPUBackend` (quantum), `CryptoBackend` — each `{device::Int}` +|=== ++ +Maps to PanLL's 11-backend set: FPGA→FPGA, DSP→DSP, math→Math, physics→PPU, +tensor→TPU, vector→VPU, neural→NPU, crypto→Crypto, quantum→QPU. *Gap to +close:* Axiom.jl has no explicit `I/O` or `audio` backend — the form is +extended by adding subtypes following the identical pattern. + +. **A `SmartBackend` per-operation dispatcher.** Routes each kernel to its + fastest backend from *recorded benchmark data*, with **graceful fallback + to the Julia/reference backend** when the preferred native backend is + unavailable. Holds references to candidate backends; dispatch is + per-operation (e.g. matmul→BLAS/Julia, gelu→Zig-SIMD), not global. + +. **Device selection delegated to `AcceleratorGate`.** Not inline: + `select_backend`, `fits_on_device`, `estimate_cost`, `device_capabilities`, + `detect_platform`, `DeviceCapabilities`, `PlatformInfo`. Capability- and + cost-based selection + platform detection live in a separate registered + package (`hyperpolymath/AcceleratorGate`, already in the Julia + registration chain). PanLL should consume this, not reinvent it. + +. **ABI/FFI split = the estate language architecture.** + * **Idris2 ABI = formal spec/scaffold:** `src/Abi/{Types,Layout,Foreign}.idr`, + concrete `axiom_*` symbols (no template placeholders), typechecks via + `idris2 --source-dir src --check`. + * **Zig FFI = authoritative production runtime:** + `ffi/zig/{src/main.zig,build.zig,include/axiom.h,test/integration_test.zig}`, + exports concrete `axiom_*` C ABI symbols. *"For release/readiness + decisions, treat the Zig FFI path as authoritative."* + * **Host bridge:** `src/backends/zig_ffi.jl`. Bidirectional — + host→runtime (`axiom_process`, `axiom_process_array`) and runtime→host + callbacks (`axiom_register_callback`, `axiom_invoke_callback`). + +. **Concrete symbol naming.** C ABI symbols are `_*` (here + `axiom_*`) — concrete, no `{{placeholders}}`. PanLL clades use a concrete + `panll_*` / clade-scoped scheme; placeholder-only files are not done. + +. **Honest status precedence.** Julia = reference/fallback; Idris2 ABI = + formal scaffold (must typecheck); Zig FFI = authoritative for release. + Plus CI: backend-parity + runtime-smoke checks gate readiness. + +== Re-validation status (the ADR-0001 gate) + +* **Characterised:** ✅ (this document, from the cloned repo). +* **Self-attested validation (per `Axiom.jl/ABI-FFI-README.md`):** Idris2 + ABI typechecks; `cd ffi/zig && zig build test` passes; Julia↔Zig path is + CI-covered (backend parity + runtime smoke). The repo's `EXPLAINME.adoc` + is explicit about caveats (e.g. `@axiom` shape-check is macro-expansion + time, not dependent-type). +* **Independent re-validation (done 2026-05-17):** + ** **Idris2 ABI: ✅ PASSES.** `src/Abi/{Types,Layout,Foreign}.idr` all + typecheck clean with Idris2 0.8.0 (`/dev/tools/provers/idris2/0.8.0`). + The formal contract is sound. + ** **Zig FFI: ❌ FAILS — mechanical bot corruption.** + `ffi/zig/src/main.zig` has **17** invalid identifiers of the form + `Axiom.jl_init`, `Axiom.jl_process`, … — a bad token substitution put + the *repo name with the `.jl` extension* where the project token + belongs (should be `axiom_init`, `axiom_process`, …). `.` is illegal + in a Zig identifier, so `zig build test` (Zig 0.15.2) does not compile. + ** **Damage is localised:** `ffi/zig/include/axiom.h`, the integration + test, and `ABI-FFI-README.md` are **clean** and correctly use + `axiom_*`. Only the implementation file `main.zig` was mangled. The + *design* is intact; this is exactly the "bot/interference mess" class + ADR-0001 warns about, and is a trivial `s/Axiom\.jl_/axiom_/` repair. + ** **Estate spread:** the same corruption/placeholder class is present in + `panll/panel-clades/ffi/zig/{build.zig,test/integration_test.zig}`. + +=== Gate verdict + +**PASSED with caveat.** The architectural general form is characterised and +the formal Idris2 contract re-validates clean — this document is a +trustworthy reference for P2 *design*. The reference *Zig implementation* +needs a trivial de-corruption (Axiom.jl repo, separate from this work) +before it is a runnable exemplar. P2 build (not design) is gated on that +repair landing. + +== Implication for PanLL panel-clades + +`panel-clades/` already mirrors this skeleton (Idris2 `src/abi/*.idr`, Zig +`ffi/zig/`, a2ml clade specs) but is an *uninstantiated template*. The work +is to instantiate it *to this exact form*: AbstractBackend supertype + 11 +backend subtypes + Smart dispatcher + AcceleratorGate consumption + concrete +Idris2 ABI + authoritative Zig FFI + bidirectional host bridge + parity/smoke +CI. No deviation from the Axiom.jl form. diff --git a/docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc b/docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc index bfd351b4..afc9216b 100644 --- a/docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc +++ b/docs/decisions/ADR-0001-coprocessor-and-panel-clades-pivot.adoc @@ -88,6 +88,22 @@ divergence ("rot"): provisioning → P2 coprocessor clade exemplar (Axiom.jl-pattern, 11 backends) → P3 bulk panel→clade. +== Gate outcome (2026-05-17) + +Axiom.jl cloned to `~/dev/repos/Axiom.jl`; approach characterised in +`docs/architecture/AXIOM-GENERAL-FORM.adoc`. Re-validation: + +* Idris2 ABI (`src/Abi/*.idr`) — **typechecks clean** (Idris2 0.8.0). +* Zig FFI (`ffi/zig/src/main.zig`) — **fails to build**: 17 `Axiom.jl_*` + invalid identifiers from a bad token substitution (bot/interference + mess, per the anti-goals above). Header/tests/README are clean; design + is sound; trivial `s/Axiom\.jl_/axiom_/` repair in the Axiom.jl repo. +* Same corruption class also present in `panel-clades/ffi/zig/`. + +**Verdict: gate PASSED with caveat.** Pattern + formal contract trusted → +P2 *design* may proceed. P2 *build* is gated on the Axiom.jl `main.zig` +de-corruption landing (separate repo; owner decision pending). + == Status of related artefacts * PR #37 (`fix/tech-debt-remediation`): merge as legacy-stabilisation or shelve.