arcane-os 0.57.0 → 0.59.0

package/docs/reference/README.md

@@ -52,7 +52,13 @@ alone does not make bare module names resolve in a browser.
 | Call `globalThis.Arcane` | [Arcane Core API](core/arcane-api.md) |
 | Connect a browser to one Core transport | [Core browser client](core-client.md) |
 | Compose native Core dispatch, service lifecycle, and stdio hosting | [Native Core runtime](core-runtime.md) |
+| Run application-selected llama.cpp, Ollama or ONNX through Core | [Local AI through Core](local-ai.md) |
+| Retain a Nemotron model and diarize caller-fed audio streams | [Native speaker diarization](diarization.md) |
+| Persist application-selected preferences through Core | [Core preferences service](core-preferences.md) |
+| Read complete selected Git text without changing a checkout | [Git text snapshots](git-text-snapshot.md) |
 | Build an installed-SDK portable Core payload | [Portable Core packaging](core-native-packaging.md) |
+| Build a Windows executable without an OS checkout | [Windows executable packaging](core-native-packaging.md#windows-executable) |
+| Compose a Mac application with an architecture-matched host | [macOS application composition](core-native-packaging.md#macos-application-composition) |
 | Subscribe to native events | [Arcane event reference](core/arcane-events.md) |
 | Use provider-neutral AI lifecycle, chat, speech, persistence, or document context | [Normalized AI](#normalized-ai) |
 | Choose a normalized typed browser decision surface | [Browser typed decisions](ai/browser-decisions.md) |
@@ -79,9 +85,11 @@ This repository contains explicitly versioned surfaces with different owners:
 
 Browser modules and reusable Core client/runtime/lifecycle source belong to the
 SDK. The portable provider uses this installed package by default and assembles
-an app payload with explicitly selected services; it supplies no executable
-platform host. Explicit Arcane OS provider overrides and integrated shared
-checks remain available. Arcane OS retains its product composition and policy.
+an app payload with explicitly selected services; portable itself supplies no
+executable host. The Windows provider pairs that payload with the installed
+SDK version's precompiled WebView2/SEA release asset. Explicit Arcane OS provider
+overrides and integrated shared checks remain available. Arcane OS retains its
+product composition and policy.
 The historical Core reference snapshot describes a separate host contract;
 matching a protocol name or assembling a payload alone does not establish that
 a composed host supplies every required method or service.
@@ -131,6 +139,15 @@ select a documentation commit whose contracts match the published package.
 Generated output still belongs to the canonical `site/` tree and requires its
 usual coordinated output ownership. Generation does not publish hosted Pages.
 
+For a selected release whose documentation correction lands after unrelated
+source, `createReferenceSite({inputs})` and `writeReferenceSite({inputs})` accept
+one explicit input owner with `readText(relativePath)` and
+`listFiles(relativeDirectory)`. It is shared with the contract extractor. Keep
+package/runtime reads and document discovery on the release commit, and overlay
+only reviewed documentation records from the correction commit. In particular,
+preserve the selected inventory's member set instead of importing later public
+APIs. Omitted `inputs` preserves the live or `sourceRef` behavior above.
+
 ### Historical 0.3.4 publication record
 
 The following records describe that earlier release only. They do not identify
@@ -201,6 +218,8 @@ Ollama, Wllama, Whisper, Kokoro, native, or cloud transport:
 | Offer explicit selected-model start/cancel UI | [`chat.html`](runtime-components.md#chathtml), [`speech.html`](runtime-components.md#speechhtml), and [`voice-transcription.html`](runtime-components.md#voice-transcriptionhtml) | Browser/native WebView components; user activation emits a cancelable request before any LLM or STT load intent, and recording stays disabled without sticky ready STT. |
 | Use Core-normalized chat | [`globalThis.Arcane.ai`](core/arcane-ai-contracts.md) | Native/Core only when separately admitted. |
 | Run a caller-selected GGUF LLM locally | [`arcane-os/ai/browser-wasm`](ai/browser-wasm.md) | Browser secure context with WebAssembly and OPFS/DBOPFS; explicit CPU selection or WebGPU with full offload and no automatic CPU fallback. |
+| Run application-selected native llama.cpp/Ollama chat | [`arcane-os/ai/core-local`, `arcane-os/core/local-ai`](local-ai.md) | Explicit Core connection and selected native runtimes; installation, availability and loaded-model readiness remain distinct. |
+| Run a local ONNX graph with named tensors | [`arcane-os/local-ai/onnx`, `arcane-os/ai/core-onnx`](local-ai.md#native-onnx-sessions) | Retained native workers; browser access requires an available Core ONNX service. |
 | Run caller-selected Whisper/Kokoro locally | [`arcane-os/ai/browser-speech`](ai/browser-speech.md) | Browser with DBOPFS, Web Locks, Workers and selected upstream sources; automatic WebNN NPU, WebGPU, then WASM loading, or an explicit backend. |
 | Use native browser recognition/voices or selected cloud TTS | [Speech provider choices](ai/browser-speech.md) | Native APIs depend on the browser and may use remote services; cloud TTS requires the application key and endpoint access. |
 | Send complete chat, System One or image requests without retained history | [`arcane-os/ai/twin-cloud`](ai/twin-cloud.md) | Node or browser with Fetch and explicit model/credentials; image results contain every returned image as a Blob. |

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 and macOS ARM64/x64 have SDK-owned provider and host composition
+source. Their assembly paths require the matching numeric release's native
+host archive; npm publication alone does not supply that archive or establish
+platform execution. The macOS provider composes AppKit, WebKit and the shared
+Node Core payload. Linux and Android retain their explicit checkout providers
+where listed. See [native output and host requirements](core-native-packaging.md).
 
 ## Capability-first matrix
 
@@ -88,7 +88,14 @@ macOS host, but they do not supply that native platform host or bridge.
 | Read host identity, capabilities, storage, preferences, appearance, or platform state | `globalThis.Arcane` | **Cross-host** where the method is implemented and admitted | Promise behavior and `Arcane.Error` are normalized. Result fields are normalized unless the method explicitly documents a platform-dependent snapshot. |
 | 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 a portable Core payload from the installed SDK | `arcane-os/native/portable-provider` | **Node**; explicit Windows, Linux or macOS platform selection | 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. |
+| Compose a macOS application bundle | [`arcane-os/native/macos-provider`](core-native-packaging.md#macos-application-composition) | **Node** assembly with matching host archive; matching Darwin ARM64/x64 for execution | Complete portable content stays in Resources. AppKit/WebKit launch, stable packaged origin, document activation and graceful Core drain remain host-owned. Source implementation is separate from a built/published host archive or actual Mac execution. |
+| Persist application-owned Core preferences | [`arcane-os/core/preferences`](core-preferences.md) | **Node** Core service; renderer uses existing `Arcane.preferences` methods | Application-selected file and exact keys/JSON values, ordered in-process writes and service-lifetime drain. Unreadable storage remains untouched; saved values do not set operating-system preferences. |
+| Read complete selected text from Git | [`createGitTextSnapshot`](git-text-snapshot.md) from `arcane-os` | **Node** with Git on Windows, Linux or macOS; Android requires host adaptation | One selected revision, complete UTF-8 content and independent result copies. A dedicated bare object cache leaves working checkouts untouched; shared refresh and drain own actual completion. |
+| 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. |
+| Label speakers in caller-fed mono audio | [`arcane-os/diarization`, `arcane-os/core/diarization`](diarization.md) | **Node** with built helper, selected official NeMo libraries and Nemotron model; official CPU archives cover Windows x64 and Linux/macOS x64/arm64 | Independent retained streams, complete timed segments and optional probability frames. Generic labels are not personal identities or speech transcripts; cancellation and close observe native cleanup. Android needs host adaptation. |
 | 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

@@ -77,6 +77,13 @@ The compatibility facade retains its operation-specific timeouts and streaming
 callbacks. Streaming IDs and isolated-operation IDs are separate protocol
 correlation fields alongside the supplied request fields.
 
+`Arcane.speech.synthesize(request, {signal})` forwards the optional cancellation
+signal through the same request lifetime. Existing one-argument calls retain
+the 180,000 ms timeout and pass the complete request unchanged. A pre-aborted
+signal sends no synthesis request; an in-flight abort sends `request.cancel`
+and suppresses late responses. Actual synthesis interruption depends on the
+registered speech service and its engine; the facade supplies no speech engine.
+
 ## Events and request lifetime
 
 `events.on(name, listener)`, `once(name, listener)` and
@@ -124,6 +131,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`.
@@ -208,10 +212,14 @@ details and [the client contract](core-client.md) for native bridge integration.
 
 The generated Core entry accepts `--arcane-launch-config <path>`. The public
 `readCoreLaunchContext({argv=process.argv.slice(2)}={})` function in
-`arcane-os/core/host` reads that explicitly selected JSON object. Without the
-flag it returns `{}`. Missing files, missing flag values and malformed JSON
-report their actual errors; the reader does not search for configuration,
-rewrite it or change the process environment.
+`arcane-os/core/host` reads that explicitly selected JSON object. A native host
+can separately supply `--arcane-host-state-root <directory>` for the reader's
+`stateRoot` default. Every field in the explicit JSON object takes precedence
+unchanged, including an explicitly present `stateRoot` with a relative, null or
+other application-owned value. With neither argument the reader returns `{}`.
+Missing files, missing argument values and malformed JSON report their actual
+errors; the reader does not search for configuration, resolve or validate the
+state directory, rewrite the file or change the process environment.
 
 The generated entry supplies an artifact-derived `appRoot` and then applies the
 complete explicit launch context. Every service factory receives that same
@@ -220,7 +228,10 @@ launcher can supply the user's selected `workspaceRoot` and writable
 `stateRoot` at launch instead of embedding this machine's paths in an app
 package. The host owns those selections; the SDK does not choose a product's
 workspace, namespace, saved preferences or models. JSON values and additional
-application-owned fields remain unchanged.
+application-owned fields remain unchanged, including an app-selected
+`preferencesFile`. The state directory supplies no preference filename and
+triggers no stored-data discovery or migration. Linux and other composing hosts
+may pass the same separate argument; the reader chooses no platform directory.
 
 ## Selected local-AI runtimes
 
@@ -242,6 +253,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:
@@ -294,8 +312,11 @@ Arcane.exe --arcane-launch-config path/to/launch.json
 The complete JSON object reaches the service factories as their second
 argument. A supplied `stateRoot` also owns the WebView2 profile and diagnostic
 directory. Otherwise the launcher uses the current user's local application
-data under `Arcane/<app-id>`. The launcher does not invent an application
-workspace. Relative launch-file paths resolve from the invocation's working
+data under `Arcane/<app-id>`. It forwards that actual host selection through
+`--arcane-host-state-root`, so ordinary double-click startup supplies `stateRoot`
+to every Core service factory. The complete explicit launch context still takes
+precedence without rewriting its fields. The launcher does not invent an
+application workspace. Relative launch-file paths resolve from the invocation's working
 directory. `--close-on-stdin-eof` is an explicit process-owner option used by the
 SDK runner; an ordinary double-clicked window closes through its own UI.
 
@@ -331,3 +352,102 @@ 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 shared launch reader also
+supplies that host default to every application service factory, with explicit
+launch fields taking precedence. 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.