arcane-os 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.30.0
+
+- Add the public `arcane-os/ai/twin-cloud` subpath with stateless `fetchRequest`
+  for Node and browser callers. Supply the TWiN key, model, messages, optional
+  structured-output schema and cancellation signal explicitly. The result is
+  the complete parsed provider completion, with no browser startup, saved
+  conversation, hidden model default or output cap.
+- Share the existing TWiN HTTP, structured JSON, overload retry and cancellation
+  implementation with the browser AI owner while preserving its public methods
+  and lifecycle. Only overload responses with HTTP 429 use the existing
+  three-second retry; other failures retain their complete provider response.
+
+## 0.29.1
+
+- Preserve complete long and non-ASCII filenames in application release bundles
+  through standard per-file PAX path extensions. Public bundle creation and
+  verification retain logical payload paths and complete file content without
+  application-side renaming. Ordinary USTAR representation remains supported,
+  and the existing SDK-version metadata contract is unchanged. Bundles using
+  extended paths require the updated SDK reader or another PAX-capable reader.
+- Preserve application-authored resource URL queries, including `v`, encoded
+  and repeated fields, empty query segments, and fragments. Import-map refresh,
+  serving, packaging, and PWA delivery now change only SDK-owned `arcaneVersion`
+  fields through the existing shared transformer.
+
 ## 0.29.0
 
 - Add `legacyAppPaths: false` to `arcane-packager.json` for root applications

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.29.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.30.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -604,9 +604,13 @@ prior file until the replacement is complete. Cancellation or failure before
 commit restores the prior output when that can be done without overwriting a
 concurrent change. A conflicting or uncertain path is preserved for inspection.
 
-The archive uses the documented USTAR+gzip structure and publishes its v1 JSON
-contract at `arcane-os/schemas/arcane-app-bundle.json`. When the user explicitly
-selects bundle verification, it rejects malformed archives, links, devices,
+The archive uses USTAR+gzip with per-file PAX path extensions for long or
+non-ASCII filenames and publishes its v1 JSON contract at
+`arcane-os/schemas/arcane-app-bundle.json`. Logical filenames and content remain
+complete; ordinary USTAR paths retain their existing representation, and bundle
+metadata keeps its existing SDK-version matching contract. Readers must support
+PAX path extensions to consume bundles that need them. When the
+user explicitly selects bundle verification, it rejects malformed archives, links, devices,
 unsafe or colliding paths, unsupported archive members, trailing data, and
 inconsistent descriptor or inventory structure. These checks reject corrupt
 selected artifacts; they do not impose byte-count, hash, provenance, or

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

