arcane-os 0.96.0 → 0.97.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.97.1
+
+- Extract repeated selected TAR members in order, retaining the last complete
+  occurrence instead of rejecting valid upstream model companion archives.
+- Preserve earlier extracted files through interrupted replacements and replay
+  unfinished archive selections on retry. Completed archive selections remain
+  reusable while independent model files resume their own transfers.
+
+## 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

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.96.0` SDK contract. Development applications declare
+This checkout defines the `0.97.1` 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

@@ -63,6 +63,11 @@ async function prepareNativeProjection(client, method, params, {signal, onProgre
         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];

package/docs/reference/README.md

@@ -84,6 +84,10 @@ alone does not make bare module names resolve in a browser.
 | 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) |
@@ -92,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) |

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

@@ -341,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` |
@@ -355,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

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

@@ -1,17 +1,113 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.95.0",
+  "sdkVersion": "0.97.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 322,
+  "memberCount": 328,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "local-ai-nemotron:NEMO_SPEECH_MODELS",
+      "name": "NEMO_SPEECH_MODELS",
+      "displayName": "NEMO_SPEECH_MODELS",
+      "kind": "constant",
+      "signature": "NEMO_SPEECH_MODELS",
+      "entrypoints": [
+        "arcane-os/local-ai/nemotron"
+      ],
+      "primaryImport": "arcane-os/local-ai/nemotron",
+      "group": "Core native speech",
+      "summary": "Describes the selected complete Nemotron and Magpie upstream model companions.",
+      "availability": "Node; importing this catalog performs no I/O",
+      "protocol": "Selected NVIDIA NeMo-Speech.cpp 0.2.0 model catalog",
+      "normalization": "stt selects ASR and diarization; tts selects Magpie, NanoCodec and ten tokenizer/configuration members. Each record exposes modelId, providerId, name, members, resourcePaths and optional archives. No acquisition, runtime install, device choice or inference occurs at import."
+    },
+    {
+      "id": "local-ai-nemotron:prepareNemotronModels",
+      "name": "prepareNemotronModels",
+      "displayName": "prepareNemotronModels()",
+      "kind": "function",
+      "signature": "prepareNemotronModels({modelAssets,workingDirectory,directories,id,signal,onProgress,refresh=false}={})",
+      "entrypoints": [
+        "arcane-os/local-ai/nemotron"
+      ],
+      "primaryImport": "arcane-os/local-ai/nemotron",
+      "group": "Core native speech",
+      "summary": "Explicitly prepares the complete ASR and diarization catalog selection.",
+      "availability": "Node with the existing model-assets service",
+      "protocol": "Native model-assets discovery and persistent preparation",
+      "normalization": "Resolves assetProjectionId, directory, members, resourcePaths and idempotent asynchronous release(). An omitted id is generated. Optional directories are searched first unless refresh:true; the first complete matching catalog selection is borrowed, otherwise shared prepare acquires the complete set beneath workingDirectory/model-assets. Ordered asynchronous onProgress forwards native acquisition resume/restart/wait/activity and terminal records. Direct installed-directory reuse retains phase/completed/total/unit:'files' records for reuse then ready. The shared owner retains completed members and closed partials after interruption/cancellation; explicit retry follows its conditional HTTP continuation and single-member restart rules, with same-selection cross-process coordination. Caller cancellation is independent while another interested caller remains; final cancellation joins I/O and retains resumable data. Engines retain actual use; callers release preparation ownership after retention. Borrowed originals and complete acquisitions remain stored. No runtime install, device choice, microphone or inference."
+    },
+    {
+      "id": "local-ai-nemotron:prepareMagpieModels",
+      "name": "prepareMagpieModels",
+      "displayName": "prepareMagpieModels()",
+      "kind": "function",
+      "signature": "prepareMagpieModels({modelAssets,workingDirectory,directories,id,signal,onProgress,refresh=false}={})",
+      "entrypoints": [
+        "arcane-os/local-ai/nemotron"
+      ],
+      "primaryImport": "arcane-os/local-ai/nemotron",
+      "group": "Core native speech",
+      "summary": "Explicitly prepares Magpie, NanoCodec and all matching tokenizer companions.",
+      "availability": "Node with the existing model-assets service",
+      "protocol": "Native model-assets discovery and persistent preparation",
+      "normalization": "Same discovery, preparation, cancellation, ordered progress and release contract as prepareNemotronModels, using NEMO_SPEECH_MODELS.tts. Resolves assetProjectionId, directory, members, resourcePaths and release; resourcePaths contains model, codec and tokenizerConfig. The shared TAR owner extracts ten selected tokenizer/configuration members from upstream ranges while preserving complete files. Retry preserves completed companions and replays required TAR segment framing; ordinary model members use the shared conditional HTTP resume rules. Native acquisition reports its semantic states while direct installed-directory reuse keeps the existing phase/file-count records. Voice, language and device remain caller-owned; preparation performs no synthesis."
+    },
+    {
+      "id": "core-model-assets:discoverCoreModelAssets",
+      "name": "discoverCoreModelAssets",
+      "displayName": "discoverCoreModelAssets()",
+      "kind": "function",
+      "signature": "discoverCoreModelAssets({client=getInstalledCoreClient(),directories,catalog,recursive,signal}={})",
+      "entrypoints": [
+        "arcane-os/ai/core-model-assets"
+      ],
+      "primaryImport": "arcane-os/ai/core-model-assets",
+      "group": "Core model assets",
+      "summary": "Discovers installed native model sets and companions in explicit directories.",
+      "availability": "Browser with an available model-assets Core service",
+      "protocol": "arcane/1 modelAssets.discover",
+      "normalization": "Resolves the native directories/models result unchanged, including ordered GGUF shards, missingMembers, completeness and catalog/acquisition source records. Directories and catalogs remain application-owned; filesystem availability does not establish model selection or readiness. No download, copy, move or engine load. Missing Core reports ARCANE_MODEL_ASSETS_CORE_UNAVAILABLE; actual operation and cancellation failures remain observable."
+    },
+    {
+      "id": "core-model-assets:openExistingCoreModelAssets",
+      "name": "openExistingCoreModelAssets",
+      "displayName": "openExistingCoreModelAssets()",
+      "kind": "function",
+      "signature": "openExistingCoreModelAssets({client=getInstalledCoreClient(),directory,members,signal}={})",
+      "entrypoints": [
+        "arcane-os/ai/core-model-assets"
+      ],
+      "primaryImport": "arcane-os/ai/core-model-assets",
+      "group": "Core model assets",
+      "summary": "Opens a complete borrowed projection without copying installed model originals.",
+      "availability": "Browser with an available model-assets Core service",
+      "protocol": "arcane/1 modelAssets.openExisting and modelAssets.release",
+      "normalization": "Generates its projection id and resolves id, directory, members and idempotent asynchronous release(). Native engines retain their own use; borrowed originals remain intact. Missing members report MODEL_ASSET_MEMBERS_MISSING with the complete list. Cancellation joins uncancelled release before rejecting; actual Core and cleanup failures remain observable."
+    },
+    {
+      "id": "core-model-assets:downloadCoreModelAssets",
+      "name": "downloadCoreModelAssets",
+      "displayName": "downloadCoreModelAssets()",
+      "kind": "function",
+      "signature": "downloadCoreModelAssets({client=getInstalledCoreClient(),workingDirectory,members,archives,refresh=false,signal,onProgress}={})",
+      "entrypoints": [
+        "arcane-os/ai/core-model-assets"
+      ],
+      "primaryImport": "arcane-os/ai/core-model-assets",
+      "group": "Core model assets",
+      "summary": "Acquires a complete native model selection with correlated progress and joined cancellation.",
+      "availability": "Browser with an available model-assets Core service",
+      "protocol": "arcane/1 modelAssets.prepare/cancelPrepare/release and modelAssets.progress",
+      "normalization": "Generates its projection id and resolves id, directory, members and idempotent asynchronous release(). The native owner acquires complete ordinary and TAR-selected companions; full request-correlated semantic progress awaits asynchronous callbacks in order, including actual wait/resume/restart/heartbeat/stall and terminal states. Cancellation or callback failure joins native cancelPrepare cleanup and callback delivery before settlement; actual cleanup failures remain observable. On Core preparation failure, already queued terminal progress is delivered before internal cleanup cancellation and helper rejection. Explicit caller cancellation preserves the no-late-callback boundary. Release relinquishes preparation ownership while completed downloads remain stored; interrupted/cancelled transfers retain completed members and closed partials for explicit retry under the native owner's conditional HTTP continuation/member-restart rules. Same-selection cross-process acquisition is owned by the native service, not a separate browser downloader. No implicit model, runtime or device selection."
+    },
     {
       "id": "core-document-acquisition:createDocumentAcquisitionService",
       "name": "createDocumentAcquisitionService",
@@ -255,7 +351,7 @@
       "name": "createNemotronRuntime",
       "displayName": "createNemotronRuntime()",
       "kind": "function",
-      "signature": "createNemotronRuntime({runtime,prepare,modelId='nemotron-3.5-asr-streaming-0.6b',modelPath,diarizationModelPath,gpu,onEvent}={})",
+      "signature": "createNemotronRuntime({runtime,prepare,modelId='nemotron-3.5-asr-streaming-0.6b',modelPath,diarizationModelPath,modelAssets,assetProjectionId,resourcePaths,gpu,onEvent}={})",
       "entrypoints": [
         "arcane-os/local-ai/nemotron"
       ],
@@ -264,7 +360,7 @@
       "summary": "Retains one native recognizer and optional diarizer across explicit utterance endpoints.",
       "availability": "Node with a matching first-party helper, selected NeMo ASR runtime and models; Windows/Linux/macOS source, Android host adaptation",
       "protocol": "Native ASR C ABI through one retained helper and replaying nemotron.state",
-      "normalization": "Returns current/subscribe/load/unload/transcribe/openStream/close. Exact ordered Float32 or f32le input uses the actual declared sample rate; complete snapshots retain alternatives, words, timestamps and speaker scope. forceEndpoint preserves the native stream; finish drains terminally. Callback joins reject NEMOTRON_CALLBACK_WAIT. Cancellation joins cleanup and exposes resetRequired when an in-flight native call requires helper termination; explicit load is required afterward. No microphone, semantic completion or fallback."
+      "normalization": "Returns current/subscribe/load/unload/transcribe/openStream/close. Exact ordered Float32 or f32le input uses the actual declared sample rate; complete snapshots retain alternatives, words, timestamps and speaker scope. forceEndpoint preserves the native stream; finish drains terminally. Callback joins reject NEMOTRON_CALLBACK_WAIT. Cancellation joins cleanup and exposes resetRequired when an in-flight native call requires helper termination; explicit load is required afterward. No microphone, semantic completion or fallback. Optional modelAssets and completed assetProjectionId select exact resourcePaths.model and optional resourcePaths.diarization members. Load retains that projection before yielding through actual helper cleanup; callers may release preparation ownership after loading begins. An active selection must be unloaded before replacement; direct paths remain supported."
     },
     {
       "id": "local-ai-nemotron:default",
@@ -551,14 +647,14 @@
       "name": "createSpeechService",
       "displayName": "createSpeechService()",
       "kind": "function",
-      "signature": "createSpeechService({stt,tts,signal}={})",
+      "signature": "createSpeechService({stt,tts,signal,autoLoad=true}={})",
       "entrypoints": ["arcane-os/core/speech"],
       "primaryImport": "arcane-os/core/speech",
       "group": "Core native speech",
       "summary": "Composes host-supplied transcription and synthesis engines with independent loading and role readiness.",
       "availability": "Node Core with explicitly supplied engines; engine platform, model and format support remain engine-owned",
       "protocol": "arcane/1 speech.status/load/unload/transcribe/synthesize; optional open/push/endpoint/finish/cancel/synthesizeStream/audioConsumed/cancelSynthesis with speech.state/progress/opened/transcription/audio",
-      "normalization": "Returns current/subscribe/close/start/methods/drain/dispose; forwards complete requests and results unchanged; replaying service state, synchronous accepted Thinking, combined request/lifetime cancellation and concurrent joined engine shutdown. Explicit load/unload require role stt or tts and forward the remaining activation fields and complete result through that role's configured engine; supported preparation remains with that engine. Per-role supportsStreaming reflects actual engine methods independently of readiness. Request-scoped streaming retains exact PCM and unchanged snapshots; endpoint preserves stream scope, terminal finish drains, and cancellation joins native ownership. Awaited TTS audio acknowledgements apply producer backpressure without blocking control traffic. ASR finals do not decide conversation completion. Startup waiting is independently owned from caller cancellation; no automatic provider selection is introduced."
+      "normalization": "Returns current/subscribe/close/start/methods/drain/dispose; forwards complete requests and results unchanged; replaying service state, synchronous accepted Thinking, combined request/lifetime cancellation and concurrent joined engine shutdown. Explicit load/unload require role stt or tts and forward the remaining activation fields and complete result through that role's configured engine; supported preparation remains with that engine. Per-role supportsStreaming reflects actual engine methods independently of readiness. Request-scoped streaming retains exact PCM and unchanged snapshots; endpoint preserves stream scope, terminal finish drains, and cancellation joins native ownership. Awaited TTS audio acknowledgements apply producer backpressure without blocking control traffic. ASR finals do not decide conversation completion. Startup waiting is independently owned from caller cancellation; no automatic provider selection is introduced. autoLoad:false exposes subscriptions and role capabilities without startup loads; explicit speech.load activates the selected role. Omission preserves independent automatic startup loading."
     },
     {
       "id": "core-speech:default",
@@ -655,8 +751,8 @@
       "group": "Core model assets",
       "summary": "Owns persistent native model acquisitions, temporary browser projections and actual engine retain lifetimes.",
       "availability": "Node Core with an application-selected working directory",
-      "protocol": "arcane/1 modelAssets.open/write/complete/release/status and modelAssets.state",
-      "normalization": "Returns current/prepare/retain/release/dispose and Core service lifecycle. Explicit prepare({id,workingDirectory,members:[{path,url}],signal,onProgress,refresh=false}) reuses complete exact ordered source selections stored beneath workingDirectory/model-assets or streams every selected upstream member concurrently. Complete acquisitions survive release, disposal and restart. refresh:true acquires a separate complete set without overwriting retained originals; ordinary reuse makes no network freshness claim. Matching same-process callers share acquisition with independent callbacks/cancellation, and the final interested cancellation joins unfinished I/O before removing only that attempt. Separate processes may fetch independently. release(id) relinquishes live preparation ownership; actual native retain lifetimes remain. Browser open/write/complete projections retain temporary cleanup after final native use. Startup downloads nothing; no migration, eviction or partial-transfer resumption."
+      "protocol": "arcane/1 modelAssets.open/write/complete/release/status/discover/openExisting/prepare/cancelPrepare, modelAssets.state and modelAssets.progress",
+      "normalization": "Returns current/discover/openExisting/prepare/retain/release/dispose and Core service lifecycle. Explicit prepare({id,workingDirectory,members=[],archives=[],signal,onProgress,refresh=false}) acquires complete ordered ordinary {path,url} members and optional {url,format:'tar',ranges?,members:[{path,member}]} archive selections, including PAX paths. Complete exact ordered source selections beneath workingDirectory/model-assets are reused without a network freshness check and persist through release, disposal and restart; refresh:true selects a separate acquisition. Interrupted/cancelled transfers retain completed final members and closed partials; retry resumes the same recorded attempt and downloads only missing members. Ordinary HTTP continuation uses retained strong ETag or Last-Modified with Range/If-Range; matching 206 appends, while 200/416/no validator/prior encoded content restarts only that member and retains one earlier partial until replacement succeeds. TAR segment replay preserves completed companions. Transport framing remains internal. Same-process matching callers share acquisition with independent callbacks/cancellation; cancelling one leaves others running, and the final cancellation joins I/O while retaining resumable data. Same-selection processes coordinate their recorded transfer owner, wait, then reuse/resume after release or exit; unrelated transfers stay concurrent. Complete member promotion follows stream/file close; readiness follows all members. Native progress includes phase/state/message/completed/total/unit:'files' and optional memberIndex/path/reason/recovery/error/activity. Phases open/download/reuse/resume/restart/complete/ready/waiting/heartbeat/stalled/interrupted/cancelled/failed expose actual work; five-second heartbeat and stalled after fifteen seconds without source activity do not diagnose an outage or invent percentages. Plain message/recovery are user-facing; complete error remains diagnostic. discover reads explicit directories/catalogs and reports complete model records, ordered GGUF shards and missing companions without load/download/origin claims beyond supplied selections. Readable symlinks use real-path cycle detection. openExisting borrows complete originals, reports MODEL_ASSET_MEMBERS_MISSING with full missing members, and never removes originals. release relinquishes preparation ownership while native retains continue through actual use; browser open/write/complete projections retain their original temporary cleanup. Core exposes discover/openExisting/prepare/cancelPrepare and request-correlated modelAssets.progress; cancelPrepare joins cleanup. Startup downloads nothing; no automatic migration or eviction."
     },
     {
       "id": "core-model-assets-service:default",
@@ -789,14 +885,14 @@
       "name": "createLocalAIService",
       "displayName": "createLocalAIService()",
       "kind": "function",
-      "signature": "createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent,prepare,executionDevices}={})",
+      "signature": "createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent,prepare,executionDevices,autoStart=true}={})",
       "entrypoints": ["arcane-os/core/local-ai"],
       "primaryImport": "arcane-os/core/local-ai",
       "group": "Core local AI",
       "summary": "Composes selected native llama.cpp, Ollama and ONNX engines as a Core service with retained process/worker ownership and model lifecycle.",
       "availability": "Node with selected upstream runtime distributions or available configured system services",
       "protocol": "arcane/1 methods and events; llama.cpp OpenAI HTTP/SSE, Ollama native HTTP/NDJSON and ONNX tensor transport",
-      "normalization": "Application-owned runtime and model requirements; optional prepare supplies installed records during this service startup. Optional executionDevices supplies a borrowed catalog to ONNX and llama.cpp; its supplying owner retains catalog disposal responsibility. onnx.load forwards executionPreference and executionTarget with existing model-path resolution, cancellation and omitted-target behavior. getONNXRuntime() returns the actual prepared ONNX owner for native composition after context.getService('local-ai'); callers reacquire after recovery and retain the acquired handle for cleanup. llama.load({model,assetProjectionId,resourcePaths,executionTarget}) retains resourcePaths.model from the existing model-assets owner through actual managed process exit. Omitted target retains the same model's selection or configured default; null requests the runtime default. Explicit Windows NVIDIA targets resolve this host's deviceId to its CUDA device identity; unsupported or unavailable selections report their actual failure without substitution. execution distinguishes requested/resolved/configured targets from observedTarget:null. Existing external listeners retain their model/device ownership and reject managed reconfiguration. llama.status/models observe without starting or restarting an engine. Independent services, complete responses and exact owned-process cleanup remain unchanged."
+      "normalization": "Application-owned runtime and model requirements; optional prepare supplies installed records during this service startup. Optional executionDevices supplies a borrowed catalog to ONNX and llama.cpp; its supplying owner retains catalog disposal responsibility. onnx.load forwards executionPreference and executionTarget with existing model-path resolution, cancellation and omitted-target behavior. getONNXRuntime() returns the actual prepared ONNX owner for native composition after context.getService('local-ai'); callers reacquire after recovery and retain the acquired handle for cleanup. llama.load({model,assetProjectionId,resourcePaths,executionTarget}) retains resourcePaths.model from the existing model-assets owner through actual managed process exit. Omitted target retains the same model's selection or configured default; null requests the runtime default. Explicit Windows NVIDIA targets resolve this host's deviceId to its CUDA device identity; unsupported or unavailable selections report their actual failure without substitution. execution distinguishes requested/resolved/configured targets from observedTarget:null. Existing external listeners retain their model/device ownership and reject managed reconfiguration. llama.status/models observe without starting or restarting an engine. Independent services, complete responses and exact owned-process cleanup remain unchanged. autoStart:false leaves selected engines unprepared and unstarted at Core startup. Explicit localai.prepare invokes configured preparation, emits complete localai.preparation events, starts configured engines and returns current state. Concurrent callers share preparation and completed preparation is reused; engine/model readiness remains separate. Omission preserves startup preparation."
     },
     {
       "id": "core-local-ai:default",
@@ -4712,7 +4808,7 @@
       "summary": "Creates the SDK-owned provider that assembles one selected app and explicit services into a portable Core payload.",
       "availability": "Node; produces a portable payload rather than an executable host",
       "protocol": "arcane-native-builder/1 portable provider",
-      "normalization": "Preserves complete selected app and dependency releases; an explicit services selection overrides appDescriptor.native.services, otherwise the descriptor selection is used; optional appDescriptor.native.window carries positive integral logical client width/height, optional resizable and optional state normal/maximized/fullscreen into manifest.window with omitted fields preserved; the selected platform host owns the applied behavior. Generated coreListener opt-in composes one passive model-observation service from the existing host.runtime and actual services exposing localai.status/image.status/decisions.status before listener binding, with absent owners null and renderer attachment separate. Ordinary stdio and sharedHost/headless behavior remains unchanged; no model creation, getService or readiness barrier. Generated runtime/arcane-core.mjs accepts --arcane-app-entry <app-relative-module> through the host's supported Node executable. It imports the packaged app/ module's top-level work with complete process.argv unchanged and no automatic export call; the app owns launch-context reads, services, signals and shutdown. Include the entry and complete source closure through package.nativeResources. The flag skips ordinary Core startup; omission retains it. See mcp-stdio.md#launch-from-a-native-package and core-native-packaging.md#app-owned-runtime-entry. Reports executable:false and never substitutes for an unavailable platform host"
+      "normalization": "Preserves complete selected app and dependency releases; an explicit services selection overrides appDescriptor.native.services, otherwise the descriptor selection is used; optional appDescriptor.native.window carries positive integral logical client width/height, optional resizable and optional state normal/maximized/fullscreen into manifest.window with omitted fields preserved; the selected platform host owns the applied behavior. Generated coreListener opt-in composes one passive model-observation service from the existing host.runtime and actual services exposing localai.status/image.status/decisions.status before listener binding, with absent owners null and renderer attachment separate. Ordinary stdio and sharedHost/headless behavior remains unchanged; no model creation, getService or readiness barrier. Generated runtime/arcane-core.mjs accepts --arcane-app-entry <app-relative-module> through the host's supported Node executable. It imports the packaged app/ module's top-level work with complete process.argv unchanged and no automatic export call; the app owns launch-context reads, services, signals and shutdown. Include the entry and complete source closure through package.nativeResources. The flag skips ordinary Core startup; omission retains it. See mcp-stdio.md#launch-from-a-native-package and core-native-packaging.md#app-owned-runtime-entry. Reports executable:false and never substitutes for an unavailable platform host Build assembles temporarily then publishes at outputRoot/app-id; later successful builds replace only that app. Previous output is retained through completion callback and cancellation acceptance and restored on publication failure. Models and saved state remain in separate persistent directories."
     },
     {
       "id": "native-portable-provider:arcaneNativeBuilderProvider",
@@ -4754,7 +4850,7 @@
       "summary": "Assembles selected application services and browser content with the SDK-owned Windows x64 WebView2 and SEA host.",
       "availability": "Node for assembly; Windows x64 with WebView2 Runtime for execution",
       "protocol": "arcane-native-builder/1 windows-x64 provider",
-      "normalization": "Uses a selected hostDirectory or the exact installed SDK version's numeric release asset; preserves complete payloads; app displayName plus .exe (app ID fallback) and matching .exe.config use Windows filename substitutions only; manifest.host.executable owns inventory, icon, verify and run while generic cache/Core names remain unchanged; native.icon PNG/ICO derives the copied executable and host.icon without an app compiler, while other formats retain assembly with native.icon.unsupported and executableIcon:false; the matching host loads the selected window/taskbar icon and handles window.setTheme with per-field applied/unsupported results; native.window selects initial 96-DPI logical client width/height, optional resizable and optional state normal/maximized/fullscreen through manifest.window. The matching host scales dimensions to actual DPI, fits initial placement to the usable screen and applies an explicit state afterward; omitted fields preserve existing host behavior. Fullscreen fills the selected monitor without a frame and retains normal bounds/frame controls for restoration. Requesting-window window.state/window.setState observe actual minimized/maximized state and prevent activation/focus assignment during visible transitions without selecting TopMost or changing Core, origin or profile. Saved Settings remain application-owned; no saved-bounds subsystem is added and initial-fit logic is not reapplied during later resizing; run cancellation closes stdin and waits for host-owned graceful shutdown. Packaged runtime/ArcaneCore.exe accepts --arcane-app-entry <app-relative-module> directly, without a script argument or GUI launcher; it imports the packaged app/ module's top-level work, preserves complete process.argv and invokes no export. Include the entry and complete source closure through package.nativeResources. The app owns launch-context reads, services, signals and shutdown; the flag skips ordinary Core startup, while omission preserves it. See mcp-stdio.md#launch-from-a-native-package and core-native-packaging.md#app-owned-runtime-entry"
+      "normalization": "Uses a selected hostDirectory or the exact installed SDK version's numeric release asset; preserves complete payloads; app displayName plus .exe (app ID fallback) and matching .exe.config use Windows filename substitutions only; manifest.host.executable owns inventory, icon, verify and run while generic cache/Core names remain unchanged; native.icon PNG/ICO derives the copied executable and host.icon without an app compiler, while other formats retain assembly with native.icon.unsupported and executableIcon:false; the matching host loads the selected window/taskbar icon and handles window.setTheme with per-field applied/unsupported results; native.window selects initial 96-DPI logical client width/height, optional resizable and optional state normal/maximized/fullscreen through manifest.window. The matching host scales dimensions to actual DPI, fits initial placement to the usable screen and applies an explicit state afterward; omitted fields preserve existing host behavior. Fullscreen fills the selected monitor without a frame and retains normal bounds/frame controls for restoration. Requesting-window window.state/window.setState observe actual minimized/maximized state and prevent activation/focus assignment during visible transitions without selecting TopMost or changing Core, origin or profile. Saved Settings remain application-owned; no saved-bounds subsystem is added and initial-fit logic is not reapplied during later resizing; run cancellation closes stdin and waits for host-owned graceful shutdown. Packaged runtime/ArcaneCore.exe accepts --arcane-app-entry <app-relative-module> directly, without a script argument or GUI launcher; it imports the packaged app/ module's top-level work, preserves complete process.argv and invokes no export. Include the entry and complete source closure through package.nativeResources. The app owns launch-context reads, services, signals and shutdown; the flag skips ordinary Core startup, while omission preserves it. See mcp-stdio.md#launch-from-a-native-package and core-native-packaging.md#app-owned-runtime-entry Successful builds publish at outputRoot/app-id through the shared joined replacement lifecycle, retaining previous output through completion/cancellation acceptance and restoring it on failure. Separate runtime caches, models, profiles and unrelated outputs are preserved."
     },
     {
       "id": "native-windows-provider:arcaneNativeBuilderProvider",
@@ -4796,7 +4892,7 @@
       "summary": "Composes a complete selected portable payload with the architecture-selected SDK Mac host in an application bundle.",
       "availability": "Node assembly; matching Darwin architecture and selected host artifact for execution",
       "protocol": "arcane-native-builder/1 macos-arm64 and macos-x64 provider",
-      "normalization": "Resources remains target.rootDir; bundleRoot names the app bundle; selected hostDirectory or exact-version host assets; run closes stdin and awaits graceful drain; source availability does not establish artifact publication or Mac execution"
+      "normalization": "Resources remains target.rootDir; bundleRoot names the app bundle; selected hostDirectory or exact-version host assets; run closes stdin and awaits graceful drain; source availability does not establish artifact publication or Mac execution Accepted bundles use outputRoot/app-id.app; later successful builds replace only that bundle through the joined publication lifecycle, preserving separate model and saved-state directories."
     },
     {
       "id": "native-macos-provider:arcaneNativeBuilderProvider",
@@ -4877,10 +4973,10 @@
       "entrypoints": ["arcane-os/core/host"],
       "primaryImport": "arcane-os/core/host",
       "group": "Native Core host composition",
-      "summary": "Resolves matching per-app native state, workspace and optional shared endpoint defaults for packaged UI and external MCP.",
+      "summary": "Resolves app-private native state/workspace, same-user shared model storage and optional shared endpoint defaults for packaged UI and external MCP.",
       "availability": "Node native locations on Windows/Linux/macOS; Android and other hosts supply stateRoot and native adaptation",
       "protocol": "Pure native launch-context resolution and existing local IPC",
-      "normalization": "Returns a new complete context with only omitted stateRoot/workspaceRoot and selected sharedHost endpoint/log fields filled; preserves explicit values and additional payloads. Native launchContext presence opts generated entry into resolution; omitted sharedHost retains stdio. Optional coreListener:{endpoint} is preserved without endpoint defaults and attaches to that same window-owned runtime in the generated entry; selecting it together with sharedHost reports TypeError there. No I/O, saved-state discovery, process startup, migration or ArcaneData/Repos change. Malformed selected appId/stateRoot/sharedHost inputs report TypeError; platform IPC errors remain operation-owned."
+      "normalization": "Returns a new complete context with only omitted stateRoot/workspaceRoot/modelsDirectory and selected sharedHost endpoint/log fields filled; preserves explicit values and additional payloads. Native launchContext presence opts generated entry into resolution; omitted sharedHost retains stdio. Optional coreListener:{endpoint} is preserved without endpoint defaults and attaches to that same window-owned runtime in the generated entry; selecting it together with sharedHost reports TypeError there. No I/O, saved-state discovery, process startup, migration or ArcaneData/Repos change. Malformed selected appId/stateRoot/sharedHost inputs report TypeError; platform IPC errors remain operation-owned. On Windows/Linux/macOS an omitted modelsDirectory resolves to the operating-system user's shared Arcane/Models directory, independently of app-private stateRoot/workspaceRoot and disposable native output. An explicit stateRoot does not redirect this shared default; explicit modelsDirectory remains unchanged. Other adapted hosts may supply a shared directory, with omitted modelsDirectory retaining absolute stateRoot/Models. This resolver affects its consumers rather than every provider store and creates, moves or migrates no files; applications may separately discover prior app-local originals."
     },
     {
       "id": "core-host:readCoreLaunchContext",

package/docs/reference/model-assets.md

@@ -119,8 +119,9 @@ 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}]`.
 
-Complete acquisitions persist under `workingDirectory/model-assets/` across
-release, native unload, service disposal and process restart. Relative working
+Complete acquisitions and interrupted transfer state persist under
+`workingDirectory/model-assets/` across release, native unload, service disposal
+and process restart. Relative working
 directories resolve from `appRoot`. Reuse matches the entire ordered
 `[{path,url}]` selection in that actual store; the operation `id` is a separate
 live lifetime, not the stored selection. Different URLs, relative paths, member
@@ -136,9 +137,14 @@ untouched. Later ordinary preparations reuse the newer completed selection.
 A failed refresh leaves the earlier completed acquisition available. Refresh
 does not change the selected URLs or imply upstream revision discovery.
 
-Progress uses `open`, `download`, `complete`, `reuse` and `ready` phases, with
-`completed`, `total` and `unit:'files'`; member progress additionally includes
-`memberIndex` and `path`. Progress callbacks may return a promise, which the
+Progress includes `open`, `download`, `resume`, `restart`, `complete`, `reuse`
+and `ready`, plus waiting, heartbeat, stalled and terminal interruption states.
+Records carry `state`, a user-facing `message`, `completed`, `total` and
+`unit:'files'`; member progress additionally includes `memberIndex` and `path`.
+Recovery guidance belongs in `recovery`; a complete serialized `error` belongs
+in developer inspection. A stalled state means no recent transfer activity was
+observed, not that the SDK has established an Internet outage. Render active
+transfers without inventing a per-file percentage. Progress callbacks may return a promise, which the
 preparation observes in order. Each caller owns its callbacks; a slow or failed
 callback does not hold another caller's transfer or result. Callbacks must not
 await cleanup of the preparation currently calling them. Callback failures
@@ -177,6 +183,13 @@ 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.
 
+Repeated selected TAR names follow sequential extraction: the last complete
+occurrence replaces the earlier file only after closing its temporary output.
+An interrupted archive pass retains those files and replays its selected
+segments on retry, so an earlier occurrence is never mistaken for the final
+one. Fully completed archive selections are reused while other model files
+continue their own resumable downloads.
+
 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
@@ -245,21 +258,41 @@ build output. The native launch context exposes its platform-specific
 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:
+one shared location for the operating-system user, independent of the app ID.
+It preserves an explicitly supplied `modelsDirectory` unchanged and creates,
+moves or migrates no files:
 
-| Host | Default application state root |
+| Host | Default shared model directory |
 | --- | --- |
-| 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` |
+| Windows | `%LOCALAPPDATA%/Arcane/Models`; the user's `AppData/Local` when that environment variable is absent |
+| macOS | `~/Library/Application Support/Arcane/Models` |
+| Linux | `$XDG_DATA_HOME/Arcane/Models` when absolute, otherwise `~/.local/share/Arcane/Models` |
+| Android or another host adaptation | `<stateRoot>/Models`; the host supplies an explicit shared `modelsDirectory` when its platform allows sharing |
 
 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.
 
