@mikrojs/native 0.18.2 → 0.19.0-pr-352.20260829215534

package/CMakeLists.txt

@@ -43,7 +43,10 @@ set(MIKROJS_CORE_SOURCES
     src/mik_text_encoding.cpp
     src/mik_color.cpp
     src/mik_abort.cpp
+    src/mik_http_client.cpp
+    src/mik_wifi_client.cpp
     src/mik_cbor.cpp
+    src/mik_schema.cpp
     src/mik_result.cpp
     src/mik_console.cpp
     src/mik_sys.cpp
@@ -88,7 +91,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 ota/client ota/config pin pwm reader sleep spi sntp stdio stream sys test uart udp wifi
+    MODULES abort cbor env result schema fs i2c kv/nvs kv/rtc kv/shared module neopixel observable observable/lazy observable/operators ota ota/client ota/config pin pwm reader sleep spi sntp stdio stream sys test uart udp
     MODULE_PREFIX "mikro"
     SYMBOL_PREFIX "mikro"
     TARGET gen_bytecode
@@ -194,6 +197,7 @@ if(BUILD_TESTING)
         test/app_store_test.cpp
         test/oom_test.cpp
         test/oom_inject_test.cpp
+        test/mem_usable_size_test.cpp
         test/fs_test.cpp
         test/console_stdio_test.cpp
         test/cbor_js_test.cpp
@@ -207,6 +211,8 @@ if(BUILD_TESTING)
         test/stream_test.cpp
         test/runtime_recycle_test.cpp
         test/udp_test.cpp
+        test/http_client_test.cpp
+        test/wifi_client_test.cpp
         test/observable_test.cpp
         test/unhandled_rejection_test.cpp
         test/ota_policy_test.cpp
@@ -214,6 +220,7 @@ if(BUILD_TESTING)
         test/ota_config_test.cpp
         test/ota_js_hooks_test.cpp
         test/ota_wire_fixtures_test.cpp
+        test/schema_conformance_test.cpp
         test/sys_codec_test.cpp
     )
 
@@ -233,9 +240,25 @@ if(BUILD_TESTING)
     )
     add_dependencies(mikrojs_tests gen_checkin_fixtures)
 
+    # ── Schema conformance fixtures ──────────────────────────────────
+    # mikro/schema has two implementations: @mikrojs/schema (host) and
+    # src/mik_schema.cpp (device). The generator records what core.ts does and
+    # test/schema_conformance_test.cpp replays it through the native module.
+    # Always regenerated so the fixtures cannot lag core.ts.
+    set(_SCHEMA_FIXTURE_DIR "${CMAKE_CURRENT_BINARY_DIR}/gen/schema-fixtures")
+    add_custom_target(gen_schema_fixtures
+        COMMAND node "${CMAKE_CURRENT_SOURCE_DIR}/scripts/gen-schema-fixtures.js"
+            "${_SCHEMA_FIXTURE_DIR}"
+        COMMENT "Generating schema conformance fixtures from @mikrojs/schema"
+        WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+        VERBATIM
+    )
+    add_dependencies(mikrojs_tests gen_schema_fixtures)
+
     target_link_libraries(mikrojs_tests PRIVATE mikrojs)
     target_compile_definitions(mikrojs_tests PRIVATE
-        "MIK_CHECKIN_FIXTURE_DIR=\"${_CHECKIN_FIXTURE_DIR}\"")
+        "MIK_CHECKIN_FIXTURE_DIR=\"${_CHECKIN_FIXTURE_DIR}\""
+        "MIK_SCHEMA_FIXTURE_DIR=\"${_SCHEMA_FIXTURE_DIR}\"")
     target_include_directories(mikrojs_tests PRIVATE
         "${CMAKE_CURRENT_SOURCE_DIR}/test"
         "${CMAKE_CURRENT_SOURCE_DIR}/deps/nanocbor/include"

package/include/mikrojs/mem.h

@@ -36,4 +36,8 @@ void mik__oom_inject_fail_after(int64_t n);
 /* Net live allocations across all mem.cpp allocators, for leak checks
  * spanning an inject/recover cycle. */
 int64_t mik__oom_inject_live_allocs(void);
+/* Force the usable-size latch for hook-mode allocator tests: fn installs
+ * a fake platform hook, null restores header mode. Pointers must not
+ * cross a mode switch — the mode decides the allocation's offset. */
+void mik__usable_size_latch_override(size_t (*fn)(const void* ptr));
 #endif

package/include/mikrojs/ota_client.h

@@ -178,9 +178,9 @@ public:
      * 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);
