arcane-os 0.94.0 → 0.96.0

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

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.92.0",
+  "sdkVersion": "0.95.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 314,
+  "memberCount": 322,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
@@ -250,6 +250,134 @@
       "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-nemotron:createNemotronRuntime",
+      "name": "createNemotronRuntime",
+      "displayName": "createNemotronRuntime()",
+      "kind": "function",
+      "signature": "createNemotronRuntime({runtime,prepare,modelId='nemotron-3.5-asr-streaming-0.6b',modelPath,diarizationModelPath,gpu,onEvent}={})",
+      "entrypoints": [
+        "arcane-os/local-ai/nemotron"
+      ],
+      "primaryImport": "arcane-os/local-ai/nemotron",
+      "group": "Core native speech",
+      "summary": "Retains one native recognizer and optional diarizer across explicit utterance endpoints.",
+      "availability": "Node with a matching first-party helper, selected NeMo ASR runtime and models; Windows/Linux/macOS source, Android host adaptation",
+      "protocol": "Native ASR C ABI through one retained helper and replaying nemotron.state",
+      "normalization": "Returns current/subscribe/load/unload/transcribe/openStream/close. Exact ordered Float32 or f32le input uses the actual declared sample rate; complete snapshots retain alternatives, words, timestamps and speaker scope. forceEndpoint preserves the native stream; finish drains terminally. Callback joins reject NEMOTRON_CALLBACK_WAIT. Cancellation joins cleanup and exposes resetRequired when an in-flight native call requires helper termination; explicit load is required afterward. No microphone, semantic completion or fallback."
+    },
+    {
+      "id": "local-ai-nemotron:default",
+      "name": "default",
+      "displayName": "createNemotronRuntime default export",
+      "kind": "function",
+      "signature": "default as createNemotronRuntime",
+      "entrypoints": [
+        "arcane-os/local-ai/nemotron"
+      ],
+      "primaryImport": "arcane-os/local-ai/nemotron",
+      "group": "Core native speech",
+      "summary": "Default binding for the same createNemotronRuntime function.",
+      "availability": "Node with a matching first-party helper, selected NeMo ASR runtime and models; Windows/Linux/macOS source, Android host adaptation",
+      "protocol": "Native ASR C ABI through one retained helper and replaying nemotron.state",
+      "normalization": "Binding identity equals the named createNemotronRuntime export"
+    },
+    {
+      "id": "local-ai-nemotron-build:buildNemotronHelper",
+      "name": "buildNemotronHelper",
+      "displayName": "buildNemotronHelper()",
+      "kind": "function",
+      "signature": "async buildNemotronHelper({runtime,outputRoot,signal,onEvent}={})",
+      "entrypoints": [
+        "arcane-os/local-ai/nemotron/build"
+      ],
+      "primaryImport": "arcane-os/local-ai/nemotron/build",
+      "group": "Core native speech",
+      "summary": "Builds the first-party retained Nemotron ASR helper against a caller-selected NeMo installation.",
+      "availability": "Node with CMake 3.26+, C++17 toolchain and platform-matching public NeMo ASR headers/libraries/CMake package",
+      "protocol": "Owned configure/build/install process lifecycle",
+      "normalization": "runtime.cmakeDirectory and outputRoot select the prepared upstream installation and owned output. Returns platform/architecture/root/helperExecutable/executable and complete configure/compile/install diagnostics. Preserves cancellation and process failures; installs no dependency, model or toolchain and performs no inference."
+    },
+    {
+      "id": "local-ai-nemotron-build:default",
+      "name": "default",
+      "displayName": "buildNemotronHelper default export",
+      "kind": "function",
+      "signature": "default as buildNemotronHelper",
+      "entrypoints": [
+        "arcane-os/local-ai/nemotron/build"
+      ],
+      "primaryImport": "arcane-os/local-ai/nemotron/build",
+      "group": "Core native speech",
+      "summary": "Default binding for the same buildNemotronHelper function.",
+      "availability": "Node with CMake 3.26+, C++17 toolchain and platform-matching public NeMo ASR headers/libraries/CMake package",
+      "protocol": "Owned configure/build/install process lifecycle",
+      "normalization": "Binding identity equals the named buildNemotronHelper export"
+    },
+    {
+      "id": "local-ai-magpie:createMagpieRuntime",
+      "name": "createMagpieRuntime",
+      "displayName": "createMagpieRuntime()",
+      "kind": "function",
+      "signature": "createMagpieRuntime({runtime,prepare,paths,modelAssets,assetProjectionId,resourcePaths,modelId='magpie',voice='Aria',languageCode='en-US',executionTarget,signal,onEvent}={})",
+      "entrypoints": [
+        "arcane-os/local-ai/magpie"
+      ],
+      "primaryImport": "arcane-os/local-ai/magpie",
+      "group": "Core native speech",
+      "summary": "Retains native Magpie and NanoCodec for complete audio or ordered PCM synthesis.",
+      "availability": "Node with a matching first-party helper, selected NeMo TTS runtime, Magpie/tokenizer and NanoCodec assets; Windows/Linux/macOS source, Android host adaptation",
+      "protocol": "Native TTS C ABI through one retained helper and replaying magpie.state",
+      "normalization": "Returns current/subscribe/load/unload/synthesize/synthesizeStream/stop/close. Explicit CPU/CUDA selection, model-owned voice map and per-request language remain separate from exact input. Complete wav/pcm export and awaited ordered s16le onAudio delivery share FIFO request ownership. Native speed is 1. Stop targets a requestId and joins native/callback cleanup; self-joins reject MAGPIE_CALLBACK_WAIT. Playback and conversational meaning remain caller-owned; no download or fallback."
+    },
+    {
+      "id": "local-ai-magpie:default",
+      "name": "default",
+      "displayName": "createMagpieRuntime default export",
+      "kind": "function",
+      "signature": "default as createMagpieRuntime",
+      "entrypoints": [
+        "arcane-os/local-ai/magpie"
+      ],
+      "primaryImport": "arcane-os/local-ai/magpie",
+      "group": "Core native speech",
+      "summary": "Default binding for the same createMagpieRuntime function.",
+      "availability": "Node with a matching first-party helper, selected NeMo TTS runtime, Magpie/tokenizer and NanoCodec assets; Windows/Linux/macOS source, Android host adaptation",
+      "protocol": "Native TTS C ABI through one retained helper and replaying magpie.state",
+      "normalization": "Binding identity equals the named createMagpieRuntime export"
+    },
+    {
+      "id": "local-ai-magpie-build:buildMagpieHelper",
+      "name": "buildMagpieHelper",
+      "displayName": "buildMagpieHelper()",
+      "kind": "function",
+      "signature": "async buildMagpieHelper({runtime,outputRoot,signal,onEvent}={})",
+      "entrypoints": [
+        "arcane-os/local-ai/magpie/build"
+      ],
+      "primaryImport": "arcane-os/local-ai/magpie/build",
+      "group": "Core native speech",
+      "summary": "Builds the first-party Magpie synthesis helper against a caller-selected NeMo installation.",
+      "availability": "Node with CMake 3.26+, C++17 toolchain, platform threads and matching public NeMo TTS headers/libraries/CMake package",
+      "protocol": "Owned configure/build/install process lifecycle",
+      "normalization": "runtime.cmakeDirectory and outputRoot select the prepared upstream installation and owned output. Returns platform/architecture/root/helperExecutable and complete configure/compile/install diagnostics. Preserves cancellation and process failures; installs no dependency, model or toolchain and performs no inference."
+    },
+    {
+      "id": "local-ai-magpie-build:default",
+      "name": "default",
+      "displayName": "buildMagpieHelper default export",
+      "kind": "function",
+      "signature": "default as buildMagpieHelper",
+      "entrypoints": [
+        "arcane-os/local-ai/magpie/build"
+      ],
+      "primaryImport": "arcane-os/local-ai/magpie/build",
+      "group": "Core native speech",
+      "summary": "Default binding for the same buildMagpieHelper function.",
+      "availability": "Node with CMake 3.26+, C++17 toolchain, platform threads and matching public NeMo TTS headers/libraries/CMake package",
+      "protocol": "Owned configure/build/install process lifecycle",
+      "normalization": "Binding identity equals the named buildMagpieHelper export"
+    },
     {
       "id": "local-ai-whisper:createWhisperRuntime",
       "name": "createWhisperRuntime",
@@ -429,8 +557,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/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."
+      "protocol": "arcane/1 speech.status/load/unload/transcribe/synthesize; optional open/push/endpoint/finish/cancel/synthesizeStream/audioConsumed/cancelSynthesis with speech.state/progress/opened/transcription/audio",
+      "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. Per-role supportsStreaming reflects actual engine methods independently of readiness. Request-scoped streaming retains exact PCM and unchanged snapshots; endpoint preserves stream scope, terminal finish drains, and cancellation joins native ownership. Awaited TTS audio acknowledgements apply producer backpressure without blocking control traffic. ASR finals do not decide conversation completion. Startup waiting is independently owned from caller cancellation; no automatic provider selection is introduced."
     },
     {
       "id": "core-speech:default",
@@ -4444,7 +4572,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. 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."
+      "normalization": "speech.openStream(request,options) returns streamId/ready/completion/current/push/forceEndpoint/finish/cancel with ordered exact Float32 input and complete snapshot callbacks; endpoint/finish delivery joins must occur outside their own callbacks. Explicit stream cancel joins native cleanup, distinct from ordinary signal cancellation. speech.synthesizeStream(request,{signal,onAudio,onProgress,onRequest}) awaits required ordered Uint8Array PCM callbacks and exact consumption acknowledgements, joins cancellation, and returns complete terminal metadata without playback. Both streams have no fixed timeout. 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/inventory/runtime-modules.json

@@ -5,12 +5,12 @@
     "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
     "branch": "main",
     "path": "runtime/arcane",
-    "sdkVersion": "0.51.1",
+    "sdkVersion": "0.95.0",
     "protocol": "arcane/1"
   },
