@mikrojs/native 0.18.1 → 0.18.2

package/include/mikrojs/mikrojs.h

@@ -234,11 +234,20 @@ bool MIK_ConsumeOOMFlag(MIKRuntime* mik_rt);
 void MIK_ReportOOM(MIKRuntime* mik_rt, const MIKOOMEvent* event);
 
 /* Per-module opaque data slots (for platform-specific modules to store state).
- * Slots are allocated dynamically via MIK_AllocModuleSlot(). */
+ *
+ * A slot index identifies one module for the lifetime of the process and means
+ * the same thing in every runtime, so reserve it once and cache it:
+ *
+ *     static int my_slot = -1;
+ *     if (my_slot < 0) my_slot = MIK_ReserveModuleSlot();
+ *
+ * Reserving per runtime instead would hand the same index to two modules as
+ * soon as a second runtime initialized a different set of them, and each
+ * would then read the other's state through the wrong type. */
 #define MIK_MODULE_DATA_SLOTS 16
 void MIK_SetModuleData(MIKRuntime* mik_rt, int slot, void* data);
 void* MIK_GetModuleData(MIKRuntime* mik_rt, int slot);
-int MIK_AllocModuleSlot(MIKRuntime* mik_rt);
+int MIK_ReserveModuleSlot(void);
 
 /* Self-registration for native modules (ESP32, board, driver modules).
  * Modules call MIK_REGISTER_MODULE() at file scope. The module loader

package/include/mikrojs/ota_client.h

@@ -250,9 +250,6 @@ private:
      * policy working normally — already current, a trial still resolving — are
      * not failures and are not reported. */
     void NoteDecline(MIKOtaDeclineReason reason, const std::string& detail);
-    /* Apply a config delivered without an offer: it is for the running
-     * release. Returns whether stored state changed. */
-    bool ApplyRunningConfig(const MIKOtaStoredConfig* config, int trial_boots);
     void ScheduleNext(NextRound next);
     int64_t Jitter(int64_t ms);
     int64_t Now() const;

package/include/mikrojs/ota_config.h

@@ -11,6 +11,11 @@
  * than the one running is ignored, because it was computed against a different
  * release's schema.
  *
+ * The writes deliver a document into those slots. The built-in check-in client
+ * takes them from its response; an app running its own transport (`ota.parseConfig`
+ * / `ota.applyConfig`) takes them from wherever its client got them. Both go
+ * through here, so the two cannot disagree about the trial and the baseline.
+ *
  * The read answers with an object or throws: there is no "no config yet" value.
  * A build that went through the tooling carries a manifest, the manifest
  * carries the defaults, and an app that declares no config schema gets an empty
@@ -97,4 +102,50 @@ private:
     JSContext* defaults_ctx_ = nullptr;
 };
 
+/* ── the writes ──────────────────────────────────────────────────────────── */
+
+/* What a write did to the store.
+ *
+ * `kUnchanged` covers both "identical to what is already held" and "a clear
+ * with nothing to clear": nothing moved, and the rev the device echoes is the
+ * one it echoed before. `kFailed` is a store that could not answer, which is
+ * not the same as nothing to do — the caller must not echo the new rev, so the
+ * writer sends the document again. */
+enum class MIKOtaConfigWrite {
+    kUnchanged,
+    kApplied,
+    kCleared,
+    kStaged,
+    kFailed,
+};
+
+const char* mik__ota_config_write_to_str(MIKOtaConfigWrite write);
+
+/* Deliver a document to the RUNNING release: the document it replaces becomes
+ * the rollback baseline, and a trial of `trial_boots` is armed, because a
+ * schema-valid value can still be fatal to the app. A NULL config, or one whose
+ * doc is absent, is the clear. */
+MIKOtaConfigWrite mik__ota_apply_running_config(const MIKOtaEnv* env,
+                                                const MIKOtaStoredConfig* config,
+                                                int trial_boots);
+
+/* Stage a document alongside an offered build: it was computed for that
+ * release, so it applies at its trial boot, with the build. A NULL config, or
+ * one whose doc is absent, stages the clear: the new release holds no document
+ * and its manifest defaults stand in. */
+void mik__ota_stage_next_config(const MIKOtaEnv* env, const MIKOtaStoredConfig* config);
+
+/* Deliver a document whose slot is not known from context, which is the case
+ * for a client that receives one over its own transport: the version stamp
+ * decides. Stamped for the running release it is applied, anything else is
+ * staged for the build it names. */
+MIKOtaConfigWrite mik__ota_deliver_config(const MIKOtaEnv* env, const MIKOtaStoredConfig* config,
+                                          int trial_boots);
+
+/* Settle a running-release trial on the health signal a completed check-in is.
+ * Adopts only once the app has READ the document: a check-in completing before
+ * the app ever ran with the new values proves nothing about them. Returns
+ * whether a trial was settled. */
+bool mik__ota_adopt_config_trial(const MIKOtaEnv* env);
+
 }  // namespace mikrojs

