arcane-os 0.93.0 → 0.94.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.94.0
+
+- Recover all TWiN HTTP 429 quota responses through the shared chat/System One
+  transport. Honor Retry-After or exponential backoff, share a transient
+  same-endpoint/credential cooldown, and pace concurrent recovery dispatches.
+  Fetch rejection, 429 and 529 share three retries; cancellation stops waits.
+  Preserve exact requests and complete terminal errors, including provider
+  status_code and nested error records. Do not replay 400/413 errors, consumed
+  streams, callbacks, or image submissions.
+- Include the completed native Kokoro synthesis capability: retained voices,
+  explicit model preparation, owned cancellation and audio output through the
+  shared native speech contract. Reuse its retained compatible runtime and
+  source archives alongside the existing native host, Whisper and ONNX assets.
+  Package inclusion is distinct from application or native-runtime acceptance.
+
 ## 0.93.0
 
 - Add native desktop notification status, submission, state and removal through

package/README.md

@@ -25,7 +25,7 @@ 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.93.0` SDK contract. Development applications declare
+This checkout defines the `0.94.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;

package/browser-runtime/ai/twin-cloud.mjs

@@ -4,6 +4,8 @@ import {arcaneLogging} from '../logging.mjs';
 const is = new Is(false);
 const twinChatURL = 'https://inference.do-ai.run/v1/chat/completions';
 const twinSystemOneURL = 'https://inference.do-ai.run/v1/systemone';
