arcane-os 0.2.0 → 0.2.2

package/docs/reference/cli.md

@@ -168,8 +168,10 @@ npm exec -- arcane doctor --workspace . --arcane-root "../Arcane OS"
 ### Overview
 
 Authenticates one selected application's physical browser runtime, generates
-its standard browser import map, and commits the map artifact and matching
-managed HTML entry as one bounded refresh.
+its standard browser import map, and commits the map artifact and configured
+managed HTML entry as one bounded refresh. Packaging uses the same operation
+with the complete included `.html`/`.htm` document inventory so every packaged
+browser page receives byte-identical managed import-map JSON.
 
 ```text
 arcane import-map [--workspace <directory>] [--app <id>]
@@ -183,8 +185,10 @@ identical executable alias.
 The generated artifact is
 `apps/<id>/modules/arcane.importmap.json`. Its exact JSON is also installed in
 the app entry as `<script type="importmap" data-arcane-import-map>` before
-module loading. In SDK `0.1.2`, the authenticated physical-v1 runtime produces
-86 entries and intentionally has no package-root mapping.
+module loading. In SDK `0.2.1`, the complete authenticated physical-v1 runtime
+produces 91 entries and intentionally has no package-root mapping. That count
+describes the shipped SDK closure; the command receipt remains authoritative
+for the exact map written to the selected application.
 
 ### Result and safety
 
@@ -200,8 +204,10 @@ Success returns the normal selected-workspace wrapper:
         artifactPath,
         artifactRelativePath,
         entryPath,
+        documentPaths,
+        documentCount:1,
         imports,
-        entryCount:86,
+        entryCount:91,
         excludedModules:['modules/CaseEvidenceIndexer.js'],
         files:[
             {role:'artifact',path,bytes,sha256},
@@ -213,12 +219,25 @@ Success returns the normal selected-workspace wrapper:
 }
 ```
 
-The two file records bind the committed byte length and SHA-256 for the artifact
-and HTML entry. A post-commit observer failure preserves delivery as a successful
-receipt with `eventDelivery.status === 'degraded'` and
+For the direct CLI command, `documentPaths` contains the configured entry and
+`documentCount` is one. The `files` array always places the artifact first, the
+configured entry second, and any additional packaging documents afterward as
+`{role:'document',path,bytes,sha256}` in deterministic order. Every record binds
+the committed byte length and SHA-256. A post-commit observer failure preserves
+delivery as a successful receipt with `eventDelivery.status === 'degraded'` and
 `ARCANE_EVENT_DELIVERY_FAILED`; it does not roll back valid application bytes.
 Packaging refuses a committed refresh that reports cleanup warnings.
 
+An authenticated external package also publishes
+`/ARCANE_RUNTIME_PROJECTION.json`. The immutable JSON is
+`{schemaVersion:1,kind:'arcane-app-runtime-projection',sdkVersion,
+pathPrefix:'arcane/',fileCount,totalBytes,contentSha256,
+files:[{path,bytes,sha256}]}` and is bound by the packaged release inventory.
+The development server exposes the same public route from its authenticated
+workspace projection. The private `/ARCANE_APP_RELEASE.json` authority is not
+served to application code. Invalid or forged projection data fails
+`ARCANE_RUNTIME_PROJECTION_INVALID`.
+
 The canonical integrated-legacy workspace has a deliberate compatibility
 result instead of an artifact: `importMap.skipped` is `true`,
 `importMap.compatibility` is `'integrated-legacy'`, and the reason states that