-  "artifactCount": 93,
-  "javascriptArtifactCount": 91,
-  "esmExportCount": 375,
+  "artifactCount": 95,
+  "javascriptArtifactCount": 93,
+  "esmExportCount": 377,
   "artifacts": [
     {
       "file": "runtime/arcane/modules/AI.js",
@@ -27,11 +27,11 @@
         "AI_READY_EVENT",
         "default"
       ],
-      "summary": "Owns provider-selectable chat and the one-time caller-authority browser STT/TTS configuration, lifecycle, synthesis, transcription, and playback boundary.",
+      "summary": "Owns provider-selectable chat and the caller-selected browser/native STT/TTS configuration, lifecycle, synthesis, transcription, and playback boundary.",
       "availability": "Browser + native bridge + TWiN Cloud",
       "protocol": "arcane-ai-browser-speech-configuration/1, AIProviderRuntime arcane-ai-provider/2 routes, globalThis.arcaneEvents, TWiN Cloud HTTPS, Arcane.ollama, Arcane.speech, Android WebView bridge",
       "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized Whisper STT and Kokoro TTS execution with default capacities 1 and 4 respectively, explicit provider-neutral execution snapshots through status(role,{execution:true}), sticky readiness, canonical window.user readiness without compatibility-event object-identity admission or polling, exact ordered structural calls with required arguments.message, atomic nonblank all-ID tool-result sequencing, complete all-choice streaming/data validation, native Ollama structural adaptation, complete-response then all validated tool callbacks then completion ordering, observed async callbacks, Blob/File transcription, default repeated-formatting-mark removal from cloned outbound TTS input, explicit textFormat:'plain' preservation for complete synthesis/preparation while streaming cleanup remains automatic and caller/visible content stays exact, immediate exact-segment synthesis, per-call voice/speed capture, optional final-segment pause on the existing audio clock, optional per-call terminal playback completion, detached preparation with complete semantic DBOPFS audio reuse and same-owner pending request sharing; each preparation owns its pending activation interest, final-interest cancellation aborts that activation while other interests preserve it, complete cache hits start no model, and cancellation after readiness leaves the ready model loaded; independent prepared playback without a model load for cached audio, ordered audio-clock scheduling, playable audio, active-generation TTS operation-failure routing, mute, and cancellation are normalized; provider/model/runtime/voice policy remains caller-owned. Both speech roles default execution.device to auto: webnn-npu when navigator.ml.createContext is exposed, then webgpu when navigator.gpu is exposed, then wasm for CPU execution. Failed backend loads clean up the pool before trying fresh Workers with the same prepared model and dtype; explicit devices never fall back. STT capacity only accepts 1; TTS accepts 1 through 4. Execution snapshots expose requestedDevice, selectedDevice, maxConcurrentRequests, and activeRequestCount for both roles; selectedDevice is null while unloaded and names the successful upstream session backend request when loaded. It does not prove every operation used the physical NPU: WebNN unsupported operations may use WASM, and compatibility depends on the browser, driver, hardware, and graph. High-level LLM selection defaults to eager activation; startLanguageModel:false preserves the selected tuple and registered adapters without preloading through later readiness callbacks. Caller cancellation waits for accepted old-role cleanup and prevents later configuration/preload, or reaches the first owned load after selection commits. Newer accepted selections supersede older continuations; deferred or cancelled activation stays inactive until explicit load/startup, and a caller abort after successful settlement never unloads the ready model. Separate callers joining an existing runtime load retain their current cancellation ownership.",
-      "surface": "Native fetchTTS(payload,signal) and fetchSTT(audio,signal) forward caller cancellation separately from their complete Core speech payloads, normalize aborts to AbortError and suppress late results; actual engine interruption remains service-owned. prepareTTSPlayback(payload,signal) silently returns a real Blob or native-speech descriptor; native controls expose finished/released/state/error/pause/resume/stop, and actual release owns the playback lane. fetchTTS and durable prepareTTS report ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE for native voices. Request-local model overrides remain exact and never mutate the configured model. Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; default speech-input cleanup with SDK-internal preparation metadata and explicit complete-call textFormat:'plain' consumed before engine dispatch; `prepareTTS({parts,storage,identity,textFormat,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); async `readPreparedTTS({parts,textFormat,storage,identity,signal,onState})` returning a complete ready handle or null through the same semantic matcher, with no activation, unmute, synthesis, playback, storage writes, or partial repair; manifest, audio availability, and returned-handle reads use DBOPFS createTable:false so absent tables remain absent; supplied adapters own that read-existing behavior; missing matches/audio return null, malformed metadata and storage failures reject, and omitted storage sees only completed matching same-AI in-memory audio; hits replay ready state, misses emit nothing, and the lookup signal detaches on settlement while returned-handle cancellation stays independent; `prepareAudioOutput()` returning the persistent WebAudio handle {kind,state,contextState,error,subscribe,resume,dispose} without resume, unmute, model load, sources, sound, or gesture listeners; current-state replay and output-specific canonical `AI_AUDIO_OUTPUT_STATE_EVENT` (`ai-audio-output-state`), with ready only for an actually running context; explicit owner disposal observes context-bound cleanup and close; `playPreparedTTS(prepared,{signal,onState,audioOutput})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; explicit live same-AI audioOutput borrows its context until owner disposal, while omission or null preserves per-playback terminal close; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`. `setAI(llmService,sttService,ttsService,model,modelTTS,modelSTT,options)` and `transitionAI(llmService,sttService,ttsService,model,modelTTS,modelSTT,options)` preserve six positional preferences; `configureProviders(selections,options)` and `transitionProviders(selections,options)` accept the same optional {signal:null,startLanguageModel:true} defaults. setAI retains its synchronous boolean and configureProviders its synchronous route result. Explicit `providerRuntime.load('llm',{signal})` or `startProviders({startLanguageModel:true,signal})` activates a deferred selected route."
+      "surface": "Explicit null LLM service and null model constructor arguments leave LLM routes unselected; omitted/empty arguments retain defaults, and an existing window.ai is reused. supportsTranscriptionCapture() and createTranscriptionCapture(options) expose selected-provider capture without starting it. Native capture forwards exact PCM, callbacks and external endpoint/stop/cancel joins; finals are recognition segments, never automatic chat. Streaming native TTS preparation is inert, play consumes ordered PCM and released joins native cleanup. Per-utterance languageCode is forwarded separately from text. voice/speed/languageCode persist with an unfinished streamTTS utterance through finishTTS; explicit language change queues the previous remainder under its prior selection. Native fetchTTS(payload,signal) and fetchSTT(audio,signal) forward caller cancellation separately from their complete Core speech payloads, normalize aborts to AbortError and suppress late results; actual engine interruption remains service-owned. prepareTTSPlayback(payload,signal) silently returns a real Blob or native-speech descriptor; native controls expose finished/released/state/error/pause/resume/stop, and actual release owns the playback lane. fetchTTS and durable prepareTTS report ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE for browser-native voices without audio export; Magpie retains full-audio export. Request-local model overrides remain exact and never mutate the configured model. Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, languageCode, pauseAfterMs, and waitForPlayback; default speech-input cleanup with SDK-internal preparation metadata and explicit complete-call textFormat:'plain' consumed before engine dispatch; `prepareTTS({parts,storage,identity,textFormat,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); async `readPreparedTTS({parts,textFormat,storage,identity,signal,onState})` returning a complete ready handle or null through the same semantic matcher, with no activation, unmute, synthesis, playback, storage writes, or partial repair; manifest, audio availability, and returned-handle reads use DBOPFS createTable:false so absent tables remain absent; supplied adapters own that read-existing behavior; missing matches/audio return null, malformed metadata and storage failures reject, and omitted storage sees only completed matching same-AI in-memory audio; hits replay ready state, misses emit nothing, and the lookup signal detaches on settlement while returned-handle cancellation stays independent; `prepareAudioOutput()` returning the persistent WebAudio handle {kind,state,contextState,error,subscribe,resume,dispose} without resume, unmute, model load, sources, sound, or gesture listeners; current-state replay and output-specific canonical `AI_AUDIO_OUTPUT_STATE_EVENT` (`ai-audio-output-state`), with ready only for an actually running context; explicit owner disposal observes context-bound cleanup and close; `playPreparedTTS(prepared,{signal,onState,audioOutput})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; explicit live same-AI audioOutput borrows its context until owner disposal, while omission or null preserves per-playback terminal close; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`. `setAI(llmService,sttService,ttsService,model,modelTTS,modelSTT,options)` and `transitionAI(llmService,sttService,ttsService,model,modelTTS,modelSTT,options)` preserve six positional preferences; `configureProviders(selections,options)` and `transitionProviders(selections,options)` accept the same optional {signal:null,startLanguageModel:true} defaults. setAI retains its synchronous boolean and configureProviders its synchronous route result. Explicit `providerRuntime.load('llm',{signal})` or `startProviders({startLanguageModel:true,signal})` activates a deferred selected route."
     },
     {
       "file": "runtime/arcane/modules/AIModelSelectionController.js",
@@ -92,7 +92,7 @@
       "availability": "Cross-host in-process runtime; registered providers remain browser, native, or cloud specific",
       "protocol": "arcane-ai-runtime/2, arcane-ai-provider/2, arcane-ai-model-authority/1",
       "normalization": "Normalizes mutable complete per-role routes, lifecycle/status, cancellation, streaming cleanup, capacity-1 FIFO LLM/STT lanes, bounded provider-declared parallel TTS requests with FIFO overflow, default repeated-formatting-mark removal from cloned direct TTS payloads or explicit textFormat:'plain' preservation with the control consumed before engine dispatch, local-only selection, direct LLM history/declaration/terminal structural contracts, complete all-choice content/reasoning FIFO iteration, private automatic provider draining with result-first buffering, terminal-only structural calls, exact per-choice observed/terminal correlation, and a separate complete validated terminal result without creating a fallback.",
-      "surface": "Protocol constants; singleton-only `AIProviderRuntime`; `aiProviderRuntime`; `getAIProviderRuntime()`; provider registration/identity/selection, closed three-role and STT/TTS-only validation/configuration/replacement, status/catalog/inspection, startup, per-role load/unload/dispose/cancel, dispose-all, request/stream/speech aliases, SDK-internal speech-input preparation metadata, and setSpeechMuted(muted,{signal}={}) controls. Each pending unmute caller owns its abortable interest; the final interest aborts the owned activation while other preparation/playback or joining direct TTS-load interests preserve it. A pre-aborted unmute starts no activation. Explicit mute retains global cancellation and joined unload even with an aborted observer signal."
+      "surface": "supportsTranscriptionCapture(providerId=null) reports the provider capture capability; createTranscriptionCapture(options) returns null or an owned start/stop/cancel/destroy/done handle with optional forceEndpoint. Start requires an idle ready selected STT role, remains in the initiating user gesture and is never queued. Capture holds that role until done joins cleanup; cancellation/retirement uses the same role owner. Native streaming TTS uses the existing request lane with ordered awaited PCM callbacks. Protocol constants; singleton-only `AIProviderRuntime`; `aiProviderRuntime`; `getAIProviderRuntime()`; provider registration/identity/selection, closed three-role and STT/TTS-only validation/configuration/replacement, status/catalog/inspection, startup, per-role load/unload/dispose/cancel, dispose-all, request/stream/speech aliases, SDK-internal speech-input preparation metadata, and setSpeechMuted(muted,{signal}={}) controls. Each pending unmute caller owns its abortable interest; the final interest aborts the owned activation while other preparation/playback or joining direct TTS-load interests preserve it. A pre-aborted unmute starts no activation. Explicit mute retains global cancellation and joined unload even with an aborted observer signal."
     },
     {
       "file": "runtime/arcane/modules/AIResponseURLPolicy.js",
@@ -442,11 +442,11 @@
       "exports": [
         "default"
       ],
-      "summary": "Owns continuous microphone capture with rolling pre-roll, activity-triggered pause/periodic segments, complete WAV delivery, final flush, and cancellation.",
+      "summary": "Owns continuous microphone capture with complete ordered PCM or rolling pre-roll, activity-triggered pause/periodic segments, complete WAV delivery, final flush, and cancellation.",
       "availability": "Browser / native WebView with getUserMedia, AudioContext, and AudioWorklet",
       "protocol": "Native microphone and Web Audio lifecycle; internal VoiceCaptureWorklet MessagePort",
-      "normalization": "Complete mono Float32 WAV Blob segments with session-local sequence, pause/periodic/stop reason, and durationMs. Sound amplitude drives segmentation without semantic speech recognition. Inactive audio produces no segment, and periodic segments do not reuse samples. Stop releases microphone tracks immediately and waits for final flush; cancel releases capture and suppresses late callbacks.",
-      "surface": "default ContinuousVoiceCapture; constructor({preRollMs=1500,quietMs=2000,chunkMs=30000,activityThreshold=0.02,onSegment,onError,onState}); start({mediaConstraints={audio:true},signal}={}) resolves boolean; stop() resolves after final flush; cancel() and destroy() release the owned session."
+      "normalization": "mode:pcm transfers every sample in ordered Float32Array records with actual sampleRate/channels/sequence; amplitude activity reports no semantic speech decision and never gates PCM. flush joins earlier PCM delivery without closing capture. Stop/cancel/destroy join accepted PCM and actual AudioContext close, surfacing failures. In the default segments mode: Complete mono Float32 WAV Blob segments with session-local sequence, pause/periodic/stop reason, and durationMs. Sound amplitude drives segmentation without semantic speech recognition. Inactive audio produces no segment, and periodic segments do not reuse samples. Stop releases microphone tracks immediately and waits for final flush; cancel releases capture and suppresses late callbacks.",
+      "surface": "default ContinuousVoiceCapture; constructor({preRollMs=1500,quietMs=2000,chunkMs=30000,activityThreshold=0.02,mode=segments,pcmChunkMs=100,onSegment,onPCM,onActivity,onError,onState}); start({mediaConstraints={audio:true},sampleRate,signal}={}) resolves boolean; flush() resolves after pending PCM delivery; stop() resolves after final flush and close; cancel() and destroy() release the owned session."
     },
     {
       "file": "runtime/arcane/modules/ConversationActionItems.js",
@@ -991,6 +991,32 @@
       "normalization": "Complete mutable definition data with coded syntax errors for malformed input.",
       "surface": "`parseModelDefinition()`, `loadModelDefinitionSystemPrompt()`."
     },
