@mikrojs/native 0.18.0 → 0.18.1

package/include/mikrojs/ota_client.h

@@ -0,0 +1,342 @@
+#pragma once
+
+#include <quickjs.h>
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "mikrojs/ota_env.h"
+#include "mikrojs/ota_policy.h"
+
+namespace mikrojs {
+
+/* Why an offered build was not armed. Each is the policy working as intended;
+ * the distinction is logged and reported because the app's next move differs. */
+enum class MIKOtaDeclineReason {
+    kTrialPending,
+    kCurrent,
+    kAbandoned,
+    kExhausted,
+    kDownloadFailed,
+    kInstallFailed,
+};
+
+const char* mik__ota_decline_reason_to_str(MIKOtaDeclineReason reason);
+
+enum class MIKOtaCheckStatus {
+    kStaged,
+    kUpToDate,
+    kNotStaged,
+    kFailed,
+    kUnauthorized,
+    kNotEnrolled,
+};
+
+const char* mik__ota_check_status_to_str(MIKOtaCheckStatus status);
+
+struct MIKOtaCheckOptions {
+    /* Budget for the check-in round trip. */
+    uint32_t checkin_timeout_ms = 10000;
+    /* Budget for the build download: a total deadline that cancels the
+     * transfer mid-stream, so it needs orders of magnitude more than a
+     * check-in body does. */
+    uint32_t download_timeout_ms = 300000;
+    bool require_confirm = true;
+    int trial_boots = 1;
+};
+
+/* Where an asynchronous round hook stands. */
+enum class MIKOtaHookState {
+    kPending,
+    kOk,
+    kFailed,
+};
+
+/* The per-round network hook pair: `beforeCheck` and the teardown it hands
+ * back. It belongs to one watch call rather than to the platform, so it lives
+ * outside MIKOtaEnv. Begin* returns false when there is no hook to run, in
+ * which case the machine moves straight on.
+ *
+ * A failed BeginBeforeCheck skips the round and no teardown runs: unwinding a
+ * partial setup is the hook's own business. */
+class MIKOtaRoundHooks {
+public:
+    virtual ~MIKOtaRoundHooks() = default;
+    virtual bool BeginBeforeCheck() = 0;
+    virtual MIKOtaHookState PollBeforeCheck() = 0;
+    virtual bool BeginTeardown() = 0;
+    virtual MIKOtaHookState PollTeardown() = 0;
+};
+
+struct MIKOtaCheckResult {
+    MIKOtaCheckStatus status = MIKOtaCheckStatus::kFailed;
+    /* Set on kStaged. */
+    MIKOtaOffer offer;
+    /* On kUpToDate: the running build's stored config changed since the app
+     * could last have read it — delivered or cleared this round, or applied by
+     * this boot's install or rollback. */
+    bool config_updated = false;
+    /* Set on kNotStaged. */
+    MIKOtaDeclineReason decline_reason = MIKOtaDeclineReason::kCurrent;
+    /* Set on kFailed and on kNotStaged with a download or install failure. */
+    MIKOtaError error;
+    /* The response status behind a kFailed/kUnauthorized, or 0. */
+    int http_status = 0;
+};
+
+/* Fires exactly once per Check(), when that round settles. */
+using MIKOtaCheckSink = std::function<void(const MIKOtaCheckResult&)>;
+
+struct MIKOtaWatchOptions : MIKOtaCheckOptions {
+    /* Steady interval between rounds, end-of-round to start-of-next. Floored
+     * at 30s: each round's TLS session leaves heap and socket residue that
+     * needs time to drain, and the value may arrive from remote config, so the
+     * floor bounds the damage a mistyped document can do. */
+    uint32_t checkin_interval_ms = 30 * 60 * 1000;
+    uint32_t initial_delay_ms = 5000;
+    /* Interval after a failed round, capped at checkin_interval_ms. */
+    uint32_t retry_after_failure_ms = 60000;
+    /* Spread every scheduled delay by ±10%, so a fleet that lost power
+     * together does not check in phase-locked forever. */
+    bool jitter = true;
+    /* Borrowed, not owned: must outlive the watch. */
+    MIKOtaRoundHooks* hooks = nullptr;
+    /* Fires as each round settles, before any restart. A watch loop otherwise
+     * reports nothing to the app, which then has to poll for what changed —
+     * config delivery in particular, which is invisible from outside. */
+    MIKOtaCheckSink on_round;
+};
+
+
+/* Why the device did not take the build it was last offered.
+ *
+ * Without this a registry cannot tell "still working on it" from "gave up": the
+ * device stops retrying, its running checksum never changes, and the registry
+ * waits for an install that is never coming. `exhausted` is per-boot and clears
+ * on reboot; `abandoned` is permanent for those bytes. */
+struct MIKOtaDeclineReport {
+    char checksum[65] = {};
+    MIKOtaDeclineReason reason = MIKOtaDeclineReason::kExhausted;
+    /* The underlying error, when there was one. */
+    std::string detail;
+};
+
+/* Everything the check-in report carries. A struct because the list grew past
+ * what positional arguments stay readable at. */
+struct MIKOtaCheckinFacts {
+    const MIKDeviceIdentity* identity = nullptr;
+    const MIKOtaRunningBuild* running = nullptr;
+    int name_rev = 0;
+    /* NULL or empty sends the cleared `[rev]` pair. */
+    const char* name = nullptr;
+    bool has_free = false;
+    size_t free_bytes = 0;
+    const MIKOtaDiagnostic* last_install = nullptr;
+    /* NULL or empty omits the key. */
+    const char* echo_rev = nullptr;
+    const MIKOtaConfigErrorReport* config_error = nullptr;
+    const MIKOtaDeclineReport* last_decline = nullptr;
+};
+
+/* The states a round can rest in between Poll() calls. Parsing the response and
+ * closing the install are synchronous, so they are transitions, not states. */
+enum class MIKOtaClientState {
+    kIdle,
+    kBeforeCheck,
+    kCheckIn,
+    kDownload,
+    kTeardown,
+};
+
+/* Largest check-in response the client will buffer. Real ones run to a few
+ * hundred bytes; the cap is what keeps a confused or hostile registry from
+ * growing the buffer until the device runs out of heap. */
+constexpr size_t MIK__OTA_MAX_RESPONSE_BYTES = 8192;
+
+/**
+ * The OTA client: one check-in round at a time, driven by Poll().
+ *
+ * `Check()` queues a forced round. `Watch()` runs rounds on a jittered cadence
+ * and restarts the device after staging a build. Both share one queue, because
+ * staging is a single native session and two interleaved rounds would corrupt
+ * it — a Check() issued mid-round waits its turn and still gets its own result.
+ */
+class MIKOtaClient {
+public:
+    /* `config` is borrowed and may be NULL: it is only read for the defaults
+     * rev the check-in reports, and must outlive the client. */
+    explicit MIKOtaClient(const MIKOtaEnv* env);
+    ~MIKOtaClient();
+    MIKOtaClient(const MIKOtaClient&) = delete;
+    MIKOtaClient& operator=(const MIKOtaClient&) = delete;
+
+    /* Queue one forced round. `sink` fires from a later Poll() — except on an
+     * un-enrolled device, which settles inline before Check() returns. */
+    void Check(const MIKOtaCheckOptions& options, MIKOtaCheckSink sink);
+
+    /* Start the free-running loop. Inert, with a log line, on an un-enrolled
+     * device. At most one watch per client. */
+    void Watch(const MIKOtaWatchOptions& options);
+
+    /* No further rounds, and the pending delay is cancelled. A round in flight
+     * still completes, but a build it stages no longer auto-restarts — it stays
+     * armed for the next natural reboot. */
+    void StopWatch();
+
+    /* Change the cadence of a running watch, floored the same way Watch() floors
+     * it. A wait already counting is re-timed from when it started, so lowering
+     * the interval brings the next round forward instead of waiting out the old
+     * one — which is the case this exists for, a cadence arriving from remote
+     * config. The initial delay is left alone: it is not the interval. */
+    void SetCheckinInterval(uint32_t interval_ms);
+
+    /* One turn of the machine: settle what is ready, start what is due. Call it
+     * once per loop pass. */
+    void Poll();
+
+    MIKOtaClientState state() const { return state_; }
+    /* The delay last handed to the scheduler, jitter included, or -1 when no
+     * round is scheduled. */
+    int64_t scheduled_delay_ms() const { return scheduled_delay_ms_; }
+    bool watching() const { return watching_ && !watch_stopped_; }
+    bool HasLastInstall() const { return has_last_install_; }
+    bool BootConfigChanged() const { return boot_config_changed_; }
+
+private:
+    /* Which delay the pending wait is counting, so a cadence change can re-time
+     * it against the right one. */
+    enum class PendingWait { kNone, kInitial, kInterval, kRetry };
+
+    /* What the loop does after a round: retry at the shortened interval, or
+     * wait the full one. Deliberately not "did the check-in succeed" — a
+     * rejected update key also waits the full interval, so a dead key does not
+     * hammer the registry every retry interval forever. */
+    enum class NextRound { kSoon, kLater };
+
+    struct Round {
+        bool is_watch = false;
+        MIKOtaCheckOptions options;
+        MIKOtaCheckSink sink;
+        std::string registry_url;
+        std::string bearer;
+    };
+
+    /* One transition. Returns true when it moved, so Poll can keep going. */
+    bool Step();
+
+    /* Transport callbacks. They only record what arrived (and, for a download,
+     * stream it into staging); every decision is taken from Poll(), so the
+     * machine never advances re-entrantly from inside the transport. */
+    static void HeadersThunk(void* user_data, int status);
+    static void DownloadHeadersThunk(void* user_data, int status);
+    static void DataThunk(void* user_data, const uint8_t* data, size_t len);
+    static void DoneThunk(void* user_data, int status, const char* error_msg);
+
+    bool Enrollment(std::string* out_url, std::string* out_bearer) const;
+    void StartRound();
+    void BeginCheckIn();
+    void OnCheckInSettled();
+    bool BeginDownload();
+    void OnDownloadSettled();
+    void FinishRound(NextRound next);
+    void Finalize(NextRound next);
+
+    void ReconcileOnce();
+    /* Record a decline worth telling the registry about. Reasons that are the
+     * 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;
+    void Log(int level, const char* fmt, ...) const;
+
+    const MIKOtaEnv* env_;
+    MIKOtaClientState state_ = MIKOtaClientState::kIdle;
+
+    std::vector<Round> queue_;
+    Round active_;
+
+    /* Boot-once bookkeeping, held across rounds. */
+    bool reconciled_ = false;
+    bool has_last_install_ = false;
+    MIKOtaDiagnostic last_install_ = {};
+    bool boot_config_changed_ = false;
+    bool warned_insecure_ = false;
+    /* Held until a check-in delivers it, exactly like last_install_. A reboot
+     * loses an undelivered one, which is right for `exhausted` (the budget
+     * resets anyway) and harmless for `abandoned` (the next offer re-declines
+     * immediately and reports again). */
+    bool has_last_decline_ = false;
+    MIKOtaDeclineReport last_decline_;
+
+    /* The round in flight. */
+    bool allow_insecure_ = false;
+    MIKOtaRunningBuild running_ = {};
+    MIKOtaCheckResult result_;
+    bool teardown_armed_ = false;
+    NextRound pending_next_ = NextRound::kLater;
+
+    /* The exchange in flight. */
+    void* http_handle_ = nullptr;
+    bool http_done_ = false;
+    int http_status_ = 0;
+    std::string http_error_;
+    std::vector<uint8_t> response_body_;
+    bool response_too_large_ = false;
+
+    /* The download in flight. */
+    MIKOtaApplySession apply_;
+    MIKOtaOffer offer_;
+    size_t download_skip_ = 0;
+    bool write_failed_ = false;
+    MIKOtaError write_error_;
+    /* The config the response carried, if any, kept until the round settles. */
+    bool have_response_config_ = false;
+    MIKOtaStoredConfig response_config_ = {};
+    std::vector<uint8_t> response_config_doc_;
+
+    /* Watch state. */
+    bool watching_ = false;
+    bool watch_stopped_ = false;
+    MIKOtaWatchOptions watch_options_;
+    std::string watch_registry_url_;
+    std::string watch_bearer_;
+    int64_t deadline_ms_ = -1;
+    int64_t scheduled_delay_ms_ = -1;
+    PendingWait pending_wait_ = PendingWait::kNone;
+    /* When the pending wait began, so it can be re-timed without drifting. */
+    int64_t wait_started_ms_ = 0;
+};
+
+/* True when both urls share a scheme and authority. Deliberately literal: with
+ * no URL parser here, a spelled-out default port does not compare equal. */
+bool mik__ota_same_origin(const std::string& a, const std::string& b);
+
+/* True for http:// on a LAN/loopback/mDNS host: development, not the internet.
+ * Anywhere else the scheme is not a judgement call — over http the offer's
+ * checksum is forgeable in the same response that names it. */
+bool mik__ota_is_private_http(const std::string& url);
+
+/* Validate an untrusted registry value into an offer.
+ *
+ * The JS-value twin of mik__ota_parse_offer, for a caller holding a decoded
+ * check-in response rather than the fields. Absent or malformed reads as no
+ * offer; a url that is present but unusable also warns on the console, the way
+ * the TypeScript parseOffer did, because that case is a registry misconfiguring
+ * itself rather than a device with nothing to do. */
+bool mik__ota_parse_offer_js(JSContext* ctx, JSValueConst raw, bool allow_insecure,
+                             MIKOtaOffer* out_offer);
+
+/* The check-in report, CBOR-encoded. The shape is a contract with the
+ * registry's /api/v1/checkin; optional keys are omitted, never sent as null. */
+std::vector<uint8_t> mik__ota_build_checkin_report(const MIKOtaCheckinFacts& facts);
+
+}  // namespace mikrojs

