# Echolot Capability Prober

A throwaway diagnostic app that runs the borderline **no-root** operations from the Echolot
feasibility matrix on a **real device** and reports what actually works on that Android build.
Its job is to turn "should work / needs verification" spec notes into observed facts before the
production app hardens around them. Several probes naturally evolve into the tier-detection code
the real app needs anyway.

Package / appId: `app.echo_lot.prober` (derived from the echo-lot.app domain; hyphen → underscore
because Android application IDs and Java packages cannot contain hyphens).

## What it probes

| Probe | Question it answers | Expected result |
|---|---|---|
| `link.snapshot` | What does `LinkProperties` expose per active network? | SUPPORTED |
| `icmp.ping4` / `icmp.ping6` | Does the unprivileged ICMP datagram socket work? | SUPPORTED (no root needed) |
| `sockopt.matrix` | Are IP_TTL, IP_TOS, IP_RECVERR, IP_MTU_DISCOVER accepted? | SUPPORTED / PARTIAL |
| `trace.errqueue_reachable` | Is errqueue traceroute reachable from the Os API? | likely PARTIAL → needs a small native shim |
| `multinetwork.request_and_bind` | Can we hold + bind Wi-Fi / cellular / ethernet concurrently? | SUPPORTED for links present now |
| `local.mdns_discover` | Does multicast reception / mDNS work with a MulticastLock? | SUPPORTED |
| `peer.ble_advertise` | Can this chipset advertise BLE (peer-mode channel)? | device-dependent |
| `shizuku.command_battery` | Does the Shizuku shell tier return neighbor table, RA routes, DHCP logs? | SUPPORTED if Shizuku running |

Each result carries a **verdict** (SUPPORTED / PARTIAL / UNSUPPORTED / INCONCLUSIVE / ERROR),
a one-line summary, and raw **evidence** (sockopt return codes, addresses, timings, and the actual
dump excerpts from the Shizuku commands — capturing the per-device format the real parsers must
handle). Export the whole run as JSON with the Export button and share it anywhere.

## Building

Needs Android Studio (Koala or newer) or a local Android SDK; **this repo was scaffolded without
network access to Google's Maven, so dependencies download on your first local build.**

```
# Point the build at your SDK (or let Android Studio create local.properties):
echo "sdk.dir=/path/to/Android/sdk" > local.properties

./gradlew :app:assembleDebug
./gradlew :app:installDebug     # with a device/emulator attached
```

The debug APK lands in `app/build/outputs/apk/debug/`.

## Using the Shizuku tier

1. Install [Shizuku](https://shizuku.rikka.app/) and start it via **wireless ADB pairing** (no root).
2. Launch the prober, tap **Run all probes**. The Shizuku probe requests permission on first use.
3. If Shizuku isn't running the probe reports INCONCLUSIVE (everything else still runs).

## Notes / known gaps

- Errqueue traceroute (`MSG_ERRQUEUE` recvmsg + cmsg parse) is expected to need a native C-over-JNI
  shim; this prober only confirms the sockopts + call-path availability. Wiring the shim is the
  next spike if the verdict is PARTIAL.
- Multi-network probe can only bind transports physically present at run time. To exercise USB
  ethernet, attach an adapter first.
- BLE advertising support is genuinely chipset-dependent; a UNSUPPORTED here is a real finding.

## Relationship to the specs

Result IDs mirror the `measurement-schema.md` test-type registry where one exists, and the JSON
report shape is a stripped-down cousin of the full measurement document. The specs live in
[`../docs/`](../docs/) — `feature-catalog-and-feasibility.md`, `measurement-schema.md`,
`probe-protocol.md`.