arcane-os 0.63.0 → 0.65.0

package/docs/reference/sdk-api.md

@@ -55,8 +55,12 @@ runtime layouts.
 | `arcane-os/core/contracts` | Shared Core protocol, frame, method and diagnostic error contracts. |
 | `arcane-os/core/classic-source` | Node generator for the canonical classic-script Core client projection. |
 | `arcane-os/core/runtime` | App-neutral native Core dispatcher and service lifecycle. |
+| `arcane-os/core/development` | App-service composition and document-owned Core transport during source development, independently of local AI. |
 | `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/codex/app-server` | Explicit native Codex App Server session, complete live turns, server requests and recovery. |
+| `arcane-os/mcp/stdio` | Node MCP STDIO server for app-owned tools and static resources. |
+| `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 +73,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. |
@@ -381,6 +386,13 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `createCoreFacade()` | function | `arcane-os/core/client` | Core browser client | Browser and native WebView JavaScript hosts |
 | `installCoreClient()` | function | `arcane-os/core/client` | Core browser client | Browser and native WebView JavaScript hosts |
 | `getInstalledCoreClient()` | function | `arcane-os/core/client` | Core browser client | Browser and native WebView JavaScript hosts |
+| `subscribeCoreClient()` | function | `arcane-os/core/client` | Core browser client | Browser and native WebView JavaScript hosts |
+| `createDevelopmentCore()` | function | `arcane-os/core/development`, `arcane-os` | Core source development | Node on Windows, Linux and macOS; Android requires host adaptation |
+| `createCodexAppServerSession()` | function | `arcane-os/codex/app-server` | Native Codex sessions | Node with an explicitly selected Codex App Server executable |
+| `openCodexAppServerSession()` | function | `arcane-os/codex/app-server` | Native Codex sessions | Node with an explicitly selected Codex App Server executable |
+| `createMcpStdioServer()` | function | `arcane-os/mcp/stdio` | MCP STDIO | Node streams on Windows, Linux and macOS; Android needs host adaptation |
+| `MCP_PROTOCOL_VERSION` | constant | `arcane-os/mcp/stdio` | MCP STDIO | Node |
+| `McpProtocolError` | class | `arcane-os/mcp/stdio` | MCP STDIO | Node |
 | `createCoreClassicSource()` | function | `arcane-os/core/classic-source` | Core classic client projection | Node; generated source runs in browser and native WebView renderers |
 | `createCoreRuntime()` | function | `arcane-os/core/runtime` | Native Core runtime | Node on Windows, Linux and macOS native hosts; Android requires host adaptation |
 | `encodeCoreFrame()` | function | `arcane-os/core/stdio` | Native Core stdio transport | Node |
@@ -391,6 +403,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 +426,11 @@ 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 |
+| `createWhisperRuntime()` | function | `arcane-os/local-ai/whisper` | Core native speech | Node with a prepared matching helper, runtime, decoder and selected model |
+| `createWhisperRuntime default export` | function | `arcane-os/local-ai/whisper` | Core native speech | Same retained native engine factory |
+| `buildWhisperHelper()` | function | `arcane-os/local-ai/whisper/build` | Core native speech | Node with installed CMake/C++17 toolchain and matching Whisper source/runtime |
+| `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 |
@@ -4132,6 +4151,11 @@ inspection is distinct from executing them or verifying a browser deployment.
 
 Starts one owned browser development server with exact runtime/app route mappings and a caller-selected bind address.
 
