arcane-os 0.95.0 → 0.96.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.96.0
+
+- Publish successful portable, Windows and macOS native builds to one stable
+  app-specific output directory. Assemble separately and retain the previous
+  output through promotion, callback acceptance and recoverable rollback;
+  keep model caches and user profiles outside replacement.
+- Add persistent native model acquisition and installed-model discovery through
+  the shared Core model-assets owner. Preserve complete split GGUF sets and
+  companion files, stream selected TAR members, report file-based progress,
+  and join cancellation and cleanup while retaining completed originals.
+- Expose upstream Nemotron/diarization and Magpie/NanoCodec model selections
+  through the existing native speech API. Nemotron retains selected resource
+  projections until its owned helper closes; no model or runtime redistribution
+  is added.
+- Add explicit native language-model startup and an app-scoped Models directory.
+  Preserve existing automatic startup defaults and ordinary speech APIs.
+  Package delivery remains distinct from native inference or app acceptance.
+
 ## 0.95.0
 
 - Add retained native Nemotron streaming recognition and optional diarization,

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.95.0` SDK contract. Development applications declare
+This checkout defines the `0.96.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/ai/core-model-assets.mjs

@@ -3,6 +3,80 @@ import {getInstalledCoreClient} from '../core/client.mjs';
 
 const is = new Is(false);
 
