arcane-os 0.93.0 → 0.94.0

package/docs/reference/local-ai.md

@@ -1,13 +1,16 @@
 # Local AI through Core
 
 Core owns native llama.cpp and Ollama processes, ONNX worker sessions,
-selected local image generation and retained Whisper transcription. The browser retains its own
+selected local image generation, retained Whisper transcription and native
+Kokoro synthesis. The browser retains its own
 Wllama and ONNX implementations, and can also use an explicitly connected Core
 when that system service is available. Runtime installation, model loading and
 inference are separate operations.
 
 Native ONNX runs caller-selected graphs with complete named input/output tensors.
-Applications own preprocessing, tokenization and model-specific pipelines.
+Applications own preprocessing, tokenization and model-specific pipelines unless
+they explicitly select an SDK engine such as native Kokoro, which owns its
+versioned speech frontend.
 Browser ONNX continues through its existing browser implementation.
 
 ## Application requirements
@@ -113,6 +116,71 @@ the SDK does not guess a companion location. Installation records distinguish
 the distribution's `backend` from its `requestedBackend` execution mode.
 Selecting an unavailable distribution reports its actual error.
 
+### Native Kokoro selection
+
+Select both the existing ONNX runtime and the native speech helper:
+
+```json
+{
+  "runtimes": [
+    {"id": "onnx"},
+    {"id": "kokoro-native", "modelId": "kokoro"}
+  ]
+}
+```
+
+`kokoro-native` is the installable helper ID, `kokoro-onnx` is the speech
+provider ID, and `kokoro` is the default model alias. The requirement also
+preserves `model`, `revision`, `dtype`, prepared `paths`, `assetProjectionId`,
+`resourcePaths`, `sessionOptions`, `executionPreference` and `executionTarget`
+for the engine. The implemented model/revision, complete resource mapping,
+voices, synthesis formats and cancellation contract are in
+[native speech](native-speech.md#native-kokoro-engine).
+
+With no `helperRoot` or `url`, Windows x64 preparation selects
+`arcane-kokoro-windows-x64.tar.gz` from the installed SDK's numeric release:
+`https://github.com/TheWizardNexus/arcane-os-sdk/releases/download/<sdk-version>/arcane-kokoro-windows-x64.tar.gz`.
+That SDK version selects the default helper release; an authored runtime
+`version` alone does not select another SDK release's helper.
+An explicit `url` selects a complete platform-matching archive, with optional
+`version` metadata. Alternatively, `helperRoot` supplies an already prepared
+complete tree copied into the new installation. Select one of these sources.
+Linux and macOS currently require that explicit archive or prepared tree;
+the native CMake source is available, with no claim of an exercised helper
+build on those platforms.
+
+The helper record accepts `helperExecutable`, `espeakDataDirectory` and
+`libraryDirectory` overrides within the selected tree. Defaults are
+`bin/arcane-kokoro.exe` on Windows (`bin/arcane-kokoro` elsewhere), `share`, and
+`bin`. The data field identifies the parent containing `espeak-ng-data`.
+Overrides are relative to the selected tree or absolute locations inside
+`helperRoot`; all three paths relocate with that complete tree. Installation
+prepares the helper and its matching data, independently of ONNX and without
+downloading model weights, tokenizer files or voices.
+
+Development and generated native composition register this engine as the TTS
+role of `createSpeechService`, sharing the existing model-assets service and
+the selected local-ai ONNX owner. Whisper, when selected, retains the separate
+STT role and device choice. Construction and no-assets startup leave Kokoro
+unloaded without helper preparation. An explicit activation with prepared
+resources acquires the helper in development and waits only for that existing
+ONNX owner. Native packaging has already bundled the helper. These waits stay
+inside speech activation; page rendering and independent services continue.
+Omitting the explicit `onnx` requirement reports unavailability on activation.
+After an explicit `localai.services.recover({runtimes: ['onnx']})` completes,
+the next explicit `speech.load({role: 'tts', ...selection})` reacquires the
+current ONNX owner through existing preparation, after prior activation cleanup.
+
+For saved browser assets, prepare the complete projection through the existing
+[`model-assets` owner](model-assets.md), then call
+`Arcane.speech.load({role: 'tts', modelId: 'kokoro', assetProjectionId,
+resourcePaths, executionTarget}, {signal})`. Core retains the incoming
+projection before replacing its activation and releases it only after native
+exit. Preparing/loading a model remains separate from installing the helper.
+Raw constructor `paths` are caller-prepared native paths; portable assembly
+does not turn external model paths or a prior process's projection ID into
+packaged resources. Prepare the intended model resources at their actual host.
+
 ## Development
 
 ```sh
@@ -125,6 +193,8 @@ configuration. Subsequent `arcane dev` runs reuse the saved requirements.
 application selects its `models` in the runtime record before requesting a
 load or generation. The development owner composes separate image and
 model-assets services alongside the existing chat/ONNX service.
+`--local-ai onnx,kokoro-native` records the native TTS requirements above;
+its model activation remains explicit when no assets are configured.
 Development checks selected endpoints and existing executable paths, then
 installs missing runtimes under the application's `.arcane/local-ai/runtimes`.
 Runtime preparation runs alongside HTTP serving. Browser rendering continues
@@ -174,8 +244,8 @@ processes. An already running external service remains running.
 handle with `ready`, `current()`, `handler()` and `close()`. Its `ready` promise
 means Core composition has started, not that installation or a selected model
 is ready. Runtime preparation continues at each owning service. `current()`
-includes separate `core`, `localAI` and optional `image` state; image status
-remains callable during preparation. Composition failures reject `ready`;
+includes separate `core`, `localAI` and optional `image` and `speech` state;
+image status remains callable during preparation. Composition failures reject `ready`;
 later service preparation failures remain on Core lifecycle and diagnostic
 events. Page rendering waits for neither.
 
@@ -227,7 +297,8 @@ owner; it neither prepares another runtime nor loads a model. An unselected
 engine reports `LOCAL_AI_RUNTIME_NOT_SELECTED`; an unavailable or recovering
 owner reports `LOCAL_AI_RUNTIME_UNAVAILABLE`, and an aborted service lifetime
 retains its abort reason. Development and generated native compositions register
-one shared model-assets service when ONNX or image generation is selected.
+one shared model-assets service when ONNX, llama.cpp, image generation or
+native Kokoro is selected.
 
 Reacquire `getONNXRuntime()` on each explicit model load because runtime recovery
 replaces that owner. Retain the acquired handle for that session's cleanup and
@@ -757,6 +828,11 @@ retains that metadata with the complete native libraries. Image records include
 `libraryPath`,
 `bindingModulePath`, requested `backend`, installed `variants` and selected
 `models` metadata. Variant records carry backend, runtime root and library path.
+Kokoro records include `helperExecutable`, `espeakDataDirectory` and
+`libraryDirectory`; bundling preserves the complete helper tree under
+`runtime/local-ai/kokoro-native` and makes all three paths artifact-relative.
+The generated entry resolves them on the destination host and obtains the
+existing ONNX owner when the selected TTS activation needs it.
 Bundle returns `{runtimes,files}`,
 with artifact-relative runtime paths and a complete emitted file inventory.
 Bundling requires a fresh native staging destination, preserving existing

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