arcane-os 0.56.0 → 0.57.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.57.0
+
+- Add local model chat through explicit llama.cpp/Ollama runtime requirements,
+  reusable installation and bundling, a retained Core local-AI service, and an
+  optional browser-to-Core provider. Preserve complete requests and streamed
+  responses, model readiness, cancellation and owned process shutdown. Apps own
+  model selection and defaults; preparation does not block ordinary page startup.
+- Add authored Core service selection and launch context. Factories receive
+  authored options and the separate app-root/runtime context; explicit launch
+  context overrides remain supported. Portable packages can bundle explicitly
+  selected local-AI runtimes without changing browser-only output.
+- Add Windows x64 executable packaging through the public Windows native
+  provider and the matching release's retained WebView2/Node SEA host asset.
+  Client injection precedes app scripts, service requests retain complete JSON,
+  and accepted service work drains before the owned Core process exits.
+- Add `runProcess` cancellation mode `close-input` for owned graceful shutdown;
+  the existing `terminate-tree` default remains unchanged. Includes separately
+  delivered macOS process source, without claiming a complete macOS host.
+- Correct the documented Node document-library subpath and lexical-search
+  example. No preferences service, Nemotron diarization, native ONNX, native
+  Kokoro or local image generation is introduced in this release.
+
 ## 0.56.0
 
 - Add explicit `package.nativeResources` selection for native-only application

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.56.0` SDK contract. Development applications declare
+This checkout defines the `0.57.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/browser-runtime/ai/core-local.mjs

