arcane-os 0.76.0 → 0.78.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.78.0
+
+- Add `AI.readPreparedTTS()` and shared `readPreparedSpeech()` for complete
+  cache-only narration lookup. Return a ready playback handle or `null` without
+  loading a model, unmuting, synthesizing, writing storage or repairing partial
+  audio. Preserve complete semantic matching and genuine storage errors.
+- Keep lookup cancellation independent from a successfully returned handle.
+  Replay uses the existing prepared-playback owner and can borrow the caller's
+  silent reusable audio output; no autoplay permission is implied.
+- Add optional existing-only DBOPFS table/file reads while preserving ordinary
+  lazy-creation defaults. Cache-only lookup and later audio reads leave missing
+  tables absent.
+- Give Kokoro voice caching a real Worker-lifetime response cache after runtime
+  import, while DBOPFS remains the durable model/resource owner. Preserve saved
+  native caches and clear transient responses on unload.
+- Report a complete stored model resource as cached loading rather than a new
+  network download. This release changes no model selection, native engine or
+  physical-device routing and makes no live-model execution claim.
+
+## 0.77.0
+
+- Add `AI.prepareAudioOutput()` for synchronous, silent preparation of a reusable
+  WebAudio output. Observe its actual context state through immediate subscription
+  replay and `AI_AUDIO_OUTPUT_STATE_EVENT`; resume and dispose explicitly.
+- Add optional `audioOutput` to `playPreparedTTS()` so prepared narration borrows
+  that same output across plays. Completion and stop leave the borrowed context
+  open; omission preserves the existing per-playback context lifecycle.
+- Keep replacement, pending suspension, decoding, cancellation and disposal tied
+  to their actual output and playback owners. Cleanup failures remain observable
+  and failed context closure can be retried. Independent native speech, saved
+  audio and detached preparation retain their existing ownership.
+- Preparation plays no sound, creates no audio source, resumes no context,
+  changes no mute setting and loads no model. A running WebAudio context is not
+  a guarantee of future autoplay, native speech or HTML audio readiness. No
+  physical-GPU placement or native-engine change is included.
+
 ## 0.76.0
 
 - Add public `textFormat:'plain'` to the `SpeechPlayback` constructor and

package/README.md

@@ -20,7 +20,7 @@ selected SDK projection or an explicit live SDK source mount. Both profiles
 share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.76.0` SDK contract. Development applications declare
+This checkout defines the `0.78.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;

package/browser-runtime/ai/dbopfs-model-resources.mjs

