docs: silicon-core reconnaissance report (backend/FFI/GPU audit, deliverables A–J)

[arena-ai-coding-agent]

Summary

Read-only engineering reconnaissance of Axiom.jl's backend / native FFI / GPU / coprocessor responsibilities, answering: does the package combine too many responsibilities, are the accelerated paths what the docs say, and should a standalone runtime package (SiliconCore.jl / CoprocessorRuntime.jl) be extracted?

This PR adds documentation and reproduction scripts only. No file under src/, ext/, zig/, ffi/ or test/ is modified; no dependency, structure or CI change. Everything is under docs/investigation/2026-09-26-silicon-core-recon/.

Deliverable	File
Index, method, environment, executive summary	README.adoc
A. Component map (production-tested / experimental / stub / disconnected / doc-only)	A-component-map.adoc
B. Backend status table	B-backend-status.adoc
C. ABI/FFI discrepancy report	C-abi-ffi-discrepancies.adoc
D. Numerical parity risk report	D-numerical-parity-risks.adoc
E. Memory/performance report	E-memory-performance.adoc
F. Extraction recommendation (options A–D)	F-extraction-recommendation.adoc
G. Proposed package/API boundary (design only)	G-api-boundary.adoc
H. Staged plan + verification plan	H-staged-plan.adoc
I. Changes explicitly NOT recommended	I-not-recommended.adoc
J. 40 upstream issues with evidence, severity, bucket	J-upstream-issues.adoc
Minimal reproductions (Zig tests + ctypes probes)	repro/

Key findings

Empirically confirmed against the CI-built libaxiom_zig.so (Zig 0.15.2, -Doptimize=ReleaseFast); scripts in repro/:

• J-01 (Critical) axiom_batchnorm uses a fixed [4096]f32 stack scratch (zig/src/norm.zig:143): silently wrong for 4097–8191 features, SIGSEGV from 8192. Reachable from forward(bn::BatchNorm) whenever a Zig backend is active.
• J-02 (High) backend_maxpool2d / backend_global_avgpool2d Zig wrappers pass column-major memory to row-major NHWC kernels → wrong values for any N>1 or C>1.
• J-03 (High) axiom_tanh returns NaN for x ≥ 44.5 and +Inf (gelu in the same file already uses the overflow-safe form).
• J-05 (High) Julia always calls axiom_matmul_checked, which is 9–16× slower than the axiom_matmul kernel the published benchmarks measured (512²: 284.6 ms vs 21.7 ms).
• J-04 (Medium, UB) chunking underflow at batch_size = 5 in parallel_layernorm/rmsnorm/batch: panics in Debug/ReleaseSafe, crashes a ReleaseFast test binary, accidentally benign in the shipped .so.
• 44 real exports vs. "32 / 36" in TOPOLOGY.adoc, ABI-FFI-README.adoc, zig/src/axiom.zig; ffi/zig does not compile (export fn Axiom.jl_init()) despite being documented as "internally self-consistent".

Static findings (Julia was not available in the investigation sandbox; each carries a maintainer-runnable check and is labelled [static]): the documented production path compile(model, backend=ZigBackend(path)) runs pure Julia unless set_backend! is also called and the CI "accelerated" smoke test cannot detect it; every Zig wrapper silently falls back when the library is unavailable (no strict mode); AXIOM_CUDA_AVAILABLE=1 asserts GPU availability without a device; precision=:float16 / :mixed paths do not do what they claim; the proof/certificate layer records no backend, kernel or ABI provenance.

Recommendation

Option D — defer extraction; stabilise internal interfaces first, with an explicit exit criterion to Option B. Decisive evidence: the extraction has already been attempted once (AcceleratorGate.jl, "extracted from Axiom.jl's backend module") and is vendored back into Axiom as dead code behind an always-false applicable guard with a disjoint type hierarchy. G specifies the minimal runtime API (requested/selected/executed backend, fallback_used, precision, device identity, kernel/ABI version, strict mode); H sequences Phase 0 (fixes + parity tests) → Phase 1 (in-tree Axiom.Runtime seam) → Phase 2 (evidence gate) → Phase 3 (conditional extraction superseding AcceleratorGate rather than creating a third package).

How to reproduce

cd zig && zig build -Doptimize=ReleaseFast          # Zig 0.15.2, as CI
cd ../docs/investigation/2026-09-26-silicon-core-recon/repro
python3 batchnorm_probe.py ../../../../zig/zig-out/lib/libaxiom_zig.so    # needs numpy
python3 layout_probe.py    ../../../../zig/zig-out/lib/libaxiom_zig.so
python3 activation_probe.py ../../../../zig/zig-out/lib/libaxiom_zig.so
python3 matmul_cost.py     ../../../../zig/zig-out/lib/libaxiom_zig.so
zig test -OReleaseSafe --dep axiom -Mroot=repro_batchnorm.zig -Maxiom=../../../../zig/src/axiom.zig

Notes for reviewers

• Line references are against 79e6f48.
• Suggested follow-ups are listed in J-upstream-issues.adoc §J.3 (open J-01/J-02/J-03 as individual issues with the repro scripts attached; then the "requested vs executed backend" epic pointing at G/H).
• Two corrections made during the investigation are recorded rather than hidden: an initial static prediction that GELU shared the tanh overflow was wrong (the probe corrected it), and the batch=5 underflow is documented as UB rather than a confirmed production crash because the shipped .so happens to be benign.

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 57634f29-8554-4838-b1b1-27e7c36430cf

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}