@mikrojs/native 0.17.0-pr-276.20260721233726 → 0.17.0

package/CMakeLists.txt

@@ -82,7 +82,7 @@ endif()
 include(cmake/mikrojs_bytecode.cmake)
 mikrojs_generate_bytecode(
     RUNTIME_DIR "${CMAKE_CURRENT_SOURCE_DIR}/runtime"
-    MODULES abort cbor env result schema fs http/helpers http/request i2c kv/nvs kv/rtc kv/shared module neopixel observable observable/lazy observable/operators ota pin pwm reader sleep spi sntp stdio stream sys test uart udp wifi
+    MODULES abort cbor env result schema fs http/helpers http/request i2c kv/nvs kv/rtc kv/shared module neopixel observable observable/lazy observable/operators ota ota/client pin pwm reader sleep spi sntp stdio stream sys test uart udp wifi
     MODULE_PREFIX "mikro"
     SYMBOL_PREFIX "mikro"
     TARGET gen_bytecode

package/include/mikrojs/private.h

@@ -340,11 +340,17 @@ void mik__repl_set_paused(bool paused);
  * log.txt, and replies MIK_MSG_OK. No-op (still OK) when file logging
  * is disabled. */
 #define MIK_CMD_LOG_RESET 0x2C
-/* Adopt a streamed .tgz build as the live app via the OTA install path,
- * establishing the rollback baseline (.ota-last-good.tgz). The build must
- * already be staged via DEPLOY_PUT("/.build.tgz", size) + PUT_CHUNK frames.
+/* Stage a streamed .tgz build for install at the next boot. The build must
+ * already be staged via DEPLOY_PUT("/.build.tgz", size) + PUT_CHUNK frames;
+ * the device verifies its SHA-256 now and the boot reconcile installs it on
+ * a clean heap (adopt mode: comes up GOOD, no trial, no rollback baseline).
  * Payload: u16le checksum_len | checksum bytes. */
 #define MIK_CMD_DEPLOY_BUILD 0x2D
+/* Report and clear the outcome of the last adopt-mode boot install. No
+ * payload. Reply is MIK_MSG_OK with:
+ *   u8 status (0 none | 1 ok | 2 fail) | u16le chk_len | chk
+ *   | u16le reason_len | reason | u16le detail_len | detail. */
+#define MIK_CMD_DEPLOY_RESULT 0x2E
 
 #define MIK_CMD_CONFIG_LIST 0x40
 #define MIK_CMD_CONFIG_SET 0x41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/native",
-  "version": "0.17.0-pr-276.20260721233726",
+  "version": "0.17.0",
   "description": "Mikro.js C++ runtime library and Node.js native addon",
   "keywords": [
     "esp32",
@@ -64,6 +64,7 @@
     "./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",
@@ -85,14 +86,14 @@
     "cmake-js": "^8.0.0",
     "node-addon-api": "^8.7.0",
     "node-gyp-build": "^4.8.4",
-    "@mikrojs/quickjs": "0.17.0-pr-276.20260721233726+1bcc126"
+    "@mikrojs/quickjs": "0.17.0"
   },
   "devDependencies": {
     "@swc/core": "^1.15.30",
     "@types/node": "^24.12.2",
     "esbuild": "^0.28.0",
     "terser": "^5.46.2",
-    "@mikrojs/registry": "0.17.0-pr-276.20260721233726+1bcc126"
+    "@mikrojs/registry": "0.17.0"
   },
   "engines": {
     "node": ">=24.0.0"

package/runtime/ota/client-impl.ts

@@ -0,0 +1,590 @@
+// Internal: the OTA client state machine behind `mikro/ota/client`. Bundled
+// into ota/client.js; not exposed as its own subpath. Exists as a seam so host
+// tests can drive the whole client against fakes — no hardware, no registry,
+// no real restart.
+
+import type {Request, RequestError} from 'mikro/http/helpers'
+import {err, ok} from 'mikro/result'
+
+import type {CborError} from '../cbor/types.js'
+import type {Result} from '../result/types.js'
+import type {DeviceName} from '../sys/types.js'
+import type {Diagnostic, Offer, Ota, OtaError, Update} from './types.js'
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+
+/** Immutable facts about this device and the firmware under it. */
+export interface DeviceIdentity {
+  deviceId: string
+  /** Firmware version string, and the hash of that image. A build published
+   *  against a different firmware is withheld rather than offered. */
+  firmware: string
+  firmwareHash: string
+  /** QuickJS bytecode version the linked engine reads; a build compiled for
+   *  another one cannot run here. */
+  bytecode: number
+}
+
+/**
+ * Every effect the client can have on the world, in one record. Nothing below
+ * `createOtaClient` reaches for a runtime import — effects arrive here, so the
+ * policy can run against a fake with no hardware and no risk of a real
+ * restart().
+ */
+export interface ClientIo {
+  /** Wall-clock delay. The only clock the client has. */
+  sleep(ms: number): Promise<void>
+  /** HTTP. The only network the client has. */
+  request: Request
+  /** Uniform [0, 1). Injected so tests can pin the jitter. */
+  random(): number
+  /** Serial diagnostics. Format string and args pass through untouched. */
+  log(level: LogLevel, format: string, ...args: unknown[]): void
+  /** CBOR codec for the check-in wire. */
+  encode(value: unknown): Result<Uint8Array, CborError>
+  decode(data: Uint8Array): Result<unknown, CborError>
+
+  /** The `mikro/ota` policy surface (staging, trials, retry budgets). */
+  ota: Ota
+  identity(): DeviceIdentity
+  /** Bytes free on the partition a build is staged onto, or undefined when the
+   *  platform cannot report it. */
+  storageFree(): number | undefined
+  deviceName(): DeviceName
+  setDeviceName(name: DeviceName): void
+  restart(): never
+}
+
+export interface CheckOptions {
+  /** Budget for the check-in round trip. Default 10s. */
+  checkinTimeoutMs?: number
+  /** Budget for the build download. Separate from the check-in's because it is
+   *  a total wallclock deadline that cancels the transfer mid-stream, and an
+   *  image needs orders of magnitude more of it than a check-in body does.
+   *  Default 5m. */
+  downloadTimeoutMs?: number
+  /** Require a completed check-in (via `ota.confirm()`, which the client fires
+   *  itself) before an installed build is kept. Default true. */
+  requireConfirm?: boolean
+  /** Clean boots a trial may consume before an unconfirmed build reverts.
+   *  A deep-sleep wake counts as a clean boot, so wake-cycle devices on flaky
+   *  networks should raise this above the default 1. */
+  trialBoots?: number
+}
+
+/** Runs after its round settles — after the check and any download, and before
+ *  an auto-restart — so the network brought up in `beforeCheck` can go down. */
+export type Teardown = () => void | Promise<void>
+
+export interface WatchOptions extends CheckOptions {
+  /** Steady interval between rounds, end-of-round to start-of-next. Default 30m. */
+  checkinIntervalMs?: number
+  /** Delay before the first round. Default 5s. */
+  initialDelayMs?: number
+  /** Interval after a failed round, capped at `checkinIntervalMs`. Default 1m. */
+  retryAfterFailureMs?: number
+  /** Spread every scheduled sleep by ±10%, so a fleet that lost power together
+   *  does not check in phase-locked forever. Default true; pass false for
+   *  exact intervals (a demo watching for the update to land, a single
+   *  device where the spread only delays it). */
+  jitter?: boolean
+  /** Bring the network up for one round. `err` skips the round (retried at the
+   *  failure interval) and no teardown runs — partial setup is the hook's own
+   *  job to unwind. State shared with the teardown stays in this one scope. */
+  beforeCheck?(): Promise<Result<Teardown, unknown>>
+}
+
+export interface Watcher {
+  /** Prevent future rounds and cancel the pending sleep. An in-flight round
+   *  completes, but a build it stages no longer auto-restarts — it stays armed
+   *  for the next natural reboot. */
+  stop(): void
+}
+
+/** Why an offered build was not armed. Each is the policy working as intended;
+ *  the distinction is logged and returned because the app's next move differs. */
+export type DeclineReason =
+  | 'trial-pending'
+  | 'current'
+  | 'abandoned'
+  | 'exhausted'
+  | 'download-failed'
+  | 'install-failed'
+
+/** The check-in never completed. */
+export type CheckError = RequestError | CborError | {name: 'Status'; status: number}
+
+export type CheckResult =
+  /** Build downloaded, verified, and armed. The app restarts when ready. */
+  | {status: 'staged'; offer: Offer}
+  | {status: 'up-to-date'}
+  /** An offer arrived but was not armed. */
+  | {status: 'not-staged'; reason: DeclineReason; error?: OtaError}
+  /** Transient: the check-in did not complete, so the running trial (if any)
+   *  was not confirmed. */
+  | {status: 'failed'; error: CheckError}
+  /** The registry rejected the update key (HTTP 401). Permanent until
+   *  re-enrollment over the cable. */
+  | {status: 'unauthorized'}
+  | {status: 'not-enrolled'}
+
+export interface OtaClient {
+  check(options?: CheckOptions): Promise<CheckResult>
+  watch(options?: WatchOptions): Watcher
+}
+
+const DEFAULT_CHECKIN_TIMEOUT_MS = 10_000
+const DEFAULT_DOWNLOAD_TIMEOUT_MS = 300_000
+const DEFAULT_INTERVAL_MS = 30 * 60_000
+const DEFAULT_INITIAL_DELAY_MS = 5_000
+const DEFAULT_RETRY_MS = 60_000
+
+/** What the watch 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 (a dead key mustn't hammer the
+ *  registry every retry interval forever). */
+type NextRound = 'soon' | 'later'
+
+interface Enrollment {
+  registryUrl: string
+  bearer: string
+}
+
+export function createOtaClient(io: ClientIo): OtaClient {
+  // One check at a time: staging is a single native session, and two
+  // interleaved check-ins would corrupt it. Later calls queue behind the
+  // running one; each still gets its own result.
+  let chain: Promise<unknown> = Promise.resolve()
+
+  // reconcile() clears its report as it reads, so it runs once per boot and
+  // the report is held here until a check-in actually delivers it — a failed
+  // first check-in no longer loses it.
+  let reconciled = false
+  let lastInstall: Diagnostic | undefined
+
+  let warnedInsecure = false
+
+  function enqueue<T>(task: () => Promise<T>): Promise<T> {
+    const run = chain.then(task)
+    chain = run.then(
+      () => undefined,
+      () => undefined,
+    )
+    return run
+  }
+
+  function enrollment(): Enrollment | undefined {
+    // Written as a pair over the cable by `mikro ota enroll`; enrollment is the
+    // opt-in. Update keys never arrive over the network.
+    const registryUrl = io.ota.registry()
+    const bearer = io.ota.bearer()
+    if (registryUrl === undefined || bearer === undefined) return undefined
+    return {registryUrl, bearer}
+  }
+
+  function reconcileOnce(): void {
+    if (reconciled) return
+    reconciled = true
+    const report = io.ota.reconcile()
+    lastInstall = report.lastInstall
+    if (report.reverted) {
+      io.log('warn', 'ota: previous update failed its trial and was rolled back')
+    }
+    if (report.installed) {
+      io.log('info', 'ota: installed build %s on this boot', report.installed.slice(0, 12))
+    }
+  }
+
+  async function runCheck(enrolled: Enrollment, options: CheckOptions): Promise<CheckResult> {
+    const {registryUrl, bearer} = enrolled
+    const allowInsecure = isPrivateHttp(registryUrl)
+    if (allowInsecure && !warnedInsecure) {
+      // Every boot, not once at enrollment: a device that quietly runs a
+      // forgeable update channel should say so for as long as it does.
+      warnedInsecure = true
+      io.log(
+        'warn',
+        'ota: registry is http:// on a private network — updates are NOT authenticated',
+      )
+    }
+    reconcileOnce()
+
+    const running = io.ota.running()
+    const identity = io.identity()
+    const named = io.deviceName()
+    const free = io.storageFree()
+    // The shape is a contract with the registry's /api/v1/checkin: these are
+    // the inputs it arbitrates an offer from. Optional keys are omitted, not
+    // sent as undefined — the registry reads an absent `free` as "no figure to
+    // report", and JSON clients drop the key the same way.
+    const report = {
+      ...identity,
+      running,
+      // The name pair: `[rev]` when cleared, `[rev, name]` otherwise. Sent
+      // every time so a lost response settles on the next check-in.
+      name: named.name === undefined ? [named.rev] : [named.rev, named.name],
+      ...(free === undefined ? {} : {free}),
+      ...(lastInstall === undefined ? {} : {lastInstall}),
+    }
+    io.log(
+      'debug',
+      'ota: checking %s (running %s v%s, bytecode %d, fw %s)',
+      `${registryUrl}/api/v1/checkin`,
+      running.checksum?.slice(0, 12) ?? 'none',
+      running.version ?? '?',
+      identity.bytecode,
+      identity.firmware,
+    )
+
+    const encoded = io.encode(report)
+    if (!encoded.ok) {
+      io.log('error', 'ota: could not encode the check-in report', encoded.error)
+      return {status: 'failed', error: encoded.error}
+    }
+    const res = await io.request(`${registryUrl}/api/v1/checkin`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/cbor',
+        accept: 'application/cbor',
+        authorization: `Bearer ${bearer}`,
+      },
+      timeoutMs: options.checkinTimeoutMs ?? DEFAULT_CHECKIN_TIMEOUT_MS,
+      body: encoded.value,
+    })
+    if (!res.ok) {
+      io.log('error', 'ota: checkin failed', res.error)
+      return {status: 'failed', error: res.error}
+    }
+    const response = res.value
+    if (response.status === 401) {
+      // The update key no longer authenticates (rotated, device deleted).
+      // Only a 401 means this. There is no fallback secret — re-enroll over
+      // the cable. Release the connection before returning.
+      await response.close()
+      io.log(
+        'error',
+        'ota: registry rejected the update key; re-enroll with `mikro ota enroll --re-enroll`',
+      )
+      return {status: 'unauthorized'}
+    }
+    if (response.status === 415) {
+      // The wire is CBOR-only by design; there is no JSON fallback to hide a
+      // registry that predates it.
+      await response.close()
+      io.log(
+        'error',
+        'ota: registry does not accept CBOR check-ins; upgrade the registry to a version that supports application/cbor',
+      )
+      return {status: 'failed', error: {name: 'Status', status: 415}}
+    }
+    if (!response.ok) {
+      // Release the connection before the heap-sensitive image request — an
+      // abandoned response holds its native slot and TLS buffers until its
+      // timeout fires.
+      await response.close()
+      io.log('error', 'ota: checkin returned status %d', response.status)
+      return {status: 'failed', error: {name: 'Status', status: response.status}}
+    }
+    const raw = await response.bytes()
+    if (!raw.ok) {
+      io.log('error', 'ota: reading the checkin response failed', raw.error)
+      return {status: 'failed', error: raw.error}
+    }
+    const body = io.decode(raw.value)
+    if (!body.ok) {
+      io.log('error', 'ota: invalid checkin response body', body.error)
+      return {status: 'failed', error: body.error}
+    }
+
+    // The check-in completed: the cached install report is delivered.
+    lastInstall = undefined
+
+    // Confirm before applying: a completed check-in is the whole health signal
+    // requireConfirm waits for, whether or not an offer follows — and resolving
+    // the trial now lets an offer published during it stage in this same pass
+    // (applyOffer skips every offer while a trial is unresolved).
+    if (running.trial) {
+      io.log('info', 'ota: check-in completed — confirming this build as healthy')
+    }
+    io.ota.confirm()
+
+    const renamed = nameFrom(body.value)
+    if (renamed !== undefined) {
+      io.setDeviceName(renamed)
+      io.log('info', 'ota: registry renamed this device to %s', renamed.name ?? '(no name)')
+    }
+
+    const offer = io.ota.parseOffer(body.value, {allowInsecure})
+    if (offer === undefined) {
+      io.log('debug', 'ota: up to date, running the latest build')
+      return {status: 'up-to-date'}
+    }
+    io.log(
+      'info',
+      'ota: update available (%s, %d bytes); downloading',
+      offer.checksum.slice(0, 12),
+      offer.size,
+    )
+    const applied = await io.ota.applyOffer(
+      offer,
+      (update) => download(enrolled, options, offer, update),
+      {
+        requireConfirm: options.requireConfirm ?? true,
+        trialBoots: options.trialBoots ?? 1,
+      },
+    )
+    if (!applied.ok) {
+      const reason: DeclineReason =
+        applied.error.name === 'DownloadFailed' ? 'download-failed' : 'install-failed'
+      io.log('error', 'ota: update failed', applied.error)
+      return {status: 'not-staged', reason, error: applied.error}
+    }
+    if (applied.value === 'staged') {
+      io.log('info', 'ota: download verified and staged')
+      return {status: 'staged', offer}
+    }
+    // Not staged, not an error — applyOffer declined the offer:
+    //   current       already running this build
+    //   trial-pending the running build hasn't resolved its trial (nearly
+    //                 unreachable: the confirm above resolves it first)
+    //   abandoned     the build is corrupt and won't be retried
+    //   exhausted     the retry budget for this build is spent until next boot
+    io.log('info', 'ota: offer not staged (%s)', applied.value)
+    return {status: 'not-staged', reason: applied.value}
+  }
+
+  /** The download pump: stream the build straight into the staging area,
+   *  resuming an interrupted transfer with a Range request. Chunked on purpose:
+   *  buffering the whole build would put ~2x its size on the heap. */
+  async function download(
+    enrolled: Enrollment,
+    options: CheckOptions,
+    offer: Offer,
+    update: Update,
+  ): Promise<Result<void, {message: string}>> {
+    const from = update.resumeOffset
+    // Already complete: a finish that failed transiently leaves every byte on
+    // flash and the offer pending, so resuming would ask for `bytes=<size>-`
+    // and take the 416 as a failed download forever. Hand it straight back to
+    // re-verify.
+    if (from >= offer.size) return ok()
+    if (from > 0) {
+      io.log('info', 'ota: resuming download from byte %d of %d', from, offer.size)
+    }
+    // Same-origin only. `offer.url` may legitimately point at another host (a
+    // CDN, an object store), so the update key goes out only when the download
+    // is on the registry's own origin. A build fetched elsewhere is a public
+    // artifact the checksum vouches for; a store that needs auth carries it in
+    // a signed url instead.
+    const headers: Record<string, string> = {}
+    if (from > 0) headers.range = `bytes=${from}-`
+    if (sameOrigin(offer.url, enrolled.registryUrl)) {
+      headers.authorization = `Bearer ${enrolled.bearer}`
+    }
+    const res = await io.request(offer.url, {
+      headers,
+      timeoutMs: options.downloadTimeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS,
+    })
+    if (!res.ok) {
+      return err({message: `download failed: ${describeRequestError(res.error)}`})
+    }
+    const response = res.value
+    if (!response.ok) {
+      await response.close()
+      return err({message: `download returned status ${response.status}`})
+    }
+    // A server free to ignore Range answers 200 with the whole build. Drop the
+    // prefix we already hold rather than failing, which would spend a retry
+    // for nothing.
+    let skip = response.status === 206 ? 0 : from
+    for await (const chunk of response.body) {
+      if (!chunk.ok) {
+        await response.close()
+        return err({message: `reading the download failed: ${describeRequestError(chunk.error)}`})
+      }
+      let bytes = chunk.value
+      if (skip > 0) {
+        if (bytes.length <= skip) {
+          skip -= bytes.length
+          continue
+        }
+        bytes = bytes.subarray(skip)
+        skip = 0
+      }
+      const written = update.write(bytes)
+      if (!written.ok) {
+        await response.close()
+        return written
+      }
+    }
+    return ok()
+  }
+
+  function check(options: CheckOptions = {}): Promise<CheckResult> {
+    const enrolled = enrollment()
+    if (enrolled === undefined) {
+      return Promise.resolve({status: 'not-enrolled'})
+    }
+    return enqueue(() => runCheck(enrolled, options))
+  }
+
+  function watch(options: WatchOptions = {}): Watcher {
+    const maybeEnrolled = enrollment()
+    if (maybeEnrolled === undefined) {
+      io.log('info', 'ota: device not enrolled; run `mikro ota enroll` to enable OTA updates')
+      return {stop: () => undefined}
+    }
+    // Explicitly typed: the narrowing above does not reach into the hoisted
+    // round() declaration below.
+    const enrolled: Enrollment = maybeEnrolled
+    const intervalMs = options.checkinIntervalMs ?? DEFAULT_INTERVAL_MS
+    const retryMs = Math.min(options.retryAfterFailureMs ?? DEFAULT_RETRY_MS, intervalMs)
+
+    let stopped = false
+    let cancelSleep: (() => void) | undefined
+
+    // ±10% so a power-cut fleet doesn't stay phase-locked on the registry.
+    const jitterOn = options.jitter ?? true
+    function jitter(ms: number): number {
+      if (!jitterOn) return ms
+      return Math.round(ms * (0.9 + io.random() * 0.2))
+    }
+
+    function pause(ms: number): Promise<void> {
+      return new Promise((resolve) => {
+        cancelSleep = resolve
+        void io.sleep(jitter(ms)).then(resolve)
+      })
+    }
+
+    async function round(): Promise<NextRound> {
+      let teardown: Teardown | undefined
+      if (options.beforeCheck) {
+        let setup: Result<Teardown, unknown>
+        try {
+          setup = await options.beforeCheck()
+        } catch (e) {
+          setup = err(e)
+        }
+        if (!setup.ok) {
+          io.log('warn', 'ota: beforeCheck failed; skipping this check', setup.error)
+          return 'soon'
+        }
+        teardown = setup.value
+      }
+
+      // Contain OTA faults: an uncaught throw (e.g. an OOM from the native
+      // HTTP layer under a low-heap stream) must not bubble out of the
+      // detached loop. A crashed check is just a check that didn't complete.
+      let outcome: CheckResult | undefined
+      try {
+        outcome = await enqueue(() => runCheck(enrolled, options))
+      } catch (e) {
+        io.log('error', 'ota: check crashed', e)
+      }
+
+      // Teardown before any restart: the round is over either way, and the
+      // hook's invariant — teardown runs whenever setup succeeded — must not
+      // depend on what the check found.
+      if (teardown !== undefined) {
+        try {
+          await teardown()
+        } catch (e) {
+          io.log('warn', 'ota: teardown failed', e)
+        }
+      }
+
+      if (outcome === undefined) return 'soon'
+      if (outcome.status === 'staged') {
+        if (stopped) {
+          // stop() won the race: leave the build armed for the next natural
+          // reboot instead of restarting under the caller.
+          io.log('info', 'ota: update staged; watcher stopped, restart deferred')
+          return 'later'
+        }
+        io.log('info', 'ota: staged; restarting to install')
+        io.restart() // never returns
+      }
+      return outcome.status === 'failed' ? 'soon' : 'later'
+    }
+
+    async function loop(): Promise<void> {
+      await pause(options.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS)
+      while (!stopped) {
+        const next = await round()
+        if (stopped) return
+        await pause(next === 'later' ? intervalMs : retryMs)
+      }
+    }
+
+    // Detached: never awaited by the caller, so the app keeps running
+    // regardless of OTA outcome. round() contains every throw, so this
+    // promise cannot reject.
+    void loop()
+
+    return {
+      stop: () => {
+        stopped = true
+        cancelSleep?.()
+      },
+    }
+  }
+
+  return {check, watch}
+}
+
+/** Render a RequestError into prose. `DownloadFn`'s contract carries only a
+ *  `message` string forward into the `DownloadFailed` the policy reports, so
+ *  this line is all that survives to explain a failed download on serial —
+ *  include the underlying message, not just the variant name. */
+function describeRequestError(error: RequestError): string {
+  return 'message' in error && error.message !== '' ? `${error.name}: ${error.message}` : error.name
+}
+
+/**
+ * The name pair a check-in response carries, as `[rev, name]` (or `[rev]` when
+ * it was cleared), or undefined when there is nothing to adopt. No `name` field
+ * means "no change" and never "clear it": a response lost after the registry
+ * adopted the device's own name looks exactly the same as one that never
+ * arrived, and re-sending the pair next check-in settles it.
+ */
+export function nameFrom(body: unknown): DeviceName | undefined {
+  if (typeof body !== 'object' || body === null) return undefined
+  const pair = (body as {name?: unknown}).name
+  if (!Array.isArray(pair)) return undefined
+  const rev = pair[0]
+  if (typeof rev !== 'number' || !Number.isInteger(rev) || rev < 0) return undefined
+  const value = pair[1]
+  return typeof value === 'string' && value !== '' ? {rev, name: value} : {rev}
+}
+
+/** 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. Used
+ *  to decide whether the update key may ride the download request. */
+export function sameOrigin(a: string, b: string): boolean {
+  const origin = (url: string): string | undefined => {
+    const sep = url.indexOf('://')
+    if (sep < 0) return undefined
+    const start = sep + 3
+    const end = url.indexOf('/', start)
+    const authority = end < 0 ? url.slice(start) : url.slice(start, end)
+    return authority === '' ? undefined : (url.slice(0, start) + authority).toLowerCase()
+  }
+  const left = origin(a)
+  return left !== undefined && left === origin(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. */
+export function isPrivateHttp(url: string): boolean {
+  if (!url.startsWith('http://')) return false
+  const host = (url.slice(7).split('/')[0] ?? '').split(':')[0] ?? ''
+  if (host === 'localhost' || host.endsWith('.local')) return true
+  const p = host.split('.').map((s) => parseInt(s, 10))
+  if (p.length !== 4 || p.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return false
+  if (p[0] === 10 || p[0] === 127) return true
+  if (p[0] === 192 && p[1] === 168) return true
+  if (p[0] === 169 && p[1] === 254) return true
+  return p[0] === 172 && p[1]! >= 16 && p[1]! <= 31
+}

package/runtime/ota/client.ts

@@ -0,0 +1,77 @@
+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'
+
+import {type ClientIo, createOtaClient, type LogLevel} from './client-impl.js'
+
+export type {
+  CheckError,
+  CheckOptions,
+  CheckResult,
+  DeclineReason,
+  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)
+
+/**
+ * One-shot update check for wake-cycle apps: check in with the registry,
+ * confirm the running trial, and download + stage any offered build. Never
+ * restarts — on `{status: 'staged'}` the app calls `restart()` once its
+ * in-flight work is done. Connectivity is the app's business: call this with
+ * the network already up.
+ */
+export const check = client.check
+
+/**
+ * Periodic update checks for always-on apps: a detached background loop that
+ * checks on a jittered cadence, retries sooner after failures, and restarts
+ * the device after staging a build. Use `beforeCheck` to bring the network up
+ * 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

package/runtime/ota/ota.ts

@@ -44,9 +44,9 @@ const store: OtaStore = {
 }
 
 // Written as a pair to mik.sys by `mikro ota enroll`: the registry url and
-// the device credential that authenticates against it.
+// the device update key that authenticates against it.
 function bearer(): string | undefined {
-  const v = sysGet('ota.credential')
+  const v = sysGet('ota.updateKey')
   return typeof v === 'string' ? v : undefined
 }
 

package/runtime/ota/policy.ts

@@ -62,10 +62,10 @@ interface OtaDeps {
   store: OtaStore
   /** Live app version from /app/package.json, or undefined if unreadable. */
   readAppVersion(): string | undefined
-  /** The check-in bearer: the device credential from the system store, or
+  /** The check-in bearer: the device update key from the system store, or
    *  undefined on an un-enrolled device. */
   bearer(): string | undefined
-  /** The registry url the credential was minted against, or undefined. */
+  /** The registry url the update key was issued against, or undefined. */
   registry(): string | undefined
 }
 
@@ -116,7 +116,7 @@ export function parseOffer(raw: unknown, opts?: {allowInsecure?: boolean}): Offe
   // name where the build lives — a CDN or object store on another host, a signed
   // url with its own query. Integrity is the checksum, verified over the whole
   // download before install, so a wrong host yields a failed install, never a
-  // bad one; and the credential is the caller's to confine (the reference client
+  // bad one; and the update key is the caller's to confine (the reference client
   // attaches it only when the url is same-origin with the registry).
   return {url: o.url, checksum: o.checksum, size: o.size}
 }

package/runtime/ota/types.ts

@@ -133,12 +133,12 @@ export interface Ota {
   confirm(): void
   /** Reinstall the previous build immediately. */
   revert(): Result<void, OtaInstallError>
-  /** The check-in bearer: the device credential written at enrollment
+  /** The check-in bearer: the device update key written at enrollment
    *  (`mikro ota enroll`), or `undefined` on an un-enrolled device. Read-only:
-   *  credentials are provisioned over serial, never delivered in-band. */
+   *  update keys are provisioned over serial, never delivered in-band. */
   bearer(): string | undefined
   /** The registry url the device was enrolled against, written next to the
-   *  credential at enrollment, or `undefined` on an un-enrolled device. */
+   *  update key at enrollment, or `undefined` on an un-enrolled device. */
   registry(): string | undefined
 }
 

package/src/mik_repl.cpp

@@ -32,9 +32,11 @@ static bool repl_protocol_mode = false;
 static bool repl_paused = false;
 static bool repl_async_skipped = false;  /* set when eval bails on paused async */
 static MIKReplTransport* repl_transport = nullptr;
-/* Sized to hold the base map plus the longest `[rev, name]` pair the platform
- * name setter accepts, so a named device never has to drop its name. */
-static uint8_t ready_buf[256];
+/* Sized to hold the base map plus a maximum-length npm package name as the
+ * `fw` identity (214 chars), with room to spare for a typical `[rev, name]`
+ * pair. A max-length identity combined with a near-max device name can still
+ * exceed this; refresh_ready then drops the name (never the identity). */
+static uint8_t ready_buf[384];
 static size_t ready_len = 0;
 
 /* Transient flag: set by MIK_ProtocolExit to break the current ServeLoop
@@ -879,7 +881,12 @@ static std::vector<uint8_t> proto_complete(JSContext* ctx, const char* partial,
 /* ── Protocol-mode REPL ──────────────────────────────────────────── */
 
 /* Fills ready_buf/ready_len with CBOR device info:
- * {"chip": tstr, "id": tstr, "v": tstr, "name": tstr (only when named)}.
+ * {"chip": tstr, "id": tstr, "v": tstr, "fw": tstr (when built with
+ * MIK_FW_NAME), "name": tstr (only when named)}.
+ * `fw` is the firmware identity (the firmware project's package name). The
+ * host only auto-flashes its bundled prebuilt over a device whose identity
+ * matches that prebuilt; omitting it reads as firmware predating identity
+ * reporting, which the host treats as its own bundled firmware.
  * `name` carries the raw `[rev, name]` pair from mik.sys, so the host reads the
  * name and its revision together and can never see them out of step. Omitted
  * entirely when the device has never been named, which the host reads as
@@ -896,16 +903,20 @@ static void refresh_ready(MIKReplTransport* transport);
 /* Encodes the MSG_READY map into buf, or measures it when buf is null. Returns
  * the length the encoding needs, which exceeds cap when it did not fit. */
 static size_t encode_ready(uint8_t* buf, size_t cap, const char* chip, const char* id,
-                           const char* version, const char* name) {
+                           const char* version, const char* fw, const char* name) {
     nanocbor_encoder_t enc;
     nanocbor_encoder_init(&enc, buf, cap);
-    nanocbor_fmt_map(&enc, name ? 4 : 3);
+    nanocbor_fmt_map(&enc, 3 + (fw ? 1 : 0) + (name ? 1 : 0));
     nanocbor_put_tstr(&enc, "chip");
     nanocbor_put_tstr(&enc, chip);
     nanocbor_put_tstr(&enc, "id");
     nanocbor_put_tstr(&enc, id);
     nanocbor_put_tstr(&enc, "v");
     nanocbor_put_tstr(&enc, version);
+    if (fw) {
+        nanocbor_put_tstr(&enc, "fw");
+        nanocbor_put_tstr(&enc, fw);
+    }
     if (name) {
         nanocbor_put_tstr(&enc, "name");
         nanocbor_put_tstr(&enc, name);
@@ -922,6 +933,12 @@ static void refresh_ready(MIKReplTransport* transport) {
         MIK_FW_VERSION;
 #else
         "0.0.0-dev";
+#endif
+    const char* fw =
+#ifdef MIK_FW_NAME
+        MIK_FW_NAME;
+#else
+        nullptr;
 #endif
     const char* name =
         MIK_GetPlatform()->get_device_name ? MIK_GetPlatform()->get_device_name() : nullptr;
@@ -929,11 +946,16 @@ static void refresh_ready(MIKReplTransport* transport) {
      * end but still reports the length it would have needed, so ready_len must
      * come from a run that actually fit: sending the measured length would read
      * past ready_buf. Drop `name` rather than truncate it, since a partial pair
-     * decodes as a different name at the host. */
-    if (name && encode_ready(nullptr, 0, chip, id, version, name) > sizeof(ready_buf)) {
+     * decodes as a different name at the host. `name` goes before `fw`: a
+     * dropped `fw` reads as the host's own bundled firmware, re-enabling the
+     * auto-reflash the identity exists to prevent. */
+    if (name && encode_ready(nullptr, 0, chip, id, version, fw, name) > sizeof(ready_buf)) {
         name = nullptr;
     }
-    ready_len = encode_ready(ready_buf, sizeof(ready_buf), chip, id, version, name);
+    if (fw && encode_ready(nullptr, 0, chip, id, version, fw, name) > sizeof(ready_buf)) {
+        fw = nullptr;
+    }
+    ready_len = encode_ready(ready_buf, sizeof(ready_buf), chip, id, version, fw, name);
     if (ready_len > sizeof(ready_buf)) ready_len = 0;
 }