Local datasets and updaters¶
Reference data is useful only if its provenance and freshness are visible. RF Sentry prefers atomic appliance generations and browser-local query stores over runtime Internet APIs.
Lifecycle¶
stateDiagram-v2
[*] --> Fetching
Fetching --> Verifying
Verifying --> Building
Building --> Candidate
Candidate --> Active: atomic publish
Fetching --> Previous: network failure
Verifying --> Previous: integrity failure
Building --> Previous: build failure
Active --> Hydrating: browser sees generation
Hydrating --> Queryable
A failed refresh preserves the current generation. Source observation age and download time are distinct; a fresh HTTP fetch cannot rejuvenate stale source data through the power of optimism.
FCC Amateur corpus¶
- Source: FCC weekly public archive through a fixed gateway relay.
- Browser format: SQLite WASM with OPFS persistence.
- Default mode: Indexed, preserving explicit saved Indexed/Eager preferences.
- Common RAM tier: compact summaries, callsign-to-USI claims and callsign index.
- Optional mode: Eager SQLite page-cache warming with explicit progress/cancel.
- Transition: peak-memory admission; recycle sequentially when releasing Eager.
- Runtime Internet requirement after hydration: none.
FCC is an exception to the appliance-generation diagram: its browser owner checks, imports and publishes the corpus. The Pi only relays the fixed source.
Relay and origin boundary¶
| Endpoint | Scope |
|---|---|
/api/v1/enrichment/capabilities |
configured canonical origin, relay availability and ownership/storage contract |
/api/v1/enrichment/fcc/amateur |
fixed FCC Amateur ZIP relay; bounded transfer/backpressure, GET/HEAD and validated conditional/range headers |
The relay accepts no arbitrary upstream target, parses/caches no corpus, starts no extra daemon and wakes no receiver. Its configuration is appliance identity/policy, not a compiled device hostname. Browser durable data is partitioned by origin; a noncanonical valid origin receives a warning rather than a silent redirect that would strand its archive/preferences.
Storage and ownership¶
fcc.worker.ts owns generation-scoped SQLite/WASM databases in OPFS synchronous
access-handle (SAH) pools. An exclusive Web Lock coordinates one active owner;
follower tabs relay bounded queries/status over BroadcastChannel. Promoting
a follower loads the active generation once before scheduling updates. A child
generation builder does not join the tab-ownership channel.
RAM summaries and callsign claims/indexes serve compact enrichment and callsign autocomplete with no persistent reads on that path. Full dossiers, related USI/history traversal and FTS forensic search use the same SQLite truth on demand. Indexed uses a bounded dossier cache. Learned RF observations remain in their separate IndexedDB store; FCC data is not copied into each observation.
Lossless import and replacement¶
Retain the exact source ZIP and every entry/logical record, emitted field, unknown schema drift, source offsets/counts, callsign/USI relationships, inactive/reassigned history and multiline comments. Search projections and field labels are derived indexes, not permission to discard raw evidence.
- Check source revision/size and origin-storage headroom for both current and staged generations before import. A changed revision does not delete the active dataset first.
- Stage download and import in a separate generation. The bounded child builder owns disposable staging resources, not another full active hot tier.
- Validate SQLite integrity, foreign keys, FTS/source consistency, total record counts and required-entry source counts against the FCC counts manifest. Record source SHA-256, schema, tool/library identity and import provenance.
- Open/check the candidate and hydrate its compact tier before switching
active.json. Release the outgoing eager page cache before final promotion; warm optional Eager pages only after the old connection is retired. - Publish the valid replacement before removing old generation assets. Failed or cancelled staging leaves the prior valid generation active. Failed cleanup is a storage warning, not permission to roll back a successful promotion.
The browser owner normally checks revisions at a bounded daily interval; the upstream archive is weekly. No browser owner means no hidden appliance FCC import job. Source revision, fetch/import time and RF capture time are different clocks.
RAM modes and transitions¶
Current runtime.ts preserves explicit Indexed/Eager choices. Legacy implicit
Auto or unrecognized values resolve to Indexed, not a device-memory-based Eager
choice. The historical Auto benchmark remains evidence for its dated policy.
Both modes have the same compact summary/claim/callsign indexes; Eager warms
raw-record/search-document pages in bounded, cancellable batches.
Current SQLite cache settings are 256 MiB for Indexed and 1 GiB for Eager.
These are configured page-cache capacities, not measured resident memory;
JS summaries, claims, WASM allocation and browser overhead are additional.
fccPolicy.ts admits Eager against an estimated transition peak using current
WASM bytes, sampled hot-tier cost, cache-growth and batch reserves, with a
configured budget tightened by a reported heap limit. It is not a measurement
of total browser/system memory or a browser allocation guarantee.
Warming happens in the existing owner, not a parallel full eager candidate.
Switching back, cancellation or failure requests disposal and termination
before starting an indexed replacement: SQLite shrinking alone cannot release
a grown WebAssembly.Memory. The persisted corpus stays intact. See
operator controls for progress and temporary
readiness behavior.
Ledger and qualification¶
docs/roadmap/intelligence-maps.md Phase 9A — Contracts and Transport and Phase 9B — Corpus
Benchmark and Data Plane record accepted relay/data-plane decisions. The
2026-09-07 benchmark approved SQLite/WASM + generation OPFS pools + RAM
compact enrichment; its sizes, timings and Auto-to-Eager choice are dated
measurements, not current defaults or current-machine memory estimates.
Read the later Phase 9B browser decision alongside Phase 9A: Chrome is the reference browser, and Firefox compatibility is welcome but not a Phase 9B release blocker. The recorded brief import-start decoder-reset burst remains a future QoS optimization, never permission for sustained degradation or a wedged receiver. Heavy whole-origin memory/GC profiling must not run automatically during reception; low-cost owned-allocation accounting is a different operation.
Implementation anchors: src/enrichment/fcc.worker.ts, fccCorpus.ts,
fccLogicalStream.ts, fccRelationships.ts, fccOwnership.ts, fccPolicy.ts,
runtime.ts and EnrichmentFoundation.ts; relay scope is in
components/rfsentry-api/src/fcc_relay.c. fccCorpus.test.ts,
fccLogicalStream.test.ts, fccOwnership.test.ts, fccPolicy.test.ts and
enrichmentContracts.test.ts are focused regression references. Historical
benchmark detail remains in docs/verification/intelligence/fcc-corpus/report.md.
FAA aviation metadata¶
- Source: configured public FAA aircraft reference inputs.
- Appliance: background updater builds versioned local artifacts.
- Publication: atomic
currentgeneration served under the existing origin. - Browser: bounded hydration and lookup caches, including negative results.
- Decoder dependency: none; raw aircraft decoding continues without it.
CTY callsign prefixes¶
The local CTY dataset supports prefix/country context and callsign interpretation. Its exact upstream revision, hash, license, and generated asset are recorded in the bundled provenance file. Prefix context is not transmitter geolocation proof.
The pinned source/notice lives under components/rfsentry-web/tools/cty/vendor/.
The production build verifies provenance and emits a same-origin browser asset;
the station worker verifies its hash before parsing. No runtime third-party CTY
request or FCC availability is required to commit a supported station observation.
Map and astronomy data¶
| Reference | Local artifact / ownership | Source and meaning |
|---|---|---|
| Geographic basemap | /map/basemap/ generated assets; bundled MapLibre runtime/worker |
Natural Earth public-domain geometry, labels and boundaries; not a street-navigation database |
| Regulatory geocoding | /map/geocode/manifest.json and generation/shard artifacts |
Census TIGER/Line, postal, place and state references; resolution in a browser worker with generation-keyed cache |
| Orbital catalog | /map/space/catalog.json |
CelesTrak elements plus bounded SatNOGS transmitter metadata joined by NORAD ID; browser propagation/prediction, not received positions |
| Stars | /map/celestial/stars-v1.bin and manifest.json |
pinned HYG v4.4, CC BY-SA 4.0; current built catalog contains 25,790 magnitude-filtered records |
| Moon appearance | /map/celestial/moon-lroc-1k.jpg |
NASA Scientific Visualization Studio CGI Moon Kit / LRO reference texture, credited in the manifest |
The map consumes reference artifacts, not authoritative RF observations. Asset
manifests retain upstream identity, revision, hash and attribution; the celestial
manifest lives at components/rfsentry-web/public/map/celestial/manifest.json.
tools/map/build-celestial-catalog.mjs controls catalog generation/verification.
Do not replace provenance with a generic claim that an asset is merely local.
Appliance publication and browser work¶
components/rfsentry-geocode/ and components/rfsentry-orbital/ provide bounded
oneshot services/timers installed by install.sh. Their installed configuration
and /var/lib/ state govern refresh; published artifacts live under the static
web tree, not another application server. The Census job uses low-priority
CPU/I/O policy and resumable source-aware checkpoints. Both refresh paths keep
last-good artifacts on failure rather than replacing valid references with an
empty generation.
Census publication follows the advertised TIGER vintage, prefers ADDRFEAT,
uses EDGES only as an explicit lower-fidelity fallback and reports locality-only
coverage when address ranges are unavailable. Atomic activation and source
status distinguish expected coverage limits from malformed downloads or failed
refresh. Clients lazily load needed geography and invalidate cached geocodes
by dataset generation; they do not put parsing or storage reads on decoder rows.
Orbital publication retains last-good element groups and RF metadata where available. A metadata outage can leave a valid position-only catalog; it does not establish a missing satellite observation. Interactive indexing, SGP4 propagation, passes/Doppler and rendering belong to browser workers/RAM/GPU, not continuous analytical work on the Pi.
Offline and optional online operation¶
Core geographic, geocoder, orbital and celestial references are served locally.
Explicitly selected online vector styles and photographic basemaps are the
optional client-to-Internet paths. They must remain separate from received RF
evidence and narrowly authorized by CSP, with COEP: credentialless, cross-origin
isolation and SharedArrayBuffer support preserved.
The celestial calculations share the map reference time, so stars, Sun, Moon, and terminator rewind with replay. The universe does not require a CDN, though it does remain annoyingly large.
The star catalog stays in retained GPU geometry; ephemerides update at bounded
cadence and Earth rotation advances in shaders. All sky transforms share
src/map/astronomy.ts and MapReferenceTime, not independent wall-clock loops.
See map architecture for lifecycle and
the ledger note for the separate
map/celestial acceptance checkpoints. Historic publication counts describe
their dated generations, not an assurance that every future source is complete.
Dataset health¶
The UI should expose active generation, source time, fetch/build time, size, mode, and errors. Background jobs are bounded and yield to active reception. Deleting preview caches is different from deleting authoritative source data; controls must say which one they do.