@@ -0,0 +1,306 @@
+import Is from '../dependencies/strong-type/index.js';
+import {getInstalledCoreClient} from '../core/client.mjs';
+
+const is = new Is(false);
+const PROVIDER_PROTOCOL = 'arcane-ai-provider/2';
+const AUTHORITY_PROTOCOL = 'arcane-ai-model-authority/1';
+
+function localAIError(code, message, cause) {
+    const error = cause === undefined ? new Error(message) : new Error(message, {cause});
+    error.code = code;
+    return error;
+}
+
+function cancelled(reason) {
+    const error = localAIError('ARCANE_AI_REQUEST_ABORTED', 'The local AI request was cancelled.', reason);
+    error.name = 'AbortError';
+    return error;
+}
+
+/**
+ * Browser-safe llama.cpp access through an existing Core connection. The app
+ * selects its model; Core owns the running engine and its loaded sessions.
+ * Creating this provider neither connects a transport nor installs a runtime.
+ */
+export function createCoreLocalAIProvider({client = getInstalledCoreClient(), id = 'llama.cpp'} = {}) {
+    if (!is.string(id) || !id.trim()) throw new TypeError('The Core AI provider id must be a nonempty string.');
+    if (client !== null && (!is.function(client?.invoke) || !is.function(client?.events?.on))) {
+        throw new TypeError('The Core AI client must expose invoke and events.on.');
+    }
+
+    let runtime = null;
+    let models = [];
+    let selection = null;
+    let disposed = false;
+    let loading = false;
+    let sequence = 0;
+    let lifecycleRevision = 0;
+    const requests = new Set();
+
+    function requireClient() {
+        if (disposed) throw localAIError('ARCANE_AI_PROVIDER_DISPOSED', 'The Core AI provider is disposed.');
+        if (!client) throw localAIError('ARCANE_AI_CORE_UNAVAILABLE', 'Local llama.cpp requires an available Core connection.');
+        return client;
+    }
+
+    function requireSelection(value) {
+        if (value?.providerId !== id || !is.string(value?.modelId) || !value.modelId
+            || value.localOnly !== true) {
+            throw localAIError('ARCANE_AI_MODEL_AUTHORITY_REQUIRED', 'The local provider requires an explicit matching provider and model.');
+        }
+        return value;
+    }
+
+    function loadedModel() {
+        return selection && models.find(function selectedModel(model) {
+            return model.id === selection.modelId && model.loaded === true;
+        });
+    }
+
+    function modelReady() {
+        return runtime?.available === true && runtime.state === 'ready' && Boolean(loadedModel());
+    }
+
+    function status() {
+        const loaded = !disposed && modelReady();
+        return {
+            state: disposed ? 'disposed' : loading ? 'loading' : loaded ? 'ready'
+                : runtime?.error ? 'error' : runtime?.available === true ? 'unloaded' : 'unavailable',
+            loaded,
+            busy: loading || requests.size > 0,
+            modelId: selection?.modelId ?? null,
+            available: !disposed && runtime?.available === true,
+            installed: runtime?.installed === true,
+            error: runtime?.error ?? null
+        };
+    }
+
+    function acceptRuntime(value) {
+        runtime = value ?? null;
+        models = is.array(runtime?.models) ? runtime.models : [];
+        for (const request of requests) {
+            const model = models.find(function requestModel(record) { return record.id === request.modelId; });
+            if (model?.loaded === true) request.loaded = true;
+            if (runtime?.available !== true || (request.loaded && (runtime.state !== 'ready' || model?.loaded !== true))) {
+                request.controller.abort(localAIError('ARCANE_AI_MODEL_NOT_READY', 'The requested local model is no longer ready.', runtime?.error));
+            }
+        }
+        return status();
+    }
+
+    const unsubscribe = client?.events.on('localai.state', function localRuntimeChanged(snapshot) {
+        if (disposed || !is.array(snapshot?.runtimes)) return;
+        lifecycleRevision += 1;
+        acceptRuntime(snapshot.runtimes.find(function llamaRuntime(value) {
+            return value.id === 'llama.cpp';
+        }));
+    }) ?? function noCoreSubscription() {};
+
+    function authority(value) {
+        return {protocol: AUTHORITY_PROTOCOL, providerId: id, modelId: value.modelId};
+    }
+
+    async function inspect(value, {signal} = {}) {
+        requireSelection(value);
+        if (signal?.aborted) throw cancelled(signal.reason);
+        try {
+            const core = requireClient();
+            const statusRevision = lifecycleRevision;
+            const current = await core.invoke('llama.status', {}, {signal});
+            if (lifecycleRevision === statusRevision) acceptRuntime(current);
+            if (runtime?.available !== true) {
+                return {
+                    available: false,
+                    code: 'ARCANE_AI_PROVIDER_UNAVAILABLE',
+                    message: 'The local llama.cpp runtime is unavailable.',
+                    error: runtime?.error ?? null
+                };
+            }
+            if (!models.some(function matchesModel(model) { return model.id === value.modelId; })) {
+                return {
+                    available: false,
+                    code: 'ARCANE_AI_MODEL_UNAVAILABLE',
+                    message: 'The selected model is unavailable in the local llama.cpp runtime.'
+                };
+            }
+            return {available: true, authority: authority(value)};
+        } catch (error) {
+            if (signal?.aborted || error?.name === 'AbortError') throw error;
+            acceptRuntime({...runtime, available: false, state: 'error', error});
+            return {available: false, code: error.code ?? 'ARCANE_AI_CORE_UNAVAILABLE', message: error.message, error};
+        }
+    }
+
+    async function load({selection: value, signal, progress} = {}) {
+        const core = requireClient();
+        requireSelection(value);
+        if (signal?.aborted) throw cancelled(signal.reason);
+        selection = value;
+        loading = true;
+        try {
+            progress?.({phase: 'loading', modelId: value.modelId});
+            const revision = lifecycleRevision;
+            const current = await core.invoke('llama.load', {model: value.modelId}, {signal});
+            if (lifecycleRevision === revision) acceptRuntime(current);
+            if (!modelReady()) throw localAIError('ARCANE_AI_MODEL_NOT_READY', 'Core did not report the selected model loaded and ready.', current?.error);
+            progress?.({phase: 'ready', modelId: value.modelId});
+            return {authority: authority(value), status: {...status(), state: 'ready', busy: false}};
+        } finally {
+            loading = false;
+        }
+    }
+
+    function ownRequest(signal, modelId) {
+        const controller = new AbortController();
+        function forwardAbort() { controller.abort(signal.reason); }
+        signal?.addEventListener('abort', forwardAbort, {once: true});
+        if (signal?.aborted) forwardAbort();
+        const request = {controller, result: null, modelId, loaded: models.some(function loadedTarget(model) {
+            return model.id === modelId && model.loaded === true;
+        })};
+        requests.add(request);
+        request.release = function releaseRequest() {
+            signal?.removeEventListener('abort', forwardAbort);
+            requests.delete(request);
+        };
+        return request;
+    }
+
+    function streamRequest(core, parameters, signal) {
+        const request = ownRequest(signal, parameters.model);
+        const chunks = [];
+        const readers = [];
+        let complete = false;
+        let failure = null;
+        sequence += 1;
+        const streamId = is.function(core.uuid) ? core.uuid()
+            : globalThis.crypto?.randomUUID?.() ?? `${id}:${Date.now()}:${sequence}:${Math.random()}`;
+
+        function flush() {
+            while (readers.length && chunks.length && !request.controller.signal.aborted) {
+                readers.shift().resolve({value: chunks.shift(), done: false});
+            }
+            if (!complete || (chunks.length && !request.controller.signal.aborted)) return;
+            while (readers.length) {
+                const reader = readers.shift();
+                if (failure) reader.reject(failure);
+                else reader.resolve({value: undefined, done: true});
+            }
+        }
+
+        const stopChunks = core.events.on('llama.chunk', function receiveChunk(event) {
+            if (event?.streamId !== streamId || complete || request.controller.signal.aborted) return;
+            chunks.push(event.chunk);
+            flush();
+        });
+
+        request.result = Promise.resolve().then(function invokeStream() {
+            return core.invoke('llama.chat', {...parameters, stream: true, streamId}, {signal: request.controller.signal});
+        }).then(function streamCompleted(result) {
+            if (request.controller.signal.aborted) throw cancelled(request.controller.signal.reason);
+            return result;
+        }).catch(function streamFailed(error) {
+            failure = error;
+            throw error;
+        }).finally(function releaseStream() {
+            complete = true;
+            stopChunks();
+            request.release();
+            flush();
+        });
+        request.result.catch(function observeRetainedStreamFailure() {});
+
+        function cancel(reason) {
+            if (!complete) request.controller.abort(reason);
+            return request.result.then(function cancelledAfterSuccess() {}, function cancelledAfterFailure() {});
+        }
+
+        return {
+            result: request.result,
+            cancel,
+            [Symbol.asyncIterator]() {
+                return {
+                    next() {
+                        if (request.controller.signal.aborted) return Promise.reject(failure ?? cancelled(request.controller.signal.reason));
+                        if (chunks.length) return Promise.resolve({value: chunks.shift(), done: false});
+                        if (complete) return failure ? Promise.reject(failure) : Promise.resolve({value: undefined, done: true});
+                        return new Promise(function awaitChunk(resolve, reject) { readers.push({resolve, reject}); });
+                    },
+                    async return() {
+                        await cancel();
+                        return {value: undefined, done: true};
+                    }
+                };
+            }
+        };
+    }
+
+    async function request({selection: value, operation, payload, signal} = {}) {
+        const core = requireClient();
+        requireSelection(value);
+        if (signal?.aborted) throw cancelled(signal.reason);
+        if (loading || selection?.modelId !== value.modelId) {
+            throw localAIError('ARCANE_AI_MODEL_NOT_READY', 'Load the selected local model before requesting inference.');
+        }
+        const model = payload?.model ?? value.modelId;
+        if (!models.some(function knownModel(record) { return record.id === model; })) {
+            const revision = lifecycleRevision;
+            const current = await core.invoke('llama.status', {}, {signal});
+            if (lifecycleRevision === revision) acceptRuntime(current);
+        }
+        if (!models.some(function knownModel(record) { return record.id === model; })) {
+            throw localAIError('ARCANE_AI_MODEL_UNAVAILABLE', 'The requested model is unavailable in the local llama.cpp runtime.');
+        }
+        if (runtime?.available !== true || runtime.state !== 'ready'
+            || (model === value.modelId && !modelReady())) {
+            throw localAIError('ARCANE_AI_MODEL_NOT_READY', 'The requested local runtime or selected model is not ready.');
+        }
+        const parameters = {model, payload};
+        if (operation === 'stream') return streamRequest(core, parameters, signal);
+        if (operation !== 'chat') throw localAIError('ARCANE_AI_PROVIDER_OPERATION_UNAVAILABLE', 'The local llama.cpp provider supports chat and stream.');
+        const pending = ownRequest(signal, model);
+        pending.result = Promise.resolve().then(function invokeChat() {
+            return core.invoke('llama.chat', {...parameters, stream: false}, {signal: pending.controller.signal});
+        }).then(function chatCompleted(result) {
+            if (pending.controller.signal.aborted) throw cancelled(pending.controller.signal.reason);
+            return result;
+        }).finally(pending.release);
+        return pending.result;
+    }
+
+    async function unload({selection: value = selection, signal} = {}) {
+        const core = requireClient();
+        if (signal?.aborted) throw cancelled(signal.reason);
+        for (const request of requests) request.controller.abort();
+        await Promise.allSettled([...requests].map(function activeResult(request) { return request.result; }));
+        if (!value) return status();
+        requireSelection(value);
+        const revision = lifecycleRevision;
+        const current = await core.invoke('llama.unload', {model: value.modelId}, {signal});
+        if (lifecycleRevision === revision) acceptRuntime(current);
+        selection = null;
+        return status();
+    }
+
+    async function dispose(options = {}) {
+        if (disposed) return status();
+        if (selection || requests.size) await unload(options);
+        disposed = true;
+        unsubscribe();
+        return status();
+    }
+
+    return {
+        protocol: PROVIDER_PROTOCOL,
+        role: 'llm',
+        id,
+        localOnly: true,
+        catalog: function catalog() { return [...models]; },
+        status,
+        inspect,
+        load,
+        request,
+        unload,
+        dispose
+    };
+}

