fix: upstream independent compiler and runtime fixes

[aaronvg]

Summary

• fix match/catch arm parsing and formatting around //# headers
• preserve interface and generic associated-error information in catch/throws analysis
• render captured structured logs in BAML syntax and retain thrown-error context in test output
• honor explicit source roots without redirecting sibling or unmarked source trees
• preserve structural media values in prompt tags
• expand control-flow graphs through methods, interfaces, and generic dispatch

The experimental baml_std/ai package, AI-only compiler/runtime work, provider continuation authentication, temporary AI fixtures, and realtime process APIs are intentionally excluded.

Validation

• cargo fmt --all -- --check
• cargo nextest run -p baml_cli (539 passed)
• cargo nextest run -p bex_engine (595 passed; one pre-existing leaky test annotation)
• cargo nextest run -p baml_project (81 passed)
• cargo nextest run -p sys_ops (12 passed)
• cargo nextest run -p baml_tests arm_header_comments (6 passed)
• cargo nextest run -p baml_tests catch_interface_refinement (6 passed)
• cargo nextest run -p baml_tests generic_bound_associated_error_is_reused_by_throws_analysis (1 passed)

---

Note

Medium Risk
Changes span project discovery (could load unintended trees only when --from is explicit), catch/throws typing, and LLM prompt assembly—areas that affect compile correctness and provider requests—but behavior is heavily covered by new e2e and snapshot tests.

Overview
Compiler & formatting: Match/catch arm parsing no longer spins on empty recovery or rejects //# header comments between arms; the formatter AST carries those headers via ArmListItem. Catch-arm reachability now treats interface throw facts and concrete refiners symmetrically (subtype checks), removing false unreachable-arm warnings. Generic calls can reuse instantiated throws from the call plan when type variables would otherwise leak.

CLI project loading: Introduces ProjectLayout (resolve_project_layout) splitting settings root vs source root. An explicit --from loads that tree even without baml.toml/baml_src/, and does not redirect a sibling directory (e.g. alternate baml_src_temp2) into the primary baml_src/ while still picking up an ancestor manifest when present. fmt, run, and introspection paths share this logic; playground keeps marker-based discovery.

LLM prompts & logs: render_prompt_values leaves Role and media types uncooked; assemble_prompt_ast builds multi-part content (including PDF URLs) instead of stringifying media away. Captured trace values for baml test --logs render as BAML-like structural strings, not protobuf debug dumps. Test run_test uses catch_all (e, ctx) so non-panic failures surface rendered error context in CLI output.

Playground CFG: Control-flow graph expansion resolves calls through TIR (methods, interface virtual dispatch with binding-aware cache keys) so generic runner.run(self) inlines concrete implementer bodies in visualization.

