arcane-os 0.95.0 → 0.96.0

package/docs/reference/runtime-modules.md

@@ -115,6 +115,8 @@ own asynchronous work, cancellation, and backpressure.
 | [`MemoryRecords.js`](#memoryrecordsjs) | esm | Normalizes memory content and detects meaningful stored memory. | Cross-host | Fully normalized string/boolean results. |
 | [`MessageAdvisory.js`](#messageadvisoryjs) | esm | Normalizes message content advisories and contains per-message inspection failures. | Cross-host | Normalized advisory records; inspector failures converted to unavailable results. |
 | [`ModelDefinition.js`](#modeldefinitionjs) | esm | Parses the deterministic packaged Modelfile subset and extracts the SYSTEM prompt. | Cross-host | Complete mutable definition with coded malformed-input errors. |
+| [`NativeSpeechCapture.js`](#nativespeechcapturejs) | esm | Connects microphone PCM to one retained Core recognition stream. | Browser / native WebView with streaming Core speech | Complete snapshots, retained endpoint scope and joined capture/native cleanup. |
+| [`NativeSpeechPlayback.js`](#nativespeechplaybackjs) | esm | Prepares and plays ordered native PCM using shared Web Audio. | Browser / native WebView with streaming speech | Inert preparation, exact audio order and separate playback/release completion. |
 | [`Ollama.js`](#ollamajs) | esm | Provides the first-class Arcane Ollama client without direct access to localhost:11434. | Native bridge | Principal methods preserve provider-native envelopes; readiness/text/unload helpers normalize. |
 | [`OllamaModelIdentifier.js`](#ollamamodelidentifierjs) | esm | Validates and canonicalizes the syntax of Ollama model identifiers without granting model admission. | Cross-host | Fully normalized string/boolean result. |
 | [`OllamaSettings.js`](#ollamasettingsjs) | esm | Defines complete runtime/service preference schemas and deterministic Arcane brain alias names. | Cross-host | Fully normalized settings/name contract. |
@@ -155,6 +157,12 @@ own asynchronous work, cancellation, and backpressure.
 
 ### Overview
 
+Explicit speech-only construction uses
+`new AI(null, 'LOCAL_SPEACH', 'LOCAL_SPEACH', null, ttsModel, sttModel)`.
+Both LLM arguments must be `null`; no default LLM is selected or activated.
+Omitted or empty arguments retain historical defaults, and an existing
+`window.ai` singleton is reused. Later `configureProviders` can select an LLM.
+
 Provider-selectable chat, speech-to-text, text-to-speech, tool calling,
 structured output, streaming, bounded synthesis, and ordered audio-clock
 playback.
@@ -174,6 +182,7 @@ read-only `ttsSegmentation`, `configureTTSSegmentation()`,
 `readPreparedTTS({parts,textFormat,storage,identity,signal,onState})`,
 `prepareAudioOutput()`, `playPreparedTTS(prepared,{signal,onState,audioOutput})`,
 `finishTTS()`, `prepareTTSPlayback()`, `fetchTTS()`, `fetchSTT()`, `stopAudio()`, `resumeAudio()`,
+`supportsTranscriptionCapture()`, `createTranscriptionCapture(options={})`,
 `playAudio()`; consumes `user-entity-loaded` and `arcane-ollama-ready`,
 installs `window.ai`, and emits `ai-ready`, `ai-tts-failure`, and
 `AI_AUDIO_OUTPUT_STATE_EVENT` (`'ai-audio-output-state'`).
@@ -415,7 +424,7 @@ physical accelerator; WebNN may execute unsupported operations through WASM.
 Calling `status()` without options keeps
 the existing sticky lifecycle snapshot and does not inspect provider execution.
 Provider inspection failures are surfaced to the caller.
-`fetchTTS({model,voice,input,responseFormat,speed},signal,preparation={})` accepts the public
+`fetchTTS({model,voice,input,responseFormat,languageCode,speed},signal,preparation={})` accepts the public
 provider-neutral synthesis shape, requires any explicit model to match the
 selected route, and fills an omitted voice only from the selected model
 catalog's `defaultVoice`. An omitted response format preserves the instance's
@@ -438,13 +447,15 @@ default cleanup. The third `preparation` argument is reserved for SDK-internal
 delegation, where `{speechInputPrepared:true}` prevents a second cleanup pass;
 applications omit it. `streamTTS(text='',end=false,options={})` and
 `finishTTS()` use the selected playback boundary. The third-argument options below
-are available in SDK `0.5.12`. In these streaming options, the `textFormat`
+are available from SDK `0.5.12`, with `languageCode` added in `0.95.0`.
+In these streaming options, the `textFormat`
 compatibility extra added in SDK `0.5.16` remains ignored:
 
 | Field | Default | Meaning |
 | --- | --- | --- |
 | `voice` | Current selected model's default voice | A supplied voice is captured for every segment extracted by this call and forwarded unchanged to `fetchTTS()`. It does not change the instance or provider default. |
 | `speed` | Current `ai.voiceSpeed` | A supplied positive speed is captured for those segments and forwarded to `fetchTTS()`. It does not change `ai.voiceSpeed`. |
+| `languageCode` | Selected engine's language default | Per-utterance language control, separate from the unchanged text. Support belongs to the selected engine/tokenizer; Magpie uses natural speed `1`. |
 | `pauseAfterMs` | `0` | Finite, nonnegative milliseconds placed after the final extracted segment on the existing audio clock. Invalid values throw `RangeError`; no pause is inserted between this call's other segments. |
 | `waitForPlayback` | `false` | Omission retains the preparation promise. With `true`, the promise resolves after every extracted segment reaches a terminal playback state: `true` when all naturally end, or `false` after terminal cancellation or failure. |
 | `textFormat` | Ignored streaming compatibility extra | Streaming narration retains automatic cleanup. The public plain selection belongs to complete synthesis payloads or `prepareTTS` options. |
@@ -461,13 +472,24 @@ formatting state. Streaming `textFormat` is not an opt-out.
 
 Voice, speed, pause, and playback overrides belong to the segments
 extracted in that invocation, including any text buffered by an earlier call.
-Those overrides are not retained with an unfinished `end:false` remainder; a
-later call supplies its own options, and `finishTTS()` uses their defaults
-while flushing any pending formatting mark. Use `end:true`
-for a complete passage. A call extracting no segments resolves
-`true` without waiting for earlier jobs; `finishTTS()` remains a preparation
+Voice, speed and languageCode are retained with an unfinished `end:false`
+utterance through continuation and `finishTTS()`. Explicitly changed language
+first queues the old remainder under its prior selection, then accepts new text.
+End, mute and stop clear the retained selection. Pause and waitForPlayback
+remain per-call controls.
+
+Use `end:true` for a complete passage. A call extracting no segments resolves
+`true` without waiting for earlier jobs, except that a language-change call also
+joins its preceding remainder preparation. `finishTTS()` remains a preparation
 flush, not a queue-wide playback barrier. A muted call resolves `false`.
 
+A native engine catalog with `speech.streaming:true` selects an inert PCM
+playback descriptor through `prepareTTSPlayback`. Explicit play uses the shared
+provider lane and Web Audio output; `released` joins native cleanup independently
+of `finished`. Magpie also retains complete-audio `fetchTTS`; browser-native
+voices without audio export retain their existing unsupported result. See
+[shared native capture/playback](native-speech.md#shared-ai-capture-and-playback).
+
 `prepareTTSPlayback(payload,signal,preparation={})` is the silent playback-oriented
 request. Audio-file providers retain the `fetchTTS()` Blob contract; a selected
 model with `speech.playback:'native'` returns an inert `native-speech` descriptor.
@@ -1130,6 +1152,17 @@ The singleton exposes read-only `protocol`, `configured`, and `speechMuted`;
 `setSpeechMuted(muted,{signal}={})`. Provider payloads must be data-only; callbacks,
 accessors, symbols, and cycles are rejected at the provider boundary.
 
+`supportsTranscriptionCapture(providerId=null)` checks the selected provider's
+capture implementation and optional capability predicate. Construction of
+`createTranscriptionCapture(options)` performs no capture; it returns null or
+an owned `start/stop/cancel/destroy/done` wrapper with `forceEndpoint` when the
+provider supplies it. Start must originate in the user's capture action and
+requires an idle ready STT role; it is never queued. The role remains owned
+until `done` joins cleanup, including on cancellation or provider retirement.
+Native streaming TTS likewise uses the existing provider request lane rather
+than an application-owned synthesis queue. See
+[shared native capture/playback](native-speech.md#shared-ai-capture-and-playback).
+
 `setSpeechMuted(false,{signal})` shares pending activation while retaining an
 independent interest for each caller. Aborting one signal rejects only that
 caller's wait. When no pending interests remain, abort reaches the owned load.
@@ -2046,11 +2079,22 @@ component adds ordered STT, persistence, retry, and presentation.
 ### Public surface
 
 Default export `ContinuousVoiceCapture` accepts
-`{preRollMs=1500,quietMs=2000,chunkMs=30000,activityThreshold=0.02,onSegment,onError,onState}`.
-`start({mediaConstraints={audio:true},signal}={})` acquires microphone input and
+`{preRollMs=1500,quietMs=2000,chunkMs=30000,activityThreshold=0.02,mode='segments',pcmChunkMs=100,onPCM,onActivity,onSegment,onError,onState}`.
+`start({mediaConstraints={audio:true},sampleRate,signal}={})` acquires microphone input and
 resolves `true` once capture starts, or `false` after cancellation or a
 reported start failure. Starting capture is an explicit caller action.
 
+Select `mode:'pcm'` to deliver every captured sample through ordered awaited
+`onPCM({samples:Float32Array,sampleRate,channels:1,sequence})` callbacks.
+The record reports the actual AudioContext rate. `pcmChunkMs` is transport
+scheduling, never a recording limit. `onActivity({active,audioTime})` reports
+amplitude changes without gating PCM or interpreting speech. `flush()` sends
+pending samples and awaits preceding delivery while leaving capture open.
+Stop drains accepted PCM and joins actual AudioContext closure. Cancel/destroy
+suppress queued delivery and join in-flight delivery and close; genuine delivery
+and cleanup failures reject rather than being reported as success.
+
+In the default `mode:'segments'`:
 `onSegment({audio,sequence,reason,durationMs})` receives a complete
 `audio/wav` Blob containing mono Float32 audio. Sequence starts at one for
 each capture session; reason is `pause`, `periodic`, or `stop`. The detector
@@ -2073,7 +2117,8 @@ cancellation boundary. The optional signal cancels this capture session.
 flushes the active clip before reporting interruption while the worklet remains
 available. A failed audio context or processor reports interruption directly;
 audio still inside an unavailable processor cannot be recovered. Callback
-promises are observed without delaying capture or stop acknowledgement.
+promises for segment/state/activity observers are observed without delaying
+capture; ordered PCM delivery and actual context closure are joined at stop.
 Capture state is independent
 of model readiness, STT processing, and application save state.
 
@@ -3411,6 +3456,100 @@ import * as module from '/arcane/modules/ModelDefinition.js';
 console.log(Object.keys(module));
 ```
 
+## NativeSpeechCapture.js
+
+### Overview
+
+Default `createNativeSpeechCapture({speech,model,...options})` connects one
+microphone lifetime to one retained Core ASR stream. Construction opens no
+microphone or model. Applications normally use `ai.createTranscriptionCapture`,
+which also owns the selected provider slot.
+
+### Public surface and lifetime
+
+Options are `sampleRate=16000`, `pcmChunkMs=100`, `activityThreshold=0.02`,
+`streamOptions`, `mediaConstraints`, `onUpdate`, `onInterim`, `onSegment`,
+`onActivity`, `onState`, `onError`, `onProgress` and `onRequest`.
+The handle exposes `start({signal,mediaConstraints})` (boolean promise),
+`forceEndpoint()`, `stop()`, `requestStop()`, `cancel(reason)`,
+`destroy(reason)`, `done`, and `current()`. Capture uses the actual selected
+sample rate; `streamOptions.sampleRate` overrides the factory rate. Every PCM
+contribution is retained in order.
+
+Recognition callbacks receive `(result,{requestStop})`; `onUpdate` precedes
+the appropriate final `onSegment` or provisional `onInterim`. Partials replace,
+finals preserve complete native segments and speaker scope. Call `requestStop()`
+without awaiting it, return from the callback, then join `stop()` or `done`
+externally. Never await those or `forceEndpoint()` from their own callback.
+External endpoint flushes pending audio and recognition while keeping capture
+and the stream open. Stop closes capture and drains terminally. Cancel/destroy
+join both cleanup owners without claiming a complete transcript. `current()`
+returns the latest snapshot or null. Actual failures remain in `done` and
+`onError`. No snapshot or control sends chat or decides conversational meaning.
+
+### Availability and example
+
+Requires microphone, Web Audio and AudioWorklet in a browser/native WebView,
+plus an explicitly selected ready streaming Core speech engine.
+
+```javascript
+import createNativeSpeechCapture from 'arcane-os/modules/NativeSpeechCapture.js';
+
+function prepareDragonInterpreter(speech, model, showSnapshot) {
+    return createNativeSpeechCapture({speech, model, onUpdate: showSnapshot});
+}
+// Start from the application's capture action; its owner joins stop/done.
+```
+
+See [Core speech](native-speech.md) and [Nemotron](native-nemotron.md) for complete
+native formats, results, callback constraints, reset and platform prerequisites.
+
+## NativeSpeechPlayback.js
+
+### Overview
+
+Default `prepareNativeSpeechPlayback({speech,request,getAudioContext,signal=null})`
+prepares an inert native speech descriptor. It creates no model, microphone or
+separate utterance queue. Applications normally use `ai.prepareTTSPlayback`.
+
+### Public surface and lifetime
+
+The result is `{kind:'native-speech',input,voice,language,speed,play}`.
+`play({signal,onState})` returns `finished`, `released`, live `state` and
+`error`, plus boolean `pause()`, `resume()` and `stop()` controls.
+Preparation performs no synthesis/playback. Play consumes ordered signed
+16-bit little-endian PCM at its supplied rate and channel count through the
+caller-owned AudioContext, with awaited audio-clock backpressure.
+Pause retains unplayed audio; stop cancels only this utterance.
+
+`finished` resolves true after natural playback or false after stop, and
+rejects actual failure. `released` additionally joins native synthesis and
+cleanup. Both preparation and play signals can cancel. The shared output
+context remains open for its owner. `onState({state,error})` observes queued,
+waiting-for-audio, playing, paused, complete, stopped or error.
+Missing callable dependencies throw TypeError; unusable PCM or a closed context
+reports `ARCANE_AI_SPEECH_PLAYBACK_FAILED`. Native, playback and cleanup
+failures remain observable, including combined causes.
+
+### Availability and example
+
+Requires browser Web Audio plus a supplied streaming speech API.
+
+```javascript
+import prepareNativeSpeechPlayback from 'arcane-os/modules/NativeSpeechPlayback.js';
+
+function prepareDragonAnnouncement(speech, getAudioContext, signal) {
+    return prepareNativeSpeechPlayback({
+        speech, getAudioContext, signal,
+        request: {input: 'The dragon has landed.', languageCode: 'en-US'}
+    });
+}
+// Play from the owning action, then join the control's released promise.
+```
+
+See [Magpie](native-magpie.md) and
+[shared native playback](native-speech.md#shared-ai-capture-and-playback).
+
 ## Ollama.js
 
 ### Overview
@@ -4826,7 +4965,7 @@ the audio rendering thread. It performs no semantic speech detection or STT.
 No ESM exports. The capture owner loads this static file with
 `audioContext.audioWorklet.addModule()` and creates the
 `arcane-continuous-voice-capture` processor with
-`{preRollMs,quietMs,chunkMs,activityThreshold}` in `processorOptions`.
+`{preRollMs,quietMs,chunkMs,activityThreshold,mode,pcmChunkMs}` in `processorOptions`.
 `activityThreshold` measures root-mean-square amplitude over fixed 20 ms
 windows counted from the audio sample rate, independently of browser callback
 lengths. Brief peaks do not reset the quiet duration when the window's RMS
@@ -4843,6 +4982,13 @@ trailing audio before the quiet boundary. Analysis adds at most one 20 ms
 window of capture-to-segmentation delay; model processing is independently
 owned by the transcription queue.
 
+In `mode:'pcm'`, the processor transfers every sample through
+`{type:'pcm',audio:ArrayBuffer,sampleRate,sequence}` and reports
+`{type:'activity',active,audioTime}` on amplitude-state changes. It keeps no
+semantic classifier and does not omit quiet audio. `{type:'flush',id}` sends
+pending PCM then `{type:'flushed',id}` without stopping. The capture owner
+adds `channels:1` and joins ordered delivery before resolving its flush.
+
 The owner sends `{type:'stop'}`. The processor transfers each complete
 `{type:'segment',audio:ArrayBuffer,sampleRate,sequence,reason,durationMs}`
 and finally `{type:'stopped'}`. Each complete WAV includes its own format,

package/docs/reference/sdk-api.md

@@ -81,6 +81,10 @@ runtime layouts.
 | `arcane-os/ai/core-image` | Browser image lifecycle and complete PNG Blobs through an available Core service. |
 | `arcane-os/core/image` | Native image Core service with independent runtime preparation and retained model ownership. |
 | `arcane-os/core/speech` | Independent injected STT/TTS engine loading, request cancellation and joined Core service lifetime. |
+| `arcane-os/local-ai/nemotron` | Retained native streaming recognition with complete timed words and optional diarization. |
+| `arcane-os/local-ai/nemotron/build` | First-party ASR helper build against a prepared NeMo runtime. |
+| `arcane-os/local-ai/magpie` | Retained native Magpie/NanoCodec synthesis with complete audio or ordered PCM. |
+| `arcane-os/local-ai/magpie/build` | First-party TTS helper build against a prepared NeMo runtime. |
 | `arcane-os/local-ai/whisper` | Retained native Whisper model, complete recordings and joined helper lifetime. |
 | `arcane-os/local-ai/kokoro` | Retained native Kokoro synthesis using the existing ONNX/model-resource owners and a compiled phonemization/Opus helper. |
 | `arcane-os/local-ai/whisper/build` | First-party persistent helper build against selected installed Whisper headers and libraries. |
@@ -476,6 +480,14 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `KOKORO_REVISION` | constant | `arcane-os/local-ai/kokoro` | Core native speech | Selected upstream model revision |
 | `KOKORO_SAMPLE_RATE` | constant | `arcane-os/local-ai/kokoro` | Core native speech | Native PCM sample rate |
 | `KOKORO_VOICES` | constant | `arcane-os/local-ai/kokoro` | Core native speech | Complete 28-voice US/GB selection |
+| `createNemotronRuntime()` | function | `arcane-os/local-ai/nemotron` | Core native speech | Node with a matching first-party helper, selected NeMo ASR runtime and models; Windows/Linux/macOS source, Android host adaptation |
+| `createNemotronRuntime default export` | function | `arcane-os/local-ai/nemotron` | Core native speech | Same named function |
+| `buildNemotronHelper()` | function | `arcane-os/local-ai/nemotron/build` | Core native speech | Node with CMake 3.26+, C++17 toolchain and platform-matching public NeMo ASR headers/libraries/CMake package |
+| `buildNemotronHelper default export` | function | `arcane-os/local-ai/nemotron/build` | Core native speech | Same named function |
+| `createMagpieRuntime()` | function | `arcane-os/local-ai/magpie` | Core native speech | Node with a matching first-party helper, selected NeMo TTS runtime, Magpie/tokenizer and NanoCodec assets; Windows/Linux/macOS source, Android host adaptation |
+| `createMagpieRuntime default export` | function | `arcane-os/local-ai/magpie` | Core native speech | Same named function |
+| `buildMagpieHelper()` | function | `arcane-os/local-ai/magpie/build` | Core native speech | Node with CMake 3.26+, C++17 toolchain, platform threads and matching public NeMo TTS headers/libraries/CMake package |
+| `buildMagpieHelper default export` | function | `arcane-os/local-ai/magpie/build` | Core native speech | Same named function |
 | `createWhisperRuntime()` | function | `arcane-os/local-ai/whisper` | Core native speech | Node with a prepared matching helper, runtime, decoder and selected model |
 | `createWhisperRuntime default export` | function | `arcane-os/local-ai/whisper` | Core native speech | Same retained native engine factory |
 | `buildWhisperHelper()` | function | `arcane-os/local-ai/whisper/build` | Core native speech | Node with installed CMake/C++17 toolchain and matching Whisper source/runtime |
@@ -7232,6 +7244,18 @@ no engine. The native routes of `AI.fetchTTS(payload, signal)` and
 `AI.fetchSTT(audio, signal)` forward their signals through these calls and
 normalize cancellation to `AbortError` with `ARCANE_AI_REQUEST_ABORTED`.
 
+`facade.speech.openStream(request,options)` returns
+`{streamId,ready,completion,current,push,forceEndpoint,finish,cancel}`.
+Ordered Float32 input retains the actual declared sample rate. Endpoint preserves
+stream/speaker scope and waits preceding updates; finish drains terminally.
+Do not await endpoint/finish/completion from their own update callback. Explicit
+cancel joins its native cleanup control, unlike ordinary signal cancellation.
+`synthesizeStream(request,{signal,onAudio,onProgress,onRequest})` awaits each
+complete ordered Uint8Array PCM contribution and its consumption acknowledgement,
+returns terminal metadata, and joins native cancellation. It plays no audio.
+Both streaming operations have no fixed timeout. Engine support/readiness remains
+independent from facade availability. See [streaming native speech](core-client.md#streaming-native-speech).
+
 `facade.window.state({signal}?)` reads the calling document's native window;
 `facade.window.setState({state}, {signal}?)` selects `normal`, `maximized` or
 `fullscreen` for that same window. The matching Windows host returns
@@ -8961,6 +8985,211 @@ US/GB voice identifiers. The engine uses `af_heart` when the caller omits
 `voice`; an explicit unsupported selection reports an error. Use this complete
 array to populate a native Kokoro voice selector.
 
+## createNemotronRuntime()
+
+### Overview and syntax
+
+Creates one retained native recognizer and optional diarizer without opening a
+microphone, loading a model or starting inference at construction.
+
+```javascript
+createNemotronRuntime({
+    runtime, prepare, modelId = 'nemotron-3.5-asr-streaming-0.6b',
+    modelPath, diarizationModelPath, gpu, onEvent
+} = {})
+```
+
+Supply a prepared `runtime` or lazy `prepare({signal,onEvent})` descriptor
+with `helperExecutable` and selected native library paths. Select `gpu`
+explicitly (native ordinal, or `-1` for CPU). Model paths may come from the
+descriptor; omit the diarization path when speaker labels are not requested.
+Preparation, models and device selection remain caller-owned.
+
+### Returned members and lifetime
+
+The engine exposes `current/subscribe/load/unload/transcribe/openStream/close`.
+Current state and replaying subscriptions report actual loaded readiness,
+native version, requested device, active speaker scope, error and reset state.
+`load` initializes the selection; `unload` and `close` join owned cleanup.
+
+`openStream({sampleRate=16000,languageCode,model,onUpdate,signal})` resolves an
+owned `push/forceEndpoint/finish/cancel/completion/current` handle plus
+`sampleRate` and `speakerScope`. Feed mono `Float32Array` or
+`{encoding:'f32le',data:BASE64}` at the actual declared rate. The native sample
+rate contract accepts integer 8000–96000 or 0 for model rate. No encoded-media
+decoder is supplied. Updates preserve every alternative, text, word, timestamp,
+numeric speaker and final/provisional status.
+
+`forceEndpoint` drains an utterance while retaining stream and speaker scope;
+`finish` terminally drains accepted input. Partial snapshots replace; finals
+remain separate recognition segments, never inferred conversational completion.
+`transcribe({audio,sampleRate,model?,languageCode?},options)` uses this same
+stream and returns complete `{text,words,results,speakerScope}`.
+
+Cancellation joins native and callback cleanup. Terminating genuinely
+noninterruptible helper work exposes `resetRequired` and requires explicit
+reload; no engine restarts silently. Callbacks must return before joining their
+own stream/engine lifecycle, otherwise `NEMOTRON_CALLBACK_WAIT` is reported.
+Unsupported input reports `NEMOTRON_AUDIO_FORMAT_UNSUPPORTED`; native, callback
+and cleanup failures remain observable.
+
+### Availability and example
+
+Node on Windows, Linux and macOS with the first-party helper and matching
+upstream NeMo ASR runtime/models; Android requires host adaptation. Selected
+Windows helper compilation is recorded in the [engine guide](native-nemotron.md);
+that is separate from inference, microphone or other-platform execution.
+
+```javascript
+import {createNemotronRuntime} from 'arcane-os/local-ai/nemotron';
+
+function prepareDragonInterpreter(runtime, modelPath, gpu) {
+    return createNemotronRuntime({runtime, modelPath, gpu});
+}
+// The native owner explicitly loads, supplies PCM and joins close.
+```
+
+See [native Nemotron](native-nemotron.md) for complete options, snapshots,
+callback rules and cancellation/reset outcomes.
+
+## createNemotronRuntime default export
+
+The default export from `arcane-os/local-ai/nemotron` is the same
+`createNemotronRuntime` function, with identical inputs, results and lifetime.
+
+## buildNemotronHelper()
+
+### Overview and syntax
+
+`buildNemotronHelper({runtime,outputRoot,signal,onEvent}={})` configures, builds
+and installs only the first-party Nemotron helper. `runtime.cmakeDirectory`
+selects an installed NeMo CMake package with its matching public ASR headers and
+libraries; `outputRoot` is the caller-owned output directory.
+
+### Result, availability and example
+
+Returns `{platform,architecture,root,helperExecutable,executable,diagnostics}`;
+`executable` aliases `helperExecutable`, and diagnostics retains complete
+configure/compile/install results. Requires Node, CMake 3.26+, a C++17 compiler
+and matching platform runtime. It downloads no dependency or model and performs
+no inference. Cancellation and process failures remain observable.
+
+```javascript
+import {buildNemotronHelper} from 'arcane-os/local-ai/nemotron/build';
+
+async function buildSelectedRecognizer(runtime, outputRoot, signal, onEvent) {
+    return buildNemotronHelper({runtime, outputRoot, signal, onEvent});
+}
+```
+
+See [preparation and selection](native-nemotron.md#preparation-and-selection).
+
+## buildNemotronHelper default export
+
+The default export from `arcane-os/local-ai/nemotron/build` is the same
+`buildNemotronHelper` function.
+
+## createMagpieRuntime()
+
+### Overview and syntax
+
+Creates one retained native Magpie/NanoCodec synthesis owner. Construction
+downloads, loads and plays nothing.
+
+```javascript
+createMagpieRuntime({
+    runtime, prepare, paths, modelAssets, assetProjectionId, resourcePaths,
+    modelId = 'magpie', voice = 'Aria', languageCode = 'en-US',
+    executionTarget, signal, onEvent
+} = {})
+```
+
+Supply a prepared executable/library descriptor or `prepare({signal})`.
+Select matching Magpie, NanoCodec and tokenizer `paths`, or an existing
+model-assets projection and `resourcePaths`. Explicit `executionTarget`
+selects CPU or CUDA with the host's visible device/UUID; no provider or device
+fallback is inferred. The tokenizer's own speaker map determines voice IDs.
+
+### Returned members and lifetime
+
+The engine exposes `current/subscribe/load/unload/synthesize/synthesizeStream/stop/close`.
+State includes independent loaded readiness, active/queued requests, voice and
+language defaults, model-owned voices and streaming/format capability.
+`load` retains selected models; `unload` and `close` join owned work/assets.
+
+Both synthesis methods accept exact `{input,model?,voice?,languageCode?,speed?}`;
+language is separate control information, and native speed must be 1.
+`synthesize(request,{signal,requestId,onProgress})` returns complete base64
+WAV (default) or PCM audio, MIME/format and speech metadata. Select
+`responseFormat:'pcm'` explicitly when needed.
+`synthesizeStream(request,{signal,requestId,onProgress,onAudio})` requires an
+awaited ordered `onAudio({pcm,format,sampleRate,channels,requestId})` callback.
+PCM is a Node Buffer of signed 16-bit little-endian samples; terminal metadata
+has `complete:true` without retaining the complete audio again. Playback
+belongs to the caller.
+
+Requests retain FIFO ownership. `stop({requestId})` stops only that queued or
+active utterance and joins native/callback cleanup; cancellation rejects
+synthesis. In-flight native interruption is observed at a PCM callback boundary.
+A callback can abort its caller-owned signal and return; self-joining lifecycle
+calls reject `MAGPIE_CALLBACK_WAIT`. Complete native and cleanup errors remain
+observable. An interrupted request never returns fabricated complete audio.
+
+### Availability and example
+
+Node on Windows, Linux and macOS with a matching helper, upstream NeMo TTS
+runtime and selected model assets; Android needs host adaptation. The
+[engine guide](native-magpie.md) separates selected Windows compilation from
+unverified inference, playback and other-platform execution.
+
+```javascript
+import {createMagpieRuntime} from 'arcane-os/local-ai/magpie';
+
+function prepareDragonAnnouncer(runtime, paths, executionTarget) {
+    return createMagpieRuntime({runtime, paths, executionTarget});
+}
+// The native owner loads explicitly; synthesis returns audio, not playback.
+```
+
+See [native Magpie](native-magpie.md) for complete selection, language, voices,
+callback constraints and request lifetime.
+
+## createMagpieRuntime default export
+
+The default export from `arcane-os/local-ai/magpie` is the same
+`createMagpieRuntime` function, with identical inputs, results and lifetime.
+
+## buildMagpieHelper()
+
+### Overview and syntax
+
+`buildMagpieHelper({runtime,outputRoot,signal,onEvent}={})` configures, builds
+and installs the first-party Magpie helper against the caller's installed
+`runtime.cmakeDirectory`, public NeMo TTS headers and matching libraries.
+
+### Result, availability and example
+
+Returns `{platform,architecture,root,helperExecutable,diagnostics}`, preserving
+complete configure/compile/install results. Requires Node, CMake 3.26+, C++17,
+platform threads and matching NeMo libraries. `outputRoot` belongs to the
+caller. It downloads no dependency, model or voice and performs no inference.
+Cancellation and process failures remain observable.
+
+```javascript
+import {buildMagpieHelper} from 'arcane-os/local-ai/magpie/build';
+
+async function buildSelectedAnnouncer(runtime, outputRoot, signal, onEvent) {
+    return buildMagpieHelper({runtime, outputRoot, signal, onEvent});
+}
+```
+
+See [helper build prerequisites](native-magpie.md#build-the-first-party-helper).
+
+## buildMagpieHelper default export
+
+The default export from `arcane-os/local-ai/magpie/build` is the same
+`buildMagpieHelper` function.
+
 ## createWhisperRuntime()
 
 ### Overview
@@ -9114,6 +9343,18 @@ requests and results unchanged. Format decoding, model processing and encoding
 remain with that engine. This factory supplies no speech engine or automatic
 browser/native provider selection.
 
+Optional engine `openStream({...options,signal,onUpdate})` supplies continuous
+recognition; optional `synthesizeStream(request,{signal,onProgress,onAudio,requestId})`
+supplies awaited ordered PCM output. Each role reports `supportsStreaming`
+independently from loaded readiness. The Core streaming methods are
+`speech.open`, `push`, `endpoint`, `finish`, `cancel`, `synthesizeStream`,
+`audioConsumed` and `cancelSynthesis` (each under `speech.`). Request-scoped
+`speech.opened`, `speech.transcription` and `speech.audio` events retain stream
+ownership; TTS acknowledgements apply backpressure while control traffic continues.
+Endpoint drains an utterance without closing its stream; finish closes terminally.
+ASR finals are recognition segments, not conversational decisions. Cancellation
+joins the selected engine's native work. See the [complete streaming contract](native-speech.md#continuous-transcription-and-streaming-synthesis).
+
 ### Members, results and events
 
 The returned object has `name: 'speech'`, `current`, `subscribe`, `close`,
@@ -9170,10 +9411,12 @@ their operation with `SPEECH_ENGINE_UNAVAILABLE`; work after shutdown begins
 rejects with `CORE_CLOSING`. Engine errors remain observable, and engine cleanup
 failures reject shutdown with `AggregateError`. Asynchronous listener failures
 reach developer diagnostics. Engine platform support remains its own contract;
-this Node composition layer adds no engine dependency. Existing AI readiness
-consumers recognize `whisper.cpp` and `kokoro-onnx` IDs independently of the
-service's engine-neutral interface. See the [complete engine and lifetime
-contract](native-speech.md).
+this Node composition layer adds no engine dependency. The shared AI adapter
+follows the selected model and engine in per-role snapshots, including Nemotron
+and Magpie. Only its older aggregate-only fallback retains fixed
+`whisper.cpp`/`whisper-small` and `kokoro-onnx`/`kokoro` expectations.
+Unavailable streaming operations reject `SPEECH_OPERATION_UNAVAILABLE` without
+fallback. See the [complete engine and lifetime contract](native-speech.md).
 
 ## createSpeechService default export
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.95.0",
+  "version": "0.96.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -137,8 +137,8 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/conversation-closing-report.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/native-windows-icon.test.mjs test/risk-signal-analyzer.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/ai-ollama-readiness.test.mjs test/core-ollama-lifecycle.test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-kokoro-complete-input.test.mjs test/browser-speech-providers.test.mjs test/browser-speech-artifacts.test.mjs test/browser-speech-resource-bridge.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/codex-app-server.test.mjs test/mcp-stdio-server.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-client-installation.test.mjs test/core-ai-installation.test.mjs test/core-llama-lifecycle.test.mjs test/core-development.test.mjs test/core-host.test.mjs test/core-shared-host.test.mjs test/core-model-assets.test.mjs test/core-native-services.test.mjs test/core-packaged-web.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-committed-events.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-model-resources.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/document-acquisition.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/execution-devices.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/local-image-editing.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/model-resource-bridge.test.mjs test/native-decisions.test.mjs test/native-onnx.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
-    "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-macos-provider.test.mjs test/native-plan.test.mjs test/native-portable-provider.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/ai-ollama-readiness.test.mjs test/core-ollama-lifecycle.test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-kokoro-complete-input.test.mjs test/browser-speech-providers.test.mjs test/browser-speech-artifacts.test.mjs test/browser-speech-resource-bridge.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/codex-app-server.test.mjs test/mcp-stdio-server.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-client-installation.test.mjs test/core-ai-installation.test.mjs test/core-llama-lifecycle.test.mjs test/core-development.test.mjs test/core-host.test.mjs test/core-shared-host.test.mjs test/core-model-assets.test.mjs test/core-native-services.test.mjs test/core-packaged-web.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-committed-events.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-model-resources.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/document-acquisition.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/execution-devices.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/local-image-editing.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/model-resource-bridge.test.mjs test/nemo-models.test.mjs test/native-decisions.test.mjs test/native-onnx.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
+    "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-macos-provider.test.mjs test/native-plan.test.mjs test/native-portable-provider.test.mjs test/native-provider-loader.test.mjs test/native-publish-output.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/html-import-packaged-script.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/ai-audio-output.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",
     "check:release": "node tools/check-source.mjs --package-only && npm run test:release",

package/src/core/host.mjs

@@ -39,6 +39,7 @@ export function resolveNativeLaunchContext({appId, context = {}} = {}) {
     const resolved = {
         ...context,
         stateRoot,
+        modelsDirectory: context.modelsDirectory === undefined ? path.join(root, 'Models') : context.modelsDirectory,
         workspaceRoot: context.workspaceRoot === undefined ? path.join(root, 'Workspace') : context.workspaceRoot
     };
     if (context.sharedHost !== undefined) {