Document the crates.io freeze and the git-dependency workflow

.github/workflows/ci.yml

@@ -197,8 +197,12 @@ jobs:
       LLVM_SYS_221_STRICT_VERSIONING: "1"
       CC: clang-22
       CXX: clang++-22
-      # Build the runtime from THIS PR's checked-out source, not from crates.io.
-      MUX_RUNTIME_SRC: ${{ github.workspace }}
+      # Force the archive built from THIS PR's source below. The compiler no
+      # longer reads MUX_RUNTIME_SRC and never builds a runtime while compiling
+      # a program (muxlang/mux-context ADR 0004), so without this it would link
+      # the runtime its own Cargo.lock pins and this job would silently stop
+      # testing the runtime under review.
+      MUX_RUNTIME_LIB: ${{ github.workspace }}/target/debug/libmux_runtime.a
     steps:
       - name: Check out runtime (this PR)
         uses: actions/checkout@v4
@@ -223,9 +227,9 @@ jobs:
       - name: Cache Cargo registry and build
         uses: actions/cache@v4
         with:
-          # Intentionally NOT caching ~/.cache/mux-lang: the compiler builds the
-          # runtime from source there, and this job exists to exercise THIS
-          # branch's runtime source, so it must rebuild it fresh every run.
+          # The runtime archive itself is rebuilt from this checkout every run
+          # (below) rather than restored, since exercising THIS branch's source
+          # is the whole point of the job.
           path: |
             ~/.cargo/registry
             ~/.cargo/git
@@ -234,6 +238,15 @@ jobs:
           key: ${{ runner.os }}-downstream-cargo-${{ hashFiles('mux-compiler/Cargo.lock') }}-${{ hashFiles('Cargo.lock') }}
           restore-keys: |
             ${{ runner.os }}-downstream-cargo-
+      - name: Build this PR's runtime archive
+        # Compiled Mux programs link libmux_runtime.a, and cargo emits a
+        # dependency's rlib but never its staticlib - so the archive has to be
+        # built here explicitly, from this checkout.
+        run: |
+          set -euo pipefail
+          cargo build --locked
+          test -f "$MUX_RUNTIME_LIB"
+
       - name: Compiler executable integration tests against runtime source
         # These tests compile and link .mux programs end to end, so an
         # undefined-symbol / FFI-signature break in the runtime fails here.

AGENTS.md

@@ -82,19 +82,24 @@ No LLVM/clang needed. CI runs fmt + clippy + tests + a SonarQube scan.
 - The compiler links the BUILT library; it does NOT import this crate's Rust code.
 - Changing exported FFI symbols/signatures is a coupled change with the compiler.
 - A coupled change (a new language feature needing a new runtime function) ships in
