arcane-os 0.90.0 → 0.92.0

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.
 
@@ -5385,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,remoteBase,ref,selectPath,gitIdentity,onEvent,run=runProcess}={})
+createGitTextSnapshot({cacheDirectory,remote,remoteBase,ref,selectPath,allowUnborn=false,gitIdentity,onEvent,run=runProcess}={})
 ```
 
 Import from `arcane-os`. The application owns the cache location, remote, ref,
@@ -5397,6 +5421,14 @@ 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 `allowUnborn:true` observes the complete remote advertisement on every
+acquisition. Only successful empty output returns
+`{revision:null,files:[],unborn:true}`; committed results add `unborn:false` and
+retain the actual commit even for an empty tree. Any advertised HEAD, branch
+or tag continues through ordinary selected-ref fetch; missing refs and actual
+Git failures remain errors. Omitted/false preserves the prior result and commands.
+See [unborn remotes](git-text-snapshot.md#unborn-remotes).
+
 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
@@ -5452,6 +5484,28 @@ once and stdin remains open until cancellation or a callback/input failure
 requests shutdown. On Microsoft NT, `npm` and `npx` are normalized to their Node
 CLI entrypoints.
 
+For the literal `git` command on Windows, the default runner reads Git for
+Windows' registered `InstallPath` in the current-user and machine registry
+views. When that installation's `cmd/git.exe` exists, its `cmd` directory is
+appended only to this child's effective PATH. Existing entries and native
+command lookup retain priority; duplicate `Path`/`PATH` spellings follow Node's
+lexical selection. Other environment fields, explicit executable paths,
+custom process adapters, other commands and other platforms keep their existing
+behavior. No global environment or registry setting is changed, and no Git
+download, installation or command retry occurs.
+
+One successful location is retained in memory for this process while its
+executable remains present. A removed executable triggers fresh discovery;
+absent, failed and cancelled lookups are not retained. Concurrent cold callers
+own independent discovery and cancellation. The standard Windows registry
+helper uses the existing process owner; its lifecycle callbacks have
+`process.git.discovery.*` event names, and its captured metadata is separate
+from the requested command's output. Missing registration leaves ordinary
+lookup unchanged. Discovery failure emits `process.git.discovery.unavailable`
+with the complete error before ordinary lookup continues. Cancellation or an
+event-callback failure stops the operation before Git starts. Normal Git
+errors and missing-working-directory errors remain actual command failures.
+
 An `AsyncIterable` input instead feeds stdin with awaited writes and closes it
 when the producer finishes. Its `return()` must cooperate with cancellation of
 an outstanding `next()`; the process owner drains both input and output work.
@@ -8376,7 +8430,7 @@ explicit existing path. The application owns the remote, branch and Core API.
 ### Signature and result
 
 ```text
