arcane-os 0.62.0 → 0.64.0

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

@@ -0,0 +1,139 @@
+# SDXL Base 1.0 through Core
+
+The `sdxl-base-1.0` model definition selects Stability AI's complete SDXL Base
+1.0 checkpoint for text-to-image generation through the shared
+[local image runtime](local-image-generation.md). Applications supply their
+own complete prompts and own the resulting images and saved associations.
+The model uses the shared retained native context, progress, cancellation
+and complete PNG result contract.
+
+## Model selection
+
+Select this runtime record under `native.localAI` in `arcane-app.json`, or
+the corresponding package projection's `localAI` record:
+
+```json
+{
+    "runtimes": [
+        {
+            "id": "stable-diffusion.cpp",
+            "version": "master-929-3f8527a",
+            "backend": "auto",
+            "models": ["sdxl-base-1.0"]
+        }
+    ]
+}
+```
+
+The built-in ID supplies the cohesive `SDXL_BASE_1_0_MODEL` definition from
+`src/local-ai/image-models/sdxl.mjs`. The shared service exposes its resource
+metadata through `image.status` and `images.inspect()`.
+
+Backend discovery, accelerated-device selection and CPU fallback belong to
+the shared runtime. This model definition leaves `context` empty and adds no
+device or precision override. Available acceleration depends on the selected
+runtime distribution; see the shared guide's platform availability. Model
+selection alone does not establish actual execution on any device.
+
+## Prepare the checkpoint and generate an image
+
+The single `model` resource is the official
+[sd_xl_base_1.0.safetensors checkpoint](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/462165984030d82259a11f4367a4eed129e94a7b/sd_xl_base_1.0.safetensors)
+at revision `462165984030d82259a11f4367a4eed129e94a7b`. It includes the text
+encoders, denoiser and original VAE. Standalone base generation uses this one
+resource; a refiner, separate VAE, LoRA or Python converter is unnecessary for
+this selection. The upstream model carries the
+[CreativeML Open RAIL++-M license](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/462165984030d82259a11f4367a4eed129e94a7b/LICENSE.md).
+
+The existing DBOPFS model store owns the authoritative download. The shared
+[model-assets service](model-assets.md) prepares complete native working files
+when the application loads the model. Installing the native runtime does not
+download a second model copy.
+
+This example extends the shared generation guide. It uses an existing `images`
+accessor, DBOPFS-backed `modelStore`, application-selected `workingDirectory`
+and request `signal`:
+
+```javascript
+import {createBrowserModelSource} from 'arcane-os/ai/browser-wasm';
+import {prepareCoreModelAssets} from 'arcane-os/ai/core-model-assets';
+
+const selected = (await images.inspect({signal})).models.find(
+    function selectedSDXL(model) {
+        return model.id === 'sdxl-base-1.0';
+    }
+);
+const resource = selected.resources.model;
+const source = createBrowserModelSource({
+    id: selected.id,
+    files: [{name: resource.filename, url: resource.url}]
+});
+const stored = await modelStore.ensure(source, {signal});
+const projection = await prepareCoreModelAssets({
+    workingDirectory,
+    members: source.files.map(function workingMember(member, index) {
+        return {path: member.name, file: stored.files[index]};
+    }),
+    signal
+});
+
+try {
+    await images.load({
+        model: selected.id,
+        assetProjectionId: projection.id,
+        resourcePaths: {model: resource.filename},
+        signal
+    });
+} finally {
+    await projection.release();
+}
+
+const result = await images.generate({
+    model: selected.id,
+    prompt: 'An octopus librarian shelving tiny books inside a glass submarine.',
+    signal
+});
+// Display result.images using the shared guide's Blob preview example.
+```
+
+Change the prompt to request another scene. The model defaults to a
+1024-by-1024 canvas; pass `parameters: {width, height}` to select other native
+dimensions. Display or save every returned image using its actual width and
+height. Each result contains the complete PNG Blob.
+
+Successful loading retains the working projection in the native model owner.
+Releasing the caller's preparation handle preserves that native retain.
+Repeated generation reuses the loaded context; unload it when the application
+no longer needs it. Follow the shared lifecycle contract for request
+cancellation, state subscriptions, unloading and accessor closure.
+
+## Defaults and operation scope
+
+Only canvas dimensions are model-specific defaults here. Sampling parameters
+remain owned by the selected native engine and can be supplied through
+`parameters.sample_params`. At `master-929-3f8527a`, SDXL resolves the native
+default sampler to Euler A and scheduler to discrete, with 20 steps and CFG 7.
+These are native defaults; Stability AI's separate base-plus-refiner example
+and Python pipeline have their own sampling configuration.
+
+The selected engine has an explicit path for SDXL's embedded original VAE,
+including its native convolution scaling. The model definition leaves that
+treatment with the engine and supplies no guessed weight-type override or
+separate VAE checkpoint. Output quality, speed and device behavior depend on
+the actual selected runtime and generation parameters.
+
+The SDK forwards the complete caller prompt to the native API. The engine
+applies its own text conditioning and prompt-weighting syntax; see the shared
+guide for native string-boundary limitations. The SDK adds no avatar wording,
+style instructions or application-specific content.
+
+This definition advertises `txt2img`. Whole-image editing, masked editing and
+reference-image editing are separate operations with their own model and
+runtime requirements. This base selection does not advertise those operations.
+
+The model resource and standalone use follow the
+[official model card](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/462165984030d82259a11f4367a4eed129e94a7b/README.md).
+Native defaults and embedded-VAE behavior follow the selected engine's
+[request implementation](https://github.com/leejet/stable-diffusion.cpp/blob/master-929-3f8527a/src/pipeline/request.cpp),
+[parameter initialization](https://github.com/leejet/stable-diffusion.cpp/blob/master-929-3f8527a/src/stable-diffusion.cpp)
+and [model construction](https://github.com/leejet/stable-diffusion.cpp/blob/master-929-3f8527a/src/pipeline/model_builders.cpp).

package/docs/reference/local-whisper.md

@@ -0,0 +1,219 @@
+# Native Whisper transcription
+
+Arcane runs `whisper.cpp` through a persistent native helper. A selected model
+stays loaded across recordings. The helper reports actual model readiness,
+native progress and timestamped segments, and completes cancellation before
+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.
+
+## Select the runtime and model
+
+An application's `arcane-app.json` selects native speech alongside its other
+independent local runtimes:
+
+```json
+{
+  "native": {
+    "localAI": {
+      "runtimes": [
+        {
+          "id": "whisper.cpp",
+          "backend": "auto",
+          "models": ["whisper-small"]
+        }
+      ]
+    }
+  }
+}
+```
+
+The equivalent package configuration is `arcane-package.json`'s `localAI`.
+Existing unrelated descriptor fields remain part of the application's file.
+`models` defaults to an empty array, so selecting the runtime alone acquires no
+model. A single selected model becomes `modelId`; multiple models require an
+explicit selected `modelId` before transcription. The built-in `whisper-small`
+descriptor selects the official `ggerganov/whisper.cpp` `ggml-small.bin` model.
+An explicit model descriptor is `{id, path}` or `{id, url, filename?}`.
+
+Default Windows x64 preparation acquires the selected complete upstream
+Whisper 1.9.4/b5130 CUDA 12.4 and CPU distributions, FFmpeg 9.0.2 essentials,
+the selected model, and Arcane's helper asset from the matching SDK numeric
+release. The Windows helper includes its selected Visual C++ release runtime
+DLLs beside the executable. Preparation shares matching installation jobs, observes cancellation,
+and preserves the complete selected runtime trees. Model-selection changes
+can reuse the already prepared runtime and matching models.
+
+With `backend: "auto"`, accelerated runtimes are attempted before CPU. Failure
+to load an accelerated runtime falls back to the prepared CPU runtime. If
+native accelerated inference fails, Arcane drains that context and retries the
+complete decoded recording once on CPU with the same model. Cancellation,
+input errors and observer errors do not trigger this retry. Explicit `cuda`,
+`metal` or `cpu` selections retain that chosen backend.
+
+During that accepted request's internal recovery, the engine reports
+`state: "recovering"`, `loaded: false`, and `busy: true`, with the same selected
+provider and model. It accepts no new transcription while the old context
+drains and the CPU context loads. Only actual CPU readiness restores `ready`.
+An explicitly unloaded, replaced, or closed model remains a cancellation
+boundary; internal recovery preserves the original request and its signal.
+
+`requestedBackend` identifies a preference. `observedBackend` and
+`backendEvidence` report native initialization evidence when available; they
+do not claim that every computation runs on the GPU. No driver or compiler is
+installed on application startup.
+
+## Core and development integration
+
+Development and generated native Core entries compose a
+[`createSpeechService`](./native-speech.md) with the selected Whisper engine.
+Speech preparation and model loading proceed independently of the page,
+chat and image services. Core publishes retained `speech.state` and per-request
+`speech.progress`; transcription availability follows the selected engine's
+actual loaded state. The shared service remains usable when only STT is
+selected, through `transcriptionAvailable` and `roles.stt`.
+
+The native bundle includes the helper, runtime libraries, decoder and selected
+model under its runtime directory beside the application executable. Those
+resources stay in the application bundle. They are not embedded into one
+Windows executable. The compiler and matching upstream headers are build-time
+requirements for the first-party helper only.
+
+Applications may continue using the existing Core call:
+
+```js
+const transcript = await client.speech.transcribe({
+    audioBase64,
+    mimeType: 'audio/webm',
+    model: 'whisper-small'
+}, {signal});
+console.log(transcript.text);
+```
+
+FFmpeg decodes the complete recorded media into mono 16 kHz PCM at the native
+transport boundary. The original recording remains untouched during the
+operation. Arcane imposes no recording-duration cap and does not trim the
+transcript. The upstream inference API's signed-integer sample argument is
+reported honestly if a recording cannot fit that native call; no audio is
+silently shortened. Complete operation files are removed only after decoder
+and native inference cleanup have completed.
+
+## Public engine API
+
+```js
+import {createWhisperRuntime} from 'arcane-os/local-ai/whisper';
+
+const stt = createWhisperRuntime({
+    runtime: preparedRuntime,
+    modelId: 'whisper-small',
+    temporaryDirectory: applicationSpeechDirectory,
+    onEvent: reportDiagnostic
+});
+const unsubscribe = stt.subscribe(renderModelState);
+await stt.load({signal});
+try {
+    const result = await stt.transcribe({audioBase64, mimeType, model: 'whisper-small'}, {
+        signal,
+        onProgress: renderTranscriptionProgress
+    });
+    console.log(result.text, result.segments);
+} finally {
+    unsubscribe();
+    await stt.close();
+}
+```
+
+`createWhisperRuntime(options)` performs no model load. `options.runtime` is a
+prepared descriptor returned by `ensureLocalAIRuntimes`; alternatively,
+`options.prepare({signal, onEvent})` lazily returns that descriptor during
+`load`. `temporaryDirectory` is required and belongs to the application.
+
+| Member | Contract |
+| --- | --- |
+| `current()` | Returns `providerId`, selected `modelId`, lifecycle `state`, `loaded`, `busy`, correlated `requestId` or null, requested/observed backend, evidence and any error. |
+| `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. |
+| `unload()` | Cancels and joins active load/transcription, releases the native context, and permits a later explicit load. |
+| `close()` | Joins shutdown and disposes this engine permanently. Repeated calls share the same shutdown. |
+
+One retained model processes one recording at a time; a simultaneous request
+receives `WHISPER_BUSY`. Model changes use `await stt.unload()` followed by
+`stt.load({modelId})`. The `ready` state remains `loaded: true` with `busy: true`
+during ordinary inference. Progress records include the native event plus
+`backend` and `attempt`, so a CPU retry remains distinguishable. Segment text
+is preserved in order. The final result is
+`{text, language, duration, segments: [{index, start, end, text}]}`; times are
+seconds and are native segment timestamps, not invented word timestamps.
+
+Full process diagnostics stay with `onEvent` and native process failures.
+Applications should use their selected inspection surface for those details
+and keep ordinary user status concise.
+An error snapshot retains the failed operation's `requestId` after `busy`
+becomes false, allowing the caller to correlate its actual pending response.
+A new request or model load supersedes that identity; unload and close clear
+it. No recording or request payload is retained by this correlation field.
+Progress callbacks may cancel through the supplied controller and return;
+they must not await the same transcription or its shutdown from inside its
+own output callback. Await those operations in the initiating owner instead.
+
+## Explicit runtimes and helper builds
+
+Windows, Linux and macOS host integration uses the same public engine and
+portable helper source. Automatic archive selection currently provides the
+Windows x64 distribution above. Other targets supply their complete selected
+runtime, decoder and compiled helper paths; their native execution requires
+verification on that actual platform. Android requires a host adapter for
+its process and library lifecycle.
+
+An explicit runtime requirement can supply:
+
+```js
+{
+    id: 'whisper.cpp',
+    version: '1.9.4',
+    backend: 'auto',
+    variants: [
+        {backend: 'cuda', root: cudaRuntimeDirectory, libraryDirectory: cudaLibraryDirectory},
+        {backend: 'cpu', root: cpuRuntimeDirectory, libraryDirectory: cpuLibraryDirectory}
+    ],
+    helperExecutable,
+    helperRoot,
+    decoderExecutable,
+    decoderRoot,
+    models: [{id: 'whisper-small', path: selectedModelPath}],
+    modelId: 'whisper-small'
+}
+```
+
+`libraryDirectory` belongs to its complete variant root. `decoderExecutable`
+belongs to `decoderRoot` (which defaults to its containing directory).
+`helperExecutable` similarly belongs to `helperRoot`; its complete directory
+tree is retained, including app-local native dependencies.
+Preparation copies those selected resources into its owned installation, and
+native packaging projects their paths relative to the application bundle.
+`helperUrl`, `helperVersion`, and `decoderUrl` allow an explicitly selected
+published distribution instead of local paths. Dependency permissions remain
+the caller's responsibility.
+
+```js
+import {buildWhisperHelper} from 'arcane-os/local-ai/whisper/build';
+
+const helper = await buildWhisperHelper({
+    runtime: {directory: runtimeLibraryDirectory, sourceDirectory: matchingUpstreamSource},
+    outputRoot: helperBuildDirectory,
+    signal,
+    onEvent: reportDiagnostic
+});
+```
+
+The builder runs CMake configure/build/install against the selected matching
+public upstream headers and runtime. Optional `cmake`, `generator`,
+`cmakeArgs` and `env` select the existing toolchain. It returns the helper
+`executable`, platform, architecture, runtime directory and complete build
+diagnostics. The helper's documented process contract is in
+[`native/README.md`](../../src/local-ai/whisper/native/README.md).
+On MSVC, CMake's installed runtime-library module adds release CRT files to
+the helper's `bin/` directory. `-DMSVC_REDIST_DIR=...` selects an existing
+redistributable directory when needed. Windows provides the Universal CRT;
+compiler tools and debug runtimes stay outside the application bundle.

package/docs/reference/native-speech.md

@@ -0,0 +1,163 @@
+# Native speech service
+
+`createSpeechService({stt, tts, signal} = {})` composes independently selected
+native speech engines into one Core service. It is the named and default export
+from `arcane-os/core/speech`.
+
+The host supplies an STT engine, a TTS engine, or both. Construction performs no
+installation, model download, model loading, or inference. Core registration
+exposes `speech.status`, `speech.transcribe`, and `speech.synthesize`; an
+operation whose engine was omitted rejects with `SPEECH_ENGINE_UNAVAILABLE`.
+The optional `signal` controls the service lifetime.
+
+```js
+import {createCoreRuntime} from 'arcane-os/core/runtime';
+import {createSpeechService} from 'arcane-os/core/speech';
+
+// The host prepares and constructs its selected transcription engine.
+const speech = createSpeechService({stt: transcriptionEngine});
+const core = createCoreRuntime({services: [speech]});
+core.start();
+```
+
+This service is the shared integration layer. It does not supply or install a
+Kokoro or Sherpa-ONNX engine. Engine preparation, model resources, device
+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.
+
+## Startup and status
+
+`start(context)` subscribes to each configured engine and starts their loads
+independently. It returns immediately, allowing Core and `speech.status` to
+respond while models load. A failure in one role leaves the other role usable.
+Each engine publishes the actual state of its selected model.
+
+`current()` and `speech.status` return the same snapshot:
+
+| Field | Meaning |
+|---|---|
+| `ready` | Both speech roles are available. A service configured with only STT or only TTS retains `ready: false`. |
+| `transcriptionAvailable` | The STT engine reports a loaded model in `ready` or `running` state, and the service is accepting work. |
+| `synthesisAvailable` | The equivalent independent TTS readiness. |
+| `status` | `created`, `ok`, `closing`, or `closed`. `ok` describes the operational service; model loading and failures are reported per role. |
+| `sttEngine`, `ttsEngine` | The configured engines' `providerId` values, or an empty string for an omitted engine. |
+| `roles.stt`, `roles.tts` | Each engine's complete current state plus the service's `available` boolean. |
+| `closed` | Whether the service has completed its shutdown attempt. Any engine cleanup failure remains observable. |
+
+An engine's state includes `providerId`, `modelId`, `state`, `loaded`, and
+`busy`, with its complete error or progress information when present. An
+omitted role has `state: 'unavailable'`, `loaded: false`, and `busy: false`.
+File presence, a spawned process, and a callable bridge do not establish loaded
+model readiness. Existing readiness consumers additionally recognize
+the engine IDs `whisper.cpp` and `kokoro-onnx`; another engine ID requires the
+corresponding consumer integration.
+
+## Events and subscriptions
+
+`subscribe(listener, {replay = true, signal} = {})` immediately delivers the
+current snapshot by default and returns an unsubscribe function. The optional
+subscription signal removes only that listener. Closed services can still
+replay their final snapshot. Promise rejections from listeners are reported
+through developer diagnostics.
+
+Changes are published through the SDK's existing event owner and Core as
+`speech.state`. A Core client observes them with
+`Arcane.events.on('speech.state', listener)`. Core's generic runtime replay
+does not replay custom speech state. A browser consumer should subscribe first,
+then request `Arcane.speech.status()`, retaining any newer event received while
+that initial request is pending.
+
+`speech.progress` carries `{requestId, role, status: 'Thinking', progress}`.
+The service emits `progress: {phase: 'accepted'}` synchronously when accepting
+a speech request. Subsequent progress is the selected engine's actual report;
+cancelled requests publish no later progress.
+
+## Engine interface
+
+Each supplied engine implements:
+
+- `current()` returning the actual selected-model state.
+- `subscribe(listener)` with immediate current-state replay and an unsubscribe
+  function.
+- `load({signal})`, resolving only after the constructor-selected model has
+  loaded. Independent engines may load concurrently.
+- `transcribe(request, {signal, onProgress, requestId})` for STT, or
+  `synthesize(request, {signal, onProgress, requestId})` for TTS. `requestId` is
+  the actual Core request's control metadata, separate from the unchanged payload.
+- `close()`, cancelling and joining its native work and releasing its resources.
+
+The service forwards each complete request and result unchanged. It applies
+no input trimming, content limits, model or voice substitution, transcript
+rewriting, or audio conversion. The engine owns any format decoding,
+phonemization, required model segmentation, output encoding, and supported
+model selection. Necessary processing must preserve complete ordered input
+and output through that engine's public contract.
+
+## Cancellation and shutdown
+
+The request's `context.signal` reaches its engine together with the service's
+lifetime signal. A request waiting for its role's shared startup load can
+cancel promptly without cancelling another request or the other speech role.
+The retained startup load remains observed by the service. Queued and active
+inference cancellation belongs to the engine; it must stop the actual native
+operation and settle independently of service disposal.
+
+This matters because Core cancels and awaits active requests before calling
+service shutdown hooks. An engine that interrupts requests only in `close()`
+would prevent Core from reaching that cleanup hook.
+
+`close()` and `drain()` stop acceptance, abort the service lifetime, close both
+engines concurrently, and await their startup and request tasks. Repeated calls
+share one shutdown promise. Actual engine cleanup failures reject with an
+`AggregateError` and remain in role diagnostics. `dispose()` additionally
+releases the service's event subscriptions. New work after shutdown begins
+rejects with `CORE_CLOSING`.
+
+## AI built-in native speech readiness
+
+The `AI` module's `LOCAL_SPEACH` adapter observes `speech.state` before reading
+`Arcane.speech.status()`. A newer event takes precedence over an outstanding
+initial status response. Each role loads independently: STT does not wait for
+TTS, and unmuting waits for the selected TTS model rather than a callable facade.
+
+For this service's role snapshots, readiness requires the exact selected
+`modelId`, its engine identity, `loaded: true`, `available: true`, and a `ready`
+or `running` state. Model loading remains an ordinary cancellable waiting state.
+An engine error, unavailable role, or different selected model rejects the
+adapter load. Later readiness loss or engine/model replacement invalidates the
+AI role and cancels its queued and active requests through the existing provider
+runtime. A new explicit role load or unmute can observe the next ready state.
+
+An engine can report `state: 'recovering'`, `loaded: false`, `busy: true`, and
+the continuing Core `requestId` while retrying an already accepted request on
+the same selected provider and model. Availability remains false. The built-in
+STT adapter preserves only its own correlated pending request through this
+state; another caller's recovery supplies no continuation authority. The real
+RPC ID comes from `Arcane.speech.transcribe`'s optional `onRequest` observer.
+The engine retains that ID on a terminal error snapshot until the snapshot is
+superseded, allowing the pending RPC to deliver its actual complete failure
+rather than converting it into cancellation. True unload, close, replacement,
+transport loss and caller cancellation retain their existing ownership.
+
+The shared AI observation becomes `recovering` with `loaded: false`, `busy:
+true`, and its existing runtime `operationId`. An error may likewise retain
+`busy: true` until the actual operation settles. New inference still requires
+genuine loaded readiness. The STT provider request context includes a
+`refreshState()` callback which rereads that provider's status only while the
+exact request remains owned; it changes observation, not execution authority.
+Shared speech components retain their own real runtime operation through this
+recovery, keep new dispatch readiness-gated, and preserve native microphone
+capture's separate cancellation and final/interim lifetime.
+
+Older fixed-model hosts expose the published aggregate-only `SpeechStatus`
+contract instead of per-model lifecycle. The adapter preserves their independent
+health-based readiness for `whisper-small` with `whisper.cpp` and `kokoro` with
+`kokoro-onnx`, using `status: 'ok'` and the corresponding availability boolean.
+That contract is a one-shot health observation, not evidence of a persistently
+loaded native model or a continuous lifecycle event stream.
+
+Cancellation, unload, disposal, and route retirement release adapter-owned
+subscriptions. They do not close the host's shared engines or alter complete
+speech requests and results. Browser and explicitly registered speech providers
+retain their existing lifecycle contracts.

package/docs/reference/runtime-modules.md

@@ -1121,6 +1121,14 @@ work. Promise settlement proves only that the provider's exposed request promise
 completed; provider-specific cancellation acknowledgement remains the selected
 provider's boundary.
 
+An STT provider's request context also supplies `refreshState()`. An engine
+lifecycle observer may call it to reread `provider.status()` while that exact
+request remains active. A recovering or failed pending request is observed as
+`loaded: false`, `busy: true`, with its existing runtime operation ID; the
+callback does not make a new request ready or change its supplied payload.
+After cancellation, unload, disposal, replacement, or settlement it has no
+effect on the retired request.
+
 Direct LLM `request()`, `chat()`, and `stream()` use the same message history,
 tool-declaration, emitted-call, all-choice, and ordered parallel-call contracts
 as the high-level AI API module, including one nonblank matching result for
@@ -1229,13 +1237,17 @@ observable without exposing provider transports in application code.
 
 Exact exports: `AI_RUNTIME_INTENT_EVENT`, `AI_RUNTIME_PROTOCOL`,
 `AI_RUNTIME_ROLES`, `AI_RUNTIME_STARTUP_EVENT`, `AI_RUNTIME_STATES`,
-`AI_RUNTIME_STATE_EVENT`, `getAIRuntimeState`,
+`AI_RUNTIME_STATE_EVENT`, `continuesAIRuntimeOperation`, `getAIRuntimeState`,
 `publishAIRuntimeRoleState`, `publishAIRuntimeRolesState`,
 `requestAIRuntimeIntent`, `startAIRuntime`, `subscribeAIRuntimeIntents`, and
 `subscribeAIRuntimeState`.
 
 Each role record is exactly `{role,state,providerId,modelId,localOnly,loaded,
 busy,operationId,progress,error}`.
+`continuesAIRuntimeOperation(previous,current,operationId)` identifies the same
+already-owned provider/model/runtime operation in a busy, unloaded `recovering`
+or `error` observation. Pass the actual runtime operation ID, not a component's
+local counter. It grants neither readiness nor permission to start new work.
 `subscribeAIRuntimeState(listener,{signal=null,emitCurrent=true})` installs its
 subscription and synchronously replays the current mutable snapshot by default;
 `subscribeAIRuntimeIntents(listener,{signal=null})` is future-only. Both return
@@ -1251,7 +1263,9 @@ transcription-model load.
 ### Availability and normalization
 
 **Cross-host state contract.** States are `unavailable`, `unloaded`, `loading`,
-`ready`, `unloading`, `error`, and `disposed`. Revisions increase monotonically.
+`recovering`, `ready`, `unloading`, `error`, and `disposed`. Recovery remains
+`loaded: false`; `recovering` and `error` may retain `busy: true` with an actual
+`operationId` until the pending request settles. Revisions increase monotonically.
 The events `arcane-ai-runtime-state`, `arcane-ai-runtime-intent`, and
 `arcane-ai-runtime-startup-settled` normalize observation only: receiving one
 does not grant a native capability, prove browser support, or load a provider.