feat(mic)!: standalone SystemMic interface + shipped Resident::M5Mic driver

[genmon]

Replaces #23 (auto-closed by GitHub when its stacked base branch was deleted on #21's merge — same branch and commits, now against main). #21 has merged, so the diff here is exactly the SystemMic v2 change.

SystemMic is no longer a Driver

The mic used nothing from Driver — no Lua module, no events, no update() — and the one coupling it had (the lifecycle set calling void begin()) is exactly what blocked convergence: MicBus needs begin() to report failure, and C++ won't let a subclass change the return type. Three HRD backends with radically different internals (sync I2S, M5Unified's async queue, multi-mic array + AFE stage) had independently converged on the same three methods; that is now the interface:

class SystemMic {
  virtual bool begin() = 0;      // acquire hardware + start capture; false = failed
  virtual void end() {}          // stop + release (shared-codec co-user)
  virtual int  read(int16_t* buf, int maxSamples, int timeoutMs) = 0;
  virtual uint32_t sampleRate() const = 0;
  virtual int frameSamples() const { return 512; }
};

HawthornMicrophone is this, verbatim, plus the two getters — downstream it gets deleted, not adapted. The five-rule contract (capture runs begin()→end(); never hand hardware the caller's buffer; timeoutMs == 0 = don't block; short reads legal; single caller) lives in the header and api.md.

The pump owns capture: startMicStream() begins the mic and now returns bool — false when there is no systemMic or begin() fails, a state that previously silently "streamed" nothing. stopMicStream() ends it. Capture hardware is held only while streaming (what shared mic/speaker codecs need); cost is ~2 frames of priming latency at stream start, imperceptible behind a 500 ms push-to-talk hold.

Resident::M5Mic

src/ResidentM5Mic.h — opt-in (not included by Resident.h), header-only, compiles to nothing without M5Unified, which stays the consumer's dependency. Wiring a mic on any M5 board is now:

#include <ResidentM5Mic.h>
Resident::M5Mic mic;
cfg.systemMic = &mic;

It is hawthorn-firmware #117's on-device-validated M5Microphone ported whole — three-buffer rotation deriving completion from record()'s two-request lag, mic task pinned core 1 / priority 18, audit() health counters — with two deliberate changes:

• timeoutMs == 0 is a non-blocking poll per the contract. HRD's advance() treats <= 0 as block indefinitely — the inversion flagged on #117 — which would hang the sandbox loop under the pump. An empty non-blocking poll is routine and does not count as an Audit::timeouts fault.
• Underrun detection is queue-occupancy-based (isRecording() == 0 outside priming = mic task parked and discarded its DMA chunk), replacing the wait-duration heuristic (waited < 2 ms), which misfires under a non-blocking caller where zero wait is the healthy case. Works for both blocking (MicBus) and non-blocking (pump) callers.

The m5stick-voice example deletes its 120-line M5MicDriver.h; task priorities, memcpy and rotation logic now live once, in the shipped driver.

Verification

• 91/91 native unit cases (3 new pump-ownership tests: begin-once-per-stream / fail-fast / end-on-stop; the lifecycle regression test now also pins "mic NOT begun at setup"), cppcheck clean, all example envs build including both m5stick-voice boards compiling ResidentM5Mic.h.
• Local ESP-IDF v5.5.3 build of espidf-basic (header-only addition; component CMake lists only ResidentSandbox.cpp).
• The pre-port rotation driver was validated on-device today (M5StickS3 → live worker, clean transcript). On-device re-test of this PR pending — same board, exercising the new begin/end-per-hold path.

Downstream (hawthorn-firmware)

After #117 merges and this releases as v0.7.0: bump vendor/resident; delete HawthornMicrophone.hpp + lib/M5Microphone; rename the base class in MicBus/Microphone/MicArray + add sampleRate() one-liners; boards adopt Resident::M5Mic (its Audit surface is unchanged, so existing m5mic.audit() dumps keep working). MicBus needs no behavioural change — begin()->bool, end(), read(...,1000) all already conform.

🤖 Generated with Claude Code