@mikrojs/firmware 0.18.2 → 0.18.3-next.20260829153835

package/components/mikrojs/mik_logfile.cpp

@@ -5,6 +5,7 @@
 
 #include <cstdarg>
 #include <cstdio>
+#include <cstdlib>
 #include <cstring>
 #include <ctime>
 #include <sys/stat.h>
@@ -18,11 +19,16 @@
 
 static const char* TAG = "mik_logfile";
 
-/* Static buffers — total ~1.5 KiB plus a FreeRTOS mutex. */
-static char s_line_buf[512];        /* current line being assembled */
-static char s_stdio_buf[1024];      /* setvbuf target for the FILE* */
-static char s_path_main[96];        /* "<dir>/log.txt"   */
-static char s_path_rot[100];        /* "<dir>/log.txt.1" */
+/* Log buffers (~1.7 KiB), heap-allocated in mik_logfile_init so boots
+ * without a configured log file don't carry them in BSS. Never freed once
+ * logging is enabled — suspend/resume reuse the paths and stdio buffer. */
+struct MIKLogBufs {
+    char line[512];      /* current line being assembled */
+    char stdio[1024];    /* setvbuf target for the FILE* */
+    char path_main[96];  /* "<dir>/log.txt"   */
+    char path_rot[100];  /* "<dir>/log.txt.1" */
+};
+static MIKLogBufs* s_bufs = nullptr;
 static SemaphoreHandle_t s_mtx = nullptr;
 static FILE* s_file = nullptr;
 static size_t s_file_size = 0;
@@ -62,16 +68,26 @@ static bool line_is_error_level(const char* line, size_t len) {
     return false;
 }
 
+/* Caller holds s_mtx. fflush only moves the stdio buffer into the VFS;
+ * on LittleFS the bytes stay in the file handle's cache — invisible to
+ * other opens (fs.readFile, `mikro logs pull`) and lost on power cut —
+ * until fsync commits them. A flush that isn't durable defeats the
+ * purpose of the flush policy, so always pair the two. */
+static void flush_to_flash() {
+    fflush(s_file);
+    fsync(fileno(s_file));
+}
+
 /* Caller holds s_mtx. */
 static void rotate_if_needed() {
     if (s_file_size < s_max_size) return;
     fclose(s_file);
     s_file = nullptr;
-    unlink(s_path_rot);
-    rename(s_path_main, s_path_rot);
-    s_file = fopen(s_path_main, "a");
+    unlink(s_bufs->path_rot);
+    rename(s_bufs->path_main, s_bufs->path_rot);
+    s_file = fopen(s_bufs->path_main, "a");
     if (s_file) {
-        setvbuf(s_file, s_stdio_buf, _IOFBF, sizeof(s_stdio_buf));
+        setvbuf(s_file, s_bufs->stdio, _IOFBF, sizeof(s_bufs->stdio));
         s_file_size = 0;
     }
 }
@@ -84,12 +100,12 @@ static void emit_line() {
         s_line_has_ts = false;
         return;
     }
-    size_t n = fwrite(s_line_buf, 1, s_line_pos, s_file);
+    size_t n = fwrite(s_bufs->line, 1, s_line_pos, s_file);
     s_file_size += n;
-    bool is_err = line_is_error_level(s_line_buf, s_line_pos);
+    bool is_err = line_is_error_level(s_bufs->line, s_line_pos);
     if (s_flush_policy == MIK_LOG_FLUSH_LINE ||
         (s_flush_policy == MIK_LOG_FLUSH_ERROR && is_err)) {
-        fflush(s_file);
+        flush_to_flash();
     }
     rotate_if_needed();
     s_line_pos = 0;
