arcane-os 0.78.0 → 0.79.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.79.0
+
+- Add public `createExecutionDeviceCatalog()` and `createExecutionDeviceService()`
+  with lazy Windows CPU/GPU/NPU discovery, stable host-local identities,
+  complete discovery issues, explicit refresh, cancellation and disposal.
+  `localai.devices` and `localai.resolveTarget` use the existing Core transport
+  without loading models or changing saved preferences.
+- Share one catalog per local-AI Core lifetime. Native ONNX and Laya accept
+  `executionTarget` for a physical CPU or mapped DirectML GPU. Automatic GPU
+  selection can use the largest reported dedicated capacity among addressable
+  hardware GPUs; integrated GPUs remain eligible. Unsupported or unavailable
+  selections are reported without silently choosing another physical device.
+- Preserve caller options and complete execution diagnostics. Distinguish the
+  requested, resolved and configured target from observed execution; successful
+  configuration is not GPU/NPU execution proof. Laya target replacement cancels
+  and drains only its retiring activation before the successor starts.
+- Keep discovery independent from model readiness and preserve existing engine
+  behavior when a target is omitted. Browser Wllama, native llama.cpp, image and
+  Whisper device routing are unchanged; this release adds no driver, model or
+  native runtime dependency.
+
 ## 0.78.0
 
 - Add `AI.readPreparedTTS()` and shared `readPreparedSpeech()` for complete

package/README.md

@@ -20,12 +20,17 @@ 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.78.0` SDK contract. Development applications declare
+This checkout defines the `0.79.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;
 registry state is deliberately not baked into application artifacts.
 
+[Physical execution devices](docs/reference/execution-devices.md) exposes Windows
+CPU/GPU/NPU discovery and native ONNX/Laya target selection through the existing
+Core host, independently of model loading. Device presence, configured provider
+placement and observed model execution remain separate facts.
+
 Standalone browser apps use their repository root and installed npm package directly, without a
 generated workspace `arcane/` directory or `arcane.lock.json`. Select the
 [four installed-package routes](docs/reference/protocols.md#installed-package-browser-routes)

package/browser-runtime/ai/core-onnx.mjs

@@ -106,9 +106,13 @@ export function createCoreONNXRuntime({client: suppliedClient} = {}) {
         }
     }
 
-    async function load({id, model, sessionOptions, signal, timeoutMs} = {}) {
+    async function load({id, model, sessionOptions, executionPreference, executionTarget, signal, timeoutMs} = {}) {
         const currentConnection = connection;
-        const result = await invoke('onnx.load', {id, model, sessionOptions}, {signal, timeoutMs});
+        const result = await invoke(
+            'onnx.load',
+            {id, model, sessionOptions, executionPreference, executionTarget},
+            {signal, timeoutMs}
+        );
         currentConnection.controller.signal.throwIfAborted();
         return result;
     }

package/browser-runtime/core/contracts.mjs

@@ -32,6 +32,16 @@ export const CORE_METHOD_CONTRACTS={
     'preferences.set':{input:'{key,value}',output:'{key,value}'},
     'preferences.setMany':{input:'{entries}',output:'preference-batch-result'},
     'preferences.delete':{input:'{key}',output:'{key,deleted}'},
+    'localai.devices': {
+        input: '{refresh?}',
+        output: '{platform,state,devices,issues}',
+        meaning: 'Physical host inventory, independent of model startup. Presence does not establish engine support or observed execution.'
+    },
+    'localai.resolveTarget': {
+        input: '{executionTarget:{deviceId}|null,refresh?}',
+        output: '{requestedTarget,resolvedDevice,resolution,reason}',
+        meaning: 'Resolve a saved physical identity. Explicit null selects engine-owned automatic resolution; it does not claim a configured or observed device.'
+    },
     'window.setTheme': {
         input: '{backgroundColor?,textColor?}: null reset or {red,green,blue,alpha}',
         output: '{platform,supported,applied,unsupported}',

package/docs/publishing.md

@@ -53,6 +53,22 @@ and reports npm's response. It tolerates npm's publish-time scanning. If
 scanning or manual review remains pending, the workflow reports that state and
 a rerun safely resumes without republishing the version.
 
+Registry verification requires both the selected version/channel metadata and
+an ordinary complete GET of that exact version's published `dist.tarball` URL.
+Metadata visibility alone is not downloadable-package delivery. The verifier
+reads exact-version metadata, follows its tarball URL, and consumes the full
+successful response before reporting completion. Missing metadata, an HTTP
+failure, or an interrupted body remains pending within the existing bounded
+retry window; the remaining window also bounds the metadata/tarball requests.
+The existing npm metadata subprocesses retain their current behavior. If they
+consume the window, including a zero-wait invocation, the verifier reports
+pending without starting a new download observation.
+It records the actual failure and exits unsuccessfully if availability does not
+arrive. It does not save a second artifact, repack, republish, alter registry
+tags, add cache-bypass parameters, or impose a content-size or hash comparison.
+Requester notices follow successful version/channel and download observation;
+consumer installation and application verification remain separately owned.
+
 The public `0.3.2` release is fixed to package-source commit
 `445bd2d982f12e6ef8dd2b615c70512000cc5224`, selected Check run
 `33264677687`, and publication/registry run `33264829711`. Its numeric Git tag
@@ -77,9 +93,10 @@ The npm package already has its trusted-publishing relationship. Each later
 release therefore follows the same direct selected-artifact path: push the
 intended `main` source, manually run Check for that exact revision, review the
 resulting package inventory and legal notices, then manually dispatch
-publication with that Check run and artifact. Confirm the selected version and
-dist-tag after publication. Never rebuild or repack the artifact under
-publication authority, and never substitute a different source revision.
+publication with that Check run and artifact. Confirm the selected version,
+dist-tag, and complete published tarball availability after publication. Never
+rebuild or repack the artifact under publication authority, and never substitute
+a different source revision.
 
 Generated app CI uses `npm ci --ignore-scripts`, so its lock must exist and its
 dependency source must be reachable by the runner. External application CI uses

package/docs/reference/execution-devices.md

@@ -0,0 +1,157 @@
+# Physical execution devices
+
+The local-AI Core host exposes physical device discovery independently of model
+installation, loading and inference. A device being present does not establish
+that a particular engine can use it. The engine resolves that second question
+when the application explicitly loads its selected model.
+
+## List devices without loading a model
+
+Use the application's existing Core client:
+
+```js
+const catalog = await client.invoke('localai.devices', {refresh: false}, {signal});
+console.log(catalog.devices);
+console.log(catalog.issues);
+```
+
+The inventory has `{platform, state, devices, issues}`. `platform` uses Node's
+platform name. `state` is `ready`, `partial` or `unavailable`. Incomplete or failed
+discovery is reported in `issues`; it is not evidence that the machine has no
+devices. This initial discovery implementation uses Windows host APIs. Other
+platforms report this capability as unavailable while retaining their existing
+AI runtime behavior.
+
+Each device has the following fields:
+
+| Field | Meaning |
+| --- | --- |
+| `deviceId` | Stable host-local selection key, or `null` when identity could not be established. |
+| `identitySource` | `windows-pnp-instance`, `host-cpu`, or `null`. |
+| `kind` | `cpu`, `gpu` or `npu`. |
+| `name` | Complete reported display name. Names are not selection identities. |
+| `present` | Whether the queried device is present. |
+| `isHardware`, `isIntegrated` | Reported hardware facts, or `null` when unavailable. |
+| `dedicatedMemoryMiB` | Reported dedicated capacity, or `null`; used only for supported automatic GPU selection. |
+| `addresses` | Observed adapter addresses described below. These are not persistent selection keys. |
+| `processors` | Actual processor records for the aggregate CPU option; an empty array for GPU/NPU records. |
+
+GPU and NPU identities are actual, uniquely correlated Windows PnP instance IDs.
+An adapter whose stable identity cannot be established remains in the inventory
+with `deviceId: null` and a corresponding issue. The SDK does not invent a key
+from a name, enumeration order, hardware model number or adapter LUID.
+
+The CPU choice uses `deviceId: 'cpu'` and `identitySource: 'host-cpu'`. It selects
+the whole-host CPU execution target, without claiming socket or core affinity.
+Its `processors` entries contain `{deviceId, name, socketDesignation, cores,
+logicalProcessors}`; unavailable optional facts are `null`.
+
+`addresses` contains:
+
+```js
+{
+  adapterLuid: {highPart, lowPart}, // or null
+  pci: {bus, device, function: pciFunction}, // or null
+  dxgiAdapterIndex // or null
+}
+```
+
+The DXGI index is the actual `EnumAdapters` index joined to the adapter's LUID.
+It is never inferred from DXCore or PnP enumeration order. It supplies a possible
+DirectML address, not proof of provider availability or successful execution.
+No CUDA ordinal is inferred from these Windows addresses.
+
+An issue contains `{source, code, message, deviceId}`. `source` identifies `cpu`,
+`gpu`, `npu`, `identity` or `dxgi`; `deviceId` is `null` when no stable identity
+was established. Keep the complete diagnostic available to developers rather
+than substituting an empty inventory.
+
+## Resolve a saved selection
+
+Store the selected physical ID with the application's existing preferences,
+keyed by provider and model. The SDK introduces no new preference store and
+does not change the six-slot model preference tuple.
+
+```js
+const resolution = await client.invoke('localai.resolveTarget', {
+  executionTarget: {deviceId: savedDeviceId}
+}, {signal});
+```
+
+The result contains `{requestedTarget, resolvedDevice, resolution, reason}`:
+
+- `matched`: the complete device record was found. Engine support is still a
+  separate question.
+- `unavailable` with `device-not-present`: complete relevant discovery did not
+  find that saved identity. Preserve the saved selection so the application can
+  show that it is currently unavailable.
+- `unsupported` with `inventory-unavailable` or `identity-unresolved`: discovery
+  cannot establish the requested identity. Do not describe it as an absent device.
+- `automatic` with `engine-default-required`: an explicit `executionTarget: null`
+  asks the selected engine to choose at its activation boundary. The physical
+  resolver returns `resolvedDevice: null` because it cannot establish the
+  engine's routing capabilities.
+
+Calling the resolver does not load a model, change preferences or replace an
+existing activation. A model load that omits `executionTarget` retains that
+API's existing constructor, session-option and default behavior. Explicit
+`null` selects automatic resolution for the new activation; it does not erase
+or relabel a running session.
+
+## Engine configuration and execution evidence
+
+The physical-target integration described here applies to native ONNX and
+native Laya through Core. Listing host devices does not add physical-device
+selection to browser WebGPU/Wllama or to the separate native llama.cpp, image
+and Whisper owners. Their existing backend options remain unchanged. A browser
+uses the existing Core connection for this inventory; the catalog does not
+create a native connection or replace a browser provider.
+
+An engine receives the saved selection as `executionTarget: {deviceId}`. It
+owns provider availability, the physical-to-provider address mapping and the
+actual session configuration. Its public state distinguishes the requested
+target, physical resolution, configured target and observed execution. A
+successful session configuration alone is not evidence that every operation ran
+on a GPU or NPU.
+
+Automatic selection can prefer the hardware GPU with the highest reported
+dedicated capacity among supported targets with established routing. An
+integrated GPU remains eligible when it meets those same conditions. An unavailable saved
+target is not silently replaced by another device or a cloud route. See
+[native ONNX](local-ai.md#native-onnx-sessions) and [native decisions](native-decisions.md)
+for the selected engine's load, replacement, cancellation and status contracts.
+
+## Catalog and Core ownership
+
+SDK development local-AI composition and generated native composition with
+`localAI` selected register one lazy catalog and its independent
+`execution-devices` service. An empty runtime selection still permits device
+discovery. Hosts without local-AI composition retain their existing service
+selection. A manually composed Core can register the service explicitly:
+
+```js
+import {createExecutionDeviceCatalog} from 'arcane-os/local-ai/execution-devices';
+import {createExecutionDeviceService} from 'arcane-os/core/execution-devices';
+import {createLocalAIService} from 'arcane-os/core/local-ai';
+
+const executionDevices = createExecutionDeviceCatalog({signal});
+const services = [
+  createExecutionDeviceService({catalog: executionDevices}),
+  createLocalAIService(localAI, {appRoot, runtimes, signal, executionDevices})
+];
+```
+
+Pass these definitions to the existing Core host. The independent service owns
+catalog disposal. The local-AI engine borrows the same catalog; it does not
+dispose a supplied owner or create another discovery process per model.
+
+For direct Node use, `createExecutionDeviceCatalog({signal})` returns
+`devices({refresh, signal})`, `resolveTarget({executionTarget, refresh, signal})`
+and `dispose()`. The direct caller owns disposal. Construction performs no
+discovery I/O. Calls reuse/coalesce the host's discovery; `refresh: true` requests
+an explicit new observation. There is no background polling. Closing the owner
+releases its discovery work and native query resources.
+
+The catalog queries installed operating-system facilities. It does not install
+drivers, download models, alter system policy or introduce a hardware admission
+rule. A host capability failure remains an honest unavailable/partial result.

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

@@ -1,30 +1,58 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.77.0",
+  "sdkVersion": "0.78.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 299,
+  "memberCount": 301,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "local-ai-execution-devices:createExecutionDeviceCatalog",
+      "name": "createExecutionDeviceCatalog",
+      "displayName": "createExecutionDeviceCatalog()",
+      "kind": "function",
+      "signature": "createExecutionDeviceCatalog({signal}={})",
+      "entrypoints": ["arcane-os/local-ai/execution-devices"],
+      "primaryImport": "arcane-os/local-ai/execution-devices",
+      "group": "Physical execution devices",
+      "summary": "Owns lazy physical-device discovery and saved device-ID resolution independently of models and inference.",
+      "availability": "Node; Windows discovery is implemented, while other platforms return an unavailable inventory without changing existing AI behavior",
+      "protocol": "Physical inventory {platform,state,devices,issues}; target resolution {requestedTarget,resolvedDevice,resolution,reason}",
+      "normalization": "Returns async devices({refresh=false,signal}={}), async resolveTarget({executionTarget=null,refresh=false,signal}={}) and dispose(). Construction performs no discovery I/O; calls share cached/coalesced discovery and refresh explicitly requests a new observation. Complete records and issues distinguish ready, partial and unavailable discovery. A saved deviceId resolves as matched, unavailable or unsupported; null returns automatic/engine-default-required without discovery, and a non-null target without a nonempty string deviceId throws TypeError. Physical presence never proves engine support or actual execution. Request cancellation rejects AbortError/ARCANE_CANCELLED and the last departing caller stops the query; retained dispose() joins owned discovery shutdown, and constructor-signal abort disposes the catalog. The direct caller owns disposal; no polling, model loading, preference writes or silent target substitution. See execution-devices.md for all record fields and reasons."
+    },
+    {
+      "id": "core-execution-devices:createExecutionDeviceService",
+      "name": "createExecutionDeviceService",
+      "displayName": "createExecutionDeviceService()",
+      "kind": "function",
+      "signature": "createExecutionDeviceService({catalog=createExecutionDeviceCatalog()}={})",
+      "entrypoints": ["arcane-os/core/execution-devices"],
+      "primaryImport": "arcane-os/core/execution-devices",
+      "group": "Physical execution devices",
+      "summary": "Registers physical-device discovery as an independent Core service with catalog lifetime ownership.",
+      "availability": "Node Core; available independently of selected or loaded model runtimes, with discovery support reported by the catalog",
+      "protocol": "arcane/1 localai.devices and localai.resolveTarget",
+      "normalization": "Returns the execution-devices service with localai.devices({refresh=false}) and localai.resolveTarget({executionTarget=null,refresh=false}); both forward the Core request signal and return the catalog's complete result. Registration performs no discovery or model work. dispose() owns disposal of the supplied or default catalog; other services may borrow that same catalog without owning it."
+    },
     {
       "id": "local-ai-decisions:createNativeDecisionModel",
       "name": "createNativeDecisionModel",
       "displayName": "createNativeDecisionModel()",
       "kind": "function",
-      "signature": "createNativeDecisionModel({onnx,modelAssets,workingDirectory,paths,model='onnx-community/laya-typed-decisions-ONNX',revision='main',dtype='fp32',sessionOptions,executionPreference='gpu',signal}={})",
+      "signature": "createNativeDecisionModel({onnx,modelAssets,workingDirectory,paths,model='onnx-community/laya-typed-decisions-ONNX',revision='main',dtype='fp32',sessionOptions,executionPreference='gpu',executionTarget,signal}={})",
       "entrypoints": ["arcane-os/local-ai/decisions"],
       "primaryImport": "arcane-os/local-ai/decisions",
       "group": "Native typed decisions",
       "summary": "Explicit native Laya FP32 option scoring through an existing ONNX owner and a tokenizer Worker.",
       "availability": "Node on Windows/Linux/macOS with selected ONNX Runtime and model files; Android needs host adaptation",
       "protocol": "Shared browser/native decision encoding with native named tensor results",
-      "normalization": "Returns load/evaluate/classify/current/status/subscribe/unload/dispose; preserves complete separate state/question/options/type and original rows, raw scores and every graph output. Explicit load prepares selected upstream files or uses caller-owned paths; GPU preference attempts advertised providers then CPU. Cancellation retires the shared activation; files remain retained through actual ONNX and tokenizer Worker exit. No chat history or duplicate inference engine."
+      "normalization": "Returns load/evaluate/classify/current/status/subscribe/unload/dispose; preserves complete separate state/question/options/type and original rows, raw scores and every graph output. Explicit load prepares selected upstream files or uses caller-owned paths. load({executionTarget,signal}) retains the latest selected target when omitted or undefined, initially the factory selection; null requests automatic resolution, while {deviceId} forwards the saved physical selection to the existing ONNX owner. With no target selection, GPU preference still attempts advertised providers then CPU and explicit session providers retain precedence. Same-target loads share activation; a changed target cancels the earlier request and joins its actual ONNX/tokenizer cleanup before replacement. pendingActivation reports the requested replacement separately; current().execution remains the complete ONNX load record, with requested/resolved/configured/observed target diagnostics in current().execution.execution. Configuration alone does not prove physical execution. Cancellation retires the shared activation; files remain retained through actual ONNX and tokenizer Worker exit. No preference writes, chat history or duplicate inference engine."
     },
     {
       "id": "core-decisions:createNativeDecisionService",
@@ -38,7 +66,7 @@
       "summary": "Renderer-independent native Laya service reusing the registered local-AI and model-assets owners.",
       "availability": "Node Core with selected native ONNX and model files",
       "protocol": "arcane/1 decisions.status/load/evaluate/unload and decisions.state",
-      "normalization": "Registration starts no model or tokenizer. Explicit load obtains dependency-ready same-process owners and reacquires getONNXRuntime after recovery. Native load/evaluate/classify/current/subscribe/unload/dispose preserve complete results; RPC uses the existing tensor codec. Unload has accepted service lifetime; host shutdown cancels request-lifetime load/evaluation."
+      "normalization": "Registration starts no model or tokenizer. Explicit load obtains dependency-ready same-process owners and reacquires getONNXRuntime after recovery. Factory configuration accepts executionTarget; direct load({executionTarget,signal}) and Core decisions.load({executionTarget}) preserve omitted/undefined selection and explicit null automatic selection. Same-target loads coalesce; changed targets cancel pending work and join the prior model's disposal before replacement. pendingActivation remains separate from the full activation execution record and its nested execution diagnostics. Native load/evaluate/classify/current/subscribe/unload/dispose preserve complete results; RPC uses the existing tensor codec. Unload has accepted service lifetime; host shutdown cancels request-lifetime load/evaluation."
     },
     {
       "id": "core-decisions:default",
@@ -353,14 +381,14 @@
       "name": "createONNXRuntime",
       "displayName": "createONNXRuntime()",
       "kind": "function",
-      "signature": "createONNXRuntime({modulePath,signal,onEvent}={})",
+      "signature": "createONNXRuntime({modulePath,onEvent,signal,executionDevices}={})",
       "entrypoints": ["arcane-os/local-ai/onnx"],
       "primaryImport": "arcane-os/local-ai/onnx",
       "group": "Core local AI",
       "summary": "Owns explicitly loaded ONNX graphs and complete named tensor inference in retained native workers.",
       "availability": "Node on Windows/Linux/macOS x64/arm64 with prepared onnxruntime-node; Android needs host adaptation",
       "protocol": "Per-session worker lifecycle with structured-clone tensors and replaying state",
-      "normalization": "Returns load/run/unload/current/subscribe/close; load accepts executionPreference gpu for advertised provider creation attempts then CPU, while explicit sessionOptions.executionProviders takes precedence. Complete execution diagnostics distinguish configured providers from physical acceleration. stopping revokes new runs while exited records actual Worker exit; recoverable run errors preserve the session. Cleanup joins exit and output delivery even when termination fails."
+      "normalization": "Returns load/run/unload/current/subscribe/close. load({id,model,sessionOptions,executionPreference,executionTarget,signal}) preserves existing behavior when executionTarget is omitted: gpu preference tries advertised providers then CPU, while explicit sessionOptions.executionProviders takes precedence. Explicit null requests automatic selection; with gpu preference and no explicit providers it prefers the highest dedicatedMemoryMiB among mapped hardware GPUs, including integrated hardware, then uses existing provider selection when no eligible mapping exists. A saved {deviceId} selects whole-host CPU or an established DirectML adapter mapping; unavailable, unsupported or conflicting targets report LOCAL_AI_EXECUTION_TARGET_UNAVAILABLE, LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED or LOCAL_AI_EXECUTION_TARGET_CONFLICT without silently replacing the selection. Every loaded session reports requestedTarget, resolvedDevice, resolution/reason and configuredTarget {source,executionProviders}; observedTarget remains null because configuration does not prove physical execution. SDK-selected GPU configurations retain CPU operator support. A supplied executionDevices catalog is borrowed; otherwise the runtime owns its lazy catalog. stopping revokes new runs while exited records actual Worker exit; recoverable run errors preserve the session. Cleanup cancels target discovery and joins preparation, exit and output delivery even when termination fails."
     },
     {
       "id": "core-onnx:createCoreONNXRuntime",
@@ -374,7 +402,7 @@
       "summary": "Accesses local system ONNX through an existing Core client with complete tensor transport.",
       "availability": "Browser with available Core ONNX service; construction installs no runtime or model",
       "protocol": "arcane/1 onnx.status/load/run/unload and localai.state",
-      "normalization": "Returns load/run/unload/inspect/current/subscribe/close; omitted client follows late installation/replacement/retirement and reads current status, while explicit client including null stays fixed. Retirement clears readiness and cancels owned work; late old-client results are suppressed. Preserves typed and string tensors; close removes subscriptions and cancels requests without closing shared Core or implicitly unloading shared models"
+      "normalization": "Returns load/run/unload/inspect/current/subscribe/close; load({id,model,sessionOptions,executionPreference,executionTarget,signal,timeoutMs}) forwards provider preference and physical selection while preserving omitted-versus-null target semantics. Complete native execution diagnostics distinguish requested, resolved and configured targets from unobserved physical execution. Omitted client follows late installation/replacement/retirement and reads current status, while explicit client including null stays fixed. Retirement clears readiness and cancels owned work; late old-client results are suppressed. Preserves typed and string tensors; close removes subscriptions and cancels requests without closing shared Core or implicitly unloading shared models"
     },
     {
       "id": "root:createGitTextSnapshot",
@@ -465,14 +493,14 @@
       "name": "createLocalAIService",
       "displayName": "createLocalAIService()",
       "kind": "function",
-      "signature": "createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent,prepare}={})",
+      "signature": "createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent,prepare,executionDevices}={})",
       "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. 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.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; 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.status/models observe without starting or restarting an engine. Independent services, complete responses and exact owned-process cleanup remain unchanged."
     },
     {
       "id": "core-local-ai:default",
@@ -4192,7 +4220,7 @@
       "summary": "Describes existing Core method input, output and semantic shapes.",
       "availability": "Node and browser/bundler",
       "protocol": "arcane/1 method descriptions",
-      "normalization": "Descriptive data only; the active host and its registered services remain the authority for method availability"
+      "normalization": "Descriptive data only, including independent localai.devices inventory and localai.resolveTarget physical-selection records; presence does not establish engine support or observed execution. The active host and its registered services remain the authority for method availability"
     },
     {
       "id": "core-contracts:CoreError",

package/docs/reference/local-ai.md

@@ -169,6 +169,10 @@ process between requests, and joins cleanup during disposal.
 Optional `prepare({signal,onEvent})` returns resolved runtime records before
 this service starts its selected engines. The managed development owner uses
 that callback without delaying the HTTP listener or independent services.
+Optional `executionDevices` supplies the shared execution-device catalog to
+the ONNX owner. Development and generated native composition share one catalog
+per Core lifetime with the independent `execution-devices` service. The ONNX
+owner does not dispose an injected catalog; the composing owner retains it.
 This factory accepts chat/ONNX requirements; the separate
 [`createLocalImageService()`](local-image-generation.md#core-service-and-transport)
 owns image requirements. The development and generated native composition
@@ -384,8 +388,8 @@ try {
 }
 ```
 
-The factory accepts `{modulePath,signal?,onEvent?}` and starts no worker until
-`load({id,model,sessionOptions?,executionPreference?,signal?})`. The model path is absolute for this
+The factory accepts `{modulePath,signal?,onEvent?,executionDevices?}` and starts no worker until
+`load({id,model,sessionOptions?,executionPreference?,executionTarget?,signal?})`. The model path is absolute for this
 direct Node API. Session creation defaults to the CPU execution provider;
 explicit native session options remain caller-owned. The returned session
 record contains `id`, `model`, `state`, `loaded`, `error`, input/output names and
@@ -400,7 +404,7 @@ A recoverable run error keeps `stopping:false` and the loaded session usable.
 rejected load or inference. Unload joins worker exit and output delivery even
 when requesting termination fails; complete cleanup errors remain observable.
 
-Select `executionPreference: 'gpu'` to try the installed runtime's advertised
+With `executionTarget` omitted, select `executionPreference: 'gpu'` to try the installed runtime's advertised
 CUDA, TensorRT, DirectML, CoreML and WebGPU providers in that order, followed by
 CPU when no accelerator session can be created. Discovery runs once per load;
 each advertised candidate receives one actual session-creation attempt with CPU
@@ -413,18 +417,106 @@ DirectML attempts default `enableMemPattern` to `false` and `executionMode` to
 `'sequential'` as required by that provider; explicit caller values remain
 unchanged, including on the final CPU attempt.
 
-Automatic GPU selection adds an `execution` record to the loaded session and
-its ordinary state events: `preference`, complete `supportedBackends`,
+Every loaded session includes an `execution` record in its ordinary state
+events: `preference`, `requestedTarget`, `resolvedDevice`, `resolution`,
+`reason`, `configuredTarget`, `observedTarget`, complete `supportedBackends`,
 `selectedProviders`, ordered `attempts` with their full errors, `fallback`, and
-`discoveryError`. Each attempt records `executionProviders`, `status`
-(`configured` or `failed`), and `error`. `fallback: true` means the SDK created
+`discoveryError`. Each attempt records provider names in `executionProviders`,
+its requested `configuredTarget`, `status` (`configured` or `failed`), and
+`error`. The accepted top-level `configuredTarget` is
+`{source,executionProviders}`; it retains the complete provider options,
+including native numeric `deviceId` values. Its `source` is `cpu-default`,
+`session-options`, `gpu-preference`, `execution-target`, or
+`automatic-physical-target`. It remains `null` until session creation succeeds.
+`fallback: true` means the SDK attempted
 the final CPU session after GPU preference, including when no GPU candidate was
-advertised. Successful creation establishes an accepted provider configuration;
+advertised; `loaded` establishes whether creation succeeded. Successful creation establishes an accepted provider configuration;
 it does not establish that a GPU executed any graph nodes. If every attempt
 fails, the load error retains the complete attempt errors and `execution`
 record. Inference failures retain their existing behavior and do not replay
 inference on another provider.
 
+### Physical execution targets
+
+`executionTarget: {deviceId}` selects a physical identifier returned by the
+[execution-device catalog](execution-devices.md). The identifier is separate
+from an ONNX provider's numeric device ordinal. `executionTarget: null` requests
+automatic selection for this new session. Omission keeps the previous provider
+selection and exact explicit `sessionOptions` behavior described above.
+Generic ONNX sessions still require unloading a live ID before replacement;
+passing another target cannot silently replace that running session.
+
+The current physical routes are the catalog's whole-host CPU (`deviceId: 'cpu'`)
+and GPUs with an actual `addresses.dxgiAdapterIndex` when the installed ONNX
+binding advertises DirectML. DirectML receives
+`{name: 'dml', deviceId: dxgiAdapterIndex}` and retains CPU participation for
+unsupported graph operators. The index comes from DXGI enumeration joined to
+the physical device; a display order, DXCore order or CUDA ordinal is not
+substituted. No CPU socket/core affinity, physical CUDA mapping or NPU provider
+support is inferred from inventory.
+
+An explicit physical target gets one configuration attempt. Missing hardware,
+unsupported provider mapping and contradictory explicit session options report
+`LOCAL_AI_EXECUTION_TARGET_UNAVAILABLE`,
+`LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED`, or
+`LOCAL_AI_EXECUTION_TARGET_CONFLICT`, respectively. An explicit provider list
+must already select the mapped target; it is not overwritten. An automatic
+target conflicts with a fixed provider `deviceId` in explicit session options.
+Matching DirectML options retain caller-authored values and receive only the
+omitted `enableMemPattern: false` and `executionMode: 'sequential'` defaults.
+Native session-creation failures preserve their original errors. The SDK does
+not retry a physical target on another adapter or provider.
+
+For `executionTarget: null` with `executionPreference: 'gpu'` and no explicit
+provider list, automatic selection chooses the largest known positive
+`dedicatedMemoryMiB` among present hardware GPUs with a stable ID and actual
+DirectML mapping, when that provider is advertised. An integrated GPU remains
+eligible when it meets those same conditions. Once selected, that adapter
+gets one attempt. If no such candidate is established, the existing ordered
+provider attempts remain available and report their unresolved physical
+identity honestly. Omitted targets keep their existing selection behavior.
+
+```js
+await onnx.load({
+  id: 'cheese-radar',
+  model: absoluteModelPath,
+  executionPreference: 'gpu',
+  executionTarget: null
+});
+```
+
+`requestedTarget` preserves the requested physical record, or `null` for no
+explicit physical choice. `resolvedDevice` is the matched catalog record or
+`null`; `resolution` describes physical resolution, not engine compatibility.
+During initial physical discovery it is `null`; the resolver then supplies
+`matched`, `automatic`, `unavailable` or `unsupported`. `reason` explains the
+selection or inability. `observedTarget` remains `null`: ONNX Runtime Node
+exposes no actual physical placement observation here, including after a
+successful run. Accepted GPU configuration does not establish that every node
+ran on that GPU.
+
+The runtime creates a lazy catalog only when `executionDevices` is omitted and
+disposes only that owned catalog at close. Catalog preparation belongs to the
+loading session, follows its cancellation and is joined during release. It
+does not serialize independent sessions or delay browser rendering.
+
+### What Settings can know before loading
+
+`localai.devices` and `localai.resolveTarget` belong to the independent
+`execution-devices` service and do not load a model or wait for model-runtime
+preparation. They establish detected hardware and physical identity only.
+Settings can show those records and retain an application-owned preference
+keyed by provider/model. A matched physical ID is not a confirmed selectable
+target for every engine.
+
+The current ONNX binding's compiled-provider discovery runs in the session
+worker at an explicit load. There is no model-free ONNX capability query in
+this interface. Before that observation, engine compatibility is unknown;
+do not label every enumerated GPU or NPU supported. An advertised provider
+still does not establish usable provider libraries, model compatibility or
+actual execution. Consume the explicit load's configuration or complete
+failure, and keep observed placement unknown when it is not supplied.
+
 `run({id,feeds,fetches?,runOptions?,signal?})` returns the complete output-name
 map of `{type,dims,data}` tensors. Input records use that same shape with native
 typed data or string arrays. Optional `fetches` selects output names or supplies
@@ -456,7 +548,7 @@ Other sessions retain their own lifetimes.
 | Core method | Parameters | Result |
 | --- | --- | --- |
 | `onnx.status` | `{}` | Runtime availability and current `models` session records |
-| `onnx.load` | `{id,model,sessionOptions?}` | Loaded session; relative model paths resolve from `appRoot` |
+| `onnx.load` | `{id,model,sessionOptions?,executionPreference?,executionTarget?}` | Loaded session; relative model paths resolve from `appRoot` |
 | `onnx.run` | `{id,feeds,fetches?,runOptions?}` | Complete encoded tensor output map |
 | `onnx.unload` | `{id}` | Released session record |
 
@@ -477,7 +569,9 @@ onnx.close();
 
 The accessor exposes `load`, `run`, `unload`, `inspect`, `current`, `subscribe`
 and `close`. Request methods accept `signal` and optional `timeoutMs` (default
-`0`, no elapsed-time cutoff). It preserves full typed tensor values, including
+`0`, no elapsed-time cutoff). Load forwards `executionPreference` and preserves
+the native load's distinction between omitted and null `executionTarget`.
+Tensor transport preserves full typed tensor values, including
 64-bit integers, floating-point special values and strings, through the
 transport codec. `current()` adds `busy` and `closed` to its latest Core state.
 Closing the accessor cancels its requests and subscriptions; model unloading