Skip to content

rfsentry agent instructions

Project scope and safety

This is personal, educational software-defined-radio and DSP software. It processes RF samples received from the operator's own SDR hardware and works with publicly documented radio protocols unless explicitly documented otherwise. It is not intended for computer intrusion, credential acquisition, malware, exploitation, unauthorized system access, or destructive cybersecurity activity.

NRSC-5 diagnostic builds use memory-sanitizer instrumentation solely to find memory-safety defects in the project's own browser decoder. Captured IQ replay is local, operator-directed radio/DSP regression testing; it must not acquire credentials, probe unrelated processes, or gain network, hardware, tuner, or filesystem authority beyond the explicitly supplied decoder artifacts and IQ capture.

rfsentry is the umbrella project for the Raspberry Pi network SDR appliance, its resilient rtl_tcp mechanisms, and the intelligent WebSDR platform.

Task-specific documentation

Use README.md for repository entry points and read the MkDocs chapter matching the subsystem being changed, rather than every runbook for every task:

Work Documentation source
Appliance/USB lifecycle documentation/architecture/appliance.md
Identity, TLS, and recovery profiles documentation/operator/appliance-identity.md
Receiver controls and tuner capabilities documentation/operator/receivers.md
DSP, audio, FFTs, and waterfall documentation/architecture/browser-dsp.md
Detection, candidate analysis, and assisted tuning documentation/operator/detection.md
Decoder ABI, isolation, and job lifecycle documentation/decoders/index.md, documentation/operator/decoder-workspace.md
Capture clocks and decoder timing documentation/development/contracts.md
DVR, replay, and storage controls documentation/architecture/replay-storage.md, documentation/operator/storage.md
Station learning and geographic evidence documentation/intelligence/stations.md
FCC corpus, hydration, and replacement documentation/intelligence/datasets.md, documentation/operator/storage.md
Map rendering, celestial layers, and reference time documentation/architecture/map.md, documentation/operator/map-replay.md
Aircraft identity, FAA enrichment, and aviation history documentation/intelligence/aviation.md
SATCOM reception, products, and provenance documentation/decoders/goes-hrit.md, documentation/intelligence/satcom.md
Build, validation, and installation documentation/development/build.md

documentation/ is the source of the locally served /docs/ site. docs/roadmap/ owns the topic requirements and acceptance ledger; docs/WEBSDR.md is navigation only. For each change, read its relevant subsystem requirements, accepted corrections, and open exit gates as well as the matching MkDocs chapter. Current code/configuration/manifests establish implemented behavior; the ledger preserves intended contracts and acceptance status. Flag conflicts, account for later checkpoints, and never silently discard a requirement or mark an open gate complete merely because code exists or local tests pass. The public profile is profiles/example, a synthetic template for operator customization. Installed configuration remains authoritative.

For optional rfSentry Server work, read the Server acceptance/future-scope in docs/roadmap/server.md (its numbering is separate from WebSDR phases), documentation/operator/rfsentry-server.md and the applicable components/rfsentry-server/ARCHIVE.md or PRODUCTS.md contract. Browser consumption also uses documentation/operator/record-sources.md and documentation/architecture/replay-storage.md. Qualification ownership and limitations live in documentation/development/build.md and validation.md; docs/verification/README.md indexes selected substantiation and its limits. Update the relevant permanent document when behavior or acceptance changes. Phase 8 and narrow Phase 9 Server-product consumption are operator-accepted; Phase 6 performance acceptance remains separate. Remaining Server Phase 9 and Phases 10–12 require separate authorization. Keep implementation, exact-source qualification and operator acceptance distinct. Processing admission must retain worker reservations until reaping, protect ingestion/control headroom and keep ordered contexts under one owner. Product publication must bind synchronized assets to durable progress and compatible recovery; browser discovery/fetch positions are neither decoder checkpoints nor acquisition ACK authority. Server record archiving uses the shared C++ canonical core and durable segment/ SQLite commits before delivery ACKs. Ingestion and retention require explicit per-stream activation; pairing/upgrades must preserve previously inactive intent. Negotiated delivery windows and receive/commit pipelines must preserve legacy-window progress, per-consumer/aggregate bounds and generation-bound durable ACKs. Worker contention uses bounded fair admission; storage faults must still stop ACK advancement. Server RAM availability and browser-local recovery are distinct from durable archive completion. Preserve the negotiated available/durable read distinction, bounded pending-data ownership and explicit partial-flush reasons; reads must not force persistence or advance appliance durability ACKs.

Appliance and configuration guardrails

Live configuration is authoritative: inspect before replacing it. Keep deployed command/service names stable unless a migration is approved; components use the rfsentry-* namespace.

