# 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)

```markdown
# 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:

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