Add GPL QCSuper Android bridge backend

Cargo.toml

@@ -3,6 +3,7 @@ members = [
     "crates/6grok-core",
     "crates/6grok-agent",
     "crates/6grok-api",
+    "crates/6grok-qcsuper",
 ]
 resolver = "2"
 

README.md

@@ -15,6 +15,8 @@ The working implementation currently provides:
 - passive Qualcomm DIAG capture and raw replay;
 - active Qualcomm `DIAG_LOG_CONFIG_F` capability probing and log-mask configuration;
 - capability-aware `signaling`, `radio` and `full` Qualcomm profiles;
+- GPL QCSuper interoperability backend for rooted Android `/dev/diag` through QCSuper `adb_bridge`;
+- QCSuper-derived signaling and IP/DPL capture profiles with pinned provenance;
 - normalized JSONL capture/replay;
 - MediaTek 9-byte parser-record ingestion;
 - Samsung MIPC-style and raw-PDU ingestion using the parser's synthetic namespaces;
@@ -26,19 +28,19 @@ The working implementation currently provides:
 ```text
 modem / phone
      |
-     | DIAG / SDM / vendor trace
+     | DIAG / QCSuper bridge / SDM / vendor trace
      v
-+-------------+       +-------------+       +------------------+
-| 6grok-agent | ----> | 6grok-core  | ----> | fivegrok-parser  |
-+-------------+       +-------------+       +------------------+
-       |                     |                       |
-       | raw capture         | MessagePack           | decoded packets
-       v                     v                       v
-    replay              +-----------+          JSON / history
-                        | 6grok-api |
-                        +-----------+
-                         /    |     \
-                       REST   WS   GSMTAP -> Wireshark
++----------------+     +-------------+       +------------------+
+| 6grok-agent /  | --> | 6grok-core  | ----> | fivegrok-parser  |
+| 6grok-qcsuper  |     +-------------+       +------------------+
++----------------+            |                       |
+       |                       | MessagePack           | decoded packets
+       v                       v                       v
+ raw / JSONL              +-----------+          JSON / history
+                          | 6grok-api |
+                          +-----------+
+                           /    |     \
+                         REST   WS   GSMTAP -> Wireshark
 ```
 
 ## Build
@@ -55,9 +57,9 @@ rustup target add aarch64-unknown-linux-musl
 cargo build --release --target aarch64-unknown-linux-musl -p sixgrok-agent
 ```
 
-The produced executable is named `6grok-agent`.
+The primary edge executable is named `6grok-agent`. The GPL QCSuper interoperability executable is `6grok-qcsuper`.
 
-## Qualcomm capture
+## Qualcomm serial/USB capture
 
 Passive capture from a modem that is already producing DIAG logs:
 
@@ -97,6 +99,45 @@ Replay a raw Qualcomm capture:
 cargo run -p sixgrok-agent -- replay capture.bin
 ```
 
+## Rooted Android via QCSuper
+
+`6grok-qcsuper` interoperates with the TCP endpoint created by QCSuper's GPL `adb_bridge`. This is useful on Qualcomm Android devices where `/dev/diag` requires the diagchar setup logic already implemented and tested by QCSuper.
+
+QCSuper's default bridge port is TCP 43555. Once its bridge is running and forwarded by ADB, probe the modem from 6grok:
+
+```bash
+cargo run -p sixgrok-qcsuper -- probe
+```
+
+Capture QCSuper's established signaling selection:
+
+```bash
+cargo run -p sixgrok-qcsuper -- capture --profile signaling
+```
+
+Capture Qualcomm IP/DPL records:
+
+```bash
+cargo run -p sixgrok-qcsuper -- capture --profile ip
+```
+
+Or request the union and send normalized frames directly to a remote API service:
+
+```bash
+cargo run -p sixgrok-qcsuper -- capture \
+  --profile full \
+  --frame-capture android.jsonl \
+  --server 10.0.0.2:5566
+```
+
+For a non-default forwarded endpoint:
+
+```bash
+cargo run -p sixgrok-qcsuper -- capture --bridge 127.0.0.1:43556 --profile signaling
+```
+
+The backend does not vendor QCSuper's Android executable. QCSuper remains the source of the on-device `/dev/diag` bridge; 6grok speaks its HDLC-over-TCP interface and performs DIAG log configuration itself. The integration is pinned to QCSuper commit `aa555b4f7f25f7a8bf4e5afd4dcb884edf2f6735` and its source-level provenance is recorded in [`THIRD_PARTY.md`](THIRD_PARTY.md).
+
 ## Service / remote agents
 
 Start the aggregation service:
@@ -149,10 +190,10 @@ See [`docs/MULTI_VENDOR.md`](docs/MULTI_VENDOR.md).
 
 6grok intentionally uses a **multi-license architecture**.
 
-- The combined `6grok-agent` application is `GPL-3.0-or-later`.
+- The combined `6grok-agent` application and `sixgrok-qcsuper` backend are `GPL-3.0-or-later`.
 - Original reusable `sixgrok-core` and `sixgrok-api` code is available under `MIT OR GPL-3.0-or-later` where indicated by repository metadata.
 - Third-party files retain their exact upstream license, copyright and notices.
