arcane-os 0.77.0 → 0.79.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.79.0
+
+- Add public `createExecutionDeviceCatalog()` and `createExecutionDeviceService()`
+  with lazy Windows CPU/GPU/NPU discovery, stable host-local identities,
+  complete discovery issues, explicit refresh, cancellation and disposal.
+  `localai.devices` and `localai.resolveTarget` use the existing Core transport
+  without loading models or changing saved preferences.
+- Share one catalog per local-AI Core lifetime. Native ONNX and Laya accept
+  `executionTarget` for a physical CPU or mapped DirectML GPU. Automatic GPU
+  selection can use the largest reported dedicated capacity among addressable
+  hardware GPUs; integrated GPUs remain eligible. Unsupported or unavailable
+  selections are reported without silently choosing another physical device.
+- Preserve caller options and complete execution diagnostics. Distinguish the
+  requested, resolved and configured target from observed execution; successful
+  configuration is not GPU/NPU execution proof. Laya target replacement cancels
+  and drains only its retiring activation before the successor starts.
+- Keep discovery independent from model readiness and preserve existing engine
+  behavior when a target is omitted. Browser Wllama, native llama.cpp, image and
+  Whisper device routing are unchanged; this release adds no driver, model or
+  native runtime dependency.
+
+## 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,12 +20,17 @@ 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.79.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;
 registry state is deliberately not baked into application artifacts.
 
+[Physical execution devices](docs/reference/execution-devices.md) exposes Windows
+CPU/GPU/NPU discovery and native ONNX/Laya target selection through the existing
+Core host, independently of model loading. Device presence, configured provider
+placement and observed model execution remain separate facts.
+
 Standalone browser apps use their repository root and installed npm package directly, without a
 generated workspace `arcane/` directory or `arcane.lock.json`. Select the
 [four installed-package routes](docs/reference/protocols.md#installed-package-browser-routes)

package/browser-runtime/ai/core-onnx.mjs

@@ -106,9 +106,13 @@ export function createCoreONNXRuntime({client: suppliedClient} = {}) {
         }
     }
 
