arcane-os 0.95.0 → 0.96.0

package/docs/reference/inventory/runtime-modules.json

@@ -5,12 +5,12 @@
     "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
     "branch": "main",
     "path": "runtime/arcane",
-    "sdkVersion": "0.51.1",
+    "sdkVersion": "0.95.0",
     "protocol": "arcane/1"
   },
-  "artifactCount": 93,
-  "javascriptArtifactCount": 91,
-  "esmExportCount": 375,
+  "artifactCount": 95,
+  "javascriptArtifactCount": 93,
+  "esmExportCount": 377,
   "artifacts": [
     {
       "file": "runtime/arcane/modules/AI.js",
@@ -27,11 +27,11 @@
         "AI_READY_EVENT",
         "default"
       ],
-      "summary": "Owns provider-selectable chat and the one-time caller-authority browser STT/TTS configuration, lifecycle, synthesis, transcription, and playback boundary.",
+      "summary": "Owns provider-selectable chat and the caller-selected browser/native STT/TTS configuration, lifecycle, synthesis, transcription, and playback boundary.",
       "availability": "Browser + native bridge + TWiN Cloud",
       "protocol": "arcane-ai-browser-speech-configuration/1, AIProviderRuntime arcane-ai-provider/2 routes, globalThis.arcaneEvents, TWiN Cloud HTTPS, Arcane.ollama, Arcane.speech, Android WebView bridge",
       "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized Whisper STT and Kokoro TTS execution with default capacities 1 and 4 respectively, explicit provider-neutral execution snapshots through status(role,{execution:true}), sticky readiness, canonical window.user readiness without compatibility-event object-identity admission or polling, exact ordered structural calls with required arguments.message, atomic nonblank all-ID tool-result sequencing, complete all-choice streaming/data validation, native Ollama structural adaptation, complete-response then all validated tool callbacks then completion ordering, observed async callbacks, Blob/File transcription, default repeated-formatting-mark removal from cloned outbound TTS input, explicit textFormat:'plain' preservation for complete synthesis/preparation while streaming cleanup remains automatic and caller/visible content stays exact, immediate exact-segment synthesis, per-call voice/speed capture, optional final-segment pause on the existing audio clock, optional per-call terminal playback completion, detached preparation with complete semantic DBOPFS audio reuse and same-owner pending request sharing; each preparation owns its pending activation interest, final-interest cancellation aborts that activation while other interests preserve it, complete cache hits start no model, and cancellation after readiness leaves the ready model loaded; independent prepared playback without a model load for cached audio, ordered audio-clock scheduling, playable audio, active-generation TTS operation-failure routing, mute, and cancellation are normalized; provider/model/runtime/voice policy remains caller-owned. Both speech roles default execution.device to auto: webnn-npu when navigator.ml.createContext is exposed, then webgpu when navigator.gpu is exposed, then wasm for CPU execution. Failed backend loads clean up the pool before trying fresh Workers with the same prepared model and dtype; explicit devices never fall back. STT capacity only accepts 1; TTS accepts 1 through 4. Execution snapshots expose requestedDevice, selectedDevice, maxConcurrentRequests, and activeRequestCount for both roles; selectedDevice is null while unloaded and names the successful upstream session backend request when loaded. It does not prove every operation used the physical NPU: WebNN unsupported operations may use WASM, and compatibility depends on the browser, driver, hardware, and graph. High-level LLM selection defaults to eager activation; startLanguageModel:false preserves the selected tuple and registered adapters without preloading through later readiness callbacks. Caller cancellation waits for accepted old-role cleanup and prevents later configuration/preload, or reaches the first owned load after selection commits. Newer accepted selections supersede older continuations; deferred or cancelled activation stays inactive until explicit load/startup, and a caller abort after successful settlement never unloads the ready model. Separate callers joining an existing runtime load retain their current cancellation ownership.",
-      "surface": "Native fetchTTS(payload,signal) and fetchSTT(audio,signal) forward caller cancellation separately from their complete Core speech payloads, normalize aborts to AbortError and suppress late results; actual engine interruption remains service-owned. prepareTTSPlayback(payload,signal) silently returns a real Blob or native-speech descriptor; native controls expose finished/released/state/error/pause/resume/stop, and actual release owns the playback lane. fetchTTS and durable prepareTTS report ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE for native voices. Request-local model overrides remain exact and never mutate the configured model. Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; default speech-input cleanup with SDK-internal preparation metadata and explicit complete-call textFormat:'plain' consumed before engine dispatch; `prepareTTS({parts,storage,identity,textFormat,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); async `readPreparedTTS({parts,textFormat,storage,identity,signal,onState})` returning a complete ready handle or null through the same semantic matcher, with no activation, unmute, synthesis, playback, storage writes, or partial repair; manifest, audio availability, and returned-handle reads use DBOPFS createTable:false so absent tables remain absent; supplied adapters own that read-existing behavior; missing matches/audio return null, malformed metadata and storage failures reject, and omitted storage sees only completed matching same-AI in-memory audio; hits replay ready state, misses emit nothing, and the lookup signal detaches on settlement while returned-handle cancellation stays independent; `prepareAudioOutput()` returning the persistent WebAudio handle {kind,state,contextState,error,subscribe,resume,dispose} without resume, unmute, model load, sources, sound, or gesture listeners; current-state replay and output-specific canonical `AI_AUDIO_OUTPUT_STATE_EVENT` (`ai-audio-output-state`), with ready only for an actually running context; explicit owner disposal observes context-bound cleanup and close; `playPreparedTTS(prepared,{signal,onState,audioOutput})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; explicit live same-AI audioOutput borrows its context until owner disposal, while omission or null preserves per-playback terminal close; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`. `setAI(llmService,sttService,ttsService,model,modelTTS,modelSTT,options)` and `transitionAI(llmService,sttService,ttsService,model,modelTTS,modelSTT,options)` preserve six positional preferences; `configureProviders(selections,options)` and `transitionProviders(selections,options)` accept the same optional {signal:null,startLanguageModel:true} defaults. setAI retains its synchronous boolean and configureProviders its synchronous route result. Explicit `providerRuntime.load('llm',{signal})` or `startProviders({startLanguageModel:true,signal})` activates a deferred selected route."
+      "surface": "Explicit null LLM service and null model constructor arguments leave LLM routes unselected; omitted/empty arguments retain defaults, and an existing window.ai is reused. supportsTranscriptionCapture() and createTranscriptionCapture(options) expose selected-provider capture without starting it. Native capture forwards exact PCM, callbacks and external endpoint/stop/cancel joins; finals are recognition segments, never automatic chat. Streaming native TTS preparation is inert, play consumes ordered PCM and released joins native cleanup. Per-utterance languageCode is forwarded separately from text. voice/speed/languageCode persist with an unfinished streamTTS utterance through finishTTS; explicit language change queues the previous remainder under its prior selection. Native fetchTTS(payload,signal) and fetchSTT(audio,signal) forward caller cancellation separately from their complete Core speech payloads, normalize aborts to AbortError and suppress late results; actual engine interruption remains service-owned. prepareTTSPlayback(payload,signal) silently returns a real Blob or native-speech descriptor; native controls expose finished/released/state/error/pause/resume/stop, and actual release owns the playback lane. fetchTTS and durable prepareTTS report ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE for browser-native voices without audio export; Magpie retains full-audio export. Request-local model overrides remain exact and never mutate the configured model. Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, languageCode, pauseAfterMs, and waitForPlayback; default speech-input cleanup with SDK-internal preparation metadata and explicit complete-call textFormat:'plain' consumed before engine dispatch; `prepareTTS({parts,storage,identity,textFormat,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); async `readPreparedTTS({parts,textFormat,storage,identity,signal,onState})` returning a complete ready handle or null through the same semantic matcher, with no activation, unmute, synthesis, playback, storage writes, or partial repair; manifest, audio availability, and returned-handle reads use DBOPFS createTable:false so absent tables remain absent; supplied adapters own that read-existing behavior; missing matches/audio return null, malformed metadata and storage failures reject, and omitted storage sees only completed matching same-AI in-memory audio; hits replay ready state, misses emit nothing, and the lookup signal detaches on settlement while returned-handle cancellation stays independent; `prepareAudioOutput()` returning the persistent WebAudio handle {kind,state,contextState,error,subscribe,resume,dispose} without resume, unmute, model load, sources, sound, or gesture listeners; current-state replay and output-specific canonical `AI_AUDIO_OUTPUT_STATE_EVENT` (`ai-audio-output-state`), with ready only for an actually running context; explicit owner disposal observes context-bound cleanup and close; `playPreparedTTS(prepared,{signal,onState,audioOutput})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; explicit live same-AI audioOutput borrows its context until owner disposal, while omission or null preserves per-playback terminal close; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`. `setAI(llmService,sttService,ttsService,model,modelTTS,modelSTT,options)` and `transitionAI(llmService,sttService,ttsService,model,modelTTS,modelSTT,options)` preserve six positional preferences; `configureProviders(selections,options)` and `transitionProviders(selections,options)` accept the same optional {signal:null,startLanguageModel:true} defaults. setAI retains its synchronous boolean and configureProviders its synchronous route result. Explicit `providerRuntime.load('llm',{signal})` or `startProviders({startLanguageModel:true,signal})` activates a deferred selected route."
     },
     {
       "file": "runtime/arcane/modules/AIModelSelectionController.js",
@@ -92,7 +92,7 @@
       "availability": "Cross-host in-process runtime; registered providers remain browser, native, or cloud specific",
       "protocol": "arcane-ai-runtime/2, arcane-ai-provider/2, arcane-ai-model-authority/1",
       "normalization": "Normalizes mutable complete per-role routes, lifecycle/status, cancellation, streaming cleanup, capacity-1 FIFO LLM/STT lanes, bounded provider-declared parallel TTS requests with FIFO overflow, default repeated-formatting-mark removal from cloned direct TTS payloads or explicit textFormat:'plain' preservation with the control consumed before engine dispatch, local-only selection, direct LLM history/declaration/terminal structural contracts, complete all-choice content/reasoning FIFO iteration, private automatic provider draining with result-first buffering, terminal-only structural calls, exact per-choice observed/terminal correlation, and a separate complete validated terminal result without creating a fallback.",
-      "surface": "Protocol constants; singleton-only `AIProviderRuntime`; `aiProviderRuntime`; `getAIProviderRuntime()`; provider registration/identity/selection, closed three-role and STT/TTS-only validation/configuration/replacement, status/catalog/inspection, startup, per-role load/unload/dispose/cancel, dispose-all, request/stream/speech aliases, SDK-internal speech-input preparation metadata, and setSpeechMuted(muted,{signal}={}) controls. Each pending unmute caller owns its abortable interest; the final interest aborts the owned activation while other preparation/playback or joining direct TTS-load interests preserve it. A pre-aborted unmute starts no activation. Explicit mute retains global cancellation and joined unload even with an aborted observer signal."
+      "surface": "supportsTranscriptionCapture(providerId=null) reports the provider capture capability; createTranscriptionCapture(options) returns null or an owned start/stop/cancel/destroy/done handle with optional forceEndpoint. Start requires an idle ready selected STT role, remains in the initiating user gesture and is never queued. Capture holds that role until done joins cleanup; cancellation/retirement uses the same role owner. Native streaming TTS uses the existing request lane with ordered awaited PCM callbacks. Protocol constants; singleton-only `AIProviderRuntime`; `aiProviderRuntime`; `getAIProviderRuntime()`; provider registration/identity/selection, closed three-role and STT/TTS-only validation/configuration/replacement, status/catalog/inspection, startup, per-role load/unload/dispose/cancel, dispose-all, request/stream/speech aliases, SDK-internal speech-input preparation metadata, and setSpeechMuted(muted,{signal}={}) controls. Each pending unmute caller owns its abortable interest; the final interest aborts the owned activation while other preparation/playback or joining direct TTS-load interests preserve it. A pre-aborted unmute starts no activation. Explicit mute retains global cancellation and joined unload even with an aborted observer signal."
     },
     {
       "file": "runtime/arcane/modules/AIResponseURLPolicy.js",
@@ -442,11 +442,11 @@
       "exports": [
         "default"
       ],
-      "summary": "Owns continuous microphone capture with rolling pre-roll, activity-triggered pause/periodic segments, complete WAV delivery, final flush, and cancellation.",
+      "summary": "Owns continuous microphone capture with complete ordered PCM or rolling pre-roll, activity-triggered pause/periodic segments, complete WAV delivery, final flush, and cancellation.",
       "availability": "Browser / native WebView with getUserMedia, AudioContext, and AudioWorklet",
       "protocol": "Native microphone and Web Audio lifecycle; internal VoiceCaptureWorklet MessagePort",
-      "normalization": "Complete mono Float32 WAV Blob segments with session-local sequence, pause/periodic/stop reason, and durationMs. Sound amplitude drives segmentation without semantic speech recognition. Inactive audio produces no segment, and periodic segments do not reuse samples. Stop releases microphone tracks immediately and waits for final flush; cancel releases capture and suppresses late callbacks.",
-      "surface": "default ContinuousVoiceCapture; constructor({preRollMs=1500,quietMs=2000,chunkMs=30000,activityThreshold=0.02,onSegment,onError,onState}); start({mediaConstraints={audio:true},signal}={}) resolves boolean; stop() resolves after final flush; cancel() and destroy() release the owned session."
+      "normalization": "mode:pcm transfers every sample in ordered Float32Array records with actual sampleRate/channels/sequence; amplitude activity reports no semantic speech decision and never gates PCM. flush joins earlier PCM delivery without closing capture. Stop/cancel/destroy join accepted PCM and actual AudioContext close, surfacing failures. In the default segments mode: Complete mono Float32 WAV Blob segments with session-local sequence, pause/periodic/stop reason, and durationMs. Sound amplitude drives segmentation without semantic speech recognition. Inactive audio produces no segment, and periodic segments do not reuse samples. Stop releases microphone tracks immediately and waits for final flush; cancel releases capture and suppresses late callbacks.",
+      "surface": "default ContinuousVoiceCapture; constructor({preRollMs=1500,quietMs=2000,chunkMs=30000,activityThreshold=0.02,mode=segments,pcmChunkMs=100,onSegment,onPCM,onActivity,onError,onState}); start({mediaConstraints={audio:true},sampleRate,signal}={}) resolves boolean; flush() resolves after pending PCM delivery; stop() resolves after final flush and close; cancel() and destroy() release the owned session."
     },
     {
       "file": "runtime/arcane/modules/ConversationActionItems.js",
@@ -991,6 +991,32 @@
       "normalization": "Complete mutable definition data with coded syntax errors for malformed input.",
       "surface": "`parseModelDefinition()`, `loadModelDefinitionSystemPrompt()`."
     },
