arcane-os 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.2.3
+
+- Made shared voice transcription consume authoritative sticky STT state,
+  expose explicit selected-unloaded activation, and keep recording disabled
+  until the selected route is genuinely ready and non-busy.
+- Added owned cancellation and current-operation guards across microphone
+  permission, recording, transcription, save, completion, transcript
+  replacement, synchronous public events, teardown, and stale settlement.
+- Centralized the shared STT activation control in
+  `createSTTActivationController()` without automatic downloads, hidden
+  provider selection, or application policy.
+
+## 0.2.2
+
+- Corrected latest-request-wins ownership so each newly admitted AI request
+  aborts and settles the prior provider operation, revalidates role readiness,
+  and prevents stale results from restoring superseded state.
+- Made speech startup and controls explicitly lifecycle-owned: STT startup is
+  opt-in, selected-unloaded STT exposes user activation and cancellation,
+  caller abort reaches shared transcription, and TTS mute/unmute owns its load,
+  cancellation, playback, and unload sequence.
+- Kept positive speech readiness bound to admitted sticky provider state while
+  exposing truthful capability-only legacy OpenAI, Ollama, and Core speech
+  routes without downloads, hidden provider selection, model authority, or
+  fallback.
+- Preserved the existing shared Blob/File STT and WAV TTS request shapes at the
+  browser-provider boundary, with explicit decode/format errors and
+  provider/model-owned TTS voice defaults.
+
 ## 0.2.1
 
 - Added explicit selected-unloaded chat activation, truthful legacy Cloud/Core

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.2.1` SDK contract. Applications pin one exact npm
+This checkout defines the `0.2.3` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into immutable
 application artifacts.
 
@@ -132,7 +132,7 @@ uses the same controller for automatic memory extraction.
 Create a new repository-shaped Arcane application with the exact stable SDK:
 
 ```bash
-npx arcane-os@0.2.1 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.2.3 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run check
@@ -143,7 +143,7 @@ To enroll an existing repository, install the exact SDK and initialize only
 missing Arcane files:
 
 ```bash
-npm install --save-dev --save-exact arcane-os@0.2.1
+npm install --save-dev --save-exact arcane-os@0.2.3
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -159,7 +159,7 @@ npm exec -- arcane-os targets
 No global SDK install or standalone Arcane CLI is required. The application
 repository's exact npm dependency and lockfile own the CLI and toolchain version.
 
-Use `npx arcane-os@0.2.1` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.2.3` for the initial bootstrap because it names this npm
 package explicitly; bare `npx arcane` outside an installed project could resolve
 a different package. Both installed commands invoke the same headless toolchain.
 Project-local npm scripts use the SDK pinned by that app's `package-lock.json`,
@@ -180,7 +180,7 @@ node ./bin/arcane.mjs new local-app --path ../local-app --target portable --git
 
 # From the generated app repository
 cd ../local-app
-npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.2.1.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.2.3.tgz
 npm run check
 npm ci
 ```
@@ -191,7 +191,7 @@ still verifies the installed package name and exact version, the locked runtime
 identity, and the runtime bytes. Local directory `file:` dependencies are not
 accepted because npm may install them as links; use a packed `.tgz`. A GitHub
 runner also needs that tarball at the locked path. After publication, replace
-the local declaration with the exact `arcane-os@0.2.1` registry package and
+the local declaration with the exact `arcane-os@0.2.3` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -304,7 +304,7 @@ recorded length through a final identity check; an appended byte, concurrent
 growth, path replacement, or hard link fails closed. NFC paths use defined
 UTF-8 byte ordering, covered by one pinned golden bundle digest on every
 supported Node/runner combination. This SDK accepts only the explicitly listed
-`0.2.1` bundle generation; structural validity does not imply cross-SDK
+`0.2.3` bundle generation; structural validity does not imply cross-SDK
 compatibility, and a release with zero payload bytes cannot be created. Portable
 path validation rejects file/directory prefix conflicts, case-colliding prefix
 spellings, and Windows device aliases including superscript COM/LPT digits.
@@ -350,7 +350,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.2.1` exposes one browser target and five explicitly paired
+Version `0.2.3` exposes one browser target and five explicitly paired
 native development targets: a verified non-runnable portable directory, a
 Windows x64 unsigned-local-test EXE bundle, Linux x64 and Linux ARM64
 unsigned-local-test DEBs, and an Android development-signed APK. The

