arcane-os 0.95.0 → 0.97.0

package/docs/reference/sdk-api.md

@@ -81,6 +81,10 @@ runtime layouts.
 | `arcane-os/ai/core-image` | Browser image lifecycle and complete PNG Blobs through an available Core service. |
 | `arcane-os/core/image` | Native image Core service with independent runtime preparation and retained model ownership. |
 | `arcane-os/core/speech` | Independent injected STT/TTS engine loading, request cancellation and joined Core service lifetime. |
+| `arcane-os/local-ai/nemotron` | Retained native streaming recognition with complete timed words and optional diarization. |
+| `arcane-os/local-ai/nemotron/build` | First-party ASR helper build against a prepared NeMo runtime. |
+| `arcane-os/local-ai/magpie` | Retained native Magpie/NanoCodec synthesis with complete audio or ordered PCM. |
+| `arcane-os/local-ai/magpie/build` | First-party TTS helper build against a prepared NeMo runtime. |
 | `arcane-os/local-ai/whisper` | Retained native Whisper model, complete recordings and joined helper lifetime. |
 | `arcane-os/local-ai/kokoro` | Retained native Kokoro synthesis using the existing ONNX/model-resource owners and a compiled phonemization/Opus helper. |
 | `arcane-os/local-ai/whisper/build` | First-party persistent helper build against selected installed Whisper headers and libraries. |
@@ -476,12 +480,26 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `KOKORO_REVISION` | constant | `arcane-os/local-ai/kokoro` | Core native speech | Selected upstream model revision |
 | `KOKORO_SAMPLE_RATE` | constant | `arcane-os/local-ai/kokoro` | Core native speech | Native PCM sample rate |
 | `KOKORO_VOICES` | constant | `arcane-os/local-ai/kokoro` | Core native speech | Complete 28-voice US/GB selection |
+| `createNemotronRuntime()` | function | `arcane-os/local-ai/nemotron` | Core native speech | Node with a matching first-party helper, selected NeMo ASR runtime and models; Windows/Linux/macOS source, Android host adaptation |
+| `NEMO_SPEECH_MODELS` | constant | `arcane-os/local-ai/nemotron` | Core native speech | Node; selected upstream model catalog, no acquisition at import |
+| `prepareNemotronModels()` | function | `arcane-os/local-ai/nemotron` | Core native speech | Node with the shared model-assets service |
+| `prepareMagpieModels()` | function | `arcane-os/local-ai/nemotron` | Core native speech | Node with the shared model-assets service |
+| `createNemotronRuntime default export` | function | `arcane-os/local-ai/nemotron` | Core native speech | Same named function |
+| `buildNemotronHelper()` | function | `arcane-os/local-ai/nemotron/build` | Core native speech | Node with CMake 3.26+, C++17 toolchain and platform-matching public NeMo ASR headers/libraries/CMake package |
+| `buildNemotronHelper default export` | function | `arcane-os/local-ai/nemotron/build` | Core native speech | Same named function |
+| `createMagpieRuntime()` | function | `arcane-os/local-ai/magpie` | Core native speech | Node with a matching first-party helper, selected NeMo TTS runtime, Magpie/tokenizer and NanoCodec assets; Windows/Linux/macOS source, Android host adaptation |
+| `createMagpieRuntime default export` | function | `arcane-os/local-ai/magpie` | Core native speech | Same named function |
+| `buildMagpieHelper()` | function | `arcane-os/local-ai/magpie/build` | Core native speech | Node with CMake 3.26+, C++17 toolchain, platform threads and matching public NeMo TTS headers/libraries/CMake package |
+| `buildMagpieHelper default export` | function | `arcane-os/local-ai/magpie/build` | Core native speech | Same named function |
 | `createWhisperRuntime()` | function | `arcane-os/local-ai/whisper` | Core native speech | Node with a prepared matching helper, runtime, decoder and selected model |
 | `createWhisperRuntime default export` | function | `arcane-os/local-ai/whisper` | Core native speech | Same retained native engine factory |
 | `buildWhisperHelper()` | function | `arcane-os/local-ai/whisper/build` | Core native speech | Node with installed CMake/C++17 toolchain and matching Whisper source/runtime |
 | `buildWhisperOpenVinoRuntime()` | function | `arcane-os/local-ai/whisper/openvino-build` | Core native speech | Windows x64 Node with installed matching Whisper/OpenVINO sources and CMake/MSVC toolchain |
 | `createSpeechService default export` | function | `arcane-os/core/speech` | Core native speech | Same shared speech service factory |
 | `prepareCoreModelAssets()` | function | `arcane-os/ai/core-model-assets` | Core model assets | Browser with complete Blob/File members and available Core service |