+const activeHTTPRequests = new Map();
+const httpRetryDelayMs = 3000;
 
 /** A stateless TWiN request; browser AI shares the HTTP and format owners below. */
 export async function fetchRequest({
@@ -450,10 +452,24 @@ export function openAIResponseFormat(format){
 /** Shared with browser streaming; consume no successful body at this boundary. */
 export async function fetchHTTPResponse(url, options, {onRetry = null} = {}) {
     const {signal} = options;
-    const retryDelayMs = 3000;
     const maxRecoveryRetries = 3;
-    let recoveryRetries = 0;
     let attempt = 0;
+    let retry = null;
+    const destination = url?.url ?? String(url);
+    const headers = new Headers(options.headers ?? url?.headers);
+    const requestOptions = {...options, headers};
+    const authorization = headers.get('authorization') ?? '';
+    let accounts = activeHTTPRequests.get(destination);
+    if (!accounts) {
+        accounts = new Map();
+        activeHTTPRequests.set(destination, accounts);
+    }
+    let pacing = accounts.get(authorization);
+    if (!pacing) {
+        pacing = {active: 0, rateLimited: false, resumeAt: 0, nextDispatchAt: 0, error: null};
+        accounts.set(authorization, pacing);
+    }
+    pacing.active += 1;
     try {
         while (true) {
             if (signal?.aborted) {
@@ -462,7 +478,7 @@ export async function fetchHTTPResponse(url, options, {onRetry = null} = {}) {
             let response;
             let error;
             try {
-                response = await fetch(url, options);
+                response = await dispatchHTTPRequest(url, requestOptions, pacing, onRetry, retry, attempt);
             } catch (fetchError) {
                 if (isAIRequestAbort(fetchError, signal)) {
                     throw normalizeAIRequestAbort(fetchError);
@@ -483,7 +499,7 @@ export async function fetchHTTPResponse(url, options, {onRetry = null} = {}) {
                         ? await response.json()
                         : await response.text();
                 } catch (bodyError) {
-                    if (status !== 529 || isAIRequestAbort(bodyError, signal)) {
+                    if ((status !== 429 && status !== 529) || isAIRequestAbort(bodyError, signal)) {
                         throw bodyError;
                     }
                     error = bodyError;
@@ -495,61 +511,108 @@ export async function fetchHTTPResponse(url, options, {onRetry = null} = {}) {
             const message = is.string(error)
                 ? error
                 : error?.error?.message ?? error?.message;
-            const overload = status === 429
-                && is.string(message)
-                && message.toLowerCase().includes('overload');
-            if (!overload) {
-                if ((status !== null && status !== 529)
-                    || recoveryRetries >= maxRecoveryRetries) {
-                    throw error;
-                }
-                recoveryRetries += 1;
+            const retryDelayMs = status === 429
+                ? httpRateLimitDelay(response, httpRetryDelayMs * (2 ** Math.min(attempt, maxRecoveryRetries - 1)))
+                : httpRetryDelayMs;
+            if (status === 429) {
+                pacing.rateLimited = true;
+                pacing.resumeAt = Math.max(pacing.resumeAt, Date.now() + retryDelayMs);
+                pacing.error = error;
+            }
+            if ((status !== null && status !== 429 && status !== 529)
+                || attempt >= maxRecoveryRetries) {
+                throw error;
             }
             attempt += 1;
             arcaneLogging.warn(
                 `${message ?? 'AI request transport failed.'}\nRetrying in ${retryDelayMs / 1000} seconds`,
                 error
             );
-            observeRequestRetry(
-                onRetry,
-                {phase: 'waiting', attempt, delayMs: retryDelayMs, status, error}
-            );
-            await new Promise(
-                function waitForRequestRetry(resolve, reject) {
-                    function finishRetryDelay() {
-                        signal?.removeEventListener('abort', cancelRetryDelay);
-                        resolve();
-                    }
-                    function cancelRetryDelay() {
-                        clearTimeout(timer);
-                        signal.removeEventListener('abort', cancelRetryDelay);
-                        reject(normalizeAIRequestAbort(signal.reason));
-                    }
-                    const timer = setTimeout(finishRetryDelay, retryDelayMs);
-                    signal?.addEventListener(
-                        'abort',
-                        cancelRetryDelay,
-                        {once: true}
-                    );
-                    if (signal?.aborted) {
-                        cancelRetryDelay();
-                    }
-                }
-            );
-            if (signal?.aborted) {
-                throw normalizeAIRequestAbort(signal.reason);
-            }
-            observeRequestRetry(
-                onRetry,
-                {phase: 'requesting', attempt, delayMs: retryDelayMs, status, error}
-            );
+            retry = {phase: 'waiting', attempt, delayMs: retryDelayMs, status, error};
+            observeRequestRetry(onRetry, retry);
+            await waitForHTTPDelay(retryDelayMs, signal);
         }
     } catch (error) {
         if (isAIRequestAbort(error, signal)) {
             throw normalizeAIRequestAbort(error);
         }
         throw error;
+    } finally {
+        pacing.active -= 1;
+        if (pacing.active === 0) {
+            // Retain neither credentials nor quota state beyond the active request group.
+            accounts.delete(authorization);
+            if (accounts.size === 0) {
+                activeHTTPRequests.delete(destination);
+            }
+        }
+    }
+}
+
+function httpRateLimitDelay(response, fallback) {
+    const value = response.headers.get('retry-after')?.trim();
+    if (!value) return fallback;
+    const seconds = Number(value);
+    if (is.finite(seconds)) {
+        return seconds >= 0 && is.finite(seconds * 1000) ? seconds * 1000 : fallback;
     }
+    // Accept HTTP weekday date forms, not an arbitrary numeric string interpreted as a date.
+    const date = /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun)/i.test(value) ? Date.parse(value) : NaN;
+    return is.finite(date) ? Math.max(0, date - Date.now()) : fallback;
+}
+
+async function dispatchHTTPRequest(url, options, pacing, onRetry, retry, attempt) {
+    const {signal} = options;
+    let observation = null;
+    // Only an observed quota response coordinates otherwise independent requests.
+    while (pacing.rateLimited) {
+        if (signal?.aborted) throw normalizeAIRequestAbort(signal.reason);
+        const delayMs = Math.max(pacing.resumeAt, pacing.nextDispatchAt) - Date.now();
+        if (delayMs <= 0) {
+            // Claim and initiate Fetch in this continuation, with no intervening asynchronous wait.
+            pacing.nextDispatchAt = Date.now() + httpRetryDelayMs;
+            break;
+        }
+        if (!retry && !observation) {
+            observation = {phase: 'waiting', attempt, delayMs, status: 429, error: pacing.error};
+            observeRequestRetry(onRetry, observation);
+        }
+        await waitForHTTPDelay(delayMs, signal);
+    }
+    if (observation && !signal?.aborted) {
+        observeRequestRetry(onRetry, {...observation, phase: 'requesting'});
+    }
+    if (retry) {
+        observeRequestRetry(onRetry, {...retry, phase: 'requesting'});
+    }
+    if (signal?.aborted) throw normalizeAIRequestAbort(signal.reason);
+    return fetch(url, options);
+}
+
+async function waitForHTTPDelay(delayMs, signal) {
+    let remaining = delayMs;
+    do {
+        if (signal?.aborted) throw normalizeAIRequestAbort(signal.reason);
+        // Only split at the host timer range; never shorten the provider's requested wait.
+        const milliseconds = Math.min(remaining, 2147483647);
+        await new Promise(
+            function waitForRequestRetry(resolve, reject) {
+                function finishRetryDelay() {
+                    signal?.removeEventListener('abort', cancelRetryDelay);
+                    resolve();
+                }
+                function cancelRetryDelay() {
+                    clearTimeout(timer);
+                    signal.removeEventListener('abort', cancelRetryDelay);
+                    reject(normalizeAIRequestAbort(signal.reason));
+                }
+                const timer = setTimeout(finishRetryDelay, milliseconds);
+                signal?.addEventListener('abort', cancelRetryDelay, {once: true});
+                if (signal?.aborted) cancelRetryDelay();
+            }
+        );
+        remaining -= milliseconds;
+    } while (remaining > 0);
 }
 
 function observeRequestRetry(onRetry, state) {

package/browser-runtime/core/client.mjs

@@ -598,6 +598,8 @@ export function createCoreFacade(client){
             remove:name=>invoke('environment.delete',{name})},
         mail:{send:request=>invoke('mail.send',request??{},{timeoutMs:450000})},
         speech:{status:()=>invoke('speech.status',{},{timeoutMs:10000}),
+            load:function loadSpeech(request,options){return invoke('speech.load',request??{},{timeoutMs:0,signal:options?.signal,onRequest:options?.onRequest});},
+            unload:function unloadSpeech(request,options){return invoke('speech.unload',request??{},{timeoutMs:0,signal:options?.signal,onRequest:options?.onRequest});},
             synthesize:(request,options)=>invoke('speech.synthesize',request??{},{timeoutMs:180000,signal:options?.signal}),
             transcribe:(request,options)=>invoke('speech.transcribe',request??{},{timeoutMs:180000,signal:options?.signal,onRequest:options?.onRequest})},
         localAI:{status:()=>invoke('localai.status',{},{timeoutMs:15000}),

package/docs/reference/ai/twin-cloud.md

@@ -94,17 +94,34 @@ The key is
 transport authentication, not part of either callback's message payload. Keep
 credentials out of application logging as well.
 
-Before a successful response is consumed, a rejected Fetch or HTTP `529` can
-retry up to three times, waiting `3000` milliseconds before each retry. These
-two failure types share that three-retry budget. HTTP `429` with a message
-containing `overload` (case-insensitive) retains its unlimited three-second
-retry behavior and does not consume that budget. Each attempt reuses the exact
-destination, Fetch options, serialized request, and signal. Other HTTP errors,
-successful-response decoding failures, and application callback failures do not
-retry. A known HTTP `529` also retries when reading or parsing its diagnostic
-body fails; `onRetry.error` retains that exact failure, which is thrown unchanged
-if recovery is exhausted. Diagnostic-body failures for other HTTP statuses do
-not retry. The last complete failure is thrown unchanged when recovery is exhausted.
+Before a successful response is consumed, rejected Fetch calls and HTTP `429`
+or `529` share a budget of three retries (four total attempts). Every `429`
+qualifies, including request-per-minute and token-per-minute quota responses;
+the error message does not select recovery. A readable `Retry-After` header
+supplies the `429` delay as seconds or an HTTP date. Otherwise the upcoming
+retry number selects a `3000`, `6000`, or `12000` millisecond delay. Rejected
+Fetch and `529` retain their `3000` millisecond delay. A provider's longer wait
+is preserved, split only at the host timer's range when necessary.
+
+After an observed `429`, overlapping requests through this module with the
+same exact endpoint and Authorization value share the latest cooldown and
+dispatch at least three seconds apart. A later quota response extends that
+cooldown, including a terminal quota response while sibling calls remain active;
+its fallback remains at most `12000` milliseconds. Different endpoints and credentials remain independent, and requests
+before any quota response remain concurrent. This is active-operation pacing,
+not a persistent global rate limiter: the module releases the group, including
+its credential key and error, when its last HTTP operation settles. It does not
+coordinate separate tabs, processes, or independently loaded module instances.
+
+Each attempt reuses the exact destination, Fetch option values, serialized request,
+and signal. Headers are normalized once through standard Fetch `Headers` and
+retained for retries, including when the caller supplied a one-shot iterable.
+Other HTTP errors (including `400` and `413`), successful-response
+decoding failures, and application callback failures do not retry. A known
+`429` or `529` also retries when reading its diagnostic body fails;
+`onRetry.error` retains that exact failure. The last complete error is thrown
+unchanged on exhaustion, preserving provider fields such as `status_code` and
+nested `error.type`/`error.message`. No error envelope is rebuilt or sanitized.
 Pass a fresh
 `AbortController`'s `signal` and call `abort()` to cancel. Cancellation during
 the request, response-body read, retry wait, or callback settlement prevents
@@ -114,12 +131,16 @@ A missing key uses `AI_PROVIDER_NOT_CONFIGURED`, a missing explicit model
 throws `TypeError`, and an unsupported `structuredOutput` input uses
 `AI_STRUCTURED_OUTPUT_INVALID`.
 
-Optional `onRetry({phase,attempt,delayMs,status,error})` observes each retry.
+Optional `onRetry({phase,attempt,delayMs,status,error})` observes recovery.
 `phase:'waiting'` arrives before the abortable delay; `phase:'requesting'`
 arrives immediately before the next Fetch. `attempt` is the one-based upcoming
-retry number across both retry policies, `delayMs` is `3000`, `status` is the
+retry number across the shared budget, `delayMs` is the selected wait, `status` is the
 HTTP status or `null` for a rejected Fetch, and `error` is the complete original
-failure value. This observer runs synchronously without awaiting its returned
+failure value. An initial request waiting behind an already observed quota
+reports `attempt:0`, `status:429`, and that complete quota error. Shared pacing
+can extend the actual wait beyond its initial observation; `requesting` is
+emitted only after that wait, immediately before dispatch. This observer runs
+synchronously without awaiting its returned
 promise. Synchronous throws and rejected promises are reported through the
 shared console logger and cannot change the request outcome or trigger another
 retry. `onRequest` still runs once per logical request. Retry observations stay

package/docs/reference/availability-and-normalization.md

@@ -99,7 +99,7 @@ where listed. See [native output and host requirements](core-native-packaging.md
 | Label speakers in caller-fed mono audio | [`arcane-os/diarization`, `arcane-os/core/diarization`](diarization.md) | **Node** with built helper, selected official NeMo libraries and Nemotron model; official CPU archives cover Windows x64 and Linux/macOS x64/arm64 | Independent retained streams, complete timed segments and optional probability frames. Generic labels are not personal identities or speech transcripts; cancellation and close observe native cleanup. Android needs host adaptation. |
 | Use local AI without coupling app code to Ollama HTTP | `Arcane.localAI`, `Arcane.ai`, or `/arcane/modules/Ollama.js` | Primarily **Native**; Android exposes a narrower admitted inference projection | Admission, errors, and managed-operation events are normalized. Direct Ollama response envelopes remain **Provider-native**. |
 | Use TWiN Cloud from the renderer profile | `/arcane/modules/AI.js` | **Cloud** from an allowed browser/native renderer | High-level chat behavior is normalized by the module. The TWiN access key authenticates remote LLM chat; raw provider diagnostics remain provider-specific. No automatic cloud fallback is inferred from local failure. |
-| Send one TWiN Cloud request with an explicit key and model | `fetchRequest` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch and a remote HTTPS provider | Keeps complete messages and returns the full parsed provider JSON. Rejected Fetch and HTTP 529 share three retries after 3000 ms; HTTP 429 overload retains unlimited three-second retries. Optional `onRetry` reports waiting/requesting phases without blocking recovery. Shared structured-output mapping and cancellation match browser TWiN transport. No browser profile, AI/user singleton, DBOPFS, or retained request history is created. |
+| Send one TWiN Cloud request with an explicit key and model | `fetchRequest` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch and a remote HTTPS provider | Keeps complete messages and returns the full parsed provider JSON. Rejected Fetch and all HTTP 429/529 share three retries. Quota recovery honors Retry-After or exponential delay; active same-endpoint/credential requests share cooldown and paced dispatch. Optional `onRetry` reports waiting/requesting without blocking recovery. Complete errors and cancellation match browser TWiN transport. No browser profile, AI/user singleton, DBOPFS, or retained request history is created. |
 | Evaluate caller-owned state and questions with TWiN System One | `fetchSystemOneRequest` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch and a remote HTTPS provider | Posts the explicit model and complete state/questions through the existing JSON transport. Returns the entire parsed provider result and shares its retry, diagnostic, and cancellation behavior. Model choice, question definitions, answer interpretation, and scoring policy stay with the caller; no conversation state is retained. |
 | Generate images from a complete caller-owned prompt | `generateImages` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch, Blob, and a remote HTTPS provider | Caller selects `fal-ai/flux/schnell` or `stable-diffusion-3.5-large`, credentials, and provider parameters. Returns every image as a Blob with media metadata in provider order; owns progress, job polling, and cancellation. Submission is not automatically replayed after an ambiguous failure. Display and storage stay application-owned. |
 | Use speech through one application helper | `/arcane/modules/AI.js` and `Arcane.speech` | **Browser** or **Native** | Whisper and Kokoro keep their on-device paths; explicitly selected Web Speech STT/TTS and TWiN Cloud TTS declare their non-local behavior. `prepareTTSPlayback` supports real audio and silent native descriptors; `fetchTTS` and durable `prepareTTS` require real audio. Provider choice, model, voice, and credentials stay application-owned. |

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

@@ -6,7 +6,7 @@
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 308,
+  "memberCount": 314,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
@@ -166,6 +166,90 @@
       "protocol": "arcane/1 service definition",
       "normalization": "Binding identity equals the named createNativeDecisionService export"
     },
+    {
+      "id": "local-ai-kokoro:createNativeKokoroRuntime",
+      "name": "createNativeKokoroRuntime",
+      "displayName": "createNativeKokoroRuntime()",
+      "kind": "function",
+      "signature": "createNativeKokoroRuntime({onnx,modelAssets,runtime,prepare,modelId='kokoro',model=KOKORO_MODEL,revision=KOKORO_REVISION,dtype='fp32',paths,assetProjectionId,resourcePaths,sessionOptions,executionPreference='gpu',executionTarget,signal,onEvent}={})",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "Composes the selected Kokoro FP32 graph with the host's existing ONNX/model-resource owners and a persistent native phonemization/Opus helper.",
+      "availability": "Node with matching prepared helper/data and ONNX resources; SDK helper archive for Windows x64, other hosts require a matching custom helper distribution",
+      "protocol": "Replaying kokoro.state, retained ONNX activation and complete ordered native speech requests",
+      "normalization": "Returns current/subscribe/load/synthesize/unload/close; construction performs no preparation or inference. Explicit load selects a DBOPFS projection or complete native resource paths; synthesis retains complete ordered input, selected US/GB voice and 24kHz mono WAV or Ogg Opus output. Active cancellation joins owned helper/session retirement and preserves surviving queued work on the same configured provider; ONNX native interruption may wait for the current call. No alternate model, voice or provider retry is introduced. See native-speech.md for exact activation, selection and result contracts."
+    },
+    {
+      "id": "local-ai-kokoro:default",
+      "name": "default",
+      "displayName": "createNativeKokoroRuntime default export",
+      "kind": "function",
+      "signature": "default as createNativeKokoroRuntime",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "Default binding for the same native Kokoro engine factory.",
+      "availability": "Node with matching prepared native resources",
+      "protocol": "Native Kokoro engine lifecycle",
+      "normalization": "Binding identity equals the named createNativeKokoroRuntime export"
+    },
+    {
+      "id": "local-ai-kokoro:KOKORO_MODEL",
+      "name": "KOKORO_MODEL",
+      "displayName": "KOKORO_MODEL",
+      "kind": "constant",
+      "signature": "const KOKORO_MODEL",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "Identifies the Kokoro model implemented by the native frontend.",
+      "availability": "Node",
+      "protocol": "Native model selection",
+      "normalization": "Value is onnx-community/Kokoro-82M-v1.0-ONNX; constructor selection preserves this model's FP32 graph and resource contract"
+    },
+    {
+      "id": "local-ai-kokoro:KOKORO_REVISION",
+      "name": "KOKORO_REVISION",
+      "displayName": "KOKORO_REVISION",
+      "kind": "constant",
+      "signature": "const KOKORO_REVISION",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "Identifies the selected upstream Kokoro model revision.",
+      "availability": "Node",
+      "protocol": "Native model resource selection",
+      "normalization": "Value is 1939ad2a8e416c0acfeecc08a694d14ef25f2231; graph, tokenizer and voice resources use this same revision"
+    },
+    {
+      "id": "local-ai-kokoro:KOKORO_SAMPLE_RATE",
+      "name": "KOKORO_SAMPLE_RATE",
+      "displayName": "KOKORO_SAMPLE_RATE",
+      "kind": "constant",
+      "signature": "const KOKORO_SAMPLE_RATE",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "Native Kokoro PCM synthesis rate in samples per second.",
+      "availability": "Node",
+      "protocol": "Audio format",
+      "normalization": "Value is 24000; the selected output is mono WAV or Ogg Opus with the complete synthesized sample sequence"
+    },
+    {
+      "id": "local-ai-kokoro:KOKORO_VOICES",
+      "name": "KOKORO_VOICES",
+      "displayName": "KOKORO_VOICES",
+      "kind": "constant",
+      "signature": "const KOKORO_VOICES",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "The 28 supported US and British English voice identifiers for the selected native Kokoro resources.",
+      "availability": "Node",
+      "protocol": "Native speech voice selection",
+      "normalization": "Complete ordered voice array exported by the frontend; af_heart is the omitted voice default. An unsupported explicit voice reports its actual incompatibility without substitution."
+    },
     {
       "id": "local-ai-whisper:createWhisperRuntime",
       "name": "createWhisperRuntime",
@@ -345,8 +429,8 @@
       "group": "Core native speech",
       "summary": "Composes host-supplied transcription and synthesis engines with independent loading and role readiness.",
       "availability": "Node Core with explicitly supplied engines; engine platform, model and format support remain engine-owned",
-      "protocol": "arcane/1 speech.status/transcribe/synthesize with speech.state/progress",
-      "normalization": "Returns current/subscribe/close/start/methods/drain/dispose; forwards complete requests and results unchanged; replaying service state, synchronous accepted Thinking, combined request/lifetime cancellation and concurrent joined engine shutdown; no engine installation or automatic provider selection"
+      "protocol": "arcane/1 speech.status/load/unload/transcribe/synthesize with speech.state/progress",
+      "normalization": "Returns current/subscribe/close/start/methods/drain/dispose; forwards complete requests and results unchanged; replaying service state, synchronous accepted Thinking, combined request/lifetime cancellation and concurrent joined engine shutdown. Explicit load/unload require role stt or tts and forward the remaining activation fields and complete result through that role's configured engine; supported preparation remains with that engine. Startup waiting is independently owned from caller cancellation; no automatic provider selection is introduced."
     },
     {
       "id": "core-speech:default",
@@ -609,10 +693,10 @@
       "entrypoints": ["arcane-os/local-ai"],
       "primaryImport": "arcane-os/local-ai",
       "group": "Core local AI",
-      "summary": "Reuses selected managed native runtimes or installs complete llama.cpp/Ollama/image distributions, ONNX npm runtime trees with selected SDK native libraries, or NeMo libraries.",
+      "summary": "Reuses selected managed native runtimes or installs complete llama.cpp/Ollama/image distributions, ONNX npm runtime trees with selected SDK native libraries, NeMo libraries, or Kokoro native helper/data trees.",
       "availability": "Node; selected distribution platform and architecture assets determine runtime availability",
       "protocol": "Upstream release archives and selected ONNX/Koffi npm installations; corrected Windows x64 ONNX native libraries from the installed SDK numeric release",
-      "normalization": "Returns absolute runtime records, including image library/binding/variant/model metadata; Windows x64 ONNX with no explicit URL and omitted version or 1.30.0 adds nativeDistributionRevision 1.30.0-directml-reshape-1, reuses that revision or prepares a fresh installation while preserving older trees; explicit URLs and other ONNX versions/platforms retain their upstream package path; shares matching installs, preserves libraries, reports failures without changing global PATH or services and prepares no model files"
+      "normalization": "Returns absolute runtime records, including image library/binding/variant/model metadata; Windows x64 ONNX with no explicit URL and omitted version or 1.30.0 adds nativeDistributionRevision 1.30.0-directml-reshape-1, reuses that revision or prepares a fresh installation while preserving older trees; explicit URLs and other ONNX versions/platforms retain their upstream package path; shares matching installs, preserves libraries, reports failures without changing global PATH or services and prepares no model files. Kokoro returns helperExecutable, espeakDataDirectory and libraryDirectory for the complete selected helper tree; Windows x64 defaults to the installed SDK numeric release, while explicit url/helperRoot supplies another prepared distribution and preserves model/ONNX ownership."
     },
     {
       "id": "local-ai:bundleLocalAIRuntimes",
@@ -626,7 +710,7 @@
       "summary": "Copies selected complete runtime distributions into a fresh native artifact staging root.",
       "availability": "Node; supports bundling selected published platform assets independently of the build host",
       "protocol": "Artifact-relative runtime/local-ai layout",
-      "normalization": "Returns {runtimes,files} with artifact-relative runtime/variant paths and complete inventory; corrected Windows x64 ONNX retains nativeDistributionRevision and complete native libraries while modulePath becomes artifact-relative; image URL descriptors remain for post-launch preparation and external model working paths report portability incompatibility"
+      "normalization": "Returns {runtimes,files} with artifact-relative runtime/variant paths and complete inventory; corrected Windows x64 ONNX retains nativeDistributionRevision and complete native libraries while modulePath becomes artifact-relative; image URL descriptors remain for post-launch preparation and external model working paths report portability incompatibility. Kokoro retains the complete helper/data tree and relocates helperExecutable, espeakDataDirectory and libraryDirectory; ONNX and model resources retain their separate owners."
     },
     {
       "id": "root:WS",
@@ -4122,7 +4206,7 @@
       "summary": "Sends one complete TWiN Cloud request with an explicit caller-owned key and model.",
       "availability": "Node and Browser; remote HTTPS provider",
       "protocol": "TWiN Cloud complete-response chat",
-      "normalization": "Preserves complete messages and parsed provider JSON; maps explicit structured-output, tool, and reasoning options; shares overload-only HTTP 429 retry after 3000 ms and cancellation; retains no browser profile, storage, or request history"
+      "normalization": "Preserves complete messages and provider JSON; Fetch rejection and all HTTP 429/529 share three retries; quota recovery honors Retry-After or exponential delay with transient same-endpoint/credential pacing, complete terminal errors and cancellation; retains no browser profile, storage, or history"
     },
     {
       "id": "twin-cloud:fetchSystemOneRequest",
@@ -4171,21 +4255,21 @@
       "name": "fetchHTTPResponse",
       "displayName": "fetchHTTPResponse()",
       "kind": "function",
-      "signature": "async fetchHTTPResponse(url,options)",
+      "signature": "async fetchHTTPResponse(url,options,{onRetry=null}={})",
       "entrypoints": ["arcane-os/ai/twin-cloud"],
       "primaryImport": "arcane-os/ai/twin-cloud",
       "group": "Shared AI transport integration",
       "summary": "Returns a successful unconsumed Fetch Response through the shared AI HTTP owner.",
       "availability": "Node and Browser",
       "protocol": "Shared AI HTTP transport",
-      "normalization": "Preserves caller Fetch options and complete error bodies; repeats only overload HTTP 429 after 3000 ms; signal cancellation uses ARCANE_AI_REQUEST_ABORTED"
+      "normalization": "Preserves caller Fetch options and complete errors; Fetch rejection and all HTTP 429/529 share three retries; Retry-After or exponential quota delay and transient same-endpoint/credential pacing remain abortable; onRetry observes waiting/requesting; cancellation uses ARCANE_AI_REQUEST_ABORTED"
     },
     {
       "id": "twin-cloud:fetchJSONResponse",
       "name": "fetchJSONResponse",
       "displayName": "fetchJSONResponse()",
       "kind": "function",
-      "signature": "async fetchJSONResponse(url,options)",
+      "signature": "async fetchJSONResponse(url,options,{onRetry=null}={})",
       "entrypoints": ["arcane-os/ai/twin-cloud"],
       "primaryImport": "arcane-os/ai/twin-cloud",
       "group": "Shared AI transport integration",
@@ -4360,7 +4444,7 @@
       "summary": "Projects a Core client into the established application-facing Arcane namespace.",
       "availability": "Browser and native WebView JavaScript hosts with a Core client",
       "protocol": "arcane/1 compatibility facade",
-      "normalization": "Routes namespace methods through client.invoke while retaining operation-specific parameters, correlation, streaming callbacks, timeouts and cancellation; window.state({signal}?) reads the requesting window and window.setState({state},{signal}?) selects normal, maximized or fullscreen. The matching Windows host returns {platform:'windows',supported:true,state}, including observed minimized state, restores normal bounds/frame controls on leaving fullscreen and prevents activation/focus assignment during visible state transitions without changing TopMost, Core, origin or profile. Saved Settings remain application-owned; cancellation does not undo an applied change and unavailable hosts retain their actual errors without fallback. window.setTheme(presentation,{signal}?) forwards the complete per-window backgroundColor/textColor record, with omitted fields unchanged and null reset, and returns the host's actual applied/unsupported result without changing system appearance. notifications.status/show/state/close forward complete caller requests and standard invoke options; status normalizes only METHOD_NOT_ALLOWED with core-namespace-unavailable while retaining the complete original error. Matching native window hosts retain complete notification records and ordered revisions across renderer navigation, with notifications.state events and subscribe-before-snapshot recovery. Submitted means native Show returned, not displayed or read; cancellation after submission does not remove an accepted notice, and explicit close retains its record. Recipient, text, trigger, deduplication and navigation policy remains application-owned"
+      "normalization": "Routes namespace methods through client.invoke while retaining operation-specific parameters, correlation, streaming callbacks, timeouts and cancellation; window.state({signal}?) reads the requesting window and window.setState({state},{signal}?) selects normal, maximized or fullscreen. The matching Windows host returns {platform:'windows',supported:true,state}, including observed minimized state, restores normal bounds/frame controls on leaving fullscreen and prevents activation/focus assignment during visible state transitions without changing TopMost, Core, origin or profile. Saved Settings remain application-owned; cancellation does not undo an applied change and unavailable hosts retain their actual errors without fallback. window.setTheme(presentation,{signal}?) forwards the complete per-window backgroundColor/textColor record, with omitted fields unchanged and null reset, and returns the host's actual applied/unsupported result without changing system appearance. notifications.status/show/state/close forward complete caller requests and standard invoke options; status normalizes only METHOD_NOT_ALLOWED with core-namespace-unavailable while retaining the complete original error. Matching native window hosts retain complete notification records and ordered revisions across renderer navigation, with notifications.state events and subscribe-before-snapshot recovery. Submitted means native Show returned, not displayed or read; cancellation after submission does not remove an accepted notice, and explicit close retains its record. Recipient, text, trigger, deduplication and navigation policy remains application-owned. speech.load(request,options) and speech.unload(request,options) forward complete activation requests, cancellation and request observers with no elapsed-time cutoff; selected engines own preparation and native retirement."
     },
     {
       "id": "core-client:installCoreClient",