@typecad/framework-zephyr 1.0.0-alpha.14 → 1.0.0-alpha.16

package/dist/strategy.js

@@ -1,9 +1,12 @@
 // ---------------------------------------------------------------------------
 // ZephyrStrategy — Zephyr RTOS target
 //
-// Outputs C++ built with `west` (the Zephyr build tool). Programs use the
-// Arduino-style setup()/loop() pair; a generated main() bridges them into
-// Zephyr's standard C entry point and yields to the scheduler between loops.
+// Outputs C++ built with `west` (the Zephyr build tool). Zephyr is a standard
+// C main()-based RTOS, so the program's entrypoint IS main(): top-level
+// statements lower straight into it. Worker programs keep the scaffolded
+// top-level `while (true)`; event-driven programs (UI / async / native
+// timers) end with a scheduler loop in main() that ticks the UI runtime and
+// pumps microtasks each frame, yielding to the kernel with k_msleep(1).
 //
 // GPIO is lowered through devicetree specs (gpio_pin_*_dt) so an active-low
 // LED's polarity is honored by the DT flags, not by the generated code. See
@@ -14,11 +17,12 @@
 // are covered by the TypeCAD Runtime Exception (see RUNTIME_EXCEPTION.md at the
 // repository root) and are not subject to the license of this tool source.
 // ---------------------------------------------------------------------------
-import { buildWorkerRuntimePolyfill } from '@typecad/cuttlefish/api/shared';
 import { applyStringMethodRewrites } from '@typecad/cuttlefish/api/shared';
 import { programUsesSafety } from '@typecad/cuttlefish/api';
 import { entryHasUI } from '@typecad/cuttlefish/ui-hook';
-import { chipForTarget, setActiveChip } from './chips/index.js';
+import { generateBoard, generateBoardModuleFromContract } from './boardgen.js';
+import { syncBoardCatalog, ensureFreshBoardCatalog, } from './sdk/board-catalog-sync.js';
+import { setActiveChip, NO_BOARD_CHIP } from './chips/index.js';
 import { resolveChipFromBoard } from './chips/resolve.js';
 import { emitGpioDevDispatcher } from './chips/controllers.js';
 /**
@@ -29,15 +33,11 @@ import { emitGpioDevDispatcher } from './chips/controllers.js';
  * hygiene: every emitted function/variable is referenced). `undefined`
  * (no program — probe paths) means "no information": callers emit every
  * descriptor channel, preserving probe behavior.
- *
- * `pwm` also covers tone.* — the tone lowering drives the descriptor's
- * first PWM spec regardless of pin, so any tone op marks it used.
  */
 function collectUsedPins(program, kind, chip) {
     if (!program)
         return undefined;
     const pins = new Set();
-    let usesTone = false;
     const visit = (node) => {
         if (!node || typeof node !== 'object')
             return;
@@ -48,13 +48,11 @@ function collectUsedPins(program, kind, chip) {
             const name = o.operation;
             const pin = o.pin;
             if (typeof name === 'string' && typeof pin === 'number') {
-                if (kind === 'adc' && (name === 'adc.read' || name === 'adc.read_voltage'))
+                if (kind === 'adc' && (name === 'adc.read' || name === 'adc.read_voltage' || name === 'adc.read_raw' || name === 'adc.read_mv'))
                     pins.add(pin);
                 if (kind === 'pwm' && name.startsWith('pwm.'))
                     pins.add(pin);
             }
-            if (kind === 'pwm' && typeof name === 'string' && name.startsWith('tone.'))
-                usesTone = true;
         }
         for (const v of Object.values(n)) {
             if (Array.isArray(v)) {
@@ -66,24 +64,320 @@ function collectUsedPins(program, kind, chip) {
         }
     };
     visit(program);
-    if (kind === 'pwm' && usesTone) {
-        const first = chip?.pwm?.specs[0];
-        if (first)
-            pins.add(first.pin);
-    }
     return pins;
 }
+/**
+ * The inline-override escape hatch: ADC ops carrying construction-time
+ * device overrides (hal/adc-pin.ts opts) name DT device labels the manifest
+ * may not know — the shim's init block must declare their device handles
+ * (the reads reference them) and fire even when the chip has no adc facts
+ * at all.
+ */
+function collectAdcOverrideDevices(program) {
+    const devices = new Set();
+    if (!program)
+        return devices;
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        const op = n.operation;
+        if (op && typeof op === 'object') {
+            const o = op;
+            if (typeof o.operation === 'string' && o.operation.startsWith('adc.')
+                && typeof o.deviceOverride === 'string' && o.deviceOverride !== '') {
+                devices.add(o.deviceOverride);
+            }
+        }
+        for (const v of Object.values(n)) {
+            if (Array.isArray(v)) {
+                for (const item of v)
+                    visit(item);
+            }
+            else if (v && typeof v === 'object')
+                visit(v);
+        }
+    };
+    visit(program);
+    return devices;
+}
+/**
+ * PWM construction-time overrides (the escape hatch): controller+channel
+ * vouched for by the user on pins the manifest may not map. The shim emits
+ * their alias vars; the overlay regen's marker merge creates the DT nodes.
+ */
+function collectPwmOverrideSpecs(program) {
+    const specs = [];
+    if (!program)
+        return specs;
+    const seen = new Set();
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        const op = n.operation;
+        if (op && typeof op === 'object') {
+            const o = op;
+            const ctrl = typeof o.controllerOverride === 'string' && o.controllerOverride !== '' ? o.controllerOverride : undefined;
+            const ch = typeof o.channelOverride === 'number' && o.channelOverride >= 0 ? o.channelOverride : undefined;
+            if (typeof o.operation === 'string' && o.operation.startsWith('pwm.')
+                && typeof o.pin === 'number' && (ctrl || ch !== undefined) && !seen.has(o.pin)) {
+                seen.add(o.pin);
+                specs.push({ pin: o.pin, controller: ctrl ?? 'pwm0', channel: ch ?? 0 });
+            }
+        }
+        for (const v of Object.values(n)) {
+            if (Array.isArray(v)) {
+                for (const item of v)
+                    visit(item);
+            }
+            else if (v && typeof v === 'object')
+                visit(v);
+        }
+    };
+    visit(program);
+    return specs;
+}
+/**
+ * Which I2C/SPI/UART controller indexes the program actually drives (parsed
+ * from the ops' bus/port id, same as the lowerings' parseControllerIndex).
+ * `undefined` (no program — probe paths) means "no information": callers
+ * emit every declared controller, preserving probe behavior.
+ *
+ * The per-controller state blocks are emitted only for these indexes — an
+ * unused declared controller's `__tc_<bus>N_dev` would trip -Werror's
+ * -Wunused-variable (Zephyr builds with warnings-as-errors), the same
+ * hygiene collectUsedPins enforces for per-channel ADC/PWM state.
+ */
+function collectUsedBusIndices(program) {
+    if (!program)
+        return undefined;
+    const indices = { i2c: new Set(), spi: new Set(), uart: new Set() };
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        const op = n.operation;
+        if (op && typeof op === 'object') {
+            const o = op;
+            const name = o.operation;
+            if (typeof name === 'string') {
+                const m = name.match(/^(i2c|spi|uart)\./);
+                if (m) {
+                    const bus = m[1];
+                    const id = typeof o.bus === 'string' ? o.bus : typeof o.port === 'string' ? o.port : undefined;
+                    // parseControllerIndex() (what the lowering uses to pick the state
+                    // prefix) maps a digitless alias like 'Wire'/'SPI'/'Serial' to
+                    // controller 0 — the collector must agree, or the state block for
+                    // controller 0 is skipped and every __tc_<bus>0_* reference dangles.
+                    const idx = id?.match(/(\d+)$/);
+                    indices[bus].add(idx ? parseInt(idx[1], 10) : 0);
+                }
+            }
+        }
+        for (const v of Object.values(n)) {
+            if (Array.isArray(v)) {
+                for (const item of v)
+                    visit(item);
+            }
+            else if (v && typeof v === 'object')
+                visit(v);
+        }
+    };
+    visit(program);
+    return indices;
+}
+/**
+ * Collect the distinct DT-bound sensors the program's ops reference, as
+ * `${part}|${bus}|${address}` keys (same shape as peripheral-usage's
+ * sensorPartsUsed). Feeds the per-sensor device-handle state block — only
+ * constructed sensors emit state, and only sensors whose ops were emitted
+ * get a DT node.
+ */
+export function collectSensors(program) {
+    if (!program)
+        return undefined;
+    const sensors = new Map();
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        const op = n.operation;
+        if (op && typeof op === 'object') {
+            const o = op;
+            if (o.operation === 'sensor.fetch' || o.operation === 'sensor.get') {
+                const part = String(o.part ?? '');
+                const bus = String(o.bus ?? '');
+                const port = o.port ?? 0;
+                const busKind = String(o.busKind ?? 'i2c');
+                const spiHz = o.spiHz ?? 0;
+                const spiMode = o.spiMode ?? 0;
+                const alertPin = o.alertPin ?? -1;
+                const key = `${part}|${bus}|${port}|${busKind}`;
+                if (!sensors.has(key))
+                    sensors.set(key, { part, bus, port, busKind, spiHz, spiMode, alertPin });
+            }
+        }
+        for (const v of Object.values(n)) {
+            if (Array.isArray(v)) {
+                for (const item of v)
+                    visit(item);
+            }
+            else if (v && typeof v === 'object')
+                visit(v);
+        }
+    };
+    visit(program);
+    return sensors;
+}
+/**
+ * Collect the distinct thin SPI targets the program's ops reference
+ * (spi.transceive / spi.dev_write), keyed `${bus}|${cs}`. Mirrors
+ * collectSensors: only constructed targets whose ops were emitted get a
+ * spi_dt_spec state block and a DT child node.
+ */
+export function collectSpiTargets(program) {
+    if (!program)
+        return undefined;
+    const targets = new Map();
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        const op = n.operation;
+        if (op && typeof op === 'object') {
+            const o = op;
+            if (o.operation === 'spi.transceive' || o.operation === 'spi.dev_write' || o.operation === 'spi.reg_read') {
+                const bus = String(o.bus ?? '');
+                const cs = o.cs ?? 0;
+                const key = `${bus}|${cs}`;
+                if (!targets.has(key)) {
+                    targets.set(key, { bus, cs, hz: o.hz ?? 0, mode: o.mode ?? 0 });
+                }
+            }
+        }
+        for (const v of Object.values(n)) {
+            if (Array.isArray(v)) {
+                for (const item of v)
+                    visit(item);
+            }
+            else if (v && typeof v === 'object')
+                visit(v);
+        }
+    };
+    visit(program);
+    return targets;
+}
+/**
+ * Collect the distinct UART RX rings the program reads (uart.rx_* ops),
+ * keyed by controller index. Mirrors collectSpiTargets: only ports whose RX
+ * ops were emitted get a ring + ISR (an unused ISR is -Wunused-function
+ * under Zephyr's -Werror).
+ */
+export function collectUartRings(program) {
+    if (!program)
+        return undefined;
+    const rings = new Map();
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        const op = n.operation;
+        if (op && typeof op === 'object') {
+            const o = op;
+            if (o.operation === 'uart.rx_arm' || o.operation === 'uart.rx_available'
+                || o.operation === 'uart.rx_peek' || o.operation === 'uart.rx_read') {
+                const port = String(o.port ?? 'UART0');
+                const m = port.match(/(UART|uart)(\d+)/) ?? port.match(/(\d+)/);
+                const index = m ? parseInt(m[m.length - 1], 10) : 0;
+                if (!rings.has(index)) {
+                    rings.set(index, { index, ring: o.ring ?? 64 });
+                }
+            }
+        }
+        for (const v of Object.values(n)) {
+            if (Array.isArray(v)) {
+                for (const item of v)
+                    visit(item);
+            }
+            else if (v && typeof v === 'object')
+                visit(v);
+        }
+    };
+    visit(program);
+    return rings;
+}
+/**
+ * Collect the distinct threads the program STARTS (thread.start ops), keyed
+ * by instance. Only started threads emit state — see shimLines.
+ */
+export function collectThreads(program) {
+    if (!program)
+        return undefined;
+    const threads = new Map();
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        const op = n.operation;
+        if (op && typeof op === 'object') {
+            const o = op;
+            if (o.operation === 'thread.start') {
+                const instance = o.instance ?? 0;
+                if (!threads.has(instance)) {
+                    threads.set(instance, { instance, stackBytes: o.stackBytes ?? 2048, priority: o.priority ?? 5 });
+                }
+            }
+        }
+        for (const v of Object.values(n)) {
+            if (Array.isArray(v)) {
+                for (const item of v)
+                    visit(item);
+            }
+            else if (v && typeof v === 'object')
+                visit(v);
+        }
+    };
+    visit(program);
+    return threads;
+}
 import { lowerHalOp } from './lowering/index.js';
