arcane-os 0.88.1 → 0.89.0

package/src/local-ai/llama-execution-windows.ps1

@@ -0,0 +1,158 @@
+# Invoked through stdin by the SDK's owned process; stdout contains one JSON record.
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+
+try {
+    # Enumerate the installed driver's devices in this helper only. An empty
+    # CUDA_VISIBLE_DEVICES value hides every device, so remove the inherited value.
+    [Environment]::SetEnvironmentVariable('CUDA_VISIBLE_DEVICES', $null, [EnvironmentVariableTarget]::Process)
+
+    Add-Type -TypeDefinition @'
+using System;
+using System.Globalization;
+using System.Runtime.InteropServices;
+using System.Text;
+
+namespace Arcane.LocalAI {
+    [StructLayout(LayoutKind.Sequential)]
+    public struct AdapterLuid {
+        public uint LowPart;
+        public int HighPart;
+    }
+
+    public sealed class CudaDeviceIdentity {
+        public string Uuid;
+        public uint NodeMask;
+        public AdapterLuid Luid;
+        public string UuidFunction;
+
+        // NVIDIA CU_DEVICE_ATTRIBUTE_TCC_DRIVER is 35. CUDA's Windows LUID
+        // contract is undefined in TCC mode, so only WDDM devices can be matched.
+        // https://nvidia.github.io/cuda-python/cuda-bindings/latest/module/driver.html
+        private const int TccDriverAttribute = 35;
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuInit(uint flags);
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuDeviceGetCount(out int count);
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuDeviceGet(out int device, int ordinal);
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuDeviceGetAttribute(out int value, int attribute, int device);
+
+        // CUDA writes the native Windows LUID layout: unsigned LowPart followed
+        // by signed HighPart. Marshaling the struct preserves that native layout.
+        // https://learn.microsoft.com/en-us/windows/win32/api/winnt/ns-winnt-luid
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuDeviceGetLuid(out AdapterLuid luid, out uint nodeMask, int device);
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuDeviceGetUuid_v2([Out] byte[] uuid, int device);
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuDeviceGetUuid([Out] byte[] uuid, int device);
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuGetErrorName(int error, out IntPtr name);
+
+        [DllImport("nvcuda.dll", ExactSpelling = true)]
+        private static extern int cuGetErrorString(int error, out IntPtr message);
+
+        private static void Check(int result, string operation) {
+            if (result == 0) return;
+            IntPtr name;
+            IntPtr message;
+            int nameResult = cuGetErrorName(result, out name);
+            int messageResult = cuGetErrorString(result, out message);
+            throw new InvalidOperationException(
+                operation + " returned CUDA error " + result + ": " +
+                (nameResult == 0 ? Marshal.PtrToStringAnsi(name) : "cuGetErrorName returned " + nameResult) + "; " +
+                (messageResult == 0 ? Marshal.PtrToStringAnsi(message) : "cuGetErrorString returned " + messageResult)
+            );
+        }
+
+        private static string ReadUuid(int device, out string function) {
+            // CUuuid's 16 native octets are unavoidable ABI storage. CUDA UUID
+            // text keeps their order; System.Guid would reverse several fields.
+            byte[] uuid = new byte[16];
+            int result;
+            try {
+                result = cuDeviceGetUuid_v2(uuid, device);
+                function = "cuDeviceGetUuid_v2";
+            } catch (EntryPointNotFoundException) {
+                // Older drivers expose the original function for this same
+                // device. No device or backend selection changes on this path.
+                result = cuDeviceGetUuid(uuid, device);
+                function = "cuDeviceGetUuid";
+            }
+            Check(result, function);
+            StringBuilder text = new StringBuilder("GPU-");
+            for (int index = 0; index < uuid.Length; index++) {
+                if (index == 4 || index == 6 || index == 8 || index == 10) text.Append('-');
+                text.Append(uuid[index].ToString("x2", CultureInfo.InvariantCulture));
+            }
+            return text.ToString();
+        }
+
+        public static CudaDeviceIdentity Resolve(uint lowPart, int highPart) {
+            Check(cuInit(0), "cuInit");
+            int count;
+            Check(cuDeviceGetCount(out count), "cuDeviceGetCount");
+            CudaDeviceIdentity matched = null;
+            int tccCount = 0;
+            for (int ordinal = 0; ordinal < count; ordinal++) {
+                int device;
+                Check(cuDeviceGet(out device, ordinal), "cuDeviceGet(" + ordinal + ")");
+                int tcc;
+                Check(cuDeviceGetAttribute(out tcc, TccDriverAttribute, device), "cuDeviceGetAttribute(TCC_DRIVER, " + ordinal + ")");
+                if (tcc != 0) {
+                    tccCount++;
+                    continue;
+                }
+                AdapterLuid luid;
+                uint nodeMask;
+                Check(cuDeviceGetLuid(out luid, out nodeMask, device), "cuDeviceGetLuid(" + ordinal + ")");
+                if (luid.LowPart != lowPart || luid.HighPart != highPart) continue;
+                if (matched != null) {
+                    throw new InvalidOperationException("Multiple CUDA devices share the selected adapter LUID; the catalog selection cannot identify one CUDA device.");
+                }
+                string function;
+                string uuid = ReadUuid(device, out function);
+                matched = new CudaDeviceIdentity { Uuid = uuid, NodeMask = nodeMask, Luid = luid, UuidFunction = function };
+            }
+            if (matched == null) {
+                throw new InvalidOperationException(
+                    "No WDDM CUDA device matches the selected adapter LUID. CUDA devices enumerated: " + count +
+                    "; TCC devices without a defined LUID: " + tccCount + "."
+                );
+            }
+            return matched;
+        }
+    }
+}
+'@
+
+    $lowPart = [uint32]::Parse($env:ARCANE_LLAMA_LUID_LOW, [Globalization.CultureInfo]::InvariantCulture)
+    $highPart = [int32]::Parse($env:ARCANE_LLAMA_LUID_HIGH, [Globalization.CultureInfo]::InvariantCulture)
+    $device = [Arcane.LocalAI.CudaDeviceIdentity]::Resolve($lowPart, $highPart)
+    [ordered]@{
+        uuid = $device.Uuid
+        nodeMask = $device.NodeMask
+        adapterLuid = [ordered]@{
+            lowPart = $device.Luid.LowPart
+            highPart = $device.Luid.HighPart
+        }
+        driverMode = 'wddm'
+        uuidFunction = $device.UuidFunction
+    } | ConvertTo-Json -Depth 4 -Compress
+} catch {
+    [Console]::Error.WriteLine($_.Exception.ToString())
+    if ($null -ne $_.ErrorDetails) { [Console]::Error.WriteLine($_.ErrorDetails.Message) }
+    if ($null -ne $_.InvocationInfo) { [Console]::Error.WriteLine($_.InvocationInfo.PositionMessage) }
+    if ($_.ScriptStackTrace) { [Console]::Error.WriteLine($_.ScriptStackTrace) }
+    exit 1
+}

