QVAC-18183 feat[api]: non-inference migrations + decorated-promise requestId

[simon-iribarren]

🎯 What problem does this PR solve?

• loadModel, downloadAsset, and rag were the last three long-running server-side handlers without registry-routed cancellation. Cancelling them meant either reaching into cancelHandler.ts's legacy case "downloadAsset" / case "rag" arms (workspace-wide or download-key-wide blast radius) or waiting for shutdown — there was no cancel({ requestId }) parity with completion/embeddings/transcribe/etc.
• Both kinds also carried their own out-of-band cancel-tracking maps: activeTransfers (download-manager.ts) and activeOperations (rag-operation-manager.ts). Two sources of truth for "what's running" meant cancel routing through registry.cancel(...) could disagree with the ad-hoc maps, especially during shutdown sweeps.
• The Promise-shaped public-API calls (loadModel(...), downloadAsset(...)) didn't expose requestId synchronously, so a client UI couldn't wire a Stop button to a specific in-flight call before its await resolved — only completion(...) had that contract (via the CompletionRun object).

📝 How does it solve it?

• rag (kind "rag") — server/rpc/handlers/rag.ts now opens await using ctx = registry.begin({ kind: "rag" }) for every workspace-bound op (ingest, saveEmbeddings, reindex). rag-operation-manager.ts is rewritten around a small workspace → requestId map plus a shutdown sweep (cancelAllRagOperations). The old activeOperations / registerRagOperation / unregisterRagOperation / cancelRagOperation API is removed.
• downloadAsset (kind "downloadAsset") — handler wraps the resolve flow in registry.begin(...) and threads ctx.signal plus a DownloadHooks.requestBinding into resolveModelPath(...). In download-manager.ts, startOrJoinDownload now accepts a per-subscriber binding ({ signal, scope, requestId }). Content-addressed dedup keyed on downloadKey is preserved (two callers requesting the same artifact still share one transfer) but each subscriber attaches an abort listener that rejects its promise alone, and the new maybeCancelTransfer(transfer) helper aborts the underlying transfer only when the last subscriber leaves. scope.defer(() => removeSubscriber(...)) is the safety-net cleanup for handler-exit paths that don't go through the abort listener.
• loadModel (kind "loadModel") — handler wraps the download-then-load flow in registry.begin(...), threads ctx.signal into the resolver chain, and gates the addon-level plugin.createModel(...) / model.load(false) call on ctx.signal.aborted before and after. The load phase is soft-cancel only — the addon's load path doesn't accept a signal today; documented as a follow-up.
• Design decision: loadModel opens its registry context with modelId: undefined. LoadModelRequest for a fresh load doesn't carry a modelId until the config-hash is computed inside the handler, so the registry slot is keyed by requestId alone. Implication: cancel({ modelId, kind: "loadModel" }) is a no-op for in-progress loads — cancel by requestId (via op.requestId on the decorated promise) is the only path. This is captured in the inline comment on the handler and the "what's on the registry today" dispatch-level table in request-lifecycle-primitives.mdc; flagging here so reviewers don't have to re-derive it.
• Decorated-promise requestId — new helper packages/sdk/utils/decorate-promise.ts (Object.assign-based, intentionally not a prototype extension). loadModel(...) and downloadAsset(...) return Promise<string> & { requestId: string } so callers can grab op.requestId synchronously and fire cancel({ requestId: op.requestId }) before the network round-trip resolves. The unwrap chain is preserved: await loadModel(...) still returns the model id (backward-compat).
• Cursor rules updated — request-lifecycle-primitives.mdc flips the migration table to mark M3b/M3c shipped, documents the decorated-promise pattern, and adds the "what's on the registry today" dispatch-level truth table. docs/request-lifecycle-system.mdc flips the M3c roadmap row.

§4 Open decisions (resolved)

• Decision A — cancel error class: A.1, reuse InferenceCancelledError (52419) across non-inference handlers. Zero new public-API surface. The naming oddity is filed as a potential rename follow-up.
• Decision B — RAG workspace-level admission: B.2, dispatcher-level pre-emption in rag.ts. Before registry.begin({ kind: "rag" }), the dispatcher walks the workspace→requestId map and calls registry.cancel({ requestId: prev }) for any prior in-flight op on the same workspace. No new field on ConcurrencyPolicy. The cancel-prior → begin-new order is load-bearing.
• resolveModelPath signal threading: signal: AbortSignal parameter, not a full ctx: RequestContext. The resolver doesn't need the context — just the signal — so the narrower parameter is the idiomatic shape across all call sites.

cancelHandler.ts's case "downloadAsset" and case "rag" arms stay intact (M1 compat contract). They now emit a deprecation log line and route through registry.cancel(...) rather than the legacy direct paths. M3d retires the dispatcher entirely.

🧪 How was it tested?

