arcane-os 0.57.0 → 0.58.0

package/docs/reference/local-ai.md

@@ -1,13 +1,13 @@
 # Local AI through Core
 
-Core owns native llama.cpp and Ollama processes. The browser retains its own
+Core owns native llama.cpp and Ollama processes and ONNX worker sessions. The browser retains its own
 Wllama and ONNX implementations, and can also use an explicitly connected Core
 when that system service is available. Runtime installation, model loading and
 inference are separate operations.
 
-This native service currently implements llama.cpp and Ollama. Native ONNX
-inference remains separate unfinished work. Browser ONNX continues through its
-existing browser implementation.
+Native ONNX runs caller-selected graphs with complete named input/output tensors.
+Applications own preprocessing, tokenization and model-specific pipelines.
+Browser ONNX continues through its existing browser implementation.
 
 ## Application requirements
 
@@ -19,7 +19,8 @@ Existing native fields remain alongside this record:
 {
   "runtimes": [
     {"id": "llama.cpp"},
-    {"id": "ollama"}
+    {"id": "ollama"},
+    {"id": "onnx"}
   ],
   "llamaCpp": {
     "modelsDirectory": "models/llama"
@@ -31,7 +32,8 @@ Existing native fields remain alongside this record:
 ```
 
 Each runtime requirement accepts `id`, optional upstream `version`, and an
-optional runtime archive `url`. A string runtime ID is also accepted.
+optional runtime archive `url`. ONNX resolves its official npm package or an
+explicitly supplied package archive. A string runtime ID is also accepted.
 Omitting the version allows reuse of an available runtime. Explicit versions
 select that upstream distribution; an existing service must match the requested
 version before it is reused. A service occupying the selected address is
@@ -48,7 +50,7 @@ application. Applications choose and provision their models explicitly.
 ## Development
 
 ```sh
-arcane dev --local-ai llama.cpp,ollama
+arcane dev --local-ai llama.cpp,ollama,onnx
 ```
 
 The option adds those runtime requirements to the authored application
@@ -64,6 +66,13 @@ service or machine environment. Windows and macOS use the host archive utility;
 Linux requires `tar`, and `unzip` when extracting a selected Windows ZIP.
 Zstandard archives use the supported Node runtime's decompressor.
 
+Selected ONNX preparation installs `onnxruntime-node@1.30.0` by default into a
+managed npm prefix, retaining its complete published runtime dependency tree.
+It uses the upstream CPU installation option to skip supplementary GPU downloads.
+Node/npm must be available while preparing that runtime; a native app consumes
+the bundled tree without installing it again. Applications that omit ONNX do
+not install its package.
+
 For the optional development browser connection, load the bootstrap after the
 managed import map and before creating a Core-backed provider:
 
@@ -111,6 +120,9 @@ service and a loaded model are separate facts.
 `localai.services.recover({runtimes: ['llama.cpp']})` makes one explicit recovery
 attempt for the selected runtimes; omission selects all configured runtimes.
 Recovery restarts only SDK-owned processes and reconnects to external services.
+Recovering ONNX releases its sessions; explicitly load models again afterward.
+Its state is `recovering` and unavailable until the previous workers exit and
+the new session owner is ready.
 An external llama.cpp server returns HTTP 503 during initial model loading and
 offers no readiness subscription at that stage. Core retains `state: 'loading'`;
 a subsequent explicit load or recovery request checks again. There is no
@@ -175,6 +187,106 @@ silently change the application's saved model choice. Release registration
 with `unregister()` and dispose the provider at the application's owning
 lifecycle boundary.
 
+## Native ONNX sessions
+
+```js
+import {ensureLocalAIRuntimes} from 'arcane-os/local-ai';
+import {createONNXRuntime} from 'arcane-os/local-ai/onnx';
+
+const [runtime] = await ensureLocalAIRuntimes({
+  runtimes: ['onnx'], directory: '.arcane/local-ai/runtimes'
+});
+const onnx = createONNXRuntime({modulePath: runtime.modulePath});
+try {
+  const loaded = await onnx.load({id: 'cheese-radar', model: absoluteModelPath});
+  // Supply the actual names, shapes and values expected by this graph.
+  const outputs = await onnx.run({id: loaded.id, feeds});
+  console.log(outputs);
+} finally {
+  await onnx.close();
+}
+```
+
+The factory accepts `{modulePath,signal?,onEvent?}` and starts no worker until
+`load({id,model,sessionOptions?,signal?})`. The model path is absolute for this
+direct Node API. Session creation defaults to the CPU execution provider;
+explicit native session options remain caller-owned. The returned session
+record contains `id`, `model`, `state`, `loaded`, `error`, input/output names and
+metadata. A live ID requires explicit unload before replacement. An ID may be
+loaded again once its previous worker exits after a failed load or unload.
+A run error retains the loaded session so a corrected request can use it.
+
+`run({id,feeds,fetches?,runOptions?,signal?})` returns the complete output-name
+map of `{type,dims,data}` tensors. Input records use that same shape with native
+typed data or string arrays. Optional `fetches` selects output names or supplies
+output tensors using the upstream API. Worker transport copies supplied tensor
+data; returned output records contain the results, and caller-owned preallocated
+buffers are not mutated in place. Each session retains its own worker and
+loaded graph; work for independent sessions proceeds concurrently. Runs for one
+session execute in order and wait at that session's loading boundary. There is
+no token streaming in the generic tensor operation.
+
+String input containing U+0000 reports an incompatibility at the native tensor
+boundary: the Node binding uses null-terminated strings and cannot preserve
+that input completely. The SDK does not alter the supplied string.
+
+`current()` returns `{sessions,closed}`. `subscribe(listener)` replays current
+state synchronously and returns an unsubscribe function. Load, readiness,
+unload and failures remain observable. `unload({id,signal?})` releases that
+session; `close()` owns all remaining workers and awaits their actual exits.
+
+Cancelling a queued run removes that run. Cancelling active native work stops
+delivery and retires its worker; the session becomes unavailable until loaded
+again. ONNX Runtime's Node binding offers no native inference interruption:
+worker termination can wait for a native call to return. Shutdown observes the
+actual exit and does not claim that rejecting a request stopped native work.
+Other sessions retain their own lifetimes.
+
+### ONNX through Core and the browser
+
+| Core method | Parameters | Result |
+| --- | --- | --- |
+| `onnx.status` | `{}` | Runtime availability and current `models` session records |
+| `onnx.load` | `{id,model,sessionOptions?}` | Loaded session; relative model paths resolve from `appRoot` |
+| `onnx.run` | `{id,feeds,fetches?,runOptions?}` | Complete encoded tensor output map |
+| `onnx.unload` | `{id}` | Released session record |
+
+Use the browser accessor to handle the Core tensor transport:
+
+```js
+import {createCoreONNXRuntime} from 'arcane-os/ai/core-onnx';
+
+const onnx = createCoreONNXRuntime({client});
+const stop = onnx.subscribe(function showRuntime(state) { console.log(state); });
+await onnx.inspect();
+await onnx.load({id: 'cheese-radar', model: 'models/cheese-radar.onnx'});
+const outputs = await onnx.run({id: 'cheese-radar', feeds});
+await onnx.unload({id: 'cheese-radar'});
+stop();
+onnx.close();
+```
+
+The accessor exposes `load`, `run`, `unload`, `inspect`, `current`, `subscribe`
+and `close`. Request methods accept `signal` and optional `timeoutMs` (default
+`0`, no elapsed-time cutoff). It preserves full typed tensor values, including
+64-bit integers, floating-point special values and strings, through the
+transport codec. `current()` adds `busy` and `closed` to its latest Core state.
+Closing the accessor cancels its requests and subscriptions; model unloading
+is explicit because other accessors may share the Core session. It never
+closes the shared Core client.
+
+Construction neither opens a connection nor installs a runtime. A browser needs
+an already available native Core service or the explicit development bridge.
+Unavailable native ONNX leaves browser ONNX/Wllama under the application's
+existing selection. This tensor API does not select an LLM, tokenizer, speech,
+image or avatar pipeline.
+
+Native ONNX CPU package targets are Windows, Linux and macOS on `x64`/`arm64`,
+as listed in Microsoft's [Node binding platform matrix](https://github.com/microsoft/onnxruntime/blob/v1.30.0/js/node/README.md).
+Android needs its host's native ONNX adapter; the Node package contains no
+Android binding. Platform support here describes upstream package targets,
+not execution evidence on each platform.
+
 ## Native bundling
 
 The SDK portable native build includes selected official runtime trees under
@@ -191,7 +303,29 @@ Architectures are `x64` or `arm64`. Availability depends on the upstream
 runtime's published platform assets; Ollama has no official Android runtime
 archive in this installer.
 
-Ensure returns absolute `{id,version,platform,architecture,root,executable}`
-records. Bundle returns `{runtimes,files}`, with artifact-relative runtime paths
-and a complete emitted file inventory. Bundling requires a fresh native staging
-destination, preserving existing completed outputs.
+Ensure returns absolute `{id,version,platform,architecture,root}` records.
+Server runtimes also include `executable`; ONNX includes `modulePath` pointing
+to its public package entry. Bundle returns `{runtimes,files}`,
+with artifact-relative runtime paths and a complete emitted file inventory.
+Bundling requires a fresh native staging destination, preserving existing
+completed outputs.
+
+### NeMo Speech library runtime
+
+The runtime helpers also accept `{id: 'nemo-speech', version: '0.2.0'}` to
+prepare NVIDIA's official CPU library distribution. An omitted NeMo version
+selects `0.2.0`. Its published targets are Windows `x64`, Linux `x64`/`arm64`,
+and macOS `x64`/`arm64`.
+
+NeMo records include `includeDirectory`, `libraryDirectory`, `binaryDirectory`,
+and `cmakeDirectory`; they have no server `executable`. The complete upstream
+tree remains under `root`, including any archive prefix directory. Use the
+returned `cmakeDirectory` as `NeMoSpeech_DIR` when calling
+`find_package(NeMoSpeech CONFIG REQUIRED COMPONENTS Diarization)`, then link
+the upstream `NeMoSpeech::Diarization` target. Bundling preserves the complete
+tree and makes all these paths relative to the native artifact root.
+
+This helper installs the library. The application configuration and development
+CLI select llama.cpp, Ollama and ONNX services described above;
+NeMo model selection and a native diarization helper belong to their owning
+integration.

package/docs/reference/protocols.md

@@ -47,12 +47,14 @@ These protocols normalize orchestration and results. They do not normalize a
 Windows EXE, Linux DEB, Android APK, and portable directory into the same
 artifact kind.
 
-Portable CLI operations load the installed SDK's
-`arcane-os/native/portable-provider` by default. Explicit `--arcane-root`
-selection retains the checkout provider route; executable targets still need
-their platform provider/toolchain. `arcane-os/core/host` composes the reusable
-native runtime with explicitly supplied app services. Neither export is a
-browser import, executable host or installer. The synchronous classic facade
+Portable CLI operations load `arcane-os/native/portable-provider`; Windows x64
+loads `arcane-os/native/windows-provider`, both from the installed SDK by
+default. The Windows provider assembles the matching precompiled WebView2/SEA
+host release asset. Explicit `--arcane-root` selection retains the checkout
+route; Linux and Android still need their platform provider/toolchain.
+`arcane-os/core/host` composes the reusable native runtime with explicitly
+supplied app services. These Node entries remain separate from browser imports;
+portable itself remains a non-executable payload. The synchronous classic facade
 and browser-safe client retain their separate public entries. Integrated
 shared checks keep their existing Arcane OS development provider.
 
@@ -1047,10 +1049,15 @@ or a dependency is ready.
 
 ### Microsoft NT / WebView2
 
-The renderer uses the WebView2 host messaging surface. The host binds one app
-identity and native policy to the session before Core dispatch. Microsoft NT
-can expose managed-service and privileged platform operations that do not exist
-in an ordinary browser.
+The SDK Windows host mounts the selected app at a virtual HTTPS origin and
+injects the canonical classic facade before application scripts. Ordered
+`arcane/1` requests and complete responses cross its owned WebView2/Core bridge;
+each connected document requests authoritative runtime/service replay. Its
+selected service composition supplies the actual methods. Closing the window
+cancels renderer requests and drains accepted service work before Core exits.
+See [Windows executable packaging](core-native-packaging.md#windows-executable).
+Arcane OS can separately compose product policy and privileged services; the
+generic SDK host does not copy that product composition.
 
 ### Linux / WebKitGTK
 
@@ -1070,12 +1077,13 @@ reachable.
 
 ### macOS
 
-No macOS executable target, native bridge, platform host, artifact, or run
-contract is exposed by this SDK version. A browser may still run browser-only
-application code. A separately composed macOS host may use the reusable Node
-Core runtime, framed stdio transport, host composition, and portable payload,
-but those SDK primitives do not create a native bridge or executable host and
-do not by themselves satisfy a native capability.
+This version includes Foundation-only `ArcaneCoreProcess` source for an
+explicit executable, framed pipes and graceful child lifecycle. It supplies no
+macOS renderer bridge, executable target, artifact or run command. A separately
+composed macOS host may combine that source with the reusable Node runtime,
+stdio transport, host composition and portable payload. Source delivery does
+not establish compilation or execution on macOS. See
+[the macOS process-source contract](core-native-packaging.md#macos-process-source).
 
 ## Development and remote HTTP transport
 
@@ -1159,9 +1167,10 @@ The common contract ends where platform truth must remain different:
   not run an unrelated browser implementation as a substitute;
 - the portable target defaults to the installed SDK provider and assembles a
   non-executable payload without an Arcane OS checkout;
-- executable native targets require their explicit checkout/provider, and the
-  composed host must supply the protocol, version, features, capabilities,
-  methods, and services that its application contract requires;
+- Windows x64 defaults to the installed SDK's matching precompiled host;
+  Linux/Android retain explicit checkout/providers. Every composed host must
+  supply the protocol, version, features, capabilities, methods and services
+  that its application contract requires;
 - that current-build compatibility does not promise that a future SDK will accept
   this Core or that this SDK will accept a future Core.
 

package/docs/reference/pwa.md

@@ -261,11 +261,14 @@ origin root and starts at the selected app entry: `/index.html` for a standalone
 root app with that entry, or `/apps/<id>/<entry>` for a nested app. Use one
 selected app per development origin. The SDK uses `node-http-server` for source
 and packaged-preview serving, including conditional resource responses.
-Arcane development servers default to HTTPS, including localhost, and packaged
-browser previews require HTTPS. Configure the workspace certificate pair before
+Arcane development servers and packaged browser previews default to HTTPS,
+including localhost. Configure the workspace certificate pair before
 starting the ordinary command; see [development HTTPS setup](cli.md#development-https-setup).
 Explicit source-only `arcane dev --http` serves the same generated PWA routes
 without loading certificates; see [explicit HTTP development](cli.md#explicit-http-development).
+API callers may select `http:true` in packaged mode to serve the existing
+packaged web root, without generating or changing its PWA files. Browser
+secure-context and installation requirements remain browser-owned.
 `--public` selects the IPv4 wildcard bind address; it does not enable PWA
 configuration, change manifest metadata, or determine browser installability.