-import { buildZephyrWorkerBacking } from './lowering/worker-backing.js';
-import { adcInitLines } from './lowering/adc.js';
+import { adcInitLines, adcChannelForPin } from './lowering/adc.js';
 import { pwmInitLines } from './lowering/pwm.js';
 import { dacInitLines } from './lowering/dac.js';
 import { fsInitLines } from './lowering/fs.js';
 import { hwtimerInitLines } from './lowering/hwtimer.js';
 import { i2cInitLines } from './lowering/i2c.js';
+import { sensorStateLines } from './lowering/sensor.js';
+import { spiTargetStateLines } from './lowering/spi.js';
+import { threadStateLines } from './lowering/thread.js';
+import { uartRingStateLines } from './lowering/uart.js';
 import { spiInitLines } from './lowering/spi.js';
 import { uartInitLines } from './lowering/uart.js';
-import { interruptInitLines } from './lowering/interrupts.js';
+import { usbInitLines, usbdDeviceLines } from './lowering/usb.js';
+/**
+ * STM32F4 boot-time DBGMCU setup: set DBG_SLEEP|DBG_STOP|DBG_STANDBY
+ * (DBGMCU_CR @ 0xE0042004, bits 0–2) so SWD stays attachable while the app
+ * sleeps. RCC_APB1ENR (0x40023840) bit 18 clocks the DBGMCU first — F4 gates
+ * register access behind it. Raw-register form (not the STM32 LL headers) so
+ * the shim stays include-light; AUTOSAR-clean via reinterpret_cast.
+ */
+function stm32f4DbgmcuLines() {
+    return [
+        '// CUTTLEFISH_STM32_DBGMCU_BEGIN',
+        '#include <zephyr/init.h>',
+        'static int __tc_stm32_dbgmcu_keep_swd_alive(void) {',
+        '    volatile uint32_t* const rcc_apb1enr = reinterpret_cast<volatile uint32_t*>(0x40023840);',
+        '    *rcc_apb1enr = *rcc_apb1enr | (1UL << 18);',
+        '    volatile uint32_t* const dbgmcu_cr = reinterpret_cast<volatile uint32_t*>(0xE0042004);',
+        '    *dbgmcu_cr = *dbgmcu_cr | 0x7u;',
+        '    return 0;',
+        '}',
+        'SYS_INIT(__tc_stm32_dbgmcu_keep_swd_alive, PRE_KERNEL_1, 0);',
+        '// CUTTLEFISH_STM32_DBGMCU_END',
+    ];
+}
+import { interruptInitLines, collectInterruptPins } from './lowering/interrupts.js';
 import { wdtInitLines } from './lowering/wdt.js';
 import { bleInitLines } from './lowering/ble.js';
 import { wifiInitLines } from './lowering/wifi.js';
@@ -93,7 +387,6 @@ import { preferencesInitLines } from './lowering/preferences.js';
 import { randomInitLines } from './lowering/random.js';
 import { generateZephyrInitCode, generateZephyrBreakpointCode, generateZephyrLogpointCode } from './debug-codegen.js';
 import { generateStaticAsyncRuntime } from '@typecad/cuttlefish/api/shared';
-import { buildTimerPolyfill } from './async/timer-polyfill.js';
 import { resolveZephyrDisplayOp, newDisplayState } from './display/index.js';
 import { buildDisplayRuntime } from './display/gfx.js';
 import { ZEPHYR_DISPLAY_PROFILES, BUILT_IN_PROFILES } from './display/profiles.js';