-createRepositoryWorkspace({name,directory,dataRoot,remote,remoteBase,branch,longPaths,cloneIdentity,gitIdentity,onEvent,run=runProcess}={})
+createRepositoryWorkspace({name,directory,dataRoot,remote,remoteBase,branch,initialBranch,longPaths,cloneIdentity,gitIdentity,onEvent,run=runProcess}={})
 ```
 
 Returns `{directory,open,status,configuration,pull,push,write,close,drain,dispose}`. Construction does
@@ -8387,6 +8441,17 @@ 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 `initialBranch` selects `refs/heads/<initialBranch>` only after a new
+clone, successful complete empty remote advertisement, explicit local
+initial-state observation and a successful empty local-ref listing. Any local
+ref supplied by a Git template or hook remains unchanged. Existing destinations and committed/advertised
+clones keep their branches; `branch` still means Git's existing-branch/tag clone
+selection. New-clone `open` results with this option add complete ordered
+preparation `outputs`; subsequent failures retain completed outputs and their
+original cause. Omission adds no command or result field. See
+[first-publication composition](core-repositories.md#first-publication-from-an-unborn-remote)
+for the direct first commit/push without an implicit pull.
+
 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,
@@ -8422,13 +8487,17 @@ omitted fields remain inherited. Username remains a credential hint, with
 authentication owned by ordinary Git and its configured helper.
 
 `configuration({signal})` observes an existing working root without clone,
-initialization or fetch. It returns `{repositoryRoot,headRef,origin,upstream}`:
+initialization or fetch. It returns `{repositoryRoot,headRef,revision,unborn,origin,upstream}`:
 full symbolic HEAD (including unborn, null when detached), origin URL/pushURL
 arrays and current branch remote/merge/URL/pushURL arrays. Unset, empty and
-repeated configuration values remain distinct. These are ordinary configured
-values, not authentication or endpoint proof, and are not atomic with later
-operations. Raw stdout is decoded without replacement; unrepresentable text
-reports `ARCANE_GIT_CONFIGURATION_NOT_TEXT` with full diagnostics.
+repeated configuration values remain distinct. `revision:null,unborn:true`
+comes only from Git's explicit porcelain-v2 initial state; committed and
+detached states retain their current revision with `unborn:false`. Missing
+branch-state output reports `ARCANE_REPOSITORY_HEAD_UNAVAILABLE`. These are
+ordinary configured values and local branch observations, not authentication
+or endpoint proof, and are not atomic with later operations. Raw stdout is
+decoded without replacement; unrepresentable text 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
@@ -9012,14 +9081,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
@@ -10146,7 +10223,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.90.0",
+  "version": "0.92.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

@@ -5,7 +5,7 @@ import Is from 'strong-type';
 import {ArcaneError, throwIfAborted} from '../errors.mjs';
 import {runProcess} from '../process.mjs';
 import {captureRepositoryRemote, captureRepositoryTarget, repositoryConfiguration, pullRepositoryTarget, pushRepositoryTarget,
-    repositoryPushArguments, repositoryStatus} from '../repository.mjs';
+    repositoryHeadArguments, repositoryHeadState, repositoryPushArguments, repositoryStatus} from '../repository.mjs';
 import {createGitIdentityRunner} from '../git-identity.mjs';
 
 export {readGitIdentity} 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, remoteBase, branch, longPaths, cloneIdentity = {}, gitIdentity, onEvent, run = runProcess} = {}
+    {name, directory, dataRoot, remote, remoteBase, branch, initialBranch, longPaths, cloneIdentity = {}, gitIdentity, onEvent, run = runProcess} = {}
 ) {
     let selected = directory;
     if (selected === undefined) {
@@ -59,6 +59,12 @@ export function createRepositoryWorkspace(
     if (remote !== undefined) requireString(remote, 'remote');
     const remoteArgument = captureRepositoryRemote(remote, remoteBase);
     if (branch !== undefined) requireString(branch, 'branch');
+    if (initialBranch !== undefined) {
+        requireString(initialBranch, 'initialBranch');
+        if (!initialBranch.isWellFormed() || initialBranch.includes('\0')) {
+            throw new TypeError('initialBranch must be text representable as a native process argument.');
+        }
+    }
     if (longPaths !== undefined && !is.boolean(longPaths)) {
         throw new TypeError('longPaths must be a boolean when supplied.');
     }
@@ -126,9 +132,60 @@ export function createRepositoryWorkspace(
             arguments_,
             {cwd: path.dirname(repositoryDirectory), signal, onEvent}
         );
+        let outputs;
+        if (initialBranch !== undefined) {
+            const options = {cwd: repositoryDirectory, signal, onEvent};
+            outputs = [];
+            function completed(operation, observation) {
+                outputs.push({operation, stdout: observation.stdout, stderr: observation.stderr,
+                    code: observation.code, signal: observation.signal ?? null});
+            }
+            completed('clone', result);
+            try {
+                throwIfAborted(signal);
+                const advertised = await prepareRun('git', ['ls-remote', '--symref', '--', remoteArgument],
+                    {cwd: path.dirname(repositoryDirectory), signal, onEvent});
+                completed('observeRemote', advertised);
+                throwIfAborted(signal);
+                if (advertised.code !== 0) {
+                    throw new ArcaneError('ARCANE_OPERATION_FAILED', 'Git remote observation failed.', {details: advertised});
+                }
+                if (advertised.stdout === '') {
+                    const state = await prepareRun('git', [...repositoryHeadArguments], options);
+                    completed('observeHead', state);
+                    throwIfAborted(signal);
+                    if (state.code !== 0) {
+                        throw new ArcaneError('ARCANE_OPERATION_FAILED', 'Git branch state observation failed.', {details: state});
+                    }
+                    if (repositoryHeadState(state.stdout, state).unborn) {
+                        const references = await prepareRun('git', ['for-each-ref', '--format=%(refname)'], options);
+                        completed('observeRefs', references);
+                        throwIfAborted(signal);
+                        if (references.code !== 0) {
+                            throw new ArcaneError('ARCANE_OPERATION_FAILED', 'Git local ref observation failed.', {details: references});
+                        }
+                        // Git templates or hooks can supply local refs even
+                        // when the remote and this checkout's HEAD are unborn.
+                        if (references.stdout === '') {
+                            const selection = await prepareRun('git', ['symbolic-ref', 'HEAD', `refs/heads/${initialBranch}`], options);
+                            completed('selectInitialBranch', selection);
+                            throwIfAborted(signal);
+                            if (selection.code !== 0) {
+                                throw new ArcaneError('ARCANE_OPERATION_FAILED', 'Git initial branch selection failed.', {details: selection});
+                            }
+                        }
+                    }
+                }
+            } catch (cause) {
+                throw new ArcaneError(cause?.code ?? 'ARCANE_REPOSITORY_PREPARE_FAILED',
+                    cause instanceof Error ? cause.message : String(cause),
+                    {cause, details: {directory: repositoryDirectory, cloned: true, outputs}, exitCode: cause?.exitCode});
+            }
+        }
         throwIfAborted(signal);
         opened = true;
-        return {directory: repositoryDirectory, cloned: true, stdout: result.stdout, stderr: result.stderr};
+        return {directory: repositoryDirectory, cloned: true, stdout: result.stdout, stderr: result.stderr,
+            ...(outputs === undefined ? {} : {outputs})};
     }
 
     function accept(operation, signal) {