package/docs/reference/README.md

@@ -111,6 +111,26 @@ The [changelog](../../CHANGELOG.md) records changes by version; the
 identify the corresponding published package source. A newer website does not
 change the version installed in your application.
 
+### Generate the selected reference site
+
+The existing `node tools/build-reference-site.mjs --write` command reads the
+live checkout. For release documentation while disjoint source work continues,
+select the reviewed documentation commit explicitly:
+
+```sh
+node tools/build-reference-site.mjs --write --source-ref <documentation-commit>
+```
+
+The same option is accepted by `createReferenceSite({sourceRef})` and
+`writeReferenceSite({sourceRef})`. It reads the selected commit's package
+version, complete reference documents and inventories, inventory-selected
+runtime sources, and authored site inputs directly from Git in memory. It
+creates no checkout or export and leaves source drafts untouched. Rendering
+uses the current canonical generator and its authored semantic contracts;
+select a documentation commit whose contracts match the published package.
+Generated output still belongs to the canonical `site/` tree and requires its
+usual coordinated output ownership. Generation does not publish hosted Pages.
+
 ### Historical 0.3.4 publication record
 
 The following records describe that earlier release only. They do not identify

package/docs/reference/cli.md

@@ -49,6 +49,7 @@ meaning and cardinality rules:
 | `--app` | app id or label | Workspace/app operations except shared scope and `verify-bundle`; optional diagnostic label for `mail serve`. |
 | `--apps-root` | `.` or `apps` | `new`, `init`; standalone setup defaults to the repository root. |
 | `--sdk-runtime-source` | SDK checkout directory | `dev` only; maps live SDK source through the selected browser destinations for that server process. |
