[rossirpaulo]

Summary

• Remove the implementation-only LSP latency/mutex design document added by fix(lsp): resolve the 0.14 mutex/latency regression — Phase 0 containment + Phase 1 bounded ingress #4000.
• Rewrite code comments to describe their concurrency, publication, cancellation, and position-encoding invariants directly.
• Rename the remaining document-coded test name so the implementation no longer depends on phase, decision, or invariant labels from the deleted document.

Why

The design document served as an implementation plan for #4000. Keeping it after the implementation merged makes the repository carry a stale roadmap, while references such as I1, D8, B2, and Phase 0C leave code comments dependent on that external numbering scheme. The updated comments preserve the durable behavior and constraints locally.

Validation

• cargo fmt --all -- --check
• cargo clippy via commit hooks
• cargo test -p baml_lsp_server -p bex_project -p baml_lsp2_actions (235 passed, 1 ignored)
• pnpm --filter @b/pkg-playground typecheck
• pnpm --filter @b/pkg-playground test -- run-gating.test.ts (125 passed)

Summary by CodeRabbit

• Documentation
  • Clarified and simplified language-server documentation covering tokenization, diagnostics, cancellation, concurrency behavior, lifecycle/shutdown semantics, and playground run-gating.
  • Updated comment wording to remove outdated internal design references.
  • Removed an obsolete LSP latency/mutex design document.
• Tests
  • Renamed a test for clearer Protocol error-code mapping intent (assertions and behavior unchanged).

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 67568664-12fc-4ee2-9051-a398eee7d7f5

📥 Commits

Reviewing files that changed from the base of the PR and between 3f7f444 and 24e1382.

📒 Files selected for processing (3)

• baml_language/crates/baml_lsp2_actions/src/tokens.rs
• baml_language/crates/bex_project/src/bex_lsp/multi_project/mod.rs
• baml_language/crates/bex_project/src/bex_lsp/multi_project/request.rs

🚧 Files skipped from review as they are similar to previous changes (3)

• baml_language/crates/baml_lsp2_actions/src/tokens.rs
• baml_language/crates/bex_project/src/bex_lsp/multi_project/request.rs
• baml_language/crates/bex_project/src/bex_lsp/multi_project/mod.rs

---

📝 Walkthrough

Walkthrough

Documentation comments and one test name were revised across LSP, multi-project orchestration, project concurrency, and playground code. Obsolete design labels were removed and existing behavior descriptions were clarified without modifying executable logic, APIs, data structures, or test assertions.

Changes

LSP transport and runtime documentation

