arcane-os 0.55.0 → 0.57.0

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

@@ -1,17 +1,87 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.55.0",
+  "sdkVersion": "0.56.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 244,
+  "memberCount": 254,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "core-local:createCoreLocalAIProvider",
+      "name": "createCoreLocalAIProvider",
+      "displayName": "createCoreLocalAIProvider()",
+      "kind": "function",
+      "signature": "createCoreLocalAIProvider({client,id='llama.cpp'}={})",
+      "entrypoints": ["arcane-os/ai/core-local"],
+      "primaryImport": "arcane-os/ai/core-local",
+      "group": "Core local AI",
+      "summary": "Browser llama.cpp provider through an explicitly connected Core, with application-owned model selection and complete response streaming.",
+      "availability": "Browser with an available Core local AI service; construction installs no runtime or model",
+      "protocol": "arcane-ai-provider/2 LLM lifecycle over arcane/1",
+      "normalization": "Preserves complete payloads and original parsed chunks; waits for the exact requested model and cancels on observed readiness loss"
+    },
+    {
+      "id": "core-local-ai:createLocalAIService",
+      "name": "createLocalAIService",
+      "displayName": "createLocalAIService()",
+      "kind": "function",
+      "signature": "createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent}={})",
+      "entrypoints": ["arcane-os/core/local-ai"],
+      "primaryImport": "arcane-os/core/local-ai",
+      "group": "Core local AI",
+      "summary": "Composes selected native llama.cpp and Ollama engines as a Core service with retained process ownership and model lifecycle.",
+      "availability": "Node with selected upstream runtime distributions or available configured system services",
+      "protocol": "arcane/1 methods and events; llama.cpp OpenAI HTTP/SSE and Ollama native HTTP/NDJSON",
+      "normalization": "Application-owned runtime and model requirements; independent startup, complete responses and exact owned-process cleanup"
+    },
+    {
+      "id": "core-local-ai:default",
+      "name": "default",
+      "displayName": "createLocalAIService default export",
+      "kind": "function",
+      "signature": "default as createLocalAIService",
+      "entrypoints": ["arcane-os/core/local-ai"],
+      "primaryImport": "arcane-os/core/local-ai",
+      "group": "Core local AI",
+      "summary": "Default binding for the same native Core local AI service factory.",
+      "availability": "Node",
+      "protocol": "arcane/1 service definition",
+      "normalization": "Binding identity equals the named createLocalAIService export"
+    },
+    {
+      "id": "local-ai:ensureLocalAIRuntimes",
+      "name": "ensureLocalAIRuntimes",
+      "displayName": "ensureLocalAIRuntimes()",
+      "kind": "function",
+      "signature": "ensureLocalAIRuntimes({runtimes=[],directory,platform,architecture,signal,onEvent}={})",
+      "entrypoints": ["arcane-os/local-ai"],
+      "primaryImport": "arcane-os/local-ai",
+      "group": "Core local AI",
+      "summary": "Reuses selected managed native runtimes or installs complete official llama.cpp and Ollama distributions.",
+      "availability": "Node; upstream platform and architecture assets determine runtime availability",
+      "protocol": "Official upstream release downloads and host archive extraction",
+      "normalization": "Returns absolute runtime records; shares matching concurrent installs, preserves libraries and reports failures without changing global PATH or services"
+    },
+    {
+      "id": "local-ai:bundleLocalAIRuntimes",
+      "name": "bundleLocalAIRuntimes",
+      "displayName": "bundleLocalAIRuntimes()",
+      "kind": "function",
+      "signature": "bundleLocalAIRuntimes({runtimes=[],directory,outputRoot,platform,architecture,signal,onEvent}={})",
+      "entrypoints": ["arcane-os/local-ai"],
+      "primaryImport": "arcane-os/local-ai",
+      "group": "Core local AI",
+      "summary": "Copies selected complete runtime distributions into a fresh native artifact staging root.",
+      "availability": "Node; supports bundling published upstream platform assets independently of the build host",
+      "protocol": "Artifact-relative runtime/local-ai layout",
+      "normalization": "Returns {runtimes,files} with relative runtime records and the complete emitted inventory; model resources remain application-owned"
+    },
     {
       "id": "root:WS",
       "name": "WS",
@@ -380,7 +450,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Headless toolchain operations",
-      "summary": "Packages the selected app and builds one explicitly selected target; tests or checks run only when explicitly requested or required for the selected release output.",
+      "summary": "Packages the selected app and builds one explicitly selected target; paired native assembly applies each selected and bundled app's nativeResources and separate input output directory, preserving complete release records and explicit providers. Tests or checks run only when explicitly requested or required for the selected release output.",
       "availability": "Node; selected operation may produce browser or native output",
       "protocol": "Shared headless operation API + arcane-cli-events/1",
       "normalization": "SDK-normalized inputs, errors, events, and documented result"
@@ -937,14 +1007,14 @@
       "name": "inspectApp",
       "displayName": "inspectApp()",
       "kind": "function",
-      "signature": "async inspectApp({workspaceRoot, appId, signal}={})",
+      "signature": "async inspectApp({workspaceRoot, appId, signal, target, outputDirectory}={})",
       "entrypoints": [
         "arcane-os",
         "arcane-os/packager"
       ],
       "primaryImport": "arcane-os",
       "group": "Packaging and release bundles",
-      "summary": "Loads one validated packager app plan, including the shared descriptor-admitted browser document inventory and final workspace-relative output selected by app outputDirectory or default dist/appId.",
+      "summary": "Inspects one complete app plan without copying files. Target defaults to browser; nonbrowser selection adds explicit nativeResources outside browserDocuments and uses dist/.native/target/appId for a nonempty native include list. Explicit operation outputDirectory wins; other calls retain the saved outputDirectory or dist/appId.",
       "availability": "Node",
       "protocol": "SDK packager and deterministic bundle contract",
       "normalization": "Normalized SDK validation with complete canonical archive and release content"
@@ -1239,7 +1309,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Packaging and release bundles",
-      "summary": "Builds one selected browser application release into app outputDirectory or default dist/appId through staged whole-directory replacement, preserving source and unrelated prior destinations; it never runs tests or checks automatically.",
+      "summary": "Builds one complete app release with browser selection by default. Nonbrowser targets add explicit nativeResources through a late complete-content copy and separate native input output; moduleFormat is independent. Adapters receive actual target and effective browserPwa. Explicit operation outputDirectory wins; staged replacement preserves source and unrelated outputs. No tests or checks run automatically.",
       "availability": "Node",
       "protocol": "SDK packager and deterministic bundle contract",
       "normalization": "Normalized SDK validation with complete canonical archive and release content"
@@ -1256,7 +1326,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Headless toolchain operations",
-      "summary": "Runs the high-level package operation for one selected application using the same app-selected final outputDirectory, defaulting to dist/appId, with no separate destination override.",
+      "summary": "Runs the high-level browser package operation for one selected application using the saved outputDirectory or dist/appId, with no separate destination override. Paired native buildApplication separately applies actual target and nativeResources selection.",
       "availability": "Node; selected operation may produce browser or native output",
       "protocol": "Shared headless operation API + arcane-cli-events/1",
       "normalization": "SDK-normalized inputs, errors, events, and documented result"
@@ -1370,7 +1440,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Runtime and app descriptors",
-      "summary": "Projects a schema-2 descriptor into the compatible schema-1 application package contract.",
+      "summary": "Projects a schema-2 descriptor into the compatible schema-1 package contract, including optional package.nativeResources as top-level nativeResources; omitted selection stays omitted, empty include stays empty, and omitted exclude becomes an empty array.",
       "availability": "Node",
       "protocol": "Node ESM",
       "normalization": "SDK-normalized inputs, errors, events, and documented result"
@@ -2073,7 +2143,7 @@
       ],
       "primaryImport": "arcane-os/packager",
       "group": "Packaging and release bundles",
