QVAC-18183 feat[api]: cancel capability + per-handler cancel scope + structured logging

Lands the three M3a framework primitives so subsequent handler migration
sub-PRs (M3b/M3c) have a single, declarative contract to slot into:

1. `PluginHandlerDefinition.cancel: { scope: "request" | "model" | "none"; hard?: boolean }`
   - Added to `schemas/plugin.ts` (`PluginHandlerCancel`, `PluginHandlerCancelScope`)
     + runtime schema validation on `pluginHandlerDefinitionRuntimeSchema`.
   - Declared on every built-in plugin manifest (llamacpp-completion,
     llamacpp-embedding, whispercpp/parakeet-transcription, nmtcpp-translation,
     onnx-tts/ocr, sdcpp-generation). The truth-table assignment is pinned by
     `test/unit/plugin-cancel-capability.test.ts`.

2. `RequestRegistry.policy({ kind, oneAtATimePerModel })`:
   - Admission control runs before scope/controller allocation in `begin(...)`.
     Rejecting a request raises `RequestRejectedByPolicyError` (52420) carrying
     `requestId`, `kind`, `modelId`, `reason` — re-exported from `@qvac/sdk` for
     `instanceof` checks.
   - The worker singleton installs `{ kind: "completion", oneAtATimePerModel: true }`
     on first access, matching the llama.cpp addon's single-decode-loop reality.

3. Structured `[request-lifecycle]` emits at begin/cancel/end:
   - Fixed log shape `requestId=<id> kind=<kind> modelId=<id|"-"> state=<state>` so
     `grep "requestId=abc"` returns the full per-request story chronologically.
   - `withRequestContext(logger, ctx)` extends the same prefix to handler-level
     emits; threaded through `completion(...)` and into `KvCacheSession` so
     KV-cache turn lifecycle shares the request's correlation tuple.
   - Single-cancel-emit guard suppresses duplicate cancel lines when
     `cancel({ requestId })` is invoked twice.

Verification (from `packages/sdk/`):
- `bun run lint` (eslint + tsc): clean.
- `bun run test:unit`: 49 files / all asserts pass, including the 4 M3a test
  files (`plugin-cancel-capability` 7/7, `request-registry` 41/41,
  `request-lifecycle-logging` 6/6, `with-request-context` 5/5).

Cursor rules updated alongside the code:
- `request-lifecycle-primitives.mdc`: cancel-capability declaration table,
  concurrency-policy contract, structured-logging shape, error-codes table now
  carries 52420.
- `docs/request-lifecycle-system.mdc`: migration-roadmap table reflects M3a
  shipped; three new FAQ entries explain *why* each primitive was chosen;
  implementation files table covers the new modules.
- `error-handling.mdc`: 52420 row added.

This PR is framework-only — no handler is migrated onto `registry.begin(...)` here
beyond the completion handler that landed in M2. Handler migrations follow in
M3b (inference handlers), M3c (non-inference / addon handlers), and M3d (CLI
cancel bridge + cancelHandler retirement).

Author: simon-iribarren

.cursor/rules/sdk/docs/request-lifecycle-system.mdc

@@ -180,6 +180,7 @@ Located in `@/utils/errors-server`
 - `RequestIdConflictError` (52417) - `registry.begin(...)` called with a `requestId` already present
 - `RequestNotFoundError` (52418) - registry lookup miss (no in-flight request for the given id)
 - `InferenceCancelledError` (52419) - cancelled inference run; carries `requestId` + `partial: { text?, toolCalls?, stats? }`. Constructed client-side on `stopReason: "cancelled"` (event stream ends normally; promise-aggregates reject with this). Re-exported from `@qvac/sdk` for `instanceof` checks.
+- `RequestRejectedByPolicyError` (52420) - registry concurrency-policy admission failure (e.g. `oneAtATimePerModel`); carries `requestId`, `kind`, `modelId`, and a `reason` string. Re-exported from `@qvac/sdk` for `instanceof` checks. See `.cursor/rules/sdk/request-lifecycle-primitives.mdc` for the policy contract.
 
 #### RAG Operations (52,800-52,999)
 - `RAGSaveFailedError` - Save failed

.cursor/rules/sdk/error-handling.mdc

