@mikrojs/native 0.18.0 → 0.18.1

package/include/mikrojs/ota_js_hooks.h

@@ -0,0 +1,71 @@
+#pragma once
+
+/**
+ * The `beforeCheck` hook, bridged from JS into the round machine.
+ *
+ * This is the one place the client re-enters JavaScript, and everything it
+ * touches comes back from app code — so it lives here, in the portable library,
+ * rather than in the firmware module. Nothing in it needs ESP-IDF, and every
+ * bug it has had so far was a marshalling bug that only a device could show.
+ */
+
+#include <quickjs.h>
+
+#include <cstdint>
+#include <string>
+
+#include "mikrojs/ota_client.h"
+
+namespace mikrojs {
+
+/**
+ * What a hook may hand back, and what each shape means:
+ *
+ *   a function            the round runs, and this runs after it
+ *   nothing               the round runs, with no teardown
+ *   an `err` Result       the round is skipped and retried sooner
+ *   an `ok` Result        as its value: a teardown function, or nothing
+ *   a thrown exception    the round is skipped and retried sooner
+ *
+ * Anything else is taken as success with no teardown. A promise of any of the
+ * above is awaited first.
+ *
+ * The bare-function form exists because wrapping every teardown in `ok()` is
+ * ceremony on the path that always succeeds, while the Result form is what lets
+ * a failing setup hand its own error straight back.
+ */
+class MIKOtaJsHooks : public MIKOtaRoundHooks {
+public:
+    /* Takes ownership of `before_check`, which may be undefined (no hook). */
+    MIKOtaJsHooks(JSContext* ctx, JSValue before_check);
+    ~MIKOtaJsHooks() override;
+    MIKOtaJsHooks(const MIKOtaJsHooks&) = delete;
+    MIKOtaJsHooks& operator=(const MIKOtaJsHooks&) = delete;
+
+    bool BeginBeforeCheck() override;
+    MIKOtaHookState PollBeforeCheck() override;
+    bool BeginTeardown() override;
+    MIKOtaHookState PollTeardown() override;
+
+    /* True once beforeCheck has handed back a teardown to run. */
+    bool has_teardown() const;
+
+private:
+    void Call(JSValue fn);
+    /* Interpret a settled value from app code. */
+    void Settle(JSValue value);
+    static JSValue OnFulfilled(JSContext* ctx, JSValueConst this_val, int argc, JSValueConst* argv,
+                               int magic, JSValue* func_data);
+
+    JSContext* ctx_;
+    JSValue before_check_;
+    JSValue teardown_ = JS_UNDEFINED;
+    MIKOtaHookState state_ = MIKOtaHookState::kOk;
+    bool awaiting_before_check_ = false;
+    /* Identifies this instance to a promise callback that outlives it. Never
+     * reused, so a continuation from a destroyed hooks object cannot land on
+     * whatever was allocated at the same address afterwards. */
+    uint64_t id_;
+};
+
+}  // namespace mikrojs

package/include/mikrojs/ota_policy.h

