apk-reverse/docs/tool-verification/EXTENSION-dexsql.md

# Extension verification — dexsql, the SQL query layer (parity, decode, cache, MCP)

Covers the pass that adopted `dexsql` as a third indexer beside `rasc`/`droidasc`/`ddc` and
registered it as the `dex_query_sql` capability. Strength labels as this directory's README defines
them.

Reference environment: Windows 10.0.26100, PowerShell 7, Python 3.14.0, no device attached. The tool
is a release download (`dexsql-windows-amd64.exe`, v0.1.0, 21,365,760 B, sha256
`f354ebcf715de9a66ef8ebe08b2b36807ab58e25cd5a1c0812e497fc1fcfc448`) — no build step, no Python, no
JVM, no Android SDK.

**Headline: the class-definition parity check passes on all four archives — identical to `rasc`,
`droidasc` and `ddc`, zero differences either way — and the string cross-reference agrees site for
site. Three claims came back *smaller* than they could have been sold: the persistent cache is not a
speed switch, `decode` emits smali rather than Java, and the SQL match semantics are not `findrefs`'s.
The MCP surface was exercised to a tool listing, not end to end from a client.**

---

## 1. Class-definition parity — observed

The check that decides whether a new indexer may be trusted for location questions at all, and the
same comparison `rasc_build.py --verify` performs between `rasc` and `droidasc`. Each tool prints
class identity in its own shape, so each output is parsed per format and normalised to a DEX
descriptor before comparing — a single regex over all four outputs measures the regex, not the tools
(this pass's own first defect: an unescaped `$` in a descriptor pattern silently dropped classes whose
names contain `$` or non-ASCII characters, and reported `droidasc` as 38 classes where it returns 647).

| Archive | dexsql | rasc | droidasc | ddc | verdict |
|---|---|---|---|---|---|
| 1.4 MB MASTG challenge | 1,396 | 1,396 | 1,396 | 1,396 | identical |
| 4.3 MB hardened | 647 | 647 | 647 | 647 | identical |
| 38.7 MB hardened | 4 | 4 | 4 | 4 | identical |
| 34.8 MB app | 30,768 | 30,768 | 30,768 | 30,768 | identical |

Zero differences in either direction on every row. The two small counts are the hardened targets, not
the tools: the business dex is encrypted inside a shell and is in no DEX any of the four can read.

Full class listing, best of 3, stdout redirected to a file — the same shape for all four tools:

| Archive | dexsql | rasc | droidasc | ddc |
|---|---|---|---|---|
| 1.4 MB / 1,396 classes | 0.035 s | 0.028 s | 0.149 s | 0.109 s |
| 4.3 MB / 647 classes | 0.031 s | 0.025 s | 0.139 s | 0.099 s |
| 38.7 MB / 4 classes | 0.040 s | 0.021 s | 0.156 s | 0.092 s |
| 34.8 MB / 30,768 classes | 0.136 s | 0.055 s | 0.200 s | 0.156 s |

The `rasc` and `droidasc` columns reproduce this repository's earlier figures for the same 34.8 MB
archive (0.048 s / 0.190 s), which is what makes the new column comparable rather than merely new.
`dexsql` is 1.5× faster than the Python indexer and 2.5× slower than the Rust one, so **it does not
replace `rasc` for a plain class list** — it answers questions the other two cannot express.

## 2. Cross-reference parity, and the semantics that differ — observed

```
$ dexsql query --input <1.4 MB challenge> --sql \
    "SELECT DISTINCT method_class, method_name FROM method_strings WHERE value LIKE '%http%'"
Landroid/support/v4/content/res/TypedArrayUtils; | hasAttribute
Landroid/support/v4/text/util/LinkifyCompat;     | addLinks
Landroid/support/v4/util/PatternsCompat;         | <clinit>
```

`rasc findrefs … string http` and `droidasc findrefs … string http` return exactly those three sites,
and `ddc findrefs` agrees. **The matching semantics differ, and the difference is a trap worth
recording:** `findrefs` matches a *substring*, while SQL needs `LIKE '%…%'`. `WHERE value = 'http'`
returns **zero rows** and is not a broken query — no method in that archive holds a literal that *is*
`http`. A first pass read that empty result as a tool defect; the control was the same query with
`LIKE`, which reproduced ASC's answer exactly.

## 3. `decode` against `ddc disasm` — observed

```
$ dexsql decode --input <challenge> --method 'Lsg/vantagepoint/uncrackable3/MainActivity;->verifyLibs()V'
.method private verifyLibs()V
    .registers 14
    const-string v0, "UnCrackable3"
    new-instance v1, Ljava/util/HashMap;
    ...
```

