arcane-os 0.89.0 → 0.91.0

package/docs/reference/native-decisions.md

@@ -179,10 +179,25 @@ 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
-file owner; it neither vendors the weights nor creates a second persistent
-model store. The approved `@huggingface/tokenizers@0.2.0` dependency reads the
+revision. On explicit `load()`, the existing model-assets owner reuses complete
+native acquisitions under the selected `workingDirectory/model-assets/`, or
+fetches the complete selected members concurrently when absent. Complete
+acquisitions survive unload, disposal and application restart. Reuse matches
+the entire ordered original path/URL selection; it never substitutes another
+model, revision, precision or device. Supplied projections and caller-owned
+`paths` retain their existing precedence and lifecycle.
+
+Ordinary preparation reuses the selected URLs without checking whether mutable
+upstream content changed. Explicit reacquisition is available through native
+[`modelAssets.prepare({refresh:true,...})`](model-assets.md#native-ownership),
+whose ready projection can be supplied through the existing
+`assetProjectionId`/`resourcePaths` contract. It preserves earlier complete
+acquisitions and active native retains. Incomplete attempts are not reused or
+resumed; separate processes may perform duplicate acquisitions in disjoint
+directories. The shared model-assets owner handles storage without an
+application-local cache copy or a second model store.
+
+The approved `@huggingface/tokenizers@0.2.0` dependency reads the
 selected tokenizer files in its Worker. No Transformers or second ONNX runtime
 is loaded by this API.
 

package/docs/reference/sdk-api.md

@@ -1044,6 +1044,25 @@ ordinary browser output remain unchanged. See
 [native-module package output](protocols.md#native-module-package-output)
 for resource handling and the static transformation boundary.
 
+`browserDecisions` defaults to `false`. Explicit `browserDecisions: true`
+acquires the bundled Transformers.js 4.3.0 entry, matching ONNX Runtime
+1.31.0-dev.20260914-8d85527a0 asyncify module/WASM and both licenses into
+the package stage beside the selected SDK `ai/browser-decisions.mjs`, under
+`decisions-runtime/`. Installed-package routes retain their configured
+dependency path, including aliases; source and installed dependencies remain
+unchanged, with no workspace-root `arcane/` projection. The selected SDK decision
+module must be included in the package. Acquisition happens after native-module
+and asset rewriting, preserving upstream content unchanged in both module
+formats. The distribution joins the returned and release-manifest inventories
+and any enabled PWA's ordinary offline selection. The default and dry runs
+perform no optional acquisition; dry runs report selected inputs. Repeat this
+option on each package build that should acquire the closure. Cancellation and
+HTTP or observer failures abort/join acquisition before stage cleanup and
+preserve previous output. The existing `workspace.decisions.started` and
+`workspace.decisions.progress` events report file progress. See the
+[extension-local decision guide](ai/browser-decisions.md#extension-local-executables-manifest-v3)
+for `runtime.local: true`, upstream versions and complete error details.
+
 An operation may override `outputDirectory` without changing the saved app
 configuration. For example, package a complete application beneath an
 application-owned extension manifest and launcher:
@@ -1875,6 +1894,11 @@ module/WASM and license files from their upstream distributions into
 `transformersVersion`, `onnxRuntimeVersion` and `files` under
 `workspaceRuntime.browserDecisions`. The default `false` performs no optional
 acquisition. Select this option on each refresh that should retain those files.
+For applications with installed-package routes, use
+`packageApp({workspaceRoot, appId, browserDecisions: true})` to place the
+distribution beside the actual deployed SDK module. This physical materializer
+continues to own only the separate `arcane/` projection; it does not populate or
+modify `node_modules`.
 The [extension-local decision guide](ai/browser-decisions.md#extension-local-executables-manifest-v3)
 describes `runtime.local: true`, complete resource ownership and MV3 usage.
 
@@ -3831,12 +3855,21 @@ async repositoryPull({ workspaceRoot=process.cwd(), target, signal, onEvent, run
 
 Import it from `arcane-os`. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.
 
-Optional `target:{remote,ref}` captures exact nonempty native-representable
-strings before any wait and selects `git pull --ff-only -- <remote> <ref>:`.
+Optional `target:{remote,ref,remoteBase?}` captures the exact nonempty
+native-representable `remote` and `ref` strings before any wait and selects
+`git pull --ff-only -- <remote> <ref>:`.
 The current clean branch receives a fast-forward-only integration; the SDK
 never switches branches, resets or changes configuration. Without a target,
 the existing configured pull and result remain unchanged. Targeted results
 add `target`, complete `stdout` and `stderr` to the existing pull result.
+
+Supplying `target.remoteBase` explicitly selects a local filesystem locator:
+only the Git remote argument becomes `path.resolve(remoteBase, remote)`, captured
+once at acceptance before status work. Relative bases, including `''`, use the
+working directory at that moment. The returned target retains the original
+`remote`, `ref` and supplied base text. Omission preserves Git remote names,
+URLs, SCP-like addresses and remote-helper strings without guessed parsing.
+Unrepresentable base text reports `TypeError` without transformation.
 See [checkout configuration and selected targets](core-repositories.md#existing-checkout-configuration-and-selected-targets).
 
 ### Availability and normalization
@@ -3877,20 +3910,29 @@ detached HEAD, then, without `target`, runs plain `git push`; the repository's c
 configured upstream/remote, Git credentials, hooks, and server policy remain
 authoritative. Unlike `repositoryPull()`, this function does **not** require a
 clean worktree. It does not create a commit or choose an application destination.
-Optional `target:{remote,ref}` captures the original nonempty
-native-representable strings before any wait and runs
+Optional `target:{remote,ref,remoteBase?}` captures the original nonempty
+native-representable `remote` and `ref` strings before any wait and runs
 `git push --no-follow-tags -- <remote> HEAD:<ref>`. This publishes current HEAD
 to the caller-selected ref without force or implicit configured tag following.
 It changes no branch or Git configuration; credentials, URL interpretation,
 hooks and remote rejection remain Git-owned.
 
+Supplying `target.remoteBase` explicitly selects a local filesystem locator:
+only the Git remote argument becomes `path.resolve(remoteBase, remote)`, captured
+once at acceptance before status work. Relative bases, including `''`, use the
+working directory at that moment. Later directory or target-object changes do
+not redirect accepted work. Omission preserves Git remote names, URLs, SCP-like
+addresses and remote-helper strings without guessed parsing. Unrepresentable
+base text reports `TypeError` without transformation.
+
 The promise resolves to
 `{action:'push', repositoryRoot, branch, output}`. `output` is trimmed stdout,
 or trimmed stderr when stdout is empty. A missing Git executable, failed status
 probe, rejected/nonzero push, cancellation, or event-callback failure rejects
 with the normalized process error. Cancellation stops the local process tree;
 it cannot prove that a remote accepted no objects before the interruption.
-Targeted results also contain the captured `target` and complete
+Targeted results also contain the captured `target`, retaining original
+`remote`, `ref` and any supplied `remoteBase`, and complete
 `stdout`/`stderr`; omitting the target preserves the existing result shape.
 See [checkout configuration and selected targets](core-repositories.md#existing-checkout-configuration-and-selected-targets).
 
@@ -5367,7 +5409,7 @@ a dedicated bare Git cache. It does not create or alter a working checkout.
 ### Signature, lifecycle, and result
 
 ```text
-createGitTextSnapshot({cacheDirectory,remote,ref,selectPath,gitIdentity,onEvent,run=runProcess}={})
+createGitTextSnapshot({cacheDirectory,remote,remoteBase,ref,selectPath,gitIdentity,onEvent,run=runProcess}={})
 ```
 
 Import from `arcane-os`. The application owns the cache location, remote, ref,
@@ -5379,6 +5421,16 @@ await accepted refresh/process cleanup. Errors remain observable instead of
 returning stale or partial success. See [Git text snapshots](git-text-snapshot.md)
 for complete inputs, text semantics, errors, events and Core service composition.
 
+Optional `remoteBase` explicitly selects `remote` as a local filesystem locator.
+Only its Git fetch argument is derived using `path.resolve(remoteBase, remote)`,
+once at construction, independently of the cache location and later changes to
+the working directory. Relative bases, including `''`, use the construction-time
+working directory. Original locator/options remain unchanged. Omission preserves
+Git remote names, URLs, SCP-like addresses and remote-helper strings without
+guessed parsing. Unrepresentable base text reports `TypeError` without
+transformation; actual Git failures retain their existing error behavior.
+See [relative local repository locators](core-repositories.md#relative-local-repository-locators).
+
 Optional `gitIdentity:{name?,email?,username?}` captures a child-process-only
 selection for init/fetch and subsequent Git commands, preserving shared refresh
 cancellation and complete content. See [Git identity configuration](core-repositories.md#git-identity-configuration)
@@ -8348,7 +8400,7 @@ explicit existing path. The application owns the remote, branch and Core API.
 ### Signature and result
 
 ```text
-createRepositoryWorkspace({name,directory,dataRoot,remote,branch,longPaths,cloneIdentity,gitIdentity,onEvent,run=runProcess}={})
+createRepositoryWorkspace({name,directory,dataRoot,remote,remoteBase,branch,longPaths,cloneIdentity,gitIdentity,onEvent,run=runProcess}={})
 ```
 
 Returns `{directory,open,status,configuration,pull,push,write,close,drain,dispose}`. Construction does
@@ -8359,6 +8411,16 @@ work and preserves the checkout. No CLI cwd, launch state, preference, snapshot
 cache or existing user-data location changes. See the [complete inputs, results,
 errors and lifecycle](core-repositories.md#one-connected-working-checkout).
 
+Optional factory `remoteBase` explicitly selects the initial-clone `remote` as
+a local filesystem locator. Only its Git argument is derived through the host's
+native `path.resolve(remoteBase, remote)`, once at construction. Relative bases,
+including `''`, use the construction-time working directory. The caller's
+original locator remains unchanged; Git clone may save the derived argument as
+its ordinary origin setting. Omission preserves Git remote names, URLs, SCP-like
+addresses and remote-helper strings without guessed parsing. Unrepresentable
+base text reports `TypeError` without transformation.
+See [relative local repository locators](core-repositories.md#relative-local-repository-locators).
+
 Optional `longPaths` captures a boolean for new Windows clones. Explicit true
 or false supplies clone-local `core.longpaths` before the first checkout and
 persists it only in the new repository. Omission preserves inherited/template
@@ -8394,11 +8456,15 @@ reports `ARCANE_GIT_CONFIGURATION_NOT_TEXT` with full diagnostics.
 
 `pull({target,signal})`, `push({target,signal})` and
 `write({files:[{path,content}],message,target,signal})` accept optional
-`target:{remote,ref}`, captured as original strings at acceptance. The target
+`target:{remote,ref,remoteBase?}`, captured as original strings at acceptance. The target
 selects a fast-forward-only pull into the current branch or a non-force push
 of current HEAD to the selected ref, without switching branches or changing
-configuration. It is independent of initial-clone `remote`/`branch`; omission
-preserves ordinary configured behavior. See the [complete configuration and
+configuration. An operation's own `remoteBase` declares local-path intent and
+captures the native absolute Git argument once at acceptance, before queueing.
+It is independent of initial-clone `remote`/`remoteBase`/`branch`; omission of
+`target` preserves ordinary configured behavior. Targeted pull/push results and
+writer results/failure outcomes retain original `remote`, `ref` and any supplied
+`remoteBase`, including relative or empty base text. See the [complete configuration and
 target contract](core-repositories.md#existing-checkout-configuration-and-selected-targets).
 
 `write` snapshots the exact selected
@@ -8970,14 +9036,22 @@ directory and complete member files.
 
 `current()` returns `{closing,projections}`. `retain(id)` accepts a completed
 projection and returns `{id,directory,members,release}` for a native owner.
-Native `prepare({id,workingDirectory,members,signal,onProgress})` accepts
-ordered `{path,url}` members and returns their ready projection. Explicit calls
-stream complete upstream responses through the same file owner; startup
-downloads nothing. Independent members transfer concurrently and progress
-reports phases and completed files. `release(id)` relinquishes preparation
-ownership; cancellation, release and disposal join fetches and writes before
-cleanup. Native retain handles keep completed files alive until actual engine
-release. See [native preparation](model-assets.md#native-ownership).
+Native `prepare({id,workingDirectory,members,signal,onProgress,refresh=false})`
+accepts ordered `{path,url}` members and returns their ready projection.
+Complete native acquisitions persist beneath `workingDirectory/model-assets/`
+through unload, disposal and restart; ordinary calls reuse the exact complete
+ordered source selection without a network freshness check. Explicit
+`refresh:true` acquires a separate complete set without replacing active files.
+Independent members transfer concurrently and progress reports phases and
+completed files. Matching same-process preparations share acquisition with
+independent callbacks and cancellation; the last interested cancellation joins
+unfinished I/O and removes only that attempt. Separate processes may acquire
+the same selection independently. Startup downloads nothing.
+`release(id)` relinquishes live preparation ownership. Native retains continue
+through actual engine release; completed native acquisitions remain stored.
+Browser `open/write/complete` projections retain their temporary lifetime and
+are removed only after all native uses end. See
+[native preparation](model-assets.md#native-ownership).
 `dispose()` releases preparation ownership and joins file writes, closes and
 all native retain lifetimes before cleanup. The native owner releases its
 handle only after its actual context/worker use ends. Original stored model
@@ -9003,7 +9077,7 @@ import createLocalAIService from 'arcane-os/core/local-ai';
 
 ### Overview
 
-Reuses matching managed runtimes or installs complete selected official
+Reuses matching managed runtimes or installs complete selected
 llama.cpp/Ollama/ONNX/image distributions or NeMo libraries in an explicitly supplied directory.
 
 ### Signature and result
@@ -9016,14 +9090,22 @@ Import it from `arcane-os/local-ai`. Runtime requirements accept IDs or
 `{id,version?,url?}` records. The result is an array of absolute
 `{id,version,platform,architecture,root}` records, with `executable` for servers,
 `modulePath` for ONNX, image `libraryPath`/`bindingModulePath`/`variants`/`models`,
-or NeMo library directories. Image requirements also accept `backend` and
+or NeMo library directories. The SDK-selected Windows x64 ONNX `1.30.0`
+distribution also returns `nativeDistributionRevision: '1.30.0-directml-reshape-1'`.
+With no explicit `url`, an omitted ONNX version or explicit `1.30.0` selects
+the corrected native archive from the installed SDK's numeric release.
+Other ONNX versions, platforms/architectures and explicit URLs retain their
+upstream package path. Reuse requires the selected revision; older installation
+trees remain intact while a fresh installation is prepared. See
+[ONNX runtime preparation](local-ai.md#development).
+Image requirements also accept `backend` and
 `models`; their pinned default runtime, CPU/Metal selection and separate model
 preparation are described in [local image generation](local-image-generation.md).
 Matching concurrent
 installs share their work. Downloads retain runtime libraries and surface
 network/archive failures; cancellation and operation events remain observable.
 Installation changes no global PATH or system service and loads no model.
-Supported assets belong to the selected upstream distribution; see
+Supported assets belong to the selected distribution; see
 [platform and archive requirements](local-ai.md#native-bundling).
 
 ```javascript
@@ -9057,6 +9139,11 @@ contains the complete emitted inventory. Existing runtime destinations are
 preserved and reported as a conflict. Copying settles all started work and
 reports failures/cancellation without executing app services or models.
 
+The corrected Windows x64 ONNX selection retains its
+`nativeDistributionRevision` and complete native libraries. Its `modulePath`
+is relocated with the other runtime paths; bundling introduces no separate
+runtime selection. See [ONNX runtime preparation](local-ai.md#development).
+
 Image records relocate the complete library, binding and variant paths. Model
 URL descriptors retain their original acquisition metadata for preparation
 after launch. Runtime-contained native model paths become artifact-relative;
@@ -10091,7 +10178,9 @@ Cancellation terminates that client's Worker and rejects its in-flight work.
 No decisions are inserted into chat history or durable storage.
 
 For explicitly selected extension-local execution, supply `runtime: {local:
-true}` after materializing with `browserDecisions: true`. The SDK directly
+true}` after `packageApp({workspaceRoot, appId, browserDecisions: true})` for
+installed-package routes, or after opting into the existing physical runtime
+materializer. The SDK directly
 imports its deployment-local `decisions-runtime/transformers.min.js` and
 matched asyncify module/WASM. Explicit `runtime.moduleUrl` and
 `runtime.wasmPaths: {mjs, wasm}` may select other compatible files in that same

package/package.json

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

package/src/browser-decisions-distribution.mjs

@@ -0,0 +1,95 @@
+import Is from 'strong-type';
+import {mkdir, writeFile} from 'node:fs/promises';
+import path from 'node:path';
+
+const is = new Is(false);
+
+function throwIfAborted(signal) {
+    if (!signal?.aborted) return;
+    const error = signal.reason instanceof Error ? signal.reason : new Error('Operation cancelled.');
+    error.code = error.code || 'ARCANE_CANCELLED';
+    throw error;
+}
+
+async function emit(onEvent, event) {
+    if (is.function(onEvent)) await onEvent(event);
+}
+
+export 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 or
+        // package; 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; })
+    };
+}

package/src/core/repositories.mjs

@@ -4,7 +4,7 @@ import path from 'node:path';
 import Is from 'strong-type';
 import {ArcaneError, throwIfAborted} from '../errors.mjs';
 import {runProcess} from '../process.mjs';
-import {captureRepositoryTarget, repositoryConfiguration, repositoryPull, repositoryPush,
+import {captureRepositoryRemote, captureRepositoryTarget, repositoryConfiguration, pullRepositoryTarget, pushRepositoryTarget,
     repositoryPushArguments, repositoryStatus} from '../repository.mjs';
 import {createGitIdentityRunner} from '../git-identity.mjs';
 
@@ -45,7 +45,7 @@ export function resolveArcaneDataPaths({dataRoot} = {}) {
 
 /** One connected checkout, composed into an application's own Core service. */
 export function createRepositoryWorkspace(
-    {name, directory, dataRoot, remote, branch, longPaths, cloneIdentity = {}, gitIdentity, onEvent, run = runProcess} = {}
+    {name, directory, dataRoot, remote, remoteBase, branch, longPaths, cloneIdentity = {}, gitIdentity, onEvent, run = runProcess} = {}
 ) {
     let selected = directory;
     if (selected === undefined) {
@@ -57,6 +57,7 @@ export function createRepositoryWorkspace(
     }
     requireString(selected, 'directory');
     if (remote !== undefined) requireString(remote, 'remote');
+    const remoteArgument = captureRepositoryRemote(remote, remoteBase);
     if (branch !== undefined) requireString(branch, 'branch');
     if (longPaths !== undefined && !is.boolean(longPaths)) {
         throw new TypeError('longPaths must be a boolean when supplied.');
@@ -119,7 +120,7 @@ export function createRepositoryWorkspace(
         }
         arguments_.push(...cloneConfiguration);
         if (branch !== undefined) arguments_.push('--branch', branch);
-        arguments_.push('--', remote, repositoryDirectory);
+        arguments_.push('--', remoteArgument, repositoryDirectory);
         const result = await prepareRun(
             'git',
             arguments_,
@@ -187,7 +188,7 @@ export function createRepositoryWorkspace(
         return accept(
             async function pullRepository() {
                 await prepare(signal);
-                return repositoryPull({workspaceRoot: repositoryDirectory, target: selectedTarget, signal, onEvent, run: execute});
+                return pullRepositoryTarget(selectedTarget, {workspaceRoot: repositoryDirectory, signal, onEvent, run: execute});
             },
             signal
         );
@@ -200,7 +201,7 @@ export function createRepositoryWorkspace(
         return accept(
             async function pushRepository() {
                 await prepare(signal);
-                return repositoryPush({workspaceRoot: repositoryDirectory, target: selectedTarget, signal, onEvent, run: execute});
+                return pushRepositoryTarget(selectedTarget, {workspaceRoot: repositoryDirectory, signal, onEvent, run: execute});
             },
             signal
         );
@@ -246,7 +247,7 @@ export function createRepositoryWorkspace(
             async function writeRepositoryFiles() {
                 const outcome = {
                     directory: repositoryDirectory,
-                    ...(selectedTarget === undefined ? {} : {target: {...selectedTarget}}),
+                    ...(selectedTarget === undefined ? {} : {target: {...selectedTarget.target}}),
                     state: 'local',
                     stage: 'prepare',
                     paths: selectedFiles.map(function selectedPath(file) { return file.path; }),