@@ -0,0 +1,131 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <string>
+
+#include "mikrojs/ota_env.h"
+
+namespace mikrojs {
+
+struct MIKOtaOffer {
+    std::string url;
+    std::string checksum;
+    size_t size = 0;
+};
+
+struct MIKOtaInstallOptions {
+    int trial_boots = 1;
+    bool require_confirm = false;
+    bool install_now = false;
+};
+
+enum class MIKOtaApplyOutcome {
+    kStaged,
+    kTrialPending,
+    kCurrent,
+    kAbandoned,
+    kExhausted,
+};
+
+const char* mik__ota_outcome_to_str(MIKOtaApplyOutcome outcome);
+
+struct MIKOtaError {
+    // One of "StagingFailed", "TooLarge", "StagingFull", "DownloadFailed",
+    // "InstallFailed".
+    std::string name;
+    std::string kind;    // "corrupt", "transient", "oom" (for InstallFailed)
+    std::string message;
+};
+
+class MIKOtaUpdate {
+public:
+    virtual ~MIKOtaUpdate() = default;
+    virtual size_t resume_offset() const = 0;
+    virtual bool write(const uint8_t* bytes, size_t len, MIKOtaError* out_err) = 0;
+    virtual bool finish(const MIKOtaInstallOptions& options, MIKOtaError* out_err) = 0;
+    virtual void abort() = 0;
+};
+
+using MIKOtaDownloadFn = std::function<bool(MIKOtaUpdate& update, MIKOtaError* out_err)>;
+
+class MIKOtaStore {
+public:
+    explicit MIKOtaStore(const MIKOtaEnv* env) : env_(env) {}
+
+    /* The offer url is stored as a digest, not verbatim: a presigned url can run
+     * to several hundred bytes, past both the read buffer here and what the
+     * device's kv can hold, and a url that fails to round-trip never compares
+     * equal — which reset the retry budget on every round and let a build that
+     * cannot install retry forever. */
+    bool UrlMatches(const std::string& url) const;
+    void SetUrl(const std::string& url);
+
+    std::string GetAttempt() const;
+    void SetAttempt(const std::string& checksum);
+
+    int32_t GetTries() const;
+    void SetTries(int32_t n);
+
+    std::string GetBad() const;
+    void SetBad(const std::string& checksum);
+
+    bool GetInFlight() const;
+    void SetInFlight(bool in_flight);
+
+private:
+    const MIKOtaEnv* env_;
+};
+
+/* Validate untrusted offer fields into a well-formed MIKOtaOffer */
+bool mik__ota_parse_offer(const char* url, const char* checksum, int64_t size, bool allow_insecure,
+                         MIKOtaOffer* out_offer, std::string* out_warn_reason);
+
+/* Reconcile on-boot outcome and manage retry budget */
+MIKOtaReconcileOutcome mik__ota_policy_reconcile(const MIKOtaEnv* env);
+
+/* Query currently running build information */
+MIKOtaRunningBuild mik__ota_policy_running(const MIKOtaEnv* env);
+
+/* Revert current trial to last good build */
+bool mik__ota_policy_revert(const MIKOtaEnv* env, MIKOtaError* out_err);
+
+/* Confirm currently running build */
+void mik__ota_policy_confirm(const MIKOtaEnv* env);
+
+/* Apply an update offer according to the safety and retry policies. The
+ * download runs to completion inside the call; callers whose transport is
+ * asynchronous use the split form below instead. */
+bool mik__ota_policy_apply_offer(const MIKOtaEnv* env, const MIKOtaOffer& offer,
+                                 MIKOtaDownloadFn download, const MIKOtaInstallOptions& options,
+                                 MIKOtaApplyOutcome* out_outcome, MIKOtaError* out_err);
+
+/* One apply attempt, held open across an asynchronous download. `update` is
+ * null when the policy declined the offer before any staging began. */
+struct MIKOtaApplySession {
+    const MIKOtaEnv* env = nullptr;
+    std::string checksum;
+    std::unique_ptr<MIKOtaUpdate> update;
+};
+
+/* Run the pre-download gates and, if the offer survives them, open the staging
+ * session. Returns false with `out_err` set only for StagingFailed; a declined
+ * offer returns true with `out_outcome` set and `session->update` left null.
+ *
+ * A session with an open `update` MUST be closed with mik__ota_policy_apply_end,
+ * or the in-flight flag stays set and the attempt is counted as one that took
+ * the device down — which is exactly what should happen if the caller dies. */
+bool mik__ota_policy_apply_begin(const MIKOtaEnv* env, const MIKOtaOffer& offer,
+                                 MIKOtaApplySession* session, MIKOtaApplyOutcome* out_outcome,
+                                 MIKOtaError* out_err);
+
+/* Close an attempt opened by mik__ota_policy_apply_begin. `download_message` is
+ * used only when `download_ok` is false, as the DownloadFailed message. */
+bool mik__ota_policy_apply_end(MIKOtaApplySession* session, bool download_ok,
+                               const std::string& download_message,
+                               const MIKOtaInstallOptions& options,
+                               MIKOtaApplyOutcome* out_outcome, MIKOtaError* out_err);
+
+}  // namespace mikrojs