The instruction sequence matches `ddc disasm <challenge> sg.vantagepoint.uncrackable3.MainActivity.verify`
line for line on that method. `decode` emits **smali, not Java** — that is a feature for the
bytecode-level decision `dex-patching.md` requires, and a limitation when the question is Java-level,
where `ddc getclass` still owns it. A missing class exits 1 with `Error: not_found: selected file,
method, or class not found`.

## 4. The persistent cache is not a speed switch — observed

```
$ dexsql prepare-cache --input <34.8 MB app> --output cache     # 0.196 s, writes cache.dxc2 34,481,119 B
$ dexsql query --input <app> --full --sql "SELECT count(*) FROM method_calls"      # 0.121 s
$ dexsql query-cache --cache-file cache/cache.dxc2 --sql "SELECT count(*) FROM method_calls"   # 0.098 s
$ dexsql query --input <app> --full --sql "<top-20 GROUP BY over method_calls>"    # 0.470 s
$ dexsql query-cache --cache-file cache/cache.dxc2 --sql "<same aggregate>"        # 0.458 s
```

**Under 20%, not an order of magnitude**, because parse-and-build is already 0.12 s on that archive.
On the 38.7 MB sample the cache is a net *loss* (0.071 s from cache against 0.042 s direct). The
honest claim is "hold one dataset across many queries in a long session", not "queries get fast" —
and the cache file is roughly the size of the source archive.

## 5. Error surface and read-only enforcement — observed

Every failure exits 1 with a named cause, and writes are refused:

| Input | Result |
|---|---|
| missing class | `Error: not_found: selected file, method, or class not found` |
| missing file, or a non-dex file | `Error: load_failed at load_inputs: failed to prepare native input cache` |
| unknown column | `Error: invalid_query at execute_sql: unknown column `nope`` |
| unknown relation | `Error: invalid_query at execute_sql: unknown relation `nope`` |
| `DELETE FROM classes` | `Error: SQL statement 1 failed` — the statement is rejected |

## 6. The MCP surface, exercised to its boundary — observed (listing), unverified (client)

`dexsql mcp` speaks JSON-RPC over stdio; an `initialize` + `tools/list` handshake returns 13 tools:
`open_dataset`, `list_datasets`, `close_dataset`, `list_tables`, `describe_table`, `query`, `decode`,
`get_manifest`, `get_manifest_components`, `list_resource_files`, `read_resource`, `query_resources`,
plus an embedded English documentation catalog on `resources/list`. Every list-shaped result carries
`next_offset`, and the resource tools read `resources.arsc` and archive entries without extracting
them to disk. Quotas are explicit (`--max-datasets`, `--max-input-bytes`, `--max-dex-bytes`,
`--max-output-bytes`, `--timeout-ms`), and the server's own instructions say a running timeout closes
the affected dataset. **No client session was driven against it in this pass** — the tool list and the
schemas are what is measured.

## 7. What this pass deliberately did not do

- No Linux or macOS asset was downloaded or run: the release publishes `linux-amd64`, `linux-arm64`
  and `darwin-arm64` binaries and none was exercised.
- No MCP client session: the handshake and tool inventory were read, the tools were not called.
- No patching through `dexsql`: it has no write path, and nothing here claims one.
- No claim about a packed target beyond the parity row: on both hardened archives it returns the same
  class count as the other three tools, and the payload is not in any readable DEX.

## 8. Facts this pass pinned for the next one

- **A new indexer earns trust by the class-set comparison, not by its feature list.** The parity check
  is cheap (four tools, four archives, seconds) and it is the only evidence that separates "answers
  location questions correctly" from "parses most of the file". Do it before adopting the next one.
- **Parse each tool's own output format.** The first pass compared four differently-shaped outputs
  with one regex and produced two false verdicts — one an unescaped `$`, one a dotted-vs-descriptor
  mismatch. A comparison harness is itself a tool that needs a control.
- **`doctor.py` is the registration surface.** Adding `tool:dexsql` plus a `dex_query_sql` capability
  makes G2 report the tool instead of guessing, and `INSTALL_HINTS` is where a release download or a
  from-source build declares the location this kit's own install step produces, so a machine that
  followed the instructions is not reported BLOCKED.
- **The three indexers now have a stated division of labour:** `rasc` locates fastest, `droidasc` is
  the Python cross-check, `dexsql` answers joins and aggregates (and carries the resource model).
  Writing that down is what keeps the next pass from re-deriving it.