arcane-os 0.94.0 → 0.95.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.95.0
+
+- Add retained native Nemotron streaming recognition and optional diarization,
+  with ordered complete snapshots, explicit utterance endpoints, speaker scope,
+  and joined cancellation. Preserve existing Whisper and complete transcription.
+- Add native Magpie/NanoCodec synthesis with model-owned voice selection,
+  per-request language, ordered PCM streaming, complete WAV/PCM export, and
+  exact-utterance cancellation. Preserve authored input and natural model rate;
+  the caller supplies upstream runtime and model assets without SDK vendoring.
+- Extend shared Core speech and browser clients with correlated streaming
+  capture/output, consumed-audio acknowledgements and native cleanup joins.
+  Connect AI playback through its existing queues and shared AudioContext,
+  retaining per-utterance pause/resume/stop and complete-audio APIs.
+- Keep capture ownership, recognition segments and model-owned conversational
+  decisions distinct. Windows x64 native helpers compiled and installed against
+  the approved NeMo 0.2.0 runtime; inference, microphone/audio acceptance and
+  other-platform execution remain separate evidence boundaries.
+
 ## 0.94.0
 
 - Recover all TWiN HTTP 429 quota responses through the shared chat/System One

package/README.md

@@ -25,7 +25,7 @@ selected SDK projection or an explicit live SDK source mount. Both profiles
 share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.94.0` SDK contract. Development applications declare
+This checkout defines the `0.95.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;

package/browser-runtime/core/client.mjs