package/include/mikrojs/private.h

@@ -123,9 +123,9 @@ struct MIKRuntime {
     std::vector<std::pair<std::string, std::string>> env_vars;
     /* Opaque per-module data slots for platform-specific modules.
      * Used by registered native modules to store their state on the runtime.
-     * Slots are allocated dynamically via MIK_AllocModuleSlot(). */
+     * Indexed by MIK_ReserveModuleSlot(), which is process-wide, so a slot
+     * means the same module in every runtime. */
     void* module_data[MIK_MODULE_DATA_SLOTS] = {};
-    int next_module_slot = 0;
     /* Virtual modules: name → JS source.  Checked by the module loader before
      * the builtin bytecode table, allowing host-side JS to override any
      * native:* C module (e.g. mocking device modules for desktop dev). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/native",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "description": "Mikro.js C++ runtime library and Node.js native addon",
   "keywords": [
     "esp32",
@@ -88,14 +88,14 @@
     "cmake-js": "^8.0.0",
     "node-addon-api": "^8.7.0",
     "node-gyp-build": "^4.8.4",
-    "@mikrojs/quickjs": "0.18.1"
+    "@mikrojs/quickjs": "0.18.2"
   },
   "devDependencies": {
     "@swc/core": "^1.15.30",
     "@types/node": "^24.12.2",
     "esbuild": "^0.28.0",
     "terser": "^5.46.2",
-    "@mikrojs/registry": "0.18.1"
+    "@mikrojs/registry": "0.18.2"
   },
   "engines": {
     "node": ">=24.0.0"

package/runtime/internal.d.ts

@@ -546,6 +546,9 @@ declare module 'native:mikro/ota_client' {
   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 confirm: Ota['confirm']
   export const revert: Ota['revert']
   export const bearer: Ota['bearer']

package/runtime/ota/ota.ts

@@ -8,9 +8,12 @@
 
 import {config} from 'mikro/ota/config'
 import {
+  applyConfig,
   applyOffer,
   bearer,
+  configState,
   confirm,
+  parseConfig,
   parseOffer,
   reconcile,
   registry,
@@ -30,6 +33,9 @@ const ota: Ota = {
   bearer,
   registry,
   config,
+  parseConfig,
+  applyConfig,
+  configState,
 }
 
 export {ota}

package/runtime/ota/types.ts

@@ -150,6 +150,44 @@ export interface ConfigTrial {
   read: boolean
 }
 
+/** What a config write did to the store. Only `applied` and `cleared` change
+ *  what the running build reads; `staged` changes what the next one will. */
+export type ConfigWrite =
+  /** Stored as the running build's config. The document it replaced is kept as
+   *  the rollback baseline and a trial is armed, so the next `ota.confirm()`
+   *  after the app has read it is what keeps it. */
+  | 'applied'
+  /** Stored for the release the document names, which is not the one running.
+   *  It applies when that build installs, with the build. */
+  | 'staged'
+  /** The document was removed. The manifest defaults stand alone again. */
+  | 'cleared'
+  /** Nothing moved: the document is identical to the one already held (rev
+   *  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. */
+  | 'failed'
+  /** Not a usable config document. Validate with `parseConfig` first to find
+   *  out before the delivery, and 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,7 +235,11 @@ export interface Ota {
     download: DownloadFn,
     options?: InstallOptions,
   ): Promise<Result<ApplyOutcome, OtaError>>
-  /** Mark the running trial as healthy so it is kept rather than rolled back. */
+  /** Mark the running trial as healthy so it is kept rather than rolled back.
+   *  Settles a delivered config document's trial by the same call: a completed
+   *  check-in is the health signal both of them wait for. A config trial waits
+   *  additionally for the app to have read the document, so a `confirm()` from
+   *  an app that never called `config()` keeps nothing. */
   confirm(): void
   /** Reinstall the previous build immediately. */
   revert(): Result<void, OtaInstallError>
@@ -236,6 +278,46 @@ export interface Ota {
    * fixable states, never a value the app has to branch on.
    */
   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.
+   *
+   * 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.
+   */
+  configState(): ConfigState
 }
 
 /** The `mikro/ota` singleton. The runtime value is provided by the on-device

package/src/mik_ota_client.cpp

@@ -10,6 +10,7 @@
 #include <vector>
 
 #include "mikrojs/cbor_helpers.h"
+#include "mikrojs/ota_config.h"
 #include "mikrojs/ota_slots.h"
 #include "mikrojs/platform.h"
 
@@ -800,26 +801,13 @@ void MIKOtaClient::OnCheckInSettled() {
     // Confirm before applying: a completed check-in is the whole health signal
     // require_confirm waits for, whether or not an offer follows — and resolving
     // the trial now lets an offer published during it stage in this same pass.
+    // It settles a running-release config delivery's trial too (see
+    // mik__ota_policy_confirm): the same signal, for the same reason.
     if (running_.trial) {
         Log(MIK_LOG_INFO, "ota: check-in completed — confirming this build as healthy");
     }
     mik__ota_policy_confirm(env_);
 
-    // A completed check-in is the health signal for BOTH trials: the build's
-    // (confirmed above) and a running-release config delivery's. The config
-    // trial additionally waits for the app to have READ the document — a
-    // check-in completing before the app ever ran with the new values proves
-    // nothing about them.
-    // A read that FAILED is not a read that found nothing: it fails under the
-    // heap pressure this check-in just created, and adopting on it would take a
-    // document the app never read.
-    MIKOtaConfigTrial config_trial = {};
-    MIKOtaKvStatus trial_status = mik__ota_load_trial(env_, &config_trial);
-    if (trial_status == MIK_OTA_KV_ABSENT || (trial_status == MIK_OTA_KV_OK && config_trial.read)) {
-        mik__ota_clear_slot(env_, MIK_OTA_CFG_PREV);
-        mik__ota_clear_trial(env_);
-    }
-
     bool has_url_key = false;
     std::string offer_url;
     std::string offer_checksum;
@@ -939,8 +927,11 @@ void MIKOtaClient::OnCheckInSettled() {
     if (!has_url_key || !offer_valid) {
         // OR in this boot's promote/restore, delivered once: the config those
         // applied is as new to the app as one this round delivered.
-        bool updated = ApplyRunningConfig(have_response_config_ ? &response_config_ : nullptr,
-                                          active_.options.trial_boots);
+        MIKOtaConfigWrite write = mik__ota_apply_running_config(
+            env_, have_response_config_ ? &response_config_ : nullptr,
+            active_.options.trial_boots);
+        bool updated =
+            write == MIKOtaConfigWrite::kApplied || write == MIKOtaConfigWrite::kCleared;
         updated = updated || boot_config_changed_;
         boot_config_changed_ = false;
         Log(MIK_LOG_DEBUG, "ota: up to date, running the latest build");
@@ -1109,12 +1100,7 @@ void MIKOtaClient::OnDownloadSettled() {
     // with the build, applied together at the trial boot. An absent doc is the
     // clear, so it stages "the new release holds no document" and the manifest
     // defaults stand in.
-    if (have_response_config_ && response_config_.doc_cbor && response_config_.doc_cbor_len > 0) {
-        mik__ota_store_slot(env_, MIK_OTA_CFG_NEXT, response_config_);
-        Log(MIK_LOG_INFO, "ota: config staged for %s", response_config_.version);
-    } else {
-        mik__ota_clear_slot(env_, MIK_OTA_CFG_NEXT);
-    }
+    mik__ota_stage_next_config(env_, have_response_config_ ? &response_config_ : nullptr);
 
     Log(MIK_LOG_INFO, "ota: download verified and staged");
     result_.status = MIKOtaCheckStatus::kStaged;
@@ -1122,59 +1108,6 @@ void MIKOtaClient::OnDownloadSettled() {
     FinishRound(NextRound::kLater);
 }
 
-bool MIKOtaClient::ApplyRunningConfig(const MIKOtaStoredConfig* config, int trial_boots) {
-    if (!config) return false;
-
-    if (!config->doc_cbor || config->doc_cbor_len == 0) {
-        // A rev riding along does not turn a clear into a document.
-        mik__ota_clear_trial(env_);
-        mik__ota_clear_config_error(env_);
-        mik__ota_clear_slot(env_, MIK_OTA_CFG_PREV);
-        if (!mik__ota_load_slot(env_, MIK_OTA_CFG_CURRENT).present) return false;
-        mik__ota_clear_slot(env_, MIK_OTA_CFG_CURRENT);
-        Log(MIK_LOG_INFO, "ota: config cleared by the registry");
-        return true;
-    }
-
-    MIKOtaLoadedConfig previous = mik__ota_load_slot(env_, MIK_OTA_CFG_CURRENT);
-
-    // Without the document being replaced there is no baseline to roll back to,
-    // and clearing the one already stored would strand a bad document with
-    // nowhere to fall back to. Leave everything alone; the rev the device
-    // echoes is unchanged, so the registry sends this again next round.
-    if (previous.failed) return false;
-
-    // A registry is meant to send config only when the rev the device echoed
-    // differs, but one that sends it every round must not cost anything: taking
-    // an identical document as a change would re-write NVS on every round, put
-    // the document back on trial it had already passed, and tell the app its
-    // config changed when nothing did. The rev counts as part of the document —
-    // it is what the device echoes, so a new one has to be stored and echoed
-    // back even when the values are the same.
-    if (previous.present && strcmp(previous.cfg.rev, config->rev) == 0 &&
-        strcmp(previous.cfg.version, config->version) == 0 &&
-        previous.cfg.doc_cbor_len == config->doc_cbor_len &&
-        (config->doc_cbor_len == 0 ||
-         memcmp(previous.cfg.doc_cbor, config->doc_cbor, config->doc_cbor_len) == 0)) {
-        return false;
-    }
-
-    // The old document is kept as the rollback baseline: a schema-valid value
-    // can still be fatal to the app (a GPIO this board does not have), and the
-    // crash it causes can fire before any check-in runs.
-    if (previous.present) {
-        mik__ota_store_slot(env_, MIK_OTA_CFG_PREV, previous.cfg);
-    } else {
-        mik__ota_clear_slot(env_, MIK_OTA_CFG_PREV);
-    }
-    mik__ota_store_slot(env_, MIK_OTA_CFG_CURRENT, *config);
-    MIKOtaConfigTrial trial = {trial_boots, false};
-    mik__ota_store_trial(env_, trial);
-    mik__ota_clear_config_error(env_);
-    Log(MIK_LOG_INFO, "ota: config updated for %s", config->version);
-    return true;
-}
-
 void MIKOtaClient::FinishRound(NextRound next) {
     // Teardown before any restart: the round is over either way, and the hook's
     // invariant — teardown runs whenever setup succeeded — must not depend on

package/src/mik_ota_config.cpp

@@ -10,6 +10,7 @@
 
 #include "mikrojs/cbor_helpers.h"
 #include "mikrojs/ota_slots.h"
+#include "mikrojs/platform.h"
 
 namespace mikrojs {
 
@@ -293,4 +294,140 @@ JSValue MIKOtaConfigReader::Defaults(JSContext* ctx) {
     return defaults_;
 }
 
+/* ── the writes ──────────────────────────────────────────────────────────── */
+
+namespace {
+
+/* `arg` fills the one %s a config log line ever carries. */
+void LogConfig(const MIKOtaEnv* env, int level, const char* fmt, const char* arg = nullptr) {
+    if (!env || !env->log) return;
+    if (arg) {
+        env->log(env->opaque, level, fmt, arg);
+    } else {
+        env->log(env->opaque, level, "%s", fmt);
+    }
+}
+
+}  // namespace
+
+const char* mik__ota_config_write_to_str(MIKOtaConfigWrite write) {
+    switch (write) {
+        case MIKOtaConfigWrite::kUnchanged:
+            return "unchanged";
+        case MIKOtaConfigWrite::kApplied:
+            return "applied";
+        case MIKOtaConfigWrite::kCleared:
+            return "cleared";
+        case MIKOtaConfigWrite::kStaged:
+            return "staged";
+        case MIKOtaConfigWrite::kFailed:
+            return "failed";
+    }
+    return "unknown";
+}
+
+MIKOtaConfigWrite mik__ota_apply_running_config(const MIKOtaEnv* env,
+                                                const MIKOtaStoredConfig* config,
+                                                int trial_boots) {
+    if (!config) return MIKOtaConfigWrite::kUnchanged;
+
+    if (!config->doc_cbor || config->doc_cbor_len == 0) {
+        // A rev riding along does not turn a clear into a document.
+        mik__ota_clear_trial(env);
+        mik__ota_clear_config_error(env);
+        mik__ota_clear_slot(env, MIK_OTA_CFG_PREV);
+        MIKOtaLoadedConfig held = mik__ota_load_slot(env, MIK_OTA_CFG_CURRENT);
+        if (held.failed) return MIKOtaConfigWrite::kFailed;
+        if (!held.present) return MIKOtaConfigWrite::kUnchanged;
+        mik__ota_clear_slot(env, MIK_OTA_CFG_CURRENT);
+        LogConfig(env, MIK_LOG_INFO, "ota: config cleared");
+        return MIKOtaConfigWrite::kCleared;
+    }
+
+    MIKOtaLoadedConfig previous = mik__ota_load_slot(env, MIK_OTA_CFG_CURRENT);
+
+    // Without the document being replaced there is no baseline to roll back to,
+    // and clearing the one already stored would strand a bad document with
+    // nowhere to fall back to. Leave everything alone; the rev the device
+    // echoes is unchanged, so the writer sends this again.
+    if (previous.failed) return MIKOtaConfigWrite::kFailed;
+
+    // A registry is meant to send config only when the rev the device echoed
+    // differs, but one that sends it every round must not cost anything: taking
+    // an identical document as a change would re-write NVS on every round, put
+    // the document back on trial it had already passed, and tell the app its
+    // config changed when nothing did. The rev counts as part of the document —
+    // it is what the device echoes, so a new one has to be stored and echoed
+    // back even when the values are the same.
+    if (previous.present && strcmp(previous.cfg.rev, config->rev) == 0 &&
+        strcmp(previous.cfg.version, config->version) == 0 &&
+        previous.cfg.doc_cbor_len == config->doc_cbor_len &&
+        (config->doc_cbor_len == 0 ||
+         memcmp(previous.cfg.doc_cbor, config->doc_cbor, config->doc_cbor_len) == 0)) {
+        return MIKOtaConfigWrite::kUnchanged;
+    }
+
+    // The old document is kept as the rollback baseline: a schema-valid value
+    // can still be fatal to the app (a GPIO this board does not have), and the
+    // crash it causes can fire before any check-in runs.
+    if (previous.present) {
+        mik__ota_store_slot(env, MIK_OTA_CFG_PREV, previous.cfg);
+    } else {
+        mik__ota_clear_slot(env, MIK_OTA_CFG_PREV);
+    }
+    mik__ota_store_slot(env, MIK_OTA_CFG_CURRENT, *config);
+    MIKOtaConfigTrial trial = {trial_boots, false};
+    mik__ota_store_trial(env, trial);
+    mik__ota_clear_config_error(env);
+    LogConfig(env, MIK_LOG_INFO, "ota: config updated for %s", config->version);
+    return MIKOtaConfigWrite::kApplied;
+}
+
+void mik__ota_stage_next_config(const MIKOtaEnv* env, const MIKOtaStoredConfig* config) {
+    if (config && config->doc_cbor && config->doc_cbor_len > 0) {
+        mik__ota_store_slot(env, MIK_OTA_CFG_NEXT, *config);
+        LogConfig(env, MIK_LOG_INFO, "ota: config staged for %s", config->version);
+        return;
+    }
+    // The clear is staged too: the offered release holds no document, and its
+    // manifest defaults stand in once it runs.
+    mik__ota_clear_slot(env, MIK_OTA_CFG_NEXT);
+}
+
+MIKOtaConfigWrite mik__ota_deliver_config(const MIKOtaEnv* env, const MIKOtaStoredConfig* config,
+                                          int trial_boots) {
+    if (!config) return MIKOtaConfigWrite::kUnchanged;
+
+    char running[32] = {};
+    if (!env || !env->read_app_version ||
+        !env->read_app_version(env->opaque, running, sizeof(running))) {
+        // The version the document has to be matched against could not be read,
+        // so which slot it belongs in is unknown. Storing it in either would be
+        // a guess, and the reader drops a document stamped for another release
+        // without a sound, so the guess would fail silently.
+        return MIKOtaConfigWrite::kFailed;
+    }
+
+    if (strcmp(config->version, running) == 0) {
+        return mik__ota_apply_running_config(env, config, trial_boots);
+    }
+    // Stamped for another release: it is the document that release will read,
+    // and it applies with the build, not before it.
+    mik__ota_stage_next_config(env, config);
+    return MIKOtaConfigWrite::kStaged;
+}
+
+bool mik__ota_adopt_config_trial(const MIKOtaEnv* env) {
+    // A read that FAILED is not a read that found nothing: it fails under heap
+    // pressure, and adopting on it would keep a document the app never read.
+    MIKOtaConfigTrial trial = {};
+    MIKOtaKvStatus status = mik__ota_load_trial(env, &trial);
+    // With no trial in progress the clears are housekeeping, not a settlement.
+    bool settled = status == MIK_OTA_KV_OK && trial.read;
+    if (status != MIK_OTA_KV_ABSENT && !settled) return false;
+    mik__ota_clear_slot(env, MIK_OTA_CFG_PREV);
+    mik__ota_clear_trial(env);
+    return settled;
+}
+
 }  // namespace mikrojs

