1.4 The vocabulary
The toolkit uses a small number of words in a strict sense. This table is the authoritative definition; later chapters assume it.
| Word | Definition |
|---|---|
| module | One of sixty-one shell scripts under modules/, identified by a two-digit number. |
| verb | One --flag operation of a module. Verbs return the exit codes of §1.2. |
| store | The directory under loot/ a module writes. Usually one TSV with a fixed header. |
| row | One record in a store. A row is evidence; a deleted row is a lost finding. |
| case | A named collection under the casebook, into which stores can be exported as evidence. |
| capture | A pcap or a pcapng on disk. Modules that read captures never invent one. |
| target | The cell, network or device the operator has declared that the session is about. |
| bench | This machine and its radios, as reported by the header strip and 05_field_kit.sh. |
| node | A machine registered in the fleet that a module can be pointed at instead of the local bench. |
| transport | How a node is reached: local, ssh, adb, serial, qmi, mbim, diag, sms. |
| class | What a node is, as measured: dongle, CPE, handset, single-board computer, core, relay. |
| capability | A measured ability of a node, e.g. sdr-tx, gsmtap, pcsc, core. |
| role | A suggested use for a node, derived from its capabilities: sensor, catcher, core, relay. |
| stream | A node's ongoing event feed, drained from a spool file with a byte cursor. |
| run | One bounded execution of a module, with a name, logs and evidence rows. |
| evidence | A stored fact with a source and a confidence: observed or advertised. |
| chip | A stated precondition on a card: needs a radio, needs a capture, transmits, reads. |
| gate | One of the tools/check-*.sh scripts that fails the tree when a claim stops being true. |
| referee | An independent oracle (tshark, pycrate, a published vector) used to check our own decoder. |
| handoff | Exit code 3. The work moved somewhere this toolkit cannot follow, and it says where. |
| selftest | A module's --selftest, which asserts its own behaviour and prints a count. |
Three words appear on every screen and must not be confused:
- ready — the operation can run with what is present.
- degraded — it can run, with a stated limitation.
- handoff — it cannot run here; the next step is elsewhere, and the message names it.
Part 1 has stated what the toolkit is, the rules it keeps, the surfaces that express them and the words they use. Part 2 is practical: dependencies, radios, and the first hour of work from an empty machine to a case that contains evidence.