Skip to content

ADR 0005: Manifested, isolated decoder workers

  • Status: accepted
  • Date: 2026-08-24

Decision

Every decoder is described by a versioned manifest: identity, accepted sample kind/rates, expected modes and bandwidth, output event kinds, computational cost, execution target, license metadata, and resource limits. Decoder output uses the common decoder-event schema.

Browser decoders run in dedicated Web Workers/WASM instances. Native-only decoders run as bounded child processes behind the future gateway, never as in-process plugins. Crashes, timeouts, excessive output, and malformed events terminate only that decoder job.

Phase 6A implements contract v2 alongside the retained v1 schemas. V2 names the precise input domain (complex IQ, linear audio, FM discriminator, FM multiplex, envelope/pulse, or protocol bits), exact rates, bandwidth and tuning reference, timing requirements, ABI, content hash, source hash, automatic-start policy, compatibility, and bounded resources. Normalized events carry lane, receiver/path, target, capture epoch/sample time, synchronization and validation state, RF/decoder reference, quality fields, structured payload, and bounded media descriptors.

Phase 6B.0 extends the browser ABI to 1.1 without removing the Phase 6A diagnostic fixture. The generic worker accepts manifested complex, real, or bit-domain float blocks and drains bounded UTF-8 status, normalized protocol events, interleaved decoder audio, and fragmented binary media. The worker, not the module, stamps lane, receiver, path, capture-clock, and job identity. Malformed pointers, lengths, text, rates, dimensions, fragments, or payloads fault only the decoder job.

The browser catalog is generated and schema-validated during the build. It is compiled into the worker allowlist; fetching a different manifest can never introduce executable code. Each shipped WASM is lazy-loaded from a content-addressed path, checked against its SHA-256 digest, instantiated, and queried for its explicit ABI before accepting input.

Browser data path

full-rate IQ -> protected DSP -> fine-analysis credit queue
  -> candidate/decoder bridge -> bounded protocol-policy input domain
  -> dedicated decoder worker -> bounded events / audio / binary media

Full-rate IQ never crosses React or the browser main thread for a decoder. The bridge's channelizer is independent of speaker volume, mute, squelch, browser AGC, de-emphasis, and the audible filter. Only its bounded low-rate output is transferred to the decoder worker. Queue loss and RF/configuration boundaries are explicit discontinuities.

The bridge uses streaming half-band reduction followed by a band-limiting FIR and an exact rational phase accumulator. Fractional decoder rates are retained as integer numerator/denominator pairs. Protocol manifests choose occupied, fixed, or RF channel-grid span policy, guard width, input reference, domain, and exact supported rates rather than inheriting the visible rectangle or speaker filter by accident.

Decoder audio has a separate exact-phase stereo 48 kHz conversion and continuity path. Binary objects are fragment-checked and assembled into a bounded session-local store; only an explicit operator download exposes the stored object. The build allowlist is generated from a deterministic readable matrix that records compiler/linker, scalar or SIMD feature, all source and patch hashes, and the final content-addressed artifact hash.

The detachable signal-intelligence view is a same-origin React portal. It shares the authoritative tuner application's state and callbacks; it cannot construct an API client, receiver lease, IQ socket, DSP worker, decoder worker, or audio engine. Closing or reloading the child window therefore cannot affect the live lane, and the main application can reattach its portal host.

The initial diagnostic-iq module is project-owned test instrumentation, not a protocol classifier. It proves asset integrity, ABI negotiation, complex-IQ flow, timing, lifecycle, isolation, and bounded telemetry before third-party protocol code is imported. Its output is always labeled unvalidated diagnostic data.

Lifecycle

Jobs are lane-scoped and move through suggested, preparing, synchronizing, running, holding, and terminal complete, stopped, cancelled, or fault states. Retunes, incompatible passband/mode changes, target loss, receiver faults, lane release, and explicit cancellation sever decoder input without faulting reception. A manifest bounds retries, wall time, memory, queue duration, event rate, retained events, and media bytes.

Manual-VFO targets do not depend on Phase 2 detection. Detected targets use a stable parent identity. Both physical lanes own independent managers and workers.

Scheduling

Cost classes (tiny, light, medium, heavy) are admission-control hints, not marketing labels. Eco mode admits tiny/light jobs; balanced mode may admit medium jobs; performance mode may admit heavy jobs when thermal/power policy allows. User requests and live listening take precedence over background classification.