arcane-os 0.95.0 → 0.97.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.97.0
+
+- Share native model storage across applications for the same operating-system
+  user on Windows, Linux and macOS. Preserve explicit model locations and
+  app-private settings, profiles and chat history without moving existing data.
+- Retain completed model companions and interrupted partial downloads. Explicit
+  retries resume compatible HTTP transfers or restart only the affected member;
+  completed shards are reused and selected TAR companions remain preserved.
+- Coordinate same-selection acquisition across processes, recover after an
+  exited transfer owner, and preserve independent caller cancellation.
+- Expose actual activity, waiting, stalled, resumed and terminal download states
+  through the shared model-assets API. Deliver queued failure progress before
+  browser cleanup, with complete technical errors in developer inspection.
+
+## 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.97.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,85 @@ 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) {
+        // Core publishes the terminal transfer state before rejecting prepare.
+        // Deliver that queued state before our cleanup cancellation can suppress
+        // it. Explicit caller cancellation still owns its existing boundary.
+        try { await delivery; }
+        catch (deliveryError) { callbackFailure ??= deliveryError; }
+        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,11 +76,18 @@ 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) |
 | Project complete stored model files into native working files | [Model assets through Core](model-assets.md) |
 | Prepare selected upstream model members in native services | [Native preparation and retained lifetime](model-assets.md#native-ownership) |
+| Discover installed models, ordered GGUF shards and required companion files | [Model discovery and existing-file projections](model-assets.md) |
+| Download selected model members with visible file progress and joined cancellation | [downloadCoreModelAssets()](sdk-api.md#downloadcoremodelassets) and [native model assets](model-assets.md) |
+| Prepare the complete Nemotron or Magpie model selection | [Shared native speech catalog](sdk-api.md#preparenemotronmodels) |
+| Use same-user shared native model storage or explicit directory overrides and prepare engines on demand | [Model locations and activation](model-assets.md) |
 | Retain a Nemotron model and diarize caller-fed audio streams | [Native speaker diarization](diarization.md) |
 | Persist application-selected preferences through Core | [Core preferences service](core-preferences.md) |
 | Read complete selected Git text without changing a checkout | [Git text snapshots](git-text-snapshot.md) |
@@ -89,6 +96,7 @@ alone does not make bare module names resolve in a browser.
 | Write, commit and push complete selected repository text | [Selected-text repository writing](core-repositories.md#write-commit-and-push-selected-text) |
 | Observe existing checkout configuration and capture an explicit remote/ref | [Repository configuration and selected targets](core-repositories.md#existing-checkout-configuration-and-selected-targets) |
 | Build an installed-SDK portable Core payload | [Portable Core packaging](core-native-packaging.md) |
+| Replace only the selected app's successful native build while preserving model storage | [Stable native output](core-native-packaging.md#output-and-host-contract) |
 | Resolve matching native state/workspace/endpoint defaults and preserve explicit launch values | [Launch-time locations](core-native-packaging.md#launch-time-locations) and [resolveNativeLaunchContext()](sdk-api.md#resolvenativelaunchcontext) |
 | Build a Windows executable without an OS checkout | [Windows executable packaging](core-native-packaging.md#windows-executable) |
 | Compose a Mac application with an architecture-matched host | [macOS application composition](core-native-packaging.md#macos-application-composition) |
@@ -243,6 +251,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
@@ -309,6 +341,10 @@ It returns a new complete context and fills only omitted fields:
 | `stateRoot` on Windows | `%LOCALAPPDATA%/Arcane/<appId>`; standard home `AppData/Local` fallback when the environment value is absent |
 | `stateRoot` on macOS | `~/Library/Application Support/Arcane/<appId>` |
 | `stateRoot` on Linux | Absolute `$XDG_DATA_HOME/Arcane/<appId>`, otherwise `~/.local/share/Arcane/<appId>` |
+| `modelsDirectory` on Windows | `%LOCALAPPDATA%/Arcane/Models`, with the same standard home fallback |
+| `modelsDirectory` on macOS | `~/Library/Application Support/Arcane/Models` |
+| `modelsDirectory` on Linux | Absolute `$XDG_DATA_HOME/Arcane/Models`, otherwise `~/.local/share/Arcane/Models` |
+| `modelsDirectory` on other adapted hosts | `<resolved stateRoot>/Models` unless the host supplies an explicit shared location |
 | `workspaceRoot` | `<resolved stateRoot>/Workspace` |
 | `sharedHost.endpoint`, only when `sharedHost` is selected | Windows named pipe `\\.\pipe\Arcane-` followed by the URL-encoded complete resolved state path; Linux/macOS socket `<resolved stateRoot>/core.sock` |
 | `sharedHost.logFile`, only when `sharedHost` is selected | `<resolved stateRoot>/Core.log` |
@@ -323,9 +359,15 @@ shared entry creates its selected state directory because its socket/log need
 that parent; application services continue to own workspace I/O. Custom
 endpoint/log parent directories retain the existing shared-host requirements.
 
-Explicit `stateRoot`, `workspaceRoot`, endpoint, log filename and additional
-fields remain authored values; the resolver derives omitted paths from the
-absolute selected state location. Relative explicit paths retain the caller's
+Models default to one directory per operating-system user, independent of the
+application ID or app-private state root. Apps selecting the same sources and
+shared model store reuse the SDK acquisition owner. Preferences, profiles,
+chat history, workspace and IPC remain app-scoped. Existing app-local models
+are not moved or deleted: callers can discover and open them in place.
+
+Explicit `stateRoot`, `modelsDirectory`, `workspaceRoot`, endpoint, log filename
+and additional fields remain authored values. The resolver derives app-private
+paths from the absolute selected state location. Relative explicit paths retain the caller's
 working-directory meaning, so UI and MCP callers must select the same location.
 No hashing, app-local OS path composition, directory scanning, or new repository
 location rule is involved. `resolveArcaneDataPaths()` continues to own its
@@ -751,7 +793,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