arcane-os 0.29.1 → 0.31.0

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

@@ -6,7 +6,7 @@
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 210,
+  "memberCount": 217,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
@@ -3395,6 +3395,104 @@
       "availability": "Node and browser",
       "protocol": "Shared user.developer preference",
       "normalization": "Returns null until target.user.ready is true, then whether target.user.developer is exactly true; returns false if preference access throws"
+    },
+    {
+      "id": "twin-cloud:fetchRequest",
+      "name": "fetchRequest",
+      "displayName": "fetchRequest()",
+      "kind": "function",
+      "signature": "async fetchRequest(options={})",
+      "entrypoints": ["arcane-os/ai/twin-cloud"],
+      "primaryImport": "arcane-os/ai/twin-cloud",
+      "group": "TWiN Cloud requests",
+      "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"
+    },
+    {
+      "id": "twin-cloud:fetchHTTPResponse",
+      "name": "fetchHTTPResponse",
+      "displayName": "fetchHTTPResponse()",
+      "kind": "function",
+      "signature": "async fetchHTTPResponse(url,options)",
+      "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"
+    },
+    {
+      "id": "twin-cloud:fetchJSONResponse",
+      "name": "fetchJSONResponse",
+      "displayName": "fetchJSONResponse()",
+      "kind": "function",
+      "signature": "async fetchJSONResponse(url,options)",
+      "entrypoints": ["arcane-os/ai/twin-cloud"],
+      "primaryImport": "arcane-os/ai/twin-cloud",
+      "group": "Shared AI transport integration",
+      "summary": "Reads the complete successful provider JSON through the shared HTTP owner.",
+      "availability": "Node and Browser",
+      "protocol": "Shared AI HTTP transport",
+      "normalization": "Requires application/json, retains every parsed field without envelope validation, and checks cancellation before delivery"
+    },
+    {
+      "id": "twin-cloud:structuredOutputFormat",
+      "name": "structuredOutputFormat",
+      "displayName": "structuredOutputFormat()",
+      "kind": "function",
+      "signature": "structuredOutputFormat(value=false)",
+      "entrypoints": ["arcane-os/ai/twin-cloud"],
+      "primaryImport": "arcane-os/ai/twin-cloud",
+      "group": "Shared AI transport integration",
+      "summary": "Normalizes the existing structured-output option while preserving a supplied schema.",
+      "availability": "Node and Browser",
+      "protocol": "Shared AI structured-output options",
+      "normalization": "False/null/undefined return null, true/json return json, a plain schema object is returned unchanged, and other inputs use AI_STRUCTURED_OUTPUT_INVALID"
+    },
+    {
+      "id": "twin-cloud:openAIResponseFormat",
+      "name": "openAIResponseFormat",
+      "displayName": "openAIResponseFormat()",
+      "kind": "function",
+      "signature": "openAIResponseFormat(format)",
+      "entrypoints": ["arcane-os/ai/twin-cloud"],
+      "primaryImport": "arcane-os/ai/twin-cloud",
+      "group": "Shared AI transport integration",
+      "summary": "Maps normalized structured-output settings to chat-completion response_format.",
+      "availability": "Node and Browser",
+      "protocol": "Shared AI structured-output options",
+      "normalization": "Returns json_object, strict json_schema named structured_response with the original schema, or null; does not validate schema contents"
+    },
+    {
+      "id": "twin-cloud:isAIRequestAbort",
+      "name": "isAIRequestAbort",
+      "displayName": "isAIRequestAbort()",
+      "kind": "function",
+      "signature": "isAIRequestAbort(error,signal)",
+      "entrypoints": ["arcane-os/ai/twin-cloud"],
+      "primaryImport": "arcane-os/ai/twin-cloud",
+      "group": "Shared AI transport integration",
+      "summary": "Recognizes an aborted signal or an existing AI request cancellation error.",
+      "availability": "Node and Browser",
+      "protocol": "Shared AI cancellation",
+      "normalization": "Returns a boolean for AbortError or ARCANE_REQUEST_ABORTED, ARCANE_AI_REQUEST_ABORTED, and AI_REQUEST_ABORTED; changes no operation"
+    },
+    {
+      "id": "twin-cloud:normalizeAIRequestAbort",
+      "name": "normalizeAIRequestAbort",
+      "displayName": "normalizeAIRequestAbort()",
+      "kind": "function",
+      "signature": "normalizeAIRequestAbort(error)",
+      "entrypoints": ["arcane-os/ai/twin-cloud"],
+      "primaryImport": "arcane-os/ai/twin-cloud",
+      "group": "Shared AI transport integration",
+      "summary": "Returns the common AI AbortError while preserving the original cause.",
+      "availability": "Node and Browser",
+      "protocol": "Shared AI cancellation",
+      "normalization": "Preserves an existing ARCANE_AI_REQUEST_ABORTED value or returns an AbortError with that code and the supplied cause"
     }
   ]
 }

