0bb2f8f260
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>
71 lines
4.5 KiB
Markdown
71 lines
4.5 KiB
Markdown
# 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._
|