arcane-os 0.5.13 → 0.5.15

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.15 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
@@ -135,6 +180,50 @@ Ready adjacent audio buffers use contiguous AudioContext scheduling. Browser
 audio scheduling and selected WebGPU status do not prove physical GPU kernel
 overlap or audio quality. LLM and Whisper/STT capacity remains one.
 
+## Play a complete array with `SpeechPlayback`
+
+Use this when your application already has complete segments in an array. The
+configured `ai` below is the same instance created in the quick start.
+
+```javascript
+import SpeechPlayback from 'arcane/SpeechPlayback';
+
+const audio = document.body.appendChild(document.createElement('audio'));
+audio.controls = true;
+const narration = new SpeechPlayback({audio, speech: ai});
+const speakAll = document.body.appendChild(document.createElement('button'));
+speakAll.textContent = 'Speak all segments';
+speakAll.addEventListener('click', async function speakAllSegments() {
+  await ai.setSpeechMuted(false);
+  await narration.prepare({
+    parts: [
+      'First complete segment.',
+      'Second complete segment.',
+      'Third complete segment.'
+    ],
+    autoplay: true
+  });
+});
+```
+
+`prepare()` submits all three parts immediately because this `ai` exposes
+`fetchTTS` and advertises TTS execution capacity. With the default configuration,
+the provider admits up to four synthesis requests and keeps later requests in
+its FIFO queue. Completed audio remains indexed, so playback is always first,
+second, third even if the third synthesis finishes first.
+
+This eager path is capability-driven. A native `Arcane.speech.synthesize`
+client, or a custom client without a positive advertised TTS execution capacity,
+retains serialized synthesis with one lookahead segment. `togglePause()` pauses
+and resumes the same `audio` element. `stop()` cancels all requests owned by the
+playback. `replay()` keeps completed and pending provider segments and retries
+only failed missing segments.
+
+The default `{device:'auto',maxConcurrentRequests:4}` attempts the full ONNX
+Worker/session pool on WebGPU, then recreates that pool on WASM only if WebGPU
+loading fails. Use the status example below to read `selectedDevice`; console
+node-assignment warnings alone do not identify the selected execution device.
+
 ## Queue complete passages and wait for playback
 
 These options are available in SDK `0.5.12`.

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

