[antoniosarosi]

BEP-034 — concurrency via spawn / await. Single PR covering the spawn-options core and the future combinators (supersedes #3596).

Public BAML API (BEP-034 concurrency)

This is the complete user-facing surface this PR adds. Everything below is callable from .baml source.

Syntax

spawn { body }                       // -> Future<T, E>; runs body concurrently
await f                              // -> T; blocks until f settles, re-throws its error
spawn with t1 with t2 { body }       // middleware: applies transformers left-to-right

• spawn { e } evaluates to Future<T, E> where T is the body's value type and E its throws type. The body starts running immediately; the future is the handle.
• await f suspends until f settles, then yields its value or re-throws its error. await distributes over a union of futures: await (Future<A,E1> | Future<B,E2>) yields A | B (the error side is contributed to the awaiter's throws surface).
• spawn ... with <transformer> ... runs each transformer over an implicit SpawnParams before the runtime creates the future (see middleware below).

baml.future — futures & combinators

class Future<T, E> {
  fn cancel(self) -> bool throws never        // request cancel; false if already settled
  fn is_settled(self) -> bool throws never     // reached Ready | Error | Cancelled
  fn is_cancelled(self) -> bool throws never
  fn is_result(self) -> bool throws never      // settled with a value
  fn is_error(self) -> bool throws never        // settled with an error
  fn state(self) -> FutureState throws never
}

enum FutureState { Pending  Ready  Error  Cancelled }

// Combinators over a homogeneous Future<T,E>[] — each returns a new Future, so they compose.
fn all_complete<T, E>(futures: Future<T, E>[]) -> Future<T[], E>
//   all values in input order; losers KEEP RUNNING on failure; throws first error (input order)
fn all<T, E>(futures: Future<T, E>[]) -> Future<T[], E>
//   all values in input order; on first failure the rest are CANCELLED, then error re-thrown (JS Promise.all)
fn race<T, E>(futures: Future<T, E>[]) -> Future<T, E>
//   first to settle (success OR failure) wins; losers cancelled (JS Promise.race); empty array never settles
fn any<T, Err>(futures: Future<T, Err>[]) -> Future<T, AllFailed<Err>>
//   first to SUCCEED wins; losers cancelled; if all fail, throws AllFailed<Err> (JS Promise.any)

class AllFailed<E> { errors E[] }   // thrown by `any` when every input failed; errors in input order

baml.spawn — spawn options & with middleware

// Every `spawn` implicitly builds a SpawnParams; the `with` pipeline transforms it.
// A transformer is any function (SpawnParams<T,E>) -> SpawnParams<U,F>.
class SpawnParams<T, E> {
  body   () -> T throws E
  name   string?
  group  TaskGroup?
  cancel CancelToken?
  detach bool
}

// The built-in config transformer. `cancel` links a token; `detach = true` opts out of the
// parent→child cancel cascade and routes unhandled errors to the root task; `group` enrolls
// the spawn in a TaskGroup (parks FIFO until admitted). Leaves `body`/types unchanged.
fn options<T, E>(group: TaskGroup? = null, cancel: CancelToken? = null, detach: bool? = null)
  -> (SpawnParams<T, E>) -> SpawnParams<T, E> throws never

class TaskGroup {                                  // caps concurrency; excess spawns queue FIFO
  fn new(limit: int, name: string? = null) -> TaskGroup throws never
  fn cancel(self, pending: bool? = true, active: bool? = true) -> int throws never  // returns # signalled
  fn set_limit(self, limit: int) -> void throws never   // raise admits queued; lower never preempts; 0 pauses
  fn limit(self) -> int throws never
  fn name(self) -> string? throws never
  fn active_count(self) -> int throws never
  fn queued_count(self) -> int throws never
}

class CancelToken {                                // cooperative, one-shot; fires at next await
  fn new() -> CancelToken throws never
  fn any(tokens: CancelToken[]) -> CancelToken throws never   // fires when ANY input fires (one-directional)
  fn cancel(self) -> int throws never              // 1 if this call transitioned it, else 0
  fn is_cancelled(self) -> bool throws never
}

A cancelled task throws baml.panics.Cancelled at its next await.

Writing your own middleware

A transformer is just a function returning (SpawnParams<T,E>) -> SpawnParams<U,F>. It can set config
fields, wrap body (retry/timing), or replace it entirely (a type-changing transformer — e.g. a
fallback that catches and erases the error type to null):

function withFallback<T, E>(default_value: T) -> (SpawnParams<T, E>) -> SpawnParams<T, null> throws never {
  (params) -> {
    let original = params.body;
    SpawnParams {
      body: () -> { (original()) catch (e) { let e => default_value } },
      name: params.name, group: params.group, cancel: params.cancel, detach: params.detach,
    }
  }
}

// usage — `f : Future<int, null>`, so awaiting needs no catch:
let f = spawn with withFallback(99) { flaky() };

Transformers run eagerly at the spawn site, so a throwing transformer throws there (and is part of
the caller's throws surface). Wrong-shaped transformers are rejected at compile time with a concrete
"must return a SpawnParams" diagnostic.

Spawn options

• spawn ... with baml.spawn.options(group?, cancel?, detach?) — config-only with clause
• CancelToken (new / any / cancel / is_cancelled) + parent→child cancel cascade
• TaskGroup rate limiting (FIFO admission, exact counts)
• detach (fresh cancel token; unhandled errors routed to the root task)
• strict with validation (must be a baml.spawn.SpawnConfig)

Future combinators (baml.future)

• race / any / all / all_complete — pure-BAML stdlib over a new 1-byte AwaitAny engine primitive (__await_any: Future<T,E>[] -> int throws never, suspends until the first input settles)
• AllFailed<E> aggregate error class for any
• losers cancelled (race/any/all) or left running (all_complete) per the BEP table

Engine/runtime fixes found along the way

• fire-and-forget errors (bug 2): a child's unhandled throw is now deferred (GC-rooted stash; future stays Pending with its wake signal fired) and consumed at the single observation point (future_ready, now &mut). The spawner's post-await drain surfaces only never-observed errors — a sibling handling a child's error no longer races the spawner into a spurious UnhandledThrow. (tests/fire_and_forget.rs)
• AwaitAny index desync (bug 3): global-index bookkeeping fix that broke any
• bare-bind catch arms (bug 4): let e => in a generic fn emitted a constant-false IsType (TypeVar→Void erasure) and silently rethrew; bare binds are irrefutable — no runtime test
• copy propagation substitutes Terminator::Await operands (await <param> inside .map closures)
• unannotated lambda params infer from generic array elements mentioning only the enclosing fn's rigid generics

Generics: inferred type args at runtime

• TIR records call-site inferred bindings (call_type_instantiations); MIR threads them to frame.type_args (LoadType/TypeArgRef) — instances built inside generic fns carry real class_type_args, and typed arms like let e: AllFailed<string> match (tests/generics_runtime.rs)
• typed arms naming enclosing TypeVars (let e: AllFailed<E>) lower via type-arg templates instead of erasing

Canary merge (f5df38a)

Absorbs the spawn/GC permit deadlock fix (full baml_tests now completes on this branch), BEP-044/BEP-57, instantiation expressions, bounds, and interface-dispatch type-arg threading. Canary's strict rigid-var checking exposed pre-existing inference gaps, fixed here:

• await f contributes the future's E to escaping throws
• callee generics matched only against rigid caller TypeVars now bind (map's U:=T)
• lambda effective throws feed callee throws-generics — lifts the documented "current limitation" (covered callback throws no longer false-positive) and violations name concrete types
• miscompile fix: ShortCircuit emit assumed a stack-carried (PhiLike) destination; with LoadType before call args the carry is validly rejected, so a || b as an inferred-generic call argument read an uninitialized local. Emit now materializes the destination on the short-circuit edge (no-op for PhiLike).
• std any<T, E> → any<T, Err> (works around generic-param name capture vs map<U, E>; proper fix tracked separately)

with middleware (c37027a)

Full BEP middleware: spawn ... with a, b { body } builds a SpawnParams<T,E> and applies each transformer left-to-right — any plain BAML function (SpawnParams<T,E>) -> SpawnParams<U,F> (wrap/replace body, set config, change types). baml.spawn.options is now a pure-BAML transformer (native SpawnConfig deleted). Flushed out + fixed three language gaps: keyword segments in type paths, lambdas as block tail expressions, and unannotated lambdas now INFER their throws surface from the body (two tests asserting the old throws-never default updated). Tests: bex_engine/tests/middleware.rs incl. the BEP's withRetry.

Complete bug ledger (every bug found & fixed on this branch)

Engine / runtime

1. Fire-and-forget errors bypassed consumers — a spawned child's unhandled throw settled its Future eagerly AND queued on the spawner; a sibling that awaited + handled the error was invisible to the engine, so the spawner re-surfaced an already-handled error as UnhandledThrow. Fixed with the deferred-error model: the error parks in a GC-rooted stash, the future stays Pending (wake signal fired), future_ready is the single observe-and-consume point, and the spawner's post-await drain surfaces only never-observed errors.
2. AwaitAny index desync — global-index bookkeeping desync broke any (wrong winner index reported).
3. Copy propagation didn't substitute Terminator::Await operands — await <param> inside a .map closure read an uninitialized slot.
4. ShortCircuit emit miscompile — the emitter assumed the destination is always stack-carried (PhiLike); when inferred-generic calls push LoadType before args the carry is validly rejected, so a || b as a call argument left the value on the stack and read an uninitialized local (true || false evaluated false). Emit now materializes the destination on the short-circuit edge; MIR normalizes projection destinations. Latent before the canary merge — the suite deadlocked before reaching the || fixtures.

Type system / generics
5. Bare-bind catch arms in generic fns always rethrew — let e => emitted an IsType from its inferred type; a rigid TypeVar erases to Ty::Void in MIR making the test constant-false. Bare binds are irrefutable — no runtime test emitted (also drops tautological field tests in destructures).
6. Inferred call-site type args were discarded — TIR ran inference, substituted the return type, and threw the bindings away; MIR emitted frame type args only for explicit <...> call sites. Instances built inside generic fns carried empty class_type_args; typed arms like let e: AllFailed<string> never matched. Bindings now recorded (call_type_instantiations) and threaded to frame.type_args.
7. Typed arms naming enclosing TypeVars compiled to constant-false — let e: AllFailed<E> inside any<T, E> erased E→Void; now lowers via TypeArgRef templates resolved against the frame.
8. Recorded instantiations poisoned by fresh literal types — mk("hi") recorded T = Literal("hi") so is Box<string> compared unequal; recordings now widen_fresh(). Plus generic→generic chains recorded Unknown (TypeVar actuals refused); fixed with an allow-typevars backfill.
9. Unannotated lambda params didn't infer from generic array elements whose type only mentions the enclosing fn's rigid generics.

Throws tracking (pre-existing gaps exposed by canary's strict rigid-var checking)
10. await f contributed nothing to escaping throws — the future's E is now part of the awaiting body's throw set.
11. Callee generics matched only against rigid caller TypeVars never bound — map's U:=T in futures.map((f) -> { await f }) was skipped as a TypeVar actual, leaving U[] in result types.
12. Rigid TypeVar throw-facts collapsed lambda surfaces to Never — only genuinely open facts (fresh effect slots, Unknown) collapse now.
13. Callee throws-generics fed from lambda SURFACE instead of effective throws — an omitted-throws lambda's open surface left map's E unbound (leaking a raw TypeVar) or symbolic where the body demonstrably throws. Now fed from the side-table effective set: a non-throwing callback binds E:=never, a throwing one binds its concrete type. Lifts a documented "current limitation": a callback throw covered by the caller's declared throws no longer false-positives, and violations name concrete types instead of symbolic E.

Parser / lowering (flushed out by the middleware work)
14. spawn/await keywords rejected as path segments in type annotations (baml.spawn.SpawnParams) — parser type-path loop + CST dotted-name extractor.
15. A lambda as a block's tail expression was silently dropped from block elements — the block typed as void ("missing return value"); any function returning a transformer hit it (the std's json code had been dodging it with explicit return).
16. Unannotated lambdas defaulted to throws never with a local violation — they now infer their throws surface from the body (required for body wraps like () -> { original() } whose throws is a generic E). Omitted throws on callback params remains effect-polymorphic; explicit throws contracts remain enforced (verified: E0096 fires through the forwarding chain — an enforcement that itself depends on fixes 10–13).

Known issues (documented, not fixed here)

• Generic-param name capture: a callee's generic (map<U, E>) sharing a name with a caller's generic false-binds through the receiver-substituted signature. Worked around (any<T, E> → any<T, Err>); proper fix is alpha-renaming on receiver substitution.
• await does not yet distribute over unions of futures (BEP §await-distributes).

await over unions (94d2b46)

Awaiting Future<A, E1> | Future<B, E2> types as A | B with both error types tracked (BEP §await-distributes). Tests: bex_engine/tests/await_union.rs.

Review hardening (94d2b46)

CodeRabbit batch: any errors in INPUT order (+test) · explicit lambda throws contracts preserved · with-transformer throws contributed at spawn · copy-prop protects await xs[_i] · TaskGroup.set_limit(+N) admits up to the cap (+test) · deferred-error hygiene on cancel/fulfill · VM Spawn config validation · unified/completed generics walkers. Plus the CI fix: Object enum exceeded its 64-byte budget under heap_debug (UnscheduledFuture boxed) — the cause of the all-legs CI failure.

Canary merge round 4 (8b2c403)

Canary's c957417e7 ([codex] #3702) was a third independent implementation of inferred-generic runtime type args; this merge converges on it and fixes what the convergence broke:

1. Adopted canary's CallPlan pipeline for inferred type args — removed our parallel call_type_instantiations TIR→MIR fallback (dead code after the switch). Canary's ShortCircuit emit fix (store_on_taken_path) is the same insight as ours; took theirs.
2. runtime_call_type_args lost literal widening — canary's recording threads T = literal "hi" for mk("hi"), so an escaped instance never matches is Box<string> (runtime class-arg comparison is invariant). Restored widen_fresh on inferred bindings.
3. Canary's stricter call-result recheck false-positived on unknown holes — spawn with middleware checks transformers against (SpawnParams<T,E>) -> SpawnParams<unknown, unknown>; the normalizer implements class-arg invariance as structural equality, so the holes (and BuiltinUnknown from erased unresolved typevars, e.g. a variable-bound transformer; and equivalent spellings like T = int | 99 from fallback-arg joins) all failed E0001. is_subtype now compares same-class args pairwise: holes match anything, concrete args must be mutual subtypes (invariance as equivalence). Concrete mismatches — including canary's new iterator-stdlib diagnostics — still report.
4. heap_debug feature gap — FutureRead::ErrorPending arm added to the heap debugger's validity walk.
5. task_group_cancel_cancels_members timing — the promptness bound times run_main including compilation; the stdlib grew (ns_iter). 2s → 5s, still far under the 10s sleep it guards.

Closes the deferred interface-dispatch inferred-type-args item (canary's #3702 ships it with runtime regressions).

Verified: cargo test --workspace --all-features — 185 suites / 0 failures (sdk_test_* excluded as in CI; they require cargo-nextest setup scripts) + prek clean, rustc 1.93.0.

Deferred (follow-up branch)

• Result<T, E> type design + all_settled, .then()
• cancellation-test panic-hook hygiene

Tests: bex_engine 227/0 (incl. combinators, fire_and_forget, generics_runtime, cancellation, task_group); baml_tests diagnostics 418/418, runtime fixtures 1650/1650 (one timing-sensitive fixture flakes only under full parallel suite load); snapshots regenerated.

Summary by CodeRabbit

• New Features
  • spawn ... with middleware and options(...) for spawn configuration; CancelToken and TaskGroup APIs; future combinators all_complete, all, race, any; await-any (returns winning input index)
• Tests
  • Comprehensive BEP-034 tests for spawn options, TaskGroup, CancelToken, combinators, middleware, fire-and-forget, and runtime behavior
• Bug Fixes
  • Improved child-task error propagation and deferred fire-and-forget error semantics across await/catch boundaries

[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

📝 Walkthrough

Walkthrough

This PR implements BEP-034 concurrency model across the compiler and runtime. It adds spawn middleware configuration (SpawnParams, TaskGroup, CancelToken), future combinators (all_complete, all, race, any), an AwaitAny suspend primitive, deferred child error routing, FIFO-based rate limiting, and comprehensive engine/VM support for concurrent task execution and cancellation.

Changes

BEP-034 async concurrency model

Layer / File(s)	Summary
Future combinators and spawn middleware contracts baml_std/baml/ns_future/future.baml, baml_std/baml/ns_spawn/spawn.baml, baml_builtins2/src/lib.rs	Introduces all_complete, all, race, any, and __await_any helpers; defines SpawnParams<T, E>, TaskGroup, CancelToken, and options middleware; registers spawn builtin.
Parser and syntax support baml_compiler_parser/src/parser.rs, baml_compiler_syntax/src/ast.rs, baml_compiler2_ast/src/lower_expr_body.rs	Extends parser to accept spawn name? with expr (, expr)* { body } syntax; allows spawn/await as path segments; updates lower_expr_body to parse and lower with_exprs list.
AST representation and lowering baml_compiler2_ast/src/ast.rs, baml_compiler2_ast/src/lower_cst.rs, baml_compiler2_hir/src/builder.rs	Adds Expr::Spawn { with_exprs } field and BuiltinKind::AwaitAny variant; lowers $await_any token; updates HIR traversal to walk with_exprs.
TIR type inference and generics baml_compiler2_tir/src/builder.rs, baml_compiler2_tir/src/inference.rs, baml_compiler2_tir/src/generics.rs, baml_compiler2_tir/src/infer_context.rs	Implements spawn middleware folding by type-checking transformers; tracks per-call generic instantiations for MIR; adds contains_non_rigid_typevar and erase_typevars_where utilities; infers concrete lambda throws from body; adds SpawnWithNotATransformer error.
MIR IR, builder, and lowering baml_compiler2_mir/src/ir.rs, baml_compiler2_mir/src/builder.rs, baml_compiler2_mir/src/lower.rs	Introduces Terminator::AwaitAny { futures, destination, target, unwind }; extends Terminator::Spawn with optional config; implements middleware application and __await_any builtin dispatch; fixes short-circuit destination handling.
MIR optimization and verification baml_compiler2_mir/src/optimize.rs, baml_compiler2_emit/src/analysis.rs	Extends optimizer to rewrite and substitute through AwaitAny; updates def-use analysis, dead-block elimination, copy-propagation; extends verification for config/futures operands.
Bytecode emission and VM interpreter baml_compiler2_emit/src/emit.rs, baml_compiler2_emit/src/stack_carry.rs, baml_compiler2_emit/src/lib.rs, bex_vm_types/src/bytecode.rs, bex_vm/src/vm.rs	Extends Spawn emission to pop/push config operand; emits AwaitAny instruction; implements AwaitAny opcode to scan futures array, yield on pending, resume with winning index; updates stack carry simulation.
Engine spawn dispatch and AwaitAny execution bex_engine/src/lib.rs	Implements read_spawn_params to decode middleware options by field index; applies cancel/group/detach overrides; links user tokens and registers task-group membership; implements VmExecState::AwaitAny to race multiple futures and resume with index.
Fire-and-forget deferred errors and thread routing bex_engine/src/future.rs, bex_engine/src/thread.rs	Adds defer_error and take_deferred_error for child error deferral; makes future_ready the unified settlement point; extends BexThread with root error queue arc for detached spawn error propagation.
TaskGroup rate-limiting and CancelToken primitives bex_vm_types/src/task_group.rs, bex_vm/src/package_baml/spawn.rs	Implements FIFO-queued admission with concurrency cap, dynamic limit updates, and cancellation; implements CancelToken with composition; provides native trait implementations for both primitives.
GC rooting and value representation bex_heap/src/gc.rs, bex_vm_types/src/types.rs, bex_vm/src/package_baml/root.rs	Extends UnscheduledFuture with config field; updates GC tracing and fixup for config references; adds SpawnConfigData struct; introduces Value::is_omitted predicate.
Tests: combinators, options, and fire-and-forget bex_engine/tests/combinators.rs, bex_engine/tests/cancellation.rs, bex_engine/tests/middleware.rs, bex_engine/tests/fire_and_forget.rs, baml_src/ns_cancel_token/cancel_token.baml, baml_src/ns_task_group/task_group.baml	Tests all four combinators with concurrency and error semantics; tests spawn options middleware (identity, wrapping, chained, retry); tests CancelToken composition and cancellation-on-option; tests fire-and-forget error propagation with multiple scenarios.
Tests: task group, generics, and regression bex_engine/tests/task_group.rs, bex_engine/tests/generics_runtime.rs, bex_engine/tests/fn_typed_slots.rs, bex_engine/tests/tail_lambda.rs	Tests TaskGroup admission limits, FIFO queueing, limit updates, and wall-clock concurrency timing; tests runtime reified-generics threading in catch arms; tests lambda typing and catch arm enforcement; regression tests for tail lambdas in block position.
TIR test and debug updates baml_tests/src/compiler2_tir/phase6.rs, baml_tests/src/compiler2_tir/phase8_exceptions.rs, bex_vm/src/debug.rs, bex_vm/src/package_baml/mod.rs, tools_onionskin/src/compiler.rs	Updates phase-6 tests to expect stored lambdas infer concrete throws from body; updates phase-8 tests to reflect inferred-throws propagation with concrete type names; extends debug styling for AwaitAny; updates onionskin to handle AwaitAny yield state.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• BoundaryML/baml#3520: Main PR is directly related to #3520 because it extends the same baml_std/baml/ns_future/future.baml module introduced there (adds combinators like all_complete/all/race/any, AllFailed, and __await_any on top of the earlier FutureState + Future<T,E> foundation).

"A rabbit spawns a thousand tiny threads,
racing and waiting with careful heads,
it cancels, groups, and collects each fall—
then wakes the winner to answer the call. 🐰"

✨ 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 antoniosarosi/Future-Combinators

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
beps	Ready	Preview, Comment	Jun 8, 2026 5:05pm
new-boundaryml-website	Error		Jun 8, 2026 5:05pm
promptfiddle	Ready	Preview, Comment	Jun 8, 2026 5:05pm
promptfiddle2	Ready	Preview, Comment	Jun 8, 2026 5:05pm

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

No description provided.

[antoniosarosi]

@coderabbitai Review disposition for the latest push (94d2b46):

Fixed (9): any input-order errors (+ regression test) · explicit lambda throws surfaces preserved in callee_throws_arg_ty · spawn with transformer throws contributed at the spawn site · forward-ref check no longer descends into the deferred spawn body · spawn/await segments in generic-arg lookahead · contains_non_rigid_typevar unified over contains_typevar_where · erase_typevars_where completed (Interface/projection/Evolving/Function-shadowing) · deferred fire-and-forget errors cleared on cancel/fulfill transitions · VM validates the Spawn config operand is an Instance · copy-prop protects await xs[_i] index locals · TaskGroup::promote admits up to the new cap (+ regression test).

False positive (1): AwaitAny empty-waiters park — future_ready returns immediately-ready waiters for settled inputs, so empty waiters ⟺ empty input array, and BEP-034 specifies race([]) never settles (matching JS Promise.race([])). Comment expanded to document this.

Deferred (2, tracked): interface-dispatch inferred type args (emit_method_candidate_switch) and the cancellation-test panic-hook hygiene.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@antoniosarosi Thanks for the detailed disposition — this is very helpful for tracking review status.

Acknowledged:

• All 9 fixes noted and recorded.
• False positive clarified — the AwaitAny empty-waiters park is intentional: future_ready returns immediately-ready waiters for already-settled futures, so an empty-waiters set implies an empty input array, and BEP-034 specifies race([]) / any([]) never settles (matching Promise.race([])). Recording this to avoid re-flagging.
• Deferred (tracked): emit_method_candidate_switch interface-dispatch inferred type args and cancellation-test panic-hook hygiene — noted for follow-up.

---

✏️ Learnings added

Learnt from: antoniosarosi
URL: https://github.com/BoundaryML/baml/pull/3625

Timestamp: 2026-06-05T16:29:24.459Z
Learning: In `baml_language/crates/bex_engine/src/lib.rs` (PR `#3625`, BEP-034), the `AwaitAny` opcode parking with zero waiters when the input array is empty is intentional and correct. `future_ready` returns immediately-ready waiters for any already-settled futures, so an empty-waiters set is equivalent to an empty input array. BEP-034 specifies that `race([])` and `any([])` never settle, matching the `Promise.race([])` / `Promise.any([])` semantics in JavaScript. Do not re-flag this as a hang or missing edge-case in reviews of PR `#3625`.

---

Learnt from: antoniosarosi
URL: https://github.com/BoundaryML/baml/pull/3625

Timestamp: 2026-06-05T16:29:24.459Z
Learning: In `baml_language/crates/baml_compiler2_emit/src/emit.rs` and related MIR lowering (PR `#3625`, BEP-034), the interface-dispatch inferred type arguments path (`emit_method_candidate_switch`) does not yet record per-call type instantiations for interface method dispatch. This is a known, tracked gap deferred to a follow-up PR. Do not re-flag this in reviews of PR `#3625`.

---

Learnt from: antoniosarosi
URL: https://github.com/BoundaryML/baml/pull/3625

Timestamp: 2026-06-05T16:29:24.459Z
Learning: In `baml_language/crates/bex_engine/tests/cancellation.rs` (PR `#3625`), the cancellation test suite uses `catch_unwind` without a custom panic hook, meaning test failure messages may include panic-hook output that pollutes test logs. Panic-hook hygiene (e.g., setting a no-op hook around `catch_unwind` calls) is tracked as a follow-up improvement. Do not re-flag this in reviews of PR `#3625`.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

---

🧠 Learnings used

Learnt from: hellovai
Repo: BoundaryML/baml PR: 3369
File: baml_language/crates/baml_tests/src/compiler2_tir/phase6.rs:781-791
Timestamp: 2026-04-16T18:11:44.267Z
Learning: In `baml_language/crates/baml_tests/src/compiler2_tir/phase6.rs` (PR `#3369`), the snapshot `direct_optional_push_establishes_element_type` accepts `_[]`/`expected never` instead of `int[]` because the optional-inner-callee path (`xs?.push?.(1)`) bypasses `try_container_method_call` and does not feed evolving-list inference. This is a known gap caused by a `-X ours` merge of PR `#3374` (both sides had ~700-line changes to builder.rs), so the optional-call container-method integration is not fully wired. The fix is deferred to a follow-up PR. Do not re-flag this snapshot regression in reviews of PR `#3369`.

---

Learnt from: hellovai
Repo: BoundaryML/baml PR: 3369
File: baml_language/crates/baml_lsp2_actions_tests/test_files/syntax/expr/watch_when.baml:48-74
Timestamp: 2026-04-16T16:05:24.083Z
Learning: In `baml_language/crates/baml_lsp2_actions_tests/test_files/syntax/expr/watch_when.baml` (PR `#3369`), the diagnostic spans for "type `int` has no member `$watch`" errors intentionally cover a wider range than the exact `$watch` token — they extend to include the preceding `watch let x = 10;` statement. This is a known span regression introduced when multi-segment Path expressions replaced nested FieldAccess nodes. A comment in the file documents the issue and links to PR `#3369` discussion r3088162711. The upstream member/path span fix is deferred to a follow-up PR. Do not re-flag this span width issue in reviews of PR `#3369`.

---

Learnt from: hellovai
Repo: BoundaryML/baml PR: 3302
File: baml_language/crates/bex_engine/src/lib.rs:1113-1115
Timestamp: 2026-03-30T07:42:52.442Z
Learning: In `baml_language/crates/bex_engine/src/lib.rs`, the parked-VM GC loop in `collect_garbage()` is missing a call to `vm.apply_frame_forwarding(&forwarding)` after `vm.watch.apply_forwarding(&forwarding)`. The active-VM path in `maybe_run_gc()` (around line 1143) already has this call. This is a latent bug: it cannot trigger today because parked VMs only exist during concurrent async calls, and lambda bodies do not contain `await` yet, so no closure frame can be live across a parking point. The fix is tracked for a followup PR. Do not flag this again in reviews of PR `#3302`.

---

Learnt from: hellovai
Repo: BoundaryML/baml PR: 0
File: :0-0
Timestamp: 2026-06-03T21:21:45.704Z
Learning: In `baml_language/crates/baml_compiler2_mir/src/lower.rs` (PR `#3667`), two associated-types findings are pre-existing from BEP-57 (`#3652`, commit c14f14d9) and are intentionally out of scope for this PR and any PR scoped only to generic type-arg dispatch threading:
1. The `assoc.default` lowering around lines 959–967 uses the caller's `pkg_items` — this is a pre-existing limitation in associated-type resolution, not introduced by this PR.
2. `interface_tir_assoc_match` (~lines 7712–7729) is stricter than the type-arg matcher — also a pre-existing divergence in associated-type matching.
Do not re-flag either of these in reviews that do not explicitly touch associated-type resolution.

---

Learnt from: hellovai
Repo: BoundaryML/baml PR: 3302
File: baml_language/crates/baml_compiler2_hir/src/builder.rs:321-407
Timestamp: 2026-03-30T06:53:01.610Z
Learning: In `baml_language/crates/baml_compiler2_hir/src/builder.rs`, Pass 5 (lambda scopes) runs after Pass 3 (match arm scopes) and Pass 4 (catch arm/clause scopes) have already been popped. This means a lambda nested inside a match arm or catch arm gets its HIR scope parented to the enclosing function/let scope instead of the arm scope. As a result, the capture ancestor walk in the lambda scope never visits the arm scope, so pattern-bound variables (e.g., `Foo(v)` in a match arm) are invisible to lambdas defined in that arm. The fix is to process lambda scopes inline during the match/catch arm passes (while the arm scope is still on the stack). This is a known bug tracked for a followup PR; do not flag it again during reviews of PR `#3302`.

---

Learnt from: rossirpaulo
Repo: BoundaryML/baml PR: 3383
File: baml_language/crates/baml_compiler2_tir/src/builder.rs:1181-1206
Timestamp: 2026-04-20T23:19:07.163Z
Learning: BoundaryML/baml preference (PR `#3383` and forward): Do not infer lambda throws from the body. In checking mode, when a lambda is typed against an expected function type (e.g., callback position), use the contextual expected throws if the lambda omits a throws annotation. Validation of explicit lambda throws against the body can be added by calling `check_throws_contract` while the lambda scope is active (inside `infer_lambda_body`).

---

Learnt from: hellovai
Repo: BoundaryML/baml PR: 3302
File: baml_language/crates/baml_compiler2_tir/src/builder.rs:828-890
Timestamp: 2026-03-30T07:43:05.070Z
Learning: In `baml_language/crates/baml_compiler2_tir/src/builder.rs` (PR `#3302`), the `Expr::Lambda` check-mode branch (around line 890) uses `self.generic_params` directly when lowering parameter type annotations, without merging in `func_def.generic_params` (lambda-local generics). This means `<T>(x: T) -> T { x }` in check mode would lower `T` to `Unknown`. The fix (merging `func_def.generic_params` into a local `all_generic_params` as synthesis mode does at line 413) is intentionally deferred because generic lambdas in check mode are unusual — the expected function type cannot express a bound typevar like `T`, so no realistic call-site exercises this path. Fix if real usage emerges.

---

Learnt from: 2kai2kai2
Repo: BoundaryML/baml PR: 3324
File: baml_language/crates/baml_builtins2/baml_std/baml/uint8array.baml:38-60
Timestamp: 2026-04-03T21:52:16.230Z
Learning: In `baml_language/crates/baml_builtins2/baml_std/baml/uint8array.baml`, the `zeroes` function intentionally lacks a `throws root.errors.InvalidArgument` declaration even though the Rust implementation (`baml_language/crates/bex_vm/src/package_baml/uint8array.rs`) can return a `VmError` for negative sizes. This mismatch is a known, accepted gap deferred until a better error-handling system for builtin functions is implemented. Do not re-flag the missing `throws` on `zeroes` in future reviews.

Done