Compiler-checked hot-path discipline and tier-zero warnings

CMakeLists.txt

@@ -42,7 +42,27 @@ if(MSVC)
     # Static MSVC runtime so the Windows binary doesn't need vcredist.
     set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
 else()
-    add_compile_options(-Wall -Wextra -Werror)
+    # Tier zero on top of -Wall -Wextra: five warnings that catch real defects the base set
+    # misses. -Wdouble-promotion is the one that earns its place here specifically — the Xtensa
+    # has no FPU, so an accidental float->double promotion is a silent softfloat call in the
+    # render path, and it enforces the integer-math rule the coding standards ask for.
+    # (GCC/Clang only; the MSVC branch above uses /W4 /WX, which has no direct equivalents.)
+    add_compile_options(-Wall -Wextra -Werror
+                        -Wshadow -Wnon-virtual-dtor -Wdouble-promotion
+                        -Wimplicit-fallthrough -Wnull-dereference)
+
+    # Hot-path discipline, enforced by the compiler. MM_NONBLOCKING marks tick/tick20ms/tick1s
+    # (platform.h); -Wfunction-effects then checks TRANSITIVELY that nothing they reach
+    # allocates or blocks — which check_hotpath.py's regex cannot do, since it only sees the
+    # text of the tick body and not its callees. Clang 20+ only; the flag does not exist on
+    # GCC, so the ESP32 build keeps check_hotpath.py for src/platform/esp32/.
+    if(CMAKE_CXX_COMPILER_ID MATCHES "Clang" AND CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 20)
+        # -Wno-error while the findings are triaged: they are real (status formatting and
+        # the audio sync path on tick), but each needs a judgement — fix, accept with a
+        # scoped reason, or annotate the callee — and a red build blocks every other
+        # gate meanwhile. Drop the -Wno-error once check_hotpath reports zero.
+        add_compile_options(-Wfunction-effects -Wno-error=function-effects)
+    endif()
 endif()
 
 # `uv` is the project's Python launcher (see CLAUDE.md / moondeck/MoonDeck.md).

docs/backlog/backlog-core.md