+```javascript
+import {resolveNativeLaunchContext} from 'arcane-os/core/host';
+
+const {modelsDirectory} = resolveNativeLaunchContext({appId: 'moon-radio'});
+const projection = await modelAssets.prepare({
+    id: selectedOperationId,
+    workingDirectory: modelsDirectory,
+    members: selectedMembers,
+    signal,
+    onProgress: renderPreparationProgress
+});
+```
+
+App settings, profiles, chat history, workspace and IPC retain their app-private
+locations. This default applies to applications using the native launch resolver;
+explicit acquisition directories and other provider-owned model stores keep
+their existing contracts. Discover existing app-local models and open them in
+place rather than copying or removing them.
+
 ### Prepare a selected local runtime on demand
 
 `createLocalAIService(configuration,{autoStart:false,...options})` registers the
@@ -290,8 +323,10 @@ 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
+correlated to this preparation and observed in order. On request failure, queued
+terminal progress is delivered before internal cleanup cancellation and promise
+rejection. Explicit caller cancellation retains its no-late-callback boundary.
+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
@@ -303,24 +338,31 @@ refresh mode share an acquisition, including across service instances. They
 keep independent operation IDs, retain handles, cancellation and callbacks.
 Cancelling, releasing or disposing one interested caller leaves the others
 running. The final interested caller aborts the acquisition and joins its
