arcane-os 0.63.0 → 0.65.0

package/docs/reference/native-speech.md

@@ -82,8 +82,9 @@ Each supplied engine implements:
   function.
 - `load({signal})`, resolving only after the constructor-selected model has
   loaded. Independent engines may load concurrently.
-- `transcribe(request, {signal, onProgress})` for STT, or
-  `synthesize(request, {signal, onProgress})` for TTS.
+- `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
@@ -112,3 +113,51 @@ 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-components.md

@@ -1742,6 +1742,14 @@ owner, and the voice control retains its state-specific labels and retry action.
 Desktop speech and the dedicated `voice-transcription.html` component retain their
 existing behavior.
 
+An already accepted file transcription retains its exact owned runtime
+operation through the same provider/model's unloaded, busy `recovering` state
+or correlated pending error. This preserves the actual RPC result or failure;
+it does not enable another recording. Unload, close, provider/model replacement,
+transport loss and caller cancellation still invalidate owned work. Native Web
+Speech microphone capture keeps its independent readiness and final/interim
+cancellation lifetime. See [native speech recovery](native-speech.md).
+
 On desktop, the Hold to talk control remains disabled unless sticky STT state
 is `ready`, the role is not busy, and microphone capture is available. For an explicitly
 selected STT route, a separate keyboard-operable control presents Start
@@ -2115,7 +2123,16 @@ Unknown provider/runtime diagnostics remain complete in the developer console
 and error events, while controls use generic visible outcomes unless the Error
 owner explicitly marks nonblank copy with `userSafe:true`.
 
-For the default manual mode, if sticky readiness is lost during microphone acquisition, capture, or the STT
+An already accepted file transcription can continue through the exact same
+provider/model/runtime operation's unloaded, busy recovery or pending-error
+state. This uses the real runtime operation ID rather than the component's local
+counter; another request supplies no continuation authority. New recording and
+transcription remain readiness-gated, and actual unload, close, replacement,
+transport loss or cancellation still ends the owned request. The same shared
+rule applies to an active continuous file-transcription job. Native Web Speech
+capture retains its separate readiness, stop/final-drain and interim ownership.
+
+Outside that exact continuing request, if sticky readiness is lost during microphone acquisition, capture, or the STT
 request, the component invalidates the session, aborts the owned request signal,
 releases media, discards late completion, and emits
 `speech-transcription-cancelled`. Its source-local reason is

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.
@@ -3213,9 +3227,17 @@ Validates and canonicalizes the syntax of Ollama model identifiers without grant
 
 ### Public surface
 
-`normalizeOllamaModelIdentifier()`, `isOllamaModelIdentifier()`.
+`normalizeOllamaModelIdentifier()`, `isOllamaModelIdentifier()`,
+`sameOllamaModelIdentifier(left, right)`.
+
+Exact exports: `isOllamaModelIdentifier`, `normalizeOllamaModelIdentifier`,
+`sameOllamaModelIdentifier`.
 
-Exact exports: `isOllamaModelIdentifier`, `normalizeOllamaModelIdentifier`.
+The comparison helper applies Ollama's default registry (`registry.ollama.ai`),
+namespace (`library`) and tag (`latest`) with case-insensitive name comparison.
+It compares a selected name with resident-model names without rewriting either
+string or any outbound payload; different explicit hosts, namespaces or tags
+remain distinct. The existing identifier-validation functions are unchanged.
 
 ### Availability and normalization