@mikrojs/firmware 0.0.7

package/components/mikrojs/mik_rtc.cpp

@@ -0,0 +1,305 @@
+#include <cstring>
+
+#include <nanocbor/nanocbor.h>
+
+#include "esp_attr.h"
+#include "esp_rom_crc.h"
+#include "mikrojs/cbor_helpers.h"
+#include "mikrojs/errors.h"
+#include "mikrojs/private.h"
+#include "mikrojs/utils.h"
+
+#define MIK_RTC_TAG "native:rtc"
+#define MIK_RTC_STORE_SIZE 2048
+#define MIK_RTC_MAGIC 0x4D524A53 /* "MRJS" */
+#define MIK_RTC_MAX_KEY_LEN 255
+#define MIK_RTC_MAX_VAL_LEN 65535
+
+/* ── RTC store layout ────────────────────────────────────────────── */
+/* [4B magic] [4B crc32] [2B entry_count] [2B data_len]              */
+/* [entries: key_len(1) + key + val_len(2) + value ...]              */
+
+struct __attribute__((packed)) RtcHeader {
+    uint32_t magic;
+    uint32_t crc;
+    uint16_t entry_count;
+    uint16_t data_len;
+};
+
+static_assert(sizeof(RtcHeader) == 12, "RtcHeader must be 12 bytes");
+
+#define MIK_RTC_DATA_OFFSET sizeof(RtcHeader)
+#define MIK_RTC_DATA_CAPACITY (MIK_RTC_STORE_SIZE - MIK_RTC_DATA_OFFSET)
+
+RTC_NOINIT_ATTR static uint8_t s_rtc_store[MIK_RTC_STORE_SIZE];
+
+/* ── CRC / validation helpers ────────────────────────────────────── */
+
+static uint32_t mik__rtc_compute_crc() {
+    auto* hdr = reinterpret_cast<RtcHeader*>(s_rtc_store);
+    return esp_rom_crc32_le(0, s_rtc_store + MIK_RTC_DATA_OFFSET, hdr->data_len);
+}
+
+static bool mik__rtc_is_valid() {
+    auto* hdr = reinterpret_cast<RtcHeader*>(s_rtc_store);
+    if (hdr->magic != MIK_RTC_MAGIC) return false;
+    if (hdr->data_len > MIK_RTC_DATA_CAPACITY) return false;
+    return hdr->crc == mik__rtc_compute_crc();
+}
+
+static void mik__rtc_clear() {
+    memset(s_rtc_store, 0, MIK_RTC_STORE_SIZE);
+    auto* hdr = reinterpret_cast<RtcHeader*>(s_rtc_store);
+    hdr->magic = MIK_RTC_MAGIC;
+    hdr->crc = mik__rtc_compute_crc();
+}
+
+static void mik__rtc_ensure_valid() {
+    if (!mik__rtc_is_valid()) {
+        mik__rtc_clear();
+    }
+}
+
+static void mik__rtc_update_crc() {
+    auto* hdr = reinterpret_cast<RtcHeader*>(s_rtc_store);
+    hdr->crc = mik__rtc_compute_crc();
+}
+
+/* ── Entry iteration helpers ─────────────────────────────────────── */
+
+static uint8_t* mik__rtc_data() {
+    return s_rtc_store + MIK_RTC_DATA_OFFSET;
+}
+
+/* Returns pointer to entry start, sets out_key_len, out_key, out_val_len, out_val.
+ * Returns NULL if no more entries. */
+static uint8_t* mik__rtc_next_entry(uint8_t* pos, uint8_t* end, uint8_t* out_key_len,
+                                     const char** out_key, uint16_t* out_val_len,
+                                     const char** out_val) {
+    if (pos >= end) return nullptr;
+    if (pos + 1 > end) return nullptr;
+
+    *out_key_len = pos[0];
+    if (pos + 1 + *out_key_len + 2 > end) return nullptr;
+
+    *out_key = reinterpret_cast<const char*>(pos + 1);
+
+    uint8_t* vl = pos + 1 + *out_key_len;
+    *out_val_len = static_cast<uint16_t>(vl[0]) | (static_cast<uint16_t>(vl[1]) << 8);
+
+    if (vl + 2 + *out_val_len > end) return nullptr;
+
+    *out_val = reinterpret_cast<const char*>(vl + 2);
+    return vl + 2 + *out_val_len;
+}
+
+/* Find an entry by key. Returns pointer to its start, or NULL. */
+static uint8_t* mik__rtc_find(const char* key, uint8_t key_len, uint8_t** out_next) {
+    auto* hdr = reinterpret_cast<RtcHeader*>(s_rtc_store);
+    uint8_t* data = mik__rtc_data();
+    uint8_t* end = data + hdr->data_len;
+    uint8_t* pos = data;
+
+    while (pos < end) {
+        uint8_t ek_len;
+        const char* ek;
+        uint16_t ev_len;
+        const char* ev;
+        uint8_t* entry_start = pos;
+        uint8_t* next = mik__rtc_next_entry(pos, end, &ek_len, &ek, &ev_len, &ev);
+        if (!next) break;
+
+        if (ek_len == key_len && memcmp(ek, key, key_len) == 0) {
+            if (out_next) *out_next = next;
+            return entry_start;
+        }
+        pos = next;
+    }
+
+    if (out_next) *out_next = nullptr;
+    return nullptr;
+}
+
+static size_t mik__rtc_entry_size(uint8_t key_len, uint16_t val_len) {
+    return 1 + key_len + 2 + val_len;
+}
+
+/* ── JS functions ────────────────────────────────────────────────── */
+
+static JSValue mik__rtc_set(JSContext* ctx, JSValue this_val, int argc, JSValue* argv) {
+    mik__rtc_ensure_valid();
+
+    const char* key = JS_ToCString(ctx, argv[0]);
+    if (!key) return JS_EXCEPTION;
+    size_t key_len = strlen(key);
+
+    if (key_len == 0 || key_len > MIK_RTC_MAX_KEY_LEN) {
+        JS_FreeCString(ctx, key);
+        return mik__result_err(ctx, MIK_ERR_KV_INVALID_KEY, 0,
+                               "RTC key length must be 1-%d bytes", MIK_RTC_MAX_KEY_LEN);
+    }
+
+    /* CBOR-encode the value (two-pass: measure then encode) */
+    nanocbor_encoder_t enc;
+    nanocbor_encoder_init(&enc, nullptr, 0);
+    if (mik__cbor_encode_value(ctx, &enc, argv[1], 0) < 0) {
+        JS_FreeCString(ctx, key);
+        return mik__result_err(ctx, MIK_ERR_KV_ENCODE, 0, "RTC value is not CBOR-encodable");
+    }
+    size_t val_len = nanocbor_encoded_len(&enc);
+
+    if (val_len > MIK_RTC_MAX_VAL_LEN) {
+        JS_FreeCString(ctx, key);
+        return mik__result_err(ctx, MIK_ERR_KV_TOO_LARGE, 0,
+                               "RTC value length exceeds %d bytes", MIK_RTC_MAX_VAL_LEN);
+    }
+
+    auto* hdr = reinterpret_cast<RtcHeader*>(s_rtc_store);
+    uint8_t* data = mik__rtc_data();
+
+    /* Remove existing entry if present */
+    uint8_t* next = nullptr;
+    uint8_t* found = mik__rtc_find(key, static_cast<uint8_t>(key_len), &next);
+    if (found && next) {
+        uint8_t* end = data + hdr->data_len;
+        size_t tail = end - next;
+        memmove(found, next, tail);
+        hdr->data_len -= static_cast<uint16_t>(next - found);
+        hdr->entry_count--;
+    }
+
+    /* Check space */
+    size_t needed = mik__rtc_entry_size(static_cast<uint8_t>(key_len), static_cast<uint16_t>(val_len));
+    if (hdr->data_len + needed > MIK_RTC_DATA_CAPACITY) {
+        JS_FreeCString(ctx, key);
+        return mik__result_err(ctx, MIK_ERR_KV_STORAGE_FULL, 0,
+                               "RTC memory full (need %zu bytes, %zu available)", needed,
+                               MIK_RTC_DATA_CAPACITY - hdr->data_len);
+    }
+
+    /* Append new entry: encode CBOR directly into the RTC store */
+    uint8_t* write_pos = data + hdr->data_len;
+    write_pos[0] = static_cast<uint8_t>(key_len);
+    memcpy(write_pos + 1, key, key_len);
+    write_pos[1 + key_len] = static_cast<uint8_t>(val_len & 0xFF);
+    write_pos[1 + key_len + 1] = static_cast<uint8_t>((val_len >> 8) & 0xFF);
+
+    nanocbor_encoder_init(&enc, write_pos + 1 + key_len + 2, val_len);
+    mik__cbor_encode_value(ctx, &enc, argv[1], 0);
+
+    hdr->data_len += static_cast<uint16_t>(needed);
+    hdr->entry_count++;
+    mik__rtc_update_crc();
+
+    JS_FreeCString(ctx, key);
+    return mik__result_ok_void(ctx);
+}
+
+static JSValue mik__rtc_get(JSContext* ctx, JSValue this_val, int argc, JSValue* argv) {
+    mik__rtc_ensure_valid();
+
+    const char* key = JS_ToCString(ctx, argv[0]);
+    if (!key) return JS_EXCEPTION;
+    size_t key_len = strlen(key);
+
+    if (key_len == 0 || key_len > MIK_RTC_MAX_KEY_LEN) {
+        JS_FreeCString(ctx, key);
+        return JS_UNDEFINED;
+    }
+
+    uint8_t* found = mik__rtc_find(key, static_cast<uint8_t>(key_len), nullptr);
+    JS_FreeCString(ctx, key);
+
+    if (!found) return JS_UNDEFINED;
+
+    /* Parse the entry to extract the CBOR value */
+    auto* hdr = reinterpret_cast<RtcHeader*>(s_rtc_store);
+    uint8_t* data = mik__rtc_data();
+    uint8_t* end = data + hdr->data_len;
+
+    uint8_t ek_len;
+    const char* ek;
+    uint16_t ev_len;
+    const char* ev;
+    mik__rtc_next_entry(found, end, &ek_len, &ek, &ev_len, &ev);
+
+    /* Decode CBOR bytes back into a JS value */
+    nanocbor_value_t decoder;
+    nanocbor_decoder_init(&decoder, reinterpret_cast<const uint8_t*>(ev), ev_len);
+    JSValue result = mik__cbor_decode_value(ctx, &decoder, 0);
+    if (JS_IsException(result)) return JS_UNDEFINED;
+    return result;
+}
+
+static JSValue mik__rtc_remove(JSContext* ctx, JSValue this_val, int argc, JSValue* argv) {
+    mik__rtc_ensure_valid();
+
+    const char* key = JS_ToCString(ctx, argv[0]);
+    if (!key) return JS_EXCEPTION;
+    size_t key_len = strlen(key);
+
+    if (key_len == 0 || key_len > MIK_RTC_MAX_KEY_LEN) {
+        JS_FreeCString(ctx, key);
+        return JS_NewBool(ctx, false);
+    }
+
+    auto* hdr = reinterpret_cast<RtcHeader*>(s_rtc_store);
+    uint8_t* data = mik__rtc_data();
+
+    uint8_t* next = nullptr;
+    uint8_t* found = mik__rtc_find(key, static_cast<uint8_t>(key_len), &next);
+    JS_FreeCString(ctx, key);
+
+    if (!found || !next) return JS_NewBool(ctx, false);
+
+    uint8_t* end = data + hdr->data_len;
+    size_t tail = end - next;
+    memmove(found, next, tail);
+    hdr->data_len -= static_cast<uint16_t>(next - found);
+    hdr->entry_count--;
+    mik__rtc_update_crc();
+
+    return JS_NewBool(ctx, true);
+}
+
+static JSValue mik__rtc_js_clear(JSContext* ctx, JSValue this_val, int argc, JSValue* argv) {
+    mik__rtc_clear();
+    return JS_UNDEFINED;
+}
+
+static JSValue mik__rtc_info(JSContext* ctx, JSValue this_val, int argc, JSValue* argv) {
+    mik__rtc_ensure_valid();
+
+    auto* hdr = reinterpret_cast<RtcHeader*>(s_rtc_store);
+    JSValue obj = JS_NewObject(ctx);
+    JS_SetPropertyStr(ctx, obj, "used", JS_NewInt32(ctx, hdr->data_len));
+    JS_SetPropertyStr(ctx, obj, "total", JS_NewInt32(ctx, MIK_RTC_DATA_CAPACITY));
+    JS_SetPropertyStr(ctx, obj, "entries", JS_NewInt32(ctx, hdr->entry_count));
+    return obj;
+}
+
+/* ── Module init ─────────────────────────────────────────────────── */
+
+static int mik__rtc_module_init(JSContext* ctx, JSModuleDef* m) {
+    JS_SetModuleExport(ctx, m, "set", JS_NewCFunction(ctx, mik__rtc_set, "set", 2));
+    JS_SetModuleExport(ctx, m, "get", JS_NewCFunction(ctx, mik__rtc_get, "get", 1));
+    JS_SetModuleExport(ctx, m, "remove", JS_NewCFunction(ctx, mik__rtc_remove, "remove", 1));
+    JS_SetModuleExport(ctx, m, "clear", JS_NewCFunction(ctx, mik__rtc_js_clear, "clear", 0));
+    JS_SetModuleExport(ctx, m, "info", JS_NewCFunction(ctx, mik__rtc_info, "info", 0));
+    return 0;
+}
+
+/* ── Public API ──────────────────────────────────────────────────── */
+
+static JSModuleDef* mik__rtc_init(JSContext* ctx) {
+    JSModuleDef* m = JS_NewCModule(ctx, "native:rtc", mik__rtc_module_init);
+    if (!m) return nullptr;
+    JS_AddModuleExport(ctx, m, "set");
+    JS_AddModuleExport(ctx, m, "get");
+    JS_AddModuleExport(ctx, m, "remove");
+    JS_AddModuleExport(ctx, m, "clear");
+    JS_AddModuleExport(ctx, m, "info");
+    return m;
+}
+
+MIK_REGISTER_MODULE(rtc, "native:rtc", mik__rtc_init, nullptr, nullptr)