@@ -0,0 +1,230 @@
+import Is from 'strong-type';
+import {arcaneLogging} from '../logging.mjs';
+
+const is = new Is(false);
+const twinChatURL = 'https://inference.do-ai.run/v1/chat/completions';
+
+/** A stateless TWiN request; browser AI shares the HTTP and format owners below. */
+export async function fetchRequest({
+    twinKey,
+    model,
+    messages = [],
+    structuredOutput = false,
+    tools = [],
+    toolChoice = 'auto',
+    parallelToolCalls,
+    reasoningEffort,
+    signal = null,
+    id = Date.now(),
+    onRequest = function observeTWiNRequest(){},
+    onResponse = function observeTWiNResponse(){}
+} = {}){
+    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 fetchRequest requires an explicit model.');
+    }
+
+    const request = {model, messages, stream:false};
+    const format = structuredOutputFormat(structuredOutput);
+    if(format){
+        request.response_format = openAIResponseFormat(format);
+    }
+    if(tools.length){
+        request.tools = tools;
+        request.tool_choice = toolChoice;
+        if(parallelToolCalls !== undefined){
+            request.parallel_tool_calls = parallelToolCalls;
+        }
+    }
+    if(reasoningEffort){
+        request.reasoning_effort = reasoningEffort;
+    }
+
+    try{
+        await onRequest(
+            request,
+            id,
+            {operation:'fetch', transport:'http', destination:twinChatURL}
+        );
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        const response = await fetchJSONResponse(
+            twinChatURL,
+            {
+                method:'POST',
+                credentials:'omit',
+                headers:{
+                    'Content-Type':'application/json',
+                    Authorization:`Bearer ${twinKey}`
+                },
+                body:JSON.stringify(request),
+                ...(signal ? {signal} : {})
+            }
+        );
+        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'
+        || error?.code === 'ARCANE_REQUEST_ABORTED'
+        || error?.code === 'ARCANE_AI_REQUEST_ABORTED'
+        || error?.code === 'AI_REQUEST_ABORTED';
+}
+
+export function normalizeAIRequestAbort(error){
+    if(error?.code === 'ARCANE_AI_REQUEST_ABORTED'){
+        return error;
+    }
+    const normalized = new Error('The AI request was cancelled.', {cause:error});
+    normalized.name = 'AbortError';
+    normalized.code = 'ARCANE_AI_REQUEST_ABORTED';
+    return normalized;
+}
+
+export function structuredOutputFormat(value = false){
+    if(value === false || value === null || value === undefined){
+        return null;
+    }
+    if(value === true || value === 'json'){
+        return 'json';
+    }
+    if(
+        is.object(value)
+        && !is.array(value)
+        && (
+            Object.getPrototypeOf(value) === Object.prototype
+            || Object.getPrototypeOf(value) === null
+        )
+    ){
+        return value;
+    }
+    const error = new TypeError(
+        'AI structured output must be enabled with true, json, or a JSON Schema object.'
+    );
+    error.code = 'AI_STRUCTURED_OUTPUT_INVALID';
+    throw error;
+}
+
+export function openAIResponseFormat(format){
+    if(format === 'json'){
+        return {type:'json_object'};
+    }
+    if(format){
+        return {
+            type:'json_schema',
+            json_schema:{name:'structured_response', strict:true, schema:format}
+        };
+    }
+    return null;
+}
+
+/** Shared with browser streaming; consume no successful body at this boundary. */
+export async function fetchHTTPResponse(url, options){
+    const {signal} = options;
+    const retryDelayMs = 3000;
+    try{
+        while(true){
+            if(signal?.aborted){
+                throw normalizeAIRequestAbort(signal.reason);
+            }
+            const response = await fetch(url, options);
+            if(signal?.aborted){
+                throw normalizeAIRequestAbort(signal.reason);
+            }
+            if(response.ok){
+                return response;
+            }
+            const contentType = response.headers.get('content-type') || '';
+            const error = contentType.includes('application/json')
+                ? await response.json()
+                : await response.text();
+            if(signal?.aborted){
+                throw normalizeAIRequestAbort(signal.reason);
+            }
+            const message = is.string(error)
+                ? error
+                : error?.error?.message ?? error?.message;
+            if(
+                response.status !== 429
+                || !is.string(message)
+                || !message.toLowerCase().includes('overload')
+            ){
+                throw error;
+            }
+            arcaneLogging.warn(
+                `${message}\nRetrying in ${retryDelayMs / 1000} seconds`,
+                error
+            );
+            await new Promise(function waitForOverloadRetry(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();
+                }
+            });
+        }
+    }catch(error){
+        if(isAIRequestAbort(error, signal)){
+            throw normalizeAIRequestAbort(error);
+        }
+        throw error;
+    }
+}
+
+/** Return the entire parsed completion without selecting or rewriting choices. */
+export async function fetchJSONResponse(url, options){
+    const {signal} = options;
+    try{
+        const response = await fetchHTTPResponse(url, options);
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        const contentType = response.headers.get('content-type') || '';
+        if(!contentType.includes('application/json')){
+            throw new TypeError(
+                `AI request returned ${contentType || 'an unknown content type'} instead of JSON.`
+            );
+        }
+        const completion = await response.json();
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        return completion;
+    }catch(error){
+        if(isAIRequestAbort(error, signal)){
+            throw normalizeAIRequestAbort(error);
+        }
+        throw error;
+    }
+}

package/docs/architecture.md

@@ -273,16 +273,31 @@ External repository delivery adds a distinct schema-1
 `arcane-app-release-bundle` envelope. Bundle creation uses an authored schema-2
 `arcane-app.json`; a synthesized package or registry projection remains valid for integrated
 packaging but is not used for an external bundle. The
