feat(toolchain): make opsm.toml [runtime] the single source of truth (#67)

## Problem

OPSM had **no single source of truth for its own toolchain versions —
five sources disagreed**:

| Source | Erlang | Elixir | Notes |
|---|---|---|---|
| `.tool-versions` (what actually builds it) | 28.3.1 | 1.19.5-otp-28 |
+ vestigial nodejs 25.6.1 |
| `opsm.toml [runtime]` (read by `opsm runtime install`) | 26.2.0 |
1.16.0 | stale |
| `.gitlab-ci.yml` | `elixir:latest` | `rust:latest` | non-reproducible
|
| `e2e.yml` + `nif-build.yml` | 27.0 | 1.17 | hardcoded |
| `trust-pipeline-e2e.yml` | 26.2 | 1.16.0 | hardcoded |

Plus: **Nickel** heavily used (`runtime/**/*.ncl`) but pinned nowhere,
**Idris2** (a real build dep — `src/abi/*.idr`) unpinned, **Rust**
floating on `stable`.

## Fix

`opsm.toml [runtime]` is now canonical (dogfooding — `opsm runtime
install` already consumes it). Everything else derives from it or is
drift-checked against it:

```
opsm.toml [runtime]  ── just toolchain-sync ──►  .tool-versions ──► asdf/mise + setup-beam (version-file)
        └─ just toolchain-check (Mustfile-gated) ──► verifies .tool-versions + GitLab image pins
```

- **opsm.toml**: corrected stale pins (erlang → 28.3.1, elixir →
1.19.5-otp-28); completed the set (rust 1.97.0, nickel 1.16.0, idris2
0.8.0); dropped the vestigial nodejs pin (no package.json, nothing
invokes node — Deno is the sole JS runtime)
- **scripts/toolchain.sh** (new, POSIX sh): `sync` regenerates
`.tool-versions`; `check` fails loudly on any drift, incl. GitLab image
tags. Wired as `just toolchain-sync` / `just toolchain-check` + Mustfile
check
- **`.tool-versions`**: now generated, with idris2 (no asdf plugin —
pack/Chez route) and rust (asdf-global, cargo-audit conflict) excluded
via documented skip-list. zig/deno/nickel provision via the estate's
[`asdf-tool-plugins`](https://github.com/hyperpolymath/asdf-tool-plugins)
- **GitLab CI**: `elixir:1.19.5-otp-28` + `rust:1.97` (tags verified on
Docker Hub); also fixed the invalid `//` comment on line 2 that broke
YAML parsing. Scanner images (trivy/semgrep/trufflehog) deliberately
float — fresh detection DBs beat cosmetic pinning
- **GitHub workflows**: `setup-beam` now reads `.tool-versions`
(`version-file` + `version-type: strict`) in e2e, nif-build, and
trust-pipeline-e2e; rust steps pin `toolchain: 1.97.0` (nif-build,
echidna-validation)
- **`parse_runtime_section/1`** (`manager.ex`): hardened — comment lines
containing `=` were mis-parsed as pins and inline comments corrupted
versions; tests added
- **docs/TOOLCHAIN.adoc** (new): derivation chain, per-tool provisioner
table, the honest bootstrap story (OPSM is an Elixir escript — it cannot
provision the BEAM for itself; asdf/mise/Guix sit underneath), and the
Idris2 route (pack + Chez + GMP today; `guix.scm` is still a stub,
documented as TODO rather than overclaimed)

## Verified

- `sh scripts/toolchain.sh sync && sh scripts/toolchain.sh check` →
green
- Drift injections (`.tool-versions` version mutated; GitLab image
reverted to `:latest`) → both exit 1
- All 5 edited YAML files parse cleanly
- Elixir parser tests **not run locally** (no BEAM in this container) —
CI runs them; watching this PR for fallout, especially
`trust-pipeline-e2e` moving 26.2 → 28.3.1 (accepted risk per owner
decision)

## Known follow-ups (out of scope here)

- `guix.scm` is a stub (`source #f`) — growing it into a real manifest
is recorded in STATE.a2ml next-actions
- Handoff sections B/C (service deps wiring, solver stack) — separate
work

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01Kq24sZCEohSrNFXSuEuz6C

---
_Generated by [Claude
Code](https://claude.ai/code/session_01Kq24sZCEohSrNFXSuEuz6C)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

.github/workflows/e2e.yml

@@ -38,8 +38,10 @@ jobs:
       - name: Setup Erlang/Elixir
         uses: erlef/setup-beam@54075bcc5e249e4758d363f27d099f55d843f124 # v1.24.1
         with:
-          otp-version: '27.0'
-          elixir-version: '1.17'
+          # Versions derive from opsm.toml [runtime] via .tool-versions
+          # (generated by `just toolchain-sync` — see docs/TOOLCHAIN.adoc)
+          version-file: '.tool-versions'
+          version-type: 'strict'
       - name: Restore Mix cache
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v4
         with:
@@ -65,8 +67,10 @@ jobs:
       - name: Setup Erlang/Elixir
         uses: erlef/setup-beam@54075bcc5e249e4758d363f27d099f55d843f124 # v1.24.1
         with:
-          otp-version: '27.0'
-          elixir-version: '1.17'
+          # Versions derive from opsm.toml [runtime] via .tool-versions
+          # (generated by `just toolchain-sync` — see docs/TOOLCHAIN.adoc)
+          version-file: '.tool-versions'
+          version-type: 'strict'
       - name: Restore Mix cache
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v4
         with:

.github/workflows/echidna-validation.yml

@@ -49,6 +49,8 @@ jobs:
         if: steps.detect.outputs.relevant == 'true'
         uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable
         with:
+          # Pinned to the canonical rust version in opsm.toml [runtime]
+          toolchain: '1.97.0'
           components: clippy
       - name: Cache Rust dependencies
         if: steps.detect.outputs.relevant == 'true'

.github/workflows/nif-build.yml

@@ -26,15 +26,20 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable
+        with:
+          # Pinned to the canonical rust version in opsm.toml [runtime]
+          toolchain: '1.97.0'
       - name: Cache Rust build
         uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2
         with:
           workspaces: opsm_ex/native/opsm_pq_nif -> target
       - name: Setup Erlang/Elixir
         uses: erlef/setup-beam@54075bcc5e249e4758d363f27d099f55d843f124 # v1.24.1
         with:
-          otp-version: "27.0"
-          elixir-version: "1.17"
+          # Versions derive from opsm.toml [runtime] via .tool-versions
+          # (generated by `just toolchain-sync` — see docs/TOOLCHAIN.adoc)
+          version-file: '.tool-versions'
+          version-type: 'strict'
       - name: Restore Mix cache
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v4
         with:

.github/workflows/trust-pipeline-e2e.yml

@@ -42,8 +42,10 @@ jobs:
       - name: Install Elixir and OTP
         uses: erlef/setup-beam@54075bcc5e249e4758d363f27d099f55d843f124 # v1.24.1
         with:
-          otp-version: '26.2'
-          elixir-version: '1.16.0'
+          # Versions derive from opsm.toml [runtime] via .tool-versions
+          # (generated by `just toolchain-sync` — see docs/TOOLCHAIN.adoc)
+          version-file: '.tool-versions'
+          version-type: 'strict'
       - name: Cache Mix dependencies
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v4
         with:

.gitlab-ci.yml

@@ -1,6 +1,11 @@
 # SPDX-License-Identifier: MPL-2.0
-// Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+# Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
 # Primary CI/CD - GitLab is the source of truth
+#
+# Toolchain images (elixir/rust) are pinned to the canonical versions in
+# opsm.toml [runtime] — drift is gated by `just toolchain-check`.
+# Scanner images (trivy/semgrep/trufflehog) deliberately float: their
+# detection databases need to stay fresh, so pinning them is worse.
 
 stages:
   - security
@@ -32,7 +37,7 @@ semgrep:
   allow_failure: true
 cargo-audit:
   stage: security
-  image: rust:latest
+  image: rust:1.97
   script:
     - cargo install cargo-audit
     - cargo audit
@@ -41,7 +46,7 @@ cargo-audit:
         - Cargo.toml
 cargo-deny:
   stage: security
-  image: rust:latest
+  image: rust:1.97
   script:
     - cargo install cargo-deny
     - cargo deny check
@@ -51,7 +56,7 @@ cargo-deny:
   allow_failure: true
 mix-audit:
   stage: security
-  image: elixir:latest
+  image: elixir:1.19.5-otp-28
   script:
     - mix local.hex --force
     - mix archive.install hex mix_audit --force
@@ -66,7 +71,7 @@ mix-audit:
 # ==================
 rustfmt:
   stage: lint
-  image: rust:latest
+  image: rust:1.97
   script:
     - rustup component add rustfmt
     - cargo fmt -- --check
@@ -75,7 +80,7 @@ rustfmt:
         - Cargo.toml
 clippy:
   stage: lint
-  image: rust:latest
+  image: rust:1.97
   script:
     - rustup component add clippy
     - cargo clippy -- -D warnings
@@ -85,15 +90,15 @@ clippy:
   allow_failure: true
 mix-format:
   stage: lint
-  image: elixir:latest
+  image: elixir:1.19.5-otp-28
   script:
     - mix format --check-formatted
   rules:
     - exists:
         - mix.exs
 credo:
   stage: lint
-  image: elixir:latest
+  image: elixir:1.19.5-otp-28
   script:
     - mix local.hex --force
     - mix deps.get
@@ -107,15 +112,15 @@ credo:
 # ==================
 cargo-test:
   stage: test
-  image: rust:latest
+  image: rust:1.97
   script:
     - cargo test --all-features
   rules:
     - exists:
         - Cargo.toml
 mix-test:
   stage: test
-  image: elixir:latest
+  image: elixir:1.19.5-otp-28
   script:
     - mix local.hex --force
     - mix deps.get
@@ -128,7 +133,7 @@ mix-test:
 # ==================
 cargo-build:
   stage: build
-  image: rust:latest
+  image: rust:1.97
   script:
     - cargo build --release
   artifacts:
@@ -140,7 +145,7 @@ cargo-build:
         - Cargo.toml
 mix-build:
   stage: build
-  image: elixir:latest
+  image: elixir:1.19.5-otp-28
   script:
     - mix local.hex --force
     - mix deps.get

.machine_readable/6a2/STATE.a2ml

@@ -1,11 +1,11 @@
 # SPDX-License-Identifier: MPL-2.0
 # STATE.a2ml — Project state checkpoint
-# Updated 2026-04-25f: CRG-B achieved — 6 external targets documented
+# Updated 2026-07-09: toolchain single source of truth (opsm.toml [runtime])
 
 [metadata]
 project = "odds-and-sods-package-manager"
 version = "2.0.0"
-last-updated = "2026-04-25"
+last-updated = "2026-07-09"
 status = "first-class system active"
 
 [project-context]
@@ -169,5 +169,19 @@ evidence-file = "READINESS.md"
   - Health poll loop (180s deadline, 3s interval) before running tests
   - Full diagnostics (service logs) on failure; docker compose down always
 
+[completed-2026-07-09]
+- Toolchain single source of truth established: opsm.toml [runtime] canonical ✅
+  - Stale pins corrected (erlang 26.2.0→28.3.1, elixir 1.16.0→1.19.5-otp-28)
+  - Pin set completed: rust 1.97.0, nickel 1.16.0 (was unpinned), idris2 0.8.0
+  - Vestigial nodejs pin dropped — Deno is the sole JS runtime
+  - .tool-versions now GENERATED (scripts/toolchain.sh; just toolchain-sync)
+  - Drift gate: just toolchain-check, wired into Mustfile
+  - GitLab CI images pinned off :latest; GitHub workflows read .tool-versions
+    via setup-beam version-file (previously 3 disagreeing hardcoded sets)
+  - [runtime] parser hardened: comment lines + inline comments (manager.ex)
+  - Full story: docs/TOOLCHAIN.adoc (incl. bootstrap layering + Idris2/pack route)
+
 [next-actions]
 - Grade A: requires external user confirmation outside hyperpolymath
+- guix.scm is a stub (source #f) — grow into real manifest (erlang, elixir,
+  zig, just, nickel, idris2, chez-scheme, gmp) for reproducible bootstrap

.tool-versions

@@ -1,8 +1,17 @@
 # SPDX-License-Identifier: MPL-2.0
-# Pinned runtime versions for OPSM
-# Managed via asdf (https://asdf-vm.com)
-elixir 1.19.5-otp-28
+# GENERATED FILE — do not edit by hand.
+# Source of truth: opsm.toml [runtime]. Regenerate with: just toolchain-sync
+# Drift is CI-gated by: just toolchain-check
+#
+# Plugin sources: erlang/elixir via the standard asdf plugins;
+# zig, deno, nickel via https://github.com/hyperpolymath/asdf-tool-plugins
+#
+# Canonical pins deliberately NOT listed here (see docs/TOOLCHAIN.adoc):
+#   idris2 0.8.0 — no asdf plugin; provision via pack + Chez Scheme + GMP
+#   rust 1.97.0 — asdf-global-managed to avoid cargo-audit conflicts; CI pins it
 erlang 28.3.1
-# Note: Rust managed via asdf global (nightly). Not pinned here to avoid
-# conflicting with cargo-audit and other cargo subcommands.
-nodejs 25.6.1
+elixir 1.19.5-otp-28
+zig 0.14.0
+just 1.46.0
+deno 2.6.10
+nickel 1.16.0

Justfile

@@ -107,6 +107,18 @@ fmt-check:
 # Format all code
 fmt: fmt-ex fmt-deno
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# TOOLCHAIN (single source of truth: opsm.toml [runtime] — docs/TOOLCHAIN.adoc)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Regenerate .tool-versions from opsm.toml [runtime]
+toolchain-sync:
+    sh scripts/toolchain.sh sync
+
+# Verify .tool-versions and CI image pins match opsm.toml [runtime]
+toolchain-check:
+    sh scripts/toolchain.sh check
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # RUN
 # ═══════════════════════════════════════════════════════════════════════════════

Mustfile

@@ -11,4 +11,6 @@ checks:
     run: just test
   - name: format
     run: just fmt
+  - name: toolchain
+    run: just toolchain-check