package/include/mikrojs/ota_config.h

@@ -0,0 +1,100 @@
+#pragma once
+
+/**
+ * The `ota.config()` read.
+ *
+ * The effective config is the running build's manifest defaults with the stored
+ * document spread over them, top level only: `{...defaults, ...doc}`. Every key
+ * a document carries is a complete top-level value, computed and validated by
+ * the registry that served it at check-in, so the device never validates and
+ * never merges deeper than one level. A document stamped for a version other
+ * than the one running is ignored, because it was computed against a different
+ * release's schema.
+ *
+ * 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
+ * object. The throw is reserved for a build with no readable manifest and
+ * nothing stored, which is a build that never went through `mikro deploy`.
+ */
+
+#include <quickjs.h>
+
+#include "mikrojs/ota_env.h"
+
+namespace mikrojs {
+
+class MIKOtaConfigReader {
+public:
+    explicit MIKOtaConfigReader(const MIKOtaEnv* env) : env_(env) {}
+    ~MIKOtaConfigReader();
+    MIKOtaConfigReader(const MIKOtaConfigReader&) = delete;
+    MIKOtaConfigReader& operator=(const MIKOtaConfigReader&) = delete;
+
+    /**
+     * Read the effective config. The caller owns the returned value, a fresh
+     * object on every call so an app that mutates what it got cannot reach the
+     * cached defaults. JS_EXCEPTION means nothing could be served at all.
+     *
+     * A FAILED store read is not absence. The store can fail because reading it
+     * allocates and heap pressure (a TLS handshake in flight) can starve it.
+     * Treating that as "no document" flips a live device onto the defaults for a
+     * beat, re-configuring its GPIO mid-handshake. A failed read serves whatever
+     * the last successful read returned, for exactly as long as reads keep
+     * failing; before the first success this runtime it serves the defaults
+     * alone. A genuine clear removes the key and reads back as an honest
+     * absence, so the two cases travel different channels and cannot be
+     * confused.
+     *
+     * THE FIRST READ OF EACH BOOT THAT SERVES THE STORED DOCUMENT is also where
+     * a running-release trial is accounted. A schema-valid document can still be
+     * fatal to the app (a GPIO this board does not have), and a config-caused
+     * crash can fire before the first check-in ever runs, but never before the
+     * app reads the document that causes it, which makes the read the one hook a
+     * crash loop cannot starve. Each such boot burns one trial boot; the budget
+     * spent, the previous document is restored, the failure recorded for the
+     * next check-in to report, and this very read returns the restored values,
+     * which is what breaks the loop. A boot that never serves the document (the
+     * store could not answer, the document is stamped for another version, its
+     * bytes do not decode) leaves the trial untouched: recording that the app
+     * read a document it never saw is what the accounting exists to prevent.
+     */
+    JSValue Read(JSContext* ctx);
+
+private:
+    /* The stored document for the running version, decoded, or JS_UNDEFINED
+     * when there is none to serve. Sets *out_failed when the store could not
+     * answer, which is not the same as having nothing stored. */
+    JSValue LoadDoc(JSContext* ctx, bool* out_failed);
+    /* Accounts this boot against a running-release trial. `serving_doc` says
+     * whether this read returns the stored document, which is the only case a
+     * trial boot may be charged to. False when the store could not answer, in
+     * which case nothing was written and the whole block retries on the next
+     * read. Sets *out_rolled_back when the budget was spent and the stored
+     * document changed under the caller. */
+    bool Account(bool serving_doc, bool* out_rolled_back);
+    /* The manifest defaults, parsed once and held for the runtime's lifetime.
+     * Borrowed: the caller must not free it. JS_UNDEFINED when the manifest
+     * could not be read or parsed, which is retried on the next call. */
+    JSValue Defaults(JSContext* ctx);
+    /* What to serve when the store could not answer. */
+    JSValue ServeFallback(JSContext* ctx);
+    JSValue ServeLastGood(JSContext* ctx) const;
+    void KeepLastGood(JSContext* ctx, JSValue value);
+
+    const MIKOtaEnv* env_;
+    /* Module state resets on every boot, so "once per boot" needs no clock. */
+    bool accounted_ = false;
+    bool has_last_good_ = false;
+    JSValue last_good_ = JS_UNDEFINED;
+    /* Held so the destructor can free last_good_ without being handed a ctx. */
+    JSContext* last_good_ctx_ = nullptr;
+    /* Cached on success only: a manifest that could not be read or parsed under
+     * heap pressure must be retried, not remembered as "no defaults". */
+    bool has_defaults_ = false;
+    JSValue defaults_ = JS_UNDEFINED;
+    /* The same, for the cached defaults. */
+    JSContext* defaults_ctx_ = nullptr;
+};
+
+}  // namespace mikrojs

