arcane-os 0.57.0 → 0.58.0

package/docs/reference/availability-and-normalization.md

@@ -58,12 +58,12 @@ false when a probe throws; SDK branching continues through its owning error path
 policy, package-owned model policy, platform support, and dependency readiness
 are independent checks.
 
-The current executable host/target matrix covers Microsoft NT, Linux, and
-Android where listed. This SDK exposes no macOS executable target, native
-bridge, artifact, or run contract; WebKitGTK availability must not be
-generalized to macOS. The reusable Node Core runtime, framed stdio transport,
-host composition, and portable payload can be used by a separately composed
-macOS host, but they do not supply that native platform host or bridge.
+Windows x64 has an SDK-owned precompiled WebView2/SEA host; Linux and Android
+retain their explicit checkout providers where listed. The SDK also includes
+macOS Foundation process-adapter source, separately from an executable target,
+renderer bridge, artifact or run command. A composed macOS host may combine that
+source with the reusable Node Core runtime, stdio transport and portable payload.
+Source availability does not establish macOS compilation or execution.
 
 ## Capability-first matrix
 
@@ -89,6 +89,9 @@ macOS host, but they do not supply that native platform host or bridge.
 | Connect browser code to an existing Core transport | `arcane-os/core/client` and `arcane-os/core/contracts` | **Browser / native WebView** with an admitted transport; explicit development HTTP remains opt-in | The reusable client owns `arcane/1` correlation, readiness, cancellation, events, facades, and complete native error fidelity. It supplies no service, policy, or host process. |
 | Compose native Core services and framed stdio hosting | `arcane-os/core/runtime`, `arcane-os/core/stdio`, and `arcane-os/core/host` | **Node** on Windows, Linux, or macOS; the composing native host supplies its process and bridge | The SDK owns reusable dispatch, per-service lifecycle, request/service work ownership, cooperative cancellation, drain, and stdio framing. Product identity, policy, privileges, models, storage, and services remain host-owned. |
 | Assemble a portable Core payload from the installed SDK | `arcane-os/native/portable-provider` | **Node**; portable platform selection is currently Windows or Linux, while separately composed hosts may use the payload | The provider copies the selected app, dependencies, installed SDK runtime, Core client/runtime, and explicit service composition into a non-executable directory. It uses no `arcaneRoot` by default and does not prove host behavior or supply a platform bridge. |
