arcane-os 0.63.0 → 0.64.0

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

@@ -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-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.

package/docs/reference/sdk-api.md

@@ -57,6 +57,7 @@ runtime layouts.
 | `arcane-os/core/runtime` | App-neutral native Core dispatcher and service lifecycle. |
 | `arcane-os/core/stdio` | Framed Node stdio transport with graceful runtime drain. |
 | `arcane-os/core/host` | Node-only reusable Core host lifecycle with explicitly supplied services. |
+| `arcane-os/core/repositories` | Native persistent ArcaneData paths and explicitly selected connected working repositories. |
 | `arcane-os/core/packaged-web` | Core-owned packaged web listener with a persisted loopback origin and ready/failure events. |
 | `arcane-os/core/preferences` | Existing preference RPC methods with an application-selected file, ordered writes and owned drain. |
 | `arcane-os/core/diarization` | Lazy native speaker-diarization service, explicit stream methods and lifecycle/result events. |
@@ -69,6 +70,7 @@ runtime layouts.
 | `arcane-os/local-ai/image` | Retained native stable-diffusion.cpp context, complete PNG generation and owned worker lifetime. |
 | `arcane-os/ai/core-image` | Browser image lifecycle and complete PNG Blobs through an available Core service. |
 | `arcane-os/core/image` | Native image Core service with independent runtime preparation and retained model ownership. |
+| `arcane-os/core/speech` | Independent injected STT/TTS engine loading, request cancellation and joined Core service lifetime. |
 | `arcane-os/ai/core-model-assets` | Complete stored browser model members projected through Core into native working files. |
 | `arcane-os/core/model-assets` | Native working-file preparation, engine retain handles and joined cleanup. |
 | `arcane-os/integrated-provider` | Fixed integrated shared-development provider. |
@@ -391,6 +393,8 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `arcaneNativeBuilderProvider default export` | singleton | `arcane-os/native/portable-provider` | Portable native provider | Node; produces a portable payload rather than an executable host |
 | `startCoreHost()` | function | `arcane-os/core/host` | Native Core host composition | Node with readable input and writable output streams |
 | `readCoreLaunchContext()` | function | `arcane-os/core/host` | Native Core host composition | Node; reads explicitly selected launch JSON |
+| `resolveArcaneDataPaths()` | function | `arcane-os/core/repositories` | Native repository workspaces | Node on Windows, Linux and macOS; Android supplies its data root |
+| `createRepositoryWorkspace()` | function | `arcane-os/core/repositories` | Native repository workspaces | Node with Git; Android requires host process adaptation |
 | `createWindowsNativeProvider()` | function | `arcane-os/native/windows-provider` | Windows native provider | Node assembly; Windows x64/WebView2 execution |
 | `arcaneNativeBuilderProvider` | singleton | `arcane-os/native/windows-provider` | Windows native provider | Node assembly; Windows x64/WebView2 execution |
 | `arcaneNativeBuilderProvider default export` | singleton | `arcane-os/native/windows-provider` | Windows native provider | Node assembly; Windows x64/WebView2 execution |
@@ -412,6 +416,8 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `createCoreImageRuntime()` | function | `arcane-os/ai/core-image` | Core local images | Browser with an available Core image service |
 | `createLocalImageService()` | function | `arcane-os/core/image` | Core local images | Node Core with selected stable-diffusion.cpp requirements |
 | `createLocalImageService default export` | function | `arcane-os/core/image` | Core local images | Same native image service factory |
+| `createSpeechService()` | function | `arcane-os/core/speech` | Core native speech | Node Core with explicitly supplied speech engines |
+| `createSpeechService default export` | function | `arcane-os/core/speech` | Core native speech | Same shared speech service factory |
 | `prepareCoreModelAssets()` | function | `arcane-os/ai/core-model-assets` | Core model assets | Browser with complete Blob/File members and available Core service |
 | `createModelAssetService()` | function | `arcane-os/core/model-assets` | Core model assets | Node Core with an application-selected working directory |
 | `createModelAssetService default export` | function | `arcane-os/core/model-assets` | Core model assets | Same native working-file service factory |