@@ -554,8 +573,8 @@ Success returns:
 ```javascript
 {
     packageName:'arcane-os',
-    currentVersion:'0.1.0',
-    registryVersion:'0.1.2',
+    currentVersion:'0.2.0',
+    registryVersion:'0.2.1',
     tag:'latest',
     status:'update-available', // or 'current' or 'ahead'
     updateAvailable:true,

package/docs/reference/core/arcane-ai-contracts.md

@@ -7,6 +7,30 @@ APIs. Start with the method index in the [Arcane API Reference](arcane-api.md).
 The type names below are documentation notation for plain JavaScript values.
 They are not TypeScript declarations.
 
+## Portable SDK AI and Core AI
+
+The SDK `0.2.1` has two related but separate normalized boundaries:
+
+| Boundary | Use | Host |
+|---|---|---|
+| [`AIProviderRuntime.js`](../runtime-modules.md#aiproviderruntimejs) plus [`AIRuntimeState.js`](../runtime-modules.md#airuntimestatejs) | Register and control independent LLM, STT, and TTS providers through `arcane-ai-provider/2`; observe sticky state and startup barriers. | Cross-host controller/state; each provider retains its own browser, native, or cloud requirements. |
+| `globalThis.Arcane.ai` and `globalThis.Arcane.speech` | Call an admitted Core-normalized AI or native speech method. | Native/Core only when the current app, method, capability, provider, and host are admitted. |
+
+The browser-only [`arcane-os/ai/browser-wasm`](../ai/browser-wasm.md)
+entrypoint provides a caller-authenticated local LLM adapter, and
+[`arcane-os/ai/browser-speech`](../ai/browser-speech.md) provides
+caller-authenticated Whisper/Kokoro provider mechanisms. Neither browser
+entrypoint grants Core authority or silently falls back to native/cloud.
+
+[`PersistentAIChatSession.js`](../runtime-modules.md#persistentaichatsessionjs)
+can bind the same chat API to existing ChatEntity/DBOPFS history and memory.
+[`DBOPFSDocumentLibrary.js`](../runtime-modules.md#dbopfsdocumentlibraryjs)
+provides explicit bounded retrieval context. Those mechanisms preserve the
+existing storage semantics. Construction alone performs no search. When an
+application explicitly supplies the document library's context builder, each
+prepared send performs its bounded lexical retrieval automatically; neither
+mechanism executes a tool.
+
 ## Contract conventions
 
 | Input style | Unknown keys | Object rules |
@@ -57,15 +81,17 @@ For a provider-portable request, send only `messages`, optional
 `expectedProvider`, and optional `format`.
 
 ```js
