@mikrojs/native 0.16.0 → 0.17.0-next.20260722220623

package/CMakeLists.txt

@@ -49,6 +49,7 @@ set(MIKROJS_CORE_SOURCES
     src/mik_sys.cpp
     src/mik_repl.cpp
     src/mik_app_config.cpp
+    src/mik_app_store.cpp
     src/mik_udp.cpp
     src/mik_observable.cpp
 )
@@ -81,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 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 pin pwm reader sleep spi sntp stdio stream sys test uart udp wifi
     MODULE_PREFIX "mikro"
     SYMBOL_PREFIX "mikro"
     TARGET gen_bytecode
@@ -163,6 +164,7 @@ if(BUILD_TESTING)
         test/abort_test.cpp
         test/repl_protocol_test.cpp
         test/app_config_test.cpp
+        test/app_store_test.cpp
         test/oom_test.cpp
         test/reader_test.cpp
         test/stream_test.cpp

package/include/mikrojs/app_store.h

@@ -0,0 +1,23 @@
+#pragma once
+
+/* Portable app-store engine: atomic promotion of a staged app into the live
+ * slot, plus crash recovery. On-disk layout relative to a base path:
+ *   <base>/app          live app
+ *   <base>/.deploy-tmp  staging dir (new app built at <base>/.deploy-tmp/app)
+ *   <base>/.deploy-old  rollback copy of the previous live app
+ * POSIX only (rename/stat/dirent); no ESP-IDF, no QuickJS. */
+
+enum MIKAppCommitResult {
+    MIK_APP_COMMIT_OK = 0,
+    MIK_APP_COMMIT_STASH_FAILED,  // rename <base>/app -> <base>/.deploy-old failed
+    MIK_APP_COMMIT_SWAP_FAILED,   // rename <base>/.deploy-tmp/app -> <base>/app failed
+};
+
+/* Promote the staged app at <base>/.deploy-tmp/app into <base>/app. When
+ * `erased` is true the live app was already removed, so no rollback copy is
+ * stashed. On failure the caller is expected to clean up staging. */
+MIKAppCommitResult mik__app_commit(const char* base, bool erased);
+
+/* Recover from an interrupted commit: restore the rollback copy if the live
+ * app is missing, otherwise drop leftover staging/rollback dirs. */
+void mik__app_recover(const char* base);

package/include/mikrojs/platform.h