• bun lint — clean
• bun run typecheck — clean
• bun test test/unit/ — all new tests green; pre-existing unrelated tts-multicast.test.ts failure on this worktree is a Cannot find package '#rpc' from missing dist/, present on a clean checkout of the base branch too (not introduced here)

New tests:

• test/unit/utils/decorate-promise.test.ts — sync metadata access, unwrap-to-T (the backward-compat pin: await loadModel(...) → string), rejection propagation, in-place identity, .then / .catch / .finally chain integrity, multi-field decoration.
• test/unit/download-manager-subscriber.test.ts — dedup preserved (two callers share one transfer), per-subscriber cancel doesn't affect siblings, last-subscriber leaving aborts the transfer, scope.defer safety net for handler-exit paths, cancel error carries requestId.
• test/unit/rag-workspace-preempt.test.ts — workspace map get/set/clear semantics + the "still mine?" guard against stale scope-unwind clears stomping a newer op's mapping.
• test/unit/request-id-wire.test.ts — loadModel / downloadAsset / rag request schemas preserve requestId on the wire and treat it as optional for legacy clients (server falls back to a server-generated id).

Known follow-up

• The loadModel load phase is soft-cancel: a cancel that arrives during plugin.createModel(...) / model.load(false) lands on the registry but the addon runs to completion. The handler still rejects the client's promise with InferenceCancelledError, but the model is now registered as loaded (orphan-model trade-off). A per-load cancel surface on the addon would close this; tracked as a separate follow-up.

🔌 API Changes

Decorated-promise return shape for loadModel / downloadAsset

Before:

const modelId: string = await sdk.loadModel({ modelSrc: "..." });
// No way to cancel this specific call without grabbing the modelId
// out-of-band and calling cancel({ operation: "inference", modelId })
// (which is broad-cancel — kills every in-flight request on that model).

After:

const op = sdk.loadModel({ modelSrc: "..." });
op.requestId;                              // ← synchronously available, before await
const modelId: string = await op;          // ← legacy unwrap still works

// Stop button → exactly this load, nothing else on the model:
stopButton.onclick = () => sdk.cancel({ requestId: op.requestId });

Same shape for downloadAsset:

const op = sdk.downloadAsset({ assetSrc: "https://example.com/big.gguf" });
setTimeout(() => sdk.cancel({ requestId: op.requestId }), 1000);
await op; // rejects with InferenceCancelledError if cancelled

The return type is Promise<string> & { requestId: string }. Existing call sites that use const id = await sdk.loadModel(...) keep working without modification — the decoration adds a property without touching the prototype chain.

Per-requestId cancel for rag

The rag handler now emits a requestId in the registry for every workspace-bound op (ingest / saveEmbeddings / reindex). Clients targeting a specific RAG op via the wire envelope can cancel it directly:

const requestId = crypto.randomUUID();
const result = sdk.rag({
  type: "rag",
  operation: "ingest",
  workspace: "ws-a",
  modelId: "m1",
  documents: [...],
  requestId, // optional on the wire; legacy clients omit it and the server generates one
});

await sdk.cancel({ requestId });

The legacy sdk.cancel({ operation: "rag", workspace }) arm still works (now routed through the registry with a deprecation log line; removed in M3d).

[github-actions]

QVAC E2E — windows — ✅ all tests passed (91/91, 428s)

Config: suite=smoke · filter=(none) · exclude=(none)
View run · Artifacts: reports

[github-actions]

QVAC E2E — linux — ❌ failed

Totals: 90/91 passed · 1 failed · 98.9% · 377s
Config: suite=smoke · filter=(none) · exclude=(none)
View run · Artifacts: reports

Results by section

• addon-logging: 1/2 ❌

Failed tests

• addon-logging-during-inference: Logging test error (addon-logging-during-inference): Request "6f5330eb-65b4-4925-99a7-1f10f04b01d0" (kind: completion, modelId: 4b7b9d71f364940c) was rejected by registry concurrency policy: another …

[github-actions]

QVAC E2E — android — ❌ failed

Totals: 82/91 passed · 1 failed · 98.8% · 2031s
Config: suite=smoke · filter=(none) · exclude=(none)
View run · Artifacts: reports · Device Farm logs

Results by section

• addon-logging: 1/2 ❌

Failed tests

• addon-logging-during-inference: Logging test error (addon-logging-during-inference): Request "d569e05f2386e82425bbc499e8ebacdb" (kind: completion, modelId: 4b7b9d71f364940c) was rejected by registry concurrency policy: another comp…

[github-actions]

QVAC E2E — macos — ✅ all tests passed (91/91, 335s)

Config: suite=smoke · filter=(none) · exclude=(none)
View run · Artifacts: reports

[simon-iribarren]

/review

[github-actions]

Tier-based Approval Status

**PR Tier:** TIER1

**Current Status:** ✅ APPROVED

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



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