arcane-os 0.49.0 → 0.51.0

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

@@ -3,6 +3,7 @@ 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';
 
 /** A stateless TWiN request; browser AI shares the HTTP and format owners below. */
 export async function fetchRequest({
@@ -87,6 +88,72 @@ export async function fetchRequest({
     }
 }
 
+/** Submit caller-owned state and questions without interpreting the provider's answers. */
+export async function fetchSystemOneRequest({
+    twinKey,
+    model,
+    state,
+    questions,
+    signal = null,
+    id = Date.now(),
+    onRequest = function observeSystemOneRequest(){},
+    onResponse = function observeSystemOneResponse(){},
+    onRetry = null
+} = {}){
+    if(signal?.aborted){
+        throw normalizeAIRequestAbort(signal.reason);
+    }
+    if(!is.string(twinKey) || !twinKey){
+        const error = new Error('AI provider is not configured.');
+        error.code = 'AI_PROVIDER_NOT_CONFIGURED';
+        throw error;
+    }
+    if(!is.string(model) || !model){
+        throw new TypeError('TWiN fetchSystemOneRequest requires an explicit model.');
+    }
+
+    const request = {model, state, questions};
+    // Capture the caller's complete payload before a diagnostic observer runs.
+    const body = JSON.stringify(request);
+    try{
+        await onRequest(
+            request,
+            id,
+            {operation:'systemone', transport:'http', destination:twinSystemOneURL}
+        );
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        const response = await fetchJSONResponse(
+            twinSystemOneURL,
+            {
+                method:'POST',
+                credentials:'omit',
+                headers:{
+                    'Content-Type':'application/json',
+                    Authorization:`Bearer ${twinKey}`
+                },
+                body,
+                ...(signal ? {signal} : {})
+            },
+            {onRetry}
+        );
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        await onResponse(response, id, false);
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        return response;
+    }catch(error){
+        if(isAIRequestAbort(error, signal)){
+            throw normalizeAIRequestAbort(error);
+        }
+        throw error;
+    }
+}
+
 export function isAIRequestAbort(error, signal){
     return signal?.aborted
         || error?.name === 'AbortError'

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

@@ -1,7 +1,7 @@
 # Browser speech providers
 
 `arcane-os/ai/browser-speech` supplies caller-selected Whisper or native Web
-Speech recognition, Kokoro text-to-speech, and TWiN Cloud text-to-speech providers. Its local path
+Speech recognition and synthesis, Kokoro text-to-speech, and TWiN Cloud text-to-speech providers. Its local path
 provides artifact storage, live module routing, role Workers, provider/2
 adapters, bounded parallel TTS synthesis, audio normalization, cancellation,
 and cleanup.
@@ -82,6 +82,97 @@ honestly rather than recording again or silently switching providers. See the
 [Web Speech specification](https://webaudio.github.io/web-speech-api/#speechreco-methods)
 for native stop/abort behavior.
 
+## Native browser text-to-speech and voice previews
+
+`createBrowserSpeechSynthesisProvider({id,model:{id,name?,defaultVoice?},language?})`
+uses the host browser's `speechSynthesis` and `SpeechSynthesisUtterance`.
+The application selects this provider as its default when desired; constructing
+it does not change global preferences, activate Chat speech, or play audio.
+The provider declares `localOnly:false` because a browser voice may use a remote
+service. Individual catalog records expose the browser's `localService` value.
+
+```javascript
+import {createBrowserSpeechSynthesisProvider} from 'arcane-os/ai/browser-speech';
+
+const voicePreview = createBrowserSpeechSynthesisProvider({
+  id: 'browser-preview',
+  model: {id: 'browser-voices', name: 'Browser voices'}
+});
+const unsubscribe = voicePreview.subscribeCatalog(function showVoices(models) {
+  // Pass these real records to the application's language/voice selector.
+  console.log(models[0].voices);
+});
+
+// Call only from the application's explicit Play action.
+function playIntroduction(input, voice) {
+  return voicePreview.play({input, voice});
+}
+// The owning view unsubscribes and disposes voicePreview when it closes.
+```
+
+`catalog()` synchronously returns an array of model records. Each model has
+`speech:{playback:'native'}` and `voices:[{id,name,lang,default,localService}]`;
+`id` is the exact native `voiceURI`. `subscribeCatalog(callback)` immediately
+replays that same shape and updates it on `voiceschanged` or a changed default,
+returning an unsubscribe function. An initially empty inventory is ordinary pending browser
+state. There is no polling, discovery utterance, model download, or page-load
+barrier. Language selectors derive their choices from this actual inventory.
+
+`provider.setDefaultVoice(voiceURI)` updates the provider's current
+`catalog()[0].defaultVoice` synchronously and returns that current value.
+The application may call it from its catalog subscription after asynchronous
+voice discovery or when its saved selection changes. The SDK supplies no
+voice-name preference: preserve an explicit saved choice in the application
+and pass the exact native `voiceURI`. Repeating the current value is a no-op,
+so a catalog subscription can apply the same choice without notification loops.
+`null`, an empty string, or an omitted argument clears the configured default
+and restores the existing browser-default behavior. A non-string, non-null
+value throws `TypeError`; an unloading or disposed provider retains its
+existing lifecycle error. A voice need not be present when setting the default:
+the existing preparation/playback availability behavior below still applies.
+
+Only future preparations use the new default. Explicit request voices and
+already-prepared, queued, or active speech keep their selected voice. Updating
+the default does not load, unload, replace, cancel, pause, resume, or speak.
+AI's ordinary speech path reads this current catalog for new requests, so no
+provider reconfiguration is necessary.
+
+`prepare({input,voice?,language?,speed?},{signal?})` returns an inert
+`{kind:'native-speech',input,voice,language,speed,play(options)}` descriptor.
+`play(payload,{signal,onState})` is the explicit-preview convenience. Both
+preserve complete input. Omitted voice uses the current default, initially
+`model.defaultVoice`, or the actual browser default; a supplied voice is never replaced with a named
+SDK alias. Language comes from that voice unless explicitly provided. Neither
+API reads the conversation's language preference. A saved voice waits for
+`voiceschanged` if the inventory is empty; a nonempty inventory missing it
+reports `ARCANE_AI_SPEECH_VOICE_UNAVAILABLE`.
+
+Playback returns `{finished,released,state,error,pause(),resume(),stop()}`.
+`finished` resolves `true` on actual native end, `false` on stop/abort, and
+rejects genuine native failures. `released` resolves when native resource
+ownership actually ends: a failed pause/resume/cancel can report an error before
+the utterance terminates. `onState({state,error})` observes queued,
+waiting-for-voices, playing, paused, complete, stopped, or error. Keep complete
+errors in diagnostics and ordinary status in the interface.
+
+Preview does not depend on AI mute or model activation. Use a separate provider
+instance when the preview should have a lifetime independent of Chat's selected
+provider. Provider unload/dispose stop their own playback, invalidate prepared
+descriptors, and disposal removes catalog listeners. Web Speech pause/resume/cancel
+operate on the native synthesis object globally; the SDK serializes its own
+utterances and does not claim control isolation from unrelated direct native
+callers. See the [native synthesis contract](https://webaudio.github.io/web-speech-api/#tts-section).
+
+For Chat, configure this provider with `ai.configureSpeechProvider('tts',provider)`
+and retain the existing explicit mute/unmute lifecycle. `AI.streamTTS()` and
+`SpeechPlayback` use actual utterance completion and cancellation in original
+order. `AI.prepareTTSPlayback(payload,signal)` returns either real Blob audio or
+the native descriptor without speaking; its signal remains attached by default
+when the returned descriptor is played. `AI.fetchTTS()` and durable
+`AI.prepareTTS()` remain audio-file APIs and report
+`ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE` for native synthesis, which exposes no
+downloadable audio file.
+
 <a id="digitalocean-fal-text-to-speech"></a>
 
 ## TWiN Cloud text-to-speech

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

@@ -116,11 +116,72 @@ managed import map. Browser Fetch and CORS behavior still apply. Importing it
 does not instantiate `AI`, read saved preferences, configure speech, or change
 the existing `arcane-os/ai` browser entry.
 
+## Evaluate caller-owned state with System One
+
+Use the named `fetchSystemOneRequest` export for the provider's native
+state-and-questions operation. The application supplies the model and complete
+provider-compatible `state` and `questions`; the SDK selects no model or scoring
+policy and assigns no meaning to questions, answer keys, or scales.
+
+```javascript
+import {fetchSystemOneRequest} from 'arcane-os/ai/twin-cloud';
+
+const response = await fetchSystemOneRequest({
+    twinKey: applicationRuntime.twinKey,
+    model: 'typesafe-jev-1.13.0',
+    state: applicationState,
+    questions: applicationQuestions,
+    signal: controller.signal
+});
+```
+
+`applicationRuntime`, `applicationState`, `applicationQuestions`, and
+`controller` are supplied by the application. The example's JEV identifier is
+an explicit caller selection, not an SDK default. For OSS chat-completion models
+such as `openai-gpt-oss-120b` and `openai-gpt-oss-20b`, use `fetchRequest` with
+caller-owned messages and structured-output settings instead. The application
+chooses the operation matching its model's provider contract.
+
+```javascript
+fetchSystemOneRequest({
+    twinKey,
+    model,
+    state,
+    questions,
+    signal,
+    id,
+    onRequest,
+    onResponse,
+    onRetry
+})
+// Promise<complete parsed provider JSON>
+```
+
+The SDK posts exactly `{model,state,questions}` as JSON to
+`https://inference.do-ai.run/v1/systemone`, using `twinKey` only as bearer
+authentication. It adds no prompt, chat envelope, tool call, output limit, or
+answer conversion. Caller content stays unchanged within ordinary JSON
+transport encoding. The request is serialized before `onRequest`, so that
+diagnostic callback cannot rewrite the dispatched payload. The entire parsed
+provider JSON reaches `onResponse` and the returned promise without selecting
+or transforming answers.
+
+The explicit key/model requirements, optional `signal`, `id`, callbacks,
+retry observer, complete errors, and lack of retained history follow the shared
+request behavior above. `onRequest(request,id,metadata)` receives
+`{operation:'systemone',transport:'http',destination:'https://inference.do-ai.run/v1/systemone'}`
+as metadata. `onResponse(response,id,false)` receives the complete parsed
+response. Both callbacks are awaited; failures propagate and cancellation is
+checked again after they settle. The existing `fetchJSONResponse` owner
+provides the same HTTP retries and cancellation for this operation; no separate
+transport or retry loop is created.
+
 ### Shared low-level integration helpers
 
 The same module also exports the helpers used by browser `AI.js`. Ordinary
-callers use `fetchRequest`; these exports let SDK transport integration share
-the existing implementation rather than maintain another retry or body reader.
+callers use `fetchRequest` or `fetchSystemOneRequest`; these exports let SDK
+transport integration share the existing implementation rather than maintain
+another retry or body reader.
 
 | Export | Contract |
 | --- | --- |

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

@@ -80,6 +80,7 @@ version; WebKitGTK availability must not be generalized to macOS.
 | 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. |
+| 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. |
 | 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 and TWiN Cloud TTS declare their non-local behavior. The helper automatically cleans only the outbound synthesis-input copy and normalizes application-facing audio/text behavior while request/response plumbing differs below that boundary. |
 | Inspect or manage raw Ollama models | `Arcane.ollama` or `/arcane/modules/Ollama.js` | **Native** desktop Core for management; narrower Android inference only | Wrapper method names, errors, streaming correlation, and admission are Arcane-controlled. Direct Ollama success envelopes are intentionally provider-native. |
 | Use native terminal, installation, user, provisioning, or machine controls | matching `Arcane.*` namespace | **Native** and app/capability restricted | Calls and errors use the common bridge contract. Platform results can be host-specific and are marked in the method guide. |

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

@@ -6,7 +6,7 @@
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 219,
+  "memberCount": 220,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
@@ -3452,6 +3452,20 @@
       "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"
     },
+    {
+      "id": "twin-cloud:fetchSystemOneRequest",
+      "name": "fetchSystemOneRequest",
+      "displayName": "fetchSystemOneRequest()",
+      "kind": "function",
+      "signature": "async fetchSystemOneRequest({twinKey,model,state,questions,signal=null,id=Date.now(),onRequest,onResponse,onRetry=null}={})",
+      "entrypoints": ["arcane-os/ai/twin-cloud"],
+      "primaryImport": "arcane-os/ai/twin-cloud",
+      "group": "TWiN Cloud state-and-questions requests",
+      "summary": "Sends caller-owned model, state, and questions to the native System One endpoint with explicit credentials.",
+      "availability": "Node and Browser; remote HTTPS provider",
+      "protocol": "TWiN Cloud native System One request",
+      "normalization": "Preserves complete state and questions within JSON transport and returns the full parsed provider result; shares existing JSON transport retry, diagnostics, and cancellation; leaves model choice, scales, and answer interpretation with the caller and retains no history"
+    },
     {
       "id": "twin-cloud:fetchHTTPResponse",
       "name": "fetchHTTPResponse",

package/docs/reference/runtime-components.md

@@ -1682,8 +1682,19 @@ On desktop native capture, an accessible editable BCP47 language control occupie
 the feedback area instead of idle transcription/voice readiness boilerplate.
 `recognitionLanguage` defaults to `navigator.language`, accepts an explicit
 language tag without restricting it to the suggested choices, and is passed to
-the capture owner at start. The control is disabled during active capture so
-changes affect the next capture. Native voice loading, errors, and speaking
+the capture owner at start. Opening or reopening the editable picker shows all
+suggestions regardless of its saved/current value. Filtering begins only after
+the user changes the input text; initialization, programmatic configuration,
+and choosing a suggestion leave the full list available on the next opening.
+Suggestions display their native language and region names alongside the exact
+BCP47 tags; they are suggestions, not an exhaustive provider support inventory.
+The selected or freely typed tag remains unchanged. Arrow keys navigate the
+suggestions, Enter chooses the active suggestion, and Escape or Tab closes the
+list. The picker is visible and enabled only for desktop live-transcription
+mode, including before recording begins. It is disabled during active capture
+so changes affect the next capture; leaving live-transcription mode closes and
+disables it. File/model transcription and conversation-language configuration
+remain separate. Native voice loading, errors, and speaking
 remain visible. Model-based transcription retains its existing status, and
 mobile speech retains its existing voice-output-only presentation.
 

package/docs/reference/runtime-modules.md

@@ -160,7 +160,7 @@ read-only `ttsSegmentation`, `configureTTSSegmentation()`,
 `streamTTS(text='',end=false,options={})`,
 `prepareTTS({parts,storage,identity,signal,onState})`,
 `playPreparedTTS(prepared,{signal,onState})`,
-`finishTTS()`, `fetchTTS()`, `fetchSTT()`, `stopAudio()`, `resumeAudio()`,
+`finishTTS()`, `prepareTTSPlayback()`, `fetchTTS()`, `fetchSTT()`, `stopAudio()`, `resumeAudio()`,
 `playAudio()`; consumes `user-entity-loaded` and `arcane-ollama-ready`,
 installs `window.ai`, and emits `ai-ready` and `ai-tts-failure`.
 
@@ -374,7 +374,7 @@ marks from a cloned outbound input before delegation; the caller's payload stays
 unchanged. The third `preparation` argument is reserved for SDK-internal
 delegation, where `{speechInputPrepared:true}` prevents a second cleanup pass;
 applications omit it. `streamTTS(text='',end=false,options={})` and
-`finishTTS()` use this same request boundary. The third-argument options below
+`finishTTS()` use the selected playback boundary. The third-argument options below
 are available in SDK `0.5.12`. The `textFormat` compatibility extra added in
 SDK `0.5.16` is ignored beginning in `0.5.17`:
 
@@ -386,7 +386,7 @@ SDK `0.5.16` is ignored beginning in `0.5.17`:
 | `waitForPlayback` | `false` | Omission retains the preparation promise. With `true`, the promise resolves after every extracted segment reaches a terminal playback state: `true` when all naturally end, or `false` after terminal cancellation or failure. |
 | `textFormat` | Ignored compatibility extra | Repeated same formatting marks are removed automatically from every TTS call. This value no longer selects or disables cleanup. |
 
-The voice and speed use the existing `fetchTTS()` validation and error path.
+Audio-file voice and speed use the existing `fetchTTS()` validation and error path.
 The automatic cleanup changes only the outbound speech-input copy; displayed,
 stored, model, and caller-owned content remains exact. It is a narrow
 formatting-mark filter, not a full Markdown parser: links, code contents, list
@@ -405,6 +405,24 @@ for a complete passage. A call extracting no segments resolves
 `true` without waiting for earlier jobs; `finishTTS()` remains a preparation
 flush, not a queue-wide playback barrier. A muted call resolves `false`.
 
+`prepareTTSPlayback(payload,signal,preparation={})` is the silent playback-oriented
+request. Audio-file providers retain the `fetchTTS()` Blob contract; a selected
+model with `speech.playback:'native'` returns an inert `native-speech` descriptor.
+Its `play({signal,onState})` returns native completion and lifecycle controls.
+The preparation signal remains its default playback signal. Native input stays
+complete; per-request voice/language/speed and the configured model default own
+selection, without reading global user voice or conversation-language fields.
+Native streaming jobs wait for actual end in order and allocate no AudioContext.
+When native speech follows recorded audio, the preceding audio clock still owns
+its requested inter-part pause. Native trailing silence delays the next part,
+not the completed playback promise; cancellation retires either pending gap.
+Failed native control remains owned through its `released` promise, so Stop can
+still reach it and subsequent buffered audio cannot overlap it. Explicit saved
+Blob playback continues to use its own AudioContext even when native speech is
+the currently selected provider. `fetchTTS()` and durable `prepareTTS()` report
+`ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE` for native selection; no audio file is
+fabricated. See [native voice catalogs and previews](ai/browser-speech.md#native-browser-text-to-speech-and-voice-previews).
+
 Playback completion stays pending while the browser waits for an audio-unlock
 gesture or a recoverable resume attempt. If resuming a closed `AudioContext`
 fails, the affected jobs terminate and their playback results settle `false`.
@@ -3731,8 +3749,10 @@ new SpeechPlayback({
 })
 ```
 
-`speech` must expose either `fetchTTS(payload, signal)` or
-`synthesize(payload, {signal})`. `SpeechPlayback` also supplies a third
+`speech` may expose `prepareTTSPlayback(payload,signal)` returning a Blob or
+native descriptor, a native provider's silent `prepare(payload,{signal})`,
+`fetchTTS(payload, signal)`, or `synthesize(payload, {signal})`.
+The playback-oriented method is preferred. `SpeechPlayback` also supplies a third
 SDK-internal preparation object; existing two-argument clients may ignore it.
 `prepare({key,parts,model,voice,responseFormat,
 speed,autoplay=true})` uses only caller-supplied model, voice, and response-format
@@ -3775,6 +3795,15 @@ releases prepared URLs. Replay keeps completed URLs and still-pending provider
 work, then re-submits only failed missing provider segments before starting
 again from index zero.
 
+Native descriptors are retained separately from Blob URLs and never assigned to
+an audio element. `autoplay:false` remains silent. Play, Pause, Resume, Stop and
+Replay use the native control; only a successful current native `finished`
+advances the next part. Native errors remain observable, and a failed native
+control stays owned until its optional `released` promise confirms cleanup.
+Stale completion after stop/restart/disposal cannot advance replacement content.
+Selecting a native part hides and clears the HTML audio source while preserving
+the same shared playback state events and complete original parts.
+
 Every preparation owns an operation ID and one AbortController for each active
 synthesis segment or playback delay. Replacement,
 `stop()`, `cancel()`, and `destroy()` abort their owned signals, suppress stale

package/docs/reference/sdk-api.md

@@ -123,6 +123,7 @@ browser map are cataloged separately in [Runtime modules](runtime-modules.md).
 | Member | Kind | Import | Group | Availability |
 | --- | --- | --- | --- | --- |
 | `fetchRequest()` | function | `arcane-os/ai/twin-cloud` | TWiN Cloud requests | Node and Browser; remote HTTPS provider |
+| `fetchSystemOneRequest()` | function | `arcane-os/ai/twin-cloud` | TWiN Cloud state-and-questions requests | Node and Browser; remote HTTPS provider |
 | `fetchHTTPResponse()` | function | `arcane-os/ai/twin-cloud` | Shared AI transport integration | Node and Browser |
 | `fetchJSONResponse()` | function | `arcane-os/ai/twin-cloud` | Shared AI transport integration | Node and Browser |
 | `structuredOutputFormat()` | function | `arcane-os/ai/twin-cloud` | Shared AI transport integration | Node and Browser |
@@ -7953,6 +7954,59 @@ console.log(response);
 `server-config.json` is an application-owned, ignored configuration file;
 never commit its key or print it in diagnostics. The SDK does not read it.
 
+## fetchSystemOneRequest()
+
+### Overview
+
+Sends one native TWiN System One request with caller-owned credentials, model,
+state, and questions. Question definitions, scales, model selection, and answer
+interpretation remain application responsibilities.
+
+### Signature and result
+
+```text
+async fetchSystemOneRequest({twinKey,model,state,questions,signal=null,id=Date.now(),onRequest,onResponse,onRetry=null}={})
+```
+
+Import the named function from `arcane-os/ai/twin-cloud`. It posts
+`{model,state,questions}` to `https://inference.do-ai.run/v1/systemone` and
+returns the entire parsed provider JSON. It adds no chat messages, tools,
+scoring rules, or output limit. Payload content is preserved within ordinary
+JSON transport encoding; serialization occurs before the diagnostic callback.
+
+`onRequest(request,id,metadata)` receives the complete payload before dispatch,
+with `{operation:'systemone',transport:'http',destination:'https://inference.do-ai.run/v1/systemone'}`
+as metadata. `onResponse(response,id,false)` receives the entire parsed result
+before return. Both callbacks are awaited and failures propagate. The key is
+used only for transport authentication, outside the diagnostic payloads.
+
+### Availability and normalization
+
+**Node and Browser; Cloud transport.** Uses the existing `fetchJSONResponse`
+owner for complete errors, retries, `onRetry`, and `signal` cancellation, with
+no browser singleton, profile, storage, or retained history. A missing key uses
+`AI_PROVIDER_NOT_CONFIGURED`; a missing explicit model throws `TypeError`.
+Cancellation prevents successful return and uses `ARCANE_AI_REQUEST_ABORTED`,
+including checks after callback settlement. Import starts no request.
+
+### Example
+
+```javascript
+import {fetchSystemOneRequest} from 'arcane-os/ai/twin-cloud';
+
+const response = await fetchSystemOneRequest({
+    twinKey: applicationRuntime.twinKey,
+    model: 'typesafe-jev-1.13.0',
+    state: applicationState,
+    questions: applicationQuestions
+});
+```
+
+The runtime configuration, state, and questions in this example belong to the
+application. The JEV identifier is an explicit caller choice, not a default.
+See [TWiN Cloud](ai/twin-cloud.md#evaluate-caller-owned-state-with-system-one)
+for the complete transport and callback contract.
+
 ## fetchHTTPResponse()
 
 ### Overview

package/package.json

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