8. Architecture Decisions (ART 0513)

AD-001: Use FastAPI/Uvicorn for MRRC Modern Server

Problem: The server needs static file serving, 4 WebSocket endpoints, async serial CAT I/O, scope subprocess management, audio streaming, and auth — all in one process.

Rationale: FastAPI/Uvicorn provides direct async integration, lifespan management, middleware, and a small code surface. No Tornado, Flask, or Django needed.

Consequences: All server logic lives in server.py with modular imports from sibling modules. Lifecycle managed via @asynccontextmanager lifespan.

AD-002: Direct Serial CAT — No Hamlib/Rigctld

Problem: Hamlib adds a large dependency and another process to manage. FT-710 CAT protocol is well-documented (Yaesu standard) and straightforward.

Rationale: A dedicated CatController class with an asyncio.Lock for serialized access and thread-pool offloading is simpler, more debuggable, and has fewer failure modes than Hamlib/rigctld.

Consequences: Radio protocol code lives inside pluggable backends/<model>/ packages. Adding another radio model requires a new backend package plus factory registration, not changes to server.py.

AD-003: Dirty-Field State Broadcasting

Problem: Full state broadcasts on every poll would be wasteful (~44 fields at 10Hz).

Rationale: RadioState.update() records which fields changed; to_dirty_dict() sends only those fields. Clients merge partial updates into their local state.

Consequences: stateUpdate messages are compact; clients must maintain local state mirror.

AD-004: Tagged Dual-Codec Audio Transport (Opus + Int16 PCM)

Problem: (RX) Int16 PCM at 48kHz mono costs ~768kbps — heavy on mobile/WiFi. Opus at 64kbps cuts that 12×. (TX) Browser mic Opus encoding saves uplink bandwidth. A per-frame tag removes negotiation races — receiver inspects tag and decodes accordingly.

Rationale: opus_rx.py (copied from sunmrrc) provides direct ctypes libopus bindings. Uses max_data_bytes cap on opus_encode() to control bitrate — avoids arm64 variadic opus_encoder_ctl issues. Browser uses WASM OpusDecoder/OpusEncoder. TX encoder configured for voice with fidelity priority (static/modules/opus_codec.js): complexity=5, 64kbps CBR (stable packet size), FEC=OFF (WebSocket TCP is reliable), DTX=OFF (no priming gaps), fullband, SIGNAL=VOICE, LSB depth 16. (Raised from the original 28kbps/complexity=3 for transmit-fidelity headroom.)

Consequences: Adds libopus dependency (optional — degrades gracefully to PCM). Codec is user-switchable. AUDIO_TAG_PCM / AUDIO_TAG_OPUS are constants in both Python and JavaScript.

AD-005: scope_pipe as Standalone Subprocess

Problem: FT4222 ctypes calls are blocking and can hang. Running them in the asyncio event loop would stall the entire server. Threading is fragile with FTDI D2XX driver state.

Rationale: A subprocess isolates the FTDI driver. If scope_pipe crashes, the server continues (falls back to S-meter). Frame format: 4-byte BE uint32 length + payload. stderr carries machine-parseable STATUS: lines for diagnostics. Heartbeat frames (len=0) keep pipe alive when idle.

Consequences: scope_pipe is independently restartable. Server handles pipe exit gracefully (marks scope disconnected, switches to fallback). Two process lifecycle to manage.

Amended (V2.7): the pipe protocol gains a stdin control channel — the server pushes TX:1/TX:0 on every tx_status transition (_notify_scope_pipe_tx). While TX is active the pipe pauses SPI reads and freezes all sync/stall recovery counters (the FT-710 garbles its scope stream during TX; reading it previously churned the pipe into fatal:too_many_reinits after every PTT), and runs one clean re-sync on TX→RX. stdin EOF (parent died) also stops the pipe. Windows teardown uses taskkill /PID <pid> /T /F because terminate() only reaches the onefile bootloader and orphans the real worker (which then holds the FT4222: FT_DEVICE_NOT_FOUND for the next pipe). This subprocess is used only by the FT-710 backend; the IC-7300 backend receives 0x27 spectrum frames directly on the CI-V serial port.

AD-006: Dual-Mode Spectrum (FT4222 + S-Meter Fallback)

Problem: FT4222 requires specific libraries, D2XX driver config, and exclusive device access. It’s not always available.

Rationale: The S-meter fallback provides useful visual context (shows band activity) even without hardware scope. The binary frame format is identical in both modes — clients don’t care about the source.

Consequences: ScopeHandler has two code paths: update_from_scope_frame() (real data) and update_from_radio_state() (synthetic). scope._connected flag determines which is active.

