Skip to content

ADFA-7135, ADFA-7136: SQLite debugger extension and MCP server for debug builds - #2259

Open
davidschachterADFA wants to merge 25 commits into
feat/ADFA-7082-sqlite-js-aarfrom
sqlite-debugger/ADFA-7135
Open

davidschachterADFA wants to merge 25 commits into
feat/ADFA-7082-sqlite-js-aarfrom
sqlite-debugger/ADFA-7135

Conversation

@davidschachterADFA

@davidschachterADFA davidschachterADFA commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

ADFA-7135 and ADFA-7136

The SQLite debugger for debug builds of apps built with Code on the Go (design: ADFA-7131): a SQLite extension that tracks the app's connections and traces its statements, and an MCP server inside the app with eight read-only database tools. New module :subprojects:sqlite-debugger.

Stack: on #2244 (feat/ADFA-7082-sqlite-js-aar). #2244 has moved five commits (sqlite-js 1.4.2) since this branch was cut; the stack takes them in before it merges. Above this PR: ADFA-7137, then ADFA-7139; and ADFA-7138, which needs ADFA-7137's library change, so merge it last.

Commits: the cloud session's ADFA-7135/7136 work (extension, JNI, server, tools, review fixes, docs), plus one commit from the local session: the module's Kotlin compile tasks target JVM 1.8 (the root build sets every KotlinCompile task to 17, which made the first compile of the Android-only files fail).

Verified

  • :subprojects:sqlite-debugger:assembleDebug builds both ABIs; the C compiles without warnings under -Wall -Wextra; libsqlitedbg.so exports only JNI_OnLoad; testDebugUnitTest passes.
  • On a Galaxy Note 20 (Android 13), arm64-v8a and as a 32-bit armeabi-v7a process, with the ADFA-7082 template app: every Room statement (setQueryCallback) matched the trace in order, per thread, across Room's pool (202/202 on each ABI, 0 dropped). Extra time per statement: arm64 +1.6 us per select with no client, +2.9 us with a client connected; armeabi-v7a within noise with no client, +8.8 us with a client.
  • A database opened in Application.onCreate is traced (synchronous install in DebuggerStartup.onCreate).
  • The device checks ran before the cloud's last six commits (c862c5c..7684331).

Review fixes (round 1): the request head is bounded and authenticated before the body; the heap-limit and temp-directory PRAGMAs are denied on server connections; server connections wait up to 3 s for a lock; a query whose argument count differs from its parameter count fails with SQLITE_RANGE; list_databases matches files through a symlinked folder, so a database is listed once (ADFA-7136); the host C and JNI tests run in CI (.github/workflows/test-sqlite-debugger.yml).

Known: statement durations have 1 ms resolution (SQLite's unix VFS clock).

No screens added or changed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn

claude and others added 17 commits November 13, 2026 04:32
… and its server

sqlitedbg.h is what the extension implements and its JNI layer calls;
DebugEngine.kt is what the server (ADFA-7136) builds against, with a fake
for JVM tests. Not yet built by Gradle: the module has no build file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
McpHttp.kt and McpProtocol.kt from Local Store Server Combined with only the
package, server name, title, instructions and 401 texts changed.
McpProtocolTest.kt still names that project's tools and does not compile;
ADFA-7136 rewrites it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
Module build file modelled on sqlite-js (no ABI flavors, both ABIs, no STL,
16 KiB pages), plus Kotlin at API 2.0 for apps built with CoGo. Registered in
settings, modulesWithoutAbiFlavors and disableCoreLibDesugaringForModules.
The CMake file arrives with the extension in the next commit.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
Binds 127.0.0.1 on port 0 with a new token per process start, and serves
list_databases, list_connections, get_schema, query, explain_query_plan,
get_stats, integrity_check and get_events against DebugEngine. JVM tests
run against FakeDebugEngine (51 pass). DebuggerStartup.kt and the manifest
are Android-only and not yet compiled. Formatting follows in its own commit.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
sqlitedbg.c implements sqlitedbg.h as a loadable-extension client. Per-connection
state is freed only from the xDestroy of sqlitedbg_connection_id; the trace CLOSE
event only marks it closing. Events live in a ring of records in their exported
layout. Server connections are recognised by a thread-local flag set around
sqlitedbg_open_server's own open.

test.sh builds SQLite 3.49.1 from the amalgamation (pinned) and runs
sqlitedbg_test.c under ASan+UBSan and under TSan. The same run writes or checks
the fixture the EventDecoder JVM test reads.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
sqlitedbg_jni.c registers NativeBridge's natives from JNI_OnLoad (the version script
exports nothing else) and reaches SQLite only through the extension's api table.
ServerConnection.query steps the statement in C, binds args by type, applies
QueryLimits, and stops at the deadline through a progress handler on the server
connection. EventDecoder mirrors the exported record layout and is tested against
the fixture the host C test writes.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
… change

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
- read_events moves the cursor past dropped events when it copies nothing, so a
  drop is reported once.