-streams, writes and closes before removing only its unfinished attempt. Original
+streams, writes and closes while preserving completed members and resumable
+partial transfers. Original
 failures and cleanup failures remain observable. A completed acquisition stays
 available even if a caller cancels or its callback fails after completion.
 
-The service records completion only after every selected response and file
-close finishes. That record is ordinary cache state describing the selected
-sources and completed acquisition. A missing original member requires another
-complete acquisition. Failed attempts are removed after their owned I/O drains;
-there is no partial-transfer resumption. An abruptly interrupted process can
-leave an unfinished directory, which later calls ignore without sweeping it.
-There is no automatic migration, eviction or removal of completed acquisitions.
-
-Independent processes use disjoint attempt directories and may fetch the same
-selection concurrently. They do not overwrite each other's files or coordinate
-a cross-process acquisition lock. Concurrent completions can produce multiple
-reusable sets; either complete result may be selected when their completion
-order ties. Applications may retain their existing shared Core owner without
-introducing an additional host or application-local cache copy.
+The service promotes each file from its partial-transfer location only after
+the complete response and file close finish. It records whole-acquisition
+completion after every selected member is complete. These records describe
+ordinary transfer and cache state, not content hashes or admission receipts.
+Retry reuses completed members and resumes saved ordinary-file transfers with
+HTTP Range and available HTTP continuation metadata. HTTP offsets and validators
+remain transport-local and never become progress or model policy. If the source
+cannot continue the saved representation, the SDK reports a restart of that
+member; completed siblings remain available. Selected TAR companions preserve
+completed files; an interrupted member may require replaying its TAR segment to
+restore the archive parser's framing. No full-archive substitute is selected.
+
+Processes selecting the same ordered sources and actual store coordinate a
+short selection operation and one transfer owner. Another process waits with
+observable status rather than starting a duplicate transfer. Cancelling a
+waiting request stops its wait; it does not cancel the other process. If a
+transfer owner exits, a later contender can reclaim its recorded operation and
+continue retained data. This requires no additional application server, copied
+cache implementation or new shared Core process. Existing completed models and
+unrelated attempts are never swept or migrated automatically.
 
 ```javascript
 import {createModelAssetService} from 'arcane-os/core/model-assets';

package/docs/reference/native-speech.md

@@ -350,11 +350,24 @@ 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.
+its completed members and closed partial files remain available after an
+interruption or cancellation. Explicit retry reuses those members and resumes
+ordinary HTTP transfers when the source accepts their conditional range;
+otherwise only that member restarts with an explicit progress event. TAR
+segments replay while completed tokenizer companions remain reusable.
+Matching cross-process selections wait for the actual transfer owner, then
+reuse or resume its recorded attempt; unrelated downloads remain concurrent.
+See [native acquisition and recovery](model-assets.md#native-ownership) for the
+shared owner's complete contract. Explicit `refresh: true` requests a
+fresh acquisition. The host chooses the roots: on Windows, Linux and macOS its
+portable native launch-context resolver defaults `modelsDirectory` to the
+operating-system user's shared `Arcane/Models` directory, independently of
+app-private state and workspace. Explicit directory overrides remain unchanged;
+other adapted hosts supply their shared directory explicitly or retain the
+resolver's app-state fallback. This location applies to services using that
+resolver value, not every provider store. Resolution moves no existing files.
+An application may include its own `models` directory and prior app-local
+model locations among the discovery roots, borrowing those originals in place.
 
 The result is `{assetProjectionId, directory, members, resourcePaths, release}`.
 `release()` is idempotent and releases preparation ownership. Each engine
@@ -369,8 +382,18 @@ 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
+events. Native acquisition includes `state`, plain `message`, file counts and
+optional member, reason, recovery, error or other-owner activity. Its five-second
+heartbeat and fifteen-second no-source-activity `stalled` state describe actual
+transfer observations, not an inferred outage or percentage. `interrupted`,
+`cancelled`, `failed` and `ready` are distinct terminal states. Direct
+installed-directory reuse retains the existing `reuse`/`ready` records with
+`completed`, `total` and `unit:'files'`.
+
+Signal cancellation stops that caller's preparation interest; another interested
+caller may continue the shared acquisition. The final cancellation joins I/O
+and retains resumable data; cancelled subscribers keep their existing callback
+boundary. An abort after projection creation releases preparation ownership
 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.