AD-007: PTT Release as Safety-Critical Flow

Problem: A lost or unprocessed PTT release command can leave the radio transmitting indefinitely — a serious safety and regulatory issue.

Rationale: Release is more safety-critical than keying. Each layer catches a different failure mode: lost WS message, half-open socket, browser crash, tab close, app switch. See Chapter 15 for detailed PTT Safety Architecture. V2.63 amendment — what the original list missed: every layer above keys off a disconnect, and a connection that never closes (dropped NAT entry, Wi-Fi switch, silently discarded packets) produces no disconnect to observe, while the one opt-in fallback (MRRC_PTT_MAX_TX_SECONDS) shipped disabled. In a LAN that is an edge case; reached through a NAT it is the normal failure mode, which is why the liveness gate exists and why the cloud hub turns it on.

Consequences: Frontend PTT logic is more complex; polling skip-on-PTT ensures state consistency. (V1.2 removed the 3×200ms post-release verify loop — it added ~600ms to every release; stuck-keyup detection now relies on the 500ms TX-status poll plus the browser watchdog.)

AD-008: PyAudio Auto-Detection of Supported Radio USB Audio

Problem: USB audio device naming varies by radio, OS, and driver version. Hardcoding a device index is fragile. Previous version only searched by name substring and fell back to first input device — could select webcam mic instead of the radio. On Windows the FT-710’s card carries no “FT-710”/“YAESU” string at all (“USB Audio CODEC” or “USB Audio Device”, possibly localized/prefixed), so without tier (3) the heuristics grabbed a laptop mic (RX) or PC speakers (TX) — V2.6 field report.

Rationale: Name-based matching is more robust than index-based. The mono-channel heuristic is reliable: supported radio USB audio typically provides exactly 1 input channel (mono RX), while webcams and USB mics typically offer 2 (stereo). Full-duplex preference for TX ensures the same device is used for both RX and TX paths. Logs all available devices at startup for debugging. The generic USB-audio names rank below the radio-specific hints but above the channel heuristics; duplicates from per-host-API enumeration (MME/DirectSound/WASAPI) open the same hardware, and a genuine multi-device setup is warned about with a pointer to the env-var lock (USB Audio is the common substring covering both enumeration forms).

Consequences: Audio may still use wrong device if multiple mono USB audio devices are present. Configurable device override via env vars is the recommended approach for such setups.

Amended (V2.8): Windows full-duplex wedge — on Windows (MME/DirectSound), opening the TX playback stream on the FT-710’s C-Media codec silently wedges RX capture (stays open, error-free, delivers silence; field symptom: RX audio perfect after server restart, gone after one PTT). AudioHandler.restart_rx() originally reopened capture on TX→RX only on Windows.

Amended (V2.31): Field QSO recordings on macOS showed intermittent 20 ms RX frames with low-bandwidth/attenuated content after repeated PTT activity while a fresh parallel capture stream stayed clean. The workaround is now platform-independent: after every TX→RX transition, the server asynchronously reopens the long-lived RX capture stream. The reopen is off the event loop and does not change the 44.1 kHz device-domain / 48 kHz codec-domain contract.

AD-009: 7-Task Adaptive Polling with Bounded Lock Time

Problem: Polling too fast floods the serial port; too slow makes the UI feel unresponsive. Some fields (S-meter) change rapidly; others (filter width) rarely.

Rationale: Fast path keeps only FA/MD0/SM0 at 100ms. VS/FB run separately at 500ms, so active-VFO tracking does not bloat the IF loop. TX status and TX meters are independent 500ms tasks; TX meter polling includes RM3/RM4/RM5/RM6 and is TX-only. Settings (2s) include RG0, MS, and tuner state; slow telemetry (5s) includes RM7/RM8, PR, AO, and RI0. Poll query timeout is 0.25s to cap lock occupancy.

Consequences: PollScheduler owns task-level cadence and backpressure controls (skip_next_poll(), short pause after user command, and _cancel_polls awareness). CAT errors remain per-command and non-fatal. Since V1.7, poll loops re-check skip state AFTER each in-flight query response and discard stale reads (a mid-flight SH0; response previously overwrote a just-set filter width); the filter set path additionally verifies with a 150 ms SH0; read-back.

AD-010: Memory Channels as Server-Side JSON

Problem: Client-side-only storage loses channels across devices/browsers. Server-side persistence ensures all clients see the same channels.

Rationale: Simple JSON file is adequate for 6-99 channel slots. No database needed. Auto-broadcast keeps all clients in sync.

