|
| 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** follow `oo7`/`jtv` patterns anywhere in the standard route. |
| 66 | + |
| 67 | +== Consequences |
| 68 | + |
| 69 | +* The F1 plan in `docs/TECHNICAL_DEBT.md` ("wire the 38 Rust panels") is |
| 70 | + **void** — replaced by: regenerate panels as clades, modelled on the |
| 71 | + re-audited Axiom.jl standard route. |
| 72 | +* Critical path is gated on **characterising + re-validating Axiom.jl's |
| 73 | + backend-organisation approach** (the pattern, not the code). Axiom.jl is |
| 74 | + not present in `~/dev/repos`; obtaining it (or an authoritative write-up |
| 75 | + of its approach) is the unblock. `jtv` is unlocated and off the standard |
| 76 | + route anyway. |
| 77 | +* Phasing: P0 record+freeze (this ADR) → **GATE: characterise + re-validate |
| 78 | + Axiom.jl's approach** → P1 minimal non-speculative dev-env/`/dev/tools` |
| 79 | + provisioning → P2 coprocessor clade exemplar (Axiom.jl-pattern, 11 |
| 80 | + backends) → P3 bulk panel→clade. |
| 81 | + |
| 82 | +== Status of related artefacts |
| 83 | + |
| 84 | +* PR #37 (`fix/tech-debt-remediation`): merge as legacy-stabilisation or shelve. |
| 85 | +* `feat/panel-clades-pivot`: carries this ADR + legacy freeze marker only. |
| 86 | +* `docs/TECHNICAL_DEBT.md`: F1 section superseded by this ADR. |
0 commit comments