package/include/mikrojs/ota_slots.h

@@ -0,0 +1,47 @@
+#pragma once
+
+/**
+ * The config sync slots, as the device persists them.
+ *
+ * Three slots mirror the build's install slots: `current` is what the running
+ * build reads, `next` is staged alongside an offered build, `prev` is the
+ * rollback baseline while a delivery is unresolved. Shared by the check-in
+ * client and the `ota.config()` reader so the two agree on keys and shapes.
+ */
+
+#include <cstdint>
+#include <vector>
+
+#include "mikrojs/ota_env.h"
+
+namespace mikrojs {
+
+/* A stored config, plus the buffer its `doc` span points into. */
+struct MIKOtaLoadedConfig {
+    MIKOtaStoredConfig cfg = {};
+    std::vector<uint8_t> bytes;
+    /* A well-formed document was read. */
+    bool present = false;
+    /* The store could not answer. `present` is false but says nothing: callers
+     * that must not mistake a starved read for a clear check this first. */
+    bool failed = false;
+};
+
+MIKOtaLoadedConfig mik__ota_load_slot(const MIKOtaEnv* env, MIKOtaConfigSlot slot);
+void mik__ota_store_slot(const MIKOtaEnv* env, MIKOtaConfigSlot slot,
+                         const MIKOtaStoredConfig& cfg);
+void mik__ota_clear_slot(const MIKOtaEnv* env, MIKOtaConfigSlot slot);
+
+/* The running-release delivery trial; absent = no trial in progress. A
+ * malformed value reads as absent, but an unreadable store reads as ERROR: the
+ * config reader must not burn a trial boot on a read it never got. */
+MIKOtaKvStatus mik__ota_load_trial(const MIKOtaEnv* env, MIKOtaConfigTrial* out);
+void mik__ota_store_trial(const MIKOtaEnv* env, const MIKOtaConfigTrial& trial);
+void mik__ota_clear_trial(const MIKOtaEnv* env);
+
+/* The rolled-back document's rev and why, reported until replaced. */
+bool mik__ota_load_config_error(const MIKOtaEnv* env, MIKOtaConfigErrorReport* out);
+void mik__ota_store_config_error(const MIKOtaEnv* env, const MIKOtaConfigErrorReport& report);
+void mik__ota_clear_config_error(const MIKOtaEnv* env);
+
+}  // namespace mikrojs

package/include/mikrojs/sys_codec.h