+| `discoverCoreModelAssets()` | function | `arcane-os/ai/core-model-assets` | Core model assets | Browser with an available model-assets Core service |
+| `openExistingCoreModelAssets()` | function | `arcane-os/ai/core-model-assets` | Core model assets | Browser with an available model-assets Core service |
+| `downloadCoreModelAssets()` | function | `arcane-os/ai/core-model-assets` | Core model assets | Browser with an available model-assets Core service |
 | `createModelAssetService()` | function | `arcane-os/core/model-assets` | Core model assets | Node Core with an application-selected working directory |
 | `createModelAssetService default export` | function | `arcane-os/core/model-assets` | Core model assets | Same native working-file service factory |
 | `createLocalAIService default export` | function | `arcane-os/core/local-ai` | Core local AI | Same native service factory |
@@ -7232,6 +7250,18 @@ no engine. The native routes of `AI.fetchTTS(payload, signal)` and
 `AI.fetchSTT(audio, signal)` forward their signals through these calls and
 normalize cancellation to `AbortError` with `ARCANE_AI_REQUEST_ABORTED`.
 
+`facade.speech.openStream(request,options)` returns
+`{streamId,ready,completion,current,push,forceEndpoint,finish,cancel}`.
+Ordered Float32 input retains the actual declared sample rate. Endpoint preserves
+stream/speaker scope and waits preceding updates; finish drains terminally.
+Do not await endpoint/finish/completion from their own update callback. Explicit
+cancel joins its native cleanup control, unlike ordinary signal cancellation.
+`synthesizeStream(request,{signal,onAudio,onProgress,onRequest})` awaits each
+complete ordered Uint8Array PCM contribution and its consumption acknowledgement,
+returns terminal metadata, and joins native cancellation. It plays no audio.
+Both streaming operations have no fixed timeout. Engine support/readiness remains
+independent from facade availability. See [streaming native speech](core-client.md#streaming-native-speech).
+
 `facade.window.state({signal}?)` reads the calling document's native window;
 `facade.window.setState({state}, {signal}?)` selects `normal`, `maximized` or
 `fullscreen` for that same window. The matching Windows host returns
@@ -7899,7 +7929,12 @@ reports `ARCANE_NATIVE_RUN_UNSUPPORTED`.
 
 `build()` copies the complete selected app and dependency releases, the
 published SDK/runtime dependencies and the canonical Core entry/client into a
-fresh output directory. Service factories are imported only when a real native
+temporary assembly, then publishes it at `<outputRoot>/<app-id>/`. Later
+successful builds replace only that app's generated output. Publication retains
+the previous output until the completion callback and cancellation boundary
+accept the replacement; failure restores it. Models and saved state belong in
+their separate persistent directories. See [stable output and recovery](core-native-packaging.md#output-and-host-contract).
+Service factories are imported only when a real native
 host later launches the generated Core entry, never during packaging.
 
 The generated `runtime/arcane-core.mjs` also accepts
@@ -8039,6 +8074,11 @@ the selected output root. There is no compiler or OS checkout requirement for
 application builds. The build machine needs its normal Node/npm toolchain and
 `tar`; execution needs Windows x64, .NET Framework 4.6.2 or later and WebView2.
 
+Successful builds publish the complete payload at `<outputRoot>/<app-id>/`,
+replacing that app's prior generated artifact through the same
+[joined publication lifecycle](core-native-packaging.md#output-and-host-contract).
+Runtime caches, models, saved profiles and unrelated outputs remain separate.
+
 The matching Windows host consumes `appDescriptor.native.window` through
 `manifest.window`. Optional `width` and `height` select initial client dimensions
 in 96-DPI logical units; the host scales them for its actual DPI and fits the
@@ -8134,6 +8174,9 @@ asset is published or its Mac runtime has been executed.
 
 Build preserves the complete portable payload inside the bundle's Resources
 directory (`target.rootDir`) and returns its `.app` location as `bundleRoot`.
+The accepted bundle is `<outputRoot>/<app-id>.app/`; a later successful build
+replaces that bundle through the shared [publication lifecycle](core-native-packaging.md#output-and-host-contract),
+preserving separate saved state and model directories.
 The bundle supplies the SDK launcher and selected Node runtime. `verify()`
 reads assembled files; `run()` directly launches the bundled executable only on
 the matching Darwin architecture, observes diagnostics and waits for graceful
@@ -8297,8 +8340,9 @@ import createDiarizationService from 'arcane-os/core/diarization';
 
 ### Overview
 
-Resolves one application's native state, workspace and optional shared endpoint
-through the same public owner used by its packaged executable and external MCP.
+Resolves one application's native state, workspace and optional shared endpoint,
+plus a same-user shared model directory, through the same public owner used by
+its packaged executable and external MCP.
 This synchronous function performs no I/O, saved-state discovery, process start
 or migration.
 
@@ -8309,7 +8353,7 @@ resolveNativeLaunchContext({appId,context={}}={})
 ```
 
 Import from `arcane-os/core/host`. The result is a new complete context with
-omitted fields filled. Windows defaults to `%LOCALAPPDATA%/Arcane/<appId>`
+omitted fields filled. `stateRoot` defaults on Windows to `%LOCALAPPDATA%/Arcane/<appId>`
 (home `AppData/Local` fallback), macOS to
 `~/Library/Application Support/Arcane/<appId>`, and portable Linux Node to
 absolute `$XDG_DATA_HOME/Arcane/<appId>` or `~/.local/share/Arcane/<appId>`.
@@ -8317,6 +8361,21 @@ Android and other adapted hosts provide their actual `stateRoot` and own native
 IPC/process adaptation.
 
 An omitted `workspaceRoot` becomes `<absolute selected stateRoot>/Workspace`.
+An omitted `modelsDirectory` uses the operating-system user's shared Arcane
+model directory: `%LOCALAPPDATA%/Arcane/Models` on Windows (home `AppData/Local`
+fallback), `~/Library/Application Support/Arcane/Models` on macOS, and absolute
+`$XDG_DATA_HOME/Arcane/Models` or `~/.local/share/Arcane/Models` on Linux. This
+default remains shared when the application explicitly selects another
+`stateRoot`; application state and workspace stay separate. Explicit
+`modelsDirectory` values remain unchanged. Other adapted hosts may supply a
+shared directory explicitly; their omitted value remains
+`<absolute selected stateRoot>/Models`.
+
+This resolver supplies a location to its consumers; it neither changes every
+provider's store nor creates, moves or migrates model files. Services select
+that directory as the shared model-assets working directory, while applications
+may also discover their existing app-local originals. Model storage remains
+separate from replaceable native build output. See [persistent model locations](model-assets.md).
 Only a selected `sharedHost` object receives a default endpoint and log file:
 Windows uses a named pipe containing the URL-encoded complete absolute state
 path; Linux/macOS use `<absolute selected stateRoot>/core.sock`. The log is
@@ -8643,7 +8702,7 @@ separate states; prompts, models and application policy remain caller-owned.
 ### Signature and result
 
 ```text
-createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent,prepare,executionDevices}={})
+createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent,prepare,executionDevices,autoStart=true}={})
 ```
 
 Import it from `arcane-os/core/local-ai`. `configuration` is the authored local-AI
@@ -8667,6 +8726,16 @@ asset services keep their own lifetimes. Pass only llama.cpp/Ollama/ONNX
 requirements to this factory; `createLocalImageService()` owns selected image
 requirements. The managed development and native entrypoints separate them.
 
+`autoStart:false` leaves these selected engines unprepared and unstarted during
+Core startup. Call `client.invoke('localai.prepare', {}, {signal})` when the
+application explicitly requests preparation. The operation invokes the
+configured `prepare` owner, emits its complete events as `localai.preparation`,
+starts configured engines and returns current state. Concurrent callers share
+in-flight preparation; completed preparation is reused. Engine/model readiness
+remains separate, so this result alone does not establish inference readiness.
+The default `autoStart:true` preserves startup preparation. No model is selected
+by this option.
+
 The service provides `localai.status`, explicit `localai.services.recover`,
 `llama.status/models/load/unload/chat`, `onnx.status/load/run/unload`, and the documented native Ollama methods.
 `localai.state` reports runtime/model changes. `llama.status` and `llama.models`
@@ -8961,6 +9030,272 @@ US/GB voice identifiers. The engine uses `af_heart` when the caller omits
 `voice`; an explicit unsupported selection reports an error. Use this complete
 array to populate a native Kokoro voice selector.
 
+## createNemotronRuntime()
+
+### Overview and syntax
+
+Creates one retained native recognizer and optional diarizer without opening a
+microphone, loading a model or starting inference at construction.
+
+```javascript
+createNemotronRuntime({
+    runtime, prepare, modelId = 'nemotron-3.5-asr-streaming-0.6b',
+    modelPath, diarizationModelPath, modelAssets, assetProjectionId,
+    resourcePaths, gpu, onEvent
+} = {})
+```
+
+Supply a prepared `runtime` or lazy `prepare({signal,onEvent})` descriptor
+with `helperExecutable` and selected native library paths. Select `gpu`
+explicitly (native ordinal, or `-1` for CPU). Model paths may come from the
+descriptor; omit the diarization path when speaker labels are not requested.
+Preparation, models and device selection remain caller-owned.
+
+Alternatively supply the existing `modelAssets` service and a completed
+`assetProjectionId`, with `resourcePaths:{model,diarization?}` naming exact
+projection members. `load()` retains that projection before yielding and keeps
+it through actual helper cleanup; the caller can release preparation ownership
+after loading begins. Explicit load accepts these selection fields, and an
+active selection must be unloaded before replacement. Direct paths remain
+supported. See [shared catalog preparation](#preparenemotronmodels).
+
+### Returned members and lifetime
+
+The engine exposes `current/subscribe/load/unload/transcribe/openStream/close`.
+Current state and replaying subscriptions report actual loaded readiness,
+native version, requested device, active speaker scope, error and reset state.
+`load` initializes the selection; `unload` and `close` join owned cleanup.
+
+`openStream({sampleRate=16000,languageCode,model,onUpdate,signal})` resolves an
+owned `push/forceEndpoint/finish/cancel/completion/current` handle plus
+`sampleRate` and `speakerScope`. Feed mono `Float32Array` or
+`{encoding:'f32le',data:BASE64}` at the actual declared rate. The native sample
+rate contract accepts integer 8000–96000 or 0 for model rate. No encoded-media
+decoder is supplied. Updates preserve every alternative, text, word, timestamp,
+numeric speaker and final/provisional status.
+
+`forceEndpoint` drains an utterance while retaining stream and speaker scope;
+`finish` terminally drains accepted input. Partial snapshots replace; finals
+remain separate recognition segments, never inferred conversational completion.
+`transcribe({audio,sampleRate,model?,languageCode?},options)` uses this same
+stream and returns complete `{text,words,results,speakerScope}`.
+
+Cancellation joins native and callback cleanup. Terminating genuinely
+noninterruptible helper work exposes `resetRequired` and requires explicit
+reload; no engine restarts silently. Callbacks must return before joining their
+own stream/engine lifecycle, otherwise `NEMOTRON_CALLBACK_WAIT` is reported.
+Unsupported input reports `NEMOTRON_AUDIO_FORMAT_UNSUPPORTED`; native, callback
+and cleanup failures remain observable.
+
+### Availability and example
+
+Node on Windows, Linux and macOS with the first-party helper and matching
+upstream NeMo ASR runtime/models; Android requires host adaptation. Selected
+Windows helper compilation is recorded in the [engine guide](native-nemotron.md);
+that is separate from inference, microphone or other-platform execution.
+
+```javascript
+import {createNemotronRuntime} from 'arcane-os/local-ai/nemotron';
+
+function prepareDragonInterpreter(runtime, modelPath, gpu) {
+    return createNemotronRuntime({runtime, modelPath, gpu});
+}
+// The native owner explicitly loads, supplies PCM and joins close.
+```
+
+See [native Nemotron](native-nemotron.md) for complete options, snapshots,
+callback rules and cancellation/reset outcomes.
+
+## createNemotronRuntime default export
+
+The default export from `arcane-os/local-ai/nemotron` is the same
+`createNemotronRuntime` function, with identical inputs, results and lifetime.
+
+## `NEMO_SPEECH_MODELS`
+
+Import this catalog from `arcane-os/local-ai/nemotron`. `stt` describes the
+selected Nemotron ASR and diarization GGUF companions; `tts` describes Magpie,
+NanoCodec and the matching ten tokenizer/configuration members. Each selection
+contains `modelId`, `providerId`, `name`, ordinary `members`, `resourcePaths`
+and optional `archives`. The upstream selections come from NVIDIA's
+NeMo-Speech.cpp 0.2.0 catalog. Importing the catalog performs no I/O and installs
+no runtime or model. See [the exact companion contract](native-speech.md#selected-nemo-model-acquisition).
+
+## prepareNemotronModels()
+
+```text
+prepareNemotronModels({modelAssets,workingDirectory,directories,id,signal,onProgress,refresh=false}={})
+```
+
+Import from `arcane-os/local-ai/nemotron`. Explicitly prepares the catalog's
+complete ASR and diarization selection through the existing model-assets
+service. Optional `directories` are searched first when `refresh` is false;
+the first complete matching catalog record is opened without downloading.
+Otherwise the shared `prepare` owner acquires the complete selection beneath
+`workingDirectory/model-assets/`. `refresh:true` requests a separate acquisition.
+
+The promise resolves to `{assetProjectionId,directory,members,resourcePaths,release}`.
+An omitted `id` is generated. Ordered asynchronous `onProgress` receives full
+file-based semantic progress; existing selections report `reuse` then `ready`.
+Native acquisition additionally reports its shared resume, ownership-wait,
+activity and terminal states described under [`createModelAssetService()`](#createmodelassetservice).
+Completed members and saved partial transfers remain available for retry;
+HTTP continuation depends on the source response. Direct installed-directory
+reuse keeps its existing phase/file-count callback shape.
+Call the idempotent asynchronous `release()` to relinquish preparation ownership
+after the engine has retained it. Complete acquisitions and borrowed originals
+remain stored. Cancellation and callback failures join cleanup and preserve
+actual failures. The wrapper selects no device, installs no native runtime and
+starts no microphone or inference. See [native model acquisition](native-speech.md#selected-nemo-model-acquisition).
+
+## prepareMagpieModels()
+
+```text
+prepareMagpieModels({modelAssets,workingDirectory,directories,id,signal,onProgress,refresh=false}={})
+```
+
+Import from `arcane-os/local-ai/nemotron`. It has the same preparation,
+discovery, progress, cancellation and release contract as `prepareNemotronModels`,
+using the catalog's complete Magpie/NanoCodec/tokenizer selection. Its returned
+`resourcePaths` contains `model`, `codec` and `tokenizerConfig`. The shared TAR
+reader extracts the ten selected tokenizer members from the catalog's selected
+upstream archive ranges; offsets stay transport-local. Pass the completed
+projection to the existing Magpie engine. Voice, language and device selection
+remain caller-owned; preparation performs no synthesis.
+
+## buildNemotronHelper()
+
+### Overview and syntax
+
+`buildNemotronHelper({runtime,outputRoot,signal,onEvent}={})` configures, builds
+and installs only the first-party Nemotron helper. `runtime.cmakeDirectory`
+selects an installed NeMo CMake package with its matching public ASR headers and
+libraries; `outputRoot` is the caller-owned output directory.
+
+### Result, availability and example
+
+Returns `{platform,architecture,root,helperExecutable,executable,diagnostics}`;
+`executable` aliases `helperExecutable`, and diagnostics retains complete
+configure/compile/install results. Requires Node, CMake 3.26+, a C++17 compiler
+and matching platform runtime. It downloads no dependency or model and performs
+no inference. Cancellation and process failures remain observable.
+
+```javascript
+import {buildNemotronHelper} from 'arcane-os/local-ai/nemotron/build';
+
+async function buildSelectedRecognizer(runtime, outputRoot, signal, onEvent) {
+    return buildNemotronHelper({runtime, outputRoot, signal, onEvent});
+}
+```
+
+See [preparation and selection](native-nemotron.md#preparation-and-selection).
+
+## buildNemotronHelper default export
+
+The default export from `arcane-os/local-ai/nemotron/build` is the same
+`buildNemotronHelper` function.
+
+## createMagpieRuntime()
+
+### Overview and syntax
+
+Creates one retained native Magpie/NanoCodec synthesis owner. Construction
+downloads, loads and plays nothing.
+
+```javascript
+createMagpieRuntime({
+    runtime, prepare, paths, modelAssets, assetProjectionId, resourcePaths,
+    modelId = 'magpie', voice = 'Aria', languageCode = 'en-US',
+    executionTarget, signal, onEvent
+} = {})
+```
+
+Supply a prepared executable/library descriptor or `prepare({signal})`.
+Select matching Magpie, NanoCodec and tokenizer `paths`, or an existing
+model-assets projection and `resourcePaths`. Explicit `executionTarget`
+selects CPU or CUDA with the host's visible device/UUID; no provider or device
+fallback is inferred. The tokenizer's own speaker map determines voice IDs.
+
+### Returned members and lifetime
+
+The engine exposes `current/subscribe/load/unload/synthesize/synthesizeStream/stop/close`.
+State includes independent loaded readiness, active/queued requests, voice and
+language defaults, model-owned voices and streaming/format capability.
+`load` retains selected models; `unload` and `close` join owned work/assets.
+
+Both synthesis methods accept exact `{input,model?,voice?,languageCode?,speed?}`;
+language is separate control information, and native speed must be 1.
+`synthesize(request,{signal,requestId,onProgress})` returns complete base64
+WAV (default) or PCM audio, MIME/format and speech metadata. Select
+`responseFormat:'pcm'` explicitly when needed.
+`synthesizeStream(request,{signal,requestId,onProgress,onAudio})` requires an
+awaited ordered `onAudio({pcm,format,sampleRate,channels,requestId})` callback.
+PCM is a Node Buffer of signed 16-bit little-endian samples; terminal metadata
+has `complete:true` without retaining the complete audio again. Playback
+belongs to the caller.
+
+Requests retain FIFO ownership. `stop({requestId})` stops only that queued or
+active utterance and joins native/callback cleanup; cancellation rejects
+synthesis. In-flight native interruption is observed at a PCM callback boundary.
+A callback can abort its caller-owned signal and return; self-joining lifecycle
+calls reject `MAGPIE_CALLBACK_WAIT`. Complete native and cleanup errors remain
+observable. An interrupted request never returns fabricated complete audio.
+
+### Availability and example
+
+Node on Windows, Linux and macOS with a matching helper, upstream NeMo TTS
+runtime and selected model assets; Android needs host adaptation. The
+[engine guide](native-magpie.md) separates selected Windows compilation from
+unverified inference, playback and other-platform execution.
+
+```javascript
+import {createMagpieRuntime} from 'arcane-os/local-ai/magpie';
+
+function prepareDragonAnnouncer(runtime, paths, executionTarget) {
+    return createMagpieRuntime({runtime, paths, executionTarget});
+}
+// The native owner loads explicitly; synthesis returns audio, not playback.
+```
+
+See [native Magpie](native-magpie.md) for complete selection, language, voices,
+callback constraints and request lifetime.
+
+## createMagpieRuntime default export
+
+The default export from `arcane-os/local-ai/magpie` is the same
+`createMagpieRuntime` function, with identical inputs, results and lifetime.
+
+## buildMagpieHelper()
+
+### Overview and syntax
+
+`buildMagpieHelper({runtime,outputRoot,signal,onEvent}={})` configures, builds
+and installs the first-party Magpie helper against the caller's installed
+`runtime.cmakeDirectory`, public NeMo TTS headers and matching libraries.
+
+### Result, availability and example
+
+Returns `{platform,architecture,root,helperExecutable,diagnostics}`, preserving
+complete configure/compile/install results. Requires Node, CMake 3.26+, C++17,
+platform threads and matching NeMo libraries. `outputRoot` belongs to the
+caller. It downloads no dependency, model or voice and performs no inference.
+Cancellation and process failures remain observable.
+
+```javascript
+import {buildMagpieHelper} from 'arcane-os/local-ai/magpie/build';
+
+async function buildSelectedAnnouncer(runtime, outputRoot, signal, onEvent) {
+    return buildMagpieHelper({runtime, outputRoot, signal, onEvent});
+}
+```
+
+See [helper build prerequisites](native-magpie.md#build-the-first-party-helper).
+
+## buildMagpieHelper default export
+
+The default export from `arcane-os/local-ai/magpie/build` is the same
+`buildMagpieHelper` function.
+
 ## createWhisperRuntime()
 
 ### Overview
@@ -9091,7 +9426,7 @@ through `encoder: 'openvino-npu'`; they do not run this producer at startup.
 
 ### Overview and usage
 
-`createSpeechService({stt,tts,signal}={})` from `arcane-os/core/speech` composes
+`createSpeechService({stt,tts,signal,autoLoad=true}={})` from `arcane-os/core/speech` composes
 independently selected STT and TTS engines as one Core service. Supply either
 role or both. Construction downloads, installs and loads nothing; the host
 owns engine creation, model/device selection and supported formats.
@@ -9114,6 +9449,18 @@ requests and results unchanged. Format decoding, model processing and encoding
 remain with that engine. This factory supplies no speech engine or automatic
 browser/native provider selection.
 
+Optional engine `openStream({...options,signal,onUpdate})` supplies continuous
+recognition; optional `synthesizeStream(request,{signal,onProgress,onAudio,requestId})`
+supplies awaited ordered PCM output. Each role reports `supportsStreaming`
+independently from loaded readiness. The Core streaming methods are
+`speech.open`, `push`, `endpoint`, `finish`, `cancel`, `synthesizeStream`,
+`audioConsumed` and `cancelSynthesis` (each under `speech.`). Request-scoped
+`speech.opened`, `speech.transcription` and `speech.audio` events retain stream
+ownership; TTS acknowledgements apply backpressure while control traffic continues.
+Endpoint drains an utterance without closing its stream; finish closes terminally.
+ASR finals are recognition segments, not conversational decisions. Cancellation
+joins the selected engine's native work. See the [complete streaming contract](native-speech.md#continuous-transcription-and-streaming-synthesis).
+
 ### Members, results and events
 
 The returned object has `name: 'speech'`, `current`, `subscribe`, `close`,
@@ -9122,6 +9469,9 @@ The returned object has `name: 'speech'`, `current`, `subscribe`, `close`,
 - `start(context)` subscribes and starts both configured engine loads
   independently, returning immediately. Core and status remain responsive
   during loading; one role's failure leaves the other usable.
+  With `autoLoad:false`, subscriptions and role capabilities remain available
+  while startup requests no engine load. Explicit `speech.load` activates
+  the selected role. The default preserves automatic startup loading.
 - `current()` and `methods['speech.status']()` return the same snapshot:
   `ready`, `transcriptionAvailable`, `synthesisAvailable`, `status`,
   `sttEngine`, `ttsEngine`, `roles.stt`, `roles.tts` and `closed`.
@@ -9170,10 +9520,12 @@ their operation with `SPEECH_ENGINE_UNAVAILABLE`; work after shutdown begins
 rejects with `CORE_CLOSING`. Engine errors remain observable, and engine cleanup
 failures reject shutdown with `AggregateError`. Asynchronous listener failures
 reach developer diagnostics. Engine platform support remains its own contract;
-this Node composition layer adds no engine dependency. Existing AI readiness
-consumers recognize `whisper.cpp` and `kokoro-onnx` IDs independently of the
-service's engine-neutral interface. See the [complete engine and lifetime
-contract](native-speech.md).
+this Node composition layer adds no engine dependency. The shared AI adapter
+follows the selected model and engine in per-role snapshots, including Nemotron
+and Magpie. Only its older aggregate-only fallback retains fixed
+`whisper.cpp`/`whisper-small` and `kokoro-onnx`/`kokoro` expectations.
+Unavailable streaming operations reject `SPEECH_OPERATION_UNAVAILABLE` without
+fallback. See the [complete engine and lifetime contract](native-speech.md).
 
 ## createSpeechService default export
 
@@ -9200,24 +9552,82 @@ engine. See [complete preparation and cleanup usage](model-assets.md).
 
 `createModelAssetService({appRoot=process.cwd()}={})` from
 `arcane-os/core/model-assets` returns the Core service for
-`modelAssets.open/write/complete/release/status` and `modelAssets.state`.
+`modelAssets.open/write/complete/release/status`,
+`modelAssets.discover/openExisting/prepare/cancelPrepare`, and `modelAssets.state`.
 Relative working directories resolve from `appRoot`; explicit absolute
 directories remain caller-selected. Each projection has its own child
 directory and complete member files.
 
 `current()` returns `{closing,projections}`. `retain(id)` accepts a completed
 projection and returns `{id,directory,members,release}` for a native owner.
-Native `prepare({id,workingDirectory,members,signal,onProgress,refresh=false})`
-accepts ordered `{path,url}` members and returns their ready projection.
+Native `prepare({id,workingDirectory,members=[],archives=[],signal,onProgress,refresh=false})`
+accepts ordered `{path,url}` members and optional uncompressed TAR selections,
+returning their complete ready projection. An archive declares
+`{url,format:'tar',ranges?,members:[{path,member}]}`. Optional inclusive
+`{start,end,stopBefore?}` ranges use HTTP partial responses; the parser handles
+ordinary and PAX member paths and preserves each selected file completely.
+All declared companions must finish before readiness. Range framing stays
+transport-local.
 Complete native acquisitions persist beneath `workingDirectory/model-assets/`
 through unload, disposal and restart; ordinary calls reuse the exact complete
 ordered source selection without a network freshness check. Explicit
 `refresh:true` acquires a separate complete set without replacing active files.
-Independent members transfer concurrently and progress reports phases and
-completed files. Matching same-process preparations share acquisition with
-independent callbacks and cancellation; the last interested cancellation joins
-unfinished I/O and removes only that attempt. Separate processes may acquire
-the same selection independently. Startup downloads nothing.
+Independent members transfer concurrently. Interrupted or cancelled acquisitions
+retain completed members and closed partial files for retry. A retry reuses the
+same recorded attempt and downloads only missing members. Ordinary-file HTTP
+continuation uses its retained strong ETag or Last-Modified validator with
+`Range` and `If-Range`; a matching `206` response appends. A full `200`, `416`,
+missing validator or prior encoded response restarts only that member and
+reports `restart`. One prior partial remains until its replacement completes.
+TAR selections replay the required segment framing while preserving already
+completed companions. HTTP framing remains internal to the transfer, not
+model identity or user-facing progress.
+
+Matching same-process preparations share acquisition with independent callbacks
+and cancellation; cancelling one interested caller leaves the others running.
+The last interested cancellation joins I/O while retaining resumable data.
+Matching selections in separate processes coordinate their recorded transfer
+owner, report `waiting`, then reuse or resume after that owner releases or exits.
+Unrelated acquisitions remain concurrent. Member completion follows stream/file
+closure and promotion; whole-acquisition readiness follows all selected members.
+Startup downloads nothing, and retry remains an explicit preparation request.
+
+Native acquisition progress is
+`{phase,state,message,completed,total,unit:'files',memberIndex?,path?,reason?,recovery?,error?,activity?}`.
+Phases are `open`, `download`, `reuse`, `resume`, `restart`, `complete`, `ready`,
+`waiting`, `heartbeat`, `stalled`, `interrupted`, `cancelled` and `failed`.
+States are `waiting`, `downloading`, `stalled`, `interrupted`, `cancelled`,
+`failed` and `ready`. A five-second heartbeat keeps active work observable;
+`stalled` means no source activity arrived for fifteen seconds, not a diagnosed
+outage. Waiting may include the other owner's observed `activity`. Plain
+`message` and `recovery` belong in ordinary status; complete `error` details
+remain diagnostic data. Progress uses phases and completed-file counts, not
+invented percentages. Terminal acquisition state does not imply that a
+cancelled subscriber receives callbacks after its cancellation boundary.
+
+`discover({directories,catalog=[],recursive=true,signal})` reads only explicit
+installed directories and returns `{directories,models}`. Directory observations
+contain `{directory,exists,error?}`. Each model record has
+`{directory,entryPath,members:[{path,nativePath,available}],missingMembers,complete,source,catalogId?}`.
+The source is `directory`, `catalog` or `acquisition`. Split GGUF filename sets
+are one numerically ordered selection, including missing expected shards and
+the first shard as entry. This grouping also applies to completed acquisitions;
+all declared companions remain present. Ordinary readable symlinked files and
+directories are followed, with real-path cycle detection.
+
+Catalog entries `{id,members,archives?,entryPath?}` declare exact companion sets.
+Acquisition-backed matching honors supplied source URLs and archive member
+names; path-only catalogs and ordinary directory discovery make no origin or
+runtime-readiness claim. No files are downloaded, loaded or moved by discovery.
+
+`openExisting({id,directory,members:[{path}],signal})` opens a complete borrowed
+projection using those existing files. Missing members reject with
+`MODEL_ASSET_MEMBERS_MISSING` and the complete missing-member list. Release
+never deletes or copies borrowed originals. The three new operations also have
+matching Core RPC methods. Request-scoped `modelAssets.progress` carries
+`{id,progress}` with full file-based semantic progress; `cancelPrepare` aborts
+and joins actual acquisition cleanup. The browser helpers below preserve the
+request correlation and cancellation joins.
 `release(id)` relinquishes live preparation ownership. Native retains continue
 through actual engine release; completed native acquisitions remain stored.
 Browser `open/write/complete` projections retain their temporary lifetime and
@@ -9229,6 +9639,53 @@ handle only after its actual context/worker use ends. Original stored model
 files remain with their application owner. See
 [working-file service and wire operations](model-assets.md#native-ownership).
 
+## discoverCoreModelAssets()
+
+```text
+discoverCoreModelAssets({client=getInstalledCoreClient(),directories,catalog,recursive,signal}={})
+```
+
+Import from `arcane-os/ai/core-model-assets`. Resolves the native `discover`
+result described above through the installed Core connection. Directories and
+catalog selections remain application-owned. Complete shard and companion
+availability is filesystem evidence, not a selected or loaded model. See
+[discovery records](model-assets.md).
+
+## openExistingCoreModelAssets()
+
+```text
+openExistingCoreModelAssets({client=getInstalledCoreClient(),directory,members,signal}={})
+```
+
+Import from `arcane-os/ai/core-model-assets`. Opens selected complete existing
+files through Core and returns `{id,directory,members,release}`. The helper
+generates its projection ID; `release()` is asynchronous and idempotent.
+Native engines retain their own use; borrowed original files remain intact.
+Cancellation joins uncancelled cleanup before rejecting.
+
+## downloadCoreModelAssets()
+
+```text
+downloadCoreModelAssets({client=getInstalledCoreClient(),workingDirectory,members,archives,refresh=false,signal,onProgress}={})
+```
+
+Import from `arcane-os/ai/core-model-assets`. Explicitly invokes native
+acquisition for complete ordinary and optional TAR-selected members and returns
+`{id,directory,members,release}`. It generates the ID, observes only that request's
+complete progress, and awaits asynchronous callbacks in order. Cancellation or
+a callback failure joins native `cancelPrepare` cleanup and local callback
+delivery before settlement; actual cleanup failures remain observable.
+When Core rejects preparation, the helper first delivers already queued
+terminal progress before its internal cleanup cancellation and rejection.
+Explicit caller cancellation retains its no-late-callback boundary.
+Release relinquishes preparation ownership while completed downloads remain
+stored. Interrupted/cancelled native transfers retain completed members and
+saved partials for an explicit retry; the shared owner's HTTP continuation and
+member-restart rules apply. Progress forwards its full ownership-wait,
+heartbeat/stall and terminal records without inventing completion. No model,
+runtime or device is selected implicitly. See
+[download and progress usage](model-assets.md).
+
 ## createModelAssetService default export
 
 The default export from `arcane-os/core/model-assets` is the same