arcane-os 0.92.0 → 0.94.0

package/docs/reference/native-diagnostics.md

@@ -0,0 +1,167 @@
+# Native application diagnostics
+
+Native diagnostics retain errors from the actual packaged application's top-level
+document in its native host session. Read them through the existing app-control
+connection, without foregrounding a window, desktop input, or arbitrary script
+execution. This is a developer inspection surface, separate from ordinary product
+status and saved conversation history.
+
+The Windows WebView2 host installs the fixed observer at document creation, before
+the ordinary Core client and application scripts. It captures `window.error` and
+`unhandledrejection` events and accepts explicit reports of application-caught
+errors. It leaves the browser's ordinary error behavior intact. It does not
+intercept console output, inspect application state, collect resource/request
+bodies, or capture errors from other applications or frame documents.
+
+## Report a caught application error
+
+```js
+import {reportNativeError} from 'arcane-os/core/native-diagnostics';
+
+const receipt = await reportNativeError(error, {
+    details: {operation: 'source.load', sourceId}
+});
+// receipt: {accepted: true, sessionId, sequence}
+```
+
+`error` is the actual caught value, including non-Error rejection values.
+`details` is optional application-selected diagnostic context. Supply diagnostic
+information only; credentials, secrets, user documents and provider/tool payloads
+do not belong in this report. The SDK adds document/session metadata outside the
+reported values and does not rewrite their text. Reporting does not change the
+application's own handling of the original failure.
+
+The promise resolves after the native host retains the record. A missing document
+observer or native handler rejects with
+`ARCANE_NATIVE_DIAGNOSTICS_UNAVAILABLE`. A negative host acknowledgement rejects
+with `ARCANE_NATIVE_DIAGNOSTIC_REJECTED`, preserving the complete host reply in
+`details` and its error in `cause`. Reflection, encoding and native transport
+failures reject with their actual error. A lost reply can leave the caller's
+outcome unknown; the SDK does not automatically retry and duplicate the report.
+
+Automatic capture observes its own reporting failures through the existing
+console, with the original error, without recursively manufacturing an unhandled
+rejection. Console output remains ordinary console output; it is not retained
+diagnostic history. Applications must observe explicit reporting promises.
+
+## Retrieve retained errors
+
+Use the endpoint of the selected running app from its existing app-control launch
+configuration. Connecting does not launch the application.
+
+```js
+import {connectAppControl} from 'arcane-os/core/app-control';
+
+const control = await connectAppControl({endpoint});
+try {
+    const snapshot = await control.diagnostics();
+    console.dir(snapshot, {depth: null});
+} finally {
+    await control.close();
+}
+```
+
+`control.diagnostics({afterSequence?, documentId?}, {signal?})` invokes
+`app.control.diagnostics`. Omitted filters return every retained error.
+`afterSequence` selects records with a greater session sequence;
+`documentId` selects one actual document. Retrieval is non-consuming: independent
+inspectors can read the same complete records. Connection/cancellation behavior is
+the existing app-control contract. Retrieval does not wait for renderer, Core,
+model or application readiness and does not evaluate a script in the document.
+
+The result is:
+
+```js
+{
+    sessionId,
+    captureStartedAt,
+    captureInstalled,
+    latestSequence,
+    documents: [{documentId, documentUrl, time, receivedAt}],
+    records: [{
+        sequence, receivedAt, documentId, documentUrl, time,
+        kind, error, details, valueFormat, values, location, message
+    }]
+}
+```
+
+`sessionId` identifies this native window/host lifetime. `captureStartedAt` is the
+time its in-memory ledger was created. `captureInstalled` means document-start
+script registration completed; it does not prove that any application failure
+occurred or that a particular operation succeeded. `documents` records actual
+ingress from observed documents. Each document has one identity, shared with app
+control, independent of Core bridge generations. A cancelled navigation that
+leaves the same document alive keeps that identity.
+
+`sequence` is assigned when an error is retained, in host arrival order.
+`latestSequence` describes the whole session even when filters select fewer
+records. `time` comes from document capture; `receivedAt` comes from the host.
+`kind` is `window.error`, `unhandledrejection`, or `application`. Window errors
+include `location: {file, line, column}` when the browser exposes those fields.
+Their browser `message` is retained separately from `error`, preserving a null
+or undefined error value rather than replacing it with that message.
+`details` and `location` are otherwise omitted.
+
+Records survive document navigation and Core transport failure within the host
+session. Closing the inspector leaves them retained. Closing the native host ends
+the session; this API does not persist, migrate, prune, or recover records across
+host restarts. An empty snapshot means no matching records were retained in this
+session, not that earlier failures never occurred. Errors before capture existed,
+handled failures never explicitly reported, errors the browser does not expose,
+and vanished documents whose pending reports never reached the host remain
+unavailable. Earlier never-retained failures cannot be reconstructed through this API.
+
+## Complete error property representation
+
+Each record uses `valueFormat: 'arcane.diagnostic-value/1'`. `error` and optional
+`details` are roots into the single `values` graph. JSON-native primitives remain
+their original values. Undefined, bigint, non-finite numbers and negative zero
+have explicit typed representations. `{ref: id}` identifies a graph node.
+Repeated references and cycles retain the same identity within the record.
+
+Object nodes retain every own property descriptor, including non-enumerable and
+symbol-keyed fields. This includes full Error messages and stacks, `cause`,
+AggregateError members and custom diagnostic details. Standard error fields
+inherited from a prototype appear in `inherited`. Data descriptors contain
+`value`; accessor descriptors contain references for `get` and `set` without
+invoking either function. An accessor supplied as the `details` option is likewise
+represented rather than called. No `toJSON` method on reported content is called.
+Maps and sets retain their entries, dates their numeric time, and regular
+expressions their source and flags, alongside their own properties.
+
+This is a diagnostic property representation, not an executable object snapshot:
+functions retain their property identity, not executable closures; platform-private
+internal state and private class fields are not observable properties. The host
+stores and returns the graph without reconstructing or executing those objects.
+An object that rejects reflection causes an observable reporting failure rather
+than a silently incomplete success. Inspect the complete graph in developer
+diagnostics; do not flatten it into ordinary chat or user-facing status.
+
+## Host ownership and availability
+
+`installNativeDiagnostics(globalThis)` installs one observer per document and
+returns its owner `{documentId, ready, report}`. `ready` resolves after the document
+announcement is accepted, and `report` has the same report contract. Importing
+the ESM module alone installs no observer. The packaged native host owns
+installation and lifetime; ordinary applications use `reportNativeError`.
+
+`createNativeDiagnosticsSource()` from
+`arcane-os/core/native-diagnostics-source` projects that same canonical helper
+into the top-level document-start script. It adds no second observer or serializer.
+Windows binds the script to the dedicated `arcaneDiagnostics.Send` host object.
+This route is independent of `arcaneBridge` and the Core subprocess. Host close
+stops new ingress and removes the object/script during existing shutdown.
+
+The implementation here supplies Windows WebView2 capture and app-control
+retrieval. macOS, Linux and Android require their native host ingress/session and
+app-control adapters; this source change does not claim those adapters exist.
+The helper recognizes the same fixed-name WebKit reply handler when a host
+provides it; that transport seam is not platform availability. A browser preview
+cannot establish actual native acceptance.
+
+Native delivery requires the corresponding rebuilt SDK Windows host asset and
+consumer adoption through the published SDK package. Source inspection, authored
+fixtures and configured capture are distinct from executed built-application
+verification. Existing host stderr/log diagnostics, live Core events, readiness
+replay and `Arcane.diagnostics.recentErrors/get` retain their existing semantics;
+this API does not turn them into a historical error service.