@@ -103,11 +396,6 @@ export class ZephyrStrategy {
     constructor() {
         this.id = 'zephyr';
         this._largeEnumNames = new Set();
-        // ── Worker offload backing (Phase 1) ─────────────────────────────────────
-        // Delegates to the Zephyr backing (worker-backing.ts): k_work system
-        // workqueue + k_sem for completion. k_sem provides the kernel memory barrier
-        // the dual-core contract requires (the worker runs on a workqueue thread).
-        this._workerBacking = buildZephyrWorkerBacking();
         // Display state (mirrors Arduino's _displayCtx). Seeded on display.init; the
         // validator-probe path seeds the default profile lazily.
         this._displayState = newDisplayState();
@@ -118,24 +406,36 @@ export class ZephyrStrategy {
      * by the methods that need the descriptor (shimLines, resolveHALOperation
      * via lowerHalOp).
      *
-     * Tries to derive the chip descriptor from the board/MCU package's zephyr
-     * fields (via boardConstants) first. Falls back to the hardcoded
-     * chipForTarget registry for boards that haven't shipped zephyr config yet.
+     * The chip descriptor derives from the board/MCU manifest's zephyr
+     * fields (via boardConstants). There is no registry fallback — a board
+     * that never generated a manifest stays NO_BOARD_CHIP.
      */
+    /**
+     * Eagerly resolve + cache the chip for `program`. The emitter calls this
+     * before rendering any bodies — hal-op lowering reads the module-global
+     * chip cache, and the lazy resolve (inside shimLines) runs later than the
+     * first lowered statement.
+     */
+    prepareChip(program, ctx) {
+        this.resolveChip(ctx, program);
+    }
+    /**
+     * Contract-board generation: a custom PCB spec (typecad contract) names
+     * its wired pads and bus families; the SoC's bus controller labels come
+     * from the installed Zephyr tree's soc dtsi. Same builder as every board.
+     */
+    generateContractBoardModule(opts) {
+        return generateBoardModuleFromContract(opts);
+    }
     resolveChip(ctx, program) {
-        // 1. Try board/MCU package constants (new path)
+        // The chip view reconstructs from the project's generated board
+        // manifest (boardgen's zephyr.* constants) — the one path, for every
+        // board. No curated registry, no target-based fallback: a program with
+        // no board data resolves NO_BOARD_CHIP and the lowering reports
+        // unsupported per subsystem.
         const fromBoard = resolveChipFromBoard(program?.boardConstants);
-        if (fromBoard) {
-            setActiveChip(fromBoard);
-            return fromBoard;
-        }
-        // 2. Fall back to frameworkData.buildTarget → hardcoded registry
-        const fd = ctx?.frameworkData;
-        const target = fd?.target ??
-            fd?.buildTarget;
-        const chip = chipForTarget(target);
-        setActiveChip(chip);
-        return chip;
+        setActiveChip(fromBoard ?? NO_BOARD_CHIP);
+        return fromBoard ?? NO_BOARD_CHIP;
     }
     /**
      * Resolve the debug mode for the active target from the platform context.
@@ -165,6 +465,7 @@ export class ZephyrStrategy {
         // true so nothing is stripped — mirrors framework-esp32's forcedIncludes.
         const a = ctx?.analysis;
         const uses = (f) => (a ? !!a[f] : true);
+        const chip = this.resolveChip(ctx, _program);
         // <zephyr/drivers/gpio.h> and <cstdint> stay unconditional: gpio.h is
         // cross-cutting (gpio/power/interrupt/spi/pulse lowerings + the DT-spec
         // machinery all reference its API, and no single usesX flag owns it), and
@@ -178,12 +479,14 @@ export class ZephyrStrategy {
         // A program touching none of those needs no <cstdio>.
         const helpers = a?.usedPolyfillHelpers;
         const needsCstdio = uses('usesCstdio') || uses('usesFS') || uses('usesPreferences')
-            || uses('usesUart')
+            || uses('usesUart') || uses('usesUsb')
             || !!helpers?.has('__tc_print') || !!helpers?.has('__tc_println');
         if (needsCstdio)
             inc.push('<cstdio>');
         if (uses('usesI2C'))
             inc.push('<zephyr/drivers/i2c.h>');
+        if (uses('usesSensor'))
+            inc.push('<zephyr/drivers/sensor.h>');
         if (uses('usesSPI'))
             inc.push('<zephyr/drivers/spi.h>');
         if (uses('usesUart'))
@@ -194,6 +497,17 @@ export class ZephyrStrategy {
         // emitted, so skip the include there to avoid pulling in an unused header.
         if (isPrintf && !inc.includes('<zephyr/drivers/uart.h>'))
             inc.push('<zephyr/drivers/uart.h>');
+        // USB CDC serial: the class instance is a UART device (uart.h); the
+        // device context macros + usbd_* API live in the next-stack header.
+        if (uses('usesUsb')) {
+            if (!inc.includes('<zephyr/drivers/uart.h>'))
+                inc.push('<zephyr/drivers/uart.h>');
+            inc.push('<zephyr/usb/usbd.h>');
+            // touch-to-reset shim callback reboots via NVIC_SystemReset()
+            // (RAM-retaining Cortex-M reset — no CONFIG_REBOOT needed).
+            if (chip?.usb?.touchReset)
+                inc.push('<cmsis_core.h>');
+        }
         if (uses('usesADC'))
             inc.push('<zephyr/drivers/adc.h>');
         if (uses('usesPWM'))
@@ -208,10 +522,8 @@ export class ZephyrStrategy {
         // Hardware timers via the counter driver.
         if (uses('usesHwtimer'))
             inc.push('<zephyr/drivers/counter.h>');
-        if (uses('usesWDT'))
+        if (uses('usesWDT') || uses('usesWdt'))
             inc.push('<zephyr/drivers/watchdog.h>');
-        if (uses('usesPower'))
-            inc.push('<zephyr/pm/pm.h>', '<zephyr/pm/state.h>', '<zephyr/pm/policy.h>');
         // BLE: the bt_* GATT API + the flat-string headers the shim uses. <string>
         // is needed because a Utf8 (BleValueType.Utf8) read handler lowers to a
         // std::string-returning function (the string literal return type), and the
@@ -411,64 +723,178 @@ export class ZephyrStrategy {
         if (uses('usesNullishHelper')) {
             guardBody.push('template<typename T> inline bool cuttlefish_is_nullish(const T& v) { return false; }', 'inline bool cuttlefish_is_nullish(long long v) { return v == CUTTLEFISH_UNDEFINED; }', 'inline bool cuttlefish_is_nullish(int v) { return v == CUTTLEFISH_UNDEFINED; }', 'inline bool cuttlefish_is_nullish(double v) { return v == static_cast<double>(CUTTLEFISH_UNDEFINED); }', 'inline bool cuttlefish_is_nullish(bool v) { return v == false; }', 'template<typename T> inline bool cuttlefish_is_nullish(T* v) { return v == nullptr; }', 'template<typename T> inline bool cuttlefish_exists(const T& v) { return !cuttlefish_is_nullish(v); }', 'template<typename T, typename U> inline T cuttlefish_nullish(const T& a, U b) { return !cuttlefish_is_nullish(a) ? a : (T)b; }');
         }
-        // millis() backed by the Zephyr uptime counter. uint32_t return matches
-        // the Arduino API the shared runtime expects (wraps every ~49.7 days).
-        // Kept when the program reads the clock itself — usesWallClock,
-        // deliberately WITHOUT the delay() conflation usesMillis carries, because
-        // Zephyr's delay lowers straight to k_msleep — or has a hidden poller:
-        // async functions / the async runtime, the setInterval/setTimeout
-        // scheduler, or a mounted UI's per-frame tick.
+        // The runtime clock contract: __tc_now_ms() is the monotonic ms clock
+        // the shared runtimes (UI per-frame tick, async timers, scheduler)
+        // and currentTimeMillis() lower onto. Emitted whenever anything could
+        // read the clock: explicit Time calls, async, the interval/timeout
+        // scheduler, or a mounted UI. uint32_t wraps every ~49.7 days — every
+        // consumer compares by subtraction, so the wrap is harmless.
         if (uses('usesWallClock') || uses('hasAsync') || (!a || a.timerCallCount > 0)
             || this.programUsesAsyncRuntime(program) || entryHasUI()) {
-            guardBody.push('inline unsigned long millis() { return static_cast<unsigned long>(k_uptime_get_32()); }');
+            guardBody.push('inline uint32_t __tc_now_ms(void) { return k_uptime_get_32(); }');
         }
-        // PROGMEM: only the (Arduino-oriented) UI runtime header can reference it.
-        if (entryHasUI()) {
-            guardBody.push('#ifndef PROGMEM', '#define PROGMEM', '#endif');
+        // Num fluent math (Num.abs/min/max) + the free math trio.
+        // On Zephyr newlib none of these
+        // names are macros, so the underscore-escape rewrite the
+        // strategy needs is not. abs(long)/min/max deliberately overload (not
+        // shadow) newlib's abs(int) — exact-match int calls still resolve to the
+        // libc overload.
+        if (uses('usesNum')) {
+            guardBody.push('struct __tc_Num {', '    static long abs(long x) { return x < 0 ? -x : x; }', '    static long min(long a, long b) { return a < b ? a : b; }', '    static long max(long a, long b) { return a > b ? a : b; }', 
+            // The core emitter escapes abs/min/max member calls to a trailing
+            // underscore (C-library collision) — provide the escaped spellings so
+            // Num.abs_()/Num.min_()/Num.max_() resolve too.
+            '    static long abs_(long x) { return x < 0 ? -x : x; }', '    static long min_(long a, long b) { return a < b ? a : b; }', '    static long max_(long a, long b) { return a > b ? a : b; }', '} Num;', 'inline long abs(long v) { return v < 0 ? -v : v; }', 'inline long min(long a, long b) { return a < b ? a : b; }', 'inline long max(long a, long b) { return a > b ? a : b; }', 
+            // Escaped free-function spellings — the escape applies to bare call
+            // sites on some paths (abs_(-42)); cover both.
+            'inline long abs_(long v) { return v < 0 ? -v : v; }', 'inline long min_(long a, long b) { return a < b ? a : b; }', 'inline long max_(long a, long b) { return a > b ? a : b; }');
         }
-        // map()/constrain() Arduino-API helpers — dead code unless called. The
-        // setup emitter ORs entryHasUI() into usesConstrain before we see it (the
-        // UI runtime's progress/range draw calls constrain).
-        if (uses('usesMap')) {
-            guardBody.push('inline long map(long x, long in_min, long in_max, long out_min, long out_max) { return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min; }');
+        // Random PRNG shim: the Random namespace lowers to the __tc_rand_* PRNG.
+        // Emitted when the program actually uses the random.* ops, so a minimal
+        // program's shim stays empty. The dispatcher + PRNG helpers must precede
+        // the shims that call them (the guard block emits in push order, and
+        // C++ needs the definitions before use).
+        if (this.needsGpioReadShim(program, ctx)) {
+            guardBody.push(...emitGpioDevDispatcher(chip));
         }
-        if (uses('usesConstrain')) {
-            guardBody.push('inline long constrain(long x, long a, long b) { return x < a ? a : (x > b ? b : x); }');
+        if (uses('usesRandom')) {
+            guardBody.push(...randomInitLines());
+        }
+        // PROGMEM note: only some UI runtime headers reference it.
+        if (entryHasUI()) {
+            guardBody.push('#ifndef PROGMEM', '#define PROGMEM', '#endif');
         }
         // Test-runner console helpers: @typecad/expect's Zephyr shim calls these
         // for protocol output. Overloaded for string (const char*) and numeric
         // (double) so the same call site works for markers and test values.
-        // Emitted only when the expect preprocessor actually injected the calls
-        // (tracked as usedPolyfillHelpers).
-        if (!a || !!helpers?.has('__tc_print') || !!helpers?.has('__tc_println')) {
-            guardBody.push('inline void __tc_print(const char* s) { printf("%s", s); }', 'inline void __tc_print(double v) { printf("%g", v); }', 'inline void __tc_println(const char* s) { printf("%s\\n", s); }', 'inline void __tc_println(double v) { printf("%g\\n", v); }');
+        // The fs lowering bakes __tc_println into its error paths too, so the
+        // overloads are emitted unconditionally — ctx.analysis can be absent or
+        // stale on UI programs, and missing definitions would be a link error.
+        //
+        // The numeric form formats via INTEGER conversions only: libc float
+        // printf is not dependable across SDKs — the 0.17.5 toolchain swapped
+        // newlib for picolibc, whose default build silently prints NOTHING for
+        // %g (the same trap as newlib-nano's -u _printf_float), which emptied
+        // every [TC:EXPECT:...:value:] line. Integer %lld works in every libc
+        // configuration, and the host parser accepts plain fixed-point.
+        {
+            guardBody.push('inline void __tc_print(const char* s) { printf("%s", s); }', [
+                'static inline char* __tc_fmt_num_buf(double v, char* out, size_t cap) {',
+                '    if (v != v) { snprintf(out, cap, "nan"); return out; }',
+                '    double a = v < 0 ? -v : v;',
+                '    long long ip = (long long)a;',
+                '    long long fr = (long long)((a - (double)ip) * 1000000.0 + 0.5);',
+                '    if (fr >= 1000000LL) { ip += 1LL; fr = 0LL; }',
+                '    int used = 0;',
+                '    if (v < 0 && (ip != 0LL || fr != 0LL)) { out[used++] = \'-\'; out[used] = \'\\0\'; }',
+                '    if (fr == 0LL) { snprintf(out + used, cap - (size_t)used, "%lld", ip); return out; }',
+                '    char fbuf[8];',
+                '    int len = snprintf(fbuf, sizeof(fbuf), "%06lld", fr);',
+                '    while (len > 0 && fbuf[len - 1] == \'0\') { fbuf[--len] = \'\\0\'; }',
+                '    snprintf(out + used, cap - (size_t)used, "%lld.%s", ip, fbuf);',
+                '    return out;',
+                '}',
+                'static void __tc_fmt_num(double v) { char __b[32]; printf("%s", __tc_fmt_num_buf(v, __b, sizeof(__b))); }',
+            ].join('\n'), 'inline void __tc_print(double v) { __tc_fmt_num(v); }', 'inline void __tc_println(const char* s) { printf("%s\\n", s); }', 'inline void __tc_println(double v) { __tc_fmt_num(v); printf("\\n"); }');
+        }
+        // Serial-port write helper: writes a scalar to a UART/CDC device a byte at
+        // a time. Overloaded on const char* (strings, snprintf buffers) and double
+        // (numbers/booleans) so a single __tc_dev_put(dev, value) call site formats
+        // any writable scalar — the same overload contract __tc_print uses. Emitted
+        // when the program writes a UART or USB port (both include uart.h).
+        if (uses('usesUart') || uses('usesUsb')) {
+            guardBody.push('static inline void __tc_dev_put(const struct device* dev, const char* s) {', '    for (; *s != \'\\0\'; ++s) { uart_poll_out(dev, *s); }', '}', 'static inline void __tc_dev_put(const struct device* dev, double v) {', '    char __b[32];', '    __tc_dev_put(dev, __tc_fmt_num_buf(v, __b, sizeof(__b)));', '}');
         }
         // Per-peripheral bus state — gated on the same ctx.analysis.usesX flags as
         // forcedIncludes, so an unused peripheral emits no state (and its header is
-        // not included). Mirrors framework-esp32's shimLines espInit block.
+        // not included). Mirrors framework-esp32's shimLines espInit block. Within
+        // a bus, only the instances the program drives get state — an unused
+        // declared controller's __tc_<bus>N_dev trips -Wunused-variable under
+        // Zephyr's -Werror (collectUsedBusIndices; probes with no program emit all).
+        const usedBuses = collectUsedBusIndices(program);
         if (uses('usesI2C') && chip.i2c) {
-            for (let i = 0; i < chip.i2c.controllers.length; i++)
+            for (let i = 0; i < chip.i2c.controllers.length; i++) {
+                if (usedBuses && !usedBuses.i2c.has(i))
+                    continue;
                 guardBody.push(...i2cInitLines(chip, i));
+            }
         }
         if (uses('usesSPI') && chip.spi) {
-            for (let i = 0; i < chip.spi.controllers.length; i++)
+            for (let i = 0; i < chip.spi.controllers.length; i++) {
+                if (usedBuses && !usedBuses.spi.has(i))
+                    continue;
                 guardBody.push(...spiInitLines(chip, i));
+            }
         }
         if (uses('usesUart') && chip.uart) {
-            for (let i = 0; i < chip.uart.controllers.length; i++)
+            for (let i = 0; i < chip.uart.controllers.length; i++) {
+                if (usedBuses && !usedBuses.uart.has(i))
+                    continue;
                 guardBody.push(...uartInitLines(chip, i));
+            }
+            // Thin UART RX rings — one interrupt-drained ring per port the program
+            // reads (uart.rx_* ops). Emitted after the device handles it references.
+            const rings = collectUartRings(program);
+            if (rings) {
+                for (const r of rings.values()) {
+                    guardBody.push(...uartRingStateLines(r.index, r.ring));
+                }
+            }
+        }
+        // DT-bound sensors — one state block per constructed part (device handle
+        // + sensor_value scratch). The lowering's __tc_sensor_* references and the
+        // overlay's DT child nodes derive from the same facts (lowering/sensor.ts).
+        if (uses('usesSensor')) {
+            const sensors = collectSensors(program);
+            if (sensors) {
+                for (const s of sensors.values()) {
+                    guardBody.push(...sensorStateLines(s.part, s.bus, s.port, s.busKind, s.spiHz, s.spiMode, s.alertPin));
+                }
+            }
+        }
+        // Thin SPI targets — one spi_dt_spec per constructed target, against the
+        // DT child node the overlay emits. Same shared-facts discipline (the
+        // tc-spit-cfg comment is the overlay scanner's channel).
+        if (uses('usesSPI')) {
+            const targets = collectSpiTargets(program);
+            if (targets) {
+                for (const t of targets.values()) {
+                    guardBody.push(...spiTargetStateLines(t.bus, t.cs, t.hz, t.mode));
+                }
+            }
+        }
+        // Thin Threads — one stack + k_thread + trampoline per started slot.
+        // Keyed on thread.start ops only: join() without a prior start() on the
+        // same index is a user error that surfaces as the undefined slot symbol.
+        {
+            const threads = collectThreads(program);
+            if (threads) {
+                for (const t of threads.values()) {
+                    guardBody.push(...threadStateLines(t.instance, t.stackBytes));
+                }
+            }
+        }
+        if (uses('usesUsb') && chip.usb) {
+            guardBody.push(...usbdDeviceLines(chip));
+            for (let i = 0; i < chip.usb.cdcInstances; i++)
+                guardBody.push(...usbInitLines(chip, i));
+        }
+        // PWM init also fires (with alias vars for the override pins) when a
+        // program drives ONLY inline-override channels on a chip with no pwm
+        // facts — the lowered calls reference those aliases.
+        {
+            const pwmUserSpecs = collectPwmOverrideSpecs(program);
+            if ((uses('usesPWM') && chip.pwm) || pwmUserSpecs.length > 0) {
+                guardBody.push(...pwmInitLines(chip, collectUsedPins(program, 'pwm', chip), pwmUserSpecs));
+            }
         }
-        if (uses('usesADC') && chip.adc)
-            guardBody.push(...adcInitLines(chip, collectUsedPins(program, 'adc')));
-        if (uses('usesPWM') && chip.pwm)
-            guardBody.push(...pwmInitLines(chip, collectUsedPins(program, 'pwm', chip)));
         if (uses('usesDAC') && chip.dac)
             guardBody.push(...dacInitLines(chip));
         if (uses('usesHwtimer') && chip.hwtimer)
             guardBody.push(...hwtimerInitLines(chip));
         if (uses('usesInterrupts'))
-            guardBody.push(...interruptInitLines(chip));
-        if (uses('usesWDT') && chip.wdt)
+            guardBody.push(...interruptInitLines(chip, program ? collectInterruptPins(program) : undefined));
+        if ((uses('usesWDT') || uses('usesWdt')) && chip.wdt)
             guardBody.push(...wdtInitLines(chip));
         if (uses('usesBle'))
             guardBody.push(...bleInitLines());
@@ -499,8 +925,29 @@ export class ZephyrStrategy {
             guardBody.push(...preferencesInitLines());
         if (uses('usesFS'))
             guardBody.push(...fsInitLines());
-        if (uses('usesRandom'))
-            guardBody.push(...randomInitLines());
+        // The ADC init block also fires (with the override devices' handles)
+        // when a program uses ONLY inline-override reads on a chip with no adc
+        // facts — otherwise those reads reference undeclared device handles.
+        {
+            const adcOverrideDevices = collectAdcOverrideDevices(program);
+            if ((uses('usesADC') && chip.adc) || adcOverrideDevices.size > 0) {
+                guardBody.push(...adcInitLines(chip, collectUsedPins(program, 'adc'), adcOverrideDevices));
+            }
+        }
+        // STM32F4: keep the core debug port alive across WFI sleep. The DBGMCU
+        // gates PPB access while the core sleeps unless DBGMCU_CR DBG_SLEEP/
+        // DBG_STOP/DBG_STANDBY are set — without them openocd cannot examine or
+        // halt the running target ("Failed to read memory at 0xe000ed04", "AP
+        // write error, reset will not halt"), and with no RST pad on boards like
+        // the Black Pill the only recovery is the BOOT0 bootloader. Zephyr's
+        // CONFIG_STM32_ENABLE_DEBUG_SLEEP_STOP sets only DBG_STOP on F4 (the
+        // soc_config.c F1/L1 branch is the one that sets DBG_SLEEP), so the bits
+        // are set here at boot, unconditionally for dev boards.
+        // (soc is empty on board-resolved chips — the SoC name rides in the
+        // qualified id's variant segment, e.g. 'blackpill_f411ce/stm32f411xe'.)
+        if (chip.soc.startsWith('stm32f4') || /stm32f4\d*/.test(chip.id)) {
+            guardBody.push(...stm32f4DbgmcuLines());
+        }
         const lines = [];
         if (guardBody.length > 0) {
             lines.push('// cuttlefish runtime shim. Wrapped in a single include guard so the', '// block is safe to emit into multiple headers and .cpp files within', '// one translation unit (a .cpp may #include several headers that each', '// carry the shim). The guard ensures the definitions are seen exactly', '// once per TU.', '#ifndef CUTTLEFISH_SHIM_DEFINED', '#define CUTTLEFISH_SHIM_DEFINED', ...guardBody, '#endif // CUTTLEFISH_SHIM_DEFINED');
@@ -541,18 +988,19 @@ export class ZephyrStrategy {
             lines.push('#ifndef __TC_BP_DISABLED_DEFINED', '#define __TC_BP_DISABLED_DEFINED', 'static bool __tc_bp_disabled[256] = {0};', 'static inline bool __tc_bp_is_disabled(int id) { return id >= 0 && id < 256 && __tc_bp_disabled[id]; }', 
             // Console input: poll the UART console device. DEVICE_DT_GET(DT_CHOSEN(zephyr_console))
             // resolves to the board's console (UART0 USB-CDC on the XIAO nRF52840).
-            'static inline char __tc_debug_wait_for_continue(int id) {', '    const struct device* __con = DEVICE_DT_GET(DT_CHOSEN(zephyr_console));', '    unsigned char __c = 0;', "    while (uart_poll_in(__con, &__c) != 0) {", '        k_msleep(10);', '    }', "    // Drain the rest of the typed line so the next breakpoint waits fresh.", "    unsigned char __peek = 0;", "    while (uart_poll_in(__con, &__peek) == 0 && __peek != '\\n') { (void)0; }", "    if ((__c == 's') || (__c == 'S')) { if (id >= 0 && id < 256) __tc_bp_disabled[id] = true; }", '    return static_cast<char>(__c);', '}', '#endif // __TC_BP_DISABLED_DEFINED', '');
+            // Not every board DTS declares a zephyr,console chosen (STM32MP1 M-side,
+            // display/carrier boards): there is nothing to print a prompt on and
+            // nothing to read a key from, so breakpoints auto-continue instead of
+            // hanging an unattended run.
+            '#if DT_HAS_CHOSEN(zephyr_console)', 'static inline char __tc_debug_wait_for_continue(int id) {', '    const struct device* __con = DEVICE_DT_GET(DT_CHOSEN(zephyr_console));', '    unsigned char __c = 0;', "    while (uart_poll_in(__con, &__c) != 0) {", '        k_msleep(10);', '    }', "    // Drain the rest of the typed line so the next breakpoint waits fresh.", "    unsigned char __peek = 0;", "    while (uart_poll_in(__con, &__peek) == 0 && __peek != '\\n') { (void)0; }", "    if ((__c == 's') || (__c == 'S')) { if (id >= 0 && id < 256) __tc_bp_disabled[id] = true; }", '    return static_cast<char>(__c);', '}', '#else', 'static inline char __tc_debug_wait_for_continue(int id) { (void)id; return static_cast<char>(0); }', '#endif // DT_HAS_CHOSEN(zephyr_console)', '#endif // __TC_BP_DISABLED_DEFINED', '');
         }
-        // --- Zephyr entrypoint: main() runs setup()/loop() directly ---
-        // The cuttlefish synthesizer emits setup() and loop() (it keys off
-        // entrypointFunctionName()="setup" and requiresLoopFunction()=true). Zephyr
-        // is a standard C main()-based RTOS, so main() bridges the two: it calls
-        // setup() once, then loops loop() forever, yielding to the scheduler with
-        // k_msleep(1) each iteration (cheap cooperative yield — matches the esp32
-        // app_main pattern). Declared extern here because setup/loop live in a
-        // separate translation unit when generateHeaderFile() splits them into the
-        // header.
-        lines.push('extern void setup(void);', 'extern void loop(void);', '', 'int main(void) {', '    setup();', '    for (;;) {', '        loop();', '        k_msleep(1);', '    }', '    return 0;', '}');
+        // --- Zephyr entrypoint ---------------------------------------------------
+        // No bridge here: the synthesizer emits main() itself (it keys off
+        // entrypointFunctionName()="main" and requiresLoopFunction()=false), with
+        // the top-level statements inlined. Per-frame driving (ui_tick, microtask
+        // pumping, async task .run()) is appended to main() by the driver
+        // machinery via asyncDriverFunctionName()="main" + hostEventLoop() — see
+        // asyncLoopInjection for the scheduler loop it closes over.
         // GPIO read shim: emitted only when something actually reads a pin at
         // runtime — user digitalRead() calls, the @typecad/safety voter (calls
         // __tc_gpio_read directly), or the UI runtime header's digitalRead() poll
@@ -571,8 +1019,10 @@ export class ZephyrStrategy {
         // dispatcher that resolves the owning controller's device per pin;
         // single-controller SoCs collapse it to a one-liner. Each DT_NODELABEL is
         // still compile-time-resolved per branch, so it is always statically valid.
+        // (The dispatcher itself now lives at the top of the guard block — it must
+        // precede the wiring-ambient shims and the PinGroup factory there; the
+        // __tc_gpio_read body below is what still needs emitting here.)
         if (this.needsGpioReadShim(program, ctx)) {
-            lines.push(...emitGpioDevDispatcher(chip));
             lines.push('inline int __tc_gpio_read(int pin) { return gpio_pin_get_raw(__tc_gpio_dev(static_cast<uint32_t>(pin)), __tc_gpio_pin(static_cast<uint32_t>(pin))); }');
         }
         // __tc_gpio_write / __tc_delay_us are only referenced via @typecad/safety
@@ -591,11 +1041,16 @@ export class ZephyrStrategy {
         // Collect the pins the program uses for output config, ADC reads, and
         // interrupt attaches — deep-walking the IR the same way framework-esp32
         // does (its profileDiagnostics walks program to find gpio.set_mode /
-        // power.deep_sleep_pin / adc.read nodes).
+        // adc.read nodes).
         const outputPins = new Set();
         const adcReadPins = new Set();
+        const adcOverriddenPins = new Set();
+        const pwmOverriddenPins = new Set();
         const interruptPins = new Set();
+        const wdtOps = new Set();
         const dacPins = new Set();
+        const pwmPins = new Set();
+        const busInstances = { i2c: new Set(), spi: new Set(), uart: new Set() };
         const hwtimerInstances = new Set();
         let usesWifiOps = false;
         let usesHttpOps = false;
@@ -610,16 +1065,51 @@ export class ZephyrStrategy {
                         && typeof op.pin === 'number') {
                         outputPins.add(op.pin);
                     }
-                    if ((op.operation === 'adc.read' || op.operation === 'adc.read_voltage')
+                    if ((op.operation === 'adc.read' || op.operation === 'adc.read_voltage'
+                        || op.operation === 'adc.read_raw' || op.operation === 'adc.read_mv')
                         && typeof op.pin === 'number') {
                         adcReadPins.add(op.pin);
+                        // Inline routing overrides (construction opts): the user vouches
+                        // for the pin — the unavailable-pin diagnostic does not apply.
+                        if ((typeof op.channelOverride === 'number' && op.channelOverride >= 0)
+                            || (typeof op.deviceOverride === 'string' && op.deviceOverride !== '')) {
+                            adcOverriddenPins.add(op.pin);
+                        }
                     }
-                    if (op.operation === 'interrupt.attach' && typeof op.pin === 'number') {
+                    if (op.operation === 'interrupt.attach_flags' && typeof op.pin === 'number') {
                         interruptPins.add(op.pin);
                     }
-                    if (op.operation === 'dac.write' && typeof op.pin === 'number') {
+                    if (typeof op.operation === 'string' && op.operation.startsWith('wdt.')) {
+                        wdtOps.add(op.operation);
+                    }
+                    if ((op.operation === 'dac.write' || op.operation === 'dac.write_value')
+                        && typeof op.pin === 'number') {
                         dacPins.add(op.pin);
                     }
+                    if ((op.operation === 'pwm.set_pulse' || op.operation === 'pwm.set_duty'
+                        || op.operation === 'pwm.set_period')
+                        && typeof op.pin === 'number') {
+                        pwmPins.add(op.pin);
+                        if ((typeof op.controllerOverride === 'string' && op.controllerOverride !== '')
+                            || (typeof op.channelOverride === 'number' && op.channelOverride >= 0)) {
+                            pwmOverriddenPins.add(op.pin);
+                        }
+                    }
+                    // Bus instance usage: which I2C/SPI/UART controller indexes the
+                    // program drives (the lowering resolves index N against
+                    // chip.<bus>.controllers[N]; an undeclared index emits references
+                    // to a state block that is never declared → link error).
+                    if (typeof op.operation === 'string') {
+                        const busMatch = op.operation.match(/^(i2c|spi|uart)\./);
+                        if (busMatch) {
+                            const bus = busMatch[1];
+                            const id = typeof op.bus === 'string' ? op.bus
+                                : typeof op.port === 'string' ? op.port : undefined;
+                            const m = id?.match(/(\d+)$/);
+                            if (m)
+                                busInstances[bus].add(parseInt(m[1], 10));
+                        }
+                    }
                     if (typeof op.operation === 'string' && op.operation.startsWith('hwtimer.')) {
                         const inst = typeof op.instance === 'number'
                             ? op.instance
@@ -648,41 +1138,54 @@ export class ZephyrStrategy {
         };
         visit(program);
         // ── ADC pin validity ────────────────────────────────────────────────────
-        // The SAADC lowering resolves a HAL pin to a channel via the chip
-        // descriptor's adc.channels map. A pin not in that map resolves to -1,
-        // which emits __tc_adc-1_setup() — an undefined symbol → link error. Flag
-        // it at compile time with a clear message instead of an opaque link failure.
+        // The SAADC lowering resolves the adc.read argument to a channel via the
+        // chip descriptor's adc.channels map (pin-first, then channel-number
+        // fallback for the Arduino-compat ADC.read(n) form — see
+        // adcChannelForPin). A number resolving to neither emits
+        // __tc_adc-1_setup() — an undefined symbol → link error. Flag it at
+        // compile time with a clear message instead of an opaque link failure.
         const adcPins = new Set((chip.adc?.channels ?? []).map((c) => c.pin));
         for (const pin of adcReadPins) {
-            if (!adcPins.has(pin)) {
+            if (adcOverriddenPins.has(pin))
+                continue;
+            if (adcChannelForPin(chip, pin) < 0) {
                 const valid = [...adcPins].sort((x, y) => x - y).join(', ');
+                // Cross-peripheral suggestion: the facts know what this pin IS wired
+                // to — a PWM-capable pin misread as analog is the classic mix-up.
+                const pwmOnPin = (chip.pwm?.specs ?? []).find((s) => s.pin === pin);
+                const mixup = pwmOnPin
+                    ? ` GPIO ${pin} carries PWM on this board (${pwmOnPin.controller} ch ${pwmOnPin.channel}) — did you mean new PWM(${pin}, …)?`
+                    : '';
                 diags.push({
                     severity: 'error',
                     code: 'zephyr-adc-pin-unavailable',
                     message: `GPIO ${pin} is not a SAADC channel on ${chip.id} and cannot be read with adc.read.`,
                     hint: valid
-                        ? `Use an analog-capable pin. On ${chip.id} (SAADC): ${valid}.`
-                        : `This target has no ADC channels mapped in its chip descriptor.`,
+                        ? `Use an analog-capable pin. On ${chip.id} (SAADC): ${valid}.${mixup}`
+                        : `This target has no ADC channels mapped in its chip descriptor.${mixup}`,
                     source: program.fileName,
                 });
             }
         }
         // ── Interrupt pin validity ──────────────────────────────────────────────
-        // interrupt.attach only wires a real callback for pins listed in the chip
-        // descriptor's gpio.interruptPins (the lowering needs a DT spec to build
-        // the gpio_callback struct at init). An attach on an unlisted pin emits
-        // only a comment — silent no-op. Flag it so the user knows the handler
-        // will never fire.
+        // GPIO.onInterrupt works on every REAL GPIO: pins listed in the chip
+        // descriptor's gpio.interruptPins wire through the DT-spec chain, any
+        // other in-range pin through the raw-controller chain. What cannot work
+        // is a pin number no declared controller range covers (e.g. 99 on a
+        // 34-pin SoC) — that lowering is a comment (silent no-op). Flag only
+        // that case.
         const intPins = new Set((chip.gpio.interruptPins ?? []).map((p) => p.pin));
         for (const pin of interruptPins) {
-            if (!intPins.has(pin)) {
+            if (intPins.has(pin))
+                continue;
+            const inRange = !chip.gpioControllers || chip.gpioControllers.length === 0
+                || chip.gpioControllers.some((r) => pin >= r.minPin && pin <= r.maxPin);
+            if (!inRange) {
                 diags.push({
                     severity: 'error',
                     code: 'zephyr-interrupt-pin-unavailable',
-                    message: `GPIO ${pin} has no interrupt DT spec on ${chip.id}; interrupt.attach is a no-op.`,
-                    hint: intPins.size > 0
-                        ? `Add the pin to the chip descriptor's gpio.interruptPins, or use an interrupt-capable pin: ${[...intPins].sort((x, y) => x - y).join(', ')}.`
-                        : `This target declares no interrupt pins in its chip descriptor; interrupts are not available.`,
+                    message: `GPIO ${pin} does not exist on ${chip.id}; onInterrupt is a no-op.`,
+                    hint: `Use a real GPIO on this board (controller ranges: ${chip.gpioControllers.map((r) => `${r.nodelabel} ${r.minPin}-${r.maxPin}`).join(', ')}).`,
                     source: program.fileName,
                 });
             }
@@ -697,13 +1200,82 @@ export class ZephyrStrategy {
             const dacChannels = new Set((chip.dac?.channels ?? []).map((c) => c.pin));
             for (const pin of dacPins) {
                 if (!dacChannels.has(pin)) {
+                    const adcCh = (chip.adc?.channels ?? []).find((c) => c.pin === pin);
+                    const mixup = adcCh
+                        ? ` GPIO ${pin} is an ADC channel (${adcCh.controller ?? chip.adc?.nodeLabel ?? 'adc'} ch ${adcCh.channel}) — did you mean new ADC(${pin})?`
+                        : '';
                     diags.push({
                         severity: 'error',
                         code: 'zephyr-dac-pin-unavailable',
                         message: `GPIO ${pin} is not a DAC channel on ${chip.id} and cannot be driven with dac.write.`,
                         hint: dacChannels.size > 0
-                            ? `Use a DAC-capable pin. On ${chip.id}: ${[...dacChannels].sort((x, y) => x - y).join(', ')}.`
-                            : `${chip.id} has no DAC. Use an esp32_devkitc target (ESP32 DAC on GPIO25/26).`,
+                            ? `Use a DAC-capable pin. On ${chip.id}: ${[...dacChannels].sort((x, y) => x - y).join(', ')}.${mixup}`
+                            : `${chip.id} has no DAC. Use an esp32_devkitc target (ESP32 DAC on GPIO25/26).${mixup}`,
+                        source: program.fileName,
+                    });
+                }
+            }
+        }
+        // ── PWM pin validity ────────────────────────────────────────────────────
+        // pwm.write resolves a HAL pin to a DT spec via the chip descriptor's
+        // pwm.specs (static) or pwm.matrix (ESP32 LEDC: any matrix pin synthesizes
+        // a spec at build time). A pin on neither lowers to a comment — the pin
+        // silently never toggles. Flag it so the user knows (warning, not error:
+        // boards legitimately ship partial PWM coverage, e.g. only the aliased LED
+        // channel, and the rest of the program still works).
+        const pwmMatrix = chip.pwm?.matrix;
+        const pwmSpecPins = new Set([
+            ...(chip.pwm?.specs ?? []).map((s) => s.pin),
+            ...(pwmMatrix?.pins ?? []),
+        ]);
+        const pwmValid = [...pwmSpecPins].sort((x, y) => x - y).join(', ');
+        for (const pin of pwmPins) {
+            if (pwmOverriddenPins.has(pin))
+                continue;
+            if (!pwmSpecPins.has(pin)) {
+                // Cross-peripheral suggestion: an analog pin driven as PWM is the
+                // other classic mix-up.
+                const adcCh = (chip.adc?.channels ?? []).find((c) => c.pin === pin);
+                const mixup = adcCh
+                    ? ` GPIO ${pin} is an ADC channel (${adcCh.controller ?? chip.adc?.nodeLabel ?? 'adc'} ch ${adcCh.channel}) — did you mean new ADC(${pin})?`
+                    : '';
+                diags.push({
+                    severity: 'warning',
+                    code: 'zephyr-pwm-pin-unavailable',
+                    message: pwmMatrix
+                        ? `pwm on GPIO ${pin} lowers to a no-op: the pin is outside ${chip.id}'s PWM-capable set (USB, flash/PSRAM, strapping, and console pads are excluded), so nothing is driven.`
+                        : `pwm on GPIO ${pin} lowers to a no-op: the pin has no PWM spec in ${chip.id}'s chip descriptor, so nothing is driven.`,
+                    hint: pwmValid
+                        ? pwmMatrix
+                            ? `PWM-capable pins on ${chip.id} (first ${pwmMatrix.channelCount} driven get channels): ${pwmValid}.${mixup}`
+                            : `PWM-capable pins on ${chip.id}: ${pwmValid}.${mixup}`
+                        : `${chip.id} maps no PWM channels in its chip descriptor — pwm.* are no-ops on this target.${mixup}`,
+                    source: program.fileName,
+                });
+            }
+        }
+        // ── Bus instance validity ───────────────────────────────────────────────
+        // The bus lowerings resolve instance N against chip.<bus>.controllers[N]
+        // and emit `__tc_<bus>N_dev` references; the state block is only declared
+        // for declared controllers, so an out-of-range instance is an undefined
+        // symbol at link time. Flag it here with the board's real controller set
+        // instead (mirrors how the ADC gate replaces an opaque link error).
+        const busLabels = {
+            i2c: { name: 'I2C', label: 'Wire' },
+            spi: { name: 'SPI', label: 'SPI' },
+            uart: { name: 'UART', label: 'Serial' },
+        };
+        for (const bus of ['i2c', 'spi', 'uart']) {
+            const controllers = chip[bus]?.controllers ?? [];
+            for (const inst of busInstances[bus]) {
+                if (inst < 0 || inst >= controllers.length) {
+                    diags.push({
+                        severity: 'error',
+                        code: 'zephyr-bus-instance-unavailable',
+                        message: `${busLabels[bus].name}${inst} is used but ${chip.id} declares only ${controllers.length} ${busLabels[bus].name} controller(s) in its Zephyr chip data — the generated code would not link.`,
+                        hint: controllers.length > 0
+                            ? `Use ${busLabels[bus].name}0 (the board's default-enabled controller: ${controllers.map((c) => c.nodeLabel).join(', ')}).`
+                            : `${chip.id} declares no ${busLabels[bus].name} controllers for Zephyr.`,
                         source: program.fileName,
                     });
                 }
@@ -736,12 +1308,34 @@ export class ZephyrStrategy {
                 }
             }
         }
+        // ── Watchdog availability ───────────────────────────────────────────────
+        // wdt.* resolves the device via the chip descriptor's wdt.nodeLabel. A
+        // chip without that entry (e.g. SAM D21 — Zephyr's samd21 dtsi exposes
+        // no watchdog node) lowers to a comment — flag it so the user knows the
+        // watchdog never arms.
+        if (wdtOps.size > 0 && !chip.wdt) {
+            diags.push({
+                severity: 'error',
+                code: 'zephyr-wdt-unavailable',
+                message: `Watchdog ops are used but ${chip.id} exposes no watchdog device.`,
+                hint: `${chip.id} declares no wdt.nodeLabel (Zephyr's devicetree for this SoC has no watchdog node). Use a target with a watchdog, or drop the wdt.* calls.`,
+                source: program.fileName,
+            });
+        }
+        // ── Radio presence: family-derived, not board-curated ───────────────────
+        // Espressif ESP32 variants carry a 2.4GHz WiFi radio; every other Zephyr
+        // family in the catalog is radioless (until an Ethernet/board-wifi fact
+        // exists). Derived from the soc name — or, when no board module was
+        // generated, from the raw build target the config carries.
+        const familyTarget = `${chip.soc || ''} ${ctx?.frameworkData?.target ?? ''} ${ctx?.frameworkData?.buildTarget ?? ''}`.toLowerCase();
+        const wifiSupported = chip.wifi?.supported
+            ?? familyTarget.split(/[^a-z0-9]+/).some((t) => t.startsWith('esp32'));
         // ── WiFi target validity ────────────────────────────────────────────────
         // WiFi ops require a chip with a WiFi radio. The ESP32-S3 descriptor sets
         // wifi.supported; the XIAO nRF52840 omits it (no radio). Flag wifi usage on
         // a radioless chip so the user gets a clear "use an ESP32 target" message
         // instead of an opaque link/DT failure.
-        if (usesWifiOps && !chip.wifi?.supported) {
+        if (usesWifiOps && !wifiSupported) {
             diags.push({
                 severity: 'error',
                 code: 'zephyr-wifi-unavailable-on-target',
@@ -758,7 +1352,7 @@ export class ZephyrStrategy {
         // gets a clear "use an ESP32 target" message instead of an opaque link or
         // runtime failure. (HTTP rides over WiFi here; an Ethernet target would
         // set wifi.supported via a different transport flag if/when added.)
-        if (usesHttpOps && !chip.wifi?.supported) {
+        if (usesHttpOps && !wifiSupported) {
             diags.push({
                 severity: 'error',
                 code: 'zephyr-http-unavailable-on-target',
@@ -770,7 +1364,7 @@ export class ZephyrStrategy {
         // ── MQTT target validity ─────────────────────────────────────────────
         // Same constraint as HTTP: MQTT needs a network transport to reach a broker.
         // Flag mqtt usage on a radioless chip so the user picks a networked target.
-        if (usesMqttOps && !chip.wifi?.supported) {
+        if (usesMqttOps && !wifiSupported) {
             diags.push({
                 severity: 'error',
                 code: 'zephyr-mqtt-unavailable-on-target',
@@ -786,32 +1380,45 @@ export class ZephyrStrategy {
         return diags;
     }
     /**
-     * `loop` is forward-declared `extern` by the main() bridge shim
-     * (extern void loop(void); → int main(void) {...}), so emitting a
-     * `static void loop()` definition redeclares it with conflicting linkage,
-     * which GCC rejects. Exclude it from the static forward-declaration path
-     * — mirrors how ArduinoStrategy excludes `loop` (the Arduino core forward-
-     * declares it extern). `setup` is already handled because it equals
+     * Strip Arduino library headers that @typecad/hal's class surfaces register
+     * (I2CBus → <Wire.h>, SPIBus → <SPI.h>). The Zephyr
+     * equivalents are usage-gated forcedIncludes (<zephyr/drivers/i2c.h>, …),
+     * so an unstripped Wire.h reaches the west build and gcc rejects it
+     * ("Wire.h: No such file or directory") — this hook is why I2C/SPI class
+     * usage on Zephyr used to fail at compile time.
+     */
+    filterRequiredIncludes(includes) {
+        // Arduino-core / AVR-only headers the HAL classes declare via __includes.
+        // On Zephyr the watchdog lowers to the Zephyr driver (<zephyr/drivers/
+        // watchdog.h>, forced under usesWDT) — <avr/wdt.h> does not exist there.
+        const arduinoOnlyHeaders = new Set(['<Wire.h>', '<SPI.h>', '<avr/wdt.h>', '<avr/io.h>', '<avr/interrupt.h>', '<avr/sleep.h>', '<avr/power.h>']);
+        return includes.filter((i) => !arduinoOnlyHeaders.has(i));
+    }
+    /**
+     * Nothing to exclude: no shim or Zephyr core header forward-declares a user
+     * function extern (the old setup()/loop() bridge was the only consumer of
+     * this hook, excluding `loop`). The entrypoint itself (`main`) is already
+     * excluded from the static forward-declaration path because it equals
      * entrypointFunctionName().
      */
     forwardDeclarationExclusions() {
-        return ['loop'];
+        return [];
     }
     // ── File shape ──────────────────────────────────────────────────────────
     sourceExtension() {
         return 'cpp';
     }
     entrypointFunctionName() {
-        return 'setup';
+        return 'main';
     }
     requiresLoopFunction() {
-        return true;
+        return false;
     }
     overrideBaseName(originalBaseName, outDirBaseName, isEntryFile, isNpmPackage) {
         // npm packages are library-style — don't rename. Entry files (non-npm) take
-        // the out-dir name (mirrors Arduino's .ino-must-match-dir rule). Everything
-        // else passes through. (The manifest's entrypoint.overrideBaseName field is
-        // dead — never read in src/ — so this method is the sole name source.)
+        // the out-dir name (mirrors the directory-name-must-match-entry rule).
+        // Everything else passes through. (The manifest's entrypoint.overrideBaseName
+        // field is dead — never read in src/ — so this method is the sole name source.)
         if (isNpmPackage)
             return originalBaseName;
         if (isEntryFile)
@@ -819,8 +1426,8 @@ export class ZephyrStrategy {
         return originalBaseName;
     }
     effectiveEmitMode(requestedMode, _isNpmPackage) {
-        // Zephyr always emits .cpp (no .ino equivalent to force away from), so this
-        // is passthrough regardless of npm/app. The 2-param shape matches the
+        // Zephyr always emits .cpp (no single-file entry equivalent to force away
+        // from), so this is passthrough regardless of npm/app. The 2-param shape
         // interface and Arduino; behavior is identical across branches.
         return requestedMode;
     }
@@ -840,8 +1447,6 @@ export class ZephyrStrategy {
     mapReturnType(functionName, returnType) {
         if (functionName === 'main')
             return 'int';
-        if (functionName === 'setup' || functionName === 'loop')
-            return 'void';
         return this.normalizeCppType(returnType);
     }
     isStringLikeType(cppType) {
@@ -929,26 +1534,6 @@ export class ZephyrStrategy {
         // A throw becomes an infinite halt loop instead of a real throw.
         return 'for (;;) { k_msleep(1000); }';
     }
-    isConsoleCall(callee) {
-        return callee.startsWith('console.');
-    }
-    transformConsoleCall(method, renderedArgs, forHeader) {
-        const semi = forHeader ? '' : ';';
-        const empty = !renderedArgs || renderedArgs.trim() === '';
-        const tag = method === 'error' ? '[ERROR] ' : method === 'warn' ? '[WARN] ' : '';
-        if (empty)
-            return `printk("%s\\n", "${tag}")${semi}`;
-        const parts = renderedArgs.split(' << ');
-        if (parts.length === 1) {
-            return `printk("%s%s\\n", "${tag}", (${renderedArgs}))${semi}`;
-        }
-        const fmt = '%s' + '%s'.repeat(parts.length) + '\\n';
-        const args = [`"${tag}"`, ...parts].join(', ');
-        return `printk("${fmt}", ${args})${semi}`;
-    }
-    transformConsoleExpression(_method, _renderedArgs) {
-        return undefined;
-    }
     objectFieldInitializer() {
         return undefined;
     }
@@ -985,18 +1570,6 @@ export class ZephyrStrategy {
                     reason: 'delayMicroseconds() busy-waits the CPU for the full delay, stalling every lower-priority interrupt and the scheduler for its duration',
                     severity: 'warning',
                 }],
-            ['console.log', {
-                    reason: 'console output lowers to printk(), which is ISR-legal but slow and lock-protected (CONFIG_PRINTK_SYNC) — it adds jitter to every interrupt behind it',
-                    severity: 'info',
-                }],
-            ['console.error', {
-                    reason: 'console output lowers to printk(), which is ISR-legal but slow and lock-protected (CONFIG_PRINTK_SYNC) — it adds jitter to every interrupt behind it',
-                    severity: 'info',
-                }],
-            ['console.warn', {
-                    reason: 'console output lowers to printk(), which is ISR-legal but slow and lock-protected (CONFIG_PRINTK_SYNC) — it adds jitter to every interrupt behind it',
-                    severity: 'info',
-                }],
             ['I2C0', {
                     reason: 'I2C transactions may sleep (driver locking + clock stretching) and are not callable from Zephyr interrupt context',
                     severity: 'warning',
@@ -1076,17 +1649,16 @@ export class ZephyrStrategy {
         return false;
     }
     mathHeader() {
-        // <math.h> is the schema-permitted value (the manifest enum allows none |
-        // <math.h> | <Arduino.h>). Zephyr's toolchain provides it; the C++ <cmath>
-        // names are available via it as well.
-        return '<math.h>';
+        // <cmath>, not <math.h>: the shared lowering emits Math.<fn>() as
+        // std::<fn>() (expression-to-ir), and picolibc's <math.h> declares the
+        // C names in the global namespace only — std::round et al. fail to
+        // compile. Builds run with CONFIG_REQUIRES_FULL_LIBCPP (real libstdc++),
+        // whose <cmath> provides the std:: names.
+        return '<cmath>';
     }
     cstringHeader() {
         return '<cstring>';
     }
-    needsVectorOverload() {
-        return true;
-    }
     needsLargeEnumUnderlying() {
         return false;
     }
@@ -1098,43 +1670,109 @@ export class ZephyrStrategy {
         return undefined;
     }
     // ── Async ───────────────────────────────────────────────────────────────
-    // Hybrid: timers are native (k_timer + k_work, see src/async/timer-polyfill.ts);
-    // Promises use the heap-free static runtime (generateStaticAsyncRuntime), pumped
-    // cooperatively in loop() via cuttlefish_pump_microtasks(). There is no
-    // __tc_timer_runtime.run() poll — native timers fire from their own expiry path.
+    // Promises use the heap-free static runtime (generateStaticAsyncRuntime),
+    // pumped cooperatively via cuttlefish_pump_microtasks(). There is no
+    // __tc_timer_runtime.run() poll — periodic work is a Thread (k_thread) or a
+    // Counter (hardware timer), never a cooperative timer queue.
     getAsyncRuntimeConfig() {
         return {
             queueCapacity: 64,
             scheduler: 'microtask',
             waitForPinEdge: 'stub',
             hasPromiseRuntime: true,
-            hasTimers: true,
+            hasTimers: false,
             // Static (heap-free) runtime — no STL headers required.
             requiredIncludes: [],
         };
     }
+    /**
+     * Board module generation: join the Zephyr board data pack (extracted
+     * from the pinned tree) with the curated soc descriptors. See
+     * src/boardgen.ts.
+     */
+    generateBoardModule(target, opts) {
+        try {
+            const g = generateBoard(target, { factsJson: opts?.factsJson, asBuiltJson: opts?.asBuiltJson });
+            return { boardTs: g.boardTs, boardJson: g.boardJson, ...(g.warnings ? { warnings: g.warnings } : {}) };
+        }
+        catch (err) {
+            // A malformed facts/as-built file is the USER's error — surface it
+            // verbatim instead of the generic "cannot generate" below.
+            if (err instanceof Error && (err.message.includes('cuttlefish.facts.json') || err.message.includes('as-built.json')))
+                throw err;
+            return undefined;
+        }
+    }
+    /**
+     * Regenerate the board catalog overlay from the user's own Zephyr tree —
+     * `cuttlefish board sync`. After a `west update`, this is how new/changed/
+     * removed boards reach projects without a cuttlefish release. See
+     * src/sdk/board-catalog-sync.ts.
+     */
+    syncBoardCatalog(zephyrBase) {
+        return syncBoardCatalog(zephyrBase ? { zephyrBase } : {});
+    }
+    /**
+     * Refresh the overlay only when it is stale (provenance no longer matches
+     * the tree) — the pre-step `cuttlefish board regen` runs so a regen after
+     * `west update` picks up the tree's boards automatically. Tree walk only
+     * happens when there is actual refreshing to do.
+     */
+    ensureFreshBoardCatalog() {
+        return ensureFreshBoardCatalog();
+    }
     asyncLoopInjection(taskVarNames, configOrBool, _hasTimers) {
         const cfg = typeof configOrBool === 'boolean'
             ? { hasPromiseRuntime: configOrBool, hasTimers: _hasTimers ?? false }
             : configOrBool;
-        // Drive every async state-machine task once per loop() iteration. The task
-        // globals auto-start on their first .run() (constructor sets STATE_0, which
-        // runs unconditionally), so this is both the start and the per-frame advance.
-        // The state machine no-ops in its terminal/cyclic state, so unconditional
-        // .run() is correct (mirrors framework-arduino). No isComplete() gating.
-        const lines = [];
+        // Drive every async state-machine task once per scheduler iteration. The
+        // task globals auto-start on their first .run() (constructor sets STATE_0,
+        // which runs unconditionally), so this is both the start and the per-frame
+        // advance. The state machine no-ops in its terminal/cyclic state, so
+        // unconditional .run() is correct (mirrors framework-arduino). No
+        // isComplete() gating.
+        const work = [];
         if (cfg.hasPromiseRuntime) {
-            lines.push('cuttlefish_pump_microtasks();');
+            work.push('cuttlefish_pump_microtasks();');
         }
         for (const n of taskVarNames) {
-            lines.push(`${n}.run();`);
+            work.push(`${n}.run();`);
         }
-        // NOTE: no __tc_timer_runtime.run() — Zephyr timers are native k_timer
-        // (timer-polyfill.ts), not a cooperative poll.
-        return lines;
+        // NOTE: no timer-queue poll — periodic work is a Thread (k_thread) or a
+        // Counter (hardware timer), never a cooperative poll.
+        //
+        // main() runs once, so the per-frame work must close over its own loop.
+        // Under a mounted UI the emitter's hostEventLoop() already wraps ui_tick +
+        // these lines in `while (...) { ...; k_msleep(1); }` — return flat lines
+        // there. Otherwise (async/timer programs with no UI) self-wrap the same
+        // scheduler loop here. For a program whose top-level `while (true)` never
+        // exits, the loop below it is unreachable — harmless, and identical to the
+        // old bridge behavior (whose for(;;) around loop() was equally dead).
+        if (entryHasUI()) {
+            return work;
+        }
+        return ['for (;;) {', ...work.map((l) => `  ${l}`), '  k_msleep(1);', '}'];
     }
     asyncDriverFunctionName() {
-        return 'loop';
+        return 'main';
+    }
+    /**
+     * Zephyr's scheduler loop for event-driven programs (UI mounted). The
+     * emitter wraps the per-frame work — ui_tick plus the asyncLoopInjection
+     * lines — in `while (__tc_zephyr_event_loop) { ...; k_msleep(1); }`: a
+     * 1 ms cooperative yield to the kernel each frame, matching the cadence the
+     * old setup()/loop() bridge gave loop(). The flag is never cleared — the
+     * loop is the program's lifetime — but keeping the bool gives the condition
+     * a used symbol (a bare `while (true)` would leave nothing to name, and an
+     * unused flag would trip -Werror's -Wunused-variable).
+     */
+    hostEventLoop() {
+        return {
+            flagName: '__tc_zephyr_event_loop',
+            continueCondition: '__tc_zephyr_event_loop',
+            preIteration: '',
+            postIteration: 'k_msleep(1);',
+        };
     }
     // ── Type aliases ────────────────────────────────────────────────────────
     shouldSkipTypeAlias() {
@@ -1145,7 +1783,7 @@ export class ZephyrStrategy {
         return [];
     }
     currentTimeMillis() {
-        return 'millis()';
+        return '__tc_now_ms()';
     }
     // ── Build configuration ──────────────────────────────────────────────────
     asyncQueueCapacity() {
@@ -1188,12 +1826,10 @@ export class ZephyrStrategy {
         // cuttlefish_halt: always (the runtime header may reference it).
         // string_methods / static_array: STL-free array + string helpers a no-STL
         //   target needs (mutated/struct array literals + any string method).
-        // timer_methods: k_timer/k_work pool for setInterval/setTimeout (gated on
-        //   timerCallCount at emit time in generateNativePolyfills).
         // async_runtime: heap-free static Promise/microtask runtime (no STL needed).
         return new Set([
             'cuttlefish_halt', 'wiring_compat', 'string_methods', 'static_array',
-            'timer_methods', 'async_runtime',
+            'async_runtime',
         ]);
     }
     generateNativePolyfills(program, ctx) {
@@ -1321,22 +1957,6 @@ struct __tc_StaticArray {
                 dependencies: [],
             },
         ];
-        // Worker-offload runtime (Phase 1). Emitted only when the program uses
-        // worker.* ops, backed by the Zephyr primitives in worker-backing.ts
-        // (k_work system workqueue + k_sem for the completion barrier).
-        const usesWorker = !!(ctx?.analysis?.usesWorker);
-        if (program && usesWorker) {
-            const workerPoly = buildWorkerRuntimePolyfill(program, this, buildZephyrWorkerBacking(), { poolSize: 4 });
-            if (workerPoly)
-                polyfills.push(workerPoly);
-        }
-        // timer_methods — k_timer/k_work pool. Gated on observed timer call count;
-        // a program with no setInterval/setTimeout emits nothing.
-        const analysis = ctx?.analysis;
-        const timerCallCount = analysis?.timerCallCount ?? 0;
-        if (timerCallCount > 0) {
-            polyfills.push(buildTimerPolyfill(timerCallCount));
-        }
         // async_runtime — heap-free static Promise/microtask runtime. Emitted when
         // the program declares an async function OR references an async-runtime
         // symbol (Async.sleep/.then from a non-async fn). The static path requires
@@ -1350,10 +1970,10 @@ struct __tc_StaticArray {
                 domain: 'embedded',
                 requiredIncludes: [],
                 // Polyfill definitions emit before shimLines, but the runtime's
-                // timer bodies call millis() (defined in shimLines) — declare it
-                // first so the polyfill compiles even for programs whose source
+                // timer bodies call __tc_now_ms() (defined in shimLines) — declare
+                // it first so the polyfill compiles even for programs whose source
                 // has no explicit timing call.
-                forwardDeclarations: ['unsigned long millis();'],
+                forwardDeclarations: ['uint32_t __tc_now_ms(void);'],
                 helperStructs: [generateStaticAsyncRuntime(8, this.getAsyncRuntimeConfig().waitForPinEdge)],
                 helperFunctions: [],
                 shimMacros: [],
@@ -1413,19 +2033,10 @@ struct __tc_StaticArray {
     }
     // ── RTOS ─────────────────────────────────────────────────────────────────
     isRtosTarget() {
-        // Zephyr is a preemptive RTOS — delay()/k_msleep inside loop() is the
+        // Zephyr is a preemptive RTOS — delay()/k_msleep inside main() is the
         // expected cooperative yield, not an anti-pattern to warn about.
         return true;
     }
-    workerSpawnLines(handleId, trampolineName, waiterExpr) {
-        return this._workerBacking.spawnLines(handleId, trampolineName, waiterExpr);
-    }
-    workerSignalDoneExpr(handleId) {
-        return this._workerBacking.signalDoneExpr(handleId);
-    }
-    workerIsDoneExpr(handleId) {
-        return this._workerBacking.isDoneExpr(handleId);
-    }
     // ── Graphics ──────────────────────────────────────────────────────────────
     // Generic <zephyr/drivers/display.h> + ported GFX primitives (see src/display/).
     // resolveDisplayOp delegates to resolveZephyrDisplayOp with the per-build
@@ -1493,6 +2104,12 @@ struct __tc_StaticArray {
         if (boardId === 'esp32s3_devkitc' || boardId.startsWith('esp32s3')) {
             return 'gdb';
         }
+        // The STM32 Black Pill ships a verified ST-Link probe method in its board
+        // package (openocd runner over SWD, with the reset_config quirk for the
+        // unwired SRST line), so F5 attaches natively out of the box.
+        if (boardId.startsWith('blackpill_')) {
+            return 'gdb';
+        }
         // The plain ESP32 (esp32_devkitc) intentionally stays on 'printf': unlike
         // the S3 it has NO built-in USB-JTAG, so gdb needs an external ESP-PROG
         // probe + a different OpenOCD cfg/toolchain dir (deferred). Falls through.