arcane-os 0.94.0 → 0.96.0

package/CHANGELOG.md

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

package/README.md

@@ -25,7 +25,7 @@ selected SDK projection or an explicit live SDK source mount. Both profiles
 share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.94.0` SDK contract. Development applications declare
+This checkout defines the `0.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/browser-runtime/core/client.mjs

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

package/docs/reference/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