arcane-os 0.57.0 → 0.59.0

package/docs/reference/sdk-api.md

@@ -47,16 +47,25 @@ runtime layouts.
 | `arcane-os/testing` | Isolated test registration and execution. |
 | `arcane-os/targets` | Target adapters and dispatch. |
 | `arcane-os/native` | Native plan and builder protocol. |
-| `arcane-os/native-provider` | SDK portable default and explicit checkout provider loader. |
+| `arcane-os/native-provider` | SDK portable/Windows/macOS defaults and registered explicit checkout provider loader. |
 | `arcane-os/native/portable-provider` | Node-only portable payload provider and explicit app-service composition; not an executable host. |
+| `arcane-os/native/windows-provider` | Selected Windows x64 executable assembly and host-owned run/drain lifecycle. |
+| `arcane-os/native/macos-provider` | Architecture-selected Mac application bundle composition and host-owned run/drain lifecycle. |
 | `arcane-os/core/client` | Browser-safe Core RPC client, application facade, readiness and request cancellation. |
 | `arcane-os/core/contracts` | Shared Core protocol, frame, method and diagnostic error contracts. |
 | `arcane-os/core/classic-source` | Node generator for the canonical classic-script Core client projection. |
 | `arcane-os/core/runtime` | App-neutral native Core dispatcher and service lifecycle. |
 | `arcane-os/core/stdio` | Framed Node stdio transport with graceful runtime drain. |
 | `arcane-os/core/host` | Node-only reusable Core host lifecycle with explicitly supplied services. |
-| `arcane-os/core/local-ai` | Native llama.cpp and Ollama Core service, model readiness, complete streaming and owned process lifecycle. See [local AI through Core](local-ai.md). |
-| `arcane-os/local-ai` | Official runtime installation and native artifact bundling for selected llama.cpp/Ollama requirements. |
+| `arcane-os/core/packaged-web` | Core-owned packaged web listener with a persisted loopback origin and ready/failure events. |
+| `arcane-os/core/preferences` | Existing preference RPC methods with an application-selected file, ordered writes and owned drain. |
+| `arcane-os/core/diarization` | Lazy native speaker-diarization service, explicit stream methods and lifecycle/result events. |
+| `arcane-os/diarization` | Retained Nemotron model helper and independent caller-fed audio streams. |
+| `arcane-os/diarization/build` | First-party helper compilation against explicitly installed NeMo-Speech.cpp libraries. |
+| `arcane-os/core/local-ai` | Native llama.cpp, Ollama and ONNX Core service, model readiness, complete responses and owned lifecycle. See [local AI through Core](local-ai.md). |
+| `arcane-os/local-ai` | Official runtime installation and native artifact bundling for selected llama.cpp/Ollama/ONNX requirements and NeMo libraries. |
+| `arcane-os/local-ai/onnx` | Retained native ONNX worker sessions with explicit graph loading and complete tensor inference. |
+| `arcane-os/ai/core-onnx` | Optional browser access to system ONNX through an existing Core connection. |
 | `arcane-os/integrated-provider` | Fixed integrated shared-development provider. |
 | `arcane-os/packager` | Low-level browser app packager. |
 | `arcane-os/release-bundle` | Deterministic external release bundles. |
@@ -283,6 +292,7 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `runApplication()` | function | `arcane-os` | Headless toolchain operations | Node; selected operation may produce browser or native output |
 | `runDoctor()` | function | `arcane-os` | Workspace, doctor, repository, and server | Node |
 | `runProcess()` | function | `arcane-os` | Events, processes, and testing | Node |