Consequences: Channels survive server restarts. File is human-editable. No per-user channel isolation (single shared-password model).

AD-011: 48kHz Codec Domain with Per-Backend Device-Rate Bridge

Problem: V1.0 captured mic audio at 16 kHz (320 samples/20ms frame) but PyAudio played back at 48 kHz (expecting 960 samples/20ms). The 3:1 rate mismatch caused the output stream to underrun — every 20ms Opus frame produced 320 samples that filled only 1/3 of the 960-sample playback buffer. The remaining 2/3 was stale/residual buffer data, producing audible crackling (“咔咔咔”) on transmitted audio. The first fix unified everything at 48 kHz — but later measurement showed the FT-710 USB audio interface natively runs at 44.1 kHz, so 48 kHz PCM still could not be written straight to the device stream. The IC-7300/MK2 USB audio interface natively runs at 48 kHz, so no bridge is needed for that backend.

Rationale: Opus mandates 48 kHz; supported radios have different native USB audio rates. A stateless numpy linear-interp resampler bridges the two domains per 20 ms frame with exact integer alignment (960→882 for FT-710), costing ~µs per call with zero phase drift. Browser capture at 48 kHz works on all modern platforms (iOS 15+, Chrome, Firefox).

Consequences: Each direction has at most one SRC step at the server boundary, owned by audio_resample.py. Browser and codec stay at 48 kHz. FT-710 PyAudio streams run at 44.1 kHz with the bridge; IC-7300/MK2 PyAudio streams run at 48 kHz with no bridge. The v1.0 underrun class of bug is impossible in both domains.

Amended (V2.9): the device-domain rate is host-API-dependent, not universally 44.1 kHz. On macOS CoreAudio the codec runs natively at 44.1 kHz (bridge required, unchanged). On Windows the same C-Media codec’s native audio-engine mix rate is 48 kHz, and its MME 44.1 kHz playback path paces ~1.4× slow (measured on the Win11 KVM rig: 50×20 ms writes block 1.36–1.42 s) — the TX drain falls behind, the 400 ms cap drops 24–34 % of voice frames, TX audio crackles. Windows TX therefore opens the same-name WASAPI entry at its native rate (48 kHz) and feed_tx_audio passes 48 kHz PCM through unchanged; the 44.1 kHz bridge applies only when the stream rate is actually 44.1 kHz. RX capture stays at 44.1 kHz MME on Windows (paces correctly).

Amended (V2.14, supersedes V2.9): Windows follows the same fixed boundary as every other platform: browser/Opus remains 48 kHz and the FT-710 PyAudio device stream remains 44.1 kHz. The prior WASAPI defaultSampleRate was a Windows shared-mode mix rate, not evidence of the radio’s USB hardware clock; the KVM pacing result is retained as incident evidence but withdrawn as a device-rate policy. feed_tx_audio() therefore always performs 960→882 SRC. PortAudio reinitialization and the Windows TX→RX capture reopen workaround remain unchanged.

AD-012: Active-VFO-Aware Frequency Model

Problem: Using freq as VFO-A-only could update the wrong oscillator when VFO-B is active.

Rationale: Active-VFO tracking keeps UI and CAT semantics aligned with front-panel behavior.

Consequences: State now carries active_vfo, vfo_a_freq, and vfo_b_freq continuously.

AD-013: FT-710 Meter Calibration Tables

Problem: Raw meter values are not user-meaningful and are non-linear.

Rationale: Calibration points from FT-710 rig data provide practical watt/SWR/volt/amp displays without firmware changes.

Consequences: UI meters show engineering units; calibration can be tuned independently of polling logic.

AD-014: FT-710 CAT Errata Handling

Problem: Yaesu CAT documentation ambiguities can cause unintended RF behavior (frequency drift, invalid tuner command forms).

Rationale: Runtime behavior is grounded in observed FT-710 responses and cross-command consistency.

Consequences: Safer default control path; ambiguous commands are either corrected or intentionally omitted.

AD-015: Priority CAT Command Preemption

Problem: User TX/RX transitions can stall behind in-flight poll cycles if every query holds the serial lock to timeout.

Rationale: Priority commands set a cancel flag observed by poll loops, queued query waiters, and _read_until() threads, reducing worst-case handoff delay.

Consequences: Poll loops must be cancel-aware; UX is significantly more responsive during fast PTT/tune transitions.

AD-016: Pluggable Radio Backend Architecture (FT-710 + IC-7300 via RadioBackend/Capabilities)

