arcane-os 0.77.0 → 0.78.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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

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.77.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,
@@ -1631,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.
 
@@ -1646,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.76.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,7 +10,7 @@
   },
   "artifactCount": 93,
   "javascriptArtifactCount": 91,
-  "esmExportCount": 374,
+  "esmExportCount": 375,
   "artifacts": [
     {
       "file": "runtime/arcane/modules/AI.js",
@@ -31,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(); `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`."
+      "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",
@@ -583,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",
@@ -1092,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",

package/docs/reference/runtime-modules.md

@@ -121,7 +121,7 @@ own asynchronous work, cancellation, and backpressure.
 | [`OpenMeteoWeatherProvider.js`](#openmeteoweatherproviderjs) | esm | Searches and loads Open-Meteo data into complete mutable Arcane weather entities. | Browser / native WebView / server with fetch + cloud | Provider data normalized to mutable entities; transport errors mixed. |
 | [`PersistentAIChatSession.js`](#persistentaichatsessionjs) | esm | Adds explicit retained-history/memory policy to complete configured chat without changing DBOPFS or ChatEntity semantics. | Browser / native WebView with DBOPFS and configured chat | Retained context commits atomically; `persist:false` turns are one-operation-only. |
 | [`PreferenceStore.js`](#preferencestorejs) | esm | Loads and updates schema-defined app preferences through native storage with a narrow browser fallback. | Browser/native hybrid | Complete values and operation context retained; exact optional namespace absence or existing Android unsupported capability selects the existing local adapter; partial-service and genuine failures remain errors; an advertised rejected batch is never retried serially. |
-| [`PreparedSpeech.js`](#preparedspeechjs) | esm | Owns detached ordered preparation, semantic audio reuse, and per-caller cancellation behind AI.prepareTTS. | Browser / native WebView with injected synthesis and optional DBOPFS | Complete original inputs, ordered audio metadata, durable reuse, and observable preparation results. |
+| [`PreparedSpeech.js`](#preparedspeechjs) | esm | Owns detached ordered preparation, semantic audio reuse, cache-only lookup, and per-caller cancellation behind AI.prepareTTS and AI.readPreparedTTS. | Browser / native WebView with optional DBOPFS and injected synthesis for generation | Complete original inputs, ordered audio metadata, durable reuse, and observable preparation results. |
 | [`PrintView.js`](#printviewjs) | esm | Prints current rendered content and title through one document-owned print lifecycle. | Browser / supported native WebView print implementation | Complete rendered snapshot, preparation cancellation, resource lifetime, and honest request result. |
 | [`QRCode.min.js`](#qrcodeminjs) | classic-script | Vendored QRCode generator for DOM, canvas, SVG, and image output. | Browser vendor script | Vendor-native. |
 | [`Questionnaire.js`](#questionnairejs) | esm | Evaluates whether a one-time questionnaire prompt is due without performing the prompt. | Cross-host | Normalized conservative boolean. |
@@ -171,6 +171,7 @@ default `AI`; read-only `providerRuntime`, `speechActivationPending`, `browserSp
 read-only `ttsSegmentation`, `configureTTSSegmentation()`,
 `streamTTS(text='',end=false,options={})`,
 `prepareTTS({parts,textFormat,storage,identity,signal,onState})`,
+`readPreparedTTS({parts,textFormat,storage,identity,signal,onState})`,
 `prepareAudioOutput()`, `playPreparedTTS(prepared,{signal,onState,audioOutput})`,
 `finishTTS()`, `prepareTTSPlayback()`, `fetchTTS()`, `fetchSTT()`, `stopAudio()`, `resumeAudio()`,
 `playAudio()`; consumes `user-entity-loaded` and `arcane-ollama-ready`,
@@ -497,6 +498,34 @@ cancelling one handle does not cancel another active matching caller.
 Preparation cancellation prevents later synthesis and releases its activation
 interest. The provider's operation remains responsible for actual cleanup.
 
+`await readPreparedTTS({parts,textFormat,storage,identity,signal,onState})`
+returns a complete ready preparation handle or `null`. It uses the same original
+parts, selected speech configuration, voice/speed/pause values, text treatment,
+segmentation, and application identity as `prepareTTS()` for semantic matching.
+It never activates or unmutes a provider, synthesizes, starts playback, writes
+storage, or repairs a partial record. With storage, it reads the existing
+manifest and every ordered audio reference through the existing per-key storage
+queue. It passes `{createTable:false}` to DBOPFS manifest and audio reads,
+including later handle reads, so missing tables stay absent. Supplied database
+adapters are responsible for honoring that read-existing contract.
+No matching record or any missing audio returns `null`; unreadable
+metadata and other storage errors reject. Without storage, only a completed,
+matching, same-AI retained in-memory preparation can be returned; pending or
+failed work returns `null`.
+
+A hit returns `{segments,state,ready,getAudio(index),cancel()}` with `state`
+and every segment already `ready`; `onState` synchronously replays that state.
+A miss emits no state callback. The lookup signal rejects cancellation as
+`AbortError` and detaches when lookup settles; aborting it after success does
+not cancel the returned handle. An already-started non-abortable database read
+may finish after cancellation; observed cancellation prevents subsequent reads
+or a returned handle. The handle's explicit `cancel()` retains its
+own lifetime. Durable `getAudio(index)` reopens the stored file with its retained
+MIME type, so a later file removal remains an observable error. Native speech
+without audio export rejects with `ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE`, as
+`prepareTTS()` does. Pass a returned handle to `playPreparedTTS()` only when
+playback is wanted.
+
 `playPreparedTTS(prepared,{signal,onState,audioOutput})` can attach immediately. Its returned
 `{state,error,finished,pause(),resume(),stop()}` handle schedules segments in
 their original order using the existing AI audio clock. `finished` resolves `true` after
@@ -2254,6 +2283,23 @@ default `DBOPFS`; installs `window.dbopfs`, emits `dbopfs-ready`; table/file/bac
 
 Exact exports: `DBOPFS_EVENT_TYPES`, `DBOPFS_REASONS`, `default`.
 
+`getTableHandle(tableName='', {create=true}={})` lazily opens or creates the
+requested table by default. `{create:false}` looks up only an existing table
+without joining a pending create request; a missing table rejects with the
+platform's `NotFoundError`. The existing `memories` / `memory` alias is retained.
+`readFile(tableName='', fileName='', {createTable=true}={})` returns the complete
+raw file. `{createTable:false}` also prevents table creation, and missing tables
+or files reject with `NotFoundError`. Its synchronous-access worker fallback
+already opens existing app/table/file handles without creating them.
+
+`get(tableName='', fileName='', force=false, {createTable=true}={})` retains its
+existing parsed-value cache and `force` behavior, forwarding `createTable` when
+it reads a file. On a read, `NotFoundError` resolves `null`; other errors reject.
+Use `get(tableName,fileName,true,{createTable:false})` for an existing-storage
+lookup that does not return an earlier cached value. Omitted options preserve the previous
+lazy table-creation behavior. These options change neither write operations nor
+the owning app scope's initialization.
+
 `subscribeChanges(listener, {signal, once})` observes
 `DBOPFS_EVENT_TYPES.change` (`dbopfs-change`) through the existing canonical
 `arcane-os/event-manager` source. It returns an idempotent unsubscribe function
@@ -3649,10 +3695,11 @@ console.log(Object.keys(module));
 
 ### Overview
 
-Shared preparation mechanism used by `AI.prepareTTS()`. It owns ordered
-generation admission, same-owner request sharing, complete audio storage and
-semantic reuse, and each caller's preparation lifetime. It does not construct
-an audio context, play speech, or select application content.
+Shared preparation mechanism used by `AI.prepareTTS()` and `AI.readPreparedTTS()`.
+It owns ordered generation admission, same-owner request sharing, complete audio
+storage and semantic reuse, cache-only lookup, and each caller's preparation
+lifetime. It does not construct an audio context, play speech, or select
+application content.
 
 ### Public surface
 
@@ -3661,10 +3708,29 @@ segmentation=null,storage=null,identity=null,signal=null,onState,synthesize})`.
 The owning AI supplies already segmented speech parts, complete original parts,
 its selection snapshot, and its synthesis callback. The returned handle is
 `{segments,state,ready,getAudio(index),cancel()}`. Applications use
-`AI.prepareTTS()` and `AI.playPreparedTTS()` so the existing AI owner retains
-automatic formatting cleanup, segmentation, provider readiness/capacity, and
+`AI.prepareTTS()`, `AI.readPreparedTTS()`, and `AI.playPreparedTTS()` so the existing
+AI owner retains automatic formatting cleanup, segmentation, provider readiness/capacity, and
 ordered playback. See the [complete preparation contract](ai/browser-speech.md#prepare-narration-once-and-replay-stored-audio).
 
+Named async `readPreparedSpeech({owner,parts,originalParts=parts,selection=null,
+segmentation=null,storage=null,identity=null,signal=null,onState=null})` uses
+the same complete semantic matcher and resolves a ready preparation handle or
+`null`. It performs no synthesis, model activation, playback, storage writes,
+or repair. A durable lookup reads the existing manifest and every audio file;
+missing matching records or audio return `null`, while malformed metadata and
+other read failures reject. Manifest, audio availability, and returned-handle
+audio reads pass `{createTable:false}` to DBOPFS so a missing table is never
+created; supplied adapters own the same read-existing behavior. Without storage
+it reads only a completed matching same-owner in-memory preparation, never
+pending or failed work. A hit replays
+ready state through `onState`; a miss emits nothing. Lookup cancellation rejects
+with `AbortError` and is detached on settlement. After success the returned
+handle's explicit `cancel()` is independent of the lookup signal; its `ready`
+resolves the complete record and `getAudio(index)` preserves the existing MIME
+and later-read error behavior. Already-started non-abortable database reads may
+settle after cancellation; no further reads or handle are returned after the
+cancellation is observed.
+
 `storage:{db,table,key}` is optional; the ready DBOPFS instance supplies
 `get`, `set`, `readFile`, and `writeFile`. JSON-compatible semantic inputs stay
 complete in the version-1 manifest. Raw audio is persisted separately and its
@@ -3672,13 +3738,14 @@ MIME type is retained in metadata. Storage mutation serializes by database,
 table, and key within the realm. Synthesis sharing is scoped to the same owner
 and matching semantic inputs/storage; playback remains outside this module.
 
-Exact exports: `prepareSpeech`.
+Exact exports: `prepareSpeech`, `readPreparedSpeech`.
 
 ### Availability and normalization
 
-**Browser or native WebView with Blob, AbortController, an injected synthesis
-callback, and optional ready DBOPFS.** Import creates no provider or
-playback. Calling the preparation function starts owned asynchronous work.
+**Browser or native WebView with Blob, AbortController, optional ready DBOPFS,
+and an injected synthesis callback for generation.** Import creates no provider or
+playback. Calling `prepareSpeech` starts owned asynchronous generation/reuse;
+`readPreparedSpeech` only reads existing complete audio.
 `ready` rejects complete synthesis/storage failures or `AbortError` after
 cancellation; successful audio remains available for reuse. Malformed part,
 storage, or semantic metadata inputs throw `TypeError`; an invalid segment

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.77.0",
+  "version": "0.78.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/runtime/arcane/modules/AI.js

@@ -26,7 +26,7 @@ import {
     openAIResponseFormat
 } from 'arcane-os/ai/twin-cloud';
 import {MarkdownSpeech,stripSpeechFormatting} from 'arcane-os/speech-text';
-import {prepareSpeech} from './PreparedSpeech.js';
+import {prepareSpeech, readPreparedSpeech} from './PreparedSpeech.js';
 import {createToolTextObserver} from 'arcane-os/ai/tool-text-stream';
 
 const completeValue=(value)=>value;
@@ -6341,16 +6341,15 @@ class AI {
         return result;
     }
 
-    prepareTTS({parts, textFormat, storage = null, identity = null, signal = null, onState = null} = {}) {
+    #preparedSpeechInput(parts, textFormat, operation) {
         if(this.#providerSpeechModel()?.speech?.playback==='native'){
             const error=new Error('Native browser speech has no audio file to prepare or store; use prepareTTSPlayback.');
             error.code='ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE';
             throw error;
         }
         if(!is.array(parts)) {
-            throw new TypeError('AI.prepareTTS parts must be an array.');
+            throw new TypeError(`${operation} parts must be an array.`);
         }
-        const runtime = this;
         const selected = this.#providerRuntime.selection('tts');
         const configuredSpeech = this.browserSpeechConfiguration?.tts;
         const configuration = configuredSpeech
@@ -6367,12 +6366,9 @@ class AI {
             responseFormat: selected ? this.#providerSpeechResponseFormat() : this.audioFormat,
             configuration
         };
-        const browserGeneration = this.#browserSpeechGeneration;
-        const controlGeneration = this.#speechControlGeneration;
         const defaultVoice = selected
             ? this.#providerSpeechVoice()
             : this.#builtInSpeechDefaultVoice('tts', this.ttsService);
-        const responseFormat = selection.responseFormat;
         const segmentation = this.ttsSegmentation;
         const segments = [];
         for(const part of parts) {
@@ -6398,6 +6394,33 @@ class AI {
                 );
             }
         }
+        return {segments, selection, segmentation, selected};
+    }
+
+    async readPreparedTTS({parts, textFormat, storage = null, identity = null, signal = null, onState = null} = {}) {
+        const {segments, selection, segmentation} = this.#preparedSpeechInput(parts, textFormat, 'AI.readPreparedTTS');
+        this.#traceSpeech('readPreparedTTS.call', {parts, segments, selection, segmentation, identity, storage});
+        return readPreparedSpeech(
+            {
+                owner: this,
+                parts: segments,
+                originalParts: parts,
+                selection,
+                segmentation,
+                storage,
+                identity,
+                signal,
+                onState
+            }
+        );
+    }
+
+    prepareTTS({parts, textFormat, storage = null, identity = null, signal = null, onState = null} = {}) {
+        const {segments, selection, segmentation, selected} = this.#preparedSpeechInput(parts, textFormat, 'AI.prepareTTS');
+        const runtime = this;
+        const browserGeneration = this.#browserSpeechGeneration;
+        const controlGeneration = this.#speechControlGeneration;
+        const responseFormat = selection.responseFormat;
         this.#traceSpeech('prepareTTS.call', {parts, segments, selection, segmentation, identity, storage});
         async function synthesizePreparedSpeech(part, requestSignal) {
             function assertPreparedSpeechSelection() {

package/runtime/arcane/modules/DBOPFS.js

@@ -554,12 +554,13 @@ class DBOPFS {
 
     /**
      * Gets the directory handle for a table.
-     * Creates the table if it does not exist.
+     * Creates the table if it does not exist unless create is false.
      *
      * @param {string} tableName
+     * @param {{create?:boolean}} options A false create performs an existing-table lookup only.
      * @returns {Promise<FileSystemDirectoryHandle>}
      */
-    async getTableHandle(tableName=''){
+    async getTableHandle(tableName='',{create=true}={}){
         if(!this.ready){
             await this.readyPromise;
         }
@@ -582,6 +583,14 @@ class DBOPFS {
             return existingHandle;
         }
 
+        if(!create){
+            // A read-existing lookup must not wait for another caller to create the table.
+            return this.#db.getDirectoryHandle(
+                directoryName,
+                {create:false}
+            );
+        }
+
         if(!this.#tableHandlePromises[registeredTableName]){
             const handlePromise=this.#db.getDirectoryHandle(
                 directoryName,
@@ -736,10 +745,14 @@ class DBOPFS {
      *
      * @param {string} tableName
      * @param {string} fileName
+     * @param {{createTable?:boolean}} options A false createTable preserves an absent table.
      * @returns {Promise<File>}
      */
-    async readFile(tableName='',fileName=''){
-        const table=await this.getTableHandle(tableName)
+    async readFile(tableName='',fileName='',{createTable=true}={}){
+        const table=await this.getTableHandle(
+            tableName,
+            {create:createTable}
+        )
         const handle=await table.getFileHandle(fileName,{create:false})
 
         if(is.function(handle.getFile)){
@@ -818,14 +831,19 @@ class DBOPFS {
      * @param {string} tableName
      * @param {string} fileName
      * @param {boolean} force
+     * @param {{createTable?:boolean}} options A false createTable preserves an absent table.
      * @returns {Promise<*>}
      */
-    async get(tableName='',fileName='',force=false){
+    async get(tableName='',fileName='',force=false,{createTable=true}={}){
         if(force||!this.#tables[tableName]?.[fileName]){
             const cacheState=this.#fileCacheState(tableName,fileName);
             const cacheRevision=cacheState.revision;
             try{
-                const file=await this.readFile(tableName,fileName)
+                const file=await this.readFile(
+                    tableName,
+                    fileName,
+                    {createTable}
+                )
                 const textContent=await file.text()
 
                 if(!this.#tables[tableName]){

package/runtime/arcane/modules/PreparedSpeech.js

@@ -111,8 +111,10 @@ function serializeStorage(storage,execute){
     return operation;
 }
 
-async function readManifest(storage){
-    const stored=await storage.db.get(storage.table,storage.fileName,true);
+async function readManifest(storage,cacheOnly=false){
+    const stored=cacheOnly
+        ?await storage.db.get(storage.table,storage.fileName,true,{createTable:false})
+        :await storage.db.get(storage.table,storage.fileName,true);
     if(stored===null||stored===undefined)return {version:1,entries:[]};
     const manifest=copyJSON(stored);
     if(manifest.version!==1||!is.array(manifest.entries)){
@@ -349,9 +351,10 @@ function finishPreparation(job,error){
     job.finished.resolve();
 }
 
-function createJob(ownerState,input,storage,synthesize,previous){
-    const job={
+function createJobState(input,storage,synthesize=null,previous=null){
+    return {
         input,storage,synthesize,previous,
+        cacheOnly:false,
         controller:new AbortController(),
         interests:new Set(),
         state:'queued',
@@ -367,6 +370,10 @@ function createJob(ownerState,input,storage,synthesize,previous){
             return {...part,index,state:'queued',audioFile:null,contentType:null,error:null};
         })
     };
+}
+
+function createJob(ownerState,input,storage,synthesize,previous){
+    const job=createJobState(input,storage,synthesize,previous);
     const admission=ownerState.admission.then(function admitOrderedPreparation(){
         return admitPreparation(job);
     });
@@ -416,7 +423,9 @@ function createHandle(job,signal,onState){
             if(!interest.active)throw abortError();
             if(!job.storage)return job.slots[index].blob;
             const audio=job.record.segments[index];
-            const file=await job.storage.db.readFile(job.storage.table,audio.audioFile);
+            const file=job.cacheOnly
+                ?await job.storage.db.readFile(job.storage.table,audio.audioFile,{createTable:false})
+                :await job.storage.db.readFile(job.storage.table,audio.audioFile);
             if(!interest.active)throw abortError();
             return file.type===audio.contentType?file:new Blob([file],{type:audio.contentType});
         },
@@ -482,4 +491,100 @@ function prepareSpeech({
     return createHandle(job,signal,onState);
 }
 
-export {prepareSpeech};
+/** Read complete existing audio without synthesis, storage writes, or repair. */
+async function readPreparedSpeech({
+    owner,
+    parts,
+    originalParts=parts,
+    selection=null,
+    segmentation=null,
+    storage=null,
+    identity=null,
+    signal=null,
+    onState=null
+}={}){
+    if((!owner||!is.object(owner))&&!is.function(owner)){
+        throw new TypeError('Speech preparation requires its owning AI instance.');
+    }
+    if(!is.array(parts)||(onState!==null&&!is.function(onState))){
+        throw new TypeError('Cached speech requires ordered parts and an optional state callback.');
+    }
+    const input=copyJSON({parts,originalParts,selection,segmentation,identity});
+    const destination=normalizeStorage(storage);
+    if(signal?.aborted)throw abortError();
+    function completeCachedRead(job){
+        // The lookup signal owns only this read. Retained audio keeps its own
+        // explicit cancellation lifetime after a successful lookup returns.
+        const handle=createHandle(job,null,onState);
+        if(signal?.aborted){
+            handle.cancel();
+            throw abortError();
+        }
+        return handle;
+    }
+    if(!destination){
+        const jobs=owners.get(owner)?.jobs;
+        if(!jobs)return null;
+        for(const job of jobs){
+            if(job.storage||!job.done||job.failed||job.controller.signal.aborted
+                ||!sameInput(job.input,input))continue;
+            if(!job.slots.every(function hasRetainedAudio(slot){
+                return slot.settled&&slot.blob instanceof Blob;
+            }))return null;
+            return completeCachedRead(job);
+        }
+        return null;
+    }
+    const cancelled=deferred();
+    function cancelRead(){cancelled.reject(abortError());}
+    signal?.addEventListener('abort',cancelRead,{once:true});
+    try{
+        const reading=serializeStorage(destination,async function readCachedPreparation(){
+            if(signal?.aborted)throw abortError();
+            const manifest=await readManifest(destination,true);
+            if(signal?.aborted)throw abortError();
+            const record=manifest.entries.find(function findCachedPreparation(entry){
+                return sameInput(entry,input);
+            });
+            if(!record)return null;
+            if(!is.array(record.segments)||record.segments.length!==input.parts.length){
+                throw new TypeError('Stored speech preparation segments are unreadable.');
+            }
+            let complete=true;
+            for(const audio of record.segments){
+                if(!audio?.audioFile){
+                    complete=false;
+                    continue;
+                }
+                if(!is.string(audio.contentType)){
+                    throw new TypeError('Stored speech audio content type is unreadable.');
+                }
+                if(signal?.aborted)throw abortError();
+                try{
+                    const file=await destination.db.readFile(destination.table,audio.audioFile,{createTable:false});
+                    if(!(file instanceof Blob)){
+                        throw new TypeError('Stored speech audio must be a Blob.');
+                    }
+                }catch(error){
+                    if(error?.name!=='NotFoundError')throw error;
+                    complete=false;
+                }
+                if(signal?.aborted)throw abortError();
+            }
+            return complete?record:null;
+        });
+        const record=await Promise.race([reading,cancelled.promise]);
+        if(signal?.aborted)throw abortError();
+        if(!record)return null;
+        const job=createJobState(input,destination);
+        job.cacheOnly=true;
+        job.record=record;
+        for(let index=0;index<job.slots.length;index+=1)settleSegment(job,index);
+        finishPreparation(job);
+        return completeCachedRead(job);
+    }finally{
+        signal?.removeEventListener('abort',cancelRead);
+    }
+}
+
+export {prepareSpeech,readPreparedSpeech};