arcane-os 0.64.0 → 0.65.0

package/docs/reference/mcp-stdio.md

@@ -0,0 +1,263 @@
+# MCP STDIO server
+
+Expose application-owned tools and static resources to an MCP client with
+`arcane-os/mcp/stdio`. This optional Node entrypoint owns one JSON-RPC session,
+UTF-8 newline framing, discovery, request correlation, cooperative cancellation,
+and graceful drain. The application owns its launch command, tool definitions,
+resource contents, business behavior, and underlying service lifetime.
+
+Availability: Node on Windows, Linux, and macOS, using the package's supported
+Node version. Android requires a host that supplies the same Node stream and
+process environment. Importing the entrypoint starts no process or listener.
+It is separate from the native Core `arcane/1` transport and its Content-Length
+frames; the two stream formats are not interchangeable.
+
+## createMcpStdioServer
+
+```javascript
+import {createMcpStdioServer} from 'arcane-os/mcp/stdio';
+
+const menu = {
+    content: 'Moon soup\nExtra tentacles available.',
+    message: {chef: 'Octopus', open: true}
+};
+
+const server = createMcpStdioServer(
+    {
+        serverInfo: {name: 'moon-pantry', version: '1.0.0'},
+        instructions: 'Ask moon.menu for the complete lunar dinner menu.',
+        tools: [
+            {
+                name: 'moon.menu',
+                description: 'Read the complete lunar dinner menu.',
+                inputSchema: {type: 'object'},
+                annotations: {readOnlyHint: true},
+                handler: readMenu
+            }
+        ],
+        resources: [
+            {
+                uri: 'pantry://menu',
+                name: 'menu',
+                title: 'Lunar dinner menu',
+                mimeType: 'application/json',
+                handler: readMenuResource
+            }
+        ]
+    }
+);
+
+function readMenu(args, {signal}) {
+    signal.throwIfAborted();
+    return {
+        content: [{type: 'text', text: JSON.stringify(menu)}],
+        structuredContent: menu
+    };
+}
+
+function readMenuResource({uri}, {signal}) {
+    signal.throwIfAborted();
+    return {
+        contents: [{uri, mimeType: 'application/json', text: JSON.stringify(menu)}]
+    };
+}
+
+server.start();
+try {
+    await server.closed;
+} catch {
+    // The adapter already sent its diagnostic to stderr.
+    process.exitCode = 1;
+}
+```
+
+Save this in the consuming application and configure the MCP client's subprocess
+command as `node` with that application's script path. Client configuration
+file formats and process launch policy remain client-owned. Change `menu` to
+change the complete result; no model, repository, or native host is needed for
+this example.
+
+The application explicitly converts its domain record into an MCP result.
+The SDK does not guess from `content`, `message`, or other domain field names.
+The serialized text in this example is an application-selected representation;
+the SDK never adds it automatically.
+
+### Parameters
+
+`createMcpStdioServer(options)` returns a server object synchronously.
+
+| Option | Contract |
+| --- | --- |
+| `serverInfo` | Required MCP implementation object with `name` and `version` strings. Optional MCP implementation fields are passed through. |
+| `instructions` | Optional complete instruction string returned by initialization. |
+| `tools` | Optional static array; each entry is a complete MCP tool descriptor plus `handler(args, context)`. Defaults to `[]`. Tool names identify handlers exactly and must be unique. |
+| `resources` | Optional static array; each entry is a complete MCP resource descriptor plus `handler(params, context)`. Defaults to `[]`. Each resource requires `uri` and `name`; URIs identify handlers exactly and must be unique. |
+| `onDiagnostic` | Optional error observer. Omit it for complete error text on the selected stderr stream. It may return a promise, which participates in drain. Observer failures are reported to stderr and retained by `closed`. |
+
+The factory captures catalog entries at construction. Discovery preserves
+descriptor fields, including authored schemas, descriptions, annotations,
+icons, and metadata; only the local `handler` function is omitted. No tool
+arguments, descriptions, schemas, resources, or result content are injected,
+trimmed, rewritten, or shortened. Supply JSON-serializable protocol values.
+
+The SDK checks the request envelope and required result container. It does not
+provide a general JSON Schema evaluator. The application supplies a valid
+`inputSchema` object, owns the handler's input semantics, and ensures any
+declared `outputSchema` matches its structured result. This adapter does not
+implement task-augmented execution; descriptors must describe ordinary tool
+execution.
+
+### Handler inputs and results
+
+Tool handlers receive `params.arguments` unchanged. Omitted arguments become
+an empty object as the protocol's no-argument case. Resource handlers receive
+the complete `resources/read` params object, including its exact `uri` and
+any metadata. A handler may return its result directly or return a promise.
+
+Each handler receives a context with:
+
+- `signal`: its own request's `AbortSignal`;
+- `requestId`: the original string or integer ID, including numeric zero;
+- `method`: `tools/call` or `resources/read`;
+- `params`: the complete request params object;
+- `clientInfo` and `clientCapabilities`: the client's initialization objects.
+
+A tool handler returns an explicit MCP `CallToolResult`, including a `content`
+array and optional `structuredContent`, `isError`, `_meta`, or other protocol
+fields. All supplied content blocks and JSON fields pass through. Resource
+handlers return an explicit `ReadResourceResult` with a `contents` array;
+complete text or already encoded binary resource contents pass through.
+The application creates these protocol result objects deliberately. A plain
+domain object with `content: 'some text'` is not a `CallToolResult` and produces
+an internal protocol error rather than being silently converted.
+
+For a domain failure, return a complete `CallToolResult` with `isError: true`.
+An ordinary exception thrown by a tool handler becomes an `isError: true`
+text result containing the exception's complete message, and the complete
+exception is also reported through diagnostics. Throw `McpProtocolError` for
+an explicit JSON-RPC failure. Other resource or adapter exceptions produce
+`-32603` and a diagnostic; malformed result containers and non-serializable
+results also produce `-32603`.
+Custom fields on an ordinary thrown error remain in diagnostics unless the
+application explicitly maps its known outcome to `structuredContent` in an
+`isError: true` tool result.
+
+## start
+
+`server.start({input, output, error})` attaches to caller-owned Node streams and
+returns the same server. Defaults are `process.stdin`, `process.stdout`, and
+`process.stderr`. Start each server exactly once with an open readable input and
+open writable output/diagnostic streams. Output and diagnostics must be separate
+streams. Byte-mode input preserves split UTF-8 sequences; a stream already
+decoded into strings remains responsible for its own decoding.
+
+Messages are processed as their newline arrives, without waiting for EOF. A
+final complete JSON record is also accepted when EOF arrives without its final
+newline. LF and CRLF transport endings are accepted. JSON escaping preserves
+embedded line breaks in the decoded payload. Malformed JSON receives `-32700`;
+its complete original line is included in diagnostics. Invalid UTF-8 fails at
+the decoder and closes the transport with the complete affected input chunks
+and pending decoded text in its diagnostic error.
+
+Requests execute independently, including overlapping calls to one tool.
+Only complete output writes are ordered, waiting for each Node write callback
+before sending the next record. An error, close, or finish event during a pending
+output or diagnostic write settles that write as failed even when its callback
+never arrives; a later callback cannot settle it again. The application decides
+whether its own data access requires narrower serialization. The adapter adds
+no process-wide queue.
+
+Only JSON-RPC messages are written to `output`. Application handlers and their
+dependencies must also reserve stdout for protocol traffic; use stderr or the
+application's diagnostic owner for logs. The adapter does not replace global
+console functions.
+
+## cancel
+
+`server.cancel(requestId, reason)` requests cooperative cancellation and returns
+`true` only when an active cancellable handler was signalled. String and numeric
+IDs remain distinct. Unknown, completed, already cancelled, and initialization
+requests return `false`. The same behavior handles client
+`notifications/cancelled` messages. Late results from cancelled work have no
+protocol response, as described by the
+[MCP cancellation contract](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation).
+
+The handler must pass its signal to its actual I/O or computation and release
+owned resources. Signalling does not prove external work stopped. The adapter
+retains the handler promise until it really settles; a handler that ignores
+cancellation can keep drain and close pending.
+
+## drain
+
+`await server.drain()` waits for accepted handlers, diagnostic observers, and
+output write callbacks to settle. It does not stop input or abort requests, so
+newly accepted work can extend the wait. Use `close()` when input must first
+stop. Tool and request errors are delivered as protocol outcomes; transport and
+diagnostic delivery failures are retained by `closed`.
+
+## close
+
+`await server.close({cancelPending: false})` stops reading, pauses the input,
+drains accepted work and writes, detaches the adapter's stream listeners, and
+settles `closed`. It is idempotent. Normal input EOF follows this same graceful
+path. Explicit `cancelPending: true` aborts pending work instead; repeated close
+may request cancellation while an earlier graceful close is draining.
+
+Stream failures request cancellation, report diagnostics, and reject `closed`
+after owned work settles. An input closed without EOF is a transport failure.
+The adapter does not end or destroy caller streams, terminate the process,
+install process signal handlers, start an application host, or close
+application services. The launcher owns those actions after the adapter drains.
+
+## closed
+
+`server.closed` is a promise for actual session cleanup. It resolves after a
+normal close or EOF and rejects with an `AggregateError` when transport or
+diagnostic delivery failed. Observe it even when the initiating caller continues
+other work. Request failures alone do not close the session.
+
+## MCP_PROTOCOL_VERSION
+
+`MCP_PROTOCOL_VERSION` is exactly `'2025-11-25'`. Initialization always returns
+that supported version. A client proposing another version must accept this
+profile or disconnect. This is the initialize/initialized STDIO profile;
+support for later discovery-based profiles is not implied. See the normative
+[lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)
+and [STDIO transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports).
+
+Supported requests are `initialize`, `ping`, `tools/list`, `tools/call`,
+`resources/list`, `resources/read`, and `resources/templates/list` (an empty
+template catalog). Tools and resources capabilities are advertised when their
+catalogs are nonempty. Lists return their complete catalogs without pagination;
+supplying a cursor receives `-32602`. Send `notifications/initialized` after
+the initialization response before ordinary operations.
+
+There are no prompts, subscriptions, list-change events, MCP logging requests,
+server-to-client requests, sampling, elicitation, task augmentation, HTTP
+transport, or automatic client configuration. Unknown methods return `-32601`;
+notifications never receive responses. JSON-RPC batches are not part of this
+profile. IDs must be strings or integers and are unique for the session.
+
+The result shapes follow the official
+[tool](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
+and [resource](https://modelcontextprotocol.io/specification/2025-11-25/server/resources)
+contracts. This narrow adapter does not claim every optional MCP capability.
+
+## McpProtocolError
+
+`new McpProtocolError(code, message, data)` represents an explicit protocol
+failure. `code` is a JSON-RPC integer, `message` is its complete string, and
+optional `data` is JSON-serializable protocol detail. It extends `Error` and
+exposes `name`, `code`, `message`, and optional `data`.
+
+The adapter uses `-32700` for malformed JSON, `-32600` for invalid requests,
+`-32601` for unknown methods, `-32602` for malformed params or unknown tools,
+`-32603` for internal failures, and `-32002` for a missing resource. Its
+`-32000` lifecycle error requests initialization before ordinary operations.
+
+## Evidence boundary
+
+`test/mcp-stdio-server.test.mjs` contains focused in-memory stream fixtures for
+these contracts. Authored fixtures and source review do not establish an
+executed client integration or platform run. Run local tests only under the
+applicable explicit testing or selected-output authority.

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

@@ -3227,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`.
+Exact exports: `isOllamaModelIdentifier`, `normalizeOllamaModelIdentifier`,
+`sameOllamaModelIdentifier`.
+
+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
 

package/docs/reference/sdk-api.md

@@ -55,8 +55,11 @@ 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. |
@@ -383,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 |
@@ -417,6 +427,9 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `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 |
@@ -4138,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
@@ -4658,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`
@@ -7062,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
@@ -7102,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
@@ -7731,7 +7884,7 @@ explicit existing path. The application owns the remote, branch and Core API.
 createRepositoryWorkspace({name,directory,dataRoot,remote,branch,onEvent,run=runProcess}={})
 ```
 
-Returns `{directory,open,status,pull,push,close,drain,dispose}`. Construction does
+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
@@ -7739,6 +7892,14 @@ 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';
 
@@ -7955,6 +8116,95 @@ 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