clawdie/layered-soul
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
layered-soul/docs/TOOLCHAIN.md
Sam & Claude 0bb2f8f260 docs: flip to python3=3.11 default (3.12 available); trim the pillow noise 
Per operator decision: stop fighting FreeBSD's PYTHON_DEFAULT=3.11 — python3 is
3.11 everywhere, python3.12 stays available for apps needing newer. This makes
Pillow trivial (py311-pillow imports on python3), so the prior "3.12 floor +
py312-pillow absent + run on 3.11 explicitly" explanation collapses.

- TOOLCHAIN.md: table row + decision section flipped to 3.11-default and cut to a
  few lines (supersedes the 17.jun.2026 "3.12 floor" decision); symlink note now
  says build.sh points python3 at 3.11.
- CAPABILITY-ROUTING.md: trimmed the osa line + worked example — image-render via
  py311-pillow on python3, no version gymnastics.
- HOST-MATRIX.md: trimmed the operator-image image-render/screenshot note.

prettier + layered_soul validate clean. Dates in edited blocks use EU format.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-21 10:12:29 +02:00

4.5 KiB
Raw Blame History

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 for the agent matrix and HOST-MATRIX.md for per-host hardware facts.