@@ -0,0 +1,61 @@
+#pragma once
+
+/**
+ * Encodings for the runtime's persisted state, shared by its native and JS
+ * readers.
+ *
+ * native:mikro/nvs_kv stores each value as the CBOR encoding of the value
+ * itself, so `sysSet('ota.tries', 2)` writes a CBOR integer and
+ * `sysSet('ota.url', s)` writes a CBOR text string. Native readers of those same
+ * keys — the OTA policy store — have to agree byte for byte, or the C and JS
+ * implementations disagree about live device state.
+ *
+ * These helpers are that agreement, in the portable library so host tests can
+ * hold them to it.
+ */
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Encode `value` as a bare CBOR text string. Returns the number of bytes the
+ * encoding needs, which may exceed out_len — nothing is written in that case, so
+ * a caller can measure with (NULL, 0) first. */
+size_t mik__kv_encode_str(const char* value, uint8_t* out, size_t out_len);
+
+/* Decode a bare CBOR text string into out (always NUL-terminated on success).
+ * False when the value is not a text string or does not fit. */
+bool mik__kv_decode_str(const uint8_t* in, size_t in_len, char* out, size_t out_len);
+
+/* Encode `value` as a bare CBOR integer. */
+size_t mik__kv_encode_i32(int32_t value, uint8_t* out, size_t out_len);
+
+/* Decode a bare CBOR integer. False when the value is not an integer that fits
+ * in an int32. */
+bool mik__kv_decode_i32(const uint8_t* in, size_t in_len, int32_t* out);
+
+/**
+ * The device name pair.
+ *
+ * The platform stores it as the JSON text `[rev]` or `[rev, name]` — one value,
+ * so the pair can never be read or written half-updated (see runtime/sys/sys.ts,
+ * which is the other end of this encoding). Revision 0 with no name means never
+ * named.
+ */
+
+/* Parse the stored pair. False when the text is not a well-formed pair, which
+ * callers read as "never named" rather than as an error. `out_name` is set to the
+ * empty string when the name was cleared. */
+bool mik__device_name_parse(const char* json, int* out_rev, char* out_name, size_t name_len);
+
+/* Format a pair for storage. Pass NULL or "" as `name` to write `[rev]`.
+ * Returns the length the text needs, which may exceed out_len. */
+size_t mik__device_name_format(int rev, const char* name, char* out, size_t out_len);
+
+#ifdef __cplusplus
+}
+#endif

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/native",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "Mikro.js C++ runtime library and Node.js native addon",
   "keywords": [
     "esp32",
@@ -64,12 +64,14 @@
     "./runtime/neopixel/types": "./runtime/neopixel/types.ts",
     "./runtime/observable/operators": "./runtime/observable/operators.ts",
     "./runtime/observable/types": "./runtime/observable/types.ts",
-    "./runtime/ota/client-impl": "./runtime/ota/client-impl.ts",
     "./runtime/ota/types": "./runtime/ota/types.ts",
     "./runtime/pin/types": "./runtime/pin/types.ts",
     "./runtime/pwm/types": "./runtime/pwm/types.ts",
     "./runtime/reader/types": "./runtime/reader/types.ts",
+    "./runtime/result/native-result.node-shim": "./dist/runtime/result/native-result.node-shim.js",
     "./runtime/result/types": "./runtime/result/types.ts",
+    "./runtime/schema/core": "./dist/runtime/schema/core.js",
+    "./runtime/schema/shared": "./dist/runtime/schema/shared.js",
     "./runtime/schema/types": "./runtime/schema/types.ts",
     "./runtime/sleep/types": "./runtime/sleep/types.ts",
     "./runtime/sntp/types": "./runtime/sntp/types.ts",
@@ -86,14 +88,14 @@
     "cmake-js": "^8.0.0",
     "node-addon-api": "^8.7.0",
     "node-gyp-build": "^4.8.4",
-    "@mikrojs/quickjs": "0.18.0"
+    "@mikrojs/quickjs": "0.18.1"
   },
   "devDependencies": {
     "@swc/core": "^1.15.30",
     "@types/node": "^24.12.2",
     "esbuild": "^0.28.0",
     "terser": "^5.46.2",
-    "@mikrojs/registry": "0.18.0"
+    "@mikrojs/registry": "0.18.1"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -102,7 +104,7 @@
     "bench": "cmake -B build -DBUILD_TESTING=ON && cmake --build build --target memory_bench &&./build/memory_bench",
     "build:native": "cmake-js compile --directory addon && node scripts/copy-prebuild.js",
     "build:native:debug": "cmake-js compile --debug --directory addon && node scripts/copy-prebuild.js",
-    "build:ts": "tsc -p tsconfig.build.json",
+    "build:ts": "tsc -p tsconfig.build.json && tsc -p tsconfig.runtime-build.json",
     "clean": "cmake-js clean --directory addon && rm -rf prebuilds",
     "compare-minifiers": "node scripts/compare-minifiers.js --open",
     "publint": "publint",

package/runtime/internal.d.ts

@@ -11,6 +11,10 @@ declare module 'mikro/kv/shared' {
   export {KVError, makeCreateValue, mapKvError, type NativeKvFns} from './kv/shared.js'
 }
 
+declare module 'mikro/ota/config' {
+  export {config} from './ota/config.js'
+}
+
 declare module 'mikro/observable/lazy' {
   export {lazyEvent} from './observable/lazy.js'
 }
@@ -528,22 +532,24 @@ declare module 'native:mikro/udp' {
   export function bind(opts: BindOptions): Promise<Result<NativeUdpSocket, UdpError>>
 }
 
-declare module 'native:mikro/ota' {
-  import type {NativeOta} from './ota/policy.js'
-
-  // The native module exports the NativeOta contract's methods directly.
-  export function stageBegin(checksum: string, size: number): ReturnType<NativeOta['stageBegin']>
-  export function stageWrite(bytes: Uint8Array): ReturnType<NativeOta['stageWrite']>
-  export function stageFinish(
-    trialBoots: number,
-    requireConfirm: boolean,
-    installNow: boolean,
-  ): ReturnType<NativeOta['stageFinish']>
-  export function stageAbort(): void
-  export function markValid(): void
-  export function revert(): ReturnType<NativeOta['revert']>
-  export function running(): ReturnType<NativeOta['running']>
-  export function reconcile(): ReturnType<NativeOta['reconcile']>
+declare module 'native:mikro/ota_client' {
+  import type {CheckOptions, CheckResult, Ota, Watcher, WatchOptions} from './ota/types.js'
+
+  // Backed by src/mik_ota_client.cpp, src/mik_ota_config.cpp and
+  // src/mik_ota_policy.cpp.
+  export function check(options?: CheckOptions): Promise<CheckResult>
+  export function watch(options?: WatchOptions): Watcher
+  export function config(): unknown
+
+  // 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 confirm: Ota['confirm']
+  export const revert: Ota['revert']
+  export const bearer: Ota['bearer']
+  export const registry: Ota['registry']
 }
 
 declare module 'native:mikro/i2s' {

package/runtime/kv/shared.ts

@@ -71,11 +71,17 @@ export function makeCreateValue(native: NativeKvFns) {
         }
         return v
       } catch (e) {
-        // Decode failure: corrupt data, delete it
-        native.remove(key)
-        const fallback = onReadError(e)
-        if (fallback !== undefined) native.set(key, fallback)
-        return fallback
+        // TypeError is the native's corruption marker (stored bytes that do
+        // not decode): delete and heal. Anything else is a transient read
+        // failure (nvs open/read starved of heap) — the stored value is
+        // intact, so surface the error without touching it.
+        if (e instanceof TypeError) {
+          native.remove(key)
+          const fallback = onReadError(e)
+          if (fallback !== undefined) native.set(key, fallback)
+          return fallback
+        }
+        return onReadError(e)
       }
     }
 

package/runtime/kv/types.ts

@@ -64,7 +64,7 @@ export type KVOptions<S> =
       /** Called when reading stored data fails (decode error, schema mismatch).
        *  On decode failure, corrupt data is deleted. On schema mismatch, stored data is kept.
        *  Return a fallback value, or undefined. Default: `() => undefined`. */
-      onReadError: (error: KVError | SchemaError) => Infer<S>
+      onReadError: (error: KVError | SchemaError | Error) => Infer<S>
     }
   | {
       schema: OptionalSchema
@@ -72,7 +72,7 @@ export type KVOptions<S> =
       /** Called when reading stored data fails (decode error, schema mismatch).
        *  On decode failure, corrupt data is deleted. On schema mismatch, stored data is kept.
        *  Return a fallback value, or undefined. Default: `() => undefined`. */
-      onReadError?: (error: KVError | SchemaError) => Infer<S>
+      onReadError?: (error: KVError | SchemaError | Error) => Infer<S>
     }
   | {
       schema?: never
@@ -80,7 +80,7 @@ export type KVOptions<S> =
       /** Called when reading stored data fails (decode error, schema mismatch).
        *  On decode failure, corrupt data is deleted. On schema mismatch, stored data is kept.
        *  Return a fallback value, or undefined. Default: `() => undefined`. */
-      onReadError: (error: KVError) => unknown
+      onReadError: (error: KVError | Error) => unknown
     }
   | {
       schema?: never
@@ -88,7 +88,7 @@ export type KVOptions<S> =
       /** Called when reading stored data fails (decode error, schema mismatch).
        *  On decode failure, corrupt data is deleted. On schema mismatch, stored data is kept.
        *  Return a fallback value, or undefined. Default: `() => undefined`. */
-      onReadError?: (error: KVError) => unknown
+      onReadError?: (error: KVError | Error) => unknown
     }
 
 export interface KVValue<T> {

package/runtime/ota/client.ts

@@ -1,20 +1,15 @@
-import {decode, encode} from 'mikro/cbor'
-import {request} from 'mikro/http/request'
-import {ota} from 'mikro/ota'
-import {sleep} from 'mikro/sleep'
-import {
-  deviceId,
-  deviceName,
-  firmware,
-  restart,
-  setDeviceName,
-  storageUsage,
-  version,
-} from 'mikro/sys'
+// The OTA check-in client. The state machine lives in C
+// (src/mik_ota_client.cpp); this is the app-facing surface over it.
+//
+// There is deliberately no logic here. Every decision — the retry budget, the
+// trial gates, the config slots, the jittered cadence, the download pump with
+// its resume — is in the portable library, where host tests drive it against a
+// fake platform.
 
-import {type ClientIo, createOtaClient, type LogLevel} from './client-impl.js'
+import {check as nativeCheck, watch as nativeWatch} from 'native:mikro/ota_client'
 
 export type {
+  BeforeCheckResult,
   CheckError,
   CheckOptions,
   CheckResult,
@@ -22,41 +17,7 @@ export type {
   Teardown,
   Watcher,
   WatchOptions,
-} from './client-impl.js'
-
-/* eslint-disable no-console -- serial diagnostics are the client's only output channel */
-const consoleFor: Record<LogLevel, (format: string, ...args: unknown[]) => void> = {
-  debug: (format, ...args) => console.debug(format, ...args),
-  info: (format, ...args) => console.log(format, ...args),
-  warn: (format, ...args) => console.warn(format, ...args),
-  error: (format, ...args) => console.error(format, ...args),
-}
-/* eslint-enable no-console */
-
-/** The real device. Every runtime symbol the client uses is bound here and
- *  nowhere else; `ota` members go through arrows because they are methods on
- *  the builtin singleton. */
-const deviceIo: ClientIo = {
-  sleep,
-  request,
-  random: Math.random,
-  log: (level, format, ...args) => consoleFor[level](format, ...args),
-  encode,
-  decode,
-  ota,
-  identity: () => ({
-    deviceId,
-    firmware: version,
-    firmwareHash: firmware.hash,
-    bytecode: firmware.bytecodeVersion,
-  }),
-  storageFree: () => storageUsage()?.free,
-  deviceName,
-  setDeviceName,
-  restart,
-}
-
-const client = createOtaClient(deviceIo)
+} from './types.js'
 
 /**
  * One-shot update check for wake-cycle apps: check in with the registry,
@@ -65,7 +26,7 @@ const client = createOtaClient(deviceIo)
  * in-flight work is done. Connectivity is the app's business: call this with
  * the network already up.
  */
-export const check = client.check
+export const check = nativeCheck
 
 /**
  * Periodic update checks for always-on apps: a detached background loop that
@@ -74,4 +35,4 @@ export const check = client.check
  * per round (its returned teardown runs after the round). Do not combine with
  * `check()` — the two modes are alternatives, one per app.
  */
-export const watch = client.watch
+export const watch = nativeWatch

package/runtime/ota/config.ts

@@ -0,0 +1,18 @@
+// `ota.config()`, backed by the C reader (src/mik_ota_config.cpp).
+//
+// Its own module rather than part of `mikro/ota`: an app that only reads config
+// should not also pay for the policy surface, which most apps never touch.
+
+import {config as nativeConfig} from 'native:mikro/ota_client'
+
+import type {RegisteredConfig} from './types.js'
+
+/**
+ * The effective config for the running build: the manifest defaults with the
+ * stored document spread over them, top level only. Always an object, and a
+ * fresh one on every call.
+ *
+ * Throws when there is nothing to serve: a build with no readable manifest and
+ * no stored document, which is a build that never went through `mikro deploy`.
+ */
+export const config = nativeConfig as <T = RegisteredConfig>() => T