@mikrojs/native 0.19.0 → 0.20.0

package/CMakeLists.txt

@@ -61,6 +61,7 @@ set(MIKROJS_CORE_SOURCES
     src/mik_ota_js_hooks.cpp
     src/mik_ota_client.cpp
     src/mik_sys_codec.cpp
+    src/mik_watchdog.cpp
 )
 
 add_library(mikrojs STATIC
@@ -91,7 +92,7 @@ endif()
 include(cmake/mikrojs_bytecode.cmake)
 mikrojs_generate_bytecode(
     RUNTIME_DIR "${CMAKE_CURRENT_SOURCE_DIR}/runtime"
-    MODULES abort cbor env result schema fs i2c kv/nvs kv/rtc kv/shared module neopixel observable observable/lazy observable/operators ota ota/client ota/config pin pwm reader sleep spi sntp stdio stream sys test uart udp
+    MODULES abort cbor env result schema fs i2c kv/nvs kv/rtc kv/shared module neopixel observable observable/lazy observable/operators ota ota/client ota/config pin pwm reader sleep spi sntp stdio stream sys test uart udp watchdog
     MODULE_PREFIX "mikro"
     SYMBOL_PREFIX "mikro"
     TARGET gen_bytecode
@@ -222,6 +223,7 @@ if(BUILD_TESTING)
         test/ota_wire_fixtures_test.cpp
         test/schema_conformance_test.cpp
         test/sys_codec_test.cpp
+        test/watchdog_test.cpp
     )
 
     # ── Check-in wire fixtures ───────────────────────────────────────

package/include/mikrojs/mikrojs.h

@@ -54,8 +54,18 @@ typedef struct MIKConfig {
     char log_dir[64];
     uint32_t log_max_size;
     MIKLogFlush log_flush;
+    /* Watchdog budgets in ms, 0 = disabled. Mirror of the `watchdog` key in
+     * the host-side TS config. blocking: one event-loop turn holding the
+     * loop; feed: gap between watchdog.feed() calls; awake: time since boot. */
+    int blocking_timeout_ms;
+    int feed_timeout_ms;
+    int awake_timeout_ms;
 } MIKConfig;
 
+/* Shipped blocking default. The ESP32 side static_asserts this against the
+ * hardware TWDT timeout so the two cannot drift out of order. */
+#define MIK_WATCHDOG_BLOCKING_DEFAULT_MS 30000
+
 void MIK_DefaultConfig(MIKConfig* config);
 int MIK_LoadConfig(const char* base_path, MIKConfig* config);
 void MIK_SetConfig(MIKRuntime* mik_rt, const MIKConfig* config);
@@ -400,6 +410,17 @@ void MIK_ProtocolClose(void);
  * and must detach before freeing. */
 void MIK_ProtocolAttach(MIKRuntime* mik_rt);
 
+/* Record what `mik_rt` was handed at boot, reported on MSG_READY. Call once,
+ * from the boot path, at the point the app's entry is about to be evaluated:
+ * the figures then describe the floor an app starts from rather than whatever
+ * happens to be free when a client connects. Later calls are ignored, so a
+ * supervisor that swaps runtimes can't overwrite the boot reading with a
+ * per-test one. MIK_ProtocolAttach calls this itself, which covers embedders
+ * that never call it; a boot path with a test supervisor should call it
+ * explicitly, before the supervisor allocates, so both modes report the same
+ * figure. */
+void MIK_CaptureBootMemory(MIKRuntime* mik_rt);
+
 /* Unbind the current runtime. Call before MIK_FreeRuntime when swapping
  * runtimes mid-session. The session remains open. */
 void MIK_ProtocolDetach(void);

package/include/mikrojs/ota_policy.h

@@ -51,6 +51,18 @@ public:
 
 using MIKOtaDownloadFn = std::function<bool(MIKOtaUpdate& update, MIKOtaError* out_err)>;
 
+/* Why the last offered build was not taken, in wire-string form, held in the
+ * store until a completed check-in delivers it. Persisted rather than held in
+ * memory (unlike the built-in client's copy) because an own-transport decline
+ * happens after that wake's check-in, so it must survive a deep sleep to make
+ * the next report. Field caps match the registry's checkin validation, which
+ * rejects a body whose lastDecline oversteps them. */
+struct MIKOtaDeclineRecord {
+    char checksum[65] = {};
+    char reason[65] = {};
+    char detail[257] = {};
+};
+
 class MIKOtaStore {
 public:
     explicit MIKOtaStore(const MIKOtaEnv* env) : env_(env) {}
@@ -75,6 +87,11 @@ public:
     bool GetInFlight() const;
     void SetInFlight(bool in_flight);
 
+    /* False when no record stands. */
+    bool GetDecline(MIKOtaDeclineRecord* out) const;
+    void SetDecline(const MIKOtaDeclineRecord& record);
+    void ClearDecline();
+
 private:
     const MIKOtaEnv* env_;
 };

package/include/mikrojs/platform.h

@@ -19,6 +19,9 @@ typedef struct MIKPlatform {
      *  deep sleep (hosts), where callers fall back to restart(). */
     void (*deep_sleep_us)(uint64_t us);
     void (*yield)(void);
+    /** Feed the hardware task watchdog for the calling task. NULL where the
+     *  platform has none (hosts) or the watchdog is compiled out. */
+    void (*feed_watchdog)(void);
     size_t (*get_free_system_mem)(void);
     size_t (*get_min_free_system_mem)(void); /* All-time low watermark */
     size_t (*get_total_system_mem)(void);

package/include/mikrojs/private.h

@@ -80,6 +80,21 @@ struct MIKRuntime {
      * the host can still deploy/clean/--recover during the grace window,
      * then platform->restart() fires from MIK_Loop. */
     int64_t restart_at_us;
+    /* Watchdog state (mik_watchdog.cpp). All per-runtime, no atomics needed.
+     * blocking_start_us == 0 means "stamp on the next interrupt poll"; the
+     * handler switches itself off when it fires and back on at mik__blocking_begin. */
+    int64_t blocking_start_us;
+    bool blocking_armed;
+    /* Set when the limit is hit, consumed by the error dump that reports it. */
+    bool blocking_tripped;
+    /* Feed deadline: last feed()/re-stamp; feed_armed clears when it fires. */
+    int64_t feed_last_us;
+    bool feed_armed;
+    /* Awake budget: deploy-pause time credited against get_boot_us(). */
+    int64_t awake_pause_offset_us;
+    bool awake_armed;
+    /* Boot-clock stamp of the current pause; 0 = not paused. */
+    int64_t pause_start_us;
     const char* fs_base_path;
     const char* fs_root;  /* Sandbox root for mikrojs/fs operations (separate from module resolution) */
     size_t fs_limit;      /* Max bytes for fs_root (0 = unlimited) */
@@ -296,6 +311,31 @@ JSModuleDef* mik__udp_init(JSContext* ctx);
 JSModuleDef* mik__observable_init(JSContext* ctx);
 void mik__observable_dispatch_free(struct MIKRuntime* mik_rt);
 
+/* Watchdog (mik_watchdog.cpp). */
+/* Start a fresh blocking budget: top of each MIK_Loop pass, eval entry
+ * points, REPL eval, and on return from a deliberately blocking native
+ * (lightSleep). One store; the interrupt handler stamps on its next poll. */
+void mik__blocking_begin(struct MIKRuntime* mik_rt);
+/* JS_SetInterruptHandler callback; opaque is the MIKRuntime*. */
+int mik__watchdog_interrupt(JSRuntime* rt, void* opaque);
+/* If the blocking deadline was hit, log the watchdog line and clear the
+ * flag. Returns whether it did; callers print the error trace after. */
+bool mik__watchdog_report_blocking(struct MIKRuntime* mik_rt);
+/* Switch feed/awake on from mik_rt->config. Called once the config is set. */
+void mik__watchdog_arm(struct MIKRuntime* mik_rt);
+/* Feed and awake checks. Runs at the top of MIK_Loop after the restart_at_us
+ * branch; a feed miss throws an uncatchable error into mik_rt->ctx, on an
+ * awake overrun calls MIK_Stop directly. */
+void mik__watchdog_check(struct MIKRuntime* mik_rt);
+/* On return from lightSleep: fresh blocking budget and feed window. */
+void mik__watchdog_wake(struct MIKRuntime* mik_rt);
+/* Deploy/REPL pause bookkeeping: re-stamp the feed clock and credit the
+ * paused span to the awake budget. */
+void mik__watchdog_pause_begin(struct MIKRuntime* mik_rt);
+void mik__watchdog_pause_end(struct MIKRuntime* mik_rt);
+/* Registers native:mikro/watchdog (feed) on ctx. */
+void mik__watchdog_init(JSContext* ctx);
+
 bool mik__repl_is_evaluating(void);
 
 /* REPL protocol mode (mik_repl.cpp) — used by mik_console.cpp, mik_stdio.cpp */

package/include/mikrojs/utils.h

@@ -68,6 +68,11 @@ void mik_assert(const struct AssertionInfo info);
     }
 
 void mik_call_handler(JSContext* ctx, JSValue func, int argc, JSValue* argv);
+/* Print one always-visible error line the way console.error does: an error
+ * frame in protocol mode, stderr otherwise. platform->log is filtered per
+ * tag on the device and silent by default, so lines that precede a reboot
+ * (watchdog lines, panic actions) go through here instead. */
+void mik__print_error_line(const char* fmt, ...) __attribute__((format(printf, 1, 2)));
 void mik_dump_error(JSContext* ctx);
 void mik_dump_error1(JSContext* ctx, JSValue exception_val);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/native",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Mikro.js C++ runtime library and Node.js native addon",
   "keywords": [
     "esp32",
@@ -80,21 +80,22 @@
     "./runtime/test/types": "./runtime/test/types.ts",
     "./runtime/uart/types": "./runtime/uart/types.ts",
     "./runtime/udp/types": "./runtime/udp/types.ts",
+    "./runtime/watchdog/types": "./runtime/watchdog/types.ts",
     "./runtime/wifi/types": "./runtime/wifi/types.ts"
   },
   "dependencies": {
     "cmake-js": "^8.0.0",
     "node-addon-api": "^8.7.0",
     "node-gyp-build": "^4.8.4",
-    "@mikrojs/quickjs": "0.19.0"
+    "@mikrojs/quickjs": "0.20.0"
   },
   "devDependencies": {
     "@swc/core": "^1.15.30",
     "@types/node": "^24.12.2",
     "esbuild": "^0.28.0",
     "terser": "^5.46.2",
-    "@mikrojs/registry": "0.19.0",
-    "@mikrojs/schema": "0.19.0"
+    "@mikrojs/registry": "0.20.0",
+    "@mikrojs/schema": "0.20.0"
   },
   "engines": {
     "node": ">=24.0.0"

package/runtime/internal.d.ts

@@ -170,6 +170,10 @@ declare module 'native:mikro/pin' {
   export function analogReadMillivolts(pin: number, attenuation: number): Result<number, PinError>
 }
 
+declare module 'native:mikro/watchdog' {
+  export function feed(): void
+}
+
 declare module 'native:mikro/sleep' {
   import type {DeepWakeupSources, LightWakeupSources} from '@mikrojs/native/runtime/sleep/types'
 
@@ -580,12 +584,8 @@ declare module 'native:mikro/ota_client' {
 
   // The mikro/ota policy surface.
   export const reconcile: Ota['reconcile']
-  export const running: Ota['running']
-  export const parseOffer: Ota['parseOffer']
   export const applyOffer: Ota['applyOffer']
-  export const parseConfig: Ota['parseConfig']
-  export const applyConfig: Ota['applyConfig']
-  export const configState: Ota['configState']
+  export const decline: Ota['decline']
   export const report: Ota['report']
   export const settle: Ota['settle']
   export const confirm: Ota['confirm']

package/runtime/ota/ota.ts

@@ -8,18 +8,14 @@
 
 import {config} from 'mikro/ota/config'
 import {
-  applyConfig,
   applyOffer,
   bearer,
-  configState,
   confirm,
-  parseConfig,
-  parseOffer,
+  decline,
   reconcile,
   registry,
   report,
   revert,
-  running,
   settle,
 } from 'native:mikro/ota_client'
 
@@ -27,17 +23,13 @@ import type {Ota} from './types.js'
 
 const ota: Ota = {
   reconcile,
-  running,
-  parseOffer,
   applyOffer,
   confirm,
   revert,
   bearer,
   registry,
   config,
-  parseConfig,
-  applyConfig,
-  configState,
+  decline,
   report,
   settle,
 }

package/runtime/ota/types.ts

@@ -6,7 +6,8 @@ import type {Result} from '../result/types.js'
 /** An update offered by a registry: what to fetch and how to verify it, nothing
  *  more. Whether this device should take it is the registry's decision, made
  *  against the firmware and bytecode version the device reports at check-in and
- *  the whole set of builds it holds. Validate untrusted input with `parseOffer`. */
+ *  the whole set of builds it holds. `settle()` validates the untrusted
+ *  response fields into one. */
 export interface Offer {
   /** https URL of the .tgz build */
   url: string
@@ -117,24 +118,6 @@ export type ApplyOutcome =
  *  mismatch code, since it cannot tell a bad hash from bad bytes. */
 export type OtaError = OtaWriteError | OtaBeginError | OtaInstallError | OtaDownloadError
 
-/** One stored config document: the complete effective config computed and
- *  validated by the registry (or by the CLI at cable-seed time), the opaque
- *  token that identifies it, and the release version it was computed for.
- *  The device stores and returns it without understanding it: validation is
- *  the writer's job, and the registry already ships the code. */
-export interface StoredConfig {
-  /** Opaque registry-issued token echoed as `configRev` on check-ins. The
-   *  registry serves its document whenever the echo differs from its own
-   *  current rev, so a document it does not recognize is replaced. */
-  rev?: string
-  /** The release version this document was computed for. A document stamped
-   *  for another version is ignored by `ota.config()`. */
-  version: string
-  /** The served document: the deviation overlay the read resolves over the
-   *  build's manifest defaults. */
-  doc?: unknown
-}
-
 /** The three config slots, mirroring the build's install slots: `current` is
  *  what the running build reads, `next` is staged with an offered build,
  *  `prev` is the rollback baseline while a trial is unresolved. */
@@ -166,28 +149,13 @@ export type ConfigWrite =
    *  included), or it was a clear with nothing to clear. */
   | 'unchanged'
   /** Nothing was written, and the reason is transient: the store could not
-   *  answer, or the running version could not be read. Keep echoing the rev
-   *  from `configState()` so the document is served again, rather than the rev
-   *  of the document that did not land. */
+   *  answer, or the running version could not be read. The next `report()`
+   *  still echoes the held rev, so the document is served again, rather than
+   *  the rev of the document that did not land. */
   | 'failed'
-  /** Not a usable config document. Validate with `parseConfig` first to find
-   *  out before the delivery, and log what the wire actually carried. */
+  /** Not a usable config document; log what the wire actually carried. */
   | 'invalid'
 
-/** What a check-in body owes the registry about config, for a client that
- *  builds its own. */
-export interface ConfigState {
-  /** The rev to send as `configRev`: the registry serves its document whenever
-   *  this differs from its own current rev. Absent when the device holds no
-   *  document. After a rolled-back trial this is the FAILED document's rev,
-   *  which is what stops the registry serving it again. */
-  rev?: string
-  /** A document that failed its trial and was rolled back, reported until it
-   *  is replaced. Send it as `configError`, or an operator has no way to see
-   *  that the document they published took the device down. */
-  error?: ConfigErrorReport
-}
-
 /** A config document rolled back after a failed trial; reported on check-ins
  *  while it stands. `rev` names the failed document, and the client keeps
  *  echoing it as `configRev`, which is what stops the registry re-serving
@@ -197,6 +165,19 @@ export interface ConfigErrorReport {
   message: string
 }
 
+/** Why the last offered build was not taken. Without it a registry that waits
+ *  for `running.checksum` to turn into the offered checksum cannot tell a
+ *  device still working through a download from one that has permanently
+ *  stopped trying. */
+export interface DeclineReport {
+  /** The declined build, 64 lowercase hex characters. */
+  checksum: string
+  /** A module outcome ({@link DeclineReason}) or the app's own word for a
+   *  reason only it can see, at most 64 characters. */
+  reason: DeclineReason | (string & {})
+  detail?: string
+}
+
 /** The check-in body a device owes its registry, as `ota.report()` builds it.
  *  Field shapes match the wire, so a client (or the proxy behind it) can
  *  forward fields verbatim into `POST /api/v1/checkin`. */
@@ -217,10 +198,17 @@ export interface CheckinReport {
   /** Why a previous install failed. Present after a `reconcile()` that found
    *  one, until a `settle()` marks it delivered. */
   lastInstall?: Diagnostic
-  /** The held document's rev to echo; see {@link ConfigState.rev}. */
+  /** The held document's rev to echo: the registry serves its document
+   *  whenever this differs from its own current rev. After a rolled-back
+   *  trial this is the FAILED document's rev, which is what stops the
+   *  registry serving it again. */
   configRev?: string
-  /** A rolled-back document to report; see {@link ConfigState.error}. */
+  /** A rolled-back document to report; see {@link ConfigErrorReport}. */
   configError?: ConfigErrorReport
+  /** Why the last offered build was not taken. Present after `applyOffer`
+   *  declined one or the app recorded its own via `decline()`, until a
+   *  `settle()` marks it delivered. */
+  lastDecline?: DeclineReport
 }
 
 /** What `ota.settle()` took from a completed check-in's response. */
@@ -260,15 +248,14 @@ export type RegisteredConfig = keyof OtaConfig extends never ? unknown : OtaConf
 export interface Ota {
   /** Report what happened to a previous update on this boot, and clear the report. */
   reconcile(): InstallOutcome
-  /** The build currently executing, read from the live app. */
-  running(): RunningBuild
-  /** Validate a registry value into an `Offer`, or `undefined` if unusable.
-   *  `allowInsecure` (dev only) accepts an http build url instead of https. */
-  parseOffer(raw: unknown, opts?: {allowInsecure?: boolean}): Offer | undefined
   /** Run the full update policy: skip checks and the retry limit, download
    *  via the `download` callback, and verification. Compatibility is not
    *  re-checked: the registry selected this build for the reported firmware,
-   *  and a mismatched archive fails its checksum or fails to load. */
+   *  and a mismatched archive fails its checksum or fails to load.
+   *
+   *  An offer it does not stage is recorded for the registry the way
+   *  `decline()` records one, except `'current'` and `'trial-pending'`,
+   *  which are not declines. */
   applyOffer(
     offer: Offer,
     download: DownloadFn,
@@ -318,50 +305,29 @@ export interface Ota {
    */
   config<T = RegisteredConfig>(): T
   /**
-   * Validate a config document a client received over its own transport, or
-   * `undefined` when it cannot be used. What `parseOffer` is to an offer.
-   *
-   * A usable document is an object with a non-empty `version` (the release it
-   * was computed for, which decides where `applyConfig` puts it), an optional
-   * `rev` short enough to echo intact, and a `doc` that is an object or absent.
-   * An absent `doc` is the clear, not a malformed document.
-   *
-   * Whether the document survives CBOR is settled by `applyConfig`, which is
-   * where the stored bytes are made.
-   */
-  parseConfig(raw: unknown): StoredConfig | undefined
-  /**
-   * Store a config document, for a client that received one over its own
-   * transport. The built-in client covers the ordinary case and does not go
-   * through here.
-   *
-   * The `version` stamp decides where it lands: stamped for the running
-   * release it is applied, and the document it replaces is kept as the
-   * rollback baseline; stamped for another it is staged for the build it
-   * names, to apply when that build installs. The return value says which
-   * happened, and says when nothing did.
+   * Record why an offered build was not taken, for the next `report()` to
+   * carry as `lastDecline` and a later `settle()` to mark delivered — the
+   * same lifecycle as `lastInstall`. `applyOffer` records its own outcomes,
+   * so this is for a reason only the app can see: its own download budget
+   * spent, a build its policy refuses. Without a recorded decline the
+   * registry cannot tell a device still working through a download from one
+   * that has stopped, and shows the update pending forever.
    *
-   * A delivery to the running release arms a trial. Each boot whose first
-   * `config()` read serves the document burns one of `trialBoots`, and the
-   * budget spent with no `confirm()` in between restores the previous
-   * document. On a wake-cycle device every wake is a boot, so raise
-   * `trialBoots` above the default when a check-in can plausibly fail a few
-   * cycles in a row.
-   */
-  applyConfig(config: StoredConfig, options?: {trialBoots?: number}): ConfigWrite
-  /**
-   * What the device owes its registry about config: the rev to echo, and a
-   * rolled-back document to report. A client that builds its own check-in body
-   * needs both. Without the echo the registry re-serves the same document on
-   * every check-in; without the report a document that took the device down is
-   * re-served forever and nobody is told.
+   * Persisted on the device, so it survives a deep sleep: on a wake-cycle
+   * device the decline always lands after that wake's check-in, and the next
+   * wake's `report()` is its first chance to travel. Recording again
+   * overwrites; only the last decline stands. Throws a `TypeError` on a
+   * checksum that is not 64 lowercase hex characters or a `reason` past 64
+   * characters, since the registry would reject the whole check-in body;
+   * `detail` is free text and is cut to 256 characters instead.
    */
-  configState(): ConfigState
+  decline(checksum: string, reason: DeclineReason | (string & {}), detail?: string): void
   /**
    * The check-in body the device owes its registry, assembled: identity,
-   * `running()`, the name pair, free storage, the pending `lastInstall`
-   * report, and what `configState()` resolves. One call instead of gathering
-   * the fields by hand, and the same facts the built-in client sends.
+   * the running build, the name pair, free storage, the pending `lastInstall`
+   * report, a recorded `lastDecline`, and the config echo. One
+   * call instead of gathering the fields by hand, and the same facts the
+   * built-in client sends.
    *
    * Call `reconcile()` first, on every boot: it is what surfaces the
    * `lastInstall` report this reads (`settle()` marks it delivered).
@@ -370,9 +336,12 @@ export interface Ota {
   /**
    * Take a COMPLETED check-in's response, whole: confirm the running trial
    * and a read config document's trial (exactly `confirm()`), adopt a
-   * delivered name pair, store a delivered config document (exactly
-   * `applyConfig`, with `trialBoots`), and validate the offer fields (exactly
-   * `parseOffer(raw)`, with `allowInsecure`). An empty or null response is
+   * delivered name pair, store a delivered config document, and validate the
+   * offer fields (`allowInsecure`, dev only, accepts an http build url). A
+   * stored document arms a trial of `trialBoots` boots: each boot whose first
+   * `config()` read serves it burns one, and the budget spent with no
+   * `confirm()` in between restores the previous document, so raise it above
+   * the default on a wake-cycle device. An empty or null response is
    * the registry's quiet round: nothing to deliver, and the confirm still
    * happens, which is the point of calling. A response of any other shape
    * never decoded: a captive portal handed back HTML, or a proxy sent an