Skip to content

feat: implement baml toolchain pin - #4386

Merged
sxlijin merged 6 commits into
canaryfrom
sxlijin/b-1123-bytecode-version-skew
Aug 13, 2026
Merged

feat: implement baml toolchain pin#4386
sxlijin merged 6 commits into
canaryfrom
sxlijin/b-1123-bytecode-version-skew

Conversation

@sxlijin

@sxlijin sxlijin commented Aug 12, 2026

Copy link
Copy Markdown
Contributor

Summary

  • add baml toolchain pin <canary|nightly|version|path> to select a project-local toolchain in the nearest baml.toml
  • share installation, channel activation, and local-path validation behavior with baml toolchain use
  • preserve manifest formatting and comments while replacing conflicting toolchain.version, toolchain.channel, or toolchain.path selectors
  • update generated-bytecode version-skew diagnostics to recommend the executable pin command
  • identify each bridge's package ecosystem in upgrade guidance, including “the Python package,” npm, Go, Rust, NuGet, Maven, Swift, and C++

Why

The existing version-skew error told users to pin toolchain.version manually or change their machine-wide default with baml toolchain use. BAML did not provide a command that performed the project-local edit.

This makes the primary recovery path directly executable, supports the same selector forms as baml toolchain use, and keeps the alternative bridge-upgrade guidance specific to the active SDK ecosystem.

Behavior

baml toolchain pin canary
baml toolchain pin nightly
baml toolchain pin 0.15.1-nightly.20260807.a
baml toolchain pin ./target/debug/baml-cli

The command:

  • finds the nearest baml.toml from the current directory
  • validates the manifest before downloading or writing
  • installs exact versions when missing
  • installs and activates channel selections
  • validates local binaries and stores a normalized path
  • atomically writes the matching [toolchain] key: version, channel, or path
  • removes conflicting selectors while preserving TOML comments and formatting

Validation

  • cargo test -p baml -p bridge_cffi — 43 wrapper unit tests, 5 wrapper integration tests, 37 bridge unit tests, and bridge ABI/header/unhandled-spawn tests passed
  • cargo clippy -p baml -p bridge_cffi --all-targets -- -D warnings
  • cargo fmt --all -- --check
  • rebuilt the Python bridge with uv run maturin develop --uv
  • uv run pytest -n 0 tests/test_engine.py::TestBasics::test_generated_bytecode_version_skew_fails_before_deserialization -q — 1 passed
  • uv run ruff check tests/test_engine.py
  • git diff --check

Linear: B-1123

Follow-up to #4315 and #4380.

Summary by CodeRabbit

  • New Features

    • Added baml toolchain pin to select a project-specific toolchain by version, release channel, or local executable path.
    • Toolchain settings are saved in the nearest project manifest, with paths normalized automatically.
    • Added offline status support for verifying pinned toolchains.
  • Bug Fixes

    • Improved version-mismatch guidance with clear steps to pin or upgrade the toolchain and regenerate code.
    • Preserved existing manifest formatting and comments when updating toolchain settings.

@linear

linear Bot commented Aug 12, 2026

Copy link
Copy Markdown

B-1123

@vercel

vercel Bot commented Aug 12, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
beps Ready Ready Preview Aug 13, 2026 12:24am
promptfiddle2 Ready Ready Preview Aug 13, 2026 12:24am

Request Review

@coderabbitai

coderabbitai Bot commented Aug 12, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: cedfcdb8-ad89-4cb9-a21b-12c79a7e1c39

📥 Commits

Reviewing files that changed from the base of the PR and between 2a0ae6a and 13bfe2c.

📒 Files selected for processing (1)
  • baml_language/crates/baml/tests/toolchain_pin_e2e.rs
🚧 Files skipped from review as they are similar to previous changes (1)
  • baml_language/crates/baml/tests/toolchain_pin_e2e.rs

📝 Walkthrough

Walkthrough

Changes

The CLI adds baml toolchain pin for version, channel, and local path selectors. It discovers the nearest project manifest and preserves TOML formatting and comments. Version-skew diagnostics now recommend pinning or upgrading the bridge package.

Toolchain selection and compatibility

Layer / File(s) Summary
Toolchain selector CLI and discovery
baml_language/crates/baml/Cargo.toml, baml_language/crates/baml/src/main.rs
The CLI parses baml toolchain pin, discovers project manifests, and accepts normalized local path selectors.
Manifest pinning and selector persistence
baml_language/crates/baml/src/main.rs
Toolchain selection validates or installs selectors and updates baml.toml while preserving comments and formatting.
Pinning validation
baml_language/crates/baml/src/main.rs, baml_language/crates/baml/tests/toolchain_pin_e2e.rs
Tests cover manifest mutation, version and channel pinning, local paths, activation state, canonical paths, and offline status output.
Version-skew repair guidance
baml_language/crates/bridge_cffi/src/identity.rs, baml_language/crates/bridge_cffi/src/lib.rs, baml_language/sdks/python/tests/test_engine.py
Bridge diagnostics recommend toolchain pinning or bridge-package upgrades. Rust and Python assertions check the revised guidance.