@@ -7421,12 +7427,23 @@ application builds. The build machine needs its normal Node/npm toolchain and
 The returned `arcane-native-builder/1` provider exposes `describe`, `doctor`,
 `prepare`, `build`, `verify` and `run`. Build returns `{app,target,manifest}`
 with the actual directory at `target.rootDir`. Verification reads the artifact;
-it does not launch the window. Run launches `Arcane.exe` and observes complete
-diagnostics and exit. Cancellation closes input and waits for host-owned drain,
+it does not launch the window. Run launches the executable recorded in the
+saved `manifest.host.executable` and observes complete diagnostics and exit.
+Cancellation closes input and waits for host-owned drain,
 including accepted service work, without a forced termination deadline. Missing
 prerequisites, download/extraction failures and host failures remain observable
 through the operation's error/event boundary.
 
+Assembly names the launcher from `appDescriptor.displayName` plus `.exe`,
+with a matching `.exe.config` file. Low-level compositions without a nonempty
+string display name use the app ID. Windows-reserved filename characters and
+control characters become underscores; reserved DOS device basenames receive
+an underscore prefix. Supported Unicode, spaces and case remain, as do the
+original descriptor and title. Icon embedding, file inventory, verification
+and run use this same name. Existing artifacts retain the executable recorded
+in their manifest; the reusable downloaded host retains `Arcane.exe` and
+`Arcane.exe.config`, and `runtime/ArcaneCore.exe` remains unchanged.
+
 During assembly, `appDescriptor.native.icon` selects the app's existing image.
 PNG and ICO inputs produce a derived `runtime/arcane-app.ico` and update only
 the copied application's executable icon. Source assets, the selected host