Problem: The server was hard-wired to the FT-710 — Yaesu ASCII CAT, FT4222 spectrum, 44.1 kHz USB audio — so supporting the Icom IC-7300 (CI-V protocol, in-band 0x27 spectrum, 48 kHz native audio) would have meant forking server logic.

Rationale: A backend ABC mirroring the CAT surface plus defaulted hooks (bands/ui_modes/filter_tables/poll-item lists/init_scope/create_scope_producer) keeps server.py, polling, and state radio-neutral; capabilities pushed in fullState let the frontend adapt bands, modes, FIL1-3 filters, ATT/PRE steps, meter visibility, and scope banner without protocol changes.

Amended 2026-09-12 (V2.41): the Icom side of this layer became profile-driven. backends/ic7300/civ_profiles.py holds one CivModelProfile per model (address, Transceive set-mode item, scope geometry, bands, modes, attenuator steps, meter curves, verification flags, provenance) and the shared codec/controller/scope producer take those values as optional parameters whose defaults reproduce the previous IC-7300 constants. Adding IC-705/IC-7610/IC-7760 therefore required no new protocol code and no server.py model branches — three subclasses overriding one attribute, one registry entry, and a capability-driven attenuation bound. Models without hardware evidence set verified=False and refuse keying until MRRC_ALLOW_UNVERIFIED_TX=1 (the first time this layer carries an explicit unverified state rather than implying acceptance). The package directory name backends/ic7300/ now hosts the shared Icom core; renaming it to backends/icom/ is tracked as a separate change.

Consequences: New radios are added as a backends/<model>/ package plus factory registration; FT-710 behavior is unchanged (compat shims keep root imports valid); IC-7300 hardware-verification items (S-meter top point, TUNE carrier behavior, MK2 transceive item) remain flagged in code comments.

AD-017: 服务端 QSO 录音（增量 MP3、16 kHz 存储域）

Problem: 浏览器端录音器把到达的帧无时间戳地顺序拼接，网络抖动、jitter-buffer 补帧与队列丢弃被永久写进文件 —— 表现为回放”颤抖/哆嗦”（字段报告 2026-09-12）。此外音频只在页面可见时可靠，且 500 KB 的 MP3 编码器要下发到每个客户端。

Rationale: 服务端取音点是设备域 PCM（AudioHandler.read_rx_chunk()）与 Opus 解码输出，二者都不经过网络；时间戳 + 容差 + 空洞填静音把”抖动”与”真实停顿”分开处理，这正是回放平滑的关键。增量编码让 RAM 恒定（编码器 + FIR 状态 + 单块）且进程崩溃后磁盘上的前缀仍可播放，相对内存缓冲方案 1 小时录音省约 115 MB（本项目发布树莓派镜像）。16 kHz 是与兄弟项目 mrrc 一致的存储域，使 recordings/ 目录可直接被其既有工具消费（同一命名 <freq>kHz_<date>_<time>.mp3）。

Consequences: 16 kHz 是只写汇点，从 48 kHz codec 域到达：44.1 kHz 设备音频先经 audio_resample（AD-011 唯一 SRC 桥），再经专用抗混叠 FIR 抽取 3:1；录音路径不回灌 codec/device 域，AD-011 不受影响。录音与 CAT 解耦（USB 音频可用、CAT 断线也能录，无 CAT 时频率记为 0 → 文件名 00000kHz）。保留策略刻意不自动清理（§13 R10），会话上限 MRRC_RECORDINGS_MAX_SESSION_MIN 只停止录音、不删除文件。不做所有权仲裁（I6 仍未解决）：任何已认证客户端可启停，状态对所有客户端广播。

Writer 生命周期（V2.45 修正）：writer 任务是每会话一次性的 —— 收到 stop 哨兵、MP3 定稿后即 return，这正是关闭流程能 await 它完成刷盘的前提。因此它的创建属于每个会话，而不是 lifespan：_ensure_rec_writer()（幂等）在录音开始、stop 入队与音频块入队前调用，发现任务已结束就重建。只在启动时创建一次会让任务在首次 REC/STOP 后永久消失 —— 此后每个会话都没有消费者，有界队列瞬间填满、所有块被丢弃，stop() 再用静音补齐时间轴，产出一个大小正确但 100% 静音的 MP3（2026-09-12 现场报告）。队列满时 stop 路径不得在事件循环上直接调用 session.stop()（writer 线程可能正在 add_audio）：改为丢弃最旧的一块给哨兵腾位，保持单写者不变式。丢弃计数按会话统计并随 recordingState 上报 —— 块被丢弃是”录音有空洞”的唯一可观测信号。

8.16 Decision Summary

