arcane-os 0.5.13 → 0.5.14

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.5.14
+
+- Add the shared `arcane-os/logging` console owner using the existing
+  `user.developer` preference. Route first-party runtime diagnostics and
+  default model loggers through this owner; preserve warnings and errors
+  when developer mode is disabled.
+- Trace complete speech API inputs, generation queues, Worker requests and
+  responses, decoded audio, scheduled playback, natural completion,
+  cancellation, and failure under that same developer preference. Preserve
+  caller text, voice, speed, language selection, and playback behavior.
+- Preserve complete cloud AI error responses and retry HTTP 429 overload
+  responses after three seconds with the original request and cancellation
+  signal. Keep partial streams and tool callbacks outside the retry path.
+- Preserve exact URL import-map aliases while adding matching versioned
+  aliases, including authored imports, scopes, and generated dependency paths.
+
 ## 0.5.13
 
 - Derive local browser resource queries from the selected SDK package version

package/browser-runtime/ai/browser-wasm-llm-provider.mjs

@@ -1,3 +1,4 @@
+import { arcaneLogging } from '../logging.mjs';
 import {
   ARCANE_AI_ADAPTER_PROTOCOL,
   ArcaneAIError,
@@ -1148,7 +1149,7 @@ export function createDbopfsModelStore({
     try {
       await removeMemberRangeParts(modelName, { total });
     } catch (error) {
-      globalThis.console?.warn?.(
+      arcaneLogging.warn?.(
         "Arcane could not remove superseded browser model range parts.",
         error,
       );
@@ -1163,7 +1164,7 @@ export function createDbopfsModelStore({
         total: ranges[0]?.total ?? null,
       });
     } catch (error) {
-      globalThis.console?.warn?.(
+      arcaneLogging.warn?.(
         "Arcane could not remove superseded browser model range parts.",
         error,
       );
@@ -1195,7 +1196,7 @@ export function createDbopfsModelStore({
         await removeMemberRangeParts(modelName, { total });
       }
     } catch (error) {
-      globalThis.console?.warn?.(
+      arcaneLogging.warn?.(
         "Arcane could not remove superseded browser model range parts.",
         error,
       );
@@ -2404,7 +2405,7 @@ function callbackStreamHandle({ runtime, request, signal, onSettled }) {
       Promise.resolve().then(() => this.cancel(
         "The stream consumer stopped before completion.",
       )).catch(function reportBrowserWasmStreamReturnCancellationFailure(error) {
-        console.error("Arcane browser-WASM stream early-return cancellation failed.", error);
+        arcaneLogging.error("Arcane browser-WASM stream early-return cancellation failed.", error);
       });
       return { value, done: true };
     },
@@ -2432,7 +2433,7 @@ function validatedV1StreamHandle(opened, request) {
       Promise.resolve().then(function cancelInvalidV1StreamHandle() {
         return opened.cancel("The v1 provider returned an invalid stream handle.");
       }).catch(function reportInvalidV1StreamCleanupFailure(error) {
-        console.error("Arcane invalid v1 stream cleanup failed.", error);
+        arcaneLogging.error("Arcane invalid v1 stream cleanup failed.", error);
       });
     }
     throw fail(
@@ -2447,7 +2448,7 @@ function validatedV1StreamHandle(opened, request) {
     Promise.resolve().then(function cancelRejectedV1Iterator() {
       return opened.cancel(error);
     }).catch(function reportRejectedV1IteratorCleanupFailure(cleanupError) {
-      console.error("Arcane rejected v1 stream iterator cleanup failed.", cleanupError);
+      arcaneLogging.error("Arcane rejected v1 stream iterator cleanup failed.", cleanupError);
     });
     throw error;
   }
@@ -2455,7 +2456,7 @@ function validatedV1StreamHandle(opened, request) {
     Promise.resolve().then(function cancelInvalidV1Iterator() {
       return opened.cancel("The v1 provider returned an invalid stream iterator.");
     }).catch(function reportInvalidV1IteratorCleanupFailure(error) {
-      console.error("Arcane invalid v1 stream iterator cleanup failed.", error);
+      arcaneLogging.error("Arcane invalid v1 stream iterator cleanup failed.", error);
     });
     throw fail(
       "ARCANE_AI_INVALID_PROVIDER_RESULT",
@@ -2539,13 +2540,13 @@ function validatedV1StreamHandle(opened, request) {
         Promise.resolve().then(function returnUnderlyingV1Stream() {
           return iterator.return(value);
         }).catch(function reportUnderlyingV1StreamReturnFailure(error) {
-          console.error("Arcane v1 stream iterator return failed.", error);
+          arcaneLogging.error("Arcane v1 stream iterator return failed.", error);
         });
       }
       Promise.resolve().then(function cancelReturnedV1Stream() {
         return opened.cancel("The stream consumer stopped before completion.");
       }).catch(function reportReturnedV1StreamCancellationFailure(error) {
-        console.error("Arcane v1 stream early-return cancellation failed.", error);
+        arcaneLogging.error("Arcane v1 stream early-return cancellation failed.", error);
       });
       return { value, done: true };
     },
@@ -2778,7 +2779,7 @@ export function createBrowserWasmLlmProvider({
   store,
   loadDefaults = {},
   security,
-  logger = console,
+  logger = arcaneLogging,
 } = {}) {
   const configuredModels = providerModelSources(sources);
   const modelSources = configuredModels.sources;

package/browser-runtime/ai/browser-wllama-runtime.mjs

@@ -1,3 +1,4 @@
+import { arcaneLogging } from '../logging.mjs';
 import { Wllama } from "./wllama/index.mjs";
 
 const completeValue = (value) => value;
@@ -276,7 +277,7 @@ function initialEvidence() {
  * network or browser side effects until load() is called. Runtime URLs are
  * fixed relative to this module for npm and materialized /arcane/sdk trees.
  */
-export function createPackagedWllamaRuntime({ logger = console } = {}) {
+export function createPackagedWllamaRuntime({ logger = arcaneLogging } = {}) {
   let engine = null;
   let pending = null;
   let inferenceActive = false;

package/browser-runtime/ai/model-controller.mjs

@@ -1,3 +1,4 @@
+import { arcaneLogging } from '../logging.mjs';
 import { createArcaneEventSource } from "arcane-os/event-manager";
 
 export const ARCANE_AI_ADAPTER_PROTOCOL = "arcane-ai-adapter/1";
@@ -1372,7 +1373,7 @@ export class ModelController {
           Promise.resolve().then(()=>value.cancel(
             "The provider returned an invalid stream handle.",
           )).catch(function reportInvalidModelStreamCleanupFailure(error){
-            console.error("Arcane invalid model stream cleanup failed.",error);
+            arcaneLogging.error("Arcane invalid model stream cleanup failed.",error);
           });
         }
         throw new ArcaneAIError(
@@ -1386,7 +1387,7 @@ export class ModelController {
       }catch(error){
         Promise.resolve().then(()=>value.cancel(error)).catch(
           function reportRejectedModelIteratorCleanupFailure(cleanupError){
-            console.error("Arcane rejected model stream iterator cleanup failed.",cleanupError);
+            arcaneLogging.error("Arcane rejected model stream iterator cleanup failed.",cleanupError);
           },
         );
         throw error;
@@ -1395,7 +1396,7 @@ export class ModelController {
         Promise.resolve().then(()=>value.cancel(
           "The provider returned an invalid stream iterator.",
         )).catch(function reportInvalidModelIteratorCleanupFailure(error){
-          console.error("Arcane invalid model stream iterator cleanup failed.",error);
+          arcaneLogging.error("Arcane invalid model stream iterator cleanup failed.",error);
         });
         throw new ArcaneAIError(
           "ARCANE_AI_INVALID_PROVIDER_RESULT",
@@ -1468,7 +1469,7 @@ export class ModelController {
             const value = opened ?? await openPromise;
             await value.cancel?.(reason);
           } catch (error) {
-            console.error("Arcane model provider cancellation failed.",error);
+            arcaneLogging.error("Arcane model provider cancellation failed.",error);
           }
           try {
             await result;
@@ -1491,7 +1492,7 @@ export class ModelController {
         Promise.resolve().then(()=>this.cancel(
           "The stream consumer stopped before completion.",
         )).catch(function reportModelStreamReturnCancellationFailure(error){
-          console.error("Arcane model stream early-return cancellation failed.",error);
+          arcaneLogging.error("Arcane model stream early-return cancellation failed.",error);
         });
         return { value, done: true };
       },

package/browser-runtime/ai/speech-worker-client.mjs

@@ -3,8 +3,10 @@ import {
   normalizeSpeechWorkerErrorEnvelope,
   SPEECH_WORKER_PROTOCOL,
 } from "./speech-worker-runtime.mjs";
+import { arcaneLogging } from "../logging.mjs";
 
 const completeValue = (value) => value;
+let nextSpeechWorkerClientId = 0;
 
 const PUBLIC_WORKER_OPERATIONS = new Set([
   "load",
@@ -57,6 +59,7 @@ const WORKER_CLIENTS = new WeakSet();
  * Workers remain available.
  */
 class SpeechWorkerClient {
+  #diagnosticId = ++nextSpeechWorkerClientId;
   #role;
   #createWorker;
   #worker = null;
@@ -84,6 +87,29 @@ class SpeechWorkerClient {
     });
     this.#onTermination = onTermination;
     WORKER_CLIENTS.add(this);
+    this.#trace("created", { workerUrl: workerUrl.href });
+  }
+
+  #trace(phase, detail = {}, beforeTransfer = false) {
+    if (!arcaneLogging.enabled) return;
+    let snapshot = detail;
+    if (beforeTransfer) {
+      try {
+        // Preserve complete request content before postMessage transfers it.
+        snapshot = structuredClone(detail);
+      } catch {
+        // Retain the complete original if native cloning cannot represent it.
+      }
+    }
+    arcaneLogging.debug("[Arcane speech worker]", {
+      clientId: this.#diagnosticId,
+      role: this.#role,
+      phase,
+      timestamp: new Date().toISOString(),
+      timeMs: globalThis.performance?.now?.() ?? Date.now(),
+      pendingRequests: this.#pending.size,
+      ...snapshot,
+    });
   }
 
   #listen(target, type, listener) {
@@ -103,6 +129,7 @@ class SpeechWorkerClient {
     }
     const worker = validateWorker(this.#createWorker());
     this.#worker = worker;
+    this.#trace("started");
     this.#listen(worker, "message", (event) => {
       this.#handleMessage(event.data);
     });
@@ -126,6 +153,7 @@ class SpeechWorkerClient {
   }
 
   #handleMessage(message) {
+    this.#trace("response", { message });
     if (message?.protocol !== SPEECH_WORKER_PROTOCOL) {
       void this.terminate(clientError(
         "ARCANE_AI_ADAPTER_PROTOCOL_MISMATCH",
@@ -177,7 +205,9 @@ class SpeechWorkerClient {
   }
 
   request(op, payload, { signal = null } = {}) {
+    this.#trace("request.call", { op, payload, aborted: signal?.aborted });
     if (!PUBLIC_WORKER_OPERATIONS.has(op)) {
+      this.#trace("request.rejected", { op, reason: "unknown-operation" });
       return Promise.reject(clientError(
         "ARCANE_AI_INVALID_REQUEST",
         "The speech worker operation is not part of its protocol.",
@@ -185,12 +215,16 @@ class SpeechWorkerClient {
         `${this.#role}-worker-operation-unknown`,
       ));
     }
-    if (signal?.aborted) return Promise.reject(abortError(signal, this.#role, op));
+    if (signal?.aborted) {
+      this.#trace("request.cancelled", { op, reason: signal.reason });
+      return Promise.reject(abortError(signal, this.#role, op));
+    }
     let worker;
     try {
       worker = this.#start();
       this.#transport = worker;
     } catch (error) {
+      this.#trace("request.error", { op, error });
       return Promise.reject(error);
     }
     const id = this.#nextId;
@@ -206,6 +240,7 @@ class SpeechWorkerClient {
       function onAbort() {
         const pending = client.#pending.get(id);
         if (!pending) return;
+        client.#trace("request.cancelled", { id, op, reason: signal?.reason });
         if (client.#role === "tts" && op === "use") {
           client.#pending.delete(id);
           pending.cleanup();
@@ -213,13 +248,16 @@ class SpeechWorkerClient {
           const cancelId = client.#nextId;
           client.#nextId += 1;
           try {
-            client.#transport.postMessage({
+            const cancellation = {
               protocol: SPEECH_WORKER_PROTOCOL,
               id: cancelId,
               op: "cancel",
               payload: { targetId: id },
-            });
+            };
+            client.#trace("request.dispatch", { message: cancellation }, true);
+            client.#transport.postMessage(cancellation);
           } catch (error) {
+            client.#trace("request.error", { id: cancelId, op: "cancel", error });
             const failure = clientError(
               "ARCANE_AI_WORKER_MESSAGE_ERROR",
               "Unable to cancel an operation in the speech Worker.",
@@ -251,8 +289,10 @@ class SpeechWorkerClient {
       };
       const transfers = collectSpeechTransferables(payload);
       try {
+        client.#trace("request.dispatch", { message }, true);
         client.#transport.postMessage(message, transfers);
       } catch (error) {
+        client.#trace("request.error", { id, op, error });
         client.#pending.delete(id);
         cleanup();
         const failure = clientError(
@@ -272,6 +312,7 @@ class SpeechWorkerClient {
   }
 
   async terminate(reason = null, { intentional = true } = {}) {
+    this.#trace("terminate.call", { reason, intentional });
     if (typeof intentional !== "boolean") {
       throw new TypeError("Speech Worker termination intent must be a boolean.");
     }
@@ -303,6 +344,7 @@ class SpeechWorkerClient {
       if (termination && typeof termination.then === "function") await termination;
     } finally {
       for (const pending of pendingOperations) pending.reject(terminationReason);
+      this.#trace("terminated", { reason: terminationReason, intentional });
       this.#onTermination(completeValue({ reason: terminationReason, intentional }));
     }
   }

package/browser-runtime/event-manager.mjs

@@ -1,4 +1,5 @@
 import EventPubSub from 'event-pubsub';
+import {arcaneLogging} from './logging.mjs';
 import {createDOMInstrumentation} from './dom-event-instrumentation.mjs';
 
 export {
@@ -1368,7 +1369,7 @@ function createArcaneEventAuthority(){
                 return;
             }
         }catch{}
-        try{globalThis.console?.error?.('Arcane event listener failed.',error);}
+        try{arcaneLogging.error('Arcane event listener failed.',error);}
         catch{}
     }
 

package/browser-runtime/logging.mjs

@@ -0,0 +1,58 @@
+/** Read the shared user preference; null means the user has not loaded yet. */
+export function readArcaneDeveloperMode(target=globalThis){
+    try{
+        if(target?.user?.ready!==true){
+            return null;
+        }
+
+        return target.user.developer===true;
+    }catch{
+        return false;
+    }
+}
+
+function emitArcaneLog(method,diagnostic,args){
+    try{
+        if(diagnostic&&readArcaneDeveloperMode()!==true){
+            return;
+        }
+        globalThis.console?.[method]?.(...args);
+    }catch{
+        // Console diagnostics must never change the operation being observed.
+    }
+}
+
+const loggingOwnerKey=Symbol.for('arcane.logging');
+
+/**
+ * The shared developer console owner. Diagnostic methods read user.developer
+ * for every emission and use info so they remain visible at normal console
+ * levels. Warnings, errors, and failure traces remain visible in every mode.
+ * Arguments pass through unchanged and are never retained by this owner.
+ */
+export const arcaneLogging=globalThis[loggingOwnerKey]??{
+    get enabled(){
+        return readArcaneDeveloperMode()===true;
+    },
+    log(...args){
+        emitArcaneLog('info',true,args);
+    },
+    info(...args){
+        emitArcaneLog('info',true,args);
+    },
+    debug(...args){
+        emitArcaneLog('info',true,args);
+    },
+    warn(...args){
+        emitArcaneLog('warn',false,args);
+    },
+    error(...args){
+        emitArcaneLog('error',false,args);
+    },
+    trace(...args){
+        emitArcaneLog('trace',false,args);
+    }
+};
+
+globalThis[loggingOwnerKey]=arcaneLogging;
+globalThis.arcaneLogging=arcaneLogging;

package/docs/reference/README.md

@@ -17,7 +17,7 @@ high-level page links to the relevant deep section instead of repeating it.
 Install the SDK in your application:
 
 ```sh
-npm install --save-exact arcane-os@0.5.12
+npm install --save-exact arcane-os@0.5.14
 ```
 
 For your first AI call, follow the [TWiN Cloud quick start](ai/twin-cloud.md).
@@ -34,6 +34,7 @@ alone does not make bare module names resolve in a browser.
 | --- | --- |
 | Use the Node.js package API | [SDK JavaScript API](sdk-api.md) |
 | Publish central events, capture complete time-travel history, or observe the DOM | [EventManager and event-stack reference](event-manager.md) |
+| Inspect complete AI and speech calls using the shared developer-mode preference | [Shared logger](sdk-api.md#arcanelogging) and [speech developer diagnostics](ai/browser-speech.md#developer-diagnostics) |
 | Use the `arcane` command | [CLI reference](cli.md) |
 | Generate named browser imports or inspect the selected physical runtime | [`arcane import-map`](cli.md#arcane-import-map) and [browser runtime delivery](protocols.md#browser-runtime-delivery) |
 | Choose browser, native, cloud, or cross-host behavior | [Availability and normalization](availability-and-normalization.md) |
@@ -56,9 +57,9 @@ This repository contains explicitly versioned surfaces with different owners:
 
 | Surface | Source identity | Meaning |
 | --- | --- | --- |
-| SDK and CLI | `arcane-os` `0.5.12` | The Node.js toolchain, portable `arcane-os/event-manager`, `arcane-os/mail`, `arcane-os/preference-store`, and `arcane-os/speech-playback` entrypoints, plus the browser-only `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints in this checkout. |
-| Browser runtime | SDK `0.5.12`, protocol `arcane/1`, `runtime/` | The SDK-canonical runtime tree. `listRuntimeFiles()`, `readRuntimeFile()`, and `loadRuntimeRelease()` derive its current inventory directly from the selected directory. |
-| Browser SDK runtime | SDK `0.5.12`, `browser-runtime/` | The browser closure for events, Wllama, and Browser Speech mechanisms. `listSdkBrowserRuntimeFiles()`, `readSdkBrowserRuntimeFile()`, and `loadSdkBrowserRuntimeRelease()` derive its current inventory directly from the selected directory. |
+| SDK and CLI | `arcane-os` `0.5.14` | The Node.js toolchain, portable `arcane-os/event-manager`, `arcane-os/logging`, `arcane-os/mail`, `arcane-os/preference-store`, and `arcane-os/speech-playback` entrypoints, plus the browser-only `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints in this checkout. |
+| Browser runtime | SDK `0.5.14`, protocol `arcane/1`, `runtime/` | The SDK-canonical runtime tree. `listRuntimeFiles()`, `readRuntimeFile()`, and `loadRuntimeRelease()` derive its current inventory directly from the selected directory. |
+| Browser SDK runtime | SDK `0.5.14`, `browser-runtime/` | The browser closure for events, shared logging, Wllama, and Browser Speech mechanisms. `listSdkBrowserRuntimeFiles()`, `readSdkBrowserRuntimeFile()`, and `loadSdkBrowserRuntimeRelease()` derive its current inventory directly from the selected directory. |
 | Core reference snapshot | Arcane OS commit `567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e`, protocol `arcane/1` | The application-facing Core contract imported into `docs/reference/core/`, with SDK-local links and package-boundary notes added explicitly. |
 
 The SDK runtime source and Core reference have different owners. A browser
@@ -73,7 +74,7 @@ and the distinction between a documentation snapshot and the selected runtime.
 
 ## Installed documentation and release identity
 
-This reference accompanies `arcane-os@0.5.12`. The installed package includes
+This reference accompanies `arcane-os@0.5.14`. The installed package includes
 the maintained `docs/` tree and `examples/wasm-ai-demo/` source alongside
 README and CHANGELOG. Open `node_modules/arcane-os/docs/reference/README.md`
 for the matching local reference. The generated website and test suites remain
@@ -122,10 +123,10 @@ Public reference entries follow the established Arcane documentation model:
 
 ## Public runtime inventory
 
-The package exposes 204 semantic JavaScript records across 16 JavaScript
+The package exposes 198 semantic JavaScript records across 17 JavaScript
 entrypoints, plus eight JSON Schemas and package metadata. Ten entrypoints are
 Node.js control-plane surfaces,
-`arcane-os/event-manager`, `arcane-os/mail`, `arcane-os/preference-store`, and
+`arcane-os/event-manager`, `arcane-os/logging`, `arcane-os/mail`, `arcane-os/preference-store`, and
 `arcane-os/speech-playback` run in Node and browsers, and
 `arcane-os/ai/browser-wasm` plus `arcane-os/ai/browser-speech` are browser-only.
 The [machine-readable package

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

@@ -13,7 +13,7 @@ import map resolves `arcane/AI` and `arcane/DBOPFS`. These browser modules are
 not Node inference APIs. To create an application:
 
 ```bash
-npx arcane-os@0.5.12 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.5.14 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 npm run dev
@@ -121,6 +121,51 @@ window.addEventListener('ai-tts-failure', function reportSpeechFailure(event) {
 
 Call `speechEvents.abort()` when disposing that interface to remove the listener.
 
+## Developer diagnostics
+
+The shared logging API and speech traces are available in SDK `0.5.14`.
+
+Arcane uses the existing shared `user.developer` preference for diagnostic
+logging. Enable **developer mode** in the application's profile settings; the
+logger reads that preference on every emission after the shared user is ready.
+There is no separate speech verbosity or language setting. Ordinary warnings
+and errors remain visible with developer mode disabled.
+
+Applications can use the same owner for their complete AI requests and parsed
+responses:
+
+```javascript
+import { arcaneLogging } from 'arcane-os/logging';
+
+arcaneLogging.info('AI request', request);
+arcaneLogging.info('AI response', response);
+```
+
+`arcaneLogging.log`, `.info`, and `.debug` use the developer preference and
+appear at the browser console's normal Info level. `.warn`, `.error`, and
+failure `.trace` calls remain visible in either mode. The same logger is
+available as `globalThis.arcaneLogging`; it stores no diagnostic history.
+
+Speech diagnostics include complete API inputs and results, selected provider
+and model, exact segment text, voice and speed, generation queue state, Worker
+request IDs and responses, and decoding/playback events. Worker requests are
+copied only for developer diagnostics before native transfer detaches their
+audio buffers; the original request still goes to the Worker unchanged.
+
+Follow a speech `jobId` through `queue.add`, `generation.request`,
+`generation.result`, `decode.result`, `playback.scheduled`, `playback.ended`,
+and `queue.complete`. Cancellation and failure appear as `queue.cancelled`
+and `queue.failed`. Each playback record includes the audio clock,
+sample rate, duration, playback rate, and scheduled start/end when available.
+For ready adjacent buffers, `gapSeconds` is zero on the same audio clock;
+`audioEnd` marks the end of audio and `scheduledEnd` includes the caller's
+requested pause. A positive gap can expose generation arriving too late to
+fill the audio clock continuously. A scheduled event alone does not establish
+that the buffer finished; use its `playback.ended` event.
+
+Diagnostics do not change text, voice, speed, language selection, segmentation,
+generation capacity, or playback scheduling. They stay outside chat history.
+
 ## Four synthesis slots and exact-order playback
 
 Capacity 4 means up to four segments synthesize at once. Segment 5 and later

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

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.5.12",
+  "sdkVersion": "0.5.14",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 204,
+  "memberCount": 198,
   "members": [
     {
       "id": "root:APP_BUNDLE_DESCRIPTOR_NAME",
@@ -3189,6 +3189,34 @@
       "availability": "Node and browser",
       "protocol": "Arcane Mail HTTP transport",
       "normalization": "Returns compact JSON and rejects non-object or non-serializable reports"
+    },
+    {
+      "id": "logging:arcaneLogging",
+      "name": "arcaneLogging",
+      "displayName": "arcaneLogging",
+      "kind": "singleton",
+      "signature": "const arcaneLogging",
+      "entrypoints": ["arcane-os/logging"],
+      "primaryImport": "arcane-os/logging",
+      "group": "Shared logging",
+      "summary": "Shared console owner controlled by the existing user.developer preference.",
+      "availability": "Node and browser",
+      "protocol": "Shared user.developer preference and host console",
+      "normalization": "Reads developer mode on every diagnostic emission; log, info, and debug use console.info only when enabled; warn, error, and failure trace remain visible in either mode; arguments pass through unchanged without retained history"
+    },
+    {
+      "id": "logging:readArcaneDeveloperMode",
+      "name": "readArcaneDeveloperMode",
+      "displayName": "readArcaneDeveloperMode()",
+      "kind": "function",
+      "signature": "readArcaneDeveloperMode(target=globalThis)",
+      "entrypoints": ["arcane-os/logging"],
+      "primaryImport": "arcane-os/logging",
+      "group": "Shared logging",
+      "summary": "Reads the existing developer-mode preference without creating or changing a setting.",
+      "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"
     }
   ]
 }

package/docs/reference/runtime-modules.md

@@ -152,6 +152,24 @@ entry points. `streamMessage(...)` and `streamRequest(options)` deliver
 incremental responses. The positional and object forms share the existing
 provider implementations; neither form is a retired compatibility API.
 
+Built-in cloud chat decodes an HTTP error body once as JSON or text and rejects
+with that complete value unchanged. It does not reconstruct an Error, replace
+the message, or add `providerMessage`, `status`, or an SDK failure code to the
+provider body. Network and decoding errors also pass through; cancellation
+retains the existing `ARCANE_AI_REQUEST_ABORTED` contract.
+
+When the HTTP status is `429` and the existing `error.message`, `message`, or
+plain-text body contains `overload`, ignoring case, the request retries after
+three seconds without a retry-count limit. Each warning shows the complete
+message followed by `Retrying in ${retryDelayMs / 1000} seconds` through the
+shared console logger, separately from the provider error. Every attempt uses
+the same destination, headers, complete serialized body, and cancellation
+signal; `onRequest` runs once for the logical request. Cancellation stops the
+delay and prevents another attempt. Retrying happens before a successful
+response is consumed, so partial streams and tool callbacks are never replayed.
+Native Ollama and externally supplied provider adapters retain their own
+transport behavior.
+
 Initialization uses the canonical realm user's actual readiness state. If
 `window.user?.ready` is already true, AI initializes immediately. Otherwise one
 shared registration observes `user-entity-loaded`, then rechecks readiness