Source becomes software. Evidence earns promotion.

Quick start · What it does · Measured results · Safety · Status · ADRs

Rune is a learning toolchain for Rust that wraps Cargo. A normal build replays a frozen, content-addressed plan with no model call and Cargo dependency resolution in offline mode. Existing build scripts remain trusted host code. Exploring faster implementations is a separate, budgeted step, and nothing a model proposes is promoted until an independent evaluator accepts it.

Naming. The binary is rune; the crates.io package is rune-toolchain, because rune and rune-cli belong to the Rune scripting language. If you also have rune-cli installed, the two binaries collide on $PATH.

rune promote now requires a signed evaluation receipt (--receipt) and a separately supplied trusted public key (--trusted-key); unsigned reports are no longer promoted. See the migration and release procedure.

cargo install rune-toolchain        # installs the `rune` binary (Rust 1.88+)

cd your-cargo-workspace             # needs Cargo.toml and a committed Cargo.lock
rune build --freeze                 # approve a plan from today's inputs, build offline
rune verify                         # rebuild in a clean directory, compare artifact digests
rune explain                        # plan lineage, budget, evidence
rune rollback                       # restore the previous approved plan

Edit a source file and rune build refuses to run (stale plan: source_digest) until you approve a new plan with --freeze. That refusal is the point: an approved plan is bound to the exact source tree, lockfile and rustc -vV it was approved against.

Run rune --help for flags. Exit codes: 0 ok, 1 failure or rejection, 2 missing credentials.

1. Recall. Recipes are retrieved by fingerprint (source semantics, target, CPU features, compiler, ABI, policy). Retrieval ranks; it cannot approve.
2. Propose. OpenRouter, within an explicit dollar and token budget, with data_collection: deny, zdr: true and allow_fallbacks: false.
3. Apply. Agent Booster 0.2.2 (pinned, via a Node sidecar) or a built-in exact replace, both hash-checked.
4. Evaluate. A separate evaluator builds baseline and candidate in isolated copies, runs the visible tests, then a hidden holdout, then paired benchmarks.
5. Retain. Only validated evidence enters memory. Rejected recipes stay searchable with their failure scope.
6. Promote. Approval keys cover target, compiler, policy, contract and evaluator version. Any change invalidates them.

These come from tests in this repository, run on one x86_64 Linux machine with a Rust 1.98 toolchain. They are not benchmarks of your code.

Read the numbers with these caveats. The CI width reflects variance within one session, not drift across days. The speedup is for a small kernel written to benefit from the technique. The ledger reconciliation compares the ledger with a log written from the same provider response, so it is not an independent billing check. The recipe-selection figure is on synthetic records.

• Frozen inputs. A plan's id is the SHA-256 of its canonical JSON. A tampered plan file fails the id check; plan ids are validated as hex before they touch a path.
• No model in the build path. build and verify never read credentials and never write the ledger. Tests assert this.
• Independent evaluation. The contract, thresholds and holdout live outside the candidate tree and are hashed into the report. A candidate that edits its own tests, benches or .cargo/config.toml is rejected.
• Explicit gates, not a score. New unsafe, new dependencies, new build.rs or proc-macros, and new capabilities (std::net, std::process, filesystem writes, env) each reject on their own.
• Statistics. At least 30 paired, interleaved samples after warmup; the lower bound of the 95% CI of the speedup must exceed 1 + min_improvement; guard benchmarks must not regress beyond their tolerance.
• Honest isolation. Candidate runs use a timeout, prlimit memory and CPU limits, a network namespace and a scrubbed environment, and the report lists the layers actually applied. The workspace copy is a plain copy unless the filesystem supports reflinks. This is not a hardened sandbox; build scripts and proc-macros are untrusted code.
• Promotion trust. rune promote requires an Ed25519 evaluator receipt and an independently supplied --trusted-key outside the candidate workspace. It authenticates the exact report bytes and compares measured baseline, compiler, native target, policy and evaluator identity before approving the candidate. rune eval --signing-key KEY --receipt-out RECEIPT --out REPORT produces receipts on a trusted native runner. Missing isolation requires explicit opt in at evaluation and promotion. The signing account remains trusted; this does not safely sandbox hostile build scripts or protect a signing key from processes running as that account. See ADR 011.
• Cost control. Budgets are reserved before any paid call, tracked in exact micro-dollars, and overruns are recorded rather than hidden.
• Reversible cleanup. Only generated objects recorded in an ownership manifest can be collected. Unreachable ones are quarantined for seven days; file age never authorizes deleting source. Rollback plans keep their artifacts.
• Supply chain. CI runs cargo audit and cargo deny with an explicit license allowlist.

Cross-compiling is compile evidence only. Performance claims need execution on the target.

Loading is blocked on an ABI mismatch or a missing CPU feature, and a target without an executor reports unvalidated. The artifact envelope is an ordinary evidence directory binding source, lockfile, plan, toolchain, target, test summary, policy and executable digests. A signature proves provenance and integrity, not correctness, and counts as trusted only when verified against a public key you supply. It is not an RVF container: the published rvf-runtime cannot store an arbitrary payload, and a ZIP is not RVF.

Implemented and tested: everything in the tables above. Not done, and not claimed:

• MetaHarness and AgenticOW. Neither is integrated. MetaHarness exposes no performance-evaluation API, and AgenticOW is a copy-on-write vector store for agent memory, not a workspace sandbox. Rune ships its own evaluator and workspace behind an Evaluator trait so an adapter can be added.
• RuVector ranking. An optional ruvector feature ranks with ruvector-core HNSW. It is off by default because that dependency tree needs Rust 1.89.
• Learning claim. Scoped evidence now exists for memory based selection within twelve synthetic sorting contexts: frozen training memory selected a validated improvement in 53.5% of 288 fresh input cases, versus 35.5% for random choice and 36.8% for the training selected fixed algorithm. The prospective confirmation passed its frozen confidence and significance gates. The earlier 34-kernel study remains Insufficient, and the 36-case sorting pilot remains NoDifference. See proof and limits, confirmation protocol and result. Generalization to independent kernel families and production optimization remains unproven.
• Real hardware. No aarch64 hardware was available; aarch64 and WASM results are emulator or foreign-runtime correctness evidence.
• Release gate. Fixture gates pass, and a snapshot of Rune's own workspace with real dependencies now builds through plain Cargo and Rune with an identical selected product; a fresh rebuild reproduces its digest. This checks one selected product, with the observed workspace and toolchain. See proof.
• Compiler integration. Rune reuses rustc and Cargo. MIR passes and a compiler fork are out of scope.

• ADR 001: Rune architecture and Cargo compatibility
• ADR 002: Bounded OpenRouter reasoning
• ADR 003: Agent Booster as the local edit engine
• ADR 004: RuVector evidence and transfer memory
• ADR 005: Independent validation and security contracts
• ADR 006: Hardware contracts and artifacts
• ADR 007: Isolation and safe cleanup
• ADR 008: Delivery gates and economic acceptance
• ADR 009: Rune identity and visual language
• ADR 010: rGi as an optional campaign supervisor
• ADR 011: Authenticated evaluator provenance
• ADR 012: Stable workspace product and path selection

Validation receipts and source provenance

cargo fmt --all --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked
cargo deny check && cargo audit

The Agent Booster tests need npm install --ignore-scripts at the repository root (the version is pinned in package-lock.json). rune improve needs OPENROUTER_API_KEY in the environment, never on disk; without it the command exits 2 before any ledger write or request.

MIT. See LICENSE.