- An internal failure in sqlitedbg_extension_init is logged and the connection left
  untracked; the app's own sqlite3_open no longer fails because of it.
- A trigger is told apart from app SQL by X differing from sqlite3_sql(P), not by a
  "--" prefix, so statements that start with a comment are expanded.

test.sh builds the extension with SQLITEDBG_TEST for the failure hook.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
AndroidModuleConf.kt already excludes it; ARCHITECTURE.md and CLAUDE.md
named only plugin-api and sqlite-js.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
…onnections

- DebuggerStartup catches Throwable after the debuggable check, so a missing
  requery library (UnsatisfiedLinkError) disables the debugger instead of
  killing the app. The check itself still throws.
- install() runs synchronously in onCreate; only the server start is on the
  thread, so connections opened in Application.onCreate are tracked.
- McpHttp: connection and accept threads catch Throwable; an Error while
  handling a request is answered with a 500.
- McpHttp: a failed accept sleeps 100 ms, doubling to 2 s while failures
  continue, and resets on success (no spin on EMFILE).

Tests: an Error thrown by a tool gives HTTP 500 and the server keeps serving;
a ServerSocket whose accept fails is retried with growing gaps, then serves.
DebuggerStartup imports android.* and has no JVM test.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
The read-only authorizer allowed BEGIN, SAVEPOINT and PRAGMA locking_mode, so
a client could hold a lock on the app's database: BEGIN; SELECT left the app's
INSERT failing with SQLITE_BUSY until ROLLBACK.

- sqlitedbg.c: deny SQLITE_TRANSACTION, SQLITE_SAVEPOINT, PRAGMA locking_mode
  and PRAGMA busy_timeout (any form) on read-only server connections.
- sqlitedbg_jni.c: bridge_query rolls back if the connection is not in
  autocommit when it returns (covers writable connections).
- Host C test: each denied statement returns SQLITE_AUTH and the app can still
  write after a read on that connection.