AD-018: Yaesu 多机型走 profile 驱动的共享 ASCII-CAT 核心（FT-710 验证路径保持独立）

Problem: 加 Yaesu 机型时最省事的做法是让每台新机继承 FT710Backend，但这会把每日在用的 FT-710 类层次拖进三台未验证机型的需求里，并把并非按共享核心设计的 cat_controller.py 事实上变成共享核心（含 FT-710 专有假设）；而「同期把 FT-710 也迁到共享核心」虽能让核心被真机验证，却让一个发布里改动用户每天通话的代码路径，爆炸半径最大。

Rationale: Hamlib 4.7.2 自身就是该架构的先例（newcat.c 13,048 行共享核心 + ftdx10.c/ftdx101.c/ft710.c 各 ~300 行机型表），仓库内也有已验证的同类先例（backends/ic7300/civ_profiles.py）。新核心因此坐在「被真机验证过的传输逻辑 + 数据化机型表」之上，同时 FT-710 的现场行为零风险。核心的无真机验证问题由 Hamlib 模拟器与 pty 假电台测试补偿。

Consequences: 短期存在两条 Yaesu 代码路径（框架/串口逻辑有少量重复），迁移列为三期：真机在手时逐命令 A/B 对比新旧实现，MRRC_RADIO_MODEL=ft710 是回滚开关。加第 5 个 Yaesu 机型只需加一张 profile 表 —— FT-891（V2.72）实测了这句话，并暴露它差一点才成立：它的滤波宽度写格式与家族不同（SH01NN vs SH00NN，Hamlib newcat.c:9658-9663 的 int on = is_ft891），纯数据表装不下「命令前缀」这类差异。修法是给 profile 加 filter_width_prefix 字段、核心 set_filter_width 改读它（对四款已发布机型字节等价），于是核心仍然零机型分支——结论修正为：加机型只需一张 profile 表，必要时给表加一个字段，但绝不在核心里写 if model ==。

AD-019: 未验证机型仅接收（TX 门禁 + 只读身份校验 + 逐表溯源）

Problem: 无真机的实现容易被呈现为「已验证」：表头曲线看起来一样、模式表看起来合理，一旦现场表现不同，用户无法判断是电台行为、接线还是实现猜测。更危险的是 TX——在未验证的频率/功率语义上发射可能对电台或天线系统不利。

Rationale: 「不确定就说不确定」比「猜一个并当作数据」成本低得多：门禁把风险最高的动作（发射）变成显式选择，溯源让每张表都可追溯、可纠正，诊断脚本把闭合缺口变成一次粘贴。

Consequences: 新机型首次连接只收不发（UI 显示”实验性，仅接收”），需要操作者显式开启；模式/滤波/表头在获得现场回传前都带未验证标记；dual_rx（FTDX101D/MP 与 FTX-1F 的双接收）只记录不实现，留待二期独立规格。FT-891（V2.72）给本决定补上了第二类证据：现场支持上报也算硬件证据，可用于关闭离线源推不出的事实（它的 38400 8N1 串口参数、无 USB 声卡、S 表偏高 1–1.5 S 三项都来自老产品 2026-09-17 的一份上报，见 §13.3 A10）。这比「无真机 ⇒ 全部只能假定」更强，但纪律不变：推论值不写成期望值——FT-891 的 ID; 应答可由 NC_RIGID_FT891=135 推出 0135，仍按操作者决定留空只记日志；另一份产品的电表观测也不用来改本仓库的曲线。

AD-020: 一键 CQ（服务端一次性自动化发射，复用 PTT 安全链路）

Problem: 呼叫 CQ 是每次通联都要做的重复动作：按住 PTT、对准话筒、念完一整套呼号与”Listening”。远程操作时这套动作最容易出问题——说话时麦克风增益、网络抖动、忘记松 PTT。现场反馈（2026-09-13）希望「按一下就能 CQ」，且每次发射必须有明确终点。

Rationale: 播放端放在服务端，则音频从磁盘到声卡全程不过网络，抖动与丢包都不影响发射内容；键控路径复用已现场验证的 PTT 释放架构（AD-007 的强制松键 + 15 章的七层防线），因此”忘记停止”这一类风险由既有防线兜底，而不是新写一套超时逻辑。前端只做状态镜像（cqState），多端天然一致。

Consequences: cq_player.py 是纯音频/状态机模块（可脱机测试，不 import 硬件库）；服务端启动时若资产缺失/损坏/超长（>30 s）则以 WARNING 明确说明并禁用按键，绝不静默；fullState.cq 让中途刷新页面/重连的客户端也能看到进行中的呼叫。