Never commit credentials, private keys, Wi-Fi profiles, session cookies, access tokens, .env files, or captured user data. Run ./scripts/check-secrets.sh and python3 scripts/check-publication.py --staged before every commit. A secret-scan pass is not a privacy, history or release pass.

Publication follows SECURITY.md and documentation/development/publication-checks.md. Noncredential deployment details (domains, callsigns, unapproved email, account paths, actual serials/mappings and identifying telemetry) still require publication approval. Use coherent synthetic examples; preserve approved attribution, the owner's selected public email, upstream credits, public datasets/geography, hardware classes, protocol fixtures and required integrity hashes. The owner has accepted the existing runner names/labels, machine/workspace hashes, browser path and resource/version details; do not reopen that decision or broaden it to other private information. Keep exact audit values/originals/maps outside Git and all publication roots. Never feed them to contributor code or public CI. Use a reviewed external checker copy in isolated mode for private matching; unavailable required inputs must remain NOT RUN/incomplete, never a pass. Do not echo matched content. Actual credential exposure requires separately authorized/verified revocation or rotation; deleting text/history is insufficient. Stop before replacing an embedded deployment dependency that lacks a supported configuration source. Never constrain installed/private configuration merely to pass a public example rule. This policy grants no standing authorization to rewrite history.

  • Serials identify hardware; aliases identify its operational role. Live /etc/rtl_tcp/*.conf / /etc/rfsentry/routes.d/*.conf own inventory/policy. Transient indices and cached ports never prove identity.
  • sdr-demandd owns public receiver ports and transient serial-keyed backends; backends stay disabled at boot. The unprivileged gateway uses public loopback demand ports, never direct USB, private backends, or receiver service control.
  • Preserve independent lanes/leases, active-client protection, clean close, bounded retries, sparse logs, and idle shutdown. Static UI/auth must not wake hardware, and one receiver's fault or release must not disturb another.
  • Keep the validated USB hierarchy and accessory dependencies. Never switch a reserved cascade port. Preserve serial-verified cold census/cache repair and pruning, stop backends before their ports, and disable children before parents. Keep receiver/deep-idle deadlines distinct; logical isolation is not VBUS proof.
  • Select the matching recovery profile; never transplant another Pi's USB or voltage policy. Preserve verified VHF direct routing and fan-hf's 125 MHz translation; exclude unverified paths from automatic routing/scanning.
  • /etc/rfsentry/appliance.conf owns public identity, ports, origins, and TLS policy. Never compile device addresses/accounts into defaults. Host-only inputs stay outside Git or in ignored config/local/; public examples belong in profiles.
  • Keep IQ on its configured dedicated streaming listener, separate from API/web traffic. QoS changes own only rfSentry's rules and must preserve ECN, unrelated firewall policy, receiver ownership, and established acquisition.
  • Tuner gain and driver offset tuning are capability-gated, lane-local, and recorded with IQ. Reapply supported offset tuning across acquisition/retune/rate changes without moving the logical RF axis; never use undocumented register writes. Command acceptance is not hardware readback; tuner, digital, and browser AGC differ.
  • Preserve operator settings. Fresh lanes start with browser AGC off and request 28.0 dB manual tuner gain, normalized to supported steps. Automatic tuner gain remains an explicit option, never a silently substituted default.
  • Keep Chrony client-only, with persistent drift, startup-only stepping, normal slewing, and non-blocking boot. Status/banner queries stay bounded and local.
  • Respect appliance power limits; avoid needless daemons, RAM, polling, or wakeups. Never add a second watchdog daemon while systemd owns the hardware watchdog.

DSP, display, and assisted-tuning guardrails

  • Keep high-rate IQ and heavy DSP outside React/main-thread processing. Protect acquisition, manual tuning, and audio with isolated workers, bounded queues, shared/transferable handoffs, and local failure handling. Preserve early readiness events, continuity telemetry, and resize-aware presentation.
  • Keep raw FFT evidence separate from display smoothing and dBFS separate from calibrated dBm. Re-project/remap capture-wide waterfall history on view, layout, or capture changes; never erase it for presentation or layer wide history beneath fine history. Keep levels and operator selections stable.
  • Display center/span, VFO, logical RF, and physical tuner center are distinct. Lane-local navigation must not cause needless hardware retunes or override sticky manual mode/bandwidth/step. Preserve explicit FIR cutoffs and reliable drag capture; selecting a signal alone must not change receiver settings.
  • The fast detector owns signal existence, confirmation, and parent identity. Fine evidence may refine confirmed bounds, never create/confirm a signal. Preserve receiver/path masks, absolute-RF boundary evidence, independent-window accounting, recurrence identity, and scale-aware grouping; lobes are evidence, not extra signals. Never move published edges to chase a power peak.
  • The per-lane Signal detection control must isolate detector-only work while off without disabling manual reception or manual-VFO decoding. Preserve this requirement and its open proof gates; hiding overlays alone is not isolation.
  • Candidate analysis is passive, isolated, and limited to the selected parent or one lane-local automatic probe; operator selection wins. Preserve evidence across compatible jitter/fades but never concatenate IQ across gaps. Unknown is uncertainty, priors are not evidence, and scores are not probabilities; replace established classifications only after sustained contrary evidence.
  • Assisted activation is lane-local, explicit, cancellable, undoable, and subordinate to pins/manual takeover. Fit the published occupied envelope to the mode's real passband; BW90/BW99 must not replace those bounds. Decoder Start stays explicit by default, Auto Start stays persisted/default-off, and trials need expiry/cooldown and actual decoder validation for protocol claims.
  • Use configured sample rates and sample-domain tuner quarantine; retain flags and advance sample counters across discarded settling samples. High-rate selections are not proof of loss-free acquisition. IQ quality uses complete fixed sample windows, not transport boundaries, with gap-aware hysteresis.
  • Gain optimization needs fresh complete raw-IQ quality and local signal evidence, supported bounded steps, quarantine, and remeasurement. Preserve the route/capture center, detector identity, and history on settings-only changes.
  • Residual DC correction runs before VFO translation in all derived DSP paths; never rewrite raw recordings, paint over FFT bins, or call it hardware calibration.
  • Keep bounded audio priming/rebuffering, ordered blocks, and continuity/limiting telemetry without React work in the sample hot path. New worker-callable DSP exports must pass the explicit WASM allowlist and instantiated-browser-WASM tests.

Browser and subsystem invariants

  • Decoders are isolated, content-addressed browser modules with a build-time allowlist, artifact verification, and explicit ABI handshake. Preserve exact rates, manifested input policy, and bounded input/output/media. Keep the live decoder tap independent of lossy analysis and channelize in its input worker; never send full-rate live IQ through React or let decoder failure disturb another subsystem/lane.
  • The signal-intelligence pop-out is a same-origin React portal into the main tuner process. The main window remains the sole owner of API clients, receiver leases, IQ sockets, DSP/decoder workers, and audio engines. Never turn the pop-out into a second application instance or receiver path.
  • Browser support sessions are operator-started diagnostics only. Use the dedicated debug profile (reusable by default or disposable with --fresh) and loopback-only SSH tunnel documented in tools/browser-debug/README.md; never expose Chrome DevTools publicly, attach to the normal workstation browser profile, or install a persistent debug service.
  • The optional tools/rfsentry-client utility installs the browser workstation, not the Pi appliance. Preserve its shared CLI/loopback-GUI engine, canonical- origin warning, dedicated managed Chrome profile, inspectable launch command, and conservative Standard/Workstation modes. Workstation mode may disable background timer/renderer throttling; neither mode may disable Chrome's sandbox, TLS validation, web security, or site isolation, force a GPU backend, or reuse/purge an unmarked ordinary Chrome profile.
  • Jobs are explicit and lane-local; keep manual-VFO decoding available with detection off, preserve parent identity, and stop/resynchronize only affected jobs at incompatible boundaries. Input must remain independent of listening controls unless the manifest requires that domain; never add SDR connections.
  • Preserve paired clock anchors, integer sample-time mapping, FIR delay/phase, exact rational positions, capture epochs, and discontinuities. Bind UTC once per capture epoch and advance by source samples; bind FT slots once and advance by decoder samples. Missing UTC stays explicit, never an unlabelled arrival clock.
  • Preserve pinned FT engines, CRC-labelled evidence, and bounded review history. Frequency priors are not protocol proof or tuning references. Automation yields to pins/manual takeover; retain default-off Auto Start and signal Follow, validated holds, and separate detector bounds, held envelope, passband, and search.
  • NRSC-5 modules receive only bounded IQ, never device, network, CLI, or file authority. Preserve stereo/exclusive audio handoff, enforce restricted services in UI and module, bound radio content, and label emergency content as not safety-certified. Positive AM and wider acceptance gates remain open in the ledger.
  • NRSC-5 sanitizer jobs are explicit/operator-only. Keep full dependency instrumentation, privacy-normalized provenance, bounded diagnostic IQ, and exact WASM/loader/source-map hash matching on replay; captures/reports stay ignored.
  • Keep .mjs loaders JavaScript under nosniff and the gateway MIME regression. diagnostic-iq output stays unvalidated substrate evidence, not protocol identity.
  • Raw IQ timeshift belongs to browser ingress before DSP fan-out, with hot RAM, dedicated OPFS storage, bounded replay reads, and exact acquisition runs even across storage batches. Preserve raw evidence; replay never pauses/retunes live hardware. Keep the 60-second/1 GB hot defaults, duration precedence, protect-history default, and Go Live clearing only after deliberate sacrifice of newer history. Only small preferences enter localStorage; never turn the Pi into a DVR store.
  • Waterfall history is a derived capture-time/RF-indexed cache, not raw IQ. Preserve it across presentation resets, replace replayed rows, prune with IQ, and clear on full session release. Native emitted Float32 is the default; reduction/quantization requires explicit operator choice. Account for visual payload separately and expose combined nominal-memory overruns.
  • Keep station identity, regulatory identity, geographic assertions, RF observations, and derived intelligence distinct. Callsigns may have multiple FCC USIs; mailing/prefix geography is approximate context, not a transmitter position. Receiver and operator locations differ; distances use capture-time evidence for the receiver/path that heard the station.
  • StationIntelligenceService owns browser learned-state access and RAM compact projections over separate IndexedDB evidence. Preserve capture-time history, replay-stable observation identity, visible loss accounting, and no silent pruning. Addressed stations are not heard stations. Learning remains usable without FCC/CTY; consumers must not reconstruct parallel identity/geography.
  • FCC truth stays in browser SQLite/WASM + OPFS, not learned-station records. The gateway is a fixed-source bounded relay only: no arbitrary proxy, corpus parser/cache, receiver wake, or device authority. Preserve origin isolation and canonical-origin warnings without silent redirects. Retain lossless source evidence; check headroom and fully validate staged generations before switching the active pointer or retiring old data.
  • FCC defaults to Indexed while respecting explicit operator preferences. Compact decode enrichment stays RAM-only. Eager transitions need progress, cancellation and a peak-memory budget; never overlap full owner workers, and recycle to release grown WASM memory. Do not run automatic whole-origin memory profiling during reception or treat a dated startup-reset exception as permission for sustained RF degradation or a wedged receiver.
  • Maps are browser-owned presentation consumers of shared intelligence, selection, geography, and MapReferenceTime; never duplicate evidence logic. Keep RF and regulatory geography distinct, including Best Estimate provenance and disagreement. Interactive indexing, analysis, propagation and rendering belong to browser workers/RAM/GPU, not the Pi.
  • Core map/geocoder/orbital/celestial assets stay local; Pi refresh jobs are bounded. Online vector/photographic basemaps require explicit selection and scoped providers. Preserve COEP: credentialless, narrow CSP, cross-origin isolation and SharedArrayBuffer support.
  • Map work stays subordinate to reception/DSP/audio/decoder/DVR. Preserve local fault isolation, retained GPU resources, hidden-view suspension and context recovery.
  • Portal scheduling uses its own ownerDocument.defaultView. Advance map time from capture/replay plus monotonic elapsed time, not timer counts; restoration catches up without missed-tick backlogs or backward motion. Paused history stays fixed.
  • src/map/astronomy.ts owns the shared Sun/Moon/Earth frame for sky, terminator and greyline. Keep bounded ephemerides and retained/shader-driven celestial rendering; no second wall-clock/Sun model. Replay rewinds the complete scene.
  • Aviation workspace/map share AviationIntelligenceService and aircraft selection, separate from amateur station/FCC identity. Qualified addresses identify aircraft; protocol is observation provenance, not an identity silo. Never create FCC associations from ICAO, registration or flight ID. Preserve capture-time, replay-idempotent evidence and bounded indexed history; live views use compact RAM, not archive hydration. Never project future RF evidence.
  • SATCOM reuses lane-local ingress/channelizer/decoder; never open a competing receiver. HRIT reception needs sync plus Viterbi/CCSDS RS-validated CADUs, not configured frequency/target. dBFS is not dBm; preserve report semantics.
  • Validated CADUs bypass React/generic media. Isolate assemblies by lane, receiver/route, job, live/replay and source epoch; separate raster work from reception. Target, relay, product source and times remain distinct evidence.
  • SATCOM raw IQ is authoritative; preserve originals and reception history with reconstruction/derivation provenance. Hide presentation, not ingestion. Shared CCSDS machinery does not qualify another HRIT/LRIT service profile.
  • GOES OPFS writes must persist the intended byte range. Snapshot borrowed views before asynchronous ownership gaps and use exact buffers or immutable Blobs; do not clone whole backing buffers/heaps for small ranges. A no-copy path requires explicit stable ownership as well as full-buffer geometry.
  • Browser record reconstruction prefers genuine MEMORY64=1. The operator's compatibility exception permits pinned MEMORY64=2 with the same wasm64 C++ layout/i64 ABI when capability probes require it. Preserve artifact validation, OPFS and exclusive ownership; never fall back on hash/ABI/initialization errors or add a separate MEMORY64=0 implementation without explicit authorization.
  • GOES client resource policy is separate from WASM addressing. Keep native pixels, exact identities and retained history; do not classify hardware by lowered memory64, touch or browser name. Preserve workstation parallelism. Constrained context/worker retirement requires committed recovery and settled ownership; cancelled decodes stay charged until settlement or termination.
  • The gateway must emit exactly one CSP. Its script-src includes the scoped 'wasm-unsafe-eval' keyword required by browser DSP, never the broader 'unsafe-eval'. Do not re-enable libwebsockets' duplicate canned CSP.
  • WebSDR phases require an operator-approved overview. Completed roadmap items use - [x] ~~item~~ in the applicable docs/roadmap/ topic.

Documentation maintenance

  • Keep README a concise public entry point. Current procedures have one authoritative home under documentation/; use neutral examples and explain prerequisites for readers unfamiliar with any particular installation.
  • Topic roadmaps own requirements, dependencies and open gates. Preserve separate WebSDR/Server phase numbering, accepted corrections and partial-acceptance limits. Implementation, exact-source qualification and operator acceptance are distinct.
  • Retain verification only for a specific public claim, regression, decision or open gate, with necessary data and honest source/date/transformation limits. Consolidate useful outcomes; remove redundant reports and obsolete owner context. Do not automatically archive it or append conversations/routine execution diaries.
  • Preserve consequential reasoning in ADRs, not a second operational manual. Follow documentation/reference/source-documents.md for ownership.
  • Inspect installer, build, test and packaging consumers before moving/removing documents. Validate required sources and operator destinations before mutation. Keep repository, built-site and installed/offline navigation usable without independently maintained copies. Run strict docs and link/anchor checks.
  • Documentation edits do not authorize deployment, qualification, new releases or history rewriting. Preserve licensing, attribution and all existing gates.

Contributor workflow

  • Current operator policy is signed, scoped commits published directly to main. Do not open new PRs unless the operator explicitly changes that policy. Keep qualification failures and incomplete phase acceptance visible; publishing code to main does not waive release gates or authorize the next phase.
  • Use conventional commits: subject at most 50 characters, body wrapped at 72. Run ./scripts/check-secrets.sh before every commit, activate .githooks with ./scripts/setup-git-hooks.sh, and never bypass failed hooks.
  • Run Node/npm through scripts/node-toolchain.sh or the validation scripts; never replace Debian's system Node. Preserve pinned/content-addressed artifacts.
  • CI suite ownership, runner trust and exact-main artifact promotion are defined in documentation/development/build.md#coordinated-ci-and-artifact-promotion. Preserve installed gates and artifact identity; do not restore duplicate independent build triggers or silently rebuild qualified release packages. Release workflows are tag-only: a tag calls the shared qualification graph for missing exact-main proofs, then runs missing installed gates and publishes the unchanged qualified packages. Main pushes never start Release. Keep the shared source lease through publication and use distinct nested workflow groups. Manual installed qualification belongs to Packages / Server. Do not add completion-event release triggers, polling or automatic retries of failed tests.
  • Run checks proportionate to changed boundaries; ./scripts/validate.sh --full is the comprehensive entry point. See the build chapter for focused commands.
  • Ingestion changes affecting buffering, persistence, retention, activation, ACKs or storage recovery require actual mounted-ingestion execution on the final code, including all six faults and exact recovery. Ordinary ingestion.py --faults/--case all does not execute mounted faults without the mount harness. Record ordinary, mounted, sanitizer and installed coverage separately; missing execution remains pending, never a pass. Before recommending a release tag for such changes, require installed qualification on both architectures for the exact published SHA using the existing workflow.
  • Ingestion fault tests must fence activation with a known original durable cursor and matching subscription/configuration, explicitly reach the intended persistence boundary, and preserve source-observed ACK evidence across peer retirement. Do not replace these proofs with status-only waits, arbitrary delays, larger timeouts, weakened assertions or retries until green.
  • On the Pi, run heavy builds/tests sequentially with one compiler job. Check free disk/RAM before starting; reuse current binaries for test-only edits and remove only identified obsolete generated artifacts, preserving active builds, operator data and diagnostic evidence. Report required checks that cannot run.