package/src/mik_ota_policy.cpp

@@ -5,6 +5,7 @@
 #include <memory>
 #include <string>
 
+#include "mikrojs/ota_config.h"
 #include "mikrojs/platform.h"
 
 namespace mikrojs {
@@ -205,6 +206,13 @@ void mik__ota_policy_confirm(const MIKOtaEnv* env) {
     if (env && env->mark_valid) {
         env->mark_valid(env->opaque);
     }
+    // One confirm settles both trials. A completed check-in is the health
+    // signal each of them waits for, so an app running its own client gets the
+    // config trial resolved by the same call the built-in client makes — and
+    // the two cannot drift into settling one trial but not the other. The
+    // config trial has its own extra gate (the app must have read the
+    // document), which lives in mik__ota_adopt_config_trial.
+    mik__ota_adopt_config_trial(env);
 }
 
 namespace {

package/src/mikrojs.cpp

@@ -533,8 +533,15 @@ void* MIK_GetModuleData(MIKRuntime* mik_rt, int slot) {
 // NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
 mik_module_desc_t* mik__module_registry_head = nullptr;
 
-int MIK_AllocModuleSlot(MIKRuntime* mik_rt) {
-    int slot = mik_rt->next_module_slot++;
+int MIK_ReserveModuleSlot(void) {
+    /* Process-wide and never released: a module keeps one index for the life
+     * of the process, so every runtime agrees on what that index holds. A
+     * per-runtime counter would restart at zero and alias modules across
+     * runtimes. Callers reserve once (guard on their cached slot being < 0);
+     * reserving per runtime would exhaust the table instead. */
+    // NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
+    static int next_slot = 0;
+    int slot = next_slot++;
     CHECK(slot < MIK_MODULE_DATA_SLOTS);
     return slot;
 }