@@ -18,6 +18,7 @@ mod code_action;
 mod code_lens;
 mod completion;
 mod data_flow;
+mod detached_transpile;
 mod diagnostic;
 mod doc_highlights;
 mod document_symbols;
 
@@ -0,0 +1,52 @@
+//! Running a transpile from a request handler.
+//!
+//! The transpiler builds databases of its own — a single-file one holding the source
+//! it is lowering, and the project rebuilt over that source when a pre-pass rewrote
+//! it. Reading a salsa field attaches the database it belongs to, and attaching a
+//! second one while a first is attached is a panic: "Cannot change database
+//! mid-query". Every request handler runs inside `salsa::attach(&db, …)`, so every
+//! one of those reads is a panic here.
+//!
+//! Attachment is per thread, so a thread that has attached nothing is a thread the
+//! nested build is legal on — which is the state the `by` command line runs in, and
+//! why none of this reproduces there. That is also why it went unnoticed: the tests
+//! that cover these same operations call the library directly.
+//!
+//! This is a workaround and worth naming as one. The nesting belongs to the
+//! transpiler, not to any request, so the fix that would remove this is for a
+//! type-aware pass to be handed a database rather than construct one. Until then
+//! every caller that already holds one attached has to arrange not to be — the same
+//! reason `by_stage::emit`'s transpile loop cannot be parallelised.
+
+use std::panic::AssertUnwindSafe;
+
+use ruff_db::panic::catch_unwind;
+
+/// Run `op` on a thread that has attached no database.
+///
+/// `Err` when it panicked, which the caller reports rather than propagates: a client
+/// has one shape to read, and a request that got no answer at all leaves whatever it
+/// was about to do with the result in an unknown state.
+///
+/// The panic is caught *inside* the thread rather than read off its join handle. The
+/// hook that captures a panic rather than printing it is armed per thread, so one
+/// caught only by the join would still have printed a raw backtrace to the server's
+/// log on the way out. Caught here it is logged the way the rest of the server logs
+/// a panicking handler, and the caller is told only that there is nothing to return.
+pub(super) fn transpile_detached<R: Send>(op: impl FnOnce() -> R + Send) -> Result<R, ()> {
+    let caught =
+        std::thread::scope(|scope| scope.spawn(|| catch_unwind(AssertUnwindSafe(op))).join());
+    match caught {
+        Ok(Ok(value)) => Ok(value),
+        Ok(Err(panic)) => {
+            tracing::error!("the transpiler panicked: {panic}");
+            Err(())
+        }
+        // the thread unwound past the catch, which leaves nothing to report but the
+        // same answer: there is no result
+        Err(_) => {
+            tracing::error!("the transpiler's thread failed");
+            Err(())
+        }
+    }
+}
@@ -16,6 +16,7 @@ use by_transforms::Config;
 use lsp_types::{LspRequestMethod, MessageDirection, Request, TextDocumentIdentifier, Uri};
 use ty_project::{Db as _, ProjectDatabase};
 
+use super::detached_transpile::transpile_detached;
 use crate::server::api::traits::{
     BackgroundDocumentRequestHandler, RequestHandler, RetriableRequestHandler,
 };
