arcane-os 0.93.0 → 0.95.0

package/docs/reference/inventory/package-api.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.92.0",
+  "sdkVersion": "0.94.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 308,
+  "memberCount": 314,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
@@ -166,6 +166,90 @@
       "protocol": "arcane/1 service definition",
       "normalization": "Binding identity equals the named createNativeDecisionService export"
     },
+    {
+      "id": "local-ai-kokoro:createNativeKokoroRuntime",
+      "name": "createNativeKokoroRuntime",
+      "displayName": "createNativeKokoroRuntime()",
+      "kind": "function",
+      "signature": "createNativeKokoroRuntime({onnx,modelAssets,runtime,prepare,modelId='kokoro',model=KOKORO_MODEL,revision=KOKORO_REVISION,dtype='fp32',paths,assetProjectionId,resourcePaths,sessionOptions,executionPreference='gpu',executionTarget,signal,onEvent}={})",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "Composes the selected Kokoro FP32 graph with the host's existing ONNX/model-resource owners and a persistent native phonemization/Opus helper.",
+      "availability": "Node with matching prepared helper/data and ONNX resources; SDK helper archive for Windows x64, other hosts require a matching custom helper distribution",
+      "protocol": "Replaying kokoro.state, retained ONNX activation and complete ordered native speech requests",
+      "normalization": "Returns current/subscribe/load/synthesize/unload/close; construction performs no preparation or inference. Explicit load selects a DBOPFS projection or complete native resource paths; synthesis retains complete ordered input, selected US/GB voice and 24kHz mono WAV or Ogg Opus output. Active cancellation joins owned helper/session retirement and preserves surviving queued work on the same configured provider; ONNX native interruption may wait for the current call. No alternate model, voice or provider retry is introduced. See native-speech.md for exact activation, selection and result contracts."
+    },
+    {
+      "id": "local-ai-kokoro:default",
+      "name": "default",
+      "displayName": "createNativeKokoroRuntime default export",
+      "kind": "function",
+      "signature": "default as createNativeKokoroRuntime",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "Default binding for the same native Kokoro engine factory.",
+      "availability": "Node with matching prepared native resources",
+      "protocol": "Native Kokoro engine lifecycle",
+      "normalization": "Binding identity equals the named createNativeKokoroRuntime export"
+    },
+    {
+      "id": "local-ai-kokoro:KOKORO_MODEL",
+      "name": "KOKORO_MODEL",
+      "displayName": "KOKORO_MODEL",
+      "kind": "constant",
+      "signature": "const KOKORO_MODEL",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "Identifies the Kokoro model implemented by the native frontend.",
+      "availability": "Node",
+      "protocol": "Native model selection",
+      "normalization": "Value is onnx-community/Kokoro-82M-v1.0-ONNX; constructor selection preserves this model's FP32 graph and resource contract"
+    },
+    {
+      "id": "local-ai-kokoro:KOKORO_REVISION",
+      "name": "KOKORO_REVISION",
+      "displayName": "KOKORO_REVISION",
+      "kind": "constant",
+      "signature": "const KOKORO_REVISION",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "Identifies the selected upstream Kokoro model revision.",
+      "availability": "Node",
+      "protocol": "Native model resource selection",
+      "normalization": "Value is 1939ad2a8e416c0acfeecc08a694d14ef25f2231; graph, tokenizer and voice resources use this same revision"
+    },
+    {
+      "id": "local-ai-kokoro:KOKORO_SAMPLE_RATE",
+      "name": "KOKORO_SAMPLE_RATE",
+      "displayName": "KOKORO_SAMPLE_RATE",
+      "kind": "constant",
+      "signature": "const KOKORO_SAMPLE_RATE",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "Native Kokoro PCM synthesis rate in samples per second.",
+      "availability": "Node",
+      "protocol": "Audio format",
+      "normalization": "Value is 24000; the selected output is mono WAV or Ogg Opus with the complete synthesized sample sequence"
+    },
+    {
+      "id": "local-ai-kokoro:KOKORO_VOICES",
+      "name": "KOKORO_VOICES",
+      "displayName": "KOKORO_VOICES",
+      "kind": "constant",
+      "signature": "const KOKORO_VOICES",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "The 28 supported US and British English voice identifiers for the selected native Kokoro resources.",
+      "availability": "Node",
+      "protocol": "Native speech voice selection",
+      "normalization": "Complete ordered voice array exported by the frontend; af_heart is the omitted voice default. An unsupported explicit voice reports its actual incompatibility without substitution."
+    },
     {
       "id": "local-ai-whisper:createWhisperRuntime",
       "name": "createWhisperRuntime",
@@ -345,8 +429,8 @@
       "group": "Core native speech",
       "summary": "Composes host-supplied transcription and synthesis engines with independent loading and role readiness.",
       "availability": "Node Core with explicitly supplied engines; engine platform, model and format support remain engine-owned",
-      "protocol": "arcane/1 speech.status/transcribe/synthesize with speech.state/progress",
-      "normalization": "Returns current/subscribe/close/start/methods/drain/dispose; forwards complete requests and results unchanged; replaying service state, synchronous accepted Thinking, combined request/lifetime cancellation and concurrent joined engine shutdown; no engine installation or automatic provider selection"
+      "protocol": "arcane/1 speech.status/load/unload/transcribe/synthesize with speech.state/progress",
+      "normalization": "Returns current/subscribe/close/start/methods/drain/dispose; forwards complete requests and results unchanged; replaying service state, synchronous accepted Thinking, combined request/lifetime cancellation and concurrent joined engine shutdown. Explicit load/unload require role stt or tts and forward the remaining activation fields and complete result through that role's configured engine; supported preparation remains with that engine. Startup waiting is independently owned from caller cancellation; no automatic provider selection is introduced."
     },
     {
       "id": "core-speech:default",
@@ -609,10 +693,10 @@
       "entrypoints": ["arcane-os/local-ai"],
       "primaryImport": "arcane-os/local-ai",
       "group": "Core local AI",
-      "summary": "Reuses selected managed native runtimes or installs complete llama.cpp/Ollama/image distributions, ONNX npm runtime trees with selected SDK native libraries, or NeMo libraries.",
+      "summary": "Reuses selected managed native runtimes or installs complete llama.cpp/Ollama/image distributions, ONNX npm runtime trees with selected SDK native libraries, NeMo libraries, or Kokoro native helper/data trees.",
       "availability": "Node; selected distribution platform and architecture assets determine runtime availability",
       "protocol": "Upstream release archives and selected ONNX/Koffi npm installations; corrected Windows x64 ONNX native libraries from the installed SDK numeric release",
-      "normalization": "Returns absolute runtime records, including image library/binding/variant/model metadata; Windows x64 ONNX with no explicit URL and omitted version or 1.30.0 adds nativeDistributionRevision 1.30.0-directml-reshape-1, reuses that revision or prepares a fresh installation while preserving older trees; explicit URLs and other ONNX versions/platforms retain their upstream package path; shares matching installs, preserves libraries, reports failures without changing global PATH or services and prepares no model files"
+      "normalization": "Returns absolute runtime records, including image library/binding/variant/model metadata; Windows x64 ONNX with no explicit URL and omitted version or 1.30.0 adds nativeDistributionRevision 1.30.0-directml-reshape-1, reuses that revision or prepares a fresh installation while preserving older trees; explicit URLs and other ONNX versions/platforms retain their upstream package path; shares matching installs, preserves libraries, reports failures without changing global PATH or services and prepares no model files. Kokoro returns helperExecutable, espeakDataDirectory and libraryDirectory for the complete selected helper tree; Windows x64 defaults to the installed SDK numeric release, while explicit url/helperRoot supplies another prepared distribution and preserves model/ONNX ownership."
     },
     {
       "id": "local-ai:bundleLocalAIRuntimes",
@@ -626,7 +710,7 @@
       "summary": "Copies selected complete runtime distributions into a fresh native artifact staging root.",
       "availability": "Node; supports bundling selected published platform assets independently of the build host",
       "protocol": "Artifact-relative runtime/local-ai layout",
-      "normalization": "Returns {runtimes,files} with artifact-relative runtime/variant paths and complete inventory; corrected Windows x64 ONNX retains nativeDistributionRevision and complete native libraries while modulePath becomes artifact-relative; image URL descriptors remain for post-launch preparation and external model working paths report portability incompatibility"
+      "normalization": "Returns {runtimes,files} with artifact-relative runtime/variant paths and complete inventory; corrected Windows x64 ONNX retains nativeDistributionRevision and complete native libraries while modulePath becomes artifact-relative; image URL descriptors remain for post-launch preparation and external model working paths report portability incompatibility. Kokoro retains the complete helper/data tree and relocates helperExecutable, espeakDataDirectory and libraryDirectory; ONNX and model resources retain their separate owners."
     },
     {
       "id": "root:WS",
@@ -4122,7 +4206,7 @@
       "summary": "Sends one complete TWiN Cloud request with an explicit caller-owned key and model.",
       "availability": "Node and Browser; remote HTTPS provider",
       "protocol": "TWiN Cloud complete-response chat",
-      "normalization": "Preserves complete messages and parsed provider JSON; maps explicit structured-output, tool, and reasoning options; shares overload-only HTTP 429 retry after 3000 ms and cancellation; retains no browser profile, storage, or request history"
+      "normalization": "Preserves complete messages and provider JSON; Fetch rejection and all HTTP 429/529 share three retries; quota recovery honors Retry-After or exponential delay with transient same-endpoint/credential pacing, complete terminal errors and cancellation; retains no browser profile, storage, or history"
     },
     {
       "id": "twin-cloud:fetchSystemOneRequest",
@@ -4171,21 +4255,21 @@
       "name": "fetchHTTPResponse",
       "displayName": "fetchHTTPResponse()",
       "kind": "function",
-      "signature": "async fetchHTTPResponse(url,options)",
+      "signature": "async fetchHTTPResponse(url,options,{onRetry=null}={})",
       "entrypoints": ["arcane-os/ai/twin-cloud"],
       "primaryImport": "arcane-os/ai/twin-cloud",
       "group": "Shared AI transport integration",
       "summary": "Returns a successful unconsumed Fetch Response through the shared AI HTTP owner.",
       "availability": "Node and Browser",
       "protocol": "Shared AI HTTP transport",
-      "normalization": "Preserves caller Fetch options and complete error bodies; repeats only overload HTTP 429 after 3000 ms; signal cancellation uses ARCANE_AI_REQUEST_ABORTED"
+      "normalization": "Preserves caller Fetch options and complete errors; Fetch rejection and all HTTP 429/529 share three retries; Retry-After or exponential quota delay and transient same-endpoint/credential pacing remain abortable; onRetry observes waiting/requesting; cancellation uses ARCANE_AI_REQUEST_ABORTED"
     },
     {
       "id": "twin-cloud:fetchJSONResponse",
       "name": "fetchJSONResponse",
       "displayName": "fetchJSONResponse()",
       "kind": "function",
-      "signature": "async fetchJSONResponse(url,options)",
+      "signature": "async fetchJSONResponse(url,options,{onRetry=null}={})",
       "entrypoints": ["arcane-os/ai/twin-cloud"],
       "primaryImport": "arcane-os/ai/twin-cloud",
       "group": "Shared AI transport integration",
@@ -4360,7 +4444,7 @@
       "summary": "Projects a Core client into the established application-facing Arcane namespace.",
       "availability": "Browser and native WebView JavaScript hosts with a Core client",
       "protocol": "arcane/1 compatibility facade",
-      "normalization": "Routes namespace methods through client.invoke while retaining operation-specific parameters, correlation, streaming callbacks, timeouts and cancellation; window.state({signal}?) reads the requesting window and window.setState({state},{signal}?) selects normal, maximized or fullscreen. The matching Windows host returns {platform:'windows',supported:true,state}, including observed minimized state, restores normal bounds/frame controls on leaving fullscreen and prevents activation/focus assignment during visible state transitions without changing TopMost, Core, origin or profile. Saved Settings remain application-owned; cancellation does not undo an applied change and unavailable hosts retain their actual errors without fallback. window.setTheme(presentation,{signal}?) forwards the complete per-window backgroundColor/textColor record, with omitted fields unchanged and null reset, and returns the host's actual applied/unsupported result without changing system appearance. notifications.status/show/state/close forward complete caller requests and standard invoke options; status normalizes only METHOD_NOT_ALLOWED with core-namespace-unavailable while retaining the complete original error. Matching native window hosts retain complete notification records and ordered revisions across renderer navigation, with notifications.state events and subscribe-before-snapshot recovery. Submitted means native Show returned, not displayed or read; cancellation after submission does not remove an accepted notice, and explicit close retains its record. Recipient, text, trigger, deduplication and navigation policy remains application-owned"
+      "normalization": "Routes namespace methods through client.invoke while retaining operation-specific parameters, correlation, streaming callbacks, timeouts and cancellation; window.state({signal}?) reads the requesting window and window.setState({state},{signal}?) selects normal, maximized or fullscreen. The matching Windows host returns {platform:'windows',supported:true,state}, including observed minimized state, restores normal bounds/frame controls on leaving fullscreen and prevents activation/focus assignment during visible state transitions without changing TopMost, Core, origin or profile. Saved Settings remain application-owned; cancellation does not undo an applied change and unavailable hosts retain their actual errors without fallback. window.setTheme(presentation,{signal}?) forwards the complete per-window backgroundColor/textColor record, with omitted fields unchanged and null reset, and returns the host's actual applied/unsupported result without changing system appearance. notifications.status/show/state/close forward complete caller requests and standard invoke options; status normalizes only METHOD_NOT_ALLOWED with core-namespace-unavailable while retaining the complete original error. Matching native window hosts retain complete notification records and ordered revisions across renderer navigation, with notifications.state events and subscribe-before-snapshot recovery. Submitted means native Show returned, not displayed or read; cancellation after submission does not remove an accepted notice, and explicit close retains its record. Recipient, text, trigger, deduplication and navigation policy remains application-owned. speech.load(request,options) and speech.unload(request,options) forward complete activation requests, cancellation and request observers with no elapsed-time cutoff; selected engines own preparation and native retirement."
     },
     {
       "id": "core-client:installCoreClient",

package/docs/reference/local-ai.md

@@ -1,13 +1,16 @@
 # Local AI through Core
 
 Core owns native llama.cpp and Ollama processes, ONNX worker sessions,
-selected local image generation and retained Whisper transcription. The browser retains its own
+selected local image generation, retained Whisper transcription and native
+Kokoro synthesis. 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.
 
 Native ONNX runs caller-selected graphs with complete named input/output tensors.
-Applications own preprocessing, tokenization and model-specific pipelines.
+Applications own preprocessing, tokenization and model-specific pipelines unless
+they explicitly select an SDK engine such as native Kokoro, which owns its
+versioned speech frontend.
 Browser ONNX continues through its existing browser implementation.
 
 ## Application requirements
@@ -113,6 +116,71 @@ the SDK does not guess a companion location. Installation records distinguish
 the distribution's `backend` from its `requestedBackend` execution mode.
 Selecting an unavailable distribution reports its actual error.
 
+### Native Kokoro selection
+
+Select both the existing ONNX runtime and the native speech helper:
+
+```json
+{
+  "runtimes": [
+    {"id": "onnx"},
+    {"id": "kokoro-native", "modelId": "kokoro"}
+  ]
+}
+```
+
+`kokoro-native` is the installable helper ID, `kokoro-onnx` is the speech
+provider ID, and `kokoro` is the default model alias. The requirement also
+preserves `model`, `revision`, `dtype`, prepared `paths`, `assetProjectionId`,
+`resourcePaths`, `sessionOptions`, `executionPreference` and `executionTarget`
+for the engine. The implemented model/revision, complete resource mapping,
+voices, synthesis formats and cancellation contract are in
+[native speech](native-speech.md#native-kokoro-engine).
+
+With no `helperRoot` or `url`, Windows x64 preparation selects
+`arcane-kokoro-windows-x64.tar.gz` from the installed SDK's numeric release:
+`https://github.com/TheWizardNexus/arcane-os-sdk/releases/download/<sdk-version>/arcane-kokoro-windows-x64.tar.gz`.
+That SDK version selects the default helper release; an authored runtime
+`version` alone does not select another SDK release's helper.
+An explicit `url` selects a complete platform-matching archive, with optional
+`version` metadata. Alternatively, `helperRoot` supplies an already prepared
+complete tree copied into the new installation. Select one of these sources.
+Linux and macOS currently require that explicit archive or prepared tree;
+the native CMake source is available, with no claim of an exercised helper
+build on those platforms.
+
+The helper record accepts `helperExecutable`, `espeakDataDirectory` and
+`libraryDirectory` overrides within the selected tree. Defaults are
+`bin/arcane-kokoro.exe` on Windows (`bin/arcane-kokoro` elsewhere), `share`, and
+`bin`. The data field identifies the parent containing `espeak-ng-data`.
+Overrides are relative to the selected tree or absolute locations inside
+`helperRoot`; all three paths relocate with that complete tree. Installation
+prepares the helper and its matching data, independently of ONNX and without
+downloading model weights, tokenizer files or voices.
+
+Development and generated native composition register this engine as the TTS
+role of `createSpeechService`, sharing the existing model-assets service and
+the selected local-ai ONNX owner. Whisper, when selected, retains the separate
+STT role and device choice. Construction and no-assets startup leave Kokoro
+unloaded without helper preparation. An explicit activation with prepared
+resources acquires the helper in development and waits only for that existing
+ONNX owner. Native packaging has already bundled the helper. These waits stay
+inside speech activation; page rendering and independent services continue.
+Omitting the explicit `onnx` requirement reports unavailability on activation.
+After an explicit `localai.services.recover({runtimes: ['onnx']})` completes,
+the next explicit `speech.load({role: 'tts', ...selection})` reacquires the
+current ONNX owner through existing preparation, after prior activation cleanup.
+
+For saved browser assets, prepare the complete projection through the existing
+[`model-assets` owner](model-assets.md), then call
+`Arcane.speech.load({role: 'tts', modelId: 'kokoro', assetProjectionId,
+resourcePaths, executionTarget}, {signal})`. Core retains the incoming
+projection before replacing its activation and releases it only after native
+exit. Preparing/loading a model remains separate from installing the helper.
+Raw constructor `paths` are caller-prepared native paths; portable assembly
+does not turn external model paths or a prior process's projection ID into
+packaged resources. Prepare the intended model resources at their actual host.
+
 ## Development
 
 ```sh
@@ -125,6 +193,8 @@ configuration. Subsequent `arcane dev` runs reuse the saved requirements.
 application selects its `models` in the runtime record before requesting a
 load or generation. The development owner composes separate image and
 model-assets services alongside the existing chat/ONNX service.
+`--local-ai onnx,kokoro-native` records the native TTS requirements above;
+its model activation remains explicit when no assets are configured.
 Development checks selected endpoints and existing executable paths, then
 installs missing runtimes under the application's `.arcane/local-ai/runtimes`.
 Runtime preparation runs alongside HTTP serving. Browser rendering continues
@@ -174,8 +244,8 @@ processes. An already running external service remains running.
 handle with `ready`, `current()`, `handler()` and `close()`. Its `ready` promise
 means Core composition has started, not that installation or a selected model
 is ready. Runtime preparation continues at each owning service. `current()`
-includes separate `core`, `localAI` and optional `image` state; image status
-remains callable during preparation. Composition failures reject `ready`;
+includes separate `core`, `localAI` and optional `image` and `speech` state;
+image status remains callable during preparation. Composition failures reject `ready`;
 later service preparation failures remain on Core lifecycle and diagnostic
 events. Page rendering waits for neither.
 
@@ -227,7 +297,8 @@ owner; it neither prepares another runtime nor loads a model. An unselected
 engine reports `LOCAL_AI_RUNTIME_NOT_SELECTED`; an unavailable or recovering
 owner reports `LOCAL_AI_RUNTIME_UNAVAILABLE`, and an aborted service lifetime
 retains its abort reason. Development and generated native compositions register
-one shared model-assets service when ONNX or image generation is selected.
+one shared model-assets service when ONNX, llama.cpp, image generation or
+native Kokoro is selected.
 
 Reacquire `getONNXRuntime()` on each explicit model load because runtime recovery
 replaces that owner. Retain the acquired handle for that session's cleanup and
@@ -757,6 +828,11 @@ retains that metadata with the complete native libraries. Image records include
 `libraryPath`,
 `bindingModulePath`, requested `backend`, installed `variants` and selected
 `models` metadata. Variant records carry backend, runtime root and library path.
+Kokoro records include `helperExecutable`, `espeakDataDirectory` and
+`libraryDirectory`; bundling preserves the complete helper tree under
+`runtime/local-ai/kokoro-native` and makes all three paths artifact-relative.
+The generated entry resolves them on the destination host and obtains the
+existing ONNX owner when the selected TTS activation needs it.
 Bundle returns `{runtimes,files}`,
 with artifact-relative runtime paths and a complete emitted file inventory.
 Bundling requires a fresh native staging destination, preserving existing

package/docs/reference/native-magpie.md

@@ -0,0 +1,98 @@
+# Native Magpie speech
+
+`arcane-os/local-ai/magpie` exports `createMagpieRuntime` as a named and default export. It retains the selected Magpie model and NanoCodec decoder in one owned native process. It produces complete encoded audio or ordered PCM callbacks; the caller owns playback. Existing Kokoro, browser speech, and complete-audio APIs remain separate capabilities.
+
+## Prepare and select the runtime
+
+Supply a prepared native executable and the external NeMo shared-library directory:
+
+```js
+import {createMagpieRuntime} from 'arcane-os/local-ai/magpie';
+
+const speech = createMagpieRuntime({
+    runtime: {helperExecutable, libraryDirectory},
+    paths: {
+        model: magpieModel,
+        codec: nanoCodecModel,
+        tokenizerDirectory
+    },
+    executionTarget: {backend: 'cuda', cudaVisibleDevices: selectedCudaUuid},
+    voice: 'Aria',
+    languageCode: 'en-US'
+});
+await speech.load();
+```
+
+The paths identify an already selected Magpie GGUF, matching tokenizer assets, and matching NanoCodec decoder. Nothing is downloaded or copied by this factory. `executionTarget.backend` must explicitly select `cuda` or `cpu`. For CUDA, the native device owner supplies its selected visible device or UUID through `cudaVisibleDevices`; the child receives that process-local environment before loading CUDA. The adapter does not invent a GPU ordinal, select another device, or fall back to another provider.
+
+Instead of `runtime`, supply `prepare({signal})`, returning the prepared descriptor directly: `{helperExecutable, libraryDirectory, ...}`. Preparation runs when loading needs the executable, alongside model metadata preparation. It must return the descriptor, not a `{runtime}` wrapper. Without `libraryDirectory`, the executable's directory is used.
+
+Applications using model-assets ownership may replace `paths` with `modelAssets`, `assetProjectionId`, and `resourcePaths: {model, codec, tokenizerConfig}`. The resource paths identify members of the retained projection; the tokenizer directory is derived from the selected configuration member. The projection stays retained until its native helper closes.
+
+Other factory options are `modelId` (default `magpie`), a lifetime `signal`, and `onEvent` for the existing process/event diagnostics. Factory defaults are voice `Aria` and language `en-US`; both are exposed by `current()`.
+
+## State and lifecycle
+
+- `current()` returns provider/model identity, `state`, `loaded`, `busy`, active `requestId`, `queuedRequests`, `defaultVoice`, `languageCode`, model-owned `voices`, configured execution information, `sampleRate`, progress, and a serialized error. Its speech catalog is `{streaming: true, responseFormats: ['wav', 'pcm'], defaultResponseFormat: 'wav'}`. Configured execution is not evidence of actual GPU inference.
+- `subscribe(listener, {replay: true, signal})` observes lifecycle state and replays the current state by default; it returns an unsubscribe function.
+- `load({paths, assetProjectionId, resourcePaths, executionTarget, modelId, signal})` loads or replaces the selected resources. Reusing the same selection reuses its loaded engine. The optional signal cancels that caller's load wait; the factory lifetime signal owns engine cancellation. Load the engine before requesting speech.
+- `unload()` cancels owned work, joins native and callback cleanup, releases retained assets, and leaves the factory reusable.
+- `close()` joins unloading and disposes the factory. Repeated close calls share completion.
+
+Requests accepted by one engine are processed in order. Unloading or replacing that engine cancels its owned work; it does not cancel another engine or audio owner.
+
+## Exact requests, voices, and languages
+
+Both synthesis methods accept the same request:
+
+```js
+const request = {
+    input: 'The moon is closed for dragon maintenance.',
+    voice: 'Aria',
+    languageCode: 'en-US'
+};
+```
+
+`input` is passed unchanged: no trimming, sentence splitting, prompt injection, tempo stage, or output cap. A NUL or an unpaired surrogate cannot be represented by the native UTF-8 C-string interface and produces an explicit incompatibility error.
+
+Optional `model` must match the configured `modelId`. `voice` defaults to the factory selection and is resolved case-insensitively against the matching tokenizer's `model_config.yaml` speaker-map reference and its model-owned JSON IDs. Embedded GGUF voice labels are not used as the selection map.
+
+`languageCode` (or `language_code`) is separate per-request control information; it never changes the authored input. Omission uses the configured language. The application/model owns language selection. Installed tokenizer support determines whether a language can run; a language listed in configuration is not proof of runtime support. Native errors are returned rather than switching languages or engines. The public native ABI supplies the natural speaking rate only; an optional `speed` must be `1`.
+
+## Complete audio and streaming audio
+
+`synthesize(request, {signal, requestId, onProgress})` resolves with complete `audioBase64`, `contentType`, `format`, `sampleFormat: 's16le'`, sample rate, channel count, model, voice, language code, speed, and request ID. Set `request.responseFormat` to `wav` (default) or `pcm`. WAV uses the external RIFF framing; when a complete result cannot fit that format, select PCM or streaming instead of truncating it.
+
+`synthesizeStream(request, {signal, requestId, onProgress, onAudio})` requires `onAudio` and awaits each callback in original order:
+
+```js
+const controller = new AbortController();
+const completion = speech.synthesizeStream(request, {
+    signal: controller.signal,
+    requestId: 'dragon-announcement',
+    async onAudio({pcm, format, sampleRate, channels, requestId}) {
+        await audioOutput.write({pcm, format, sampleRate, channels, requestId});
+    }
+});
+const result = await completion;
+```
+
+`pcm` is a Node `Buffer` of signed 16-bit little-endian interleaved PCM; the current native engine returns mono audio. The callback includes `format: 's16le'`, `sampleRate`, `channels`, and `requestId`. Awaited callback delivery applies backpressure to the native helper. The streaming terminal result contains metadata and `complete: true`, without accumulating or returning the audio again. Browser/Core transport and playback have their own delivery and cleanup owners.
+
+`onProgress` receives synthesis progress. Callback failures cancel the matching utterance and remain observable. A caller-supplied `requestId` identifies its active or queued request; otherwise the runtime creates one.
+
+## Cancellation and callback ownership
+
+`await speech.stop({requestId})` stops only that active or queued utterance and joins native completion and callback cleanup. It returns `{requestId, stopped: true}`, or `stopped: false` when the ID is no longer owned. Cancellation of an active native call is observed at a PCM callback boundary: this ABI has no asynchronous pre-first-PCM interrupt. Model creation can be cancelled by retiring its owned process.
+
+An output callback must return before joining its own stop, unload, close, or selection replacement. Those self-joining calls reject with `MAGPIE_CALLBACK_WAIT`; their return types do not change inside callbacks. To cancel from `onAudio` or `onProgress`, synchronously call the caller-owned `controller.abort()` and return. The external owner then awaits the synthesis completion and cleanup. Likewise, do not await a new queued synthesis from a callback that the current synthesis is awaiting.
+
+The synthesis promise rejects on cancellation or failure. Native errors, callback failures, and cleanup failures remain observable; combined failures are preserved in aggregates. Complete audio is never reported for an interrupted request.
+
+## Build the first-party helper
+
+`arcane-os/local-ai/magpie/build` exports named/default `buildMagpieHelper({runtime, outputRoot, signal, onEvent})`. The selected upstream installation supplies `runtime.cmakeDirectory`, containing `NeMoSpeechConfig.cmake`, its public TTS headers, and its platform-matching libraries. Build prerequisites are CMake 3.26 or newer, a C++17 compiler, platform threads support, and that prepared NeMo TTS installation.
+
+The builder configures, builds, and installs the SDK's `arcane-magpie` executable under `outputRoot`. It returns `{platform, architecture, root, helperExecutable, diagnostics: {configure, compile, install}}`. Combine its executable with the selected upstream `libraryDirectory` for the runtime descriptor. The SDK does not vendor NeMo libraries, models, tokenizer assets, or voices.
+
+The source targets Windows, Linux, and macOS; Android requires its host adaptation and compatible upstream runtime. On October 17, 2026, the selected Windows x64 helper configured, compiled, and installed successfully against installed NeMo-Speech.cpp 0.2.0 using CMake 4.4.3, Visual Studio 2022, MSVC 19.44.35217, and Windows SDK 10.0.26100. Each operation exited 0, with complete diagnostics retained in the SDK's ignored selected-output directory. The helper was not launched: model inference, microphone capture, and audio playback remain unexecuted for this adapter. Linux and macOS compilation and execution remain unverified. Build success, actual selected-device inference, and audible playback are separate evidence boundaries.

package/docs/reference/native-nemotron.md

@@ -0,0 +1,204 @@
+# Native Nemotron streaming transcription
+
+`arcane-os/local-ai/nemotron` provides `createNemotronRuntime`, a Node/Core
+adapter for NVIDIA's public NeMo Speech ASR C ABI. One owned helper retains the
+selected recognizer and optional diarization model. One active audio stream
+belongs to that engine at a time. Existing Whisper transcription and standalone
+diarization remain separate supported capabilities.
+
+This adapter has no microphone, playback, conversational endpoint detector,
+keyword classifier, cloud fallback or automatic engine replacement. The host
+owns capture and the model owns conversational interpretation. A final ASR
+segment does not establish that the person has finished thinking, yielded the
+conversation, approved an action or issued an instruction.
+
+## Preparation and selection
+
+Select an upstream NeMo Speech runtime with its public ASR headers, library,
+runtime dependencies and CMake package configuration. This implementation was
+source-reviewed against the installed NVIDIA NeMo-Speech.cpp 0.2.0 public ABI,
+`nemotron-3.5-asr-streaming-0.6b` and `Nemotron-3-Diarization`. Acquire runtime and
+model assets through their upstream distribution; the SDK adapter does not
+download or redistribute them.
+
+`arcane-os/local-ai/nemotron/build` exports `buildNemotronHelper`:
+
+```js
+import {buildNemotronHelper} from 'arcane-os/local-ai/nemotron/build';
+import {createNemotronRuntime} from 'arcane-os/local-ai/nemotron';
+
+const built = await buildNemotronHelper(
+    {
+        runtime: {cmakeDirectory: selectedNeMoCmakeDirectory},
+        outputRoot: selectedHelperOutputDirectory,
+        signal,
+        onEvent
+    }
+);
+const engine = createNemotronRuntime(
+    {
+        runtime: {
+            helperExecutable: built.helperExecutable,
+            binaryDirectory: selectedNeMoBinaryDirectory,
+            libraryDirectory: selectedNeMoLibraryDirectory
+        },
+        modelPath: selectedAsrModelPath,
+        diarizationModelPath: selectedDiarizationModelPath,
+        gpu: selectedNativeGpuOrdinal,
+        onEvent
+    }
+);
+await engine.load();
+```
+
+The builder requires CMake 3.26 or later and a platform C++17 toolchain. It
+configures, builds and installs only the first-party helper, returning
+`helperExecutable`, its `executable` alias, `root`, `platform`, `architecture`
+and complete configure/build/install diagnostics. The caller selects the output
+directory and supplies the appropriate installed upstream runtime. Windows
+loads its runtime through the child's `PATH`; Linux uses `LD_LIBRARY_PATH` and
+macOS uses `DYLD_LIBRARY_PATH`, alongside the helper's loader-relative paths.
+`runtime.env` supplies additional child-only environment settings.
+
+`gpu` is required: supply the native runtime's selected GPU ordinal or explicitly
+select `-1` for CPU. Device selection belongs to the host. When the host changes
+`CUDA_VISIBLE_DEVICES`, the ordinal must describe that child's visible devices.
+The adapter reports `requestedGpu`; `observedBackend` remains `null` because a
+requested device alone does not prove GPU inference.
+
+Instead of `runtime`, supply an asynchronous
+`prepare({signal, onEvent})` function returning that prepared descriptor.
+Preparation runs during `load`, never at construction. `modelPath`,
+`diarizationModelPath` and `gpu` may also be supplied by the returned descriptor.
+Omit `diarizationModelPath` when speaker labels are not requested.
+
+## Engine lifecycle
+
+- `current()` returns selected provider/model, lifecycle `state`, `loaded`,
+  `busy`, native version, requested device, active speaker scope, errors and any
+  explicit reset requirement.
+- `subscribe(listener, {replay: true, signal} = {})` immediately replays current
+  state and observes subsequent lifecycle events; it returns an unsubscribe
+  function.
+- `load({modelId, modelPath, diarizationModelPath, gpu, signal} = {})` loads the
+  selected models and resolves only when native readiness is reported.
+  `modelId` defaults to `nemotron-3.5-asr-streaming-0.6b`. Concurrent callers share
+  that load; one caller's signal cancels its wait, not the shared load. Unload
+  before replacing an active selection.
+- `unload()` cancels and joins the active stream and model preparation, closes
+  the owned helper, and retains selection for a later explicit load.
+- `close()` joins unload and disposes lifecycle subscriptions.
+
+The host can compose this engine into the existing
+[`createSpeechService`](./native-speech.md) STT engine seam. Readiness follows
+the selected engine, not an application startup barrier.
+
+## Ordered streaming
+
+```js
+const stream = await engine.openStream(
+    {
+        model: 'nemotron-3.5-asr-streaming-0.6b',
+        sampleRate: actualCaptureSampleRate,
+        signal,
+        onUpdate: async function showRecognition(result) {
+            await displayCompleteSnapshot(result);
+        }
+    }
+);
+await stream.push(monoFloat32Samples);
+await stream.forceEndpoint();
+// The same stream accepts the next utterance, preserving its speaker scope.
+await stream.push(nextMonoFloat32Samples);
+await stream.finish();
+await stream.completion;
+```
+
+`openStream({sampleRate = 16000, languageCode, model, onUpdate, signal} = {})`
+requires the selected model to be ready, or waits for its already-started load.
+It never silently reloads after a reset. An explicit `model` must match the
+loaded selection. `sampleRate` is the actual input rate: an integer from 8000
+through 96000, or `0` for the model rate. It is passed unchanged to the native
+API. The transport's ordered 100 ms scheduling does not reinterpret a 48 kHz
+recording as 16 kHz or discard audio.
+
+The returned handle contains `push`, `forceEndpoint`, `finish`, `cancel`,
+`completion`, `current`, `sampleRate` and `speakerScope`:
+
+- `push(audio)` accepts mono `Float32Array` or
+  `{encoding: 'f32le', data: BASE64}` and resolves to all ordered snapshots from
+  that input. The encoded form carries exact little-endian float32 samples.
+  Keep a supplied array unchanged until its push settles. Other encoded
+  recordings produce `NEMOTRON_AUDIO_FORMAT_UNSUPPORTED`; caller-owned decoding
+  is required.
+- `forceEndpoint()` drains the current ASR utterance while retaining the native
+  stream, recognizer and diarization scope. Capture closure and conversational
+  turn completion remain the host's decisions.
+- `finish()` queues behind all accepted input, terminally finishes and drains
+  the native stream, delivers remaining snapshots, and resolves with that final
+  drain's snapshot array. The loaded engine remains available for another
+  stream.
+- `current()` returns the latest delivered snapshot, or `null` before one is
+  available.
+- `completion` settles after terminal finish or joined cancellation. Successful
+  finish resolves to the final drain's snapshots; earlier snapshots have already
+  been delivered through `onUpdate` and each operation's result.
+
+Each snapshot includes `sequence`, `final`, `audioProcessedSeconds`,
+`channelTag`, `speakerScope`, and every native `alternatives` record with its
+exact `text`, `confidence`, `languageCodes` and `words`. Every word preserves
+`word`, `startTimeMs`, `endTimeMs`, `confidence` and numeric `speaker`. Top-level
+`text` and `words` expose the first alternative without changing its content.
+
+Partial snapshots are provisional replacements, not appended transcript text.
+Native endpoint finals describe individual utterances in a continuing stream;
+they are forwarded unchanged. Keep their boundaries distinct. Speaker numbers
+distinguish voices within the reported scope, not named people or biometric
+identity. A new stream has a new scope. Timestamp values retain the native
+runtime's units and origin without an invented offset.
+
+Callbacks run serially in native result order and may be asynchronous. A
+callback failure stops the stream, remains observable, and retains complete
+native result records in diagnostics. Inside an active `onUpdate` callback,
+calling `push`, `forceEndpoint`, `finish`, `cancel`, `unload` or `close` raises
+`NEMOTRON_CALLBACK_WAIT`: those joined operations would wait for the callback
+itself. Abort the caller-owned signal synchronously if cancellation is needed
+there, return from the callback, then join through the external owner.
+
+## Cancellation and complete recordings
+
+`cancel(reason)` and an aborted stream signal first request ordinary native
+stream closure. If a noninterruptible public-ABI call is in flight, cancellation
+terminates only this engine's owned helper and joins it. It also joins accepted
+JavaScript operations and output callbacks before releasing stream ownership.
+Explicit cancellation resolves `completion` and `cancel` with
+`{cancelled: true, resetRequired, speakerScope, diagnostics?}`. Actual native,
+callback or cleanup failures reject and retain their diagnostic causes.
+
+After helper termination, `current()` reports `resetRequired: true`, a reset
+record and `state: 'unloaded'`. The next caller must explicitly `load()`;
+recognizer replacement and speaker-scope reset are never silent. Ordinary
+stream closure keeps the loaded helper. No cancellation claims that unfinished
+recognition produced a complete final.
+
+`transcribe(request, {signal, onProgress, onUpdate} = {})` uses the same stream
+implementation for complete recordings. Supply `{audio, sampleRate, model?,
+languageCode?}` or a direct supported audio value at the default sample rate.
+It returns `{text, words, results, speakerScope}`, retaining all final records
+in `results`, and emits accepted/recognizing progress. Its final text is the
+ordered concatenation of native final text without inserted separators. It
+does not decode WAV, MP3 or other encoded recording formats.
+
+## Evidence boundary
+
+The adapter, transport and platform paths have been source-reviewed. On October
+17, 2026, the selected Windows x64 helper configured, compiled and installed
+successfully against installed NeMo-Speech.cpp 0.2.0 using CMake 4.4.3, Visual
+Studio 2022, MSVC 19.44.35217 and Windows SDK 10.0.26100. Each operation exited 0;
+complete diagnostics remain in the SDK's ignored selected-output directory. The
+helper was not launched, and there is no measured latency, GPU-inference,
+microphone, diarization, audio playback or multi-utterance acceptance result for
+this adapter. Linux and macOS compilation and execution remain unverified.
+Compilation, header review and upstream documentation remain distinct from a
+built native application's observed behavior. Android requires the necessary
+host integration and a matching native runtime.