-- QCSuper (`GPL-3.0-or-later`) and SCAT (`GPL-2.0-or-later`) source may be reused/adapted in the GPL application with explicit provenance.
+- QCSuper (`GPL-3.0-or-later`) and SCAT (`GPL-2.0-or-later`) source may be reused/adapted in GPL application components with explicit provenance.
 - MIT, Apache-2.0 and compatible BSD material may also be incorporated while retaining its original terms.
 - `GPL-2.0-only`, AGPL and other licenses outside the reviewed compatibility policy are not imported into the combined application without explicit review.
 
@@ -164,7 +205,7 @@ The root [`LICENSE`](LICENSE) contains the GPLv3 license text. See [`docs/LICENS
 
 - native MediaTek mdlogger/CCCI acquisition;
 - validated native Samsung Shannon SDM acquisition;
-- additional Qualcomm Android/USB transports and QCSuper-derived capabilities;
+- direct Android diagchar backend where it adds value beyond QCSuper bridge interoperability;
 - GPS/NMEA/gpsd synchronized location frames;
 - AT-monitor fallback for DIAG-locked devices;
 - persistent capture/database backend;

REUSE.toml

@@ -31,6 +31,7 @@ path = [
   "crates/6grok-agent/src/profiles.rs",
   "crates/6grok-agent/src/qualcomm.rs",
   "crates/6grok-agent/src/vendor_records.rs",
+  "crates/6grok-qcsuper/Cargo.toml",
 ]
 SPDX-FileCopyrightText = "2026 mbound"
 SPDX-License-Identifier = "GPL-3.0-or-later"

THIRD_PARTY.md

@@ -55,15 +55,40 @@ Its upstream-specific MIT copy remains preserved in `THIRD_PARTY_LICENSES/fivegr
 
 ## QCSuper
 
-QCSuper declares GPL-3.0+ / GPL-3.0-or-later. Its code may now be copied or adapted into GPL-covered 6grok application components. When this is done, keep upstream copyright/license information and add a provenance comment identifying the upstream commit and source path.
+QCSuper is currently pinned for provenance at:
+
+`aa555b4f7f25f7a8bf4e5afd4dcb884edf2f6735` (QCSuper 2.1.3, 2026-07-23)
+
+QCSuper declares GPL-3.0+ / GPL-3.0-or-later. Its code may be copied or adapted into GPL-covered 6grok application components. The first integration is `crates/6grok-qcsuper`, a Rust interoperability backend for QCSuper's Android `/dev/diag` TCP bridge.
+
+Upstream material used for that backend:
+
+| Upstream path | 6grok use |
+|---|---|
+| `src/qcsuper/inputs/adb.py` | bridge address/transport behavior and HDLC-over-TCP interoperability |
+| `src/qcsuper/inputs/adb_bridge/adb_bridge.c` | bridge framing/stream behavior and Android `/dev/diag` implementation reference |
+| `src/qcsuper/modules/_enable_log_mixin.py` | translated/adapted signaling and IP/DPL capture selections |
+| `src/qcsuper/inputs/_hdlc_mixin.py` | DIAG HDLC interoperability reference |
+
+The bridge client itself is written in Rust for 6grok and carries GPL-3.0-or-later SPDX metadata. QCSuper-derived log selections explicitly record the upstream commit/path in source comments. The standard GPLv3 text is retained under `LICENSES/GPL-3.0-or-later.txt` and as the repository root `LICENSE`.
 
 Do not move QCSuper-derived code into a component advertised as MIT-only. If functionality needs to be shared with a permissive library, isolate an independently written interface/data model from the GPL-derived implementation.
 
+### Qualcomm log-mask semantics cross-check
+
+QCSuper calls the range value a log-mask bit size in parts of its implementation, but Qualcomm DIAG sources and Osmocom model the protocol field as inclusive `last_item`. 6grok therefore deliberately retains an inclusive mask length of `floor(last_item / 8) + 1` bytes. This is covered by regression tests, including a boundary where `last_item == 8` and bit 8 must occupy a second byte.
+
+References used for this protocol cross-check include Qualcomm `diaglog.c` implementations and `osmocom/osmo-qcdiag/src/diag_log.c`; no Qualcomm source is copied into the dual-licensed core.
+
 ## SCAT
 
+SCAT is currently pinned for provenance at:
+
+`361ff551a4fbb30789c46750c00586682a7a9b26` (2026-09-03)
+
 SCAT declares `GPL-2.0-or-later`. This is compatible with the GPLv3 6grok application because the "or later" grant permits selecting GPLv3 terms for the combined work.
 
-SCAT-derived files must retain their `GPL-2.0-or-later` identity and copyright. Do not rewrite their file-level SPDX identifier to GPL-3.0 merely because the combined binary is distributed under GPLv3 terms.
+SCAT is being used to corroborate Qualcomm DIAG behavior and as the primary implementation reference for native Shannon/MediaTek acquisition work. SCAT-derived files must retain their `GPL-2.0-or-later` identity and copyright. Do not rewrite their file-level SPDX identifier to GPL-3.0 merely because the complete executable is conveyed under compatible GPLv3 terms.
 
 ## Apache/BSD sources
 

crates/6grok-qcsuper/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "sixgrok-qcsuper"
+version = "0.1.0"
+edition.workspace = true
+license = "GPL-3.0-or-later"
+repository.workspace = true
+rust-version.workspace = true
+
+[[bin]]
+name = "6grok-qcsuper"
+path = "src/main.rs"
+
+[dependencies]
+sixgrok-core = { path = "../6grok-core" }
+anyhow.workspace = true
+clap.workspace = true
+crc.workspace = true
+serde_json.workspace = true