@typecad/framework-zephyr 1.0.0-alpha.8

package/dist/lowering/power.js

@@ -0,0 +1,64 @@
+// ---------------------------------------------------------------------------
+// Power lowering — Zephyr power management
+//
+// Zephyr enters low-power states from the idle thread per policy. The app-facing
+// controls are pm_state_force (override policy to force a state on next idle)
+// and k_sleep (block the calling thread, allowing the system to idle into a
+// low-power state). "Deep sleep" maps to k_sleep (the SoC picks its deepest
+// allowed state); "light sleep" best-effort forces SUSPEND_TO_IDLE.
+//
+// deep_sleep_pin configures the wake GPIO as an interrupt source then k_sleeps
+// (the interrupt wakes the SoC). CPU frequency is SoC-specific (nRF52 has a
+// fixed 64 MHz HFXO with no portable dynamic scaling) and stays a documented
+// no-op. deep_sleep_pin targets gpio0 (single-controller nRF52840 case);
+// multi-controller SoC routing is a documented follow-on.
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a HAL power.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export function lowerPower(op) {
+    const o = op;
+    switch (op.operation) {
+        case 'power.deep_sleep':
+            // Block for the requested duration; the idle thread + PM policy will enter
+            // the deepest state the SoC allows during the sleep.
+            return { code: `k_sleep(K_MSEC(${o.ms}));` };
+        case 'power.light_sleep':
+            // Best-effort: force a shallow suspend on the next idle. pm_state_force
+            // requires a pm_state_info; SUSPEND_TO_IDLE is a common shallow state.
+            return { code: `pm_state_force(0, &(const struct pm_state_info){ .state = PM_STATE_SUSPEND_TO_IDLE, .substate_id = 0 });` };
+        case 'power.set_cpu_frequency':
+            // nRF52 has a fixed 64 MHz HFXO; no portable dynamic scaling from C++.
+            // Documented no-op (best-effort), matching Arduino's approach.
+            return { code: `/* power.set_cpu_frequency(${o.mhz}): nRF52 fixed 64 MHz HFXO — no portable scaling */` };
+        case 'power.deep_sleep_pin': {
+            // Configure the pin as a GPIO wake source (level interrupt), then k_sleep
+            // until the interrupt fires. A static gpio_callback + a no-op handler (the
+            // wake just needs the interrupt enabled; the handler does nothing). level:
+            // 1=high, 0=low. Targets gpio0 (single-controller nRF52840); multi-
+            // controller SoC routing is a documented follow-on.
+            const pin = o.pin;
+            const level = o.level;
+            const flags = level ? 'GPIO_INT_LEVEL_HIGH' : 'GPIO_INT_LEVEL_LOW';
+            return {
+                code: [
+                    '{',
+                    `    static struct gpio_callback __tc_wake_cb;`,
+                    `    const struct device* __dev = DEVICE_DT_GET(DT_NODELABEL(gpio0));`,
+                    `    gpio_pin_configure(__dev, ${pin}, GPIO_INPUT);`,
+                    `    gpio_init_callback(&__tc_wake_cb, [](const struct device*, struct gpio_callback*, gpio_port_pins_t) { (void)0; }, BIT(${pin}));`,
+                    `    gpio_add_callback(__dev, &__tc_wake_cb);`,
+                    `    gpio_pin_interrupt_configure(__dev, ${pin}, ${flags});`,
+                    `    k_sleep(K_FOREVER);`,
+                    `    gpio_pin_interrupt_configure(__dev, ${pin}, GPIO_INT_DISABLE);`,
+                    `    gpio_remove_callback(__dev, &__tc_wake_cb);`,
+                    '}',
+                ].join(' '),
+            };
+        }
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/preferences.d.ts

@@ -0,0 +1,23 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+/**
+ * The preferences runtime shim. All helpers are `static`/`inline` so unused
+ * ones don't trip -Wunused-function in the single generated TU (mirrors
+ * wifi.ts / http.ts / mqtt.ts).
+ *
+ * The cache is the source of truth at runtime: settings_load() repopulates it
+ * once at boot via h_set, and every put / get / remove reads or writes it
+ * directly. settings_save_one and settings_delete keep flash in sync on
+ * writes; reads never touch flash. This is the same split the ESP32
+ * Preferences library uses (NVS is the cache, just in flash-backed RAM pages).
+ */
+export declare function preferencesInitLines(): string[];
+/**
+ * Resolve a HAL preferences.* op to Zephyr C++ via the __tc_prefs_* shim.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning
+ * ops (the get_* family). The `default` arm throws the standard unsupported-op
+ * error so the manifest validator's per-op probe stays honest.
+ */
+export declare function lowerPreferences(op: HALOpIR): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/preferences.js

@@ -0,0 +1,345 @@
+// ---------------------------------------------------------------------------
+// Preferences lowering — Zephyr settings subsystem (ZMS backend)
+//
+// The HAL Preferences surface is the ESP32-NVS session model: begin(ns) →
+// typed put_*/get_* → end(). Zephyr's settings subsystem has no session — it
+// is a flat dotted key-space plus a one-time settings_load() at boot that
+// fills an in-RAM cache via the h_set callback. We model the session on top:
+//
+//   begin("app")   → records the active subtree prefix "tc/app/"
+//   putInt("k",v)  → writes the cache + settings_save_one("tc/app/k", bytes, 4)
+//   getInt("k",d)  → cache lookup, returns d if absent
+//   remove("k")    → settings_delete("tc/app/k") + drop cache slot
+//   clear()        → settings_delete each known tc/<ns>/* key + clear cache
+//   end()          → clears the prefix (NOT the cache — end() is not a wipe on
+//                    ESP32 either; it only closes the NVS handle)
+//
+// begin/end are intentionally lightweight on Zephyr. They stay in the IR so a
+// future backend that genuinely needs a session/namespace (NVS, a crypto-
+// sealed store) has the hook without lowering every read through setup. On
+// Zephyr they only carry the key prefix.
+//
+// The settings backend is ZMS (Zephyr Memory Storage), selected by
+// CONFIG_SETTINGS + CONFIG_ZMS + CONFIG_SETTINGS_ZMS. The backend locates the
+// storage partition automatically: the fixed-partition labeled
+// `storage_partition`, or whatever /chosen `zephyr,settings-partition` points
+// at (see dt-config/overlay.ts). No partition macro is referenced here.
+//
+// EMIT BOUNDARY: emitted bytes land in user firmware. Covered by the TypeCAD
+// Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
+// ---------------------------------------------------------------------------
+/** Render a HAL field: pass through (already rendered by the resolver). */
+function s(v) {
+    return String(v);
+}
+// Type tags for the cache slot payload. Scoped enum (AUTOSAR: enum class).
+// The on-metal order matters: these are stored in the `type` byte and matched
+// at h_set time, so do not renumber.
+const TAG = {
+    INT: 1,
+    UINT: 2,
+    BOOL: 3,
+    FLOAT: 4,
+    STRING: 5,
+};
+/**
+ * The preferences runtime shim. All helpers are `static`/`inline` so unused
+ * ones don't trip -Wunused-function in the single generated TU (mirrors
+ * wifi.ts / http.ts / mqtt.ts).
+ *
+ * The cache is the source of truth at runtime: settings_load() repopulates it
+ * once at boot via h_set, and every put / get / remove reads or writes it
+ * directly. settings_save_one and settings_delete keep flash in sync on
+ * writes; reads never touch flash. This is the same split the ESP32
+ * Preferences library uses (NVS is the cache, just in flash-backed RAM pages).
+ */
+export function preferencesInitLines() {
+    return [
+        `// CUTTLEFISH_PREFS_BEGIN`,
+        `#define __TC_PREFS_SLOT_COUNT 32`,
+        `#define __TC_PREFS_KEY_LEN   48`,
+        `#define __TC_PREFS_VAL_LEN   32`,
+        `#define __TC_PREFS_STR_LEN   31`,
+        ``,
+        `// One cache slot. The full settings key (tc/<ns>/<key>) lives in key[] so`,
+        `// remove()/clear() can reconstruct the exact name to settings_delete. The`,
+        `// value is stored in its native wire form (little-endian for the numeric`,
+        `// types) so h_set can memcpy straight from the settings read callback.`,
+        `struct __tc_prefs_slot final {`,
+        `    char key[__TC_PREFS_KEY_LEN];`,
+        `    uint8_t type;`,
+        `    uint8_t val[__TC_PREFS_VAL_LEN];`,
+        `    uint8_t len;`,
+        `    bool used;`,
+        `};`,
+        ``,
+        `// Active namespace prefix ("tc/<ns>/"). begin() overwrites it; end() clears.`,
+        `// prefs_ns is deliberately sized to hold "tc/" + a 16-char ns + "/" + NUL.`,
+        `static struct {`,
+        `    char ns[24];`,
+        `    bool loaded;`,
+        `    __tc_prefs_slot slots[__TC_PREFS_SLOT_COUNT];`,
+        `} __tc_prefs;`,
+        ``,
+        `// ── settings_load() handler (the only mandatory callback) ───────────────`,
+        `// settings_load() calls h_set once per stored key it finds, handing us the`,
+        `// value via read_cb. We copy it into a cache slot keyed by the full dotted`,
+        `// path. h_get/h_commit are unused (the cache is the post-load source of`,
+        `// truth) so they return -ENOENT / 0 to satisfy the handler contract.`,
+        `static int __tc_prefs_h_set(const char* name, size_t len, settings_read_cb read_cb, void* cb_arg) {`,
+        `    (void)len;`,
+        `    for (int i = 0; i < __TC_PREFS_SLOT_COUNT; i++) {`,
+        `        if (!__tc_prefs.slots[i].used) {`,
+        `            // Stash the type byte (first val byte) by reading into the slot.`,
+        `            ssize_t got = read_cb(cb_arg, __tc_prefs.slots[i].val, __TC_PREFS_VAL_LEN);`,
+        `            if (got <= 0) { return static_cast<int>(got); }`,
+        `            __tc_prefs.slots[i].len = static_cast<uint8_t>(got);`,
+        `            // Type is encoded as the first byte of the stored value (see put_*).`,
+        `            __tc_prefs.slots[i].type = __tc_prefs.slots[i].val[0];`,
+        `            (void)snprintf(__tc_prefs.slots[i].key, __TC_PREFS_KEY_LEN, "%s", name);`,
+        `            __tc_prefs.slots[i].used = true;`,
+        `            return 0;`,
+        `        }`,
+        `    }`,
+        `    return 0;  // cache full — silently drop (matches ESP32 NVS-full behavior)`,
+        `}`,
+        `static int __tc_prefs_h_get(const char* key, char* val, int val_len_max) {`,
+        `    (void)key; (void)val; (void)val_len_max;`,
+        `    return -ENOENT;`,
+        `}`,
+        `static int __tc_prefs_h_commit(void) { return 0; }`,
+        `SETTINGS_STATIC_HANDLER_DEFINE(tc_prefs, "tc", __tc_prefs_h_get, __tc_prefs_h_set,`,
+        `                                __tc_prefs_h_commit, NULL);`,
+        ``,
+        `// One-time subsystem init + load. Idempotent — the HAL may call begin()`,
+        `// repeatedly. settings_subsys_init() is itself idempotent in Zephyr, but the`,
+        `// loaded flag short-circuits the (relatively expensive) settings_load() walk.`,
+        `static inline void __tc_prefs_ensure_loaded(void) {`,
+        `    if (!__tc_prefs.loaded) {`,
+        `        (void)settings_subsys_init();`,
+        `        (void)settings_load();`,
+        `        __tc_prefs.loaded = true;`,
+        `    }`,
+        `}`,
+        ``,
+        `// Build the full settings name "tc/<ns>/<key>" into out. ns is the active`,
+        `// prefix set by begin(); the slot's key[] stores this full path so remove()`,
+        `// and clear() can settings_delete the exact stored name.`,
+        `static void __tc_prefs_full(char* out, size_t outsz, const char* key) {`,
+        `    (void)snprintf(out, outsz, "%s%s", __tc_prefs.ns, key);`,
+        `}`,
+        ``,
+        `// Slot lookup by full settings name. Returns nullptr when absent (the get_*`,
+        `// helpers then fall back to the caller's default value, matching the ESP32`,
+        `// getInt(key, default) contract).`,
+        `static __tc_prefs_slot* __tc_prefs_find(const char* full) {`,
+        `    for (int i = 0; i < __TC_PREFS_SLOT_COUNT; i++) {`,
+        `        if (__tc_prefs.slots[i].used &&`,
+        `            strncmp(__tc_prefs.slots[i].key, full, __TC_PREFS_KEY_LEN) == 0) {`,
+        `            return &__tc_prefs.slots[i];`,
+        `        }`,
+        `    }`,
+        `    return nullptr;`,
+        `}`,
+        ``,
+        `// Allocate (or reuse) a slot for a full name. Eviction is last-write on a`,
+        `// free slot; a full cache returns nullptr and the put silently no-ops (the`,
+        `// in-RAM value is still returned to the program on get, just not persisted).`,
+        `static __tc_prefs_slot* __tc_prefs_slot_for(const char* full) {`,
+        `    __tc_prefs_slot* existing = __tc_prefs_find(full);`,
+        `    if (existing != nullptr) { return existing; }`,
+        `    for (int i = 0; i < __TC_PREFS_SLOT_COUNT; i++) {`,
+        `        if (!__tc_prefs.slots[i].used) { return &__tc_prefs.slots[i]; }`,
+        `    }`,
+        `    return nullptr;`,
+        `}`,
+        ``,
+        `// Generic typed put: stamp the type byte, stash the value, persist via`,
+        `// settings_save_one, and mirror into the cache. The type byte rides along`,
+        `// as val[0] so h_set can recover it on the next boot without a separate`,
+        `// name→type map.`,
+        `template <typename T>`,
+        `static inline void __tc_prefs_put(const char* key, uint8_t tag, const T& value) {`,
+        `    char full[__TC_PREFS_KEY_LEN];`,
+        `    __tc_prefs_full(full, sizeof(full), key);`,
+        `    uint8_t buf[1U + sizeof(T)];`,
+        `    buf[0] = tag;`,
+        `    (void)memcpy(&buf[1], &value, sizeof(T));`,
+        `    (void)settings_save_one(full, buf, sizeof(buf));`,
+        `    __tc_prefs_slot* slot = __tc_prefs_slot_for(full);`,
+        `    if (slot != nullptr) {`,
+        `        (void)snprintf(slot->key, __TC_PREFS_KEY_LEN, "%s", full);`,
+        `        slot->type = tag;`,
+        `        slot->len = static_cast<uint8_t>(sizeof(buf));`,
+        `        (void)memcpy(slot->val, buf, sizeof(buf));`,
+        `        slot->used = true;`,
+        `    }`,
+        `}`,
+        ``,
+        `template <typename T>`,
+        `static inline T __tc_prefs_get(const char* key, uint8_t tag, T def) {`,
+        `    char full[__TC_PREFS_KEY_LEN];`,
+        `    __tc_prefs_full(full, sizeof(full), key);`,
+        `    __tc_prefs_slot* slot = __tc_prefs_find(full);`,
+        `    if (slot == nullptr || slot->type != tag || slot->len < (1U + sizeof(T))) {`,
+        `        return def;`,
+        `    }`,
+        `    T out;`,
+        `    (void)memcpy(&out, &slot->val[1], sizeof(T));`,
+        `    return out;`,
+        `}`,
+        ``,
+        `// ── Lifecycle (session model on top of the flat key-space) ──────────────`,
+        `// begin records "tc/<ns>/" as the prefix every subsequent key is built under.`,
+        `// end clears the prefix (NOT the cache). Both are cheap on Zephyr: the real`,
+        `// work is in settings_load() at boot. They exist for portability with the`,
+        `// ESP32 NVS session model and so a future session-needing backend has a hook.`,
+        `static inline void __tc_prefs_begin(const char* ns, bool readOnly) {`,
+        `    (void)readOnly;`,
+        `    __tc_prefs_ensure_loaded();`,
+        `    (void)snprintf(__tc_prefs.ns, sizeof(__tc_prefs.ns), "tc/%s/", ns);`,
+        `}`,
+        `static inline void __tc_prefs_end(void) {`,
+        `    __tc_prefs.ns[0] = '\\0';`,
+        `}`,
+        ``,
+        `// remove: drop one key from flash and the cache. Falls back to no-op if the`,
+        `// slot isn't cached (settings_delete on a missing key returns -ENOENT, which`,
+        `// we swallow).`,
+        `static inline void __tc_prefs_remove(const char* key) {`,
+        `    char full[__TC_PREFS_KEY_LEN];`,
+        `    __tc_prefs_full(full, sizeof(full), key);`,
+        `    (void)settings_delete(full);`,
+        `    __tc_prefs_slot* slot = __tc_prefs_find(full);`,
+        `    if (slot != nullptr) { slot->used = false; }`,
+        `}`,
+        ``,
+        `// clear: drop every key under the active namespace. We walk the cache (the`,
+        `// authoritative list of keys we have written) and settings_delete each whose`,
+        `// full name starts with the active ns prefix, then mark the slot free. Only`,
+        `// the active namespace is cleared — keys under other namespaces survive.`,
+        `static inline void __tc_prefs_clear(void) {`,
+        `    const size_t plen = strlen(__tc_prefs.ns);`,
+        `    for (int i = 0; i < __TC_PREFS_SLOT_COUNT; i++) {`,
+        `        if (__tc_prefs.slots[i].used &&`,
+        `            strncmp(__tc_prefs.slots[i].key, __tc_prefs.ns, plen) == 0) {`,
+        `            (void)settings_delete(__tc_prefs.slots[i].key);`,
+        `            __tc_prefs.slots[i].used = false;`,
+        `        }`,
+        `    }`,
+        `}`,
+        ``,
+        `// ── Typed accessors ─────────────────────────────────────────────────────`,
+        `// Each put_* stamps its tag byte and persists; each get_* reads the cache and`,
+        `// returns the default on miss/type-mismatch (mirrors ESP32 Preferences).`,
+        `static inline void __tc_prefs_put_int(const char* key, int32_t v) {`,
+        `    __tc_prefs_put<int32_t>(key, ${TAG.INT}, v);`,
+        `}`,
+        `static inline int32_t __tc_prefs_get_int(const char* key, int32_t def) {`,
+        `    return __tc_prefs_get<int32_t>(key, ${TAG.INT}, def);`,
+        `}`,
+        `static inline void __tc_prefs_put_uint(const char* key, uint32_t v) {`,
+        `    __tc_prefs_put<uint32_t>(key, ${TAG.UINT}, v);`,
+        `}`,
+        `static inline uint32_t __tc_prefs_get_uint(const char* key, uint32_t def) {`,
+        `    return __tc_prefs_get<uint32_t>(key, ${TAG.UINT}, def);`,
+        `}`,
+        `static inline void __tc_prefs_put_bool(const char* key, bool v) {`,
+        `    uint8_t b = v ? 1U : 0U;`,
+        `    __tc_prefs_put<uint8_t>(key, ${TAG.BOOL}, b);`,
+        `}`,
+        `static inline bool __tc_prefs_get_bool(const char* key, bool def) {`,
+        `    uint8_t b = __tc_prefs_get<uint8_t>(key, ${TAG.BOOL}, def ? 1U : 0U);`,
+        `    return b != 0U;`,
+        `}`,
+        `static inline void __tc_prefs_put_float(const char* key, float v) {`,
+        `    __tc_prefs_put<float>(key, ${TAG.FLOAT}, v);`,
+        `}`,
+        `static inline float __tc_prefs_get_float(const char* key, float def) {`,
+        `    return __tc_prefs_get<float>(key, ${TAG.FLOAT}, def);`,
+        `}`,
+        ``,
+        `// Strings are length-prefixed into the value buffer (capped at STR_LEN so the`,
+        `// whole slot still fits in __TC_PREFS_VAL_LEN). get copies out with a NUL and`,
+        `// returns def when the slot is absent or the wrong type.`,
+        `static inline void __tc_prefs_put_string(const char* key, const char* v) {`,
+        `    char full[__TC_PREFS_KEY_LEN];`,
+        `    __tc_prefs_full(full, sizeof(full), key);`,
+        `    uint8_t buf[1U + __TC_PREFS_STR_LEN];`,
+        `    buf[0] = ${TAG.STRING};`,
+        `    size_t n = strlen(v);`,
+        `    if (n > __TC_PREFS_STR_LEN) { n = __TC_PREFS_STR_LEN; }`,
+        `    (void)memcpy(&buf[1], v, n);`,
+        `    (void)settings_save_one(full, buf, 1U + n);`,
+        `    __tc_prefs_slot* slot = __tc_prefs_slot_for(full);`,
+        `    if (slot != nullptr) {`,
+        `        (void)snprintf(slot->key, __TC_PREFS_KEY_LEN, "%s", full);`,
+        `        slot->type = ${TAG.STRING};`,
+        `        slot->len = static_cast<uint8_t>(1U + static_cast<uint8_t>(n));`,
+        `        (void)memcpy(slot->val, buf, 1U + n);`,
+        `        slot->used = true;`,
+        `    }`,
+        `}`,
+        `static inline const char* __tc_prefs_get_string(const char* key, const char* def) {`,
+        `    static char out[__TC_PREFS_STR_LEN + 1U];`,
+        `    char full[__TC_PREFS_KEY_LEN];`,
+        `    __tc_prefs_full(full, sizeof(full), key);`,
+        `    __tc_prefs_slot* slot = __tc_prefs_find(full);`,
+        `    if (slot == nullptr || slot->type != ${TAG.STRING} || slot->len < 1U) {`,
+        `        return def;`,
+        `    }`,
+        `    size_t n = slot->len - 1U;`,
+        `    if (n > __TC_PREFS_STR_LEN) { n = __TC_PREFS_STR_LEN; }`,
+        `    (void)memcpy(out, &slot->val[1], n);`,
+        `    out[n] = '\\0';`,
+        `    return out;`,
+        `}`,
+        `// CUTTLEFISH_PREFS_END`,
+        ``,
+    ];
+}
+/**
+ * Resolve a HAL preferences.* op to Zephyr C++ via the __tc_prefs_* shim.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning
+ * ops (the get_* family). The `default` arm throws the standard unsupported-op
+ * error so the manifest validator's per-op probe stays honest.
+ */
+export function lowerPreferences(op) {
+    const o = op;
+    switch (op.operation) {
+        case 'preferences.begin':
+            // readOnly is honored as a no-op: Zephyr settings has no read-only mount,
+            // and silently ignoring it matches the ESP32 Preferences behavior when
+            // an RO handle is written (the put returns an error the app doesn't see).
+            return { code: `__tc_prefs_begin(${s(o.namespace)}, ${o.readOnly ? 'true' : 'false'});` };
+        case 'preferences.end':
+            return { code: `__tc_prefs_end();` };
+        case 'preferences.clear':
+            return { code: `__tc_prefs_clear();` };
+        case 'preferences.remove':
+            return { code: `__tc_prefs_remove(${s(o.key)});` };
+        case 'preferences.put_int':
+            return { code: `__tc_prefs_put_int(${s(o.key)}, ${s(o.value)});` };
+        case 'preferences.get_int':
+            return { expression: `__tc_prefs_get_int(${s(o.key)}, ${s(o.defaultValue)})` };
+        case 'preferences.put_uint':
+            return { code: `__tc_prefs_put_uint(${s(o.key)}, ${s(o.value)});` };
+        case 'preferences.get_uint':
+            return { expression: `__tc_prefs_get_uint(${s(o.key)}, ${s(o.defaultValue)})` };
+        case 'preferences.put_bool':
+            return { code: `__tc_prefs_put_bool(${s(o.key)}, ${o.value ? 'true' : 'false'});` };
+        case 'preferences.get_bool':
+            return { expression: `__tc_prefs_get_bool(${s(o.key)}, ${o.defaultValue ? 'true' : 'false'})` };
+        case 'preferences.put_float':
+            return { code: `__tc_prefs_put_float(${s(o.key)}, ${s(o.value)});` };
+        case 'preferences.get_float':
+            return { expression: `__tc_prefs_get_float(${s(o.key)}, ${s(o.defaultValue)})` };
+        case 'preferences.put_string':
+            return { code: `__tc_prefs_put_string(${s(o.key)}, ${s(o.value)});` };
+        case 'preferences.get_string':
+            return { expression: `__tc_prefs_get_string(${s(o.key)}, ${s(o.defaultValue)})` };
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/pulse.d.ts

@@ -0,0 +1,7 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/** Resolve a HAL pulse.* or shift.* op to Zephyr C++ (bit-bang). */
+export declare function lowerPulseOrShift(op: HALOpIR, chip: ZephyrChipDescriptor): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/pulse.js

@@ -0,0 +1,82 @@
+// ---------------------------------------------------------------------------
+// Pulse + shift lowering — bit-bang via GPIO + timing
+//
+// pulse.in measures the duration of a pulse (HIGH or LOW) on a GPIO pin by
+// edge-polling with k_uptime_get. shift.out/in bit-bang a byte through a data
+// + clock pin pair using gpio_pin_set + k_busy_wait. These are software
+// implementations (no hardware pulse capture on nRF for the HAL surface); they
+// are correct but not high-precision.
+// ---------------------------------------------------------------------------
+import { controllerNodelabelForPin } from '../chips/controllers.js';
+/** `DEVICE_DT_GET(DT_NODELABEL(<owning-controller>))` for a HAL pin. */
+function devForPin(chip, pin) {
+    return `DEVICE_DT_GET(DT_NODELABEL(${controllerNodelabelForPin(chip, pin)}))`;
+}
+/** Resolve a HAL pulse.* or shift.* op to Zephyr C++ (bit-bang). */
+export function lowerPulseOrShift(op, chip) {
+    const o = op;
+    switch (op.operation) {
+        case 'pulse.in': {
+            // Wait for the pin to reach `value`, then measure until it changes.
+            // Edge-poll with k_uptime_get() (ms granularity — coarse but correct,
+            // and 64-bit so it cannot wrap mid-measurement over ~49 days). The wait
+            // for the start edge is bounded by the timeout; the measurement of the
+            // pulse itself is intentionally unbounded (that IS the pulse length).
+            // Returns -1 (0) if the start edge never arrives within the timeout.
+            const pin = o.pin;
+            const want = o.value;
+            const dev = devForPin(chip, pin);
+            const timeout = o.timeout ?? 1_000_000; // default 1s in us
+            return {
+                expression: `({ int64_t __max = static_cast<int64_t>(${timeout} / 1000); int64_t __t0 = k_uptime_get(); bool __ok = true; while (gpio_pin_get_raw(${dev}, ${pin}) != ${want}) { if ((k_uptime_get() - __t0) > __max) { __ok = false; break; } } int32_t __ret = 0; if (__ok) { int64_t __start = k_uptime_get(); while (gpio_pin_get_raw(${dev}, ${pin}) == ${want}) { } __ret = static_cast<int32_t>((k_uptime_get() - __start) * 1000); } __ret; })`,
+            };
+        }
+        case 'pulse.in_long': {
+            // Same as pulse.in but for long pulses. Previously this spun forever
+            // with NO timeout (the comment claimed "no overflow concern" but the
+            // real risk was hanging the thread on a stuck pin). Apply the same
+            // timeout-bounded start-edge wait as pulse.in (bug Q5).
+            const pin = o.pin;
+            const want = o.value;
+            const dev = devForPin(chip, pin);
+            const timeout = o.timeout ?? 3_000_000; // default 3s in us (long pulses)
+            return {
+                expression: `({ int64_t __max = static_cast<int64_t>(${timeout} / 1000); int64_t __t0 = k_uptime_get(); bool __ok = true; while (gpio_pin_get_raw(${dev}, ${pin}) != ${want}) { if ((k_uptime_get() - __t0) > __max) { __ok = false; break; } } int32_t __ret = 0; if (__ok) { int64_t __start = k_uptime_get(); while (gpio_pin_get_raw(${dev}, ${pin}) == ${want}) { } __ret = static_cast<int32_t>((k_uptime_get() - __start) * 1000); } __ret; })`,
+            };
+        }
+        case 'shift.out': {
+            // Bit-bang `value` (MSB or LSB first) via dataPin + clockPin. The two
+            // pins may sit on different GPIO controllers on multi-controller SoCs
+            // (ESP32-S3), so each is resolved to its own owning controller.
+            const dataPin = o.dataPin;
+            const clockPin = o.clockPin;
+            const dataDev = devForPin(chip, dataPin);
+            const clockDev = devForPin(chip, clockPin);
+            const msbFirst = o.bitOrder === 'msb';
+            const init = msbFirst ? '7' : '0';
+            const test = msbFirst ? '(__i >= 0)' : '(__i < 8)';
+            const step = msbFirst ? '__i--' : '__i++';
+            return {
+                code: `for (int __i = ${init}; ${test}; ${step}) { gpio_pin_set_raw(${dataDev}, ${dataPin}, (${o.value} >> __i) & 1); gpio_pin_set_raw(${clockDev}, ${clockPin}, 1); k_busy_wait(1); gpio_pin_set_raw(${clockDev}, ${clockPin}, 0); }`,
+            };
+        }
+        case 'shift.in': {
+            // Read 8 bits (MSB or LSB first) from dataPin, clocking on clockPin.
+            const dataPin = o.dataPin;
+            const clockPin = o.clockPin;
+            const dataDev = devForPin(chip, dataPin);
+            const clockDev = devForPin(chip, clockPin);
+            const msbFirst = o.bitOrder === 'msb';
+            const init = msbFirst ? '7' : '0';
+            const test = msbFirst ? '(__i >= 0)' : '(__i < 8)';
+            const step = msbFirst ? '__i--' : '__i++';
+            const accum = msbFirst ? '__v = (__v << 1)' : '__v |= (bit << __i)';
+            return {
+                expression: `({ uint8_t __v = 0; for (int __i = ${init}; ${test}; ${step}) { gpio_pin_set_raw(${clockDev}, ${clockPin}, 1); k_busy_wait(1); int bit = gpio_pin_get_raw(${dataDev}, ${dataPin}); gpio_pin_set_raw(${clockDev}, ${clockPin}, 0); ${accum}; } __v; })`,
+            };
+        }
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/pwm.d.ts

@@ -0,0 +1,15 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Emit the per-channel PWM spec declarations. One per spec in the chip
+ * descriptor. Called from shimLines when the program uses PWM.
+ */
+export declare function pwmInitLines(chip: ZephyrChipDescriptor): string[];
+/**
+ * Resolve a HAL pwm.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export declare function lowerPwm(op: HALOpIR, chip: ZephyrChipDescriptor): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/pwm.js

@@ -0,0 +1,59 @@
+// ---------------------------------------------------------------------------
+// PWM lowering — pwm_dt_spec via pwm-led0 alias
+//
+// The XIAO nRF52840 exposes PWM via the `pwm-led0` devicetree alias (PWM_OUT0
+// on P0.17, inverted). The lowering emits a `pwm_dt_spec` per channel and uses
+// `pwm_set_pulse_dt` / `pwm_set_dt`. Duty is scaled from the Arduino-style
+// 0–255 (or 0–1023) range to nanoseconds against the spec's period.
+// ---------------------------------------------------------------------------
+/** Look up a PWM spec by HAL pin number. */
+function findPwmSpec(chip, pin) {
+    return chip.pwm?.specs.find((s) => s.pin === pin);
+}
+/** The C variable name emitted for a PWM channel's spec. */
+function pwmVarName(spec) {
+    return `__tc_pwm_${spec.dtSpec.replace(/-/g, '_')}`;
+}
+/**
+ * Emit the per-channel PWM spec declarations. One per spec in the chip
+ * descriptor. Called from shimLines when the program uses PWM.
+ */
+export function pwmInitLines(chip) {
+    const lines = ['// CUTTLEFISH_PWM_BEGIN'];
+    for (const spec of chip.pwm?.specs ?? []) {
+        lines.push(`static const struct pwm_dt_spec ${pwmVarName(spec)} = PWM_DT_SPEC_GET(DT_ALIAS(${spec.dtSpec}));`);
+    }
+    lines.push('// CUTTLEFISH_PWM_END');
+    return lines;
+}
+/**
+ * Resolve a HAL pwm.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export function lowerPwm(op, chip) {
+    const o = op;
+    const spec = findPwmSpec(chip, o.pin);
+    if (!spec) {
+        // Probe / unlisted pin: return a comment so the resolver reports non-
+        // undefined (the manifest validator's probe sends pin:0 with no spec).
+        // A real program pins the descriptor's pwm.specs entry.
+        return { code: `/* pwm on pin ${o.pin}: no PWM spec in chip descriptor */` };
+    }
+    const v = pwmVarName(spec);
+    switch (op.operation) {
+        case 'pwm.write': {
+            // Duty is 0–255 (Arduino analogWrite). Scale to ns against the period.
+            return { code: `pwm_set_pulse_dt(&${v}, (static_cast<uint32_t>(${o.duty}) * ${v}.period) / 255);` };
+        }
+        case 'pwm.get_frequency': {
+            // period is in ns; frequency = 1e9 / period (Hz).
+            return { expression: `(${v}.period ? (1000000000ULL / ${v}.period) : 0)` };
+        }
+        case 'pwm.get_resolution':
+            // Arduino-compatible 8-bit duty range.
+            return { expression: '8' };
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/random.d.ts

@@ -0,0 +1,18 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+/**
+ * The random runtime shim. The xorshift32 state is a 32-bit word seeded from
+ * sys_rand_get on first use; random.seed overwrites it. Helpers are
+ * `static`/`inline` so the single generated TU does not trip -Wunused-function
+ * when only a subset of the ops is used (mirrors preferences.ts / wifi.ts).
+ */
+export declare function randomInitLines(): string[];
+/**
+ * Resolve a HAL random.* op to Zephyr C++ via the __tc_rand_* shim.
+ * Returns `{ code }` for the statement op (seed), `{ expression }` for the
+ * value-returning ops (int / range). The `default` arm throws the standard
+ * unsupported-op error so the manifest validator's per-op probe stays honest.
+ */
+export declare function lowerRandom(op: HALOpIR): {
+    code?: string;
+    expression?: string;
+};