@@ -64,6 +64,15 @@ typedef struct MIKPlatform {
      *  original 6 MAC bytes. The returned pointer must remain valid for the
      *  lifetime of the platform. */
     const char* (*get_device_id)(void);
+    /** The device's stored name, or NULL when it has never been named. The
+     *  value is opaque here: it is the `[rev, name]` pair the OTA check-in
+     *  carries, kept as one string so the name and its revision can never be
+     *  stored out of step. Backed by NVS on ESP32; host platforms keep it in
+     *  memory for the process. The returned pointer must remain valid until
+     *  the next set_device_name call. */
+    const char* (*get_device_name)(void);
+    /** Store the name pair, replacing any previous value. */
+    void (*set_device_name)(const char* value);
     /** Reason the chip last reset, as a stable lowercase string. On ESP32
      *  this maps esp_reset_reason(): "power-on", "software", "panic",
      *  "watchdog", "interrupt-watchdog", "task-watchdog", "brownout",

package/include/mikrojs/private.h

@@ -340,10 +340,21 @@ 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.
+ * Payload: u16le checksum_len | checksum bytes. */
+#define MIK_CMD_DEPLOY_BUILD 0x2D
 
 #define MIK_CMD_CONFIG_LIST 0x40
 #define MIK_CMD_CONFIG_SET 0x41
 #define MIK_CMD_CONFIG_DELETE 0x42
+/* KV provisioning: write/delete a `mikro/kv/nvs` string value over serial
+ * (stored as a CBOR text-string blob in the "mik.kv" namespace, the same
+ * encoding the native kv module uses). Device provisioning state, unlike
+ * env config it is never synced or cleared by deploys. */
+#define MIK_CMD_KV_SET 0x43
+#define MIK_CMD_KV_DELETE 0x44
 
 /* Env entry flags */
 #define MIK_ENV_FLAG_SECRET 0x01

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/native",
-  "version": "0.16.0",
+  "version": "0.17.0-next.20260722220623",
   "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/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",
@@ -84,13 +85,14 @@
     "cmake-js": "^8.0.0",
     "node-addon-api": "^8.7.0",
     "node-gyp-build": "^4.8.4",
-    "@mikrojs/quickjs": "0.16.0"
+    "@mikrojs/quickjs": "0.17.0-next.20260722220623+e03f4a6"
   },
   "devDependencies": {
     "@swc/core": "^1.15.30",
     "@types/node": "^24.12.2",
     "esbuild": "^0.28.0",
-    "terser": "^5.46.2"
+    "terser": "^5.46.2",
+    "@mikrojs/registry": "0.17.0-next.20260722220623+e03f4a6"
   },
   "engines": {
     "node": ">=24.0.0"

package/runtime/internal.d.ts

@@ -8,7 +8,7 @@ type NR<T> = {ok: true; value: T} | {ok: false; error: {code: number; message: s
 // import them. Keep these in sync with the MODULES list in the firmware +
 // @mikrojs/native CMakeLists.
 declare module 'mikro/kv/shared' {
-  export {KVError, makeCreateValue, type NativeKvFns} from './kv/shared.js'
+  export {KVError, makeCreateValue, mapKvError, type NativeKvFns} from './kv/shared.js'
 }
 
 declare module 'mikro/observable/lazy' {
@@ -44,6 +44,7 @@ declare module 'native:mikro/sys' {
     systemTotal: number
     systemLargestFree: number
   }
+  export function storageUsage(): {total: number; used: number; free: number} | undefined
   export function jsMemoryUsage(): JsMemoryUsage
   export function gc(): void
   /** Unload the module whose namespace object is `ns`; returns the number of
@@ -52,6 +53,10 @@ declare module 'native:mikro/sys' {
   /** True if `ns` is the namespace of a loaded, non-anchored (non-builtin) module. */
   export function isUnloadableNamespace(ns: object): boolean
   export function activeTimers(): number
+  /** The raw stored `[rev, name]` pair as text, or undefined when never named.
+   *  Backed by NVS on device and by process memory on hosts. */
+  export function deviceName(): string | undefined
+  export function setDeviceName(value: string): void
   export function setTime(millisSinceEpoch: number): void
   export function uptime(): {boot: number; rtc: number}
   export function restart(): never
@@ -289,7 +294,11 @@ declare module 'native:mikro/nvs_kv' {
   export function set(key: string, value: unknown): NRV
   export function get(key: string): unknown
   export function remove(key: string): boolean
-  export function clear(): void
+  export function clear(): NRV
+  export function sysSet(key: string, value: unknown): NRV
+  export function sysGet(key: string): unknown
+  export function sysRemove(key: string): boolean
+  export function sysClear(): NRV
   export function info(): {entries: number; used: number; total: number; free: number}
 }
 
@@ -519,6 +528,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/i2s' {
   import type {I2sError, I2sSamples} from '@mikrojs/native/runtime/i2s/types'
   import type {Result} from 'mikro/result'

package/runtime/kv/nvs.ts

@@ -1,7 +1,9 @@
-import {KVError, makeCreateValue} from 'mikro/kv/shared'
-import {clear, get, info, remove, set} from 'native:mikro/nvs_kv'
+import {KVError, makeCreateValue, mapKvError} from 'mikro/kv/shared'
+import {err, ok} from 'mikro/result'
+import {clear, get, info, remove, set, sysClear} from 'native:mikro/nvs_kv'
 
-import type {NvsStorage} from './types.js'
+import type {Result} from '../result/types.js'
+import type {KVError as KVErrorType, NvsStorage} from './types.js'
 
 // Loaded in isolation: this file avoids `native:mikro/rtc`, so apps importing
 // `mikrojs/kv/nvs` directly don't pay for the RTC backend. `KVError` and
@@ -10,8 +12,18 @@ import type {NvsStorage} from './types.js'
 
 export {KVError}
 
+// A full clear attempts both stores even if the first fails; the first
+// error is returned so a partial wipe surfaces.
+function clearStorage(options?: {full?: boolean}): Result<void, KVErrorType> {
+  const cleared = clear()
+  const sysCleared = options?.full === true ? sysClear() : undefined
+  if (!cleared.ok) return err(mapKvError(cleared.error))
+  if (sysCleared !== undefined && !sysCleared.ok) return err(mapKvError(sysCleared.error))
+  return ok()
+}
+
 export const nvsStorage = {
   createValue: makeCreateValue({get, set, remove, clear, info}),
-  clear,
+  clear: clearStorage,
   info,
 } as NvsStorage

package/runtime/kv/shared.ts

@@ -30,11 +30,12 @@ export type NativeKvFns = {
   get: (key: string) => unknown
   set: (key: string, value: unknown) => NativeResult
   remove: (key: string) => boolean
-  clear: () => void
+  /* void (rtc) or a native Result (nvs); unused by createValue */
+  clear: () => unknown
   info: () => unknown
 }
 
-function mapKvError(e: NativeError) {
+export function mapKvError(e: NativeError) {
   switch (e.code) {
     case KV_STORAGE_FULL:
     case KV_TOO_LARGE:

package/runtime/kv/types.ts

@@ -138,8 +138,9 @@ export interface NvsStorage {
     options?: Opts,
   ): KVValue<InferOpts<Schema, Opts>>
 
-  /** Erase all NVS key-value data. */
-  clear(): void
+  /** Erase all app key-value data. With `{full: true}`, also erase the runtime's
+   *  system store. The system store is never touched otherwise. */
+  clear(options?: {full?: boolean}): Result<void, KVError>
   /** Get info about NVS key-value usage. */
   info(): NvsStorageInfo
 }

package/runtime/ota/ota.ts

@@ -0,0 +1,77 @@
+import {readFile} from 'mikro/fs'
+import {sysGet, sysSet} from 'native:mikro/nvs_kv'
+import * as native from 'native:mikro/ota'
+
+import {createOta, type OtaStore} from './policy.js'
+import type {Ota} from './types.js'
+
+// Policy state, persisted to the mik.sys NVS namespace so the retry budget
+// survives a crash-loop and app-level nvsStorage.clear() can't wipe it.
+// NVS keys are capped at 15 chars.
+// A dropped write cannot be recovered from here, but it must not pass in
+// silence: `ota.tries` and `ota.inflight` are the crash-loop latch, so losing
+// either hands the retry budget back on every boot and the bound that stops a
+// panicking build from being retried forever is gone.
+function put(key: string, value: string | number): void {
+  const r = sysSet(key, value)
+  // eslint-disable-next-line no-console
+  if (!r.ok) console.error(`ota: could not persist ${key}`, r.error)
+}
+
+const store: OtaStore = {
+  getUrl: () => {
+    const v = sysGet('ota.url')
+    return typeof v === 'string' ? v : undefined
+  },
+  setUrl: (url) => put('ota.url', url),
+  getAttempt: () => {
+    const v = sysGet('ota.att')
+    return typeof v === 'string' ? v : undefined
+  },
+  setAttempt: (checksum) => put('ota.att', checksum),
+  getTries: () => {
+    const v = sysGet('ota.tries')
+    return typeof v === 'number' ? v : 0
+  },
+  setTries: (n) => put('ota.tries', n),
+  getBad: () => {
+    const v = sysGet('ota.bad')
+    return typeof v === 'string' ? v : undefined
+  },
+  setBad: (checksum) => put('ota.bad', checksum),
+  getInFlight: () => sysGet('ota.inflight') === 1,
+  setInFlight: (value) => put('ota.inflight', value ? 1 : 0),
+}
+
+// Written as a pair to mik.sys by `mikro ota enroll`: the registry url and
+// the device credential that authenticates against it.
+function bearer(): string | undefined {
+  const v = sysGet('ota.credential')
+  return typeof v === 'string' ? v : undefined
+}
+
+function registry(): string | undefined {
+  const v = sysGet('ota.registry')
+  return typeof v === 'string' ? v : undefined
+}
+
+function readAppVersion(): string | undefined {
+  const r = readFile('/app/package.json', 'utf-8')
+  if (!r.ok) return undefined
+  try {
+    const pkg = JSON.parse(r.value) as {version?: unknown}
+    return typeof pkg.version === 'string' ? pkg.version : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const ota: Ota = createOta({
+  native,
+  store,
+  readAppVersion,
+  bearer,
+  registry,
+})
+
+export {ota}

package/runtime/ota/policy.ts

@@ -0,0 +1,299 @@
+import {err, ok} from 'mikro/result'
+
+import type {Result} from '../result/types.js'
+import type {
+  ApplyOutcome,
+  DownloadFn,
+  InstallOptions,
+  InstallOutcome,
+  Offer,
+  Ota,
+  OtaDownloadError,
+  OtaError,
+  OtaInstallError,
+  RunningBuild,
+  Update,
+} from './types.js'
+
+/** The native:mikro/ota contract (ESP-only C module; stubbed on host). */
+export interface NativeOta {
+  stageBegin(
+    checksum: string,
+    size: number,
+  ): {ok: true; resumeOffset: number} | {ok: false; error: string}
+  // No `kind` here, unlike stageFinish: every write failure is a storage
+  // problem and maps to StagingFull, so there is nothing to discriminate on.
+  stageWrite(bytes: Uint8Array): {ok: true} | {ok: false; error: string}
+  stageFinish(
+    trialBoots: number,
+    requireConfirm: boolean,
+    installNow: boolean,
+  ): {ok: true} | {ok: false; error: string; kind: 'corrupt' | 'transient' | 'oom'}
+  stageAbort(): void
+  markValid(): void
+  revert(): {ok: true} | {ok: false; error: string}
+  running(): {checksum?: string; trial: boolean}
+  reconcile(): {
+    installed?: string
+    reverted: boolean
+    diagnostic?: {reason: string; detail?: string}
+  }
+}
+
+/** Crash-loop-safe policy state, persisted to NVS with short keys. */
+export interface OtaStore {
+  getUrl(): string | undefined
+  setUrl(url: string): void
+  /** Checksum the retry budget is currently counting against. */
+  getAttempt(): string | undefined
+  setAttempt(checksum: string): void
+  getTries(): number
+  setTries(n: number): void
+  getBad(): string | undefined
+  setBad(checksum: string): void
+  /** True while an install attempt is running. Still true at boot means the
+   *  last one never returned, i.e. it crashed the device. */
+  getInFlight(): boolean
+  setInFlight(value: boolean): void
+}
+
+interface OtaDeps {
+  native: NativeOta
+  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
+   *  undefined on an un-enrolled device. */
+  bearer(): string | undefined
+  /** The registry url the credential was minted against, or undefined. */
+  registry(): string | undefined
+}
+
+/** Number of staging attempts for one url before a checksum is abandoned. */
+const MAX_TRIES = 3
+
+/** Validate an untrusted registry value into an `Offer`, or `undefined`. */
+export function parseOffer(raw: unknown, opts?: {allowInsecure?: boolean}): Offer | undefined {
+  // null/undefined is the registry's "no update available" signal, not a
+  // malformed offer, so return quietly without a warning.
+  if (raw === null || raw === undefined) return undefined
+  const reject = (reason: string): undefined => {
+    // eslint-disable-next-line no-console
+    console.warn(`ota: ignoring offer (${reason})`)
+    return undefined
+  }
+  if (typeof raw !== 'object') return reject('not an object')
+  const o = raw as Record<string, unknown>
+  // No url is "no update", not a malformed offer: a check-in with nothing newer
+  // still returns a body when the registry has something else to say — a name to
+  // adopt, say — and the reference client reads that before parseOffer. Warn
+  // only when a url is present but unusable, so a dashboard rename that coincides
+  // with "up to date" does not log a misleading warning on every device.
+  if (o.url === undefined) return undefined
+  if (typeof o.url !== 'string') return reject('missing url')
+  // https is required so the device never downloads executable bytecode over
+  // plaintext; allowInsecure (dev only) also permits http for local registries.
+  const schemeOk =
+    o.url.startsWith('https://') || (opts?.allowInsecure === true && o.url.startsWith('http://'))
+  // Only the path has to name a .tgz. A registry is free to hang a query on the
+  // url — a signed-url registry puts an expiry and signature there — and the
+  // device treats the whole string as opaque, so rejecting on the query would
+  // forbid that for no gain.
+  const pathEnd = o.url.search(/[?#]/)
+  const urlPath = pathEnd < 0 ? o.url : o.url.slice(0, pathEnd)
+  if (!schemeOk || !urlPath.endsWith('.tgz')) {
+    return reject(opts?.allowInsecure ? 'url must be an http(s) .tgz' : 'url must be an https .tgz')
+  }
+  if (typeof o.checksum !== 'string' || o.checksum.length === 0) return reject('missing checksum')
+  // Must be a positive integer: a negative size fails the first write with
+  // TooLarge, and 0 disables the cap on both sides, leaving the download
+  // unbounded.
+  if (typeof o.size !== 'number' || !Number.isInteger(o.size) || o.size <= 0) {
+    return reject('invalid size')
+  }
+  // The url's host is not checked. The offer arrives in an authenticated
+  // check-in response from the enrolled registry, so the registry is trusted to
+  // 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
+  // attaches it only when the url is same-origin with the registry).
+  return {url: o.url, checksum: o.checksum, size: o.size}
+}
+
+function makeUpdate(native: NativeOta, size: number | undefined, resumeOffset: number): Update {
+  let written = resumeOffset
+  return {
+    resumeOffset,
+    write(bytes) {
+      if (size !== undefined && written + bytes.length > size) {
+        return err({name: 'TooLarge' as const, message: `build exceeds offered size ${size}`})
+      }
+      const r = native.stageWrite(bytes)
+      if (!r.ok) return err({name: 'StagingFull' as const, message: r.error})
+      written += bytes.length
+      return ok()
+    },
+    finish(options) {
+      const r = native.stageFinish(
+        options?.trialBoots ?? 1,
+        options?.requireConfirm ?? false,
+        options?.install === 'now',
+      )
+      if (r.ok) return ok()
+      return err({name: 'InstallFailed' as const, kind: r.kind, message: r.error})
+    },
+    abort() {
+      native.stageAbort()
+    },
+  }
+}
+
+/** True if the failure means the bytes are bad and must not be retried. */
+function isAbandon(e: OtaError): boolean {
+  return e.name === 'InstallFailed' && e.kind === 'corrupt'
+}
+
+export function createOta(deps: OtaDeps): Ota {
+  const {native, store, readAppVersion} = deps
+
+  function beginUpdate(options: {checksum: string; size: number}) {
+    const r = native.stageBegin(options.checksum, options.size)
+    if (!r.ok) return err({name: 'StagingFailed' as const, message: r.error})
+    return ok(makeUpdate(native, options.size, r.resumeOffset))
+  }
+  // beginUpdate stays internal: staging is only ever driven through the policy.
+
+  function reconcile(): InstallOutcome {
+    // Give the budget back once per boot. Everything it counts is transient
+    // (OOM, a truncated download), and a reboot is the one signal available
+    // here that conditions may have changed — there is no clock to back off
+    // against. Without this the budget is a permanent latch: three OOM
+    // failures would strand the device on the old build forever, even once
+    // free heap recovered.
+    //
+    // Unless the last attempt crashed. A native OOM panics into a restart, so
+    // an unconditional reset zeroes the count on exactly the failure the budget
+    // exists to bound, and the device reboots into the same attempt forever.
+    // The in-flight flag is still set only in that case, so the crashed attempt
+    // keeps its bump and MAX_TRIES eventually binds.
+    if (store.getInFlight()) store.setInFlight(false)
+    else store.setTries(0)
+    const r = native.reconcile()
+    const out: InstallOutcome = {reverted: r.reverted}
+    if (r.installed !== undefined) out.installed = r.installed
+    if (r.diagnostic !== undefined) out.lastInstall = r.diagnostic
+    return out
+  }
+
+  function running(): RunningBuild {
+    const r = native.running()
+    const out: RunningBuild = {trial: r.trial}
+    if (r.checksum !== undefined) out.checksum = r.checksum
+    const v = readAppVersion()
+    if (v !== undefined) out.version = v
+    return out
+  }
+
+  function revert(): Result<void, OtaInstallError> {
+    const r = native.revert()
+    if (r.ok) return ok()
+    return err({name: 'InstallFailed' as const, kind: 'transient' as const, message: r.error})
+  }
+
+  async function applyOffer(
+    offer: Offer,
+    download: DownloadFn,
+    options?: InstallOptions,
+  ): Promise<Result<ApplyOutcome, OtaError>> {
+    const run = native.running()
+    // (a) a trial is unresolved. Reported distinctly because the caller's
+    // response differs from every other skip: the build on trial still needs
+    // confirming, and treating this like "nothing to do" lets the trial lapse
+    // and roll back a healthy build just because a newer one was published.
+    if (run.trial) return ok('trial-pending')
+    // (b) already running this build
+    if (offer.checksum === run.checksum) return ok('current')
+    // (d) device has given up on this build
+    if (offer.checksum === store.getBad()) return ok('abandoned')
+    // (e) retry budget, keyed on url *and* checksum. Exhausting it only stops
+    // attempts against this exact build at this exact url; the checksum is not
+    // abandoned, because everything counted here is transient by construction
+    // (a corrupt build is abandoned at (h) instead). Marking it bad would be
+    // unrecoverable: check (d) runs before this, so re-publishing the same
+    // build at a fresh url could never revive it, and nothing clears `bad`. A
+    // device on flaky wifi would permanently lose a good build after three
+    // failed downloads.
+    //
+    // The checksum has to be part of the key because a registry that serves a
+    // stable url ("/latest.tgz", re-pointed on publish) would otherwise never
+    // reset: three failures against the old build would skip every future one
+    // at that url, permanently, since the reset on success is unreachable.
+    if (offer.url !== store.getUrl() || offer.checksum !== store.getAttempt()) {
+      store.setUrl(offer.url)
+      store.setAttempt(offer.checksum)
+      store.setTries(0)
+    }
+    const tries = store.getTries()
+    if (tries >= MAX_TRIES) return ok('exhausted')
+    // (f) bump before the attempt, so a crash mid-attempt still counts — the
+    // flag is what makes that true across a reboot (see reconcile). The finally
+    // clears it on every ordinary exit, and deliberately does not run when the
+    // attempt takes the device down with it.
+    store.setTries(tries + 1)
+    store.setInFlight(true)
+    try {
+      return await attempt(offer, download, options)
+    } finally {
+      store.setInFlight(false)
+    }
+  }
+
+  async function attempt(
+    offer: Offer,
+    download: DownloadFn,
+    options?: InstallOptions,
+  ): Promise<Result<ApplyOutcome, OtaError>> {
+    // (g) stage, download, verify
+    const begun = beginUpdate({checksum: offer.checksum, size: offer.size})
+    if (!begun.ok) return err(begun.error)
+    const update = begun.value
+    // The download callback is the app's transport code. A failure there (network,
+    // a write rejection) is transient: keep the bumped tries so it retries next time,
+    // and do NOT abandon the checksum (that is only for a corrupt build).
+    const downloaded = await download(update)
+    if (!downloaded.ok) {
+      update.abort()
+      const downloadError: OtaDownloadError = {
+        name: 'DownloadFailed',
+        message: downloaded.error.message,
+      }
+      return err(downloadError)
+    }
+    // (h) a corrupt build is the one thing worth abandoning: the same bytes will
+    // fail identically forever. Abort first, or the verified-bad staging file
+    // (up to the whole build) sits on the app partition until some later offer
+    // happens to reclaim it.
+    const finished = update.finish(options)
+    if (!finished.ok) {
+      if (isAbandon(finished.error)) {
+        update.abort()
+        store.setBad(offer.checksum)
+      }
+      return err(finished.error)
+    }
+    store.setTries(0)
+    return ok('staged')
+  }
+
+  return {
+    reconcile,
+    running,
+    parseOffer,
+    applyOffer,
+    confirm: () => native.markValid(),
+    revert,
+    bearer: deps.bearer,
+    registry: deps.registry,
+  }
+}

package/runtime/ota/types.ts

@@ -0,0 +1,147 @@
+import type {Result} from '../result/types.js'
+
+/** An update offered by a registry: what to fetch and how to verify it, nothing
+ *  more. Whether this device should take it is the registry's decision, made
+ *  against the firmware and bytecode version the device reports at check-in and
+ *  the whole set of builds it holds. Validate untrusted input with `parseOffer`. */
+export interface Offer {
+  /** https URL of the .tgz build */
+  url: string
+  /** content hash, verified after download */
+  checksum: string
+  /** build size in bytes */
+  size: number
+}
+
+export interface InstallOptions {
+  /** clean cycles a trial must survive before it is kept (default 1) */
+  trialBoots?: number
+  /** require `ota.confirm()` instead of auto-keeping (default false) */
+  requireConfirm?: boolean
+  /** when to unpack and swap (default 'next-boot') */
+  install?: 'now' | 'next-boot'
+}
+
+export interface Diagnostic {
+  /** short failure category, e.g. "ota_install_failed" */
+  reason: string
+  /** human-readable detail */
+  detail?: string
+}
+
+export interface InstallOutcome {
+  /** checksum of a build installed this boot, if any */
+  installed?: string
+  /** whether a trial was rolled back this boot */
+  reverted: boolean
+  /** why a previous install failed, to forward to the registry */
+  lastInstall?: Diagnostic
+}
+
+export interface RunningBuild {
+  /** checksum of the executing build */
+  checksum?: string
+  /** its package.json version */
+  version?: string
+  /** true while it is still on trial */
+  trial: boolean
+}
+
+export interface Update {
+  /** Bytes already staged for this checksum. Start a Range request here to resume. */
+  readonly resumeOffset: number
+
+  /** Append downloaded bytes. Enforces the size limit as bytes arrive. */
+  write(bytes: Uint8Array): Result<void, OtaWriteError>
+
+  /** Verify the staged build against the checksum and size, then stage it for install.
+   *  Defaults to installing on the next boot; pass `{install: 'now'}` to install in place. */
+  finish(options?: InstallOptions): Result<void, OtaError>
+
+  /** Discard the staging session. */
+  abort(): void
+}
+
+/** The download callback given to `applyOffer`. Fetch the build bytes any way
+ *  you like and write them with `update.write`; return `ok()` when done, or
+ *  `err({message})` to signal a download failure (retried on a later attempt). */
+export type DownloadFn = (update: Update) => Promise<Result<void, {message: string}>>
+
+/** Staging ran out of room, or exceeded the offered size. */
+export type OtaWriteError =
+  | {name: 'StagingFull'; message: string}
+  | {name: 'TooLarge'; message: string}
+
+/** Staging could not be started: the offer is malformed, or the build does not
+ *  fit this device's filesystem. Not blacklisted — a malformed offer is not the
+ *  build's fault, and a re-publish at a corrected size must be able to succeed. */
+export type OtaBeginError = {name: 'StagingFailed'; message: string}
+
+/** The build failed to unpack or swap. `kind` is `corrupt` for bad bytes
+ *  (retrying cannot help, so it is abandoned), or `transient`/`oom` for storage
+ *  and memory failures that are retried within the retry limit. */
+export type OtaInstallError = {
+  name: 'InstallFailed'
+  kind: 'corrupt' | 'transient' | 'oom'
+  message: string
+}
+
+/** The download callback returned a failure. Transient: the attempt is
+ *  retried on a later `applyOffer`, not abandoned (unlike a corrupt build). */
+export type OtaDownloadError = {name: 'DownloadFailed'; message: string}
+
+/** Why `applyOffer` did not stage the offer. Only `staged` means bytes landed.
+ *
+ *  These are outcomes, not errors: each one is the policy working as intended.
+ *  They are distinguished because the caller's next move differs — in
+ *  particular `trial-pending` is the one case where the app should confirm the
+ *  build it is running rather than treat the offer as handled. */
+export type ApplyOutcome =
+  /** The build was downloaded, verified, and armed for install. */
+  | 'staged'
+  /** A trial is unresolved: this device must settle the build it is running
+   *  before it can take another. */
+  | 'trial-pending'
+  /** This build is already the running build. */
+  | 'current'
+  /** This build was abandoned as corrupt and will not be retried. */
+  | 'abandoned'
+  /** The retry budget for this build is spent until the next boot. */
+  | 'exhausted'
+
+/** Returned by `applyOffer` and `finish`. A failed checksum arrives here as
+ *  `InstallFailed` with `kind: 'corrupt'` — the native side has no separate
+ *  mismatch code, since it cannot tell a bad hash from bad bytes. */
+export type OtaError = OtaWriteError | OtaBeginError | OtaInstallError | OtaDownloadError
+
+export interface Ota {
+  /** Report what happened to a previous update on this boot, and clear the report. */
+  reconcile(): InstallOutcome
+  /** The build currently executing, read from the live app. */
+  running(): RunningBuild
+  /** Validate a registry value into an `Offer`, or `undefined` if unusable.
+   *  `allowInsecure` (dev only) accepts an http build url instead of https. */
+  parseOffer(raw: unknown, opts?: {allowInsecure?: boolean}): Offer | undefined
+  /** Run the full update policy: skip checks, compatibility, retry limit,
+   *  download via the `download` callback, and verification. */
+  applyOffer(
+    offer: Offer,
+    download: DownloadFn,
+    options?: InstallOptions,
+  ): Promise<Result<ApplyOutcome, OtaError>>
+  /** Mark the running trial as healthy so it is kept rather than rolled back. */
+  confirm(): void
+  /** Reinstall the previous build immediately. */
+  revert(): Result<void, OtaInstallError>
+  /** The check-in bearer: the device credential written at enrollment
+   *  (`mikro ota enroll`), or `undefined` on an un-enrolled device. Read-only:
+   *  credentials 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. */
+  registry(): string | undefined
+}
+
+/** The `mikro/ota` singleton. The runtime value is provided by the on-device
+ *  builtin (or the sim stub); this declaration carries its type for hosts. */
+export declare const ota: Ota

package/runtime/sys/sys.ts

@@ -2,6 +2,8 @@ import {err, ok, PanicError, type Result} from 'mikro/result'
 import {getWakeupCause as nativeGetWakeupCause} from 'native:mikro/sleep'
 import * as native from 'native:mikro/sys'
 
+import type {DeviceName} from './types.js'
+
 export function uptime(): {boot: number; rtc: number} {
   return native.uptime()
 }
@@ -21,6 +23,12 @@ export function memoryUsage() {
   return native.memoryUsage()
 }
 
+/** Bytes on the app filesystem, the partition an OTA build is downloaded and
+ *  staged onto. Undefined when the platform cannot report it. */
+export function storageUsage() {
+  return native.storageUsage()
+}
+
 export function jsMemoryUsage() {
   return native.jsMemoryUsage()
 }
@@ -37,6 +45,34 @@ export const firmware = native.firmware
 
 export const deviceId: string = native.deviceId
 
+/**
+ * The device's name and the logical revision that orders renames against a
+ * registry. Stored as one `[rev, name]` value — the same shape a check-in
+ * carries — so the pair can never be read or written half-updated. Revision 0
+ * with no name means never named, and callers fall back to {@link deviceId}.
+ */
+export function deviceName(): DeviceName {
+  const raw = native.deviceName()
+  if (typeof raw !== 'string') return {rev: 0}
+  try {
+    const pair = JSON.parse(raw) as unknown
+    if (!Array.isArray(pair)) return {rev: 0}
+    const rev: unknown = pair[0]
+    if (typeof rev !== 'number' || !Number.isInteger(rev) || rev < 0) return {rev: 0}
+    const value: unknown = pair[1]
+    return typeof value === 'string' && value !== '' ? {rev, name: value} : {rev}
+  } catch {
+    return {rev: 0}
+  }
+}
+
+/** Persist a name pair, e.g. one adopted from a registry check-in. */
+export function setDeviceName(value: DeviceName): void {
+  native.setDeviceName(
+    JSON.stringify(value.name === undefined ? [value.rev] : [value.rev, value.name]),
+  )
+}
+
 export const resetReason = native.resetReason
 
 export function restart(): never {

package/runtime/sys/types.ts

@@ -113,8 +113,28 @@ export declare const board: BoardInfo
  * yields the original 6 MAC bytes. On host/Node builds, derived from
  * the hostname via FNV-1a hash (stable across restarts on the same
  * machine). */
+/** Bytes on the app filesystem, the partition an OTA build is downloaded and
+ *  staged onto. Undefined when the platform cannot report it. */
+export declare function storageUsage(): {total: number; used: number; free: number} | undefined
+
 export declare const deviceId: string
 
+/** A device name paired with the revision that orders renames. Both sides bump
+ *  the revision on every deliberate rename, so whichever is higher wins without
+ *  needing a clock the device may not have. */
+export interface DeviceName {
+  rev: number
+  /** Absent when the name is cleared, or never set. */
+  name?: string
+}
+
+/** The device's name and its revision; revision 0 with no name means never
+ *  named, and callers fall back to {@link deviceId}. */
+export declare function deviceName(): DeviceName
+
+/** Persist a name pair, e.g. one adopted from a registry check-in. */
+export declare function setDeviceName(value: DeviceName): void
+
 /** Firmware build identifiers */
 export declare const firmware: {
   /** ELF SHA256 hash on ESP32, "dev" on host */
@@ -123,6 +143,8 @@ export declare const firmware: {
   readonly date: string
   /** ESP-IDF version, undefined on host */
   readonly idfVersion: string | undefined
+  /** QuickJS bytecode version the linked engine reads/writes */
+  readonly bytecodeVersion: number
 }
 
 /** Why the device last reset. A clean `restart()` reports `'software'`;

package/src/mik_app_store.cpp

@@ -0,0 +1,134 @@
+#include "mikrojs/app_store.h"
+
+#include <dirent.h>
+#include <stdio.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+namespace {
+
+bool path_exists(const char* path) {
+    struct stat st;
+    return stat(path, &st) == 0;
+}
+
+/* An app is a directory. `stat` succeeds for a regular file too, so a build
+ * archive carrying a *file* named `app` would otherwise pass the staged-app
+ * guard below: commit would stash the live app, move that file into the app
+ * slot, and drop the stash, leaving the device with no app and no rollback. */
+static bool dir_exists(const char* path) {
+    struct stat st;
+    return stat(path, &st) == 0 && S_ISDIR(st.st_mode);
+}
+
+/* Deepest tree this will descend into. Builds are 2-3 levels; the untar path
+ * caps member depth well below this. The bound exists so a tree left by an
+ * older firmware (or a hostile archive that predates the cap) cannot overflow
+ * the main task stack here, because this runs from boot recovery: a panic
+ * would reboot straight back into the same call and never reach the install
+ * budget. Past the bound the tree is left on disk, which fails the next
+ * install instead of bricking the device. */
+constexpr int kMaxDepth = 32;
+
+/* `path` is a mutable buffer of `cap` bytes holding the directory to remove;
+ * each level appends into it and truncates on the way out, so a frame costs a
+ * few dozen bytes rather than a 512-byte path of its own. */
+void rmdir_recursive_at(char* path, size_t cap, int depth) {
+    DIR* dir = opendir(path);
+    if (!dir) return;
+
+    const size_t base = strlen(path);
+    struct dirent* entry;
+    while ((entry = readdir(dir)) != NULL) {
+        if (strcmp(entry->d_name, ".") == 0 || strcmp(entry->d_name, "..") == 0) continue;
+
+        const int n = snprintf(path + base, cap - base, "/%s", entry->d_name);
+        if (n < 0 || (size_t)n >= cap - base) {
+            path[base] = 0;  /* would truncate to a different path; skip it */
+            continue;
+        }
+
+        struct stat st;
+        if (stat(path, &st) == 0 && S_ISDIR(st.st_mode)) {
+            if (depth < kMaxDepth) rmdir_recursive_at(path, cap, depth + 1);
+        } else {
+            unlink(path);
+        }
+        path[base] = 0;
+    }
+    closedir(dir);
+    rmdir(path);
+}
+
+void rmdir_recursive(const char* path) {
+    char buf[512];
+    const size_t n = strlen(path);
+    if (n >= sizeof(buf)) return;
+    memcpy(buf, path, n + 1);
+    rmdir_recursive_at(buf, sizeof(buf), 0);
+}
+
+}  // namespace
+
+MIKAppCommitResult mik__app_commit(const char* base, bool erased) {
+    char app[512];
+    char tmp[512];
+    char old[512];
+    char staged_app[512];
+    snprintf(app, sizeof(app), "%s/app", base);
+    snprintf(tmp, sizeof(tmp), "%s/.deploy-tmp", base);
+    snprintf(old, sizeof(old), "%s/.deploy-old", base);
+    snprintf(staged_app, sizeof(staged_app), "%s/app", tmp);
+
+    /* No-staged guard (hardening over the original): if nothing was staged,
+     * leave the live app untouched and just clean up. The original logic
+     * would have deleted the live app in this degenerate case. */
+    if (!dir_exists(staged_app)) {
+        rmdir_recursive(old);
+        rmdir_recursive(tmp);
+        return MIK_APP_COMMIT_OK;
+    }
+
+    /* Atomic swap: staging dir → app dir */
+    if (path_exists(app) && !erased) {
+        rmdir_recursive(old);
+        if (rename(app, old) != 0) {
+            return MIK_APP_COMMIT_STASH_FAILED;
+        }
+    }
+
+    if (rename(staged_app, app) != 0) {
+        if (path_exists(old)) {
+            rename(old, app);
+        }
+        return MIK_APP_COMMIT_SWAP_FAILED;
+    }
+
+    rmdir_recursive(old);
+    rmdir_recursive(tmp);
+    return MIK_APP_COMMIT_OK;
+}
+
+void mik__app_recover(const char* base) {
+    char app[512];
+    char tmp[512];
+    char old[512];
+    snprintf(app, sizeof(app), "%s/app", base);
+    snprintf(tmp, sizeof(tmp), "%s/.deploy-tmp", base);
+    snprintf(old, sizeof(old), "%s/.deploy-old", base);
+
+    bool has_app = path_exists(app);
+    bool has_old = path_exists(old);
+    bool has_tmp = path_exists(tmp);
+
+    if (!has_app && has_old) {
+        rename(old, app);
+    } else if (has_old) {
+        rmdir_recursive(old);
+    }
+
+    if (has_tmp) {
+        rmdir_recursive(tmp);
+    }
+}

package/src/mik_repl.cpp

@@ -32,7 +32,9 @@ 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;
-static uint8_t ready_buf[96];
+/* 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];
 static size_t ready_len = 0;
 
 /* Transient flag: set by MIK_ProtocolExit to break the current ServeLoop
@@ -876,6 +878,65 @@ 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)}.
+ * `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
+ * revision 0.
+ *
+ * Rebuilt per CMD_HELLO rather than cached at protocol open: the running app
+ * can adopt a registry name mid-session, and a host holding a revision from the
+ * opening handshake would write its next rename at a stale revision, which the
+ * registry then reads as behind and reverts. Only ever emitted in reply to a
+ * client CMD_HELLO, so a passive serial viewer (e.g. idf.py monitor) still
+ * doesn't see the device announcing itself unprompted. */
+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) {
+    nanocbor_encoder_t enc;
+    nanocbor_encoder_init(&enc, buf, cap);
+    nanocbor_fmt_map(&enc, name ? 4 : 3);
+    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 (name) {
+        nanocbor_put_tstr(&enc, "name");
+        nanocbor_put_tstr(&enc, name);
+    }
+    return nanocbor_encoded_len(&enc);
+}
+
+static void refresh_ready(MIKReplTransport* transport) {
+    const char* chip = transport->chip_name ? transport->chip_name : "unknown";
+    const char* id = MIK_GetPlatform()->get_device_id();
+    if (!id) id = "";
+    const char* version =
+#ifdef MIK_FW_VERSION
+        MIK_FW_VERSION;
+#else
+        "0.0.0-dev";
+#endif
+    const char* name =
+        MIK_GetPlatform()->get_device_name ? MIK_GetPlatform()->get_device_name() : nullptr;
+    /* Measured against a null buffer first. nanocbor stops writing at the buffer
+     * 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)) {
+        name = nullptr;
+    }
+    ready_len = encode_ready(ready_buf, sizeof(ready_buf), chip, id, version, name);
+    if (ready_len > sizeof(ready_buf)) ready_len = 0;
+}
+
 void MIK_ProtocolOpen(MIKReplTransport* transport) {
     if (repl_active) return;
 
@@ -886,41 +947,6 @@ void MIK_ProtocolOpen(MIKReplTransport* transport) {
     show_depth = 2;
     show_hidden = false;
 
-    /* Build MSG_READY with CBOR device info: {"chip": tstr, "id": tstr, "v": tstr}.
-     * Cached here and only emitted in response to a client CMD_HELLO so a
-     * passive serial viewer (e.g. idf.py monitor) doesn't see the device
-     * spamming its identity unprompted. */
-    {
-        const char* chip = transport->chip_name ? transport->chip_name : "unknown";
-        const char* id = MIK_GetPlatform()->get_device_id();
-        if (!id) id = "";
-        const char* version =
-#ifdef MIK_FW_VERSION
-            MIK_FW_VERSION;
-#else
-            "0.0.0-dev";
-#endif
-
-        nanocbor_encoder_t enc;
-        nanocbor_encoder_init(&enc, nullptr, 0);
-        nanocbor_fmt_map(&enc, 3);
-        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);
-        ready_len = nanocbor_encoded_len(&enc);
-
-        nanocbor_encoder_init(&enc, ready_buf, sizeof(ready_buf));
-        nanocbor_fmt_map(&enc, 3);
-        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);
-    }
 }
 
 void MIK_ProtocolAttach(MIKRuntime* mik_rt) {
@@ -1102,7 +1128,9 @@ void MIK_ProtocolServeLoop(void) {
                 break;
 
             case MIK_CMD_HELLO:
-                /* Client-initiated handshake: reply with cached MSG_READY. */
+                /* Client-initiated handshake: rebuild so the name pair is
+                 * current, then reply. */
+                refresh_ready(transport);
                 mik__proto_send(transport, MIK_MSG_READY, ready_buf, ready_len);
                 break;
             }

package/src/mik_sys.cpp

@@ -28,6 +28,27 @@ static JSValue mik__sys_eval_script(JSContext* ctx, JSValue this_val, int argc,
     return ret;
 }
 
+/* Free/used bytes on the app filesystem ("user", mounted at /appfs) — the
+ * partition an OTA build is downloaded and staged onto. Undefined when the
+ * platform can't report it. */
+static JSValue mik__sys_storage_usage(JSContext* ctx, JSValue this_val, int argc,
+                                      JSValue* argv) {
+    (void)this_val;
+    (void)argc;
+    (void)argv;
+    const MIKPlatform* platform = MIK_GetPlatform();
+    size_t total = 0;
+    size_t used = 0;
+    if (!platform->get_fs_info || !platform->get_fs_info("user", &total, &used)) {
+        return JS_UNDEFINED;
+    }
+    JSValue obj = JS_NewObject(ctx);
+    JS_SetPropertyStr(ctx, obj, "total", JS_NewInt64(ctx, (int64_t)total));
+    JS_SetPropertyStr(ctx, obj, "used", JS_NewInt64(ctx, (int64_t)used));
+    JS_SetPropertyStr(ctx, obj, "free", JS_NewInt64(ctx, (int64_t)(total > used ? total - used : 0)));
+    return obj;
+}
+
 static JSValue mik__sys_memory_usage(JSContext* ctx, JSValue this_val, int argc,
                                          JSValue* argv) {
     JSMemoryUsage mem;
@@ -227,14 +248,52 @@ static JSValue mik__sys_firmware(JSContext* ctx) {
     JS_SetPropertyStr(ctx, obj, "date", JS_NewString(ctx, MIK_BUILD_DATE_UTC));
     JS_SetPropertyStr(ctx, obj, "idfVersion", JS_NewString(ctx, "n/a"));
 #endif
+    /* BC_VERSION is a #define inside quickjs.c (not exported in any header).
+     * Serialize a trivial value and read byte 0 of the output: that's the
+     * bytecode version the linked engine writes (matches builtins.cpp's
+     * data[0] read). */
+    size_t bc_len = 0;
+    uint8_t* bc_buf = JS_WriteObject(ctx, &bc_len, JS_NULL, JS_WRITE_OBJ_BYTECODE);
+    int bc = (bc_buf && bc_len > 0) ? bc_buf[0] : 0;
+    if (bc_buf) js_free(ctx, bc_buf);
+    JS_SetPropertyStr(ctx, obj, "bytecodeVersion", JS_NewInt32(ctx, bc));
     return obj;
 }
 
+/* The stored `[rev, name]` pair, or undefined when never named. Read through
+ * the platform so `mikro/sys` stays loadable on hosts with no NVS. */
+static JSValue mik__sys_device_name(JSContext* ctx, JSValue this_val, int argc, JSValue* argv) {
+    (void)this_val;
+    (void)argc;
+    (void)argv;
+    const MIKPlatform* platform = MIK_GetPlatform();
+    const char* value = platform->get_device_name ? platform->get_device_name() : NULL;
+    return value ? JS_NewString(ctx, value) : JS_UNDEFINED;
+}
+
+static JSValue mik__sys_set_device_name(JSContext* ctx, JSValue this_val, int argc,
+                                        JSValue* argv) {
+    (void)this_val;
+    const MIKPlatform* platform = MIK_GetPlatform();
+    if (!platform->set_device_name) return JS_UNDEFINED;
+    if (argc < 1 || JS_IsUndefined(argv[0]) || JS_IsNull(argv[0])) {
+        platform->set_device_name(NULL);
+        return JS_UNDEFINED;
+    }
+    const char* value = JS_ToCString(ctx, argv[0]);
+    if (!value) return JS_EXCEPTION;
+    platform->set_device_name(value);
+    JS_FreeCString(ctx, value);
+    return JS_UNDEFINED;
+}
+
 void mik__sys_api_init(JSContext* ctx, JSValue ns) {
     JS_SetPropertyStr(ctx, ns, "evalScript",
                       JS_NewCFunction(ctx, mik__sys_eval_script, "evalScript", 1));
     JS_SetPropertyStr(ctx, ns, "memoryUsage",
                       JS_NewCFunction(ctx, mik__sys_memory_usage, "memoryUsage", 0));
+    JS_SetPropertyStr(ctx, ns, "storageUsage",
+                      JS_NewCFunction(ctx, mik__sys_storage_usage, "storageUsage", 0));
     JS_SetPropertyStr(ctx, ns, "jsMemoryUsage",
                       JS_NewCFunction(ctx, mik__sys_js_memory_usage, "jsMemoryUsage", 0));
     JS_SetPropertyStr(ctx, ns, "gc", JS_NewCFunction(ctx, mik__sys_gc, "gc", 0));
@@ -269,6 +328,11 @@ void mik__sys_api_init(JSContext* ctx, JSValue ns) {
     JS_SetPropertyStr(ctx, ns, "deviceId",
                       device_id ? JS_NewString(ctx, device_id) : JS_UNDEFINED);
 
+    JS_SetPropertyStr(ctx, ns, "deviceName",
+                      JS_NewCFunction(ctx, mik__sys_device_name, "deviceName", 0));
+    JS_SetPropertyStr(ctx, ns, "setDeviceName",
+                      JS_NewCFunction(ctx, mik__sys_set_device_name, "setDeviceName", 1));
+
     const char* reset_reason =
         platform->get_reset_reason ? platform->get_reset_reason() : NULL;
     JS_SetPropertyStr(ctx, ns, "resetReason",

package/src/mikrojs.cpp

@@ -90,9 +90,11 @@ static void mik__add_exports(JSContext* ctx, JSModuleDef* m, const char* const*
 }
 
 static const char* const sys_exports[] = {
-    "evalScript", "memoryUsage", "jsMemoryUsage",  "gc",          "setTime",
-    "uptime",     "restart",     "version",        "board",       "firmware",
-    "deviceId",   "resetReason", "activeTimers",   "unloadNamespace", "isUnloadableNamespace"};
+    "evalScript",      "memoryUsage",           "storageUsage", "jsMemoryUsage",
+    "gc",              "setTime",               "uptime",       "restart",
+    "version",         "board",                 "firmware",     "deviceId",
+    "deviceName",      "setDeviceName",         "resetReason",  "activeTimers",
+    "unloadNamespace", "isUnloadableNamespace"};
 
 static int mik__sys_module_init(JSContext* ctx, JSModuleDef* m) {
     JSValue ns = JS_NewObjectProto(ctx, JS_NULL);

package/src/platform_posix.cpp

@@ -92,6 +92,22 @@ static int posix_stdin_read(void* buf, size_t len) {
 /* Derive a stable device ID from the hostname. FNV-1a hash truncated to
  * 6 bytes, then Crockford's Base32 encoded (10 lowercase chars).
  * Deterministic across restarts on the same machine. */
+/* Host builds have no NVS: the name lives for the process only, which is
+ * enough for tests and the simulator. */
+static char posix_device_name[128] = {0};
+
+static const char* posix_get_device_name(void) {
+    return posix_device_name[0] == '\0' ? NULL : posix_device_name;
+}
+
+static void posix_set_device_name(const char* value) {
+    if (!value) {
+        posix_device_name[0] = '\0';
+        return;
+    }
+    snprintf(posix_device_name, sizeof(posix_device_name), "%s", value);
+}
+
 static const char* posix_get_device_id(void) {
     static const char cb32[] = "0123456789abcdefghjkmnpqrstvwxyz";
     static char id[11] = {0};
@@ -151,6 +167,8 @@ static const MIKPlatform posix_platform = {
     .stderr_write = posix_stderr_write,
     .stdin_read = posix_stdin_read,
     .get_device_id = posix_get_device_id,
+    .get_device_name = posix_get_device_name,
+    .set_device_name = posix_set_device_name,
     .get_reset_reason = posix_get_reset_reason,
 };