fix(installer): bootstrap with compatible Linux wrappers

[sxlijin]

Fixes #4624

We have two structural issues with install.sh/wrapper:

• There is no version of the wrapper that works on Alpine-based images (we don't ship a musl build).
• The wrapper only works on really new Linux images, specifically it requires a newer libc than the current Debian LTS (bookworm) ships with.

This PR implements three fixes:

• install.sh now can choose glibc or musl wrapper (it prefers glibc if available, but falls back to musl if it can't find it)
• we now ship both glibc and musl builds for the wrapper
  • glibc has support for a pluggable module system to modify network path at runtime (NSS), so although we could just only ship musl I opted to ship glibc+musl. (other issues around malloc performance are not relevant for the wrapper).
  • note that reqwest itself respects things like HTTPS_PROXY so maybe musl only would be OK, if it ends up being a significant maintenance burden
• we've lowered our glibc compatibility floor: x64 now works with glibc 2.17 and arm64 works with glibc 2.28, per the findings we made when we were choosing our backwards compatibility floors for engine

Ad-hoc testing with Debian Bookworm and Alpine on native x86_64 and aarch64 GitHub runners confirms this fix works:

• Without this change: published canary install.sh and wrapper — all four platform jobs fail during toolchain bootstrap.
• With this change: this PR's install.sh and workflow-built wrappers — all four platform jobs pass through installer selection, wrapper execution, toolchain download, and real CLI init/check commands.

[vercel]

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

Project	Deployment	Actions	Updated
beps	Ready	Preview	Sep 1, 2026 1:47am UTC
developer-docs	Error		Sep 1, 2026 1:47am UTC
promptfiddle2	Ready	Preview	Sep 1, 2026 1:47am UTC

[github-actions]

⏭️ 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.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Team

Run ID: 65f3234e-9089-4235-8dd6-f0d3b7ba530e

📥 Commits

Reviewing files that changed from the base of the PR and between 6baaa83 and 3844783.

📒 Files selected for processing (6)

• .github/workflows/build2-bridge-cffi.reusable.yaml
• .github/workflows/build2-java-sdk.reusable.yaml
• .github/workflows/build2-wrapper.reusable.yaml
• .github/workflows/release-baml-language.yml
• mise.toml
• scripts/tests/test_release_pipeline_contract.py

Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

The release contract now records GNU GLIBC ceilings. Linux installation detects GNU or musl and selects the matching wrapper. A reusable workflow builds, validates, packages, and smoke-tests libc-specific wrappers.

Changes

Linux libc compatibility

Layer / File(s)	Summary
GNU compatibility contract release/platforms.json, scripts/baml_release_platforms.py, scripts/tests/test_baml_release_platforms.py	GNU Linux wrappers declare glibc_max: "2.18". The value enters the GitHub Actions matrix and is validated as a dotted numeric version. Tests cover libc-specific assets and invalid metadata.
Libc detection and target selection scripts/install.sh, scripts/tests/test_install_sh.py	Linux ARM64 and x86_64 installation detects GNU or musl and selects the matching target. Offline tests simulate both libc variants.
Reusable wrapper release workflow .github/workflows/build2-wrapper.reusable.yaml, .github/workflows/release-baml-language.yml, scripts/tests/test_release_pipeline_contract.py	The release workflow calls a reusable wrapper builder. The builder generates its matrix, builds standard and no-self-update wrappers, checks ABI limits, runs pinned-container installer tests, archives outputs, and uploads artifacts.
Cross-tool provisioning .github/workflows/build2-bridge-cffi.reusable.yaml, .github/workflows/build2-java-sdk.reusable.yaml, mise.toml	Linux cross-compilation setup uses mise. The cargo:cross version is pinned to 0.2.5.

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

Merge Risk: 🔵 Low · up to 38447

The installer now selects GNU or musl Linux wrappers, but release publication still depends on a separate wrapper version bump to publish the matching manifest and artifacts. If that coordination is missed, affected Linux installations can fail until the wrapper release is promoted; the PR is otherwise mergeable with explicit owner follow-up before release.

Sequence Diagram(s)

sequenceDiagram
  participant ReleaseWorkflow
  participant WrapperBuilder
  participant ABIValidator
  participant LibcContainer
  participant InstallScript
  ReleaseWorkflow->>WrapperBuilder: Pass source_sha and wrapper_version
  WrapperBuilder->>WrapperBuilder: Generate matrix and build wrappers
  WrapperBuilder->>ABIValidator: Check GLIBC symbols and dynamic dependencies
  ABIValidator->>LibcContainer: Select Debian or Alpine image
  LibcContainer->>InstallScript: Run offline installer verification
  InstallScript->>LibcContainer: Select GNU or musl wrapper

Loading

Suggested reviewers: rossirpaulo, 2kai2kai2

Poem

A rabbit maps the GNU trail
Musl wrappers guard the rail
GLIBC bounds are written bright
Builds cross safely through the night
Every archive lands just right

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 45.45% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 5 files. (5 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes address issue #4624 by detecting Linux libc, selecting GNU or musl wrappers, publishing GNU wrappers with a GLIBC 2.18 ceiling, and adding compatibility verification for Debian and Alpine …
Out of Scope Changes check	✅ Passed	The workflow, platform contract, installer, toolchain, and test changes support compatible Linux wrapper publication and selection. The shared cross-installation updates and version pin are related im…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: the installer now bootstraps with compatible Linux wrappers.

Full details: Linked Issues check

Explanation

The changes address issue #4624 by detecting Linux libc, selecting GNU or musl wrappers, publishing GNU wrappers with a GLIBC 2.18 ceiling, and adding compatibility verification for Debian and Alpine environments.

Full details: Out of Scope Changes check

Explanation

The workflow, platform contract, installer, toolchain, and test changes support compatible Linux wrapper publication and selection. The shared cross-installation updates and version pin are related implementation changes.

Full details: Docstring Coverage

Explanation

Docstring coverage is 45.45% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 5 files. (5 skipped: 5 unsupported.)

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch sxlijin/issue-4624-bookworm-installer

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-30T06:30:25.866206Z	d6d7525	PR opened

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

Binary size checks passed

✅ 7 passed

	Artifact	Platform	File	Gzip	Gated on	Baseline	Delta	Status
✅	baml-cli	Linux	🔒 72.9 MB	27.5 MB	file	72.9 MB	+8.8 KB (+0.0%)	OK
✅	packed-program	Linux	🔒 28.6 MB	10.9 MB	file	28.6 MB	-20.0 KB (-0.1%)	OK
✅	baml-cli	macOS	🔒 63.4 MB	25.2 MB	file	63.3 MB	+33.1 KB (+0.1%)	OK
✅	packed-program	macOS	🔒 25.8 MB	10.2 MB	file	25.8 MB	-43.8 KB (-0.2%)	OK
✅	baml-cli	Windows	🔒 83.1 MB	27.9 MB	file	83.0 MB	+87.2 KB (+0.1%)	OK
✅	packed-program	Windows	🔒 30.9 MB	10.8 MB	file	30.9 MB	-73.3 KB (-0.2%)	OK
✅	bridge_wasm	WASM	22.2 MB	🔒 5.7 MB	gzip	5.7 MB	+32.2 KB (+0.6%)	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

[sxlijin]

@coderabbitai review

Fresh review was requested after merging canary, but CodeRabbit did not respond within the requested two-minute window.

[coderabbitai]

⚠️ Action not completed

Head commit changed.

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.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.