arcane-os 0.29.0 → 0.30.0

package/docs/reference/pwa.md

@@ -150,9 +150,10 @@ The same bootstrap starts one initially hidden `pwa-install.html` component with
 the generated manifest's app name. Component loading and worker registration
 proceed independently.
 
-The selected PWA browser delivery removes `v` and `arcaneVersion` from actual
-local resource references, including the managed import map. Other query fields,
-fragments, source spelling and unrelated payloads are preserved. The offline
+The selected PWA browser delivery removes only SDK-owned `arcaneVersion` fields
+from actual local resource references, including the managed import map. Authored
+fields such as `v`, encoded and repeated fields, empty query segments, fragments,
+source spelling and unrelated payloads are preserved. The offline
 manifest now carries release information. Non-PWA and native delivery retain
 the [existing asset version contract](asset-versioning.md).
 

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 |
@@ -629,12 +637,17 @@ async function previewNextPrerelease(workspaceRoot) {
 
 ### Overview
 
-Writes one deterministic USTAR+gzip external application bundle from the selected authored release state.
+Writes one deterministic USTAR+gzip external application bundle from the selected
+authored release state. Long or non-ASCII filenames use per-file POSIX PAX `path`
+extensions, preserving their complete UTF-8 spelling and file content. Ordinary
+USTAR entries remain unchanged. Metadata framing is excluded from the manifest's
+logical file inventory. Existing portable-path rules, schema 1, and the
+`ustar+gzip` format identifier remain unchanged.
 
 ### Signature and result
 
 ```text
-async createAppReleaseBundle({ receipt, releaseRoot, outputPath, overwrite=false, signal, onEvent }={})
+async createAppReleaseBundle({releaseRoot, appDescriptor, outputPath, overwrite=false, signal, onEvent}={})
 ```
 
 Import it from `arcane-os` or `arcane-os/release-bundle`. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.
@@ -658,6 +671,9 @@ async function usecreateAppReleaseBundle(...arguments_) {
 ### Overview
 
 Builds the exact 512-byte canonical USTAR header for one validated bundle entry.
+This low-level helper remains a single regular-file header with the USTAR field
+limits. Use `createAppReleaseBundle()` to encode complete long or Unicode paths;
+the bundle writer supplies PAX framing where needed.
 
 ### Signature and result
 
@@ -1104,7 +1120,14 @@ async function useverifyApp(...arguments_) {
 
 ### Overview
 
-Parses and authenticates one deterministic app bundle without extraction.
+Parses one deterministic app bundle without extraction and checks its structural
+manifest and complete logical file inventory. It supports ordinary USTAR entries
+and per-file POSIX PAX `path` extensions. The complete extended path is used by
+`files` and `readFile()`; the metadata and regular-header placeholder are not
+payload files. Malformed or orphaned PAX records produce `ARCANE_BUNDLE_INVALID`.
+Other PAX attributes and archive member types remain unsupported. The existing
+same-SDK-version condition remains unchanged. An older reader without PAX support
+must be updated before importing a bundle that requires these path extensions.
 
 ### Signature and result
 
@@ -7621,6 +7644,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/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -38,6 +38,7 @@
     "./speech-text": "./browser-runtime/speech-text.mjs",
     "./ai/browser-wasm": "./browser-runtime/ai/browser-wasm.mjs",
     "./ai/tool-text-stream": "./browser-runtime/ai/tool-text-stream.mjs",
+    "./ai/twin-cloud": "./browser-runtime/ai/twin-cloud.mjs",
     "./ai/browser-speech": "./browser-runtime/ai/browser-speech.mjs",
     "./mail": "./src/mail-api.mjs",
     "./testing": "./src/testing.mjs",
@@ -85,7 +86,7 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/modal.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/update-check.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/modal.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/twin-cloud.test.mjs test/update-check.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",

package/runtime/arcane/modules/AI.js

@@ -16,6 +16,14 @@ import {
 } from './AIProviderRuntime.js';
 import {normalizeOllamaModelIdentifier} from './OllamaModelIdentifier.js';
 import {arcaneLogging} from 'arcane-os/logging';
+import {
+    fetchHTTPResponse,
+    fetchJSONResponse,
+    isAIRequestAbort,
+    normalizeAIRequestAbort,
+    structuredOutputFormat as normalizeStructuredOutput,
+    openAIResponseFormat
+} from 'arcane-os/ai/twin-cloud';
 import {MarkdownSpeech,stripSpeechFormatting} from 'arcane-os/speech-text';
 import {prepareSpeech} from './PreparedSpeech.js';
 import {createToolTextObserver} from 'arcane-os/ai/tool-text-stream';
@@ -121,24 +129,6 @@ function aiInitializationError(code,reason,message){
     return error;
 }
 
-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';
-}
-
-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;
-}
-
 function normalizeAIReasoningEffort(value){
     if(value===undefined||value===null||value===''){
         return '';
@@ -3776,69 +3766,6 @@ class AI {
         return true;
     }
 
-    async #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;
-        }
-    }
-
     #nativeOllama(){
         const client=globalThis.Arcane?.ollama;
 
@@ -4171,48 +4098,6 @@ class AI {
         ];
     }
 
