arcane-os 0.4.2 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.5.1
+
+- Separated the TWiN Cloud LLM access key from the legacy OpenAI speech
+  credential so neither provider's key is sent to the other's endpoint while
+  retaining the established `ai.license` alias for TWiN Cloud chat.
+
+## 0.5.0
+
+- Added bounded parallel Browser-WASM model downloads across split GGUF
+  members and resumable HTTP Range parts while preserving descriptor order and
+  the configured transfer limit.
+- Added retry pickup for completed shards and Range parts, with transparent
+  fallback to one full fetch when a source does not support usable ranges.
+- Added determinate aggregate download progress with transferred and remaining
+  data, live speed, approximate time remaining, active transfers, and transfer
+  mode.
+- Reused complete same-model legacy cache entries in preference to incomplete
+  replacements and removed redundant legacy files and completed fragments when
+  cleanup succeeds.
+- Replaced the default remote LLM destination and model with TWiN Cloud at the
+  OpenAI-compatible DigitalOcean inference endpoint, added the TWiN access-key
+  configuration surface, and retained the prior route and credential names as
+  compatibility aliases.
+
 ## 0.4.2
 
 - Added transparent Browser-WASM model loading status across cache checks,

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.4.2` SDK contract. Applications pin one exact npm
+This checkout defines the `0.5.1` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -79,6 +79,20 @@ Arcane OS must consume the same locked SDK projection as other applications;
 any remaining OS-side duplicate is legacy consumer migration state, not source
 authority.
 
+## TWiN Cloud
+
+TWiN Cloud is the SDK's default remote language-model service. It sends
+OpenAI-compatible chat-completion requests to
+`https://inference.do-ai.run/v1/chat/completions` with model
+`openai-gpt-oss-120b`. Supply the bearer credential through `ai.twinKey` or
+`globalThis.arcane.config.twinCloud.accessKey`. The established `ai.license`
+property and internal `OPENAI` route identifier remain compatibility aliases;
+applications should present the service and credential as **TWiN Cloud** and
+**TWiN access key**. The TWiN key is used only for remote LLM chat. Existing
+OpenAI speech routes remain separate and read only their legacy
+`globalThis.arcane.config.openAI.apiKey`; the SDK never sends a TWiN key to
+those speech endpoints.
+
 ## Browser-local AI
 
 `arcane-os/ai/browser-wasm` provides the shared Wllama LLM provider. The app
@@ -96,11 +110,36 @@ const source=createBrowserModelSource({
 });
 ```
 
-Model members require only their names and URLs. The ordinary path does not
-count, limit, hash, or identify model content by its byte representation.
+Model members require only their names and URLs. A member may also declare a
+positive safe-integer `bytes` value so the application can present determinate
+progress and the transport can plan parallel HTTP ranges. An unusable value is
+treated as unavailable and never blocks the ordinary download. That value is observational
+transfer metadata: it never validates, admits, identifies, or decides cache
+reuse for model content. During a cache miss, the store reports live aggregate
+`loadedBytes`, `totalBytes`, `remainingBytes`, `bytesPerSecond`, `etaSeconds`,
+`activeTransfers`, `transferLimit`, and `transferMode` alongside the existing
+completed-file counts. Chunk-driven updates are coalesced on a 250 ms cadence;
+transfer-plan, active-worker, and completion boundaries publish immediately.
 Optional hardening is inactive unless the caller explicitly selects
-`secure:true`. The DBOPFS store processes all members in order and commits its
-completion record last. Capability reports evaluate each
+`secure:true`. The DBOPFS store downloads ordered members with one bounded
+parallel transfer pool and returns them in descriptor order. Completed shards
+survive an interrupted attempt and only missing shard or Range-part work is
+fetched on retry. A
+monolithic file uses up to `downloadConcurrency` active workers (four by
+default) over up to 16 deterministic, resumable HTTP range parts when the server
+confirms `206` responses and the total comes from `Content-Range` or, when that
+header is not exposed, optional declared `bytes`.
+When a followed redirect turns the first Range probe into `200`, the SDK probes
+the final URL directly before reusing that original response as the single-fetch
+fallback. Completed range parts survive restart and are presented to Wllama as
+one logical model. Split members use the same Range negotiation with one active
+Range worker per member, so completed parts within a shard can also resume
+without multiplying the configured transfer bound. A probe without an
+observable or declared total falls back to one full fetch. Once a complete
+whole file or Range set is available, the store removes superseded fragments
+and the exact legacy duplicate for that model when DBOPFS deletion succeeds;
+cleanup failure is warned without hiding the usable model.
+Capability reports evaluate each
 app-supplied model as `compatible`, `incompatible`, or `unknown`; the app can
 render that result without the SDK inventing or filtering its catalog.
 
@@ -126,7 +165,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.4.2 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.5.1 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run check
@@ -137,7 +176,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.4.2
+npm install --save-dev --save-exact arcane-os@0.5.1
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -153,7 +192,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.4.2` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.5.1` 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`,
@@ -174,7 +213,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.4.2.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.5.1.tgz
 npm run check
 npm ci
 ```
@@ -184,7 +223,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.4.2` registry package and
+the local declaration with the exact `arcane-os@0.5.1` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -322,7 +361,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.4.2` exposes one browser target and five explicitly paired
+Version `0.5.1` 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