M3.5: pending outcomes for commands that wait for the language server

Step 1 of M3.5: the shared mechanism. M3.4 and M3.5 build on it.

- Engine: `Outcome.pending: Option<Pending>`. `Pending::new(rx, timeout,
  finish)`; `Pending::wait()` is called without the engine lock and
  returns at the answer, a dropped sender or the deadline (timeout + 1 s).
  `Engine::resolve(answered)` then runs `finish(state, reply)` inside the
  guard, under the lock. `run_waiting(lock, cmd, params, publish)` does
  all three steps for hosts.
- Hosts: `Host::run`, `testkit::EngineBackend` and the control test
  backend use `run_waiting`.
- New IPC `engine_execute_waiting` (`#[tauri::command(async)]`, off the
  main thread) with `runWaiting()` in `ui/src/ipc.ts`. Only `lsp.*`
  requests use it.

Ordering guarantee:
- `engine_execute` stays synchronous on the main thread, so ordinary
  commands (`buffer.edit`) still run in call order.
- The order towards the server is fixed under the engine lock:
  `buffer.edit` queues its didChange on the session's FIFO queue before
  it returns, and `lsp::submit` queues the request on the same queue.
  A request therefore sees every edit whose `buffer.edit` returned
  first, and the UI awaits the sync's `idle()` before sending one.

Failures:
- A stall is caught by the request timeout, with the deadline as
  backstop.
- On restart, close, quit or crash the request is dropped or resolved
  as stopped, so the waiter gets an error, never a hang.

Tests: `crates/engine/tests/pending.rs` (answer, lock free while
waiting, dropped sender, deadline, resolve, lsp.restart while a
request is pending) and Vitest for `runWaiting`. Gate: 13 steps,
321 s, Vitest 443 + 1 skipped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-22 06:36:20 +02:00
parent a674040797
commit 20d1d28c32
11 changed files with 603 additions and 18 deletions

View file

@ -402,6 +402,26 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- `crates/control/tests/lsp.rs` runs over TCP with ticks on.
- Vitest: `ui/tests/editor/lint.test.ts` and `ui/tests/problems/ProblemsToolWindow.test.ts`.
### Pending outcomes: commands that wait for the language server (M3.5)
- **Why:** `lsp.definition` returns `{locations}`, `lsp.completion` returns items. The answer comes from Phpactor, and nothing may wait for it under the engine lock (M3.3).
- **API** (`crates/engine/src/command.rs`, `engine.rs`):
- A command queues its request with `lsp::submit(state, |server| server.request_with(…, callback))`; the callback sends into an `mpsc` channel.
- The command returns `Outcome::pending(Pending::new(receiver, timeout, finish))` at once.
- The host calls `Pending::wait()` *without* the lock. It returns when the answer arrives, the sender is dropped or the deadline passes (timeout + 1 s of grace; the request's own timeout should be shorter, so it reports first).
- Then, with the lock again, `Engine::resolve(answered)` runs `finish(state, reply)` in the guard. `reply` is `Some(Ok(value))`, `Some(Err(LspError))` or `None` (no answer). The finish builds the value and may change the state; a rename applies its edit here.
- `lutra_engine::run_waiting(lock, command, params, publish)` does all three steps for a host. Events of each step are published while the lock is held. Effects come from the first step.
- **Hosts:** `Host::run` (desktop), `testkit::EngineBackend` and the control protocol's test backend use `run_waiting`. Control-channel and MCP callers (one thread per connection) get the final value directly.
- **IPC and ordering:**
- `engine_execute` stays a synchronous Tauri command on the main thread, so every ordinary command (`buffer.edit` above all) runs in call order, as before.
- The new `engine_execute_waiting` (`#[tauri::command(async)]`, `runWaiting` in `ui/src/ipc.ts`) runs `Host::run` off the main thread, so the window stays responsive while Phpactor works. Only `lsp.*` requests use it.
- `engine_execute` itself did not move off the main thread, unlike the first plan: moving it would let two ordinary commands race for the lock, and the order of `buffer.edit` calls must stay the call order.
- The order towards Phpactor is fixed under the engine lock: `buffer.edit` queues its `didChange` on the session queue (`lsp::record_edits`) before it returns, and `submit` queues the request on the same FIFO queue. A request therefore sees every edit whose `buffer.edit` returned before it, and the frontend awaits the buffer sync's `idle()` before sending one.
- **Failures:**
- Phpactor stalls: the request times out in `lutra-lsp`; the waiter's deadline is the backstop.
- `lsp.restart`, project close, `app.quit` (`shutdown_now`) or a crash: queued jobs are dropped and in-flight requests resolve with `Stopped`/`ServerCrashed`, so the waiter gets an error at once instead of hanging (test: `crates/engine/tests/pending.rs`).
- A finish must check that its answer still applies to the state; `lsp.rename` refuses when a buffer's version changed since the request.
### Toolchain (M3.1)
- **Owner decision D15:** Lutra downloads the Phpactor PHAR itself; PHP is the user's (found through `php.executable` or `PATH`). Library code lives in `crates/lsp/src/toolchain/` (L3), the engine side in `crates/engine/src/cmd/toolchain.rs`.
@ -444,6 +464,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
| Date | Change | Summary |
|---|---|---|
| 2026-10-22 | minor | M3.5 step 1: pending outcomes (`Pending`, `Engine::resolve`, `run_waiting`), `engine_execute_waiting` / `runWaiting` |
| 2026-10-20 | minor | M3.10: autosave (blur, tab switch, idle), `flushDirty`, `file.saveAll {skipConflicts}`, disk conflicts and own-write hashes in `Buffers` |
| 2026-10-21 | minor | M3.3: engine ↔ Phpactor wiring (session thread, ordered sync, `lspStatus`, `diagnosticsChanged`, `diagnostics.list`, `lsp.status`, `lsp.restart`), Phpactor-on-Windows workarounds, lint extension, Problems tab |
| 2026-10-19 | minor | M3.8: MCP server (`lutra mcp`, dual era 2026-07-28 + legacy `initialize`), tools, resources, event buffer; `buffer.list` |