+Source callers may pass `core`, a handle returned by
+[`createDevelopmentCore()`](#createdevelopmentcore). The server delegates the
+Core HTTP routes and closes that owner during shutdown. The existing internal
+`localAI` handle remains accepted; `core` takes precedence when explicitly supplied.
+
 HTTP and HTTPS serving use published `node-http-server` 10.0.0. The SDK
 selects source routes and supplies generated representations; the module owns
 static-file conditional GET/HEAD handling and response delivery. The SDK
@@ -4652,6 +4676,14 @@ async function usedescribeTargets(...arguments_) {
 
 Starts one owned browser development server for the selected application.
 
+The selected descriptor's `native.services` composes application Core services
+independently of local AI. Programmatic `serviceModules:[{module,options}]`
+replaces that list; `services` adds constructed service definitions and `context`
+supplies app-owned launch fields. The result adds `core` when composed and retains
+`localAI` for selected native local AI. Page rendering and the listener do not
+wait for service readiness. See [source-development Core](core-development.md)
+for explicit `/arcane-core.js` loading, cancellation and current-state replay.
+
 `http`, `https`, `certPath`, `keyPath`, and `tls` follow the
 [`startDevServer()` transport contract](#startdevserver), alongside `host`, `port`, and
 `httpPort`. By default, `port` selects HTTPS and `httpPort` selects the HTTP `308`
@@ -7056,6 +7088,46 @@ const client = getInstalledCoreClient();
 console.log(client ? client.runtime.current() : 'No SDK client is installed.');
 ```
 
+## subscribeCoreClient()
+
+### Overview
+
+Observes the selected global's SDK client installation without creating a
+transport or delaying rendering. Applications can subscribe before independently
+loaded development or native bootstrap code installs the client.
+
+### Signature and result
+
+```text
+subscribeCoreClient(listener,{global=globalThis,emitCurrent=true,signal}={})
+```
+
+Import from `arcane-os/core/client`. Returns an idempotent unsubscribe function.
+The listener receives `{client,previousClient,reason,error}` with the exact
+client and error objects. Reasons are `current`, `installed`, `closed` and
+`transport-failed`. Current state replays synchronously unless disabled; an
+already-aborted signal registers nothing. Close or terminal failure releases
+the prior installation before notification. A reentrant replacement is retained.
+
+### Availability and normalization
+
+**Browser and native WebView JavaScript hosts.** Installation is distinct from
+Core, service or model readiness. Read `client.runtime.current()` and subscribe
+to that client's authoritative runtime/service events for those states. This
+observer starts no service and uses the shared event owner, not polling. See
+[Core client](core-client.md) and [source-development Core](core-development.md).
+
+### Example
+
+```javascript
+import {subscribeCoreClient} from 'arcane-os/core/client';
+
+const unsubscribe = subscribeCoreClient(function installationChanged({client}) {
+    console.log(client ? client.runtime.current() : 'Core is not installed.');
+});
+// The application owner calls unsubscribe() when this observer is retired.
+```
+
 ## createCoreClassicSource()
 
 ### Overview
@@ -7096,6 +7168,93 @@ const source = await createCoreClassicSource({
 nativeHost.setDocumentCreatedScript(source);
 ```
 
+## createCodexAppServerSession()
+
+Import from `arcane-os/codex/app-server`. Creates a synchronous session handle
+without starting a process. `connect()` starts the caller-selected executable
+and completes native JSONL initialization. The session owns explicit thread
+creation/resumption, complete native requests, live turn callbacks, exact-turn
+completion, interruption, real server-request replies and process retirement.
+Application-owned prompts, approvals and display policy stay with the caller.
+It neither attaches to desktop chats nor installs or authenticates Codex.
+See the complete [session options, methods, events, results, errors and recovery
+contract](codex-app-server.md).
+
+## openCodexAppServerSession()
+
+Import from `arcane-os/codex/app-server`. Creates the same session, awaits
+`connect()`, and returns it; failed opening disposes the owned process before
+rejecting. Prefer `createCodexAppServerSession()` when the caller must retain
+the handle during initialization. Neither factory creates or resumes a thread.
+See [connection ownership](codex-app-server.md#open-an-explicitly-selected-connection).
+
+## createMcpStdioServer()
+
+Import from `arcane-os/mcp/stdio`. Creates one optional Node STDIO session for
+application-owned tool and static-resource descriptors. `start()` attaches
+caller-owned streams; handlers receive complete arguments and return explicit
+MCP result containers. Requests run independently; protocol output writes are
+ordered. Normal EOF and `close()` drain accepted work. Cancellation is
+cooperative, and transport failures remain observable through `closed`.
+See [options, handlers, methods, errors and supported profile](mcp-stdio.md).
+
+## MCP_PROTOCOL_VERSION
+
+Import from `arcane-os/mcp/stdio`. The supported initialization profile is
+exactly `'2025-11-25'`. This does not claim later profiles or every optional
+capability. See [protocol support](mcp-stdio.md#mcp_protocol_version).
+
+## McpProtocolError
+
+Import from `arcane-os/mcp/stdio`. `new McpProtocolError(code,message,data)`
+represents an explicit JSON-RPC error with complete message and optional data.
+Ordinary domain tool failures use an explicit `CallToolResult` with `isError`.
+See [error outcomes](mcp-stdio.md#mcpprotocolerror).
+
+## createDevelopmentCore()
+
+### Overview
+
+Composes application-selected Core services and the SDK-owned development HTTP
+transport independently of local AI. Import from `arcane-os/core/development`
+or `arcane-os`; ordinary applications normally use `developApplication()` with
+their descriptor's `native.services`.
+
+### Signature and result
+
+`createDevelopmentCore({appRoot=process.cwd(),application,version,services=[],serviceModules=[],context={},getReplayEvents,signal,onEvent}={})`
+returns `{ready,handler,current,close}` synchronously. Module default factories
+receive unchanged `(options,context)`. `ready` reports composed dispatcher
+startup, not readiness of every service. `current()` returns complete
+`{state,error,core}`; `handler(request,response)` owns `/rpc`, `/events` and both
+bootstrap aliases; idempotent `close()` joins accepted service work and output.
+
+### Availability and example
+
+Node on Windows, Linux and macOS. Browser callers use the public Core client.
+Android needs its host adapter. This adds no cross-process host discovery.
+
+```javascript
+import {createDevelopmentCore, startDevServer} from 'arcane-os';
+
+const core = createDevelopmentCore({
+    appRoot: process.cwd(),
+    serviceModules: [{module: 'bridge/moon-cheese.mjs', options: {shelf: 'Lunar cheddar'}}]
+});
+let server;
+try {
+    server = await startDevServer({workspaceRoot: process.cwd(), core});
+    await server.closed;
+} finally {
+    await core.close();
+}
+```
+
+The [complete guide](core-development.md) defines document cancellation,
+service-lifetime drain, diagnostics, optional explicit service snapshots and
+non-blocking page bootstrap. App policy and explicit native process activation
+remain app-owned.
+
 ## createCoreRuntime()
 
 ### Overview
@@ -7421,12 +7580,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 +7846,71 @@ 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,write,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).
+
+`write({files:[{path,content}],message,signal})` snapshots the exact selected
+strings, writes those repository-relative files, commits only their literal
+paths and performs an ordinary non-force push. It retains unrelated staged
+paths and existing Git filters/hooks. Results and causal failures distinguish
+confirmed local writes, commits, pushes and uncertain attempted side effects;
+complete process output is retained. See [the complete writer outcome
+contract](core-repositories.md#write-commit-and-push-selected-text).
+
+```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 +8116,181 @@ selected model and native engine.
 The default export from `arcane-os/core/image` is the same
 `createLocalImageService` factory and lifecycle described above.
 
+## createWhisperRuntime()
+
+### Overview
+
+Creates one retained native Whisper engine from a prepared runtime or a lazy
+preparation function. Construction starts no helper, model load or inference.
+Import the named factory from `arcane-os/local-ai/whisper`.
+
+### Syntax and inputs
+
+```javascript
+createWhisperRuntime({runtime, prepare, modelId, temporaryDirectory, onEvent}={})
+```
+
+Supply `runtime` or `prepare({signal,onEvent})`, and an application-owned
+`temporaryDirectory`. `modelId` selects a model from the prepared runtime;
+omitting it uses the runtime's selected model. `onEvent` receives complete
+native preparation/process diagnostics. The runtime describes matching helper,
+Whisper backend libraries, decoder and model files; see the complete
+[native Whisper preparation contract](local-whisper.md).
+
+### Returned members and lifetime
+
+| Member | Contract |
+| --- | --- |
+| `current()` | Returns `providerId`, `modelId`, `state`, `loaded`, `busy`, `requestId`, `requestedBackend`, `observedBackend`, `backendEvidence` and `error`. State reports actual helper/model readiness. |
+| `subscribe(listener,{replay=true,signal}={})` | Observes the current snapshot immediately by default, then each state change; returns the unsubscribe closure. |
+| `load({modelId,signal}={})` | Prepares the selected runtime if necessary and retains its initialized helper/model. Same-model loading is shared; replacement remains explicit. |
+| `transcribe(request,{signal,onProgress,requestId}={})` | Accepts the complete `{audioBase64,mimeType?,model?,language?,translate?}` recording for the loaded model and returns `{text,language,duration,segments}`. `audioBase64` transports the original media; the decoder recognizes its actual format. Progress is ordered; control metadata stays outside the request. |
+| `unload()` | Cancels owned loading/transcription, joins decoder/helper work and releases the retained model before resolving its state snapshot. |
+| `close()` | Performs joined unload and disposes state observation. Repeated calls share the closing result. |
+
+The decoder consumes the complete submitted media into native 16 kHz mono PCM
+without changing the caller's recording. The result preserves the engine's
+complete text and segment order. Temporary operation files remain until decoder
+and inference settle. The engine accepts one active recording; overlapping
+requests report `WHISPER_BUSY`, and unavailable/closing/model failures retain
+their explicit diagnostics. Caller cancellation retains its supplied reason.
+
+With `backend: 'auto'`, an eligible accelerated native failure may drain that
+helper and retry the same complete recording and selected model once on the
+prepared CPU backend. Its snapshot is `recovering`, unloaded and busy during
+recovery. Cancellation, malformed input, observer/protocol failure and explicit
+backend selection do not cause that retry. `requestId` is the actual optional
+transport correlation, never a generated replacement or payload field; it
+remains through terminal error settlement and clears or changes on the next
+request/load/unload/close. The [shared speech adapter](native-speech.md) preserves
+only that continuing owned request, while new requests require actual readiness.
+
+### Availability and example
+
+Node on Windows, Linux and macOS with matching native resources; Android needs
+the corresponding host/process adaptation. Prepared files establish resource
+availability, not execution on every platform. This uses an already prepared
+runtime and the application's own temporary directory:
+
+```javascript
+import {createWhisperRuntime} from 'arcane-os/local-ai/whisper';
+import {createSpeechService} from 'arcane-os/core/speech';
+
+const stt = createWhisperRuntime({runtime, modelId: 'whisper-small', temporaryDirectory});
+const speech = createSpeechService({stt});
+// Register speech with the existing Core owner; it owns start/drain/dispose.
+```
+
+## createWhisperRuntime default export
+
+The default binding from `arcane-os/local-ai/whisper` is identical to the named
+[`createWhisperRuntime()`](#createwhisperruntime) factory and has the same inputs,
+members, readiness, cancellation and native-resource requirements.
+
+## buildWhisperHelper()
+
+`buildWhisperHelper({runtime,outputRoot,cmake='cmake',generator,cmakeArgs=[],env,
+signal,onEvent}={})` from `arcane-os/local-ai/whisper/build` builds the first-party
+persistent helper using the installed native toolchain. `runtime.directory`
+selects the prepared libraries and `runtime.sourceDirectory` selects their
+matching headers; `outputRoot` owns build/install output. Optional CMake
+arguments, generator and environment remain caller-selected.
+
+The operation runs configure, Release build and install in order. It returns
+`{platform,architecture,root,executable,runtimeDirectory,diagnostics}`, with
+complete `configure`, `compile` and `install` process results. Cancellation and
+process errors use the existing owned process lifetime. It installs neither a
+toolchain nor a model and performs no inference. Windows helper installation
+includes the selected compiler's redistributable runtime closure. Use a
+toolchain and prepared runtime matching the target platform/architecture; a
+source package alone is not a compiled helper. See the [helper build procedure](local-whisper.md).
+
+## 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.65.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -59,8 +59,12 @@
     "./core/contracts": "./browser-runtime/core/contracts.mjs",
     "./core/classic-source": "./src/core-classic-source.mjs",
     "./core/runtime": "./src/core/runtime.mjs",
+    "./core/development": "./src/core/development.mjs",
     "./core/stdio": "./src/core/stdio.mjs",
     "./core/host": "./src/core/host.mjs",
+    "./codex/app-server": "./src/codex/app-server.mjs",
+    "./mcp/stdio": "./src/mcp/stdio-server.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 +77,9 @@
     "./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",
+    "./local-ai/whisper/openvino-build": "./src/local-ai/whisper/openvino-build.mjs",
     "./integrated-provider": "./src/integrated-provider-loader.mjs",
     "./packager": "./src/packager/core.mjs",
     "./release-bundle": "./src/release-bundle.mjs",
@@ -114,7 +121,7 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/conversation-closing-report.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/native-windows-icon.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-host.test.mjs test/core-packaged-web.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/local-image-editing.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/ai-ollama-readiness.test.mjs test/core-ollama-lifecycle.test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/codex-app-server.test.mjs test/mcp-stdio-server.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-client-installation.test.mjs test/core-development.test.mjs test/core-host.test.mjs test/core-packaged-web.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/local-image-editing.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-macos-provider.test.mjs test/native-plan.test.mjs test/native-portable-provider.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/html-import-packaged-script.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",

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();