main at 53aeb9d. Revised the same day, twice: the provisioning engine
changed from an isolated mise to rattler and conda-forge, then a deeper research pass hardened the
trust model, the data directory, the updater’s concurrency and the per-language sources (see
“Alternatives considered”).
[!important] Status: designed, Phase 0 done, Phases 1–5 not built codecalc is a product for other people, on macOS, Windows, Linux and other systems. Its language runtimes must stay current on their own and must never break a user’s machine while doing it. This document is the plan. Each phase below is one pull request.
Why the current runtime code cannot do this
codecalc/runtimes.py reports and updates runtimes through the package managers it finds on the
host. Its manager map was written on and for one Linux ARM64 server:
Four further problems showed up on 2026-10-27, three fixed in #368:
swiftly updateuninstalled the in-use toolchain and left none selected, so every Swift run failed while the update reported success (fixed: re-select the global default).- A missing apt language (PHP, C#) was reported as “up to date” (fixed:
installed: false). - apt’s “latest” meant “latest in this distro’s sources” without saying so (fixed:
latest_scope). update_runtimes(apply=True)asks for confirmation through MCP elicitation, and that prompt was cancelled in Claude Code, so nothing can apply an update unattended. Open.
Goals and non-goals
Goals:- A user on macOS, Windows or Linux (x86_64 and arm64) gets working runtimes without installing a package manager first.
- Runtimes update without anyone running a command, and only to the exact bytes CI has proven.
- A bad update is detected and rolled back automatically. The previous version keeps working.
- The project keeps itself current: new upstream releases flow in through CI, and humans only see failures.
- Updating the user’s own toolchains. codecalc reports on them and suggests commands; it changes them only on explicit, per-manager opt-in.
- Supporting every language on every OS. Coverage is published honestly per OS.
- Using elevated privileges (
sudo, UAC) anywhere in the update path. - Compiling anything on the user’s machine. Every managed runtime is a prebuilt binary.
- musl hosts (Alpine). conda-forge builds target glibc; musl users get host runtimes only.
Design
1. Two kinds of runtime
Execution resolves a language in this order: a managed runtime if one is installed and healthy,
then a host runtime, then “not available” with a suggested install command. A user setting can
prefer host runtimes instead (for people who want codecalc to run exactly what they run).
Managed runtimes are always run by absolute path through
current.json, never through PATH.
The data directory must be short and contain no spaces. Conda packages carry their install path
inside text and binary files, and rattler rewrites shebangs to #!/usr/bin/env when the prefix
contains a space or a shebang grows past 127 bytes (Linux) or 512 bytes (macOS). So:
- macOS and Linux:
$XDG_DATA_HOME/codecalc(default~/.local/share/codecalc). macOS does not use~/Library/Application Support, which contains a space. - Windows:
%LOCALAPPDATA%\codecalc, with short subdirectory names. A username containing a space is a tested case (Phase 2). CODECALC_DATA_DIRoverrides the location everywhere.- codecalc refuses to install managed runtimes on a
noexecmount and says why.
<sha8> suffix (from the manifest entry’s hash) keeps a rebuild of the same version from
colliding with the installed one. Prefixes are written once, at their final path, and never
modified after the pointer moves to them. Where hardlinks from pkgs/ cannot work (a
cross-device data directory), rattler falls back to copying.
2. Provisioning: three tiers in one manifest
Every managed language comes from exactly one tier per target. The tier is recorded in the manifest, so the client never guesses. Tier 1: conda packages through rattler. codecalc embedspy-rattler, the Rust installer behind pixi, as an ordinary
pip dependency. It ships abi3 wheels for Linux (glibc and musl hosts), macOS and Windows on x86_64
and arm64. conda-forge is the only project building portable, relocatable binaries for most of
these languages; Modular’s max channel serves Mojo the same way.
- CI owns solving. A
pixi.tomlin the repo declares one environment per language; CI solves it intopixi.lock, which pins every package and every dependency by URL and sha256 per platform. - The client never solves. It hands rattler’s
install()the explicit package list for its platform from the manifest. This also avoids downloading repodata (the full win-64repodata.jsonis 418 MB) and the documented conda-forge repodata stalls. - Channels are pinned explicitly in the lock (rattler now follows CEP-42 channel relations by
default). codecalc never resolves or falls back to Anaconda’s
defaultschannel, which is paid; conda-forge itself is free to use commercially, under Anaconda’s Terms of Service. - Every package URL has mirrors, tried in order under the same sha256:
conda.anaconda.org, thenrepo.prefix.dev. - Link scripts and menuinst stay off. rattler’s own docstring warns that link scripts run unsandboxed code.
- No external tool is fetched, nothing is put on the user’s
PATH, and nothing outside<data>/is written. The Phase 2 spike proves the last claim on each OS.
Source per language and target
Key: CF conda-forge (Tier 1), MAX Modular’s channel (Tier 1), V vendor archive (Tier 2), H host only (Tier 3), — unsupported. “(verify)” cells are confirmed or changed by the Phase 2 spike.
Notes on the choices:
- C, C++, Fortran on Windows are Tier 1. conda-forge’s
clang_win-64needs Visual Studio, but its mingw-w64gcc/gxx/gfortran(win-64) andzig cc(win-arm64) need no admin rights. The trade-off is the GCC or Zig ABI, not MSVC’s. - Vendor builds where conda-forge lags: openjdk has had no upload since 2026-02-18 (Temurin
instead); conda-forge typescript is on 6.x against upstream 7 (run TypeScript through Deno);
deno trails by weeks and has no win-arm64 build, while Deno publishes a
.sha256sumper asset. Gleam publishes sha256 and Sigstore per asset for all six targets. - Haskell: conda-forge’s ghc is 8.10.7 from 2021. ghcup bindists (
SHA256SUMSplus.sig) replace it; Windows is unverified. - Python stays on conda-forge, which tracks upstream within days. python-build-standalone is the drop-in if that ever changes.
- win-arm64 is thin: about 15 of 31 languages even with vendor fills.
3. The runtime manifest is the source of truth
Every codecalc release publishesruntimes.lock.json, generated from pixi.lock plus the Tier 2
entries:
linux-64, linux-aarch64, osx-64, osx-arm64,
win-64, win-arm64). Conda package paths are relative so each mirror can serve them.
Rules:
- A version enters the manifest only after the conformance suite passes on that target in CI. Clients update to the manifest, never to “whatever upstream released last night”.
- Every downloaded file, in either tier, is checked against its sha256 before use. conda-forge does not publish package attestations, so these hashes are the whole integrity guarantee and the manifest’s own security is load-bearing.
- The manifest is signed with Sigstore keyless signing from the release workflow (GitHub OIDC
identity). Clients verify it with the
sigstorePython library, offline, against a cached trust root refreshed on the 24-hour update cadence (by default the library checks for trust-root updates on every start, which a frequently started, sometimes offline server cannot rely on). Verification checks the workflow identity, repository and ref. - A signature proves who signed a manifest, not that it is the newest. To stop an attacker or a
stale CDN replaying an older signed manifest:
serialonly goes up. The client stores the highest serial it has accepted and rejects lower.expiresbounds a manifest’s life. An expired manifest freezes updates and warns; it never uninstalls anything.- The accepted signing identities are pinned in codecalc, and changing them needs a rotation record signed by the current identity.
- An unverifiable manifest is ignored, and the client keeps its current runtimes.
- The existing reliability tiers (
tested,best_effort,plan_only; today 4, 25 and 1 languages) carry over per target, so the published support table is the manifest.
4. The updater on the user’s machine
No system timer is needed for the common case:- On server start, if more than 24 hours have passed since the last check, fetch the latest manifest in the background. Tool calls are never blocked on this.
- Take
update.lock(an OS file lock). Several MCP clients each starting codecalc is the normal case, and rustup’s maintainers document how unlocked concurrent updates corrupt installs. The lock is held from download through pointer swap and cleanup. A second process that cannot get it skips this round. - Verify the manifest (section 3). For each language in use whose manifest entry differs from
current.json, install the new version directly into its final<version>-<sha8>prefix. There is no staging directory: the path is baked into the files, and Windows cannot move a directory across drives. A language is installed the first time it is run. - Run the language’s smoke test (the existing
doctor --deepprobe for that language). - Pass: copy
current.jsontocurrent.json.prev, then swapcurrent.jsonatomically (write a temp file, fsync,os.replace). Fail: delete the new prefix, keep the old version active, record the failure instate.json, and surface it incodecalc doctor.current.jsonis validated on load; if it is damaged,current.json.previs used. - Keep one previous version per language. Delete older prefixes, then cache entries no prefix
uses. On Windows a running executable cannot be deleted: anything that fails to delete moves to
trash/and is retried at the next start. - If the OS refuses to run a managed binary (Windows Smart App Control or App Control policy, macOS policy), record it as a policy denial, fall back to the host runtime, and report it plainly. Never retry it in a loop.
CODECALC_AUTO_UPDATE=0turns the background updater off.CODECALC_RUNTIMES=hostprefers host runtimes everywhere.CODECALC_DATA_DIRmoves the data directory.- A version pin per language in user config stops that language from moving.
5. A CLI that needs no MCP client
Phase 1 adds:update --apply needs no MCP elicitation, which
resolves problem 4. schedule --install writes a launchd agent (macOS), a Task Scheduler entry
(Windows) or a systemd user timer (Linux) for people whose server never restarts. All three run
codecalc runtimes update --apply --json and never need elevation.
6. codecalc updates itself through its install channel
7. The project maintains itself
- A scheduled workflow runs
pixi updateand checks Tier 2 upstreams for new releases, then opens a PR bumpingpixi.lockand the Tier 2 entries. - The conformance suite runs on the ubuntu, macOS and Windows runners (the matrix already exists), installing each runtime exactly as a client would.
- Green: the PR auto-merges, and the release workflow cuts a release that publishes the signed
manifest with the next
serial. - Red: the workflow files an issue, and that language stays on its previous version.
Alternatives considered
The first draft also said mise leaks Rust into
~/.rustup and ~/.cargo. That was unfair:
rustup supports RUSTUP_HOME and CARGO_HOME. The other objections stand.
Checked on 2026-10-27 against anaconda.org, PyPI and GitHub: py-rattler 0.28.0 publishes
win_amd64, win_arm64 and musllinux wheels; conda-forge Python covers all six targets; conda-forge
Erlang, Elixir, jq, gawk, bash and zsh have no native win-64 build; ghc is 8.10.7; Swift is absent.
Full sources: the research report “Runtime provisioning for codecalc” (kept outside the repo).
Phases
Phase 2 spike (about one day)
- A
pixi.tomlwith one environment per language, solved for linux-aarch64, osx-arm64, win-64 and win-arm64, plus the Tier 2 entries for those targets. - A throwaway installer that installs each environment with
py-rattlerfrom the lock (and each vendor archive with the downloader), then runs the language’s hello-world. - A GitHub Actions run on ubuntu-24.04-arm, macos-latest, windows-latest and windows-11-arm that records pass/fail, install time and disk use per language, records the Authenticode status of every Windows executable, and diffs the filesystem to confirm nothing was written outside the data directory.
- Extra cells: a Windows user profile whose name contains a space; a deep-path install (.NET, the JDK, R) on Windows; a Windows 11 image with Smart App Control enforced; two updaters started at once against the same data directory.
Risks and open questions
- Windows code-integrity policy (highest risk). Smart App Control checks every executable and
library the OS loads, whatever its origin. It allows unsigned code only if Microsoft’s reputation
service knows it, and it has blocked unsigned developer tools after updates. App Control for
Business and AppLocker can block execution from
%LOCALAPPDATA%outright. Nobody has checked whether conda-forge’s Windows builds are Authenticode-signed; if they are not and SAC blocks them, Windows cells move to signed vendor builds. Phase 2 measures this. - py-rattler churn. It is pre-1.0, with 42 releases since 2023 and breaking changes in almost
every minor release, some silent (build strings became
BuildStringobjects, sorecord.build == "py312_0"is now always False). A 0.27.5 patch broke Windows extraction of deep .NET paths. Mitigation: pin it exactly, call it only through one adapter, give the adapter contract tests for silent semantic changes, make a Windows deep-tree install (.NET, JDK, R) a required check for any bump, and keep micromamba as the fallback engine behind the adapter. - Windows coverage is uneven, and win-arm64 is thin (about 15 of 31). Phase 2 publishes the measured table before anything is promised.
- conda-forge lag. Most packages track upstream within days; some do not (openjdk, typescript, bash, tcl). The bump workflow surfaces lag, and a language that falls too far behind moves to Tier 2.
- conda-forge availability. Repodata downloads have stalled since late 2025. The client never downloads repodata and has a second mirror.
- Package trust. conda-forge publishes no package attestations, so trust rests on the signed
manifest and sha256 checks. Turn on rattler’s
attestation_policyfor channels that publish attestations, and for conda-forge if it starts. - Disk use. Each runtime bundles its own libraries, so the full set can reach several gigabytes. Mitigated by installing on first use, hardlinking from the shared cache and keeping one rollback version.
- Network-restricted environments. The updater must fail quietly and keep working offline;
CODECALC_AUTO_UPDATE=0and the offline bundles must be documented for air-gapped installs. - Sigstore on clients. Verifying in Python adds a dependency. If it is too heavy, the fallback is checksum files signed by the release key, verified with a vendored public key; serial and expiry still apply.
- Who confirms MCP-initiated applies? Problem 4 (elicitation cancelled in some clients) still
affects the MCP
update_runtimestool. The CLI path does not depend on it; the MCP tool may become report-only once the background updater exists.