@@ -153,9 +153,14 @@ export { SUPPORTED_AUDIO_FORMATS } from "./constants/audio";
 // promises. `InferenceCancelledError` rides the standard `QvacError`
 // envelope, but consumers reach for it through `instanceof` on
 // `await run.final` / `run.text` / `run.toolCalls` / `run.stats`
-// rejections.
+// 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".
 export { InferenceCancelledError } from "./utils/errors-server";
 export type { InferenceCancelledPartial } from "./utils/errors-server";
+export { RequestRejectedByPolicyError } from "./utils/errors-server";
 
 // Logging exports
 export { getLogger, SDK_LOG_ID } from "./logging";

.cursor/rules/sdk/request-lifecycle-primitives.mdc

@@ -1,6 +1,24 @@
 import { z } from "zod";
 import type { ModelSrcInput } from "./model-src-utils";
 
+/**
+ * Granularity at which the addon can cancel.
+ *  - `"request"` — addon cancels a specific in-flight `requestId`.
+ *  - `"model"` — addon cancels whatever is running on the model.
+ *  - `"none"` — no addon cancel surface; SDK falls back to soft-cancel
+ *    (stop yielding, drop result; the C++ work runs to completion).
+ */
+export type PluginHandlerCancelScope = "request" | "model" | "none";
+
+export interface PluginHandlerCancel {
+  scope: PluginHandlerCancelScope;
+  /**
+   * `true` — `addon.cancel()` interrupts compute; otherwise it's
+   * best-effort. Only meaningful for `scope: "model" | "request"`.
+   */
+  hard?: boolean;
+}
+
 /**
  * Definition for a plugin handler with explicit Zod schemas.
  * Each handler must define its request/response schemas for validation.
@@ -21,6 +39,11 @@ export interface PluginHandlerDefinition<
         ) => Promise<O> | AsyncGenerator<O>
       : never
     : never;
+  /**
+   * Cancel surface this handler advertises. Omitting is equivalent
+   * to `{ scope: "none" }` (soft-cancel fallback).
+   */
+  cancel?: PluginHandlerCancel;
 }
 
 /**
@@ -43,6 +66,8 @@ export interface DuplexPluginHandlerDefinition<
         ) => AsyncGenerator<O>
       : never
     : never;
+  /** See `PluginHandlerDefinition.cancel`. */
+  cancel?: PluginHandlerCancel;
 }
 
 /**
@@ -254,13 +279,23 @@ const zodSchemaLikeRuntimeSchema = z
   })
   .catchall(z.unknown());
 
+const pluginHandlerCancelRuntimeSchema = z
+  .object({
+    scope: z.enum(["request", "model", "none"], {
+      error: "cancel.scope must be 'request', 'model', or 'none'",
+    }),
+    hard: z.boolean().optional(),
+  })
+  .catchall(z.unknown());
+
 export const pluginHandlerDefinitionRuntimeSchema = z
   .object({
     requestSchema: zodSchemaLikeRuntimeSchema,
     responseSchema: zodSchemaLikeRuntimeSchema,
     streaming: z.boolean({ error: "streaming must be a boolean" }),
     duplex: z.boolean().optional(),
     handler: functionRuntimeSchema,
+    cancel: pluginHandlerCancelRuntimeSchema.optional(),
   })
   .catchall(z.unknown());
 

packages/sdk/index.ts

@@ -41,6 +41,7 @@ export const SDK_SERVER_ERROR_CODES = {
   REQUEST_ID_CONFLICT: 52417,
   REQUEST_NOT_FOUND: 52418,
   INFERENCE_CANCELLED: 52419,
+  REQUEST_REJECTED_BY_POLICY: 52420,
 
   // RAG Operations (52,800-52,999)
   RAG_SAVE_FAILED: 52800,
@@ -309,6 +310,16 @@ const serverErrorDefinitions: ErrorCodesMap = {
     message: (requestId: string) =>
       `Inference request "${requestId}" was cancelled before it could complete`,
   },
+  [SDK_SERVER_ERROR_CODES.REQUEST_REJECTED_BY_POLICY]: {
+    name: "REQUEST_REJECTED_BY_POLICY",
+    message: (
+      requestId: string,
+      kind: string,
+      modelId: string,
+      reason: string,
+    ) =>
+      `Request "${requestId}" (kind: ${kind}, modelId: ${modelId}) was rejected by registry concurrency policy: ${reason}`,
+  },
 
   // RAG Operations (52,800-52,999)
   [SDK_SERVER_ERROR_CODES.RAG_SAVE_FAILED]: {

packages/sdk/schemas/plugin.ts

@@ -42,6 +42,7 @@ import { parseToolCalls } from "@/server/utils/tools";
 import { getResponseFormatJsonSchema } from "@/server/utils/response-format";
 import { buildAutoCacheSaveHistory, type CacheMessage } from "@/server/utils";
 import { getServerLogger } from "@/logging";
+import type { Logger } from "@/logging/types";
 import { AttachmentNotFoundError } from "@/utils/errors-server";
 import { nowMs } from "@/profiling";
 import {
@@ -415,11 +416,21 @@ export async function* completion(
     toolDialect?: ToolDialect;
     responseFormat?: ResponseFormat;
   },
-  opts: { signal: AbortSignal; scope: DisposableScope },
+  opts: {
+    signal: AbortSignal;
+    scope: DisposableScope;
+    /**
+     * Request-scoped logger forwarded to `createKvCacheSession` so
+     * kv-cache lines share the request's lifecycle prefix. Falls
+     * back to the module-level server logger when omitted.
+     */
+    logger?: Logger;
+  },
 ): AsyncGenerator<{ token: string }, CompletionResult, unknown> {
   const { history, modelId, kvCache, tools, generationParams, responseFormat } =
     params;
   const { signal, scope } = opts;
+  const requestLogger = opts.logger ?? logger;
 
   const modelConfig = getModelConfig(modelId);
   const toolsEnabled = (modelConfig as { tools?: boolean }).tools === true;
@@ -470,7 +481,7 @@ export async function* completion(
     const addon = model.addon;
     if (addon?.cancel) {
       addon.cancel.call(addon).catch((err: unknown) => {
-        logger.warn(
+        requestLogger.warn(
           `[cancel] addon.cancel() rejected during abort for modelId=${modelId}: ${err instanceof Error ? err.message : String(err)}`,
         );
       });
@@ -523,7 +534,7 @@ export async function* completion(
   // rollback. Cancellations / zero-token replies / rename failures all
   // unwind through the same `scope.defer` hook. ----
 
-  const session = createKvCacheSession(modelId);
+  const session = createKvCacheSession(modelId, { logger: requestLogger });
   const systemPromptFromHistory = extractSystemPrompt(history);
   // Dynamic mode lets each turn carry its own tool set, so the cache
   // hash must not depend on the tool list — otherwise a tool change

packages/sdk/schemas/sdk-errors-server.ts

@@ -14,8 +14,12 @@ import {
   logCacheStatus,
 } from "@/server/bare/plugins/llamacpp-completion/ops/cache-logger";
 import { getServerLogger } from "@/logging";
+import type { Logger } from "@/logging/types";
 
-const logger = getServerLogger();
+// Used by cross-model paths that have no `RequestContext` (e.g.
+// `deleteKvCacheState`). Per-session call sites receive a logger from
+// the caller — typically `withRequestContext(...)`.
+const moduleLogger = getServerLogger();
 
 /**
  * Single owner of the three KV-cache bookkeeping layers.
@@ -204,7 +208,17 @@ interface InternalTurnState {
 
 // ----- factory -----
 
-export function createKvCacheSession(modelId: string): KvCacheSession {
+/**
+ * Construct a session bound to one `(modelId, turn-owning request)`
+ * scope. `options.logger` is the per-instance logger the session emits
+ * through (typically `withRequestContext(getServerLogger(), ctx)`);
+ * falls back to the module-scoped logger when omitted.
+ */
+export function createKvCacheSession(
+  modelId: string,
+  options?: { logger?: Logger },
+): KvCacheSession {
+  const logger = options?.logger ?? moduleLogger;
   // Per-session map: each `TurnHandle` carries an opaque entry here. A
   // WeakMap so handles drop their state once the handler scope releases
   // the reference; the module-scoped maps above survive.
@@ -254,7 +268,7 @@ export function createKvCacheSession(modelId: string): KvCacheSession {
 
     if (!exists) {
       await input.primeIfMissing(cachePath);
-      await verifyPrimedFile(cachePath);
+      await verifyPrimedFile(cachePath, logger);
       initializedCaches.add(registryKey);
     }
 
@@ -297,7 +311,7 @@ export function createKvCacheSession(modelId: string): KvCacheSession {
 
     if (!cacheExists) {
       await input.primeIfMissing(cachePath);
-      await verifyPrimedFile(cachePath);
+      await verifyPrimedFile(cachePath, logger);
       initializedCaches.add(registryKey);
     }
 
@@ -453,9 +467,9 @@ export async function deleteKvCacheState(
     const removed = await deleteCacheUtil({ all: true });
     cachedMessageCounts.clear();
     initializedCaches.clear();
-    // `removed` is the kv-cache root dir; logging surfaces it for
-    // ops visibility but isn't part of the contract.
-    logger.debug(`[kv-cache] Cleared all caches under ${removed}`);
+    // `removed` is the kv-cache root dir; surfaces it for ops
+    // visibility but isn't part of the contract.
+    moduleLogger.debug(`[kv-cache] Cleared all caches under ${removed}`);
     return;
   }
 
@@ -512,7 +526,10 @@ export async function deleteKvCacheState(
  * `completion-stream.ts` lets the error propagate up and no
  * `initializedCaches` entry is recorded.
  */
-async function verifyPrimedFile(cachePath: string): Promise<void> {
+async function verifyPrimedFile(
+  cachePath: string,
+  logger: Logger,
+): Promise<void> {
   let stats: { size: number };
   try {
     stats = await fsPromises.stat(cachePath);

packages/sdk/server/bare/plugins/llamacpp-completion/ops/completion-stream.ts

@@ -30,8 +30,12 @@ import { attachModelExecutionMs } from "@/profiling/model-execution";
 import { getModelConfig } from "@/server/bare/registry/model-registry";
 import { createCompletionNormalizer } from "@/server/utils/completion-normalizer";
 import { detectToolDialect } from "@/server/utils/tool-integration";
-import { getRequestRegistry } from "@/server/bare/runtime";
+import {
+  getRequestRegistry,
+  withRequestContext,
+} from "@/server/bare/runtime";
 import { generateServerRequestId } from "@/server/bare/runtime/request-id";
+import { getServerLogger } from "@/logging";
 
 
 function createLlmModel(
@@ -96,6 +100,7 @@ export const llmPlugin = definePlugin({
       requestSchema: completionStreamRequestSchema,
       responseSchema: completionStreamResponseSchema,
       streaming: true,
+      cancel: { scope: "model", hard: true },
 
       handler: async function* (request) {
         const filteredHistory = request.history.map(
@@ -141,6 +146,8 @@ export const llmPlugin = definePlugin({
           modelId: request.modelId,
         });
 
+        const requestLogger = withRequestContext(getServerLogger(), ctx);
+
         const stream = completion(
           {
             history: filteredHistory,
@@ -151,7 +158,7 @@ export const llmPlugin = definePlugin({
             ...(toolsActive && { toolDialect: dialect }),
             ...(request.responseFormat && { responseFormat: request.responseFormat }),
           },
-          { signal: ctx.signal, scope: ctx.scope },
+          { signal: ctx.signal, scope: ctx.scope, logger: requestLogger },
         );
 
         try {
@@ -210,6 +217,7 @@ export const llmPlugin = definePlugin({
       requestSchema: finetuneRequestSchema,
       responseSchema: finetuneResponseSchema,
       streaming: false,
+      cancel: { scope: "none" },
 
       handler: function (request) {
         return finetune(request);
@@ -220,6 +228,7 @@ export const llmPlugin = definePlugin({
       requestSchema: translateRequestSchema,
       responseSchema: translateResponseSchema,
       streaming: true,
+      cancel: { scope: "model", hard: true },
 
       handler: async function* (request) {
         const stream = translate(request);

packages/sdk/server/bare/plugins/llamacpp-completion/ops/kv-cache-session.ts

@@ -110,6 +110,9 @@ export const embeddingsPlugin = definePlugin({
       requestSchema: embedRequestSchema,
       responseSchema: embedResponseSchema,
       streaming: false,
+      // Model-wide hard cancel via `addon.cancel()` on the llama.cpp
+      // embedding addon. Compute is interrupted when fired.
+      cancel: { scope: "model", hard: true },
 
       handler: async function (request) {
         const embedResult = await embed({