+| Assemble and run a Windows executable | [`arcane-os/native/windows-provider`](core-native-packaging.md#windows-executable) | **Node** for assembly; Windows x64, .NET Framework 4.6.2+ and WebView2 for execution | Uses the installed SDK version's precompiled release asset and explicit app services. Complete diagnostics and accepted service work drain on run cancellation; no OS checkout or application-side native compiler is required. |
+| Use application-selected llama.cpp/Ollama through Core | [`arcane-os/core/local-ai`, `arcane-os/ai/core-local`](local-ai.md) | **Node** native service; **Browser / native WebView** provider through an explicit Core connection | Independent runtime/model lifecycle, complete streaming and cancellation. Official runtime preparation follows explicit app requirements; model selection and business policy stay app-owned. |
+| Run native ONNX tensors | [`arcane-os/local-ai/onnx`, `arcane-os/ai/core-onnx`](local-ai.md#native-onnx-sessions) | **Node** Windows/Linux/macOS x64/arm64; **Browser / native WebView** through available Core | Explicit graph loading, retained workers and complete tensor outputs. Android requires host adaptation. Native calls can delay worker termination; cleanup observes actual exit. |
 | Use local AI without coupling app code to Ollama HTTP | `Arcane.localAI`, `Arcane.ai`, or `/arcane/modules/Ollama.js` | Primarily **Native**; Android exposes a narrower admitted inference projection | Admission, errors, and managed-operation events are normalized. Direct Ollama response envelopes remain **Provider-native**. |
 | Use TWiN Cloud from the renderer profile | `/arcane/modules/AI.js` | **Cloud** from an allowed browser/native renderer | High-level chat behavior is normalized by the module. The TWiN access key authenticates remote LLM chat; raw provider diagnostics remain provider-specific. No automatic cloud fallback is inferred from local failure. |
 | Send one TWiN Cloud request with an explicit key and model | `fetchRequest` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch and a remote HTTPS provider | Keeps complete messages and returns the full parsed provider JSON. Rejected Fetch and HTTP 529 share three retries after 3000 ms; HTTP 429 overload retains unlimited three-second retries. Optional `onRetry` reports waiting/requesting phases without blocking recovery. Shared structured-output mapping and cancellation match browser TWiN transport. No browser profile, AI/user singleton, DBOPFS, or retained request history is created. |

package/docs/reference/cli.md

@@ -49,7 +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). |
+| `--local-ai` | comma-separated runtime IDs | `dev` only; adds `llama.cpp`, `ollama` and/or `onnx` 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. |
@@ -367,7 +367,7 @@ 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>] [--local-ai llama.cpp,ollama]
+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,onnx]
 ```
 
 `--local-ai` saves the selected requirements in `native.localAI`, or in
@@ -406,7 +406,7 @@ device, since `localhost` refers to that device and `0.0.0.0` is a bind address.
 Network URLs come from one interface snapshot at startup and do not establish
 remote reachability through the machine's firewall or network.
 
-HTTPS is the default for development and required for packaged browser previews.
+HTTPS is the default for development and packaged browser previews.
 The published `node-http-server` 10.0.0 integration negotiates HTTP/2 or HTTP/1.1
 on the same HTTPS port using the configured PEM pair. Source routes, generated
 PWA resources, and conditional responses use the same serving pipeline.
@@ -448,6 +448,10 @@ close the owned HTTP listener and settle the same lifecycle.
 `--key`, or `--http-port` is a usage error. Omitting it preserves HTTPS;
 certificate errors never select HTTP automatically.
 
+The public `startDevServer()` API also accepts `http:true` in packaged mode;
+this does not add a CLI preview command or change `dev` into packaged serving.
+See [the API contract](sdk-api.md#startdevserver).
+
 A LAN HTTP origin does not receive the browser's localhost secure-context
 exception. For Chrome development, Chromium documents
 `chrome://flags/#unsafely-treat-insecure-origin-as-secure` with the exact HTTP
@@ -700,10 +704,10 @@ npm exec -- arcane verify-bundle dist/hello-world-1.0.0.arcane-app.tar.gz
 
 ### Overview
 
-Loads the SDK package provider for portable by default, or the fixed provider
-from an explicitly selected Arcane OS checkout. It diagnoses the selected
-provider prerequisites without building an app. Executable targets still
-require `--arcane-root` and their platform toolchains.
+Loads the SDK package provider for `portable` or `windows-x64` by default, or
+the fixed provider from an explicitly selected Arcane OS checkout. It diagnoses
+selected prerequisites without building an app. Windows uses the matching
+precompiled SDK host; Linux and Android retain their checkout/toolchain routes.
 
 ```text
 arcane native-doctor --target <native-target> [--arcane-root <directory>]
@@ -719,8 +723,7 @@ is unavailable; it never returns a browser package as a substitute.
 
 ```bash
 npm exec -- arcane native-doctor \
-  --target windows-x64 \
-  --arcane-root "../Arcane OS"
+  --target windows-x64
 ```
 
 ## `arcane native-prepare`
@@ -762,6 +765,9 @@ The output remains target-specific inside the common plan contract.
 Portable uses the SDK package without an OS checkout, copies complete selected
 app/dependency payloads and generates the Core entry/classic client source.
 It adds no executable platform host or automatically discovered app services.
+Windows x64 uses the SDK package provider and its matching precompiled release
+asset without an OS checkout or application-side native compilation. See
+[Windows requirements and artifact layout](core-native-packaging.md#windows-executable).
 An explicit `--arcane-root` continues to select the checkout provider.
 Integrated builds retain an output root outside the OS checkout; only an
 explicit checkout provider must share the workspace root.
@@ -775,7 +781,6 @@ rather than returning a fictional native artifact plan.
 ```bash
 npm exec -- arcane build \
   --target windows-x64 \