+| `createGitTextSnapshot()` | function | `arcane-os` | Workspace, doctor, repository, and server | Node with Git |
 | `runRegisteredTests()` | function | `arcane-os` | Events, processes, and testing | Node |
 | `runRepositoryAction()` | function | `arcane-os` | Workspace, doctor, repository, and server | Node |
 | `runTarget()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
@@ -375,6 +385,27 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `arcaneNativeBuilderProvider` | singleton | `arcane-os/native/portable-provider` | Portable native provider | Node; produces a portable payload rather than an executable host |
 | `arcaneNativeBuilderProvider default export` | singleton | `arcane-os/native/portable-provider` | Portable native provider | Node; produces a portable payload rather than an executable host |
 | `startCoreHost()` | function | `arcane-os/core/host` | Native Core host composition | Node with readable input and writable output streams |
+| `readCoreLaunchContext()` | function | `arcane-os/core/host` | Native Core host composition | Node; reads explicitly selected launch JSON |
+| `createWindowsNativeProvider()` | function | `arcane-os/native/windows-provider` | Windows native provider | Node assembly; Windows x64/WebView2 execution |
+| `arcaneNativeBuilderProvider` | singleton | `arcane-os/native/windows-provider` | Windows native provider | Node assembly; Windows x64/WebView2 execution |
+| `arcaneNativeBuilderProvider default export` | singleton | `arcane-os/native/windows-provider` | Windows native provider | Node assembly; Windows x64/WebView2 execution |
+| `createMacOSNativeProvider()` | function | `arcane-os/native/macos-provider` | macOS native provider | Node assembly; matching Darwin architecture and selected host asset |
+| `arcaneNativeBuilderProvider` | singleton | `arcane-os/native/macos-provider` | macOS native provider | Node assembly; matching Darwin architecture and selected host asset |
+| `arcaneNativeBuilderProvider default export` | singleton | `arcane-os/native/macos-provider` | macOS native provider | Node assembly; matching Darwin architecture and selected host asset |
+| `createPackagedWebService()` | function | `arcane-os/core/packaged-web` | Native packaged web serving | Node Core lifetime; actual listener readiness before navigation |
+| `createPreferencesService()` | function | `arcane-os/core/preferences` | Core preference persistence | Node Core runtime with an application-selected file |
+| `createPreferencesService default export` | function | `arcane-os/core/preferences` | Core preference persistence | Same Core service factory |
+| `createDiarization()` | function | `arcane-os/diarization` | Native speaker diarization | Node with a built helper, selected NeMo libraries and caller-selected model |
+| `buildDiarizationHelper()` | function | `arcane-os/diarization/build` | Native speaker diarization | Node with installed CMake/C++17 toolchain and selected runtime |
+| `createDiarizationService()` | function | `arcane-os/core/diarization` | Native speaker diarization | Node Core runtime with explicitly selected helper, runtime and model |
+| `createDiarizationService default export` | function | `arcane-os/core/diarization` | Native speaker diarization | Same Core service factory |
+| `createCoreLocalAIProvider()` | function | `arcane-os/ai/core-local` | Core local AI | Browser/native WebView with an available Core connection |
+| `createLocalAIService()` | function | `arcane-os/core/local-ai` | Core local AI | Node with selected llama.cpp/Ollama/ONNX runtimes |
+| `createONNXRuntime()` | function | `arcane-os/local-ai/onnx` | Core local AI | Node with prepared Microsoft ONNX runtime |
+| `createCoreONNXRuntime()` | function | `arcane-os/ai/core-onnx` | Core local AI | Browser with an available Core ONNX service |
+| `createLocalAIService default export` | function | `arcane-os/core/local-ai` | Core local AI | Same native service factory |
+| `ensureLocalAIRuntimes()` | function | `arcane-os/local-ai` | Core local AI | Node; selected upstream platform assets |
+| `bundleLocalAIRuntimes()` | function | `arcane-os/local-ai` | Core local AI | Node; complete native runtime assembly |
 | `MAIL_OUTBOX_IDEMPOTENCY_WINDOW_MS` | constant | `arcane-os/mail` | Portable Mail | Node and browser metadata |
 | `MAIL_OUTBOX_PROTOCOL` | constant | `arcane-os/mail` | Portable Mail | Node and browser metadata |
 | `MAIL_OUTBOX_STATES` | constant | `arcane-os/mail` | Portable Mail | Node and browser metadata |
@@ -2723,10 +2754,12 @@ async function useloadArcaneIntegratedProvider(...arguments_) {
 
 ### Overview
 
-Loads the package-owned portable provider when `arcaneRoot` is omitted and
-`target` is `portable`. An explicit root retains the fixed Arcane OS checkout
-provider route, including its errors; there is no silent fallback. Other native
-targets still require that root. Normal Node module resolution owns imports.
+Loads the package-owned provider when `arcaneRoot` is omitted and `target` is
+`portable` or `windows-x64`. Portable produces a non-executable payload; Windows
+assembles the matching precompiled SDK host. An explicit root retains the fixed
+Arcane OS checkout provider route, including its errors; there is no silent
+fallback. Other native targets still require that root. Normal Node module
+resolution owns imports.
 
 ### Signature and result
 
@@ -4113,7 +4146,7 @@ Import it from `arcane-os`. Source mode accepts
 `{workspaceRoot=process.cwd(), appId, mode='source', host='127.0.0.1', port=0, httpPort=0, http=false,
 certPath, keyPath, tls, signal, onEvent}` and serves one validated
 workspace application plus its complete SDK or integrated runtime. Packaged mode uses
-`{mode:'packaged', releaseRoot, workspaceRoot, host, port, httpPort, certPath, keyPath, tls,
+`{mode:'packaged', releaseRoot, workspaceRoot, host, port, httpPort, http=false, certPath, keyPath, tls,
 signal, onEvent}` and serves the complete selected release files.
 External source mode accepts both the installed-package route layout and the
 existing physical runtime layout. Installed-package mode serves the configured
@@ -4128,8 +4161,8 @@ The SDK request hook returns `308` for HTTP with a `Location` pointing to the
 actual HTTPS port while preserving the original request path and query. Both listeners
 use the selected host.
 
-Source servers default to HTTPS, including localhost; packaged browser previews
-require HTTPS. The existing `https` option is accepted; `https:false` and
+Source servers and packaged browser previews default to HTTPS, including
+localhost. The existing `https` option is accepted; `https:false` and
 `tls:false` alone do not disable HTTPS. HTTPS startup reads `.arcane/dev/server-cert.pem` and
 `.arcane/dev/server-key.pem` relative to `workspaceRoot` unless explicit
 `certPath` and `keyPath` are supplied together; relative paths resolve from the
@@ -4141,10 +4174,15 @@ handshake; browser trust and address matching are evaluated when a client
 connects. The CLI's `--public` selects the wildcard bind;
 the API's `host` option alone changes only the bind address.
 
-Explicit `http:true` selects one HTTP content listener in source mode and skips
+Explicit `http:true` selects one HTTP content listener in source or packaged mode and skips
 certificate loading. `port` selects that listener's port, including `0` for an
-available port. The same application, runtime and generated PWA routes are
-served. `http` must be boolean; `http:true` rejects packaged mode, `https:true`,
+available port. Source mode keeps the same application, runtime and generated PWA routes.
+Packaged mode serves the complete selected `releaseRoot`; pass the artifact's
+web-root directory, not its enclosing native package directory. Its declared
+application start path, query and fragment are preserved. A caller requiring a
+stable origin must reuse its selected host and port; a bind conflict rejects
+startup rather than silently choosing another port.
+`http` must be boolean; `http:true` rejects `https:true`,
 explicit certificate/key paths, a `tls` value other than `undefined`, `null` or
 `false`, and a nonzero `httpPort`. Browser secure-context and installation
 requirements remain browser-owned; see [explicit HTTP development](cli.md#explicit-http-development).
@@ -4154,10 +4192,10 @@ The promise settles after all selected listeners are ready and resolves to
 networkUrls, httpPort, httpOrigin, httpUrl, close, closed, lifecycle}`. `server` is the raw Node
 server for application content: `Http2SecureServer` for PEM-backed HTTPS,
 `https.Server` for explicit raw `tls` options, or `http.Server` for explicit
-HTTP source mode. HTTP/2 uses Node's compatibility request/response APIs;
+HTTP mode. HTTP/2 uses Node's compatibility request/response APIs;
 callers accessing the raw server must account for its native type.
 `protocol` describes the URL scheme: `'https:'` for either negotiated HTTPS
-protocol or `'http:'` with explicit HTTP source mode.
+protocol or `'http:'` with explicit HTTP mode.
 `url` and `cleanUrl` are the same application URL. Wildcard listeners use
 `localhost` in that local URL; `host` retains the actual bound address.
 `httpPort` is the actual HTTP listener port, `httpOrigin` is its HTTP origin,
@@ -5092,24 +5130,85 @@ import {registeredTestCount} from 'arcane-os';
 console.log(registeredTestCount());
 ```
 
+## createGitTextSnapshot()
+
+### Overview
+
+Reads complete application-selected UTF-8 text from one fetched revision using
+a dedicated bare Git cache. It does not create or alter a working checkout.
+
+### Signature, lifecycle, and result
+
+```text
+createGitTextSnapshot({cacheDirectory,remote,ref,selectPath,onEvent,run=runProcess}={})
+```
+
+Import from `arcane-os`. The application owns the cache location, remote, ref,
+path predicate and service factory. The returned `refresh({signal}={})` returns
+`{revision,files:[{path,content}]}` in Git tree order. Concurrent calls share work;
+unchanged fetched revisions reuse completed text retrieval. Caller cancellation
+ends only that wait. `close()`, `drain()` and `dispose()` stop acceptance and
+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.
+
+### Example
+
+```js
+import {createGitTextSnapshot} from 'arcane-os';
+
+const dispatches = createGitTextSnapshot({
+    cacheDirectory: applicationCacheDirectory,
+    remote: applicationRepository,
+    ref: applicationRef,
+    selectPath: function selectDispatch(filename) {
+        return filename.startsWith('dispatches/') && filename.endsWith('.md');
+    }
+});
+const snapshot = await dispatches.refresh({signal});
+await dispatches.close();
+```
+
 ## runProcess()
 
 ### Overview
 
-Runs one shell-free child command with complete stdout and stderr, ordered stream events, heartbeats, and process-tree cancellation.
+Runs one shell-free child command with complete stdout and stderr, ordered stream
+events, heartbeats, and explicitly selected process cancellation behavior.
 
 ### Signature, parameters, and result
 
 ```text
-async runProcess(command, args=[], { cwd, env, signal, onEvent, heartbeatMs=5000, terminationGraceMs=DEFAULT_TERMINATION_GRACE_MS, allowNonzero=false, input }={})
+async runProcess(command, args=[], { cwd, env, signal, onEvent, onOutput, captureOutput=true, emitOutputEvents=true, outputEncoding='utf8', heartbeatMs=5000, terminationGraceMs=DEFAULT_TERMINATION_GRACE_MS, allowNonzero=false, input, cancellationMode='terminate-tree' }={})
 ```
 
 Import it from `arcane-os`. `command` is executed directly with `shell:false`;
 `args` must be a fixed array of strings, so shell expansion, pipelines, and
 redirection never occur. `cwd` selects the child directory. `env` is shallowly
-merged over `process.env`. When supplied, `input` is written once and stdin is
-closed; otherwise stdin is closed immediately. On Microsoft NT, `npm` and `npx`
-are normalized to their Node CLI entrypoints.
+merged over `process.env`. In the default `cancellationMode:'terminate-tree'`,
+supplied `input` is written once and stdin is closed; otherwise stdin closes
+immediately. With `cancellationMode:'close-input'`, optional input is written
+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.
+
+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.
+`onOutput({stream,chunk})` receives complete ordered chunks and is awaited with
+backpressure for each stream. UTF-8 decoding retains split characters. The
+default capture and nonempty-line events remain unchanged; line events are not
+a substitute for lossless chunk delivery.
+
+`captureOutput` and `emitOutputEvents` accept booleans or per-stream selections,
+for example `{stdout:false}` while stderr retains its default. A stream with
+capture disabled returns `null` and requires an `onOutput` consumer.
+`outputEncoding` defaults to `'utf8'`; explicitly selecting `null`, globally or
+per stream such as `{stdout:null}`, delivers native `Buffer` chunks unchanged.
+A raw stream requires capture and line events explicitly disabled for that
+stream plus an `onOutput` owner. It is never decoded or sent as text implicitly.
+Complete failed chunks, original callback failures, process diagnostics and
+exit results remain available through the normal error record after drain.
 
 `onEvent` is awaited in order for `process.starting`, nonempty
 `process.stdout`/`process.stderr` lines, coalesced `process.heartbeat`, and the
@@ -5129,12 +5228,21 @@ text stream preserves its complete content. A missing executable rejects with
 and spawn/runtime failures use the normalized SDK error boundary, with the
 nonzero result retained in error details.
 
-Aborting `signal` emits cancellation-requested state, terminates the owned
-process tree, escalates to a forced tree termination after the grace interval,
-drains event delivery, and rejects with `ARCANE_CANCELLED` and exit code 130.
-An `onEvent` failure also stops the tree and rejects with that callback failure.
-Cancellation proves only that the local process tree was stopped; it cannot
-reverse external effects already performed by the command.
+Aborting `signal` emits cancellation-requested state. The default mode terminates
+the owned process tree and escalates after the grace interval. `close-input`
+instead closes only the child's stdin, with no forced termination or deadline;
+the selected child must own EOF shutdown. This lets a native host finish
+accepted service work before exiting. Both paths continue observing output and
+drain event delivery before rejection with `ARCANE_CANCELLED` and exit code 130.
+An abort after the child's close event does not cancel already completed work.
+
+An `onEvent` failure requests shutdown through the same selected mode. The
+close-input failure retains the child's complete result in `details` and
+additional failures in `errors`, with the original primary error as `cause`
+when wrapping is needed. A cancellation rejection can therefore contain a
+successful child exit code `0`; that is the child's drained result, distinct
+from the cancelled caller operation. Cancellation cannot reverse external
+effects already performed by the command.
 
 ### Availability and normalization
 
@@ -7110,17 +7218,24 @@ await transport.closed;
 
 Creates the SDK-owned native builder for one portable Core payload. The caller
 selects application service modules already present in the app release. The
-provider does not load Arcane OS source, choose a model, download a runtime,
-compile an executable or substitute for an unavailable platform host.
+provider does not load Arcane OS source, choose a model, compile an executable
+or substitute for an unavailable platform host. An explicit `native.localAI`
+selection prepares and bundles its selected official runtime distributions;
+without that selection, no local-AI runtime is downloaded.
 
 ### Signature and result
 
 ```text
-createPortableNativeProvider({services=[]}={})
+createPortableNativeProvider({services,packagedWeb=false,webKitDocumentLifecycle=false}={})
 ```
 
 Import it from `arcane-os/native/portable-provider`. Each service selection is
-`{module, options}`. The returned `arcane-native-builder/1` provider exposes
+`{module, options}`. Omitted `services` uses `appDescriptor.native.services`;
+an explicit array, including `[]`, overrides the descriptor selection.
+The Mac composition selects `packagedWeb:true` for the SDK-owned serving service
+and `webKitDocumentLifecycle:true` for the canonical client projection. Defaults
+retain the existing portable and Windows behavior.
+The returned `arcane-native-builder/1` provider exposes
 `describe()`, `doctor()`, `prepare()`, `build()`, `verify()` and `run()`.
 `describe()` and successful payload results report `executable:false`; `run()`
 reports `ARCANE_NATIVE_RUN_UNSUPPORTED`.
@@ -7156,8 +7271,10 @@ console.log(await provider.describe());
 
 ### Overview
 
-Package-owned portable provider with no preconfigured application services. It
-is the named binding for the same object exposed as this subpath's default.
+Package-owned provider with no preconfigured application services. Each native
+provider subpath exports its own singleton and exposes that same object as its
+default binding. The ordinary singleton uses the app descriptor's service
+selection.
 
 ### Value and import
 
@@ -7165,13 +7282,16 @@ is the named binding for the same object exposed as this subpath's default.
 const arcaneNativeBuilderProvider
 ```
 
-Import it from `arcane-os/native/portable-provider`.
+Import it from `arcane-os/native/portable-provider` for a non-executable payload,
+or `arcane-os/native/windows-provider` for the Windows x64 executable contract.
 
 ### Availability and normalization
 
-**Node; produces a portable payload rather than an executable host.** The
-singleton retains the complete `arcane-native-builder/1` portable-provider
-contract described by `createPortableNativeProvider()`.
+**Node for assembly.** The portable singleton retains the contract described by
+`createPortableNativeProvider()`. The Windows singleton retains
+`createWindowsNativeProvider()` and needs Windows x64/WebView2 for execution.
+The two providers are distinct objects; named/default identity holds within
+each selected subpath.
 
 ### Example
 
@@ -7195,12 +7315,14 @@ Default package binding for the same object exposed as
 default as arcaneNativeBuilderProvider
 ```
 
-Import it from `arcane-os/native/portable-provider`.
+Import it from `arcane-os/native/portable-provider` or
+`arcane-os/native/windows-provider`, selecting that subpath's provider.
 
 ### Availability and normalization
 
-**Node; produces a portable payload rather than an executable host.** The
-default and named bindings have exact object identity and the same lifecycle.
+**Node for assembly; execution depends on the selected provider.** Within each
+subpath the default and named bindings have exact object identity and the same
+lifecycle; portable remains a non-executable payload.
 
 ### Example
 
@@ -7212,6 +7334,434 @@ import portableProvider, {
 console.log(portableProvider === arcaneNativeBuilderProvider); // true
 ```
 
+## createWindowsNativeProvider()
+
+### Overview
+
+Creates the SDK-owned Windows x64 provider. It assembles the selected app's
+complete portable payload with the precompiled WebView2 launcher and Node SEA
+Core from the numeric release matching the installed SDK version.
+
+### Signature and result
+
+```text
+createWindowsNativeProvider({services,hostDirectory}={})
+```
+
+Import it from `arcane-os/native/windows-provider`. `services` has the same
+descriptor/explicit-array semantics as the portable provider. An optional
+`hostDirectory` selects an already-built complete host tree; otherwise `build()`
+downloads and extracts the matching `arcane-native-windows-x64.tar.gz` beneath
+the selected output root. There is no compiler or OS checkout requirement for
+application builds. The build machine needs its normal Node/npm toolchain and
+`tar`; execution needs Windows x64, .NET Framework 4.6.2 or later and WebView2.
+
+The returned `arcane-native-builder/1` provider exposes `describe`, `doctor`,
+`prepare`, `build`, `verify` and `run`. Build returns `{app,target,manifest}`
+with the actual directory at `target.rootDir`. Verification reads the artifact;
+it does not launch the window. Run launches `Arcane.exe` and observes complete
+diagnostics and exit. Cancellation closes input and waits for host-owned drain,
+including accepted service work, without a forced termination deadline. Missing
+prerequisites, download/extraction failures and host failures remain observable
+through the operation's error/event boundary.
+
+### Example
+
+```javascript
+import {createWindowsNativeProvider} from 'arcane-os/native/windows-provider';
+
+const nativeBuilder = createWindowsNativeProvider({
+    services: [{module: 'native/moon-ledger.mjs', options: {ledgerName: 'Cheese debts'}}]
+});
+```
+
+Pass `nativeBuilder` to the existing native build-plan contract. For the ordinary
+CLI route and the complete artifact/launch contract, see
+[Windows executable packaging](core-native-packaging.md#windows-executable).
+
+## createMacOSNativeProvider()
+
+```text
+createMacOSNativeProvider({services,hostDirectory}={})
+```
+
+Import from `arcane-os/native/macos-provider`. The named
+`arcaneNativeBuilderProvider` and default export are the same provider with
+descriptor-owned services and the exact SDK release's selected host asset.
+The six-method `arcane-native-builder/1` contract supports `macos-arm64` and
+`macos-x64`, platform `macos`, format `app`. A selected `hostDirectory` allows
+same-project collaboration on host output; otherwise assembly downloads the
+matching numeric SDK release's `arcane-native-macos-<architecture>.tar.gz`.
+Neither an available source implementation nor `doctor()` proves that the
+asset is published or its Mac runtime has been executed.
+
+Build preserves the complete portable payload inside the bundle's Resources
+directory (`target.rootDir`) and returns its `.app` location as `bundleRoot`.
+The bundle supplies the SDK launcher and selected Node runtime. `verify()`
+reads assembled files; `run()` directly launches the bundled executable only on
+the matching Darwin architecture, observes diagnostics and waits for graceful
+Core/listener drain on cancellation. See the complete
+[macOS composition and prerequisite contract](core-native-packaging.md#macos-application-composition).
+
+## createPackagedWebService()
+
+```text
+createPackagedWebService({artifactRoot}, context={})
+```
+
+Import from `arcane-os/core/packaged-web`. Returns the Core service
+`{name:'packaged-web', start, drain}`. Start reads the native manifest, serves
+its complete web root with the existing explicit HTTP packaged server on
+`127.0.0.1`, and emits `core.web.ready` with `{origin,url,port}` only after the
+actual listener is ready and its first selected port is saved. The complete
+manifest start URL is resolved against that origin.
+
+State uses `context.stateRoot` or the native launcher's separate
+`--arcane-host-state-root` argument. The saved `packaged-web-origin.json` keeps
+the same port on subsequent launches; unreadable state or port conflicts remain
+errors, with no silent new origin. Startup rejection belongs to the Core
+`core.service.state` event; an unexpected post-start close/failure emits
+`core.web.failed` with the complete serialized error. Drain owns listener close
+and lifecycle completion. No application launch payload is rewritten, no model
+is loaded, and the ordinary server's HTTPS default is unchanged.
+
+## createPreferencesService()
+
+### Overview
+
+Supplies the five existing `Arcane.preferences` methods using an application-selected
+JSON file. Construction performs no filesystem work. Preference names, defaults,
+schemas and writable location remain application-owned.
+
+### Signature and result
+
+```text
+createPreferencesService({file}={})
+```
+
+Import from `arcane-os/core/preferences`. The returned Core service exposes
+`preferences.list/get/set/setMany/delete`, `drain()` and `dispose()`. Writes use
+`lifetime:'service'`, preserve complete JSON values and existing document metadata,
+and acknowledge after the new content is flushed and the selected file replaced.
+Operations selecting the same resolved filename share an ordered in-process queue.
+Unreadable or malformed files report their errors without being replaced; a missing
+file starts with empty entries. Unrepresentable JSON values fail before replacement.
+
+```javascript
+import {createPreferencesService} from 'arcane-os/core/preferences';
+
+const preferences = createPreferencesService({file: selectedPreferenceFile});
+```
+
+Register the service with the existing Core owner. Its drain/dispose stops new
+acceptance, waits for accepted work and exposes failures; subsequent calls reject
+with `CORE_CLOSING`. See [method results, storage and service composition](core-preferences.md).
+
+## createPreferencesService default export
+
+The default export from `arcane-os/core/preferences` is the same
+`createPreferencesService` factory, with identical arguments, method results
+and lifecycle:
+
+```javascript
+import createPreferencesService from 'arcane-os/core/preferences';
+```
+
+## createDiarization()
+
+### Overview
+
+Retains one caller-selected Nemotron model in its first-party native helper and
+accepts independent mono-audio streams. Results contain generic timed speaker
+labels; they do not identify people or perform speech recognition.
+
+### Signature and result
+
+```text
+createDiarization({executable,modelPath,runtime,onEvent}={})
+```
+
+Import from `arcane-os/diarization`. Supply absolute helper/model paths and the
+selected runtime's library locations. The returned owner starts the helper and
+exposes `ready`, `completion`, `current()`, replaying `subscribe()`,
+`openStream()`, `diarize()` and `close()`. Readiness resolves only after model
+loading. Each stream owns `push`, `finish`, `cancel`, `completion` and `current`;
+pushes preserve mono float32 input, use backpressure and return the latest timed
+segment snapshot. Caller callbacks may receive every probability frame.
+
+```javascript
+import {createDiarization} from 'arcane-os/diarization';
+
+const speakers = createDiarization({executable, modelPath, runtime});
+const result = await speakers.diarize({audio: monoSamples, sampleRate: 16000});
+await speakers.close();
+```
+
+Load, callback, process and cleanup failures remain observable. Cancellation
+suppresses later results for its stream and closes it after accepted native
+commands; the C ABI supplies no immediate interrupt. Close drains owned work
+and observes helper exit. See [complete audio, callback and cancellation contracts](diarization.md).
+
+## buildDiarizationHelper()
+
+```text
+async buildDiarizationHelper({runtime,outputRoot,signal,onEvent}={})
+```
+
+Import from `arcane-os/diarization/build`. Builds the first-party helper for the
+current host using installed CMake/C++17 tools and the selected runtime's
+`cmakeDirectory`. Returns `{platform,architecture,root,executable,diagnostics}`
+after configure, compile and install, retaining complete command diagnostics.
+Missing inputs or actual tool failures reject through the shared process owner;
+no compiler, model or runtime is downloaded by this function.
+
+```javascript
+import {buildDiarizationHelper} from 'arcane-os/diarization/build';
+
+const helper = await buildDiarizationHelper({runtime, outputRoot: helperDirectory});
+```
+
+See [runtime preparation, helper placement and platform support](diarization.md#runtime-and-helper).
+
+## createDiarizationService()
+
+```text
+createDiarizationService(options={},launch={})
+```
+
+Import from `arcane-os/core/diarization`. This synchronous `native.services`
+factory accepts `{executable,modelPath,runtime,onEvent}` and the native launch
+context. Relative executable/model paths use `workspaceRoot`, then `appRoot`,
+then the current directory. It supplies `diarization.status`, `diarization.load`,
+`diarization.open`, `diarization.push`, `diarization.finish`, `diarization.cancel`
+and `diarization.recording`, state/update/probability events and drain/dispose hooks.
+The first actual operation loads the model, independently of Core startup.
+
+```javascript
+import {createDiarizationService} from 'arcane-os/core/diarization';
+
+const service = createDiarizationService({executable, modelPath, runtime}, launch);
+```
+
+Session audio has service lifetime and explicit cancellation; a recording's
+request cancellation closes only that recording. Complete float32 samples use
+the documented Core transport framing. See [inputs, results, events and lifetime](diarization.md#core-service).
+
+## createDiarizationService default export
+
+The default binding from `arcane-os/core/diarization` is exactly the named
+`createDiarizationService` factory, with the same selection and service lifecycle:
+
+```javascript
+import createDiarizationService from 'arcane-os/core/diarization';
+```
+
+## readCoreLaunchContext()
+
+### Overview
+
+Reads only the complete JSON object explicitly selected by
+`--arcane-launch-config <path>`; it does not search for application configuration.
+
+### Signature and result
+
+```text
+async readCoreLaunchContext({argv=process.argv.slice(2)}={})
+```
+
+Import it from `arcane-os/core/host`. The promise resolves to `{}` when the flag
+is absent, or the complete parsed object when present. A missing flag value,
+unreadable file, malformed JSON or non-object value rejects. Relative paths use
+the process working directory. The reader does not rewrite content or mutate
+the environment.
+
+```javascript
+import {readCoreLaunchContext} from 'arcane-os/core/host';
+
+const launchContext = await readCoreLaunchContext();
+```
+
+The generated entry supplies artifact-derived `appRoot`, then applies the whole
+explicit context and passes the same object as every service factory's second
+argument. Authored service options remain the first argument. Workspace/state
+locations and additional fields belong to the launcher/application. See
+[launch-time locations](core-native-packaging.md#launch-time-locations).
+
+## createCoreLocalAIProvider()
+
+### Overview
+
+Creates a browser-safe llama.cpp LLM provider through an existing Core client.
+Construction selects no model and installs no runtime or transport.
+
+### Signature and result
+
+```text
+createCoreLocalAIProvider({client=getInstalledCoreClient(),id='llama.cpp'}={})
+```
+
+Import it from `arcane-os/ai/core-local`. The provider implements
+`arcane-ai-provider/2` and exposes `catalog`, `status`, `inspect`, `load`,
+`request`, `unload` and `dispose`. Register it with the shared AI provider runtime,
+select the exact provider/model with `localOnly:true`, and load that selection.
+Requests wait for the requested model's actual readiness, preserve complete
+payloads and parsed streaming chunks, and cancel on observed readiness loss.
+Missing Core reports unavailability; it does not choose a browser or cloud route.
+Dispose/unregister at the caller's owning lifecycle boundary.
+
+```javascript
+import {createCoreLocalAIProvider} from 'arcane-os/ai/core-local';
+import {getAIProviderRuntime} from 'arcane-os/ai-provider-runtime';
+
+const provider = createCoreLocalAIProvider();
+const unregister = getAIProviderRuntime().register(provider);
+```
+
+See [the browser provider guide](local-ai.md#browser-llamacpp-provider) for model
+selection, streaming, cancellation and primary-model reload behavior.
+
+## createLocalAIService()
+
+### Overview
+
+Composes application-selected llama.cpp, Ollama and ONNX engines as a native Core
+service. Runtime installation, process availability and model readiness remain
+separate states; prompts, models and application policy remain caller-owned.
+
+### Signature and result
+
+```text
+createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent}={})
+```
+
+Import it from `arcane-os/core/local-ai`. `configuration` is the authored local-AI
+record; `appRoot` resolves its relative model paths and `runtimes` supplies
+resolved installed runtime records. It returns a Core service definition with
+`current()` and independent selected-engine startup. Compose it through the
+existing Core lifecycle. Shutdown cancels owned work and joins owned processes;
+an already running external service remains under its external owner.
+
+The service provides `localai.status`, explicit `localai.services.recover`,
+`llama.status/models/load/unload/chat`, `onnx.status/load/run/unload`, and the documented native Ollama methods.
+`localai.state` reports runtime/model changes. `llama.chunk` and `ollama.chunk`
+carry original parsed chunks with `streamId`; terminal responses remain complete.
+There is no background health polling or implicit model choice.
+
+```javascript
+import {createLocalAIService} from 'arcane-os/core/local-ai';
+
+const service = createLocalAIService(application.native.localAI, {appRoot, runtimes});
+```
+
+See [Core service configuration, results and failures](local-ai.md#core-service)
+and [native bundling](local-ai.md#native-bundling).
+
+## createONNXRuntime()
+
+`createONNXRuntime({modulePath,signal?,onEvent?})` from `arcane-os/local-ai/onnx`
+owns retained native ONNX sessions in workers. It exposes `load({id,model,
+sessionOptions?,signal?})`, `run({id,feeds,fetches?,runOptions?,signal?})`,
+`unload({id,signal?})`, `current()`, replaying `subscribe(listener)` and `close()`.
+The direct model path is absolute. Complete typed tensor records use
+`{type,dims,data}`; callers own the actual graph's inputs and preprocessing.
+
+Models load only on explicit requests. A live session ID requires unloading
+before replacement. Independent sessions run concurrently; same-session work
+waits at that session's loading/execution boundary. Queued cancellation removes
+that request; active cancellation retires the affected worker and suppresses
+its response. Native code can delay termination; cleanup waits for actual exit.
+See [complete signatures, readiness, cancellation and usage](local-ai.md#native-onnx-sessions).
+
+## createCoreONNXRuntime()
+
+`createCoreONNXRuntime({client=getInstalledCoreClient()}={})` from
+`arcane-os/ai/core-onnx` accesses an available Core ONNX service. Its `load`,
+`run`, and `unload` mirror the native session selection and accept `signal` and
+`timeoutMs` (default `0`). Relative model paths resolve at Core's `appRoot`.
+The accessor owns complete tensor transport encoding/decoding, `inspect()`,
+`current()`, replaying `subscribe(listener)` and `close()`. Closing cancels this
+accessor's requests and subscriptions; unloading shared models is explicit.
+Construction installs no runtime and opens no transport. Existing browser
+ONNX/Wllama remain independent. See [Core and browser usage](local-ai.md#onnx-through-core-and-the-browser).
+
+## createLocalAIService default export
+
+The default binding from `arcane-os/core/local-ai` is exactly the named
+`createLocalAIService` factory above, with the same arguments, return value and
+lifecycle:
+
+```javascript
+import createLocalAIService from 'arcane-os/core/local-ai';
+```
+
+## ensureLocalAIRuntimes()
+
+### Overview
+
+Reuses matching managed runtimes or installs complete selected official
+llama.cpp/Ollama/ONNX distributions or NeMo libraries in an explicitly supplied directory.
+
+### Signature and result
+
+```text
+async ensureLocalAIRuntimes({runtimes=[],directory,platform=process.platform,architecture=process.arch,signal,onEvent}={})
+```
+
+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, or NeMo library directories. 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
+[platform and archive requirements](local-ai.md#native-bundling).
+
+```javascript
+import {ensureLocalAIRuntimes} from 'arcane-os/local-ai';
+
+// Call explicitly when the app needs its selected official runtime installed.
+async function prepareMoonCheeseRuntime(){
+    return ensureLocalAIRuntimes({
+        runtimes: ['llama.cpp'], directory: '.arcane/local-ai/runtimes'
+    });
+}
+```
+
+## bundleLocalAIRuntimes()
+
+### Overview
+
+Prepares selected runtimes through the same installer and copies their complete
+trees into one fresh native staging destination.
+
+### Signature and result
+
+```text
+async bundleLocalAIRuntimes({runtimes=[],directory,outputRoot,platform=process.platform,architecture=process.arch,signal,onEvent}={})
+```
+
+Import it from `arcane-os/local-ai`. `directory` owns the reusable installation;
+`outputRoot` owns the fresh artifact. The promise resolves to `{runtimes,files}`:
+runtime paths are artifact-relative under `runtime/local-ai/<id>`, and `files`
+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.
+
+```javascript
+import {bundleLocalAIRuntimes} from 'arcane-os/local-ai';
+
+// Call explicitly with a fresh output directory for this native assembly.
+async function bundleMoonCheeseRuntime(outputRoot){
+    return bundleLocalAIRuntimes({
+        runtimes: ['llama.cpp'], directory: '.arcane/local-ai/runtimes', outputRoot
+    });
+}
+```
+
+The ordinary provider invokes this owner only for an explicit native local-AI
+selection. See [selected local-AI runtimes](core-native-packaging.md#selected-local-ai-runtimes).
+
 ## startCoreHost()
 
 ### Overview