+    {
+      "file": "runtime/arcane/modules/NativeSpeechCapture.js",
+      "name": "NativeSpeechCapture.js",
+      "kind": "esm",
+      "exports": [
+        "default"
+      ],
+      "summary": "Connects one microphone lifetime to one retained Core transcription stream without deciding conversational turns.",
+      "availability": "Browser / native WebView with microphone, AudioWorklet and selected streaming Core speech",
+      "protocol": "ContinuousVoiceCapture PCM and Arcane.speech.openStream",
+      "normalization": "Exact ordered mono PCM at the actual declared rate; complete provisional/final snapshots and callback controls. forceEndpoint flushes audio and recognition while preserving capture and stream scope; stop drains terminally; cancel joins capture/native cleanup without claiming a complete transcript.",
+      "surface": "default createNativeSpeechCapture({speech,model,sampleRate=16000,pcmChunkMs=100,activityThreshold=0.02,streamOptions,mediaConstraints,onUpdate,onInterim,onSegment,onActivity,onState,onError,onProgress,onRequest}); returns start({signal,mediaConstraints}), forceEndpoint(), stop(), requestStop(), cancel(reason), destroy(reason), done and current(). Recognition callbacks receive (result,{requestStop}); request a stop then return, and join externally. No implicit model load, conversation reply or fallback."
+    },
+    {
+      "file": "runtime/arcane/modules/NativeSpeechPlayback.js",
+      "name": "NativeSpeechPlayback.js",
+      "kind": "esm",
+      "exports": [
+        "default"
+      ],
+      "summary": "Prepares an inert native speech descriptor and plays ordered PCM through the existing shared Web Audio owner.",
+      "availability": "Browser / native WebView with Web Audio and selected streaming speech",
+      "protocol": "speech.synthesizeStream with awaited PCM consumption",
+      "normalization": "Preparation starts no synthesis or playback. play schedules every supplied s16le sample in original order with audio-clock backpressure. Pause retains playback position; stop cancels only that utterance. finished and released distinguish playback termination from joined native cleanup; errors remain observable.",
+      "surface": "default prepareNativeSpeechPlayback({speech,request,getAudioContext,signal=null}); returns {kind:native-speech,input,voice,language,speed,play}. play({signal,onState}) returns finished/released/state/error/pause/resume/stop. The caller owns its AudioContext; this module never closes unrelated output."
+    },
     {
       "file": "runtime/arcane/modules/Ollama.js",
       "name": "Ollama.js",
@@ -1462,11 +1488,11 @@
       "name": "VoiceCaptureWorklet.js",
       "kind": "worker",
       "exports": [],
-      "summary": "Segments microphone samples on the audio rendering thread and transfers complete mono Float32 WAV clips to ContinuousVoiceCapture.",
+      "summary": "Transfers continuous PCM or segments microphone samples on the audio rendering thread and transfers complete mono Float32 WAV clips to ContinuousVoiceCapture.",
       "availability": "AudioWorkletGlobalScope",
       "protocol": "AudioWorklet processor arcane-continuous-voice-capture and its owner-local MessagePort",
-      "normalization": "Rolling pre-roll, fixed 20 ms RMS activity windows independent of callback length, audio-frame quiet duration, periodic boundaries, sequence, complete original WAV audio, and stop acknowledgement are owned here. activityThreshold is RMS amplitude, not peak amplitude. Stop classifies a partial final window using its actual samples and retains softer trailing audio in the active clip. Inactive capture emits no clips; adjacent periodic clips have no repeated samples.",
-      "surface": "No ESM exports. ContinuousVoiceCapture loads this static worklet, supplies processorOptions, receives segment messages, and requests stop followed by the stopped acknowledgement."
+      "normalization": "mode:pcm emits every original sample in ordered PCM frames at the actual worklet sample rate, plus activity observations; pcmChunkMs defines transport scheduling, not a recording cap. flush returns pending PCM and a correlated flushed acknowledgement without closing the processor. The default segments mode retains rolling pre-roll, fixed 20 ms RMS activity windows independent of callback length, audio-frame quiet duration, periodic boundaries, sequence, complete original WAV audio, and stop acknowledgement. activityThreshold is RMS amplitude, not peak amplitude. Stop classifies a partial final window using its actual samples and retains softer trailing audio in the active clip. Inactive capture emits no clips; adjacent periodic clips have no repeated samples.",
+      "surface": "No ESM exports. ContinuousVoiceCapture loads this static worklet, supplies processorOptions, receives segment or pcm/activity/flushed messages, and requests stop followed by the stopped acknowledgement."
     },
     {
       "file": "runtime/arcane/modules/WaitForComponent.js",

package/docs/reference/model-assets.md

@@ -110,11 +110,11 @@ try {
 }
 ```
 
-`prepare({id,workingDirectory,members,signal,onProgress,refresh=false})` reuses
+`prepare({id,workingDirectory,members,archives,signal,onProgress,refresh=false})` reuses
 a complete native acquisition or fetches the explicitly selected members.
 Every member has its original relative `path` and selected `url`; the caller
 supplies the complete companion-file set. Independent members download
-concurrently. Each complete response stream is written directly to its native
+concurrently, with up to four independent source transfers active. Each complete response stream is written directly to its native
 file, without a whole-model buffer or base64 conversion. No model or runtime
 is selected or downloaded by service startup. The result remains the ready
 projection snapshot with ordered `members: [{path,nativePath}]`.
@@ -144,6 +144,158 @@ callback does not hold another caller's transfer or result. Callbacks must not
 await cleanup of the preparation currently calling them. Callback failures
 reject that caller's preparation. HTTP failures
 retain `url`, `status` and the complete response text in `response`.
+During an active member, repeated activity notifications are emitted at most
+once per second; opening, member completion and terminal phases remain distinct.
+Progress describes files and phases, never transfer volume.
+
+### Selected archive companions
+
+An optional `archives` array acquires exact companion members from an upstream
+uncompressed TAR source through this same acquisition owner:
+
+```javascript
+const projection = await modelAssets.prepare({
+    id: selectedOperationId,
+    workingDirectory: selectedModelDirectory,
+    members: selectedModelFiles,
+    archives: [{
+        url: selectedArchiveURL,
+        format: 'tar',
+        members: [
+            {path: 'tokenizer/model_config.yaml', member: 'model_config.yaml'},
+            {path: 'tokenizer/speakers.json', member: 'speakers.json'}
+        ]
+    }],
+    signal,
+    onProgress
+});
+```
+
+The result orders ordinary members first, followed by each archive's declared
+members. Extraction preserves each complete selected file. TAR names and PAX
+path records select members; a leading `./` is archive path framing. Missing
+selected members reject preparation and identify the missing names. Gzip and
+other archive formats are outside this reader's contract.
+
+When the upstream catalog supplies aligned TAR segments, an archive may include
+`ranges:[{start,end,stopBefore?}]`. The reader requests each inclusive HTTP range
+once and parses its TAR framing; `stopBefore` ends that segment before the
+specified member. Offsets and TAR lengths are solely external transport framing.
+They are never download progress, model readiness criteria or content identity.
+Ranges require the matching HTTP partial-content response; no complete-archive
+fallback is silently substituted. Native reuse identifies archive members by
+their selected URL, archive member name and output path, alongside ordinary
+members, without re-fetching an already completed set.
+
+## Discover and open installed files
+
+`discover({directories,catalog=[],recursive=true,signal})` inspects only the
+explicit directories, without downloading, copying, loading or selecting a
+model. Paths resolve from `appRoot`. It returns:
+
+```javascript
+{
+    directories: [{directory, exists, error}], // error is present only on failure
+    models: [{
+        directory,
+        entryPath,
+        members: [{path, nativePath, available}],
+        missingMembers: [],
+        complete: true,
+        source: 'directory', // or 'catalog' or 'acquisition'
+        catalogId // present for a matching caller-owned catalog entry
+    }]
+}
+```
+
+Ordinary `.gguf` files are candidates. Split names such as
+`moon-00001-of-00003.gguf` form one candidate with all expected members in numeric
+order, including explicit missing members. The first shard is `entryPath`,
+including when a completed acquisition declared only later shards or listed
+them out of order. Acquisition candidates retain all their ordinary and
+companion members alongside these required shards; separate filename groups
+are never inferred to be one model. Symlinked model files and directories are
+followed, with already visited directory targets reused rather than rescanned.
+Discovery does not establish a model's role, runtime compatibility or successful
+inference. Those selections remain with the application and engine owners.
+
+Catalog entries are `{id,members:[{path,url?}],archives?,entryPath?}`. They describe
+an exact companion set and can include nested tokenizer files or multiple model
+files. A discovered catalog candidate reports every expected member, including
+missing companions. Completed native acquisition records are also discoverable;
+when the catalog supplies URLs or archive member names, acquisition matching
+also preserves those recorded source selections. A different pinned source with
+the same filenames is not relabeled as that catalog selection. Path-only catalogs
+and ordinary installed-directory candidates make no source-revision claim.
+Unfinished acquisition attempts are ignored. Discovery never removes either.
+Set `recursive:false` for a directory-only inspection. Missing root directories
+are reported with `exists:false`; other root access failures include their
+complete serialized error. A failure while reading a descendant is surfaced.
+
+`openExisting({id,directory,members:[{path}],signal})` opens a complete selected
+set as an ordinary ready projection. It rechecks every member and reports
+`MODEL_ASSET_MEMBERS_MISSING` with `members` when files are absent. It performs
+no copy or network request. Engines use the same `retain(id)` lifecycle.
+Preparation release, engine unload and service disposal never delete borrowed
+originals. External edits or deletion remain controlled by the files' owner.
+
+The application supplies persistent model directories separately from disposable
+build output. The native launch context exposes its platform-specific
+`modelsDirectory`; apps may additionally inspect selected application directories.
+The model-assets service creates no platform directory policy of its own.
+
+`resolveNativeLaunchContext({appId,context})` defaults `modelsDirectory` to
+`Models` beneath the resolved persistent `stateRoot`. It preserves an explicitly
+supplied `modelsDirectory` unchanged and creates or migrates no files:
+
+| Host | Default application state root |
+| --- | --- |
+| Windows | `%LOCALAPPDATA%/Arcane/<appId>`; the user's `AppData/Local` when that environment variable is absent |
+| macOS | `~/Library/Application Support/Arcane/<appId>` |
+| Linux | `$XDG_DATA_HOME/Arcane/<appId>` when absolute, otherwise `~/.local/share/Arcane/<appId>` |
+| Android or another host adaptation | The host supplies its explicit app-private `stateRoot` |
+
+Pass this `modelsDirectory` as the acquisition `workingDirectory` and as one
+discovery directory. Completed files then live beneath its `model-assets`
+subdirectory, separate from replaceable application builds. Additional selected
+application directories can participate in the same discovery call.
+
+### Prepare a selected local runtime on demand
+
+`createLocalAIService(configuration,{autoStart:false,...options})` registers the
+existing local-AI owner without preparing or starting its selected runtimes at
+Core startup. The default remains `autoStart:true`, preserving existing startup
+behavior. After the user explicitly requests preparation, invoke
+`client.invoke('localai.prepare', {}, {signal,timeoutMs:0})`. The operation uses
+the configured existing runtime preparation callback and returns the current
+local-AI state; it does not invent a runtime or model selection.
+
+Preparation callback events are published as `localai.preparation` with their
+complete original event payload. Subscribe through the existing Core event
+owner to display actual preparation phases. Concurrent preparation requests
+reuse the owner's in-flight work, and subsequent completed calls reuse its
+prepared state. Runtime and model selection, explicit model acquisition and
+microphone activation remain app-owned; preparation is not an inference or
+microphone operation. Rendering the interface and
+discovering installed files need not wait for runtime preparation.
+
+### Browser discovery and explicit download
+
+`arcane-os/ai/core-model-assets` additionally exports
+`discoverCoreModelAssets({client,directories,catalog,recursive,signal})`,
+`openExistingCoreModelAssets({client,directory,members,signal})`, and
+`downloadCoreModelAssets({client,workingDirectory,members,archives,refresh,signal,onProgress})`.
+`client` defaults to the installed Core client. Discovery returns the native
+record above; opening and downloading return `{id,directory,members,release}`.
+The existing Blob-based `prepareCoreModelAssets` keeps its original contract.
+
+Download progress callbacks receive the complete semantic progress record,
+correlated to this preparation and observed in order. Callback failure cancels
+the operation. Cancellation joins explicit native cleanup and local callback
+delivery before the helper settles; cleanup failures remain observable.
+Callbacks must not await their own enclosing preparation or cancellation join.
+Applications initiate downloads explicitly and display actual phases, selected
+member paths, completed-file counts and errors in the appropriate surface.
 
 `release(id)` relinquishes preparation ownership without a request signal.
 Same-process callers sharing the actual store, complete source selection and
@@ -186,7 +338,8 @@ try {
 ```
 
 `createModelAssetService({appRoot})` returns a Core service with `current()`,
-`prepare(options)`, `retain(id)`, `release(id)` and `dispose()`. `retain()` accepts only a completed projection
+`discover(options)`, `openExisting(options)`, `prepare(options)`, `retain(id)`,
+`release(id)` and `dispose()`. `retain()` accepts only a completed projection
 and returns `{id,directory,members,release}`. A native engine takes this handle
 before loading and releases it after actual unload, failed-load cleanup or
 worker exit. A rejected inference/load promise alone does not establish native
@@ -249,6 +402,10 @@ for source selection, cancellation and complete row/output contracts.
 | Method | Parameters | Result |
 | --- | --- | --- |
 | `modelAssets.open` | `{id,workingDirectory,members:[{path}]}` | Preparing projection and native member paths |
+| `modelAssets.discover` | `{directories,catalog?,recursive?}` | Directory status and complete/incomplete model candidates |
+| `modelAssets.openExisting` | `{id,directory,members:[{path}]}` | Ready retained projection of existing originals |
+| `modelAssets.prepare` | `{id,workingDirectory,members,archives?,refresh?}` | Ready persistent acquisition; request-scoped `modelAssets.progress` emits `{id,progress}` |
+| `modelAssets.cancelPrepare` | `{id}` | Cancel and join the matching native preparation, then release its preparation ownership |
 | `modelAssets.write` | `{id,memberIndex,contentBase64}` | `{id,memberIndex,written:true}` after the native write |
 | `modelAssets.complete` | `{id}` | Ready projection after all files close |
 | `modelAssets.release` | `{id}` | Released preparation ownership; native uses may retain the files |
@@ -258,6 +415,10 @@ The browser helper owns this transport sequence. Correlation IDs identify
 operations; they are unrelated to content identity. Original model files remain
 separate and complete. A retry creates a new working projection from the stored
 assets; it does not redownload them or replace the authoritative DBOPFS record.
+`cancelPrepare` and `release` have service lifetime so cancellation of the
+original request cannot cancel its cleanup control. Native preparation follows
+the original request signal, including connection cancellation; raw RPC callers
+join `cancelPrepare` when cancelling and release any successful unused projection.
 
 The implementation uses browser streams, the existing portable Core JSON
 transport and Node filesystem operations. Native paths and cleanup follow the

package/docs/reference/native-speech.md

@@ -1,6 +1,6 @@
 # Native speech service
 
-`createSpeechService({stt, tts, signal} = {})` composes independently selected
+`createSpeechService({stt, tts, signal, autoLoad = true} = {})` composes independently selected
 native speech engines into one Core service. It is the named and default export
 from `arcane-os/core/speech`.
 
@@ -50,6 +50,13 @@ independently. It returns immediately, allowing Core and `speech.status` to
 respond while models load. A failure in one role leaves the other role usable.
 Each engine publishes the actual state of its selected model.
 
+Use `autoLoad: false` when the host first needs the user to select or download
+model files. Startup still subscribes and exposes the ordinary unloaded state;
+it does not call either engine's `load()`. Explicit `speech.load({role,
+...selection})` activates the prepared role afterward. The default remains
+`true` for existing hosts. This option changes service startup, not the selected
+engine's missing-model errors or inference readiness requirement.
+
 `current()` and `speech.status` return the same snapshot:
 
 | Field | Meaning |
@@ -66,9 +73,10 @@ An engine's state includes `providerId`, `modelId`, `state`, `loaded`, and
 `busy`, with its complete error or progress information when present. An
 omitted role has `state: 'unavailable'`, `loaded: false`, and `busy: false`.
 File presence, a spawned process, and a callable bridge do not establish loaded
-model readiness. Existing readiness consumers additionally recognize
-the engine IDs `whisper.cpp` and `kokoro-onnx`; another engine ID requires the
-corresponding consumer integration.
+model readiness. The shared AI adapter follows the selected engine identity
+and model in these per-role snapshots, including Nemotron and Magpie. Only the
+older aggregate-only fallback retains fixed `whisper.cpp`/`whisper-small` and
+`kokoro-onnx`/`kokoro` expectations.
 
 Each role also reports `supportsStreaming`: STT requires the configured
 engine's `openStream()` method, and TTS requires its `synthesizeStream()` method.
@@ -288,6 +296,99 @@ share one shutdown promise. Actual engine cleanup failures reject with an
 releases the service's event subscriptions. New work after shutdown begins
 rejects with `CORE_CLOSING`.
 
+## Selected NeMo model acquisition
+
+`NEMO_SPEECH_MODELS`, `prepareNemotronModels`, and `prepareMagpieModels` are
+named exports from `arcane-os/local-ai/nemotron`. Importing them performs no
+network access, installation, model loading, or inference. The catalog records
+NVIDIA's selected [NeMo-Speech.cpp v0.2.0 model index](https://github.com/NVIDIA/NeMo-Speech.cpp/blob/v0.2.0/models/index.json):
+
+| Role | Complete default selection |
+|---|---|
+| `stt` | Nemotron 3.5 streaming ASR Q8_0 and Nemotron 3 Diarization Q8_0. |
+| `tts` | Magpie multilingual v2607 F16, NanoCodec 22 kHz F16 decoder, and all ten matching tokenizer/configuration/speaker-map members from the same Magpie revision. |
+
+Each role exposes `{modelId, providerId, name, members, resourcePaths}`.
+`members` contains ordered `{path, url}` file sources. TTS also exposes
+`archives`, with the upstream uncompressed `.nemo` TAR source, its selected
+transport ranges, and exact `{path, member}` tokenizer entries. The shared
+[model-assets service](model-assets.md) owns discovery, acquisition, progress,
+cancellation, persistence, and projection lifetime; these helpers do not create
+another downloader or store. Tokenizer files retain their complete original
+contents. The selected tokenizer configuration and its referenced JSON speaker
+map continue to own voice IDs.
+
+```js
+import {createNemotronRuntime, prepareNemotronModels} from 'arcane-os/local-ai/nemotron';
+import {createSpeechService} from 'arcane-os/core/speech';
+
+const stt = createNemotronRuntime({runtime, modelAssets, gpu: -1});
+const speech = createSpeechService({stt, autoLoad: false});
+// Run this only for the user's explicit model preparation action.
+const prepared = await prepareNemotronModels({
+  modelAssets,
+  workingDirectory: modelsDirectory,
+  directories: [modelsDirectory, appModelsDirectory],
+  signal,
+  onProgress: showModelProgress
+});
+try {
+  await stt.load({
+    assetProjectionId: prepared.assetProjectionId,
+    resourcePaths: prepared.resourcePaths,
+    signal
+  });
+} finally {
+  await prepared.release();
+}
+```
+
+Both preparation helpers accept `{modelAssets, workingDirectory, directories,
+id, signal, onProgress, refresh = false}`. With `directories`, they ask the
+shared owner for the first complete matching catalog selection in those roots
+before downloading. `openExisting()` borrows its original files and never
+deletes them. Incomplete selections stay visible through the owner's discovery
+results and are not mistaken for a complete model. When no complete match is
+available, the existing acquisition path prepares the complete selected set;
+its completed downloads remain reusable. Explicit `refresh: true` requests a
+fresh acquisition. The host chooses the roots: its portable native launch
+context supplies `modelsDirectory` under the resolved per-user `stateRoot` by
+default, while explicit directory overrides remain supported. An application
+may include its own `models` directory among the discovery roots.
+
+The result is `{assetProjectionId, directory, members, resourcePaths, release}`.
+`release()` is idempotent and releases preparation ownership. Each engine
+retains the projection synchronously when `load()` accepts it, so the caller
+may release its preparation after starting that load. Nemotron accepts
+`modelAssets`, `assetProjectionId`, and `resourcePaths` in its constructor and
+`assetProjectionId`/`resourcePaths` in `load()`, with roles `{model, diarization}`.
+Magpie uses `{model, codec, tokenizerConfig}`. Native file paths still work
+through the engines' existing options. Nemotron requires unloading before
+changing an active selection; its retained files are released only after
+native work and helper exit have joined. Load failures also join asset cleanup,
+and cleanup failures remain observable.
+
+`onProgress` receives ordered, awaited shared-owner phase and file-completion
+events, including reuse and ready for installed selections. Signal cancellation
+stops that preparation's work; an abort after projection creation releases it
+before rejecting. Engine load cancellation remains separate: cancelling the
+caller's wait does not cancel a shared activation; explicit engine unload/close
+owns that cancellation.
+
+The default GGUF selections are individual complete upstream files. The shared
+owner also discovers ordered GGUF shard sets and reports their missing members;
+HTTP range transfers and tokenizer TAR ranges are transport mechanisms, not
+additional model shards. A discovered shard set alone does not establish that a
+selected native engine can load that model. The engine remains the authority
+for model compatibility and actual readiness.
+
+The [upstream native runtime](https://github.com/NVIDIA/NeMo-Speech.cpp/blob/v0.2.0/docs/install.md)
+provides Windows, Linux, and macOS distributions. Model files and that runtime
+remain separate upstream assets, not vendored SDK payloads. This acquisition
+integration received source review only; no download, inference, or new platform
+execution is claimed here. See the [Nemotron](native-nemotron.md) and
+[Magpie](native-magpie.md) contracts for native preparation and execution evidence.
+
 ## Native Kokoro engine
 
 `createNativeKokoroRuntime` is the named and default export from