ADFA-5405: Let templates reference each other (#1779)

* ADFA-5405: Add a Pebble loader that reads the Templates table

Pebble's StringLoader treats the name it is handed as the template body, so a
cross-reference resolves to itself: {% include "nav.peb" %} renders the literal
text "nav.peb", with no exception and no log line. That caps the web server at
one self-contained template per page.

This loader resolves a name against Templates.name instead, so extends, include,
import and embed all work. A name with no row throws LoaderException naming it.

Not wired up yet -- the next commit switches the engine over to it.

* ADFA-5405: Load templates by name, so they can reference each other

The engine now loads through DatabaseTemplateLoader instead of StringLoader, so
an author can build a page out of several Templates rows -- a layout to extend,
a nav partial to include -- instead of one self-contained file.

Content rows still name their outermost template by id, so render() resolves the
id to a name and lets the engine load and cache from there. That drops our own
compiled-template map: the engine already caches by name, which is the better
key anyway, since a partial shared by many pages is then compiled once. Both
caches are dropped on a database swap, the engine's included -- it caches by
name, so a template edited under the same name would otherwise survive one.

A reference to a name with no row now fails the request. It used to render the
name as text.

* ADFA-5405: Render the bookshelf by name, dropping its id cache

Templates resolve by name now, so the bookshelf endpoint no longer has to look
its id up and hold on to it: renderNamedTemplate takes the name straight.

That removes the whole cache-coherency mechanism the cached id needed -- the
volatile field, its lock, the generation it was tagged with, and the pre-serve
refresh that existed only to make the generation check land on the right side of
a swap. Nothing outside the content source caches per database any more, and the
source applies a pending swap inside lookup()/withDatabase() itself.

isCursorOneRow went with it; the id lookup was its only caller.

* ADFA-5405: Name the unresolvable template in the /pr/bs error

handleBsEndpoint replaced the caught exception's message with generic text, so a
bookshelf template the loader cannot resolve -- the row itself, or anything it
references -- 500ed with nothing to identify it. The name is the whole point of
failing loudly.

The generic text stays as the fallback for an exception with no message.

Found in review of #1779.

* ADFA-5405: Handle a reference cycle, and clean up the render diagnostics

Review follow-ups on #1779.

A cycle between two templates is reachable now that a reference resolves to
another row, and Pebble has no cycle detection: it recurses until the stack
ends. StackOverflowError is an Error, so every catch on the serving path passes
it through and the client gets a closed socket with no status line. Raised as an
IllegalStateException naming the template instead. The listener already survived
this (the accept loop catches Throwable), so this is about the response.

PebbleException formats getMessage() as "<text> (<file>:<line>)" and the loader
throws with both null, so /pr/bs was answering "... not found in the database
(?:?)". Translated to getPebbleMessage() in the content source, which also keeps
Pebble out of both transports.

clearTemplateCache() left the tag cache populated, so a template's {% cache %}
blocks would outlive the database swap the rest of the method exists to handle.

Dropped renderTemplate(): the id-keyed entry point had one caller, which the
previous commit moved to renderNamedTemplate, and no test uses it. Said plainly
in the KDoc that generation and refreshDatabase have no production reader.

The regression test from the previous commit asserted the body contained
"bookshelf", which the generic fallback text does too -- it passed with or
without the fix. It now asserts the loader's own sentence, and fails without it.

* ADFA-5405: Correct the stale swap comment on serveRequest

The call it described, discardCachesIfDatabaseChanged(), was deleted two commits
ago. The swap is applied by lookup()/withDatabase() inside the content source
now, so a request reaching neither does not poll for one -- the opposite of what
the comment led a reader to expect.

* ADFA-5405: Keep a parse error's file and line, and bound a runaway render

Second review pass on #1779.

The getPebbleMessage() change in 6e6d865 traded one diagnostic loss for
another: it strips PebbleException's "(<file>:<line>)" suffix from every
exception, not just the loader's null/null ones, so a syntax error in a template
said what was wrong but not which template or line. Now conditional on the
exception actually carrying neither. The new test fails without it with
'Unexpected token "EXECUTE_END"' and no template name.

maxRenderedSize bounds output that grows without end -- a runaway loop stays at
one frame, so the StackOverflowError guard never sees it and OutOfMemoryError is
an Error every catch on this path misses. Pebble raises a PebbleException at the
limit instead. Not covered by a test: exercising it means rendering 16M chars.

clearTemplateCache() now takes the write lock. The sentinel and the interceptor
call it with no lock, so clearing three caches piecemeal under a concurrent
render could hand it a template from before the clear and a tag-cache miss from
after -- the mixed state the sentinel is pressed to escape.

resourceExists() no longer copies the whole template blob into a CursorWindow to
answer a boolean, and generation/refreshDatabase() are marked @VisibleForTesting
rather than described as unused in prose.

The Templates DDL is now in documentation-database.md. Two reviews read the bare
column list there and concluded name has no UNIQUE constraint; it does -- SQLite
resolves the single-quoted UNIQUE('name') to the column.

* ADFA-5405: Address the review, and close the leak one layer deeper

All three findings hold. The first one is not fully fixed by what it
suggested, which is the interesting part.

The echoed message is narrowed, and there was a second site. The
suggestion was to give render failures a distinct type and echo only
those; TemplateRenderException does that, extending IllegalStateException
so callers that only care the render failed are unaffected. But narrowing
handleBsEndpoint's catch does not stop the leak: realHandleBsEndpoint has
its own catch around bookshelfJson which calls sendError with e.message
and returns null, so the outer catch never sees the exception. That inner
site is where a SQLiteException's SQL and withDatabase's check() failure --
which names the database file -- were actually reaching the client. Both
are closed now. The regression test fails against the first fix alone,
which is how the second site turned up.

MAX_RENDERED_CHARS drops from 16 MiB to 1 MiB. The arithmetic in the
finding is right: Pebble counts characters, so 16 Mi chars is a 33.5 MB
char[], the doubling that reaches it holds 33.5 MB and 67 MB at once, and
toString() copies another 33.5 MB. Against a 192-256 MB heap the runaway
loop OOMs long before the guard fires -- the one case it exists for. The
old number was headroom over the largest context in the database, which is
an unrelated quantity, as its own comment conceded. 1 MiB still sits well
above any legitimate rendered page here.

clearTemplateCache carries swapDatabaseIfChanged's warning. It takes the
write lock, withDatabase runs its block under the read lock, and
ReentrantReadWriteLock does not upgrade -- so withDatabase {
clearTemplateCache() } deadlocks permanently. Latent: all four current
callers are outside the read lock. The note is what keeps the next one out.

Separately, and NOT fixed here: sendError echoes e.message on two general
request paths too (WebServer.kt around the request-processing catch, and
the DocumentationLookup.Failed branch). Same exposure, any content path
rather than just /pr/bs, and pre-existing rather than introduced by this
ticket -- so it wants its own change, not a quiet widening of this one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gw89A3KWsPtvgPYtXYLBwr

* ADFA-5405: sweep the leak to the other transport, and close the swap window

Review of #1779 found the error-message leak this PR fixed for /pr/bs was
left in place on serveRequest, which answers every documentation URL on
the same port any app on the device can GET. Same rule applies there now:
only a TemplateRenderException's message reaches the client, everything
else gets generic text and the detail goes to the log.

The bookshelf handler built its payload under one withDatabase and
rendered the template under a second, so a debug-database swap landing
between them rendered the new database's template against the old one's
payload -- the pairing the bookshelfTemplateId/generation machinery this
PR deleted used to keep. renderNamedTemplate now takes a payload builder
and spans both under one acquisition. Nesting was not an option:
withDatabase takes the write lock to check for a swap before it takes the
read lock, so a nested call deadlocks.

That also removes the inner try/catch around the payload build, which is
why `a failure that is not a template failure answers 500 without leaking
internals` could not fail before: the inner catch answered and returned,
so the classification the test names never ran. It runs now, and
reverting the classification fails it.

DatabaseTemplateLoader: every failure leaves as a LoaderException,
including SQLite's. Pebble does not wrap what a loader throws, so a raw
SQLiteException escaped renderNamed's PebbleException catch carrying SQL
text and reached the branch above as "not a template failure". Also
rejects a duplicated name instead of taking row 0 by scan order (the
sibling check templateName already made for the id path), and a NULL
content column by name instead of an NPE with no message.

templateName's two diagnostics are TemplateRenderException now, so the id
half of the render path classifies the same way as the name half, and its
database failures are wrapped rather than escaping with SQL text.

MAX_RENDERED_CHARS keeps its value and loses the claim that it is "6x the
largest legitimate rendered page here" -- unmeasured, and unmeasurable
from this repo, since documentation.db is fetched rather than checked in.
The comment now says what the number is for and what to do if a real page
ever trips it.

Not done, filed as ADFA-5626: replacing the StackOverflowError catch with
an in-flight template-name set. It is the better mechanism, but Pebble
resolves {% include %} at evaluate time against its own compiled-template
cache, so the loader is not consulted and there is no seam to track
names through without a custom extension. The catch does produce a
correct 500 naming the template.

Also not done: removing refreshDatabase() and generation as dead
production code. Both are test-only, but the two refreshDatabase tests
pin a real past regression (it used to fall through to the swap check
after close()), and I would rather keep that coverage than the tidiness.
Noted in ADFA-5626.

Tests: 109 green across the documentation and web server suites, three
new loader tests, one new WebServerTest for the swept sibling. Both new
guards were mutated and fail without their fix.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017CCQUU7tBzZL61EmQhJP8j

* ADFA-5405: sweep resourceExists, and widen the render cap

resourceExists had none of the error handling getReader was given, so a
SQLiteException escaped it raw with its SQL text -- and because it returns
a Boolean rather than a Reader, the caller above could not classify the
throw as a template failure at all. Same wrapping as getReader now. The
KDoc's reason for not caring was that Pebble only reaches this through
loaders that are not wired here, which is a fact about today's wiring
rather than about the loader's contract.

MAX_RENDERED_CHARS goes from 1 MiB to 4 Mi chars. The old number was
uncalibrated by my own admission, and a cap where Pebble's default is
unbounded can turn a page that served into a 500. 4 Mi chars is an 8 MB
char[] with a ~32 MB transient through the doubling step and toString,
against a 192-256 MB heap -- still comfortably ahead of the OOM it exists
to catch, since unbounded growth passes any finite number, but with a
wide margin over real content rather than a tight one.

Review argued the multi-megabyte rows readChunks exists for prove content
that large reaches the writer. They do not: render() runs only for
templateId > 0 and those rows are the bundled PDFs, which have no
template. The comment now says so, since that was the reasoning the old
number lacked.

Tests: 110 green, one new for the swept sibling.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017CCQUU7tBzZL61EmQhJP8j

* ADFA-5405: guard the other NULL column

templateName() read cursor.getString(0) into a non-null String. getString
returns a platform type, so a NULL Templates.name yielded null and the
implicit check threw a bare NPE, which the RuntimeException catch below
rewrapped as "Cannot read the template for ID N" -- losing which column
was null and, unlike the loader's path, never naming the template.

The loader guards exactly this for getBlob, with a test. This was the
second of the two sites and the sweep missed it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017CCQUU7tBzZL61EmQhJP8j

* ADFA-5405: honour the loader's existence contract, and stop encoding one fact twice

resourceExists is Pebble's existence predicate -- what a DelegatingLoader
uses to decide whether to fall through to the next loader -- so a throw
there aborts resolution where a miss would fall back. The previous commit
made it throw, to keep SQL text out of the response. That kept the SQL
out and broke the contract to do it; logging keeps both.

It also disagreed with getReader about a duplicated name: the predicate
said the template existed, the reader refused to load it. It counts now
rather than existence-checking, so a name with more than one row answers
false, which is what the reader will do with it anyway.

realHandleBsEndpoint returns Unit. Removing the isCursorOneRow path took
its only `return false` with it, so the Boolean had become a constant
that the caller assigned to the same variable markOutputStarted already
set -- two mechanisms for one piece of state, and a later early return
that updated only one would leave the caller sending response headers
onto a socket that already carries a body.

Tests: 113 green across the documentation and web server suites, two new
for the predicate.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017CCQUU7tBzZL61EmQhJP8j

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: davidschachterADFA

app/src/main/java/com/itsaky/androidide/localWebServer/WebServer.kt

@@ -1,6 +1,5 @@
 package com.itsaky.androidide.localWebServer
 
-import android.database.Cursor
 import android.database.sqlite.SQLiteDatabase
 import android.net.TrafficStats
 import android.os.Environment.getExternalStorageDirectory
@@ -11,6 +10,7 @@ import com.itsaky.androidide.documentation.DocumentationContent
 import com.itsaky.androidide.documentation.DocumentationContentSource
 import com.itsaky.androidide.documentation.DocumentationLookup
 import com.itsaky.androidide.documentation.DocumentationRequestInterceptor
+import com.itsaky.androidide.documentation.TemplateRenderException
 import com.itsaky.androidide.utils.ContentTypeHeaders
 import com.itsaky.androidide.utils.DatabaseVersionResolver
 import org.slf4j.LoggerFactory
@@ -148,18 +148,6 @@ class WebServer(
 			.serializeNulls()
 			.create()
 
-	// -1 means "not fetched yet". Volatile because the WebView transport shares this server's
-	// process, and the interceptor's reads can run on WebView threads while the accept loop writes.
-	@Volatile
-	private var bookshelfTemplateId: Int = -1
-
-	private val cacheLock = Any()
-
-	// Which of the source's databases bookshelfTemplateId was filled from. The compiled templates
-	// themselves live in the source and are dropped by its own swap.
-	@Volatile
-	private var cachedDatabaseGeneration = 0L
-
 	// Long enough to stop a descriptor-exhaustion spin starving the connections whose closing would
 	// fix it; short enough to be invisible to a user, and never paid on a successful accept.
 	private val initialAcceptBackoffMs = 50L
@@ -547,31 +535,11 @@ class WebServer(
 			return sendError(writer, output, 501, "Not Implemented")
 		}
 
-		// serveRequest applies any pending sdcard debug-database swap via the content source.
+		// The content source applies a pending sdcard debug-database swap inside lookup()/withDatabase(),
+		// so a request reaching neither -- an unknown /pr/ target -- does not poll for one.
 		serveRequest(writer, output, path)
 	}
 
-	/**
-	 * Invalidates the cached bookshelf template identifier when the documentation database changes.
-	 */
-	private fun discardCachesIfDatabaseChanged() {
-		// Apply any pending swap first. The source swaps inside lookup()/withDatabase(), so checking
-		// the generation before those runs reads the generation from before the swap: on the very
-		// request that swaps, this would leave bookshelfTemplateId pointing at the previous
-		// database's template row -- rendering the old bookshelf, or 500ing if that id is absent.
-		contentSource.refreshDatabase()
-
-		if (contentSource.generation == cachedDatabaseGeneration) return
-
-		synchronized(cacheLock) {
-			val generation = contentSource.generation
-			if (generation == cachedDatabaseGeneration) return
-
-			bookshelfTemplateId = -1
-			cachedDatabaseGeneration = generation
-		}
-	}
-
 	/**
 	 * Serves a parsed request using the appropriate diagnostic endpoint or documentation content.
 	 *
@@ -584,8 +552,6 @@ class WebServer(
 		output: java.io.OutputStream,
 		path: String,
 	) {
-		discardCachesIfDatabaseChanged()
-
 		// Handle the special "pr" endpoint with highest priority
 		if (path.startsWith("pr/", false)) {
 			if (debugEnabled) log.debug("Found a pr/ path, '{}'.", path)
@@ -623,7 +589,13 @@ class WebServer(
 			}
 
 			is DocumentationLookup.Failed -> {
-				sendError(writer, output, httpInternalServerError, "Internal Server Error", lookup.cause.message ?: "")
+				log.error("Cannot serve the documentation request", lookup.cause)
+				// Same rule as /pr/bs, and for the same reason: only a template failure names a
+				// template, and only its message is safe to send. A SQLiteException carries SQL text
+				// and withDatabase's check() carries the database's filesystem path, and any app on
+				// the device can GET this port. This is the sibling the first pass missed.
+				val detail = (lookup.cause as? TemplateRenderException)?.message ?: "Internal Server Error"
+				sendError(writer, output, httpInternalServerError, "Internal Server Error", detail)
 			}
 		}
 	}
@@ -801,10 +773,25 @@ class WebServer(
 		var outputStarted = false
 
 		try {
-			outputStarted = realHandleBsEndpoint(writer, output) { outputStarted = true }
+			realHandleBsEndpoint(writer, output) { outputStarted = true }
 		} catch (e: Exception) {
 			log.error("Error handling /pr/bs endpoint: {}", e.message)
-			sendError(writer, output, httpInternalServerError, "Internal Server Error 6", "Error generating bookshelf HTML.", outputStarted)
+			// The message is echoed ONLY for a template failure. That one names a template -- the
+			// bookshelf row itself, or anything it references -- and the name is the whole diagnostic
+			// (ADFA-5405). Everything else keeps the generic text, because this catch spans the whole
+			// of realHandleBsEndpoint: a SQLiteException carries SQL, and withDatabase's
+			// check(openIfNeeded()) carries the database's filesystem path. Any app on the device can
+			// GET this port, so echoing those was handing out internals for the sake of one
+			// diagnostic.
+			val detail = (e as? TemplateRenderException)?.message ?: "Error generating bookshelf HTML."
+			sendError(
+				writer,
+				output,
+				httpInternalServerError,
+				"Internal Server Error 6",
+				detail,
+				outputStarted,
+			)
 		}
 
 		if (debugEnabled) log.debug("Leaving handleBsEndpoint().")
@@ -864,54 +851,36 @@ class WebServer(
 	/**
 	 * Generates the bookshelf page and sends it to the client.
 	 *
-	 * @return `true` if a response was produced, `false` if processing failed or no response was produced.
+	 * Returns nothing: [markOutputStarted] is how the caller learns the response has begun, and it
+	 * fires at the moment it actually does. Returning the same fact as well meant two mechanisms
+	 * for one piece of state -- and once the only early return went, the returned value was a
+	 * constant. A later early return that updated one and not the other would leave the caller
+	 * sending response headers onto a socket that already carries a body.
 	 */
 	private fun realHandleBsEndpoint(
 		writer: PrintWriter,
 		output: java.io.OutputStream,
 		markOutputStarted: () -> Unit,
-	): Boolean {
+	) {
 		if (debugEnabled) log.debug("Entering realHandleBsEndpoint().")
 
-		// Null means an error response has already been sent, so there is nothing left to write.
-		val jsonText =
-			contentSource.withDatabase { database ->
-				try {
-					val json = bookshelfJson(database)
-					if (debugEnabled) log.debug("json content = '{}'.", String(json, Charsets.UTF_8))
-					if (debugEnabled) log.debug("before fetch bookshelf template ID = '{}'", bookshelfTemplateId)
-
-					// Have we already fetched the template
-					if (bookshelfTemplateId == -1) {
-						database.rawQuery("SELECT id FROM Templates WHERE name = 'bookshelf'", arrayOf()).use { cursor ->
-							if (!isCursorOneRow(cursor, writer, output)) {
-								return@withDatabase null
-							}
-
-							cursor.moveToFirst()
-							bookshelfTemplateId = cursor.getInt(0)
-							if (debugEnabled) log.debug("after the fetch bookshelf template ID = '{}'", bookshelfTemplateId)
-						}
-					}
-
-					json
-				} catch (e: Exception) {
-					log.error("Error processing request: {}", e.message)
-					sendError(writer, output, httpInternalServerError, "Internal Server Error", e.message ?: "")
-					null
+		// The payload and the template are built under one database acquisition, so a swap cannot
+		// land between them. Nothing is caught here: handleBsEndpoint's catch is the single place
+		// that decides what reaches the client, and an inner catch that answered and returned made
+		// that decision unreachable for everything raised inside this block.
+		val result =
+			contentSource.renderNamedTemplate("bookshelf", "/bookshelf") { database ->
+				bookshelfJson(database).also {
+					if (debugEnabled) log.debug("json content = '{}'.", String(it, Charsets.UTF_8))
 				}
-			} ?: return false
-
-		val result = contentSource.renderTemplate(bookshelfTemplateId, jsonText, "/bookshelf")
+			}
 
 		if (debugEnabled) log.debug("Bookshelf result is '{}'.", String(result))
 
 		markOutputStarted()
 		writeNormalToClient(writer, output, String(result))
 
 		if (debugEnabled) log.debug("Leaving realHandleBsEndpoint().")
-
-		return true
 	}
 
 	/**
@@ -1070,22 +1039,6 @@ ORDER BY BC.category,
 		)
 	}
 
-	private fun isCursorOneRow(
-		cursor: Cursor,
-		writer: PrintWriter,
-		output: java.io.OutputStream,
-	): Boolean {
-		if (cursor.count == 1) {
-			return true
-		}
-		if (cursor.count == 0) {
-			sendError(writer, output, httpNotFound, "Corrupt database, no rows found, expected one.")
-		} else {
-			sendError(writer, output, httpInternalServerError, "Corrupt database - found ${cursor.count} rows when 1 was expected.")
-		}
-		return false
-	}
-
 	/**
 	 * Builds an HTML table of recent projects from the provided project database and writes it to the client.
 	 *

app/src/test/java/com/itsaky/androidide/localWebServer/WebServerTest.kt

@@ -363,15 +363,9 @@ class WebServerTest {
 		// The bookshelf join matches nothing: a cursor whose moveToNext() is immediately false.
 		every { db.rawQuery(match { it.contains("FROM Content AS C") }, any()) } returns
 			mockk<Cursor>(relaxed = true) { every { moveToNext() } returns false }
-		// The bookshelf template: its id lookup, then its body -- a Pebble expression over the JSON
-		// context, so the assertion proves the empty-shelf payload actually reached the render.
+		// The bookshelf template's body, fetched by name (ADFA-5405) -- a Pebble expression over the
+		// JSON context, so the assertion proves the empty-shelf payload actually reached the render.
 		every { db.rawQuery(match { it.contains("FROM Templates WHERE name") }, any()) } returns
-			mockk<Cursor>(relaxed = true) {
-				every { count } returns 1
-				every { moveToFirst() } returns true
-				every { getInt(0) } returns 7
-			}
-		every { db.rawQuery(match { it.contains("FROM Templates WHERE id") }, any()) } returns
 			mockk<Cursor>(relaxed = true) {
 				every { count } returns 1
 				every { moveToFirst() } returns true
@@ -392,6 +386,114 @@ class WebServerTest {
 		}
 	}
 
+	// ADFA-5405: a template the endpoint cannot resolve -- the bookshelf row, or anything it
+	// references -- is named by the loader's throw, and handleBsEndpoint has to pass that name on
+	// rather than replace it with its generic text. The name is the whole diagnostic.
+	@Test
+	fun `a bookshelf template that is not in the database answers 500 naming it`() {
+		val port = freePort()
+		val db = mockk<SQLiteDatabase>(relaxed = true)
+		every { SQLiteDatabase.openDatabase(any(), isNull(), any()) } returns db
+		every { db.rawQuery(match { it.contains("FROM Content AS C") }, any()) } returns
+			mockk<Cursor>(relaxed = true) { every { moveToNext() } returns false }
+		// No bookshelf row: a relaxed cursor's moveToFirst() is already false.
+		every { db.rawQuery(match { it.contains("FROM Templates WHERE name") }, any()) } returns mockk<Cursor>(relaxed = true)
+
+		val server = WebServer(testConfig(port))
+		val serverThread = Thread { server.start() }.apply { isDaemon = true }
+		serverThread.start()
+		try {
+			awaitPortBound(port)
+			val response = sendRawGetRequest(port, "/pr/bs")
+			assertTrue("Expected a 500 status line, got:\n$response", response.startsWith("HTTP/1.1 500"))
+			// The loader's own text, not just the template name: the generic fallback on the same
+			// sendError call is "Error generating bookshelf HTML.", which contains "bookshelf" too,
+			// so asserting on the name alone passes with or without the fix.
+			assertTrue(
+				"Expected the loader's diagnostic, got:\n$response",
+				response.contains("Template 'bookshelf' not found in the database"),
+			)
+			assertFalse("Expected no Pebble placeholder padding, got:\n$response", response.contains("(?:?)"))
+		} finally {
+			server.stop()
+			serverThread.join(2_000)
+		}
+	}
+
+	// The other half of the ADFA-5405 diagnostic: handleBsEndpoint's catch spans the whole handler,
+	// so echoing e.message put anything thrown in there into the response body -- a SQLiteException's
+	// SQL, or withDatabase's check() failure naming the database file. Any app on the device can GET
+	// this port. Only a template failure is echoed now; this pins that the rest is not.
+	//
+	// This throw has to reach that catch to pin anything. It did not until the inner try/catch
+	// around the payload build was removed: that one answered and returned, so the classification
+	// under test never ran and this test passed against the unfixed code.
+	@Test
+	fun `a failure that is not a template failure answers 500 without leaking internals`() {
+		val port = freePort()
+		val db = mockk<SQLiteDatabase>(relaxed = true)
+		every { SQLiteDatabase.openDatabase(any(), isNull(), any()) } returns db
+		// Thrown from inside the handler rather than from openDatabase, which would fail start()
+		// before the port is bound. The type matters more than the origin: this is the same
+		// IllegalStateException that withDatabase's check() raises, which used to be
+		// indistinguishable from a template diagnostic and so was echoed verbatim -- and its message
+		// carries both a filesystem path and SQL, the two things worth not sending.
+		every { db.rawQuery(match { it.contains("FROM Content AS C") }, any()) } throws
+			IllegalStateException(
+				"unable to open database file /data/user/0/com.itsaky.androidide/databases/documentation.db " +
+					"(while compiling: SELECT C.content FROM Content AS C JOIN ContentTypes)",
+			)
+
+		val server = WebServer(testConfig(port))
+		val serverThread = Thread { server.start() }.apply { isDaemon = true }
+		serverThread.start()
+		try {
+			awaitPortBound(port)
+			val response = sendRawGetRequest(port, "/pr/bs")
+			assertTrue("Expected a 500 status line, got:\n$response", response.startsWith("HTTP/1.1 500"))
+			assertTrue(
+				"Expected the generic text, got:\n$response",
+				response.contains("Error generating bookshelf HTML."),
+			)
+			assertFalse("Leaked a filesystem path:\n$response", response.contains("/data/user/0/"))
+			assertFalse("Leaked a database filename:\n$response", response.contains("documentation.db"))
+			assertFalse("Leaked SQL text:\n$response", response.contains("SELECT C.content"))
+		} finally {
+			server.stop()
+			serverThread.join(2_000)
+		}
+	}
+
+	// The sibling handleBsEndpoint's fix missed: serveRequest answers every documentation URL, and
+	// its Failed branch sent lookup.cause.message verbatim. Same port, same reachable-by-any-app
+	// exposure, and ADFA-5405's loader made database failures reachable from more places.
+	@Test
+	fun `a documentation request that fails answers 500 without leaking internals`() {
+		val port = freePort()
+		val db = mockk<SQLiteDatabase>(relaxed = true)
+		every { SQLiteDatabase.openDatabase(any(), isNull(), any()) } returns db
+		every { db.rawQuery(match { it.contains("FROM   Content") }, any()) } throws
+			IllegalStateException(
+				"unable to open database file /data/user/0/com.itsaky.androidide/databases/documentation.db " +
+					"(while compiling: SELECT C.content FROM Content C)",
+			)
+
+		val server = WebServer(testConfig(port))
+		val serverThread = Thread { server.start() }.apply { isDaemon = true }
+		serverThread.start()
+		try {
+			awaitPortBound(port)
+			val response = sendRawGetRequest(port, "/k/html/basic-syntax.html")
+			assertTrue("Expected a 500 status line, got:\n$response", response.startsWith("HTTP/1.1 500"))
+			assertFalse("Leaked a filesystem path:\n$response", response.contains("/data/user/0/"))
+			assertFalse("Leaked a database filename:\n$response", response.contains("documentation.db"))
+			assertFalse("Leaked SQL text:\n$response", response.contains("SELECT C.content"))
+		} finally {
+			server.stop()
+			serverThread.join(2_000)
+		}
+	}
+
 	// ADFA-5241: the two transports have to answer the same way about what a response says, and
 	// only a real response proves what this one sends. The decision itself lives in
 	// ContentTypeHeaders, shared with DocumentationRequestInterceptor.