-      "summary": "Validates one schema-1 packager app configuration and its relationship to the root config, including optional workspace-relative final outputDirectory without changing source layout or app identity.",
+      "summary": "Validates one schema-1 packager app configuration, optional nativeResources literal include/exclude selection and workspace-relative outputDirectory without changing source layout or app identity. Native include may be empty; exclude defaults to an empty array.",
       "availability": "Node",
       "protocol": "SDK packager and deterministic bundle contract",
       "normalization": "Normalized SDK validation with complete canonical archive and release content"
@@ -2172,7 +2242,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Packaging and release bundles",
-      "summary": "Authenticates one existing browser app release through the low-level packager API.",
+      "summary": "Reads an existing app release and compares its complete file inventory with its manifest. Pass a target-selected native release's output as outputDirectory; this API does not infer a native target or execute services or hosts.",
       "availability": "Node",
       "protocol": "SDK packager and deterministic bundle contract",
       "normalization": "Normalized SDK validation with complete canonical archive and release content"
@@ -3657,7 +3727,7 @@
       "entrypoints": ["arcane-os/core/contracts"],
       "primaryImport": "arcane-os/core/contracts",
       "group": "Core protocol contracts",
-      "summary": "Describes the public fields on Core request, response, event and cancellation frames.",
+      "summary": "Describes the public fields on Core request, response, event, cancellation and runtime.replay control frames.",
       "availability": "Node and browser/bundler",
       "protocol": "arcane/1 wire descriptions",
       "normalization": "Descriptive data only; it does not admit methods, validate application policy or create a transport"