AD-021: 支持诊断包（服务端构建 + 白名单脱敏 + 独立接收端）

Problem: 问题上报长期以”现象描述”到达（“有杂音”“升级后不响了”），第一轮往返都花在索取证据上：哪个版本、什么平台、日志在哪。而 MRRC Modern 的打包版根本没有服务端日志文件——日志只进控制台窗口，窗口关掉就没了。

Rationale: 证据只有在故障现场才能收集：设备表、实际采样率、串口状态、scope 是真实还是 S 表回退、TX 门禁状态，这些都无法事后补问。因此在服务端一次性收集、脱敏、自证（含自动体检结论），把”维护者第一眼要看的东西”直接写进包里的 summary.txt；入口放在浏览器则三端（Web/iOS/Android）与树莓派都可用。

Consequences: 用户自助路径从”发消息描述问题”变成”点三下拿到编号”；维护者从”追问”变成”读摘要”。代价是一个新的常驻服务（接收端）与一条隐私契约——后者是硬约束：白名单之外一律丢弃并计数，包内出现密钥即是回归。

Amendment (2026-09-17, 支持链路第 2 期): 分诊与答复由 dev_tools/support_autopilot.py + support_answers.py 完成： 轮询接收端 → 取包解包 → 组装摘要（复用第 1 期的 collect_context，含 summary.txt 与日志尾部）→ pi（只读工具、仓库为工作目录）按固定 JSON 契约产出结论 → 渲染成答复卡。 发布规则：默认只写草稿（dist/support_answers/），--publish 才更新 website/answers/index.html、 git commit 并单文件 rsync 上线（全站部署仍是交互式的，不能进 cron）；即使带 --publish， need_more_info 也不发布（那是给操作员的问题，不是答复）。护栏：幂等 state.json、 单轮上限 2 条、pi 超时 540 s、半包跳过、单条失败不中断。 公开页的隐私边界由 support_answers.redact_public 承担（邮箱/手机号/设备路径/串口/内网地址/本机与临时路径）， 并有用带敏感值的假包做负例测试——与第 1 期的入包白名单互为镜像。实测边界：真机跑通一次端到端 （4m12s，结论引用了 server.py:_rec_enqueue 与 recorder.py:383 的真实代码位置），但结论质量只在 该合成包上验证过；cron 连续运行与真实用户包的表现待观察。

AD-022: 一键升级通道（生成式清单 + 自证成功 + 发射门禁）

Problem: 前两期把报障→结论打通了，但用户拿到修复仍要自己找下载页、对 SHA、重装。同时升级类功能最容易自欺：安装器退出码 0 不等于升级成功，已拉起安装器更不等于。

Rationale: 因此把成功定义成一个只能由新版本自己写下的事实（lastResult.status == ok），并把清单做成生成物（从产物本身算哈希）—— 这两条让升级成功与清单可信都不依赖任何人的自觉。发射门禁沿用第 15 章的既有分层：升级是维护动作，绝不与载波争资源。

Consequences: 维护者发版时多一步 make_latest_json.py，换来用户侧检查→下载→校验→安装→自证全程可判定；代价是两片交付期间只有检查可用 —— 这是有意的：半成品升级器会动用户的机器。

AD-023: 远程会话遥测（实测 Listener 并发与上行，计数不含标识）

Problem: Cloud Hub（mrrc_hub/SDD AD-H12）明确拒绝在拿到”单实例真实 Listener 并发分布”之前建设 RX 扇出，而那个数字的原材料（spectrum_clients / audio_rx_clients / _listen_tokens）一直只活在内存里、随进程消失。同时实测已表明单会话带宽里频谱占 ~86%（1701 B/帧 × 30 fps ≈ 408 kbps，对比 RX Opus 64 kbps）〔2026-10-07 校正，见 AD-025：30 fps 是 tick 率而非出帧率——真频谱只在硬件帧计数前进时发送，实测 11.1 fps ⇒ 频谱 ~151 kbps payload、占单会话 ~72%（不是 86%）；408 kbps 是 S-meter 回退态的数字。结论方向不变（频谱仍是主项），但 hub 的容量输入应以 151 kbps 与可配档位为准。〕—— 猜错的代价不是数字难看，而是重构错了子系统。

Rationale: 把”要不要做扇出”从判断变成读数：峰值会话数回答”值不值得”，两路上行字节回答”省下多少”。同时把隐私边界写死在模块里（只有计数和字节），使这份观测可以默认开启、可以放上公网端点，而不必先谈同意书。

AD-024: 会话令牌传输（Cookie 优先、Header 给原生客户端、Query 弃用）

