arcane-os 0.77.0 → 0.79.0

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

@@ -1,30 +1,58 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.76.0",
+  "sdkVersion": "0.78.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 299,
+  "memberCount": 301,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "local-ai-execution-devices:createExecutionDeviceCatalog",
+      "name": "createExecutionDeviceCatalog",
+      "displayName": "createExecutionDeviceCatalog()",
+      "kind": "function",
+      "signature": "createExecutionDeviceCatalog({signal}={})",
+      "entrypoints": ["arcane-os/local-ai/execution-devices"],
+      "primaryImport": "arcane-os/local-ai/execution-devices",
+      "group": "Physical execution devices",
+      "summary": "Owns lazy physical-device discovery and saved device-ID resolution independently of models and inference.",
+      "availability": "Node; Windows discovery is implemented, while other platforms return an unavailable inventory without changing existing AI behavior",
+      "protocol": "Physical inventory {platform,state,devices,issues}; target resolution {requestedTarget,resolvedDevice,resolution,reason}",
+      "normalization": "Returns async devices({refresh=false,signal}={}), async resolveTarget({executionTarget=null,refresh=false,signal}={}) and dispose(). Construction performs no discovery I/O; calls share cached/coalesced discovery and refresh explicitly requests a new observation. Complete records and issues distinguish ready, partial and unavailable discovery. A saved deviceId resolves as matched, unavailable or unsupported; null returns automatic/engine-default-required without discovery, and a non-null target without a nonempty string deviceId throws TypeError. Physical presence never proves engine support or actual execution. Request cancellation rejects AbortError/ARCANE_CANCELLED and the last departing caller stops the query; retained dispose() joins owned discovery shutdown, and constructor-signal abort disposes the catalog. The direct caller owns disposal; no polling, model loading, preference writes or silent target substitution. See execution-devices.md for all record fields and reasons."
+    },
+    {
+      "id": "core-execution-devices:createExecutionDeviceService",
+      "name": "createExecutionDeviceService",
+      "displayName": "createExecutionDeviceService()",
+      "kind": "function",
+      "signature": "createExecutionDeviceService({catalog=createExecutionDeviceCatalog()}={})",
+      "entrypoints": ["arcane-os/core/execution-devices"],
+      "primaryImport": "arcane-os/core/execution-devices",
+      "group": "Physical execution devices",
+      "summary": "Registers physical-device discovery as an independent Core service with catalog lifetime ownership.",
+      "availability": "Node Core; available independently of selected or loaded model runtimes, with discovery support reported by the catalog",
+      "protocol": "arcane/1 localai.devices and localai.resolveTarget",
+      "normalization": "Returns the execution-devices service with localai.devices({refresh=false}) and localai.resolveTarget({executionTarget=null,refresh=false}); both forward the Core request signal and return the catalog's complete result. Registration performs no discovery or model work. dispose() owns disposal of the supplied or default catalog; other services may borrow that same catalog without owning it."
+    },
     {
       "id": "local-ai-decisions:createNativeDecisionModel",
       "name": "createNativeDecisionModel",
       "displayName": "createNativeDecisionModel()",
       "kind": "function",
-      "signature": "createNativeDecisionModel({onnx,modelAssets,workingDirectory,paths,model='onnx-community/laya-typed-decisions-ONNX',revision='main',dtype='fp32',sessionOptions,executionPreference='gpu',signal}={})",
+      "signature": "createNativeDecisionModel({onnx,modelAssets,workingDirectory,paths,model='onnx-community/laya-typed-decisions-ONNX',revision='main',dtype='fp32',sessionOptions,executionPreference='gpu',executionTarget,signal}={})",
       "entrypoints": ["arcane-os/local-ai/decisions"],
       "primaryImport": "arcane-os/local-ai/decisions",
       "group": "Native typed decisions",
       "summary": "Explicit native Laya FP32 option scoring through an existing ONNX owner and a tokenizer Worker.",
       "availability": "Node on Windows/Linux/macOS with selected ONNX Runtime and model files; Android needs host adaptation",
       "protocol": "Shared browser/native decision encoding with native named tensor results",
-      "normalization": "Returns load/evaluate/classify/current/status/subscribe/unload/dispose; preserves complete separate state/question/options/type and original rows, raw scores and every graph output. Explicit load prepares selected upstream files or uses caller-owned paths; GPU preference attempts advertised providers then CPU. Cancellation retires the shared activation; files remain retained through actual ONNX and tokenizer Worker exit. No chat history or duplicate inference engine."
+      "normalization": "Returns load/evaluate/classify/current/status/subscribe/unload/dispose; preserves complete separate state/question/options/type and original rows, raw scores and every graph output. Explicit load prepares selected upstream files or uses caller-owned paths. load({executionTarget,signal}) retains the latest selected target when omitted or undefined, initially the factory selection; null requests automatic resolution, while {deviceId} forwards the saved physical selection to the existing ONNX owner. With no target selection, GPU preference still attempts advertised providers then CPU and explicit session providers retain precedence. Same-target loads share activation; a changed target cancels the earlier request and joins its actual ONNX/tokenizer cleanup before replacement. pendingActivation reports the requested replacement separately; current().execution remains the complete ONNX load record, with requested/resolved/configured/observed target diagnostics in current().execution.execution. Configuration alone does not prove physical execution. Cancellation retires the shared activation; files remain retained through actual ONNX and tokenizer Worker exit. No preference writes, chat history or duplicate inference engine."
     },
     {
       "id": "core-decisions:createNativeDecisionService",
@@ -38,7 +66,7 @@
       "summary": "Renderer-independent native Laya service reusing the registered local-AI and model-assets owners.",
       "availability": "Node Core with selected native ONNX and model files",
       "protocol": "arcane/1 decisions.status/load/evaluate/unload and decisions.state",
-      "normalization": "Registration starts no model or tokenizer. Explicit load obtains dependency-ready same-process owners and reacquires getONNXRuntime after recovery. Native load/evaluate/classify/current/subscribe/unload/dispose preserve complete results; RPC uses the existing tensor codec. Unload has accepted service lifetime; host shutdown cancels request-lifetime load/evaluation."
+      "normalization": "Registration starts no model or tokenizer. Explicit load obtains dependency-ready same-process owners and reacquires getONNXRuntime after recovery. Factory configuration accepts executionTarget; direct load({executionTarget,signal}) and Core decisions.load({executionTarget}) preserve omitted/undefined selection and explicit null automatic selection. Same-target loads coalesce; changed targets cancel pending work and join the prior model's disposal before replacement. pendingActivation remains separate from the full activation execution record and its nested execution diagnostics. Native load/evaluate/classify/current/subscribe/unload/dispose preserve complete results; RPC uses the existing tensor codec. Unload has accepted service lifetime; host shutdown cancels request-lifetime load/evaluation."
     },
     {
       "id": "core-decisions:default",
@@ -353,14 +381,14 @@
       "name": "createONNXRuntime",
       "displayName": "createONNXRuntime()",
       "kind": "function",
-      "signature": "createONNXRuntime({modulePath,signal,onEvent}={})",
+      "signature": "createONNXRuntime({modulePath,onEvent,signal,executionDevices}={})",
       "entrypoints": ["arcane-os/local-ai/onnx"],
       "primaryImport": "arcane-os/local-ai/onnx",
       "group": "Core local AI",
       "summary": "Owns explicitly loaded ONNX graphs and complete named tensor inference in retained native workers.",
       "availability": "Node on Windows/Linux/macOS x64/arm64 with prepared onnxruntime-node; Android needs host adaptation",
       "protocol": "Per-session worker lifecycle with structured-clone tensors and replaying state",
-      "normalization": "Returns load/run/unload/current/subscribe/close; load accepts executionPreference gpu for advertised provider creation attempts then CPU, while explicit sessionOptions.executionProviders takes precedence. Complete execution diagnostics distinguish configured providers from physical acceleration. stopping revokes new runs while exited records actual Worker exit; recoverable run errors preserve the session. Cleanup joins exit and output delivery even when termination fails."
+      "normalization": "Returns load/run/unload/current/subscribe/close. load({id,model,sessionOptions,executionPreference,executionTarget,signal}) preserves existing behavior when executionTarget is omitted: gpu preference tries advertised providers then CPU, while explicit sessionOptions.executionProviders takes precedence. Explicit null requests automatic selection; with gpu preference and no explicit providers it prefers the highest dedicatedMemoryMiB among mapped hardware GPUs, including integrated hardware, then uses existing provider selection when no eligible mapping exists. A saved {deviceId} selects whole-host CPU or an established DirectML adapter mapping; unavailable, unsupported or conflicting targets report LOCAL_AI_EXECUTION_TARGET_UNAVAILABLE, LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED or LOCAL_AI_EXECUTION_TARGET_CONFLICT without silently replacing the selection. Every loaded session reports requestedTarget, resolvedDevice, resolution/reason and configuredTarget {source,executionProviders}; observedTarget remains null because configuration does not prove physical execution. SDK-selected GPU configurations retain CPU operator support. A supplied executionDevices catalog is borrowed; otherwise the runtime owns its lazy catalog. stopping revokes new runs while exited records actual Worker exit; recoverable run errors preserve the session. Cleanup cancels target discovery and joins preparation, exit and output delivery even when termination fails."
     },
     {
       "id": "core-onnx:createCoreONNXRuntime",
@@ -374,7 +402,7 @@
       "summary": "Accesses local system ONNX through an existing Core client with complete tensor transport.",
       "availability": "Browser with available Core ONNX service; construction installs no runtime or model",
       "protocol": "arcane/1 onnx.status/load/run/unload and localai.state",
-      "normalization": "Returns load/run/unload/inspect/current/subscribe/close; omitted client follows late installation/replacement/retirement and reads current status, while explicit client including null stays fixed. Retirement clears readiness and cancels owned work; late old-client results are suppressed. Preserves typed and string tensors; close removes subscriptions and cancels requests without closing shared Core or implicitly unloading shared models"
+      "normalization": "Returns load/run/unload/inspect/current/subscribe/close; load({id,model,sessionOptions,executionPreference,executionTarget,signal,timeoutMs}) forwards provider preference and physical selection while preserving omitted-versus-null target semantics. Complete native execution diagnostics distinguish requested, resolved and configured targets from unobserved physical execution. Omitted client follows late installation/replacement/retirement and reads current status, while explicit client including null stays fixed. Retirement clears readiness and cancels owned work; late old-client results are suppressed. Preserves typed and string tensors; close removes subscriptions and cancels requests without closing shared Core or implicitly unloading shared models"
     },
     {
       "id": "root:createGitTextSnapshot",
@@ -465,14 +493,14 @@
       "name": "createLocalAIService",
       "displayName": "createLocalAIService()",
       "kind": "function",
-      "signature": "createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent,prepare}={})",
+      "signature": "createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent,prepare,executionDevices}={})",
       "entrypoints": ["arcane-os/core/local-ai"],
       "primaryImport": "arcane-os/core/local-ai",
       "group": "Core local AI",
       "summary": "Composes selected native llama.cpp, Ollama and ONNX engines as a Core service with retained process/worker ownership and model lifecycle.",
       "availability": "Node with selected upstream runtime distributions or available configured system services",
       "protocol": "arcane/1 methods and events; llama.cpp OpenAI HTTP/SSE, Ollama native HTTP/NDJSON and ONNX tensor transport",
-      "normalization": "Application-owned runtime and model requirements; optional prepare supplies installed records during this service startup. getONNXRuntime() returns the actual prepared ONNX owner for native composition after context.getService('local-ai'); callers reacquire after recovery and retain the acquired handle for cleanup. llama.status/models observe without starting or restarting an engine. Independent services, complete responses and exact owned-process cleanup remain unchanged."
+      "normalization": "Application-owned runtime and model requirements; optional prepare supplies installed records during this service startup. Optional executionDevices supplies a borrowed catalog to ONNX; its supplying owner retains catalog disposal responsibility. onnx.load forwards executionPreference and executionTarget with existing model-path resolution, cancellation and omitted-target behavior. getONNXRuntime() returns the actual prepared ONNX owner for native composition after context.getService('local-ai'); callers reacquire after recovery and retain the acquired handle for cleanup. llama.status/models observe without starting or restarting an engine. Independent services, complete responses and exact owned-process cleanup remain unchanged."
     },
     {
       "id": "core-local-ai:default",
@@ -4192,7 +4220,7 @@
       "summary": "Describes existing Core method input, output and semantic shapes.",
       "availability": "Node and browser/bundler",
       "protocol": "arcane/1 method descriptions",
-      "normalization": "Descriptive data only; the active host and its registered services remain the authority for method availability"
+      "normalization": "Descriptive data only, including independent localai.devices inventory and localai.resolveTarget physical-selection records; presence does not establish engine support or observed execution. The active host and its registered services remain the authority for method availability"
     },
     {
       "id": "core-contracts:CoreError",

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/local-ai.md

@@ -169,6 +169,10 @@ process between requests, and joins cleanup during disposal.
 Optional `prepare({signal,onEvent})` returns resolved runtime records before
 this service starts its selected engines. The managed development owner uses
 that callback without delaying the HTTP listener or independent services.
+Optional `executionDevices` supplies the shared execution-device catalog to
+the ONNX owner. Development and generated native composition share one catalog
+per Core lifetime with the independent `execution-devices` service. The ONNX
+owner does not dispose an injected catalog; the composing owner retains it.
 This factory accepts chat/ONNX requirements; the separate
 [`createLocalImageService()`](local-image-generation.md#core-service-and-transport)
 owns image requirements. The development and generated native composition
@@ -384,8 +388,8 @@ try {
 }
 ```
 
-The factory accepts `{modulePath,signal?,onEvent?}` and starts no worker until
-`load({id,model,sessionOptions?,executionPreference?,signal?})`. The model path is absolute for this
+The factory accepts `{modulePath,signal?,onEvent?,executionDevices?}` and starts no worker until
+`load({id,model,sessionOptions?,executionPreference?,executionTarget?,signal?})`. The model path is absolute for this
 direct Node API. Session creation defaults to the CPU execution provider;
 explicit native session options remain caller-owned. The returned session
 record contains `id`, `model`, `state`, `loaded`, `error`, input/output names and
@@ -400,7 +404,7 @@ A recoverable run error keeps `stopping:false` and the loaded session usable.
 rejected load or inference. Unload joins worker exit and output delivery even
 when requesting termination fails; complete cleanup errors remain observable.
 
-Select `executionPreference: 'gpu'` to try the installed runtime's advertised
+With `executionTarget` omitted, select `executionPreference: 'gpu'` to try the installed runtime's advertised
 CUDA, TensorRT, DirectML, CoreML and WebGPU providers in that order, followed by
 CPU when no accelerator session can be created. Discovery runs once per load;
 each advertised candidate receives one actual session-creation attempt with CPU
@@ -413,18 +417,106 @@ DirectML attempts default `enableMemPattern` to `false` and `executionMode` to
 `'sequential'` as required by that provider; explicit caller values remain
 unchanged, including on the final CPU attempt.
 
-Automatic GPU selection adds an `execution` record to the loaded session and
-its ordinary state events: `preference`, complete `supportedBackends`,
+Every loaded session includes an `execution` record in its ordinary state
+events: `preference`, `requestedTarget`, `resolvedDevice`, `resolution`,
+`reason`, `configuredTarget`, `observedTarget`, complete `supportedBackends`,
 `selectedProviders`, ordered `attempts` with their full errors, `fallback`, and
-`discoveryError`. Each attempt records `executionProviders`, `status`
-(`configured` or `failed`), and `error`. `fallback: true` means the SDK created
+`discoveryError`. Each attempt records provider names in `executionProviders`,
+its requested `configuredTarget`, `status` (`configured` or `failed`), and
+`error`. The accepted top-level `configuredTarget` is
+`{source,executionProviders}`; it retains the complete provider options,
+including native numeric `deviceId` values. Its `source` is `cpu-default`,
+`session-options`, `gpu-preference`, `execution-target`, or
+`automatic-physical-target`. It remains `null` until session creation succeeds.
+`fallback: true` means the SDK attempted
 the final CPU session after GPU preference, including when no GPU candidate was
-advertised. Successful creation establishes an accepted provider configuration;
+advertised; `loaded` establishes whether creation succeeded. Successful creation establishes an accepted provider configuration;
 it does not establish that a GPU executed any graph nodes. If every attempt
 fails, the load error retains the complete attempt errors and `execution`
 record. Inference failures retain their existing behavior and do not replay
 inference on another provider.
 
+### Physical execution targets
+
+`executionTarget: {deviceId}` selects a physical identifier returned by the
+[execution-device catalog](execution-devices.md). The identifier is separate
+from an ONNX provider's numeric device ordinal. `executionTarget: null` requests
+automatic selection for this new session. Omission keeps the previous provider
+selection and exact explicit `sessionOptions` behavior described above.
+Generic ONNX sessions still require unloading a live ID before replacement;
+passing another target cannot silently replace that running session.
+
+The current physical routes are the catalog's whole-host CPU (`deviceId: 'cpu'`)
+and GPUs with an actual `addresses.dxgiAdapterIndex` when the installed ONNX
+binding advertises DirectML. DirectML receives
+`{name: 'dml', deviceId: dxgiAdapterIndex}` and retains CPU participation for
+unsupported graph operators. The index comes from DXGI enumeration joined to
+the physical device; a display order, DXCore order or CUDA ordinal is not
+substituted. No CPU socket/core affinity, physical CUDA mapping or NPU provider
+support is inferred from inventory.
+
+An explicit physical target gets one configuration attempt. Missing hardware,
+unsupported provider mapping and contradictory explicit session options report
+`LOCAL_AI_EXECUTION_TARGET_UNAVAILABLE`,
+`LOCAL_AI_EXECUTION_TARGET_UNSUPPORTED`, or
+`LOCAL_AI_EXECUTION_TARGET_CONFLICT`, respectively. An explicit provider list
+must already select the mapped target; it is not overwritten. An automatic
+target conflicts with a fixed provider `deviceId` in explicit session options.
+Matching DirectML options retain caller-authored values and receive only the
+omitted `enableMemPattern: false` and `executionMode: 'sequential'` defaults.
+Native session-creation failures preserve their original errors. The SDK does
+not retry a physical target on another adapter or provider.
+
+For `executionTarget: null` with `executionPreference: 'gpu'` and no explicit
+provider list, automatic selection chooses the largest known positive
+`dedicatedMemoryMiB` among present hardware GPUs with a stable ID and actual
+DirectML mapping, when that provider is advertised. An integrated GPU remains
+eligible when it meets those same conditions. Once selected, that adapter
+gets one attempt. If no such candidate is established, the existing ordered
+provider attempts remain available and report their unresolved physical
+identity honestly. Omitted targets keep their existing selection behavior.
+
+```js
+await onnx.load({
+  id: 'cheese-radar',
+  model: absoluteModelPath,
+  executionPreference: 'gpu',
+  executionTarget: null
+});
+```
+
+`requestedTarget` preserves the requested physical record, or `null` for no
+explicit physical choice. `resolvedDevice` is the matched catalog record or
+`null`; `resolution` describes physical resolution, not engine compatibility.
+During initial physical discovery it is `null`; the resolver then supplies
+`matched`, `automatic`, `unavailable` or `unsupported`. `reason` explains the
+selection or inability. `observedTarget` remains `null`: ONNX Runtime Node
+exposes no actual physical placement observation here, including after a
+successful run. Accepted GPU configuration does not establish that every node
+ran on that GPU.
+
+The runtime creates a lazy catalog only when `executionDevices` is omitted and
+disposes only that owned catalog at close. Catalog preparation belongs to the
+loading session, follows its cancellation and is joined during release. It
+does not serialize independent sessions or delay browser rendering.
+
+### What Settings can know before loading
+
+`localai.devices` and `localai.resolveTarget` belong to the independent
+`execution-devices` service and do not load a model or wait for model-runtime
+preparation. They establish detected hardware and physical identity only.
+Settings can show those records and retain an application-owned preference
+keyed by provider/model. A matched physical ID is not a confirmed selectable
+target for every engine.
+
+The current ONNX binding's compiled-provider discovery runs in the session
+worker at an explicit load. There is no model-free ONNX capability query in
+this interface. Before that observation, engine compatibility is unknown;
+do not label every enumerated GPU or NPU supported. An advertised provider
+still does not establish usable provider libraries, model compatibility or
+actual execution. Consume the explicit load's configuration or complete
+failure, and keep observed placement unknown when it is not supplied.
+
 `run({id,feeds,fetches?,runOptions?,signal?})` returns the complete output-name
 map of `{type,dims,data}` tensors. Input records use that same shape with native
 typed data or string arrays. Optional `fetches` selects output names or supplies
@@ -456,7 +548,7 @@ Other sessions retain their own lifetimes.
 | Core method | Parameters | Result |
 | --- | --- | --- |
 | `onnx.status` | `{}` | Runtime availability and current `models` session records |
-| `onnx.load` | `{id,model,sessionOptions?}` | Loaded session; relative model paths resolve from `appRoot` |
+| `onnx.load` | `{id,model,sessionOptions?,executionPreference?,executionTarget?}` | Loaded session; relative model paths resolve from `appRoot` |
 | `onnx.run` | `{id,feeds,fetches?,runOptions?}` | Complete encoded tensor output map |
 | `onnx.unload` | `{id}` | Released session record |
 
@@ -477,7 +569,9 @@ onnx.close();
 
 The accessor exposes `load`, `run`, `unload`, `inspect`, `current`, `subscribe`
 and `close`. Request methods accept `signal` and optional `timeoutMs` (default
-`0`, no elapsed-time cutoff). It preserves full typed tensor values, including
+`0`, no elapsed-time cutoff). Load forwards `executionPreference` and preserves
+the native load's distinction between omitted and null `executionTarget`.
+Tensor transport preserves full typed tensor values, including
 64-bit integers, floating-point special values and strings, through the
 transport codec. `current()` adds `busy` and `closed` to its latest Core state.
 Closing the accessor cancels its requests and subscriptions; model unloading

package/docs/reference/native-decisions.md

@@ -58,7 +58,7 @@ name to `decisions`. It exposes `load`, `evaluate`, `classify` (an alias for
 | Method | Parameters and result |
 | --- | --- |
 | `decisions.status` | Current lifecycle snapshot; does not load anything. |
-| `decisions.load` | Explicit activation; returns the ready lifecycle snapshot. The request signal cancels activation. |
+| `decisions.load` | `{executionTarget?}`, where the target is `{deviceId:string}` or `null`; explicit activation or target replacement, returning the ready lifecycle snapshot. The request signal cancels activation. |
 | `decisions.evaluate` | `{rows, runOptions?}`; returns `{decisions, outputs}`. The request signal cancels the active model operation. |
 | `decisions.unload` | Releases the activation. Service-lifetime cleanup continues after the caller disconnects. |
 
@@ -111,12 +111,66 @@ is loaded by this API.
 This graph selection requires `dtype:'fp32'`, which is also the default; another
 dtype reports the incompatible selection rather than substituting a graph.
 `sessionOptions` and `runOptions` pass to the existing native ONNX API unchanged.
-`executionPreference` defaults to `gpu` here: actual advertised native GPU
-provider creation is attempted, followed by an honest CPU fallback. Explicit
-`sessionOptions.executionProviders` takes precedence. The underlying generic
-ONNX factory continues to default to CPU. Accepted provider configuration is
-not evidence that GPU nodes executed. Full provider-attempt diagnostics remain
-in `execution`; see [native ONNX sessions](local-ai.md#native-onnx-sessions).
+With no `executionTarget` selection, `executionPreference` defaults to `gpu`
+here: actual advertised native GPU provider creation is attempted, followed by
+an honest CPU fallback. Explicit `sessionOptions.executionProviders` takes
+precedence on that unchanged path. The underlying generic ONNX factory
+continues to default to CPU. Accepted provider configuration is not evidence
+that GPU nodes executed. Full provider-attempt diagnostics remain in
+`execution`; see [native ONNX sessions](local-ai.md#native-onnx-sessions).
+
+## Select an activation's execution device
+
+Both factories accept `executionTarget: {deviceId:string}` or `null` in their
+configuration. Direct model and service calls accept
+`load({executionTarget, signal})`; the Core `decisions.load` method carries the
+same target in its parameters. Use an actual stable ID from the shared
+[physical device catalog](execution-devices.md), or the documented whole-host
+CPU ID:
+
+```js
+await decisions.load({executionTarget: {deviceId: 'cpu'}});
+// A different explicit selection drains the current activation and replaces it.
+await decisions.load({executionTarget: null});
+```
+
+Omitting `executionTarget`, or supplying `undefined`, retains the most recent
+explicit selection, initially the factory's selection. When neither supplies a
+target, existing constructor, session-option and provider-default behavior
+remains unchanged. Explicit `null` requests automatic device resolution at the
+new activation boundary. It remains distinct from omission. The selection
+stays available for a later explicit load after unloading or a failed load;
+the SDK creates no preference store and does not change application preferences.
+
+The decision owner forwards the target to its existing ONNX owner. That owner
+resolves the physical ID, supported provider and provider-specific address.
+An unavailable or unsupported explicit target reports its actual failure; it
+does not silently select another adapter or a cloud provider. GPU selection
+does not require every graph node to execute on the GPU: supported CPU graph
+partitioning remains an engine concern. See the native ONNX contract for exact
+target routing and automatic-selection behavior.
+
+The existing `current().execution` field remains the complete ONNX session load
+record for that activation. Its `execution` member carries `requestedTarget`,
+`resolvedDevice`, `resolution`, `configuredTarget` and `observedTarget`, alongside
+provider-attempt diagnostics. These distinguish requested selection, physical
+resolution, accepted configuration and actual execution evidence. An unknown
+`observedTarget` remains `null`; successful configuration alone does not establish
+which device executed graph nodes.
+
+`pendingActivation` is separately `null` or `{executionTarget}` while a load or
+replacement is pending; its `executionTarget` property is omitted at JSON
+transport when the selection is `undefined`. A pending target never overwrites the previous
+activation's `execution` record. The old record remains attributable to the
+retiring activation until its cleanup completes, then the new activation owns
+its own record. A request is not a claim that the requested device is running.
+
+Concurrent loads for the same target share their pending activation. A
+different target supersedes the earlier pending request, which rejects with
+cancellation instead of returning another target's ready result. Replacement
+joins this model's actual tokenizer/native cleanup before creating its
+successor. Independent model owners retain their independent workers and
+lifetimes; there is no all-model loading barrier or trial inference.
 
 ## Complete inputs and outputs
 
@@ -148,14 +202,15 @@ runtime; sharing the encoding implementation alone does not establish it.
 ## Lifetime and cancellation
 
 `current()` returns `{family, model, revision, dtype, state, loaded, busy,
-activeRequests, progress, error, execution}`. States include `unloaded`,
+activeRequests, progress, error, execution, pendingActivation}`. States include
+`unloaded`,
 `loading`, `ready`, `unloading`, `disposing`, `disposed` and `error`. Semantic
 progress includes model preparation, tokenization and evaluation; downloaded
 members report files, not byte progress. Complete technical errors belong in
 developer diagnostics, while the application owns its user-facing status.
 
-Concurrent callers share one explicit activation. Cancelling a load or
-evaluation cancels that activation and its outstanding operations, because the
+Concurrent callers selecting the same target share one explicit activation.
+Cancelling a load or evaluation cancels that activation and its outstanding operations, because the
 native session and tokenizer have one owner. Use separately owned models when
 independent cancellation is required. The construction `signal` governs the
 whole model lifetime. `unload()` permits another explicit load after successful

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