+| `--local-ai` | comma-separated runtime IDs | `dev` only; adds `llama.cpp` and/or `ollama` requirements to application configuration and prepares missing runtimes alongside serving. See [local AI through Core](local-ai.md). |
 | `--arcane-root` | directory | `doctor`, native `build`/`run`, `native-doctor`, `native-prepare` |
 | `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to HTTPS at `127.0.0.1:8000`; `mail serve` defaults to HTTPS with HTTP/2 at `0.0.0.0:4433` and accepts an explicit bind host. |
 | `--http-port` | integer 0–65535 | Browser `dev`/`run` HTTP redirect listener; defaults to `0`, which selects an available port. |
@@ -366,9 +367,16 @@ An explicit live-source SDK mapping follows the selected browser destinations
 while reading canonical SDK source; it never replaces installed files.
 
 ```text
-arcane dev [--app <id>] [--public] [--http | --https] [--cert <file> --key <file>] [--host <address>] [--port 8000] [--http-port 0] [--sdk-runtime-source <sdk-root>]
+arcane dev [--app <id>] [--public] [--http | --https] [--cert <file> --key <file>] [--host <address>] [--port 8000] [--http-port 0] [--sdk-runtime-source <sdk-root>] [--local-ai llama.cpp,ollama]
 ```
 
+`--local-ai` saves the selected requirements in `native.localAI`, or in
+`arcane-package.json.localAI` for a package-only app. Later development runs
+reuse them. Available services and executables are reused; missing runtimes
+are installed inside the application while serving starts independently.
+Applications choose their model files and optional browser Core connection.
+See [local AI through Core](local-ai.md) for configuration and native bundling.
+
 ### Lifecycle
 
 Startup refreshes the selected authored `arcane-app.json` projection into

package/docs/reference/core-native-packaging.md

@@ -1,22 +1,28 @@
 # Portable Core packaging
 
 `arcane-os/native/portable-provider` owns the portable native payload in the SDK
-package. It does not load Arcane OS source, choose models, download a runtime,
-or compile an executable. Windows, Linux and macOS hosts may compose this
+package. It does not load Arcane OS source, choose models or compile an
+executable. An application's explicit `native.localAI` selection can include
+its selected upstream runtimes through the SDK local-AI installer. Without that
+selection, assembly does no local-AI runtime preparation. Windows, Linux and macOS hosts may compose this
 Node-based payload; Android needs its separate native host adaptation. The
 current CLI's portable platform selections remain Windows and Linux. A portable
 artifact is not a Windows executable, Linux package or Android application.
 
 `loadArcaneNativeProvider({target:'portable'})` selects the installed SDK provider
 without an `arcaneRoot`. Supplying an explicit `arcaneRoot` retains the existing
-checkout-provider route. Other native targets remain with their actual platform
+checkout-provider route. The SDK also owns the `windows-x64` executable provider
+described below. Other native targets remain with their actual platform
 providers; the loader does not substitute this payload for an unavailable host.
 
 ## Provider and selected input
 
 The default export and `arcaneNativeBuilderProvider` are the same provider.
-`createPortableNativeProvider({services:[]})` creates one with application-owned
-service configuration. All implement `arcane-native-builder/1`:
+`createPortableNativeProvider({services})` creates one with application-owned
+service configuration. Without that override, the provider uses the selected
+app descriptor's `native.services`, or an empty selection when omitted. An
+explicit `services:[]` overrides the descriptor with no app services.
+All implement `arcane-native-builder/1`:
 
 - `describe()` identifies the portable target and `executable:false`.
 - `doctor({targetRequest, signal, onEvent})` reports missing SDK Core source files.
@@ -42,6 +48,45 @@ receipts, hashes, content limits or security policy. The package-relative source
 root comes from the provider module's own location, not `toolchainRoot` or an
 Arcane OS machine bundle.
 
+## Native-only application resources
+
+Select application service modules and their complete local source closure in
+the authored schema-2 descriptor's `package.nativeResources`, separately from
+its browser `include`/`exclude` selection:
+
+```json
+{
+  "package": {
+    "nativeResources": {
+      "include": ["native", "src", "package.json"],
+      "exclude": ["native/drafts"]
+    }
+  }
+}
+```
+
+This is a descriptor excerpt for the app-owned service example below. The
+projected schema-1 field is top-level `nativeResources`. Paths are literal and
+app-relative; directories include descendants. Omission or an empty include
+keeps previous selection and output behavior. The app supplies every required
+source file explicitly; packaging does not discover or execute services.
+
+Paired `buildApplication()` passes the actual native target to the selected app
+and every explicitly bundled app. With a nonempty native include list, their
+input releases use `dist/.native/<target>/<app-id>` instead of the saved browser
+output, preserving existing browser/PWA artifacts. Each app's own selection is
+applied; complete releases and actual roots are forwarded to the provider.
+The provider then copies them unchanged into its artifact layout described below.
+
+At the low-level `packageApp()` boundary, `target` defaults to `'browser'` and
+is independent of `moduleFormat`. Nonbrowser selection disables generated PWA
+content. Native-only files bypass browser document/module/asset transformations;
+a file also in the ordinary browser selection retains that existing processing.
+An explicit low-level `outputDirectory` still wins. Inspect the emitted input
+with `verifyApp({workspaceRoot,appId,outputDirectory:release.output})`; neither
+that inventory verification nor packaging launches the service or platform host.
+See [the complete selection contract](protocols.md#native-only-application-resources).
+
 ## Output and host contract
 
 Each build creates a fresh `arcane-portable-*` directory beneath `outputRoot`.
@@ -85,7 +130,9 @@ host must:
 1. Mount `app/` at the root of its local application URL origin, preserving the
    selected start path and all navigable documents.
 2. Inject `runtime/arcane-api.js` at document creation. It is produced by the
-   canonical `createCoreClassicSource()` generator, not a copied OS client.
+   canonical `createCoreClassicSource()` generator with `replayRuntimeState:true`.
+   Once its transport listener is attached, each document requests the current
+   Core and service state without starting services again.
 3. Start `runtime/arcane-core.mjs` with the host's supported Node runtime and
    connect the existing framed stdin/stdout transport.
 4. Close input and await Core's drain before terminating the child process.
@@ -100,7 +147,21 @@ is not the native serving contract. No host is launched during packaging.
 
 ## Explicit application services
 
-Pass native service modules already included in the selected app release:
+For the ordinary SDK build command, select native service modules in the
+application's authored descriptor. Include their source closure through
+`package.nativeResources` as described above:
+
+```json
+{
+  "native": {
+    "services": [
+      {"module":"native/moon-ledger.mjs", "options":{"ledgerName":"Cheese debts"}}
+    ]
+  }
+}
+```
+
+Direct SDK compositions can instead pass that selection to the provider:
 
 ```js
 import {createPortableNativeProvider} from 'arcane-os/native/portable-provider';