package/components/mikrojs/mik_serial_io.cpp

@@ -0,0 +1,362 @@
+#include <cerrno>
+#include <stdio.h>
+#include <string.h>
+
+#include "driver/uart.h"
+#include "esp_intr_alloc.h"
+#include "esp_log.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "nvs.h"
+#include "nvs_flash.h"
+#include "mikrojs/mikrojs.h"
+#include "mikrojs/platform.h"
+#include "mikrojs_esp32.h"
+#include "soc/soc_caps.h"
+#include "soc/uart_pins.h"
+
+#if SOC_USB_SERIAL_JTAG_SUPPORTED
+#include "driver/usb_serial_jtag.h"
+/* mikrojs owns the USB-Serial/JTAG peripheral directly. Leaving
+ * CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y would have ESP-IDF register a
+ * VFS and write to the TX FIFO from stdio, racing our driver ISR. */
+#if CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG
+#error "Set CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=n (see sdkconfig.defaults.esp32*)"
+#endif
+#endif
+
+/* ── Console I/O ────────────────────────────────────────────────────
+ *
+ * Talks to UART0 and (where supported) the USB-Serial/JTAG peripheral
+ * directly through the ESP-IDF driver API, deliberately skipping the
+ * VFS / newlib stdio integration. Rationale:
+ *
+ *   - With `CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y`, ESP-IDF's startup
+ *     code registers a USB-JTAG VFS, hooks it into newlib's stdio, and
+ *     installs the driver before app_main() runs. On boards that cold-
+ *     boot from battery, that early VFS/newlib setup has been observed
+ *     to tip the supply past the brown-out threshold and lock the
+ *     chip. Micropython avoids this by talking to the USB-JTAG
+ *     hardware directly, never touching VFS; we do the same here but
+ *     use the stable public driver API (`usb_serial_jtag_*_bytes`)
+ *     instead of register-level LL calls, so the code survives IDF
+ *     major-version bumps without rework.
+ *
+ *   - sdkconfig keeps `CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=n` and
+ *     `CONFIG_ESP_CONSOLE_UART_DEFAULT=y`. That makes UART0 the target
+ *     of ESP_LOG/printf, but log output is already filtered to NONE in
+ *     production. We manage both consoles ourselves.
+ *
+ *   - The active console latches to whichever interface receives the
+ *     first byte from the host CLI (same UX as before).
+ */
+
+/* UART0 is always present on chips without USB-Serial/JTAG (plain
+ * ESP32). On chips with USJ, it's installed only when the
+ * CONFIG_MIKROJS_CONSOLE_FALLBACK_UART Kconfig is enabled (default
+ * n). Enable it to get the auto-detect dev UX on boards where a
+ * USB-TTL adapter is sometimes used instead of the native USB port;
+ * costs ~4 KB DRAM + a UART ISR in IRAM. */
+#if !SOC_USB_SERIAL_JTAG_SUPPORTED || CONFIG_MIKROJS_CONSOLE_FALLBACK_UART
+#define MIK_CONSOLE_HAS_UART 1
+#else
+#define MIK_CONSOLE_HAS_UART 0
+#endif
+
+static enum { CONSOLE_UART, CONSOLE_USB_SERIAL_JTAG } s_console =
+#if SOC_USB_SERIAL_JTAG_SUPPORTED
+    CONSOLE_USB_SERIAL_JTAG;
+#else
+    CONSOLE_UART;
+#endif
+
+#if SOC_USB_SERIAL_JTAG_SUPPORTED
+static bool s_usj_installed = false;
+#endif
+
+void mik__console_init(void) {
+#if SOC_USB_SERIAL_JTAG_SUPPORTED
+    /* Install USB-Serial/JTAG via the public driver API only. No VFS
+     * registration, no `fileno(stdin)`, no newlib integration — that's
+     * the whole point of this path.
+     *
+     * Both rings are sized to fit the largest single TLV frame plus a
+     * little headroom for the next frame's header to land alongside it.
+     *
+     * RX (host → device): the largest single command frame is a
+     * CMD_DEPLOY_PUT_CHUNK (≤ 2 KB body + 5 B header). Deploy PUTs no
+     * longer carry the file body in one frame — they're streamed as
+     * begin + N chunks with per-chunk MSG_OK pacing — so this size is
+     * a function of the chunk size, not of the largest deployable file.
+     * 4 KB gives ~2× headroom over a single chunk so the next command
+     * can be queued behind it.
+     *
+     * TX (device → host): bumped from the IDF default (256 B) to 2 KB
+     * so MSG_READY resends during the boot-handshake window don't fill
+     * the ring before the CLI's TTY starts draining. At 256 B the ring
+     * fills after ~3 MSG_READY sends, then subsequent writes (including
+     * the MSG_OK response to the first CMD_RUNTIME_PAUSE) stall long
+     * enough to blow past the CLI's 10 s pause timeout and force a
+     * restart-and-retry on every `mikro dev`. 2 KB is still small
+     * enough not to meaningfully dent RAM for display-heavy apps. */
+    usb_serial_jtag_driver_config_t usj_cfg = USB_SERIAL_JTAG_DRIVER_CONFIG_DEFAULT();
+    usj_cfg.rx_buffer_size = 4096;
+    usj_cfg.tx_buffer_size = 2048;
+    s_usj_installed = (usb_serial_jtag_driver_install(&usj_cfg) == ESP_OK);
+#endif
+
+#if MIK_CONSOLE_HAS_UART
+    /* UART0 for the primary (ESP32) or fallback (USJ-capable chips with
+     * CONFIG_MIKROJS_CONSOLE_FALLBACK_UART=y) console path. Configured
+     * explicitly because ESP_CONSOLE_UART_DEFAULT's startup code may
+     * not leave the hardware in the state we want for raw read/write. */
+    uart_config_t uart_config = {};
+    uart_config.baud_rate = 115200;
+    uart_config.data_bits = UART_DATA_8_BITS;
+    uart_config.parity = UART_PARITY_DISABLE;
+    uart_config.stop_bits = UART_STOP_BITS_1;
+    uart_config.flow_ctrl = UART_HW_FLOWCTRL_DISABLE;
+    uart_config.source_clk = UART_SCLK_DEFAULT;
+    uart_param_config(UART_NUM_0, &uart_config);
+    uart_set_pin(UART_NUM_0, U0TXD_GPIO_NUM, U0RXD_GPIO_NUM,
+                 UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
+    /* IRAM ISR keeps UART alive during flash writes (LittleFS deploys). */
+    uart_driver_install(UART_NUM_0, 4096, 0, 0, NULL, ESP_INTR_FLAG_IRAM);
+#endif
+}
+
+int mik__console_read(void* buf, size_t len) {
+#if SOC_USB_SERIAL_JTAG_SUPPORTED
+    if (s_console == CONSOLE_USB_SERIAL_JTAG) {
+        if (s_usj_installed) {
+            int n = usb_serial_jtag_read_bytes(buf, len, 0);
+            if (n > 0) return n;
+        }
+#if MIK_CONSOLE_HAS_UART
+        /* Auto-detect: probe UART0 too so the first byte on either
+         * interface latches the active console. Once latched to UART
+         * we stop probing USJ to avoid interleaving input streams. */
+        int n = uart_read_bytes(UART_NUM_0, buf, len, 0);
+        if (n > 0) {
+            s_console = CONSOLE_UART;
+            return n;
+        }
+#endif
+        /* The REPL protocol treats 0 as EOF, so map "no data
+         * available right now" to -1/EAGAIN like the old VFS
+         * path did. */
+        errno = EAGAIN;
+        return -1;
+    }
+#endif
+#if MIK_CONSOLE_HAS_UART
+    int n = uart_read_bytes(UART_NUM_0, buf, len, 0);
+    if (n == 0) {
+        errno = EAGAIN;
+        return -1;
+    }
+    return n;
+#else
+    errno = EAGAIN;
+    return -1;
+#endif
+}
+
+int mik__console_write(const void* buf, size_t len) {
+#if SOC_USB_SERIAL_JTAG_SUPPORTED
+    if (s_console == CONSOLE_USB_SERIAL_JTAG) {
+        /* No host attached: the ring buffer would fill and block writes
+         * forever. Drop silently so boot-time TLV sends (MSG_READY etc.)
+         * don't stall on bus/battery-only power. */
+        if (!s_usj_installed || !usb_serial_jtag_is_connected()) {
+            return (int)len;
+        }
+        /* Chunk writes below the TX ring size. `usb_serial_jtag_write_bytes`
+         * will not accept more than fits contiguously in the ring, so asking
+         * for (say) 257 bytes of a 256-byte ring returns 0 every iteration
+         * regardless of how fast the host drains. 64 sits well under any
+         * reasonable ring config.
+         *
+         * Bail after ~10 s of zero-progress iterations (host gone AWOL) so
+         * the runtime can't hang forever. */
+        const size_t max_chunk = 64;
+        const uint8_t* p = (const uint8_t*)buf;
+        size_t remaining = len;
+        int no_progress_ticks = 0;
+        while (remaining > 0) {
+            if (!usb_serial_jtag_is_connected()) return (int)len;
+            size_t chunk = remaining < max_chunk ? remaining : max_chunk;
+            int n = usb_serial_jtag_write_bytes(p, chunk, pdMS_TO_TICKS(200));
+            if (n > 0) {
+                p += n;
+                remaining -= (size_t)n;
+                no_progress_ticks = 0;
+            } else if (++no_progress_ticks > 50) {
+                return (int)len;
+            }
+        }
+        return (int)len;
+    }
+#endif
+#if MIK_CONSOLE_HAS_UART
+    return uart_write_bytes(UART_NUM_0, buf, len);
+#else
+    /* No console backend installed — drop the bytes. */
+    return (int)len;
+#endif
+}
+
+/* ── Binary serial I/O ──────────────────────────────────────────── */
+
+void mik__serial_binary_begin_no_echo(void) {
+    esp_log_level_set("*", ESP_LOG_NONE);
+    /* No line-ending translation to disable: we bypass VFS entirely,
+     * so `\n` passes through unchanged on both USJ and UART paths. */
+}
+
+/* ── NVS helpers ─────────────────────────────────────────────────── */
+
+const char* MIK__NVS_NS_ENV = "mik.env";
+const char* MIK__NVS_NS_SEC = "mik.sec";
+
+void mik__nvs_clear_namespace(const char* ns) {
+    nvs_handle_t handle;
+    if (nvs_open(ns, NVS_READWRITE, &handle) == ESP_OK) {
+        nvs_erase_all(handle);
+        nvs_commit(handle);
+        nvs_close(handle);
+    }
+}
+
+bool mik__nvs_put_string(const char* ns, const char* key, const char* value) {
+    nvs_handle_t handle;
+    esp_err_t err = nvs_open(ns, NVS_READWRITE, &handle);
+    if (err != ESP_OK) return false;
+
+    err = nvs_set_str(handle, key, value);
+    if (err == ESP_OK) {
+        err = nvs_commit(handle);
+    }
+    nvs_close(handle);
+    return err == ESP_OK;
+}
+
+/* Write only if the value differs from what's already stored. `out_changed`
+ * is set to true when the stored value ends up different than before, false
+ * if the existing value already matched. Returns false on I/O failure. */
+bool mik__nvs_put_string_if_diff(const char* ns, const char* key, const char* value,
+                                 bool* out_changed) {
+    nvs_handle_t handle;
+    esp_err_t err = nvs_open(ns, NVS_READWRITE, &handle);
+    if (err != ESP_OK) return false;
+
+    bool changed = true;
+    size_t existing_len = 0;
+    if (nvs_get_str(handle, key, nullptr, &existing_len) == ESP_OK) {
+        size_t new_len = strlen(value);
+        if (existing_len == new_len + 1) {
+            char buf[512];
+            if (existing_len <= sizeof(buf) &&
+                nvs_get_str(handle, key, buf, &existing_len) == ESP_OK) {
+                changed = memcmp(buf, value, new_len) != 0;
+            }
+        }
+    }
+
+    if (changed) {
+        err = nvs_set_str(handle, key, value);
+        if (err == ESP_OK) {
+            err = nvs_commit(handle);
+        }
+    }
+    nvs_close(handle);
+
+    if (out_changed) *out_changed = changed;
+    return err == ESP_OK;
+}
+
+bool mik__nvs_is_secret(const char* key) {
+    nvs_handle_t handle;
+    if (nvs_open(MIK__NVS_NS_SEC, NVS_READONLY, &handle) != ESP_OK) {
+        return false;
+    }
+    uint8_t val = 0;
+    esp_err_t err = nvs_get_u8(handle, key, &val);
+    nvs_close(handle);
+    return err == ESP_OK && val == 1;
+}
+
+bool mik__nvs_set_secret_flag(const char* key, bool secret) {
+    nvs_handle_t handle;
+    if (nvs_open(MIK__NVS_NS_SEC, NVS_READWRITE, &handle) != ESP_OK) {
+        return false;
+    }
+    esp_err_t err = secret ? nvs_set_u8(handle, key, 1) : nvs_erase_key(handle, key);
+    /* Erasing a key that wasn't there is a no-op success for our purposes. */
+    if (err == ESP_ERR_NVS_NOT_FOUND) err = ESP_OK;
+    if (err == ESP_OK) err = nvs_commit(handle);
+    nvs_close(handle);
+    return err == ESP_OK;
+}
+
+/* Sets the env var. `out_changed` reports whether the stored value or secret
+ * flag ended up differing from before (true on first insert, on value change,
+ * or on secret-flag flip). Returns false on I/O failure (env value or secret
+ * flag); `out_changed` is left untouched when returning false. */
+bool mik__nvs_env_set(const char* key, const char* value, bool secret, bool* out_changed) {
+    bool was_secret = mik__nvs_is_secret(key);
+    bool value_changed = false;
+    if (!mik__nvs_put_string_if_diff(MIK__NVS_NS_ENV, key, value, &value_changed)) {
+        return false;
+    }
+    if (was_secret != secret && !mik__nvs_set_secret_flag(key, secret)) {
+        return false;
+    }
+    if (out_changed) *out_changed = value_changed || (was_secret != secret);
+    return true;
+}
+
+/* Erases the env var. Returns true if the key existed before the call. */
+bool mik__nvs_env_delete(const char* key) {
+    bool existed = false;
+    nvs_handle_t handle;
+    if (nvs_open(MIK__NVS_NS_ENV, NVS_READWRITE, &handle) == ESP_OK) {
+        size_t len = 0;
+        if (nvs_get_str(handle, key, nullptr, &len) == ESP_OK) {
+            existed = true;
+        }
+        nvs_erase_key(handle, key);
+        nvs_commit(handle);
+        nvs_close(handle);
+    }
+    mik__nvs_set_secret_flag(key, false);
+    return existed;
+}
+
+/* ── NVS → MIK_SetEnvVar bridge ─────────────────────────────────── */
+
+void MIK_LoadEnvFromNVS(MIKRuntime* mik_rt) {
+    nvs_handle_t handle;
+    if (nvs_open(MIK__NVS_NS_ENV, NVS_READONLY, &handle) != ESP_OK) {
+        return;
+    }
+
+    nvs_iterator_t it = NULL;
+    esp_err_t err = nvs_entry_find_in_handle(handle, NVS_TYPE_STR, &it);
+    while (err == ESP_OK && it != NULL) {
+        nvs_entry_info_t info;
+        nvs_entry_info(it, &info);
+
+        size_t len = 0;
+        if (nvs_get_str(handle, info.key, NULL, &len) == ESP_OK) {
+            char buf[512];
+            if (len <= sizeof(buf) && nvs_get_str(handle, info.key, buf, &len) == ESP_OK) {
+                MIK_SetEnvVar(mik_rt, info.key, buf);
+            }
+        }
+
+        err = nvs_entry_next(&it);
+    }
+    nvs_release_iterator(it);
+    nvs_close(handle);
+}