-    async function load({id, model, sessionOptions, signal, timeoutMs} = {}) {
+    async function load({id, model, sessionOptions, executionPreference, executionTarget, signal, timeoutMs} = {}) {
         const currentConnection = connection;
-        const result = await invoke('onnx.load', {id, model, sessionOptions}, {signal, timeoutMs});
+        const result = await invoke(
+            'onnx.load',
+            {id, model, sessionOptions, executionPreference, executionTarget},
+            {signal, timeoutMs}
+        );
         currentConnection.controller.signal.throwIfAborted();
         return result;
     }

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/browser-runtime/core/contracts.mjs

@@ -32,6 +32,16 @@ export const CORE_METHOD_CONTRACTS={
     'preferences.set':{input:'{key,value}',output:'{key,value}'},
     'preferences.setMany':{input:'{entries}',output:'preference-batch-result'},
     'preferences.delete':{input:'{key}',output:'{key,deleted}'},
+    'localai.devices': {
+        input: '{refresh?}',
+        output: '{platform,state,devices,issues}',
+        meaning: 'Physical host inventory, independent of model startup. Presence does not establish engine support or observed execution.'
+    },
+    'localai.resolveTarget': {
+        input: '{executionTarget:{deviceId}|null,refresh?}',
+        output: '{requestedTarget,resolvedDevice,resolution,reason}',
+        meaning: 'Resolve a saved physical identity. Explicit null selects engine-owned automatic resolution; it does not claim a configured or observed device.'
+    },
     'window.setTheme': {
         input: '{backgroundColor?,textColor?}: null reset or {red,green,blue,alpha}',
         output: '{platform,supported,applied,unsupported}',

package/docs/publishing.md

@@ -53,6 +53,22 @@ and reports npm's response. It tolerates npm's publish-time scanning. If
 scanning or manual review remains pending, the workflow reports that state and
 a rerun safely resumes without republishing the version.
 
+Registry verification requires both the selected version/channel metadata and
+an ordinary complete GET of that exact version's published `dist.tarball` URL.
+Metadata visibility alone is not downloadable-package delivery. The verifier
+reads exact-version metadata, follows its tarball URL, and consumes the full
+successful response before reporting completion. Missing metadata, an HTTP
+failure, or an interrupted body remains pending within the existing bounded
+retry window; the remaining window also bounds the metadata/tarball requests.
+The existing npm metadata subprocesses retain their current behavior. If they
+consume the window, including a zero-wait invocation, the verifier reports
+pending without starting a new download observation.
+It records the actual failure and exits unsuccessfully if availability does not
+arrive. It does not save a second artifact, repack, republish, alter registry
+tags, add cache-bypass parameters, or impose a content-size or hash comparison.
+Requester notices follow successful version/channel and download observation;
+consumer installation and application verification remain separately owned.
+
 The public `0.3.2` release is fixed to package-source commit
 `445bd2d982f12e6ef8dd2b615c70512000cc5224`, selected Check run
 `33264677687`, and publication/registry run `33264829711`. Its numeric Git tag
@@ -77,9 +93,10 @@ The npm package already has its trusted-publishing relationship. Each later
 release therefore follows the same direct selected-artifact path: push the
 intended `main` source, manually run Check for that exact revision, review the
 resulting package inventory and legal notices, then manually dispatch
-publication with that Check run and artifact. Confirm the selected version and
-dist-tag after publication. Never rebuild or repack the artifact under
-publication authority, and never substitute a different source revision.
+publication with that Check run and artifact. Confirm the selected version,
+dist-tag, and complete published tarball availability after publication. Never
+rebuild or repack the artifact under publication authority, and never substitute
+a different source revision.
 
 Generated app CI uses `npm ci --ignore-scripts`, so its lock must exist and its
 dependency source must be reachable by the runner. External application CI uses

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/execution-devices.md

@@ -0,0 +1,157 @@
+# Physical execution devices
+
+The local-AI Core host exposes physical device discovery independently of model
+installation, loading and inference. A device being present does not establish
+that a particular engine can use it. The engine resolves that second question
+when the application explicitly loads its selected model.
+
+## List devices without loading a model
+
+Use the application's existing Core client:
+
+```js
+const catalog = await client.invoke('localai.devices', {refresh: false}, {signal});
+console.log(catalog.devices);
+console.log(catalog.issues);
+```
+
+The inventory has `{platform, state, devices, issues}`. `platform` uses Node's
+platform name. `state` is `ready`, `partial` or `unavailable`. Incomplete or failed
+discovery is reported in `issues`; it is not evidence that the machine has no
+devices. This initial discovery implementation uses Windows host APIs. Other
+platforms report this capability as unavailable while retaining their existing
+AI runtime behavior.
+
+Each device has the following fields:
+
+| Field | Meaning |
+| --- | --- |
+| `deviceId` | Stable host-local selection key, or `null` when identity could not be established. |
+| `identitySource` | `windows-pnp-instance`, `host-cpu`, or `null`. |
+| `kind` | `cpu`, `gpu` or `npu`. |
+| `name` | Complete reported display name. Names are not selection identities. |
+| `present` | Whether the queried device is present. |
+| `isHardware`, `isIntegrated` | Reported hardware facts, or `null` when unavailable. |
+| `dedicatedMemoryMiB` | Reported dedicated capacity, or `null`; used only for supported automatic GPU selection. |
+| `addresses` | Observed adapter addresses described below. These are not persistent selection keys. |
+| `processors` | Actual processor records for the aggregate CPU option; an empty array for GPU/NPU records. |
+
+GPU and NPU identities are actual, uniquely correlated Windows PnP instance IDs.
+An adapter whose stable identity cannot be established remains in the inventory
+with `deviceId: null` and a corresponding issue. The SDK does not invent a key
+from a name, enumeration order, hardware model number or adapter LUID.
+
+The CPU choice uses `deviceId: 'cpu'` and `identitySource: 'host-cpu'`. It selects
+the whole-host CPU execution target, without claiming socket or core affinity.
+Its `processors` entries contain `{deviceId, name, socketDesignation, cores,
+logicalProcessors}`; unavailable optional facts are `null`.
+
+`addresses` contains:
+
+```js
+{
+  adapterLuid: {highPart, lowPart}, // or null
+  pci: {bus, device, function: pciFunction}, // or null
+  dxgiAdapterIndex // or null
+}
+```
+
+The DXGI index is the actual `EnumAdapters` index joined to the adapter's LUID.
+It is never inferred from DXCore or PnP enumeration order. It supplies a possible
+DirectML address, not proof of provider availability or successful execution.
+No CUDA ordinal is inferred from these Windows addresses.
+
+An issue contains `{source, code, message, deviceId}`. `source` identifies `cpu`,
+`gpu`, `npu`, `identity` or `dxgi`; `deviceId` is `null` when no stable identity
+was established. Keep the complete diagnostic available to developers rather
+than substituting an empty inventory.
+
+## Resolve a saved selection
+
+Store the selected physical ID with the application's existing preferences,
+keyed by provider and model. The SDK introduces no new preference store and
+does not change the six-slot model preference tuple.
+
+```js
+const resolution = await client.invoke('localai.resolveTarget', {
+  executionTarget: {deviceId: savedDeviceId}
+}, {signal});
+```
+
+The result contains `{requestedTarget, resolvedDevice, resolution, reason}`:
+
+- `matched`: the complete device record was found. Engine support is still a
+  separate question.
+- `unavailable` with `device-not-present`: complete relevant discovery did not
+  find that saved identity. Preserve the saved selection so the application can
+  show that it is currently unavailable.
+- `unsupported` with `inventory-unavailable` or `identity-unresolved`: discovery
+  cannot establish the requested identity. Do not describe it as an absent device.
+- `automatic` with `engine-default-required`: an explicit `executionTarget: null`
+  asks the selected engine to choose at its activation boundary. The physical
+  resolver returns `resolvedDevice: null` because it cannot establish the
+  engine's routing capabilities.
+
+Calling the resolver does not load a model, change preferences or replace an
+existing activation. A model load that omits `executionTarget` retains that
+API's existing constructor, session-option and default behavior. Explicit
+`null` selects automatic resolution for the new activation; it does not erase
+or relabel a running session.
+
+## Engine configuration and execution evidence
+
+The physical-target integration described here applies to native ONNX and
+native Laya through Core. Listing host devices does not add physical-device
+selection to browser WebGPU/Wllama or to the separate native llama.cpp, image
+and Whisper owners. Their existing backend options remain unchanged. A browser
+uses the existing Core connection for this inventory; the catalog does not
+create a native connection or replace a browser provider.
+
+An engine receives the saved selection as `executionTarget: {deviceId}`. It
+owns provider availability, the physical-to-provider address mapping and the
+actual session configuration. Its public state distinguishes the requested
+target, physical resolution, configured target and observed execution. A
+successful session configuration alone is not evidence that every operation ran
+on a GPU or NPU.
+
+Automatic selection can prefer the hardware GPU with the highest reported
+dedicated capacity among supported targets with established routing. An
+integrated GPU remains eligible when it meets those same conditions. An unavailable saved
+target is not silently replaced by another device or a cloud route. See
+[native ONNX](local-ai.md#native-onnx-sessions) and [native decisions](native-decisions.md)
+for the selected engine's load, replacement, cancellation and status contracts.
+
+## Catalog and Core ownership
+
+SDK development local-AI composition and generated native composition with
+`localAI` selected register one lazy catalog and its independent
+`execution-devices` service. An empty runtime selection still permits device
+discovery. Hosts without local-AI composition retain their existing service
+selection. A manually composed Core can register the service explicitly:
+
+```js
+import {createExecutionDeviceCatalog} from 'arcane-os/local-ai/execution-devices';
+import {createExecutionDeviceService} from 'arcane-os/core/execution-devices';
+import {createLocalAIService} from 'arcane-os/core/local-ai';
+
+const executionDevices = createExecutionDeviceCatalog({signal});
+const services = [
+  createExecutionDeviceService({catalog: executionDevices}),
+  createLocalAIService(localAI, {appRoot, runtimes, signal, executionDevices})
+];
+```
+
+Pass these definitions to the existing Core host. The independent service owns
+catalog disposal. The local-AI engine borrows the same catalog; it does not
+dispose a supplied owner or create another discovery process per model.
+
+For direct Node use, `createExecutionDeviceCatalog({signal})` returns
+`devices({refresh, signal})`, `resolveTarget({executionTarget, refresh, signal})`
+and `dispose()`. The direct caller owns disposal. Construction performs no
+discovery I/O. Calls reuse/coalesce the host's discovery; `refresh: true` requests
+an explicit new observation. There is no background polling. Closing the owner
+releases its discovery work and native query resources.
+
+The catalog queries installed operating-system facilities. It does not install
+drivers, download models, alter system policy or introduce a hardware admission
+rule. A host capability failure remains an honest unavailable/partial result.