-archive contains exactly `ARCANE_APP_BUNDLE.json`, canonical `arcane-app.json`,
+logical file inventory contains exactly `ARCANE_APP_BUNDLE.json`, canonical `arcane-app.json`,
 `payload/ARCANE_APP_RELEASE.json`, and the release inventory beneath `payload/`
 in that order. The envelope adds no repository-only source or build tooling
 beyond that selected release inventory. Individual apps remain responsible for
 their authored source policy.
 
-The bundle contract uses the documented USTAR+gzip structure. Explicit bundle
-verification parses the selected archive without extraction and rejects
-genuinely malformed structures, unsafe or colliding paths, unsupported members,
-trailing data, and incompatible bundle generations. These corrupt-artifact
+The bundle contract retains schema 1 and the `ustar+gzip` format identifier.
+Ordinary representable ASCII paths use the existing USTAR headers. Long paths
+and non-ASCII names use a [POSIX PAX](https://docs.oracle.com/cd/E86824_01/html/E54763/pax-1.html)
+per-file `x` header containing the complete
+UTF-8 `path`, immediately before that file's regular header and content. This
+transport framing is not a payload member and never appears in the logical
+inventory or `readFile()` results. Path spelling and file content remain unchanged;
+the existing portable-path rules still apply. The public
+`createCanonicalUstarHeader()` helper remains a single USTAR header and retains
+its format-local field limits; complete bundles use `createAppReleaseBundle()`.
+
+The bundle reader consumes these `path` extensions for the following file only,
+as well as ordinary USTAR entries. Other PAX attributes and archive member
+types remain outside this bundle profile. Older SDK readers without PAX support
+cannot read bundles that require these extensions; update the consuming SDK
+before importing one. The existing same-SDK-version bundle condition is unchanged.
+Explicit bundle verification parses the selected archive without extraction and
+rejects genuinely malformed structures, unsafe or colliding paths, unsupported
+members, and incompatible bundle generations. These corrupt-artifact
 checks do not create byte-count, content-hash, provenance, or admission gates
 for ordinary development, packaging, serving, or running.
 

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

@@ -1,8 +1,125 @@
 # TWiN Cloud: one request
 
-TWiN Cloud is the high-level `AI.js` default remote LLM service, named `TWIN`.
-Speech stays on device and does not use the TWiN access key. This guide uses the
-same managed browser imports as the [browser speech quick start](browser-speech.md).
+Use `fetchRequest` from `arcane-os/ai/twin-cloud` for a complete TWiN Cloud
+request in Node or a browser with an explicit key and model. It imports no
+browser profile, DOM, user singleton, or storage, and starts no work on import.
+The existing browser `AI.js` interface remains available for applications that
+already use its provider selection, lifecycle, and speech. TWiN Cloud is that
+interface's default remote LLM service, named `TWIN`; speech stays on device
+and does not use the TWiN access key.
+
+## Node: explicit key, model, and structured result
+
+Install the published `arcane-os` package in the Node project. Keep the key in
+the application's existing server configuration, outside source control and
+diagnostics. In this example, `server-config.json` is that caller-owned local
+configuration file with a `twinKey` property; add its exact path to `.gitignore`
+before creating it. The SDK does not discover or write this file.
+
+```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: 'Explain why the moon-powered toaster keeps burning breakfast. Return HTML and plain text.'
+    }],
+    structuredOutput: {
+        type: 'object',
+        properties: {
+            html: {type: 'string'},
+            text: {type: 'string'}
+        },
+        required: ['html', 'text'],
+        additionalProperties: false
+    }
+});
+
+console.log(response);
+```
+
+`model` is required and remains exactly the supplied identifier. This function
+does not select the browser profile's default model. The example's prompt and
+`html`/`text` schema are caller-owned data, not SDK business logic. Changing
+those fields changes the requested result without changing the SDK.
+
+The resolved value is the complete parsed provider JSON, including every
+choice and provider field. The SDK does not extract only the first message,
+parse its content into a second object, or replace the response with an
+application-specific record. The supplied schema becomes
+`response_format: {type:'json_schema', json_schema:{name:'structured_response',
+strict:true, schema:...}}`. `structuredOutput:true` or `'json'` instead selects
+`response_format:{type:'json_object'}`; omission leaves structured output off.
+
+## Shared request behavior
+
+The focused API accepts complete `messages`, optional `tools`, `toolChoice`,
+`parallelToolCalls`, and `reasoningEffort` in addition to the explicit
+`twinKey` and `model`. Tool options use the existing chat-completion wire fields
+`tools`, `tool_choice`, and `parallel_tool_calls` when `tools` is nonempty.
+A supplied nonempty `reasoningEffort` uses the provider's `reasoning_effort`
+field; omission preserves its default. No output limit is added by this API.
+The function neither executes tools nor adds provider-response envelope
+validation.
+
+Optional `id`, `onRequest(request,id,metadata)`, and
+`onResponse(response,id,false)` follow the complete-response `AI.fetchRequest`
+callback shape. The request callback runs before dispatch; the response
+callback receives the complete parsed result before it is returned. Omitted
+`id` uses `Date.now()`; request metadata is
+`{operation:'fetch',transport:'http',destination:'https://inference.do-ai.run/v1/chat/completions'}`.
+The key is
+transport authentication, not part of either callback's message payload. Keep
+credentials out of application logging as well.
+
+Only HTTP `429` with a message containing `overload` (case-insensitive) repeats automatically,
+after `3000` milliseconds. Another overload repeats the same complete request;
+other HTTP failures do not become an automatic retry loop. Pass a fresh
+`AbortController`'s `signal` and call `abort()` to cancel. Cancellation during
+the request, response-body read, retry wait, or callback settlement prevents
+successful result delivery and rejects with `ARCANE_AI_REQUEST_ABORTED`.
+Other HTTP failures throw the complete parsed JSON error body or text body.
+A missing key uses `AI_PROVIDER_NOT_CONFIGURED`, a missing explicit model
+throws `TypeError`, and an unsupported `structuredOutput` input uses
+`AI_STRUCTURED_OUTPUT_INVALID`.
+
+The SDK retains no request or response history between calls and uses no
+DBOPFS, chat entity, or memory extraction. Each call's `messages` are its
+complete caller-supplied context. The caller decides whether and how to keep
+the result; this stateless transport adds no saved conversation or migration.
+
+Browser applications can use this same focused import through their generated
+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.
+
+### 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.
+
+| Export | Contract |
+| --- | --- |
+| `fetchHTTPResponse(url,options)` | Uses the caller's Fetch options, overload retry and cancellation; returns a successful `Response` with its body unconsumed. |
+| `fetchJSONResponse(url,options)` | Uses that HTTP owner, requires `application/json`, and returns the complete parsed body without selecting choices. |
+| `structuredOutputFormat(value=false)` | Maps false/null/undefined to null, true/`'json'` to `'json'`, and preserves a supplied plain JSON Schema object. Other inputs use `AI_STRUCTURED_OUTPUT_INVALID`. |
+| `openAIResponseFormat(format)` | Maps the normalized value to `json_object`, strict `json_schema` named `structured_response`, or null. |
+| `isAIRequestAbort(error,signal)` | Recognizes an aborted signal, `AbortError`, or the existing Arcane AI/request cancellation codes. |
+| `normalizeAIRequestAbort(error)` | Preserves an existing `ARCANE_AI_REQUEST_ABORTED` error or creates that `AbortError` with the original value as its cause. |
+
+These helpers start no work on import. HTTP helpers require explicit URL and
+options; they do not add a key, model, browser state, or retained conversation.
+Overload warnings use the shared console logger and preserve the complete
+provider error.
+
+## Existing browser AI interface
+
+The following browser example uses the same managed imports as the
+[browser speech quick start](browser-speech.md).
 
 ## Install and import
 

package/docs/reference/asset-versioning.md

@@ -3,7 +3,7 @@
 Applications that enable [PWA delivery](pwa.md) use clean local resource URLs.
 Their generated offline manifest and service worker own the selected application
 and SDK release information. In that mode, the delivery transformer removes
-both `v` and `arcaneVersion`, preserving other query fields and fragments.
+only the SDK-owned `arcaneVersion` field, preserving authored query fields and fragments.
 The behavior below continues to apply when PWA delivery is disabled and to native
 packages. Workspace runtime materialization remains usable by either target;
 the selected browser delivery applies its PWA URL policy.
@@ -15,11 +15,12 @@ SDK package metadata, not a timestamp, content measurement, or application
 constant.
 
 For example, an existing `./arcane/modules/HTMLImport.js?v=6#module` reference
-becomes `./arcane/modules/HTMLImport.js?arcaneVersion=${version}#module`.
-`arcaneVersion` is the sole resource version field: transformation removes `v`,
-updates the first existing `arcaneVersion`, and removes duplicate version fields.
-Regenerating for another SDK release replaces that version value. Unrelated
-query fields, their spelling, and fragments remain intact.
+becomes `./arcane/modules/HTMLImport.js?v=6&arcaneVersion=${version}#module`.
+`arcaneVersion` is the SDK's resource version field: transformation updates its
+first existing value and removes duplicate `arcaneVersion` fields, or appends it
+when absent. Regenerating for another SDK release replaces only that SDK value.
+Authored fields, including `v`, encoded keys and values, repeated or empty query
+segments, their source spelling, and fragments remain intact.
 
 ## Public tooling
 

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

@@ -78,6 +78,7 @@ version; WebKitGTK availability must not be generalized to macOS.
 | Read host identity, capabilities, storage, preferences, appearance, or platform state | `globalThis.Arcane` | **Cross-host** where the method is implemented and admitted | Promise behavior and `Arcane.Error` are normalized. Result fields are normalized unless the method explicitly documents a platform-dependent snapshot. |
 | 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. Shared structured-output mapping, overload-only HTTP 429 retry after 3000 ms, and cancellation match browser TWiN transport. No browser profile, AI/user singleton, DBOPFS, or retained request history is created. |
 | Use speech through one application helper | `/arcane/modules/AI.js` and `Arcane.speech` | **Browser** or **Native** | The helper keeps audio on device: Whisper owns STT and Kokoro owns TTS. It automatically cleans only the outbound speech-input copy and normalizes application-facing audio/text behavior while browser and native 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. |
@@ -240,6 +241,14 @@ snapshot.
 
 ### Provider-native within an Arcane boundary
 
+[`arcane-os/ai/twin-cloud`](ai/twin-cloud.md) accepts an explicit `twinKey` and
+`model`, with the same named `fetchRequest` import in Node and managed browsers.
+It preserves complete provider response JSON while mapping the supplied
+structured-output, tool, and reasoning options to the TWiN wire contract.
+The SDK adds no output cap or persisted context. Cancellation applies during
+request, body read, overload retry wait, and callback settlement. The existing
+profile-backed browser `AI.js` entry and its lifecycle remain separate.
+
 Direct `Arcane.ollama.chat()`, `generate()`, `show()`, `embed()`, and lifecycle
 methods return complete Ollama-compatible envelopes. Arcane still owns error
 normalization, chunk correlation, and host transport, but it does

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/*"
@@ -464,14 +464,14 @@
       "name": "createAppReleaseBundle",
       "displayName": "createAppReleaseBundle()",
       "kind": "function",
-      "signature": "async createAppReleaseBundle({ receipt, releaseRoot, outputPath, overwrite=false, signal, onEvent }={})",
+      "signature": "async createAppReleaseBundle({releaseRoot, appDescriptor, outputPath, overwrite=false, signal, onEvent}={})",
       "entrypoints": [
         "arcane-os",
         "arcane-os/release-bundle"
       ],
       "primaryImport": "arcane-os",
       "group": "Packaging and release bundles",
-      "summary": "Writes one deterministic USTAR+gzip external application bundle from the selected authored release state.",
+      "summary": "Writes one deterministic USTAR+gzip external application bundle, using per-file POSIX PAX path extensions for complete long or non-ASCII filenames.",
       "availability": "Node",
       "protocol": "SDK packager and deterministic bundle contract",
       "normalization": "Normalized SDK validation with complete canonical archive and release content"
@@ -2164,7 +2164,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Packaging and release bundles",
-      "summary": "Parses and authenticates one deterministic app bundle without extraction.",
+      "summary": "Parses one deterministic app bundle without extraction, supporting ordinary USTAR entries and complete per-file POSIX PAX paths within the existing same-SDK-version contract.",
       "availability": "Node",
       "protocol": "SDK packager and deterministic bundle contract",
       "normalization": "Normalized SDK validation with complete canonical archive and release content"
@@ -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"
     }
   ]
 }