@@ -96,7 +96,7 @@ export function createDbopfsResourceStore({dbopfs, tableName, fetchImpl = global
                 const file = await parts.read(entry.name, {signal});
                 if (file) {
                     const state = await parts.state(entry.name, {signal});
-                    onProgress?.({phase: 'download', completed: state.parts.length,
+                    onProgress?.({phase: 'load', message: 'Reading stored model resource', completed: state.parts.length,
                         total: state.parts.length, unit: 'shards', cached: true, url: request.url});
                     return {...entry.metadata, file};
                 }

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

@@ -997,6 +997,7 @@ function createOrdinaryArtifactModuleRouter(
   role,
   reader,
   originalWorker,
+  responseCaches,
 ) {
   const nestedWorkers = new Set();
   const router = completeValue({
@@ -1015,8 +1016,8 @@ function createOrdinaryArtifactModuleRouter(
       return reader.fetchResource(input, init, modulePath);
     },
 
-    async openCache() {
-      throw new Error('Browser CacheStorage is unavailable in this speech Worker; resources use DBOPFS through fetch.');
+    openCache(modulePath, name) {
+      return responseCaches.open(name);
     },
 
     createWorker(modulePath, specifier, options = {}) {
@@ -1143,6 +1144,63 @@ function installOrdinaryArtifactModuleRouter(scope, configuration, role, send, s
   const resourceClient = createModelResourceClient({ send });
   let requestSignal = null;
   let reportProgress = null;
+  let cacheClosed = false;
+  const responseCacheEntries = new Map();
+  const responseCaches = {
+    async open(name) {
+      assertCacheActive(requestSignal);
+      const cacheName = String(name);
+      let cache = responseCacheEntries.get(cacheName);
+      if (!cache) {
+        const responses = new Map();
+        cache = {
+          responses,
+          api: {
+            async match(input) {
+              assertCacheActive(requestSignal);
+              const stored = responses.get(cacheRequestKey(input));
+              if (!stored) return undefined;
+              const response = new Response(stored.body, stored);
+              Object.defineProperties(response, {
+                url: { value: stored.url },
+                redirected: { value: stored.redirected },
+                type: { value: stored.type },
+              });
+              return response;
+            },
+            async put(input, response) {
+              const signal = requestSignal;
+              assertCacheActive(signal);
+              const key = cacheRequestKey(input);
+              const copy = response.clone();
+              const body = await copy.blob();
+              assertCacheActive(signal);
+              responses.set(key, {
+                body,
+                status: response.status,
+                statusText: response.statusText,
+                headers: [...response.headers],
+                url: response.url,
+                redirected: response.redirected,
+                type: response.type,
+              });
+            },
+          },
+        };
+        responseCacheEntries.set(cacheName, cache);
+      }
+      return cache.api;
+    },
+  };
+  function assertCacheActive(signal) {
+    throwIfAborted(signal, 'speech-resource-cache-cancelled');
+    if (cacheClosed) throw new Error('The speech Worker response cache was unloaded.');
+  }
+  function cacheRequestKey(input) {
+    const RequestConstructor = scope.Request ?? Request;
+    const request = new RequestConstructor(input);
+    return JSON.stringify([request.method, request.url]);
+  }
   if (!is.function(originalFetch)) {
     throw workerError(
       "ARCANE_AI_PROVIDER_UNAVAILABLE",
@@ -1166,8 +1224,9 @@ function installOrdinaryArtifactModuleRouter(scope, configuration, role, send, s
     role,
     reader,
     originalWorker,
+    responseCaches,
   );
-  const originalProperties = ['fetch', 'Worker', MODULE_ROUTER_NAME].map(
+  const originalProperties = ['fetch', 'Worker', 'caches', MODULE_ROUTER_NAME].map(
       function originalWorkerProperty(name) {
           return { name, descriptor: Object.getOwnPropertyDescriptor(scope, name) };
       },
@@ -1240,7 +1299,22 @@ function installOrdinaryArtifactModuleRouter(scope, configuration, role, send, s
     receive: resourceClient.receive,
     setSignal(signal) { requestSignal = signal; },
     setProgress(report) { reportProgress = report; },
+    enableResponseCache() {
+      // Transformers captures cache capability during import. Kokoro then uses
+      // this real, Worker-lifetime match/put cache for voices; fetch remains the
+      // sole route to durable DBOPFS resources. No native saved cache is touched.
+      assertCacheActive(requestSignal);
+      Object.defineProperty(scope, 'caches', {
+        configurable: true,
+        enumerable: true,
+        writable: true,
+        value: responseCaches,
+      });
+    },
     async cleanup() {
+      cacheClosed = true;
+      for (const cache of responseCacheEntries.values()) cache.responses.clear();
+      responseCacheEntries.clear();
       resourceClient.close(new Error('The speech Worker resource owner was unloaded.'));
       let cleanupFailure = null;
       try {
@@ -1773,6 +1847,7 @@ export function createSpeechWorkerRuntime({ role, scope = globalThis, send } = {
       );
       const namespace = await import(entry.moduleUrl);
       throwIfAborted(signal, `${role}-load-cancelled`);
+      environment.enableResponseCache();
       restoreNamespace = configureRuntimeNamespace(
         namespace,
         configuration,
@@ -2071,6 +2146,7 @@ export function installBrowserSpeechArtifactModuleWorker(role, scope = globalThi
             target?.sourceUrl ?? request.targetUrl,
         );
         await import(target?.moduleUrl ?? request.targetUrl);
+        environment.enableResponseCache();
         scope.removeEventListener("message", bootstrap);
         await new Promise((resolve) => queueMicrotask(resolve));
         for (const queuedEvent of queued.splice(0)) replayWorkerMessage(scope, queuedEvent);

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

@@ -727,6 +727,54 @@ pause delays the next queued audio on the existing `AudioContext` clock; it
 does not delay the preceding promise after that passage's last buffer ends.
 The promise is a playback result, not a listener acknowledgement.
 
+## Read stored narration without starting generation
+
+`await ai.readPreparedTTS({parts,textFormat,storage,identity,signal,onState})`
+returns a complete prepared handle or `null`. It uses the same complete inputs,
+selected speech configuration, formatting treatment, segmentation, storage key,
+and semantic `identity` as `prepareTTS()`. Supply the same options used to
+prepare the audio. A changed selection or input is a cache miss, not permission
+to generate replacement audio.
+
+This operation never activates or unmutes a provider, synthesizes speech,
+creates stored records, repairs partial audio, or joins pending generation.
+With `storage`, it reads the existing manifest and every ordered audio file.
+Missing or incomplete audio returns `null`; unreadable metadata and other
+storage errors reject. Without storage, it finds only already-complete audio
+retained by this same AI instance. A miss leaves all existing data unchanged.
+
+```javascript
+async function readNarration(text, key, signal) {
+    return ai.readPreparedTTS({
+        parts: [{
+            input: text,
+            voice: speechSelection.model.defaultVoice,
+            speed: 1,
+            pauseAfterMs: 0
+        }],
+        storage: {db: dbopfs, table: 'saved_narration', key},
+        identity: {
+            model: speechSelection.model,
+            runtime: speechSelection.runtime
+        },
+        signal
+    });
+}
+```
+
+A returned handle has the ordinary `segments`, `state`, `ready`, `getAudio(index)`,
+and `cancel()` contract and can be passed to `ai.playPreparedTTS()` from the
+application's playback action, including with its existing `audioOutput`.
+The lookup signal governs only the read and rejects cancellation as
+`AbortError`. After a successful return, aborting that signal does not invalidate
+the retained handle; explicit handle cancellation and playback cancellation
+remain separate. A successful read does not promise future autoplay permission
+or prevent a later application-owned removal of stored files.
+
+Applications decide which saved narration candidates to inspect. For example,
+newest-first lookup can skip a newer partial preparation and then inspect an
+older complete candidate without activating any model.
+
 ## Prepare narration once and replay stored audio
 
 Use `ai.prepareTTS()` when preparation must continue independently of playback,
@@ -889,7 +937,7 @@ provider cleanup remains observable through that operation's settlement.
 
 ### Playback controls and independent lifetimes
 
-`ai.playPreparedTTS(prepared,{signal,onState})` returns
+`ai.playPreparedTTS(prepared,{signal,onState,audioOutput})` returns
 `{state,error,finished,pause(),resume(),stop()}` immediately. It uses the
 existing AI audio-clock scheduler and waits for each earlier segment before scheduling
 later audio. Ready adjacent buffers retain contiguous scheduling. Requested
@@ -902,8 +950,9 @@ states are `waiting`, `waiting-for-gesture`, `scheduled`, `paused`, `complete`,
 `stopped`, and `error`. Use `waiting-for-gesture` to present an audio-unlock
 control. A `false` result from `resume()` is not a first-segment-ready signal;
 inspect `state` and `error` to distinguish a stopped or unavailable context
-from browser gesture waiting. The ordinary playback path creates its audio
-context immediately, before the first audio segment is ready.
+from browser gesture waiting. With `audioOutput` omitted or `null`, playback
+creates its own audio context immediately, before the first segment is ready,
+and closes that context after completion, stop, cancellation, or failure.
 
 `finished` resolves `true` after natural playback completion and `false` after
 stop, playback cancellation, or failure. Real failures also reach the existing
@@ -931,6 +980,87 @@ preparations. A page that starts several preparations owns and observes every
 `ready` promise, even when it plays only one handle. Browser autoplay permission
 still applies; neither promise proves that a person heard the audio.
 
+### Prepare a silent reusable WebAudio output
+
+`ai.prepareAudioOutput()` synchronously returns an AI-owned output handle.
+It creates or reuses that AI's persistent WebAudio context and observes its
+actual state. Preparation stays silent: it does not resume the context, unmute
+speech, load a model, create an audio source, play a test sound, or install
+gesture listeners. It does not wait for speech preparation or provider readiness.
+
+The handle exposes `kind:'web-audio'`, live `state`, `contextState`, and `error`
+getters, `subscribe(listener)`, `resume()`, and `dispose()`. Repeated preparation
+returns the same handle until its output is disposed or its context closes.
+`contextState` is the platform context's current state, or `null` when unavailable;
+`error` retains the complete actual error, or `null`.
+
+| Output state | Meaning |
+| --- | --- |
+| `ready` | This WebAudio context is currently `running`. |
+| `suspended`, `interrupted`, or another platform state | The context reports that state; suspension alone does not establish a gesture requirement. |
+| `gesture-required` | A resume operation actually reported `NotAllowedError` while the context was not running. |
+| `unavailable` | Context creation failed; `error` contains the actual failure. |
+| `error` | An output operation failed; inspect the complete `error`. |
+| `disposing`, `disposed` | Owner disposal is in progress or has completed. |
+| `closed` | The underlying context has closed outside completed owner disposal. |
+
+`subscribe(listener)` immediately replays `{kind,state,contextState,error}` and
+then delivers state changes through the canonical AI event owner. It returns
+an idempotent unsubscribe function. The named export
+`AI_AUDIO_OUTPUT_STATE_EVENT` from `AI.js` is `'ai-audio-output-state'`; its
+canonical occurrences carry the same snapshot in `detail` and an output-specific
+`operationId`. Handle subscriptions select only their own output. Disposal or
+context closure releases those subscriptions after the terminal notification;
+a later handle subscription still receives the current snapshot immediately.
+
+`resume()` is an explicit asynchronous action for the application's user-gesture
+flow. It resolves `true` only when the context is actually running, and `false`
+when unavailable, disposed, superseded, or held by a paused prepared playback.
+A platform rejection rejects with its actual error and retains that failure in
+the output state. It does not unmute speech or load a model. Output readiness
+does not establish HTML audio readiness, native-speech readiness, future autoplay
+permission, available speech audio, or audible delivery.
+
+Pass the handle explicitly to borrow that exact output for prepared playback:
+
+```javascript
+// ai and prepared are the same AI owner and preparation used above.
+const audioOutput = ai.prepareAudioOutput();
+
+function observeNarrationOutput(listener) {
+  return audioOutput.subscribe(listener);
+}
+
+function resumeNarrationOutput() {
+  // Call from the application's user action and observe the returned promise.
+  return audioOutput.resume();
+}
+
+function playNarration() {
+  return ai.playPreparedTTS(prepared, {audioOutput});
+}
+
+function disposeNarrationOutput() {
+  // Call when this owner no longer needs the output; observe its promise.
+  return audioOutput.dispose();
+}
+```
+
+The selected handle must be live and belong to the same AI instance; another
+owner's, closed, or disposing output throws `TypeError`. Borrowed playback
+retains the same ordered scheduling, pause/resume, cancellation, and single-lane
+replacement behavior. Completion or stopping playback leaves the output open
+for reuse. Merely preparing an output does not change the omitted-option path.
+
+The application owns the output lifetime and calls `dispose()` when finished
+with it. Disposal stops playback bound to that context and any following work
+waiting on its clock, observes cleanup, and awaits the actual context close.
+It preserves detached preparation, saved audio, unrelated contexts, and model
+selection. Concurrent calls share the disposal promise. Actual cleanup or close
+errors reject and remain observable; a failed context close permits a later
+disposal retry. Stop/mute controls retain their existing playback/provider scope
+and do not replace this explicit output disposal.
+
 ## Stream chunks as they arrive
 
 Use the configured `ai` created above. Run this snippet from an owned user
@@ -1549,8 +1679,13 @@ as graph runtimes:
 Inside the dedicated speech Worker, native CacheStorage is temporarily
 unavailable before runtime import, so the selected runtime takes its existing
 fetch path. Transformers' public browser/custom/filesystem cache switches are
-disabled there. The SDK does not fabricate Cache matches or mutation results,
-and it neither clears nor changes saved native caches. The original Worker
+disabled there. After the runtime import, Kokoro's voice `caches.open()` calls
+use a Worker-local response cache with actual `match`/`put` results. It retains
+complete response bodies and metadata in memory for that Worker only; a miss
+does not fetch, and ordinary fetch still owns durable DBOPFS persistence. This
+temporary response retention is separate from Kokoro's own in-memory voice
+arrays. Unload clears it, and an unfinished put cannot repopulate it afterward.
+The SDK neither clears nor changes saved native caches. The original Worker
 environment is restored on unload or failed import. Existing explicit
 `removeBrowserSpeechModelCache()` remains a separate caller-selected operation.
 
@@ -1564,6 +1699,10 @@ closed resource parts survive cancellation. Existing whole-file caches remain
 readable without migration. HTTP resume is used only when the server returns
 the requested range; otherwise the complete resource is downloaded anew.
 Worker termination aborts and joins its parent-owned resource operations.
+An existing complete resource reports `phase:'load'`, `cached:true`, and
+`message:'Reading stored model resource'` with its complete shard progress.
+That event describes a DBOPFS read, not a network download or model-session
+reload. The resource owner does not fetch that stored response again.
 
 Routing discovery is best effort and is not an admission gate. If the scanner
 cannot interpret a module, that module is left unchanged and follows its native

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

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.75.0",
+  "sdkVersion": "0.77.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",

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

@@ -10,13 +10,14 @@
   },
   "artifactCount": 93,
   "javascriptArtifactCount": 91,
-  "esmExportCount": 373,
+  "esmExportCount": 375,
   "artifacts": [
     {
       "file": "runtime/arcane/modules/AI.js",
       "name": "AI.js",
       "kind": "esm",
       "exports": [
+        "AI_AUDIO_OUTPUT_STATE_EVENT",
         "AI_BROWSER_SPEECH_CONFIGURATION_PROTOCOL",
         "AI_BROWSER_SPEECH_ERROR_CODES",
         "AI_BROWSER_SPEECH_EVENT_TYPES",
@@ -30,7 +31,7 @@
       "availability": "Browser + native bridge + TWiN Cloud",
       "protocol": "arcane-ai-browser-speech-configuration/1, AIProviderRuntime arcane-ai-provider/2 routes, globalThis.arcaneEvents, TWiN Cloud HTTPS, Arcane.ollama, Arcane.speech, Android WebView bridge",
       "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized Whisper STT and Kokoro TTS execution with default capacities 1 and 4 respectively, explicit provider-neutral execution snapshots through status(role,{execution:true}), sticky readiness, canonical window.user readiness without compatibility-event object-identity admission or polling, exact ordered structural calls with required arguments.message, atomic nonblank all-ID tool-result sequencing, complete all-choice streaming/data validation, native Ollama structural adaptation, complete-response then all validated tool callbacks then completion ordering, observed async callbacks, Blob/File transcription, default repeated-formatting-mark removal from cloned outbound TTS input, explicit textFormat:'plain' preservation for complete synthesis/preparation while streaming cleanup remains automatic and caller/visible content stays exact, immediate exact-segment synthesis, per-call voice/speed capture, optional final-segment pause on the existing audio clock, optional per-call terminal playback completion, detached preparation with complete semantic DBOPFS audio reuse and same-owner pending request sharing; each preparation owns its pending activation interest, final-interest cancellation aborts that activation while other interests preserve it, complete cache hits start no model, and cancellation after readiness leaves the ready model loaded; independent prepared playback without a model load for cached audio, ordered audio-clock scheduling, playable audio, active-generation TTS operation-failure routing, mute, and cancellation are normalized; provider/model/runtime/voice policy remains caller-owned. Both speech roles default execution.device to auto: webnn-npu when navigator.ml.createContext is exposed, then webgpu when navigator.gpu is exposed, then wasm for CPU execution. Failed backend loads clean up the pool before trying fresh Workers with the same prepared model and dtype; explicit devices never fall back. STT capacity only accepts 1; TTS accepts 1 through 4. Execution snapshots expose requestedDevice, selectedDevice, maxConcurrentRequests, and activeRequestCount for both roles; selectedDevice is null while unloaded and names the successful upstream session backend request when loaded. It does not prove every operation used the physical NPU: WebNN unsupported operations may use WASM, and compatibility depends on the browser, driver, hardware, and graph.",
-      "surface": "Native fetchTTS(payload,signal) and fetchSTT(audio,signal) forward caller cancellation separately from their complete Core speech payloads, normalize aborts to AbortError and suppress late results; actual engine interruption remains service-owned. prepareTTSPlayback(payload,signal) silently returns a real Blob or native-speech descriptor; native controls expose finished/released/state/error/pause/resume/stop, and actual release owns the playback lane. fetchTTS and durable prepareTTS report ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE for native voices. Request-local model overrides remain exact and never mutate the configured model. Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; default speech-input cleanup with SDK-internal preparation metadata and explicit complete-call textFormat:'plain' consumed before engine dispatch; `prepareTTS({parts,storage,identity,textFormat,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); `playPreparedTTS(prepared,{signal,onState})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
+      "surface": "Native fetchTTS(payload,signal) and fetchSTT(audio,signal) forward caller cancellation separately from their complete Core speech payloads, normalize aborts to AbortError and suppress late results; actual engine interruption remains service-owned. prepareTTSPlayback(payload,signal) silently returns a real Blob or native-speech descriptor; native controls expose finished/released/state/error/pause/resume/stop, and actual release owns the playback lane. fetchTTS and durable prepareTTS report ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE for native voices. Request-local model overrides remain exact and never mutate the configured model. Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; default speech-input cleanup with SDK-internal preparation metadata and explicit complete-call textFormat:'plain' consumed before engine dispatch; `prepareTTS({parts,storage,identity,textFormat,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); async `readPreparedTTS({parts,textFormat,storage,identity,signal,onState})` returning a complete ready handle or null through the same semantic matcher, with no activation, unmute, synthesis, playback, storage writes, or partial repair; manifest, audio availability, and returned-handle reads use DBOPFS createTable:false so absent tables remain absent; supplied adapters own that read-existing behavior; missing matches/audio return null, malformed metadata and storage failures reject, and omitted storage sees only completed matching same-AI in-memory audio; hits replay ready state, misses emit nothing, and the lookup signal detaches on settlement while returned-handle cancellation stays independent; `prepareAudioOutput()` returning the persistent WebAudio handle {kind,state,contextState,error,subscribe,resume,dispose} without resume, unmute, model load, sources, sound, or gesture listeners; current-state replay and output-specific canonical `AI_AUDIO_OUTPUT_STATE_EVENT` (`ai-audio-output-state`), with ready only for an actually running context; explicit owner disposal observes context-bound cleanup and close; `playPreparedTTS(prepared,{signal,onState,audioOutput})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; explicit live same-AI audioOutput borrows its context until owner disposal, while omission or null preserves per-playback terminal close; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
     },
     {
       "file": "runtime/arcane/modules/AIModelSelectionController.js",
@@ -582,7 +583,7 @@
       "availability": "Browser / native WebView",
       "protocol": "OPFS, DBOPFSWorker, Compression Streams, per-realm globalThis.arcaneEvents authority, and native BroadcastChannel for live same-app/storage-partition committed changes",
       "normalization": "App scope and recognized file parsing are normalized; nonblank unreadable JSONL rows remain complete raw strings, empty-table removal reports removed, absent, or not-empty after a create:false directory lookup and without scanning or recursively clearing a directory, same-named files are preserved, aliases and cached handles are invalidated only when the directory is gone, and unexpected DOM/storage errors are preserved.",
-      "surface": "default `DBOPFS`; installs `window.dbopfs`, emits `dbopfs-ready`; subscribeChanges(listener,{signal,once}) observes DBOPFS_EVENT_TYPES.change (dbopfs-change), returns idempotent unsubscribe/.dispose, and publishes metadata {applicationId,storagePath,tableName,directoryName,fileName,action,originId,sequence,changeId,remote} after successful storage commits only. Actions are write/append/delete/table-delete; batches preserve partial success, remote receipts invalidate targeted aliases before local publication and never rebroadcast, and pagehide/pageshow closes/reopens the native channel and clears memory caches without replay or fabricated changes. Local subscription/storage continue when BroadcastChannel is unavailable. Table/file/backup APIs include removeEmptyTable(tableName). createCompressedPNG({tableNames,additionalTables,signal}) returns a PNG Blob without download or record writes; omitted names select all, [] none, and supplied tables replace matching saved tables in the export. downloadCompressedPNG(name,options) reuses the same preparation and initiates one download; cancellation prevents it. restoreFromPNG(file,{selectTables}) closes the decoded image after pixel extraction, awaits the optional caller selection/projection before any writes, and rejects DBOPFS_RESTORE_WRITE_FAILED AggregateError after all selected table batches settle when records fail, preserving original errors and failures {tableName,fileName,reason}; successful writes remain. No-options restore and setMany retain their contracts."
+      "surface": "default `DBOPFS`; installs `window.dbopfs`, emits `dbopfs-ready`; subscribeChanges(listener,{signal,once}) observes DBOPFS_EVENT_TYPES.change (dbopfs-change), returns idempotent unsubscribe/.dispose, and publishes metadata {applicationId,storagePath,tableName,directoryName,fileName,action,originId,sequence,changeId,remote} after successful storage commits only. Actions are write/append/delete/table-delete; batches preserve partial success, remote receipts invalidate targeted aliases before local publication and never rebroadcast, and pagehide/pageshow closes/reopens the native channel and clears memory caches without replay or fabricated changes. Local subscription/storage continue when BroadcastChannel is unavailable. Table/file/backup APIs include getTableHandle(tableName='',{create=true}={}), readFile(tableName='',fileName='',{createTable=true}={}), get(tableName='',fileName='',force=false,{createTable=true}={}), and removeEmptyTable(tableName). Explicit create:false/createTable:false reads existing tables without creation or joining pending create work; default lazy creation remains unchanged. Low-level missing tables/files reject NotFoundError; get retains parsed caching/force semantics and resolves null only for NotFoundError, propagating other failures. Worker fallback reads already use existing app/table/file handles. createCompressedPNG({tableNames,additionalTables,signal}) returns a PNG Blob without download or record writes; omitted names select all, [] none, and supplied tables replace matching saved tables in the export. downloadCompressedPNG(name,options) reuses the same preparation and initiates one download; cancellation prevents it. restoreFromPNG(file,{selectTables}) closes the decoded image after pixel extraction, awaits the optional caller selection/projection before any writes, and rejects DBOPFS_RESTORE_WRITE_FAILED AggregateError after all selected table batches settle when records fail, preserving original errors and failures {tableName,fileName,reason}; successful writes remain. No-options restore and setMany retain their contracts."
     },
     {
       "file": "runtime/arcane/modules/DBOPFSDocumentLibrary.js",
@@ -1091,13 +1092,14 @@
       "name": "PreparedSpeech.js",
       "kind": "esm",
       "exports": [
-        "prepareSpeech"
+        "prepareSpeech",
+        "readPreparedSpeech"
       ],
-      "summary": "Owns detached ordered speech preparation, complete semantic audio reuse, and per-caller cancellation behind AI.prepareTTS.",
-      "availability": "Browser or native WebView with Blob, AbortController, an injected synthesis callback, and optional ready DBOPFS",
+      "summary": "Owns detached ordered speech preparation, complete semantic audio reuse, cache-only lookup, and per-caller cancellation behind AI.prepareTTS and AI.readPreparedTTS.",
+      "availability": "Browser or native WebView with Blob, AbortController, optional ready DBOPFS, and an injected synthesis callback for generation",
       "protocol": "In-process preparation handle plus caller-owned DBOPFS raw audio and version-1 semantic manifest",
-      "normalization": "Preserves complete original parts and JSON-compatible semantic context, shares pending matching work on the same owner/storage group, admits segments in order, stores complete Blobs and MIME metadata, retains successful audio after failure or cancellation, and separates generation readiness from playback.",
-      "surface": "Named prepareSpeech({owner,parts,originalParts,selection,segmentation,storage,identity,signal,onState,synthesize}) returns {segments,state,ready,getAudio(index),cancel()}; applications use AI.prepareTTS and AI.playPreparedTTS so the shared AI owner retains segmentation, provider readiness, capacity, and playback."
+      "normalization": "Preserves complete original parts and JSON-compatible semantic context, shares pending matching work on the same owner/storage group, admits segments in order, stores complete Blobs and MIME metadata, retains successful audio after failure or cancellation, and separates generation readiness from playback. Cache-only lookup uses the same semantic matcher, reads every stored audio reference without writes or repair, and returns null for missing matches/audio while preserving genuine read failures.",
+      "surface": "Named prepareSpeech({owner,parts,originalParts,selection,segmentation,storage,identity,signal,onState,synthesize}) returns {segments,state,ready,getAudio(index),cancel()}. Named async readPreparedSpeech({owner,parts,originalParts=parts,selection=null,segmentation=null,storage=null,identity=null,signal=null,onState=null}) returns a complete ready handle or null without synthesis, activation, unmute, playback, or storage writes. Manifest, audio availability, and returned-handle reads pass DBOPFS createTable:false, leaving absent tables absent; supplied adapters own the same read-existing contract. Omitted storage reads only completed matching same-owner in-memory preparations; pending or failed work returns null. A hit replays ready state and a miss emits nothing. The lookup signal detaches on settlement; the returned handle keeps independent explicit cancellation and MIME-preserving getAudio, including later storage errors. Applications use AI.prepareTTS, AI.readPreparedTTS, and AI.playPreparedTTS so the shared AI owner retains segmentation, provider readiness, capacity, and playback."
     },
     {
       "file": "runtime/arcane/modules/PrintView.js",