package/include/mikrojs/ota_env.h

@@ -0,0 +1,192 @@
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct MIKOtaEnv MIKOtaEnv;
+
+/* HTTP callbacks. All three fire *after* http_request has returned, from
+ * whatever drains the transport (the loop consumer on device, Tick() in the
+ * host tests) — never re-entrantly from inside the call itself. */
+
+/* Response status, delivered before any body byte. The client needs it ahead
+ * of the body: a 206 means the Range was honoured and no prefix must be
+ * dropped, and a 401 body is discarded rather than staged. */
+typedef void (*MIKOtaHttpHeadersCb)(void* user_data, int status);
+typedef void (*MIKOtaHttpDataCb)(void* user_data, const uint8_t* data, size_t len);
+/* Terminal, exactly once per request. `status` repeats the response status, or
+ * is 0 when the exchange never completed; `error_msg` is NULL on success. */
+typedef void (*MIKOtaHttpDoneCb)(void* user_data, int status, const char* error_msg);
+
+typedef struct MIKOtaHttpCallbacks {
+    MIKOtaHttpHeadersCb headers;
+    MIKOtaHttpDataCb data;
+    MIKOtaHttpDoneCb done;
+    void* user_data;
+} MIKOtaHttpCallbacks;
+
+typedef struct MIKOtaHttpRequest {
+    const char* url;
+    const char* method; /* "GET" or "POST" */
+    const char* const* header_keys;
+    const char* const* header_values;
+    size_t header_count;
+    const uint8_t* body;
+    size_t body_len;
+    uint32_t timeout_ms;
+} MIKOtaHttpRequest;
+
+/* Device identity */
+typedef struct MIKDeviceIdentity {
+    char device_id[64];
+    char firmware_version[32];
+    char firmware_hash[65];
+    int bytecode_version;
+} MIKDeviceIdentity;
+
+/* Diagnostic info from reconcile */
+typedef struct MIKOtaDiagnostic {
+    char reason[64];
+    char detail[128];
+} MIKOtaDiagnostic;
+
+/* Reconcile outcome */
+typedef struct MIKOtaReconcileOutcome {
+    char installed[65]; /* SHA-256 hex or empty string if none */
+    bool reverted;
+    bool has_diagnostic;
+    MIKOtaDiagnostic diagnostic;
+} MIKOtaReconcileOutcome;
+
+/* Running build info */
+typedef struct MIKOtaRunningBuild {
+    char checksum[65]; /* SHA-256 hex or empty string if none */
+    char version[32];  /* package.json version or empty string if none */
+    bool trial;
+} MIKOtaRunningBuild;
+
+/* Install error kind: 0 = corrupt, 1 = transient, 2 = oom */
+enum {
+    MIK_OTA_ERR_CORRUPT = 0,
+    MIK_OTA_ERR_TRANSIENT = 1,
+    MIK_OTA_ERR_OOM = 2,
+};
+
+/* Outcome of a kv read. */
+typedef enum MIKOtaKvStatus {
+    MIK_OTA_KV_OK = 0,
+    /* Nothing was ever stored under this key. */
+    MIK_OTA_KV_ABSENT = 1,
+    /* The store could not answer — out of heap, backend error. Says nothing
+     * about whether a value exists. */
+    MIK_OTA_KV_ERROR = 2,
+} MIKOtaKvStatus;
+
+/* Config slots */
+typedef enum MIKOtaConfigSlot {
+    MIK_OTA_CFG_CURRENT = 0,
+    MIK_OTA_CFG_NEXT = 1,
+    MIK_OTA_CFG_PREV = 2,
+} MIKOtaConfigSlot;
+
+/* Config trial state */
+typedef struct MIKOtaConfigTrial {
+    int left;
+    bool read;
+} MIKOtaConfigTrial;
+
+/* The spec caps a config rev at 64 characters (the reference registry emits
+ * 16); plus the NUL. A short buffer truncates, and a truncated echo never
+ * matches the current rev, so the registry re-sends the document forever. */
+#define MIK_OTA_REV_MAX 65
+
+/* Config error report */
+typedef struct MIKOtaConfigErrorReport {
+    char rev[MIK_OTA_REV_MAX];
+    char message[256];
+} MIKOtaConfigErrorReport;
+
+/* Stored config document representation */
+typedef struct MIKOtaStoredConfig {
+    char rev[MIK_OTA_REV_MAX]; /* empty string if none */
+    char version[32];          /* required */
+    uint8_t* doc_cbor;         /* CBOR-encoded document bytes, or NULL if absent/clear */
+    size_t doc_cbor_len;
+} MIKOtaStoredConfig;
+
+/* MIKOtaEnv struct: the platform seam for OTA policy and client state machine */
+struct MIKOtaEnv {
+    void* opaque;
+
+    /* ── HTTP ─────────────────────────────────────────────────────────── */
+    /* Start a request. Returns an opaque handle, or NULL when it could not be
+     * started (the client treats that as a failed round).
+     *
+     * Everything reachable from `req` and `cbs` is borrowed for the duration of
+     * this call only — url, headers and body included. A transport that outlives
+     * the call must copy what it needs before returning. */
+    void* (*http_request)(void* opaque, const MIKOtaHttpRequest* req,
+                          const MIKOtaHttpCallbacks* cbs);
+    /* Abandon an in-flight request. No further callbacks fire for it. */
+    void (*http_cancel)(void* opaque, void* req_handle);
+
+    /* ── KV store (mik.sys namespace) ─────────────────────────────────── */
+    /* Read a blob. With out_buf NULL, writes the required size into inout_len.
+     *
+     * Absent and failed are different answers and must not be merged: the config
+     * reader falls back to the build's manifest defaults on absent, but holds the
+     * last document it read on failure. Collapsing the two flips a live device
+     * onto defaults for a beat whenever a read is starved of heap — which is
+     * exactly when a TLS handshake is in flight. */
+    MIKOtaKvStatus (*kv_get_blob)(void* opaque, const char* key, uint8_t* out_buf,
+                                  size_t* inout_len);
+    bool (*kv_set_blob)(void* opaque, const char* key, const uint8_t* data, size_t len);
+    /* NOTE: the string and integer getters are still two-valued. Their callers
+     * (the retry-budget store) read a failure as absence, which hands the budget
+     * back a boot early. Same class of bug as the blob case above; worth the same
+     * treatment when the policy's error handling is revisited. */
+    bool (*kv_get_str)(void* opaque, const char* key, char* out_buf, size_t max_len);
+    bool (*kv_set_str)(void* opaque, const char* key, const char* val);
+    bool (*kv_get_i32)(void* opaque, const char* key, int32_t* out_val);
+    bool (*kv_set_i32)(void* opaque, const char* key, int32_t val);
+    bool (*kv_remove)(void* opaque, const char* key);
+
+    /* ── Install ops (firmware mik_ota.cpp) ────────────────────────────── */
+    bool (*stage_begin)(void* opaque, const char* checksum, size_t size, size_t* out_resume_offset,
+                        char* err_buf, size_t err_len);
+    bool (*stage_write)(void* opaque, const uint8_t* data, size_t len, char* err_buf,
+                        size_t err_len);
+    bool (*stage_finish)(void* opaque, int trial_boots, bool require_confirm, bool install_now,
+                         char* err_buf, size_t err_len, int* out_err_kind);
+    void (*stage_abort)(void* opaque);
+    void (*mark_valid)(void* opaque);
+    bool (*revert)(void* opaque, char* err_buf, size_t err_len);
+    bool (*running)(void* opaque, MIKOtaRunningBuild* out_running);
+    void (*reconcile)(void* opaque, MIKOtaReconcileOutcome* out_outcome);
+
+    /* ── System / Identity ────────────────────────────────────────────── */
+    bool (*identity)(void* opaque, MIKDeviceIdentity* out_id);
+    bool (*storage_free)(void* opaque, size_t* out_free); /* returns true if supported */
+    bool (*get_device_name)(void* opaque, int* out_rev, char* out_name, size_t name_len);
+    void (*set_device_name)(void* opaque, int rev, const char* name);
+    void (*restart)(void* opaque);
+    int64_t (*monotonic_ms)(void* opaque);
+    double (*random_fraction)(void* opaque); /* uniform [0, 1) */
+    void (*log)(void* opaque, int level, const char* fmt, ...);
+    bool (*read_app_version)(void* opaque, char* out_version, size_t ver_len);
+    /* The running build's mikro.app.json, as text. Returns a malloc'd
+     * NUL-terminated string the caller frees, or NULL when there is no manifest
+     * — which is how a build that never went through deploy reads. Allocated
+     * rather than copied into a caller buffer because a manifest carries the
+     * build's whole configDefaults and has no useful fixed bound. */
+    char* (*read_manifest)(void* opaque);
+};
+
+#ifdef __cplusplus
+}
+#endif