@@ -3709,14 +3779,14 @@
       "name": "createCoreClient",
       "displayName": "createCoreClient()",
       "kind": "function",
-      "signature": "createCoreClient({global=globalThis,transport=null,eventOwner=arcaneEvents,eventOwnerReady,autoConnect=true,onError}={})",
+      "signature": "createCoreClient({global=globalThis,transport=null,eventOwner=arcaneEvents,eventOwnerReady,autoConnect=true,replayRuntimeState=false,onError}={})",
       "entrypoints": ["arcane-os/core/client"],
       "primaryImport": "arcane-os/core/client",
       "group": "Core browser client",
       "summary": "Creates one correlated Arcane Core RPC client with explicit transport, readiness, events, cancellation and lifetime ownership.",
       "availability": "Browser and native WebView JavaScript hosts; custom transports require a callable send(frame)",
       "protocol": "arcane/1 over the selected host transport",
-      "normalization": "Preserves complete request, result and event data; rejects invalid transports before readiness, retains FIFO handoff to the shared event owner and reports transport failures that arrive after request settlement"
+      "normalization": "Preserves complete request, result and event data; retains FIFO event-owner handoff; failTransport(error) settles pending RPCs and acknowledgements with the complete failure and releases the client lifetime; opt-in replayRuntimeState sends one observed nonblocking runtime.replay control after transport readiness"
     },
     {
       "id": "core-client:createCoreFacade",
@@ -3741,24 +3811,38 @@
       "entrypoints": ["arcane-os/core/client"],
       "primaryImport": "arcane-os/core/client",
       "group": "Core browser client",
-      "summary": "Installs one synchronous global Arcane facade and native receive callback for the selected renderer lifetime.",
+      "summary": "Installs one synchronous global Arcane facade, native receive callback and terminal transport-failure callback for the selected renderer lifetime.",
       "availability": "Browser and native WebView JavaScript hosts",
       "protocol": "arcane/1 renderer facade",
-      "normalization": "Repeated installation returns the same client; closing releases subscriptions, callbacks, timers and pending renderer requests without killing Core"
+      "normalization": "Repeated installation returns the same client; close/failTransport release owned resources and restore prior globals only while still owned; __arcaneTransportFailed preserves the complete host failure without killing Core"
+    },
+    {
+      "id": "core-client:getInstalledCoreClient",
+      "name": "getInstalledCoreClient",
+      "displayName": "getInstalledCoreClient()",
+      "kind": "function",
+      "signature": "getInstalledCoreClient(global=globalThis)",
+      "entrypoints": ["arcane-os/core/client"],
+      "primaryImport": "arcane-os/core/client",
+      "group": "Core browser client",
+      "summary": "Returns the exact live SDK-installed client or null without installing, connecting or changing globals.",
+      "availability": "Browser and native WebView JavaScript hosts",
+      "protocol": "arcane/1 renderer client ownership",
+      "normalization": "Recognizes ESM and classic SDK installation identity; returns null after close or terminal failure and does not treat a foreign Arcane facade as an SDK client"
     },
     {
       "id": "core-classic-source:createCoreClassicSource",
       "name": "createCoreClassicSource",
       "displayName": "createCoreClassicSource()",
       "kind": "function",
-      "signature": "async createCoreClassicSource({eventOwnerModuleURL}={})",
+      "signature": "async createCoreClassicSource({eventOwnerModuleURL,replayRuntimeState=false}={})",
       "entrypoints": ["arcane-os/core/classic-source"],
       "primaryImport": "arcane-os/core/classic-source",
       "group": "Core classic client projection",
       "summary": "Generates the native host's classic injection script from the installed canonical Core client and contracts.",
       "availability": "Node; generated source runs in browser and native WebView renderers",
       "protocol": "arcane/1 classic-script injection",
-      "normalization": "Returns the complete canonical client projection; installs synchronous facade shapes while deferring only the shared event-owner module connection when document parsing is incomplete"
+      "normalization": "Returns the complete canonical client projection; installs synchronous facade shapes while deferring only the event-owner module connection when document parsing is incomplete; forwards explicit runtime replay selection with a false default"
     },
     {
       "id": "core-runtime:createCoreRuntime",
@@ -3772,7 +3856,7 @@
       "summary": "Creates an app-neutral Core dispatcher with explicit services, request lifetimes, events and graceful drain.",
       "availability": "Node on Windows, Linux and macOS native hosts; Android requires its host adaptation",
       "protocol": "arcane/1 dispatcher and service lifecycle",
-      "normalization": "Starts services independently, preserves request correlation and complete results/errors, cancels only request-lifetime work and waits accepted service-lifetime responses before ordered service drain and disposal"
+      "normalization": "Starts services independently, preserves complete results/errors, cancels only request-lifetime work and drains accepted service work; runtime.replay publishes current dispatcher/service state without restart and preserves reentrant lifecycle publication order"
     },
     {
       "id": "core-stdio:encodeCoreFrame",
@@ -3821,14 +3905,14 @@
       "name": "createPortableNativeProvider",
       "displayName": "createPortableNativeProvider()",
       "kind": "function",
-      "signature": "createPortableNativeProvider({services=[]}={})",
+      "signature": "createPortableNativeProvider({services}={})",
       "entrypoints": ["arcane-os/native/portable-provider"],
       "primaryImport": "arcane-os/native/portable-provider",
       "group": "Portable native provider",
       "summary": "Creates the SDK-owned provider that assembles one selected app and explicit services into a portable Core payload.",
       "availability": "Node; produces a portable payload rather than an executable host",
       "protocol": "arcane-native-builder/1 portable provider",
-      "normalization": "Preserves complete selected app and dependency releases, uses explicit service module factories, reports executable:false and never substitutes for an unavailable platform host"
+      "normalization": "Preserves complete selected app and dependency releases; an explicit services selection overrides appDescriptor.native.services, otherwise the descriptor selection is used; reports executable:false and never substitutes for an unavailable platform host"
     },
     {
       "id": "native-portable-provider:arcaneNativeBuilderProvider",
@@ -3858,6 +3942,62 @@
       "protocol": "arcane-native-builder/1 portable provider",
       "normalization": "Binding identity is exactly equal to the named arcaneNativeBuilderProvider export"
     },
