arcane-os 0.93.0 → 0.95.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.95.0
+
+- Add retained native Nemotron streaming recognition and optional diarization,
+  with ordered complete snapshots, explicit utterance endpoints, speaker scope,
+  and joined cancellation. Preserve existing Whisper and complete transcription.
+- Add native Magpie/NanoCodec synthesis with model-owned voice selection,
+  per-request language, ordered PCM streaming, complete WAV/PCM export, and
+  exact-utterance cancellation. Preserve authored input and natural model rate;
+  the caller supplies upstream runtime and model assets without SDK vendoring.
+- Extend shared Core speech and browser clients with correlated streaming
+  capture/output, consumed-audio acknowledgements and native cleanup joins.
+  Connect AI playback through its existing queues and shared AudioContext,
+  retaining per-utterance pause/resume/stop and complete-audio APIs.
+- Keep capture ownership, recognition segments and model-owned conversational
+  decisions distinct. Windows x64 native helpers compiled and installed against
+  the approved NeMo 0.2.0 runtime; inference, microphone/audio acceptance and
+  other-platform execution remain separate evidence boundaries.
+
+## 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.95.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

@@ -569,6 +569,199 @@ export function createCoreClient({
 export function createCoreFacade(client){
     const {invoke,events,uuid}=client;
     const long={timeoutMs:LONG_OPERATION_TIMEOUT};
+    function speechStreamEvents(streamId,options){
+        const controller=new AbortController();
+        const signal=options.signal?AbortSignal.any([options.signal,controller.signal]):controller.signal;
+        const subscriptions=[];
+        let delivery=Promise.resolve();
+        let callbackFailure;
+        function listen(name,callback){
+            if(callback===undefined)return;
+            if(typeof callback!=='function')throw new TypeError(`${name} observer must be a function.`);
+            subscriptions.push(events.on(name,function receiveSpeechStreamEvent(event){
+                if(event?.streamId!==streamId||signal.aborted)return;
+                delivery=delivery.then(function deliverOrderedSpeechEvent(){
+                    if(!signal.aborted)return callback(event);
+                });
+                delivery.catch(function cancelFailedSpeechObserver(error){
+                    callbackFailure??=error;
+                    controller.abort(error);
+                });
+            }));
+        }
+        function dispose(){
+            for(const unsubscribe of subscriptions.splice(0))unsubscribe();
+        }
+        async function delivered(){
+            await delivery;
+            signal.throwIfAborted();
+        }
+        async function settle(task,{preserveTaskFailure=false}={}){
+            let result;
+            let failure;
+            let failed=false;
+            let deliveryFailure;
+            let deliveryFailed=false;
+            try{
+                try{result=await task;}catch(error){failed=true;failure=error;}
+                try{await delivery;}catch(error){deliveryFailed=true;deliveryFailure=callbackFailure??error;}
+                if(preserveTaskFailure&&failed&&deliveryFailed&&failure!==deliveryFailure){
+                    throw new AggregateError([deliveryFailure,failure],'Speech callback and native cleanup failed.');
+                }
+                if(failed||deliveryFailed)throw callbackFailure??deliveryFailure??failure;
+                signal.throwIfAborted();
+                return result;
+            }finally{dispose();}
+        }
+        return {controller,signal,listen,settle,dispose,delivered};
+    }
+    function encodeSpeechSamples(samples){
+        if(!(samples instanceof Float32Array))throw new TypeError('Speech stream push requires Float32Array PCM.');
+        const encoded=new Uint8Array(samples.length*4);
+        const view=new DataView(encoded.buffer);
+        const bits=new Uint32Array(samples.buffer,samples.byteOffset,samples.length);
+        for(let index=0;index<bits.length;index+=1)view.setUint32(index*4,bits[index],true);
+        let binary='';
+        for(const value of encoded)binary+=String.fromCharCode(value);
+        return {encoding:'f32le',data:globalThis.btoa(binary)};
+    }
+    function decodeSpeechAudio(audio){
+        if(audio?.pcm?.encoding!=='base64'||typeof audio.pcm.data!=='string'){
+            throw new TypeError('Streaming speech audio requires base64 PCM transport.');
+        }
+        const binary=globalThis.atob(audio.pcm.data);
+        const pcm=new Uint8Array(binary.length);
+        for(let index=0;index<binary.length;index+=1)pcm[index]=binary.charCodeAt(index);
+        return {...audio,pcm};
+    }
+    function openSpeechStream(request={},options={}){
+        const streamId=uuid();
+        const owned=speechStreamEvents(streamId,options);
+        let resolveReady;
+        let rejectReady;
+        let opened=false;
+        let ending=false;
+        let snapshot=null;
+        let controls=Promise.resolve();
+        let finishing=null;
+        let cancelling=null;
+        const ready=new Promise(function waitForSpeechStream(resolve,reject){
+            resolveReady=resolve;
+            rejectReady=reject;
+        });
+        ready.catch(function observeSpeechStreamReadinessFailure(){});
+        try{
+            owned.listen('speech.opened',function speechStreamOpened(event){
+                opened=true;
+                resolveReady(event);
+            });
+            owned.listen('speech.transcription',function transcriptionUpdated(event){
+                snapshot=event.result;
+                return options.onUpdate?.(event.result);
+            });
+            if(options.onProgress!==undefined){
+                owned.listen('speech.progress',function speechStreamProgress(event){return options.onProgress(event);});
+            }
+        }catch(error){owned.dispose();throw error;}
+        const completion=owned.settle(invoke('speech.open',{streamId,options:request},{
+            timeoutMs:0,signal:owned.signal,onRequest:options.onRequest
+        })).then(function speechStreamCompleted(result){
+            if(!opened)throw new CoreError({code:'SPEECH_STREAM_NOT_OPENED',message:'The speech stream ended before readiness.'});
+            return result;
+        }).catch(function speechStreamFailed(error){
+            rejectReady(error);
+            throw error;
+        }).finally(function releaseSpeechStream(){ending=true;});
+        completion.catch(function observeOwnedSpeechStreamFailure(){});
+        function control(method,parameters={}){
+            const task=controls.then(async function sendOrderedSpeechControl(){
+                await ready;
+                owned.signal.throwIfAborted();
+                return invoke(method,{streamId,...parameters},{timeoutMs:0,signal:owned.signal});
+            });
+            controls=task;
+            task.catch(function cancelFailedSpeechControl(error){owned.controller.abort(error);});
+            return task;
+        }
+        return {
+            streamId,ready,completion,
+            current:function currentSpeechTranscript(){return snapshot;},
+            push:function pushSpeechSamples(samples){
+                if(ending)return Promise.reject(new CoreError({code:'SPEECH_STREAM_ENDING',message:'The speech stream is finishing.'}));
+                return control('speech.push',{audio:encodeSpeechSamples(samples)});
+            },
+            forceEndpoint:function endpointSpeechStream(){
+                if(ending)return Promise.reject(new CoreError({code:'SPEECH_STREAM_ENDING',message:'The speech stream is finishing.'}));
+                return control('speech.endpoint').then(async function deliverEndpointSnapshots(result){
+                    await owned.delivered();
+                    return result;
+                });
+            },
+            finish:function finishSpeechStream(){
+                if(!ending){
+                    ending=true;
+                    finishing=control('speech.finish').then(function finishSpeechDelivery(){return completion;});
+                    finishing.catch(function observeSpeechFinishFailure(){});
+                }
+                return finishing??completion;
+            },
+            cancel:function cancelSpeechStream(reason){
+                if(cancelling)return cancelling;
+                ending=true;
+                const stopping=invoke('speech.cancel',{streamId},{timeoutMs:0});
+                owned.controller.abort(reason);
+                // A transcript callback may await cancellation. Native cleanup
+                // must not wait for that same callback through completion.
+                cancelling=stopping;
+                return cancelling;
+            }
+        };
+    }
+    function synthesizeSpeechStream(request={},options={}){
+        if(typeof options.onAudio!=='function')throw new TypeError('Streaming speech synthesis requires an onAudio consumer.');
+        const streamId=uuid();
+        const owned=speechStreamEvents(streamId,options);
+        try{
+            owned.listen('speech.audio',async function synthesisAudio(event){
+                await options.onAudio(decodeSpeechAudio(event.audio));
+                owned.signal.throwIfAborted();
+                await invoke('speech.audioConsumed',{streamId,sequence:event.sequence},{timeoutMs:0,signal:owned.signal});
+            });
+            if(options.onProgress!==undefined){
+                owned.listen('speech.progress',function synthesisProgress(event){return options.onProgress(event);});
+            }
+        }catch(error){owned.dispose();throw error;}
+        if(owned.signal.aborted)return owned.settle(Promise.reject(owned.signal.reason));
+        // Keep the response pending until the native operation settles. Generic
+        // invoke cancellation settles locally before native cleanup can finish.
+        const operation=invoke('speech.synthesizeStream',{streamId,request},{
+            timeoutMs:0,onRequest:options.onRequest
+        });
+        let cancellation=null;
+        function cancelSynthesis(){
+            if(cancellation)return;
+            cancellation=invoke('speech.cancelSynthesis',{streamId},{timeoutMs:0});
+            cancellation.catch(function observeSynthesisCleanupFailure(){});
+        }
+        owned.signal.addEventListener('abort',cancelSynthesis,{once:true});
+        if(owned.signal.aborted)cancelSynthesis();
+        const joined=(async function joinSynthesisCleanup(){
+            let result;
+            const failures=[];
+            try{result=await operation;}catch(error){
+                if(!owned.signal.aborted||error?.name!=='AbortError')failures.push(error);
+            }
+            if(cancellation){
+                try{await cancellation;}catch(error){failures.push(error);}
+            }
+            if(failures.length===1)throw failures[0];
+            if(failures.length)throw new AggregateError(failures,'Speech synthesis and cleanup failed.');
+            return result;
+        })();
+        return owned.settle(joined,{preserveTaskFailure:true}).finally(function releaseSynthesisCancellation(){
+            owned.signal.removeEventListener('abort',cancelSynthesis);
+        });
+    }
     function ollamaInvoke(operation,request={},options={}){
         const onChunk=typeof options==='function'?options:options?.onChunk;
         const timeoutMs=options?.timeoutMs??(['pull','push','create'].includes(operation)?LONG_OPERATION_TIMEOUT:10*60*1000);
@@ -598,6 +791,10 @@ 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}),
+            openStream:openSpeechStream,
+            synthesizeStream:synthesizeSpeechStream,
+            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. |