arcane-os 0.5.7 → 0.5.9

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.5.9
+
+- Renamed the built-in TWiN Cloud provider and default-model preference sentinel
+  to `TWIN`. Applications must explicitly update saved `OPENAI` LLM selections;
+  the SDK does not alias the old identifier or rewrite persisted preferences.
+  Real upstream model names, wire behavior, and on-device speech remain intact.
+- Restored immediate streamed-speech synthesis admission with bounded,
+  provider-declared TTS concurrency and FIFO overflow while retaining exact
+  chunk text, cancellation, lifecycle ownership, and original playback order.
+- Added a bounded Kokoro Worker/model-session pool with GPU-first WebGPU loading,
+  explicit WebGPU or WASM selection, and an honest automatic WASM fallback that
+  preserves the caller-selected model, dtype, and voice.
+- Scheduled each contiguous ready audio buffer directly after its predecessor
+  on the `AudioContext` clock, removing callback-added stitching gaps without
+  trimming, crossfading, resampling, merging, or rewriting speech content.
+
+## 0.5.8
+
+- Added provider-neutral `reasoningEffort` to `AI.fetchRequest()` and
+  `AI.streamRequest()`, accepting `none`, `low`, `medium`, `high`, or
+  `max`. TWiN Cloud forwards an explicit value as `reasoning_effort`, omits
+  the field when unspecified, and preserves explicit
+  `openai-gpt-oss-120b` or `openai-gpt-oss-20b` model selection with the
+  existing streaming and structural-tool behavior.
+
 ## 0.5.7
 
 - Added `PersistentAIChatSession.open()` for model-authored conversation

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.5.7` SDK contract. Applications pin one exact npm
+This checkout defines the `0.5.9` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -70,28 +70,37 @@ is coordinated separately and cannot become a second source authority.
 
 The source-authority cutover is complete. `runtime/arcane/` is authored here,
 and applications copy the complete portable inventory selected by the package.
-The old Arcane OS-to-SDK synchronization direction is retired; it cannot
-overwrite SDK-canonical source.
-
-`tools/runtime-source.json` declares the SDK authority and retains the prior
-Arcane OS commit only as migration history.
 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.
+an OS-side duplicate is consumer projection state, not source authority. Git
+history records the completed source-authority migration; the current tree has
+no OS-to-SDK synchronization command or migration-only runtime-source record.
 
 ## TWiN Cloud
 
-TWiN Cloud is the SDK's default remote language-model service. It sends
-OpenAI-compatible chat-completion requests to
+TWiN Cloud is the SDK's default remote language-model service, identified by
+`TWIN`. It sends 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. Audio stays
+property remains available. Applications should present the service and
+credential as **TWiN Cloud** and **TWiN access key**. The TWiN key is used only
+for remote LLM chat. Audio stays
 on device: Whisper (`LOCAL_SPEACH` / `whisper-small`) owns transcription and
 Kokoro (`LOCAL_SPEACH` / `kokoro`) owns speech synthesis. Neither audio route
-uses the TWiN key, and no OpenAI audio key is required.
+uses the TWiN key, and neither requires a cloud audio key.
+
+The built-in provider and default-model preference sentinel are both `TWIN`.
+Applications upgrading saved `OPENAI` LLM selections must explicitly update
+those app-owned settings to `TWIN`. The SDK provides no built-in `OPENAI` alias
+and does not rewrite saved preferences. Actual upstream model identifiers remain
+unchanged.
+
+`fetchRequest()` and `streamRequest()` accept the provider-neutral
+`reasoningEffort` option with `none`, `low`, `medium`, `high`, or `max`. TWiN
+Cloud maps it to DigitalOcean Serverless Inference `reasoning_effort`; omitting
+it preserves the provider default. TWiN Cloud defaults to
+`openai-gpt-oss-120b`, and applications may explicitly select
+`openai-gpt-oss-20b` without changing streaming or structural-tool behavior.
 
 ## Browser-local AI
 
@@ -129,9 +138,6 @@ workers (four by default) over deterministic, resumable HTTP range parts of
 roughly 4 MB each, up to 4,096 parts, when the server confirms `206` responses
 and the total comes from `Content-Range` or, when that header is not exposed,
 optional declared `bytes`.
-An incomplete cache written by 0.5.3 keeps its completed coarse parts and
-subdivides only the missing intervals into the smaller current parts, so an SDK
-update preserves existing progress while reducing later refresh loss.
 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
@@ -140,8 +146,8 @@ 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.
+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.
@@ -151,7 +157,10 @@ provider factories. The package contains the plain-JavaScript provider and
 Worker machinery, not speech runtimes, models, voices, or a CDN default. An app
 must supply each runtime/model selection explicitly. Speech roles
 load, cancel, unload, fail, and recover independently, so speech failure never
-silently falls back or prevents text chat.
+silently falls back or prevents text chat. Kokoro defaults to a two-slot Worker
+and model-session pool: it selects WebGPU when the browser can load the complete
+pool and otherwise recreates that pool on WASM. Apps may select `webgpu` or
+`wasm` explicitly and may set the bounded TTS capacity from one through four.
 
 Applications that need faster spoken-response onset can configure the shared
 TTS stream without taking over synthesis or playback:
@@ -165,7 +174,10 @@ ai.configureTTSSegmentation({
 
 The compatibility default remains sentence punctuation with no word cadence.
 The configured stream preserves every character and punctuation mark, chooses
-the earliest complete boundary, and keeps synthesis and playback sequential.
+the earliest complete boundary, begins synthesis as each segment becomes
+available, and plays the completed audio in exact segment order. Ready adjacent
+buffers are scheduled consecutively on the browser audio clock rather than
+waiting for an `ended` callback before the next start.
 Any-punctuation mode recognizes boundaries without requiring whitespace while
 keeping apostrophes, commas, and hyphens that join Unicode letters or numbers
 inside the same segment.
@@ -192,7 +204,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.5.7 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.5.9 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run check
@@ -203,7 +215,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.5.7
+npm install --save-dev --save-exact arcane-os@0.5.9
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -219,7 +231,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.5.7` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.5.9` 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`,
@@ -240,7 +252,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.5.7.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.5.9.tgz
 npm run check
 npm ci
 ```
@@ -250,7 +262,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.5.7` registry package and
+the local declaration with the exact `arcane-os@0.5.9` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -388,7 +400,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.5.7` exposes one browser target and five explicitly paired
+Version `0.5.9` 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