package/browser-runtime/ARCANE_SDK_BROWSER_RELEASE.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "builder": "arcane-sdk-browser-runtime-v1",
-  "sdkVersion": "0.2.1",
+  "sdkVersion": "0.2.3",
   "source": {
     "authority": "arcane-os-sdk",
     "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
@@ -29,8 +29,8 @@
     ]
   },
   "fileCount": 25,
-  "totalBytes": 9279974,
-  "contentSha256": "a9715c4b3aef70ec4042e4738089568d6588877b29582e0f758ed83897b6814f",
+  "totalBytes": 9280047,
+  "contentSha256": "3c82ed11b24c7b7b91b62f6dc52e0b1dcd444112a29cd48413eedc008380eb61",
   "files": [
     {
       "path": "ai/ARCANE_AI_BROWSER_WASM_COMPONENTS.json",
@@ -57,8 +57,8 @@
       "path": "ai/browser-speech-providers.mjs",
       "sourcePath": "browser-runtime/ai/browser-speech-providers.mjs",
       "provenance": "sdk-source-identity",
-      "bytes": 25982,
-      "sha256": "65e0a8da2bcd46b11c3ea2ca496105875977decc53d4e4c94ca56949dbb569b1"
+      "bytes": 26055,
+      "sha256": "6a2c0caa227d78028f42434b86231236055f0cfe0e3d6b71a4f651f7005a2614"
     },
     {
       "path": "ai/browser-speech.mjs",

package/browser-runtime/ai/browser-speech-providers.mjs

@@ -449,6 +449,7 @@ function createBrowserSpeechProvider({
     providerId,
     role,
     localOnly: true,
+    ...(role === "tts" ? { defaultVoice: authority.defaultVoice } : {}),
     repository: authority.repository,
     revision: authority.revision,
     runtime: authority.runtime,

package/docs/architecture.md

@@ -200,7 +200,7 @@ length with an EOF growth probe, and rechecked by handle and pathname identity.
 Every cumulative path prefix has one case-folded spelling and one file/directory
 kind; prefix topology conflicts and the complete portable Windows device-name
 set fail before creation or admission.
-The current SDK admits only the explicitly compatible `0.2.1` bundle
+The current SDK admits only the explicitly compatible `0.2.3` bundle
 generation and rejects zero-byte payload releases.
 
 Promotion retains any prior output as an identity-bound backup until the new
@@ -320,7 +320,7 @@ through SDK-bound verified readers rather than accepting a mutable source path
 as authority. Build completion requires provider verification, and later
 verify/run calls receive the exact artifact receipt.
 
-The SDK `0.2.1` runtime requires Arcane `0.8.12` or newer. Compatibility
+The SDK `0.2.3` runtime requires Arcane `0.8.12` or newer. Compatibility
 is contractual rather than exact-version pinning: the prepared Core must meet
 the highest minimum declared by the runtime, selected app, and bundled app
 dependencies; keep each app's Arcane protocol generation; and provide every

package/docs/reference/README.md

@@ -26,25 +26,27 @@ high-level page links to the relevant deep section instead of repeating it.
 | Load a reusable HTML component | [Runtime component catalog](runtime-components.md) |
 | Call `globalThis.Arcane` | [Arcane Core API](core/arcane-api.md) |
 | Subscribe to native events | [Arcane event reference](core/arcane-events.md) |
-| Use provider-neutral AI | [Arcane AI contracts](core/arcane-ai-contracts.md) |
+| Use provider-neutral AI lifecycle, chat, speech, persistence, or document context | [Normalized AI](#normalized-ai) |
 | Run a caller-authenticated local LLM in the browser | [Browser-WASM local AI](ai/browser-wasm.md) |
+| Run caller-authenticated Whisper or Kokoro in the browser | [Browser speech providers](ai/browser-speech.md) |
 | Use Arcane Ollama | [Arcane Ollama guide](arcane-ollama.md) |
 | Understand transports and protocol switching | [Protocol and host architecture](protocols.md) |
 | Run contract and behavior tests | [Behavioral testing](behavioral-testing.md) |
 
 ## Version scope and provenance
 
-This repository contains two related, explicitly versioned surfaces:
+This repository contains explicitly versioned surfaces with different owners:
 
 | Surface | Source identity | Meaning |
 | --- | --- | --- |
-| SDK and CLI | `arcane-os` `0.1.2` | The Node.js toolchain plus the browser-only `arcane-os/ai/browser-wasm` entrypoint in this checkout. |
-| Browser runtime | Arcane OS commit `567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e`, bundle `0.8.12`, protocol `arcane/1` | The exact 155-file runtime snapshot shipped under `runtime/`. |
+| SDK and CLI | `arcane-os` `0.2.3` | The Node.js toolchain plus the browser-only `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints in this checkout. |
+| Browser runtime | SDK source commit `f97ac4f2e7cc92a00a3a466c38a67446dd112acf`, SDK `0.2.3`, protocol `arcane/1` | The SDK-canonical exact 160-file runtime shipped under `runtime/`; Arcane OS commit `c540014afe69f14cf5ae60493b7295f36dbcec64` is legacy projection provenance, not a second source authority. |
+| Browser SDK runtime | SDK source commit `f97ac4f2e7cc92a00a3a466c38a67446dd112acf`, SDK `0.2.3` | The exact 25-file authenticated browser closure: EventManager/DOM instrumentation and pinned event dependencies, Wllama runtime assets, and SDK browser speech provider/store/Worker mechanisms. It contains no model weights or speech adapter/model bytes. |
 | Core reference snapshot | Arcane OS commit `567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e`, protocol `arcane/1` | The application-facing Core contract derived into `docs/reference/core/`. Canonical inventory and focused-member content was verified unchanged at Arcane OS `main` commit `13f3ce0ae34f77a3495331c8b4c30b1bb105f8ed`; SDK-local provenance, link, and package-boundary annotations are added explicitly. |
 
-The runtime receipt and Core reference remain distinct evidence even though
-they currently share one pinned upstream source identity. A browser module's
-bytes come from the generated runtime receipt. A native build selects one
+The SDK runtime receipt and Core reference are distinct evidence and have
+different current authorities. A browser module's bytes come from the SDK
+runtime receipt. A native build selects one
 explicit Arcane OS checkout and Core. This SDK version accepts that selection
 only after its current native plan checks the exact declared protocol, version,
 features, capabilities, methods, provider contract, and identity-bound
@@ -56,6 +58,32 @@ See [Core reference provenance](core/README.md) for the imported inventory and
 the exact distinction between a documentation snapshot and shipped runtime
 bytes.
 
+## Published 0.2.2
+
+The published package is exactly `arcane-os@0.2.2` from source commit
+`d5326d206bf0bec6ad82d53605e666841aa79899`. The npm `latest` dist-tag resolves
+to `0.2.2`; the separate `dev` dist-tag remains `0.1.0-dev.5`.
+
+The admission-aware `voice-transcription.html` lifecycle and shared
+`createSTTActivationController()` contract documented below are newer canonical
+source. They are not package authority in `0.2.2`; consumers require a fresh
+numeric publication before relying on them.
+
+| Evidence | Exact value |
+| --- | --- |
+| npm integrity | `sha512-JnLzZ4+FqX9tMgRv8HMcaCPSFx3xNNRf8BF8T03fD2ymg2g8cIGZRdD/3Tbd9PLtpx1PIKCpxz6nCP6ztnu1Nw==` |
+| npm shasum | `0b0d314acce48dcb5518470cd45a54221589d4d4` |
+| Immutable release tarball | `arcane-os-0.2.2.manifest.json`; artifact `9631659213`; 6,993,999 bytes; SHA-256 `e0fe1a556b603f67f5e3c142be7154b433312d3c0f3b58632df2e7fc43cc0ca7` |
+| GitHub release | [`0.2.2`](https://github.com/TheWizardNexus/arcane-os-sdk/releases/tag/0.2.2) (tag and title are both exactly `0.2.2`) |
+| Hosted source/artifact gate | [Check run 33034955277](https://github.com/TheWizardNexus/arcane-os-sdk/actions/runs/33034955277) |
+| Trusted publication | [Run 33035086265](https://github.com/TheWizardNexus/arcane-os-sdk/actions/runs/33035086265) |
+
+The npm SLSA provenance binds the published package to that exact source commit
+and `.github/workflows/publish-dev.yml`. Hashes prove byte identity or
+consistency; provenance establishes the recorded source/workflow relationship.
+Neither claim alone proves browser hardware support, native admission, or a
+particular application's provider/model policy.
+
 ## MDN-style page contract
 
 Public reference entries follow the established Arcane documentation model:
@@ -74,11 +102,12 @@ Public reference entries follow the established Arcane documentation model:
 
 ## Public runtime inventory
 
-The package exposes 163 semantic JavaScript records across 12 JavaScript
+The package exposes 169 semantic JavaScript records across 13 JavaScript
 entrypoints, plus eight JSON Schemas, its exact runtime manifest, and package
 metadata. Ten entrypoints are Node.js control-plane surfaces,
 `arcane-os/event-manager` runs in Node and browsers, and
-`arcane-os/ai/browser-wasm` is browser-only. The [machine-readable package
+`arcane-os/ai/browser-wasm` plus `arcane-os/ai/browser-speech` are browser-only.
+The [machine-readable package
 inventory](inventory/package-api.json) and [SDK member reference](sdk-api.md)
 are checked bidirectionally against every declared JavaScript export.
 
@@ -87,7 +116,7 @@ download, install, or self-update.
 
 The synchronized browser payload exposes:
 
-- 78 JavaScript module artifacts under `runtime/arcane/modules/`, including
+- 83 JavaScript module artifacts under `runtime/arcane/modules/`, including
   ESM modules, classic vendor globals, one worker protocol, and one Node-oriented
   mail transport;
 - 15 shared entity modules under `runtime/arcane/entities/`;
@@ -100,6 +129,43 @@ vendor support files that are not ESM imports. The runtime manifest remains the
 byte-level source of truth; the catalogs explain what those bytes let a
 developer do.
 
+## Normalized AI
+
+Portable applications start with the provider-neutral runtime rather than an
+Ollama, Wllama, Whisper, Kokoro, native, or cloud transport:
+
+| Need | Public surface | Availability |
+| --- | --- | --- |
+| Select, load, unload, inspect, cancel, and use LLM/STT/TTS independently | [`AIProviderRuntime.js`](runtime-modules.md#aiproviderruntimejs) | Cross-host controller; each registered provider declares its own host requirements. |
+| Observe sticky role state and startup settlement | [`AIRuntimeState.js`](runtime-modules.md#airuntimestatejs) | Cross-host EventTarget state; observation grants no authority. |
+| Offer explicit selected-model start/cancel UI | [`chat.html`](runtime-components.md#chathtml), [`speech.html`](runtime-components.md#speechhtml), and [`voice-transcription.html`](runtime-components.md#voice-transcriptionhtml) | Browser/native WebView components; user activation emits a cancelable request before any LLM or STT load intent, and recording stays disabled without sticky ready STT. |
+| Use Core-normalized chat | [`globalThis.Arcane.ai`](core/arcane-ai-contracts.md) | Native/Core only when separately admitted. |
+| Run a caller-selected GGUF LLM locally | [`arcane-os/ai/browser-wasm`](ai/browser-wasm.md) | Browser secure context with WebGPU/full-offload evidence, WebAssembly, and OPFS/DBOPFS. |
+| Run caller-selected Whisper/Kokoro locally | [`arcane-os/ai/browser-speech`](ai/browser-speech.md) | Browser with DBOPFS, Web Locks, Workers, and caller-supplied immutable runtime/model bytes. |
+| Add bounded persistent history and memory | [`PersistentAIChatSession.js`](runtime-modules.md#persistentaichatsessionjs) | Browser/native WebView runtime with ChatEntity/DBOPFS and a configured chat function. |
+| Add explicit document search/context | [`DBOPFSDocumentLibrary.js`](runtime-modules.md#dbopfsdocumentlibraryjs) | Existing DBOPFS-style adapter; search occurs only after the app calls it or deliberately wires its context builder into chat. |
+
+There is no automatic local-to-cloud, browser-to-Core, provider-to-provider, or
+storage fallback. Tool calls remain structural data until application-owned
+policy and code decide whether to execute them. App prompts, model defaults,
+profiles, tools, business policy, and private data remain app-owned.
+
+An explicitly selected but unloaded model is not “ready.” `chat.html` keeps
+Send disabled and exposes a visible keyboard-operable LLM Start/Try again or
+Cancel loading control. `speech.html` and `voice-transcription.html` keep their
+recording operations unavailable and share the equivalent Start
+transcription/Try again/Cancel loading control for STT. Applications can
+override `requestAIActivation(intent)` or `requestSTTActivation(intent)`, or
+cancel the corresponding activation-request event. Imports and state
+observation emit no lifecycle intent, and default
+`startTranscription=false` does not request an STT startup load or begin an
+automatic model download. It does not unload a role started independently.
+Compatibility availability never creates ready STT/TTS state without an
+admitted, loaded provider. Shared STT cancel/destroy propagates an owned signal,
+and TTS Mute/Unmute updates the shared lifecycle owner. The selected TTS
+provider/model catalog owns its default voice; a saved OpenAI voice is not
+forwarded to another provider route.
+
 ## Authority and feature detection
 
 The presence of a JavaScript function is not permission to use it. Native
@@ -113,9 +179,9 @@ as package admission. Each method rechecks native policy at invocation time.
 
 ## Source, receipts, and licensing
 
-- [Pinned upstream ARCANE-OS source](https://github.com/TheWizardNexus/ARCANE-OS/tree/567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e)
-- [Exact runtime release manifest](../../runtime/ARCANE_RUNTIME_RELEASE.json)
-- [Reviewed runtime source pin](../../tools/runtime-source.json)
+- [Exact SDK runtime release manifest](../../runtime/ARCANE_RUNTIME_RELEASE.json)
+- [SDK runtime authority record](../../tools/runtime-source.json)
+- [Exact browser AI runtime receipt](../../browser-runtime/ARCANE_SDK_BROWSER_RELEASE.json)
 - [AGPL license](../../LICENSE)
 - [Commercial-license notice](../../COMMERCIAL-LICENSE.md)
 - [Third-party and distribution notice](../../NOTICE)

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

@@ -0,0 +1,336 @@
+# Browser speech providers
+
+`arcane-os/ai/browser-speech` is the shipped browser-only provider package for
+caller-supplied Whisper speech-to-text and Kokoro text-to-speech runtimes. It
+implements the same provider-neutral role contract used by
+`AIProviderRuntime.js`; it does not ship model weights, runtime adapter bytes,
+voices, download URLs, a catalog, or a cloud fallback.
+
+Use this page when an application deliberately owns browser-local speech model
+and runtime selection. For ordinary application AI lifecycle and status, start
+with the [normalized AI guide](../README.md#normalized-ai) and
+[`AIProviderRuntime.js`](../runtime-modules.md#aiproviderruntimejs).
+
+## Availability
+
+| Host | Availability | Notes |
+| --- | --- | --- |
+| Browser | Shipped | Requires DBOPFS/OPFS, Web Locks, Workers, Fetch or an injected fetch function, Blob/File, and object URLs. |
+| Native WebView | Conditional | Works only when the WebView exposes the same browser APIs and the application admits every artifact. This does not invoke Core speech. |
+| Node | Importable, execution unavailable | The ESM subpath is exported, but `0.2.2` publishes no Node speech storage, Worker, audio-decoder, or execution adapter. |
+| Cloud | Not provided | A cloud speech provider can implement `arcane-ai-provider/2`, but this package never selects one. |
+
+Browser speech is independent from `arcane-os/ai/browser-wasm`: the Wllama
+entrypoint owns the LLM role, while this entrypoint owns optional STT and TTS
+providers. Each role loads, unloads, reports status, cancels, and recovers
+independently.
+
+## Import
+
+```javascript
+import {
+  BROWSER_SPEECH_ARTIFACT_PROTOCOL,
+  createBrowserKokoroProvider,
+  createBrowserSpeechAuthority,
+  createBrowserWhisperProvider,
+  createDbopfsSpeechArtifactStore
+} from 'arcane-os/ai/browser-speech';
+```
+
+The entrypoint exports exactly those five names. Importing it downloads no
+model and starts no Worker.
+
+## `BROWSER_SPEECH_ARTIFACT_PROTOCOL`
+
+The constant is exactly `"arcane-ai-browser-speech-artifacts/1"`. It identifies
+an SDK-created artifact store; it is not model authority, a capability grant,
+or evidence that a cache is complete.
+
+## `createBrowserSpeechAuthority()`
+
+```text
+createBrowserSpeechAuthority({
+  providerId,
+  role,
+  model,
+  runtime,
+  security
+} = {})
+```
+
+Validates and freezes one caller-owned model/runtime declaration. Construction
+binds the declared identities and descriptor rules; actual downloaded or cached
+runtime-graph closure is validated by `store.prepare()` before a Worker starts.
+
+### Authority input
+
+| Field | Contract |
+| --- | --- |
+| `providerId` | Trimmed 1–128 character provider identity. |
+| `role` | Exactly `"stt"` or `"tts"`. |
+| `model.id` | Caller-owned model identity. |
+| `model.repository` | Immutable logical repository identity; the SDK does not resolve it. |
+| `model.revision` | Caller-pinned revision. Every model URL must contain this revision or its supplied SHA-256. |
+| `model.files` | Nonempty unique `{path,url,bytes?,sha256?,mediaType?}[]`. Paths are normalized relative paths; URLs are immutable HTTPS or same-origin URLs without credentials/fragments. |
+| `model.defaultVoice` | Required only for TTS. |
+| `runtime.adapter` | Exactly `"transformers-whisper"` for STT or `"kokoro-js"` for TTS. |
+| `runtime.version` / `runtime.revision` | Caller-pinned runtime identity. |
+| `runtime.entry` | Path of one JavaScript module in `runtime.files`. |
+| `runtime.files` | Nonempty immutable runtime closure. The entry module must be self-contained: undeclared imports, re-exports, executable strings, alternate transports, and child workers are rejected. |
+| `security` | Closed `{secure?,checks?:{byteLength?,sha256?}}` artifact policy. Disabled checks are disclosed rather than silently claimed. |
+
+The result is a frozen `arcane-ai-model-authority/1` record. The SDK owns the
+validation rules; the application owns every model/runtime choice, license,
+revision, URL, hash, voice, and business policy.
+
+Provider security resolves each field independently in this order: SDK default,
+`appSecurity`, provider `security`, then `load({security})`. The SDK default is
+`secure:false`. After resolution, each omitted check defaults to the effective
+`secure` value; an explicit `checks.byteLength` or `checks.sha256` boolean
+overrides that default. An enabled check requires the corresponding `bytes` or
+`sha256` field on every admitted artifact and fails closed when evidence is
+missing or mismatched. A disabled check never becomes a claim that bytes were
+verified. Direct `store.prepare()` has only its supplied security scope above
+the SDK default because it is not bound to a provider.
+
+## `createDbopfsSpeechArtifactStore()`
+
+```text
+createDbopfsSpeechArtifactStore({
+  dbopfs,
+  tableName = 'arcane_ai_browser_speech',
+  fetchImpl = null,
+  objectUrlFactory = null
+} = {})
+```
+
+Adapts an existing DBOPFS instance into an authority-scoped store. The returned
+frozen object exposes `{protocol,tableName,prepare,remove}`.
+
+`prepare(authority,{signal,onProgress,offline=false,security})`:
+
+1. obtains an exclusive Web Lock for the exact authority;
+2. admits a complete cached manifest when every record still matches;
+3. otherwise, unless `offline:true`, downloads every declared file without
+   credentials;
+4. enforces enabled byte-length and SHA-256 checks;
+5. validates the closed runtime module graph;
+6. commits `arcane.ai.browser-speech.assets.v1` only after every file succeeds;
+7. returns materialized object URLs plus a `release()` callback.
+
+An installation or cache-validation failure removes incomplete stored state for
+that authority. A request or provider-use failure does not imply cache removal.
+`offline:true` never falls back to network and rejects with
+`ARCANE_AI_ARTIFACT_OFFLINE_MISS` when no admitted cache exists.
+
+## `createBrowserWhisperProvider()`
+
+```text
+createBrowserWhisperProvider({
+  id = 'arcane-browser-whisper',
+  localOnly = true,
+  model,
+  runtime,
+  appSecurity,
+  security,
+  store,
+  offline = false
+} = {})
+```
+
+Returns a frozen `arcane-ai-provider/2` object for role `stt`. The provider
+surface is `{protocol,role,id,localOnly,catalog,inspect,status,load,request,
+unload,dispose}`.
+
+The only request operation is `transcribe`:
+
+```javascript
+async function transcribeAfterUserChoice(provider, pcmFloat32, signal) {
+  // The admitted Whisper provider must already be ready.
+  const result = await provider.request({
+    role: 'stt',
+    operation: 'transcribe',
+    signal,
+    payload: {
+      audio: pcmFloat32,
+      sampleRate: 16_000
+    }
+  });
+
+  console.log(result.text);
+}
+```
+
+`audio` must be a `Float32Array` sampled at exactly 16,000 Hz. The provider-native
+provider result is a structured `{text}` record transferred by Worker
+`postMessage`; the client does not re-freeze that cloned record. The same
+provider also accepts the shared AI.js STT
+payload `{audio:Blob|File,mimeType,model}`. It verifies `model`, decodes the
+browser audio to authoritative 16 kHz mono PCM, and then enters the same provider-native
+provider operation. Decode support and failure remain explicit.
+
+## `createBrowserKokoroProvider()`
+
+```text
+createBrowserKokoroProvider({
+  id = 'arcane-browser-kokoro',
+  localOnly = true,
+  model,
+  runtime,
+  appSecurity,
+  security,
+  store,
+  offline = false
+} = {})
+```
+
+Returns the same provider/2 lifecycle for role `tts`. The only request
+operation is `synthesize`:
+
+```javascript
+async function synthesizeAfterUserChoice(provider, signal) {
+  // The admitted Kokoro provider must already be ready.
+  const result = await provider.request({
+    role: 'tts',
+    operation: 'synthesize',
+    signal,
+    payload: {
+      text: 'Hello from Arcane.',
+      voice: 'caller-owned-voice-id',
+      speed: 1
+    }
+  });
+
+  console.log(result.audio, result.sampleRate, result.voice);
+}
+```
+
+`speed` must be greater than zero and at most four. Omitted `voice` selects the
+caller-supplied `model.defaultVoice`. The provider-native result is the structured
+`{audio:Float32Array,sampleRate:24000,voice}` record transferred by Worker
+`postMessage`; the client does not re-freeze that cloned record. The shared
+AI.js TTS payload is
+`{model,input,responseFormat,voice?,speed?}`. Only `responseFormat:"wav"` is
+admitted; the provider maps it to `{text,voice,speed}` and returns frozen
+`{audio:Uint8Array,contentType:"audio/wav"}` containing 24 kHz mono PCM.
+Shared AI.js synthesis reads the selected model's catalog default and never
+replaces it with a voice saved for a different provider route.
+
+## Lifecycle and status
+
+Whisper and Kokoro use the same independent state machine:
+
+| Operation | Behavior |
+| --- | --- |
+| `catalog()` | Returns the single caller-admitted model descriptor. TTS exposes its admitted `defaultVoice`; STT has no voice field. |
+| `inspect(selection,{signal})` | Returns `{available:true,authority}` only for the exact provider/model/local selection; mismatch returns an unavailable record. |
+| `status()` | Returns `{role,providerId,modelId,state,loaded,busy,generation,errorCode,cache}`. |
+| `load(context)` | Requires `{role,selection,progress,signal?,security?}`, admits/cache-materializes artifacts, creates one role Worker, and loads the adapter. Compatible repeated loads coalesce. |
+| `request(context)` | Runs exactly one STT or TTS operation. A provider rejects concurrent use with `ARCANE_AI_PROVIDER_BUSY`. |
+| `unload()` | Aborts active load/use, terminates the Worker, releases object URLs, and returns `unloaded`. |
+| `dispose()` | Completes unload and permanently returns `disposed`. |
+
+Cancellation after a Worker request begins terminates that Worker slot and
+returns the provider to `unloaded`; a later request requires a fresh load. A
+shared STT request can instead be aborted while the browser is still decoding
+its `Blob` or `File`, before Worker use begins. That request rejects with
+`ARCANE_AI_REQUEST_ABORTED`, but the loaded Worker remains intact and the
+provider stays `ready`. Worker crash/message failures become explicit error
+state. No result is retried through another provider.
+
+Register the providers with the projected
+[`AIProviderRuntime`](../runtime-modules.md#aiproviderruntimejs) to normalize
+selection, startup, application calls, and
+[`AIRuntimeState`](../runtime-modules.md#airuntimestatejs) observation. The
+provider objects themselves do not expose an event target.
+
+```javascript
+async function loadSpeechProviderAfterUserChoice(provider) {
+  const selection = {
+    providerId: provider.id,
+    modelId: provider.catalog()[0].id,
+    localOnly: true
+  };
+  return provider.load({
+    role: provider.role,
+    selection,
+    progress(update) {
+      console.info(update.phase, update.completed, update.total);
+    }
+  });
+}
+```
+
+The example only defines the operation; invoke it from an explicit user action
+after showing the admitted runtime/model and download policy. Requests are
+valid only after that load resolves successfully. Applications
+register and configure browser-speech providers on the shared runtime. `AI.js`
+obtains that singleton and translates its existing browser speech request shapes
+at this one provider boundary; it does not register providers, choose
+authorities, or trigger a hidden model download.
+
+## Errors
+
+| Code | Meaning |
+| --- | --- |
+| `ARCANE_AI_MODEL_AUTHORITY_REQUIRED` | Selection or authority does not match the provider. |
+| `ARCANE_AI_INVALID_REQUEST` | Role, operation, audio, text, voice, or speed is invalid. |
+| `ARCANE_AI_NOT_READY` | Use was requested before a successful load. |
+| `ARCANE_AI_PROVIDER_BUSY` | The role already has an active request. |
+| `ARCANE_AI_PROVIDER_DISPOSED` | Load/use was requested after disposal. |
+| `ARCANE_AI_REQUEST_ABORTED` | The caller's AbortSignal cancelled work. |
+| `ARCANE_AI_OPERATION_SUPERSEDED` | A newer unload/load/dispose generation replaced the operation. |
+| `ARCANE_AI_ARTIFACT_SOURCE_INVALID` | Artifact bytes or body shape are not readable. |
+| `ARCANE_AI_ARTIFACT_SOURCE_UNAVAILABLE` | Fetch is unavailable. |
+| `ARCANE_AI_ARTIFACT_DOWNLOAD_FAILED` | Network or HTTP download failed. |
+| `ARCANE_AI_ARTIFACT_SOURCE_CHANGED` | Redirect/final URL differs from the admitted immutable URL. |
+| `ARCANE_AI_ARTIFACT_SIZE_MISMATCH` | Enabled byte-length evidence differs. |
+| `ARCANE_AI_ARTIFACT_DIGEST_MISMATCH` | Enabled SHA-256 evidence differs. |
+| `ARCANE_AI_ARTIFACT_CACHE_REJECTED` | DBOPFS did not preserve the completed file. |
+| `ARCANE_AI_ARTIFACT_OFFLINE_MISS` | Strict offline use has no admitted complete cache. |
+| `ARCANE_AI_STORAGE_BUSY` | Another context owns the same authority lock. |
+| `ARCANE_AI_STORAGE_UNAVAILABLE` / `ARCANE_AI_STORAGE_READ_FAILED` / `ARCANE_AI_STORAGE_DELETE_FAILED` | The selected DBOPFS store is unavailable or could not read/delete the authority. |
+| `ARCANE_AI_RUNTIME_MODULE_GRAPH_UNDECLARED` | Runtime code leaves the closed self-contained module grammar. |
+| `ARCANE_AI_WORKER_CRASHED` / `ARCANE_AI_WORKER_MESSAGE_ERROR` | The isolated adapter Worker failed. |
+| `ARCANE_AI_ADAPTER_PROTOCOL_MISMATCH` | The Worker/client/provider protocol is not the SDK-owned contract. |
+| `ARCANE_AI_PROVIDER_LOAD_FAILED` / `ARCANE_AI_PROVIDER_REQUEST_FAILED` / `ARCANE_AI_PROVIDER_UNAVAILABLE` | Adapter load/request failed or the admitted runtime did not expose the requested provider. |
+| `ARCANE_AI_INVALID_PROVIDER_RESULT` | Whisper/Kokoro returned a result outside the normalized contract. |
+| `ARCANE_AI_UNDECLARED_ARTIFACT` | The runtime requested a file outside its admitted closure. |
+| `ARCANE_AI_AUDIO_DECODE_UNAVAILABLE` / `ARCANE_AI_AUDIO_DECODE_FAILED` | Shared Blob/File STT cannot obtain a browser decoder or cannot produce nonempty 16 kHz mono PCM. |
+| `ARCANE_AI_UNSUPPORTED_RESPONSE_FORMAT` | Shared TTS requested a format other than `wav`. |
+
+## Security and ownership
+
+- The SDK contains no speech model or adapter runtime bytes in this entrypoint.
+- The application must verify the license and authority for every supplied byte.
+- URLs never carry credentials; fetch uses `credentials: "omit"`.
+- Mutable `main`, `master`, and `latest` paths are rejected.
+- The completion manifest is consistency evidence for the admitted DBOPFS
+  bytes. It is not publisher authenticity by itself.
+- The runtime entry is isolated in a Worker and limited to its declared
+  artifact closure.
+- Tool calls are an LLM concern; speech providers execute no application tool.
+- A native `Arcane.speech` service is a different privileged host path. This
+  browser package neither calls it nor inherits its capability admission.
+
+<details>
+<summary>Protocol details</summary>
+
+The artifact store identifies itself as
+`arcane-ai-browser-speech-artifacts/1`. Authorities use
+`arcane-ai-model-authority/1`. Providers implement `arcane-ai-provider/2` with
+roles `stt` and `tts`; their only operations are `transcribe` and `synthesize`.
+The Worker client additionally binds exact role, operation, request IDs, and
+generation so stale or cross-role messages cannot settle current work.
+
+</details>
+
+## Related
+
+- [Normalized AI](../README.md#normalized-ai)
+- [Browser-WASM LLM](browser-wasm.md)
+- [AIProviderRuntime.js](../runtime-modules.md#aiproviderruntimejs)
+- [AIRuntimeState.js](../runtime-modules.md#airuntimestatejs)
+- [PersistentAIChatSession.js](../runtime-modules.md#persistentaichatsessionjs)
+- [Availability and normalization](../availability-and-normalization.md)
+- [Protocol architecture](../protocols.md#portable-ai-provider-runtime)