Layer / File(s)	Summary
LSP transport and runtime documentation baml_language/crates/baml_lsp2_actions/src/*, baml_language/crates/baml_lsp_server/src/*	Comments describing Salsa queries, bounded transport, lifecycle handling, ingress gating, runtime sessions, and playground WebSocket behavior were reworded; one protocol error test was renamed without changing assertions.

LSP contract and request documentation

Layer / File(s)	Summary
LSP contract and request documentation baml_language/crates/bex_project/src/bex_lsp/{mod.rs,notification.rs,request.rs,position_codec.rs,request_cancellation.rs}, baml_language/crates/bex_project/src/bex_lsp/multi_project/request.rs	Documentation for error mapping, snapshots, session behavior, position encoding, cancellation, notifications, request handling, and semantic-token encoding was clarified without changing interfaces or implementations.

Multi-project pipeline documentation

Layer / File(s)	Summary
Multi-project pipeline documentation baml_language/crates/bex_project/src/bex_lsp/multi_project/{mod.rs,diagnostics.rs}	Comments covering refresh, diagnostics, rebuilds, cancellation, fencing, retries, test collection, and session behavior were updated without changing control flow.

Project concurrency documentation

Layer / File(s)	Summary
Project concurrency documentation baml_language/crates/bex_project/src/project.rs	Concurrency, revision, candidate, lease, run, publication, and test lifecycle comments were rewritten while preserving code behavior and data layouts.

Playground documentation cleanup

Layer / File(s)	Summary
Playground documentation cleanup typescript2/pkg-playground/src/{ExecutionPanel.tsx,run-gating.ts}	Comments describing fail-closed rebuild and run gating were updated without runtime changes.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• BoundaryML/baml#4000: Both PRs touch the Salsa tracked queries in baml_lsp2_actions; this PR updates only their surrounding documentation comments.

Poem

A rabbit hops through comments bright,
Erasing labels out of sight.
No code was changed, no bugs took flight,
Just clearer words in morning light.
Hop, hop—docs now feel just right!

🚥 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 accurately summarizes the main change: removing obsolete LSP design doc references and related commentary.
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 paulo/cleanup-lsp-design-doc-comments

---

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
beps	Ready	Preview, Comment	Jul 14, 2026 8:03am
promptfiddle	Ready	Preview, Comment	Jul 14, 2026 8:03am
promptfiddle2	Ready	Preview, Comment	Jul 14, 2026 8:03am

[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	🔒 22.1 MB	9.4 MB	file	21.5 MB	+553.6 KB (+2.6%)	OK
✅	packed-program	Linux	🔒 15.8 MB	6.7 MB	file	15.6 MB	+209.2 KB (+1.3%)	OK
✅	baml-cli	macOS	🔒 17.0 MB	8.2 MB	file	16.6 MB	+416.0 KB (+2.5%)	OK
✅	packed-program	macOS	🔒 12.2 MB	5.9 MB	file	12.1 MB	+117.3 KB (+1.0%)	OK
✅	baml-cli	Windows	🔒 18.5 MB	8.4 MB	file	18.1 MB	+428.0 KB (+2.4%)	OK
✅	packed-program	Windows	🔒 13.1 MB	6.0 MB	file	13.0 MB	+104.8 KB (+0.8%)	OK
✅	bridge_wasm	WASM	14.6 MB	🔒 4.1 MB	gzip	4.1 MB	+79.4 KB (+2.0%)	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]

🧹 Nitpick comments (1)

baml_language/crates/bex_project/src/bex_lsp/mod.rs (1)

111-112: 📐 Maintainability & Code Quality | 🔵 Trivial

Run cargo test --lib from baml_language/.

🤖 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/bex_project/src/bex_lsp/mod.rs` around lines 111 - 112,
Run the Rust library test suite with cargo test --lib from the baml_language
directory and address any failures related to the LSP error-code mapping
documentation or implementation near the single mapping table. Ensure the tests
pass without changing the documented behavior that UnknownErrorCode is never
emitted.

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.

Nitpick comments:
In `@baml_language/crates/bex_project/src/bex_lsp/mod.rs`:
- Around line 111-112: Run the Rust library test suite with cargo test --lib
from the baml_language directory and address any failures related to the LSP
error-code mapping documentation or implementation near the single mapping
table. Ensure the tests pass without changing the documented behavior that
UnknownErrorCode is never emitted.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 5fb7b797-6439-4016-b33b-bee2ef2e06ca

📥 Commits

Reviewing files that changed from the base of the PR and between 77f7efd and 3f7f444.

📒 Files selected for processing (19)

• baml_language/crates/baml_lsp2_actions/src/annotations.rs
• baml_language/crates/baml_lsp2_actions/src/tokens.rs
• baml_language/crates/baml_lsp_server/src/lib.rs
• baml_language/crates/baml_lsp_server/src/lsp_ingress.rs
• baml_language/crates/baml_lsp_server/src/lsp_runtime.rs
• baml_language/crates/baml_lsp_server/src/native_lsp_sender.rs
• baml_language/crates/baml_lsp_server/src/playground_server.rs
• baml_language/crates/bex_project/src/bex_lsp/mod.rs
• baml_language/crates/bex_project/src/bex_lsp/multi_project/diagnostics.rs
• baml_language/crates/bex_project/src/bex_lsp/multi_project/mod.rs
• baml_language/crates/bex_project/src/bex_lsp/multi_project/notification.rs
• baml_language/crates/bex_project/src/bex_lsp/multi_project/request.rs
• baml_language/crates/bex_project/src/bex_lsp/position_codec.rs
• baml_language/crates/bex_project/src/bex_lsp/request.rs
• baml_language/crates/bex_project/src/bex_lsp/request_cancellation.rs
• baml_language/crates/bex_project/src/project.rs
• docs/design/lsp-latency-and-mutex-fix.md
• typescript2/pkg-playground/src/ExecutionPanel.tsx
• typescript2/pkg-playground/src/run-gating.ts

💤 Files with no reviewable changes (1)

• docs/design/lsp-latency-and-mutex-fix.md