+/** Inspect selected native directories without downloading or loading a model. */
+export function discoverCoreModelAssets({client = getInstalledCoreClient(), directories, catalog, recursive, signal} = {}) {
+    requireCore(client);
+    return client.invoke('modelAssets.discover', {directories, catalog, recursive}, {signal, timeoutMs: 0});
+}
+
+/** Retain existing complete files without copying them into an application build. */
+export function openExistingCoreModelAssets({client = getInstalledCoreClient(), directory, members, signal} = {}) {
+    return prepareNativeProjection(client, 'modelAssets.openExisting', {directory, members}, {signal});
+}
+
+/** Explicitly download a selected complete native model and its companions. */
+export function downloadCoreModelAssets({
+    client = getInstalledCoreClient(), workingDirectory, members, archives, refresh = false, signal, onProgress
+} = {}) {
+    return prepareNativeProjection(client, 'modelAssets.prepare', {workingDirectory, members, archives, refresh}, {signal, onProgress});
+}
+
+function requireCore(client) {
+    if (!is.function(client?.invoke)) {
+        const error = new Error('Native model assets require an available Core connection.');
+        error.code = 'ARCANE_MODEL_ASSETS_CORE_UNAVAILABLE';
+        throw error;
+    }
+}
+
+async function prepareNativeProjection(client, method, params, {signal, onProgress}) {
+    requireCore(client);
+    if (!is.function(client.uuid)) throw new TypeError('Model asset preparation requires Core operation ids.');
+    if (onProgress !== undefined && !is.function(onProgress)) throw new TypeError('Model asset onProgress must be a function.');
+    if (onProgress && !is.function(client.events?.on)) throw new TypeError('Model asset progress requires Core events.');
+    const id = client.uuid();
+    const controller = new AbortController();
+    const operationSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+    operationSignal.throwIfAborted();
+    let delivery = Promise.resolve();
+    let callbackFailure;
+    let releaseTask;
+    const unsubscribe = onProgress ? client.events.on('modelAssets.progress', function receiveProgress(event) {
+        if (event?.id !== id || operationSignal.aborted) return;
+        delivery = delivery.then(function orderedProgress() {
+            if (!operationSignal.aborted) return onProgress(event.progress);
+        });
+        delivery.catch(function failedProgress(error) {
+            callbackFailure ??= error;
+            controller.abort(error);
+        });
+    }) : undefined;
+
+    function release() {
+        releaseTask ??= client.invoke('modelAssets.release', {id}, {timeoutMs: 0});
+        return releaseTask;
+    }
+
+    try {
+        const projection = await client.invoke(method, {id, ...params}, {signal: operationSignal, timeoutMs: 0});
+        await delivery;
+        operationSignal.throwIfAborted();
+        return {id, directory: projection.directory, members: projection.members, release};
+    } catch (error) {
+        const reason = callbackFailure ?? (error?.code === 'ARCANE_REQUEST_ABORTED' && operationSignal.aborted ? operationSignal.reason : error);
+        controller.abort(reason);
+        const errors = [reason];
+        try {
+            if (method === 'modelAssets.prepare') await client.invoke('modelAssets.cancelPrepare', {id}, {timeoutMs: 0});
+            else await release();
+        } catch (cleanupError) { if (!errors.includes(cleanupError)) errors.push(cleanupError); }
+        try { await delivery; }
+        catch (deliveryError) { if (!errors.includes(deliveryError)) errors.push(deliveryError); }
+        if (errors.length > 1) throw new AggregateError(errors, 'Native model preparation and cleanup failed.', {cause: reason});
+        throw reason;
+    } finally { unsubscribe?.(); }
+}
+
 /** Projects complete caller-owned assets through Core without changing their store. */
 export async function prepareCoreModelAssets({
     client = getInstalledCoreClient(), workingDirectory, members, signal, onProgress

package/docs/reference/README.md

@@ -76,6 +76,9 @@ alone does not make bare module names resolve in a browser.
 | Select FLUX.2 Klein 4B and its three complementary model resources | [FLUX.2 Klein 4B through Core](local-image-flux.md) |
 | Select the complete SDXL Base 1.0 checkpoint for generation and whole-image editing | [SDXL Base 1.0 through Core](local-image-sdxl.md) |
 | Compose independently loaded transcription and synthesis engines | [Native speech service](native-speech.md) |
+| Stream complete native recognition with retained speaker scope | [Native Nemotron](native-nemotron.md) and [Core speech streaming](native-speech.md#continuous-transcription-and-streaming-synthesis) |
+| Produce native PCM speech with selected voice and language | [Native Magpie](native-magpie.md) |
+| Capture and play native speech through shared AI controls | [Shared AI capture and playback](native-speech.md#shared-ai-capture-and-playback) |
 | Keep a native Whisper model loaded across complete recordings | [Native Whisper transcription](local-whisper.md) |
 | Select the optional Intel NPU encoder with independent CUDA or CPU decoding | [Intel NPU Whisper](../guides/native-whisper-openvino.md) |
 | Edit an original PNG with a complete prompt and explicit strength | [Local image editing](local-image-editing.md) |
@@ -243,6 +246,12 @@ what those artifacts let a developer do.
 
 ## Normalized AI
 
+A speech-only interface explicitly passes `null` for both the first and fourth
+`AI` constructor arguments:
+`new AI(null, 'LOCAL_SPEACH', 'LOCAL_SPEACH', null, ttsModel, sttModel)`.
+This leaves the LLM unselected from construction; omitted or empty arguments
+retain their historical defaults. See [native speech startup](native-speech.md#startup-and-status).
+
 Portable applications start with the provider-neutral runtime rather than an
 Ollama, Wllama, Whisper, Kokoro, native, or cloud transport:
 

package/docs/reference/ai/browser-speech.md

@@ -233,6 +233,53 @@ Choose preparation according to the result the application needs:
 | `ai.fetchTTS(payload,signal)` | Promise resolving a real audio Blob | Audio-file providers only; does not play |
 | `ai.prepareTTS(options)` | Preparation handle with `ready` and `getAudio(index)` | Audio-file providers only; optional caller-owned durable storage |
 
+## Native Core streaming speech
+
+The shared AI controls also consume an explicitly selected native Core speech
+service. [Nemotron](../native-nemotron.md) supplies retained streaming recognition
+and optional diarization; [Magpie](../native-magpie.md) supplies streamed PCM and
+complete WAV/PCM audio. These are separate from browser Web Speech voices:
+Magpie can export audio, whereas the browser-native synthesis provider exposes
+playback only. No selected route silently falls back to another engine.
+
+For speech-only construction, pass `null` for both LLM arguments:
+`new AI(null, 'LOCAL_SPEACH', 'LOCAL_SPEACH', null, ttsModel, sttModel)`.
+This leaves the LLM unselected; omitted or empty arguments preserve defaults.
+The existing per-realm AI singleton is reused if already present. Import and
+construction do not prove native readiness.
+
+After the selected STT role is ready, `ai.supportsTranscriptionCapture()`
+reports its capture capability. `ai.createTranscriptionCapture(options)`
+returns `null` without a provider capture implementation, otherwise an owned
+`{start, stop, cancel, destroy, done, forceEndpoint?}` handle. Start from the
+user's capture action with `{signal, mediaConstraints}`. Native options include
+`sampleRate` (default 16000), `pcmChunkMs` (default 100),
+`activityThreshold` (default 0.02), `streamOptions`, `onUpdate`,
+`onInterim`, `onSegment`, `onActivity`, `onState`, `onError`,
+`onProgress`, and `onRequest`. The actual capture rate must match the native
+stream; every PCM contribution is delivered in order.
+
+Native recognition callbacks receive `(result, {requestStop})`. Keep full
+snapshots: interim results replace, and final segments retain their native
+boundaries, words, timestamps and speaker scope. A callback can call
+`requestStop()` without awaiting it and return; the external owner awaits
+`stop()` or `done`. Never await those joins or `forceEndpoint()` from their
+own callback. External `forceEndpoint()` flushes pending capture PCM and
+recognition callbacks while leaving the microphone and native stream open.
+`stop()` closes capture and drains recognition; `cancel()` and `destroy()`
+join cleanup without claiming a complete transcript. No control sends chat.
+
+For a streaming TTS catalog, `ai.prepareTTSPlayback({input, voice, languageCode, speed}, signal)`
+returns an inert descriptor. Its explicit `play()` uses the shared provider
+lane and Web Audio output. The returned control exposes `finished`,
+`released`, `state`, `error`, `pause()`, `resume()`, and `stop()`.
+`finished` describes playback completion, while `released` joins native
+cleanup. Stop targets that utterance, independently of capture.
+`fetchTTS({input, languageCode, ...}, signal)` still returns complete audio
+when the selected engine supports it. Language is caller-selected control data,
+separate from the text; Magpie supports natural speed `1` only. See
+[shared native capture/playback](../native-speech.md#shared-ai-capture-and-playback).
+
 <a id="digitalocean-fal-text-to-speech"></a>
 
 ## TWiN Cloud text-to-speech
@@ -665,13 +712,13 @@ selected execution device or assess the generated audio.
 ## Queue complete passages and wait for playback
 
 For a complete page or passage, call
-`ai.streamTTS(text, true, {voice, speed, pauseAfterMs, waitForPlayback:true})`.
+`ai.streamTTS(text, true, {voice, speed, languageCode, pauseAfterMs, waitForPlayback:true})`.
 The existing AI queue owns segmentation, concurrent synthesis, ordered
 playback, and cancellation. Supply the exact text; there is no need for an
 application sentence queue, audio cache, or playback scheduler.
 
 This function uses the configured `ai` above. Its application-supplied
-`passages` argument is an ordered array of `{text, voice?, speed?, pauseAfterMs?}`
+`passages` argument is an ordered array of `{text, voice?, speed?, languageCode?, pauseAfterMs?}`
 records. An omitted voice uses the selected model's default voice, an omitted
 speed uses `ai.voiceSpeed`, and an omitted pause is zero. Each supplied voice
 must be supported by the selected model; speed must be positive. A pause is
@@ -689,6 +736,7 @@ async function speakPassages(passages) {
                 {
                     voice: passage.voice,
                     speed: passage.speed,
+                    languageCode: passage.languageCode,
                     pauseAfterMs: passage.pauseAfterMs,
                     waitForPlayback: true
                 }
@@ -709,14 +757,17 @@ streamed speech and prepared playback owned by that AI instance and settles
 pending playback results `false`. Detached preparation described below keeps
 its independent lifetime.
 
-The selected voice and speed are captured for segments extracted by that call.
-That includes any text left in the same AI instance's partial-stream buffer;
-finish the previous producer before starting a separate complete passage.
-Voice, speed, pause, and playback options are not retained with an unfinished
-`end:false` remainder. A later call supplies its own options, and `finishTTS()`
-uses their defaults while flushing any pending single formatting mark through
-the same automatic speech-input cleanup.
-A call extracting no segments returns `true` without waiting for earlier jobs.
+Voice, speed and languageCode remain associated with an unfinished `end:false`
+utterance and its later `finishTTS()` flush; a supplied option replaces its retained
+selection. An explicitly changed language first queues the preceding remainder
+with its old selection, then accepts the new text. Language is separate control
+information and does not rewrite the text. End, mute and stop clear the retained
+selection. Pause and waitForPlayback remain per-call options. Finish a producer
+before starting an independent passage; the automatic speech-input cleanup
+still retains a pending single formatting mark until final flush.
+
+A call extracting no segments returns `true` without waiting for earlier jobs,
+except that a language-change call also joins its preceding remainder preparation.
 An already muted call returns `false`.
 
 Autoplay permission waiting and recoverable audio-resume attempts leave the

package/docs/reference/core-client.md

@@ -161,6 +161,41 @@ pre-aborted signal sends no transcription request; an in-flight abort sends
 service owns interruption and release of its actual engine operation.
 Its optional request observer uses the same pre-dispatch correlation contract.
 
+## Streaming native speech
+
+`Arcane.speech.openStream(request, {signal, onUpdate, onProgress, onRequest})`
+returns `{streamId, ready, completion, current, push, forceEndpoint, finish, cancel}`
+immediately. Await `ready` before feeding ordered mono `Float32Array` input at
+the request's actual `sampleRate`. This API opens no microphone.
+`forceEndpoint()` drains the current utterance and its ordered update callbacks
+without closing the retained stream; `finish()` drains accepted input and final
+delivery terminally. Partial snapshots replace prior partials; finals retain
+their engine-defined segment and speaker scope. Recognition never decides a
+human turn, instruction or approval.
+
+An `onUpdate` callback must return before its own `forceEndpoint()`,
+`finish()`, or `completion` join. Explicit `cancel(reason)` immediately
+suppresses later callbacks and awaits the matching native cleanup control.
+Aborting the signal instead follows ordinary request cancellation, whose browser
+promise may settle before native cleanup.
+
+`Arcane.speech.synthesizeStream(request, {signal, onAudio, onProgress, onRequest})`
+requires an `onAudio` consumer and resolves to the engine's complete terminal
+metadata. Every callback receives `{pcm: Uint8Array, format, sampleRate, channels, ...}`
+in order. The facade awaits each callback before acknowledging that contribution
+to the native producer. It does not play audio. An utterance abort joins its
+explicit native cancellation and callback cleanup; actual failures remain
+observable. A callback may abort its caller-owned signal and return, then the
+external owner joins synthesis completion.
+
+Both streaming operations have no fixed request timeout. Their scoped events
+and controls retain exact request ownership through client close, document
+retirement and transport loss. Engine support and loaded readiness are separate;
+a facade method alone supplies neither. Complete-recording transcription and
+complete-audio synthesis retain their existing contracts. See
+[Core streaming speech](native-speech.md#continuous-transcription-and-streaming-synthesis)
+for the complete protocol, cancellation and engine interfaces.
+
 ## Current-window state
 
 `Arcane.window.state({signal}?)` reads the native window hosting the calling

package/docs/reference/core-native-packaging.md

@@ -93,11 +93,43 @@ See [the complete selection contract](protocols.md#native-only-application-resou
 
 ## Output and host contract
 
-Each build creates a fresh `arcane-portable-*` directory beneath `outputRoot`.
-The result is `{app, target, manifest}`, with its actual directory at
-`target.rootDir`. Existing artifacts are preserved. Cancellation or a failed
-assembly removes only that build's newly created directory. Source/release roots
-cannot be overwritten with generated output.
+Each build assembles in a fresh temporary directory beneath `outputRoot`, then
+publishes the complete artifact to one stable app-specific child. Portable and
+Windows outputs use `<outputRoot>/<app-id>/`; macOS uses
+`<outputRoot>/<app-id>.app/`. The result remains `{app, target, manifest}`, with
+its actual payload directory at `target.rootDir` and the macOS bundle directory
+also returned as `bundleRoot`. A later successful build replaces that app's
+previous generated output instead of accumulating completed build directories.
+Windows device-name spellings such as `con` receive an underscore in the output
+folder name (`_con` or `_con.app`) on every build host; the app ID stays unchanged.
+
+Assembly leaves the current output available. Publication uses same-filesystem
+renames and retains the previous output in a temporary backup until the
+`native.payload.completed` callback accepts the new final paths. A callback
+rejection or cancellation restores the previous output; a successful build
+removes its backup and temporary assembly. The completion callback runs before
+build acceptance, including the following cancellation check; receiving that
+event alone does not establish an accepted build. `native.payload.started` identifies
+the temporary assembly, while `native.payload.completed` identifies the final
+payload and, on macOS, final bundle. Manifest paths stay relative to that payload;
+application content and explicitly supplied configuration paths stay unchanged.
+
+Only final replacement of the same app is reserved; independent assemblies and
+other apps remain concurrent. A competing publication reports the exact
+`.arcane-publish-<app-output-name>` reservation so its owner can finish before
+retrying. If recovery or backup cleanup fails, the error identifies the actual
+output, assembly and reservation paths, and whether publication committed.
+The reservation's `owner.json` records the process, acquisition time, advisory
+five-minute TTL/expiry and recovery locations. Expiry never permits automatic
+takeover or deletion. After an interrupted build, inspect those paths before restoring the previous
+output or removing the reservation. A running or locked app may prevent Windows
+replacement; close that app and retry the build after the reported failure.
+
+Replacement applies only to the matching app's generated artifact directory.
+Source/release roots, unrelated outputs, host/runtime download caches and the
+host's separate saved profile/model directories remain outside replacement.
+Existing randomly named outputs from earlier SDK versions are left untouched;
+the new stable-output lifecycle does not sweep old directories or user data.
 
 The selected app is copied unchanged under `app/`. Dependencies are copied
 unchanged under `dependencies/<index>/`; the manifest relates each directory to
@@ -751,7 +783,7 @@ produce their actual download error. SDK collaborators may select an existing
 version, another architecture or a browser-only artifact.
 
 The complete unchanged portable payload lives at
-`<app-id>.app/Contents/Resources/`. That directory remains `target.rootDir` and
+`<outputRoot>/<app-id>.app/Contents/Resources/`. That directory remains `target.rootDir` and
 contains `arcane-native.json`, `app/`, dependency releases, installed SDK files,
 Core entry/client and `runtime/node`. The additive `bundleRoot` identifies the
 `.app` directory. `Contents/MacOS/Arcane` and `Contents/Info.plist` belong to the

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

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.94.0",
+  "sdkVersion": "0.95.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 314,
+  "memberCount": 322,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
@@ -250,6 +250,134 @@
       "protocol": "Native speech voice selection",
       "normalization": "Complete ordered voice array exported by the frontend; af_heart is the omitted voice default. An unsupported explicit voice reports its actual incompatibility without substitution."
     },
+    {
+      "id": "local-ai-nemotron:createNemotronRuntime",
+      "name": "createNemotronRuntime",
+      "displayName": "createNemotronRuntime()",
+      "kind": "function",
+      "signature": "createNemotronRuntime({runtime,prepare,modelId='nemotron-3.5-asr-streaming-0.6b',modelPath,diarizationModelPath,gpu,onEvent}={})",
+      "entrypoints": [
+        "arcane-os/local-ai/nemotron"
+      ],
+      "primaryImport": "arcane-os/local-ai/nemotron",
+      "group": "Core native speech",
+      "summary": "Retains one native recognizer and optional diarizer across explicit utterance endpoints.",
+      "availability": "Node with a matching first-party helper, selected NeMo ASR runtime and models; Windows/Linux/macOS source, Android host adaptation",
+      "protocol": "Native ASR C ABI through one retained helper and replaying nemotron.state",
+      "normalization": "Returns current/subscribe/load/unload/transcribe/openStream/close. Exact ordered Float32 or f32le input uses the actual declared sample rate; complete snapshots retain alternatives, words, timestamps and speaker scope. forceEndpoint preserves the native stream; finish drains terminally. Callback joins reject NEMOTRON_CALLBACK_WAIT. Cancellation joins cleanup and exposes resetRequired when an in-flight native call requires helper termination; explicit load is required afterward. No microphone, semantic completion or fallback."
+    },
+    {
+      "id": "local-ai-nemotron:default",
+      "name": "default",
+      "displayName": "createNemotronRuntime default export",
+      "kind": "function",
+      "signature": "default as createNemotronRuntime",
+      "entrypoints": [
+        "arcane-os/local-ai/nemotron"
+      ],
+      "primaryImport": "arcane-os/local-ai/nemotron",
+      "group": "Core native speech",
+      "summary": "Default binding for the same createNemotronRuntime function.",
+      "availability": "Node with a matching first-party helper, selected NeMo ASR runtime and models; Windows/Linux/macOS source, Android host adaptation",
+      "protocol": "Native ASR C ABI through one retained helper and replaying nemotron.state",
+      "normalization": "Binding identity equals the named createNemotronRuntime export"
+    },
+    {
+      "id": "local-ai-nemotron-build:buildNemotronHelper",
+      "name": "buildNemotronHelper",
+      "displayName": "buildNemotronHelper()",
+      "kind": "function",
+      "signature": "async buildNemotronHelper({runtime,outputRoot,signal,onEvent}={})",
+      "entrypoints": [
+        "arcane-os/local-ai/nemotron/build"
+      ],
+      "primaryImport": "arcane-os/local-ai/nemotron/build",
+      "group": "Core native speech",
+      "summary": "Builds the first-party retained Nemotron ASR helper against a caller-selected NeMo installation.",
+      "availability": "Node with CMake 3.26+, C++17 toolchain and platform-matching public NeMo ASR headers/libraries/CMake package",
+      "protocol": "Owned configure/build/install process lifecycle",
+      "normalization": "runtime.cmakeDirectory and outputRoot select the prepared upstream installation and owned output. Returns platform/architecture/root/helperExecutable/executable and complete configure/compile/install diagnostics. Preserves cancellation and process failures; installs no dependency, model or toolchain and performs no inference."
+    },
+    {
+      "id": "local-ai-nemotron-build:default",
+      "name": "default",
+      "displayName": "buildNemotronHelper default export",
+      "kind": "function",
+      "signature": "default as buildNemotronHelper",
+      "entrypoints": [
+        "arcane-os/local-ai/nemotron/build"
+      ],
+      "primaryImport": "arcane-os/local-ai/nemotron/build",
+      "group": "Core native speech",
+      "summary": "Default binding for the same buildNemotronHelper function.",
+      "availability": "Node with CMake 3.26+, C++17 toolchain and platform-matching public NeMo ASR headers/libraries/CMake package",
+      "protocol": "Owned configure/build/install process lifecycle",
+      "normalization": "Binding identity equals the named buildNemotronHelper export"
+    },
+    {
+      "id": "local-ai-magpie:createMagpieRuntime",
+      "name": "createMagpieRuntime",
+      "displayName": "createMagpieRuntime()",
+      "kind": "function",
+      "signature": "createMagpieRuntime({runtime,prepare,paths,modelAssets,assetProjectionId,resourcePaths,modelId='magpie',voice='Aria',languageCode='en-US',executionTarget,signal,onEvent}={})",
+      "entrypoints": [
+        "arcane-os/local-ai/magpie"
+      ],
+      "primaryImport": "arcane-os/local-ai/magpie",
+      "group": "Core native speech",
+      "summary": "Retains native Magpie and NanoCodec for complete audio or ordered PCM synthesis.",
+      "availability": "Node with a matching first-party helper, selected NeMo TTS runtime, Magpie/tokenizer and NanoCodec assets; Windows/Linux/macOS source, Android host adaptation",
+      "protocol": "Native TTS C ABI through one retained helper and replaying magpie.state",
+      "normalization": "Returns current/subscribe/load/unload/synthesize/synthesizeStream/stop/close. Explicit CPU/CUDA selection, model-owned voice map and per-request language remain separate from exact input. Complete wav/pcm export and awaited ordered s16le onAudio delivery share FIFO request ownership. Native speed is 1. Stop targets a requestId and joins native/callback cleanup; self-joins reject MAGPIE_CALLBACK_WAIT. Playback and conversational meaning remain caller-owned; no download or fallback."
+    },
+    {
+      "id": "local-ai-magpie:default",
+      "name": "default",
+      "displayName": "createMagpieRuntime default export",
+      "kind": "function",
+      "signature": "default as createMagpieRuntime",
+      "entrypoints": [
+        "arcane-os/local-ai/magpie"
+      ],
+      "primaryImport": "arcane-os/local-ai/magpie",
+      "group": "Core native speech",
+      "summary": "Default binding for the same createMagpieRuntime function.",
+      "availability": "Node with a matching first-party helper, selected NeMo TTS runtime, Magpie/tokenizer and NanoCodec assets; Windows/Linux/macOS source, Android host adaptation",
+      "protocol": "Native TTS C ABI through one retained helper and replaying magpie.state",
+      "normalization": "Binding identity equals the named createMagpieRuntime export"
+    },
+    {
+      "id": "local-ai-magpie-build:buildMagpieHelper",
+      "name": "buildMagpieHelper",
+      "displayName": "buildMagpieHelper()",
+      "kind": "function",
+      "signature": "async buildMagpieHelper({runtime,outputRoot,signal,onEvent}={})",
+      "entrypoints": [
+        "arcane-os/local-ai/magpie/build"
+      ],
+      "primaryImport": "arcane-os/local-ai/magpie/build",
+      "group": "Core native speech",
+      "summary": "Builds the first-party Magpie synthesis helper against a caller-selected NeMo installation.",
+      "availability": "Node with CMake 3.26+, C++17 toolchain, platform threads and matching public NeMo TTS headers/libraries/CMake package",
+      "protocol": "Owned configure/build/install process lifecycle",
+      "normalization": "runtime.cmakeDirectory and outputRoot select the prepared upstream installation and owned output. Returns platform/architecture/root/helperExecutable and complete configure/compile/install diagnostics. Preserves cancellation and process failures; installs no dependency, model or toolchain and performs no inference."
+    },
+    {
+      "id": "local-ai-magpie-build:default",
+      "name": "default",
+      "displayName": "buildMagpieHelper default export",
+      "kind": "function",
+      "signature": "default as buildMagpieHelper",
+      "entrypoints": [
+        "arcane-os/local-ai/magpie/build"
+      ],
+      "primaryImport": "arcane-os/local-ai/magpie/build",
+      "group": "Core native speech",
+      "summary": "Default binding for the same buildMagpieHelper function.",
+      "availability": "Node with CMake 3.26+, C++17 toolchain, platform threads and matching public NeMo TTS headers/libraries/CMake package",
+      "protocol": "Owned configure/build/install process lifecycle",
+      "normalization": "Binding identity equals the named buildMagpieHelper export"
+    },
     {
       "id": "local-ai-whisper:createWhisperRuntime",
       "name": "createWhisperRuntime",
@@ -429,8 +557,8 @@
       "group": "Core native speech",
       "summary": "Composes host-supplied transcription and synthesis engines with independent loading and role readiness.",
       "availability": "Node Core with explicitly supplied engines; engine platform, model and format support remain engine-owned",
-      "protocol": "arcane/1 speech.status/load/unload/transcribe/synthesize with speech.state/progress",
-      "normalization": "Returns current/subscribe/close/start/methods/drain/dispose; forwards complete requests and results unchanged; replaying service state, synchronous accepted Thinking, combined request/lifetime cancellation and concurrent joined engine shutdown. Explicit load/unload require role stt or tts and forward the remaining activation fields and complete result through that role's configured engine; supported preparation remains with that engine. Startup waiting is independently owned from caller cancellation; no automatic provider selection is introduced."
+      "protocol": "arcane/1 speech.status/load/unload/transcribe/synthesize; optional open/push/endpoint/finish/cancel/synthesizeStream/audioConsumed/cancelSynthesis with speech.state/progress/opened/transcription/audio",
+      "normalization": "Returns current/subscribe/close/start/methods/drain/dispose; forwards complete requests and results unchanged; replaying service state, synchronous accepted Thinking, combined request/lifetime cancellation and concurrent joined engine shutdown. Explicit load/unload require role stt or tts and forward the remaining activation fields and complete result through that role's configured engine; supported preparation remains with that engine. Per-role supportsStreaming reflects actual engine methods independently of readiness. Request-scoped streaming retains exact PCM and unchanged snapshots; endpoint preserves stream scope, terminal finish drains, and cancellation joins native ownership. Awaited TTS audio acknowledgements apply producer backpressure without blocking control traffic. ASR finals do not decide conversation completion. Startup waiting is independently owned from caller cancellation; no automatic provider selection is introduced."
     },
     {
       "id": "core-speech:default",
@@ -4444,7 +4572,7 @@
       "summary": "Projects a Core client into the established application-facing Arcane namespace.",
       "availability": "Browser and native WebView JavaScript hosts with a Core client",
       "protocol": "arcane/1 compatibility facade",
-      "normalization": "Routes namespace methods through client.invoke while retaining operation-specific parameters, correlation, streaming callbacks, timeouts and cancellation; window.state({signal}?) reads the requesting window and window.setState({state},{signal}?) selects normal, maximized or fullscreen. The matching Windows host returns {platform:'windows',supported:true,state}, including observed minimized state, restores normal bounds/frame controls on leaving fullscreen and prevents activation/focus assignment during visible state transitions without changing TopMost, Core, origin or profile. Saved Settings remain application-owned; cancellation does not undo an applied change and unavailable hosts retain their actual errors without fallback. window.setTheme(presentation,{signal}?) forwards the complete per-window backgroundColor/textColor record, with omitted fields unchanged and null reset, and returns the host's actual applied/unsupported result without changing system appearance. notifications.status/show/state/close forward complete caller requests and standard invoke options; status normalizes only METHOD_NOT_ALLOWED with core-namespace-unavailable while retaining the complete original error. Matching native window hosts retain complete notification records and ordered revisions across renderer navigation, with notifications.state events and subscribe-before-snapshot recovery. Submitted means native Show returned, not displayed or read; cancellation after submission does not remove an accepted notice, and explicit close retains its record. Recipient, text, trigger, deduplication and navigation policy remains application-owned. speech.load(request,options) and speech.unload(request,options) forward complete activation requests, cancellation and request observers with no elapsed-time cutoff; selected engines own preparation and native retirement."
+      "normalization": "speech.openStream(request,options) returns streamId/ready/completion/current/push/forceEndpoint/finish/cancel with ordered exact Float32 input and complete snapshot callbacks; endpoint/finish delivery joins must occur outside their own callbacks. Explicit stream cancel joins native cleanup, distinct from ordinary signal cancellation. speech.synthesizeStream(request,{signal,onAudio,onProgress,onRequest}) awaits required ordered Uint8Array PCM callbacks and exact consumption acknowledgements, joins cancellation, and returns complete terminal metadata without playback. Both streams have no fixed timeout. Routes namespace methods through client.invoke while retaining operation-specific parameters, correlation, streaming callbacks, timeouts and cancellation; window.state({signal}?) reads the requesting window and window.setState({state},{signal}?) selects normal, maximized or fullscreen. The matching Windows host returns {platform:'windows',supported:true,state}, including observed minimized state, restores normal bounds/frame controls on leaving fullscreen and prevents activation/focus assignment during visible state transitions without changing TopMost, Core, origin or profile. Saved Settings remain application-owned; cancellation does not undo an applied change and unavailable hosts retain their actual errors without fallback. window.setTheme(presentation,{signal}?) forwards the complete per-window backgroundColor/textColor record, with omitted fields unchanged and null reset, and returns the host's actual applied/unsupported result without changing system appearance. notifications.status/show/state/close forward complete caller requests and standard invoke options; status normalizes only METHOD_NOT_ALLOWED with core-namespace-unavailable while retaining the complete original error. Matching native window hosts retain complete notification records and ordered revisions across renderer navigation, with notifications.state events and subscribe-before-snapshot recovery. Submitted means native Show returned, not displayed or read; cancellation after submission does not remove an accepted notice, and explicit close retains its record. Recipient, text, trigger, deduplication and navigation policy remains application-owned. speech.load(request,options) and speech.unload(request,options) forward complete activation requests, cancellation and request observers with no elapsed-time cutoff; selected engines own preparation and native retirement."
     },
     {
       "id": "core-client:installCoreClient",