arcane-os 0.65.0 → 0.67.0

package/docs/reference/local-ai.md

@@ -70,6 +70,13 @@ assembly compose it through the shared speech service without changing the
 browser's selected STT route. See [native Whisper](local-whisper.md) for the
 complete configuration, platform, media and shutdown contracts.
 
+Adding `encoder: 'openvino-npu'` selects the optional Intel NPU audio encoder
+with a separately selected CUDA or CPU decoder. The Windows x64 precompiled
+runtime uses paired GGML/XML/BIN model resources and the computer's installed
+compatible Intel NPU driver. See the [Intel NPU Whisper guide](../guides/native-whisper-openvino.md)
+for preparation, observed initialization, cancellation/reload and custom
+runtime production. Omitting the encoder retains ordinary Whisper preparation.
+
 The selected model stays loaded across recordings. An eligible native
 accelerated failure may drain that helper and retry the same complete recording
 once on the prepared CPU backend. That accepted request retains its actual
@@ -167,6 +174,34 @@ This factory accepts chat/ONNX requirements; the separate
 owns image requirements. The development and generated native composition
 split the shared application record accordingly.
 
+### Native service owners
+
+A native application service uses its Core lifecycle or request context to
+obtain the existing selected owner:
+
+```js
+const localAI = await context.getService('local-ai');
+const onnx = localAI.getONNXRuntime();
+const modelAssets = await context.getService('model-assets');
+```
+
+`getService()` awaits only that service's existing startup. The synchronous
+`getONNXRuntime()` returns its actual `load/run/unload/current/subscribe/close`
+owner; it neither prepares another runtime nor loads a model. An unselected
+engine reports `LOCAL_AI_RUNTIME_NOT_SELECTED`; an unavailable or recovering
+owner reports `LOCAL_AI_RUNTIME_UNAVAILABLE`, and an aborted service lifetime
+retains its abort reason. Development and generated native compositions register
+one shared model-assets service when ONNX or image generation is selected.
+
+Reacquire `getONNXRuntime()` on each explicit model load because runtime recovery
+replaces that owner. Retain the acquired handle for that session's cleanup and
+await its `unload({id})` without an already-aborted request signal before releasing
+the corresponding model-assets retain handle. The native ONNX owner joins actual
+worker exit; a cancelled request's rejection alone does not establish that exit.
+Core closes services concurrently, and the host can cancel in-flight native work
+at shutdown. These native members require no renderer readiness and introduce no
+second inference engine. See [native Core composition](core-runtime.md#native-service-composition).
+
 `localai.status` returns `{runtimes}` and, when Ollama is selected, the existing
 `ollama` and `models.ollama` catalog fields. Runtime records distinguish
 `installed`, `available`, `state`, `models`, ownership and errors. A listening
@@ -191,6 +226,14 @@ background health polling.
 | `llama.unload` | `{model}` | Current state after release |
 | `llama.chat` | `{model,payload,stream?,streamId?}` | Complete OpenAI-shaped completion |
 
+`llama.status` and `llama.models` observe the selected service without loading,
+restarting or waiting for it. Starting, loading, stopped and failed services
+return their retained state/catalog; an available service supplies a fresh
+catalog observation. The llama.cpp runtime record includes `released: true`
+only after Core successfully closes its owned single-model server. Explicit
+load, inference or recovery can resume that engine; observation cannot.
+Status observation adds no background polling.
+
 The `payload` is the complete request. SDK option names are translated only at
 the upstream protocol boundary; messages, tool definitions and documents remain
 unchanged. An explicit `payload.model` selects that request's model. Core waits
@@ -206,7 +249,8 @@ observe load, sleep and unload changes. Direct servers expose readiness at
 request boundaries; they do not offer the router's passive model event stream.
 
 Unloading a model from an owned single-model server closes that owned process;
-a subsequent load can start it again. Releasing an externally owned direct
+a subsequent load can start it again. Repeating that unload returns the released
+state without restarting the process. Releasing an externally owned direct
 server returns `released: true, unloaded: false`, retaining the real catalog
 and leaving that server running.
 
@@ -282,6 +326,38 @@ does not install software or select a model. A missing Core connection reports
 unavailability, leaving browser Wllama/ONNX routes available for the application
 to select.
 
+Omit `client` to follow the installed Core client through
+[`subscribeCoreClient`](core-client.md): construction may precede installation.
+Each installation reads `llama.status` without selecting, downloading or loading
+a model. Retirement or replacement synchronously revokes this provider's
+`status().loaded`, cancels its owned operations and detaches the old lifecycle
+listener. Late results cannot restore the retired selection. Explicitly load
+the selection against the replacement client before inference. Passing a
+`client`, including `null`, keeps that caller-supplied connection fixed.
+
+`status()` is this provider's current state. The `arcane-ai-provider/2` contract
+does not provide a provider-state subscription, so this installation handling
+alone does not update an idle AI runtime's retained role state. The provider
+runtime still reconciles the provider at its existing operation boundaries.
+`inspect()` reports whether an explicit load can proceed, separately from
+`status().loaded`. A genuine `starting` or `loading` service without an error
+permits that load preflight even before its catalog arrives; Core's `llama.load`
+waits for startup and verifies the exact requested model. An owned, successfully
+released service permits loading only a model retained in its actual catalog.
+An available service still requires that catalog membership. These observations
+do not fabricate model records or readiness, and unavailable external services,
+closed services and actual errors remain unavailable.
+
+`dispose()` removes installation and service subscriptions and cancels owned
+operations synchronously, then attempts its actually retained model's release
+through its captured client. A configured selection alone does not own a native
+model: disposing before load or after successful unload sends no native release,
+including when the caller explicitly supplied `client: null`. A failed release
+rejects with the actual error even though the provider is disposed; disposal
+does not establish successful native unload.
+It never unloads a retired selection through a replacement client or closes the
+shared Core client.
+
 If a router evicts the primary model while serving a request-specific model,
 reload the primary selection before its next request. The provider does not
 silently change the application's saved model choice. Release registration
@@ -309,13 +385,45 @@ try {
 ```
 
 The factory accepts `{modulePath,signal?,onEvent?}` and starts no worker until
-`load({id,model,sessionOptions?,signal?})`. The model path is absolute for this
+`load({id,model,sessionOptions?,executionPreference?,signal?})`. The model path is absolute for this
 direct Node API. Session creation defaults to the CPU execution provider;
 explicit native session options remain caller-owned. The returned session
 record contains `id`, `model`, `state`, `loaded`, `error`, input/output names and
 metadata. A live ID requires explicit unload before replacement. An ID may be
 loaded again once its previous worker exits after a failed load or unload.
 A run error retains the loaded session so a corrected request can use it.
+`current().sessions[].stopping` becomes `true` when terminal shutdown begins,
+including worker failure or explicit cancellation/unload. The session is then
+unavailable for new runs even while `loaded` remains `true` until actual exit.
+A recoverable run error keeps `stopping:false` and the loaded session usable.
+`current().sessions[].exited` reports actual worker exit, independently of a
+rejected load or inference. Unload joins worker exit and output delivery even
+when requesting termination fails; complete cleanup errors remain observable.
+
+Select `executionPreference: 'gpu'` to try the installed runtime's advertised
+CUDA, TensorRT, DirectML, CoreML and WebGPU providers in that order, followed by
+CPU when no accelerator session can be created. Discovery runs once per load;
+each advertised candidate receives one actual session-creation attempt with CPU
+available for graph nodes that the accelerator cannot handle. No provider is
+downloaded by selection. The upstream `bundled` flag describes packaging and
+does not exclude separately installed CUDA or TensorRT libraries. An explicit
+`sessionOptions.executionProviders`, including an empty array, takes precedence
+and is passed unchanged without automatic discovery or retries. Automatic
+DirectML attempts default `enableMemPattern` to `false` and `executionMode` to
+`'sequential'` as required by that provider; explicit caller values remain
+unchanged, including on the final CPU attempt.
+
+Automatic GPU selection adds an `execution` record to the loaded session and
+its ordinary state events: `preference`, complete `supportedBackends`,
+`selectedProviders`, ordered `attempts` with their full errors, `fallback`, and
+`discoveryError`. Each attempt records `executionProviders`, `status`
+(`configured` or `failed`), and `error`. `fallback: true` means the SDK created
+the final CPU session after GPU preference, including when no GPU candidate was
+advertised. Successful creation establishes an accepted provider configuration;
+it does not establish that a GPU executed any graph nodes. If every attempt
+fails, the load error retains the complete attempt errors and `execution`
+record. Inference failures retain their existing behavior and do not replay
+inference on another provider.
 
 `run({id,feeds,fetches?,runOptions?,signal?})` returns the complete output-name
 map of `{type,dims,data}` tensors. Input records use that same shape with native
@@ -376,6 +484,15 @@ Closing the accessor cancels its requests and subscriptions; model unloading
 is explicit because other accessors may share the Core session. It never
 closes the shared Core client.
 
+Omitting `client` follows Core installation events with current-client replay,
+including installation after construction. Each new connection reads
+`onnx.status`; it does not install a runtime or load a model. Retirement or
+replacement immediately clears retained session readiness and cancels this
+accessor's operations. Late old-client state and results are ignored. Passing
+an explicit `client`, including `null`, retains caller ownership and does not
+follow global installation changes. `close()` also removes the installation
+subscription.
+
 Construction neither opens a connection nor installs a runtime. A browser needs
 an already available native Core service or the explicit development bridge.
 Unavailable native ONNX leaves browser ONNX/Wllama under the application's

package/docs/reference/local-image-generation.md

@@ -199,14 +199,16 @@ ordered `Blob` or `File` members after its resumable download. Range support
 allows concurrent transfer within a member; those transfer parts remain the
 store's concern. Use `offline: true` to require an already complete stored model.
 The store does not select or run the image engine. In source development,
-load the development Core bootstrap described
-in [Local AI through Core](local-ai.md#development) before constructing the
-accessor. Native hosts install their Core client through the existing host path.
+use the development Core bootstrap described
+in [Local AI through Core](local-ai.md#development). The accessor can be
+constructed before that client is installed; perform model operations once
+the service is available. Native hosts install their Core client through the
+existing host path.
 An ordinary browser without Core reports local image generation as unavailable.
 
 | Member | Contract |
 |---|---|
-| `createCoreImageRuntime({client?, signal?, onEvent?})` | Uses the installed Core client by default, subscribes to lifecycle events and asynchronously reads one initial status snapshot. It returns immediately. |
+| `createCoreImageRuntime({client?, signal?, onEvent?})` | Follows Core installation and lifecycle events by default, asynchronously reading status for each client. An explicit `client`, including `null`, remains caller-owned. It returns immediately. |
 | `load({model, context?, assetProjectionId?, resourcePaths?, signal?})` | Loads the selected model and returns authoritative service state after native completion. `context` supplies native context options. |
 | `generate({model, prompt, parameters?, assetProjectionId?, resourcePaths?, signal?, onProgress?})` | Returns the complete result with `images: [{blob, mediaType, width, height}]`. Additional runtime result metadata remains present. |
 | `unload({signal?})` | Explicitly unloads the shared selected native context and returns its resulting state. |
@@ -229,6 +231,15 @@ model definitions, including their resource metadata before engine preparation
 finishes. Installed files do not imply a loaded model. A late status
 response never overwrites a newer lifecycle event.
 
+With `client` omitted, the accessor consumes the shared
+[`subscribeCoreClient`](core-client.md) installation stream. A late installation
+attaches the service listener and reads current status; it never installs an
+engine or loads a model. Retirement or replacement synchronously clears
+readiness and transient `Thinking`, cancels owned requests and detaches the
+retired service listener. Old state, progress and results cannot update the
+replacement connection. `close()` also removes the installation subscription;
+it does not claim that the shared native model was unloaded.
+
 Prompts and parameters pass unchanged to the native runtime. Native option
 names, supported model operations and defaults belong to that runtime and the
 selected model definition. A prompt containing U+0000 or an unpaired UTF-16

package/docs/reference/local-whisper.md

@@ -7,6 +7,12 @@ the model or recording files are reused. The browser's existing
 `AI.fetchSTT(audioFile, signal)` and Core `speech.transcribe` routes retain the
 application's selected model and cancellation signal.
 
+For the optional Intel NPU encoder, add `encoder: "openvino-npu"` to the
+runtime record. The [Intel NPU guide](../guides/native-whisper-openvino.md)
+covers the Windows x64 precompiled distribution, paired GGML/XML/BIN model
+resources, independent CUDA/CPU decoding and joined cancellation. Omitting
+`encoder` preserves the ordinary runtime and model selection below.
+
 ## Select the runtime and model
 
 An application's `arcane-app.json` selects native speech alongside its other
@@ -130,7 +136,7 @@ prepared descriptor returned by `ensureLocalAIRuntimes`; alternatively,
 
 | Member | Contract |
 | --- | --- |
-| `current()` | Returns `providerId`, selected `modelId`, lifecycle `state`, `loaded`, `busy`, correlated `requestId` or null, requested/observed backend, evidence and any error. |
+| `current()` | Returns `providerId`, selected `modelId`, lifecycle `state`, `loaded`, `busy`, correlated `requestId` or null, `requestedBackend`, `observedBackend`, `backendEvidence`, `requestedEncoder`, `observedEncoder`, `encoderEvidence` and any error. Encoder initialization evidence is separate from decoder evidence. |
 | `subscribe(listener, {replay = true, signal} = {})` | Immediately replays current state by default and returns an unsubscribe function. |
 | `load({modelId, signal} = {})` | Prepares the runtime if necessary, then waits for actual native model readiness. With no selected model it remains unloaded. |
 | `transcribe(request, {signal, onProgress, requestId} = {})` | Consumes the complete `audioBase64` recording. Optional `language` defaults to native automatic detection; `translate: true` selects Whisper's translation operation. `model` must match the loaded model. Optional `requestId` carries the caller's existing operation identity through lifecycle snapshots as separate control information; it does not alter the recording or request payload. |

package/docs/reference/mcp-stdio.md

@@ -216,7 +216,7 @@ normal close or EOF and rejects with an `AggregateError` when transport or
 diagnostic delivery failed. Observe it even when the initiating caller continues
 other work. Request failures alone do not close the session.
 
-## MCP_PROTOCOL_VERSION
+## `MCP_PROTOCOL_VERSION`
 
 `MCP_PROTOCOL_VERSION` is exactly `'2025-11-25'`. Initialization always returns
 that supported version. A client proposing another version must accept this

package/docs/reference/model-assets.md

@@ -1,6 +1,6 @@
-# Native working files from stored model assets
+# Native working files from model assets
 
-These public APIs were first published in `arcane-os@0.61.0`. Browser
+Browser preparation and native retain/release ownership were first published in `arcane-os@0.61.0`. Browser
 preparation is exported by `arcane-os/ai/core-model-assets`, and the native
 service by `arcane-os/core/model-assets`. The image example below uses
 `arcane-os/ai/core-image`, published in the same release.
@@ -87,6 +87,53 @@ cleanup failures remain observable.
 
 ## Native ownership
 
+Native services can prepare explicitly selected upstream members without a
+renderer or browser store. Obtain the registered shared service through
+`await context.getService('model-assets')`, then use its native preparation API:
+
+```javascript
+const modelAssets = await context.getService('model-assets');
+const projection = await modelAssets.prepare({
+    id: selectedOperationId,
+    workingDirectory: selectedWorkingDirectory,
+    members: selectedMembers, // [{path: 'onnx/model.onnx', url: selectedURL}, ...]
+    signal,
+    onProgress: renderPreparationProgress
+});
+const use = modelAssets.retain(projection.id);
+await modelAssets.release(projection.id);
+try {
+    await ownNativeModelLifetime(use.members);
+} finally {
+    // Join actual native unload/worker exit before releasing these files.
+    await use.release();
+}
+```
+
+`prepare({id,workingDirectory,members,signal,onProgress})` performs standard
+fetches only when explicitly called. Every member has its original relative
+`path` and selected `url`; the caller supplies the complete companion-file set.
+Independent members download concurrently. Each complete response stream is
+written directly through the existing ordered native file owner, without a
+whole-model buffer or base64 conversion. No model or runtime is selected or
+downloaded by service startup. The result is the ready projection snapshot with
+ordered `members: [{path,nativePath}]`.
+
+Progress uses `open`, `download`, `complete` and `ready` phases, with
+`completed`, `total` and `unit:'files'`; member progress additionally includes
+`memberIndex` and `path`. Progress callbacks may return a promise, which the
+preparation observes. They must not await cleanup of the preparation currently
+calling them. Callback failures remain preparation failures. HTTP failures
+retain `url`, `status` and the complete response text in `response`.
+
+`release(id)` relinquishes preparation ownership without a request signal.
+For active native downloads, release or disposal aborts their fetches and joins
+the transfer tasks and native writes before deleting only their owned child
+directory. Preparation cancellation and failure follow that same cleanup path;
+the original failures and cleanup failures remain observable. A native retain
+handle continues to protect completed files through actual engine release.
+Native preparation leaves browser DBOPFS originals and unrelated files alone.
+
 ```javascript
 import {createModelAssetService} from 'arcane-os/core/model-assets';
 
@@ -103,7 +150,7 @@ try {
 ```
 
 `createModelAssetService({appRoot})` returns a Core service with `current()`,
-`retain(id)` and `dispose()`. `retain()` accepts only a completed projection
+`prepare(options)`, `retain(id)`, `release(id)` and `dispose()`. `retain()` accepts only a completed projection
 and returns `{id,directory,members,release}`. A native engine takes this handle
 before loading and releases it after actual unload, failed-load cleanup or
 worker exit. A rejected inference/load promise alone does not establish native

package/docs/reference/native-decisions.md

@@ -0,0 +1,181 @@
+# Native Laya typed decisions
+
+`arcane-os/local-ai/decisions` and `arcane-os/core/decisions` run the selected
+Laya FP32 graph through the SDK's existing native ONNX owner. Tokenization runs
+in its own Node Worker. A Core service can load and evaluate decisions without
+a renderer, browser session, WebGPU browser context or chat provider.
+
+The application owns the model selection, original state text, questions,
+options and interpretation. The SDK owns model preparation, token framing,
+inference and cleanup. This is option scoring, not a conversational LLM, a
+replacement for a configured chat model or the cloud System One API.
+
+## Compose with existing Core services
+
+Register a decision service alongside the selected local-AI and model-assets
+services in the application's existing Core runtime:
+
+```js
+import {createNativeDecisionService} from 'arcane-os/core/decisions';
+
+const decisions = createNativeDecisionService({
+    model: 'onnx-community/laya-typed-decisions-ONNX',
+    dtype: 'fp32',
+    workingDirectory: '.models/laya'
+}, {appRoot});
+
+// Include decisions in the existing createCoreRuntime({services}) selection.
+// That runtime already owns local-ai with ONNX selected and model-assets.
+await runtime.getService('decisions');
+await decisions.load(); // Explicit activation; no model download at registration.
+try {
+    const result = await decisions.evaluate([{
+        state: 'The moon chef has one kettle and seventeen impatient dragons.',
+        question: 'What should the chef prepare?',
+        options: ['Tea', 'An inflatable castle']
+    }]);
+    console.log(result.decisions[0].value);
+} finally {
+    await decisions.unload();
+}
+```
+
+Here `runtime` and `appRoot` are the application's existing Core runtime and
+root. Add the service before starting that runtime; the example does not create
+a second Core host or engine. Development and packaged native compositions
+already register one model-assets service when ONNX is selected. The decision
+service obtains those exact owners with `context.getService('local-ai')`,
+`localAI.getONNXRuntime()` and `context.getService('model-assets')` on explicit
+load. It reacquires the current ONNX owner after a later runtime recovery.
+See [Core composition](core-runtime.md#native-service-composition) and
+[native service owners](local-ai.md#native-service-owners).
+
+`createNativeDecisionService(configuration, {appRoot})` defaults its service
+name to `decisions`. It exposes `load`, `evaluate`, `classify` (an alias for
+`evaluate`), `current`, `subscribe`, `unload` and `dispose`, plus Core lifecycle
+`start(context)`. Its RPC methods are:
+
+| Method | Parameters and result |
+| --- | --- |
+| `decisions.status` | Current lifecycle snapshot; does not load anything. |
+| `decisions.load` | Explicit activation; returns the ready lifecycle snapshot. The request signal cancels activation. |
+| `decisions.evaluate` | `{rows, runOptions?}`; returns `{decisions, outputs}`. The request signal cancels the active model operation. |
+| `decisions.unload` | Releases the activation. Service-lifetime cleanup continues after the caller disconnects. |
+
+RPC evaluation uses the SDK's existing complete JSON tensor encoding for
+`outputs` at the transport boundary. Direct native evaluation returns native
+typed tensor records. Service notifications use `decisions.state`; direct
+`subscribe(listener, {emitCurrent:true, signal})` replays current state by
+default and returns an unsubscribe function. Startup stores the service
+context only: importing or registering this service starts no tokenizer,
+model download or inference.
+
+## Direct native model
+
+`createNativeDecisionModel(options)` from `arcane-os/local-ai/decisions` returns
+`{load, evaluate, classify, current, status, subscribe, unload, dispose}`.
+`status` aliases `current`; `classify` aliases `evaluate`. Supply the existing
+native `onnx` owner, plus either the existing `modelAssets` owner and selected
+`workingDirectory`, or caller-owned native files:
+
+```js
+import {createNativeDecisionModel} from 'arcane-os/local-ai/decisions';
+
+const decisions = createNativeDecisionModel({
+    onnx: localAI.getONNXRuntime(),
+    paths: {
+        model: selectedGraphPath,
+        tokenizer: selectedTokenizerPath,
+        tokenizerConfig: selectedTokenizerConfigPath
+    }
+});
+```
+
+These direct paths are native filesystem paths. Keep the graph's external data
+beside it under the exact filename required by the graph. The Core service
+resolves configured `paths` relative to `appRoot`; it does not copy or remove
+caller-owned files. For SDK-prepared files, the default selected upstream is
+`onnx-community/laya-typed-decisions-ONNX`, revision `main`, with exactly:
+
+- `onnx/model.onnx` and `onnx/model.onnx_data`;
+- `tokenizer.json` and `tokenizer_config.json`.
+
+`model` selects the upstream Hugging Face repository and `revision` its
+revision. Native preparation performs normal upstream fetches only during
+explicit `load()`. It streams complete members through the existing working
+file owner; it neither vendors the weights nor creates a second persistent
+model store. The approved `@huggingface/tokenizers@0.2.0` dependency reads the
+selected tokenizer files in its Worker. No Transformers or second ONNX runtime
+is loaded by this API.
+
+This graph selection requires `dtype:'fp32'`, which is also the default; another
+dtype reports the incompatible selection rather than substituting a graph.
+`sessionOptions` and `runOptions` pass to the existing native ONNX API unchanged.
+`executionPreference` defaults to `gpu` here: actual advertised native GPU
+provider creation is attempted, followed by an honest CPU fallback. Explicit
+`sessionOptions.executionProviders` takes precedence. The underlying generic
+ONNX factory continues to default to CPU. Accepted provider configuration is
+not evidence that GPU nodes executed. Full provider-attempt diagnostics remain
+in `execution`; see [native ONNX sessions](local-ai.md#native-onnx-sessions).
+
+## Complete inputs and outputs
+
+`evaluate(rows, {signal, runOptions})` requires an explicitly loaded or loading
+activation; it does not silently load an inactive model. Rows retain their
+caller order, complete `state`, `question` and string-array `options`, plus
+optional `type` (`choice`, `score` or `noul`). Additional row fields remain in
+the returned row. Strings are not trimmed, rewritten or clipped. The shared
+browser/native encoding owner constructs only the model's necessary token
+framing; repeated identical state is tokenized once per batch. Tokenization
+and ONNX execution run outside Core's foreground thread.
+
+The result is `{decisions, outputs}`. Each decision contains its original
+`row`, complete option `logits`, unrounded raw-softmax `probabilities`,
+`answerIndex` and `value`. `choice` returns the selected complete option;
+`score` returns the probability-weighted zero-based option index; `noul`
+requires `[falseOption, trueOption]` and returns the probability of option 1.
+When the graph actually supplies `act_logits`, action logits, probabilities
+and `actProbability` are also returned. Every named graph output is retained
+as `{type, dims, data}`, including extra tensors and padding. Raw model scores
+are not claimed calibrated confidence. Results do not enter chat history,
+memory extraction or DBOPFS automatically.
+
+The model's real graph/context limits still apply. There is no SDK token cap,
+silent chunking or fabricated result aggregation. Native/browser token-ID or
+numerical parity requires execution evidence for the selected tokenizer and
+runtime; sharing the encoding implementation alone does not establish it.
+
+## Lifetime and cancellation
+
+`current()` returns `{family, model, revision, dtype, state, loaded, busy,
+activeRequests, progress, error, execution}`. States include `unloaded`,
+`loading`, `ready`, `unloading`, `disposing`, `disposed` and `error`. Semantic
+progress includes model preparation, tokenization and evaluation; downloaded
+members report files, not byte progress. Complete technical errors belong in
+developer diagnostics, while the application owns its user-facing status.
+
+Concurrent callers share one explicit activation. Cancelling a load or
+evaluation cancels that activation and its outstanding operations, because the
+native session and tokenizer have one owner. Use separately owned models when
+independent cancellation is required. The construction `signal` governs the
+whole model lifetime. `unload()` permits another explicit load after successful
+cleanup; `dispose()` is terminal. Readiness is revoked as disposal begins.
+
+Retained model files remain owned until the ONNX and tokenizer Workers really
+exit. A rejected load, inference or termination request alone does not permit
+file deletion. Cleanup joins active operations and native output delivery,
+preserves cleanup errors, then releases only its working projection. It never
+deletes supplied `paths`. A failed ordinary row does not destroy a healthy
+loaded session or cancel sibling evaluations. The ONNX owner's `stopping:true`
+retires decision readiness immediately on terminal Worker failure or shutdown,
+even while its physical `loaded` state remains true pending actual exit. Cancelled or
+retired operations cannot return a successful late result.
+
+Shared Node/Worker/filesystem code is portable across Windows, Linux and macOS;
+the selected ONNX Runtime build and provider determine actual platform/device
+availability. Android requires the host's supported native adaptation. Static
+source review and synthetic authored fixtures are not model execution or a
+claim of tested platform, precision or accelerator behavior.
+
+Upstream selection: [Laya FP32 model files](https://huggingface.co/onnx-community/laya-typed-decisions-ONNX/tree/main),
+[Tokenizer package](https://www.npmjs.com/package/@huggingface/tokenizers).

package/docs/reference/native-speech.md

@@ -26,6 +26,12 @@ selection, supported formats, and native process ownership remain with the
 selected engine and its host composition. Browser-only operation remains
 independent of this native service.
 
+The SDK's [retained Whisper engine](local-whisper.md) supplies native STT.
+Its optional [Intel NPU encoder](../guides/native-whisper-openvino.md) uses the
+same service, readiness events, complete request/result contract and cancellation
+path. The host selects that encoder and its paired model resources; the browser
+continues calling `speech.transcribe` without loading native libraries itself.
+
 ## Startup and status
 
 `start(context)` subscribes to each configured engine and starts their loads