sorcery-go/docs/TOOLCHAIN_SPEC.md

Toolchain Specification

1. Sovereign Toolchains

The Coven does not download pre-built GCC/LLVM binaries. Each admin maintains their own toolchains, or forges them with BTC.sh. Toolchains are stored under /opt/sorcery-go/toolchains/<triple>/ (manual) or /opt/BTC/<SYS_LABEL>/ (BTC.sh golden images). The Sandbox AttachToolchain bind-mounts the requested toolchain read-only into the build namespace.

2. BTC.sh Integration

Sorcery-Go integrates with BTC.sh for cross-compilation across 19 target architectures. The pkg/toolchain/btc.go module probes for golden images, parses their manifest JSON sidecars, and configures the build environment.

Supported Targets

Family	Targets
Intel HEDT/Server	haswell, haswell-ep, skylake, skylake-x, skylake-server
AMD Ryzen/EPYC	znver1, znver2, znver3, znver4
AMD APU	apu-zn1, apu-zn2, apu-zn3, apu-zn4
Intel Atom	atom-silvermont, atom-goldmont, atom-tremont, atom-sierraforest
Embedded	mipselr2, armv7, tilegx

ISA Tiers

ISA Tier	Flags
AVX512	-mavx512f -mavx512dq -mavx512vl -mavx512bw
AVX2	-mavx2
SSE4_2	-msse4.2
NEON	-mfpu=neon -mfloat-abi=hard
MIPS32	(per-target architecture)
TILE	(per-target architecture)

3. Required Specs (Manual Toolchains)

# Toolchain: aarch64-linux-musl

## Specifications
- **Version:** GCC 15.1.0 / Binutils 2.44
- **C Library:** musl 1.2.5
- **Optimizations:** `-O3 -flto -march=armv8-a`
- **Hardening:** `-fstack-protector-all -pie -fPIE -D_FORTIFY_SOURCE=2`

## Essence Compatibility
- **Min Engine Version:** 1.0.2
- **Supported Targets:** Generic-ARM64, Pine64, RPi5

## Validation
- **Validator Pass:** true
- **Smoke Test:** Hello-World compiled, ldd reports "not a dynamic executable"
- **Has SSP:** true
- **Has PIE:** true

4. Validation Pipeline

Every toolchain must pass pkg/toolchain.Validate before it can forge production Essences:

Check	Method
Arch detection	Parse gcc -v output for triple
Stack Smashing Protection	Inspect for --enable-default-ssp
PIE	Inspect for --enable-default-pie
LTO	Inspect for --with-default-libstdcxx-abi=lto
Smoke test	Compile int main(){} with -fstack-protector-all -pie

If Validate() returns Report.Passed = false, the Cauldron refuses to attach the toolchain and the WebUI flags it in the Toolchain Lab view.

5. Per-Spell Overrides

Some spells (kernel, glibc) need a different toolchain than the default. The WebUI lets the admin attach an override per spell:

spell: linux
toolchain_override: /opt/sorcery-go/toolchains/x86_64-linux-gnu-gcc-14

6. Fleet Re-Forge

When a toolchain is updated, the WebUI's Fleet Re-Forge button flags every Essence built with the old version and re-queues them for the Cauldron. This ensures the entire Coven runs code compiled with the latest toolchain.