arcane-os 0.94.0 → 0.96.0

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.

package/docs/reference/native-speech.md

@@ -1,13 +1,14 @@
 # Native speech service
 
-`createSpeechService({stt, tts, signal} = {})` composes independently selected
+`createSpeechService({stt, tts, signal, autoLoad = true} = {})` composes independently selected
 native speech engines into one Core service. It is the named and default export
 from `arcane-os/core/speech`.
 
 The host supplies an STT engine, a TTS engine, or both. Construction performs no
 installation, model download, model loading, or inference. Core registration
 exposes `speech.status`, `speech.load`, `speech.unload`, `speech.transcribe`,
-and `speech.synthesize`; an operation whose engine was omitted rejects with
+and `speech.synthesize`, plus the optional streaming operations described below;
+an ordinary operation whose engine was omitted rejects with
 `SPEECH_ENGINE_UNAVAILABLE`.
 The optional `signal` controls the service lifetime.
 
@@ -35,11 +36,27 @@ continues calling `speech.transcribe` without loading native libraries itself.
 
 ## Startup and status
 
+A speech-only interface can construct the shared browser AI API with explicit
+`null` for both the language-model service and model:
+`new AI(null, 'LOCAL_SPEACH', 'LOCAL_SPEACH', null, ttsModel, sttModel)`.
+This leaves both LLM routes unselected from construction onward; it does not
+register or activate the historical default language provider. Select a real
+language model later through `configureProviders`. Omitted or empty constructor
+arguments keep their historical defaults, and `setAI` retains its existing
+omitted/null/empty-field semantics.
+
 `start(context)` subscribes to each configured engine and starts their loads
 independently. It returns immediately, allowing Core and `speech.status` to
 respond while models load. A failure in one role leaves the other role usable.
 Each engine publishes the actual state of its selected model.
 