package/docs/reference/mail.md

@@ -381,7 +381,7 @@ application name and subscriber key. Existing top-level `RESEND_API_KEY` and
 `MAIL_PROFILES[profile].RESEND_API_KEY` remain supported. A nested selected
 `apiKey` takes precedence when the property exists, including null or an empty
 string, which means the selected key is absent. Only an absent nested key
-property permits fallback to the corresponding legacy key.
+property permits fallback to the corresponding root or profile key.
 
 Programmatic operations resolve both files from `options.cwd`, then
 `options.workspaceRoot`, then `process.cwd()`, choosing the first supplied
@@ -397,7 +397,7 @@ Configuration precedence is explicit:
    An explicit null retains the option's existing meaning; it does not select
    the file value again.
 2. `arcane.config.json.mail` supplies nonsecret settings absent from those options.
-3. Legacy `.arcane.env.json` root `MAIL_TLS_CERT_PATH` and `MAIL_TLS_KEY_PATH`
+3. `.arcane.env.json` root `MAIL_TLS_CERT_PATH` and `MAIL_TLS_KEY_PATH`
    supply certificate paths absent from the selected options and config member.
 4. Remaining settings use the defaults above.
 
@@ -452,7 +452,7 @@ non-interactive alternative and rejects a TTY. Each command accepts an optional
 profile argument, defaulting to `mail` independently of `arcane.config.json.mail.profile`.
 Set and delete preserve other JSON settings and profiles; status reports
 existence without returning the key. A new credential is written to the nested
-mail member. An existing legacy credential is updated at its existing location
+mail member. An existing root or profile credential is updated at its existing location
 unless the selected nested key property exists, in which case set updates that
 nested property. Delete removes both representations of only the selected key,
 so an older key cannot reappear through fallback. Other settings and profile
@@ -500,7 +500,7 @@ guidance from the same configuration. It does not require gateway TLS paths.
 Send and serve read each required JSON file once, concurrently when both are
 needed, before consuming their settings. An injected `readCredential` remains
 the credential owner and reads once. With that injection, send reads only
-`arcane.config.json`; serve also reads `.arcane.env.json` for legacy TLS paths
+`arcane.config.json`; serve also reads `.arcane.env.json` for root TLS paths
 without interpreting its unused file credential.
 
 Start the gateway:
@@ -522,7 +522,7 @@ domain, for example `https://mail.example.com:4433/v1/mail`.
 
 Set `arcane.config.json.mail.certPath` to the PEM certificate chain and
 `mail.keyPath` to its PEM private-key file. These settings belong to the listener
-and apply regardless of the selected provider profile. The legacy root
+and apply regardless of the selected provider profile. The root
 `MAIL_TLS_CERT_PATH` and `MAIL_TLS_KEY_PATH` fields in `.arcane.env.json` remain
 fallbacks. Relative certificate paths resolve from the selected configuration
 directory, including explicit programmatic path options; absolute paths are also accepted.

package/docs/reference/protocols.md

@@ -157,16 +157,17 @@ the same browser URLs and saved managed import maps.
 
 Existing `physical-v1` configurations whose first source is `arcane` remain
 supported. The explicit materializer below still refreshes those projections,
-and the default multi-app scaffold retains its existing physical layout. The
+and an explicitly selected multi-app scaffold retains its physical layout. The
 earlier installed routes with virtual `/arcane` destinations also remain
 supported. Selecting `installed-v1`
 does not delete any preexisting workspace files. The separate host-document
 `generateDocumentImportMaps()` API continues to accept an already materialized
 runtime; its input contract is unchanged.
 
-### Optional standalone root application
+### Standalone root application
 
