QVAC-18711 New content covering request lifecycle

[BrunoCampana]

Objective

• Update documentation: add content on how to cancel requests according to the new v0.11.0 implementation.
• Cover the QVAC-18180 epic specifically: everything relevant to the SDK user, except for the API reference.

Scope

Create a new "Cancellation" page.

[kinsta]

Preview deployments for qvac-docs-staging ⚡️

Status	Branch preview	Commit preview
✅ Ready	Visit preview	Visit preview

Commit: e47a14625867203596fb0abd9f469348b388f503

Deployment ID: 9a9c4053-a74a-462e-9138-28ccdc18a056

Static site name: qvac-docs-staging-fazwv

[github-actions]

Tier-based Approval Status

**PR Tier:** TIER1

**Current Status:** ✅ APPROVED

**Requirements:**
- 1 Team Member approval ✅ (1/1)
- 1 Team Lead OR Management approval ✅ (1/1)



---
*This comment is automatically updated when reviews change.*

[simon-iribarren]

Hey @BrunoCampana — thanks for getting this page in front of M3d. A few corrections needed because some of it predates the breaking-change wire-shape work that #2074 landed (the reason M3d is [bc]).

1. Stale wire shape in the "Other cancellable operations" callout

- Downloads: `cancel({ operation: "downloadAsset", downloadKey })` — see [Download lifecycle](/models/download-lifecycle).

The cancel({ operation: "downloadAsset", ... }) and cancel({ operation: "rag", ... }) wire shapes were removed in 0.11.0 — it's exactly what made #2074 [bc]. Replace with the requestId path:

const op = downloadAsset({ assetSrc: "..." });
await cancel({ requestId: op.requestId, clearCache: true });

2. The callout under-sells what's cancellable in 0.11.0

The callout currently says cancel() only covers completion(), embed(), and rag*(), and that transcribe() / translate() / textToSpeech() / ocr() / diffusion() "cannot yet be cancelled". In 0.11.0:

• Decorated-promise requestId is on: completion, loadModel, embed, transcribe, downloadAsset, ragIngest, ragSaveEmbeddings, ragReindex. All targeted-cancellable.
• Every server-side handler is on RequestRegistry. Handlers declaring cancel: { scope: "none" } (translate, textToSpeech, ocr, diffusion, upscale) do respect broad cancel via cancel({ modelId }) — the in-flight call yields when ctx.signal.aborted flips on the next yield point. They just don't get a hard mid-decode abort.

Suggested rewrite:

cancel() covers completion(), loadModel(), embed(), transcribe(), downloadAsset(), and rag*() targeted by requestId. translate(), textToSpeech(), ocr(), diffusion(), upscale() accept broad cancel by modelId but not mid-decode abort. transcribeStream(...) / textToSpeechStream(...) duplex sessions use .destroy(). Finetune still uses finetune({ operation: "cancel", ... }).

3. Broad-cancel section should show the new canonical shape

Currently only shows the legacy sugar:

await cancel({ operation: "inference", modelId });
await cancel({ operation: "embeddings", modelId });

These are kept as client-side aliases for source compat, but the canonical 0.11.0+ shape is { modelId, kind? }:

// Generic broad-cancel — preferred shape in 0.11.0+.
await cancel({ modelId });                            // every in-flight request on this model
await cancel({ modelId, kind: "completion" });        // narrow to completions
await cancel({ modelId, kind: "embeddings" });        // narrow to embeddings

// Legacy per-kind sugars — still supported via the client wrapper.
await cancel({ operation: "inference", modelId });
await cancel({ operation: "embeddings", modelId });

4. Errors section is missing two typed errors

M3d wired two more server-thrown classes through the typed-error RPC reconstructor — both are re-exported from @qvac/sdk for instanceof checks. They belong on this page:

• RequestNotFoundError (code 52418) — registry lookup miss; carries requestId. Rare in practice because cancel({ requestId }) for an already-terminated id is a no-op on the handler (returns success: true, cancelled: 0), but consumer code that narrows by class will see this for other call sites.
• RequestRejectedByPolicyError (code 52420) — registry concurrency-policy admission failure (e.g. oneAtATimePerModel). Carries requestId, kind, modelId, reason.

5. Cross-referenced page is stale (not in this PR, but worth flagging)

docs/website/content/docs/models/download-lifecycle.mdx describes the removed operation: "downloadAsset" shape end-to-end (lines ~9, 20, 22 and the embedded download-with-cancel example). With #2074 it's incorrect — the link from this new page lands users on a stale guide. Same applies to docs/website/content/docs/reference/api/index.mdx, which still documents both removed shapes.

These two pages aren't in the scope you scoped this PR to, but they need to land in lockstep with 0.11.0 for the docs story to be coherent. Happy to follow up with a separate PR for those if you'd rather keep this one tight.

---

Want me to push these fixes onto your branch as a single suggested-change commit, or would you prefer to fold them in yourself?

[BrunoCampana]

/review