+Use `autoLoad: false` when the host first needs the user to select or download
+model files. Startup still subscribes and exposes the ordinary unloaded state;
+it does not call either engine's `load()`. Explicit `speech.load({role,
+...selection})` activates the prepared role afterward. The default remains
+`true` for existing hosts. This option changes service startup, not the selected
+engine's missing-model errors or inference readiness requirement.
+
 `current()` and `speech.status` return the same snapshot:
 
 | Field | Meaning |
@@ -56,9 +73,16 @@ An engine's state includes `providerId`, `modelId`, `state`, `loaded`, and
 `busy`, with its complete error or progress information when present. An
 omitted role has `state: 'unavailable'`, `loaded: false`, and `busy: false`.
 File presence, a spawned process, and a callable bridge do not establish loaded
-model readiness. Existing readiness consumers additionally recognize
-the engine IDs `whisper.cpp` and `kokoro-onnx`; another engine ID requires the
-corresponding consumer integration.
+model readiness. The shared AI adapter follows the selected engine identity
+and model in these per-role snapshots, including Nemotron and Magpie. Only the
+older aggregate-only fallback retains fixed `whisper.cpp`/`whisper-small` and
+`kokoro-onnx`/`kokoro` expectations.
+
+Each role also reports `supportsStreaming`: STT requires the configured
+engine's `openStream()` method, and TTS requires its `synthesizeStream()` method.
+This capability is independent of `loaded` and `available`; a facade method
+alone does not establish support in the selected engine. Complete engine state,
+including `defaultVoice` and `voices` when supplied, remains present.
 
 ## Explicit role activation
 
@@ -100,6 +124,127 @@ cancelled requests publish no later progress.
 Role load/unload acknowledgements additionally carry `operation: 'load'` or
 `'unload'` in that progress record.
 
+## Continuous transcription and streaming synthesis
+
+`Arcane.speech.openStream(request, {signal, onUpdate, onProgress, onRequest})`
+returns an owned handle immediately:
+
+```js
+const recognition = Arcane.speech.openStream({sampleRate: 16000}, {
+  signal,
+  onUpdate: function retainNativeSnapshot(result) {
+    // Keep the complete snapshot. The application decides when to take a turn.
+    showRecognition(result);
+  }
+});
+await recognition.ready;
+await recognition.push(pcm); // Float32Array, supplied in capture order.
+await recognition.forceEndpoint(); // Finalizes recognition, keeps the stream.
+const complete = await recognition.finish(); // Drains and closes this stream.
+```
+
+The handle exposes `streamId`, `ready`, `completion`, `current()`,
+`push(Float32Array)`, `forceEndpoint()`, `finish()`, and `cancel(reason)`.
+`ready` resolves with the native-open acknowledgement; `completion` resolves
+with the engine's complete terminal result or rejects with its actual failure.
+`current()` returns the latest delivered complete snapshot. Pushes and endpoint
+controls are ordered, and each returned promise lets the producer apply
+backpressure without dropping captured samples. `forceEndpoint()` waits for
+ordered update callbacks preceding its control response, so an external Reply
+control can consume those final segments. `finish()` follows every accepted
+push and waits for final callback delivery. An update callback must not await
+its own `forceEndpoint()`, `finish()`, or `completion` delivery join; invoke these
+controls outside the callback. `cancel()` targets this
+stream, suppresses later callbacks immediately, and awaits its explicit native
+cleanup control; it leaves the other speech role alone. Aborting the caller's
+signal uses ordinary Core request cancellation and can settle the browser's
+request before native cleanup finishes.
+Creation opens no microphone: the selected capture owner supplies PCM.
+
+Updates are the engine's unchanged snapshots, including provisional/final
+status, words, timestamps, and speaker scope when supplied. A provisional
+snapshot replaces the preceding provisional snapshot; it is not appended text.
+An ASR final or silence boundary is recognition output, not a completed human
+turn, an instruction, or approval. `forceEndpoint()` preserves the native
+stream's speaker scope according to its engine contract. The application owns
+conversational meaning, turn completion, tool selection, and whether to issue
+an LLM request. The SDK starts no chat request from an update.
+
+The underlying `speech.open` request remains pending for the entire stream,
+with no fixed request timeout. `speech.opened` and `speech.transcription`
+events use that request's scoped emitter, carrying `{streamId, ...metadata}`
+and `{streamId, result}` respectively. They reach only the owning connection.
+`speech.push`, `speech.endpoint`, `speech.finish`, and `speech.cancel` address
+the same stream. Client close, document retirement, transport disconnect, or
+the request signal cancels the native stream through normal Core request
+ownership. This stream is not accepted service-lifetime background work.
+
+`Arcane.speech.synthesizeStream(request, {signal, onAudio, onProgress,
+onRequest})` returns a promise for the complete native terminal metadata.
+The complete synthesis payload reaches the selected engine unchanged.
+The required `onAudio(audio)` consumer receives every ordered native PCM contribution, preserving
+its metadata; `audio.pcm` is a `Uint8Array`, interpreted using the supplied
+`format`, `channels`, and `sampleRate`. Magpie supplies signed little-endian
+16-bit mono PCM. The facade does not play audio, infer audible completion, or
+add a voice, language, speed, or output limit. The selected playback owner
+consumes this stream and owns its actual playback completion and interruption.
+Give each utterance its own signal to stop precisely that utterance without
+stopping microphone capture or unrelated synthesis.
+
+The synthesis request has no fixed timeout. Its request-scoped `speech.audio`
+events contain `{streamId, sequence, audio}`; `speech.progress` also carries the
+stream correlation. The facade serializes asynchronous callbacks and sends
+`speech.audioConsumed` for that exact stream and sequence only after `onAudio`
+completes. The native producer awaits this acknowledgement before contributing
+the next PCM chunk; the event parser remains free to handle control messages.
+Sequence and acknowledgement metadata stay outside the audio payload.
+
+Aborting the utterance signal suppresses later callback delivery and sends
+`speech.cancelSynthesis`. That scoped control releases pending audio
+acknowledgements and joins the native synthesis task. The facade keeps the
+original response pending and joins this cleanup control before settling;
+ordinary cancellation rejects with the caller's reason. Callback failure
+cancels the same owned operation and retains its complete failure together with
+any native cleanup failure. Successful completion waits for all callback
+delivery. A callback may abort its caller-owned signal, while its own completion
+must not await the same synthesis promise. A transport failure remains an error,
+not evidence of completed native cleanup. Playback completion remains with the
+selected playback owner, independently of synthesis completion.
+
+The Core transport uses base64 only for PCM framing: STT transfers exact
+Float32 bit patterns as little-endian samples, and TTS transfers the engine's
+complete PCM before decoding it back to the original sample representation.
+Routing and callbacks stay outside transcript and synthesis payloads.
+Existing file transcription, complete-audio synthesis, model loading, and
+unloading methods keep their original contracts. A selected engine without the
+requested streaming method reports `SPEECH_OPERATION_UNAVAILABLE`; the SDK
+selects no replacement engine or capture path.
+
+### Shared AI capture and playback
+
+The built-in native AI adapter advertises continuous capture only when the
+selected STT engine reports streaming support. `ai.createTranscriptionCapture`
+uses the shared microphone owner, forwards the caller's media constraints and
+actual sample rate, and preserves every ordered PCM sample. Its `onUpdate`,
+`onInterim`, and `onSegment` callbacks receive the complete recognition record
+and a second `{requestStop}` argument. A callback can call `requestStop()` and
+return; the external owner joins `capture.stop()` or `capture.done`. Do not
+await those joins or `forceEndpoint()` from their own recognition callback.
+Stop drains accepted audio and final recognition; cancel joins microphone and
+native cleanup without inventing a completed transcript. Neither action sends
+a chat turn automatically.
+
+For a selected streaming TTS engine, `ai.prepareTTSPlayback()` returns an inert
+playback descriptor. Its `play()` consumes native PCM through the existing AI
+provider lane and shared audio output. Playback stop affects only that utterance;
+the control's `released` promise joins native cleanup. Existing full-audio
+`fetchTTS()` remains available. `streamTTS(text, end, {languageCode})`,
+`prepareTTSPlayback({input, languageCode, ...})`, and
+`fetchTTS({input, languageCode, ...})` carry the caller's per-utterance language
+to the native engine separately from the unchanged text. The SDK does not infer
+language or create conversation replies. See the
+[Nemotron](native-nemotron.md) and [Magpie](native-magpie.md) engine contracts.
+
 ## Engine interface
 
 Each supplied engine implements:
@@ -115,6 +260,13 @@ Each supplied engine implements:
 - `transcribe(request, {signal, onProgress, requestId})` for STT, or
   `synthesize(request, {signal, onProgress, requestId})` for TTS. `requestId` is
   the actual Core request's control metadata, separate from the unchanged payload.
+- Optional `openStream({...options, signal, onUpdate})` for continuous STT,
+  returning `{push, forceEndpoint, finish, cancel, completion, current}`.
+  Its cancellation must settle `completion` without requiring service shutdown.
+- Optional `synthesizeStream(request, {signal, onProgress, onAudio, requestId})`
+  for streaming TTS. Each `onAudio` value contains the complete `pcm` Buffer
+  and its format metadata; the engine awaits each callback before producing the
+  next contribution and joins native cleanup before settling cancellation.
 - `close()`, cancelling and joining its native work and releasing its resources.
 
 The service forwards each complete transcription/synthesis request and result
@@ -144,6 +296,99 @@ share one shutdown promise. Actual engine cleanup failures reject with an
 releases the service's event subscriptions. New work after shutdown begins
 rejects with `CORE_CLOSING`.
 
+## Selected NeMo model acquisition
+
+`NEMO_SPEECH_MODELS`, `prepareNemotronModels`, and `prepareMagpieModels` are
+named exports from `arcane-os/local-ai/nemotron`. Importing them performs no
+network access, installation, model loading, or inference. The catalog records
+NVIDIA's selected [NeMo-Speech.cpp v0.2.0 model index](https://github.com/NVIDIA/NeMo-Speech.cpp/blob/v0.2.0/models/index.json):
+
+| Role | Complete default selection |
+|---|---|
+| `stt` | Nemotron 3.5 streaming ASR Q8_0 and Nemotron 3 Diarization Q8_0. |
+| `tts` | Magpie multilingual v2607 F16, NanoCodec 22 kHz F16 decoder, and all ten matching tokenizer/configuration/speaker-map members from the same Magpie revision. |
+
+Each role exposes `{modelId, providerId, name, members, resourcePaths}`.
+`members` contains ordered `{path, url}` file sources. TTS also exposes
+`archives`, with the upstream uncompressed `.nemo` TAR source, its selected
+transport ranges, and exact `{path, member}` tokenizer entries. The shared
+[model-assets service](model-assets.md) owns discovery, acquisition, progress,
+cancellation, persistence, and projection lifetime; these helpers do not create
+another downloader or store. Tokenizer files retain their complete original
+contents. The selected tokenizer configuration and its referenced JSON speaker
+map continue to own voice IDs.
+
+```js
+import {createNemotronRuntime, prepareNemotronModels} from 'arcane-os/local-ai/nemotron';
+import {createSpeechService} from 'arcane-os/core/speech';
+
+const stt = createNemotronRuntime({runtime, modelAssets, gpu: -1});
+const speech = createSpeechService({stt, autoLoad: false});
+// Run this only for the user's explicit model preparation action.
+const prepared = await prepareNemotronModels({
+  modelAssets,
+  workingDirectory: modelsDirectory,
+  directories: [modelsDirectory, appModelsDirectory],
+  signal,
+  onProgress: showModelProgress
+});
+try {
+  await stt.load({
+    assetProjectionId: prepared.assetProjectionId,
+    resourcePaths: prepared.resourcePaths,
+    signal
+  });
+} finally {
+  await prepared.release();
+}
+```
+
+Both preparation helpers accept `{modelAssets, workingDirectory, directories,
+id, signal, onProgress, refresh = false}`. With `directories`, they ask the
+shared owner for the first complete matching catalog selection in those roots
+before downloading. `openExisting()` borrows its original files and never
+deletes them. Incomplete selections stay visible through the owner's discovery
+results and are not mistaken for a complete model. When no complete match is
+available, the existing acquisition path prepares the complete selected set;
+its completed downloads remain reusable. Explicit `refresh: true` requests a
+fresh acquisition. The host chooses the roots: its portable native launch
+context supplies `modelsDirectory` under the resolved per-user `stateRoot` by
+default, while explicit directory overrides remain supported. An application
+may include its own `models` directory among the discovery roots.
+
+The result is `{assetProjectionId, directory, members, resourcePaths, release}`.
+`release()` is idempotent and releases preparation ownership. Each engine
+retains the projection synchronously when `load()` accepts it, so the caller
+may release its preparation after starting that load. Nemotron accepts
+`modelAssets`, `assetProjectionId`, and `resourcePaths` in its constructor and
+`assetProjectionId`/`resourcePaths` in `load()`, with roles `{model, diarization}`.
+Magpie uses `{model, codec, tokenizerConfig}`. Native file paths still work
+through the engines' existing options. Nemotron requires unloading before
+changing an active selection; its retained files are released only after
+native work and helper exit have joined. Load failures also join asset cleanup,
+and cleanup failures remain observable.
+
+`onProgress` receives ordered, awaited shared-owner phase and file-completion
+events, including reuse and ready for installed selections. Signal cancellation
+stops that preparation's work; an abort after projection creation releases it
+before rejecting. Engine load cancellation remains separate: cancelling the
+caller's wait does not cancel a shared activation; explicit engine unload/close
+owns that cancellation.
+
+The default GGUF selections are individual complete upstream files. The shared
+owner also discovers ordered GGUF shard sets and reports their missing members;
+HTTP range transfers and tokenizer TAR ranges are transport mechanisms, not
+additional model shards. A discovered shard set alone does not establish that a
+selected native engine can load that model. The engine remains the authority
+for model compatibility and actual readiness.
+
+The [upstream native runtime](https://github.com/NVIDIA/NeMo-Speech.cpp/blob/v0.2.0/docs/install.md)
+provides Windows, Linux, and macOS distributions. Model files and that runtime
+remain separate upstream assets, not vendored SDK payloads. This acquisition
+integration received source review only; no download, inference, or new platform
+execution is claimed here. See the [Nemotron](native-nemotron.md) and
+[Magpie](native-magpie.md) contracts for native preparation and execution evidence.
+
 ## Native Kokoro engine
 
 `createNativeKokoroRuntime` is the named and default export from