@@ -116,20 +117,33 @@ impl BackgroundDocumentRequestHandler for TranspileRequestHandler {
         // document that was asked about — that is the reason for answering here, since cross-module
         // types resolve — and the single-file path for a fragment, which has no module to resolve
         // against however it is transpiled.
+        // Both forward paths run on a thread that has attached no database — see
+        // [`super::detached_transpile`]. Every forward transpile builds a database of its
+        // own, and doing that under this handler's attached one panics; the reverse
+        // direction is purely syntactic and needs no database at all, so it stays here.
+        let owned = db.dyn_clone();
         let response = if params.reverse {
             match by_transforms::reverse_transpile(source, &config) {
                 Ok(out) => TranspileResponse::generated(out),
                 Err(error) => TranspileResponse::failed(error),
             }
-        } else if params.source.is_some() {
-            match by_transforms::transpile(source, &config) {
-                Ok(out) => TranspileResponse::generated(out),
-                Err(error) => TranspileResponse::failed(error),
-            }
         } else {
-            match by_transforms::transpile_typed(db, file, &config, None) {
-                Ok(out) => TranspileResponse::generated(out),
-                Err(error) => TranspileResponse::failed(error.to_string()),
+            let fragment = params.source.is_some();
+            let transpiled = transpile_detached(move || {
+                if fragment {
+                    by_transforms::transpile(source, &config)
+                } else {
+                    by_transforms::transpile_typed(&*owned, file, &config, None)
+                        .map_err(|error| error.to_string())
+                }
+            });
+            match transpiled {
+                Ok(Ok(out)) => TranspileResponse::generated(out),
+                Ok(Err(error)) => TranspileResponse::failed(error),
+                // A panic is an answer here for the same reason a failure is: source that
+                // does not lower is an ordinary state for a file being edited, and a client
+                // renders an error response as a fault in the server.
+                Err(()) => TranspileResponse::failed("the transpiler panicked".to_owned()),
             }
         };
 
 
@@ -32,6 +32,8 @@
 use std::borrow::Cow;
 
 use by_stage::restage::{Restage, restage_one};
+
+use super::detached_transpile::transpile_detached;
 use lsp_types::{LspRequestMethod, MessageDirection, Request, TextDocumentIdentifier, Uri};
 use ty_project::ProjectDatabase;
 
@@ -107,38 +109,24 @@ impl BackgroundDocumentRequestHandler for TranspileForBuildRequestHandler {
             return Ok(None);
         };
 
-        // **On a thread of its own, and that is not an optimisation.** Every request handler runs
-        // inside `salsa::attach(&db, ...)`, and the transpiler builds a *second* database when a
-        // pre-pass rewrites the source it is about to lower — so it can resolve the file's imports
-        // against the real project with the rewritten text overlaid. Attaching that one while this
-        // one is attached is "Cannot change database mid-query", which salsa panics on, and a
-        // panicking handler is what the user sees as "ty encountered a problem".
-        //
-        // Attachment is per thread, so a thread that has attached nothing is a thread the nested
-        // build is legal on — which is exactly the state the `by` command line runs this in, and
-        // why it works there. Scoped so the borrow of `db` is the same one this function has.
-        // A clone rather than a borrow, because a salsa database is not `Sync`: it is cheap to
-        // clone and a clone is how every one of this server's worker threads already holds one.
+        // On a thread of its own, and that is not an optimisation — see
+        // [`super::detached_transpile`] for why a transpile cannot run on a thread that
+        // already has a database attached. A clone rather than a borrow, because a salsa
+        // database is not `Sync`: it is cheap to clone and a clone is how every one of this
+        // server's worker threads already holds one.
         let owned = db.clone();
-        let directory = params.build_directory.clone();
+        let directory = params.build_directory;
         let file = path.as_std_path().to_path_buf();
-        let restaged = std::thread::scope(|scope| {
-            scope
-                .spawn(move || restage_one(&owned, &directory, &file))
-                .join()
-        });
-
-        let restaged = match restaged {
-            Ok(restaged) => restaged,
-            // The transpile panicked rather than failed. Reported as a refusal for the reason an
-            // error is: a client has one shape to read, and a debugger that got no answer at all
-            // would leave the tree it is about to write into in an unknown state.
-            Err(_) => {
-                return Ok(Some(Restage::Refused(by_stage::restage::Refusal {
-                    refused: "the transpiler panicked while re-staging this file".to_owned(),
-                    diagnostics: Vec::new(),
-                })));
-            }
+        let restaged = transpile_detached(move || restage_one(&owned, &directory, &file));
+
+        // A panic rather than a failure is reported as a refusal for the reason an error is:
+        // a client has one shape to read, and a debugger that got no answer at all would
+        // leave the tree it is about to write into in an unknown state.
+        let Ok(restaged) = restaged else {
+            return Ok(Some(Restage::Refused(by_stage::restage::Refusal {
+                refused: "the transpiler panicked while re-staging this file".to_owned(),
+                diagnostics: Vec::new(),
+            })));
         };
 
         match restaged {
 
@@ -46,6 +46,7 @@ mod pull_diagnostics;
 mod rename;
 mod semantic_tokens;
 mod signature_help;
+mod transpile;
 mod type_hierarchy;
 mod will_rename_files;
 mod workspace_folders;
 
@@ -0,0 +1,122 @@
+//! The `by/transpile` and `by/transpileForBuild` requests, exercised through the
+//! server rather than through the library they call.
+//!
+//! That distinction is the whole reason these exist. The transpiler builds a
+//! database of its own whenever it lowers rewritten source, and a request handler
+//! runs with the project database already attached — so the nested one is a second
+//! attachment on the same thread, which salsa refuses with "Cannot change database
+//! mid-query". Nothing about it reproduces from the command line, where nothing is
+//! attached, and the `crates/ty` tests that cover the same operations therefore
+//! passed throughout. Only a request does it.
+
+use anyhow::Result;
+use lsp_types::{LspRequestMethod, MessageDirection, Request, TextDocumentIdentifier, Uri};
+use ruff_db::system::SystemPath;
+
+use crate::TestServerBuilder;
+
+#[derive(Debug, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+struct TranspileParams {
+    text_document: TextDocumentIdentifier,
+    #[serde(skip_serializing_if = "std::ops::Not::not")]
+    reverse: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    source: Option<String>,
+}
+
+#[derive(Debug, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+struct TranspileResponse {
+    #[serde(default)]
+    source: Option<String>,
+    #[serde(default)]
+    error: Option<String>,
+}
+
+enum Transpile {}
+
+impl Request for Transpile {
+    type Params = TranspileParams;
+    type Result = Option<TranspileResponse>;
+    const METHOD: LspRequestMethod<'static> = LspRequestMethod::Custom("by/transpile");
+    const MESSAGE_DIRECTION: MessageDirection = MessageDirection::ClientToServer;
+}
+
+fn params(uri: &Uri, source: Option<&str>) -> TranspileParams {
+    TranspileParams {
+        text_document: TextDocumentIdentifier { uri: uri.clone() },
+        reverse: false,
+        source: source.map(str::to_owned),
+    }
+}
+
+/// The fragment path: `source` is supplied, so the whole transpile runs over text
+/// rather than the project, and it builds an in-memory database to check that text
+/// against. That database is queried while the project's is attached.
+#[test]
+fn transpiling_a_fragment_answers_rather_than_panicking() -> Result<()> {
+    let workspace_root = SystemPath::new("src");
+    let main = SystemPath::new("src/main.by");
+    let content = "def f(a: int?) -> int:\n    return a ?? 0\n";
+
+    let mut server = TestServerBuilder::new()?
+        .with_workspace(workspace_root, None)?
+        .with_file(main, content)?
+        .build()
+        .wait_until_workspaces_are_initialized();
+
+    server.open_text_document(main, content, 1);
+    let uri = server.file_uri(main);
+
+    let response = server
+        .send_request_await::<Transpile>(params(&uri, Some(content)))
+        .expect("the server answered nothing at all");
+
+    assert!(
+        response.error.is_none(),
+        "transpile failed: {:?}",
+        response.error
+    );
+    let generated = response.source.expect("no generated source");
+    assert!(
+        generated.contains("def f("),
+        "unexpected output:\n{generated}"
+    );
+    Ok(())
+}
+
+/// The whole-document path, which goes through the project database — and then
+/// still builds one of its own, because a pre-pass rewrote the source it lowers.
+/// `enum class` is such a pre-pass.
+#[test]
+fn transpiling_a_document_answers_rather_than_panicking() -> Result<()> {
+    let workspace_root = SystemPath::new("src");
+    let main = SystemPath::new("src/main.by");
+    let content = "enum class Colour:\n    case Red\n    case Green\n\nlet chosen: Colour = Red\n";
+
+    let mut server = TestServerBuilder::new()?
+        .with_workspace(workspace_root, None)?
+        .with_file(main, content)?
+        .build()
+        .wait_until_workspaces_are_initialized();
+
+    server.open_text_document(main, content, 1);
+    let uri = server.file_uri(main);
+
+    let response = server
+        .send_request_await::<Transpile>(params(&uri, None))
+        .expect("the server answered nothing at all");
+
+    assert!(
+        response.error.is_none(),
+        "transpile failed: {:?}",
+        response.error
+    );
+    let generated = response.source.expect("no generated source");
+    assert!(
+        generated.contains("Colour"),
+        "unexpected output:\n{generated}"
+    );
+    Ok(())
+}