@@ -9,7 +9,7 @@ same managed browser imports as the [browser speech quick start](browser-speech.
 Create an application and start its source server:
 
 ```bash
-npx arcane-os@0.5.12 new hello-twin --path ./hello-twin --target browser
+npx arcane-os@0.5.15 new hello-twin --path ./hello-twin --target browser
 cd hello-twin
 npm install
 npm run dev

package/docs/reference/cli.md

@@ -214,7 +214,7 @@ portable runtime subpaths such as `arcane-os/preference-store` and
 modules. The result reports the complete map written to the selected
 application; no fixed entry count is a release contract.
 
-SDK `0.5.12` preserves the physical workspace route count and ordered include
+SDK `0.5.15` preserves the physical workspace route count and ordered include
 list. External and modern integrated routes require `components`, `css`,
 `dependencies`, `entities`, `img`, `modules`, and `sdk`; a physical workspace
 may omit only an optional trailing `security` include. The external license

package/docs/reference/core/arcane-ai-contracts.md

@@ -9,7 +9,7 @@ They are not TypeScript declarations.
 
 ## Portable SDK AI and Core AI
 
-The SDK `0.5.12` has two related but separate normalized boundaries:
+The SDK `0.5.15` has two related but separate normalized boundaries:
 
 | Boundary | Use | Host |
 |---|---|---|

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

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.5.12",
+  "sdkVersion": "0.5.15",
   "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",
@@ -1392,10 +1392,10 @@
       "entrypoints": ["arcane-os/speech-playback"],
       "primaryImport": "arcane-os/speech-playback",
       "group": "Portable runtime modules",
-      "summary": "Default binding for the canonical SpeechPlayback runtime class in Node and managed browsers.",
+      "summary": "Default binding for the canonical SpeechPlayback runtime class, with capability-gated eager provider submission and exact-order playback.",
       "availability": "Node with injected media adapters, or browser/native WebView media",
       "protocol": "SpeechPlayback runtime contract",
-      "normalization": "Binding identity and namespace come directly from the canonical runtime module"
+      "normalization": "Binding identity and namespace come directly from the canonical runtime module; a fetchTTS client with positive advertised TTS execution capacity receives all complete segments immediately while its provider owns bounded admission and SpeechPlayback retains indexed order; other clients remain serialized"
     },
     {
       "id": "speech-playback:SPEECH_PLAYBACK_STATE_EVENT",
@@ -1420,10 +1420,10 @@
       "entrypoints": ["arcane-os/speech-playback"],
       "primaryImport": "arcane-os/speech-playback",
       "group": "Portable runtime modules",
-      "summary": "Named binding for the same canonical class exposed as the subpath default.",
+      "summary": "Named binding for the same capability-aware, exact-order canonical class exposed as the subpath default.",
       "availability": "Node with injected media adapters, or browser/native WebView media",
       "protocol": "SpeechPlayback runtime contract",
-      "normalization": "Binding identity equals the default export; prepare preserves each nonblank part input exactly without trimming, splitting, or freezing it; provider and media availability remain host-owned"
+      "normalization": "Binding identity equals the default export; prepare preserves each nonblank part input exactly without trimming, splitting, or freezing it; provider-advertised capacity enables eager submission while the provider owns its bound, native and custom clients remain serialized, and media availability remains host-owned"
     },
     {
       "id": "speech-playback:splitSpeechText",
@@ -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/inventory/runtime-components.json

@@ -5,7 +5,7 @@
     "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
     "branch": "main",
     "path": "runtime/arcane/components",
-    "sdkVersion": "0.5.12"
+    "sdkVersion": "0.5.15"
   },
   "componentCount": 39,
   "loader": "/arcane/modules/HTMLImport.js",

package/docs/reference/inventory/runtime-modules.json

@@ -5,7 +5,7 @@
     "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
     "branch": "main",
     "path": "runtime/arcane",
-    "sdkVersion": "0.5.12",
+    "sdkVersion": "0.5.15",
     "protocol": "arcane/1"
   },
   "artifactCount": 84,
@@ -1153,10 +1153,10 @@
         "default",
         "splitSpeechText"
       ],
-      "summary": "Preserves exact nonblank text as one segment without trimming, splitting, or freezing it; queues latest-request synthesis and controls lookahead HTML audio playback.",
+      "summary": "Preserves exact nonblank segment text without trimming, splitting, or freezing it; eagerly submits complete parts to a capacity-advertising fetchTTS provider while keeping playback indexed, and retains serialized one-segment lookahead for other clients.",
       "availability": "Browser + compatible AI/native bridge",
-      "protocol": "AI.fetchTTS or compatible Arcane.speech.synthesize, globalThis.arcaneEvents, Blob URLs, audio element",
-      "normalization": "Exact nonblank split/part input strings are preserved in mutable records while playback policy, cancellation, Blob results, and lifecycle state are normalized; provider failures remain external.",
+      "protocol": "AI.fetchTTS plus providerRuntime TTS execution capacity, or compatible serialized Arcane.speech.synthesize; globalThis.arcaneEvents, Blob URLs, audio element",
+      "normalization": "Exact nonblank split/part input strings are preserved in mutable records. A capable provider receives complete segments immediately and owns bounded FIFO admission; URLs and playback stay in exact input order. Native/custom clients remain serialized. Cancellation, Replay recovery, Blob results, and lifecycle state are normalized; provider failures remain external.",
       "surface": "SpeechPlayback class/default, `SPEECH_PLAYBACK_STATE_EVENT`, `splitSpeechText()`, canonical playback lifecycle events, cancellation, and destroy APIs."
     },
     {

package/docs/reference/protocols.md

@@ -159,7 +159,7 @@ imports such as:
 import ollama from 'arcane/Ollama';
 ```
 
-The physical-v1 tree lives entirely beneath `arcane/`. SDK `0.5.12` projects the
+The physical-v1 tree lives entirely beneath `arcane/`. SDK `0.5.15` projects the
 complete canonical runtime and browser runtime selected by the installed SDK
 package. Runtime dependencies stay under
 `arcane/dependencies/`; the SDK event and browser-AI closure stays under
@@ -174,7 +174,7 @@ integrated physical route uses the same ordered include list in its one route.
 Omitting only that final optional entry is compatible. Removing, reordering, or
 renaming any preceding entry changes the physical contract.
 
-The `0.5.12` map derives its complete entries from the selected runtime graph;
+The `0.5.15` map derives its complete entries from the selected runtime graph;
 application source imports do not select a fixed entry count. The operation
 result reports `imports`, `entryCount`, and `excludedModules`; reached-file
 traversal remains internal. The
@@ -239,8 +239,8 @@ exactly `dependencyName`, `packageSource`,
 `canonicalPackageRoot`, `packageName`, `packageVersion`, `runtimeRoot`,
 and `browserRuntimeRoot`. A
 workspace may use the canonical dependency name or one exact npm alias such as
-`npm:arcane-os@0.5.12`; the physical package manifest must still identify
-exactly as `arcane-os@0.5.12`. Canonical-plus-alias duplicates, multiple aliases,
+`npm:arcane-os@0.5.15`; the physical package manifest must still identify
+exactly as `arcane-os@0.5.15`. Canonical-plus-alias duplicates, multiple aliases,
 links/junctions, indirect package roots, or version drift are reported.
 
 For external workspaces, `arcane dev` serves the projected `arcane/` root,
@@ -351,7 +351,7 @@ does not silently delete the app-owned cache. A complete whole member supersedes
 its current resumable fragments. Cleanup failure is warned without hiding the
 usable model.
 
-SDK `0.5.12` requires WebGPU. Load requests full offload and waits for the runtime
+SDK `0.5.15` requires WebGPU. Load requests full offload and waits for the runtime
 to report a loaded model. `navigator.gpu` presence alone is
 not readiness. There is no CPU fallback, partial-offload success mode, or
 silent switch to native/Core/cloud inference.

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
@@ -2831,8 +2849,9 @@ console.log(Object.keys(module));
 
 ### Overview
 
-Preserves exact nonblank text as one segment, queues latest-request speech
-synthesis, and controls lookahead HTML audio playback.
+Preserves exact nonblank text, admits complete speech segments according to the
+selected client's advertised capacity, and plays indexed HTML audio in exact
+input order.
 
 ### Public surface
 
@@ -2870,6 +2889,26 @@ freezing it. `prepare()` likewise preserves each nonblank part's exact `input`
 string while normalizing its other playback fields into a new mutable record.
 The class applies no part-count, character-count, pause, or input upper cap.
 
+### Admission and playback order
+
+When `speech` exposes both `fetchTTS(payload, signal)` and
+`providerRuntime.status('tts', {execution:true}).execution.maxConcurrentRequests`
+as a positive safe integer, `prepare()` submits every complete `parts` entry
+immediately. `SpeechPlayback` does not create a second limiter: the provider
+runtime owns bounded FIFO admission. Browser Kokoro defaults that capacity to
+four, so up to four segments can synthesize while later submissions wait in the
+provider queue. A later segment may finish first, but its Blob URL stays at its
+original index and is never played ahead of an earlier segment.
+
+If that capacity is absent, invalid, or unavailable, `SpeechPlayback` retains
+the compatible serialized path and prepares only one lookahead segment. This is
+the default for `Arcane.speech.synthesize` and custom clients, so native hosts
+with one synthesis lock are not driven concurrently. Pause and Resume control
+the same supplied `audio` element. Stop aborts every owned synthesis signal and
+releases prepared URLs. Replay keeps completed URLs and still-pending provider
+work, then re-submits only failed missing provider segments before starting
+again from index zero.
+
 Every preparation owns an operation ID and one AbortController for each active
 synthesis segment or playback delay. Replacement,
 `stop()`, `cancel()`, and `destroy()` abort their owned signals, suppress stale
@@ -2877,9 +2916,10 @@ settlement, release Blob URLs, and publish synchronous
 `speech-playback-state` occurrences through `globalThis.arcaneEvents`.
 Subscribers receive mutable public state detail. The detail contains
 `state`, `message`, `key`, `index`, `total`, `producing`, `buffered`, `hasAudio`,
-`operationId`, `code`, and `reason`; provider rejection remains preserved to the
-`prepare()` caller. `destroy()` also removes every audio listener and disposes
-its per-instance canonical source handle; repeated destroy returns
+`operationId`, `code`, and `reason`; a first-segment provider rejection remains
+preserved to the `prepare()` caller. Later failures surface when ordered
+playback reaches that segment. `destroy()` also removes every audio listener
+and disposes its per-instance canonical source handle; repeated destroy returns
 `false`. Signal abortion proves delivery suppression; whether provider work
 actually stops remains the selected provider's cancellation boundary.
 
@@ -2916,23 +2956,38 @@ const audio = document.body.appendChild(document.createElement('audio'));
 audio.controls = true;
 const speech = new SpeechPlayback({
   audio,
-  speech: globalThis.ai,
-  model: 'caller-selected-model',
-  voice: 'caller-selected-voice',
-  responseFormat: 'wav'
+  speech: globalThis.ai
 });
-const speakButton = document.body.appendChild(document.createElement('button'));
-speakButton.type = 'button';
-speakButton.textContent = 'Speak';
-speakButton.addEventListener('click', async () => {
+const button = document.body.appendChild(document.createElement('button'));
+button.textContent = 'Speak';
+button.addEventListener('click', async function speakCompleteSegments() {
+  await globalThis.ai.setSpeechMuted(false);
   await speech.prepare({
-    key: 'ready',
-    parts: ['Arcane is ready.'],
+    parts: [
+      'First complete segment.',
+      'Second complete segment.'
+    ],
     autoplay: true
   });
 });
 ```
 
+With the default browser speech configuration, both parts enter its capacity-4
+queue immediately and still play first, then second. Inspect the selected
+execution device without guessing from console warnings:
+
+```javascript
+const execution = globalThis.ai.providerRuntime.status(
+  'tts',
+  { execution: true }
+).execution;
+console.log(execution.selectedDevice, execution.maxConcurrentRequests);
+```
+
+`requestedDevice:'auto'` attempts the complete ONNX Worker/session pool on
+WebGPU and recreates it on WASM if WebGPU loading fails. The reported selected
+device proves provider selection, not physical GPU kernel overlap.
+
 ## StaticDocumentCatalog.js
 
 ### Overview

package/docs/reference/sdk-api.md

@@ -1,7 +1,7 @@
 # Arcane OS SDK JavaScript API
 
 The npm package exposes a Node.js ESM control plane, the portable
-`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` entrypoints, and the browser-only
 `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints.
 Those package subpaths are distinct from application-facing projection modules
@@ -18,7 +18,7 @@ This table is the Node `package.json#exports` map: it defines package
 entrypoints for SDK/tooling code. It is distinct from the generated browser
 import map that resolves application-facing `arcane/*` modules and the focused
 EventManager entry. See [browser runtime delivery](protocols.md#browser-runtime-delivery)
-for the installed-inventory-derived physical-runtime contract in SDK `0.5.12`.
+for the installed-inventory-derived physical-runtime contract in SDK `0.5.15`.
 
 | Specifier | Purpose |
 | --- | --- |
@@ -33,6 +33,7 @@ for the installed-inventory-derived physical-runtime contract in SDK `0.5.12`.
 | `arcane-os/packager` | Low-level browser app packager. |
 | `arcane-os/release-bundle` | Deterministic external release bundles. |
 | `arcane-os/event-manager` | Central synchronous events, complete time-travel history, playback, and optional DOM instrumentation. |
+| `arcane-os/logging` | Shared console diagnostics controlled by the existing `user.developer` preference. |
 | `arcane-os/preference-store` | Portable preference records and injected storage adapters. |
 | `arcane-os/speech-playback` | Portable speech preparation, playback state, and injected media adapters. |
 | `arcane-os/ai/browser-wasm` | Caller-selected browser-local Wllama inference, complete DBOPFS model storage, streaming, cancellation, and structural tool-call results. |
@@ -52,7 +53,7 @@ Protocol mechanics are intentionally kept in the [deep protocol guide](protocols
 
 ## Canonical member inventory
 
-The current JavaScript member total is derived mechanically from every `.mjs`
+The current JavaScript member total is derived mechanically from every JavaScript
 entrypoint in `package.json#exports`. Records are grouped by export name and
 `Object.is()` binding identity, then retain the sorted entrypoints that expose
 that binding; `memberCount` in
@@ -259,6 +260,8 @@ browser map are cataloged separately in [Runtime modules](runtime-modules.md).
 | `resolveMailConfig()` | function | `arcane-os/mail` | Portable Mail | Node with explicit configuration, or browser/native WebView with optional document and location defaults |
 | `sendMailReport()` | function | `arcane-os/mail` | Portable Mail | Node and browser with Fetch and AbortController, or an explicit fetch implementation |
 | `serializeMailReport()` | function | `arcane-os/mail` | Portable Mail | Node and browser |
+| `arcaneLogging` | singleton | `arcane-os/logging` | Shared logging | Node and browser |
+| `readArcaneDeveloperMode()` | function | `arcane-os/logging` | Shared logging | Node and browser |
 
 # Packaging and release bundles
 
@@ -748,7 +751,7 @@ deterministic map. The package root also contains the public
 {
   schemaVersion: 1,
   kind: 'arcane-app-runtime-projection',
-  sdkVersion: '0.5.12',
+  sdkVersion: '0.5.15',
   pathPrefix: 'arcane/',
   files: [{path}]
 }
@@ -1497,6 +1500,14 @@ specifier `arcane-os/speech-playback` works in Node package consumers and maps
 to the same runtime module in managed browsers. `arcane/SpeechPlayback` is the
 direct browser runtime name generated into the managed import map.
 
+When the supplied `speech` client has `fetchTTS` and reports a positive
+`providerRuntime.status('tts', {execution:true}).execution.maxConcurrentRequests`,
+`prepare()` submits every complete part immediately. The provider owns its
+bounded FIFO queue (browser Kokoro defaults to four), while Blob URLs and
+playback remain in exact input order. A native or custom client without that
+advertised capacity stays serialized with one lookahead. Replay keeps completed
+URLs and pending requests while retrying failed missing provider segments.
+
 ### Signature and result
 
 ```text
@@ -1513,7 +1524,18 @@ runtime module; provider and media availability remain host-owned.
 
 ```javascript
 import SpeechPlayback from 'arcane-os/speech-playback';
-const playback=new SpeechPlayback({audio,speech});
+
+const audio=document.body.appendChild(document.createElement('audio'));
+const playback=new SpeechPlayback({audio,speech:globalThis.ai});
+const button=document.body.appendChild(document.createElement('button'));
+button.textContent='Speak';
+button.addEventListener('click',async function speakCompleteSegments(){
+  await globalThis.ai.setSpeechMuted(false);
+  await playback.prepare({
+    parts:['First complete segment.','Second complete segment.'],
+    autoplay:true
+  });
+});
 ```
 
 ## SPEECH_PLAYBACK_STATE_EVENT
@@ -1543,7 +1565,9 @@ console.log(SPEECH_PLAYBACK_STATE_EVENT);
 
 ### Overview
 
-Named binding for the same canonical class exposed as the speech-playback default. `prepare()` preserves each nonblank part's exact input string without trimming, splitting, or freezing that content.
+Named binding for the same capability-aware, exact-order canonical class exposed
+as the speech-playback default. `prepare()` preserves each nonblank part's exact
+input string without trimming, splitting, or freezing that content.
 
 ### Signature and result
 
@@ -1554,7 +1578,9 @@ new SpeechPlayback(options={})
 ### Availability and normalization
 
 **Node with injected media adapters, or browser/native WebView media.** Binding
-identity equals the default export; provider and media availability remain host-owned.
+identity equals the default export. Provider-advertised capacity enables eager
+submission while that provider owns its bound; native and custom speech stays
+serialized, and media availability remains host-owned.
 
 ### Example
 
@@ -2667,7 +2693,7 @@ The import-map operation also reports the stable operation-specific strings
 `ARCANE_IMPORT_MAP_INVALID`, `ARCANE_IMPORT_MAP_UNRESOLVED`, and
 `ARCANE_IMPORT_MAP_COLLISION`; package assembly can additionally report
 `ARCANE_IMPORT_MAP_CLEANUP_FAILED`. They are normalized `ArcaneError.code`
-values, but are not properties added to this general registry in SDK `0.5.12`.
+values, but are not properties added to this general registry in SDK `0.5.14`.
 
 ### Value and import
 
@@ -3437,7 +3463,7 @@ workspace it additionally returns the exact installed package authority:
     packageSource,
     canonicalPackageRoot,
     packageName: 'arcane-os',
-    packageVersion: '0.5.12',
+    packageVersion: '0.5.15',
     runtimeRoot,
     browserRuntimeRoot
   }
@@ -3445,9 +3471,9 @@ workspace it additionally returns the exact installed package authority:
 ```
 
 The dependency can be named `arcane-os` or be one exact npm alias for
-`npm:arcane-os@0.5.12`. The selected installation must still be one direct,
+`npm:arcane-os@0.5.15`. The selected installation must still be one direct,
 physical, non-link package directory whose manifest identifies exactly as
-`arcane-os@0.5.12`; duplicate canonical/alias declarations reject.
+`arcane-os@0.5.15`; duplicate canonical/alias declarations reject.
 `allowMissingManagedImportMap` is an internal packaging/development seam. An
 ordinary caller should leave it `false`.
 
@@ -6728,6 +6754,89 @@ import {serializeMailReport} from 'arcane-os/mail';
 const body = serializeMailReport(report);
 ```
 
+# Shared logging
+
+## arcaneLogging
+
+### Overview
+
+Shared console owner for Arcane runtime and application diagnostics. Available
+in SDK `0.5.14`, it reads the existing `user.developer` preference on every
+diagnostic emission after the shared user is ready. Enable developer mode in
+the application's profile settings. There is no separate verbosity setting.
+See [speech developer diagnostics](ai/browser-speech.md#developer-diagnostics)
+for API calls, generation queue state, and playback events.
+
+### Signature and result
+
+```text
+const arcaneLogging
+arcaneLogging.enabled
+arcaneLogging.log(...args)
+arcaneLogging.info(...args)
+arcaneLogging.debug(...args)
+arcaneLogging.warn(...args)
+arcaneLogging.error(...args)
+arcaneLogging.trace(...args)
+```
+
+`enabled` is a boolean getter for the current shared preference, not another
+setting. `log`, `info`, and `debug` forward to `console.info` when enabled, so
+diagnostics appear at the console's normal Info level. `warn`, `error`, and
+failure `trace` calls forward to their corresponding console methods in either
+mode. Each method returns `undefined`; a console failure does not change the
+operation being observed.
+
+### Availability and normalization
+
+**Node and browser.** Imports reuse the same realm-local owner through
+`Symbol.for('arcane.logging')`, also exposed as `globalThis.arcaneLogging`.
+Arguments pass to the host console unchanged, including complete object
+references. The logger does not serialize content, retain diagnostic history,
+write storage, or send network requests. Diagnostics remain disabled while
+the shared user is not ready. The logger does not select a language or change
+speech generation and playback behavior.
+
+### Example
+
+```javascript
+import {arcaneLogging} from 'arcane-os/logging';
+
+arcaneLogging.info('AI request', request);
+arcaneLogging.info('AI response', parsedResponse);
+```
+
+## readArcaneDeveloperMode()
+
+### Overview
+
+Reads the same developer-mode preference used by `arcaneLogging`, preserving
+the unloaded-user state without creating or changing a setting.
+
+### Signature and result
+
+```text
+readArcaneDeveloperMode(target=globalThis)
+```
+
+`target` supplies the shared `user`. The result is `null` until
+`target.user.ready === true`, then `true` only when
+`target.user.developer === true`; other loaded preference values return
+`false`. If preference access throws, the reader returns `false`.
+
+### Availability and normalization
+
+**Node and browser.** Reads the supplied target synchronously. It performs no
+subscription, write, or logging, and does not cache the preference.
+
+### Example
+
+```javascript
+import {readArcaneDeveloperMode} from 'arcane-os/logging';
+
+const developerMode=readArcaneDeveloperMode();
+```
+
 ## 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/`.