+    {
+      "file": "runtime/arcane/modules/NativeSpeechCapture.js",
+      "name": "NativeSpeechCapture.js",
+      "kind": "esm",
+      "exports": [
+        "default"
+      ],
+      "summary": "Connects one microphone lifetime to one retained Core transcription stream without deciding conversational turns.",
+      "availability": "Browser / native WebView with microphone, AudioWorklet and selected streaming Core speech",
+      "protocol": "ContinuousVoiceCapture PCM and Arcane.speech.openStream",
+      "normalization": "Exact ordered mono PCM at the actual declared rate; complete provisional/final snapshots and callback controls. forceEndpoint flushes audio and recognition while preserving capture and stream scope; stop drains terminally; cancel joins capture/native cleanup without claiming a complete transcript.",
+      "surface": "default createNativeSpeechCapture({speech,model,sampleRate=16000,pcmChunkMs=100,activityThreshold=0.02,streamOptions,mediaConstraints,onUpdate,onInterim,onSegment,onActivity,onState,onError,onProgress,onRequest}); returns start({signal,mediaConstraints}), forceEndpoint(), stop(), requestStop(), cancel(reason), destroy(reason), done and current(). Recognition callbacks receive (result,{requestStop}); request a stop then return, and join externally. No implicit model load, conversation reply or fallback."
+    },
+    {
+      "file": "runtime/arcane/modules/NativeSpeechPlayback.js",
+      "name": "NativeSpeechPlayback.js",
+      "kind": "esm",
+      "exports": [
+        "default"
+      ],
+      "summary": "Prepares an inert native speech descriptor and plays ordered PCM through the existing shared Web Audio owner.",
+      "availability": "Browser / native WebView with Web Audio and selected streaming speech",
+      "protocol": "speech.synthesizeStream with awaited PCM consumption",
+      "normalization": "Preparation starts no synthesis or playback. play schedules every supplied s16le sample in original order with audio-clock backpressure. Pause retains playback position; stop cancels only that utterance. finished and released distinguish playback termination from joined native cleanup; errors remain observable.",
+      "surface": "default prepareNativeSpeechPlayback({speech,request,getAudioContext,signal=null}); returns {kind:native-speech,input,voice,language,speed,play}. play({signal,onState}) returns finished/released/state/error/pause/resume/stop. The caller owns its AudioContext; this module never closes unrelated output."
+    },
     {
       "file": "runtime/arcane/modules/Ollama.js",
       "name": "Ollama.js",
@@ -1462,11 +1488,11 @@
       "name": "VoiceCaptureWorklet.js",
       "kind": "worker",
       "exports": [],
-      "summary": "Segments microphone samples on the audio rendering thread and transfers complete mono Float32 WAV clips to ContinuousVoiceCapture.",
+      "summary": "Transfers continuous PCM or segments microphone samples on the audio rendering thread and transfers complete mono Float32 WAV clips to ContinuousVoiceCapture.",
       "availability": "AudioWorkletGlobalScope",
       "protocol": "AudioWorklet processor arcane-continuous-voice-capture and its owner-local MessagePort",
-      "normalization": "Rolling pre-roll, fixed 20 ms RMS activity windows independent of callback length, audio-frame quiet duration, periodic boundaries, sequence, complete original WAV audio, and stop acknowledgement are owned here. activityThreshold is RMS amplitude, not peak amplitude. Stop classifies a partial final window using its actual samples and retains softer trailing audio in the active clip. Inactive capture emits no clips; adjacent periodic clips have no repeated samples.",
-      "surface": "No ESM exports. ContinuousVoiceCapture loads this static worklet, supplies processorOptions, receives segment messages, and requests stop followed by the stopped acknowledgement."
+      "normalization": "mode:pcm emits every original sample in ordered PCM frames at the actual worklet sample rate, plus activity observations; pcmChunkMs defines transport scheduling, not a recording cap. flush returns pending PCM and a correlated flushed acknowledgement without closing the processor. The default segments mode retains rolling pre-roll, fixed 20 ms RMS activity windows independent of callback length, audio-frame quiet duration, periodic boundaries, sequence, complete original WAV audio, and stop acknowledgement. activityThreshold is RMS amplitude, not peak amplitude. Stop classifies a partial final window using its actual samples and retains softer trailing audio in the active clip. Inactive capture emits no clips; adjacent periodic clips have no repeated samples.",
+      "surface": "No ESM exports. ContinuousVoiceCapture loads this static worklet, supplies processorOptions, receives segment or pcm/activity/flushed messages, and requests stop followed by the stopped acknowledgement."
     },
     {
       "file": "runtime/arcane/modules/WaitForComponent.js",

package/docs/reference/model-assets.md

@@ -110,11 +110,11 @@ try {
 }
 ```
 
-`prepare({id,workingDirectory,members,signal,onProgress,refresh=false})` reuses
+`prepare({id,workingDirectory,members,archives,signal,onProgress,refresh=false})` reuses
 a complete native acquisition or fetches the explicitly selected members.
 Every member has its original relative `path` and selected `url`; the caller
 supplies the complete companion-file set. Independent members download
-concurrently. Each complete response stream is written directly to its native
+concurrently, with up to four independent source transfers active. Each complete response stream is written directly to its native
 file, without a whole-model buffer or base64 conversion. No model or runtime
 is selected or downloaded by service startup. The result remains the ready
 projection snapshot with ordered `members: [{path,nativePath}]`.
@@ -144,6 +144,158 @@ callback does not hold another caller's transfer or result. Callbacks must not
 await cleanup of the preparation currently calling them. Callback failures
 reject that caller's preparation. HTTP failures
 retain `url`, `status` and the complete response text in `response`.
+During an active member, repeated activity notifications are emitted at most
+once per second; opening, member completion and terminal phases remain distinct.
+Progress describes files and phases, never transfer volume.
+
+### Selected archive companions
+
+An optional `archives` array acquires exact companion members from an upstream
+uncompressed TAR source through this same acquisition owner:
+
+```javascript
+const projection = await modelAssets.prepare({
+    id: selectedOperationId,
+    workingDirectory: selectedModelDirectory,
+    members: selectedModelFiles,
+    archives: [{
+        url: selectedArchiveURL,
+        format: 'tar',
+        members: [
+            {path: 'tokenizer/model_config.yaml', member: 'model_config.yaml'},
+            {path: 'tokenizer/speakers.json', member: 'speakers.json'}
+        ]
+    }],
+    signal,
+    onProgress
+});
+```
+
+The result orders ordinary members first, followed by each archive's declared
+members. Extraction preserves each complete selected file. TAR names and PAX
+path records select members; a leading `./` is archive path framing. Missing
+selected members reject preparation and identify the missing names. Gzip and
+other archive formats are outside this reader's contract.
+
+When the upstream catalog supplies aligned TAR segments, an archive may include
+`ranges:[{start,end,stopBefore?}]`. The reader requests each inclusive HTTP range
+once and parses its TAR framing; `stopBefore` ends that segment before the
+specified member. Offsets and TAR lengths are solely external transport framing.
+They are never download progress, model readiness criteria or content identity.
+Ranges require the matching HTTP partial-content response; no complete-archive
+fallback is silently substituted. Native reuse identifies archive members by
+their selected URL, archive member name and output path, alongside ordinary
+members, without re-fetching an already completed set.
+
+## Discover and open installed files
+
+`discover({directories,catalog=[],recursive=true,signal})` inspects only the
+explicit directories, without downloading, copying, loading or selecting a
+model. Paths resolve from `appRoot`. It returns:
+
+```javascript
+{
+    directories: [{directory, exists, error}], // error is present only on failure
+    models: [{
+        directory,
+        entryPath,
+        members: [{path, nativePath, available}],
+        missingMembers: [],
+        complete: true,
+        source: 'directory', // or 'catalog' or 'acquisition'
+        catalogId // present for a matching caller-owned catalog entry
+    }]
+}
+```
+
+Ordinary `.gguf` files are candidates. Split names such as
+`moon-00001-of-00003.gguf` form one candidate with all expected members in numeric
+order, including explicit missing members. The first shard is `entryPath`,
+including when a completed acquisition declared only later shards or listed
+them out of order. Acquisition candidates retain all their ordinary and
+companion members alongside these required shards; separate filename groups
+are never inferred to be one model. Symlinked model files and directories are
+followed, with already visited directory targets reused rather than rescanned.
+Discovery does not establish a model's role, runtime compatibility or successful
+inference. Those selections remain with the application and engine owners.
+
+Catalog entries are `{id,members:[{path,url?}],archives?,entryPath?}`. They describe
+an exact companion set and can include nested tokenizer files or multiple model
+files. A discovered catalog candidate reports every expected member, including
+missing companions. Completed native acquisition records are also discoverable;
+when the catalog supplies URLs or archive member names, acquisition matching
+also preserves those recorded source selections. A different pinned source with
+the same filenames is not relabeled as that catalog selection. Path-only catalogs
+and ordinary installed-directory candidates make no source-revision claim.
+Unfinished acquisition attempts are ignored. Discovery never removes either.
+Set `recursive:false` for a directory-only inspection. Missing root directories
+are reported with `exists:false`; other root access failures include their
+complete serialized error. A failure while reading a descendant is surfaced.
+
+`openExisting({id,directory,members:[{path}],signal})` opens a complete selected
+set as an ordinary ready projection. It rechecks every member and reports
+`MODEL_ASSET_MEMBERS_MISSING` with `members` when files are absent. It performs
+no copy or network request. Engines use the same `retain(id)` lifecycle.
+Preparation release, engine unload and service disposal never delete borrowed
+originals. External edits or deletion remain controlled by the files' owner.
+
+The application supplies persistent model directories separately from disposable
+build output. The native launch context exposes its platform-specific
+`modelsDirectory`; apps may additionally inspect selected application directories.
+The model-assets service creates no platform directory policy of its own.
+
+`resolveNativeLaunchContext({appId,context})` defaults `modelsDirectory` to
+`Models` beneath the resolved persistent `stateRoot`. It preserves an explicitly
+supplied `modelsDirectory` unchanged and creates or migrates no files:
+
+| Host | Default application state root |
+| --- | --- |
+| Windows | `%LOCALAPPDATA%/Arcane/<appId>`; the user's `AppData/Local` when that environment variable is absent |
+| macOS | `~/Library/Application Support/Arcane/<appId>` |
+| Linux | `$XDG_DATA_HOME/Arcane/<appId>` when absolute, otherwise `~/.local/share/Arcane/<appId>` |
+| Android or another host adaptation | The host supplies its explicit app-private `stateRoot` |
+
+Pass this `modelsDirectory` as the acquisition `workingDirectory` and as one
+discovery directory. Completed files then live beneath its `model-assets`
+subdirectory, separate from replaceable application builds. Additional selected
+application directories can participate in the same discovery call.
+
+### Prepare a selected local runtime on demand
+
+`createLocalAIService(configuration,{autoStart:false,...options})` registers the
+existing local-AI owner without preparing or starting its selected runtimes at
+Core startup. The default remains `autoStart:true`, preserving existing startup
+behavior. After the user explicitly requests preparation, invoke
+`client.invoke('localai.prepare', {}, {signal,timeoutMs:0})`. The operation uses
+the configured existing runtime preparation callback and returns the current
+local-AI state; it does not invent a runtime or model selection.
+
+Preparation callback events are published as `localai.preparation` with their
+complete original event payload. Subscribe through the existing Core event
+owner to display actual preparation phases. Concurrent preparation requests
+reuse the owner's in-flight work, and subsequent completed calls reuse its
+prepared state. Runtime and model selection, explicit model acquisition and
+microphone activation remain app-owned; preparation is not an inference or
+microphone operation. Rendering the interface and
+discovering installed files need not wait for runtime preparation.
+
+### Browser discovery and explicit download
+
+`arcane-os/ai/core-model-assets` additionally exports
+`discoverCoreModelAssets({client,directories,catalog,recursive,signal})`,
+`openExistingCoreModelAssets({client,directory,members,signal})`, and
+`downloadCoreModelAssets({client,workingDirectory,members,archives,refresh,signal,onProgress})`.
+`client` defaults to the installed Core client. Discovery returns the native
+record above; opening and downloading return `{id,directory,members,release}`.
+The existing Blob-based `prepareCoreModelAssets` keeps its original contract.
+
+Download progress callbacks receive the complete semantic progress record,
+correlated to this preparation and observed in order. Callback failure cancels
+the operation. Cancellation joins explicit native cleanup and local callback
+delivery before the helper settles; cleanup failures remain observable.
+Callbacks must not await their own enclosing preparation or cancellation join.
+Applications initiate downloads explicitly and display actual phases, selected
+member paths, completed-file counts and errors in the appropriate surface.
 
 `release(id)` relinquishes preparation ownership without a request signal.
 Same-process callers sharing the actual store, complete source selection and
@@ -186,7 +338,8 @@ try {
 ```
 
 `createModelAssetService({appRoot})` returns a Core service with `current()`,
-`prepare(options)`, `retain(id)`, `release(id)` and `dispose()`. `retain()` accepts only a completed projection
+`discover(options)`, `openExisting(options)`, `prepare(options)`, `retain(id)`,
+`release(id)` and `dispose()`. `retain()` accepts only a completed projection
 and returns `{id,directory,members,release}`. A native engine takes this handle
 before loading and releases it after actual unload, failed-load cleanup or
 worker exit. A rejected inference/load promise alone does not establish native
@@ -249,6 +402,10 @@ for source selection, cancellation and complete row/output contracts.
 | Method | Parameters | Result |
 | --- | --- | --- |
 | `modelAssets.open` | `{id,workingDirectory,members:[{path}]}` | Preparing projection and native member paths |
+| `modelAssets.discover` | `{directories,catalog?,recursive?}` | Directory status and complete/incomplete model candidates |
+| `modelAssets.openExisting` | `{id,directory,members:[{path}]}` | Ready retained projection of existing originals |
+| `modelAssets.prepare` | `{id,workingDirectory,members,archives?,refresh?}` | Ready persistent acquisition; request-scoped `modelAssets.progress` emits `{id,progress}` |
+| `modelAssets.cancelPrepare` | `{id}` | Cancel and join the matching native preparation, then release its preparation ownership |
 | `modelAssets.write` | `{id,memberIndex,contentBase64}` | `{id,memberIndex,written:true}` after the native write |
 | `modelAssets.complete` | `{id}` | Ready projection after all files close |
 | `modelAssets.release` | `{id}` | Released preparation ownership; native uses may retain the files |
@@ -258,6 +415,10 @@ The browser helper owns this transport sequence. Correlation IDs identify
 operations; they are unrelated to content identity. Original model files remain
 separate and complete. A retry creates a new working projection from the stored
 assets; it does not redownload them or replace the authoritative DBOPFS record.
+`cancelPrepare` and `release` have service lifetime so cancellation of the
+original request cannot cancel its cleanup control. Native preparation follows
+the original request signal, including connection cancellation; raw RPC callers
+join `cancelPrepare` when cancelling and release any successful unused projection.
 
 The implementation uses browser streams, the existing portable Core JSON
 transport and Node filesystem operations. Native paths and cleanup follow the

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.