+    {
+      "id": "native-windows-provider:createWindowsNativeProvider",
+      "name": "createWindowsNativeProvider",
+      "displayName": "createWindowsNativeProvider()",
+      "kind": "function",
+      "signature": "createWindowsNativeProvider({services,hostDirectory}={})",
+      "entrypoints": ["arcane-os/native/windows-provider"],
+      "primaryImport": "arcane-os/native/windows-provider",
+      "group": "Windows native provider",
+      "summary": "Assembles selected application services and browser content with the SDK-owned Windows x64 WebView2 and SEA host.",
+      "availability": "Node for assembly; Windows x64 with WebView2 Runtime for execution",
+      "protocol": "arcane-native-builder/1 windows-x64 provider",
+      "normalization": "Uses a selected hostDirectory or the exact installed SDK version's numeric release asset; preserves complete payloads; run cancellation closes stdin and waits for host-owned graceful shutdown"
+    },
+    {
+      "id": "native-windows-provider:arcaneNativeBuilderProvider",
+      "name": "arcaneNativeBuilderProvider",
+      "displayName": "arcaneNativeBuilderProvider",
+      "kind": "singleton",
+      "signature": "const arcaneNativeBuilderProvider",
+      "entrypoints": ["arcane-os/native/windows-provider"],
+      "primaryImport": "arcane-os/native/windows-provider",
+      "group": "Windows native provider",
+      "summary": "SDK-owned Windows provider selected by the ordinary windows-x64 build command without an OS checkout.",
+      "availability": "Node for assembly; Windows x64 with WebView2 Runtime for execution",
+      "protocol": "arcane-native-builder/1 windows-x64 provider",
+      "normalization": "Uses appDescriptor.native.services and the exact SDK release host asset; binding is identical to the default export"
+    },
+    {
+      "id": "native-windows-provider:default",
+      "name": "default",
+      "displayName": "arcaneNativeBuilderProvider default export",
+      "kind": "singleton",
+      "signature": "default as arcaneNativeBuilderProvider",
+      "entrypoints": ["arcane-os/native/windows-provider"],
+      "primaryImport": "arcane-os/native/windows-provider",
+      "group": "Windows native provider",
+      "summary": "Default binding for the SDK Windows executable provider.",
+      "availability": "Node for assembly; Windows x64 with WebView2 Runtime for execution",
+      "protocol": "arcane-native-builder/1 windows-x64 provider",
+      "normalization": "Binding identity is exactly equal to the named arcaneNativeBuilderProvider export"
+    },
+    {
+      "id": "core-host:readCoreLaunchContext",
+      "name": "readCoreLaunchContext",
+      "displayName": "readCoreLaunchContext()",
+      "kind": "function",
+      "signature": "readCoreLaunchContext({argv=process.argv.slice(2)}={})",
+      "entrypoints": ["arcane-os/core/host"],
+      "primaryImport": "arcane-os/core/host",
+      "group": "Native Core host composition",
+      "summary": "Reads the complete JSON object explicitly selected by --arcane-launch-config for native service launch context.",
+      "availability": "Node, including the selected external-entry SEA launcher",
+      "protocol": "Explicit launch arguments and JSON configuration",
+      "normalization": "Returns an empty record without the flag; preserves every supplied field and value, surfaces file and JSON failures, and performs no configuration search, rewrite or environment mutation"
+    },
     {
       "id": "core-host:startCoreHost",
       "name": "startCoreHost",

package/docs/reference/local-ai.md

@@ -0,0 +1,197 @@
+# Local AI through Core
+
+Core owns native llama.cpp and Ollama processes. The browser retains its own
+Wllama and ONNX implementations, and can also use an explicitly connected Core
+when that system service is available. Runtime installation, model loading and
+inference are separate operations.
+
+This native service currently implements llama.cpp and Ollama. Native ONNX
+inference remains separate unfinished work. Browser ONNX continues through its
+existing browser implementation.
+
+## Application requirements
+
+Declare required native runtimes in `arcane-app.json` under `native.localAI`.
+The package projection retains the same record as `arcane-package.json.localAI`.
+Existing native fields remain alongside this record:
+
+```json
+{
+  "runtimes": [
+    {"id": "llama.cpp"},
+    {"id": "ollama"}
+  ],
+  "llamaCpp": {
+    "modelsDirectory": "models/llama"
+  },
+  "ollama": {
+    "modelsDirectory": "models/ollama"
+  }
+}
+```
+
+Each runtime requirement accepts `id`, optional upstream `version`, and an
+optional runtime archive `url`. A string runtime ID is also accepted.
+Omitting the version allows reuse of an available runtime. Explicit versions
+select that upstream distribution; an existing service must match the requested
+version before it is reused. A service occupying the selected address is
+preserved when its version cannot be established.
+
+`llamaCpp` accepts `url`, `model`, `modelsDirectory`, and an `args` string array.
+`model` selects a single GGUF file; `modelsDirectory` selects llama.cpp router
+mode. Paths resolve from the application root. Ollama accepts `url`,
+`modelsDirectory`, and `args`. The default endpoints are
+`http://127.0.0.1:8080` and `http://127.0.0.1:11434`, respectively. Default model
+directories are `.arcane/models/llama.cpp` and `.arcane/models/ollama` inside the
+application. Applications choose and provision their models explicitly.
+
+## Development
+
+```sh
+arcane dev --local-ai llama.cpp,ollama
+```
+
+The option adds those runtime requirements to the authored application
+configuration. Subsequent `arcane dev` runs reuse the saved requirements.
+Development checks selected endpoints and existing executable paths, then
+installs missing runtimes under the application's `.arcane/local-ai/runtimes`.
+Runtime preparation runs alongside HTTP serving. Browser rendering continues
+while installation and model readiness are pending.
+
+The SDK downloads the official llama.cpp or Ollama distribution directly and
+preserves its runtime libraries. Installation changes no global PATH, system
+service or machine environment. Windows and macOS use the host archive utility;
+Linux requires `tar`, and `unzip` when extracting a selected Windows ZIP.
+Zstandard archives use the supported Node runtime's decompressor.
+
+For the optional development browser connection, load the bootstrap after the
+managed import map and before creating a Core-backed provider:
+
+```js
+const {client} = await import('/arcane-local-ai.js');
+const status = await client.invoke('localai.status');
+console.log(status);
+```
+
+The bootstrap uses the existing Core client with RPC and ordered SSE events.
+Each browser connection owns its requests and cancellation. Closing a tab
+cancels that tab's requests; closing development stops its owned runtime
+processes. An already running external service remains running.
+
+`developApplication()` returns its usual server handle and an optional `localAI`
+handle with `ready`, `current()`, `handler()` and `close()`. Its `ready` promise
+means installation and Core composition completed. Runtime/model readiness is
+reported separately by Core status and lifecycle events. Preparation failures
+remain on that promise and the operation event stream.
+
+## Core service
+
+```js
+import {createLocalAIService} from 'arcane-os/core/local-ai';
+
+const service = createLocalAIService(application.native.localAI, {
+  appRoot,
+  runtimes,
+  signal,
+  onEvent
+});
+```
+
+The result is a Core service definition. The launch context contains resolved
+runtime records; the native builder supplies them automatically for a selected
+application. `current()` returns the current snapshot without starting another
+process. The service starts each selected runtime independently, retains its
+process between requests, and joins cleanup during disposal.
+
+`localai.status` returns `{runtimes}` and, when Ollama is selected, the existing
+`ollama` and `models.ollama` catalog fields. Runtime records distinguish
+`installed`, `available`, `state`, `models`, ownership and errors. A listening
+service and a loaded model are separate facts.
+
+`localai.services.recover({runtimes: ['llama.cpp']})` makes one explicit recovery
+attempt for the selected runtimes; omission selects all configured runtimes.
+Recovery restarts only SDK-owned processes and reconnects to external services.
+An external llama.cpp server returns HTTP 503 during initial model loading and
+offers no readiness subscription at that stage. Core retains `state: 'loading'`;
+a subsequent explicit load or recovery request checks again. There is no
+background health polling.
+
+| Method | Parameters | Result |
+| --- | --- | --- |
+| `llama.status` | `{}` | Runtime state and model catalog |
+| `llama.models` | `{}` | `{models}` |
+| `llama.load` | `{model}` | State after the exact model reports loaded |
+| `llama.unload` | `{model}` | Current state after release |
+| `llama.chat` | `{model,payload,stream?,streamId?}` | Complete OpenAI-shaped completion |
+
+The `payload` is the complete request. SDK option names are translated only at
+the upstream protocol boundary; messages, tool definitions and documents remain
+unchanged. An explicit `payload.model` selects that request's model. Core waits
+for its actual readiness before inference. Router model-load work is shared
+between concurrent callers for the same model. Cancelling a caller stops its
+wait; explicit unloading releases the model.
+
+Streaming publishes every actual parsed upstream chunk as
+`llama.chunk: {streamId,chunk}` and assembles the terminal completion. Upstream
+stream errors remain visible as their original chunks and fail the request.
+`localai.state` carries current runtime/model state. Router lifecycle events
+observe load, sleep and unload changes. Direct servers expose readiness at
+request boundaries; they do not offer the router's passive model event stream.
+
+Unloading a model from an owned single-model server closes that owned process;
+a subsequent load can start it again. Releasing an externally owned direct
+server returns `released: true, unloaded: false`, retaining the real catalog
+and leaving that server running.
+
+Ollama retains the existing Core calls for `version`, `models`/`list`, `running`,
+`show`, `chat`, `generate`, `embed`, `pull`, `push`, `create`, `copy`, and `delete`.
+Those methods use Ollama's native API. Streaming uses the existing
+`ollama.chunk: {streamId,chunk}` event. Application/OS preference operations
+such as selection, settings and brain creation remain with their existing
+owners; they are separate from this runtime service.
+
+## Browser llama.cpp provider
+
+```js
+import {createCoreLocalAIProvider} from 'arcane-os/ai/core-local';
+import {getAIProviderRuntime} from 'arcane-os/ai-provider-runtime';
+
+const provider = createCoreLocalAIProvider({client});
+const runtime = getAIProviderRuntime();
+const unregister = runtime.register(provider);
+```
+
+The provider implements `arcane-ai-provider/2` for the LLM role, with ID
+`llama.cpp` by default. Configure an exact model through the existing provider
+runtime, then load it. `catalog()`, `status()`, `inspect()`, `load()`, `request()`,
+`unload()` and `dispose()` retain the shared lifecycle. Creating the provider
+does not install software or select a model. A missing Core connection reports
+unavailability, leaving browser Wllama/ONNX routes available for the application
+to select.
+
+If a router evicts the primary model while serving a request-specific model,
+reload the primary selection before its next request. The provider does not
+silently change the application's saved model choice. Release registration
+with `unregister()` and dispose the provider at the application's owning
+lifecycle boundary.
+
+## Native bundling
+
+The SDK portable native build includes selected official runtime trees under
+`runtime/local-ai/<runtime-id>`. Runtime records in the artifact are relative
+to the artifact root and resolve on the destination machine. The generated
+Core entry composes the local AI service only when the application selects it.
+Model files remain application-selected native resources.
+
+`ensureLocalAIRuntimes()` and `bundleLocalAIRuntimes()` are exported from
+`arcane-os/local-ai`. Both accept `{runtimes,directory,platform,architecture,
+signal,onEvent}`; bundling also requires `outputRoot`. Platform names follow
+Node: `win32`, `linux`, `darwin`, and supported Android distributions.
+Architectures are `x64` or `arm64`. Availability depends on the upstream
+runtime's published platform assets; Ollama has no official Android runtime
+archive in this installer.
+
+Ensure returns absolute `{id,version,platform,architecture,root,executable}`
+records. Bundle returns `{runtimes,files}`, with artifact-relative runtime paths
+and a complete emitted file inventory. Bundling requires a fresh native staging
+destination, preserving existing completed outputs.