@@ -569,6 +569,199 @@ export function createCoreClient({
 export function createCoreFacade(client){
     const {invoke,events,uuid}=client;
     const long={timeoutMs:LONG_OPERATION_TIMEOUT};
+    function speechStreamEvents(streamId,options){
+        const controller=new AbortController();
+        const signal=options.signal?AbortSignal.any([options.signal,controller.signal]):controller.signal;
+        const subscriptions=[];
+        let delivery=Promise.resolve();
+        let callbackFailure;
+        function listen(name,callback){
+            if(callback===undefined)return;
+            if(typeof callback!=='function')throw new TypeError(`${name} observer must be a function.`);
+            subscriptions.push(events.on(name,function receiveSpeechStreamEvent(event){
+                if(event?.streamId!==streamId||signal.aborted)return;
+                delivery=delivery.then(function deliverOrderedSpeechEvent(){
+                    if(!signal.aborted)return callback(event);
+                });
+                delivery.catch(function cancelFailedSpeechObserver(error){
+                    callbackFailure??=error;
+                    controller.abort(error);
+                });
+            }));
+        }
+        function dispose(){
+            for(const unsubscribe of subscriptions.splice(0))unsubscribe();
+        }
+        async function delivered(){
+            await delivery;
+            signal.throwIfAborted();
+        }
+        async function settle(task,{preserveTaskFailure=false}={}){
+            let result;
+            let failure;
+            let failed=false;
+            let deliveryFailure;
+            let deliveryFailed=false;
+            try{
+                try{result=await task;}catch(error){failed=true;failure=error;}
+                try{await delivery;}catch(error){deliveryFailed=true;deliveryFailure=callbackFailure??error;}
+                if(preserveTaskFailure&&failed&&deliveryFailed&&failure!==deliveryFailure){
+                    throw new AggregateError([deliveryFailure,failure],'Speech callback and native cleanup failed.');
+                }
+                if(failed||deliveryFailed)throw callbackFailure??deliveryFailure??failure;
+                signal.throwIfAborted();
+                return result;
+            }finally{dispose();}
+        }
+        return {controller,signal,listen,settle,dispose,delivered};
+    }
+    function encodeSpeechSamples(samples){
+        if(!(samples instanceof Float32Array))throw new TypeError('Speech stream push requires Float32Array PCM.');
+        const encoded=new Uint8Array(samples.length*4);
+        const view=new DataView(encoded.buffer);
+        const bits=new Uint32Array(samples.buffer,samples.byteOffset,samples.length);
+        for(let index=0;index<bits.length;index+=1)view.setUint32(index*4,bits[index],true);
+        let binary='';
+        for(const value of encoded)binary+=String.fromCharCode(value);
+        return {encoding:'f32le',data:globalThis.btoa(binary)};
+    }
+    function decodeSpeechAudio(audio){
+        if(audio?.pcm?.encoding!=='base64'||typeof audio.pcm.data!=='string'){
+            throw new TypeError('Streaming speech audio requires base64 PCM transport.');
+        }
+        const binary=globalThis.atob(audio.pcm.data);
+        const pcm=new Uint8Array(binary.length);
+        for(let index=0;index<binary.length;index+=1)pcm[index]=binary.charCodeAt(index);
+        return {...audio,pcm};
+    }
+    function openSpeechStream(request={},options={}){
+        const streamId=uuid();
+        const owned=speechStreamEvents(streamId,options);
+        let resolveReady;
+        let rejectReady;
+        let opened=false;
+        let ending=false;
+        let snapshot=null;
+        let controls=Promise.resolve();
+        let finishing=null;
+        let cancelling=null;
+        const ready=new Promise(function waitForSpeechStream(resolve,reject){
+            resolveReady=resolve;
+            rejectReady=reject;
+        });
+        ready.catch(function observeSpeechStreamReadinessFailure(){});
+        try{
+            owned.listen('speech.opened',function speechStreamOpened(event){
+                opened=true;
+                resolveReady(event);
+            });
+            owned.listen('speech.transcription',function transcriptionUpdated(event){
+                snapshot=event.result;
+                return options.onUpdate?.(event.result);
+            });
+            if(options.onProgress!==undefined){
+                owned.listen('speech.progress',function speechStreamProgress(event){return options.onProgress(event);});
+            }
+        }catch(error){owned.dispose();throw error;}
+        const completion=owned.settle(invoke('speech.open',{streamId,options:request},{
+            timeoutMs:0,signal:owned.signal,onRequest:options.onRequest
+        })).then(function speechStreamCompleted(result){
+            if(!opened)throw new CoreError({code:'SPEECH_STREAM_NOT_OPENED',message:'The speech stream ended before readiness.'});
+            return result;
+        }).catch(function speechStreamFailed(error){
+            rejectReady(error);
+            throw error;
+        }).finally(function releaseSpeechStream(){ending=true;});
+        completion.catch(function observeOwnedSpeechStreamFailure(){});
+        function control(method,parameters={}){
+            const task=controls.then(async function sendOrderedSpeechControl(){
+                await ready;
+                owned.signal.throwIfAborted();
+                return invoke(method,{streamId,...parameters},{timeoutMs:0,signal:owned.signal});
+            });
+            controls=task;
+            task.catch(function cancelFailedSpeechControl(error){owned.controller.abort(error);});
+            return task;
+        }
+        return {
+            streamId,ready,completion,
+            current:function currentSpeechTranscript(){return snapshot;},
+            push:function pushSpeechSamples(samples){
+                if(ending)return Promise.reject(new CoreError({code:'SPEECH_STREAM_ENDING',message:'The speech stream is finishing.'}));
+                return control('speech.push',{audio:encodeSpeechSamples(samples)});
+            },
+            forceEndpoint:function endpointSpeechStream(){
+                if(ending)return Promise.reject(new CoreError({code:'SPEECH_STREAM_ENDING',message:'The speech stream is finishing.'}));
+                return control('speech.endpoint').then(async function deliverEndpointSnapshots(result){
+                    await owned.delivered();
+                    return result;
+                });
+            },
+            finish:function finishSpeechStream(){
+                if(!ending){
+                    ending=true;
+                    finishing=control('speech.finish').then(function finishSpeechDelivery(){return completion;});
+                    finishing.catch(function observeSpeechFinishFailure(){});
+                }
+                return finishing??completion;
+            },
+            cancel:function cancelSpeechStream(reason){
+                if(cancelling)return cancelling;
+                ending=true;
+                const stopping=invoke('speech.cancel',{streamId},{timeoutMs:0});
+                owned.controller.abort(reason);
+                // A transcript callback may await cancellation. Native cleanup
+                // must not wait for that same callback through completion.
+                cancelling=stopping;
+                return cancelling;
+            }
+        };
+    }
+    function synthesizeSpeechStream(request={},options={}){
+        if(typeof options.onAudio!=='function')throw new TypeError('Streaming speech synthesis requires an onAudio consumer.');
+        const streamId=uuid();
+        const owned=speechStreamEvents(streamId,options);
+        try{
+            owned.listen('speech.audio',async function synthesisAudio(event){
+                await options.onAudio(decodeSpeechAudio(event.audio));
+                owned.signal.throwIfAborted();
+                await invoke('speech.audioConsumed',{streamId,sequence:event.sequence},{timeoutMs:0,signal:owned.signal});
+            });
+            if(options.onProgress!==undefined){
+                owned.listen('speech.progress',function synthesisProgress(event){return options.onProgress(event);});
+            }
+        }catch(error){owned.dispose();throw error;}
+        if(owned.signal.aborted)return owned.settle(Promise.reject(owned.signal.reason));
+        // Keep the response pending until the native operation settles. Generic
+        // invoke cancellation settles locally before native cleanup can finish.
+        const operation=invoke('speech.synthesizeStream',{streamId,request},{
+            timeoutMs:0,onRequest:options.onRequest
+        });
+        let cancellation=null;
+        function cancelSynthesis(){
+            if(cancellation)return;
+            cancellation=invoke('speech.cancelSynthesis',{streamId},{timeoutMs:0});
+            cancellation.catch(function observeSynthesisCleanupFailure(){});
+        }
+        owned.signal.addEventListener('abort',cancelSynthesis,{once:true});
+        if(owned.signal.aborted)cancelSynthesis();
+        const joined=(async function joinSynthesisCleanup(){
+            let result;
+            const failures=[];
+            try{result=await operation;}catch(error){
+                if(!owned.signal.aborted||error?.name!=='AbortError')failures.push(error);
+            }
+            if(cancellation){
+                try{await cancellation;}catch(error){failures.push(error);}
+            }
+            if(failures.length===1)throw failures[0];
+            if(failures.length)throw new AggregateError(failures,'Speech synthesis and cleanup failed.');
+            return result;
+        })();
+        return owned.settle(joined,{preserveTaskFailure:true}).finally(function releaseSynthesisCancellation(){
+            owned.signal.removeEventListener('abort',cancelSynthesis);
+        });
+    }
     function ollamaInvoke(operation,request={},options={}){
         const onChunk=typeof options==='function'?options:options?.onChunk;
         const timeoutMs=options?.timeoutMs??(['pull','push','create'].includes(operation)?LONG_OPERATION_TIMEOUT:10*60*1000);
@@ -598,6 +791,8 @@ export function createCoreFacade(client){
             remove:name=>invoke('environment.delete',{name})},
         mail:{send:request=>invoke('mail.send',request??{},{timeoutMs:450000})},
         speech:{status:()=>invoke('speech.status',{},{timeoutMs:10000}),
+            openStream:openSpeechStream,
+            synthesizeStream:synthesizeSpeechStream,
             load:function loadSpeech(request,options){return invoke('speech.load',request??{},{timeoutMs:0,signal:options?.signal,onRequest:options?.onRequest});},
             unload:function unloadSpeech(request,options){return invoke('speech.unload',request??{},{timeoutMs:0,signal:options?.signal,onRequest:options?.onRequest});},
             synthesize:(request,options)=>invoke('speech.synthesize',request??{},{timeoutMs:180000,signal:options?.signal}),

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

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.92.0",
+  "sdkVersion": "0.94.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",

package/docs/reference/native-magpie.md

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

package/docs/reference/native-nemotron.md

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