layered-soul/docs/TOOLCHAIN.md

# Toolchain Baseline (cross-platform)

**Goal: the same frameworks and language runtimes across all hosts and OSes**, so an
agent relocated between Linux and FreeBSD finds an identical toolchain. Version drift
is a survivability bug — if debby and OSA disagree on Python or Node, a script that
works on one can silently fail on the other.

Probe before trusting this table — facts come from `scripts/verify_facts_probe.py
--build-tools`, not memory. Update the row when you bump a host.

## Baseline versions

| Tool       | Standard            | Linux (Debian/Ubuntu)    | FreeBSD 15 (pkg)                                                     | Manager / source                 |
| ---------- | ------------------- | ------------------------ | -------------------------------------------------------------------- | -------------------------------- |
| **Python** | **3.11** (default)  | `python3.13` (debby)     | `python3` → 3.11; `python3.12` also installed for apps needing newer | system pkg + **uv** for venvs    |
| **uv**     | ≥ 0.11              | `uv` 0.11.21             | `uv` (pkg) — confirm                                                 | standalone binary                |
| **Node**   | **24 LTS** (target) | `fnm` → v24.16.0 (debby) | `node24` + `npm-node24`                                              | **fnm** (Rust, cross-platform)   |
| **Rust**   | stable (pinned)     | rustup 1.95.0            | `rust` (pkg)                                                         | `rust-toolchain.toml` per repo   |
| **Go**     | latest stable       | `go` 1.24.4 (debby)      | `go` (pkg)                                                           | only where a Go component exists |
| **Zig**    | 0.15.2              | `~/.local/bin/zig`       | manual                                                               | pinned (herdr build dep)         |
| **tmux**   | latest stable       | `tmux`                   | `tmux`                                                               | system pkg                       |

## Conventions

### Python — never pin the version in a shebang

- Scripts use `#!/usr/bin/env python3`. **No version-pinned shebangs.** The interpreter is a
  symlink set once at image/host setup, so a version change is one edit, not a sweep.
- FreeBSD ships no bare `python3`; `clawdie-iso build.sh` points it at **3.11** (prefers
  `python3.11`, else the lowest installed).
- venv creation calls `python3 -m venv` (resolves via the symlink) — never a pinned version.
- **uv is the standard venv/dependency manager** across all OSes (`uv venv` / `uv pip` /
  `uv sync`); it picks up whatever `python3` resolves to.

### Node — LTS only, one major across the matrix

- Standard target: **Node 24 LTS** (FreeBSD already ships `node24`; npm 11).
- **Resolved 2026-06-17:** debby switched to Node 24 via `fnm` (system Node 20 remains
  for OS-level tools, but all Clawdie/agent workloads use 24). FreeBSD already on 24.
  One step remains: bump the Hermes Dockerfile `node_source:22` → `24` to match.
- `package.json` engines floor stays generous (`>=20`) but installed runtime tracks the
  agreed LTS. Never run a non-LTS Node major in production.

### Rust / Go / Zig

- Rust: pin per-repo with `rust-toolchain.toml` (channel `stable`) so FreeBSD pkg `rust`
  and Linux rustup resolve the same toolchain. TLS via rustls (no openssl-sys) for the
  `x86_64-unknown-freebsd` Tier-2 target.
- Go: only where a Go component exists; track latest stable.
- Zig pinned at 0.15.2 (herdr); bump deliberately.

### Managed tools (tmux, codex, pi, zot, …)

- These are agent/utility tools, not language runtimes. Track latest stable from the
  platform package manager; record notable pins here when they matter.
- Pi is being retired (see consolidation on zot + Colibri). Codex stays (osa, ISO builds).

## Python — 3.11 default, 3.12 available (decision)

`python3` is **3.11** on every host — FreeBSD's `PYTHON_DEFAULT`, so we don't fight it. 3.11
has everything we use (`zoneinfo`, `match`/`case`, `tomllib`). **3.12 stays installed as
`python3.12`** for anything that genuinely needs newer (call it explicitly or use a uv venv).

FreeBSD package flavors are the default `py311-*` (e.g. `py311-pillow` → `image-render`);
`py312-*` aren't in the quarterly repo, so keep them out of `pkg-list-*.txt`.

Supersedes the 17.jun.2026 "3.12 floor" decision — 3.11 is what the base ships and nothing we
run requires 3.12.

_See [`AGENTS.md`](../AGENTS.md) for the agent matrix and [`HOST-MATRIX.md`](./HOST-MATRIX.md)
for per-host hardware facts._