feat: add Lambda Dispatcher Resolver tool and APK-tooling ideas backlog

Resolves R8-merged synthetic lambda-dispatcher classes (the krb/aie/esk/ftw
pattern this project has repeatedly had to resolve by hand during APK
reverse engineering) to their exact smali+JADX source evidence, via a
list/resolve CLI over androguard (DEX structure) + a narrow smali reader
(packed-switch/sparse-switch/if-chain resolution) + a JADX case-block
correlator. All SPEC.md acceptance criteria pass (12 pytest cases) against
the real decompiled APK.

Two bugs were caught only by verifying against the raw smali rather than
assuming: baksmali's pswitch_N label suffix does not match the case value
it's reached by, and a packed-switch's "no case matched" fallthrough sits
right after the switch opcode, not after the last case label.

Also fixes a design mistake in the tool's own SPEC.md: an earlier draft
proposed committing byte-exact smali/JADX excerpts as test fixtures, which
is exactly what PROJECT_RULES.md §8 rule 20 bans (decompiled Google code,
even as research output). Tests now read from the maintainer's local,
already-gitignored reverse-engineering/apk/ tree and skip themselves when
it's absent; .gitignore updated to keep this tool's own venv/caches (but
never decompiled content) out of history the same way.

BACKLOG.md records the broader tooling ideas (UUID/BLE context
reconstruction, dataflow, schema batch-extraction, payload decoding,
version diffing) raised while scoping this tool, for later triage - none
designed or committed to being built yet.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: tedsluis

.gitignore

@@ -23,6 +23,17 @@ local.properties
 reverse-engineering/apk/
 *.apk
 
+# Lambda Dispatcher Resolver tool (reverse-engineering/tools/lambda_dispatcher_resolver/):
+# its own Python source is tracked normally (original tooling code, not derived APK content),
+# but its virtualenv/caches are not, and — same rule as above, same reason — it must never gain
+# a committed copy of decompiled smali/JADX output under its own tests/ directory either; its
+# test suite runs against the maintainer's local reverse-engineering/apk/<version>/ tree instead
+# and skips itself when that tree isn't present (see that tool's own SPEC.md §11 and tests/).
+reverse-engineering/tools/*/.venv/
+reverse-engineering/tools/*/*.egg-info/
+**/__pycache__/
+.pytest_cache/
+
 # OS/editor cruft
 .DS_Store
 Thumbs.db

TODO.md

@@ -378,6 +378,23 @@ lower priority than finishing ANC/Battery/EQ):**
 
 ## Phase 2 — APK reverse engineering
 
+- [x] **Added 2026-09-16, implemented same day — Lambda Dispatcher Resolver.**
+      `reverse-engineering/tools/lambda_dispatcher_resolver/` (`SPEC.md` for the design; `README.md`
+      for usage) mechanically resolves R8-merged synthetic lambda-dispatcher classes (the
+      `krb`/`aie`/`esk`/`ftw` pattern this project has repeatedly had to resolve by hand — see
+      `REVERSE_ENGINEERING.md`'s `qhr`/`fye` entry and `frb`-`gjv` entry) to their exact smali+JADX
+      source evidence, via a `list`/`resolve` CLI over androguard (DEX structure) + a narrow smali
+      reader (packed-switch/sparse-switch/if-chain resolution) + a JADX case-block correlator. All of
+      `SPEC.md` §10's acceptance criteria pass (12 pytest cases, including the adversarial
+      out-of-range-discriminator fixture) against the real, locally-decompiled APK — no decompiled
+      content is committed anywhere in the tool's own tree (a design mistake in `SPEC.md`'s original
+      §11 text, caught and corrected during implementation; see that section's own note). Deliberately
+      scoped to only this one capability — a possible future broader UUID/BLE-analysis pipeline is
+      tracked as ideas, not designed, in `reverse-engineering/tools/BACKLOG.md`.
+      **Not yet done:** wiring this into an actual APK-RE session's workflow (e.g. re-running it
+      against `MaestroEndpointService`'s own multibinding-assembly search, still open per
+      `REVERSE_ENGINEERING.md`'s own entry) — the tool exists and is tested, but hasn't yet been used
+      to advance a real open protocol question.
 - [x] **Groundwork/tooling — done 2026-08-30.** Governance, storage, and procedure now in place so
       the actual analysis work below can start; none of it constitutes analysis having happened yet:
       `DECISIONS.md` ADR-017 (supersedes ADR-003) permits AI mechanical assistance — search, `pbtk`

reverse-engineering/tools/BACKLOG.md