-  --arcane-root "../Arcane OS" \
   --output-root "../arcane-native-output"
 ```
 
@@ -816,6 +821,13 @@ Android providers expose supported paired native run paths. Portable output is
 a directory and intentionally cannot run. Android run requires one
 connected physical/native ARM64 device for the current target.
 
+`windows-x64` uses the package provider by default, launches `Arcane.exe`, and
+streams complete diagnostics. Its cancellation closes input and waits for the
+window/Core's accepted work to drain; it does not force-kill that host after a
+timer. WebView2 Runtime and .NET Framework 4.6.2 or later must be available on
+the Windows execution machine. Linux/Android retain their explicit provider
+requirements. Build/launch completion does not prove application domain behavior.
+
 ### Example
 
 ```bash

package/docs/reference/core-client.md

@@ -124,6 +124,86 @@ developer diagnostics, rather than ordinary
 product status surfaces. The optional `onError(error)` callback observes
 transport/event-owner failures outside individual request promises.
 
+## Optional WebKit document lifetime
+
+`webKitDocumentLifecycle:true` on `createCoreClient`, `installCoreClient` or
+`createCoreClassicSource` selects document lifetime handling for the native
+WebKit `arcane` handler with replies. It defaults to `false`; existing WebKit
+plain-JSON and alternate acknowledgement transports, WebView2, Android,
+development HTTP and supplied transports keep their existing behavior. The
+selected host must implement this contract and the existing `runtime.replay`
+control. Install the classic source at document start in the page's world.
+
+The client owns a fresh activation for the current JavaScript realm and each
+restoration from the browser's page cache. WithReply receives these transport
+records; the Core JSON string remains unchanged in its separate `json` field:
+
+| Record | Meaning |
+| --- | --- |
+| `{type:'activate', activation}` | Attach this activation before sending its Core frames. |
+| `{type:'frame', activation, json}` | Send the complete serialized Core request or control. |
+| `{type:'retire', activation, json}` | Retire this activation; `json` is the existing `requests.cancelAll` control. |
+
+Reply with `{accepted:true}` or `{accepted:false,error}` on the initiating
+WithReply promise. Frame and retirement acceptance follows the actual complete
+process write. Queue admission alone is insufficient. Activation acceptance
+follows the host's current-realm probe and any required prior-owner cancellation.
+Only this activation's outgoing frames wait for attachment; page rendering,
+facade installation and independent Core startup remain concurrent.
+An aborted, timed-out or otherwise cancelled request awaiting attachment is
+never submitted afterward; its existing cancellation control remains observable.
+
+The host calls `__arcaneWebKitDocumentCurrent(activation)` in the current main
+document's page world to probe a candidate. A token or native frame descriptor
+alone does not identify the active document. Serialize candidate probes and
+Core ingress ownership changes: finish each candidate's probe before processing
+the next announcement, and leave the current owner unchanged when a probe is
+false. Announcement arrival order cannot establish document order. A true
+probe establishes the realm at that execution instant; every later delivery
+still checks its target at execution time.
+
+Before accepting a replacement activation, write the existing
+`requests.cancelAll` control for the prior ingress owner. Do not wait for a
+retirement announcement that a destroyed document may never send. Write a
+retirement record's JSON only while that activation still owns ingress;
+reject a late retirement without cancelling the replacement's requests.
+Record request-ID-to-origin-activation correlation before submitting each
+request to Core. Responses retain that origin. Existing generic service events
+remain broadcasts to the current activation; no request association is added.
+Complete native diagnostics retain frames received while no document is active;
+restoration uses current-state replay rather than historical event delivery.
+
+Deliver through `__arcaneReceive(json, activation)` and
+`__arcaneTransportFailed(error, activation)`, passing payloads as native
+JavaScript call arguments. Both return `false` for a retired or different
+activation. Receive also returns `false` for an unrecognized frame or a
+response with no pending request; `true` means the client accepted delivery,
+which may still await its shared event owner. Failure returns `true` when it
+ends that active installation. Preserve actual evaluation failures through the
+native diagnostic owner; a `false` result is not a JavaScript exception.
+`client.acceptsNativeDelivery(activation)` exposes the same synchronous lifetime
+predicate. It accepts any activation while a client using an ordinary transport
+is live. Direct owner calls to `client.failTransport(error)` retain their
+existing terminal-failure semantics.
+
+Page hide synchronously retires the activation even with no pending requests.
+It clears completed ready state and rejects every pending renderer promise with
+the existing `ARCANE_REQUEST_ABORTED`/`AbortError`. This ends the page's wait;
+the runtime's cancellation skips service-lifetime work, so an accepted save
+continues and participates in graceful drain. Its eventual response stays with
+the retired activation and cannot settle a restored page's request. The client
+does not claim that cancellation rolled back persistence.
+
+Persisted page restoration creates a fresh activation and sends exactly one
+`runtime.replay` after native attachment. Initial attachment sends that replay
+only when `replayRuntimeState:true`. Application subscriptions survive page
+hide and restoration, including registrations awaiting the shared event owner
+and ready listeners awaiting their replay microtask. Queued deliveries from a
+retired activation are no longer applicable to those subscriptions. Replay
+supplies current Core/service state, not prior responses or request promises.
+Closing the client retires once, removes lifecycle listeners and restores its
+owned callbacks. It does not close the process or control application shutdown.
+
 ## Classic native-host injection
 
 ```js

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

@@ -6,7 +6,7 @@ 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
+current CLI's portable platform selections include Windows, Linux and macOS. A portable
 artifact is not a Windows executable, Linux package or Android application.
 
 `loadArcaneNativeProvider({target:'portable'})` selects the installed SDK provider
@@ -18,10 +18,14 @@ 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
+`createPortableNativeProvider({services,packagedWeb=false,webKitDocumentLifecycle=false})` 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.
+The Mac provider selects `packagedWeb:true` to compose the SDK's packaged-web
+Core service and `webKitDocumentLifecycle:true` for the canonical classic-client
+activation/replay contract. Both default to false, preserving ordinary portable
+and Windows composition.
 All implement `arcane-native-builder/1`:
 
 - `describe()` identifies the portable target and `executable:false`.
@@ -242,6 +246,13 @@ 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.
 
+Selected `onnx` bundles its complete managed `onnxruntime-node` dependency tree.
+Its `modulePath` resolves against the artifact root just as a server runtime's
+`executable` does. Library/module records need no executable. The generated Core
+service exposes retained worker sessions through `onnx.load/run/unload/status`;
+model files remain caller-selected application resources. See
+[native ONNX sessions](local-ai.md#native-onnx-sessions).
+
 ## Windows executable
 
 The ordinary application command is:
@@ -331,3 +342,100 @@ 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.
+
+## macOS process source
+
+`src/core/hosts/macos/ArcaneCoreProcess.h` and `.m` provide a Foundation-only
+adapter for macOS 11 or later, compiled with Objective-C ARC and blocks. A
+composing host explicitly supplies the executable URL, arguments, working
+directory and delegate; startup is asynchronous. Delegate callbacks deliver
+every raw stdout/stderr chunk and complete opaque framed JSON bodies, plus
+launch, error, exit and final completion observations. Each stream and accepted
+write retains its own order; UI dispatch belongs to the host. Callbacks must
+return normally and must not wait for another callback or completion.
+
+`sendJSONData:completion:error:` accepts an ordered write or reports a
+synchronous rejection. Write completion means the frame reached stdin, not that
+the RPC succeeded. `closeInput` rejects new sends, finishes accepted writes and
+closes stdin, then keeps observing output and child exit without a forced
+termination deadline. The delegate is retained through final completion.
+The AppKit `ArcaneHost` and launcher compose that source as described below.
+Compilation and execution on macOS remain separate evidence from the selected
+Windows output.
+
+## macOS application composition
+
+`arcane-os/native/macos-provider` exports
+`createMacOSNativeProvider({services,hostDirectory}={})`, its named
+`arcaneNativeBuilderProvider`, and the same provider as default. The six-method
+contract accepts `macos-arm64` or `macos-x64`, `platform:'macos'`, `format:'app'`
+and the existing unsigned local development selection. Ordinary CLI routing
+uses the SDK package, not an Arcane OS checkout:
+
+```sh
+npm exec -- arcane build --target macos-arm64
+npm exec -- arcane run --target macos-arm64
+```
+
+Select `macos-x64` for Intel. The descriptor must declare the selected target.
+Source implementation does not establish that an architecture's host artifact
+has been built, executed or published. Consumer assembly needs the exact numeric
+SDK release asset `arcane-native-macos-<architecture>.tar.gz`; unavailable assets
+produce their actual download error. SDK collaborators may select an existing
+`hostDirectory` explicitly. There is no fallback to source checkout, another
+version, another architecture or a browser-only artifact.
+
+The complete unchanged portable payload lives at
+`<app-id>.app/Contents/Resources/`. That directory remains `target.rootDir` and
+contains `arcane-native.json`, `app/`, dependency releases, installed SDK files,
+Core entry/client and `runtime/node`. The additive `bundleRoot` identifies the
+`.app` directory. `Contents/MacOS/Arcane` and `Contents/Info.plist` belong to the
+bundle rather than the web root; the Mac owner checks these separately from the
+Resources file inventory. Application identity supplies the stable bundle ID
+`org.arcane.<app-id>`. Executable permissions are preserved for the launcher and
+selected Node runtime.
+
+The launcher opens its window immediately and starts one Core child. The
+generated Core entry starts the `packaged-web` service alongside application
+services, without waiting for models. Only `core.web.ready`, emitted after the
+actual listener is ready and the initial port is saved, supplies the application
+URL to WebKit. It serves the complete `manifest.webRoot` at `/` and resolves the
+complete `manifest.start`, including query and fragment, against that origin.
+The classic client selects current-document activation and sticky state replay;
+navigation does not restart the Core service or replay retired requests.
+The host's main-thread readonly `isClosing` accessor exposes its existing close
+intent; an unsolicited Core exit is therefore reported separately from an
+ordinary user-requested drain, even when the process exits successfully.
+
+`createPackagedWebService({artifactRoot}, context={})` is available from
+`arcane-os/core/packaged-web`. It uses the existing
+`startDevServer({mode:'packaged',http:true,host:'127.0.0.1',port,releaseRoot})`
+owner and published `node-http-server`, not a second HTTP implementation.
+`context.stateRoot` takes precedence over the launcher's separate
+`--arcane-host-state-root` argument. The launcher defaults to
+`~/Library/Application Support/Arcane/<app-id>`; an explicitly supplied launch
+file remains unchanged and is forwarded to Core. The first successful listener
+stores its selected port in `packaged-web-origin.json`. Later launches reuse it;
+a port conflict or unreadable saved record is reported without changing origins
+or discarding stored state.
+
+The app's persistent default `WKWebsiteDataStore` uses its bundle identity.
+`stateRoot` selects Core state and diagnostics, not a custom WebKit profile
+directory. Browser API availability, OPFS and secure-context behavior remain
+WebKit-owned and require actual Mac verification; the SDK bypasses no browser
+policy. Startup failures use `core.service.state` for `name:'packaged-web'`;
+unexpected listener closure or failure uses `core.web.failed` with the complete
+serialized error. Native alerts show a concise outcome, with full diagnostics
+outside the conversation. Core drains accepted work and the listener before
+the native close completes. The optional runner stdin-EOF signal uses that same
+path; ordinary double-click startup does not wait on stdin.
+
+`tools/build-core-macos-host.mjs` is SDK host-release tooling, not an application
+compiler requirement. It accepts an explicit Darwin Node executable and its
+license, compiler path, `arm64` or `x64`, and output directory. It uses Objective-C
+ARC/blocks and Apple's Foundation, AppKit and WebKit frameworks. The host source
+targets macOS 11; the selected Node runtime may require a newer macOS version.
+Its actual runtime/platform/architecture and the SDK Node engine requirement
+must agree. Compiler/runtime execution and redistribution belong to the
+separately authorized selected host output. This source increment runs none of
+them and claims no Mac build or execution result.

package/docs/reference/core-preferences.md

@@ -0,0 +1,49 @@
+# Core preferences service
+
+`createPreferencesService({file})` from `arcane-os/core/preferences` supplies the
+existing `Arcane.preferences` RPC methods to a native Core host. The default
+export is the same factory. Construction performs no filesystem work. The
+application selects its writable file and owns preference names, defaults and
+schemas; this service does not invent them or alter operating-system settings.
+
+```js
+import path from 'node:path';
+import {createPreferencesService} from 'arcane-os/core/preferences';
+
+export default function createMoonPreferences(options, context) {
+    return createPreferencesService({
+        file: path.join(context.stateRoot, 'moon-preferences.json')
+    });
+}
+```
+
+Select this application-owned factory through `native.services`, and include it
+in `package.nativeResources`. Supply the application's selected `stateRoot`
+through the explicit launch configuration. See [native packaging](core-native-packaging.md#launch-time-locations).
+
+| Method | Input | Result |
+| --- | --- | --- |
+| `preferences.list` | `{}` | `{keys}` in sorted order |
+| `preferences.get` | `{key}` | `{key,found,value}`; missing value is `null` |
+| `preferences.set` | `{key,value}` | `{key,value}` after file replacement |
+| `preferences.setMany` | `{entries}` | `{keys,count}` after file replacement |
+| `preferences.delete` | `{key}` | `{key,deleted}` |
+
+Storage remains `{schemaVersion:1,entries}`. Exact keys, complete JSON values and
+additional existing document metadata are retained. A missing file starts with
+empty entries; reading it does not create a file. Unreadable or malformed files
+report their real errors and are not replaced with an empty record. Values that
+JSON cannot represent completely fail before replacement. There is no migration,
+truncation, namespace rewrite, default injection or frozen result.
+
+Operations selecting the same resolved filename share one ordered queue within
+the Core process. This is not a cross-process file lock. Writes flush their new
+content and replace the selected file before acknowledgment. Filesystem failures
+remain observable, including cleanup errors; this is not a claim of survival
+across every hardware or operating-system failure.
+
+`set`, `setMany` and `delete` use `lifetime:'service'`: renderer cancellation does
+not discard accepted writes. `drain()` and `dispose()` stop acceptance and wait
+for accepted operations; later calls reject with `CORE_CLOSING`. Read operations
+observe their request cancellation. Use the existing Core host shutdown owner
+so saved preferences finish before the native process exits.

package/docs/reference/diarization.md

@@ -0,0 +1,206 @@
+# Nemotron 3 speaker diarization
+
+The native diarization API uses the NVIDIA `Nemotron-3-Diarization.q8_0.gguf`
+model through the official NeMo-Speech.cpp 0.2.0 CPU libraries. It returns
+generic, one-based speaker labels and timed segments, independently of speech
+recognition. A speaker label does not identify a person. The model supports
+eight speaker channels; the helper reports the loaded model's actual channel
+count and output cadence.
+
+## Runtime and helper
+
+Select the `nemo-speech` runtime through the existing local-AI installer. Keep
+its complete upstream `bin`/`lib`/`include` and CMake layout. Model storage is
+separate and caller-selected. Obtain the selected GGUF from the
+[official NVIDIA model repository](https://huggingface.co/nvidia/Nemotron-3-Diarization).
+This API does not select an ASR model, install Python, or enable a GPU backend.
+
+`buildDiarizationHelper({runtime,outputRoot,signal,onEvent})` builds the
+first-party helper for the current host with installed CMake and its C++17
+toolchain. `runtime.cmakeDirectory` is the installer-discovered CMake package
+directory, passed as `NeMoSpeech_DIR` without assuming an archive root. The result
+is `{platform,architecture,root,executable,diagnostics}`; diagnostics retain the
+complete configure/compile/install process results. The installed helper is under
+`outputRoot/bin`; its build directory is under `outputRoot/build`. The helper
+links the upstream `NeMoSpeech::Diarization` component and is separate from
+the downloaded runtime. No compiler is downloaded by this function.
+
+Official 0.2.0 CPU archives cover Windows x64, Linux x64/ARM64, and macOS
+x64/ARM64. Linux requires glibc 2.31 or later. Android needs a host-adapted
+runtime/helper; this release's official inventory does not supply an Android
+or Windows ARM64 archive. Source portability is distinct from execution on an
+actual platform.
+
+The public Node flow uses the existing installer and one first-party helper:
+
+```javascript
+import {ensureLocalAIRuntimes} from 'arcane-os/local-ai';
+import {buildDiarizationHelper} from 'arcane-os/diarization/build';
+import {createDiarization} from 'arcane-os/diarization';
+
+const [runtime] = await ensureLocalAIRuntimes({
+    runtimes: [{id: 'nemo-speech', version: '0.2.0'}],
+    directory: selectedRuntimeDirectory
+});
+const helper = await buildDiarizationHelper({runtime, outputRoot: selectedHelperDirectory});
+```
+
+Keep the selected directories and model path under their application/host
+owner. A native artifact can place the first-party executable under
+`runtime/diarization/bin`, independently of the complete upstream library tree
+under `runtime/local-ai/nemo-speech`.
+
+## Retained model and audio streams
+
+`createDiarization({executable,modelPath,runtime,onEvent})` returns immediately
+and starts its owned helper. Supply absolute helper/model paths and the
+installer's absolute `runtime.binaryDirectory`/`runtime.libraryDirectory` paths. They configure the
+child's platform library search path; the parent environment is unchanged.
+
+The returned model has `ready`, `completion`, `current()`,
+`subscribe(listener,{emitCurrent=true,signal})`, `openStream(options)`,
+`diarize(options)`, and `close()`. `ready` resolves when the actual model is
+loaded; a failed load rejects. `completion` covers the complete helper lifetime.
+The sticky state is `loading`, `ready`, `closing`, `closed`, or `error`.
+Subscribe to this owner instead of polling or delaying unrelated UI startup.
+
+```javascript
+const diarization = createDiarization({
+    executable: helper.executable,
+    modelPath: selectedModelPath,
+    runtime
+});
+
+const stream = await diarization.openStream({
+    sampleRate: 16000,
+    onUpdate: function showSpeakers(result) {
+        renderSpeakerTimeline(result.segments);
+    }
+});
+
+await stream.push(firstMonoSamples);
+await stream.push(nextMonoSamples);
+const final = await stream.finish();
+await diarization.close();
+```
+
+`push(audio)` accepts mono `Float32Array` samples and preserves their float32
+representation. The caller owns decoding an encoded recording and choosing
+its mono channel; this API does not alter the source recording, mix channels,
+normalize amplitudes, or capture a microphone. Keep the supplied array stable
+until `push` settles. Each stream accepts one fixed sample rate: 8000–96000 Hz,
+or `0` for model-rate samples. The default is 16000 Hz. Upstream owns necessary
+resampling. Await each push for backpressure; independent streams share the
+retained model without sharing speaker/session state. Upstream serializes
+model compute internally.
+
+`openStream({sampleRate,onUpdate,onProbabilities,signal})` returns a stream with
+`push`, `finish`, `cancel`, `completion`, and `current()`. A push resolves to
+its latest segment snapshot, or `null` until native frames are available. `finish()`
+flushes all remaining audio and resampler output, returns the complete final
+result, and releases the native stream. It is idempotent. `current()` retains
+only the latest successful snapshot. Results have:
+
+```text
+{final, speakers, secondsPerFrame, frameCount,
+ segments:[{speaker,startTime,endTime}, ...]}
+```
+
+Times are seconds from the start of that caller's stream. Intermediate segment
+snapshots may revise earlier segment boundaries. Replace the displayed
+snapshot; do not append whole snapshots as new segments. Final results include
+all upstream segments, including those finalized before upstream probability
+compaction. The API adds no diarization thresholds or segment filtering.
+
+For recorded mono samples, `await diarization.diarize({audio,sampleRate,signal,
+onUpdate,onProbabilities})` uses the same complete streaming path, then finishes
+and closes that stream. It does not use upstream's length-constrained stateless
+offline operation.
+
+## Probabilities, callbacks, and cancellation
+
+Supply `onProbabilities` to receive every available probability frame as
+`{startFrame,values,speakers,secondsPerFrame}`. Values are frame-major, with one
+value per speaker channel per frame. Frame indices are absolute within the
+stream. The adapter reads between 160 ms input pushes, before upstream's old
+probability buffer can be compacted. It reports an error if an upstream gap is
+ever observed; it does not manufacture missing values. Without this callback,
+the helper does not request raw probabilities.
+
+Callbacks are awaited and their failures propagate. The caller owns retaining
+probability history, audio, and any earlier snapshots it needs. The SDK does
+not accumulate a second transcript of continuous protocol output. `onEvent`
+receives ordinary process lifecycle events and complete stderr diagnostics;
+raw stdout protocol belongs to the result callbacks instead. Keep engineering
+diagnostics in a selected developer surface, outside ordinary UI/chat history.
+
+`cancel(reason)` and the stream's abort signal stop subsequent pushes and
+suppress later result commits for that stream. Cancellation closes the stream
+after native commands already ahead of its close have returned; the C ABI
+does not offer an immediate interrupt. Other streams keep their own state.
+An already-running caller callback finishes under its caller's ownership.
+`cancel()` can be awaited inside a callback. Await the same stream's `push()`,
+`finish()`, or model `close()`
+only after the callback returns; a recursive wait reports
+`DIARIZATION_CALLBACK_WAIT` instead of deadlocking. Stream `completion`
+retains finish/cancellation cleanup failures.
+
+`close()` stops new streams, drains in-flight openings and accepted stream work,
+finishes the remaining streams, closes helper stdin, and waits for native
+cleanup/process exit. The model always outlives its streams. Complete failures
+from an operation and its cleanup remain available together.
+
+## Core service
+
+Import the named or default factory from `arcane-os/core/diarization`.
+
+`createDiarizationService({executable,modelPath,runtime,onEvent},launchContext)`
+is a synchronous `native.services` factory. Relative executable/model paths
+resolve against explicit `launchContext.workspaceRoot`, otherwise the native
+launcher's `appRoot` (or the current directory for standalone factories). Model loading is lazy at the
+first diarization operation, not a prerequisite for Core startup. The returned
+service implements `drain()` and `dispose()` and the following methods:
+
+| Method | Input / result |
+| --- | --- |
+| `diarization.status` | Current model lifecycle snapshot. |
+| `diarization.load` | Load the configured model; return readiness. |
+| `diarization.open` | `{sampleRate,probabilities}` → `{streamId,sampleRate}`. |
+| `diarization.push` | `{streamId,audio}` → current timed segment snapshot. |
+| `diarization.finish` | `{streamId}` → complete final result, releasing the stream. |
+| `diarization.cancel` | `{streamId}` → cleanup completion for that stream. |
+| `diarization.recording` | `{audio,sampleRate}` → complete final result. |
+
+Core audio is `{encoding:'f32le',data:BASE64}`: transport encoding of the exact
+little-endian float32 samples, with control metadata outside the audio. The
+service emits `diarization.state`, `diarization.update` with `{streamId,result}`,
+and optional `diarization.probabilities` with the stream ID and frame data.
+Subscribe before opening a stream. Session operations have service lifetime;
+renderer request cancellation does not discard accepted audio. Call the
+explicit cancel method for a session. A recording operation has request
+lifetime and its cancellation closes only that recording's stream.
+
+## Shared process transport
+
+The existing internal `runProcess` owner accepts scalar input as before and
+also an `AsyncIterable<string|Uint8Array>`. Iteration is backpressured by the
+child's stdin writes; iterable completion sends EOF, including in `close-input`
+mode. Cancellation/early child exit calls the iterator's `return()` and waits
+for input cleanup. The producer must make a pending `next()` settle when it is
+returned/cancelled. The diarization-owned producer does this explicitly.
+
+`onOutput({stream,chunk})` receives complete decoded UTF-8 chunks with original
+delimiters and is awaited per stream. It is not a binary stdout interface.
+`captureOutput` and `emitOutputEvents` default to `true`; each also accepts
+`{stdout,stderr}` overrides. Disabling capture requires an output consumer and
+returns `null` for that process-result field; it does not return a shortened
+transcript. Disabling output events leaves those events absent. Existing
+scalar input, full text results and ordinary event defaults remain unchanged.
+Failed output callbacks retain their complete input chunk and cause in the
+process error, including when successful output is caller-owned.
+
+## Upstream contracts
+
+The implementation follows the [stable C ABI](https://github.com/NVIDIA/NeMo-Speech.cpp/blob/v0.2.0/include/nemo_speech/diar.h),
+[SDK linkage guide](https://github.com/NVIDIA/NeMo-Speech.cpp/blob/v0.2.0/docs/sdk.md),
+and [official 0.2.0 release](https://github.com/NVIDIA/NeMo-Speech.cpp/releases/tag/v0.2.0).