@@ -7676,6 +7693,63 @@ separate argument; other composing hosts may use the same seam. This JavaScript
 contract does not establish a compiled host or matching release archive. See
 [launch-time locations](core-native-packaging.md#launch-time-locations).
 
+## resolveArcaneDataPaths()
+
+### Overview
+
+Resolves the native per-user `ArcaneData` directory and its `Repos` child without
+creating directories or changing application state.
+
+### Signature and result
+
+```text
+resolveArcaneDataPaths({dataRoot}={})
+```
+
+Returns absolute `{dataRoot,repositoriesRoot}`. Defaults use Windows LocalAppData,
+Linux XDG data home or `~/.local/share`, and macOS user Application Support.
+Android and other adapted hosts supply their persistent `dataRoot`. An explicit
+root is used directly, with relative paths resolved from the process working
+directory. See [native repository locations](core-repositories.md#persistent-locations).
+
+```javascript
+import {resolveArcaneDataPaths} from 'arcane-os/core/repositories';
+
+const {repositoriesRoot} = resolveArcaneDataPaths();
+```
+
+## createRepositoryWorkspace()
+
+### Overview
+
+Owns one native connected working checkout under `ArcaneData/Repos/<name>` or an
+explicit existing path. The application owns the remote, branch and Core API.
+
+### Signature and result
+
+```text
+createRepositoryWorkspace({name,directory,dataRoot,remote,branch,onEvent,run=runProcess}={})
+```
+
+Returns `{directory,open,status,pull,push,close,drain,dispose}`. Construction does
+no I/O. Operations accept `{signal}`; a missing or empty destination clones once,
+while existing checkout files, branches, remotes and local changes remain intact.
+Same-directory calls are ordered within the process. Shutdown drains accepted
+work and preserves the checkout. No CLI cwd, launch state, preference, snapshot
+cache or existing user-data location changes. See the [complete inputs, results,
+errors and lifecycle](core-repositories.md#one-connected-working-checkout).
+
+```javascript
+import {createRepositoryWorkspace} from 'arcane-os/core/repositories';
+
+const repository = createRepositoryWorkspace({
+    name: 'moon-cheese-dispatches',
+    remote: applicationConnection.remote
+});
+await repository.open({signal});
+await repository.close();
+```
+
 ## createCoreLocalAIProvider()
 
 ### Overview
@@ -7881,6 +7955,92 @@ selected model and native engine.
 The default export from `arcane-os/core/image` is the same
 `createLocalImageService` factory and lifecycle described above.
 
+## createSpeechService()
+
+### Overview and usage
+
+`createSpeechService({stt,tts,signal}={})` from `arcane-os/core/speech` composes
+independently selected STT and TTS engines as one Core service. Supply either
+role or both. Construction downloads, installs and loads nothing; the host
+owns engine creation, model/device selection and supported formats.
+
+```javascript
+import {createCoreRuntime} from 'arcane-os/core/runtime';
+import {createSpeechService} from 'arcane-os/core/speech';
+
+// transcriptionEngine is the host's already constructed, selected engine.
+const speech = createSpeechService({stt: transcriptionEngine});
+const core = createCoreRuntime({services: [speech]});
+core.start();
+```
+
+Each supplied engine exposes `current()`, replaying `subscribe(listener)`,
+`load({signal})`, `close()` and its role's
+`transcribe(request,{signal,onProgress})` or
+`synthesize(request,{signal,onProgress})`. The service forwards complete
+requests and results unchanged. Format decoding, model processing and encoding
+remain with that engine. This factory supplies no speech engine or automatic
+browser/native provider selection.
+
+### Members, results and events
+
+The returned object has `name: 'speech'`, `current`, `subscribe`, `close`,
+`start`, `methods`, `drain` and `dispose`:
+
+- `start(context)` subscribes and starts both configured engine loads
+  independently, returning immediately. Core and status remain responsive
+  during loading; one role's failure leaves the other usable.
+- `current()` and `methods['speech.status']()` return the same snapshot:
+  `ready`, `transcriptionAvailable`, `synthesisAvailable`, `status`,
+  `sttEngine`, `ttsEngine`, `roles.stt`, `roles.tts` and `closed`.
+  `ready` requires both roles; each independent availability flag requires
+  its model loaded in `ready` or `running` state while the service accepts work.
+  `status` is `created`, `ok`, `closing` or `closed`; per-role state carries
+  model loading, progress and complete errors. An omitted role is unavailable.
+- `subscribe(listener,{replay=true,signal}={})` replays current state by
+  default and returns an unsubscribe function. Its signal owns only that
+  subscription; a closed service can replay its final snapshot.
+- `methods['speech.transcribe'](request,context)` and
+  `methods['speech.synthesize'](request,context)` are registered as the matching
+  Core RPC methods. The context supplies `signal`, `requestId` and `emit`.
+  The service publishes synchronous accepted `Thinking` before waiting for
+  its role's load, then forwards the engine's complete progress and result.
+- `close()` and its `drain()` alias stop acceptance, abort the service lifetime,
+  close both engines concurrently and await startup and request work. Repeated
+  calls share one promise. `dispose()` also releases event subscriptions.
+
+`speech.state` carries the complete snapshot. `speech.progress` carries
+`{requestId,role,status:'Thinking',progress}` with initial
+`progress:{phase:'accepted'}`. The service's subscription replays state; Core's
+generic runtime replay does not replay this custom event. Browser consumers
+subscribe before requesting `Arcane.speech.status()` and preserve any newer
+state event received while that request is pending.
+
+### Cancellation, errors and availability
+
+The optional factory signal owns the service lifetime. A request signal is
+combined with that lifetime and reaches its selected engine. Cancelling one
+request waiting for a shared load settles that request without cancelling
+the other requests or role. No later cancelled progress or result is delivered.
+Actual queued/running native interruption belongs to the engine; it must settle
+before Core reaches service shutdown, because Core first cancels and awaits
+active requests.
+
+Invalid engine interfaces or listeners throw `TypeError`. Missing roles reject
+their operation with `SPEECH_ENGINE_UNAVAILABLE`; work after shutdown begins
+rejects with `CORE_CLOSING`. Engine errors remain observable, and engine cleanup
+failures reject shutdown with `AggregateError`. Asynchronous listener failures
+reach developer diagnostics. Engine platform support remains its own contract;
+this Node composition layer adds no engine dependency. Existing AI readiness
+consumers recognize `whisper.cpp` and `kokoro-onnx` IDs independently of the
+service's engine-neutral interface. See the [complete engine and lifetime
+contract](native-speech.md).
+
+## createSpeechService default export
+
+The default export from `arcane-os/core/speech` is the same
+`createSpeechService` factory, with identical inputs, results and lifecycle.
+
 ## prepareCoreModelAssets()
 
 `prepareCoreModelAssets({client=getInstalledCoreClient(),workingDirectory,members,signal?,onProgress?})`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.63.0",
+  "version": "0.64.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -61,6 +61,7 @@
     "./core/runtime": "./src/core/runtime.mjs",
     "./core/stdio": "./src/core/stdio.mjs",
     "./core/host": "./src/core/host.mjs",
+    "./core/repositories": "./src/core/repositories.mjs",
     "./core/packaged-web": "./src/core/services/packaged-web.mjs",
     "./core/preferences": "./src/core/services/preferences.mjs",
     "./core/diarization": "./src/diarization/service.mjs",
@@ -73,6 +74,8 @@
     "./local-ai": "./src/local-ai/install.mjs",
     "./local-ai/onnx": "./src/local-ai/onnx.mjs",
     "./local-ai/image": "./src/local-ai/image-runtime.mjs",
+    "./local-ai/whisper": "./src/local-ai/whisper/index.mjs",
+    "./local-ai/whisper/build": "./src/local-ai/whisper/build.mjs",
     "./integrated-provider": "./src/integrated-provider-loader.mjs",
     "./packager": "./src/packager/core.mjs",
     "./release-bundle": "./src/release-bundle.mjs",

package/runtime/arcane/components/speech.html

@@ -295,6 +295,7 @@
     const aiModuleImport = import('../modules/AI.js');
     const providerRuntimeImport = import('../modules/AIProviderRuntime.js');
     const {
+        continuesAIRuntimeOperation,
         requestAIRuntimeIntent,
         subscribeAIRuntimeState
     } = await import('../modules/AIRuntimeState.js');
@@ -366,6 +367,7 @@
     let ttsIntentGeneration = 0;
     let eventOperationSequence = 0;
     let transcriptionOperationId = null;
+    let transcriptionRuntimeOperationId = null;
     let ttsOperationId = null;
     let destroyed = false;
     let recognitionLanguage = is.string(host.recognitionLanguage)
@@ -826,8 +828,10 @@
 
     function applyRoleTransitions(previousSTTRole, previousTTSRole) {
         sttActivationController?.synchronize(sttRole);
-        const sttBecameUnready = previousSTTRole.state === 'ready'
-            && sttRole.state !== 'ready';
+        const continuingTranscription = transcriptionActive && !nativeCaptureSession
+            && continuesAIRuntimeOperation(previousSTTRole, sttRole, transcriptionRuntimeOperationId);
+        const sttBecameUnready = ['ready', 'recovering'].includes(previousSTTRole.state)
+            && sttRole.state !== 'ready' && !continuingTranscription;
         const ttsBecameUnready = previousTTSRole.state === 'ready'
             && ttsRole.state !== 'ready';
 
@@ -2011,10 +2015,16 @@
                 throw error;
             }
 
-            const transcription = await aiRuntime.fetchSTT(
+            const previousRuntimeOperationId = providerRuntime.status('stt').operationId;
+            const pendingTranscription = aiRuntime.fetchSTT(
                 audioFile,
                 controller.signal
             );
+            const activeRole = providerRuntime.status('stt');
+            transcriptionRuntimeOperationId = activeRole.busy
+                && activeRole.operationId !== previousRuntimeOperationId
+                ? activeRole.operationId : null;
+            const transcription = await pendingTranscription;
             if (
                 generation !== transcriptionGeneration
                 || sttRole.state !== 'ready'
@@ -2044,6 +2054,7 @@
         } finally {
             if (transcriptionAbortController === controller) {
                 transcriptionAbortController = null;
+                transcriptionRuntimeOperationId = null;
             }
             if (generation === transcriptionGeneration) {
                 transcriptionActive = false;
@@ -2144,6 +2155,7 @@
         transcriptionGeneration += 1;
         transcriptionAbortController?.abort();
         transcriptionAbortController = null;
+        transcriptionRuntimeOperationId = null;
         recordingRequested = false;
         transcriptionActive = false;
         clearSilenceTimer();