@@ -0,0 +1,113 @@
+# BACKLOG.md — Future APK-analysis tooling ideas
+
+A parking lot for tooling ideas raised while designing and building
+[`lambda_dispatcher_resolver/`](lambda_dispatcher_resolver/SPEC.md), so they aren't lost and can be
+triaged later. **Nothing here is designed, approved, or committed to being built** — this is
+deliberately one level less formal than `lambda_dispatcher_resolver/SPEC.md`. An idea graduates out
+of this file by getting its own spec document (following `lambda_dispatcher_resolver/SPEC.md` as
+the template) once the maintainer decides to pursue it.
+
+## Governance that applies to every idea below, unconditionally
+
+Any tool built from this list operates inside the exact same boundary
+`lambda_dispatcher_resolver/SPEC.md` §8 already established, not a fresh negotiation each time:
+
+- Mechanical assistance only (`DECISIONS.md` ADR-017) — a tool may search, extract, and correlate;
+  it never decides a finding's relevance to the Bluetooth protocol, and never writes into
+  `REVERSE_ENGINEERING.md`/`PROTOCOL.md`/`DECISIONS.md`/any `CAP-NNN-FINDINGS.md` itself.
+- **No decompiled APK content is ever committed, in any form, including as test fixtures** —
+  `lambda_dispatcher_resolver/SPEC.md` §11 documents a real mistake this project's own first attempt
+  at this made (committing byte-exact smali/JADX excerpts as "just test fixtures"), caught only
+  after the fact against this repo's own `.gitignore` comment quoting `PROJECT_RULES.md` §8 rule 20.
+  Every future tool's tests read from the maintainer's local, gitignored
+  `reverse-engineering/apk/<version>/` tree and skip themselves when it's absent — never a
+  committed copy.
+- Reuse this project's own FACT/HYPOTHESIS/ASSUMPTION/OPEN QUESTION vocabulary (`PROJECT_RULES.md`
+  §1) for anything a tool's output implies about protocol meaning — never invent a parallel
+  confidence taxonomy (an earlier draft proposal for this tooling area used
+  observed/inferred/confirmed; rejected for exactly this reason).
+- Test against already-confirmed findings as regression fixtures before trusting a tool on
+  something new (`lambda_dispatcher_resolver/SPEC.md` §10's own worked-example discipline,
+  generalizing `AGENTS.md` §11's "test against real capture fixtures" rule to APK-analysis tooling).
+- Decide each tool's own git-tracking boundary explicitly (source code: yes; anything derived from
+  or copied out of the decompiled APK: no) rather than assuming — per the point above.
+
+## Suggested (not binding) priority order, if any of these are pursued
+
+1. An androguard-based general structural code index (below) — natural next step once
+   `lambda_dispatcher_resolver` already has androguard wired up; replaces ad hoc
+   `grep -rl "extends X"`/`grep -rn "LFoo;->bar("` searches with a real query.
+2. UUID extraction + BLE/GATT context reconstruction — the original idea's own core ambition.
+3. Limited dataflow analysis — highest risk/effort of the group; do this only after (1) and (2)
+   prove the approach is worth the investment, and scope it to single-basic-block tracking only at
+   first (per the original proposal's own §6).
+4. Schema/payload/version tooling (items below) — independently useful, no dependency on 1-3.
+
+This ordering is a lens, not a commitment — the maintainer may pick any subset in any order.
+
+---
+
+## Idea: general androguard-based structural code index
+
+Generalizes `lambda_dispatcher_resolver`'s Layer 1 beyond just lambda-dispatcher detection into a
+standing query tool: "list every class implementing interface X," "find every caller of method
+Y" (an XREF search — exactly what a manual `grep -rn "Lgiz;->p("` search stood in for during the
+2026-09-15 `gjv.p()` trace, `REVERSE_ENGINEERING.md`'s `frb`-`gjv` entry), "list every subclass of
+Z." Cheap once androguard is already a dependency; would remove most remaining need for ad hoc
+smali `grep` during a research session.
+
+## Idea: UUID extraction + BLE/GATT context reconstruction
+
+The original, broader ambition this backlog's own tooling effort started from: UUID → usage
+location → BLE operation (`BluetoothGattCharacteristic`/`writeCharacteristic`/
+`setCharacteristicNotification`/etc.) → possible protocol role, as a relationship graph rather than
+a bare list of UUID strings. Large scope — likely its own multi-phase spec document if pursued, and
+depends on the structural code index above for the "usage location" half.
+
+## Idea: limited dataflow analysis
+
+Tracking a byte-array's construction (`new-array`/`fill-array-data`/`aput-byte`, or equivalent
+protobuf-builder calls) forward to the `writeCharacteristic`/`WriteSetting` call site it ends up
+at. The highest-risk item on this list — general dataflow across branches/loops is genuinely hard
+to get right and to trust. If ever attempted, scope the first version to straight-line,
+single-basic-block flows only, and require the same worked-example test discipline as
+`lambda_dispatcher_resolver` before it's used on anything not already manually verified.
+
+## Idea: protobuf/`RawMessageInfo` schema batch-extractor
+
+`scripts/decode_rawmessageinfo.py` already recovers one `GeneratedMessageLite` class's schema at a
+time (this is how `qhr`/`qjc`/`qjb`/etc. were originally recovered). A batch mode that scans the
+whole decompiled tree for every class matching that same generated-message shape and builds a full
+schema register automatically would remove most of the remaining manual work in
+`REVERSE_ENGINEERING.md`'s own schema-recovery entries.
+
+## Idea: wire-payload-vs-schema auto-decoder
+
+Given raw hex bytes + a DLCI, attempt to decode against every schema/envelope this project already
+knows about (the DLCI 0x08 `[Group][Code][Length][Value]` TLV shape, `qhr`'s protobuf oneof, the
+Fast Pair Message Stream shape) and report the best structural match. Generalizes the manual
+TLV-walk/protobuf-oneof-decode work redone by hand in most `CAP-NNN-FINDINGS.md` sessions (e.g.
+`CAP-050-FINDINGS.md` §3's own `scripts/decode_dlci08_tlv.py` one-off) into one reusable, testable
+decoder.
+
+## Idea: APK version-diff tool
+
+A class-level and string-level diff between two decompiled APK versions, keyed off
+`reverse-engineering/APK_VERSIONS.md`'s own version index. `APK_REVERSE_ENGINEERING_PROCEDURE.md`
+already names "the diff-against-previous-version pass" as a planned step; this would be its actual
+implementation, relevant the next time Google ships a companion-app update.
+
+## Idea: tshark/DLCI-reassignment helper library
+
+Every capture-analysis session re-derives, by hand, which session-local DLCI number currently
+carries which logical channel (RFCOMM DLCI numbers are session-local, not fixed — `CAP-001-FINDINGS.md`
+§2, `DECISIONS.md` ADR-018) by matching content signatures (e.g. `CAP-050-FINDINGS.md` §2's own
+`"google-pixel-buds-pro-v1"` re-identification after DLCI 0x08 turned out to carry HFP on one
+reconnect). A small Python wrapper standardizing "pull every payload for the channel matching
+content signature X, across every reconnect in this log" would remove a real, recurring
+misattribution risk from that manual process.
+
+---
+
+---
+https://github.com/tedsluis/opencontrolpixelbudspro2/blob/main/reverse-engineering/tools/BACKLOG.md - https://tedsluis.github.io/opencontrolpixelbudspro2/reverse-engineering/tools/BACKLOG

reverse-engineering/tools/lambda_dispatcher_resolver/README.md

@@ -0,0 +1,47 @@
+# Lambda Dispatcher Resolver
+
+See [`SPEC.md`](SPEC.md) for the design, the structural detection rules, and the governance
+constraints this tool operates under (it never writes to `REVERSE_ENGINEERING.md`/`PROTOCOL.md`/
+`DECISIONS.md`, and never judges a branch's relevance to the Bluetooth protocol — SPEC.md §8).
+
+## Setup
+
+Requires the maintainer's own locally-decompiled APK tree to already exist under
+`reverse-engineering/apk/<version>/` (see `APK_REVERSE_ENGINEERING_PROCEDURE.md`) — this tool never
+ships or commits any decompiled content of its own (SPEC.md §11).
+
+```sh
+cd reverse-engineering/tools/lambda_dispatcher_resolver
+uv venv .venv --python 3.12          # androguard's own dependency set targets 3.10-3.13
+uv pip install --python .venv/bin/python -e ".[dev]"
+```
+
+## Usage
+
+```sh
+# List every candidate lambda-dispatcher class in the APK (SPEC.md §3's structural shape check):
+.venv/bin/python3 -m lambda_dispatcher_resolver.cli list \
+  --apk-root ../../apk/v1.0.955078536-10253511
+
+# Resolve one (class, discriminator) pair to its exact smali + JADX evidence:
+.venv/bin/python3 -m lambda_dispatcher_resolver.cli resolve \
+  --apk-root ../../apk/v1.0.955078536-10253511 \
+  --class aie --discriminator 7
+```
+
+`--class` accepts the short form (`aie`), the default-package dotted form (`defpackage.aie`), or
+the raw smali descriptor (`Laie;`) — all three resolve to the same class.
+
+## Tests
+
+```sh
+.venv/bin/python3 -m pytest tests/ -v
+```
+
+The suite reads directly from the same local `reverse-engineering/apk/v1.0.955078536-10253511/`
+tree used above and is **skipped** (not failed) if that tree isn't present — see `tests/test_resolver.py`'s
+own module docstring for why it deliberately does not ship committed fixture copies of decompiled
+code.
+
+---
+https://github.com/tedsluis/opencontrolpixelbudspro2/blob/main/reverse-engineering/tools/lambda_dispatcher_resolver/README.md - https://tedsluis.github.io/opencontrolpixelbudspro2/reverse-engineering/tools/lambda_dispatcher_resolver/README