arcane-os 0.63.0 → 0.65.0

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

@@ -41,6 +41,17 @@ model's resource metadata; runtime installation does not independently download
 or bundle model files. The shared model asset owner prepares selected browser
 assets and supplies a Core working projection for native path-based loading.
 
+`flux2-klein-4b` selects the three-resource distilled FLUX.2 Klein definition.
+Its [family guide](local-image-flux.md) covers diffusion/VAE/Qwen preparation,
+four-step defaults and the advertised `txt2img` operation. Keep each model's
+supported operations distinct: selecting FLUX does not enable reference-image
+editing or imply the same input path as SD1.4 img2img.
+
+`sdxl-base-1.0` selects the complete SDXL Base checkpoint, including its text
+encoders and original VAE. Its [family guide](local-image-sdxl.md) covers the
+single model resource, 1024-by-1024 default canvas and native sampling defaults.
+It advertises `txt2img`; selecting it does not enable an editing operation.
+
 The first published distribution path selects CPU on Windows and Linux.
 On macOS, `auto` selects the same upstream universal runtime's built-in Metal
 backend, with CPU fallback; explicit `cpu` remains available. A caller-supplied

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

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

package/docs/reference/local-whisper.md

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

package/docs/reference/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.