@@ -341,6 +341,96 @@ Fix options: (a) make every live mutate scenario clear+rebuild its own canvas (c
 
 ## Housekeeping
 
+### Hot path: move blocking work off the render callbacks (architecture)
+
+`-Wfunction-effects` proves the render path really does block — these are not annotation gaps,
+they are synchronous I/O, allocation and lifecycle work reachable from `tick()`. Each needs the
+work moved to a worker or made resumable, so each is a design change rather than a lint fix.
+Confirmed by external review (CodeRabbit, PR #56).
+
+**`tick()` — every frame, the sharp ones:**
+- `PreviewDriver::tick` — `sendFrame()` writes a socket synchronously; `buildAndSendCoordTable()`
+  resizes `keptIdx_`. Currently suppressed at the site with the reason.
+- `ParallelLedDriver::tick` — `tickSync()`/`tickRing()` reach `busWaitIfBusy()`, which spins for
+  the DMA peripheral. Deliberate (the driver owns the bus for the frame) but blocking. Suppressed.
+- `Drivers::tick` — joins/stops the render-split worker synchronously on the timed-out recovery
+  path. Wants asynchronous handling that still preserves buffer ownership.
+- `HueDriver::tick` / `tick1s` — synchronous HTTP (`pushOneChangedLight`, `pollPairing`,
+  `fetchLights`, `fetchGroups`) plus allocation. Wants a queue to a worker.
+- `Layer::tick` — calls `applyState()` on a modifier rebuild, which runs prepare/release and
+  resizes ScratchBuffers. Wants the rebuild deferred to the scheduler's non-render prepare path,
+  keeping today's coalescing of `consumeNeedsRebuild()`.
+- `DemoReelEffect::tick` — `advance()`/`swapTo()` create, delete and `applyState()` child effects
+  from the render callback. Wants a pending-switch flag consumed off-tick.
+- `NetworkSendDriver::tick` — sends inline; wants to enqueue.
+- `RmtLedDriver::tick` — waits on hardware completion and reset; wants polling or offload.
+- `AudioService::tick` — UDP `sendTo`/`recvFrom` every frame (`syncSend`, `syncReceive`,
+  `syncEnsureSocket`).
+
+**`tick20ms()` / `tick1s()` — milder, same shape:**
+- `HttpServerModule::tick20ms` — inline `handleConnection` transport work, so the 100 ms budget
+  cannot actually bound it. Wants resumable connection handling. `tick1s` writes WLED state
+  frames inline; wants the existing resumable sender.
+- `MqttModule::tick1s` — synchronous DNS + discovery-buffer allocation.
+- `NetworkModule::tick1s` — WiFi/AP lifecycle transitions and tree rebuilds.
+- `FilesystemModule::tick1s` — the debounced `flush()` does filesystem work; the poll itself is
+  fine, the save wants a worker.
+- `FileManagerModule::tick1s` — `platform::filesystemUsed()`; wants a cached value.
+- `SystemModule::tick1s` — the P4 `coprocessorWifi()` path calls
+  `esp_hosted_get_coprocessor_fwversion()` synchronously; wants a cached snapshot.
+- `ImprovProvisioningModule::tick` — runs the queued APPLY_OP inline; wants a cold task to
+  execute and publish only the result.
+- `Scheduler::tick` — dispatches all of the above, so its own contract is only as good as theirs.
+
+**Explicitly NOT in scope:** the float-math findings (`BouncingBallsEffect`, `RipplesEffect`,
+`SphereMoveEffect`). Review suggested fixed-point, but the float trajectory IS the ported
+MoonLight behaviour and fidelity is deliberate. If the FPU-less Xtensa cost is real, that is a
+profiling question first, not a lint fix.
+
+Until this lands, `-Wfunction-effects` carries `-Wno-error` and `check_hotpath.py` stays as the
+enforcing gate.
+
+### Hot path: triage the 181 -Wfunction-effects findings, then delete check_hotpath.py
+
+`MM_NONBLOCKING` + `-Wfunction-effects` (the "clang-hotpath" card) checks hot-path discipline
+TRANSITIVELY — through the whole call graph, where `check_hotpath.py`'s regex reads only the
+tick body's own text. The new check finds **181** sites; the old one finds **0** in the same
+code, which is the measure of how blind it is.
+
+Split by tier, because the cost differs by orders of magnitude: **70 on `tick()`** (every
+frame), 6 on `tick20ms()`, 95 on `tick1s()`, 10 unresolved. The sharp ones are UDP
+`sendTo`/`recvFrom` inside `AudioService::tick` — socket I/O every frame. The bulk is
+`snprintf` ×20 (bounded and non-allocating; wants one policy call, not 20 edits) and 11 static
+locals (a guard variable + one-time lock on first use — a real violation).
+
+Then `check_hotpath.py` (170 lines) goes. It scans 67 tick methods, all in `src/core/` and
+`src/light/`, all compiled on desktop — a strict subset of what the compiler now covers. It is
+NOT the ESP32's safety net: `src/platform/esp32/` has no tick methods at all.
+
+**Order matters.** `check_hotpath.py` fails pre-commit today; `-Wfunction-effects` carries
+`-Wno-error` while the findings stand. Deleting the script first would leave hot-path
+discipline with nothing enforcing. So: triage → drop `-Wno-error` → delete and swap the gate.
+
+Every file with a finding is already touched by the branch that added this, so the fix costs
+no new files — but it is substantial, and wants its own branch.
+
+### ESP32 clang/LLVM toolchain — extend the clang checks to src/platform/esp32/
+
+Espressif ships an xtensa LLVM (their fork), but the installed `esp-clangd` package contains
+**only `clangd`** — no `clang++` driver — so a clang analysis pass over ESP32 sources needs their
+full LLVM installed separately.
+
+What it would buy: `-Wfunction-effects` (and clang-tidy, clang-query) over `src/platform/esp32/`
+— 20 translation units, the only code the desktop build excludes. Everything else, including the
+LED drivers, already compiles on desktop and is already checked.
+
+What it costs: a second ~1 GB toolchain, maintained purely for analysis — the firmware would
+still be built by GCC, so the analysing compiler is not the shipping compiler. That is a real
+"one rule, one owner" tension, and the reason this is a decision rather than an obvious yes.
+
+Worth revisiting when either the coverage gap bites (a hot-path bug traced to the platform layer
+that the desktop check could not see) or Espressif's LLVM becomes the default toolchain.
+
 ### clang-tidy: triage the 47 clang-analyzer findings, then gate
 
 `.clang-tidy` runs `*` minus a documented disable list and reaches zero on everything except the