refactor(lsp): Phase 0 latency and mutex containment

CONTRIBUTING.md

@@ -17,3 +17,21 @@ Please remember that BAML is maintained by humans and is used in production
 for a wide range of critical use cases. We expect our contributors to be
 thoughtful about their work and engage with us, either in our Discord or on
 the issue or pull request.
+
+# Getting Started
+
+See [README-DEV.md](./README-DEV.md) for environment setup (via
+[mise](https://mise.jdx.dev/) and `./scripts/setup-dev.sh`), the development
+workflow, and how to run tests. In short:
+
+```bash
+curl https://mise.run | sh   # install mise
+./scripts/setup-dev.sh       # install Rust and everything else
+```
+
+Rust changes go in the `baml_language/` workspace — run `cargo test --lib`
+there before submitting, and format with:
+
+```bash
+cargo fmt -- --config imports_granularity="Crate" --config group_imports="StdExternalCrate"
+```

README-DEV.md

@@ -164,6 +164,30 @@ cd integ-tests/python && uv run pytest
 cd integ-tests/ruby && rake test
 ```
 
+### Rust Workspace (`baml_language/`)
+
+The compiler, engine, and LSP server live in the `baml_language/` Cargo
+workspace. Common commands (run from `baml_language/`):
+
+```bash
+# Unit tests for the whole workspace (always run these after Rust changes)
+cargo test --lib
+
+# Unit tests for one crate
+cargo test --lib -p bex_project
+
+# Format with the repo's import style (fixes most lints)
+cargo fmt -- --config imports_granularity="Crate" --config group_imports="StdExternalCrate"
+
+# The LSP/runtime crates must also compile for the browser playground
+cargo check --target wasm32-unknown-unknown -p bridge_wasm
+```
+
+Start with `baml_language/ARCHITECTURE.md` for the compiler pipeline and
+`baml_language/TEST_INSTRUCTIONS.md` for the snapshot-test workflow. Design
+documents for larger subsystems (e.g. the LSP server's locking and rebuild
+pipeline) live in `docs/design/`.
+
 ### Building
 
 ```bash

baml_language/TEST_INSTRUCTIONS.md

@@ -5,17 +5,17 @@
 | Suite | Location | Purpose |
 |-------|----------|---------|
 | `baml_tests` | `crates/baml_tests/` | Snapshot tests with detailed CST/HIR/THIR output |
-| `lsp_actions_tests` | `crates/lsp_actions_tests/` | LSP integration tests with inline expectations |
+| `baml_lsp2_actions_tests` | `crates/baml_lsp2_actions_tests/` | LSP integration tests with inline expectations |
 
 ## Workflow: Debugging a Failing Test
 
-### 1. Identify the issue in lsp_actions_tests
+### 1. Identify the issue in baml_lsp2_actions_tests
 
 ```bash
-cargo test --package lsp_actions_tests
+cargo test --package baml_lsp2_actions_tests
 ```
 
-Look for errors in `crates/lsp_actions_tests/test_files/syntax/`.
+Look for errors in `crates/baml_lsp2_actions_tests/test_files/syntax/`.
 
 ### 2. Create a minimal repro in baml_tests
 
@@ -64,16 +64,16 @@ Edit the relevant crate (`baml_compiler_parser`, `baml_compiler_syntax`, `baml_c
 cargo test --package baml_tests my_repro
 cargo insta accept --all
 
-# Update lsp_actions_tests inline expectations
-UPDATE_EXPECT=1 cargo test --package lsp_actions_tests
+# Update baml_lsp2_actions_tests inline expectations
+UPDATE_EXPECT=1 cargo test --package baml_lsp2_actions_tests
 ```
 
 ### 7. Verify all tests pass
 
 ```bash
 # Run all tests (can skip slow parser_stress with --skip parser_stress)
 cargo test --package baml_tests -- --skip parser_stress
-cargo test --package lsp_actions_tests
+cargo test --package baml_lsp2_actions_tests
 ```
 
 ## Quick Commands
@@ -89,7 +89,7 @@ cargo test --package baml_tests
 cargo test --package baml_tests -- --skip parser_stress
 
 # Run LSP tests and auto-update expectations
-UPDATE_EXPECT=1 cargo test --package lsp_actions_tests
+UPDATE_EXPECT=1 cargo test --package baml_lsp2_actions_tests
 
 # Accept all pending snapshots
 cargo insta accept --all
@@ -108,7 +108,7 @@ cargo insta review
 - **Type checking**: `crates/baml_compiler2_tir/src/builder.rs`
 
 
-DO NOT EDIT the diagnostics manually in lsp_actions_tests. Use update_expect=1
+DO NOT EDIT the diagnostics manually in baml_lsp2_actions_tests. Use update_expect=1
 
 Find the base-case that makes syntax fail and add that to baml_test with a good name and good folder organization.
 

baml_language/crates/baml_cli/src/paint.rs

@@ -487,7 +487,7 @@ impl<'db> Highlighter<'db> {
         if let Some(cached) = self.cache.borrow().get(&file) {
             return Rc::clone(cached);
         }
-        let mut toks = semantic_tokens(self.db, file);
+        let mut toks = semantic_tokens(self.db, file).clone();
         toks.sort_by_key(|t| t.range.start());
         let rc: Rc<[SemanticToken]> = toks.into();
         self.cache.borrow_mut().insert(file, Rc::clone(&rc));

baml_language/crates/baml_lsp2_actions/src/annotations.rs

@@ -1,7 +1,7 @@
 //! Inline type / parameter-name annotations for BAML files (inlay hints).
 //!
-//! Provides `annotations(db, file) -> Vec<InlineAnnotation>` — a regular
-//! function (not a Salsa query) that walks expression-body functions in a file
+//! Provides `file_annotations(db, file) -> &Vec<InlineAnnotation>` — a Salsa
+//! tracked query that walks expression-body functions in a file
 //! (top-level functions, class/interface methods, and the synthesized
 //! `$init_test` registration functions), recursing into lambda bodies (e.g.
 //! the bodies of `test` / `testset` blocks, which lower to lambdas passed to
@@ -81,7 +81,7 @@ pub enum AnnotationKind {
 }
 
 /// A single inline annotation (inlay hint) to display in the editor.
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, PartialEq, Eq, salsa::Update)]
 pub struct InlineAnnotation {
     /// Byte offset in the file where the hint is inserted.
     pub offset: TextSize,
@@ -102,10 +102,16 @@ pub struct InlineAnnotation {
 /// Returns annotations sorted in document order (required by the LSP
 /// `textDocument/inlayHint` contract).
 ///
-/// Regular function (not a Salsa query). Internally calls Salsa-cached
-/// queries (`function_body`, `function_body_source_map`,
-/// `infer_scope_types`, `file_item_tree`, `file_semantic_index`).
-pub fn annotations(db: &dyn Db, file: SourceFile) -> Vec<InlineAnnotation> {
+/// Salsa tracked query (design B1): walks every function body against type
+/// inference (measured 40–150ms on real projects), which is too slow to
+/// recompute per request while the file is unchanged. Editors re-request
+/// inlay hints on every scroll, so this is the hottest read path.
+///
+/// Named `file_annotations` (like `file_outline`) because the tracked-query
+/// machinery claims the bare name in the type namespace, which would collide
+/// with this module.
+#[salsa::tracked(returns(ref))]
+pub fn file_annotations(db: &dyn Db, file: SourceFile) -> Vec<InlineAnnotation> {
     let item_tree = baml_compiler2_hir::file_item_tree(db, file);
     let index = baml_compiler2_hir::file_semantic_index(db, file);
 
@@ -433,7 +439,7 @@ function UseEcho() -> string {
         );
         let project = builder.build();
 
-        let hints = annotations(&project.db, project.files[0]);
+        let hints = file_annotations(&project.db, project.files[0]);
         let labels: Vec<_> = hints.iter().map(|hint| hint.label.as_str()).collect();
 
         assert!(
@@ -473,7 +479,7 @@ function Demo(items: int[]) -> string {
 "##,
         );
         let project = builder.build();
-        let hints = annotations(&project.db, project.files[0]);
+        let hints = file_annotations(&project.db, project.files[0]);
 
         // The synthesized `.push(...)` calls must not surface `value:`-style hints.
         assert!(
@@ -510,7 +516,7 @@ function Greet(name: string, items: int[]) -> string {
         );
         let project = builder.build();
 
-        let hints = annotations(&project.db, project.files[0]);
+        let hints = file_annotations(&project.db, project.files[0]);
         let labels: Vec<_> = hints.iter().map(|hint| hint.label.as_str()).collect();
 
         // `${expr}` lowers to `string.from(expr)`; that synthetic wrapper call
@@ -547,7 +553,7 @@ test "greets" {
         );
         let project = builder.build();
 
-        let hints = annotations(&project.db, project.files[0]);
+        let hints = file_annotations(&project.db, project.files[0]);
         let labels: Vec<_> = hints.iter().map(|hint| hint.label.as_str()).collect();
 
         assert!(
@@ -582,7 +588,7 @@ class Greeter {
         );
         let project = builder.build();
 
-        let hints = annotations(&project.db, project.files[0]);
+        let hints = file_annotations(&project.db, project.files[0]);
         let labels: Vec<_> = hints.iter().map(|hint| hint.label.as_str()).collect();
 
         assert!(
@@ -613,7 +619,7 @@ testset "math" {
         );
         let project = builder.build();
 
-        let hints = annotations(&project.db, project.files[0]);
+        let hints = file_annotations(&project.db, project.files[0]);
         let labels: Vec<_> = hints.iter().map(|hint| hint.label.as_str()).collect();
 
         assert!(
@@ -647,7 +653,7 @@ function Later() -> string {
         builder.source("main.baml", source);
         let project = builder.build();
 
-        let hints = annotations(&project.db, project.files[0]);
+        let hints = file_annotations(&project.db, project.files[0]);
         let y_offset = TextSize::from(
             u32::try_from(source.find("\"y\"").expect("test arg")).expect("offset fits"),
         );

baml_language/crates/baml_lsp2_actions/src/lib.rs

@@ -88,7 +88,7 @@ pub trait Db: baml_compiler2_tir::Db {}
 // ── Public API re-exports ─────────────────────────────────────────────────────
 
 pub use actions::{FileAction, FileActionKind, file_actions};
-pub use annotations::{AnnotationKind, InlineAnnotation, annotations};
+pub use annotations::{AnnotationKind, InlineAnnotation, file_annotations};
 // Re-export `DefinitionKind` so callers (e.g. bex_project) don't need to
 // depend on `baml_compiler2_hir` directly just for type conversions.
 pub use baml_compiler2_hir::contributions::DefinitionKind;

baml_language/crates/baml_lsp2_actions/src/tokens.rs

@@ -139,7 +139,7 @@ impl SemanticTokenType {
 // ── SemanticToken ─────────────────────────────────────────────────────────────
 
 /// A classified token ready for LSP encoding.
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, PartialEq, Eq, salsa::Update)]
 pub struct SemanticToken {
     pub range: TextRange,
     pub token_type: SemanticTokenType,
@@ -152,9 +152,12 @@ pub struct SemanticToken {
 /// Always returns tokens in document order (required by the LSP
 /// `textDocument/semanticTokens/full` contract).
 ///
-/// Regular function (not a Salsa query). Internally calls Salsa-cached queries
-/// (`infer_scope_types`, `function_body`, `function_body_source_map`,
-/// `file_semantic_index`, `syntax_tree`).
+/// Salsa tracked query (design B1): the CST walk re-classifies every token
+/// against type inference, which measured 40–150ms on real projects — too
+/// slow to recompute per request while the file is unchanged. Memoization
+/// keys off the file revision; edits to *other* files reuse this file's
+/// result if its inference inputs are unaffected.
+#[salsa::tracked(returns(ref))]
 pub fn semantic_tokens(db: &dyn Db, file: SourceFile) -> Vec<SemanticToken> {
     let root = baml_compiler_parser::syntax_tree(db, file);
     let mut out = Vec::new();

baml_language/crates/baml_lsp2_actions_tests/src/runner.rs

@@ -4,7 +4,7 @@ use std::{collections::HashMap, path::Path};
 
 use baml_compiler_diagnostics::{RenderConfig, render_diagnostic};
 use baml_lsp2_actions::{
-    annotations::{AnnotationKind, InlineAnnotation, annotations},
+    annotations::{AnnotationKind, InlineAnnotation, file_annotations},
     check::check_file,
     completions::completions_at,
     tokens::{SemanticToken, semantic_tokens},
@@ -165,9 +165,9 @@ pub fn run_test(parsed: &ParsedTestFile) -> TestResult {
     let actual_inlay_hints = if parsed.expected_inlay_hints.is_some() {
         let mut all_hints: Vec<(String, InlineAnnotation)> = Vec::new();
         for (filename, source_file) in &file_map {
-            let hints = annotations(&db, *source_file);
+            let hints = file_annotations(&db, *source_file);
             for hint in hints {
-                all_hints.push((filename.clone(), hint));
+                all_hints.push((filename.clone(), hint.clone()));
             }
         }
 
@@ -184,7 +184,7 @@ pub fn run_test(parsed: &ParsedTestFile) -> TestResult {
         for (filename, source_file) in &file_map {
             let tokens = semantic_tokens(&db, *source_file);
             for token in tokens {
-                all_tokens.push((filename.clone(), token));
+                all_tokens.push((filename.clone(), token.clone()));
             }
         }