-`appsRoot: "."` selects one application whose `arcane-app.json`,
+Each standalone app's root is its repository root. `appsRoot: "."` selects
+that layout: `arcane-app.json`,
 `arcane-package.json`, entry, and app-owned files occupy the workspace root.
 The declared application ID remains unchanged. `appsRoot: "apps"` continues
 to discover `apps/<id>` and supports the existing integrated and multi-app
@@ -174,29 +175,19 @@ layouts. Entries and include/exclude paths remain relative to the application.
 
 Root HTML uses `<base href="./">`; nested navigable documents use their actual
 depth back to the workspace. Managed bare imports remain the public interface;
-their targets follow the selected npm routes. `arcane import-map` also writes
-root-app navigation pages for the previous `/apps/<id>/` links, preserving
-query strings and fragments. It preserves authored files at those destinations.
-For a direct-installed root PWA it generates the static PWA records at the root,
-so normal static hosting needs no SDK request handler or runtime copy.
-
-To select root-only generated output, set `"legacyAppPaths": false` beside
-`"appsRoot": "."` in `arcane-packager.json`. This optional boolean defaults to
-`true`; it has no effect on the `appsRoot: "apps"` layout. The shared import-map
-refresh, source dev server, package inspection, dry run and package output then
-omit SDK-generated `apps/<id>/` navigation pages, navigation aliases, and the
-legacy PWA worker/offline inventory. Root PWA files and normal managed imports
-remain available. Edit the root configuration before starting `arcane dev`;
-restart an existing server after changing this workspace-level choice.
-
-This option does not change the application ID, stored data, the existing
-default installation ID or an authored `pwa.manifest.id`. It neither deletes
-existing files nor removes authored resources from the app's include/exclude
-selection. Explicitly included files under `apps/<id>/` still serve and package
-as authored resources. Previously installed launch URLs and worker update URLs
-need their old resources to remain available; retain the default compatibility
-output when those URLs still need SDK support. See the
-[root PWA compatibility boundary](pwa.md#root-only-generated-output).
+their targets follow the selected npm routes. `arcane import-map` generates
+enabled static PWA records at the app root, so normal static hosting needs no
+SDK request handler or runtime copy. Managed refresh, development serving,
+inspection, dry run and packaging add no nested `apps/<id>/` navigation pages,
+redirects, or duplicate PWA worker/inventory files. There is no output-retention
+switch for those retired records.
+
+Application identity, stored data, the existing default installation ID and an
+authored `pwa.manifest.id` remain unchanged. Authored resources continue to
+follow the app's include/exclude selection; generation does not delete existing
+files. Published SDK internals stay package-owned under `node_modules`.
+Generated and offline app files are committed, and GitHub Actions consume
+those committed files. See [root generated output](pwa.md#root-generated-output).
 
 Direct-installed root maps expose `arcane-os/modules/<filename>` and
 `arcane-os/entities/<filename>` (including extensions), plus the existing

package/docs/reference/pwa.md

@@ -38,8 +38,9 @@ comes from the selected application entry. The app owns names, icons, colors,
 display preference, routes and descriptions. Use real app icons; the SDK does
 not invent branding or claim that a browser has installed the app.
 
-Manifest URL fields are relative to the application directory. Source delivery
-and packaged delivery retain the app tree at `apps/<id>/`. For packaged output,
+Manifest URL fields are relative to the application directory. Each standalone
+app's root is its repository root. Explicit multi-app source and packaged
+delivery retain the selected app tree at `apps/<id>/`. For multi-app packaged output,
 the default `start_url` is `./apps/<id>/<entry>`, resolved from the generated
 root manifest. The default `id` and `scope` remain `./`, preserving the existing
 deployment-root installation identity. Authored relative URL fields, including
@@ -55,51 +56,30 @@ ordinary static host; it does not copy the installed runtime into `arcane/`.
 The source root defaults its installation ID to `/apps/<id>/` to preserve the
 previous source identity while its start URL and scope move to the root. An
 authored `manifest.id` remains authoritative. Packaged default identity remains
-`./`. Existing `/apps/<id>/` navigation aliases retain query strings and
-fragments and lead to the selected root document. No stored application data is
-rewritten by changing the layout.
-
-Root PWA generation also retains `apps/<id>/arcane-sw.js` and
-`apps/<id>/arcane-offline.json`. These are ordinary generated files served at
-their original URLs, including on a static host. The same canonical worker and
-current inventory use root resource/navigation URLs, rebased for the previous
-scope when deployed beneath a directory. An existing worker's inventory refresh
-can learn the new navigation destinations; the browser can update the worker at
-its retained script URL through normal update and activation. No cache deletion,
-forced activation, user-data migration or application-owned server handler is
-introduced. Offline clients require a later successful connection to receive
-updated files; fixture coverage does not establish a particular installed app's
-actual browser lifecycle.
-
-### Root-only generated output
-
-For a root application, add `"legacyAppPaths": false` to the workspace's
-`arcane-packager.json`, alongside `"appsRoot": "."`. The default is `true`.
-This selects root-only SDK-generated navigation and PWA output in import-map
-refresh, `arcane dev`, package inspection/dry run, and browser packaging:
-
-- The four root PWA files remain generated normally.
-- The SDK generates no `apps/<id>/` navigation pages, legacy worker or legacy
-  offline inventory, and adds no legacy navigation aliases or dev redirects.
+`./`. App identity and saved application data remain unchanged.
+
+### Root generated output
+
+For a standalone application, `appsRoot: "."` places the app at its repository
+root. Import-map refresh, `arcane dev`, package inspection/dry run and browser
+packaging use that layout directly:
+
+- The four root PWA files are generated normally when PWA is enabled.
+- The SDK generates no `apps/<id>/` navigation pages, nested worker or duplicate
+  offline inventory, and adds no redirects for that path family.
+- Runtime resources use the selected npm package paths; no repository-root
+  `arcane/` projection is generated.
 - The default source installation ID remains `/apps/<id>/`, the default
   packaged installation ID remains `./`, and an explicit `manifest.id` remains
-  authoritative. An ID is an installation identifier, not a request to generate
-  a directory. App identity and saved application data remain unchanged.
-- Existing files are left on disk. Explicitly selected authored old-path
-  resources remain in the normal source/package/offline inventory; this setting
-  is not a deletion or migration command.
-
-Restart `arcane dev` after changing this workspace configuration. Omission or
-`true` retains the compatibility behavior described above. The option has no
-effect on apps whose configured `appsRoot` is `"apps"`.
-
-An installed app may still launch an old `/apps/<id>/` URL, and an existing
-worker registration may still update its old script/inventory URL. Disabling
-generation does not redirect those installed clients, unregister their worker,
-clear caches or guarantee their next update. Keep compatibility output enabled
-while old URLs still require SDK support, or supply the required resources
-through the application's own declared files and hosting policy. This SDK
-option alone makes no claim about any existing installation's adoption.
+  authoritative. An ID identifies the installation; it does not generate a
+  directory or a redirect.
+- Authored resources follow their normal include/exclude selection. Generation
+  does not delete existing files, stored application data, or worker caches.
+
+Generated and offline app files are committed. GitHub Actions consume those
+committed files rather than generating them. Actual multi-app workspaces keep
+their explicit `appsRoot: "apps"` layout. This source/package contract does not
+establish any particular installed application's browser lifecycle.
 
 ### Offline resource selection
 

package/docs/reference/sdk-api.md

@@ -3,7 +3,7 @@
 The npm package exposes a Node.js ESM control plane, the portable
 `arcane-os/event-manager`, `arcane-os/logging`, `arcane-os/mail`,
 `arcane-os/preference-store`, `arcane-os/speech-playback`,
-`arcane-os/speech-text`, `arcane-os/ai/tool-text-stream`, and `arcane-os/browser-device` entrypoints, and the browser-only
+`arcane-os/speech-text`, `arcane-os/ai/tool-text-stream`, `arcane-os/ai/twin-cloud`, and `arcane-os/browser-device` entrypoints, and the browser-only
 `arcane-os/pwa`, `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints.
 The `arcane-os/modules/<filename>` and `arcane-os/entities/<filename>` paths
 resolve directly to the existing runtime files, with their actual extension.
@@ -66,6 +66,7 @@ runtime layouts.
 | `arcane-os/pwa` | Nonblocking PWA registration, worker updates, native installation state and a dismissible installation component. |
 | `arcane-os/ai/browser-wasm` | Caller-selected browser-local Wllama inference, complete DBOPFS model storage, streaming, cancellation, and structural tool-call results. |
 | `arcane-os/ai/tool-text-stream` | Shared selected tool-argument text observer for provider integration. |
+| `arcane-os/ai/twin-cloud` | Complete TWiN Cloud requests from Node or a browser with an explicit key/model and shared retry/cancellation behavior. |
 | `arcane-os/ai/browser-speech` | Caller-selected browser-local Whisper STT and Kokoro TTS provider mechanisms, ordinary upstream assets, materialized/native routing, Workers, and cancellation. |
 | `arcane-os/mail` | Portable Mail runtime, durable outbox, complete transport responses, and provider-neutral acceptance contracts. |
 
@@ -121,6 +122,13 @@ 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 |
+| `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 |
+| `openAIResponseFormat()` | function | `arcane-os/ai/twin-cloud` | Shared AI transport integration | Node and Browser |
+| `isAIRequestAbort()` | function | `arcane-os/ai/twin-cloud` | Shared AI transport integration | Node and Browser |
+| `normalizeAIRequestAbort()` | function | `arcane-os/ai/twin-cloud` | Shared AI transport integration | Node and Browser |
 | `APP_BUNDLE_DESCRIPTOR_NAME` | constant | `arcane-os` | Packaging and release bundles | Node |
 | `APP_BUNDLE_EXTENSION` | constant | `arcane-os` | Packaging and release bundles | Node |
 | `APP_BUNDLE_FORMAT` | constant | `arcane-os` | Packaging and release bundles | Node |
@@ -1049,14 +1057,13 @@ async function usevalidateAppConfig(...arguments_) {
 
 Validates one root packager mapping and its fixed shared-route boundaries.
 
-The schema-1 `arcane-packager.json` accepts the optional boolean
-`legacyAppPaths`, normalized to `true` when omitted. With `appsRoot: "."`,
-setting it to `false` omits generated legacy `apps/<id>/` navigation/PWA output
-across managed-map refresh, development serving, inspection and packaging.
-It leaves installation identity and authored file selection unchanged and has
-no effect with `appsRoot: "apps"`. See
-[standalone root applications](protocols.md#optional-standalone-root-application)
-for configuration, retained-file and existing-installation behavior.
+The schema-1 `arcane-packager.json` uses `appsRoot: "."` for standalone apps:
+each app's root is its repository root. Managed-map refresh, development
+serving, inspection and packaging use root app files and direct npm package
+paths without generated nested app redirects or duplicate PWA files.
+Installation identity and authored file selection remain unchanged.
+Explicit `appsRoot: "apps"` supports real multi-app workspaces. See
+[standalone root applications](protocols.md#standalone-root-application).
 
 ### Signature and result
 
@@ -3722,7 +3729,7 @@ actual HTTPS port while preserving the original request path and query. Both lis
 use the selected host.
 
 Source servers default to HTTPS, including localhost; packaged browser previews
-require HTTPS. The legacy `https` option is accepted but `https:false` and
+require HTTPS. The existing `https` option is accepted; `https:false` and
 `tls:false` alone do not disable HTTPS. HTTPS startup reads `.arcane/dev/server-cert.pem` and
 `.arcane/dev/server-key.pem` relative to `workspaceRoot` unless explicit
 `certPath` and `keyPath` are supplied together; relative paths resolve from the
@@ -4184,7 +4191,7 @@ The operation refreshes the selected authored descriptor's `arcane-package.json`
 projection and managed import maps under one development-refresh lock, then
 releases that lock before opening the selected source listener or listeners.
 It returns their application endpoints and shared shutdown
-lifecycle. Legacy package-only apps remain unchanged. The operation generates
+lifecycle. Package-only apps remain unchanged. The operation generates
 no packaged output; enabled PWA manifests
 are served directly from the selected source resources.
 
@@ -7636,6 +7643,265 @@ import {readArcaneDeveloperMode} from 'arcane-os/logging';
 const developerMode=readArcaneDeveloperMode();
 ```
 
+## fetchRequest()
+
+### Overview
+
+Makes one complete TWiN Cloud request with explicit caller-owned credentials
+and model selection. This named function is independent of the browser
+`AI` instance method with the same name.
+
+### Signature and result
+
+```text
+async fetchRequest(options={})
+```
+
+Import the named function from `arcane-os/ai/twin-cloud`. Supply `twinKey`,
+`model`, and complete `messages`. The function requires the explicit model;
+it reads no browser preference or default-model selection. Optional
+`structuredOutput:true` or `'json'` sends `response_format:{type:'json_object'}`.
+A supplied JSON Schema sends `response_format:{type:'json_schema',
+json_schema:{name:'structured_response',strict:true,schema:...}}`. Omission
+leaves structured output off. Optional `tools`, `toolChoice`,
+`parallelToolCalls`, and `reasoningEffort` map to their existing TWiN wire
+fields. Tool fields are sent when `tools` is nonempty; a nonempty
+`reasoningEffort` is forwarded without selecting a default. No default output
+cap, tool execution, or provider-response envelope validation is added.
+
+The return value is the entire parsed provider JSON, not only one choice or
+message. Optional callbacks are `onRequest(request,id,metadata)` before
+dispatch and `onResponse(response,id,false)` before successful return;
+`id` defaults to `Date.now()` and may be supplied by the caller. Request metadata
+is `{operation:'fetch',transport:'http',destination:'https://inference.do-ai.run/v1/chat/completions'}`.
+Both callbacks are awaited, and callback
+failures propagate. Credentials are supplied to transport rather than added to
+the message or response callback payload.
+
+### Availability and normalization
+
+**Node and Browser; Cloud transport.** Uses standard Fetch and cancellation,
+without DOM, browser profiles, user singletons, or storage initialization.
+Import starts no request. HTTP `429` whose message contains `overload`
+(case-insensitive) waits
+`3000` milliseconds and retries the complete request; other HTTP failures
+throw their complete parsed JSON or text bodies. A missing key throws
+`AI_PROVIDER_NOT_CONFIGURED`; a missing model throws `TypeError`. `signal`
+cancellation during transport, body reading, retry waiting,
+or callback settlement prevents successful return and uses
+`ARCANE_AI_REQUEST_ABORTED`. No request history, DBOPFS write, or recurring
+model context is retained. The caller owns persistence and key configuration.
+See [TWiN Cloud](ai/twin-cloud.md) for a complete Node JSON-schema example and
+the unchanged browser AI interface.
+
+### Example
+
+```javascript
+import serverConfig from './server-config.json' with {type: 'json'};
+import {fetchRequest} from 'arcane-os/ai/twin-cloud';
+
+const response = await fetchRequest({
+    twinKey: serverConfig.twinKey,
+    model: 'openai-gpt-oss-20b',
+    messages: [{role: 'user', content: 'Describe a moon-powered toaster.'}]
+});
+
+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.
+
+## fetchHTTPResponse()
+
+### Overview
+
+Shared low-level HTTP owner used by browser AI and the focused TWiN API.
+Ordinary TWiN callers use `fetchRequest()` instead.
+
+### Signature and result
+
+```text
+async fetchHTTPResponse(url,options)
+```
+
+Returns the successful Fetch `Response` without consuming its body. Both URL
+and Fetch options are caller-supplied; this helper adds no key, model, or
+request envelope. Non-success responses are read completely as JSON when the
+content type contains `application/json`, otherwise as text. Only status 429
+with an overload message repeats after 3000 ms; other error bodies are thrown.
+
+### Availability and normalization
+
+**Node and Browser.** Exported from `arcane-os/ai/twin-cloud` for shared SDK
+integration. `options.signal` cancels Fetch and the overload wait and is checked
+after response/error-body reads. Cancellation uses
+`ARCANE_AI_REQUEST_ABORTED`. Overload warnings use the existing shared logger.
+
+### Example
+
+```javascript
+import {fetchHTTPResponse} from 'arcane-os/ai/twin-cloud';
+
+// The integration supplies its selected endpoint and complete Fetch options.
+const response = await fetchHTTPResponse(endpoint, requestOptions);
+```
+
+## fetchJSONResponse()
+
+### Overview
+
+Shared complete JSON-body reader built on `fetchHTTPResponse()`.
+
+### Signature and result
+
+```text
+async fetchJSONResponse(url,options)
+```
+
+Returns the full parsed JSON value. A successful response whose content type
+does not contain `application/json` throws `TypeError`; JSON parser failures
+propagate. The helper does not select choices or validate a provider envelope.
+
+### Availability and normalization
+
+**Node and Browser.** Exported from `arcane-os/ai/twin-cloud` for shared SDK
+integration; it retains the HTTP owner's retry/cancellation behavior and checks
+cancellation again after parsing. Ordinary callers use `fetchRequest()`.
+
+### Example
+
+```javascript
+import {fetchJSONResponse} from 'arcane-os/ai/twin-cloud';
+
+// The integration supplies its selected endpoint and complete Fetch options.
+const completion = await fetchJSONResponse(endpoint, requestOptions);
+```
+
+## structuredOutputFormat()
+
+### Overview
+
+Normalizes the existing AI structured-output option without rewriting a schema.
+
+### Signature and result
+
+```text
+structuredOutputFormat(value=false)
+```
+
+False, null, and undefined return null. True and `'json'` return `'json'`.
+A plain object with `Object.prototype` or a null prototype is returned
+unchanged. Other values throw `AI_STRUCTURED_OUTPUT_INVALID`.
+
+### Availability and normalization
+
+**Node and Browser.** Synchronous helper exported from
+`arcane-os/ai/twin-cloud`; performs no network or storage operation.
+
+### Example
+
+```javascript
+import {structuredOutputFormat} from 'arcane-os/ai/twin-cloud';
+
+const format = structuredOutputFormat({
+    type: 'object',
+    properties: {text: {type: 'string'}}
+});
+```
+
+## openAIResponseFormat()
+
+### Overview
+
+Maps a normalized structured-output choice to chat-completion wire fields.
+
+### Signature and result
+
+```text
+openAIResponseFormat(format)
+```
+
+`'json'` becomes `{type:'json_object'}`; a supplied schema becomes
+`{type:'json_schema',json_schema:{name:'structured_response',strict:true,schema:format}}`.
+A disabled format returns null. Use `structuredOutputFormat()` first to
+normalize the public option; this mapper does not validate schema contents.
+
+### Availability and normalization
+
+**Node and Browser.** Synchronous helper exported from
+`arcane-os/ai/twin-cloud`, shared with browser AI and performing no I/O.
+
+### Example
+
+```javascript
+import {structuredOutputFormat, openAIResponseFormat} from 'arcane-os/ai/twin-cloud';
+
+const responseFormat = openAIResponseFormat(structuredOutputFormat(true));
+// {type: 'json_object'}
+```
+
+## isAIRequestAbort()
+
+### Overview
+
+Recognizes the existing AI request cancellation forms.
+
+### Signature and result
+
+```text
+isAIRequestAbort(error,signal)
+```
+
+Returns a boolean: true when the signal is aborted, the error name is
+`AbortError`, or its code is `ARCANE_REQUEST_ABORTED`,
+`ARCANE_AI_REQUEST_ABORTED`, or `AI_REQUEST_ABORTED`.
+
+### Availability and normalization
+
+**Node and Browser.** Synchronous helper exported from
+`arcane-os/ai/twin-cloud`; it neither changes nor aborts the supplied operation.
+
+### Example
+
+```javascript
+import {isAIRequestAbort} from 'arcane-os/ai/twin-cloud';
+
+const controller = new AbortController();
+controller.abort();
+const cancelled = isAIRequestAbort(undefined, controller.signal);
+```
+
+## normalizeAIRequestAbort()
+
+### Overview
+
+Keeps cancellation under the shared AI error code while preserving its cause.
+
+### Signature and result
+
+```text
+normalizeAIRequestAbort(error)
+```
+
+An existing `ARCANE_AI_REQUEST_ABORTED` error is returned unchanged. Otherwise
+the result is an Error named `AbortError`, with code
+`ARCANE_AI_REQUEST_ABORTED`, message `The AI request was cancelled.`, and the
+supplied value as its cause. The helper returns the error; it does not throw it.
+
+### Availability and normalization
+
+**Node and Browser.** Synchronous helper exported from
+`arcane-os/ai/twin-cloud`; creates no request, storage, or user state.
+
+### Example
+
+```javascript
+import {normalizeAIRequestAbort} from 'arcane-os/ai/twin-cloud';
+
+const cancelled = normalizeAIRequestAbort(new DOMException('Cancelled', 'AbortError'));
+```
+
 ## Data export subpaths
 
 The package also exposes eight JSON Schemas (including `arcane-os/schemas/event-stack.json`) and its package manifest. These are data contracts, not callable JavaScript members. See [schema contracts](../architecture.md) and the files under `schemas/`.