-    #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;
-    }
-
-    #openAIResponseFormat(structuredOutputFormat){
-        if(structuredOutputFormat==='json'){
-            return {type:'json_object'};
-        }
-        if(structuredOutputFormat){
-            return {
-                type:'json_schema',
-                json_schema:{
-                    name:'structured_response',
-                    strict:true,
-                    schema:structuredOutputFormat
-                }
-            };
-        }
-        return null;
-    }
-
     async #reportRequest(requestHandler,request,id,metadata){
         if(!is.function(requestHandler)){
             throw new TypeError('AI onRequest callback must be a function.');
@@ -4762,7 +4647,7 @@ class AI {
             if(signal?.aborted){
                 throw normalizeAIRequestAbort();
             }
-            const structuredOutputFormat=this.#structuredOutputFormat(
+            const structuredOutputFormat=normalizeStructuredOutput(
                 structuredOutput
             );
 
@@ -4776,7 +4661,7 @@ class AI {
         }
 
         if(structuredOutputFormat){
-            request.response_format=this.#openAIResponseFormat(
+            request.response_format=openAIResponseFormat(
                 structuredOutputFormat
             );
         }
@@ -4970,7 +4855,7 @@ class AI {
             destination:this.url
         });
         const body = JSON.stringify(request);
-        const response=await this.#fetchHTTPResponse(
+        const response=await fetchHTTPResponse(
             this.url,
             {
                 method:'POST',
@@ -5622,7 +5507,7 @@ class AI {
         if(signal?.aborted){
             throw normalizeAIRequestAbort();
         }
-        const structuredOutputFormat=this.#structuredOutputFormat(structuredOutput);
+        const structuredOutputFormat=normalizeStructuredOutput(structuredOutput);
 
         const normalizedReasoningEffort=normalizeAIReasoningEffort(
             reasoningEffort===undefined?this.reasoningEffort:reasoningEffort
@@ -5634,7 +5519,7 @@ class AI {
         }
 
         if(structuredOutputFormat){
-            request.response_format=this.#openAIResponseFormat(
+            request.response_format=openAIResponseFormat(
                 structuredOutputFormat
             );
         }
@@ -5718,7 +5603,7 @@ class AI {
             destination:this.url
         });
         const body = JSON.stringify(request);
-        const response=await this.#fetchHTTPResponse(
+        const responseJSON=await fetchJSONResponse(
             this.url,
             {
                 method:'POST',
@@ -5729,36 +5614,11 @@ class AI {
             }
         );
 
-        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.`
-            );
-        }
-
-        let responseJSON;
-        try{
-            responseJSON=await response.json();
-        }catch(error){
-            if(isAIRequestAbort(error,signal)){
-                throw normalizeAIRequestAbort(error);
-            }
-            throw error;
-        }
         if(signal?.aborted){
             throw normalizeAIRequestAbort();
         }
-
-        if(!response.id){
-            response.id=id;
-        }
-
-        //console.log(responseJSON);
-        //async
         normalizeAICompletionToolCalls(responseJSON);
         await responseHandler(responseJSON,id,false);
-        //sync
         return responseJSON;
     }
 

package/schemas/arcane-app-bundle.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/TheWizardNexus/arcane-os-sdk/schemas/arcane-app-bundle.schema.json",
   "title": "Arcane external application release bundle",
-  "description": "Structural manifest for one complete USTAR+gzip application bundle.",
+  "description": "Structural manifest for one complete USTAR+gzip application bundle, with per-file POSIX PAX path extensions for long or non-ASCII filenames. PAX framing is excluded from the logical file inventory.",
   "type": "object",
   "required": [
     "schemaVersion",