arcane-os 0.7.3 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.8.0
+
+- Add `removeBrowserSpeechModelCache()` to remove an explicitly retired Hugging
+  Face speech model from the current browser origin's upstream cache. Preserve
+  other models, voices, runtimes, DBOPFS artifacts, and preferences; report each
+  completed removal and surface cancellation or partial failure.
+- Keep model retirement policy in consuming applications. The operation starts
+  no model download or inference and leaves NPU, GPU, and CPU selection unchanged.
+
 ## 0.7.3
 
 - Correct public development serving for OPFS/DBOPFS and other browser APIs

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.7.3` SDK contract. Applications pin one exact npm
+This checkout defines the `0.8.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -35,7 +35,7 @@ Create one browser application, install its pinned SDK, and start its source
 server:
 
 ```bash
-npx arcane-os@0.7.3 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.8.0 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 npm run dev
@@ -386,7 +386,7 @@ uses the same controller for automatic memory extraction.
 Create a new repository-shaped Arcane application with the exact stable SDK:
 
 ```bash
-npx arcane-os@0.7.3 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.8.0 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run dev
@@ -396,7 +396,7 @@ To enroll an existing repository, install the exact SDK and initialize only
 missing Arcane files:
 
 ```bash
-npm install --save-dev --save-exact arcane-os@0.7.3
+npm install --save-dev --save-exact arcane-os@0.8.0
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -412,7 +412,7 @@ npm exec -- arcane-os targets
 No global SDK install or standalone Arcane CLI is required. The application
 repository's exact npm dependency and lockfile own the CLI and toolchain version.
 
-Use `npx arcane-os@0.7.3` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.8.0` for the initial bootstrap because it names this npm
 package explicitly; bare `npx arcane` outside an installed project could resolve
 a different package. Both installed commands invoke the same headless toolchain.
 Project-local npm scripts use the SDK pinned by that app's `package-lock.json`,
@@ -432,7 +432,7 @@ node ./bin/arcane.mjs new local-app --path ../local-app --target portable --git
 
 # From the generated app repository
 cd ../local-app
-npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.7.3.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.8.0.tgz
 npm ci
 ```
 
@@ -441,7 +441,7 @@ same location. The lockfile retains the selected package dependency while
 Arcane uses the installed package name and version. Local directory `file:` dependencies are not
 accepted because npm may install them as links; use a packed `.tgz`. A GitHub
 runner also needs that tarball at the locked path. After publication, replace
-the local declaration with the exact `arcane-os@0.7.3` registry package and
+the local declaration with the exact `arcane-os@0.8.0` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -580,7 +580,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.7.3` exposes one browser target and five explicitly paired
+Version `0.8.0` exposes one browser target and five explicitly paired
 native development targets: a non-runnable portable directory, a
 Windows x64 unsigned-local-test EXE bundle, Linux x64 and Linux ARM64
 unsigned-local-test DEBs, and an Android development-signed APK. The

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