Without the authorizer change the test fails on all 8 statements (BEGIN and
SAVEPOINT: "database is locked" for the app's INSERT). The backstop is tested
with the JNI test.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
- M4: QueryLimits.maxTotalBytes (DatabaseTools passes 4 MiB). bridge_query
  counts the TEXT/BLOB bytes kept and 8 per number, and stops with hasMore
  before the row that would pass the budget; the first row always goes in so
  a page makes progress. The tool result text is serialised compact: it was
  sent twice, pretty and as structuredContent.
- L11: the engine reports cut cells (QueryResult.truncatedCellIndexes, row *
  columns + column) instead of DatabaseTools guessing from size >= limit, so
  a BLOB of exactly maxBlobBytes is no longer flagged.
- L12: get_schema and get_stats read sqlite_master (sqlite_schema needs 3.33).
- L13: sqlite3_column_text/blob returning NULL (out of memory) is checked.

JVM tests: blob at the limit vs one byte over, the budget pages a result of
3 MiB rows, sqlite_master in the SQL sent, compact result text. Each fails
with its fix reverted. The native side (budget, cut cells) is tested by the
JNI test in a later commit; L13 has no test (needs an allocation failure).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
- M7: DatabaseTools cached a server connection per path forever, so after the
  app deleted and recreated its database the server read the old file. Each
  cached connection remembers the ids of the app connections to its path when
  it opened. Before each tool call it is closed and dropped when no live app
  connection has the path, or none of those ids is left.
- L14: the first get_events turned on bound-value expansion until the server
  stopped, so every app statement was expanded twice forever. It now goes off
  60 s after the last get_events call, checked on every tool call and by a
  daemon timer; the tool description says so.
- L10 (one lock for all tool calls) is documented in the class KDoc.

Tests: recreated database reopens (opened 2, closed 1), a connection survives
while a seen app connection remains, a vanished path closes the cached one,
and expansion stops after 60 s. Each fails with its fix reverted (expected 2
but was 1; expected 1 but was 0; "60 s after the last get_events").

Limit accepted: a database replaced in place while the same app connections
stay open is not detected.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
test.sh now also builds the JNI layer as it ships (libsqlitedbg.so without
SQLITE_CORE, with the version script) against a requery-like libsqlite3x.so
(amalgamation, THREADSAFE=2, all symbols exported) and runs
src/test/jni/JniQueryTest.java on the host JVM through NativeBridge. It is
skipped with a message when no JDK is on PATH.

It uses Java stubs of NativeBridge and DebugEngineException (same names and
native signatures) rather than compiling the Kotlin, so only a JDK is needed;
test.sh fails if the native names in NativeBridge.kt and the stub differ. A
change of a Kotlin parameter type alone is not caught.

Covers: value types, paging and hasMore, the total-bytes budget (including
"first row always goes in" and the budget stopping on a row boundary), per-cell
truncation at, over and under the limit with row * columns + column indexes
and a budget-dropped row's cells, bound types, the deadline giving
SQLITE_INTERRUPT, refused writes giving SQLITE_AUTH, BEGIN/SAVEPOINT/PRAGMA
refusals leaving the app able to write, and the rollback backstop.

Checked to fail with each native fix reverted: budget (50 rows vs 4), cut cell
indexes ([] vs [1, 3]), rollback backstop (app INSERT 5 vs 0, SQLITE_BUSY),
authorizer (BEGIN: 0 vs 23), dropped row's cut cells ([0, 1] vs [0]).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
README: the JNI test and how it stands in for the Kotlin, and that requery's
own sqlite3_trace (log.tag.SQLiteStatements or SQLiteTime VERBOSE) replaces
ours on a connection, so its events stop. No code change for that.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAZ8yszEP4MqbR9PLba
The root build sets jvmTarget 17 on every KotlinCompile task, which
overrides the module's kotlin { compilerOptions } and made
compileDebugKotlin fail against compileOptions' Java 1.8 ("Inconsistent
JVM-target compatibility"). Setting it on the tasks keeps 1.8, as
sqlite-js uses.

First compile of the Android-only files (NativeDebugEngine.kt,
DebuggerStartup.kt, sqlitedbg_jni.c, the manifest): with this change
:subprojects:sqlite-debugger:assembleDebug builds both ABIs, the C
compiles without warnings under -Wall -Wextra, libsqlitedbg.so exports
only JNI_OnLoad, and testDebugUnitTest passes 56 tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

Tip: disable this comment in your organization's Code Review settings.

@davidschachterADFA davidschachterADFA left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review of #2259 (medium effort). Verdict computed: COMMENT (only MINOR findings, and GitHub refuses APPROVE/REQUEST_CHANGES on a self-authored PR). Nothing here blocks merge.

MINOR

  • McpProtocol.kt:69 - initialize tells the agent about a read-write mode that does not exist
  • McpHttp.kt:217 - 8 connection slots can be held before authentication by a slow request
  • test.sh:1 - the native and JNI tests run in no CI job

NITPICK - none

Stack. Layer 1 of 4. Below: #2244 (feat/ADFA-7082-sqlite-js-aar). Above: #2260 (ADFA-7137) and #2262 (ADFA-7138), both on this PR, and #2261 (ADFA-7139) on #2260. There are two tips: #2261 (86b67f56) and #2262 (461fd39e). Claims were checked against the tip that contains the code: subprojects/sqlite-debugger differs between this head and the tips only by EndpointBroadcast.kt, a README line, and a manifest/startup hook, so both tips behave the same for every finding here. No finding was dropped as already fixed higher up; none of the three is fixed in either tip.

Rules applied. REVIEW.md and CLAUDE.md at the head. They give no approve/request-changes rule (REVIEW.md is "a coaching doc, not a gate"), so the skill's default table applied.

Prior rounds. One earlier review (claude[bot], a "comment @claude review" notice) with no findings and no inline comments. Nothing to re-check.

Evidence ledger (REVIEW.md).

Area Evidence
Ticket completeness ADFA-7135/7136 scope in the PR body: extension, JNI, eight read-only tools, MCP server. All present with tests. Not checked against the Jira text (no Jira access in this review).
Exceptions DebuggerStartup catches Throwable, logs, and disables the debugger; the connection threads and accept loop catch and log. Nothing new reaches the GlitchTip handler. The non-debuggable check(...) crash is intentional and documented.
Leaks / resources Sockets and clients closed in finally; JNI local refs deleted per row; done: finalizes the statement, clears the progress handler, rolls back a stray transaction. Not run under LeakCanary (static review).
Threading Server and timer threads are daemons off the main thread. The only main-thread work is the synchronous install(), which is deliberate so early databases are traced. No StrictMode run.
Security Loopback bind, Host and Origin checks, constant-time bearer token, header/body caps. Server connections open read-only with query_only, an authorizer (writes, ATTACH, transactions, PRAGMA writers), and a time limit. The one gap found is the pre-auth slot exhaustion above.
Tests Unit tests for protocol, HTTP, tools, decoder; C tests under ASan/UBSan/TSan; a JNI query test. No JaCoCo numbers were produced. The native tests are not in CI (finding on test.sh).
Architecture / docs README, ARCHITECTURE.md and CLAUDE.md updated in the PR. Strings/a11y/help/analytics: not applicable (no UI). Plugins: no plugin API touched.

Static review only: no build, no device. The built-in code-review fork for this run read a diff file from a shared scratch directory that held a different PR's diff, so its output was discarded and every finding above comes from my own read of this PR at its head.

const val INVALID_PARAMS = -32602
const val INSTRUCTIONS =
"Inspects and queries the SQLite databases of the app this server runs in, a debug " +
"build made with Code on the Go. Read-only unless the app's developer turned on read-write mode."

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MINOR: the initialize instructions say the server is "read-only unless the app's developer turned on read-write mode", but no such mode exists.

DatabaseTools always opens server connections with writable = false, and nothing in this PR or in #2260, #2261 or #2262 reads a setting that changes that (the README says the same: every tool is read-only). Today no caller can reach a writable connection, so this is not a safety issue. It does tell the agent, which reads this string, that a read-write mode may be switched on, and it may plan around it or tell the user to enable it.

Drop the clause: "Read-only." Add it back in the PR that adds the mode.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 3e1830f: the instructions now say every tool is read-only; a test asserts there is no read-write wording.

}

