@qvac/sdk 0.12.1 → 0.13.0

package/dist/examples/translation/translation-indic.js

@@ -5,7 +5,6 @@ import { loadModel, translate, unloadModel, MARIAN_EN_HI_INDIC_1B_Q4_0, } from "
 try {
     const modelId = await loadModel({
         modelSrc: MARIAN_EN_HI_INDIC_1B_Q4_0,
-        modelType: "nmt",
         onProgress: (progress) => {
             console.log(progress);
         },
@@ -20,7 +19,7 @@ try {
     const result = translate({
         modelId,
         text,
-        modelType: "nmt",
+        modelType: "nmtcpp-translation",
         stream: false,
     });
     const translatedText = await result.text;

package/dist/examples/translation/translation-llm-afriquegemma.js

@@ -2,7 +2,6 @@ import { translate, loadModel, unloadModel, AFRICAN_4B_TRANSLATION_Q4_K_M, } fro
 try {
     const modelId = await loadModel({
         modelSrc: AFRICAN_4B_TRANSLATION_Q4_K_M,
-        modelType: "llm",
         onProgress: (progress) => {
             console.log(progress);
         },
@@ -16,8 +15,8 @@ try {
             repeat_penalty: 1,
             seed: 42,
             predict: 256,
-            stop_sequences: ['\n']
-        }
+            stop_sequences: ["\n"],
+        },
     });
     // With explicit source language
     const engText = "Hello, how are you today?";
@@ -26,7 +25,7 @@ try {
         text: engText,
         from: "en",
         to: "swh_Latn",
-        modelType: "llm",
+        modelType: "llamacpp-completion",
         stream: false,
     });
     const translatedTextExplicit = await resultExplicit.text;

package/dist/examples/translation/translation-llm-context.js

@@ -2,7 +2,6 @@ import { translate, loadModel, unloadModel, SALAMANDRATA_2B_INST_Q8, } from "@qv
 try {
     const modelId = await loadModel({
         modelSrc: SALAMANDRATA_2B_INST_Q8,
-        modelType: "llm",
         onProgress: (progress) => {
             console.log(progress);
         },
@@ -15,7 +14,7 @@ try {
         text: engText,
         from: "en",
         to: "es",
-        modelType: "llm",
+        modelType: "llamacpp-completion",
         context: "Use formal language, letter for financial institution",
         stream: false,
     });

package/dist/examples/translation/translation-llm.js

@@ -2,7 +2,6 @@ import { translate, loadModel, unloadModel, SALAMANDRATA_2B_INST_Q4, } from "@qv
 try {
     const modelId = await loadModel({
         modelSrc: SALAMANDRATA_2B_INST_Q4,
-        modelType: "llm",
         onProgress: (progress) => {
             console.log(progress);
         },
@@ -14,7 +13,7 @@ try {
         text: engText,
         from: "en",
         to: "it",
-        modelType: "llm",
+        modelType: "llamacpp-completion",
         stream: false,
     });
     const translatedTextExplicit = await resultExplicit.text;
@@ -24,7 +23,7 @@ try {
         modelId,
         text: espText,
         to: "en",
-        modelType: "llm",
+        modelType: "llamacpp-completion",
         stream: false,
     });
     const translatedTextAutodetect = await resultAutodetect.text;

package/dist/examples/translation/translation-stream.js

@@ -1,8 +1,7 @@
-import { loadModel, translate, unloadModel, BERGAMOT_EN_ES, } from "@qvac/sdk";
+import { loadModel, translate, unloadModel, BERGAMOT_EN_ES } from "@qvac/sdk";
 try {
     const modelId = await loadModel({
         modelSrc: BERGAMOT_EN_ES,
-        modelType: "nmt",
         modelConfig: {
             engine: "Bergamot",
             from: "en",
@@ -15,7 +14,7 @@ try {
     const streamResult = translate({
         modelId,
         text,
-        modelType: "nmt",
+        modelType: "nmtcpp-translation",
         stream: true,
     });
     process.stdout.write("Translated text EN -> ES: ");

package/dist/examples/tts/chatterbox.js

@@ -7,8 +7,7 @@ const [referenceAudioSrc] = process.argv.slice(2);
 const CHATTERBOX_SAMPLE_RATE = 24000;
 try {
     const modelId = await loadModel({
-        modelSrc: TTS_T3_TURBO_EN_CHATTERBOX_Q8_0.src,
-        modelType: "tts",
+        modelSrc: TTS_T3_TURBO_EN_CHATTERBOX_Q8_0,
         modelConfig: {
             ttsEngine: "chatterbox",
             language: "en",

package/dist/examples/tts/llm-to-tts-streaming.js

@@ -59,8 +59,7 @@ function appendPcmSamples(target, chunk) {
 try {
     console.log(`Loading LLM from registry: ${LLAMA_3_2_1B_INST_Q4_0.name}`);
     const llmModelId = await loadModel({
-        modelSrc: LLAMA_3_2_1B_INST_Q4_0.src,
-        modelType: "llm",
+        modelSrc: LLAMA_3_2_1B_INST_Q4_0,
         modelConfig: {
             ctx_size: 2048,
         },
@@ -69,8 +68,7 @@ try {
     console.log(`LLM ready: ${llmModelId}`);
     console.log("Loading Supertonic TTS (registry)…");
     const ttsModelId = await loadModel({
-        modelSrc: TTS_EN_SUPERTONIC_Q8_0.src,
-        modelType: "tts",
+        modelSrc: TTS_EN_SUPERTONIC_Q8_0,
         modelConfig: {
             ttsEngine: "supertonic",
             language: "en",

package/dist/examples/tts/supertonic-multilingual.js

@@ -4,8 +4,7 @@ import { createWav, playAudio, int16ArrayToBuffer, createWavHeader, } from "./ut
 const SUPERTONIC_SAMPLE_RATE = 44100;
 try {
     const modelId = await loadModel({
-        modelSrc: TTS_MULTILINGUAL_SUPERTONIC2_Q8_0.src,
-        modelType: "tts",
+        modelSrc: TTS_MULTILINGUAL_SUPERTONIC2_Q8_0,
         modelConfig: {
             ttsEngine: "supertonic",
             language: "es",

package/dist/examples/tts/supertonic.js

@@ -5,8 +5,7 @@ import { createWav, playAudio, int16ArrayToBuffer, createWavHeader, } from "./ut
 const SUPERTONIC_SAMPLE_RATE = 44100;
 try {
     const modelId = await loadModel({
-        modelSrc: TTS_EN_SUPERTONIC_Q8_0.src,
-        modelType: "tts",
+        modelSrc: TTS_EN_SUPERTONIC_Q8_0,
         modelConfig: {
             ttsEngine: "supertonic",
             language: "en",

package/dist/examples/vla-pi05.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=vla-pi05.d.ts.map

package/dist/examples/vla-pi05.js

@@ -0,0 +1,84 @@
+/**
+ * π₀.₅ (pi05) vision-language-action example using the QVAC SDK.
+ *
+ * Loads the Physical Intelligence π₀.₅ GGUF model, runs a single inference
+ * pass with synthetic inputs (zero-filled gray images + BOS-only tokens +
+ * seeded noise), and prints the produced action chunk + per-stage timings.
+ *
+ * π₀.₅ differs from SmolVLA in two ways the SDK surfaces via `vlaHparams()`:
+ *   - `numCameras: 3` — it expects exactly three camera frames (not two).
+ *   - `stateInputMode: 'discrete'` — the robot state is tokenised into the
+ *     language prompt, so the `state` buffer is ignored. We pass an empty
+ *     `Float32Array(0)`. π₀.₅ also requires the `noise` prior.
+ *
+ * Usage:
+ *   bun examples/vla-pi05.ts [path-to-pi05.gguf]
+ *
+ * By default the example pulls the registry-baked π₀.₅ GGUF (~3.9 GB) on
+ * first run and caches it locally. Pass an absolute path on the command line
+ * to override and load a local GGUF instead.
+ */
+import { close, loadModel, PI05_BASE_Q_AGGRESSIVE, unloadModel, vla, vlaHparams, vlaPreprocessImage, } from "@qvac/sdk";
+const modelSrcOverride = process.argv[2];
+const modelSrc = modelSrcOverride ?? PI05_BASE_Q_AGGRESSIVE;
+try {
+    console.log("Loading π₀.₅ (pi05) model...");
+    const modelId = await loadModel({
+        modelSrc,
+        modelType: "ggml-vla",
+        modelConfig: { backend: "cpu" },
+        onProgress: (p) => typeof modelSrc === "string"
+            ? undefined
+            : process.stdout.write(`\rDownloading: ${p.percentage.toFixed(1)}%`),
+    });
+    if (typeof modelSrc !== "string")
+        process.stdout.write("\n");
+    console.log(`Model loaded: ${modelId}`);
+    const { hparams, backendName } = await vlaHparams({ modelId });
+    console.log(`Backend: ${backendName ?? "(unknown)"}`);
+    console.log("Hparams:", hparams);
+    // Build synthetic inputs sized to the model's expectations. A real
+    // consumer would: read camera frames, tokenize the instruction with the
+    // model's tokenizer, and (for π₀.₅) inline the robot state into the prompt.
+    const size = hparams.visionImageSize;
+    const numCameras = hparams.numCameras ?? 3;
+    const dummyPixels = new Uint8Array(size * size * 3).fill(128);
+    // π₀.₅ expects exactly `numCameras` frames.
+    const images = Array.from({ length: numCameras }, () => vlaPreprocessImage(dummyPixels, size, size, { size }));
+    const tokens = new Int32Array(hparams.tokenizerMaxLength);
+    const mask = new Uint8Array(hparams.tokenizerMaxLength);
+    // BOS-only "instruction" for the smoke test.
+    tokens[0] = 1;
+    mask[0] = 1;
+    // Discrete-state model: the state buffer is ignored (state is tokenised
+    // into the prompt), so pass an empty Float32Array. π₀.₅ requires `noise`.
+    const state = new Float32Array(0);
+    const noise = new Float32Array(hparams.chunkSize * hparams.maxActionDim);
+    console.log("Running VLA inference...");
+    const { actions, actionDim, chunkSize, stats } = await vla({
+        modelId,
+        images,
+        imgWidth: size,
+        imgHeight: size,
+        state,
+        tokens,
+        mask,
+        noise,
+    });
+    console.log(`Got ${chunkSize} action steps of dim ${actionDim}.`);
+    console.log("First step:", Array.from(actions.subarray(0, actionDim)));
+    if (stats) {
+        console.log(`Timing: vision=${stats.vision_ms?.toFixed(0)}ms ` +
+            `prefill=${stats.prefill_total_ms?.toFixed(0)}ms ` +
+            `ode=${stats.ode_ms?.toFixed(0)}ms ` +
+            `total=${stats.total_ms?.toFixed(0)}ms`);
+    }
+    await unloadModel({ modelId, clearStorage: false });
+    console.log("Model unloaded.");
+    process.exit(0);
+}
+catch (error) {
+    console.error("π₀.₅ example failed:", error);
+    await close();
+    process.exit(1);
+}

package/dist/examples/vla-smolvla.js

@@ -19,7 +19,7 @@ try {
     console.log("Loading SmolVLA model...");
     const modelId = await loadModel({
         modelSrc,
-        modelType: "vla",
+        modelType: "ggml-vla",
         modelConfig: { backend: "cpu" },
         onProgress: (p) => typeof modelSrc === "string"
             ? undefined

package/dist/examples/voice-assistant/voice-assistant.js

@@ -76,7 +76,6 @@ for (const tool of ["ffmpeg", "ffplay"]) {
 console.log("Loading whisper-tiny + Silero VAD...");
 const asrModelId = await loadModel({
     modelSrc: WHISPER_TINY,
-    modelType: "whisper",
     modelConfig: {
         vadModelSrc: VAD_SILERO_5_1_2,
         audio_format: "f32le",
@@ -93,15 +92,13 @@ const asrModelId = await loadModel({
 console.log("Loading Llama 3.2 1B...");
 const llmModelId = await loadModel({
     modelSrc: LLAMA_3_2_1B_INST_Q4_0,
-    modelType: "llm",
     modelConfig: {
         ctx_size: 4096,
     },
 });
 console.log("Loading Supertonic TTS...");
 const ttsModelId = await loadModel({
-    modelSrc: TTS_EN_SUPERTONIC_Q8_0.src,
-    modelType: "tts",
+    modelSrc: TTS_EN_SUPERTONIC_Q8_0,
     modelConfig: {
         ttsEngine: "supertonic",
         language: "en",

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import "#polyfill-bare-globals";
-export { completion, deleteCache, loadModel, downloadAsset, heartbeat, startQVACProvider, stopQVACProvider, unloadModel, transcribe, transcribeStream, embed, finetune, translate, cancel, ragChunk, ragIngest, ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings, ragReindex, ragListWorkspaces, ragCloseWorkspace, ragDeleteWorkspace, textToSpeech, textToSpeechStream, getModelInfo, getLoadedModelInfo, loggingStream, ocr, invokePlugin, invokePluginStream, diffusion, type DiffusionProgressTick, classify, video, type VideoProgressTick, upscale, modelRegistryList, modelRegistrySearch, modelRegistryGetModel, type ModelRegistrySearchParams, suspend, resume, state, vla, vlaHparams, vlaPreprocessImage, vlaPadState, VLA_DEFAULT_IMAGE_SIZE, type FinetuneHandle, } from "./client/api/index";
+export { completion, deleteCache, loadModel, downloadAsset, heartbeat, startQVACProvider, stopQVACProvider, unloadModel, transcribe, transcribeStream, bciTranscribe, bciTranscribeStream, embed, finetune, translate, cancel, ragChunk, ragIngest, ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings, ragReindex, ragListWorkspaces, ragCloseWorkspace, ragDeleteWorkspace, textToSpeech, textToSpeechStream, getModelInfo, getLoadedModelInfo, loggingStream, ocr, invokePlugin, invokePluginStream, diffusion, type DiffusionProgressTick, classify, video, type VideoProgressTick, upscale, modelRegistryList, modelRegistrySearch, modelRegistryGetModel, type ModelRegistrySearchParams, suspend, resume, state, vla, vlaHparams, vlaPreprocessImage, vlaPadState, VLA_DEFAULT_IMAGE_SIZE, type FinetuneHandle, } from "./client/api/index";
 export { close } from "./client/index";
 export { plugins } from "./client/plugins-factory";
-export { type LifecycleState, type ModelProgressUpdate, type LoadModelOptions, type LoadCustomPluginModelOptions, type DownloadAssetOptions, type Tool, type ToolCall, type ToolCallWithCall, type ToolCallError, type ToolCallEvent, type CompletionEvent, type CompletionFinal, type CompletionRun, type CompletionStats, type EmbedStats, VERBOSITY, type Attachment, type TranscribeStreamSession, type TranscribeStreamMetadataSession, type TranscribeStreamConversationSession, type TranscribeStreamEvent, type VadStateEvent, type EndOfTurnEvent, type TranscribeSegment, type TextToSpeechStreamSession, type TextToSpeechStreamResponse, type TextToSpeechStreamClientParams, type CompletionParams, type ToolDialect, type RagSearchResult, type RagSaveEmbeddingsResult, type RagReindexResult, type RagEmbeddedDoc, type RagDoc, type RagWorkspaceInfo, type RagCloseWorkspaceParams, type RagDeleteWorkspaceParams, type RagIngestStage, type RagReindexStage, type RagSaveStage, SDK_CLIENT_ERROR_CODES, SDK_SERVER_ERROR_CODES, RAG_ERROR_CODES, type QvacConfig, type ModelInfo, type GetModelInfoParams, type GetLoadedModelInfoParams, type LoadedModelInfo, type LoadedInstance, type CacheFileInfo, toolSchema, TOOLS_MODE, type ToolsMode, type McpClient, type McpClientInput, type OCRClientParams, type OCRTextBlock, type OCROptions, type ClassifyClientParams, type ClassificationResult, type DiffusionClientParams, type DiffusionStreamResponse, type DiffusionStats, type VideoClientParams, type VideoStreamResponse, type VideoStats, type UpscaleClientParams, type UpscaleStreamResponse, type UpscaleStats, type VlaConfig, type VlaClientRunParams, type VlaClientRunResult, type VlaHparams, type VlaStats, definePlugin, defineHandler, defineDuplexHandler, type QvacPlugin, type CreateModelParams, type PluginModelResult, type ModelRegistryEntry, type ModelRegistryEntryAddon, PLUGIN_LLM, PLUGIN_EMBEDDING, PLUGIN_WHISPER, PLUGIN_NMT, PLUGIN_TTS, PLUGIN_OCR, PLUGIN_DIFFUSION, PLUGIN_VLA, PLUGIN_CLASSIFICATION, SDK_DEFAULT_PLUGINS, type BuiltinPlugin, type ProfilerMode, type FinetuneValidation, type FinetuneRunParams, type FinetuneGetStateParams, type FinetuneStopParams, type FinetuneParams, type FinetuneStatus, type FinetuneProgress, type FinetuneStats, type FinetuneResult, } from "./schemas/index";
+export { type LifecycleState, type ModelProgressUpdate, type LoadModelOptions, type LoadCustomPluginModelOptions, type DownloadAssetOptions, type Tool, type ToolCall, type ToolCallWithCall, type ToolCallError, type ToolCallEvent, type CompletionEvent, type CompletionFinal, type CompletionRun, type CompletionStats, type EmbedStats, VERBOSITY, type Attachment, type TranscribeStreamSession, type TranscribeStreamMetadataSession, type TranscribeStreamConversationSession, type TranscribeStreamEvent, type VadStateEvent, type EndOfTurnEvent, type TranscribeSegment, type BciConfig, type BciTranscribeClientParams, type BciTranscribeStreamClientParams, type BciTranscribeStreamSession, type BciTranscribeStreamMetadataSession, type BciStreamOpts, type NeuralInput, type TextToSpeechStreamSession, type TextToSpeechStreamResponse, type TextToSpeechStreamClientParams, type CompletionParams, type ToolDialect, type RagSearchResult, type RagSaveEmbeddingsResult, type RagReindexResult, type RagEmbeddedDoc, type RagDoc, type RagWorkspaceInfo, type RagCloseWorkspaceParams, type RagDeleteWorkspaceParams, type RagIngestStage, type RagReindexStage, type RagSaveStage, SDK_CLIENT_ERROR_CODES, SDK_SERVER_ERROR_CODES, RAG_ERROR_CODES, type QvacConfig, type ModelInfo, type GetModelInfoParams, type GetLoadedModelInfoParams, type LoadedModelInfo, type LoadedInstance, type CacheFileInfo, toolSchema, TOOLS_MODE, type ToolsMode, type McpClient, type McpClientInput, type OCRClientParams, type OCRTextBlock, type OCROptions, type ClassifyClientParams, type ClassificationResult, type DiffusionClientParams, type DiffusionStreamResponse, type DiffusionStats, type VideoClientParams, type VideoStreamResponse, type VideoStats, type UpscaleClientParams, type UpscaleStreamResponse, type UpscaleStats, type VlaConfig, type VlaClientRunParams, type VlaClientRunResult, type VlaHparams, type VlaStats, definePlugin, defineHandler, defineDuplexHandler, type QvacPlugin, type CreateModelParams, type PluginModelResult, type ModelRegistryEntry, type ModelRegistryEntryAddon, PLUGIN_LLM, PLUGIN_EMBEDDING, PLUGIN_WHISPER, PLUGIN_BCI, PLUGIN_NMT, PLUGIN_TTS, PLUGIN_OCR, PLUGIN_DIFFUSION, PLUGIN_VLA, PLUGIN_CLASSIFICATION, SDK_DEFAULT_PLUGINS, type BuiltinPlugin, type ProfilerMode, type FinetuneValidation, type FinetuneRunParams, type FinetuneGetStateParams, type FinetuneStopParams, type FinetuneParams, type FinetuneStatus, type FinetuneProgress, type FinetuneStats, type FinetuneResult, } from "./schemas/index";
 export { type ToolInput, type ToolHandler } from "./utils/tool-helpers";
 export { MODEL_TYPES, ModelType } from "./schemas/index";
 export * from "./models/registry/index";

package/dist/index.js

@@ -1,9 +1,9 @@
 import "#polyfill-bare-globals";
 // Public API exports only
-export { completion, deleteCache, loadModel, downloadAsset, heartbeat, startQVACProvider, stopQVACProvider, unloadModel, transcribe, transcribeStream, embed, finetune, translate, cancel, ragChunk, ragIngest, ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings, ragReindex, ragListWorkspaces, ragCloseWorkspace, ragDeleteWorkspace, textToSpeech, textToSpeechStream, getModelInfo, getLoadedModelInfo, loggingStream, ocr, invokePlugin, invokePluginStream, diffusion, classify, video, upscale, modelRegistryList, modelRegistrySearch, modelRegistryGetModel, suspend, resume, state, vla, vlaHparams, vlaPreprocessImage, vlaPadState, VLA_DEFAULT_IMAGE_SIZE, } from "./client/api/index.js";
+export { completion, deleteCache, loadModel, downloadAsset, heartbeat, startQVACProvider, stopQVACProvider, unloadModel, transcribe, transcribeStream, bciTranscribe, bciTranscribeStream, embed, finetune, translate, cancel, ragChunk, ragIngest, ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings, ragReindex, ragListWorkspaces, ragCloseWorkspace, ragDeleteWorkspace, textToSpeech, textToSpeechStream, getModelInfo, getLoadedModelInfo, loggingStream, ocr, invokePlugin, invokePluginStream, diffusion, classify, video, upscale, modelRegistryList, modelRegistrySearch, modelRegistryGetModel, suspend, resume, state, vla, vlaHparams, vlaPreprocessImage, vlaPadState, VLA_DEFAULT_IMAGE_SIZE, } from "./client/api/index.js";
 export { close } from "./client/index.js";
 export { plugins } from "./client/plugins-factory.js";
-export { VERBOSITY, SDK_CLIENT_ERROR_CODES, SDK_SERVER_ERROR_CODES, RAG_ERROR_CODES, toolSchema, TOOLS_MODE, definePlugin, defineHandler, defineDuplexHandler, PLUGIN_LLM, PLUGIN_EMBEDDING, PLUGIN_WHISPER, PLUGIN_NMT, PLUGIN_TTS, PLUGIN_OCR, PLUGIN_DIFFUSION, PLUGIN_VLA, PLUGIN_CLASSIFICATION, SDK_DEFAULT_PLUGINS, } from "./schemas/index.js";
+export { VERBOSITY, SDK_CLIENT_ERROR_CODES, SDK_SERVER_ERROR_CODES, RAG_ERROR_CODES, toolSchema, TOOLS_MODE, definePlugin, defineHandler, defineDuplexHandler, PLUGIN_LLM, PLUGIN_EMBEDDING, PLUGIN_WHISPER, PLUGIN_BCI, PLUGIN_NMT, PLUGIN_TTS, PLUGIN_OCR, PLUGIN_DIFFUSION, PLUGIN_VLA, PLUGIN_CLASSIFICATION, SDK_DEFAULT_PLUGINS, } from "./schemas/index.js";
 export {} from "./utils/tool-helpers.js";
 // Model types - canonical naming with backward-compatible aliases
 export { MODEL_TYPES, ModelType } from "./schemas/index.js";
@@ -15,13 +15,15 @@ export { SUPPORTED_AUDIO_FORMATS } from "./constants/audio.js";
 // envelope, but consumers reach for it through `instanceof` on
 // `await run.final` / `run.text` / `run.toolCalls` / `run.stats`
 // rejections. `RequestRejectedByPolicyError` is thrown by
-// `RequestRegistry.begin(...)` when a registered concurrency policy
-// (e.g. `oneAtATimePerModel` on `completion`) rejects a new request;
-// it propagates out through the worker so the client can distinguish
-// "the request collided with another one" from "the request failed".
+// `await RequestRegistry.begin(...)` when a registered concurrency policy
+// refuses a new request. With the default queue policy a same-model
+// `completion` no longer rejects — it waits FIFO — so this now surfaces the
+// bounded-queue cases: `onOverflow: "reject"`, the per-model queue-depth cap,
+// or a `queueTimeoutMs` elapsing. It propagates out through the worker so the
+// client can distinguish "the model is saturated" from "the request failed".
 //
 // `RequestIdConflictError` and `RequestNotFoundError` are thrown by
-// `RequestRegistry.begin(...)` / `.end(...)` on UUID collisions and
+// `await RequestRegistry.begin(...)` / `.end(...)` on UUID collisions and
 // missing-target cancels. They're surfaced here so consumers using
 // the decorated-promise `requestId` can pattern-match on rejected
 // cancel paths. All three classes round-trip the RPC boundary via