@@ -111,7 +172,8 @@ const nativeBuilder = createPortableNativeProvider({
 ```
 
 Each module default-exports a synchronous factory returning the existing Core
-service definition. Its options must be JSON-serializable data. Module imports
+service definition. Its first argument is the complete authored options record;
+its second is the shared launch context described below. Options must be JSON-serializable data. Module imports
 and factories run only when the generated Core entry is launched, never during
 packaging. Put asynchronous initialization in `start()`, not a top-level await
 or asynchronous factory, so unrelated services and dispatcher readiness remain
@@ -142,8 +204,130 @@ observable through `onError` and `closed`; no process is killed or forcibly exit
 See [the Core runtime contract](core-runtime.md) for request and service lifetime
 details and [the client contract](core-client.md) for native bridge integration.
 
-This source increment supplies portable assembly and service composition.
-Desktop WebView executables, platform child-process ownership, Android dispatch
-and executable build toolchains require their own completed adapters. Published
+## Launch-time locations
+
+The generated Core entry accepts `--arcane-launch-config <path>`. The public
+`readCoreLaunchContext({argv=process.argv.slice(2)}={})` function in
+`arcane-os/core/host` reads that explicitly selected JSON object. Without the
+flag it returns `{}`. Missing files, missing flag values and malformed JSON
+report their actual errors; the reader does not search for configuration,
+rewrite it or change the process environment.
+
+The generated entry supplies an artifact-derived `appRoot` and then applies the
+complete explicit launch context. Every service factory receives that same
+object as its second argument, preserving its authored first argument. A
+launcher can supply the user's selected `workspaceRoot` and writable
+`stateRoot` at launch instead of embedding this machine's paths in an app
+package. The host owns those selections; the SDK does not choose a product's
+workspace, namespace, saved preferences or models. JSON values and additional
+application-owned fields remain unchanged.
+
+## Selected local-AI runtimes
+
+When `appDescriptor.native.localAI` is present, portable assembly calls the
+SDK's `bundleLocalAIRuntimes()` owner with its `runtimes` selection and the
+requested target platform/architecture. Its reusable installation directory is
+`<outputRoot>/local-ai-runtimes`; each new payload receives the complete selected
+runtime trees beneath `runtime/local-ai/`. Runtime preparation and app copying
+proceed independently and both settle before assembly can clean up an incomplete
+output. No application service or model executes during packaging.
+
+`manifest.core.localAIRuntimes` records the bundled runtime locations relative
+to the artifact root. Only the explicitly configured entry imports
+`createLocalAIService` from `arcane-os/core/local-ai`. It resolves those bundled
+locations against the installed artifact and supplies them in the launch
+context's `runtimes` array, alongside `appRoot`, before applying explicit launch
+configuration. It passes the complete authored `native.localAI` record to the
+factory. Applications without that selection have no generated local-AI import
+or service. Availability of a particular engine belongs to the selected
+local-AI installer and service; a generic ONNX runtime is not a speech model.
+
+## Windows executable
+
+The ordinary application command is:
+
+```sh
+npm exec -- arcane build --target windows-x64
+```
+
+`loadArcaneNativeProvider({target:'windows-x64'})` selects the SDK's own
+`arcane-os/native/windows-provider` without an OS checkout or `arcaneRoot`.
+Its default export and `arcaneNativeBuilderProvider` are the same provider;
+`createWindowsNativeProvider({services,hostDirectory})` permits explicit
+same-project composition. Service selection follows the portable provider's
+descriptor/override contract above.
+
+The provider assembles the selected app with the precompiled host asset
+`arcane-native-windows-x64.tar.gz` from the numeric GitHub release matching the
+builder's installed SDK version. The asset contains the launcher, WebView2
+support libraries, Node SEA Core executable and required license files. It does
+not select the newest host independently of that package. Downloads occur only
+during `build()`, use the caller's output directory, and are reused from
+`<outputRoot>/.arcane-native-hosts/<sdk-version>/windows-x64`. The build machine
+needs the standard `tar` command for extraction; application builds do not need
+a C# compiler, system Node installation for the generated executable, or host
+source scripts. The SDK build command itself still runs through the application's
+normal Node/npm toolchain.
+
+An explicit `hostDirectory` selects an already-built complete host tree instead
+of downloading one. This is useful for SDK collaborators verifying the next
+host output; downstream applications use the published package and matching
+release asset. `doctor()` reports the selected prerequisites and missing files;
+it does not download the host or probe the installed WebView runtime.
+
+The assembled directory contains `Arcane.exe`, the unchanged `app/` payload,
+Core runtime and semantic `arcane-native.json`. Launch `Arcane.exe` on Windows
+x64 with the Microsoft Edge WebView2 Runtime installed. It opens the selected
+app in WebView2 and owns its framed connection to the bundled Core process.
+`verify()` observes the assembled files and manifest; it does not execute the
+window or prove application behavior. `run()` launches the executable and
+observes complete diagnostics and exit. Cancelling that operation closes its
+input, allowing the window and accepted Core service work to drain without a
+forced process termination.
+
+For explicit user-selected workspace/state locations, launch:
+
+```sh
+Arcane.exe --arcane-launch-config path/to/launch.json
+```
+
+The complete JSON object reaches the service factories as their second
+argument. A supplied `stateRoot` also owns the WebView2 profile and diagnostic
+directory. Otherwise the launcher uses the current user's local application
+data under `Arcane/<app-id>`. The launcher does not invent an application
+workspace. Relative launch-file paths resolve from the invocation's working
+directory. `--close-on-stdin-eof` is an explicit process-owner option used by the
+SDK runner; an ordinary double-clicked window closes through its own UI.
+
+## Windows host source and selected output
+
+The SDK's `src/core/hosts/windows/ArcaneCoreProcess.cs` owns an explicitly
+selected executable, argument string and working directory. It reads complete
+framed Core messages and diagnostics, acknowledges ordered asynchronous writes,
+and closes stdin before awaiting accepted Core work, final output and process
+exit. It does not kill the child on an ordinary close.
+
+`ArcaneHost.cs` composes that process with a WebView2 window through
+`ArcaneHost.Run(options,onDiagnostic,onError)` or `ArcaneHostForm`. Options
+select the app root/start path, stable virtual HTTPS origin, profile directory,
+title, canonical classic-client source and Core process inputs. The form exposes
+`Ready`, `Completion` and `CloseAsync()`. Page navigation, transport connection,
+Core readiness and service readiness are separate states. Accepted work drains
+before the window closes; complete engineering errors go to the supplied
+diagnostic/error callbacks. Callbacks must not synchronously wait for the
+window's lifetime promises.
+
+`ArcaneLauncher.cs` supplies the executable entry point for that composition.
+`tools/build-core-windows-host.mjs` builds the selected SDK host output from the
+approved WebView2 package, existing .NET Framework compiler and selected Node
+SEA output. It retains complete compiler diagnostics and produces a fresh
+directory rather than overwriting an earlier artifact. The host requires
+.NET Framework 4.6.2 or later. This is SDK release tooling, not an application
+build requirement. Source compilation, selected host execution and real
+application behavior are separate evidence boundaries; an assembled app is not
+an installer or proof of its domain behavior.
+
+Linux, macOS, Android dispatch and each platform's output verification retain
+their separate delivery boundaries. Published
 consumers must adopt the numeric package that includes this increment; a source
 checkout or a successful source push is not that public package authority.