package/docs/reference/native-speech.md

@@ -6,8 +6,9 @@ from `arcane-os/core/speech`.
 
 The host supplies an STT engine, a TTS engine, or both. Construction performs no
 installation, model download, model loading, or inference. Core registration
-exposes `speech.status`, `speech.transcribe`, and `speech.synthesize`; an
-operation whose engine was omitted rejects with `SPEECH_ENGINE_UNAVAILABLE`.
+exposes `speech.status`, `speech.load`, `speech.unload`, `speech.transcribe`,
+and `speech.synthesize`; an operation whose engine was omitted rejects with
+`SPEECH_ENGINE_UNAVAILABLE`.
 The optional `signal` controls the service lifetime.
 
 ```js
@@ -20,11 +21,11 @@ const core = createCoreRuntime({services: [speech]});
 core.start();
 ```
 
-This service is the shared integration layer. It does not supply or install a
-Kokoro or Sherpa-ONNX engine. Engine preparation, model resources, device
-selection, supported formats, and native process ownership remain with the
-selected engine and its host composition. Browser-only operation remains
-independent of this native service.
+This service is the shared integration layer. The SDK separately exports the
+[native Kokoro engine](#native-kokoro-engine) from `arcane-os/local-ai/kokoro`.
+Engine preparation, model resources, device selection, supported formats, and
+native process ownership remain with the selected engine and its host
+composition. Browser-only operation remains independent of this native service.
 
 The SDK's [retained Whisper engine](local-whisper.md) supplies native STT.
 Its optional [Intel NPU encoder](../guides/native-whisper-openvino.md) uses the
@@ -59,6 +60,24 @@ model readiness. Existing readiness consumers additionally recognize
 the engine IDs `whisper.cpp` and `kokoro-onnx`; another engine ID requires the
 corresponding consumer integration.
 
+## Explicit role activation
+
+`speech.load({role, ...selection})` and `speech.unload({role, ...selection})`
+route only to the selected `stt` or `tts` engine. The service separates the
+`role` routing field and forwards the remaining selection fields unchanged,
+with the operation's signal. Each call returns that engine's complete result.
+An invalid role reports `SPEECH_ROLE_INVALID`; an engine without the requested
+method reports `SPEECH_OPERATION_UNAVAILABLE`. These calls do not alter the
+other speech role or select a browser provider.
+
+The browser facade is `Arcane.speech.load(request, {signal, onRequest})` and
+`Arcane.speech.unload(request, {signal, onRequest})`. Both use an unlimited Core
+request duration (`timeoutMs: 0`). Synthesis retains its existing
+`Arcane.speech.synthesize(request, {signal})` facade and 180-second timeout.
+Call `client.invoke('speech.synthesize', request, {signal, timeoutMs: 0, onRequest})`
+when the owning application explicitly needs an unlimited request duration or
+the actual request ID. The synthesis payload is the same through either path.
+
 ## Events and subscriptions
 
 `subscribe(listener, {replay = true, signal} = {})` immediately delivers the
@@ -78,6 +97,8 @@ that initial request is pending.
 The service emits `progress: {phase: 'accepted'}` synchronously when accepting
 a speech request. Subsequent progress is the selected engine's actual report;
 cancelled requests publish no later progress.
+Role load/unload acknowledgements additionally carry `operation: 'load'` or
+`'unload'` in that progress record.
 
 ## Engine interface
 
@@ -86,15 +107,18 @@ Each supplied engine implements:
 - `current()` returning the actual selected-model state.
 - `subscribe(listener)` with immediate current-state replay and an unsubscribe
   function.
-- `load({signal})`, resolving only after the constructor-selected model has
-  loaded. Independent engines may load concurrently.
+- `load({signal, ...selection})`, applying that engine's explicit selection
+  contract. Independent engines may load concurrently. Kokoro without selected
+  assets resolves to its ordinary unloaded state.
+- Optional `unload(selection)`, releasing the selected engine's model through
+  `speech.unload`; engines without this method report it unavailable.
 - `transcribe(request, {signal, onProgress, requestId})` for STT, or
   `synthesize(request, {signal, onProgress, requestId})` for TTS. `requestId` is
   the actual Core request's control metadata, separate from the unchanged payload.
 - `close()`, cancelling and joining its native work and releasing its resources.
 
-The service forwards each complete request and result unchanged. It applies
-no input trimming, content limits, model or voice substitution, transcript
+The service forwards each complete transcription/synthesis request and result
+unchanged. It applies no input trimming, content limits, model or voice substitution, transcript
 rewriting, or audio conversion. The engine owns any format decoding,
 phonemization, required model segmentation, output encoding, and supported
 model selection. Necessary processing must preserve complete ordered input
@@ -120,6 +144,191 @@ share one shutdown promise. Actual engine cleanup failures reject with an
 releases the service's event subscriptions. New work after shutdown begins
 rejects with `CORE_CLOSING`.
 
+## Native Kokoro engine
+
+`createNativeKokoroRuntime` is the named and default export from
+`arcane-os/local-ai/kokoro`. It uses the existing native ONNX owner for model
+execution and one retained C++ helper for eSpeak phonemization and Ogg Opus
+encoding. The Kokoro route requires no Python, Sherpa-ONNX or FFmpeg runtime.
+
+```js
+import {createNativeKokoroRuntime} from 'arcane-os/local-ai/kokoro';
+import {createSpeechService} from 'arcane-os/core/speech';
+
+const tts = createNativeKokoroRuntime({
+  onnx,          // The existing Core local-ai owner's getONNXRuntime() result.
+  modelAssets,   // The existing Core model-assets service.
+  runtime,       // Prepared helperExecutable, espeakDataDirectory, libraryDirectory.
+  executionPreference: 'cpu',
+  sessionOptions: {executionProviders: ['cpu']}
+});
+const speech = createSpeechService({tts});
+```
+
+The constructor accepts `{onnx, modelAssets, runtime, prepare, modelId, model,
+revision, dtype, paths, assetProjectionId, resourcePaths, sessionOptions,
+executionPreference, executionTarget, signal, onEvent}`. At least `onnx` or
+`prepare` must be supplied. Optional `prepare({signal})` returns `{onnx, runtime}`
+and runs only when an activation has selected assets and either its ONNX owner
+is absent or closed, or its helper descriptor is absent. It returns the host's
+existing ONNX owner; it does not construct another one. Construction performs
+no acquisition or loading.
+The helper data path is the **parent** containing `espeak-ng-data`.
+
+The provider ID is `kokoro-onnx`; the public `modelId` alias defaults to `kokoro`.
+The implemented model is `onnx-community/Kokoro-82M-v1.0-ONNX`, revision
+`1939ad2a8e416c0acfeecc08a694d14ef25f2231`, with `dtype: 'fp32'`. Another model,
+revision or dtype reports incompatibility. The module also exports
+`KOKORO_MODEL`, `KOKORO_REVISION`, `KOKORO_SAMPLE_RATE` (`24000`) and
+`KOKORO_VOICES`.
+
+### Resources and loading
+
+Supply either prepared native `paths` or an existing completed
+[`model-assets` projection](model-assets.md). Both mappings have
+`{model, tokenizer, tokenizerConfig, voices: {[voiceId]: path}}`: native paths
+identify prepared files, while `resourcePaths` identifies projection members.
+Projection loading requires the existing `modelAssets` service. Direct-path
+callers keep their prepared files available until engine cleanup completes.
+The complete selection contains `onnx/model.onnx`, `tokenizer.json`,
+`tokenizer_config.json`, and all 28 `voices/<voiceId>.bin` files from the same
+revision. The engine does not download models or create another model store.
+
+`load({modelId, assetProjectionId, resourcePaths, executionTarget, signal})`
+activates that selection. Omitted selection fields retain the previous choice;
+an omitted or undefined target retains the previous target, and `null` requests
+automatic selection. `modelId`, when supplied, must match this engine's alias.
+With neither constructor paths nor a projection selected, loading resolves
+unloaded without preparing the helper. Actual readiness requires the frontend
+resources, live helper and loaded ONNX session.
+
+For a complete DBOPFS-to-Core projection already prepared by the application:
+
+```js
+await Arcane.speech.load({
+  role: 'tts',
+  modelId: 'kokoro',
+  assetProjectionId: projection.id,
+  resourcePaths,
+  executionTarget: {deviceId: 'cpu'}
+}, {signal});
+```
+
+The engine retains the incoming projection before retiring a previous
+activation, including replacement using the same projection. It releases that
+retain only after frontend loading settles and the actual ONNX worker and
+helper exit. The preparation owner retains its own independent release duty.
+Cancelling a caller's `load` signal stops that caller's wait; explicit unload,
+replacement or engine close owns cancellation of the shared activation.
+After `localai.services.recover({runtimes: ['onnx']})` completes, a subsequent
+explicit `speech.load` uses the composition's `prepare` callback to reacquire
+the current ONNX owner after the previous activation's cleanup has joined.
+
+`executionPreference` defaults to `'gpu'` and accepts the existing ONNX CPU/GPU
+selection contract. `sessionOptions` and `executionTarget` reach that same
+owner unchanged. Explicit providers take precedence, and an explicit physical
+target is never retried on another device or provider. The automatic route's
+provider attempts and possible CPU selection remain visible in `execution`.
+STT keeps its own independent device selection. See
+[native ONNX execution targets](local-ai.md#physical-execution-targets);
+accepted configuration and actual physical execution are separate facts.
+
+### Synthesis, voices and state
+
+`synthesize(request, {signal, onProgress, requestId} = {})` accepts
+`{input, model?, voice?, speed?, responseFormat?}`. `input` is the complete
+string; optional `model` must match the alias. Defaults are voice `af_heart`,
+speed `1`, and format `wav`. Speed must be a positive finite float32 value.
+
+| English voice set | Exact supported IDs |
+| --- | --- |
+| US female | `af_heart`, `af_alloy`, `af_aoede`, `af_bella`, `af_jessica`, `af_kore`, `af_nicole`, `af_nova`, `af_river`, `af_sarah`, `af_sky` |
+| US male | `am_adam`, `am_echo`, `am_eric`, `am_fenrir`, `am_liam`, `am_michael`, `am_onyx`, `am_puck`, `am_santa` |
+| GB female | `bf_emma`, `bf_isabella`, `bf_alice`, `bf_lily` |
+| GB male | `bm_george`, `bm_lewis`, `bm_daniel`, `bm_fable` |
+
+The selected voice determines US or GB phonemization. Unsupported voices,
+formats and emitted phonemes report their actual errors; there is no silent
+voice substitution or phoneme omission. An embedded NUL or unpaired Unicode
+surrogate reports the public eSpeak interface's inability to consume that
+complete string. The engine preserves source text, consumes all returned
+clauses and divides model tokens into ordered segments according to the model's
+context. Each segment's complete waveform contributes to the final audio.
+
+The result is `{audioBase64, contentType, sampleRate: 24000, channels: 1,
+model, voice, speed}`. `wav` returns IEEE float32 WAV with `audio/wav`;
+`opus` and `ogg` both return finalized Ogg Opus with
+`audio/ogg; codecs=opus`. The result contains the complete encoded audio rather
+than a playback side effect. Synthesis requires a ready activation and proceeds
+in FIFO order. Progress reports the actual `phonemizing`, `synthesizing` and
+`encoding` phases; segment progress is not streamed audio.
+
+`current()` returns the selected model/provider, `state`, `loaded`, `busy`,
+active `requestId` (or `null` when omitted), `queuedRequests`, `pendingActivation`, `execution`,
+complete `progress` and serialized `error`, plus `defaultVoice` and `voices`.
+`subscribe(listener, {replay = true, signal} = {})` returns an unsubscribe
+function and replays that current state. Through Core, it appears in
+`speech.status().roles.tts` and `speech.state`.
+
+Cancelling a queued synthesis removes only that request. Cancelling active
+synthesis retires its native session/helper and joins their actual exit before
+settlement. Surviving queued requests retain their complete input and order;
+the next request reopens the same activation with the accepted provider options
+and the resolved device when known. It does not replay the cancelled synthesis or search for
+another provider. With no queued work, explicitly `load()` before new synthesis.
+Native ONNX cancellation can wait for an in-flight native call to return.
+
+`unload()` cancels the activation and its queued work, joins native cleanup and
+releases retained model assets. `close()` also disposes engine subscriptions;
+both preserve the host's shared ONNX owner and other engines. Cleanup errors
+remain complete and observable. The Core equivalent is
+`Arcane.speech.unload({role: 'tts'})`.
+
+### Native helper production and availability
+
+Windows x64 has a selected SDK helper archive, `arcane-kokoro-windows-x64.tar.gz`.
+[Runtime preparation](local-ai.md#native-kokoro-selection) resolves it from the
+installed SDK version's release. Linux and macOS use the shared JavaScript
+engine and native CMake source with an explicitly prepared, platform-matching
+complete helper tree or archive. Automatic Linux/macOS helper distributions
+are not provided; execution on those hosts remains unverified.
+
+SDK selected-output verification on October 7, 2026 used Node `26.7.0` and
+ONNX Runtime Node `1.30.0` with explicit CPU selection for the selected Windows
+helper and FP32 model. It covered US `af_heart` and GB `bf_emma` synthesis to WAV and Ogg Opus,
+including queued/active cancellation and a surviving queued request. This
+establishes that selected CPU output boundary, not GPU execution, other voices'
+pronunciation, listening acceptance or consumer application behavior.
+The subsequent Core-recovery reacquisition correction received source review
+only and was not part of those execution runs.
+
+The repository's [`tools/build-kokoro-runtime-windows.ps1`](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/tools/build-kokoro-runtime-windows.ps1)
+builds from prepared `espeak-ng`, `opus` and `libopusenc` source directories.
+Its selected inputs are the `csukuangfj/espeak-ng` fork at
+`ed530aa113046142eb5115cf2fc9157854d0ffe1` with its matching UCD and language data,
+libopus `1.6.1`, and libopusenc `0.3`. It uses installed CMake and Visual Studio
+2022 Build Tools, defaulting to MSVC `14.44.35207` and Windows SDK
+`10.0.26100.0`; it acquires no dependencies or model files.
+
+```powershell
+& ./tools/build-kokoro-runtime-windows.ps1 `
+  -SourceRoot ./.arcane/kokoro-source `
+  -OutputDirectory ./.arcane/kokoro-build `
+  -Component espeak
+```
+
+Run `espeak`, `opus` and `opusenc` components independently, concurrently when
+desired, using the same output directory. After all three complete, run
+`helper`, then `stage`. Each component retains complete command/result logs;
+do not run the same component concurrently in that output. The output must
+belong to `ProjectDirectory` and be separate from the prepared source tree.
+The staged helper, matching complete data, corresponding source and included
+terms travel together. The recipe statically links its selected libraries and
+retains their upstream notices alongside the SDK license. Model/voice assets
+and the separately selected ONNX runtime remain outside the helper package.
+This reusable recipe was source-reviewed; its publication does not claim a
+fresh execution of every component or a build on another operating system.
+
 ## AI built-in native speech readiness
 
 The `AI` module's `LOCAL_SPEACH` adapter observes `speech.state` before reading

package/docs/reference/runtime-modules.md

@@ -210,30 +210,33 @@ 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 errors pass through after the retry policy below;
-decoding errors pass through immediately. Cancellation
+successful-response decoding errors pass through immediately. 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.
-Rejected Fetch calls and HTTP `529` share a separate budget of three retries,
-each after the same `3000` millisecond delay. HTTP `429` overload retries do not
-consume that budget. The final complete network error or provider body passes
-through unchanged when recovery is exhausted. Aborts, other HTTP errors,
-successful-response body reads, stream decoding, and application callbacks
-never start another attempt.
+Rejected Fetch calls and all HTTP `429`/`529` responses share three retries.
+Quota messages need no `overload` keyword. A readable `Retry-After` controls a
+`429` wait; otherwise its upcoming retry number selects `3000`, `6000`, or
+`12000` milliseconds. Fetch rejection and `529` retain `3000` milliseconds.
+After a `429`, active requests to the same endpoint using the same credential
+share its cooldown and dispatch three seconds apart; other endpoints and
+credentials remain independent. The group is released when its last HTTP
+operation settles. See [TWiN recovery](ai/twin-cloud.md#shared-request-behavior)
+for the scope and lifetime.
+
+Every attempt uses the same destination, headers, complete serialized body,
+and signal. `onRequest` runs once. Cancellation stops waits and prevents another
+attempt. Recovery precedes successful-body consumption, so partial streams and
+tool callbacks are never replayed. Complete errors, including provider
+`status_code` and nested records, pass through unchanged on exhaustion.
+Diagnostic-body reading failures for `429`/`529` participate in recovery;
+other HTTP errors, successful-body reads, decoding, and callbacks do not.
 
 `fetchRequest()` and `streamRequest()` accept
 `onRetry({phase,attempt,delayMs,status,error})`. The observer receives
 `phase:'waiting'` before the abortable delay and `phase:'requesting'` immediately
-before the next Fetch. `attempt` is the one-based upcoming retry number across
-both retry policies; `delayMs` is `3000`; `status` is the HTTP status or `null`
+before the next Fetch. `attempt` is the one-based upcoming retry number, or zero
+for an initial request waiting behind a shared quota cooldown. `delayMs` is
+the initially selected wait; shared pacing can extend it. `status` is the HTTP status or `null`
 for rejected Fetch; `error` is the complete original failure value. The SDK
 invokes this observational callback synchronously and observes a returned
 promise without awaiting it. Callback throws and rejections are logged through