^{Reviewed by Cursor Bugbot for commit 0f29a6c. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• New Features

  • Prompts now preserve images, PDFs, and other media as structured content.
  • Trace and structured log values now render in readable formats, including nested data and media.
  • Project commands support explicit source directories, including unmarked or sibling source trees.

• Bug Fixes

  • Improved match/catch parsing, comments, error reporting, and generic exception handling.
  • Improved type-based error matching and generic interface dispatch.
  • Formatting and playground commands now handle project discovery more reliably.

Additional fixes (follow-up commits)

• fmt: fixed a formatter crash when client is used as an identifier (KW_CLIENT treated as a plain identifier in expression positions).
• fmt/parser: //# header comments are now accepted in class bodies, implements blocks, and interface bodies — extending the existing match/catch-arm header-comment support.
• parser: dedicated diagnostic when a test/testset name is written as a quoted string instead of an identifier (with a broken-syntax project covering it).
• regression pins: new fixtures ns_header_comments and ns_qualified_literals (qualified struct literals).
• housekeeping: merged latest canary (the in-BAML render_prompt_values media handling was superseded by canary's native assemble_prompt_ast; this branch keeps canary's version) and regenerated stale std/bytecode snapshots.
• refactor: centralize media wrapper class-name mapping behind MediaKind (wrapper_class_name / from_wrapper_class_name); wrapper layout knowledge moved next to BexExternalValue (media_wrapper_kind / media_wrapper_inner, MEDIA_WRAPPER_DATA_FIELD), replacing per-consumer string matches in bex_engine and the jinja value converter.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
beps	Ready	Preview	Aug 3, 2026 10:39pm
promptfiddle2	Ready	Preview	Aug 3, 2026 10:39pm

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR updates CLI project discovery, parser and formatter preservation, throw analysis, control-flow dispatch, media wrapper handling, structured value rendering, and test error reporting. It adds regression coverage for explicit source roots, header comments, generic errors, interface refinement, and qualified literals.

Changes

CLI project and source resolution

Layer / File(s)	Summary
Shared project layout resolution baml_language/crates/baml_cli/src/project_load.rs	Project loading separates effective settings roots from source roots and supports explicit manifest-less and sibling source directories.
Formatter, playground, and CLI coverage baml_language/crates/baml_cli/src/format.rs, baml_language/crates/baml_cli/src/playground_command.rs, baml_language/crates/baml_cli/tests/exit_code_e2e.rs	Formatter and playground discovery use resolved source roots. Tests cover standalone sources, sibling directories, and no-project behavior.

Parser and formatter syntax handling

Layer / File(s)	Summary
Header comments and arm recovery baml_language/crates/baml_compiler_parser/src/parser.rs, baml_language/crates/baml_tests/projects/compiles/arm_header_comments/main.baml, baml_language/crates/baml_tests/baml_src/ns_header_comments/header_comments.baml	Parser recovery accepts header comments in declarations and match/catch arms. Parser diagnostics cover invalid top-level bare test names.
Formatter AST preservation baml_language/crates/baml_fmt/src/ast/declarations.rs, baml_language/crates/baml_fmt/src/ast/expressions.rs, baml_language/crates/baml_fmt/src/lib.rs	Formatter AST nodes preserve and print header comments in declarations and arm lists.
Contextual identifiers and qualified literals baml_language/crates/baml_fmt/src/ast/tokens.rs, baml_language/crates/baml_fmt/src/ast/types.rs, baml_language/crates/baml_fmt/src/ast/expressions.rs, baml_language/crates/baml_tests/baml_src/ns_qualified_literals/qualified_literals.baml, baml_language/crates/baml_tests/projects/broken_syntax/testset_name_identifier/testset_name_identifier.baml	The formatter accepts client in additional identifier positions. Regression fixtures cover qualified struct literals and test-name syntax.

Throw analysis and reachability

Layer / File(s)	Summary
Interface and concrete throw matching baml_language/crates/baml_compiler2_tir/src/builder.rs, baml_language/crates/baml_tests/projects/compiles/catch_interface_refinement/main.baml	Throw matching recognizes interface refinement and concrete implementations as reachable.
Generic instantiated throws baml_language/crates/baml_compiler2_tir/src/callable.rs, baml_language/crates/baml_tests/src/compiler2_tir/phase8_exceptions.rs	Generic associated errors use instantiated call-plan throws when bindings remain unresolved.

Resolved control-flow graph dispatch

Layer / File(s)	Summary
Resolved call targets and graph expansion baml_language/crates/baml_project/src/db.rs	CFG expansion resolves free functions, methods, interface implementations, generic bindings, headers, recursion identities, and dispatch-aware cache keys.

Runtime value and media handling

Layer / File(s)	Summary
Media wrapper contract baml_language/crates/baml_base/src/core_types.rs, baml_language/crates/bex_external_types/src/bex_external_value.rs, baml_language/crates/bex_external_types/src/lib.rs, baml_language/crates/bex_engine/src/conversion.rs, baml_language/crates/sys_llm/src/jinja/value_conversion.rs	Media wrapper names and payload access use centralized mappings and a shared _data field constant.
Recursive structured trace rendering baml_language/crates/bex_engine/src/trace_value_encode.rs, baml_language/crates/bex_engine/src/value_capture.rs, baml_language/crates/bex_engine/tests/log_intrinsic.rs, baml_language/crates/baml_cli/tests/exit_code_e2e.rs	Structured values render in BAML-style forms, and tests assert complete rendered bodies.
Context-aware test failures baml_language/crates/baml_builtins2/baml_std/testing/registry.baml, baml_language/crates/baml_cli/tests/exit_code_e2e.rs	Generic failures use caught context text. End-to-end tests verify rendered thrown error details and source context.

Estimated code review effort: 5 (Critical) | ~90 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant ProjectLayout
  participant SourceDiscovery
  CLI->>ProjectLayout: resolve project and source roots
  ProjectLayout->>SourceDiscovery: provide source root
  SourceDiscovery-->>CLI: return BAML files

Loading

sequenceDiagram
  participant Caller
  participant TypeInference
  participant CFG
  Caller->>TypeInference: resolve function or interface target
  TypeInference-->>CFG: return location and dispatch bindings
  CFG->>CFG: expand concrete callee
  CFG-->>Caller: return resolved graph

Loading

Possibly related PRs

• BoundaryML/baml#3676: Related project and source-root resolution changes.
• BoundaryML/baml#4143: Related ErrorContext rendering behavior.
• BoundaryML/baml#4246: Related CFG call-target resolution changes.

Suggested reviewers: sxlijin, hellovai, 2kai2kai2

Poem

A rabbit maps roots through the morning light,
Header comments stay in place just right.
Errors show their captured name,
Calls resolve their concrete frame.
Media wrappers share one key,
Tests hop through syntax happily.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately identifies compiler and runtime fixes, which are major parts of the pull request, although it omits other areas.

✨ 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 codex/upstream-rust-fixes

---

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.}

