arcane-os 0.2.1 → 0.2.3

package/docs/reference/ai/browser-wasm.md

@@ -9,7 +9,7 @@ page is the focused local-browser path beneath the normalized AI decision
 guide.
 
 The wiring example assumes a scaffolded or materialized Arcane application
-with SDK `0.1.2`'s authenticated runtime tree and 86-entry browser import map.
+with SDK `0.2.2`'s authenticated runtime tree and generated browser import map.
 `arcane/DBOPFS` is a managed browser-map specifier, not an npm package export.
 See [browser runtime delivery](../protocols.md#browser-runtime-delivery) before
 using the example in a custom host or bundler.
@@ -25,9 +25,17 @@ import {
 
 const MODEL = Object.freeze({
     id:'my-reviewed-model',
-    url:'https://models.example/revisions/4f7c/model-q4.gguf',
-    bytes:123456789,
-    sha256:'0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
+    files:Object.freeze([{
+        name:'model-q4-00001-of-00002.gguf',
+        url:'https://models.example/revisions/4f7c/model-q4-00001-of-00002.gguf',
+        bytes:123456789,
+        sha256:'0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
+    },{
+        name:'model-q4-00002-of-00002.gguf',
+        url:'https://models.example/revisions/4f7c/model-q4-00002-of-00002.gguf',
+        bytes:98765432,
+        sha256:'abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789'
+    }])
 });
 
 const dbopfs = globalThis.dbopfs || new DBOPFS({applicationId:'my-app'});
@@ -41,18 +49,23 @@ const ai = createArcaneAI({
     security:{secure:true}
 });
 
-// Put this behind an explicit user action: it can download MODEL.bytes bytes.
+// Put this behind an explicit user action: it can download every declared file.
 async function loadReviewedModel() {
-    return ai.load({threads:1, contextTokens:4096, gpuLayers:0});
+    return ai.load({threads:1, contextTokens:4096});
 }
 ```
 
 The browser-WASM runtime closure packages the authenticated
 `@wllama/wllama` `3.6.0` ESM and WebAssembly runtime plus the Wllama and
 llama.cpp MIT license texts. It
-packages no model weights, model catalog, CDN fallback, native provider, speech
-synthesis, or transcription. Callers supply the exact model authority. `bytes`
-is an optional expected positive byte length, not inline model data.
+packages no model weights, default model catalog, CDN fallback, native
+provider, speech synthesis, or transcription. The sibling
+[`arcane-os/ai/browser-speech`](browser-speech.md) entrypoint supplies speech
+provider mechanisms but still no runtime/model bytes. Callers supply every
+model-source authority. Each file's `bytes` is an optional expected positive
+byte length, not inline model data. The declared URL binds selection identity;
+exact byte identity is established only by the checks the caller enables and
+supplies.
 
 ## Lifecycle at a glance
 
@@ -67,6 +80,7 @@ is an optional expected positive byte length, not inline model data.
 | `ai.llm.chat(request)` / `ai.fetchRequest(request)` | Validated OpenAI-like completion. |
 | `ai.llm.stream(request)` | Frozen async-iterator handle with `result` and `cancel(reason)`. |
 | `ai.streamRequest(request)` | Consumes the stream and returns text or `{toolName: argumentJsonString}`. |
+| `ai.createChatSession(options)` | Asynchronously resolves `Promise<PersistentAIChatSession>` bound to this exact controller; caller-supplied `chat` is rejected. |
 | `ai.unload()` | Cancels active work, releases the Wllama session, and returns flat unloaded status; the DBOPFS cache remains. |
 | `ai.dispose()` | Permanently disposes the controller; explicit `store.remove(source)` is required to delete cached model bytes. |
 
@@ -77,11 +91,19 @@ current frozen status. Provider states are `unloaded`, `loading`, `ready`,
 
 ## Model authority, security, and cache admission
 
-The canonical model descriptor is `{id, url, bytes?, sha256?}`. `id` and `url`
-are required. The URL must be absolute HTTPS without credentials or a fragment;
-revision-floating `main`, `master`, and `latest` path segments are rejected.
-When supplied, `bytes` is a positive safe integer and `sha256` is exactly 64
-hexadecimal characters.
+The canonical model descriptor is `{id, files:[{name?,url,bytes?,sha256?},...]}`.
+The ordered `files` array is nonempty; names and URLs are unique. Each URL must
+be absolute HTTPS without credentials or a fragment; revision-floating `main`,
+`master`, and `latest` path segments are rejected. When supplied, `bytes` is a
+positive safe integer and `sha256` is exactly 64 hexadecimal characters. The
+legacy one-file `{id,url,bytes?,sha256?}` shape remains accepted and normalizes
+to one ordered member.
+
+Fetch follows HTTPS redirects and records the requested and final HTTPS URL in
+the completion evidence. A redirect that leaves HTTPS is rejected. A declared
+URL, revision-looking path, or recorded final URL is not a byte digest: only an
+enabled byte-length or SHA-256 check establishes that corresponding integrity
+fact. When a check is disabled, status reports it as `unchecked`.
 
 App, provider/model-binding, and load-operation options use the same
 plain-JavaScript shape:
@@ -115,8 +137,8 @@ and does not hash or reread a multi-gigabyte model solely to produce a digest.
 Only enabled checks fail closed. Regardless of optional integrity checks, a
 load succeeds only after Wllama reports that the model is loaded.
 
-The DBOPFS adapter commits an `arcane.ai.browser-wasm.model.v3` completion
-manifest with the observed byte length. Status reports the effective
+The DBOPFS adapter commits an `arcane.ai.browser-wasm.model.v4` completion
+manifest only after every ordered file succeeds. Status reports the effective
 `security.secure`, both effective check booleans, and per-check integrity
 outcomes. Overall integrity is `verified` when every enabled check succeeded,
 `pending` while an enabled check is running, and `unchecked` when neither check
@@ -133,41 +155,53 @@ console.log(integrity.state); // 'unchecked' or 'verified'
 console.log(integrity.byteLength.observed); // actual cached/downloaded bytes
 ```
 
-For compatibility, older descriptors can supply `immutableUrl` as the URL alias
-and `name` as a cache-filename hint. If both `url` and `immutableUrl` are
-present, they must match. Legacy `licenseSpdx` and `sourceRevision` properties
-are not canonical descriptor fields or runtime admission checks; applications
-remain responsible for model selection, provenance, and license compliance.
-Version-2 cache manifests can be migrated to version 3 when their model identity
-matches, without inventing an integrity result.
+For one-file compatibility, older descriptors can supply `immutableUrl` as the
+URL alias and `name` as a cache-filename hint. If both `url` and
+`immutableUrl` are present, they must match. Legacy `licenseSpdx` and
+`sourceRevision` properties are not canonical descriptor fields or runtime
+admission checks; applications remain responsible for model selection,
+provenance, and license compliance. Version-2/3 compatibility is internal; a
+new successful completion is always recorded as version 4 without inventing an
+integrity result.
 
 `localOnly:true` describes inference after load. It does not mean a cache miss
 cannot download. Source downloads use CORS, omit credentials and referrer,
 disable HTTP caching, and honor `AbortSignal`.
 
+On Chrome, observing a lower-power Intel WebGPU adapter may open
+`chrome://flags/#force-high-performance-gpu` in a new tab and show an alert
+explaining that Chrome must be completely restarted after changing the flag.
+The notice is advisory; it does not change browser settings, prove a faster
+adapter exists, or make a failed load succeed.
+
 ## Streaming, cancellation, and tools
 
 ```javascript
-const abort = new AbortController();
-const stream = ai.llm.stream({
-    localOnly:true,
-    signal:abort.signal,
-    messages:[{role:'user', content:'Summarize this text.'}],
-    maxTokens:128
-});
-
-const cancelButton = document.querySelector('[data-cancel-local-ai]');
-const cancel = () => abort.abort('user cancelled');
-cancelButton.addEventListener('click', cancel, {once:true});
-try {
-    for await (const chunk of stream) renderChunk(chunk);
-    const completion = await stream.result;
-    renderCompletion(completion);
-} catch (error) {
-    if (error?.code !== 'ARCANE_AI_REQUEST_ABORTED') throw error;
-    renderCancelled();
-} finally {
-    cancelButton.removeEventListener('click', cancel);
+async function streamLocalSummaryAfterUserChoice(cancelButton) {
+    // The selected browser-WASM model must already be ready.
+    if (!cancelButton?.addEventListener) {
+        throw new TypeError('A cancel button is required.');
+    }
+    const abort = new AbortController();
+    const stream = ai.llm.stream({
+        localOnly:true,
+        signal:abort.signal,
+        messages:[{role:'user', content:'Summarize this text.'}],
+        maxTokens:128
+    });
+
+    const cancel = () => abort.abort('user cancelled');
+    cancelButton.addEventListener('click', cancel, {once:true});
+    try {
+        for await (const chunk of stream) renderChunk(chunk);
+        const completion = await stream.result;
+        renderCompletion(completion);
+    } catch (error) {
+        if (error?.code !== 'ARCANE_AI_REQUEST_ABORTED') throw error;
+        renderCancelled();
+    } finally {
+        cancelButton.removeEventListener('click', cancel);
+    }
 }
 ```
 
@@ -176,8 +210,11 @@ serialized; provider status exposes `busy` and `queued`. Supported request
 generation fields include temperature, top-K, top-P, min-P, repeat penalty,
 maximum tokens, seed, and stop sequences. Load settings separately include
 `contextTokens`, `batchTokens`, `microBatchTokens`, `threads`, and GPU-layer
-count. WebGPU is optional; cross-origin isolation and hardware fields are
-observations, not readiness promises.
+count. The shipped runtime always sets `gpuLayers: 99999`: WebGPU and proved
+full offload are mandatory, and there is no CPU fallback. Secure context,
+adapter selection, full-offload, logical-buffer, queue-submission, and
+settled-fence evidence are load admission; cross-origin isolation and coarse
+hardware fields remain observations.
 
 Tool definitions, tool choice, parallel-tool-call preference, and JSON or JSON
 Schema structured-output requests are passed to Wllama. Returned tool calls are
@@ -197,24 +234,41 @@ as unavailable.
 | --- | --- |
 | Source and download | `ARCANE_AI_MODEL_SOURCE_INVALID`, `ARCANE_AI_MODEL_SOURCE_UNAVAILABLE`, `ARCANE_AI_MODEL_DOWNLOAD_FAILED`, `ARCANE_AI_MODEL_REDIRECT_BLOCKED`, `ARCANE_AI_MODEL_SIZE_MISMATCH`, `ARCANE_AI_MODEL_DIGEST_MISMATCH` |
 | Cache and storage | `ARCANE_AI_MODEL_CACHE_REJECTED`, `ARCANE_AI_MODEL_OFFLINE_MISS`, `ARCANE_AI_STORAGE_UNAVAILABLE`, `ARCANE_AI_STORAGE_READ_FAILED`, `ARCANE_AI_STORAGE_DELETE_FAILED` |
-| Lifecycle | `ARCANE_AI_UNAVAILABLE`, `ARCANE_AI_NOT_READY`, `ARCANE_AI_LOAD_FAILED`, `ARCANE_AI_UNLOAD_FAILED`, `ARCANE_AI_DISPOSE_FAILED`, `ARCANE_AI_DISPOSED`, `ARCANE_AI_OPERATION_SUPERSEDED`, `ARCANE_AI_SECURITY_RELOAD_REQUIRED` |
-| Requests | `ARCANE_AI_REQUEST_ABORTED`, `ARCANE_AI_REQUEST_FAILED`, `ARCANE_AI_INVALID_PROVIDER_RESULT`, `ARCANE_AI_LOCAL_ONLY_UNAVAILABLE`, `ARCANE_AI_ADAPTER_PROTOCOL_MISMATCH` |
+| Lifecycle | `ARCANE_AI_UNAVAILABLE`, `ARCANE_AI_NOT_READY`, `ARCANE_AI_MODEL_NOT_READY`, `ARCANE_AI_LOAD_FAILED`, `ARCANE_AI_UNLOAD_FAILED`, `ARCANE_AI_DISPOSE_FAILED`, `ARCANE_AI_DISPOSED`, `ARCANE_AI_OPERATION_SUPERSEDED`, `ARCANE_AI_SECURITY_RELOAD_REQUIRED` |
+| Requests | `ARCANE_AI_REQUEST_ABORTED`, `ARCANE_AI_REQUEST_FAILED`, `ARCANE_AI_RUNTIME_BUSY`, `ARCANE_AI_INVALID_PROVIDER_RESULT`, `ARCANE_AI_LOCAL_ONLY_UNAVAILABLE`, `ARCANE_AI_ADAPTER_PROTOCOL_MISMATCH` |
+| Provider/2 adapter | `ARCANE_AI_MODEL_AUTHORITY_REQUIRED`, `ARCANE_AI_PROVIDER_ROLE_MISMATCH`, `ARCANE_AI_PROVIDER_PROGRESS_INVALID`, `ARCANE_AI_PROVIDER_STATUS_INVALID`, `ARCANE_AI_PROVIDER_OPERATION_UNAVAILABLE` |
+| WebGPU and model admission | `ARCANE_AI_WEBGPU_REQUIRED`, `ARCANE_AI_WEBGPU_API_UNAVAILABLE`, `ARCANE_AI_WEBGPU_EVIDENCE_INVALID`, `ARCANE_AI_MODEL_FULL_OFFLOAD_UNPROVEN`, `ARCANE_AI_MODEL_WEBGPU_REQUIREMENT_FAILED`, `ARCANE_AI_MODEL_GPU_MEMORY_INSUFFICIENT`, `ARCANE_AI_MODEL_SHARD_TOO_LARGE`, `ARCANE_AI_MODEL_RELOAD_REQUIRED`, `ARCANE_AI_LOAD_PLAN_RELOAD_REQUIRED` |
+| Worker cleanup and recovery | `ARCANE_AI_WORKER_TERMINATION_UNCONFIRMED`, `ARCANE_AI_COMPLETION_RECOVERY_UNCONFIRMED` |
 | Diagnostics | `ARCANE_AI_PROBE_FAILED` |
 
+Capability and status records also carry stable reason codes. These observations
+are not all thrown errors: positive and unknown states let an application
+explain why load is available, blocked, or not yet measured without guessing.
+
+| Observation | Status/reason codes |
+| --- | --- |
+| Browser prerequisites | `ARCANE_AI_WEBASSEMBLY_UNAVAILABLE`, `ARCANE_AI_OPFS_UNAVAILABLE`, `ARCANE_AI_SECURE_CONTEXT_REQUIRED` |
+| Model/storage sizing | `ARCANE_AI_MODEL_STORAGE_REQUIREMENT_UNBOUNDED`, `ARCANE_AI_MODEL_STORAGE_REQUIREMENT_UNKNOWN`, `ARCANE_AI_STORAGE_ESTIMATE_UNAVAILABLE`, `ARCANE_AI_STORAGE_ESTIMATE_FAILED`, `ARCANE_AI_STORAGE_ESTIMATE_INVALID`, `ARCANE_AI_STORAGE_NOT_MEASURED`, `ARCANE_AI_STORAGE_CAPACITY_INSUFFICIENT` |
+| Positive cache/storage state | `ARCANE_AI_MODEL_CACHE_COMPLETE`, `ARCANE_AI_STORAGE_CAPACITY_AVAILABLE` |
+| WebGPU execution evidence | `ARCANE_AI_WEBGPU_EXECUTION_OBSERVED`, `ARCANE_AI_WEBGPU_EXECUTION_UNOBSERVED` |
+| Provider and runtime failure state | `ARCANE_AI_PROVIDER_UNAVAILABLE`, `ARCANE_AI_RUNTIME_FAILED` |
+
 `capabilities()` reports browser observations such as WebAssembly, OPFS,
-WebGPU, secure context, cross-origin isolation, and hardware concurrency.
-Feature-detect them. The authoritative Chrome behavior passes without
-cross-origin isolation, so that flag is not a hard gate. `probe()` exercises
-packaged Wllama backend operations only while unloaded; it neither admits nor
-downloads a model.
+WebGPU API presence, admitted WebGPU operation, secure context, cross-origin
+isolation, and hardware concurrency. `navigator.gpu` alone is not operational
+evidence. The authoritative runtime can operate without cross-origin isolation,
+so that flag is not a hard gate; secure context and WebGPU/full-offload evidence
+are. `probe()` exercises packaged Wllama backend operations only while unloaded;
+it neither admits nor downloads a model.
 
 ## BROWSER_WASM_RUNTIME_AUTHORITY
 
 ### Overview
 
 Deep-frozen identity for the shipped browser runtime. Its protocol is
-`arcane-ai-browser-wasm/2`; the provider adapter uses
-`arcane-ai-adapter/1`. It records Wllama `3.6.0`, the embedded llama.cpp
+`arcane-ai-browser-wasm/2`; the direct provider uses
+`arcane-ai-adapter/1` and `adaptV1LlmProvider()` projects it into
+`arcane-ai-provider/2`. It records Wllama `3.6.0`, the embedded llama.cpp
 revision, authenticated module/WASM byte lengths and SHA-256 values, licenses,
 and the disabled compatibility-runtime and remote-model-helper policy.
 
@@ -255,12 +309,18 @@ createArcaneAI({ llm=null, provider=null, loadPolicy='on-demand', security }={})
 
 At least one `llm` or `provider` is required; when both are supplied, `llm`
 takes precedence. `loadPolicy` is `on-demand` or `manual`. The frozen result
-contains `llm`, `runtime`, `status`, `load`,
+contains `llm`, `runtime`, `createChatSession`, `status`, `load`,
 `unload`, `probe`, `fetchRequest`, `streamRequest`, and `dispose`.
 `security` is the app-level security configuration inherited by provider loads.
 The SDK default is `secure:false`; `ai.load({security})` can override inherited
 fields for that operation.
 
+When `llm` is an existing `ModelController`, that controller keeps the security
+and load policy with which it was created. This function does not reapply its
+`loadPolicy` argument in that case, and supplying `security` alongside the
+existing controller throws `TypeError`. Passing a provider instead creates a
+new controller with the requested policy and security.
+
 ### Availability and normalization
 
 **Browser.** It normalizes provider lifecycle and request observation without
@@ -271,17 +331,30 @@ creating a fallback provider.
 
 ```javascript
 const ai = createArcaneAI({provider, loadPolicy:'manual'});
-const off = ai.llm.on('statechange', event => renderStatus(event.detail));
-await ai.load({offline:true});
-off();
+async function loadCachedModelAfterUserChoice() {
+  const off = ai.llm.on('statechange', event => renderStatus(event.detail));
+  try {
+    return await ai.load({offline:true});
+  } finally {
+    off();
+  }
+}
 ```
 
+`await ai.createChatSession(options)` dynamically creates a
+[`PersistentAIChatSession`](../runtime-modules.md#persistentaichatsessionjs)
+whose `chat` function is permanently bound to this controller. `options` must
+be a plain object and must not contain `chat`; this prevents a session from
+claiming the controller's lifecycle while sending its turns through another
+provider.
+
 ## createBrowserModelSource()
 
 ### Overview
 
-Validates a caller-owned canonical `{id, url, bytes?, sha256?}` descriptor and
-creates the one cancellable HTTPS download source accepted by this provider.
+Validates a caller-owned canonical ordered multi-file descriptor and creates
+the cancellable HTTPS download source accepted by this provider. A legacy
+one-file descriptor normalizes to one ordered member.
 
 ### Signature and result
 
@@ -290,8 +363,10 @@ createBrowserModelSource(descriptor, { fetchImpl=null }={})
 ```
 
 The frozen source includes `kind`, the canonical descriptor fields,
-`descriptor`, and `open({signal})`. `open()` returns a readable response body,
-requested/final URLs, and `cancel()`; it does not admit bytes to the cache.
+`descriptor`, and `open(memberIndex,{signal})`. `open()` requires a member
+index for multi-file sources and returns a readable response body,
+requested/final URLs, reported byte length, and `cancel()`; it does not admit
+bytes to the cache.
 
 ### Availability and normalization
 
@@ -303,7 +378,7 @@ enabled for load.
 
 ```javascript
 const source = createBrowserModelSource(MODEL);
-console.log(source.id, source.bytes, source.sha256);
+console.log(source.id, source.files);
 ```
 
 ## createBrowserWasmLlmProvider()
@@ -316,12 +391,16 @@ created by this module. Structural lookalikes are rejected.
 ### Signature and result
 
 ```text
-createBrowserWasmLlmProvider({ source, store, loadDefaults={}, security, logger=console }={})
+createBrowserWasmLlmProvider({ source, sources, store, loadDefaults={}, security, logger=console }={})
 ```
 
-The frozen result exposes protocol and provider identity, model metadata,
-`capabilities`, `status`, `load`, `unload`, `chat`, `stream`, `streamChat`,
-`use`, `probe`, and `dispose`. Direct provider `load()` returns `{model,status}`;
+`sources` is a nonempty array of unique SDK-created model sources. Optional
+legacy `source` identifies the default and must be one member of `sources`; when
+`sources` is omitted, `source` supplies the one-model catalog. The frozen
+result exposes protocol and provider identity, default model metadata,
+`catalog`, `capabilities`, `status`, `load`, `unload`, `chat`, `stream`,
+`streamChat`, `use`, `probe`, and `dispose`. Direct provider `load()` selects a
+catalog model and returns `{model,status}`;
 the facade `ai.load()` returns the flat controller status.
 Provider `security` supplies the provider/model-binding scope. Direct
 `provider.load({security})` and facade `ai.load({security})` supply the
@@ -329,18 +408,20 @@ operation scope.
 
 ### Availability and normalization
 
-**Browser with WebAssembly and DBOPFS model bytes.** Inference is local after a
-successful Wllama load. WebGPU is optional and defaults to zero GPU layers
-unless the caller selects otherwise. Status discloses effective checks and
-whether enabled integrity checks are pending, unchecked, or verified.
+**Browser secure context with WebAssembly, OPFS/DBOPFS, WebGPU, and admitted
+full-offload evidence.** Inference is local after a successful Wllama load.
+The runtime forces `gpuLayers: 99999`; callers cannot select CPU or partial
+offload. Status discloses effective checks, capability policy, storage/model
+compatibility, and whether enabled integrity checks are pending, unchecked, or
+verified.
 
 ### Example
 
 ```javascript
 const provider = createBrowserWasmLlmProvider({
-    source,
+    sources:[source],
     store,
-    loadDefaults:{threads:1, contextTokens:4096, gpuLayers:0}
+    loadDefaults:{threads:1, contextTokens:4096}
 });
 console.log(provider.status().state); // unloaded
 ```
@@ -356,14 +437,18 @@ completion-manifest behavior.
 ### Signature and result
 
 ```text
-createDbopfsModelStore({ dbopfs, tableName='arcane_ai_browser_models' }={})
+createDbopfsModelStore({ dbopfs, tableName='arcane_ai_browser_models', estimateStorage=null }={})
 ```
 
-The frozen result contains `kind`, `tableName`, the original `adapter`, and
-`ready`, `openVerified`, `install`, `ensure`, and `remove`. `ensure()` returns a
-file, completion manifest, observed byte count, integrity detail, and cache state
-`cached` or `installed`. `openVerified()` remains a compatibility helper that
-requires both byte-length and SHA-256 verification.
+The optional `estimateStorage()` function supplies bounded storage evidence
+when the browser's default estimator is unavailable or an application owns a
+more precise quota view. The frozen result contains `kind`, `tableName`, the
+original `adapter`, and `ready`, `openVerified`, `install`, `ensure`, and
+`remove`. `ensure()` returns
+`{files,file,manifest,observedBytes,integrity,cache}`: `files` preserves the
+ordered model set, while the one-file compatibility field `file` is that sole
+member or `null`. `cache` is `cached` or `installed`. `openVerified()` remains
+a compatibility helper that requires both byte-length and SHA-256 verification.
 
 ### Availability and normalization
 
@@ -376,15 +461,52 @@ model license rights.
 
 ```javascript
 const store = createDbopfsModelStore({dbopfs});
-await store.ready();
-const cached = await store.openVerified(source);
-console.log(cached ? 'verified cache' : 'cache miss');
+async function verifyCachedModelAfterUserChoice() {
+    await store.ready();
+    const cached = await store.openVerified(source);
+    console.log(cached ? 'verified cache' : 'cache miss');
+}
+```
+
+## adaptV1LlmProvider()
+
+### Overview
+
+Projects one compatible admitted v1 browser-WASM provider into the same
+provider/2 LLM role used by `AIProviderRuntime.js`. Admission checks the v1
+protocol, required identity/methods, and local-only capability; it does not
+establish SDK provenance for an arbitrary compatible object. The adapter does
+not change the wrapped provider, download a model, execute a tool, or create a
+fallback.
+
+### Signature and result
+
+```text
+adaptV1LlmProvider(provider)
+```
+
+The frozen result exposes `{protocol:'arcane-ai-provider/2',role:'llm',id,
+localOnly:true,catalog,inspect,status,load,request,unload,dispose}`. Inspection
+returns `arcane-ai-model-authority/1` only for an exact catalog selection.
+`request()` admits only `chat` and `stream` and preserves structural tool data.
+
+### Example
+
+```javascript
+import {adaptV1LlmProvider} from 'arcane-os/ai/browser-wasm';
+import {getAIProviderRuntime} from 'arcane/AIProviderRuntime';
+
+const runtime = getAIProviderRuntime();
+const release = runtime.register(adaptV1LlmProvider(provider));
+// Configure an exact llm route before load/use. Release registration at teardown.
+release();
 ```
 
 ## Related reference
 
 - [Canonical `createArcaneAI()` entry](../sdk-api.md#createarcaneai) and the
   sibling [`BROWSER_WASM_RUNTIME_AUTHORITY`](../sdk-api.md#browserwasmruntimeauthority),
+  [`adaptV1LlmProvider()`](../sdk-api.md#adaptv1llmprovider),
   [`createBrowserModelSource()`](../sdk-api.md#createbrowsermodelsource),
   [`createBrowserWasmLlmProvider()`](../sdk-api.md#createbrowserwasmllmprovider),
   and [`createDbopfsModelStore()`](../sdk-api.md#createdbopfsmodelstore) entries
@@ -392,3 +514,6 @@ console.log(cached ? 'verified cache' : 'cache miss');
 - [Authenticated browser runtime delivery](../protocols.md#browser-runtime-delivery)
 - [Browser-WASM behavior evidence](../behavioral-testing.md#behavioral-coverage-model)
 - [DBOPFS runtime module](../runtime-modules.md#dbopfsjs)
+- [Browser speech providers](browser-speech.md)
+- [Provider-neutral AI runtime](../runtime-modules.md#aiproviderruntimejs)
+- [Persistent chat](../runtime-modules.md#persistentaichatsessionjs)

package/docs/reference/availability-and-normalization.md

@@ -11,7 +11,7 @@ it runs; the [protocol guide](protocols.md) contains the implementation detail.
 | **Browser** | Uses standard browser APIs and can run without a native host when its own dependencies are available. |
 | **Native** | Requires an admitted `globalThis.Arcane` host method or a native target provider. |
 | **Cloud** | Calls a remote provider over HTTPS and needs provider configuration and network policy. |
-| **Cross-host** | Keeps one application API while Arcane selects WebView2, WebKitGTK, Android WebView, or development HTTP transport. |
+| **Cross-host** | Keeps one application contract usable across supported hosts. Execution may stay in-process, use a registered provider, or cross a documented Arcane WebView2, WebKitGTK, Android WebView, or development HTTP transport. |
 | **Provider-native** | Intentionally returns the underlying provider's bounded envelope instead of an Arcane-normalized entity. |
 
 “Available” never means “authorized.” App grants, method allowlists, host
@@ -29,7 +29,11 @@ version; WebKitGTK availability must not be generalized to macOS.
 | Scaffold, inspect, test, package, bundle, build, verify, or run an app | `arcane` CLI or `arcane-os` package functions | **Node**; native targets invoke one explicit provider | CLI events and SDK errors/results are normalized by versioned SDK contracts. Native artifact receipts remain target-specific inside a common receipt lifecycle. |
 | Publish application events or review a bounded event history | `arcane-os/event-manager` | **Node** and **Browser**; optional DOM capture needs a browser DOM or compatible host | Live listeners receive original arguments. Recorded payloads and metadata become bounded, redacted, deeply frozen `arcane-event-stack/1` snapshots. The stack format is local diagnostic data, not a host transport. |
 | Build browser UI and app-local behavior | `/arcane/modules/*.js`, shared entities, and components | **Browser**; many modules also run inside every native renderer | Pure modules own their result contracts. Modules that call `Arcane` inherit the bridge boundary described below. |
-| Run a caller-selected local LLM entirely in a browser renderer | `arcane-os/ai/browser-wasm` through `createArcaneAI()` | **Browser** only; WebAssembly and OPFS/DBOPFS are required, WebGPU is optional, and a cache miss uses the caller's HTTPS model URL unless `offline:true` | The facade normalizes lifecycle, status, security precedence, effective-check disclosure, streaming, cancellation, and structural tool-call visibility. The canonical model descriptor is `{id, url, bytes?, sha256?}`; license is application provenance policy, not a runtime admission check. |
+| Select and observe independent LLM/STT/TTS roles | `/arcane/modules/AIProviderRuntime.js` and `AIRuntimeState.js` | **Cross-host** controller/state; registered providers retain their own host requirements | Required/projected provider members, closed route/configuration records, and validated authority/status fields; per-role lifecycle, cancellation, stream cleanup, sticky state, and startup barriers are normalized. `localOnly` fails closed and creates no fallback. |
+| Run a caller-selected local LLM entirely in a browser renderer | `arcane-os/ai/browser-wasm` through `createArcaneAI()` | **Browser** only; secure context, WebAssembly, OPFS/DBOPFS, WebGPU, requested full offload, and admitted adapter/buffer/queue/fence evidence are required; no CPU fallback | The facade normalizes multi-model lifecycle, status, security precedence, effective-check disclosure, streaming, cancellation, and structural tool-call visibility. Model sources are canonical ordered file descriptors; licenses and model choice remain application policy. |
+| Run caller-selected Whisper or Kokoro in a browser renderer | `arcane-os/ai/browser-speech` registered with `AIProviderRuntime` | **Browser** only; DBOPFS, Web Locks, Workers, Fetch/object URLs, and a caller-supplied self-contained runtime/model closure are required | STT/TTS use independent provider/2 lifecycle and status. Immutable artifact authority, manifest-last cache, strict offline admission, cancellation, Worker teardown, and request/result shapes are normalized. No runtime/model bytes or cloud fallback are supplied. |
+| Preserve bounded chat history and memory | `/arcane/modules/PersistentAIChatSession.js` | **Browser / native WebView** with ChatEntity/DBOPFS and a configured chat function | Existing DBOPFS names and memory semantics are preserved. Live-context commit is atomic; durable persistence is explicit and coherent across user/assistant/tool turns. |
+| Search an app-owned document corpus for explicit chat context | `/arcane/modules/DBOPFSDocumentLibrary.js` | **Browser** or compatible injected DBOPFS adapter | Generation/manifest completion, bounded lexical search, partial read failures, and untrusted context labels are normalized. Construction does not search; an explicitly wired context builder performs bounded retrieval for each prepared chat send. |
 | Read host identity, capabilities, storage, preferences, appearance, or platform state | `globalThis.Arcane` | **Cross-host** where the method is implemented and admitted | Promise behavior and `Arcane.Error` are normalized. Result fields are normalized unless the method explicitly documents a platform-dependent snapshot. |
 | Use local AI without coupling app code to Ollama HTTP | `Arcane.localAI`, `Arcane.ai`, or `/arcane/modules/Ollama.js` | Primarily **Native**; Android exposes a narrower admitted inference projection | Admission, errors, and managed-operation events are normalized. Direct Ollama response envelopes remain **Provider-native**. |
 | Use OpenAI from the renderer profile | `/arcane/modules/AI.js` | **Cloud** from an allowed browser/native renderer | High-level AI chat/text behavior is normalized by the module; raw provider diagnostics and some response detail remain provider-specific. No automatic cloud fallback is inferred from local failure. |
@@ -81,12 +85,19 @@ state. See [EventManager and time-travel review](event-manager.md).
 ### Browser-local provider adapter
 
 [`arcane-os/ai/browser-wasm`](ai/browser-wasm.md) exposes the same
-`arcane-ai-adapter/1` LLM lifecycle used by `createArcaneAI()`, while its
-packaged Wllama engine and caller-supplied model run inside the browser. This
+provider-neutral lifecycle used by `createArcaneAI()`, while its packaged
+Wllama engine and caller-supplied model run inside the browser. This
 surface does not require an Arcane Core method grant because it does not call a
 Core host. Browser Fetch, CORS, storage policy, secure-context behavior, and
 resource limits still apply.
 
+The shipped `0.2.2` runtime requires WebGPU and has no CPU fallback. A successful
+load requests full GPU offload (`gpuLayers: 99999`) and admits actual adapter,
+full-offload, buffer, queue, and settled-fence evidence. `navigator.gpu`
+presence by itself is not readiness. The provider emits the instrumented
+`arcane.ai.browser-wasm.webgpu.adapter.selected` capability event only after
+admitted adapter selection evidence.
+
 `localOnly:true` describes inference after load; it does not promise that load
 is offline. A normal cache miss downloads from the exact caller-supplied HTTPS
 URL. App, provider/model-binding, and load-operation options use
@@ -108,6 +119,24 @@ cache entry and otherwise rejects with `ARCANE_AI_MODEL_OFFLINE_MISS`. Tool
 calls are result data for application review and dispatch; the SDK never
 executes them.
 
+[`arcane-os/ai/browser-speech`](ai/browser-speech.md) implements the sibling
+`stt` and `tts` provider/2 roles. Each caller-authenticated Whisper or Kokoro
+provider has its own load, use, cancellation, unload, dispose, cache, Worker,
+status, and error state. The SDK supplies neither speech adapter runtime bytes
+nor model/voice bytes; every immutable file is application-owned and admitted
+through an SDK-created authority and DBOPFS artifact store.
+
+The projected [`AIProviderRuntime`](runtime-modules.md#aiproviderruntimejs)
+normalizes those browser providers and can admit an externally supplied native
+or cloud provider/2 adapter. `AI.js` also supplies compatibility adapters for
+an already-selected legacy OpenAI route, Ollama route, or admitted Core speech
+route. SDK `0.2.2` publishes no privileged Core implementation, credential,
+model, or speech-runtime authority, and those adapters never probe, select,
+download, or fall back. The sticky
+[`AIRuntimeState`](runtime-modules.md#airuntimestatejs) surface keeps
+application UI independent of transport. A selected route remains explicit:
+browser failure is not permission to invoke Core or cloud.
+
 ### Arcane bridge-normalized
 
 Core-backed calls return promises and reject with `Arcane.Error`. Transport

package/docs/reference/behavioral-testing.md

@@ -37,7 +37,10 @@ release acceptance.
 | EventManager and event stacks | Live pub/sub ordering and payload identity, nested causation, immutable/redacted snapshots, strict import, bounded overflow, seek, all playback modes/lifecycle outcomes, cancellation, and DOM start/stop/privacy behavior. | Real user journeys and browser layout belong in a browser harness; event-stack review never proves that external side effects can be replayed. |
 | CLI | Commands parse, acknowledge, select one scope, produce normalized human/JSON/NDJSON output, propagate cancellation/failure, and reject invalid cardinality. | Native build/run requires the selected real provider and host. |
 | Browser runtime modules | Every shipped ESM module parses and its export inventory matches the catalog; pure helpers run focused success/error cases. | DOM, OPFS, media, and Web Component journeys use a browser harness. |
-| Browser-WASM local AI | The exact exported namespace, canonical `{id, url, bytes?, sha256?}` descriptor, fieldwise app/provider/load security precedence, default-unchecked and secure-check paths, observed-byte persistence, honest status, provider/facade lifecycle, lazy/manual policy, successful Wllama-load requirement, abort normalization, and structural-only tool behavior run with bounded deterministic providers. | The publication gate installs the packed SDK into a real Chrome app, loads the authenticated Wllama 3.6.0 JS/WASM assets, configures `secure:true`, performs a cold exact-length/SHA-256 model install, real inference, in-flight cancellation, unload, and a verified offline reload with zero model requests. It is an explicit heavyweight capability gate, not an implicit model download in every local `npm run check`. |
+| Provider-neutral AI runtime and chat/speech activation | Provider/2 registration, closed three-role configuration, opt-in STT startup, legacy Cloud/Core speech readiness, independent LLM/STT/TTS load/unload/status, latest-request-wins settlement, owned STT signals, TTS mute lifecycle, route-owned voice defaults, sticky-state-only readiness for both speech components, shared selected-unloaded activation request/cancellation/error behavior, fail-closed programmatic voice recording, public transcript-replacement supersession of late transcribe/save/complete settlement, `AI.fetchSTT` callback-position compatibility, stale-callback suppression, and absence of silent provider fallback are exercised against bounded providers and host callbacks. | Real model/runtime admission remains the selected provider's evidence boundary; provider-promise settlement, state, an abort signal, or an activation event does not by itself prove underlying provider work stopped or native, cloud, or browser-model availability. |
+| Browser-WASM local AI | The exact exported namespace, canonical ordered `{id, files:[{name?,url,bytes?,sha256?},...]}` descriptor plus its one-file compatibility input, fieldwise app/provider/load security precedence, default-unchecked and secure-check paths, observed-byte persistence, honest capability/status reasons, provider/facade lifecycle, lazy/manual policy, successful Wllama-load requirement, abort normalization, and structural-only tool behavior run with bounded deterministic providers. | The publication gate installs the packed SDK into a real Chrome app, loads the authenticated Wllama 3.6.0 JS/WASM assets, configures `secure:true`, performs a cold exact-length/SHA-256 model install, real inference, in-flight cancellation, unload, and a verified offline reload with zero model requests. It is an explicit heavyweight capability gate, not an implicit model download in every local `npm run check`. |
+| Browser speech | Caller-owned Whisper/Kokoro authority, closed runtime graph, app/provider/load security precedence, manifest-last DBOPFS cache, strict offline admission, independent Worker lifecycle, pre-Worker versus in-Worker cancellation, Blob/File STT conversion, WAV TTS conversion, and no cloud fallback are exercised with bounded synthetic artifacts and adapters. | A real runtime/model/voice download and actual transcription or synthesis require the application's admitted immutable artifacts, licenses, browser media support, and explicit user action. |
+| Persistent chat and document context | Atomic in-memory/history commit, explicit per-turn persistence, single structural tool-call sequencing, bounded bootstrap/search/context, caller-source `evaluate()` budgets, cancellation, and reject versus `preserve-readable` partial coverage are exercised with app-scoped adapters. | Live Core/provider inference and durable browser storage remain separate authorities; tests never treat a fake chat function or in-memory adapter as host/storage proof. |
 | Core bridge docs | Canonical namespace/method/event/entity inventories match their one-per-member guides and required sections. | Live Core conformance belongs in Arcane OS because Core implementation is not shipped as SDK source. |
 | Arcane Ollama wrapper | Missing-host error, method forwarding, text/readiness normalization, unload request, and stream-option forwarding run against a deterministic fake `Arcane.ollama`. | Real managed-service, model download/create, GPU/resource admission, and service restart require an admitted Arcane host. |
 | Native providers | Plan/provider protocol, explicit target, receipt authentication, artifact reader, and unavailable-path honesty are tested with bounded fixtures. | Exact Windows, Linux, or Android artifact verification and launch must run on that actual platform/architecture. |