Problem: 浏览器前端把会话令牌拼进 ?token=，而实例跑 uvicorn 默认访问日志（含 query string），项目自己也早已知道这一点（support_bundle.py 的脱敏正则注释点名 “a ?token= inside a URL”）—— 但脱敏只在导出诊断包时发生。一旦进入 Cloud Hub 的透明代理模式，中心侧每一条访问日志都会记录各实例的 30 天令牌；而浏览器侧没有自定义头能力这一”技术理由”，其实并不成立：同源 WS 握手会自动带上 Cookie。

Rationale: 让凭证回到它能被系统正确保护的位置（Cookie / Header），URL 里只留资源路径。对已安装的原生客户端保留 query 兜底，是因为”安全改进”不该以现有用户的连接为代价 —— 但必须让它可观测，否则永远不会有人去改。

AD-025: 频谱带宽档位（形状 × 分频，以 caps 协商为闸门）

Problem: 公网出口带宽与移动流量账单的主项是频谱，但”省带宽”这件事在本仓从来没有可动的旋钮：帧长恒为 1701 B、tick 恒为 30 Hz，唯一存在的节流是 listener 的 ÷3。而两个实测事实使任何单一手段都不够——浏览器侧 permessage-deflate 已经把 wf2 的 850 个零字节压到≈1.4 B/帧（砍它对网页几乎无效），Android 侧则完全没有压缩（砍它就是全部收益）。同时 SDD §9.2.4 定义的 v1=851 B 从未上过线（全仓无任何代码发出 0x02，git log -S 零命中），文档与线上格式已经对不上；而回退路径因为没有帧计数闸门，坏消息反而比好消息贵（30 fps × 1701 B ≈ 408 kbps，对比真频谱 151 kbps）。

Rationale: 把”省带宽”从一次性的格式决定变成每 socket 可协商的档位，并且让兼容性由服务端闸门保证而不是由客户端升级保证——未声明能力的连接逐字节拿到今天的流，所以老 Android 不会因为服务端先上线而黑屏。两个因子分别覆盖两个轴（形状覆盖 Android 的 payload、分频覆盖浏览器的 deflate 后线上字节），这样”每档减半”在两种口径上都成立，而不是只在其中一个上好看。短帧用切片而非新组帧路径，是为了让 scope_handler 与 11 个 backend 完全不动——组帧代码只有一份，就不存在两份会漂移的实现。全帧保持 0x01 而不是改成 0x02，是因为已装 iOS 客户端 guard version == 0x01：一个”更贴合文档”的版本号会换来一批静默丢帧的用户。

AD-026: 初始化热点与免口令引导窗口（按网络路径开门，不按标志位）

Problem: 首次配置需要同时具备两样互为前提的东西：要配 Wi-Fi 得先能操作盒子，要操作盒子得先有网（SSH）或有显示器键盘。而”只发一个热点”并不解决问题：连上之后到达的仍是现有界面，它要一个操作者并不知道的口令。

Rationale: 1. 判据是网络状态，不是”首次开机”。 起热点 ⟺ 无网线链路 且 无可连上的已保存 Wi-Fi。配好的盒子因此永不再开热点，且不存在”是否已配置”的标志位——也就没有”标志写失败导致永久敞开”这类故障模式。 2. 闸门是网络路径，两半都要成立：state.json 的 mode == hotspot 且心跳新鲜（_setup_gate_open）且客户端 IP 在该热点网段内。网段那一半挡住”某个局域网客户端恰好是 10.42.0.x“（NM shared 默认网段与家用网段撞车是完全可能的）；心跳那一半挡住”守护进程死了但文件还在”。热点一关，那个网段不复存在，免口令分支自然失效。 3. 页面并进现有 FastAPI 应用（否决独立 setup 服务器）：设口令因此复用既有通道 first_run.update_env_file(_config_file_path(), …)，与 POST /api/setup 同函数同文件；免口令窗口可写的键集被钉成恰好两个（MRRC_WEB_PASSWORD、MRRC_AUTO_PASSWORD），MRRC_CONFIG_FILE（D-11 的载荷）与 MRRC_ALLOW_UNVERIFIED_TX（AD-019 / NFR-067）在任何可写集合里都不出现。 4. 单射频 ⇒ 切换而非并发（MT7663S 的 Wi-Fi 与蓝牙同芯片、走 SDIO）。切网期间守护进程让位：服务端在 wizard.json 里声明占用，守护进程不碰射频并按让位时长补偿窗口。回答先发出去再切（手机在切换瞬间就不在盒子上了），失败则把热点开回来并把 nmcli 的原因留在 wizard.json 里给页面显示——不许静默返回。 5. 两份文件、两个唯一写入者：守护进程（root）只写 state.json（每 tick 重写，其心跳是闸门的一半），服务端（mrrc）只写 wizard.json（占用声明）。因此不需要锁。 6. Wi-Fi 密码永不离开 nmcli 的 argv：WizardClaim 没有 password 字段（“不落盘”是 schema 的性质，而不是每个调用者要记住的承诺），nmcli 的错误文本在存下来之前过 net_wifi.scrub(text, password)。这是 support-bundle-privacy（NFR-068）在一个新写入面上的延伸。