[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.

[github-actions]

Binary size checks passed

✅ 7 passed

	Artifact	Platform	File	Gzip	Gated on	Baseline	Delta	Status
✅	baml-cli	Linux	🔒 27.6 MB	11.7 MB	file	27.4 MB	+199.8 KB (+0.7%)	OK
✅	packed-program	Linux	🔒 17.9 MB	7.4 MB	file	17.7 MB	+224.2 KB (+1.3%)	OK
✅	baml-cli	macOS	🔒 21.4 MB	10.3 MB	file	21.3 MB	+130.4 KB (+0.6%)	OK
✅	packed-program	macOS	🔒 14.0 MB	6.5 MB	file	13.8 MB	+160.9 KB (+1.2%)	OK
✅	baml-cli	Windows	🔒 23.1 MB	10.5 MB	file	23.0 MB	+123.8 KB (+0.5%)	OK
✅	packed-program	Windows	🔒 14.9 MB	6.6 MB	file	14.8 MB	+154.6 KB (+1.0%)	OK
✅	bridge_wasm	WASM	17.0 MB	🔒 4.6 MB	gzip	4.6 MB	+34.6 KB (+0.8%)	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

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

baml_language/crates/baml_compiler2_tir/src/callable.rs (1)

266-276: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Dead fallback: the new type-var fallback can never execute.

instantiated_callee_throws returns early at line 274-276 whenever call_plan.instantiated_throws is Some. Execution reaches the closure function_throws (and thus line 319-325) only when that same field is None. The new check call_plan.and_then(|plan| plan.instantiated_throws.as_ref()) at line 321 tests the identical field and can never be Some at this point.

This fallback is unreachable. It does not implement the intended behavior described for this change ("falls back to the call plan's instantiated throws when type variables remain unresolved").

🐛 Proposed fix: remove the top-level short-circuit so the per-parameter substitution can run, and only fall back to the recorded call-plan throws for members whose substitution still contains a type variable

 pub(crate) fn instantiated_callee_throws(
     inference: &ScopeInference<'_>,
     aliases: &HashMap<crate::ty::QualifiedTypeName, Ty>,
     callee_expr_id: baml_compiler2_ast::ExprId,
     args: &[baml_compiler2_ast::ExprId],
     unwrap_optional_callee: bool,
     call_plan: Option<&CallPlan>,
 ) -> Option<Ty> {
-    if let Some(throws) = call_plan.and_then(|plan| plan.instantiated_throws.clone()) {
-        return Some(throws);
-    }
     let callee_ty = inference.expression_type(callee_expr_id)?;

If the top-level check is load-bearing for another call path, verify with the codebase whether any caller relies on the early return returning before callee_ty/typed_callee are computed (e.g. to avoid a panic on a missing expression type), and adjust the fix accordingly.

Also applies to: 319-325

🤖 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/baml_compiler2_tir/src/callable.rs` around lines 266 -
276, Remove or restructure the early return in instantiated_callee_throws so the
per-parameter substitution and function_throws logic can execute when needed. In
function_throws, use the call plan’s recorded instantiated throws only for
members whose substitution still contains unresolved type variables, while
preserving any necessary guard for callers that lack callee expression types.

🧹 Nitpick comments (3)

baml_language/crates/baml_project/src/db.rs (1)

1100-1123: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider a stable key format instead of {ty:?}.

cfg_expansion_key renders each dispatch binding with Debug. The cache key then depends on the Ty Debug output, which is not a stability contract. Two structurally equal types that print differently produce separate cache entries, and future Debug changes silently change key shape. If Ty implements Display or a canonical rendering, prefer that.

This affects cache hit rate only, not correctness.

🤖 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/baml_project/src/db.rs` around lines 1100 - 1123, Update
cfg_expansion_key to render dispatch binding types with Ty’s stable Display or
canonical representation instead of Debug formatting. Keep the existing binding
sorting and function identity composition unchanged, ensuring structurally equal
types produce identical cache keys across formatting changes.

baml_language/crates/baml_fmt/src/ast/expressions.rs (1)

1568-1602: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a fmtlib unit test for arm header comments.

arm_header_comments/main.baml has a generated 10_formatter snapshot, but that formatter is covered by the compiler test project. Add a baml_fmt Rust unit test that exercises headers before and between match and catch arms and rounds through format twice. Run cargo test --lib as part of this change.

🤖 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/baml_fmt/src/ast/expressions.rs` around lines 1568 -
1602, Add a baml_fmt Rust unit test covering header comments before and between
match and catch arms, using the existing arm_header_comments fixture or
equivalent input. Assert formatting is stable by running format twice and
comparing the results, and place the test with the formatter’s library tests so
it runs under cargo test --lib.

Source: Coding guidelines

baml_language/crates/sys_ops/src/lib.rs (1)

3070-3111: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add coverage for all structured media wrappers in the prompt AST test.

This test only uses a baml.media.Pdf wrapper with an Adt(Media(...)) payload. Add cases for Image, Audio, and Video, and add one missing-path case that constructs the shorthand media primitive directly without the wrapper _data payload, so regressions in the shorthand and non-Pdf paths are covered.

Run cargo test --lib for this Rust change to confirm the new test passes.

🤖 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/sys_ops/src/lib.rs` around lines 3070 - 3111, Extend
assemble_prompt_ast_preserves_pdf_as_structural_media to cover baml.media.Image,
baml.media.Audio, and baml.media.Video wrappers using Adt(Media(...)) payloads,
plus one shorthand media primitive without the wrapper _data field. Assert each
case produces the expected PromptAstSimple::Media kind and value, while
preserving the existing PDF coverage, then run cargo test --lib.

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.

Outside diff comments:
In `@baml_language/crates/baml_compiler2_tir/src/callable.rs`:
- Around line 266-276: Remove or restructure the early return in
instantiated_callee_throws so the per-parameter substitution and function_throws
logic can execute when needed. In function_throws, use the call plan’s recorded
instantiated throws only for members whose substitution still contains
unresolved type variables, while preserving any necessary guard for callers that
lack callee expression types.

---

Nitpick comments:
In `@baml_language/crates/baml_fmt/src/ast/expressions.rs`:
- Around line 1568-1602: Add a baml_fmt Rust unit test covering header comments
before and between match and catch arms, using the existing arm_header_comments
fixture or equivalent input. Assert formatting is stable by running format twice
and comparing the results, and place the test with the formatter’s library tests
so it runs under cargo test --lib.

In `@baml_language/crates/baml_project/src/db.rs`:
- Around line 1100-1123: Update cfg_expansion_key to render dispatch binding
types with Ty’s stable Display or canonical representation instead of Debug
formatting. Keep the existing binding sorting and function identity composition
unchanged, ensuring structurally equal types produce identical cache keys across
formatting changes.

In `@baml_language/crates/sys_ops/src/lib.rs`:
- Around line 3070-3111: Extend
assemble_prompt_ast_preserves_pdf_as_structural_media to cover baml.media.Image,
baml.media.Audio, and baml.media.Video wrappers using Adt(Media(...)) payloads,
plus one shorthand media primitive without the wrapper _data field. Assert each
case produces the expected PromptAstSimple::Media kind and value, while
preserving the existing PDF coverage, then run cargo test --lib.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e8bf2e0e-2aca-4620-bce8-3ccb015de828

📥 Commits

Reviewing files that changed from the base of the PR and between e26ee02 and 0f29a6c.

⛔ Files ignored due to path filters (14)

• baml_language/crates/baml_cli/src/snapshots/baml_cli__describe_command_tests__render_builtin_namespace_llm.snap is excluded by !**/*.snap
• baml_language/crates/baml_cli/src/snapshots/baml_cli__describe_command_tests__render_builtin_package_listing.snap is excluded by !**/*.snap
• baml_language/crates/baml_tests/snapshots/compiles/arm_header_comments/baml_tests__compiles__arm_header_comments__03_ppir.snap is excluded by !**/*.snap
• baml_language/crates/baml_tests/snapshots/compiles/arm_header_comments/baml_tests__compiles__arm_header_comments__04_5_mir.snap is excluded by !**/*.snap
• baml_language/crates/baml_tests/snapshots/compiles/arm_header_comments/baml_tests__compiles__arm_header_comments__04_tir.snap is excluded by !**/*.snap
• baml_language/crates/baml_tests/snapshots/compiles/arm_header_comments/baml_tests__compiles__arm_header_comments__05_diagnostics.snap is excluded by !**/*.snap
• baml_language/crates/baml_tests/snapshots/compiles/arm_header_comments/baml_tests__compiles__arm_header_comments__06_codegen.snap is excluded by !**/*.snap
• baml_language/crates/baml_tests/snapshots/compiles/arm_header_comments/baml_tests__compiles__arm_header_comments__10_formatter__main.snap is excluded by !**/*.snap
• baml_language/crates/baml_tests/snapshots/compiles/catch_interface_refinement/baml_tests__compiles__catch_interface_refinement__03_ppir.snap is excluded by !**/*.snap
• baml_language/crates/baml_tests/snapshots/compiles/catch_interface_refinement/baml_tests__compiles__catch_interface_refinement__04_5_mir.snap is excluded by !**/*.snap
• baml_language/crates/baml_tests/snapshots/compiles/catch_interface_refinement/baml_tests__compiles__catch_interface_refinement__04_tir.snap is excluded by !**/*.snap
• baml_language/crates/baml_tests/snapshots/compiles/catch_interface_refinement/baml_tests__compiles__catch_interface_refinement__05_diagnostics.snap is excluded by !**/*.snap
• baml_language/crates/baml_tests/snapshots/compiles/catch_interface_refinement/baml_tests__compiles__catch_interface_refinement__06_codegen.snap is excluded by !**/*.snap
• baml_language/crates/baml_tests/snapshots/compiles/catch_interface_refinement/baml_tests__compiles__catch_interface_refinement__10_formatter__main.snap is excluded by !**/*.snap

📒 Files selected for processing (18)

• baml_language/crates/baml_builtins2/baml_std/baml/ns_llm/llm_types.baml
• baml_language/crates/baml_builtins2/baml_std/testing/registry.baml
• baml_language/crates/baml_cli/src/format.rs
• baml_language/crates/baml_cli/src/playground_command.rs
• baml_language/crates/baml_cli/src/project_load.rs
• baml_language/crates/baml_cli/tests/exit_code_e2e.rs
• baml_language/crates/baml_compiler2_tir/src/builder.rs
• baml_language/crates/baml_compiler2_tir/src/callable.rs
• baml_language/crates/baml_compiler_parser/src/parser.rs
• baml_language/crates/baml_fmt/src/ast/expressions.rs
• baml_language/crates/baml_project/src/db.rs
• baml_language/crates/baml_tests/projects/compiles/arm_header_comments/main.baml
• baml_language/crates/baml_tests/projects/compiles/catch_interface_refinement/main.baml
• baml_language/crates/baml_tests/src/compiler2_tir/phase8_exceptions.rs
• baml_language/crates/bex_engine/src/trace_value_encode.rs
• baml_language/crates/bex_engine/src/value_capture.rs
• baml_language/crates/bex_engine/tests/log_intrinsic.rs
• baml_language/crates/sys_ops/src/lib.rs