+    /* Start the free-running loop. Returns false, with no loop started, on an
+     * un-enrolled device. At most one watch per client. */
+    bool 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

package/include/mikrojs/platform.h

@@ -53,6 +53,14 @@ typedef struct MIKPlatform {
     /** PSRAM-targeted realloc. Grows or moves the allocation while keeping
      *  it in PSRAM. Same fallback rules as malloc_psram. */
     void* (*realloc_psram)(void* ptr, size_t size);
+    /** Usable size of a live allocation made by this platform's allocators
+     *  (malloc/calloc/realloc and the *_psram variants), as reported by
+     *  libc malloc_usable_size / malloc_size or ESP-IDF's
+     *  heap_caps_get_allocated_size. When provided, the runtime lets
+     *  QuickJS account blocks by their real size instead of prepending a
+     *  per-allocation size header (one word per live block). NULL keeps
+     *  the header scheme. */
+    size_t (*malloc_usable_size)(const void* ptr);
     bool (*get_fs_info)(const char* label, size_t* total, size_t* used);
     void (*log)(int level, const char* tag, const char* fmt, ...);
     int (*stdout_write)(const void* buf, size_t len);

package/include/mikrojs/private.h

@@ -115,6 +115,10 @@ struct MIKRuntime {
      * mik__result_ok_void. Safe to share because Result is immutable by
      * convention, and the singleton is frozen + non-extensible. */
     JSValue result_ok_void_singleton;
+    /* Shared BodyConsumedError constructor for the native mikro/http/helpers
+     * module. Created lazily on first http module init, freed in
+     * MIK_FreeRuntime. */
+    JSValue http_body_consumed_ctor;
     JSValue env_obj;  /* Frozen object with env vars, set on import.meta.env */
     struct {
         JSValue on_data;  /* JS callback for stdin data, JS_UNDEFINED when not listening */
@@ -255,9 +259,33 @@ std::string mik_inspect(JSContext* ctx, JSValue value, int depth = 2, bool color
                         bool show_hidden = false);
 void mik__inspect_register(JSContext* ctx);
 
+/* HTTP client modules mikro/http/helpers + mikro/http/request
+ * (mik_http_client.cpp). Loaded lazily via the C-module table in
+ * modules.cpp, not registered at runtime creation. */
+JSModuleDef* mik__http_helpers_load(JSContext* ctx);
+JSModuleDef* mik__http_request_load(JSContext* ctx);
+
+/* Wifi client module mikro/wifi (mik_wifi_client.cpp), same lazy table. */
+JSModuleDef* mik__wifi_client_load(JSContext* ctx);
+
+/* Load `specifier` through the module loader on behalf of `importer` and
+ * return its namespace (modules.cpp). Honors virtual-module overrides. */
+JSValue mik__load_module_ns(JSContext* ctx, const char* importer, const char* specifier,
+                            bool require_evaluated);
+
+/* Timer registry (timers.cpp) — direct scheduling for native callbacks that
+ * must not go through the JS setTimeout global. Schedule dups `func`. */
+uint32_t MIK_Timer_Schedule(MIKTimers* timers, JSContext* ctx, JSValue func, int argc,
+                            const JSValue* argv, int64_t timeout, bool is_interval, int64_t now);
+bool MIK_Timer_UnSchedule(MIKTimers* timers, JSContext* ctx, uint32_t id);
+
 /* CBOR module (mik_cbor.cpp) */
 JSModuleDef* mik__cbor_init(JSContext* ctx);
 
+/* Schema module (mik_schema.cpp). Registered lazily: the loader calls its
+ * init on first import of native:mikro/schema. */
+void mik__schema_register(void);
+
 /* Result module (mik_result.cpp) */
 JSModuleDef* mik__result_init(JSContext* ctx);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/native",
-  "version": "0.18.2",
+  "version": "0.19.0-pr-352.20260829215534",
   "description": "Mikro.js C++ runtime library and Node.js native addon",
   "keywords": [
     "esp32",
@@ -70,8 +70,6 @@
     "./runtime/reader/types": "./runtime/reader/types.ts",
     "./runtime/result/native-result.node-shim": "./dist/runtime/result/native-result.node-shim.js",
     "./runtime/result/types": "./runtime/result/types.ts",
-    "./runtime/schema/core": "./dist/runtime/schema/core.js",
-    "./runtime/schema/shared": "./dist/runtime/schema/shared.js",
     "./runtime/schema/types": "./runtime/schema/types.ts",
     "./runtime/sleep/types": "./runtime/sleep/types.ts",
     "./runtime/sntp/types": "./runtime/sntp/types.ts",
@@ -88,14 +86,15 @@
     "cmake-js": "^8.0.0",
     "node-addon-api": "^8.7.0",
     "node-gyp-build": "^4.8.4",
-    "@mikrojs/quickjs": "0.18.2"
+    "@mikrojs/quickjs": "0.19.0-pr-352.20260829215534+23027de"
   },
   "devDependencies": {
     "@swc/core": "^1.15.30",
     "@types/node": "^24.12.2",
     "esbuild": "^0.28.0",
     "terser": "^5.46.2",
-    "@mikrojs/registry": "0.18.2"
+    "@mikrojs/registry": "0.19.0-pr-352.20260829215534+23027de",
+    "@mikrojs/schema": "0.19.0-pr-352.20260829215534+23027de"
   },
   "engines": {
     "node": ">=24.0.0"

package/runtime/http/helpers.ts

@@ -2,6 +2,11 @@
 // `native:mikro/http`. Apps driving HTTP through a non-lwIP transport (e.g. an
 // LTE modem over UART) implement the `Request` type directly and reuse
 // `prepareBody` + `makeResponse` for the boring parts.
+//
+// On-device, `mikro/http/helpers` is the native C module in
+// src/mik_http_client.cpp (behavior pinned by test/http_client_test.cpp).
+// This TS source stays as the type surface and as the Node-side double for
+// the http/server vitest suite.
 
 import {err, ok} from 'mikro/result'
 

package/runtime/internal.d.ts

@@ -26,6 +26,34 @@ declare module 'native:mikro/cbor' {
   export function decode(data: Uint8Array): Result<unknown, CborError>
 }
 
+declare module 'native:mikro/schema' {
+  import type * as S from '@mikrojs/native/runtime/schema/types'
+  /* typeof-aliased rather than re-exported: `export ... from` inside an
+   * ambient module declaration resolves to never, and writing the generic
+   * signatures out again here would be a third copy of the surface. */
+  export const string: typeof S.string
+  export const number: typeof S.number
+  export const boolean: typeof S.boolean
+  export const unknown: typeof S.unknown
+  export const literal: typeof S.literal
+  export const array: typeof S.array
+  export const object: typeof S.object
+  export const tuple: typeof S.tuple
+  export const optional: typeof S.optional
+  export const union: typeof S.union
+  export const enumOf: typeof S.enumOf
+  export const taggedUnion: typeof S.taggedUnion
+  export const applyDefaults: typeof S.applyDefaults
+  export const SchemaError: typeof S.SchemaError
+  /* The plain {ok, error} envelope core.ts's local err() builds, not a
+   * mikro/result Result: parse() in schema.ts wraps it. */
+  export function validate(
+    schema: S.Schema,
+    value: unknown,
+    path: string,
+  ): {ok: false; error: S.SchemaError} | null
+}
+
 declare module 'native:mikro/result' {
   import type {ErrResult, OkResult} from './result/types.js'
   export function ok(): OkResult<void>
@@ -533,12 +561,21 @@ declare module 'native:mikro/udp' {
 }
 
 declare module 'native:mikro/ota_client' {
-  import type {CheckOptions, CheckResult, Ota, Watcher, WatchOptions} from './ota/types.js'
+  import type {Result} from 'mikro/result'
+
+  import type {
+    CheckOptions,
+    CheckResult,
+    NotEnrolledError,
+    Ota,
+    Watcher,
+    WatchOptions,
+  } from './ota/types.js'
 
   // Backed by src/mik_ota_client.cpp, src/mik_ota_config.cpp and
   // src/mik_ota_policy.cpp.
   export function check(options?: CheckOptions): Promise<CheckResult>
-  export function watch(options?: WatchOptions): Watcher
+  export function watch(options?: WatchOptions): Result<Watcher, NotEnrolledError>
   export function config(): unknown
 
   // The mikro/ota policy surface.
@@ -549,6 +586,8 @@ declare module 'native:mikro/ota_client' {
   export const parseConfig: Ota['parseConfig']
   export const applyConfig: Ota['applyConfig']
   export const configState: Ota['configState']
+  export const report: Ota['report']
+  export const settle: Ota['settle']
   export const confirm: Ota['confirm']
   export const revert: Ota['revert']
   export const bearer: Ota['bearer']

package/runtime/ota/client.ts

@@ -14,6 +14,7 @@ export type {
   CheckOptions,
   CheckResult,
   DeclineReason,
+  NotEnrolledError,
   Teardown,
   Watcher,
   WatchOptions,
@@ -34,5 +35,8 @@ export const check = nativeCheck
  * 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.
+ *
+ * Returns the watcher as a Result: an un-enrolled device gets an
+ * `err({name: 'NotEnrolled'})` and no loop is started.
  */
 export const watch = nativeWatch

package/runtime/ota/ota.ts

@@ -17,8 +17,10 @@ import {
   parseOffer,
   reconcile,
   registry,
+  report,
   revert,
   running,
+  settle,
 } from 'native:mikro/ota_client'
 
 import type {Ota} from './types.js'
@@ -36,6 +38,8 @@ const ota: Ota = {
   parseConfig,
   applyConfig,
   configState,
+  report,
+  settle,
 }
 
 export {ota}

package/runtime/ota/types.ts

@@ -197,6 +197,45 @@ export interface ConfigErrorReport {
   message: string
 }
 
+/** The check-in body a device owes its registry, as `ota.report()` builds it.
+ *  Field shapes match the wire, so a client (or the proxy behind it) can
+ *  forward fields verbatim into `POST /api/v1/checkin`. */
+export interface CheckinReport {
+  deviceId: string
+  /** Firmware version string. */
+  firmware: string
+  firmwareHash: string
+  /** QuickJS bytecode format version the running engine reads. */
+  bytecode: number
+  running: RunningBuild
+  /** The device-owned name pair: `[rev, name]`, or `[rev]` when never named
+   *  or cleared. Sent every round so a lost response settles on the next
+   *  check-in. */
+  name: [rev: number, name?: string]
+  /** Free bytes on the user partition. Absent when the platform cannot say. */
+  free?: number
+  /** Why a previous install failed. Present after a `reconcile()` that found
+   *  one, until a `settle()` marks it delivered. */
+  lastInstall?: Diagnostic
+  /** The held document's rev to echo; see {@link ConfigState.rev}. */
+  configRev?: string
+  /** A rolled-back document to report; see {@link ConfigState.error}. */
+  configError?: ConfigErrorReport
+}
+
+/** What `ota.settle()` took from a completed check-in's response. */
+export interface SettleOutcome {
+  /** A validated build offer, for the app's `applyOffer` call: the download
+   *  is the one piece of the round that stays the app's. Absent when the
+   *  response carried none. */
+  offer?: Offer
+  /** What the config delivery did, when the response carried a document.
+   *  Only `'failed'` and `'invalid'` are worth logging; see {@link ConfigWrite}. */
+  config?: ConfigWrite
+  /** A name pair was adopted from the response (a clear counts). */
+  renamed: boolean
+}
+
 declare global {
   /**
    * Merge your app's config type into this interface (next to the schema
@@ -318,6 +357,37 @@ export interface Ota {
    * re-served forever and nobody is told.
    */
   configState(): ConfigState
+  /**
+   * The check-in body the device owes its registry, assembled: identity,
+   * `running()`, the name pair, free storage, the pending `lastInstall`
+   * report, and what `configState()` resolves. One call instead of gathering
+   * the fields by hand, and the same facts the built-in client sends.
+   *
+   * Call `reconcile()` first, on every boot: it is what surfaces the
+   * `lastInstall` report this reads (`settle()` marks it delivered).
+   */
+  report(): CheckinReport
+  /**
+   * Take a COMPLETED check-in's response, whole: confirm the running trial
+   * and a read config document's trial (exactly `confirm()`), adopt a
+   * delivered name pair, store a delivered config document (exactly
+   * `applyConfig`, with `trialBoots`), and validate the offer fields (exactly
+   * `parseOffer(raw)`, with `allowInsecure`). An empty or null response is
+   * the registry's quiet round: nothing to deliver, and the confirm still
+   * happens, which is the point of calling. A response that is anything else,
+   * a string or a number, never decoded (a captive portal's HTML, a proxy's
+   * error page), so it is not a completed round: nothing settles, and the
+   * confirm does not run.
+   *
+   * Never call it on a failed request: a check-in that did not complete
+   * proves nothing about the running build, and settling it would keep
+   * exactly what rollback exists to catch.
+   *
+   * What stays the app's: the download (`applyOffer` with the returned
+   * offer), the restart after `'staged'`, and reading `ota.config()` in the
+   * same cycle so a delivered document's trial can settle.
+   */
+  settle(raw: unknown, options?: {trialBoots?: number; allowInsecure?: boolean}): SettleOutcome
 }
 
 /** The `mikro/ota` singleton. The runtime value is provided by the on-device
@@ -398,6 +468,11 @@ export interface WatchOptions extends CheckOptions {
   onConfig?(config: RegisteredConfig): void
 }
 
+/** `watch()` on a device with no enrollment pair (registry url + update key) in
+ *  the system store. Permanent for this boot: enrollment is provisioned over
+ *  the cable by `mikro ota enroll`, and a restart is what picks it up. */
+export type NotEnrolledError = {name: 'NotEnrolled'; message: string}
+
 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

package/runtime/schema/schema.ts

@@ -1,30 +1,52 @@
+/* mikro/schema. The constructors, the validator and applyDefaults are native
+ * (src/mik_schema.cpp); all this adds is the Result-returning parse(), which
+ * is the only part that needs mikro/result.
+ *
+ * @mikrojs/schema is the same DSL in TypeScript and is what the host
+ * runs (the CLI evaluating mikro.config.ts, the registry, vitest). The two are
+ * held together by scripts/gen-schema-fixtures.js and
+ * test/schema_conformance_test.cpp — change core.ts first, then mik_schema.cpp.
+ *
+ * validate() is deliberately not re-exported: parse() is the public entry, and
+ * that has been true since this module was bytecode. */
+
 import {err, ok} from 'mikro/result'
+import {validate} from 'native:mikro/schema'
 
 import type {Result} from '../result/types.js'
-import {type Infer, type Schema, type SchemaError, validate} from './core.js'
+import type {Infer, Schema, SchemaError} from './types.js'
 
 export type {
+  ArrayOptions,
   ArraySchema,
   BooleanSchema,
   DefaultOption,
+  DisplayOptions,
+  EnumEntry,
+  Format,
   Infer,
   InferRead,
   LiteralSchema,
+  MaskableOptions,
+  NumberOptions,
   NumberSchema,
   ObjectSchema,
   OptionalSchema,
   ScalarOptions,
   Schema,
+  StringOptions,
   StringSchema,
   TaggedUnionSchema,
   TupleSchema,
   UnionSchema,
+  Unit,
   UnknownSchema,
-} from './core.js'
+} from './types.js'
 export {
   applyDefaults,
   array,
   boolean,
+  enumOf,
   literal,
   number,
   object,
@@ -35,7 +57,7 @@ export {
   tuple,
   union,
   unknown,
-} from './core.js'
+} from 'native:mikro/schema'
 
 export function parse<S extends Schema>(schema: S, value: unknown): Result<Infer<S>, SchemaError> {
   const result = validate(schema, value, '')