-  TWO steps: publish the runtime (new version) first, then bump the compiler's
-  `mux-runtime = "X.Y"` pin.
-- Local coupled dev: check this out as a sibling of `mux-compiler` (resolved as
-  `../mux-runtime` automatically) or set `MUX_RUNTIME_SRC`.
-- The compiler's `full_runtime_features()` parity test reads this `Cargo.toml`'s
-  `full` feature list - keep them in sync.
+  ONE step per repo and no publish: merge here, then move the compiler's pin with
+  `cargo update -p mux-runtime`. See
+  [ADR 0004](https://github.com/muxlang/mux-context/blob/main/docs/decisions/0004-runtime-resolved-from-source.md).
+- Local coupled dev: build here and point `MUX_RUNTIME_LIB` at the resulting
+  `target/debug/libmux_runtime.a`. It is the first thing runtime resolution
+  consults, so it overrides the archive built from the locked commit - and a
+  leftover value keeps overriding it until unset.
+- The compiler always links the `full` feature set; it no longer builds a
+  feature-trimmed runtime, so there is no feature-parity test to keep in sync.
 
 ## Release
 
-Versioned independently of the compiler. Published manually from a local checkout
-(MAINTAINER-ONLY, no token in CI). Full steps:
+Not released on its own cadence. crates.io is frozen (versions through 0.5.0 stay
+published, no new ones), and `mux-compiler` consumes this repo as a git dependency
+pinned by its `Cargo.lock` - so merging to `main` is what makes a change
+available. The `version` field is inert while the channel is frozen; record
+changes under an `## [Unreleased]` changelog heading. Full steps:
 [muxlang/mux-context release process](https://github.com/muxlang/mux-context/blob/main/docs/release-process.md#mux-runtime).
-Publish the runtime before bumping the compiler's `mux-runtime` pin.
 
 ## Related repos
 

CHANGELOG.md

@@ -2,8 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+Versions through 0.5.0 were published to crates.io. That channel is now frozen:
+`mux-compiler` consumes this repo as a git dependency pinned to a commit by its
+`Cargo.lock`, so merging to `main` is what makes a change available and there is
+no version to bump. Record changes under `Unreleased` as part of the change
+itself - see
+[ADR 0004](https://github.com/muxlang/mux-context/blob/main/docs/decisions/0004-runtime-resolved-from-source.md).
+
+## [Unreleased]
+
+Nothing yet.
 
 ## [0.5.0] - 2026-07-13
 

README.md

@@ -7,7 +7,6 @@
 **The runtime and standard library for [Mux](https://github.com/muxlang)**
 
 [![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](LICENSE)
-[![crates.io](https://img.shields.io/crates/v/mux-runtime.svg?style=flat-square)](https://crates.io/crates/mux-runtime)
 [![Documentation](https://img.shields.io/badge/docs-online-blue.svg?style=flat-square)](https://mux-lang.dev)
 [![Sonar Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=muxlang_mux-runtime&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=muxlang_mux-runtime)
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=muxlang_mux-runtime&metric=coverage)](https://sonarcloud.io/summary/new_code?id=muxlang_mux-runtime)
@@ -16,8 +15,13 @@
 
 Compiled Mux programs link against this library at compile time. It is plain,
 stable Rust with **no LLVM dependency** - so runtime and standard-library work
-needs only a Rust toolchain, not the compiler's LLVM 22 + clang setup. Published
-to crates.io as [`mux-runtime`](https://crates.io/crates/mux-runtime).
+needs only a Rust toolchain, not the compiler's LLVM 22 + clang setup.
+
+> **crates.io is frozen.** Versions through 0.5.0 remain published and are not
+> yanked, but no new ones will be. `mux-compiler` consumes this repo as a git
+> dependency on `main`, pinned to an exact commit by its `Cargo.lock`, so
+> merging here is what makes a change available. See
+> [ADR 0004](https://github.com/muxlang/mux-context/blob/main/docs/decisions/0004-runtime-resolved-from-source.md).
 
 ---
 
@@ -60,19 +64,32 @@ merge (shared CI runners are too noisy for a wall-clock threshold).
 ## Relationship to the compiler
 
 The compiler does not import this crate as Rust code - it links the built library
-when producing executables and fetches the published crate from crates.io (pinning
-a compatible semver range). For coupled local development, check this repo out as a
-sibling of `mux-compiler` (the compiler resolves `../mux-runtime` automatically) or
-set `MUX_RUNTIME_SRC` to a local checkout.
+when producing executables. It resolves this repo as a git dependency on `main`,
+pinned to an exact commit by its `Cargo.lock`, and links the archive cargo builds
+into its `target/` directory. Producing that archive takes `cargo build -p
+mux-runtime`: cargo emits a dependency's rlib and never its staticlib.
+
+For coupled local development, build this repo and point `MUX_RUNTIME_LIB` at the
+resulting `target/debug/libmux_runtime.a`. That is the first thing the compiler
+consults, so it overrides the library cargo built from the locked commit -
+which also means a leftover `MUX_RUNTIME_LIB` will keep overriding it until you
+unset it.
+
+The compiler never builds this crate while compiling a Mux program, and always
+links the `full` feature set. Static linking discards archive members nothing
+references, so a program that does not touch `sql` carries no SQLite.
 
 ---
 
 ## Versioning
 
-Versioned independently of the compiler. The compiler pins a compatible semver
-range and `mux --version` reports both, e.g. `mux 0.5.1 (runtime 0.5.0)`. A
-coupled change ships as two steps: publish the runtime first, then bump the
-compiler's `mux-runtime` pin.
+The compiler identifies this repo by commit, not by version: `mux version`
+reports the locked commit as semver build metadata, e.g.
+`runtime v0.5.0+g4e2dc14`. A coupled change is one PR here and one in
+`mux-compiler` - no publish step between them.
+
+The `version` field in `Cargo.toml` is inert while crates.io is frozen. Record
+changes under an `## [Unreleased]` heading in the changelog instead.
 
 Full release steps:
 [muxlang/mux-context release process](https://github.com/muxlang/mux-context/blob/main/docs/release-process.md#mux-runtime).