@@ -99,17 +115,17 @@ static void emit_line() {
 /* Caller holds s_mtx. */
 static void append_byte(uint8_t c) {
     if (!s_line_has_ts) {
-        int n = format_timestamp(s_line_buf, sizeof(s_line_buf) - 1);
-        if (n < 0 || (size_t)n >= sizeof(s_line_buf) - 1) n = 0;
+        int n = format_timestamp(s_bufs->line, sizeof(s_bufs->line) - 1);
+        if (n < 0 || (size_t)n >= sizeof(s_bufs->line) - 1) n = 0;
         s_line_pos = (size_t)n;
         s_line_has_ts = true;
     }
-    if (s_line_pos < sizeof(s_line_buf) - 1) {
-        s_line_buf[s_line_pos++] = (char)c;
+    if (s_line_pos < sizeof(s_bufs->line) - 1) {
+        s_bufs->line[s_line_pos++] = (char)c;
     }
-    if (c == '\n' || s_line_pos >= sizeof(s_line_buf) - 1) {
-        if (s_line_pos == 0 || s_line_buf[s_line_pos - 1] != '\n') {
-            s_line_buf[s_line_pos++] = '\n';
+    if (c == '\n' || s_line_pos >= sizeof(s_bufs->line) - 1) {
+        if (s_line_pos == 0 || s_bufs->line[s_line_pos - 1] != '\n') {
+            s_bufs->line[s_line_pos++] = '\n';
         }
         emit_line();
     }
@@ -133,12 +149,12 @@ static void log_emit_tap(uint8_t msg_type, const void* data, size_t len) {
     for (size_t i = 0; i < len; i++) append_byte(p[i]);
     /* Ensure the line is closed even if the body lacks a trailing newline
      * (mik__repl_proto_send_output is called once per logical message). */
-    if (s_line_pos > 0 && s_line_buf[s_line_pos - 1] != '\n') {
+    if (s_line_pos > 0 && s_bufs->line[s_line_pos - 1] != '\n') {
         append_byte((uint8_t)'\n');
     }
     if (s_file && (msg_type == MIK_MSG_ERROR || msg_type == MIK_MSG_WARN ||
                    msg_type == MIK_MSG_EVAL_ERROR)) {
-        fflush(s_file);
+        flush_to_flash();
     }
     xSemaphoreGive(s_mtx);
 }
@@ -174,24 +190,35 @@ void mik_logfile_init(const MIKConfig* config) {
      * which is fine. */
     mkdir(config->log_dir, 0775);
 
-    if ((size_t)snprintf(s_path_main, sizeof(s_path_main), "%s/log.txt", config->log_dir) >=
-        sizeof(s_path_main)) {
+    s_bufs = static_cast<MIKLogBufs*>(calloc(1, sizeof(MIKLogBufs)));
+    if (!s_bufs) return;
+
+    if ((size_t)snprintf(s_bufs->path_main, sizeof(s_bufs->path_main), "%s/log.txt", config->log_dir) >=
+        sizeof(s_bufs->path_main)) {
         platform->log(MIK_LOG_WARN, TAG, "log dir path too long");
+        free(s_bufs);
+        s_bufs = nullptr;
         return;
     }
-    snprintf(s_path_rot, sizeof(s_path_rot), "%s.1", s_path_main);
+    snprintf(s_bufs->path_rot, sizeof(s_bufs->path_rot), "%s.1", s_bufs->path_main);
 
     s_mtx = xSemaphoreCreateMutex();
-    if (!s_mtx) return;
+    if (!s_mtx) {
+        free(s_bufs);
+        s_bufs = nullptr;
+        return;
+    }
 
-    s_file = fopen(s_path_main, "a");
+    s_file = fopen(s_bufs->path_main, "a");
     if (!s_file) {
         platform->log(MIK_LOG_WARN, TAG, "Could not open log file");
         vSemaphoreDelete(s_mtx);
         s_mtx = nullptr;
+        free(s_bufs);
+        s_bufs = nullptr;
         return;
     }
-    setvbuf(s_file, s_stdio_buf, _IOFBF, sizeof(s_stdio_buf));
+    setvbuf(s_file, s_bufs->stdio, _IOFBF, sizeof(s_bufs->stdio));
     fseek(s_file, 0, SEEK_END);
     long pos = ftell(s_file);
     s_file_size = pos > 0 ? (size_t)pos : 0;
@@ -221,9 +248,9 @@ void mik_logfile_resume(void) {
     if (!s_mtx) return;
     if (xSemaphoreTake(s_mtx, pdMS_TO_TICKS(100)) != pdTRUE) return;
     if (!s_file) {
-        s_file = fopen(s_path_main, "a");
+        s_file = fopen(s_bufs->path_main, "a");
         if (s_file) {
-            setvbuf(s_file, s_stdio_buf, _IOFBF, sizeof(s_stdio_buf));
+            setvbuf(s_file, s_bufs->stdio, _IOFBF, sizeof(s_bufs->stdio));
             fseek(s_file, 0, SEEK_END);
             long pos = ftell(s_file);
             s_file_size = pos > 0 ? (size_t)pos : 0;
@@ -239,12 +266,12 @@ void mik_logfile_reset(void) {
         fclose(s_file);
         s_file = nullptr;
     }
-    unlink(s_path_main);
-    unlink(s_path_rot);
+    unlink(s_bufs->path_main);
+    unlink(s_bufs->path_rot);
     /* Reopen the same path: unlinked, so this starts a fresh empty file. */
-    s_file = fopen(s_path_main, "a");
+    s_file = fopen(s_bufs->path_main, "a");
     if (s_file) {
-        setvbuf(s_file, s_stdio_buf, _IOFBF, sizeof(s_stdio_buf));
+        setvbuf(s_file, s_bufs->stdio, _IOFBF, sizeof(s_bufs->stdio));
         s_file_size = 0;
     }
     /* Drop any half-assembled line so a stale prefix doesn't bleed into
@@ -257,7 +284,7 @@ void mik_logfile_reset(void) {
 void mik_logfile_flush(void) {
     if (!s_mtx || !s_file) return;
     if (xSemaphoreTake(s_mtx, pdMS_TO_TICKS(50)) != pdTRUE) return;
-    fflush(s_file);
+    flush_to_flash();
     xSemaphoreGive(s_mtx);
 }
 
@@ -271,10 +298,10 @@ void mik_logfile_close(void) {
         s_prev_vprintf = nullptr;
     }
     if (s_line_pos > 0) {
-        if (s_line_buf[s_line_pos - 1] != '\n' && s_line_pos < sizeof(s_line_buf)) {
-            s_line_buf[s_line_pos++] = '\n';
+        if (s_bufs->line[s_line_pos - 1] != '\n' && s_line_pos < sizeof(s_bufs->line)) {
+            s_bufs->line[s_line_pos++] = '\n';
         }
-        if (s_file) fwrite(s_line_buf, 1, s_line_pos, s_file);
+        if (s_file) fwrite(s_bufs->line, 1, s_line_pos, s_file);
         s_line_pos = 0;
     }
     if (s_file) {

package/components/mikrojs/mik_main.cpp

@@ -1,5 +1,6 @@
 #include <cerrno>
 #include <stdio.h>
+#include <stdlib.h>
 #include <string.h>
 #include <strings.h>
 #include <sys/time.h>
@@ -97,24 +98,26 @@ static void mik__apply_nvs_log_level(void) {
     esp_log_level_set("mik_app_config", level);
 }
 
-/* File-scope scratch buffers for the supervisor loop.
+/* Scratch buffers for the supervisor loop, heap-allocated for the duration
+ * of a test-manifest run so normal boots don't carry them in BSS (~3 KB).
  *
  * Kept off the stack because the main task stack is ~24 KB and cannot
  * accommodate 1-2 KB of local buffers on top of the nested eval/module
  * normalizer call chain (observed as a stack-protection fault in
  * mik_module_normalizer on the first test file). Fixed sizes instead of
  * PATH_MAX scaling — on newlib PATH_MAX can be 4096, which is absurd for
- * our purposes and would still blow the BSS budget. These sizes fit any
- * realistic on-device test path. Only one test manifest runs per boot,
- * so single-ownership is safe. */
+ * our purposes. These sizes fit any realistic on-device test path. Only
+ * one test manifest runs per boot, so single-ownership is safe. */
 #define MIK_SUP_PATH_MAX 384
-static char s_sup_dbg[MIK_SUP_PATH_MAX + 64];
-static char s_sup_esc[MIK_SUP_PATH_MAX * 2 + 8];
-static char s_sup_buf[MIK_SUP_PATH_MAX * 2 + 512];
-/* Exception text captured by MIK_RunEntryErr when a test file fails to
- * evaluate, and its JSON-escaped form for the synthesized test event. */
-static char s_sup_err[192];
-static char s_sup_err_esc[sizeof(s_sup_err) * 2 + 8];
+struct MIKSupScratch {
+    char dbg[MIK_SUP_PATH_MAX + 64];
+    char esc[MIK_SUP_PATH_MAX * 2 + 8];
+    char buf[MIK_SUP_PATH_MAX * 2 + 512];
+    /* Exception text captured by MIK_RunEntryErr when a test file fails to
+     * evaluate, and its JSON-escaped form for the synthesized test event. */
+    char err[192];
+    char err_esc[sizeof(err) * 2 + 8];
+};
 
 /* Minimal JSON string-escape into a bounded buffer. Handles `"`, `\`, and
  * control characters; everything else copies verbatim. Returns bytes
@@ -540,6 +543,18 @@ void MIK_Main(void) {
     MIK_ProtocolOpen(&transport);
 
     if (test_mode) {
+        auto* sup = static_cast<MIKSupScratch*>(malloc(sizeof(MIKSupScratch)));
+        if (!sup) {
+            ESP_LOGE(TAG, "Not enough memory for the test supervisor");
+            /* Fail loud: a synthesized failing run-done plus end-of-manifest
+             * lets the CLI report the failure instead of hanging on a stream
+             * that will never produce results. */
+            static const char kOomRunDone[] = "{\"e\":6,\"p\":0,\"f\":1,\"k\":0,\"o\":0,\"d\":0}";
+            mik__proto_send(&transport, MIK_MSG_TEST, kOomRunDone, sizeof(kOomRunDone) - 1);
+            mik__proto_send(&transport, MIK_MSG_MANIFEST_DONE, nullptr, 0);
+            return;
+        }
+
         /* Discard the primary runtime — each test gets a fresh one. */
         MIK_FreeRuntime(mik_rt);
         mik_rt = nullptr;
@@ -548,21 +563,21 @@ void MIK_Main(void) {
             /* Diagnostic: announce the file about to run so the CLI can
              * confirm the supervisor's iteration matches its own testFiles
              * order. The MSG_DEBUG frame is rendered as a dim log line.
-             * Uses file-scope s_sup_dbg to avoid bloating the main task
-             * stack — the normalizer call chain during module resolution
-             * already sits a few KB deep. */
+             * Uses heap scratch to avoid bloating the main task stack —
+             * the normalizer call chain during module resolution already
+             * sits a few KB deep. */
             {
-                int n = snprintf(s_sup_dbg, sizeof(s_sup_dbg),
+                int n = snprintf(sup->dbg, sizeof(sup->dbg),
                                  "[supervisor] running %zu/%zu: %s", i + 1, test_count,
                                  test_paths[i]);
-                if (n > 0 && n < (int)sizeof(s_sup_dbg)) {
-                    mik__proto_send(&transport, MIK_MSG_DEBUG, s_sup_dbg, n);
+                if (n > 0 && n < (int)sizeof(sup->dbg)) {
+                    mik__proto_send(&transport, MIK_MSG_DEBUG, sup->dbg, n);
                 }
             }
             MIKRuntime* rt = create_runtime();
             MIK_EnableTestHelpers(rt);
             MIK_ProtocolAttach(rt);
-            int rc = MIK_RunEntryErr(rt, test_paths[i], s_sup_err, sizeof(s_sup_err));
+            int rc = MIK_RunEntryErr(rt, test_paths[i], sup->err, sizeof(sup->err));
             const char* fail_reason = nullptr;
             if (rc == -ENOENT) {
                 fail_reason = "Test file not found";
@@ -584,38 +599,38 @@ void MIK_Main(void) {
                  * the runtime will never emit. Escape the path so any `"`
                  * or `\` in it doesn't corrupt the JSON frame. */
                 ESP_LOGE(TAG, "%s: %s", fail_reason, test_paths[i]);
-                if (mik__json_escape(s_sup_esc, sizeof(s_sup_esc), test_paths[i]) < 0) {
+                if (mik__json_escape(sup->esc, sizeof(sup->esc), test_paths[i]) < 0) {
                     /* Path too long to fit even escaped — fall back to
                      * basename so the frame at least identifies something. */
                     const char* base = strrchr(test_paths[i], '/');
                     if (!base ||
-                        mik__json_escape(s_sup_esc, sizeof(s_sup_esc), base + 1) < 0) {
-                        s_sup_esc[0] = '?';
-                        s_sup_esc[1] = '\0';
+                        mik__json_escape(sup->esc, sizeof(sup->esc), base + 1) < 0) {
+                        sup->esc[0] = '?';
+                        sup->esc[1] = '\0';
                     }
                 }
                 /* Append the captured exception text (escaped) so the CLI
                  * shows the actual error, not just "Evaluation threw". */
-                s_sup_err_esc[0] = '\0';
-                if (rc == -EFAULT && s_sup_err[0] != '\0') {
-                    if (mik__json_escape(s_sup_err_esc, sizeof(s_sup_err_esc), s_sup_err) < 0) {
-                        s_sup_err_esc[0] = '\0';
+                sup->err_esc[0] = '\0';
+                if (rc == -EFAULT && sup->err[0] != '\0') {
+                    if (mik__json_escape(sup->err_esc, sizeof(sup->err_esc), sup->err) < 0) {
+                        sup->err_esc[0] = '\0';
                     }
                 }
                 int n;
-                if (s_sup_err_esc[0] != '\0') {
-                    n = snprintf(s_sup_buf, sizeof(s_sup_buf),
+                if (sup->err_esc[0] != '\0') {
+                    n = snprintf(sup->buf, sizeof(sup->buf),
                                  "{\"e\":3,\"s\":\"<load>\",\"t\":\"%s\",\"d\":0,"
                                  "\"m\":\"%s: %s\"}",
-                                 s_sup_esc, fail_reason, s_sup_err_esc);
+                                 sup->esc, fail_reason, sup->err_esc);
                 } else {
-                    n = snprintf(s_sup_buf, sizeof(s_sup_buf),
+                    n = snprintf(sup->buf, sizeof(sup->buf),
                                  "{\"e\":3,\"s\":\"<load>\",\"t\":\"%s\",\"d\":0,"
                                  "\"m\":\"%s\"}",
-                                 s_sup_esc, fail_reason);
+                                 sup->esc, fail_reason);
                 }
-                if (n > 0 && n < (int)sizeof(s_sup_buf)) {
-                    mik__proto_send(&transport, MIK_MSG_TEST, s_sup_buf, n);
+                if (n > 0 && n < (int)sizeof(sup->buf)) {
+                    mik__proto_send(&transport, MIK_MSG_TEST, sup->buf, n);
                 }
                 static const char kRunDone[] =
                     "{\"e\":6,\"p\":0,\"f\":1,\"k\":0,\"o\":0,\"d\":0}";
@@ -624,6 +639,7 @@ void MIK_Main(void) {
             MIK_ProtocolDetach();
             MIK_FreeRuntime(rt);
         }
+        free(sup);
 
         /* Signal end-of-manifest so the CLI can finalize its report
          * without waiting on a silent stream. */

package/components/mikrojs/mik_ota_client_module.cpp

@@ -69,6 +69,11 @@ struct MIKOtaClientState {
     JSValue on_config = JS_UNDEFINED;
     std::vector<std::unique_ptr<PendingCheck>> pending;
     bool watching = false;
+    /* The reconcile diagnostic, held for report() the way the built-in client
+     * holds it for its own rounds: env->reconcile is read-once, so this is the
+     * only copy left after ota.reconcile() ran. settle() marks it delivered. */
+    bool has_last_install = false;
+    MIKOtaDiagnostic last_install = {};
 };
 
 int mik__ota_client_slot = -1;
@@ -296,7 +301,17 @@ JSValue mik__ota_client_watch(JSContext* ctx, JSValue this_val, int argc, JSValu
         }
     }
 
-    state->client->Watch(options);
+    if (!state->client->Watch(options)) {
+        /* Enrollment is written over the cable, so nothing this boot does can
+         * make a later round succeed. Drop the hooks installed above and hand
+         * the app a typed error instead of an inert watcher. */
+        state->hooks.reset();
+        JS_FreeValue(ctx, state->on_config);
+        state->on_config = JS_UNDEFINED;
+        return mik__result_err_named(
+            ctx, "NotEnrolled",
+            "device not enrolled; run `mikro ota enroll` to enable OTA updates");
+    }
     state->watching = true;
 
     JSValue handle = JS_NewObject(ctx);
@@ -305,7 +320,7 @@ JSValue mik__ota_client_watch(JSContext* ctx, JSValue this_val, int argc, JSValu
     JS_SetPropertyStr(
         ctx, handle, "setCheckinInterval",
         JS_NewCFunction(ctx, mik__ota_client_set_interval, "setCheckinInterval", 1));
-    return handle;
+    return mik__result_ok(ctx, handle);
 }
 
 // ── the policy surface (mikro/ota) ──────────────────────────────────────────
@@ -345,6 +360,10 @@ JSValue ota_reconcile(JSContext* ctx, JSValue, int, JSValue*) {
     MIKOtaClientState* state = state_of(ctx);
     CHECK_NOT_NULL(state);
     MIKOtaReconcileOutcome outcome = mikrojs::mik__ota_policy_reconcile(state->env);
+    if (outcome.has_diagnostic) {
+        state->has_last_install = true;
+        state->last_install = outcome.diagnostic;
+    }
 
     JSValue obj = JS_NewObject(ctx);
     if (outcome.installed[0]) {
@@ -776,6 +795,20 @@ JSValue ota_apply_config(JSContext* ctx, JSValue, int argc, JSValue* argv) {
     return JS_NewString(ctx, mikrojs::mik__ota_config_write_to_str(write));
 }
 
+/* Loads the rolled-back report and sets the echo rev on `obj` under `rev_key`.
+ * After a rollback the FAILED document's rev is the one to echo, not the
+ * restored one's: echoed-equals-held is what stops the registry serving the
+ * document that just failed, until an operator changes it. Returns whether a
+ * report stands, leaving it in *report for the caller to marshal. */
+bool set_config_echo(JSContext* ctx, JSValue obj, const char* rev_key, const MIKOtaEnv* env,
+                     MIKOtaConfigErrorReport* report) {
+    bool has_error = mikrojs::mik__ota_load_config_error(env, report);
+    mikrojs::MIKOtaLoadedConfig held = mikrojs::mik__ota_load_slot(env, MIK_OTA_CFG_CURRENT);
+    const char* rev = has_error ? report->rev : (held.present ? held.cfg.rev : "");
+    if (rev[0]) JS_SetPropertyStr(ctx, obj, rev_key, JS_NewString(ctx, rev));
+    return has_error;
+}
+
 /* configState() -> {rev?, error?} */
 JSValue ota_config_state(JSContext* ctx, JSValue, int, JSValue*) {
     MIKOtaClientState* state = state_of(ctx);
@@ -783,22 +816,161 @@ JSValue ota_config_state(JSContext* ctx, JSValue, int, JSValue*) {
 
     JSValue obj = JS_NewObject(ctx);
     MIKOtaConfigErrorReport report = {};
-    bool has_error = mikrojs::mik__ota_load_config_error(state->env, &report);
-    if (has_error) {
+    if (set_config_echo(ctx, obj, "rev", state->env, &report)) {
         JSValue error = JS_NewObject(ctx);
         JS_SetPropertyStr(ctx, error, "rev", JS_NewString(ctx, report.rev));
         JS_SetPropertyStr(ctx, error, "message", JS_NewString(ctx, report.message));
         JS_SetPropertyStr(ctx, obj, "error", error);
     }
-    /* After a rollback the FAILED document's rev is the one to echo, not the
-     * restored one's: echoed-equals-held is what stops the registry serving the
-     * document that just failed, until an operator changes it. */
-    mikrojs::MIKOtaLoadedConfig held = mikrojs::mik__ota_load_slot(state->env, MIK_OTA_CFG_CURRENT);
-    const char* rev = has_error ? report.rev : (held.present ? held.cfg.rev : "");
-    if (rev[0]) JS_SetPropertyStr(ctx, obj, "rev", JS_NewString(ctx, rev));
     return obj;
 }
 
+// ── the check-in exchange, for a client with its own transport ──────────────
+//
+// report() and settle() are the two halves the built-in client runs around its
+// HTTP call: the same facts gathering as BeginCheckIn (mik_ota_client.cpp) and
+// the same completed-round handling as its response parse. Everything either
+// touches is an existing policy call, so a client that goes through here and
+// the built-in cannot disagree about what a round sends or settles.
+
+/* report() -> the check-in body the device owes its registry, wire field
+ * shapes throughout so a proxy can forward fields verbatim. */
+JSValue ota_report(JSContext* ctx, JSValue, int, JSValue*) {
+    MIKOtaClientState* state = state_of(ctx);
+    CHECK_NOT_NULL(state);
+    const MIKOtaEnv* env = state->env;
+
+    JSValue obj = JS_NewObject(ctx);
+
+    MIKDeviceIdentity identity = {};
+    if (env && env->identity) env->identity(env->opaque, &identity);
+    JS_SetPropertyStr(ctx, obj, "deviceId", JS_NewString(ctx, identity.device_id));
+    JS_SetPropertyStr(ctx, obj, "firmware", JS_NewString(ctx, identity.firmware_version));
+    JS_SetPropertyStr(ctx, obj, "firmwareHash", JS_NewString(ctx, identity.firmware_hash));
+    JS_SetPropertyStr(ctx, obj, "bytecode", JS_NewInt32(ctx, identity.bytecode_version));
+
+    JS_SetPropertyStr(ctx, obj, "running", ota_running(ctx, JS_UNDEFINED, 0, nullptr));
+
+    /* The name pair, sent every round so a lost response settles on the next
+     * check-in: [rev, name], or [rev] when never named or cleared. */
+    int name_rev = 0;
+    char name[64] = {};
+    bool has_name = env && env->get_device_name &&
+                    env->get_device_name(env->opaque, &name_rev, name, sizeof(name));
+    JSValue pair = JS_NewArray(ctx);
+    JS_SetPropertyUint32(ctx, pair, 0, JS_NewInt32(ctx, name_rev));
+    if (has_name && name[0]) JS_SetPropertyUint32(ctx, pair, 1, JS_NewString(ctx, name));
+    JS_SetPropertyStr(ctx, obj, "name", pair);
+
+    size_t free_bytes = 0;
+    if (env && env->storage_free && env->storage_free(env->opaque, &free_bytes)) {
+        JS_SetPropertyStr(ctx, obj, "free", JS_NewInt64(ctx, (int64_t)free_bytes));
+    }
+
+    if (state->has_last_install) {
+        JSValue diag = JS_NewObject(ctx);
+        JS_SetPropertyStr(ctx, diag, "reason", JS_NewString(ctx, state->last_install.reason));
+        if (state->last_install.detail[0]) {
+            JS_SetPropertyStr(ctx, diag, "detail", JS_NewString(ctx, state->last_install.detail));
+        }
+        JS_SetPropertyStr(ctx, obj, "lastInstall", diag);
+    }
+
+    /* configRev / configError, through the same resolution as configState(). */
+    MIKOtaConfigErrorReport report = {};
+    if (set_config_echo(ctx, obj, "configRev", env, &report)) {
+        JSValue error = JS_NewObject(ctx);
+        JS_SetPropertyStr(ctx, error, "rev", JS_NewString(ctx, report.rev));
+        JS_SetPropertyStr(ctx, error, "message", JS_NewString(ctx, report.message));
+        JS_SetPropertyStr(ctx, obj, "configError", error);
+    }
+    return obj;
+}
+
+/* settle(raw, {trialBoots, allowInsecure}) -> {offer?, config?, renamed}
+ *
+ * Only for a COMPLETED check-in: the confirm below is the whole health signal
+ * requireConfirm waits for, so settling a failed round would keep exactly the
+ * build (or document) that rollback exists to catch. */
+JSValue ota_settle(JSContext* ctx, JSValue, int argc, JSValue* argv) {
+    MIKOtaClientState* state = state_of(ctx);
+    CHECK_NOT_NULL(state);
+
+    JSValue raw = argc > 0 ? argv[0] : JS_UNDEFINED;
+    JSValue out = JS_NewObject(ctx);
+
+    /* Mirror the built-in's response guard (its DecodeFailed path): null or
+     * undefined is the registry's quiet round, and an object is a decoded
+     * response — but anything else is a body that never decoded (a captive
+     * portal's HTML, a proxy's error page). That is not a completed round, so
+     * nothing settles: no confirm, and the cached install report stays for
+     * the round that does complete. */
+    bool quiet = JS_IsUndefined(raw) || JS_IsNull(raw);
+    bool usable = JS_IsObject(raw) && !JS_IsArray(raw) && !JS_IsFunction(ctx, raw);
+    if (!quiet && !usable) {
+        JS_SetPropertyStr(ctx, out, "renamed", JS_FALSE);
+        return out;
+    }
+
+    /* Confirm before the deliveries, as the built-in does: it must settle the
+     * document held BEFORE this round, never the one about to be armed. */
+    mikrojs::mik__ota_policy_confirm(state->env);
+    /* The round completed, so the cached install report was delivered. */
+    state->has_last_install = false;
+
+    bool renamed = false;
+    if (usable) {
+        /* The name pair: [rev] or [rev, name]. No `name` key means "no change"
+         * and never "clear it"; junk in the pair is treated the same way. The
+         * adopt is unconditional — the registry only sends the key when its
+         * rev should win. */
+        JSValue pair = JS_GetPropertyStr(ctx, raw, "name");
+        if (JS_IsArray(pair)) {
+            JSValue rev_val = JS_GetPropertyUint32(ctx, pair, 0);
+            /* A rev is a non-negative int32, as the wire carries it; a
+             * fractional or oversized number is junk, not a truncation. */
+            double rev_num = -1;
+            bool rev_ok = JS_IsNumber(rev_val) && JS_ToFloat64(ctx, &rev_num, rev_val) == 0 &&
+                          rev_num >= 0 && rev_num <= 2147483647.0 &&
+                          rev_num == (double)(int32_t)rev_num;
+            int32_t rev = rev_ok ? (int32_t)rev_num : -1;
+            JS_FreeValue(ctx, rev_val);
+            if (rev_ok && state->env && state->env->set_device_name) {
+                JSValue name_val = JS_GetPropertyUint32(ctx, pair, 1);
+                const char* name = JS_IsString(name_val) ? JS_ToCString(ctx, name_val) : nullptr;
+                state->env->set_device_name(state->env->opaque, rev,
+                                            name && name[0] ? name : nullptr);
+                renamed = true;
+                if (name) JS_FreeCString(ctx, name);
+                JS_FreeValue(ctx, name_val);
+            }
+        }
+        JS_FreeValue(ctx, pair);
+
+        /* The config document goes through the applyConfig path unchanged, so
+         * the two entrances cannot diverge on validation or placement. */
+        JSValue cfg_raw = JS_GetPropertyStr(ctx, raw, "config");
+        if (!JS_IsUndefined(cfg_raw) && !JS_IsNull(cfg_raw)) {
+            JSValue args[2] = {cfg_raw, argc > 1 ? argv[1] : JS_UNDEFINED};
+            JS_SetPropertyStr(ctx, out, "config", ota_apply_config(ctx, JS_UNDEFINED, 2, args));
+        }
+        JS_FreeValue(ctx, cfg_raw);
+
+        /* The offer fields are top-level in the response, so the whole body
+         * goes to the parser, exactly as ota.parseOffer(body) would. */
+        bool allow_insecure = false;
+        if (argc > 1 && JS_IsObject(argv[1])) {
+            allow_insecure = opt_bool(ctx, argv[1], "allowInsecure", false);
+        }
+        MIKOtaOffer offer;
+        if (mikrojs::mik__ota_parse_offer_js(ctx, raw, allow_insecure, &offer)) {
+            JS_SetPropertyStr(ctx, out, "offer", offer_to_js(ctx, offer));
+        }
+    }
+    JS_SetPropertyStr(ctx, out, "renamed", JS_NewBool(ctx, renamed));
+    return out;
+}
+
 int mik__ota_client_module_init(JSContext* ctx, JSModuleDef* m) {
     JS_SetModuleExport(ctx, m, "check", JS_NewCFunction(ctx, mik__ota_client_check, "check", 1));
     JS_SetModuleExport(ctx, m, "watch", JS_NewCFunction(ctx, mik__ota_client_watch, "watch", 1));
@@ -819,6 +991,8 @@ int mik__ota_client_module_init(JSContext* ctx, JSModuleDef* m) {
                        JS_NewCFunction(ctx, ota_apply_config, "applyConfig", 2));
     JS_SetModuleExport(ctx, m, "configState",
                        JS_NewCFunction(ctx, ota_config_state, "configState", 0));
+    JS_SetModuleExport(ctx, m, "report", JS_NewCFunction(ctx, ota_report, "report", 0));
+    JS_SetModuleExport(ctx, m, "settle", JS_NewCFunction(ctx, ota_settle, "settle", 2));
     return 0;
 }
 
@@ -869,6 +1043,8 @@ JSModuleDef* mik__ota_client_init(JSContext* ctx) {
     JS_AddModuleExport(ctx, m, "parseConfig");
     JS_AddModuleExport(ctx, m, "applyConfig");
     JS_AddModuleExport(ctx, m, "configState");
+    JS_AddModuleExport(ctx, m, "report");
+    JS_AddModuleExport(ctx, m, "settle");
     return m;
 }
 

package/components/mikrojs/platform_esp32.cpp

@@ -112,6 +112,10 @@ static void* esp32_realloc_psram(void* ptr, size_t size) {
 #endif
 }
 
+static size_t esp32_malloc_usable_size(const void* ptr) {
+    return heap_caps_get_allocated_size(const_cast<void*>(ptr));
+}
+
 static bool esp32_get_fs_info(const char* label, size_t* total, size_t* used) {
 #if HAS_LITTLEFS
     return esp_littlefs_info(label, total, used) == ESP_OK;
@@ -326,6 +330,7 @@ static const MIKPlatform esp32_platform = {
     .malloc_psram = esp32_malloc_psram,
     .calloc_psram = esp32_calloc_psram,
     .realloc_psram = esp32_realloc_psram,
+    .malloc_usable_size = esp32_malloc_usable_size,
     .get_fs_info = esp32_get_fs_info,
     .log = esp32_log,
     .stdout_write = esp32_stdout_write,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/firmware",
-  "version": "0.18.2",
+  "version": "0.18.3-next.20260829153835",
   "description": "Mikro.js ESP32 firmware: ESP-IDF component, build tools, and project template",
   "keywords": [
     "esp-idf",
@@ -47,8 +47,8 @@
   },
   "dependencies": {
     "esbuild": "^0.28.0",
-    "@mikrojs/native": "0.18.2",
-    "@mikrojs/quickjs": "0.18.2"
+    "@mikrojs/quickjs": "0.18.3-next.20260829153835+bf6b328",
+    "@mikrojs/native": "0.18.3-next.20260829153835+bf6b328"
   },
   "engines": {
     "node": ">=24.0.0"

package/sdkconfig.defaults

@@ -32,6 +32,16 @@ CONFIG_HEAP_PLACE_FUNCTION_INTO_FLASH=y
 CONFIG_ESP_WIFI_IRAM_OPT=n
 CONFIG_ESP_WIFI_RX_IRAM_OPT=n
 
+# Run the WiFi modem-sleep RX path from flash instead of IRAM (~13KB on C6:
+# the .wifislprxiram/.wifislpiram sections). Same trade as the flags above,
+# but for the sleep wake path: slightly slower beacon RX while in modem
+# sleep with STA power save enabled.
+CONFIG_ESP_WIFI_SLP_IRAM_OPT=n
+
+# Drop the "extra" WiFi IRAM optimization (~7KB on C6: .wifiextrairam).
+# Another member of the same IRAM-for-throughput family.
+CONFIG_ESP_WIFI_EXTRA_IRAM_OPT=n
+
 # Trim WiFi driver buffers toward Espressif's low-RAM rank. The IDF defaults
 # left too little heap for a TLS handshake next to a JS runtime on no-PSRAM
 # chips. STATIC_RX is a real ~1.6 KB/buffer allocation made at wifi init; the
@@ -109,6 +119,10 @@ CONFIG_VFS_SUPPORT_SELECT=n
 
 # --- Assertions & error strings ---
 CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT=y
+# Silent assert(): still aborts (with the PC address), but drops the
+# expression/file/line strings. The visible RAM win is spi_flash's
+# cache-off code, whose rodata must live in DRAM: ~3.3KB on C6.
+CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_SILENT=y
 # Keep esp_err_to_name() readable. Costs ~2 KB flash; without this, runtime
 # errors surface as "UNKNOWN ERROR" instead of e.g. ESP_ERR_NO_MEM, which
 # makes diagnosing on-device failures unnecessarily painful.