package/src/local-ai/llama-execution.mjs

@@ -0,0 +1,169 @@
+import {readFile} from 'node:fs/promises';
+import path from 'node:path';
+import Is from 'strong-type';
+import {ArcaneError, ERROR_CODES, throwIfAborted} from '../errors.mjs';
+import {runProcess} from '../process.mjs';
+
+const is = new Is(false);
+
+/**
+ * Resolve one explicit catalog selection for a new native llama server lifetime.
+ * Default selection performs no discovery. Hardware identity and launch options
+ * are configuration evidence; the server's observed execution target stays null.
+ */
+export async function resolveLlamaExecution({
+    executionTarget, executionDevices, runtime, signal, onEvent
+} = {}) {
+    throwIfAborted(signal);
+    if (executionTarget === undefined || executionTarget === null) {
+        const cpu = runtime?.requestedBackend === 'cpu';
+        return {
+            args: cpu ? ['--device', 'none', '--gpu-layers', '0'] : [],
+            env: {},
+            execution: {
+                requestedTarget: null,
+                resolvedDevice: null,
+                resolution: 'automatic',
+                reason: cpu ? 'runtime-backend-selected' : 'engine-default-required',
+                configuredTarget: cpu ? {backend: 'cpu', device: 'none', gpuLayers: 0} : null,
+                observedTarget: null,
+                fallback: false
+            }
+        };
+    }
+    if (!is.function(executionDevices?.resolveTarget)) {
+        throw new ArcaneError(
+            'LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED',
+            'Explicit llama.cpp device selection requires the host execution-device catalog.',
+            {details: {requestedTarget: executionTarget}}
+        );
+    }
+    // The persistent device ID is resolved again for this load because a Windows
+    // adapter LUID belongs to the current host session, not the saved selection.
+    const resolution = await executionDevices.resolveTarget(
+        {executionTarget, refresh: true, signal}
+    );
+    throwIfAborted(signal);
+    const execution = {
+        ...resolution,
+        configuredTarget: null,
+        observedTarget: null,
+        fallback: false
+    };
+    if (resolution.resolution !== 'matched' || !resolution.resolvedDevice) {
+        throw new ArcaneError(
+            resolution.resolution === 'unsupported'
+                ? 'LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED'
+                : 'LOCAL_AI_EXECUTION_TARGET_UNAVAILABLE',
+            `The selected llama.cpp execution device could not be resolved: ${resolution.reason}.`,
+            {details: execution}
+        );
+    }
+    const device = resolution.resolvedDevice;
+    if (device.kind === 'cpu') {
+        execution.configuredTarget = {
+            backend: 'cpu', deviceId: device.deviceId, device: 'none', gpuLayers: 0
+        };
+        return {args: ['--device', 'none', '--gpu-layers', '0'], env: {}, execution};
+    }
+    if (device.kind !== 'gpu' || process.platform !== 'win32') {
+        throw new ArcaneError(
+            'LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED',
+            `Exact llama.cpp ${device.kind} selection is unavailable on ${process.platform}.`,
+            {details: execution}
+        );
+    }
+    if (runtime?.requestedBackend === 'cpu') {
+        throw new ArcaneError(
+            'LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED',
+            'The selected GPU is incompatible with the explicit llama.cpp CPU runtime configuration.',
+            {details: execution}
+        );
+    }
+    if (runtime?.backend !== 'cuda') {
+        throw new ArcaneError(
+            'LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED',
+            'Exact Windows GPU selection requires a llama.cpp CUDA runtime.',
+            {details: {...execution, runtimeBackend: runtime?.backend ?? null}}
+        );
+    }
+    const adapterLuid = device.addresses?.adapterLuid;
+    if (!is.integer(adapterLuid?.lowPart) || adapterLuid.lowPart < 0 || adapterLuid.lowPart > 0xffffffff
+        || !is.integer(adapterLuid?.highPart) || adapterLuid.highPart < -0x80000000 || adapterLuid.highPart > 0x7fffffff) {
+        throw new ArcaneError(
+            'LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED',
+            'The selected Windows GPU has no current adapter LUID for CUDA identity resolution.',
+            {details: execution}
+        );
+    }
+    const identity = await resolveWindowsCudaIdentity({adapterLuid, signal, onEvent});
+    throwIfAborted(signal);
+    execution.configuredTarget = {
+        backend: 'cuda',
+        deviceId: device.deviceId,
+        device: 'CUDA0',
+        uuid: identity.uuid,
+        nodeMask: identity.nodeMask,
+        adapterLuid: identity.adapterLuid,
+        driverMode: identity.driverMode,
+        identitySource: 'nvidia-cuda-driver',
+        uuidFunction: identity.uuidFunction,
+        splitMode: 'none',
+        mainGpu: 0,
+        gpuLayers: 'all'
+    };
+    if (identity.diagnostics !== '') {
+        execution.diagnostics = [{source: 'cuda-driver', message: identity.diagnostics}];
+    }
+    // A single full UUID makes CUDA0 identify the selected physical GPU in the
+    // fresh server process, independent of DXGI or inherited CUDA ordinal order.
+    return {
+        args: ['--device', 'CUDA0', '--split-mode', 'none', '--main-gpu', '0', '--gpu-layers', 'all'],
+        env: {CUDA_VISIBLE_DEVICES: identity.uuid},
+        execution
+    };
+}
+
+async function resolveWindowsCudaIdentity({adapterLuid, signal, onEvent}) {
+    const script = await readFile(
+        new URL('./llama-execution-windows.ps1', import.meta.url),
+        {encoding: 'utf8', signal}
+    );
+    throwIfAborted(signal);
+    const command = process.env.SystemRoot
+        ? path.join(process.env.SystemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
+        : 'powershell.exe';
+    async function* identityInput() {
+        yield `& {\n${script}\n}\n\n`;
+    }
+    const result = await runProcess(
+        command,
+        ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', '-'],
+        {
+            signal,
+            onEvent,
+            env: {
+                ARCANE_LLAMA_LUID_LOW: String(adapterLuid.lowPart),
+                ARCANE_LLAMA_LUID_HIGH: String(adapterLuid.highPart)
+            },
+            input: identityInput(),
+            captureOutput: true,
+            emitOutputEvents: false
+        }
+    );
+    throwIfAborted(signal);
+    let identity;
+    try {
+        identity = JSON.parse(result.stdout);
+        if (!is.string(identity?.uuid) || identity.uuid === '' || !is.integer(identity.nodeMask)) {
+            throw new TypeError('The CUDA driver identity helper returned no device identity.');
+        }
+    } catch (error) {
+        throw new ArcaneError(
+            ERROR_CODES.operationFailed,
+            'Could not read the selected CUDA device identity.',
+            {cause: error, details: result}
+        );
+    }
+    return {...identity, diagnostics: result.stderr};
+}

package/src/local-ai/server.mjs

@@ -4,6 +4,7 @@ import Is from 'strong-type';
 import {ArcaneError,ERROR_CODES,errorRecord,normalizeError,throwIfAborted} from '../errors.mjs';
 import {createEventQueue} from '../event-queue.mjs';
 import {runProcess} from '../process.mjs';
+import {resolveLlamaExecution} from './llama-execution.mjs';
 
 const is=new Is(false);
 
@@ -48,17 +49,21 @@ async function probeServer(id,url,signal){
     return observed;
 }
 
-export function createLocalAIServer({id,configuration={},runtime,appRoot,signal,onEvent,onState}={}){
+export function createLocalAIServer({id,configuration={},runtime,appRoot,signal,onEvent,onState,onExit,executionDevices,requireManaged=false}={}){
     if(!['llama.cpp','ollama'].includes(id)){
         throw new ArcaneError(ERROR_CODES.usage,`Unsupported local AI server: ${String(id)}.`);
     }
     const url=localAIServerURL(id,configuration);
     const endpoint=new URL(url);
+    const managedSelection=requireManaged||(id==='llama.cpp'&&(configuration.executionTarget!==undefined
+        ||(runtime?.requestedBackend&&runtime.requestedBackend!=='auto')));
     const controller=new AbortController();
     const operationSignal=signal?AbortSignal.any([signal,controller.signal]):controller.signal;
     const events=createEventQueue(onEvent,{onFailure:fail});
     let current={id,url,state:'starting',available:false,owned:false};
     let owned=false;
+    let external=false;
+    let execution;
     let processTask=null;
     let processObservation=null;
     let startupTask=null;
@@ -70,6 +75,8 @@ export function createLocalAIServer({id,configuration={},runtime,appRoot,signal,
     let terminalFailure=null;
     let resolveReady;
     let rejectReady;
+    let resolveManagement;
+    const management=new Promise(function discoverManagement(resolve){resolveManagement=resolve;});
     const output={stdout:'',stderr:''};
     const ready=new Promise(function createReadiness(resolve,reject){
         resolveReady=resolve;
@@ -80,7 +87,9 @@ export function createLocalAIServer({id,configuration={},runtime,appRoot,signal,
     void ready.catch(function observeReadinessFailure(){return undefined;});
 
     async function publishState(state,error){
-        current={id,url,state,available:state==='ready',owned,...(error?{error:errorRecord(error)}:{})};
+        current={id,url,state,available:state==='ready',owned,
+            managed:!external&&Boolean(runtime?.executable),
+            ...(id==='llama.cpp'?{execution:execution??null}:{}),...(error?{error:errorRecord(error)}:{})};
         await onState?.(current);
         await events.send({
             type:`local-ai.server.${state}`,
@@ -147,6 +156,8 @@ export function createLocalAIServer({id,configuration={},runtime,appRoot,signal,
             // endpoint at this actual launch boundary rather than presenting
             // that earlier installation-selection snapshot as current health.
             const observed=await probeServer(id,url,operationSignal);
+            external=true;
+            resolveManagement(false);
             if(runtime?.requestedVersion&&runtime.requestedVersion!=='latest'){
                 const requested=runtime.requestedVersion.replace(/^v/u,'');
                 if(!is.string(observed.version)||observed.version.replace(/^v/u,'')!==requested){
@@ -158,10 +169,18 @@ export function createLocalAIServer({id,configuration={},runtime,appRoot,signal,
             throwIfAborted(operationSignal);
             // An HTTP error is an existing service's state. Only a refused
             // connection allows starting the selected local executable.
-            if(!localAIConnectionRefused(error))throw error;
+            if(!localAIConnectionRefused(error)){
+                external=true;
+                resolveManagement(false);
+                throw error;
+            }
             if(!localHostname(endpoint.hostname))throw error;
         }
         if(existing){
+            external=true;
+            if(managedSelection){
+                throw new ArcaneError('LOCAL_AI_EXTERNAL_SELECTION_UNSUPPORTED','The existing llama.cpp server owns its model and device selection. Use an available listener for SDK-managed model loading.');
+            }
             await publishState('ready');
             throwIfAborted(operationSignal);
             settleReady();
@@ -170,6 +189,7 @@ export function createLocalAIServer({id,configuration={},runtime,appRoot,signal,
         if(!runtime?.executable){
             throw new ArcaneError(ERROR_CODES.prerequisiteMissing,`No installed ${id} executable was supplied.`);
         }
+        resolveManagement(true);
         if(endpoint.protocol!=='http:'){
             throw new ArcaneError(ERROR_CODES.usage,`${id} managed startup requires its direct HTTP listener URL.`);
         }
@@ -187,12 +207,19 @@ export function createLocalAIServer({id,configuration={},runtime,appRoot,signal,
         throwIfAborted(operationSignal);
         const host=endpoint.hostname.replace(/^\[|\]$/gu,'');
         const port=endpoint.port||'80';
+        const selected=id==='llama.cpp'?await resolveLlamaExecution({
+            executionTarget:configuration.executionTarget,executionDevices,runtime,signal:operationSignal,onEvent:events.send
+        }):null;
+        if(selected)execution=selected.execution;
         const arguments_=id==='ollama'?['serve',...args]:[
             '--host',host,'--port',port,'--jinja',
+            ...(managedSelection?args:[]),
             ...(configuration.model?['--model',path.resolve(appRoot,configuration.model)]:['--models-dir',modelsDirectory]),
-            ...args
+            ...(!managedSelection?args:[]),
+            ...(configuration.alias?['--alias',configuration.alias]:[]),
+            ...selected.args
         ];
-        const env=id==='ollama'?{OLLAMA_HOST:endpoint.origin,OLLAMA_MODELS:modelsDirectory}:undefined;
+        const env=id==='ollama'?{OLLAMA_HOST:endpoint.origin,OLLAMA_MODELS:modelsDirectory}:selected.env;
         owned=true;
         await publishState('starting');
         throwIfAborted(operationSignal);
@@ -215,7 +242,7 @@ export function createLocalAIServer({id,configuration={},runtime,appRoot,signal,
                 return;
             }
             await fail(error);
-        });
+        }).finally(async function releaseProcessResources(){await onExit?.();});
         void processObservation.catch(function observeProcessCallbackFailure(error){
             current={...current,state:'error',available:false,error:errorRecord(error)};
             settleReady(error);
@@ -250,7 +277,10 @@ export function createLocalAIServer({id,configuration={},runtime,appRoot,signal,
         });
     }
 
-    startupTask=start().catch(fail);
+    startupTask=start().catch(fail).finally(async function releaseUnstartedResources(){
+        resolveManagement(false);
+        if(!processTask)await onExit?.();
+    });
     void startupTask.catch(function observeStartupCallbackFailure(error){
         current={...current,state:'error',available:false,error:errorRecord(error)};
         settleReady(error);
@@ -258,5 +288,5 @@ export function createLocalAIServer({id,configuration={},runtime,appRoot,signal,
     operationSignal.addEventListener('abort',observeLifetimeAbort,{once:true});
     if(operationSignal.aborted)observeLifetimeAbort();
 
-    return {ready,url,close,get owned(){return owned;},get current(){return current;}};
+    return {ready,management,url,close,get owned(){return owned;},get external(){return external;},get current(){return current;}};
 }

package/src/native/portable-layout.mjs

@@ -155,8 +155,8 @@ export function coreEntrySource(application, version, services, {localAI, runtim
     const imageSelected = localAI?.runtimes?.some(function selectedImage(requirement) {
         return (typeof requirement === 'string' ? requirement : requirement.id) === 'stable-diffusion.cpp';
     }) ?? false;
-    const modelAssetsSelected = imageSelected || (localAI?.runtimes?.some(function selectedONNX(requirement) {
-        return (typeof requirement === 'string' ? requirement : requirement.id) === 'onnx';
+    const modelAssetsSelected = imageSelected || (localAI?.runtimes?.some(function selectedProjectedRuntime(requirement) {
+        return ['onnx', 'llama.cpp'].includes(typeof requirement === 'string' ? requirement : requirement.id);
     }) ?? false);
     const whisperSelected = localAI?.runtimes?.some(function selectedWhisper(requirement) {
         return (typeof requirement === 'string' ? requirement : requirement.id) === 'whisper.cpp';
@@ -199,13 +199,21 @@ export function coreEntrySource(application, version, services, {localAI, runtim
             '    register(packagedWeb);');
     }
     return [
-        "import {fileURLToPath} from 'node:url';",
+        "import {fileURLToPath, pathToFileURL} from 'node:url';",
         "import path from 'node:path';",
         "import {isSea} from 'node:sea';",
         ...(launchDefaults === undefined ? [] : ["import {mkdir} from 'node:fs/promises';"]),
         "import {readCoreLaunchContext, startCoreHost, startCoreListener, runSharedCoreHost, startSharedCoreBridge} from 'arcane-os/core/host';",
         "import {createModelObservationService} from 'arcane-os/core/model-observation';",
         '',
+        "const appEntryFlag = process.argv.indexOf('--arcane-app-entry', 2);",
+        'if (appEntryFlag !== -1) {',
+        '    const appEntry = process.argv[appEntryFlag + 1];',
+        "    if (appEntry === undefined || appEntry === '') throw new TypeError('--arcane-app-entry requires an app-relative module path.');",
+        "    const appRoot = fileURLToPath(new URL('../app/', import.meta.url));",
+        '    await import(pathToFileURL(path.resolve(appRoot, appEntry)).href);',
+        '} else {',
+        ...[
         ...(localAI === undefined ? [] : [
             '// Bundled runtime paths are artifact-root-relative POSIX paths.',
             'function runtimePath(relative) {',
@@ -366,6 +374,8 @@ export function coreEntrySource(application, version, services, {localAI, runtim
         '    }',
         "    process.off('SIGINT', closeCore);",
         "    process.off('SIGTERM', closeCore);",
+        '}'
+        ].map(function indentOrdinaryCore(line) { return line ? `    ${line}` : line; }),
         '}',
         ''
     ].join('\n');

package/src/workspace-runtime.mjs

@@ -85,15 +85,96 @@ async function removeTemporaryTree(location){
     await rm(location,{recursive:true,force:true}).catch(()=>{});
 }
 
+async function materializeBrowserDecisions(destination, signal, onEvent) {
+    const transformers = 'https://cdn.jsdelivr.net/npm/@huggingface/transformers@4.3.0/';
+    const onnx = 'https://cdn.jsdelivr.net/npm/onnxruntime-web@1.31.0-dev.20260914-8d85527a0/';
+    const files = [
+        {name: 'transformers.min.js', url: `${transformers}dist/transformers.min.js`},
+        {name: 'ort-wasm-simd-threaded.asyncify.mjs', url: `${onnx}dist/ort-wasm-simd-threaded.asyncify.mjs`},
+        {name: 'ort-wasm-simd-threaded.asyncify.wasm', url: `${onnx}dist/ort-wasm-simd-threaded.asyncify.wasm`},
+        {name: 'TRANSFORMERS-LICENSE', url: `${transformers}LICENSE`},
+        {name: 'ONNX-RUNTIME-LICENSE', url: `${onnx}LICENSE`}
+    ];
+    const controller = new AbortController();
+    function cancelDistribution() {
+        controller.abort(signal.reason);
+    }
+    signal?.addEventListener('abort', cancelDistribution, {once: true});
+    if (signal?.aborted) cancelDistribution();
+    let completed = 0;
+    try {
+        throwIfAborted(controller.signal);
+        await emit(
+            onEvent,
+            {type: 'workspace.decisions.started', completed, total: files.length}
+        );
+        throwIfAborted(controller.signal);
+        await mkdir(destination, {recursive: true});
+        async function acquireDistributionFile(file) {
+            try {
+                throwIfAborted(controller.signal);
+                const response = await fetch(file.url, {signal: controller.signal});
+                const content = new Uint8Array(await response.arrayBuffer());
+                if (!response.ok) {
+                    const error = new Error(`Browser decision distribution returned HTTP ${response.status} ${response.statusText}.`);
+                    error.code = 'ARCANE_DECISION_DISTRIBUTION_DOWNLOAD_FAILED';
+                    error.response = {
+                        url: response.url,
+                        status: response.status,
+                        statusText: response.statusText,
+                        headers: [...response.headers],
+                        content
+                    };
+                    throw error;
+                }
+                throwIfAborted(controller.signal);
+                // Upstream distribution content is opaque, including its own
+                // imports and license text. No SDK source rewriting applies.
+                await writeFile(path.join(destination, file.name), content);
+                throwIfAborted(controller.signal);
+                completed += 1;
+                await emit(
+                    onEvent,
+                    {type: 'workspace.decisions.progress', file: file.name, url: file.url, completed, total: files.length}
+                );
+            } catch (error) {
+                controller.abort(error);
+                throw error;
+            }
+        }
+        // One fixed distribution, acquired once for the selected projection;
+        // no model/app/architecture multiplier or installation script.
+        const outcomes = await Promise.allSettled(files.map(acquireDistributionFile));
+        const failures = new Set();
+        for (const outcome of outcomes) {
+            if (outcome.status === 'rejected') failures.add(outcome.reason);
+        }
+        if (failures.size === 1) throw [...failures][0];
+        if (failures.size > 1) {
+            throw new AggregateError([...failures], 'Browser decision distribution acquisition failed.');
+        }
+        throwIfAborted(controller.signal);
+    } finally {
+        signal?.removeEventListener('abort', cancelDistribution);
+    }
+    return {
+        transformersVersion: '4.3.0',
+        onnxRuntimeVersion: '1.31.0-dev.20260914-8d85527a0',
+        files: files.map(function distributionFilename(file) { return file.name; })
+    };
+}
+
 export async function materializeWorkspaceRuntimeContent({
     workspaceRoot,
     runtimeRoot=path.join(getSdkRoot(),'runtime'),
     browserRuntimeRoot=getSdkBrowserRuntimeRoot(),
     sdkVersion=SDK_VERSION,
+    browserDecisions=false,
     signal,
     onEvent
 }={}){
     if(!workspaceRoot)fail('workspaceRoot is required to materialize a workspace runtime.');
+    if(!is.boolean(browserDecisions))throw new TypeError('browserDecisions must be a boolean.');
     throwIfAborted(signal);
     const workspace=await realDirectory(workspaceRoot,'Workspace root');
     const runtime=await realDirectory(runtimeRoot,'SDK runtime root');
@@ -109,6 +190,7 @@ export async function materializeWorkspaceRuntimeContent({
     const backupRoot=path.join(workspace,`${BACKUP_PREFIX}${token}`);
     let backedUp=false;
     let promoted=false;
+    let decisionDistribution;
 
     await mkdir(stagingRoot);
     try{
@@ -134,6 +216,14 @@ export async function materializeWorkspaceRuntimeContent({
             );
         }
 
+        if (browserDecisions) {
+            decisionDistribution = await materializeBrowserDecisions(
+                path.join(sdkDestination, 'ai', 'decisions-runtime'),
+                signal,
+                onEvent
+            );
+        }
+
         throwIfAborted(signal);
         try{
             const existing=await lstat(destinationRoot);
@@ -160,7 +250,13 @@ export async function materializeWorkspaceRuntimeContent({
         return {
             kind:'arcane-workspace-runtime-content',
             workspaceRoot:workspace,
-            runtimeRoot:destinationRoot
+            runtimeRoot:destinationRoot,
+            ...(decisionDistribution ? {
+                browserDecisions: {
+                    ...decisionDistribution,
+                    directory: path.join(destinationRoot, 'sdk', 'ai', 'decisions-runtime')
+                }
+            } : {})
         };
     }catch(error){
         if(promoted)await removeTemporaryTree(destinationRoot);