@mikrojs/native 0.19.0 → 0.20.0

package/runtime/test/test.ts

@@ -29,40 +29,62 @@ interface Suite {
 
 const suites: Suite[] = []
 let currentSuite: Suite | null = null
-let heapBaseline = 0
-/** Free system heap (bytes) at the baseline point, or 0 on the host (no
- *  system heap). Reference point for the "peak" figure: baseline free minus
- *  the run's low-water is the most the suite needed at once. Recaptured after
- *  each suite's beforeAll, in step with heapBaseline, so warmup is excluded
- *  from the figure. */
+/** JS heap (bytes) the file still holds above baseline, summed over suites.
+ *  Retention accumulates, so a per-suite figure is added rather than
+ *  replacing the last one: a leak in suite 1 is still a leak once suite 5
+ *  has run. */
+let heapRetained = 0
+/** Baseline the running suite is measured against. Set to the previous
+ *  suite's closing heap, or recaptured after a beforeAll so that suite's
+ *  warmup is excluded. */
+let suiteBaseline = 0
+/** Free system heap (bytes) at the start of the run, or 0 on the host (no
+ *  system heap). Never recaptured: sysUsed is a peak, and warmup (module
+ *  loads, TLS, wifi) is memory the file genuinely needed at once, so
+ *  excluding it would understate how close the run came to OOM. Retention is
+ *  the figure that wants warmup excluded, and it has its own baseline. */
 let sysFreeStart = 0
 /** Lowest free system heap (bytes) sampled (post-gc) this run, or 0 on the
- *  host. The suite's closest sampled approach to OOM. The module re-inits
+ *  host. The file's closest sampled approach to OOM. The module re-inits
  *  for each test file (fresh runtime per file), so this is a true per-file
  *  figure, not a process-lifetime watermark shared across files. */
 let sysFreeFloor = 0
+/** Free system heap at the running suite's start, for its own peak. */
+let suiteFreeStart = 0
+/** Lowest free system heap sampled during the running suite. */
+let suiteFreeFloor = 0
 
 /**
- * Recapture the heap baseline. Called by the harness after each suite's
+ * Recapture the suite baseline. Called by the harness after each suite's
  * beforeAll resolves so warmup allocations (module loads, fetch/TLS
  * lazy-init, wifi connection) don't count toward heapDelta. A microtask
  * yield before the gc lets the beforeAll async frame's locals become
  * collectible — otherwise the baseline would be inflated by vars that
  * were still pinned by the suspended closure when beforeAll resolved,
- * and heapAfter would come in lower than baseline (negative delta).
+ * and the suite would close below its baseline (negative delta).
  */
-async function captureHeapBaseline(): Promise<void> {
+async function captureSuiteBaseline(): Promise<void> {
   await Promise.resolve()
+  gc()
+  const {heapUsed} = memoryUsage()
+  suiteBaseline = heapUsed
+}
+
+/**
+ * Close out the running suite: fold its retention into the file total and
+ * start the next suite from where this one ended. Returns the suite's own
+ * figures for the suite_end event, which is what a reader needs to find the
+ * suite behind a file-level regression.
+ */
+function closeSuite(): {retained: number; sysUsed: number} {
   gc()
   const {heapUsed, systemFree} = memoryUsage()
-  heapBaseline = heapUsed
-  // Recapture the system-heap baseline and reset the per-file low-water in
-  // step with heapBaseline, so warmup (module loads, TLS, wifi) is excluded
-  // from sysUsed the same way it is from heapDelta.
-  if (systemFree > 0) {
-    sysFreeStart = systemFree
-    sysFreeFloor = systemFree
-  }
+  const retained = heapUsed - suiteBaseline
+  heapRetained += retained
+  suiteBaseline = heapUsed
+  if (systemFree > 0 && systemFree < suiteFreeFloor) suiteFreeFloor = systemFree
+  const sysUsed = suiteFreeStart > suiteFreeFloor ? suiteFreeStart - suiteFreeFloor : 0
+  return {retained, sysUsed}
 }
 
 function newSuite(name: string, flags: {skip?: boolean; only?: boolean; todo?: boolean}): Suite {
@@ -372,7 +394,7 @@ type TestEvent =
   | {e: 2; s: string; t: string; d: number}
   | {e: 3; s: string; t: string; d: number; m: string}
   | {e: 4; s: string; t: string}
-  | {e: 5; s: string}
+  | {e: 5; s: string; hr?: number; su?: number}
   | {
       e: 6
       p: number
@@ -382,6 +404,7 @@ type TestEvent =
       d: number
       hb?: number
       ha?: number
+      hr?: number
       su?: number
       sf?: number
       tb?: number
@@ -425,6 +448,7 @@ function emitHeap(): void {
   if (mem.systemFree > 0) {
     evt.f = mem.systemFree
     if (sysFreeFloor === 0 || mem.systemFree < sysFreeFloor) sysFreeFloor = mem.systemFree
+    if (suiteFreeFloor === 0 || mem.systemFree < suiteFreeFloor) suiteFreeFloor = mem.systemFree
   }
   if (mem.systemMinFree > 0) evt.mf = mem.systemMinFree
   emit(evt)
@@ -445,9 +469,10 @@ async function run(): Promise<void> {
   // folded into the baseline automatically.
   gc()
   // Destructure to primitives so the live memoryUsage() object isn't held
-  // while heapBaseline is captured (it would otherwise be counted in it).
+  // while the baseline is captured (it would otherwise be counted in it).
   const {heapUsed: startHeap, systemFree: startFree} = memoryUsage()
-  heapBaseline = startHeap
+  heapRetained = 0
+  suiteBaseline = startHeap
   if (startFree > 0) {
     sysFreeStart = startFree
     sysFreeFloor = startFree
@@ -459,7 +484,10 @@ async function run(): Promise<void> {
   const hasOnly = suites.some((s) => s.only || s.tests.some((t) => t.only))
 
   for (const suite of suites) {
+    // Open this suite's own peak window on the post-gc sample emitHeap takes.
+    suiteFreeFloor = 0
     emitHeap()
+    suiteFreeStart = suiteFreeFloor
     emit({e: 1, s: suite.name, n: suite.tests.length})
 
     if (suite.skip) {
@@ -527,11 +555,10 @@ async function run(): Promise<void> {
         continue
       }
       // Recapture the baseline now that beforeAll has fully resolved and
-      // its closure frame is eligible for collection. Multi-suite files
-      // let the last successful beforeAll set the baseline — fine because
-      // every earlier suite's test allocations have already been bounded
-      // by the previous (stricter) baseline.
-      await captureHeapBaseline()
+      // its closure frame is eligible for collection. Only this suite is
+      // measured against it: earlier suites were already closed out into
+      // heapRetained, so their allocations survive the recapture.
+      await captureSuiteBaseline()
     }
 
     for (const t of suite.tests) {
@@ -600,7 +627,10 @@ async function run(): Promise<void> {
       }
     }
 
-    emit({e: 5, s: suite.name})
+    const closed = closeSuite()
+    const endEvt: TestEvent = {e: 5, s: suite.name, hr: closed.retained}
+    if (closed.sysUsed > 0) endEvt.su = closed.sysUsed
+    emit(endEvt)
   }
 
   gc()
@@ -610,14 +640,20 @@ async function run(): Promise<void> {
   if (endFree > 0 && (sysFreeFloor === 0 || endFree < sysFreeFloor)) {
     sysFreeFloor = endFree
   }
+  // Fold in whatever ran outside a suite's own accounting: a file with no
+  // suites at all, and the skip/todo bookkeeping between them.
+  heapRetained += heapAfter - suiteBaseline
   const timersAfter = activeTimers()
   const pendingAfter = pendingHttpCount()
 
   // Per-file system-heap figures. sysFreeFloor is the lowest free heap we
   // sampled (post-gc) this run; sysUsed is how far free heap fell from the
-  // baseline to that low. They sum back to the baseline free, so "peak" and
-  // "min free" read as one story. Samples are taken between tests, so a
-  // transient peak inside a single test can dip below what sysFreeFloor saw.
+  // run's start to that low. They sum back to the starting free, so "peak"
+  // and "min free" read as one story. Measured from the start of the run and
+  // never rebaselined: unlike retention, a peak wants warmup counted, since
+  // memory a beforeAll takes is memory the file needed at once. Samples are
+  // taken between tests, so a transient peak inside a single test can dip
+  // below what sysFreeFloor saw.
   const sysUsed = sysFreeStart > sysFreeFloor ? sysFreeStart - sysFreeFloor : 0
 
   const doneEvt: TestEvent = {
@@ -627,8 +663,9 @@ async function run(): Promise<void> {
     k: skipped,
     o: todo,
     d: elapsedMs(startTime),
-    hb: heapBaseline,
+    hb: startHeap,
     ha: heapAfter,
+    hr: heapRetained,
     tb: timersBefore,
     ta: timersAfter,
     pb: pendingBefore,

package/runtime/watchdog/types.ts

@@ -0,0 +1,9 @@
+export interface Watchdog {
+  /** Report progress to the feed watchdog. Call it where real work completed,
+   *  not from a bare timer. A no-op when `watchdog.feed` is not configured. */
+  feed(): void
+}
+
+/** Progress reporting for the `feed` watchdog. The limits themselves are
+ *  set in `mikro.config.ts` under `watchdog`, not from code. */
+export declare const watchdog: Watchdog

package/runtime/watchdog/watchdog.ts

@@ -0,0 +1,7 @@
+import {feed} from 'native:mikro/watchdog'
+
+import type {Watchdog} from './types.js'
+
+export type {Watchdog} from './types.js'
+
+export const watchdog: Watchdog = {feed}

package/src/eval_bytecode.cpp

@@ -19,6 +19,7 @@ int mik__eval_bytecode(JSContext* ctx, const uint8_t* buf, size_t buf_len, bool
         }
     }
 
+    mik__blocking_begin(MIK_GetRuntime(ctx));
     JSValue val = JS_EvalFunction(ctx, obj);
     if (JS_IsException(val)) {
         mik_dump_error(ctx);

package/src/mik_app_config.cpp

@@ -1,5 +1,6 @@
 #include "mikrojs/mikrojs.h"
 
+#include <climits>
 #include <cstdio>
 #include <cstdlib>
 #include <cstring>
@@ -24,6 +25,9 @@ void MIK_DefaultConfig(MIKConfig* config) {
     config->log_dir[0] = '\0';
     config->log_max_size = 64 * 1024;
     config->log_flush = MIK_LOG_FLUSH_ERROR;
+    config->blocking_timeout_ms = MIK_WATCHDOG_BLOCKING_DEFAULT_MS;
+    config->feed_timeout_ms = 0;
+    config->awake_timeout_ms = 0;
 }
 
 /* Minimal JSON parser for config file — avoids cJSON dependency.
@@ -60,6 +64,34 @@ static bool mik__json_get_number(const char* json, const char* key, double* out)
     return true;
 }
 
+static bool mik__json_is_false(const char* json, const char* key) {
+    char pattern[128];
+    snprintf(pattern, sizeof(pattern), "\"%s\"", key);
+    const char* p = strstr(json, pattern);
+    if (!p) return false;
+    p += strlen(pattern);
+    while (*p == ' ' || *p == '\t' || *p == ':') p++;
+    return strncmp(p, "false", 5) == 0;
+}
+
+/* Watchdog budget in ms. `false` and 0 disable; other values below 1 s
+ * clamp up with a warning, since a smaller budget fires on ordinary work. */
+static int mik__json_get_watchdog_ms(const MIKPlatform* platform, const char* json,
+                                     const char* key, int current) {
+    if (mik__json_is_false(json, key)) return 0;
+    double num_val;
+    if (!mik__json_get_number(json, key, &num_val)) return current;
+    if (num_val == 0) return 0;
+    if (num_val < 1000) {
+        platform->log(MIK_LOG_WARN, TAG, "%s below 1000 ms (%ld); clamping to 1000", key,
+                      (long)num_val);
+        return 1000;
+    }
+    /* Past INT_MAX the cast would wrap negative and silently disable it. */
+    if (num_val > INT_MAX) return INT_MAX;
+    return (int)num_val;
+}
+
 /* Read a JSON file into a malloc'd buffer. Caller must free(). Returns NULL on failure. */
 static char* mik__read_json_file(const char* filepath, struct stat* st) {
     if (stat(filepath, st) != 0) return nullptr;
@@ -333,6 +365,12 @@ int MIK_LoadConfig(const char* base_path, MIKConfig* config) {
             if (mik__json_get_number(buf, "onPanic.duration", &num_val)) {
                 config->panic_sleep_duration_ms = (int)num_val;
             }
+            config->blocking_timeout_ms = mik__json_get_watchdog_ms(
+                platform, buf, "watchdog.blocking", config->blocking_timeout_ms);
+            config->feed_timeout_ms = mik__json_get_watchdog_ms(platform, buf, "watchdog.feed",
+                                                                config->feed_timeout_ms);
+            config->awake_timeout_ms = mik__json_get_watchdog_ms(
+                platform, buf, "watchdog.awake", config->awake_timeout_ms);
             if (mik__json_get_number(buf, "stackSize", &num_val)) {
                 config->stack_size = (size_t)num_val;
             }

package/src/mik_console.cpp

@@ -263,6 +263,11 @@ bool mik__report_uncaught(JSContext* ctx, JSValue exc, bool in_promise) {
         }
     }
 
+    /* A blocking-watchdog timeout reaches here either through mik_dump_error
+     * (which already reported it; this is then a no-op) or as an unhandled
+     * rejection when the interrupted turn was a module evaluation. */
+    mik__watchdog_report_blocking(MIK_GetRuntime(ctx));
+
     /* Fixed-size stack buffer so this function never allocates from the
      * C++ heap. Previously we used std::string + mik_inspect here; both
      * can throw std::bad_alloc under memory pressure, and with

package/src/mik_ota_policy.cpp

@@ -116,6 +116,40 @@ void MIKOtaStore::SetInFlight(bool in_flight) {
     env_->kv_set_i32(env_->opaque, "ota.inflight", in_flight ? 1 : 0);
 }
 
+bool MIKOtaStore::GetDecline(MIKOtaDeclineRecord* out) const {
+    if (!env_ || !env_->kv_get_str) return false;
+    if (!env_->kv_get_str(env_->opaque, "ota.declined", out->checksum, sizeof(out->checksum)) ||
+        out->checksum[0] == '\0') {
+        return false;
+    }
+    if (!env_->kv_get_str(env_->opaque, "ota.declReason", out->reason, sizeof(out->reason)) ||
+        out->reason[0] == '\0') {
+        return false;
+    }
+    if (!env_->kv_get_str(env_->opaque, "ota.declDetail", out->detail, sizeof(out->detail))) {
+        out->detail[0] = '\0';
+    }
+    return true;
+}
+
+void MIKOtaStore::SetDecline(const MIKOtaDeclineRecord& record) {
+    if (!env_ || !env_->kv_set_str) return;
+    env_->kv_set_str(env_->opaque, "ota.declined", record.checksum);
+    env_->kv_set_str(env_->opaque, "ota.declReason", record.reason);
+    if (record.detail[0]) {
+        env_->kv_set_str(env_->opaque, "ota.declDetail", record.detail);
+    } else if (env_->kv_remove) {
+        env_->kv_remove(env_->opaque, "ota.declDetail");
+    }
+}
+
+void MIKOtaStore::ClearDecline() {
+    if (!env_ || !env_->kv_remove) return;
+    env_->kv_remove(env_->opaque, "ota.declined");
+    env_->kv_remove(env_->opaque, "ota.declReason");
+    env_->kv_remove(env_->opaque, "ota.declDetail");
+}
+
 // ── Offer parsing ────────────────────────────────────────────────────────────
 
 bool mik__ota_parse_offer(const char* url, const char* checksum, int64_t size, bool allow_insecure,

package/src/mik_repl.cpp

@@ -39,10 +39,11 @@ static MIKReplTransport* repl_transport = nullptr;
 static uint8_t ready_buf[384];
 static size_t ready_len = 0;
 
-/* Memory left for the app, captured once when the first runtime attaches: that
- * happens before the entry is evaluated, so these describe the floor the app is
- * handed rather than whatever is left whenever a client happens to connect.
- * Reported on MSG_READY so `mikro profile` is a read, not a deploy. */
+/* Memory left for the app, captured once from the boot path (see
+ * MIK_CaptureBootMemory) before the entry is evaluated, so these describe the
+ * floor the app is handed rather than whatever is left whenever a client
+ * happens to connect. Reported on MSG_READY so reading them is a read, not a
+ * deploy. */
 static bool boot_mem_captured = false;
 static uint32_t boot_heap_free = 0;
 static uint32_t boot_system_free = 0;
@@ -119,8 +120,8 @@ void mik__repl_proto_send_output(uint8_t msg_type, const void* data, size_t len)
  * Returns false on transport EOF/error, when MIK_ProtocolExit() is
  * signalled from inside the pump (the supervisor's mechanism for ending
  * a test-file's serve loop after __testFileDone fires), or when MIK_Loop
- * reports the attached runtime has halted (e.g. an unhandled rejection
- * set stop_requested — a test that crashed mid-execution). */
+ * reports the attached runtime has halted without a panic grace window
+ * (e.g. an unhandled rejection in a test that crashed mid-execution). */
 bool mik__proto_read_exact(MIKReplTransport* transport, void* buf, size_t n) {
     const MIKPlatform* platform = MIK_GetPlatform();
     uint8_t* p = static_cast<uint8_t*>(buf);
@@ -133,11 +134,10 @@ bool mik__proto_read_exact(MIKReplTransport* transport, void* buf, size_t n) {
             return false;
         } else {
             if (repl_mik_rt && !repl_paused) {
-                if (MIK_Loop(repl_mik_rt) != 0) {
-                    /* Runtime halted (typically unhandled rejection sets
-                     * stop_requested). Further pumping is a no-op, so
-                     * exit the serve loop and let the caller swap in the
-                     * next runtime — or restart, in non-supervisor mode. */
+                /* A panic arms restart_at_us and MIK_Loop takes the action
+                 * itself at the deadline, so keep serving (--recover). Only
+                 * a plain stop (test supervisor) ends the serve loop. */
+                if (MIK_Loop(repl_mik_rt) != 0 && repl_mik_rt->restart_at_us == 0) {
                     s_exit_serve_loop = true;
                     return false;
                 }
@@ -611,6 +611,7 @@ static bool handle_directive_impl(JSContext* ctx, const char* line, std::string&
             out.append("App is already paused\n");
         } else {
             repl_paused = true;
+            mik__watchdog_pause_begin(repl_mik_rt);
             out.append("App paused (timers, callbacks suspended). Use /resume to continue.\n");
         }
         return true;
@@ -621,6 +622,7 @@ static bool handle_directive_impl(JSContext* ctx, const char* line, std::string&
             out.append("App is not paused\n");
         } else {
             repl_paused = false;
+            mik__watchdog_pause_end(repl_mik_rt);
             out.append("App resumed\n");
         }
         return true;
@@ -852,6 +854,13 @@ bool mik__repl_is_paused(void) {
 }
 
 void mik__repl_set_paused(bool paused) {
+    if (paused != repl_paused) {
+        if (paused) {
+            mik__watchdog_pause_begin(repl_mik_rt);
+        } else {
+            mik__watchdog_pause_end(repl_mik_rt);
+        }
+    }
     repl_paused = paused;
 }
 
@@ -1003,23 +1012,26 @@ void MIK_ProtocolOpen(MIKReplTransport* transport) {
 
 }
 
+void MIK_CaptureBootMemory(MIKRuntime* mik_rt) {
+    if (!mik_rt || boot_mem_captured) return;
+    JSMemoryUsage mem;
+    JS_ComputeMemoryUsage(JS_GetRuntime(MIK_GetJSContext(mik_rt)), &mem);
+    boot_heap_free = mem.malloc_limit > (int64_t)mem.malloc_size
+                         ? (uint32_t)(mem.malloc_limit - (int64_t)mem.malloc_size)
+                         : 0;
+    boot_system_free = (uint32_t)MIK_GetPlatform()->get_free_system_mem();
+    boot_mem_reserved = mik_rt->config.mem_reserved;
+    boot_mem_captured = true;
+}
+
 void MIK_ProtocolAttach(MIKRuntime* mik_rt) {
     if (!mik_rt) return;
     repl_ctx = MIK_GetJSContext(mik_rt);
     repl_mik_rt = mik_rt;
-    /* First attach only. In test mode a fresh runtime attaches per file, and
-     * those would otherwise overwrite the boot floor with per-test figures. */
-    if (!boot_mem_captured) {
-        JSMemoryUsage mem;
-        JS_ComputeMemoryUsage(JS_GetRuntime(repl_ctx), &mem);
-        boot_heap_free =
-            mem.malloc_limit > (int64_t)mem.malloc_size
-                ? (uint32_t)(mem.malloc_limit - (int64_t)mem.malloc_size)
-                : 0;
-        boot_system_free = (uint32_t)MIK_GetPlatform()->get_free_system_mem();
-        boot_mem_reserved = mik_rt->config.mem_reserved;
-        boot_mem_captured = true;
-    }
+    /* Fallback for boot paths that don't capture explicitly. First attach
+     * only: in test mode a fresh runtime attaches per file, and those would
+     * otherwise overwrite the boot floor with per-test figures. */
+    MIK_CaptureBootMemory(mik_rt);
 }
 
 void MIK_ProtocolDetach(void) {
@@ -1035,6 +1047,9 @@ void MIK_ProtocolClose(void) {
     }
     repl_active = false;
     repl_protocol_mode = false;
+    if (repl_paused) {
+        mik__watchdog_pause_end(repl_mik_rt);
+    }
     repl_paused = false;
     repl_transport = nullptr;
     repl_ctx = nullptr;
@@ -1082,6 +1097,7 @@ void MIK_ProtocolServeLoop(void) {
 
                 repl_evaluating = true;
                 repl_async_skipped = false;
+                mik__blocking_begin(repl_mik_rt);
                 JSValue result = repl_eval_and_pump(ctx, code.c_str(), code.size());
                 repl_evaluating = false;
 
@@ -1094,6 +1110,10 @@ void MIK_ProtocolServeLoop(void) {
                 if (JS_IsException(result)) {
                     JSValue exc = JS_GetException(ctx);
 
+                    /* A synchronous throw never reaches mik_dump_error, so
+                     * consume the blocking-timeout flag here. */
+                    mik__watchdog_report_blocking(repl_mik_rt);
+
                     /* Format the error */
                     std::string msg = "Uncaught ";
                     if (JS_IsObject(exc)) {

package/src/mik_watchdog.cpp

@@ -0,0 +1,170 @@
+#include <quickjs.h>
+
+#include "mikrojs/mikrojs.h"
+#include "mikrojs/platform.h"
+#include "mikrojs/private.h"
+#include "mikrojs/utils.h"
+
+/* ── Watchdog: blocking deadline, feed deadline, awake budget ─────────
+ *
+ * All three measure wall time via get_boot_us(). The blocking deadline is
+ * polled from the QuickJS interrupt handler (every 10k branches/calls);
+ * feed and awake are checked once per MIK_Loop pass. State is per-runtime,
+ * so the Node addon's parallel runtimes need no atomics. */
+
+
+void mik__blocking_begin(MIKRuntime* mik_rt) {
+    if (!mik_rt) return;
+    mik_rt->blocking_start_us = 0;
+    mik_rt->blocking_armed = true;
+}
+
+int mik__watchdog_interrupt(JSRuntime* rt, void* opaque) {
+    (void)rt;
+    MIKRuntime* mik_rt = static_cast<MIKRuntime*>(opaque);
+    int budget_ms = mik_rt->config.blocking_timeout_ms;
+    if (budget_ms <= 0 || !mik_rt->blocking_armed) {
+        return 0;
+    }
+    int64_t now = MIK_GetPlatform()->get_boot_us();
+    int64_t start = mik_rt->blocking_start_us;
+    /* now < start: the boot clock reset (deep sleep, test platform swap). */
+    if (start == 0 || now < start) {
+        mik_rt->blocking_start_us = now;
+        return 0;
+    }
+    if (now - start >= (int64_t)budget_ms * 1000) {
+        /* One-shot: stay off while the error unwinds so finally blocks
+         * and error-handler property reads are not interrupted too. */
+        mik_rt->blocking_armed = false;
+        mik_rt->blocking_tripped = true;
+        /* The app could not feed while it was blocked; give it a fresh
+         * window so a surviving session (REPL eval) is not hit twice. */
+        mik_rt->feed_last_us = now;
+        return 1;
+    }
+    return 0;
+}
+
+bool mik__watchdog_report_blocking(MIKRuntime* mik_rt) {
+    if (!mik_rt || !mik_rt->blocking_tripped) {
+        return false;
+    }
+    mik_rt->blocking_tripped = false;
+    mik__print_error_line("[watchdog] WATCHDOG TRIGGERED: event loop blocking time exceeded "
+                          "configured limit of %d ms",
+                          mik_rt->config.blocking_timeout_ms);
+    return true;
+}
+
+void mik__watchdog_arm(MIKRuntime* mik_rt) {
+    const MIKPlatform* platform = MIK_GetPlatform();
+    const MIKConfig* cfg = &mik_rt->config;
+    mik__blocking_begin(mik_rt);
+    mik_rt->feed_armed = cfg->feed_timeout_ms > 0;
+    mik_rt->feed_last_us = platform->get_boot_us();
+    mik_rt->awake_armed = cfg->awake_timeout_ms > 0;
+    mik_rt->awake_pause_offset_us = 0;
+    mik_rt->pause_start_us = 0;
+    if (mik_rt->awake_armed && cfg->panic_mode != MIK_PANIC_DEEP_SLEEP) {
+        /* Always visible: platform->log is silent on device by default. */
+        mik__print_error_line("[watchdog] awake limit of %d ms without onPanic.mode 'deepSleep': "
+                              "the device restarts every %d ms",
+                              cfg->awake_timeout_ms, cfg->awake_timeout_ms);
+    }
+}
+
+void mik__watchdog_check(MIKRuntime* mik_rt) {
+    if (mik_rt->stop_requested || (!mik_rt->feed_armed && !mik_rt->awake_armed)) {
+        return;
+    }
+    /* A pending exception (a blocking timeout, or any uncaught throw from the
+     * entry) is about to be reported and stop the runtime. Firing feed or
+     * awake on top of it would replace that exception and lose its trace. */
+    if (JS_HasException(mik_rt->ctx)) {
+        return;
+    }
+    const MIKPlatform* platform = MIK_GetPlatform();
+    int64_t now = platform->get_boot_us();
+
+    if (mik_rt->awake_armed) {
+        int64_t elapsed_us = now - mik_rt->awake_pause_offset_us;
+        if (elapsed_us >= (int64_t)mik_rt->config.awake_timeout_ms * 1000) {
+            mik_rt->awake_armed = false;
+            mik__print_error_line("[watchdog] WATCHDOG TRIGGERED: awake time exceeded configured "
+                                  "limit of %d ms",
+                                  mik_rt->config.awake_timeout_ms);
+            /* No JS error: nothing to point a trace at, and this must not
+             * reach the OTA trial error handler (a slow link is not a bug). */
+            MIK_Stop(mik_rt);
+            return;
+        }
+    }
+
+    if (mik_rt->feed_armed) {
+        if (now < mik_rt->feed_last_us) {
+            mik_rt->feed_last_us = now;
+        } else if (now - mik_rt->feed_last_us >= (int64_t)mik_rt->config.feed_timeout_ms * 1000) {
+            mik_rt->feed_armed = false;
+            mik__print_error_line("[watchdog] WATCHDOG TRIGGERED: time since last feed() exceeded "
+                                  "configured limit of %d ms",
+                                  mik_rt->config.feed_timeout_ms);
+            /* No JS frame is active here, so uncatchable marking is moot: the
+             * JS_HasException branch in MIK_Loop routes this before any user
+             * code runs. */
+            JS_ThrowInternalError(mik_rt->ctx,
+                                  "watchdog: time since last feed() exceeded configured limit "
+                                  "of %d ms",
+                                  mik_rt->config.feed_timeout_ms);
+        }
+    }
+}
+
+void mik__watchdog_wake(MIKRuntime* mik_rt) {
+    if (!mik_rt) return;
+    mik__blocking_begin(mik_rt);
+    /* The app could not feed while asleep; it gets a fresh window, as after
+     * a pause. The awake clock keeps counting: light sleep is still uptime. */
+    mik_rt->feed_last_us = MIK_GetPlatform()->get_boot_us();
+}
+
+void mik__watchdog_pause_begin(MIKRuntime* mik_rt) {
+    if (!mik_rt || mik_rt->pause_start_us != 0) return;
+    mik_rt->pause_start_us = MIK_GetPlatform()->get_boot_us();
+}
+
+void mik__watchdog_pause_end(MIKRuntime* mik_rt) {
+    if (!mik_rt || mik_rt->pause_start_us == 0) return;
+    int64_t now = MIK_GetPlatform()->get_boot_us();
+    if (now > mik_rt->pause_start_us) {
+        mik_rt->awake_pause_offset_us += now - mik_rt->pause_start_us;
+    }
+    mik_rt->pause_start_us = 0;
+    /* The app could not feed while suspended; it gets a fresh budget. */
+    mik_rt->feed_last_us = now;
+}
+
+/* ── native:mikro/watchdog ──────────────────────────────────────────── */
+
+static JSValue mik__watchdog_feed(JSContext* ctx, JSValueConst this_val, int argc,
+                                  JSValueConst* argv) {
+    (void)this_val;
+    (void)argc;
+    (void)argv;
+    MIKRuntime* mik_rt = MIK_GetRuntime(ctx);
+    if (mik_rt && mik_rt->feed_armed) {
+        mik_rt->feed_last_us = MIK_GetPlatform()->get_boot_us();
+    }
+    return JS_UNDEFINED;
+}
+
+static int mik__watchdog_module_init(JSContext* ctx, JSModuleDef* m) {
+    JS_SetModuleExport(ctx, m, "feed", JS_NewCFunction(ctx, mik__watchdog_feed, "feed", 0));
+    return 0;
+}
+
+void mik__watchdog_init(JSContext* ctx) {
+    JSModuleDef* m = JS_NewCModule(ctx, "native:mikro/watchdog", mik__watchdog_module_init);
+    if (!m) return;
+    JS_AddModuleExport(ctx, m, "feed");
+}