Feat/panel clades pivot

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) <j.d.a.jewell@open.ac.uk>
+= 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 `<project>_*` (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.

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

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+= 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** 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
+
+* 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.
+
+== 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.
+* `feat/panel-clades-pivot`: carries this ADR + legacy freeze marker only.
+* `docs/TECHNICAL_DEBT.md`: F1 section superseded by this ADR.

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`.

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.