Skip to content

Station intelligence

Station intelligence turns protocol observations into investigable station relationships without erasing uncertainty. It correlates callsigns, decoded identity, frequencies, signal occurrences, receiver paths, and local reference data.

flowchart TB
    D[Decoder observations] --> N[Normalized station evidence]
    S[Signal detector tracks] --> N
    FCC[FCC SQLite corpus] --> E[Reference enrichment]
    CTY[CTY prefix data] --> E
    N --> ENTITY[Station/entity model]
    E --> ENTITY
    ENTITY --> INV[Investigation workspace]
    ENTITY --> MAP[Map relationships]
    ENTITY --> HIST[Capture-time history]

Evidence model

A decoded callsign is an over-the-air observation. An FCC record is a reference record. A matching string creates a qualified relationship, not proof that the licensee was the transmitter, at the listed address, using the listed station. RF remains stubbornly unwilling to file paperwork before propagating.

Each relationship retains source, observation time, decoder/job, lane/route, frequency, and validation state. Current presentation can change as stronger evidence arrives; raw evidence remains inspectable.

Only a protocol-identified transmitting station updates heard time, RF/SNR, receiver path or decoded geography. An addressed or mentioned callsign can receive ephemeral identity context without becoming a heard station. The adapter uses message roles, not token position or a plausible-looking locator: FT8's RR73 acknowledgement is not geographic evidence despite matching a four-character grid pattern.

One callsign may relate to multiple FCC unique system identifiers (USIs), including reassignment and inactive history. Provider unavailable, no match, active, inactive and ambiguous are distinct regulatory results; a non-U.S. no-match is not a decoder failure or a judgment about station authorization.

Synthetic application fixtures

Geographic and mailing fixtures document the public reference points, synthetic records and retained test relationships.

The decoder-event example and selected station/FCC tests use K0TESTX as a controlled synthetic identity. It exercises the application's permissive observation parser and U.S. prefix resolution without naming a licensee. Its five-letter suffix is outside the U.S. amateur callsign compositions in 47 CFR 2.302. It is not an on-air identity or an FT8 encoder test vector. For FCC or learned station diagnostics, replace the documented CALLSIGN variable with a record in the operator's selected dataset; an empty result for the placeholder is expected.

Capture history and replay identity

ftxObservation.ts derives rf-observation-v1 identity from receiver serial, path/profile, stable capture time, exact source-sample position, protocol, absolute RF rounded to 0.1 Hz for the textual key, and normalized message. Capture nanoseconds take precedence over the decoded slot timestamp; the normalized event time is the final fallback, not a fresh insertion/replay time. Decoder job, lane, browser session, event sequence, processing and replay identity are excluded. Re-decoding the same IQ reaches the same observation key; hearing it with another receiver remains a distinct observation.

First/last heard and current geography use capture-time ordering, not arrival order. Processing t3, t1, t2 must not overwrite the latest known RF state with the last database write. Raw observations and geographic history remain inspectable even when current presentation changes.

Storage and consumer ownership

rfsentry-station-intelligence-v1 keeps observations, aggregates, geographic assertions/evidence events, regulatory associations, receiver/operator locations and completeness metadata separate. A read/write transaction checks replay identity, adds the observation and updates its aggregate/geography together. The station worker hydrates compact learned/geographic/location state into RAM; full raw history loads for explicit bounded queries rather than decoder rows.

StationIntelligenceService.compact() and keyed subscriptions serve normal rows and monitoring. Dossiers, cursor-bounded observationPage() and complete Heard Stations search use the same facade. Consumer components do not invent another station store, callsign resolver or geography precedence chain. The shared StationSelectionStore distinguishes heard-station targets from regulatory-only FCC targets. An FCC Corpus search result must not manufacture an observed station.

Learning commits supported validated observations without waiting for FCC or CTY. Regulatory associations are asynchronous and tagged with the FCC generation, so replacement can refresh reference context without changing captured RF evidence. A provider becoming ready again can retry associations even when its generation ID has not changed.

Geography and distance

Geography is a set of assertions with evidence class, source, time, precision, approximate status and source references. Decoded Maidenhead retains cell bounds/centroid and historical locations; a later message without a grid does not erase remembered evidence. FCC mailing locality is explicitly approximate licensee context, never an authoritative transmitter/receiver position. CTY/DXCC prefix geography is broad inference, not decoded-grid precision.

Receiver and operator locations are different records. Receiver-to-transmitter distance uses the explicit location of the receiver/path that captured the observation, then an explicit receiver-wide fallback, otherwise unknown. For historical rows, that location must be effective at capture time; station grids must also be known at or before that time. Newer movement cannot leak backward. Transmitter-to-addressed-participant distance applies the same rule to both endpoints. Neither distance uses an FCC mailing address as a decoded coordinate.

Retention and failure accounting

Learned RF observations default to retain-all, without hidden rolling deletion. Bounded presentation feeds/caches are not raw-evidence retention. Quota, transaction or enqueue failures must not stop decoding: expose incomplete history, rejected/persistence-loss counts, and the last loss time/reason. Aggregate and raw-history completeness are separate facts. Any future explicit pruning policy must report the loss and earliest complete boundary.

FCC corpus

The browser imports the FCC weekly Amateur archive into SQLite WASM backed by OPFS. Indexed is the default while respecting explicit saved preferences. Both Indexed and Eager retain compact license summaries, callsign-to-USI claims and the callsign index in worker RAM; compact enrichment/autocomplete does not read SQLite or OPFS. Full dossiers and forensic queries use SQLite as needed. Eager is an explicit choice to warm a larger page cache, not a different corpus or a second callsign index.

Switching modes uses a transition-memory budget. RF Sentry does not warm a second full eager worker beside an already large worker merely because two copies would finish faster. Cancellation/failure releases the candidate and leaves a usable mode; switching back recycles the eager worker without deleting the persisted corpus.

The detailed FCC lifecycle belongs to the reference-data store, not learned-station observation retention.

Search and map

Callsign search queries local data and can open station investigation or a map context. Map relationships are entity-keyed and updated incrementally. Search results do not power a receiver and remain useful offline after corpus import.

See local datasets and FCC operating controls.

Ledger and qualification

docs/roadmap/intelligence-maps.md Phase 9A โ€” Contracts and Transport, Phase 9C โ€” Station Intelligence, and Phase 9D โ€” Investigation Experience record accepted contracts and dated evidence. documentation/intelligence/stations.md remains the detailed consumer/identity handoff; its capture, retention and geographic rules still apply. Do not reinterpret an accepted Phase 9 slice as qualification for later map, aviation or SATCOM work.

Implementation anchors: src/enrichment/ftxObservation.ts, stationStore.ts, stationModel.ts, station.worker.ts, StationIntelligenceService.ts and regulatoryProvider.ts; src/ui/station/StationSelectionStore.ts owns selection. stationStore.test.ts, stationGeography.test.ts, stationSelection.test.ts and enrichmentContracts.test.ts are focused regression references, not new live-validation claims from this documentation pass.