@@ -2331,6 +2331,53 @@ export function createDbopfsSpeechArtifactStore({
   return store;
 }
 
+export async function removeBrowserSpeechModelCache(
+    {repository, cacheStorage = globalThis.caches, signal} = {}
+) {
+    const selectedRepository = requiredText(repository, 'repository');
+    const removed = [];
+    const result = {repository: selectedRepository, removed};
+    const modelPath = `/${selectedRepository.split('/').map(encodeURIComponent).join('/')}/resolve/`;
+
+    try {
+        throwIfAborted(signal);
+        if (!is.function(cacheStorage?.has) || !is.function(cacheStorage?.open)) {
+            throw speechError(
+                'ARCANE_AI_STORAGE_UNAVAILABLE',
+                'Browser model cache storage is unavailable.',
+                undefined,
+                'browser-speech-model-cache-unavailable'
+            );
+        }
+        const cached = await cacheStorage.has('transformers-cache');
+        throwIfAborted(signal);
+        if (!cached) return result;
+        const cache = await cacheStorage.open('transformers-cache');
+        const requests = await cache.keys();
+        for (const request of requests) {
+            throwIfAborted(signal);
+            const url = new URL(request.url);
+            if (url.origin !== 'https://huggingface.co' || !url.pathname.startsWith(modelPath)) {
+                continue;
+            }
+            if (await cache.delete(request)) removed.push(request.url);
+        }
+        throwIfAborted(signal);
+        return result;
+    } catch (cause) {
+        const error = cause?.name === 'AbortError' || isBrowserSpeechArtifactError(cause)
+            ? cause
+            : speechError(
+                'ARCANE_AI_STORAGE_DELETE_FAILED',
+                'Unable to remove the selected browser speech model download.',
+                cause,
+                'browser-speech-model-cache-delete-rejected'
+            );
+        error.removed = removed;
+        throw error;
+    }
+}
+
 export function isBrowserSpeechAuthority(value) {
   return AUTHORITIES.has(value);
 }

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

@@ -4,6 +4,7 @@ export {
   createBrowserSpeechArtifactGraph,
   createBrowserSpeechAuthority,
   createDbopfsSpeechArtifactStore,
+  removeBrowserSpeechModelCache,
 } from "./browser-speech-artifacts.mjs";
 export {
   createBrowserKokoroProvider,

package/docs/architecture.md

@@ -289,7 +289,7 @@ paths are withheld from the native provider. The provider copies the complete
 selected release rather than accepting an unrelated source path. Verification
 is a separate explicit operation for a selected release artifact.
 
-The SDK `0.7.3` runtime requires Arcane `0.8.12` or newer. Compatibility
+The SDK `0.8.0` runtime requires Arcane `0.8.12` or newer. Compatibility
 is contractual rather than exact-version pinning: the prepared Core must meet
 the highest minimum declared by the runtime, selected app, and bundled app
 dependencies; keep each app's Arcane protocol generation; and provide every

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

@@ -1027,6 +1027,33 @@ forward a security payload to the Worker and performs no security work. Passing
 `{secure:true}` does not activate hardening. Any future hardening stage requires
 a separate user review and an explicit implementation change before it may execute.
 
+## `removeBrowserSpeechModelCache()`
+
+```javascript
+const removal = await removeBrowserSpeechModelCache(
+    {repository: 'Xenova/whisper-small', signal}
+);
+```
+
+Exported by `arcane-os/ai/browser-speech`. This explicit operation removes all
+cached revisions of the exact selected Hugging Face model from the current
+origin's existing `transformers-cache`. It returns `{repository,removed}`,
+where `removed` contains the complete URLs actually deleted. An absent cache or
+model returns an empty list. Other models, runtime files, the Kokoro voice
+cache, DBOPFS files, and preferences remain untouched. No model is loaded or
+downloaded and no inference is started.
+
+The caller owns model retirement policy and must stop using the retired model
+before removal so a live provider cannot download it again. This operation is
+separate from `store.remove(authority)`, which removes declared DBOPFS files.
+`cacheStorage` may explicitly supply a CacheStorage implementation; it defaults
+to `globalThis.caches`. Missing storage rejects with
+`ARCANE_AI_STORAGE_UNAVAILABLE`; cache failures reject with
+`ARCANE_AI_STORAGE_DELETE_FAILED`. An aborted `signal` stops further removals
+with `AbortError`. Deletions already completed are retained in `error.removed`;
+removal is repeatable and does not claim transactional rollback. The operation
+enumerates one cache once and awaits each matching deletion in order.
+
 ## Ordinary module routing
 
 Artifact-graph preparation reads each stored JavaScript module, discovers

package/docs/reference/sdk-api.md

@@ -125,6 +125,7 @@ browser map are cataloged separately in [Runtime modules](runtime-modules.md).
 | `createCanonicalUstarHeader()` | function | `arcane-os` | Packaging and release bundles | Node |
 | `createDbopfsModelStore()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser with a ready DBOPFS instance and OPFS |
 | `createDbopfsSpeechArtifactStore()` | function | `arcane-os/ai/browser-speech` | Browser speech providers | Browser with ready DBOPFS, Web Locks, Fetch, File/Blob, and object URLs |
+| `removeBrowserSpeechModelCache()` | function | `arcane-os/ai/browser-speech` | Browser speech providers | Browser CacheStorage; explicit removal of one selected upstream model |
 | `createNativeBuildPlan()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
 | `createNativeTargetAdapter()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
 | `createReporter()` | function | `arcane-os` | Events, processes, and testing | Node |
@@ -6396,6 +6397,24 @@ const authority = createBrowserSpeechAuthority({
 });
 ```
 
+## removeBrowserSpeechModelCache()
+
+```text
+removeBrowserSpeechModelCache({ repository, cacheStorage=globalThis.caches, signal }={})
+```
+
+Removes cached Hugging Face resources for the exact selected repository, across
+all revisions, from the current origin's existing `transformers-cache`.
+Returns `{repository,removed}`, including each complete URL actually deleted.
+An absent model or cache returns an empty list. The caller must stop using the
+retired model first; this operation does not unload providers or start inference.
+Other models, runtime resources, voice caches, declared DBOPFS artifacts, and
+preferences are preserved. Use `store.remove(authority)` separately for declared
+DBOPFS artifacts. Missing storage and cache failures surface
+`ARCANE_AI_STORAGE_UNAVAILABLE` and `ARCANE_AI_STORAGE_DELETE_FAILED`.
+Cancellation stops subsequent deletions with `AbortError`; `error.removed`
+retains the complete list of deletions already completed.
+
 ## createDbopfsSpeechArtifactStore()
 
 ### Overview

package/package.json

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