Estimated code review effort: 4 (Complex) | ~45 minutes

Mergeability Score: ⚪ Minimal · up to 13bfe

The PR adds project-local toolchain pinning and updates version-skew guidance, with the stated validation checks passing; no actionable merge-blocking risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant BamlCLI
  participant baml.toml
  participant ToolchainState
  User->>BamlCLI: Run baml toolchain pin
  BamlCLI->>baml.toml: Find nearest manifest
  BamlCLI->>baml.toml: Replace version, channel, or path
  BamlCLI->>ToolchainState: Validate or install selector
  ToolchainState-->>BamlCLI: Return active toolchain state
  BamlCLI-->>User: Report pinning result
Loading

Possibly related PRs

Poem

I’m a rabbit with a pinned little path,
TOML keeps comments along my trail.
A bridge sees skew and points the way,
Pin or upgrade, then generate.
Hop, hop—toolchains stay in place!

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely identifies the primary change: implementing the baml toolchain pin command.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch sxlijin/b-1123-bytecode-version-skew

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions

Copy link
Copy Markdown

⏭️ Performance benchmarks were skipped

Perf benchmarks (CodSpeed) are opt-in on pull requests — they no longer run on every push. They always run automatically after merge to canary/main.

To run them on this PR, do any of the following, then push a commit (or re-run CI):

  • Add RUN_CODSPEED=1 to the PR description, or
  • Include run-perf or /perf in the PR title or any commit message.

@vercel
vercel Bot temporarily deployed to Preview – beps August 12, 2026 22:54 Inactive
@vercel
vercel Bot temporarily deployed to Preview – promptfiddle2 August 12, 2026 23:00 Inactive
@github-actions

github-actions Bot commented Aug 12, 2026

Copy link
Copy Markdown

Binary size checks passed

7 passed

Artifact Platform File Gzip Gated on Baseline Delta Status
baml-cli Linux 🔒 26.2 MB 11.1 MB file 27.4 MB -1.2 MB (-4.4%) OK
packed-program Linux 🔒 16.9 MB 6.8 MB file 18.6 MB -1.7 MB (-8.9%) OK
baml-cli macOS 🔒 20.4 MB 9.7 MB file 21.3 MB -913.9 KB (-4.3%) OK
packed-program macOS 🔒 13.3 MB 6.0 MB file 14.5 MB -1.2 MB (-8.1%) OK
baml-cli Windows 🔒 21.9 MB 9.9 MB file 23.0 MB -1.1 MB (-4.7%) OK
packed-program Windows 🔒 14.1 MB 6.1 MB file 15.5 MB -1.4 MB (-9.1%) OK
bridge_wasm WASM 15.5 MB 🔒 4.2 MB gzip 4.6 MB -438.1 KB (-9.5%) OK

🔒 = the size this artifact is GATED on (ceiling + delta). Binaries gate on file size (installed binary); WASM gates on gzip (download size). The other size is shown for information only.


Generated by cargo size-gate · workflow run

@vercel
vercel Bot temporarily deployed to Preview – beps August 12, 2026 23:18 Inactive
@vercel
vercel Bot temporarily deployed to Preview – promptfiddle2 August 12, 2026 23:25 Inactive
@sxlijin sxlijin changed the title feat: add project toolchain pinning feat: implement baml toolchain pin Aug 12, 2026
@sxlijin
sxlijin marked this pull request as ready for review August 12, 2026 23:41

sxlijin commented Aug 12, 2026

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Aug 12, 2026

Copy link
Copy Markdown
Contributor
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 18f95a73ea

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread baml_language/crates/baml/src/main.rs Outdated
Comment thread baml_language/crates/bridge_cffi/src/lib.rs Outdated
@vercel
vercel Bot temporarily deployed to Preview – beps August 12, 2026 23:45 Inactive

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
baml_language/crates/bridge_cffi/src/identity.rs (1)

64-75: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Add unit coverage for every package label.

package_kind supplies user-visible repair guidance through format_version_skew, but the provided tests exercise only BridgeLanguage::Python. Add a table-driven unit test for NodeJs, Web, Python, Go, Rust, CSharp, Cpp, Java, and Swift.