-const profile = await Arcane.ai.profile();
-
-const result = await Arcane.ai.chat({
-  expectedProvider: profile.provider,
-  messages: [
-    { role: "system", content: "Answer briefly and accurately." },
-    { role: "user", content: "What models are available?" }
-  ]
-});
+async function askAvailableModelsAfterUserChoice() {
+  const profile = await Arcane.ai.profile();
+
+  return Arcane.ai.chat({
+    expectedProvider: profile.provider,
+    messages: [
+      { role: "system", content: "Answer briefly and accurately." },
+      { role: "user", content: "What models are available?" }
+    ]
+  });
+}
 ```
 
 ### AI chat message
@@ -490,6 +516,14 @@ Successful mutating AI methods include `ArcaneOperation`.
 
 ## Speech
 
+This section documents admitted, capability-gated Core/native speech calls.
+For caller-owned browser-local STT/TTS providers, use the separate
+[browser speech package](../ai/browser-speech.md). Those browser providers
+directly implement the provider-neutral runtime contract. `Arcane.speech`
+remains a separate Core/native API unless an application explicitly supplies
+an adapter; their transport, artifact authority, capability, and error
+boundaries are not interchangeable.
+
 ### Speech status
 
 `Arcane.speech.status()` takes no arguments and returns `SpeechStatus`.

package/docs/reference/inventory/package-api.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.2.0",
+  "sdkVersion": "0.2.1",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 163,
+  "memberCount": 169,
   "members": [
     {
       "id": "root:APP_BUNDLE_DESCRIPTOR_NAME",
@@ -2046,16 +2046,16 @@
       "name": "validateWorkspace",
       "displayName": "validateWorkspace()",
       "kind": "function",
-      "signature": "async validateWorkspace({workspaceRoot=process.cwd(), appId, signal, onEvent}={})",
+      "signature": "async validateWorkspace({workspaceRoot=process.cwd(), appId, allowMissingManagedImportMap=false, signal, onEvent}={})",
       "entrypoints": [
         "arcane-os"
       ],
       "primaryImport": "arcane-os",
       "group": "Workspace, doctor, repository, and server",
-      "summary": "Runs canonical workspace, runtime, descriptor, and selected-app validation with progress events.",
+      "summary": "Runs canonical workspace, runtime, descriptor, selected-app, and exact installed-SDK validation with progress events.",
       "availability": "Node",
       "protocol": "Node ESM",
-      "normalization": "SDK-normalized inputs, errors, events, and documented result"
+      "normalization": "Returns a frozen workspace receipt and, for external workspaces, the exact canonical or npm-alias-bound SDK installation authority"
     },
     {
       "id": "root:verifyApp",
@@ -2644,6 +2644,22 @@
       "protocol": "arcane-ai-browser-wasm/2 over the provider-neutral arcane-ai-adapter/1 boundary",
       "normalization": "Exact immutable runtime and component identity; it contains no model weights or model catalog"
     },
+    {
+      "id": "browser-wasm:adaptV1LlmProvider",
+      "name": "adaptV1LlmProvider",
+      "displayName": "adaptV1LlmProvider()",
+      "kind": "function",
+      "signature": "adaptV1LlmProvider(provider)",
+      "entrypoints": [
+        "arcane-os/ai/browser-wasm"
+      ],
+      "primaryImport": "arcane-os/ai/browser-wasm",
+      "group": "Browser-WASM local AI",
+      "summary": "Adapts one compatible browser LLM provider to the provider-neutral LLM role contract.",
+      "availability": "Browser; the wrapped provider retains its own WebGPU, storage, model, and lifecycle requirements",
+      "protocol": "arcane-ai-provider/2 adapted from the browser LLM adapter surface",
+      "normalization": "Projects catalog, inspection, status, lifecycle, chat, stream, cancellation, and disposal without adding a provider or fallback"
+    },
     {
       "id": "browser-wasm:createArcaneAI",
       "name": "createArcaneAI",
@@ -2658,7 +2674,7 @@
       "summary": "Creates the provider-neutral browser AI facade and LLM lifecycle controller around one compatible provider or controller.",
       "availability": "Browser; the selected provider observes its own WebAssembly, storage, and model readiness",
       "protocol": "arcane-ai-adapter/1",
-      "normalization": "Normalizes lazy or manual load, fieldwise app/provider/load security inheritance from SDK secure:false, lifecycle status, cancellation, streaming completion, and structural tool-call visibility without executing tools"
+      "normalization": "Normalizes lazy or manual load, fieldwise app/provider/load security inheritance from SDK secure:false, lifecycle status, cancellation, streaming completion, and structural tool-call visibility without executing tools; an existing ModelController retains its preconfigured security/load policy and rejects a new security option"
     },
     {
       "id": "browser-wasm:createBrowserModelSource",
@@ -2671,24 +2687,24 @@
       ],
       "primaryImport": "arcane-os/ai/browser-wasm",
       "group": "Browser-WASM local AI",
-      "summary": "Validates a canonical caller-supplied {id, url, bytes?, sha256?} descriptor and creates its cancellable no-credentials HTTPS download source.",
-      "availability": "Browser with Fetch and a readable response body; each direct open call performs its configured HTTPS fetch",
-      "protocol": "Caller-supplied immutable HTTPS model URL with optional expected byte length and SHA-256",
-      "normalization": "Canonical frozen descriptor and download handle; expected fields are required and enforced only for their effective enabled checks, and model license is not runtime admission"
+      "summary": "Validates a caller-supplied ordered multi-file model descriptor (or the legacy one-file shape) and creates cancellable no-credentials HTTPS member downloads.",
+      "availability": "Browser with Fetch and a readable response body; each direct member open performs its configured HTTPS fetch",
+      "protocol": "Caller-supplied immutable HTTPS model-file URLs with optional expected byte lengths and SHA-256 values",
+      "normalization": "Canonical frozen ordered descriptor and per-member download handle; expected fields are required and enforced only for their effective enabled checks, and model license is not runtime admission"
     },
     {
       "id": "browser-wasm:createBrowserWasmLlmProvider",
       "name": "createBrowserWasmLlmProvider",
       "displayName": "createBrowserWasmLlmProvider()",
       "kind": "function",
-      "signature": "createBrowserWasmLlmProvider({ source, store, loadDefaults={}, security, logger=console }={})",
+      "signature": "createBrowserWasmLlmProvider({ source, sources, store, loadDefaults={}, security, logger=console }={})",
       "entrypoints": [
         "arcane-os/ai/browser-wasm"
       ],
       "primaryImport": "arcane-os/ai/browser-wasm",
       "group": "Browser-WASM local AI",
       "summary": "Creates the packaged Wllama browser provider with effective-check disclosure, honest integrity status, serialized inference, streaming, abort, unload, and probe operations.",
-      "availability": "Browser; WebAssembly required, WebGPU optional, enabled checks fail closed, and successful Wllama loading is always required",
+      "availability": "Browser secure context with WebAssembly, OPFS/DBOPFS, WebGPU, and admitted full-offload/buffer/queue/fence evidence; no CPU fallback",
       "protocol": "arcane-ai-adapter/1 with OpenAI-like chat completion and streaming envelopes",
       "normalization": "Frozen lifecycle/status/security/integrity records and structured tool-call data; security fields inherit by scope and the SDK never invokes application tools"
     },
@@ -2697,7 +2713,7 @@
       "name": "createDbopfsModelStore",
       "displayName": "createDbopfsModelStore()",
       "kind": "function",
-      "signature": "createDbopfsModelStore({ dbopfs, tableName='arcane_ai_browser_models' }={})",
+      "signature": "createDbopfsModelStore({ dbopfs, tableName='arcane_ai_browser_models', estimateStorage=null }={})",
       "entrypoints": [
         "arcane-os/ai/browser-wasm"
       ],
@@ -2705,8 +2721,88 @@
       "group": "Browser-WASM local AI",
       "summary": "Adapts an existing DBOPFS instance into a model cache that records observed bytes, commits metadata last, and hashes only when SHA-256 checking is enabled.",
       "availability": "Browser with a ready DBOPFS instance and OPFS support",
-      "protocol": "arcane.ai.browser-wasm.model.v3 completion manifests over existing DBOPFS method semantics",
+      "protocol": "arcane.ai.browser-wasm.model.v4 completion manifests over existing DBOPFS method semantics",
       "normalization": "Returns cached or installed receipts with observed byte count and per-check outcomes; disabled expected-length and SHA-256 checks do not compare or hash, while enabled checks fail closed"
+    },
+    {
+      "id": "browser-speech:BROWSER_SPEECH_ARTIFACT_PROTOCOL",
+      "name": "BROWSER_SPEECH_ARTIFACT_PROTOCOL",
+      "displayName": "BROWSER_SPEECH_ARTIFACT_PROTOCOL",
+      "kind": "constant",
+      "signature": "const BROWSER_SPEECH_ARTIFACT_PROTOCOL",
+      "entrypoints": [
+        "arcane-os/ai/browser-speech"
+      ],
+      "primaryImport": "arcane-os/ai/browser-speech",
+      "group": "Browser speech providers",
+      "summary": "Stable protocol identifier for authenticated browser speech artifact stores.",
+      "availability": "Browser metadata; model/runtime admission and use require DBOPFS, Web Locks, Workers, and caller-supplied immutable artifacts",
+      "protocol": "arcane-ai-browser-speech-artifacts/1 over arcane-ai-provider/2",
+      "normalization": "Exact immutable protocol value; it grants no model authority and names no model download"
+    },
+    {
+      "id": "browser-speech:createBrowserKokoroProvider",
+      "name": "createBrowserKokoroProvider",
+      "displayName": "createBrowserKokoroProvider()",
+      "kind": "function",
+      "signature": "createBrowserKokoroProvider(options={})",
+      "entrypoints": [
+        "arcane-os/ai/browser-speech"
+      ],
+      "primaryImport": "arcane-os/ai/browser-speech",
+      "group": "Browser speech providers",
+      "summary": "Creates a local-only Kokoro text-to-speech provider for the provider-neutral AI runtime.",
+      "availability": "Browser with DBOPFS, Web Locks, Workers, object URLs, and a caller-admitted self-contained kokoro-js runtime/model closure",
+      "protocol": "arcane-ai-provider/2 tts/synthesize",
+      "normalization": "Independent load, status, request, unload, cancellation, and disposal; provider-native requests return 24000 Hz Float32Array PCM, while shared AI.js requests admit only wav and return frozen Uint8Array audio/wav data; never selects a cloud fallback"
+    },
+    {
+      "id": "browser-speech:createBrowserSpeechAuthority",
+      "name": "createBrowserSpeechAuthority",
+      "displayName": "createBrowserSpeechAuthority()",
+      "kind": "function",
+      "signature": "createBrowserSpeechAuthority({ providerId, role, model, runtime, security }={})",
+      "entrypoints": [
+        "arcane-os/ai/browser-speech"
+      ],
+      "primaryImport": "arcane-os/ai/browser-speech",
+      "group": "Browser speech providers",
+      "summary": "Validates and freezes one caller-owned Whisper or Kokoro model/runtime authority.",
+      "availability": "Browser descriptor construction; using the authority requires the selected storage and provider Web APIs",
+      "protocol": "arcane-ai-model-authority/1",
+      "normalization": "Requires immutable URL identity, exact adapter role, unique paths/URLs, and caller-supplied revision with optional byte-length and SHA-256 checks"
+    },
+    {
+      "id": "browser-speech:createBrowserWhisperProvider",
+      "name": "createBrowserWhisperProvider",
+      "displayName": "createBrowserWhisperProvider()",
+      "kind": "function",
+      "signature": "createBrowserWhisperProvider(options={})",
+      "entrypoints": [
+        "arcane-os/ai/browser-speech"
+      ],
+      "primaryImport": "arcane-os/ai/browser-speech",
+      "group": "Browser speech providers",
+      "summary": "Creates a local-only Whisper speech-to-text provider for the provider-neutral AI runtime.",
+      "availability": "Browser with DBOPFS, Web Locks, Workers, object URLs, and a caller-admitted self-contained transformers-whisper runtime/model closure",
+      "protocol": "arcane-ai-provider/2 stt/transcribe",
+      "normalization": "Independent load, status, request, unload, cancellation, and disposal; accepts provider-native Float32Array audio at exactly 16000 Hz or decodes the shared AI.js Blob/File payload to authoritative 16000 Hz mono PCM; never selects a cloud fallback"
+    },
+    {
+      "id": "browser-speech:createDbopfsSpeechArtifactStore",
+      "name": "createDbopfsSpeechArtifactStore",
+      "displayName": "createDbopfsSpeechArtifactStore()",
+      "kind": "function",
+      "signature": "createDbopfsSpeechArtifactStore({ dbopfs, tableName='arcane_ai_browser_speech', fetchImpl=null, objectUrlFactory=null }={})",
+      "entrypoints": [
+        "arcane-os/ai/browser-speech"
+      ],
+      "primaryImport": "arcane-os/ai/browser-speech",
+      "group": "Browser speech providers",
+      "summary": "Adapts an existing DBOPFS instance into an authenticated, authority-scoped speech runtime/model artifact store.",
+      "availability": "Browser with a ready DBOPFS instance, Web Locks, Fetch or an explicit fetch implementation, File/Blob, and object URLs",
+      "protocol": "arcane.ai.browser-speech.assets.v1 completion manifests under arcane-ai-browser-speech-artifacts/1",
+      "normalization": "Serializes each authority, commits its completion manifest last, deletes partial state on failure, and supports strict offline cache admission"
     }
   ]
 }

package/docs/reference/inventory/runtime-components.json

@@ -1,8 +1,16 @@
 {
   "schemaVersion": 1,
   "source": {
-    "commit": "567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e",
-    "bundleVersion": "0.8.12"
+    "authority": "sdk-canonical",
+    "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
+    "commit": "36fbe1418af3d5c343d105ee7c9456360c57785d",
+    "path": "runtime/arcane/components",
+    "sdkVersion": "0.2.1",
+    "legacyProjection": {
+      "repository": "https://github.com/TheWizardNexus/ARCANE-OS.git",
+      "commit": "c540014afe69f14cf5ae60493b7295f36dbcec64",
+      "bundleVersion": "0.8.12"
+    }
   },
   "componentCount": 39,
   "loader": "/arcane/modules/HTMLImport.js",
@@ -117,7 +125,7 @@
     {
       "file": "runtime/arcane/components/chat.html",
       "name": "chat.html",
-      "purpose": "Shared chat, file upload, streaming, speech, language, availability, and conversation-timebox surface.",
+      "purpose": "Shared chat, visible selected-model activation request, file upload, streaming, speech, language, availability, and conversation-timebox surface.",
       "methods": [
         "streamMessage()",
         "setMessageProgress()",
@@ -127,7 +135,9 @@
         "bindConversationTimebox()",
         "submitMessage()",
         "sendMessage()",
-        "languageChanged()"
+        "languageChanged()",
+        "requestAIActivation()",
+        "destroy()"
       ],
       "events": [
         "chat-ready",
@@ -135,17 +145,20 @@
         "chat-send-error",
         "chat-file-uploaded",
         "chat-language-changed",
+        "chat-ai-activation-request",
+        "chat-ai-activation-error",
         "conversation-timebox-error"
       ],
       "slots": [],
       "dependencies": [
         "MD.js",
         "File.js",
-        "ConversationTimebox.js"
+        "ConversationTimebox.js",
+        "AIRuntimeState.js"
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "UI state normalized; AI/storage/media behavior mixed"
+      "normalization": "UI/runtime state and explicit user activation intent/request normalized; destroy aborts state/activation observation, releases page/speech listeners, clears ready, returns undefined, and does not initiate provider lifecycle; the provider/runtime owner executes any load; AI/storage/media behavior mixed"
     },
     {
       "file": "runtime/arcane/components/conversation-view.html",

package/docs/reference/inventory/runtime-modules.json

@@ -1,13 +1,21 @@
 {
   "schemaVersion": 1,
   "source": {
-    "commit": "567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e",
-    "bundleVersion": "0.8.12",
+    "authority": "sdk-canonical",
+    "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
+    "commit": "36fbe1418af3d5c343d105ee7c9456360c57785d",
+    "path": "runtime/arcane",
+    "sdkVersion": "0.2.1",
+    "legacyProjection": {
+      "repository": "https://github.com/TheWizardNexus/ARCANE-OS.git",
+      "commit": "c540014afe69f14cf5ae60493b7295f36dbcec64",
+      "bundleVersion": "0.8.12"
+    },
     "protocol": "arcane/1"
   },
-  "artifactCount": 80,
-  "javascriptArtifactCount": 78,
-  "esmExportCount": 282,
+  "artifactCount": 85,
+  "javascriptArtifactCount": 83,
+  "esmExportCount": 318,
   "artifacts": [
     {
       "file": "runtime/arcane/modules/AI.js",
@@ -18,9 +26,9 @@
       ],
       "summary": "Provider-selectable chat, speech-to-text, text-to-speech, tool calling, structured output, streaming, and queued audio playback.",
       "availability": "Browser + native bridge + cloud",
-      "protocol": "OpenAI HTTPS, Arcane.ollama, Arcane.speech, Android WebView bridge",
-      "normalization": "High-level chat/speech behavior is normalized; provider diagnostics and media errors remain mixed.",
-      "surface": "default `AI`; `setAI()`, `streamRequest()`, `streamMessage()`, `fetchRequest()`, `fetch()`, `streamTTS()`, `finishTTS()`, `fetchSTT()`, `stopAudio()`, `resumeAudio()`, `playAudio()`; installs `window.ai` and emits `ai-ready`."
+      "protocol": "AIProviderRuntime arcane-ai-provider/2 routes, OpenAI HTTPS, Arcane.ollama, Arcane.speech, Android WebView bridge",
+      "normalization": "High-level chat/speech behavior, truthful legacy-route readiness, and shared browser speech request/result conversion are normalized; provider diagnostics and media errors remain mixed.",
+      "surface": "default `AI`; `providerRuntime`; `setAI()`, `configureProviders()`, `transitionAI()`, `transitionProviders()`, `startProviders()`, `setSpeechMuted()`, `streamRequest()`, `streamMessage()`, `fetchRequest()`, `fetch()`, `streamTTS()`, `finishTTS()`, `fetchSTT()`, `stopAudio()`, `resumeAudio()`, `playAudio()`; consumes `user-entity-loaded` and `arcane-ollama-ready`, installs `window.ai`, and emits `ai-ready`."
     },
     {
       "file": "runtime/arcane/modules/AIPreferenceRuntime.js",
@@ -51,6 +59,24 @@
       "normalization": "Fully normalized frozen tuple.",
       "surface": "`AI_PREFERENCE_SLOT_KEYS`, `normalizeAIPreferenceTuple()`, `aiPreferenceTuplesEqual()`."
     },
+    {
+      "file": "runtime/arcane/modules/AIProviderRuntime.js",
+      "name": "AIProviderRuntime.js",
+      "kind": "esm",
+      "exports": [
+        "AI_MODEL_AUTHORITY_PROTOCOL",
+        "AI_PROVIDER_PROTOCOL",
+        "AI_PROVIDER_RUNTIME_PROTOCOL",
+        "AIProviderRuntime",
+        "aiProviderRuntime",
+        "getAIProviderRuntime"
+      ],
+      "summary": "Provider-neutral selection, lifecycle, routing, startup, request, streaming, cancellation, and independent LLM/STT/TTS state.",
+      "availability": "Cross-host in-process runtime; registered providers remain browser, native, or cloud specific",
+      "protocol": "arcane-ai-runtime/2, arcane-ai-provider/2, arcane-ai-model-authority/1",
+      "normalization": "Normalizes immutable per-role routes, lifecycle/status, cancellation, streaming cleanup, and local-only selection without creating a fallback.",
+      "surface": "Protocol constants; singleton-only `AIProviderRuntime`; `aiProviderRuntime`; `getAIProviderRuntime()`; provider registration/configuration, lifecycle, request, stream, speech, cancellation, and mute controls."
+    },
     {
       "file": "runtime/arcane/modules/AIResponseLength.js",
       "name": "AIResponseLength.js",
@@ -84,6 +110,32 @@
       "normalization": "Normalized frozen allowlist audit.",
       "surface": "`auditAIResponseLinks()`, `extractAIResponseLinks()`, `normalizeAIResponseLink()`, `decodeHTMLCharacterReferences()`."
     },
+    {
+      "file": "runtime/arcane/modules/AIRuntimeState.js",
+      "name": "AIRuntimeState.js",
+      "kind": "esm",
+      "exports": [
+        "AI_RUNTIME_INTENT_EVENT",
+        "AI_RUNTIME_PROTOCOL",
+        "AI_RUNTIME_ROLES",
+        "AI_RUNTIME_STARTUP_EVENT",
+        "AI_RUNTIME_STATES",
+        "AI_RUNTIME_STATE_EVENT",
+        "aiRuntimeEvents",
+        "getAIRuntimeState",
+        "publishAIRuntimeRoleState",
+        "publishAIRuntimeRolesState",
+        "requestAIRuntimeIntent",
+        "startAIRuntime",
+        "subscribeAIRuntimeIntents",
+        "subscribeAIRuntimeState"
+      ],
+      "summary": "Sticky immutable LLM, speech-to-text, and text-to-speech lifecycle snapshots, intents, subscriptions, and startup-settlement barriers.",
+      "availability": "Cross-host in-process state contract; actual role readiness remains provider specific",
+      "protocol": "arcane-ai-runtime-state/1 over EventTarget",
+      "normalization": "Closed role records and monotonic revisions normalize state across providers; subscriptions never grant authority or load a provider.",
+      "surface": "Protocol/event/state constants; `aiRuntimeEvents`; snapshot, subscribe, publish, intent, and `startAIRuntime()` functions."
+    },
     {
       "file": "runtime/arcane/modules/AnsiText.js",
       "name": "AnsiText.js",
@@ -382,7 +434,7 @@
       "availability": "Native bridge by default; cross-host with injected chat",
       "protocol": "Arcane.ai.chat or injected provider",
       "normalization": "Normalized session/result; provider rejection preserved.",
-      "surface": "default `ConfiguredAIChatSession`; `history()`, `clear()`, `send()`."
+      "surface": "default `ConfiguredAIChatSession`; constructor accepts bounded coherent `initialMessages` plus configuration; `history()`, `clear()`, `prepare()`, `send()`; prior normalized and exactly-one-choice OpenAI-compatible responses normalize to one frozen session result."
     },
     {
       "file": "runtime/arcane/modules/ConversationActionItems.js",
@@ -515,6 +567,22 @@
       "normalization": "App scope normalized; DOM/storage errors preserved.",
       "surface": "default `DBOPFS`; installs `window.dbopfs`, emits `dbopfs-ready`; table/file/backup APIs."
     },
+    {
+      "file": "runtime/arcane/modules/DBOPFSDocumentLibrary.js",
+      "name": "DBOPFSDocumentLibrary.js",
+      "kind": "esm",
+      "exports": [
+        "DBOPFSDocumentLibrary",
+        "createDBOPFSDocumentLibrary",
+        "default",
+        "normalizeDBOPFSDocumentSchema"
+      ],
+      "summary": "Application-defined document corpus bootstrap, caller-source evaluation, atomic DBOPFS generations, bounded lexical search, and untrusted request-context construction.",
+      "availability": "Browser or compatible host with an existing DBOPFS-style database adapter",
+      "protocol": "Existing DBOPFS get/set/getAllKeys/delete methods; no new storage protocol",
+      "normalization": "Preserves DBOPFS method semantics, commits a completion manifest last, validates every stored generation, exposes explicit reject or preserve-readable read-failure policy, and labels retrieved context as untrusted data.",
+      "surface": "`DBOPFSDocumentLibrary`, `createDBOPFSDocumentLibrary()`, `normalizeDBOPFSDocumentSchema()`; `schema`, `bootstrap()`, `search()`, `evaluate()`, `buildContext()`, and `createContextBuilder()`."
+    },
     {
       "file": "runtime/arcane/modules/DBOPFSWorker.js",
       "name": "DBOPFSWorker.js",
@@ -557,6 +625,27 @@
       "normalization": "Strict normalized selection and coded errors.",
       "surface": "default `DirectoryPicker`, `normalizeDirectoryPickerOptions()`, `normalizeDirectorySelection()`."
     },
+    {
+      "file": "runtime/arcane/modules/DocumentLexicalSearch.js",
+      "name": "DocumentLexicalSearch.js",
+      "kind": "esm",
+      "exports": [
+        "DOCUMENT_SEARCH_FIELD_ORDER",
+        "DocumentLexicalSearch",
+        "createDocumentLexicalIndex",
+        "default",
+        "documentContextExcerpt",
+        "documentSearchTokens",
+        "normalizedDocumentSearchText",
+        "scoreDocumentBody",
+        "scoreDocumentLexicalIndex"
+      ],
+      "summary": "Dependency-free deterministic document indexing, ranked metadata/body search, bounded excerpts, and stable tie-breaking.",
+      "availability": "Cross-host in-process only",
+      "protocol": "In-process immutable record contract",
+      "normalization": "Normalizes text and filters, preserves deterministic field priority, and returns frozen results without network, storage, or provider side effects.",
+      "surface": "Search-field constant; `DocumentLexicalSearch`; index/token/score/excerpt helpers; `rank()` and bounded `search()`."
+    },
     {
       "file": "runtime/arcane/modules/DocumentNavigation.js",
       "name": "DocumentNavigation.js",
@@ -851,6 +940,21 @@
       "normalization": "Provider data normalized to entities; transport errors mixed.",
       "surface": "Endpoint constants, default provider, `mapForecast()`; search/load methods and lifecycle events."
     },
+    {
+      "file": "runtime/arcane/modules/PersistentAIChatSession.js",
+      "name": "PersistentAIChatSession.js",
+      "kind": "esm",
+      "exports": [
+        "PersistentAIChatSession",
+        "createPersistentAIChatSession",
+        "default"
+      ],
+      "summary": "Composes bounded configured chat with an existing ChatEntity so each user, assistant, and structural tool turn has an explicit persistence policy.",
+      "availability": "Browser or native WebView with the projected ChatEntity, DBOPFS, and a configured chat function or normalized Arcane.ai surface",
+      "protocol": "Existing ChatEntity/DBOPFS methods plus provider-neutral chat request/result records",
+      "normalization": "Preserves existing chat/history/memory semantics, commits live context atomically, and keeps durable persistence coherent across structural tool-call/result pairs.",
+      "surface": "Default/named `PersistentAIChatSession`, `createPersistentAIChatSession()`; `create()`, `chatEntity`, `fileName`, `ready()`, `history()`, `settleMemory()`, and `send()`."
+    },
     {
       "file": "runtime/arcane/modules/PreferenceStore.js",
       "name": "PreferenceStore.js",