Consequences: - 中间件放行必须由处理函数补回角色检查，漏掉它就是权限提升。 SETUP_GATE_PATHS（/setup、GET/POST /api/setup/wizard*）在 auth 中间件里被按相等放行到处理函数，而中间件的 listen-only 403 对这些路径必然被跳过（未鉴权的热点客户端没有角色可判）。因此 _setup_access() 是唯一裁决点：热点路径（每次进入都写 WARNING 审计：谁、什么时候、哪个 IP）或完整 admin 令牌；listen 令牌在这里被拒，且回 403 而不是 401——那个调用者是已鉴权的，401 会误导页面”会话过期”。 - 三条围栏压住开放窗口：① 只在无其他上行时存在；② 30 分钟（MRRC_SETUP_AP_TIMEOUT_MIN，可配）无人完成引导即自动关闭，且本次开机不再重开（闩是进程内的；持久化它等于把盒子变砖）；③ 每次免口令进入都留日志。恢复路径是断电重启。 - 残留风险（诚实记录）：热点开放期间，同一网段内的人可以先下手设口令接管盒子。Wi-Fi 半径十几米，公寓楼里邻居可能在里面。围栏把窗口压到”你主动插电后、且附近没有网络”的那几十分钟，但不能消除。缓解：地址同时打在 HDMI 控制台上（有显示器的人不必用热点）。 - 未验证边界（V2.80 真机闭环）：AP 模式实测不可用——固件修复（出厂 2021 版 N9，见 V2.80）后 NM/wpa_supplicant 认为 AP 已激活（COMPLETED、10.42.0.1/24 就位、零报错），但信标不上空（手机与 Mac 均扫不到）；上游移植记录同样只验证过 STA。另抓到并已修复一个同链路产品 Bug：NM 1.42 的 device wifi hotspot 不传密码会自动生成随机 WPA-PSK，「开放热点」实为加密网络——start_hotspot() 改为显式建无 security 段的 profile。STA 模式在固件修复后达到生产质量（200 包 0.5% 丢包 / 6.3 ms / 零掉线）。盒子上手因此走有线或 HDMI 路径，设计上本就不依赖 AP 成立（HDMI + nmtui 兜底）。 - 镜像装机清单加 dnsmasq（NM 的 ipv4.method=shared 靠它发 DHCP/DNS；缺它的症状是热点出现、手机连上、拿不到地址、任何地方都不报错）。单元不得排在 network-online.target 之后——它存在的理由就是没有网。

接替方案（2026-10-11）：热点这条上线路被放弃，改为「盒子接入 LAN → 打开网页 配置盒子 OS」。设计见 docs/superpowers/specs/2026-10-11-w103d-lan-box-settings-design.md， 实现见 docs/superpowers/plans/2026-10-11-w103d-lan-box-settings.md。

沿用下来的三条：无密码面必须只有一个键宽（只有 MRRC_WEB_PASSWORD）、 判据是状态而不是标志（旧的是「热点活着」，新的是「从未设过口令」）、 Wi-Fi 凭据只走 net_wifi 的 argv（为此拒绝了「全部 nmcli 写都过 root helper」 的路线，那会让 PSK 经第二条通道）。

没有沿用的：AP 生命周期、/run/mrrc/setup-ap/state.json 与 wizard.json 两个 跨用户信箱、mrrc-setup-ap.service。提权从「root supervisor 管整条热点」换成 「polkit 放行 mrrc 写 NM + 只管四个系统动词的小 root helper」。

AD-027: 出厂预置（发货版）镜像 —— 固定口令 + 系统层预置，Wi-Fi 与公网入口都从设置页配

AD-028: 本地控制面 —— 蓝牙遥控器直接驱动电台（PTT / 调谐 / 数字输入）

AD-029: 独立 SDR 接收机（对外发布的 Web 接收器）

AD-030: 串口仪器（NanoVNA-H）的接入边界 —— 一次一件、发射中闭嘴、不抢 CAT 口