As per coding guidelines, prefer Rust unit tests over integration tests where possible.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@baml_language/crates/bridge_cffi/src/identity.rs` around lines 64 - 75, Add a
Rust unit test alongside package_kind that table-drives every BridgeLanguage
variant—NodeJs, Web, Python, Go, Rust, CSharp, Cpp, Java, and Swift—and asserts
the expected package label returned by package_kind. Keep the test focused on
this method and use the existing unit-test module conventions.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@baml_language/crates/baml/tests/toolchain_pin_e2e.rs`:
- Around line 144-164: Update the toolchain pin command in the test around
local_cli to pass the platform-selected executable path, using baml-cli.exe on
Windows and baml-cli elsewhere, so it matches the fixture created by the test.

In `@baml_language/crates/bridge_cffi/src/lib.rs`:
- Around line 284-290: Update the startup version-skew error message in the
bridge failure path to use direction-neutral remediation: instruct users to
install a bridge package version compatible with BAML toolchain {generated}
instead of telling them to upgrade it. Also update
older_generated_toolchain_reports_complete_repair_guidance to assert the revised
wording and complete repair guidance while preserving the existing
pin-and-regenerate option.

---

Nitpick comments:
In `@baml_language/crates/bridge_cffi/src/identity.rs`:
- Around line 64-75: Add a Rust unit test alongside package_kind that
table-drives every BridgeLanguage variant—NodeJs, Web, Python, Go, Rust, CSharp,
Cpp, Java, and Swift—and asserts the expected package label returned by
package_kind. Keep the test focused on this method and use the existing
unit-test module conventions.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 4d7a7275-588d-4b40-a9a6-585dfdc6d61a

📥 Commits

Reviewing files that changed from the base of the PR and between 593a513 and 18f95a7.

⛔ Files ignored due to path filters (1)
  • baml_language/Cargo.lock is excluded by !**/*.lock
📒 Files selected for processing (6)
  • baml_language/crates/baml/Cargo.toml
  • baml_language/crates/baml/src/main.rs
  • baml_language/crates/baml/tests/toolchain_pin_e2e.rs
  • baml_language/crates/bridge_cffi/src/identity.rs
  • baml_language/crates/bridge_cffi/src/lib.rs
  • baml_language/sdks/python/tests/test_engine.py

Comment thread baml_language/crates/baml/tests/toolchain_pin_e2e.rs Outdated
Comment thread baml_language/crates/bridge_cffi/src/lib.rs Outdated

sxlijin commented Aug 12, 2026

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

Addressed both actionable inline findings in 2a0ae6abbf: the Windows selector now uses baml-cli.exe, and the bridge remediation is direction-neutral. Also fixed inline-table toolchain handling from the automated Codex review. The suggested exhaustive package_kind unit test is intentionally not restored because the PR author explicitly requested deletion of that test; the production mapping remains exercised by the version-skew diagnostic coverage.

@coderabbitai

coderabbitai Bot commented Aug 12, 2026

Copy link
Copy Markdown
Contributor

@sxlijin I will review the current changes in #4386, including the reported fixes in 2a0ae6abbf.


🧠 Learnings used
Learnt from: rossirpaulo
Repo: BoundaryML/baml PR: 4174
File: .github/workflows/build2-bridge-cffi.reusable.yaml:200-241
Timestamp: 2026-07-24T07:59:58.840Z
Learning: In `.github/workflows/build2-bridge-cffi.reusable.yaml`, Windows MSVC-ABI `bridge_cffi` builds use `clang-cl` rather than `cl.exe`. Their native C/C++ path hygiene is implemented with `/clang:-ffile-prefix-map` in `CFLAGS` and `CXXFLAGS`, mapping both long and 8.3 Windows path forms; do not apply MSVC `/pathmap` or `/experimental:deterministic` guidance to this workflow branch.
⚠️ Action not completed

Already reviewed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@vercel
vercel Bot temporarily deployed to Preview – beps August 12, 2026 23:50 Inactive
@vercel
vercel Bot temporarily deployed to Preview – promptfiddle2 August 12, 2026 23:57 Inactive
@vercel
vercel Bot temporarily deployed to Preview – beps August 12, 2026 23:59 Inactive
@vercel
vercel Bot temporarily deployed to Preview – promptfiddle2 August 13, 2026 00:08 Inactive
@sxlijin
sxlijin added this pull request to the merge queue Aug 13, 2026
@sxlijin
sxlijin removed this pull request from the merge queue due to a manual request Aug 13, 2026
@vercel
vercel Bot temporarily deployed to Preview – beps August 13, 2026 00:18 Inactive
@vercel
vercel Bot temporarily deployed to Preview – promptfiddle2 August 13, 2026 00:24 Inactive
@sxlijin
sxlijin added this pull request to the merge queue Aug 13, 2026
Merged via the queue into canary with commit c8d2218 Aug 13, 2026
83 checks passed
@sxlijin
sxlijin deleted the sxlijin/b-1123-bytecode-version-skew branch August 13, 2026 00:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant