ADR 0004: resolve mux-runtime from source, freeze crates.io - #32
Merged
Conversation
0002 and 0003 disagreed about what is authoritative for the runtime. 0002 had the compiler pin a semver range on a published mux-runtime, so a coupled change shipped publish-first; 0003 then had CI build from sibling source so a coupled change went green without a publish. The seam between them is what produced the [patch.crates-io] block in mux-compiler, and with it a release-checklist item and a publish handshake for every coupled change. 0004 settles it in 0003's direction and extends it to release time: the runtime is a git dependency pinned to one commit by Cargo.lock, and the crates.io channel is frozen rather than yanked. Two findings drove it - the compiler has zero mux_runtime:: references, so the dependency was only ever a source-delivery mechanism; and cargo install was the highest-friction install path, needing a Rust toolchain plus exact LLVM 22 dev libraries, while the documented path is the prebuilt installer. Mark the superseded ordering in 0002, rewrite the release process (the mux-runtime section no longer describes a publish), and correct the ARCHITECTURE dependency graph and repo table, which both still described a crates.io pin.
It solved a problem already covered three ways. mux-runtime's CI builds mux-compiler main against the runtime source, and mux-compiler's build.yml tests against runtime main on every PR, so an FFI break surfaces from both directions without the pin moving (ADR 0003). A coupled change moves the pin itself via `cargo update -p mux-runtime`, and a release settles it deliberately. A lock that trails runtime main between those moments costs nothing - that is what a lock is for. What remained was a daily CI run, PR noise, and a token question, for freshness nothing was waiting on. Record the rejection in ADR 0004 so it is not re-proposed.
Feature-trimmed runtimes were measured to buy nothing - static linking already discards unreferenced archive members, so hello world is 16K either way - while costing a build cache, source lookups, and a five-level resolution order that hid a broken release from every developer machine. Restate the version stamp's purpose too: with the source-build cache gone it identifies which runtime a binary was built against, rather than keying a cache.
It still listed the three source lookups the compiler used to try - a sibling checkout, MUX_RUNTIME_SRC, and cargo's git checkout for the locked commit - all removed with the source-build path in ADR 0004. The compiler links a prebuilt archive and never builds one while compiling a program.
Same caveat the compiler's CONTRIBUTING, AGENTS, and the website install docs now carry. Cargo emits a dependency's rlib and never its staticlib, so describing the library as simply "built by cargo into target/" is the wording that led to a compiler which could not link anything.
SKILL.md is the canonical copy of the mux agent skill, and it still described the rc-leak-check trap as a stale runtime in ~/.cache/mux-lang selected by MUX_RUNTIME_FEATURES. Neither exists: there is no build cache and no feature selection. Replace it with what an agent actually needs - the three prebuilt sources, the cargo build -p mux-runtime requirement, MUX_RUNTIME_LIB overriding everything, and why leak-check.sh forces it. ARCHITECTURE still described the runtime link as an independent semver pin reported by `mux --version`, a flag clap rejects.
This was referenced Jul 29, 2026
Merged
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
| Filename | Overview |
|---|---|
| docs/decisions/0004-runtime-resolved-from-source.md | Introduces the source-resolution and crates.io-freeze decision, including runtime linking, pinning, and release consequences. |
| docs/release-process.md | Replaces registry publishing with lockfile pin settlement and now requires runtime changelog entries in the change PR before merge. |
| ARCHITECTURE.md | Updates runtime dependency, prebuilt-library lookup, installation layout, and version-reporting documentation. |
| SKILL.md | Replaces obsolete runtime-cache guidance with the current prebuilt-runtime resolution and leak-check workflow. |
| docs/decisions/0002-independent-versioning.md | Clearly marks the obsolete runtime publishing sequence as superseded while retaining independent versioning. |
| README.md | Updates the runtime repository description to reflect its lockfile-pinned git dependency. |
| docs/decisions/README.md | Adds ADR 0004 to the decision index and states its relationship to ADR 0002. |
Reviews (2): Last reviewed commit: "Address PR review: align the resolution ..." | Re-trigger Greptile
Two findings from Greptile on #32. ARCHITECTURE and ADR 0004 described the release-install case as the library sitting beside the binary, omitting the sibling `lib/` that SKILL.md documents and that scripts/install.sh actually produces. Three canonical documents describing the same search should not disagree about where it looks, particularly when one prebuilt library can shadow another. Both now name the same two locations. The mux-runtime steps had the changelog entry follow the merge, which makes it a separate change and leaves a window where main carries code with no record of it. With no version tags that entry is the only history, so it now lands in the same PR as the change.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Records the decision the other three PRs implement, so it lands first.
Why
ADRs 0002 and 0003 disagreed about what is authoritative for the runtime. 0002 had the compiler pin a semver range on a published
mux-runtime, so a coupled change shipped publish-first. 0003 then had CI build from sibling source, so a coupled change went green without a publish. The seam between them is what produced the[patch.crates-io]block in mux-compiler, and with it a release-checklist item and a publish handshake for every coupled change - the loose thread behind muxlang/mux-runtime#26 and muxlang/mux-compiler#316.Two findings drove the direction:
mux-runtimeas a Rust library. Zeromux_runtime::references. The dependency existed only to stage source where the compiler could find it.cargo install mux-langneeds a Rust toolchain plus the exact LLVM 22 development libraries, then compiles llvm-sys from scratch. The documented install path is the prebuilt installer, which needs none of that.What 0004 decides
mux-runtimeis a git dependency onmain, pinned to one commit byCargo.lock, so--lockedbuilds stay reproducible. This extends 0003's "verify against source" from CI to release.main, so an FFI break surfaces without the pin moving.Supersedes 0002's release-time publish ordering; independent versioning otherwise stands.
Also in this PR
release-process.mdrewritten for the no-publish flow,ARCHITECTURE.mdandREADME.mdcorrected (they described a crates.io pin andmux --version, a flag clap rejects), andSKILL.md- the canonical copy of themuxagent skill - updated, since it still documented a runtime build cache andMUX_RUNTIME_FEATURESthat no longer exist.Review order
This one, then muxlang/mux-compiler (the implementation), then mux-runtime and mux-website (docs describing what now exists).
Need help on this PR? Tag
@codesmith-botwith what you need. Autofix is disabled.