arcane-os 0.78.0 → 0.79.1

package/docs/reference/native-decisions.md

@@ -58,7 +58,7 @@ name to `decisions`. It exposes `load`, `evaluate`, `classify` (an alias for
 | Method | Parameters and result |
 | --- | --- |
 | `decisions.status` | Current lifecycle snapshot; does not load anything. |
-| `decisions.load` | Explicit activation; returns the ready lifecycle snapshot. The request signal cancels activation. |
+| `decisions.load` | `{executionTarget?}`, where the target is `{deviceId:string}` or `null`; explicit activation or target replacement, returning the ready lifecycle snapshot. The request signal cancels activation. |
 | `decisions.evaluate` | `{rows, runOptions?}`; returns `{decisions, outputs}`. The request signal cancels the active model operation. |
 | `decisions.unload` | Releases the activation. Service-lifetime cleanup continues after the caller disconnects. |
 
@@ -111,12 +111,66 @@ is loaded by this API.
 This graph selection requires `dtype:'fp32'`, which is also the default; another
 dtype reports the incompatible selection rather than substituting a graph.
 `sessionOptions` and `runOptions` pass to the existing native ONNX API unchanged.
-`executionPreference` defaults to `gpu` here: actual advertised native GPU
-provider creation is attempted, followed by an honest CPU fallback. Explicit
-`sessionOptions.executionProviders` takes precedence. The underlying generic
-ONNX factory continues to default to CPU. Accepted provider configuration is
-not evidence that GPU nodes executed. Full provider-attempt diagnostics remain
-in `execution`; see [native ONNX sessions](local-ai.md#native-onnx-sessions).
+With no `executionTarget` selection, `executionPreference` defaults to `gpu`
+here: actual advertised native GPU provider creation is attempted, followed by
+an honest CPU fallback. Explicit `sessionOptions.executionProviders` takes
+precedence on that unchanged path. The underlying generic ONNX factory
+continues to default to CPU. Accepted provider configuration is not evidence
+that GPU nodes executed. Full provider-attempt diagnostics remain in
+`execution`; see [native ONNX sessions](local-ai.md#native-onnx-sessions).
+
+## Select an activation's execution device
+
+Both factories accept `executionTarget: {deviceId:string}` or `null` in their
+configuration. Direct model and service calls accept
+`load({executionTarget, signal})`; the Core `decisions.load` method carries the
+same target in its parameters. Use an actual stable ID from the shared
+[physical device catalog](execution-devices.md), or the documented whole-host
+CPU ID:
+
+```js
+await decisions.load({executionTarget: {deviceId: 'cpu'}});
+// A different explicit selection drains the current activation and replaces it.
+await decisions.load({executionTarget: null});
+```
+
+Omitting `executionTarget`, or supplying `undefined`, retains the most recent
+explicit selection, initially the factory's selection. When neither supplies a
+target, existing constructor, session-option and provider-default behavior
+remains unchanged. Explicit `null` requests automatic device resolution at the
+new activation boundary. It remains distinct from omission. The selection
+stays available for a later explicit load after unloading or a failed load;
+the SDK creates no preference store and does not change application preferences.
+
+The decision owner forwards the target to its existing ONNX owner. That owner
+resolves the physical ID, supported provider and provider-specific address.
+An unavailable or unsupported explicit target reports its actual failure; it
+does not silently select another adapter or a cloud provider. GPU selection
+does not require every graph node to execute on the GPU: supported CPU graph
+partitioning remains an engine concern. See the native ONNX contract for exact
+target routing and automatic-selection behavior.
+
+The existing `current().execution` field remains the complete ONNX session load
+record for that activation. Its `execution` member carries `requestedTarget`,
+`resolvedDevice`, `resolution`, `configuredTarget` and `observedTarget`, alongside
+provider-attempt diagnostics. These distinguish requested selection, physical
+resolution, accepted configuration and actual execution evidence. An unknown
+`observedTarget` remains `null`; successful configuration alone does not establish
+which device executed graph nodes.
+
+`pendingActivation` is separately `null` or `{executionTarget}` while a load or
+replacement is pending; its `executionTarget` property is omitted at JSON
+transport when the selection is `undefined`. A pending target never overwrites the previous
+activation's `execution` record. The old record remains attributable to the
+retiring activation until its cleanup completes, then the new activation owns
+its own record. A request is not a claim that the requested device is running.
+
+Concurrent loads for the same target share their pending activation. A
+different target supersedes the earlier pending request, which rejects with
+cancellation instead of returning another target's ready result. Replacement
+joins this model's actual tokenizer/native cleanup before creating its
+successor. Independent model owners retain their independent workers and
+lifetimes; there is no all-model loading barrier or trial inference.
 
 ## Complete inputs and outputs
 
@@ -148,14 +202,15 @@ runtime; sharing the encoding implementation alone does not establish it.
 ## Lifetime and cancellation
 
 `current()` returns `{family, model, revision, dtype, state, loaded, busy,
-activeRequests, progress, error, execution}`. States include `unloaded`,
+activeRequests, progress, error, execution, pendingActivation}`. States include
+`unloaded`,
 `loading`, `ready`, `unloading`, `disposing`, `disposed` and `error`. Semantic
 progress includes model preparation, tokenization and evaluation; downloaded
 members report files, not byte progress. Complete technical errors belong in
 developer diagnostics, while the application owns its user-facing status.
 
-Concurrent callers share one explicit activation. Cancelling a load or
-evaluation cancels that activation and its outstanding operations, because the
+Concurrent callers selecting the same target share one explicit activation.
+Cancelling a load or evaluation cancels that activation and its outstanding operations, because the
 native session and tokenizer have one owner. Use separately owned models when
 independent cancellation is required. The construction `signal` governs the
 whole model lifetime. `unload()` permits another explicit load after successful

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.78.0",
+  "version": "0.79.1",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -69,6 +69,7 @@
     "./core/preferences": "./src/core/services/preferences.mjs",
     "./core/diarization": "./src/diarization/service.mjs",
     "./core/local-ai": "./src/core/services/local-ai.mjs",
+    "./core/execution-devices": "./src/core/services/execution-devices.mjs",
     "./core/decisions": "./src/core/services/decisions.mjs",
     "./core/image": "./src/core/services/image.mjs",
     "./core/speech": "./src/core/services/speech.mjs",
@@ -77,6 +78,7 @@
     "./diarization/build": "./src/diarization/build.mjs",
     "./local-ai": "./src/local-ai/install.mjs",
     "./local-ai/onnx": "./src/local-ai/onnx.mjs",
+    "./local-ai/execution-devices": "./src/local-ai/execution-devices.mjs",
     "./local-ai/decisions": "./src/local-ai/decisions.mjs",
     "./local-ai/image": "./src/local-ai/image-runtime.mjs",
     "./local-ai/whisper": "./src/local-ai/whisper/index.mjs",
@@ -123,7 +125,7 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/conversation-closing-report.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/native-windows-icon.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/ai-ollama-readiness.test.mjs test/core-ollama-lifecycle.test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-kokoro-complete-input.test.mjs test/browser-speech-providers.test.mjs test/browser-speech-artifacts.test.mjs test/browser-speech-resource-bridge.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/codex-app-server.test.mjs test/mcp-stdio-server.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-client-installation.test.mjs test/core-ai-installation.test.mjs test/core-llama-lifecycle.test.mjs test/core-development.test.mjs test/core-host.test.mjs test/core-shared-host.test.mjs test/core-model-assets.test.mjs test/core-native-services.test.mjs test/core-packaged-web.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-committed-events.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-model-resources.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/local-image-editing.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/model-resource-bridge.test.mjs test/native-decisions.test.mjs test/native-onnx.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/ai-ollama-readiness.test.mjs test/core-ollama-lifecycle.test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-kokoro-complete-input.test.mjs test/browser-speech-providers.test.mjs test/browser-speech-artifacts.test.mjs test/browser-speech-resource-bridge.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/codex-app-server.test.mjs test/mcp-stdio-server.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-client-installation.test.mjs test/core-ai-installation.test.mjs test/core-llama-lifecycle.test.mjs test/core-development.test.mjs test/core-host.test.mjs test/core-shared-host.test.mjs test/core-model-assets.test.mjs test/core-native-services.test.mjs test/core-packaged-web.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-committed-events.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-model-resources.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/execution-devices.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/local-image-editing.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/model-resource-bridge.test.mjs test/native-decisions.test.mjs test/native-onnx.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-macos-provider.test.mjs test/native-plan.test.mjs test/native-portable-provider.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/html-import-packaged-script.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/ai-audio-output.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",

package/src/core/services/decisions.mjs

@@ -4,6 +4,10 @@ import {createArcaneEventSource} from '../../event-manager.mjs';
 import {CoreError} from '../../../browser-runtime/core/contracts.mjs';
 import {encodeTensorMap} from '../../../browser-runtime/ai/onnx-tensors.mjs';
 
+function sameExecutionTarget(left, right) {
+    return left === right || (left != null && right != null && left.deviceId !== undefined && left.deviceId === right.deviceId);
+}
+
 /** App-owned selection; shared typed-decision execution, without a renderer. */
 export function createNativeDecisionService(configuration = {}, {appRoot = process.cwd()} = {}) {
     const events = createArcaneEventSource({}, {source: 'core-decisions', eventTypes: ['decisions.state']});
@@ -15,14 +19,22 @@ export function createNativeDecisionService(configuration = {}, {appRoot = proce
     let releasing;
     let closing;
     let unsubscribe;
+    let selectedTarget = configuration.executionTarget;
+    let loadingTarget;
+    let loadedTarget;
 
     function current() {
-        return model?.current() ?? {
+        const snapshot = model?.current() ?? {
             family: 'laya', model: configuration.model ?? 'onnx-community/laya-typed-decisions-ONNX',
             revision: configuration.revision ?? 'main', dtype: configuration.dtype ?? 'fp32',
             state: closing ? 'disposed' : 'unloaded', loaded: false, busy: Boolean(loading),
             activeRequests: 0, progress: null, error: null, execution: null
         };
+        const pending = Boolean(loading) && (!snapshot.loaded || !sameExecutionTarget(loadedTarget, loadingTarget));
+        return {
+            ...snapshot, busy: snapshot.busy || pending,
+            pendingActivation: pending ? {executionTarget: loadingTarget} : snapshot.pendingActivation ?? null
+        };
     }
 
     function publish(value = current()) {
@@ -39,20 +51,24 @@ export function createNativeDecisionService(configuration = {}, {appRoot = proce
 
     function operationSignal(signal) { return signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal; }
 
-    function load({signal} = {}) {
+    function load({signal, executionTarget: requestedTarget} = {}) {
         operationSignal(signal).throwIfAborted();
         if (!context) throw new CoreError({code: 'CORE_NOT_READY', message: 'Register and start the decision service with Core before loading.'});
-        if (loading) return observeLoad(loading, loadController, signal);
-        if (model?.current().loaded) return Promise.resolve(model.current());
-        loadController = new AbortController();
-        const controller = loadController;
+        const target = requestedTarget === undefined ? selectedTarget : requestedTarget;
+        if (loading && !loadController.signal.aborted && sameExecutionTarget(loadingTarget, target)) return observeLoad(loading, loadController, signal);
+        if (!loading && model?.current().loaded && sameExecutionTarget(loadedTarget, target)) return Promise.resolve(current());
+        const previousLoad = loading;
+        const previousController = loadController;
+        const controller = new AbortController();
         const selectedSignal = AbortSignal.any([lifetime.signal, controller.signal]);
         const precedingRelease = releasing;
-        loading = Promise.resolve().then(async function loadSelectedModel() {
+        const task = Promise.resolve().then(async function loadSelectedModel() {
             selectedSignal.throwIfAborted();
             if (precedingRelease) await precedingRelease;
+            if (previousLoad) await Promise.allSettled([previousLoad]);
             selectedSignal.throwIfAborted();
             if (model) await model.dispose();
+            selectedSignal.throwIfAborted();
             unsubscribe?.();
             // Only the explicit load waits for its native dependencies. Merely
             // registering this service does not download a model or delay UI.
@@ -65,23 +81,43 @@ export function createNativeDecisionService(configuration = {}, {appRoot = proce
                 Object.entries(configuration.paths).map(function nativePath([name, value]) { return [name, path.resolve(appRoot, value)]; })
             );
             model = createNativeDecisionModel({
-                ...configuration, paths, onnx: localAI.getONNXRuntime(), modelAssets,
+                ...configuration, paths, onnx: localAI.getONNXRuntime(), modelAssets, executionTarget: target,
                 signal: lifetime.signal
             });
-            unsubscribe = model.subscribe(publish);
-            return model.load({signal: selectedSignal});
+            unsubscribe = model.subscribe(function modelStateChanged() { publish(); });
+            const result = await model.load({signal: selectedSignal});
+            selectedSignal.throwIfAborted();
+            loadedTarget = target;
+            return result;
         });
-        function settled() { loading = undefined; loadController = undefined; publish(); }
-        loading.then(settled, settled);
+        function settled() {
+            if (loading !== task) return;
+            loading = undefined;
+            loadController = undefined;
+            publish();
+        }
+        task.then(settled, settled).catch(function reportStateFailure(error) { console.error('Native decision state publication failed.', error); });
+        loading = task;
+        loadController = controller;
+        loadingTarget = target;
+        selectedTarget = target;
+        previousController?.abort(new CoreError({name: 'AbortError', code: 'ARCANE_AI_REQUEST_ABORTED', message: 'The native decision activation request was replaced.'}));
         publish();
-        return observeLoad(loading, controller, signal);
+        return observeLoad(task, controller, signal);
     }
 
     function observeLoad(task, controller, signal) {
         function abort() { controller.abort(signal.reason); }
         signal?.addEventListener('abort', abort, {once: true});
         if (signal?.aborted) abort();
-        return task.finally(function detachLoadCaller() { signal?.removeEventListener('abort', abort); });
+        return task.then(function loadedActivation(result) {
+            controller.signal.throwIfAborted();
+            const snapshot = current();
+            if ((loading && loadController !== controller) || !snapshot.loaded || snapshot.execution !== result.execution) {
+                throw new CoreError({name: 'AbortError', code: 'ARCANE_AI_REQUEST_ABORTED', message: 'The native decision activation was replaced.'});
+            }
+            return snapshot;
+        }).finally(function detachLoadCaller() { signal?.removeEventListener('abort', abort); });
     }
 
     async function evaluate(rows, {signal, runOptions} = {}) {
@@ -129,7 +165,7 @@ export function createNativeDecisionService(configuration = {}, {appRoot = proce
         start(serviceContext) { context = serviceContext; },
         methods: {
             'decisions.status': current,
-            'decisions.load': function loadRequest(parameters, request) { return load({signal: request.signal}); },
+            'decisions.load': function loadRequest(parameters, request) { return load({executionTarget: parameters?.executionTarget, signal: request.signal}); },
             'decisions.evaluate': async function evaluateRequest({rows, runOptions}, request) {
                 const result = await evaluate(rows, {runOptions, signal: request.signal});
                 // Typed arrays retain their complete values through Core's

package/src/core/services/execution-devices.mjs

@@ -0,0 +1,32 @@
+import {createExecutionDeviceCatalog} from '../../local-ai/execution-devices.mjs';
+
+/**
+ * Independent of model-service startup. Core gives this service ownership of
+ * the shared catalog's disposal; model engines borrowing it do not dispose it.
+ */
+export function createExecutionDeviceService({catalog = createExecutionDeviceCatalog()} = {}) {
+    function devices({refresh = false} = {}, {signal} = {}) {
+        return catalog.devices(
+            {refresh, signal}
+        );
+    }
+
+    function resolveTarget({executionTarget = null, refresh = false} = {}, {signal} = {}) {
+        return catalog.resolveTarget(
+            {executionTarget, refresh, signal}
+        );
+    }
+
+    function dispose() {
+        return catalog.dispose();
+    }
+
+    return {
+        name: 'execution-devices',
+        methods: {
+            'localai.devices': devices,
+            'localai.resolveTarget': resolveTarget
+        },
+        dispose
+    };
+}

package/src/core/services/local-ai.mjs

@@ -121,7 +121,7 @@ function collectCompletion(completion, chunk) {
 }
 
 /** Core owns native processes; applications own runtime and model selection. */
-export function createLocalAIService(configuration, {appRoot, runtimes = [], signal, onEvent, prepare} = {}) {
+export function createLocalAIService(configuration, {appRoot, runtimes = [], signal, onEvent, prepare, executionDevices} = {}) {
     const config = normalizeLocalAIConfig(configuration) ?? {runtimes: []};
     const lifetime = new AbortController();
     const lifetimeSignal = signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal;
@@ -173,7 +173,9 @@ export function createLocalAIService(configuration, {appRoot, runtimes = [], sig
 
     function startONNX() {
         if (!onnxRecord?.modulePath) return;
-        onnx = createONNXRuntime({modulePath: onnxRecord.modulePath, signal: lifetimeSignal, onEvent});
+        onnx = createONNXRuntime(
+            {modulePath: onnxRecord.modulePath, signal: lifetimeSignal, onEvent, executionDevices}
+        );
         stopONNXSubscription = onnx.subscribe(function onnxChanged() { publish(); });
     }
 
@@ -630,9 +632,14 @@ export function createLocalAIService(configuration, {appRoot, runtimes = [], sig
                 return snapshot();
             },
             'onnx.status': function currentONNX() { return onnxStatus(); },
-            'onnx.load': function loadONNX({id, model, sessionOptions}, request) {
-                return requireONNX().load({id, model: path.resolve(appRoot ?? process.cwd(), model), sessionOptions,
-                    signal: AbortSignal.any([lifetimeSignal, request.signal])});
+            'onnx.load': function loadONNX({id, model, sessionOptions, executionPreference, executionTarget}, request) {
+                return requireONNX().load(
+                    {
+                        id, model: path.resolve(appRoot ?? process.cwd(), model), sessionOptions,
+                        executionPreference, executionTarget,
+                        signal: AbortSignal.any([lifetimeSignal, request.signal])
+                    }
+                );
             },
             'onnx.run': async function runONNX({id, feeds, fetches, runOptions}, request) {
                 const outputs = await requireONNX().run({id, feeds: decodeTensorMap(feeds),

package/src/local-ai/decisions.mjs

@@ -13,6 +13,10 @@ function cancellation(message) {
 
 function reportCleanupFailure(error) { console.error('Native decision cleanup failed.', error); }
 
+function sameExecutionTarget(left, right) {
+    return left === right || (left != null && right != null && left.deviceId !== undefined && left.deviceId === right.deviceId);
+}
+
 /**
  * One explicitly activated Laya FP32 model using an existing native ONNX owner.
  * It does not create another inference runtime or load on construction.
@@ -20,7 +24,7 @@ function reportCleanupFailure(error) { console.error('Native decision cleanup fa
 export function createNativeDecisionModel({
     onnx, modelAssets, workingDirectory, paths,
     model = 'onnx-community/laya-typed-decisions-ONNX', revision = 'main',
-    dtype = 'fp32', sessionOptions, executionPreference = 'gpu', signal
+    dtype = 'fp32', sessionOptions, executionPreference = 'gpu', executionTarget, signal
 } = {}) {
     if (dtype !== 'fp32') throw new TypeError('This native Laya graph selection requires dtype fp32.');
     const owner = {};
@@ -33,14 +37,18 @@ export function createNativeDecisionModel({
     let progress = null;
     let lastError = null;
     let execution = null;
+    let selectedTarget = executionTarget;
+    let pendingActivation;
 
     function current() {
+        const pending = pendingActivation && (state !== 'ready' || pendingActivation.entry !== activation) ? pendingActivation : null;
         return {
             family: 'laya', model, revision, dtype, state,
-            loaded: state === 'ready', busy: state === 'loading' || Boolean(activation?.jobs.size),
+            loaded: state === 'ready', busy: state === 'loading' || Boolean(pending) || Boolean(activation?.jobs.size),
             activeRequests: activation?.jobs.size ?? 0, progress,
             error: lastError ? serializeCoreError(lastError) : null,
-            execution
+            execution,
+            pendingActivation: pending ? {executionTarget: pending.executionTarget} : null
         };
     }
 
@@ -141,8 +149,8 @@ export function createNativeDecisionModel({
         return {model: files['onnx/model.onnx'], tokenizer: files['tokenizer.json'], tokenizerConfig: files['tokenizer_config.json']};
     }
 
-    function beginActivation() {
-        const entry = {id: randomUUID(), controller: new AbortController(), jobs: new Set(), prepared: false, onnxLoadStarted: false};
+    function beginActivation(target) {
+        const entry = {id: randomUUID(), controller: new AbortController(), jobs: new Set(), prepared: false, onnxLoadStarted: false, executionTarget: target};
         activation = entry;
         state = 'loading';
         progress = {phase: 'preparing-model'};
@@ -161,7 +169,7 @@ export function createNativeDecisionModel({
             });
             entry.onnxLoadStarted = true;
             const loaded = onnx.load({
-                id: entry.id, model: files.model, sessionOptions, executionPreference,
+                id: entry.id, model: files.model, sessionOptions, executionPreference, executionTarget: entry.executionTarget,
                 signal: entry.controller.signal
             });
             const results = await Promise.allSettled([loaded, entry.tokenizer.ready]);
@@ -193,19 +201,76 @@ export function createNativeDecisionModel({
         return entry;
     }
 
-    async function load({signal: operationSignal} = {}) {
-        assertOpen(operationSignal);
-        if (releaseTask && !activation) await releaseTask;
-        assertOpen(operationSignal);
-        const entry = activation ?? beginActivation();
+    async function awaitActivation(entry, operationSignal) {
         const detach = observeCancellation(entry, operationSignal);
         try {
             await entry.loading;
             entry.controller.signal.throwIfAborted();
+            if (activation !== entry) throw cancellation('The decision activation was replaced.');
             return current();
         } finally { detach(); }
     }
 
+    function observeLoad(request, operationSignal) {
+        function abort() { request.controller.abort(operationSignal.reason); }
+        operationSignal?.addEventListener('abort', abort, {once: true});
+        if (operationSignal?.aborted) abort();
+        return request.task.then(function loadedActivation() {
+            request.controller.signal.throwIfAborted();
+            request.entry.controller.signal.throwIfAborted();
+            if (activation !== request.entry) throw cancellation('The decision activation was replaced.');
+            return current();
+        }).finally(function detachLoadCaller() { operationSignal?.removeEventListener('abort', abort); });
+    }
+
+    async function load({signal: operationSignal, executionTarget: requestedTarget} = {}) {
+        assertOpen(operationSignal);
+        const target = requestedTarget === undefined ? selectedTarget : requestedTarget;
+        if (pendingActivation && !pendingActivation.controller.signal.aborted && sameExecutionTarget(pendingActivation.executionTarget, target)) {
+            return observeLoad(pendingActivation, operationSignal);
+        }
+        if (!pendingActivation && activation && sameExecutionTarget(activation.executionTarget, target)) {
+            return awaitActivation(activation, operationSignal);
+        }
+        const previous = pendingActivation;
+        const request = {executionTarget: target, controller: new AbortController()};
+        let precedingRelease;
+        // Retain the replacement before synchronous abort/state observers run.
+        // Only this model's retiring activation must finish before its successor.
+        request.task = Promise.resolve().then(async function loadSelectedTarget() {
+            request.controller.signal.throwIfAborted();
+            if (precedingRelease) await precedingRelease;
+            assertOpen(request.controller.signal);
+            if (pendingActivation !== request) throw cancellation('The decision activation request was replaced.');
+            request.entry ??= activation ?? beginActivation(request.executionTarget);
+            return awaitActivation(request.entry, request.controller.signal);
+        });
+        function settled(error) {
+            request.detach?.();
+            if (pendingActivation !== request) return;
+            pendingActivation = undefined;
+            if (!request.entry && !activation && !disposed && state === 'loading') {
+                state = request.controller.signal.aborted ? 'unloaded' : 'error';
+                progress = null;
+                lastError = request.controller.signal.aborted ? null : error;
+            }
+            publish();
+        }
+        request.task.then(function loaded() { settled(); }, function loadFailed(error) { settled(error); }).catch(reportCleanupFailure);
+        pendingActivation = request;
+        selectedTarget = target;
+        const reason = cancellation('The decision execution target was replaced.');
+        previous?.controller.abort(reason);
+        if (activation && !sameExecutionTarget(activation.executionTarget, target)) stop(activation, reason);
+        precedingRelease = !activation ? releaseTask : undefined;
+        if (!activation && !precedingRelease) {
+            request.entry = beginActivation(target);
+            request.detach = observeCancellation(request.entry, request.controller.signal);
+        }
+        publish();
+        return observeLoad(request, operationSignal);
+    }
+
     async function evaluate(rows, {signal: operationSignal, runOptions} = {}) {
         assertOpen(operationSignal);
         const entry = activation;
@@ -247,21 +312,34 @@ export function createNativeDecisionModel({
     }
 
     function unload() {
-        return activation ? stop(activation, cancellation('The native decision model was unloaded.'))
-            : releaseTask ?? Promise.resolve(current());
+        const reason = cancellation('The native decision model was unloaded.');
+        const pending = pendingActivation;
+        pending?.controller.abort(reason);
+        const release = activation ? stop(activation, reason) : releaseTask ?? Promise.resolve(current());
+        if (!pending) return release;
+        return Promise.allSettled([release, pending.task]).then(function releasedActivation(results) {
+            if (results[0].status === 'rejected') throw results[0].reason;
+            return current();
+        });
     }
 
     function dispose() {
         if (disposal) return disposal;
         disposed = true;
         signal?.removeEventListener('abort', lifetimeAborted);
+        const pending = pendingActivation;
+        const reason = cancellation('The native decision model was disposed.');
         let release;
         disposal = Promise.resolve().then(async function disposeNativeModel() {
-            try { await release; }
+            try {
+                const results = await Promise.allSettled([release, pending?.task]);
+                if (results[0].status === 'rejected') throw results[0].reason;
+            }
             finally { state = 'disposed'; publish(); events.dispose(); }
             return current();
         });
-        release = activation ? stop(activation, cancellation('The native decision model was disposed.')) : releaseTask;
+        pending?.controller.abort(reason);
+        release = activation ? stop(activation, reason) : releaseTask;
         if (!activation && !release) { state = 'disposed'; publish(); }
         return disposal;
     }

package/src/local-ai/dev.mjs

@@ -4,19 +4,23 @@ import {createLocalAIService} from '../core/services/local-ai.mjs';
 import {createLocalImageService} from '../core/services/image.mjs';
 import {createModelAssetService} from '../core/services/model-assets.mjs';
 import {createSpeechService} from '../core/services/speech.mjs';
+import {createExecutionDeviceService} from '../core/services/execution-devices.mjs';
 import {normalizeLocalAIConfig} from './config.mjs';
 import {discoverLocalAIRuntimes} from './discover.mjs';
 import {ensureLocalAIRuntimes} from './install.mjs';
 import {createWhisperRuntime} from './whisper/index.mjs';
+import {createExecutionDeviceCatalog} from './execution-devices.mjs';
 
 /** Local engines share the ordinary app-service development transport. */
 export function createDevelopmentLocalAI({
     config, appRoot, directory, application, version, signal, onEvent,
     services = [], serviceModules = [], context = {}
 } = {}) {
+    const selected = normalizeLocalAIConfig(config) ?? {runtimes: []};
     const lifetime = new AbortController();
     signal = signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal;
-    const selected = normalizeLocalAIConfig(config) ?? {runtimes: []};
+    // Discovery starts on demand, independently of model runtime preparation.
+    const executionDevices = createExecutionDeviceCatalog({signal});
     const localConfig = {
         ...selected,
         runtimes: selected.runtimes.filter(function selectedChatRuntime(requirement) {
@@ -26,7 +30,7 @@ export function createDevelopmentLocalAI({
     const service = createLocalAIService(
         localConfig,
         {
-            appRoot, signal, onEvent,
+            appRoot, signal, onEvent, executionDevices,
             async prepare({signal, onEvent: report}) {
                 const discovered = await discoverLocalAIRuntimes({config: localConfig, appRoot, signal});
                 const installed = await ensureLocalAIRuntimes(
@@ -36,7 +40,7 @@ export function createDevelopmentLocalAI({
             }
         }
     );
-    const definitions = [service, ...services];
+    const definitions = [createExecutionDeviceService({catalog: executionDevices}), service, ...services];
     let modelAssets;
     let imageService;
     let speechService;