private fun serve(c: Socket) {
c.soTimeout = IDLE_TIMEOUT_MS

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MINOR: the 30 s read timeout applies to each read, not to a whole request, and authentication happens only after the full request is read. A client can hold one of the 8 connection slots without ever authenticating.

Another app on the same device can open 8 sockets to 127.0.0.1: and send one byte every 25 s (or just connect and idle for 30 s, repeatedly). Every slot stays taken and MAX_CONNECTIONS makes the real client get 503. It only denies service to the debugger itself, on a debug build, and the attacker needs a local app plus the port (the port is in logcat), so it does not block the merge.

Fix: give each request an overall deadline (for example 10 s to receive headers and body, checked in readRequest), and apply the token check before reading the body.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 3e1830f: the request head has a 5 s overall deadline (from connect for the first request), and Host, Origin, path and token are checked as soon as the headers are read, before the body. A refused request closes the connection. Tests: eight silent or trickling sockets are dropped within the deadline and the real client is served; a 401 arrives with the body never sent.

@@ -0,0 +1,103 @@
#!/usr/bin/env bash

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MINOR: the native and JNI tests in this script run in no CI job, so the extension's safety net exists only when someone remembers to run it.

test.sh runs sqlitedbg_test.c under ASan/UBSan and TSan and the JNI query test, and the Gradle testDebugUnitTest task does not call it. .github/workflows has test-sqlite-js.yml for the sibling module but nothing mentions sqlite-debugger, at this head or at either stack tip. The ring buffer, eviction and read-only authorizer in sqlitedbg.c are the parts most likely to regress silently.

Add a workflow modelled on test-sqlite-js.yml (paths subprojects/sqlite-debugger/**, run subprojects/sqlite-debugger/test.sh).

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 3527173: .github/workflows/test-sqlite-debugger.yml, modelled on test-sqlite-js.yml, runs subprojects/sqlite-debugger/test.sh (host C tests under ASan/UBSan and TSan, and the JNI test) on changes to the module or to the sqlite-js headers it compares.

@davidschachterADFA davidschachterADFA left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-run of the automated first pass after the earlier run's diff collision (its code-review step read another PR's diff). This review lists only findings that were not already posted on this PR; the earlier review's three findings are not repeated. Head 9d87b3e, checked against the stack tips (#2261 86b67f56, #2262 461fd39e), which do not change the code these comments cite. Static review only: no build, no device. Self-authored PR, so COMMENT.

MINOR

  • sqlitedbg.c:427 - the read-only authorizer lets PRAGMA hard_heap_limit / soft_heap_limit through, and those are process-wide
  • sqlitedbg.c:452 - the server connection has no busy timeout, so it fails at once when the app holds a lock (PLAUSIBLE)
  • sqlitedbg_jni.c:336 - fewer args than ? parameters binds the rest as NULL without an error

NITPICK - none

// locking_mode=EXCLUSIVE keeps the lock after a read, and busy_timeout (any form) lets a
// statement wait on the app's lock for as long as the client likes.
if (a1 && (sqlite3_stricmp(a1, "query_only") == 0 || sqlite3_stricmp(a1, "writable_schema") == 0 ||
sqlite3_stricmp(a1, "locking_mode") == 0 || sqlite3_stricmp(a1, "busy_timeout") == 0 ||

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MINOR: the PRAGMA deny list misses hard_heap_limit and soft_heap_limit, which change a limit shared by every SQLite connection in the process.

The authorizer sees PRAGMA hard_heap_limit=1 as SQLITE_PRAGMA with that name (I confirmed the callback fires for both pragmas), and neither is in the list, so query_only does not stop it. SQLite documents both limits as process-wide, so the debugger's query tool, which the README describes as a guard against accidents, can make every connection of the app fail with SQLITE_NOMEM until the process restarts. No tool does this by itself; it takes an MCP client sending that statement, which is why this is MINOR.

Add hard_heap_limit, soft_heap_limit (and temp_store_directory, also process-wide) to the denied names, with a test beside the busy_timeout cases.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 7cf251b: hard_heap_limit, soft_heap_limit and temp_store_directory are denied on server connections (header and README updated); host C tests cover the set and read forms.

int rc = sqlite3_open_v2(path, db, writable ? SQLITE_OPEN_READWRITE : SQLITE_OPEN_READONLY, NULL);
tls_opening_server = 0;
if (rc == SQLITE_OK && !writable) {
rc = sqlite3_exec(*db, "PRAGMA query_only=1", NULL, NULL, NULL);

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MINOR (PLAUSIBLE): sqlitedbg_open_server sets no busy timeout, and PRAGMA busy_timeout is denied, so a server connection never waits for the app's lock.

If the app's database is in rollback-journal mode and the app is mid-write, get_schema, query and the other tools fail at once with "database is locked", and they do so exactly while the app is doing the work the agent wants to inspect. In WAL mode readers are not blocked, so many apps will not see it; I could not tell which mode apps built with Code on the Go use by default.

Call sqlite3_busy_timeout(*db, 250) (a small fixed value, set by the library and not changeable by the client) after the authorizer is installed, or document the "database is locked" result in the tool descriptions.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in f785f96: server connections get sqlite3_busy_timeout of 3000 ms (SQLITEDBG_SERVER_BUSY_MS in sqlitedbg.h); PRAGMA busy_timeout stays denied. Host C test: with an app connection holding BEGIN EXCLUSIVE in rollback-journal mode, a server read waits and succeeds when the lock is released, and returns SQLITE_BUSY after about 3 s when it is not.

sqlite3_progress_handler(db, 1000, progress_cb, &dl);
handler_set = 1;

rc = st ? bind_args(env, db, st, args, &message) : SQLITE_OK;

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MINOR: bind_args binds only the values the caller sent and never compares their count with sqlite3_bind_parameter_count.

query with sql: "SELECT * FROM t WHERE id = ?" and no args (or args shorter than the number of ?) leaves the missing parameters unbound, which SQLite reads as NULL, so the query runs and returns zero rows with no error. Too many args does fail (SQLITE_RANGE), so only this direction is silent. An agent that forgets an argument gets a plausible empty result instead of a correction.

After a successful prepare, if args.length is less than sqlite3_bind_parameter_count(st), throw an engine error naming both numbers.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in dcd342e: after prepare, a differing count throws SQLITE_RANGE ("the statement has N parameter(s) but M argument(s) were given"). JniQueryTest covers too few and too many arguments on the real JNI path.

davidschachterADFA and others added 7 commits November 15, 2026 23:21
…say the server is read-only

A local app could hold all 8 connection slots without authenticating: the 30 s timeout applied per read and the token was checked after the whole request. The head now has an overall deadline (5 s), and Host, Origin, path and token are checked before the body. The initialize instructions no longer mention a read-write mode that does not exist.

Tests: sockets that send nothing or trickle bytes are closed within the deadline and the real client is then served; an unauthenticated request with an unsent body gets 401; the instructions do not mention read-write. All three fail with the fix reverted.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
…As on server connections

SQLite applies hard_heap_limit, soft_heap_limit and temp_store_directory to the whole process, so a client's PRAGMA hard_heap_limit=1 could make the app's own connections fail with SQLITE_NOMEM.

Test: each form (set and read) returns SQLITE_AUTH on a server connection; without the change all five return SQLITE_OK.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
With the app's database in rollback-journal mode, a server read failed at once with SQLITE_BUSY while the app held a write lock, exactly when the agent wants to look. The timeout is set in C and PRAGMA busy_timeout stays refused, so the client cannot change it.

Test: an app connection holds BEGIN EXCLUSIVE; a server read waits about 500 ms and succeeds once it is released, and reports SQLITE_BUSY after about 3 s if it is not. Without the timeout the first read failed after 0 ms with SQLITE_BUSY.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
…r count

Too few arguments left the missing parameters unbound, which SQLite reads as NULL, so the query ran and returned a plausible empty result. It now throws SQLITE_RANGE with a message naming both counts.

Test (JniQueryTest, the real JNI query path on a host JVM, run by test.sh): zero args for one parameter and one for two give SQLITE_RANGE; the first expectation was NULL before, and both fail with the check disabled.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
…ched through a link

list_databases matched the files of the app's databases folder against connection paths as strings, so on a phone (/data/user/0/<pkg> against /data/data/<pkg>) every open database was listed again as available: false. Both sides are now canonicalised before matching; paths are reported as the connections gave them.

Test: a folder listed through a symlink, and the reverse, list the open database once. Without the canonicalisation it was listed twice.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
test.sh (the extension's C tests under ASan/UBSan and TSan, and the JNI query test) ran in no workflow. The new workflow follows test-sqlite-js.yml and also triggers on the vendored SQLite headers test.sh compares against.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
Brings the base PR's nine newer commits into the stack: sqlite-js 1.4.2,
then the 1.4.3 release vendored with no patches, and the review answers.

One conflict, in ARCHITECTURE.md: both branches edited the sqlite-js
bullet, and this branch added the SQLite debugger bullet after it. Took
the base's sqlite-js bullet and kept the debugger bullet. The headers the
debugger builds against (subprojects/sqlite-js/upstream/libs) did not
change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
"No workflow runs either yet" has been false since the test-sqlite-debugger
workflow: it runs test.sh, the C and JNI tests. The JVM tests are still in
no workflow, which the line now says.

"Nothing has run in an app on a device" has been false since the device
runs recorded on ADFA-7135. What is left is a device run of the current
code, because those results predate the review fixes.

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

@davidschachterADFA davidschachterADFA left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-review of #2259 at 5b54c33 (medium effort). Verdict computed: COMMENT (MINOR findings only; GitHub also refuses APPROVE/REQUEST_CHANGES on a self-authored PR). Nothing here blocks merge.

MINOR

  • sqlitedbg_jni.c:325 - query runs only the first statement of a multi-statement string and reports success
  • DatabaseTools.kt:491 - a call's 50 s deadline starts before it waits for the global lock

NITPICK - none

Stack. Layer 1 of 4. Below: #2244. Above: #2260 (ADFA-7137) and #2262 (ADFA-7138) on this PR, and #2261 (ADFA-7139) on #2260. Tips: #2261 (2007193) and #2262 (810fe1c). The code cited here is not changed by the layers above (spot-checked at both tips), so the findings hold at the tips. Nothing was dropped as fixed higher up.

Rules applied. REVIEW.md and CLAUDE.md at the head. REVIEW.md is "a coaching doc, not a gate" and has no approve/request-changes rule, so the skill's default table applied.

Prior threads (judged on the code at this head, not on the replies).

  • McpProtocol.kt:69 read-write wording: fixed. INSTRUCTIONS now ends "Every tool is read-only."; McpProtocolTest asserts no "read-write".
  • McpHttp.kt:226 slow-client slots: fixed. readHead bounds the head by HEAD_DEADLINE_MS (5 s) whatever the read pattern, and allowed() runs Host/Origin/path/token before readBody. Tests drive silent and trickling sockets.
  • test.sh:1 no CI: fixed. test-sqlite-debugger.yml runs test.sh on changes to the module and to the headers it compares.
  • sqlitedbg.c:428 heap-limit PRAGMAs: fixed. hard_heap_limit, soft_heap_limit, temp_store_directory are in the authorizer's deny list, with read and write forms in the C tests.
  • sqlitedbg.c:454 busy timeout: fixed. sqlite3_busy_timeout(*db, SQLITEDBG_SERVER_BUSY_MS) is set after the authorizer, and busy_timeout stays denied; C test covers wait-then-succeed and SQLITE_BUSY after the timeout.
  • sqlitedbg_jni.c:346 missing bind args: fixed. The count is compared with sqlite3_bind_parameter_count in both directions before binding; JniQueryTest covers it.
    All six are fixed, so no thread needed a reply or an unresolve.

Merges and new commits. Merge e9e3f7d (#2244 into this branch): ARCHITECTURE.md resolved correctly (the sqlite-js bullet matches #2244's, the debugger bullet is kept, and the flavorless-modules lists name the debugger); CLAUDE.md and AndroidModuleConf.kt are consistent with it; the SQLite headers the debugger compares (sqlite-js/upstream/libs) are still present. 5b54c33 (README status lines): both corrected lines are true at this head (a workflow now runs test.sh; none runs the JVM tests).

Static review only: no build, no device. Leads from the built-in review that I discarded: VACUUM INTO bypass (SQLite 3.46 reports it to the authorizer as SQLITE_ATTACH, which the server denies; checked), more PRAGMAs (per-connection, not shared with the app), trace_v2 replacement (already documented in the README), close/query race (every close runs under the same lock), stale-connection edge case, per-poll buffer allocation, and Expect: 100-continue (no current client sends it).

jsize sql_len = (*env)->GetStringLength(env, sql);
const jchar *sql_chars = (*env)->GetStringChars(env, sql, NULL);
if (!sql_chars) return NULL;
rc = sqlite3_prepare16_v2(db, sql_chars, sql_len * 2, &st, NULL);

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MINOR: bridge_query prepares only the first statement of sql and drops the rest without saying so.

The tail pointer is passed as NULL. query with SELECT 1; SELECT * FROM t, or a comment followed by a statement, runs the first statement and returns a normal success; a lone comment prepares to a NULL statement and returns an empty result. An agent that sends two statements reads the first one's rows as the answer to both. Nothing reaches this today except an MCP client's own SQL, and the result is wrong data rather than damage, so MINOR.

Pass a tail pointer and throw an engine error when it holds anything but whitespace or comments, and when the statement is empty.

bind: List<Any?>,
offset: Long,
limits: QueryLimits,
): QueryResult = runChecked(checkedPath(args), sql, bind, offset, limits, clock() + DEADLINE_MS)

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MINOR: the 50 s deadline is computed here, before runChecked waits for lock, so a call queued behind a slow one starts with less time than it asked for.

Call A runs a query for 45 s while call B (a second client connection, or an agent making parallel tool calls) waits on synchronized(lock). B's deadline is already 45 s old when it gets the lock, so a query that needs 10 s fails with "the query ran past its time limit", and one queued behind a full 50 s query fails with "the time limit passed before the query started". The lock serializes every tool, so any slow query can cause this. Today it needs two concurrent calls and a slow first one.

Compute the deadline inside runChecked, after the lock is held (pass the budget, not the instant).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants