arcane-os 0.79.1 → 0.80.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.80.0
+
+- Add `assetProjectionId` and `resourcePaths` to native decision factories and
+  direct, service and Core `decisions.load` calls. A supplied ready projection
+  uses complete already-prepared model/tokenizer files through the existing
+  model-assets owner, without upstream preparation or another download.
+- Retain projected files through actual native ONNX and tokenizer exit, including
+  failure and cancellation. Acquire incoming ownership before retiring a prior
+  activation; coalesce only equal source, complete mapping and device selections.
+  Surface provisional cleanup failures through load, unload and disposal.
+- Preserve caller preparation ownership, original companion-file paths, complete
+  rows and outputs, configured native paths and ordinary explicit upstream
+  loading. Explicit `assetProjectionId:null` returns to that configured source.
+  Missing projections or mapped members report their actual errors.
+- Keep native Laya FP32 selection and existing runtime dependencies unchanged.
+  This release adds no model variant, GGUF route, driver, model download on
+  startup or automatic preference change.
+
 ## 0.79.1
 
 - Classify generic speech-model progress callbacks as loading, reserving

package/README.md

@@ -20,7 +20,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.79.1` SDK contract. Development applications declare
+This checkout defines the `0.80.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;

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

@@ -45,14 +45,14 @@
       "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',executionTarget,signal}={})",
+      "signature": "createNativeDecisionModel({onnx,modelAssets,workingDirectory,paths,assetProjectionId,resourcePaths,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. 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."
+      "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. load({assetProjectionId,resourcePaths,executionTarget,signal}) retains omitted or undefined source, mapping and target fields from the latest selection, initially the factory configuration. A supplied ready projection takes precedence over configured paths and upstream settings; the existing modelAssets owner retains it directly without upstream preparation or fetching. resourcePaths maps model, tokenizer and tokenizerConfig to exact projection member.path values; complete companion files remain at their original relative paths. Missing projections or mapped members report their actual failure. assetProjectionId:null returns to configured paths or existing upstream preparation when no paths were configured. Separately, executionTarget: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. Equal source, complete mapping and target selections share activation; a changed selection cancels the earlier request and joins its actual ONNX/tokenizer cleanup before replacement. Incoming projection use is retained before retiring the previous activation; caller preparation ownership is independent, and native files remain retained through actual ONNX and tokenizer Worker exit. Unload ends native use; loading again after all ownership is released requires a fresh projection. pendingActivation reports the requested replacement and projected source/mapping 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. No preference writes, chat history or duplicate inference engine."
     },
     {
       "id": "core-decisions:createNativeDecisionService",
@@ -66,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. 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."
+      "normalization": "Registration starts no model or tokenizer. Explicit load obtains dependency-ready same-process owners and reacquires getONNXRuntime after recovery. Factory configuration accepts assetProjectionId, resourcePaths and executionTarget; direct load({assetProjectionId,resourcePaths,executionTarget,signal}) and Core decisions.load({assetProjectionId,resourcePaths,executionTarget}) preserve omitted/undefined selections, with the Core request signal forwarded separately. resourcePaths maps model, tokenizer and tokenizerConfig to exact ready projection member.path values; complete companion members retain their relative paths. Supplied projections take precedence over configured paths/upstream settings, are retained through the existing model-assets owner, and never invoke upstream preparation or fetching; unavailable projections or mapped members fail directly. assetProjectionId:null returns to configured paths or existing upstream preparation, independently of executionTarget:null requesting automatic device selection. Equal source, complete mapping and target selections coalesce; changed selections cancel pending work and join the prior model's disposal before replacement. Incoming retained ownership protects projection files while the previous activation retires; caller preparation ownership remains independent, and native use retains files through actual ONNX/tokenizer exit. pendingActivation includes a projected source/mapping separately 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",

package/docs/reference/model-assets.md

@@ -168,6 +168,39 @@ Closing a browser accessor does not by itself establish native unload.
 Explicitly release unused prepared projections. Core disposal also releases
 preparation ownership and cleans up after retained engine uses end.
 
+### Native Laya decisions
+
+The existing native decision owner also consumes ready projections through
+`decisions.load({assetProjectionId, resourcePaths, executionTarget?})` over Core,
+or the direct/service `load` method with an optional `signal`. Supply all three
+resource roles with exact projection member paths:
+
+```js
+try {
+    await client.invoke('decisions.load', {
+        assetProjectionId: projection.id,
+        resourcePaths: {
+            model: 'onnx/model.onnx',
+            tokenizer: 'tokenizer.json',
+            tokenizerConfig: 'tokenizer_config.json'
+        }
+    }, {signal, timeoutMs: 0});
+} finally {
+    await projection.release();
+}
+```
+
+The complete projection must also retain the graph's companion files, including
+`onnx/model.onnx_data` for the selected Laya FP32 graph. The native owner resolves
+the three roles from `retain(id).members` and uses those files directly without
+calling `prepare` or downloading again. It releases its native use only after
+actual ONNX and tokenizer exit; it never releases the caller's preparation
+ownership. Replacement acquires incoming ownership before retiring the prior
+activation, including when only its device changes. Unavailable or incomplete
+selections report their errors without an upstream fallback. See
+[native decisions](native-decisions.md#load-complete-files-already-stored-in-dbopfs)
+for source selection, cancellation and complete row/output contracts.
+
 `current()` returns `{closing,projections}`. Each projection reports its `id`,
 `directory`, `state`, ordered `members`, `preparationOwned`, number of native
 `uses`, and `error`. Core emits `modelAssets.state` for lifecycle changes.

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` | `{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.load` | `{assetProjectionId?, resourcePaths?, executionTarget?}`; explicit activation or source/device replacement, returning the ready lifecycle snapshot. The request signal cancels activation. A target is `{deviceId:string}` or `null`. |
 | `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. |
 
@@ -100,6 +100,76 @@ caller-owned files. For SDK-prepared files, the default selected upstream is
 - `onnx/model.onnx` and `onnx/model.onnx_data`;
 - `tokenizer.json` and `tokenizer_config.json`.
 
+## Load complete files already stored in DBOPFS
+
+Use the existing [model-assets projection](model-assets.md) for complete files
+already obtained through the application's DBOPFS model store. Pass every
+original member, including `onnx/model.onnx_data`, to `prepareCoreModelAssets`.
+The original relative paths and complete content remain unchanged:
+
+```js
+import {prepareCoreModelAssets} from 'arcane-os/ai/core-model-assets';
+
+const projection = await prepareCoreModelAssets({
+    client,
+    workingDirectory: selectedWorkingDirectory,
+    members: [
+        {path: 'onnx/model.onnx', file: storedGraph},
+        {path: 'onnx/model.onnx_data', file: storedGraphData},
+        {path: 'tokenizer.json', file: storedTokenizer},
+        {path: 'tokenizer_config.json', file: storedTokenizerConfig}
+    ],
+    signal
+});
+try {
+    await client.invoke('decisions.load', {
+        assetProjectionId: projection.id,
+        resourcePaths: {
+            model: 'onnx/model.onnx',
+            tokenizer: 'tokenizer.json',
+            tokenizerConfig: 'tokenizer_config.json'
+        },
+        executionTarget: {deviceId: 'cpu'}
+    }, {signal, timeoutMs: 0});
+} finally {
+    // The native activation owns a separate retain handle after loading.
+    await projection.release();
+}
+```
+
+Here the four `stored*` values are the complete original Blob/File members
+from the application's existing store. This projects those files; it performs
+no model download. The decision service must already be registered as above.
+After loading, invoke `decisions.evaluate` with the complete `rows`, then
+`decisions.unload` when that native activation is no longer needed.
+
+Direct model and service calls accept
+`load({assetProjectionId, resourcePaths, executionTarget, signal})`; their
+factory configuration accepts the same source selection. A direct model needs
+the existing `modelAssets` owner when selecting a projection. `resourcePaths`
+maps all three roles (`model`, `tokenizer`, `tokenizerConfig`) to exact
+`member.path` values in a ready projection. Additional companion members stay
+in its retained directory; the graph finds its external data under the exact
+relative filename it references. The SDK does not rename or reconstruct them.
+
+A supplied projection is retained and used directly. It takes precedence over
+configured `paths` and upstream settings and never invokes upstream preparation
+or retries with downloaded files. Missing, unfinished or released projections,
+and missing mapped resources, report their actual failure.
+
+Omitted or `undefined` source fields retain the selected source and mappings.
+`assetProjectionId: null` returns to the factory's configured `paths`, or its
+existing upstream preparation when no paths were configured. Selecting another
+projection or changing any resource mapping replaces the activation even when
+the execution target stays the same. Equal source, mapping and device selections
+coalesce. The incoming retain is acquired before the prior activation retires,
+so device replacement can reuse a projection after the caller has released its
+preparation ownership. Superseded pending retains are released as their cleanup
+settles. Unload ends the native use; if no preparation or other use remains,
+create a fresh projection from the stored originals before loading again.
+
+## Existing upstream preparation
+
 `model` selects the upstream Hugging Face repository and `revision` its
 revision. Native preparation performs normal upstream fetches only during
 explicit `load()`. It streams complete members through the existing working
@@ -160,13 +230,14 @@ 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
+transport when the selection is `undefined`. A projected selection also includes
+`assetProjectionId` and its complete `resourcePaths` mapping. 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
+Concurrent loads for the same source, resource mapping and target share their
+pending activation. A different selection 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
@@ -209,7 +280,7 @@ 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 selecting the same target share one explicit activation.
+Concurrent callers selecting the same source, mapping and 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
@@ -219,7 +290,8 @@ cleanup; `dispose()` is terminal. Readiness is revoked as disposal begins.
 Retained model files remain owned until the ONNX and tokenizer Workers really
 exit. A rejected load, inference or termination request alone does not permit
 file deletion. Cleanup joins active operations and native output delivery,
-preserves cleanup errors, then releases only its working projection. It never
+preserves cleanup errors, then releases its native-use handle. Preparation
+ownership of a supplied projection remains with its caller. It never
 deletes supplied `paths`. A failed ordinary row does not destroy a healthy
 loaded session or cancel sibling evaluations. The ONNX owner's `stopping:true`
 retires decision readiness immediately on terminal Worker failure or shutdown,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.79.1",
+  "version": "0.80.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/src/core/services/decisions.mjs

@@ -8,20 +8,35 @@ function sameExecutionTarget(left, right) {
     return left === right || (left != null && right != null && left.deviceId !== undefined && left.deviceId === right.deviceId);
 }
 
+function sameActivation(left, right) {
+    if (!left || !right || !sameExecutionTarget(left.executionTarget, right.executionTarget) || left.assetProjectionId !== right.assetProjectionId) return false;
+    if (left.resourcePaths === right.resourcePaths) return true;
+    if (!left.resourcePaths || !right.resourcePaths) return false;
+    const entries = Object.entries(left.resourcePaths);
+    return entries.length === Object.keys(right.resourcePaths).length
+        && entries.every(function sameResource([role, member]) { return right.resourcePaths[role] === member; });
+}
+
 /** 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']});
     const lifetime = new AbortController();
+    const loads = new Set();
+    const provisionalCleanupFailures = [];
     let context;
+    let modelAssetOwner;
     let model;
     let loading;
     let loadController;
     let releasing;
     let closing;
     let unsubscribe;
-    let selectedTarget = configuration.executionTarget;
-    let loadingTarget;
-    let loadedTarget;
+    let selectedActivation = {
+        executionTarget: configuration.executionTarget,
+        ...(configuration.assetProjectionId == null ? {} : {assetProjectionId: configuration.assetProjectionId, resourcePaths: configuration.resourcePaths && {...configuration.resourcePaths}})
+    };
+    let loadingActivation;
+    let loadedActivation;
 
     function current() {
         const snapshot = model?.current() ?? {
@@ -30,10 +45,10 @@ export function createNativeDecisionService(configuration = {}, {appRoot = proce
             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));
+        const pending = Boolean(loading) && (!snapshot.loaded || !sameActivation(loadedActivation, loadingActivation));
         return {
             ...snapshot, busy: snapshot.busy || pending,
-            pendingActivation: pending ? {executionTarget: loadingTarget} : snapshot.pendingActivation ?? null
+            pendingActivation: pending ? {...loadingActivation} : snapshot.pendingActivation ?? null
         };
     }
 
@@ -51,57 +66,92 @@ export function createNativeDecisionService(configuration = {}, {appRoot = proce
 
     function operationSignal(signal) { return signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal; }
 
-    function load({signal, executionTarget: requestedTarget} = {}) {
+    function load({signal, executionTarget: requestedTarget, assetProjectionId: requestedProjection, resourcePaths: requestedPaths} = {}) {
         operationSignal(signal).throwIfAborted();
         if (!context) throw new CoreError({code: 'CORE_NOT_READY', message: 'Register and start the decision service with Core before loading.'});
-        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 projection = requestedProjection === undefined ? selectedActivation.assetProjectionId : requestedProjection;
+        const mapping = requestedPaths === undefined ? selectedActivation.resourcePaths : requestedPaths;
+        const selection = {
+            executionTarget: requestedTarget === undefined ? selectedActivation.executionTarget : requestedTarget,
+            ...(projection == null ? {} : {assetProjectionId: projection, resourcePaths: mapping && typeof mapping === 'object' && !Array.isArray(mapping) ? {...mapping} : mapping})
+        };
+        if (loading && !loadController.signal.aborted && sameActivation(loadingActivation, selection)) return observeLoad(loading, loadController, signal);
+        if (!loading && model?.current().loaded && sameActivation(loadedActivation, selection)) 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;
+        let retained;
+        let retainError;
         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.
-            const [localAI, modelAssets] = await Promise.all([
-                context.getService('local-ai'),
-                configuration.paths ? undefined : context.getService('model-assets')
-            ]);
-            selectedSignal.throwIfAborted();
-            const paths = configuration.paths && Object.fromEntries(
-                Object.entries(configuration.paths).map(function nativePath([name, value]) { return [name, path.resolve(appRoot, value)]; })
-            );
-            model = createNativeDecisionModel({
-                ...configuration, paths, onnx: localAI.getONNXRuntime(), modelAssets, executionTarget: target,
-                signal: lifetime.signal
-            });
-            unsubscribe = model.subscribe(function modelStateChanged() { publish(); });
-            const result = await model.load({signal: selectedSignal});
-            selectedSignal.throwIfAborted();
-            loadedTarget = target;
-            return result;
+            const replaced = new CoreError({name: 'AbortError', code: 'ARCANE_AI_REQUEST_ABORTED', message: 'The native decision activation request was replaced.'});
+            try {
+                if (retainError) throw retainError;
+                selectedSignal.throwIfAborted();
+                if (loading !== task) throw replaced;
+                // Only explicit load waits for these owners. A provisional use
+                // protects incoming files while the preceding model retires.
+                const [localAI, modelAssets] = await Promise.all([
+                    context.getService('local-ai'),
+                    configuration.paths && selection.assetProjectionId === undefined ? undefined : context.getService('model-assets')
+                ]);
+                selectedSignal.throwIfAborted();
+                if (loading !== task) throw replaced;
+                if (modelAssets) modelAssetOwner = modelAssets;
+                if (selection.assetProjectionId !== undefined && !retained) retained = modelAssets.retain(selection.assetProjectionId);
+                selectedSignal.throwIfAborted();
+                if (loading !== task) throw replaced;
+                previousController?.abort(replaced);
+                if (precedingRelease) await precedingRelease;
+                if (previousLoad) await Promise.allSettled([previousLoad]);
+                selectedSignal.throwIfAborted();
+                if (loading !== task) throw replaced;
+                if (model) await model.dispose();
+                selectedSignal.throwIfAborted();
+                if (loading !== task) throw replaced;
+                unsubscribe?.();
+                const paths = configuration.paths && Object.fromEntries(
+                    Object.entries(configuration.paths).map(function nativePath([name, value]) { return [name, path.resolve(appRoot, value)]; })
+                );
+                model = createNativeDecisionModel({
+                    ...configuration, paths, onnx: localAI.getONNXRuntime(), modelAssets,
+                    executionTarget: selection.executionTarget, assetProjectionId: selection.assetProjectionId,
+                    resourcePaths: selection.resourcePaths, signal: lifetime.signal
+                });
+                unsubscribe = model.subscribe(function modelStateChanged() { publish(); });
+                const result = await model.load({signal: selectedSignal});
+                selectedSignal.throwIfAborted();
+                loadedActivation = selection;
+                return result;
+            } finally {
+                previousController?.abort(replaced);
+                try { await retained?.release(); }
+                catch (error) {
+                    provisionalCleanupFailures.push(error);
+                    throw error;
+                }
+            }
         });
         function settled() {
+            loads.delete(task);
             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); });
+        loads.add(task);
         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.'}));
+        loadingActivation = selection;
+        selectedActivation = selection;
+        // A pending predecessor may hold the final native use while its workers
+        // exit. Take our use before making that predecessor's cleanup runnable.
+        if (selection.assetProjectionId !== undefined && modelAssetOwner) {
+            try { retained = modelAssetOwner.retain(selection.assetProjectionId); }
+            catch (error) { retainError = error; }
+        }
         publish();
         return observeLoad(task, controller, signal);
     }
@@ -133,9 +183,12 @@ export function createNativeDecisionService(configuration = {}, {appRoot = proce
         // rather than wait for it to download and activate first.
         loadController?.abort(new CoreError({name: 'AbortError', code: 'ARCANE_AI_REQUEST_ABORTED', message: 'The native decision load was cancelled.'}));
         const task = model?.unload() ?? Promise.resolve();
-        const acceptedLoad = loading;
+        const acceptedLoads = [...loads];
         releasing = Promise.resolve().then(async function releaseSelectedModel() {
-            const results = await Promise.allSettled([task, acceptedLoad]);
+            const results = await Promise.allSettled([task, ...acceptedLoads]);
+            if (provisionalCleanupFailures.length) throw new AggregateError([
+                ...(results[0].status === 'rejected' ? [results[0].reason] : []), ...provisionalCleanupFailures
+            ], 'Releasing native decision resources failed.');
             if (results[0].status === 'rejected') throw results[0].reason;
             return current();
         });
@@ -149,7 +202,8 @@ export function createNativeDecisionService(configuration = {}, {appRoot = proce
         const reason = new CoreError({name: 'AbortError', code: 'ARCANE_AI_REQUEST_ABORTED', message: 'The native decision service is closing.'});
         closing = Promise.resolve().then(async function closeDecisionService() {
             const failures = [];
-            try { await loading; } catch (error) { if (!lifetime.signal.aborted) failures.push(error); }
+            await Promise.allSettled([...loads]);
+            failures.push(...provisionalCleanupFailures);
             try { await model?.dispose(); } catch (error) { failures.push(error); }
             unsubscribe?.();
             publish();
@@ -165,7 +219,12 @@ export function createNativeDecisionService(configuration = {}, {appRoot = proce
         start(serviceContext) { context = serviceContext; },
         methods: {
             'decisions.status': current,
-            'decisions.load': function loadRequest(parameters, request) { return load({executionTarget: parameters?.executionTarget, signal: request.signal}); },
+            'decisions.load': function loadRequest(parameters, request) {
+                return load({
+                    executionTarget: parameters?.executionTarget, assetProjectionId: parameters?.assetProjectionId,
+                    resourcePaths: parameters?.resourcePaths, 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/local-ai/decisions.mjs

@@ -17,18 +17,29 @@ function sameExecutionTarget(left, right) {
     return left === right || (left != null && right != null && left.deviceId !== undefined && left.deviceId === right.deviceId);
 }
 
+function sameActivation(left, right) {
+    if (!sameExecutionTarget(left.executionTarget, right.executionTarget) || left.assetProjectionId !== right.assetProjectionId) return false;
+    if (left.resourcePaths === right.resourcePaths) return true;
+    if (!left.resourcePaths || !right.resourcePaths) return false;
+    const entries = Object.entries(left.resourcePaths);
+    return entries.length === Object.keys(right.resourcePaths).length
+        && entries.every(function sameResource([role, member]) { return right.resourcePaths[role] === member; });
+}
+
 /**
  * One explicitly activated Laya FP32 model using an existing native ONNX owner.
  * It does not create another inference runtime or load on construction.
  */
 export function createNativeDecisionModel({
-    onnx, modelAssets, workingDirectory, paths,
+    onnx, modelAssets, workingDirectory, paths, assetProjectionId, resourcePaths,
     model = 'onnx-community/laya-typed-decisions-ONNX', revision = 'main',
     dtype = 'fp32', sessionOptions, executionPreference = 'gpu', executionTarget, signal
 } = {}) {
     if (dtype !== 'fp32') throw new TypeError('This native Laya graph selection requires dtype fp32.');
     const owner = {};
     const events = createArcaneEventSource(owner, {source: 'native-decisions', eventTypes: [STATE_EVENT]});
+    const loads = new Set();
+    const provisionalCleanupFailures = [];
     let activation;
     let releaseTask;
     let disposal;
@@ -37,7 +48,10 @@ export function createNativeDecisionModel({
     let progress = null;
     let lastError = null;
     let execution = null;
-    let selectedTarget = executionTarget;
+    let selectedActivation = {
+        executionTarget,
+        ...(assetProjectionId == null ? {} : {assetProjectionId, resourcePaths: resourcePaths && {...resourcePaths}})
+    };
     let pendingActivation;
 
     function current() {
@@ -48,7 +62,7 @@ export function createNativeDecisionModel({
             activeRequests: activation?.jobs.size ?? 0, progress,
             error: lastError ? serializeCoreError(lastError) : null,
             execution,
-            pendingActivation: pending ? {executionTarget: pending.executionTarget} : null
+            pendingActivation: pending ? {...pending.selection} : null
         };
     }
 
@@ -131,6 +145,22 @@ export function createNativeDecisionModel({
     }
 
     async function prepareFiles(entry) {
+        if (entry.selection.assetProjectionId !== undefined) {
+            const mapping = entry.selection.resourcePaths;
+            if (!mapping || typeof mapping !== 'object' || Array.isArray(mapping)) {
+                throw new TypeError('Projected decisions require resourcePaths for model, tokenizer and tokenizerConfig.');
+            }
+            const files = {};
+            for (const role of ['model', 'tokenizer', 'tokenizerConfig']) {
+                const member = entry.retained.members.find(function selectedMember(value) { return value.path === mapping[role]; });
+                if (!member) throw new CoreError({
+                    code: 'ARCANE_DECISION_RESOURCE_UNAVAILABLE',
+                    message: `The retained decision projection has no member ${String(mapping[role])} for ${role}.`
+                });
+                files[role] = member.nativePath;
+            }
+            return files;
+        }
         if (paths) return paths;
         if (!modelAssets) throw new CoreError({code: 'ARCANE_DECISION_ASSETS_UNAVAILABLE', message: 'Native decisions need prepared paths or the Core model-assets owner.'});
         const base = `https://huggingface.co/${model}/resolve/${encodeURIComponent(revision)}/`;
@@ -149,8 +179,13 @@ export function createNativeDecisionModel({
         return {model: files['onnx/model.onnx'], tokenizer: files['tokenizer.json'], tokenizerConfig: files['tokenizer_config.json']};
     }
 
-    function beginActivation(target) {
-        const entry = {id: randomUUID(), controller: new AbortController(), jobs: new Set(), prepared: false, onnxLoadStarted: false, executionTarget: target};
+    function beginActivation(request) {
+        const entry = {
+            id: randomUUID(), controller: new AbortController(), jobs: new Set(), prepared: false, onnxLoadStarted: false,
+            selection: request.selection, executionTarget: request.selection.executionTarget, retained: request.retained
+        };
+        request.retained = undefined;
+        request.entry = entry;
         activation = entry;
         state = 'loading';
         progress = {phase: 'preparing-model'};
@@ -223,33 +258,49 @@ export function createNativeDecisionModel({
         }).finally(function detachLoadCaller() { operationSignal?.removeEventListener('abort', abort); });
     }
 
-    async function load({signal: operationSignal, executionTarget: requestedTarget} = {}) {
+    async function load({signal: operationSignal, executionTarget: requestedTarget, assetProjectionId: requestedProjection, resourcePaths: requestedPaths} = {}) {
         assertOpen(operationSignal);
-        const target = requestedTarget === undefined ? selectedTarget : requestedTarget;
-        if (pendingActivation && !pendingActivation.controller.signal.aborted && sameExecutionTarget(pendingActivation.executionTarget, target)) {
+        const projection = requestedProjection === undefined ? selectedActivation.assetProjectionId : requestedProjection;
+        const mapping = requestedPaths === undefined ? selectedActivation.resourcePaths : requestedPaths;
+        const selection = {
+            executionTarget: requestedTarget === undefined ? selectedActivation.executionTarget : requestedTarget,
+            ...(projection == null ? {} : {assetProjectionId: projection, resourcePaths: mapping && typeof mapping === 'object' && !Array.isArray(mapping) ? {...mapping} : mapping})
+        };
+        if (pendingActivation && !pendingActivation.controller.signal.aborted && sameActivation(pendingActivation.selection, selection)) {
             return observeLoad(pendingActivation, operationSignal);
         }
-        if (!pendingActivation && activation && sameExecutionTarget(activation.executionTarget, target)) {
+        if (!pendingActivation && activation && sameActivation(activation.selection, selection)) {
             return awaitActivation(activation, operationSignal);
         }
         const previous = pendingActivation;
-        const request = {executionTarget: target, controller: new AbortController()};
+        const request = {selection, 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);
+            try {
+                if (request.error) throw request.error;
+                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);
+                return await awaitActivation(request.entry, request.controller.signal);
+            } finally {
+                // A superseded request may own files without ever starting workers.
+                try { await request.retained?.release(); }
+                catch (error) {
+                    provisionalCleanupFailures.push(error);
+                    throw error;
+                } finally { request.retained = undefined; }
+            }
         });
         function settled(error) {
+            loads.delete(request.task);
             request.detach?.();
             if (pendingActivation !== request) return;
             pendingActivation = undefined;
-            if (!request.entry && !activation && !disposed && state === 'loading') {
+            if (!request.entry && !activation && !disposed && (state === 'loading' || request.error)) {
                 state = request.controller.signal.aborted ? 'unloaded' : 'error';
                 progress = null;
                 lastError = request.controller.signal.aborted ? null : error;
@@ -257,14 +308,24 @@ export function createNativeDecisionModel({
             publish();
         }
         request.task.then(function loaded() { settled(); }, function loadFailed(error) { settled(error); }).catch(reportCleanupFailure);
+        loads.add(request.task);
         pendingActivation = request;
-        selectedTarget = target;
-        const reason = cancellation('The decision execution target was replaced.');
+        selectedActivation = selection;
+        try {
+            if (selection.assetProjectionId !== undefined) {
+                if (!modelAssets) throw new CoreError({code: 'ARCANE_DECISION_ASSETS_UNAVAILABLE', message: 'Projected decisions require the Core model-assets owner.'});
+                // retain is synchronous at the model-assets public boundary.
+                // Acquire before retiring the last native use of these files.
+                request.retained = modelAssets.retain(selection.assetProjectionId);
+            }
+        } catch (error) { request.error = error; }
+        const reason = cancellation('The decision activation was replaced.');
+        if (pendingActivation !== request) request.controller.abort(reason);
         previous?.controller.abort(reason);
-        if (activation && !sameExecutionTarget(activation.executionTarget, target)) stop(activation, reason);
+        if (!request.error && !request.controller.signal.aborted && activation && !sameActivation(activation.selection, selection)) stop(activation, reason);
         precedingRelease = !activation ? releaseTask : undefined;
-        if (!activation && !precedingRelease) {
-            request.entry = beginActivation(target);
+        if (!request.error && !request.controller.signal.aborted && !activation && !precedingRelease) {
+            request.entry = beginActivation(request);
             request.detach = observeCancellation(request.entry, request.controller.signal);
         }
         publish();
@@ -316,8 +377,11 @@ export function createNativeDecisionModel({
         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 (!loads.size && !provisionalCleanupFailures.length) return release;
+        return Promise.allSettled([release, ...loads]).then(function releasedActivation(results) {
+            if (provisionalCleanupFailures.length) throw new AggregateError([
+                ...(results[0].status === 'rejected' ? [results[0].reason] : []), ...provisionalCleanupFailures
+            ], 'Releasing native decision resources failed.');
             if (results[0].status === 'rejected') throw results[0].reason;
             return current();
         });
@@ -332,7 +396,10 @@ export function createNativeDecisionModel({
         let release;
         disposal = Promise.resolve().then(async function disposeNativeModel() {
             try {
-                const results = await Promise.allSettled([release, pending?.task]);
+                const results = await Promise.allSettled([release, ...loads]);
+                if (provisionalCleanupFailures.length) throw new AggregateError([
+                    ...(results[0].status === 'rejected' ? [results[0].reason] : []), ...provisionalCleanupFailures
+                ], 'Releasing native decision resources failed.');
                 if (results[0].status === 'rejected') throw results[0].reason;
             }
             finally { state = 'disposed'; publish(); events.dispose(); }