@qvac/sdk 0.18.2 → 0.19.0

package/dist/src/utils/errors-server.js

@@ -0,0 +1,621 @@
+import { QvacErrorBase } from '@qvac/error';
+import { SDK_SERVER_ERROR_CODES } from '../schemas/sdk-errors-server.js';
+import { createErrorOptions } from './errors-base.js';
+// ============== Model Registry Errors ==============
+export class ModelAlreadyRegisteredError extends QvacErrorBase {
+    constructor(modelId, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.MODEL_ALREADY_REGISTERED, [modelId], cause));
+    }
+}
+export class ModelNotFoundError extends QvacErrorBase {
+    constructor(modelId, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.MODEL_NOT_FOUND, [modelId], cause));
+    }
+}
+export class ModelNotLoadedError extends QvacErrorBase {
+    constructor(modelId, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.MODEL_NOT_LOADED, [modelId], cause));
+    }
+}
+// ============== Model Loading Errors ==============
+export class ModelLoadFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.MODEL_LOAD_FAILED, details ? [details] : undefined, cause));
+    }
+}
+export class ModelFileNotFoundError extends QvacErrorBase {
+    constructor(modelPath, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.MODEL_FILE_NOT_FOUND, [modelPath], cause));
+    }
+}
+export class ModelFileNotFoundInDirError extends QvacErrorBase {
+    constructor(modelFile, modelDir, modelType, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.MODEL_FILE_NOT_FOUND_IN_DIR, [modelFile, modelDir, modelType], cause));
+    }
+}
+export class ModelFileLocateFailedError extends QvacErrorBase {
+    constructor(modelType, modelPath, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.MODEL_FILE_LOCATE_FAILED, [modelType, modelPath], cause));
+    }
+}
+export class ProjectionModelRequiredError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PROJECTION_MODEL_REQUIRED, undefined, cause));
+    }
+}
+export class VADModelRequiredError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.VAD_MODEL_REQUIRED, undefined, cause));
+    }
+}
+export class TtsArtifactsRequiredError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.TTS_ARTIFACTS_REQUIRED, undefined, cause));
+    }
+}
+export class TtsReferenceAudioRequiredError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.TTS_REFERENCE_AUDIO_REQUIRED, undefined, cause));
+    }
+}
+export class LegacyParakeetModelDeprecatedError extends QvacErrorBase {
+    constructor(legacyFields, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.LEGACY_PARAKEET_MODEL_DEPRECATED, [legacyFields.join(', ')], cause));
+    }
+}
+export class LegacyTtsModelDeprecatedError extends QvacErrorBase {
+    constructor(legacyFields, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.LEGACY_TTS_MODEL_DEPRECATED, [legacyFields.join(', ')], cause));
+    }
+}
+// ============== Model Unloading Errors ==============
+export class ModelUnloadFailedError extends QvacErrorBase {
+    constructor(modelId, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.MODEL_UNLOAD_FAILED, modelId ? [modelId] : undefined, cause));
+    }
+}
+// ============== Model Operation Errors ==============
+export class EmbedFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.EMBED_FAILED, details ? [details] : undefined, cause));
+    }
+}
+export class EmbedNoEmbeddingsError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.EMBED_NO_EMBEDDINGS, undefined, cause));
+    }
+}
+export class TranscriptionFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.TRANSCRIPTION_FAILED, details ? [details] : undefined, cause));
+    }
+}
+export class AudioFileNotFoundError extends QvacErrorBase {
+    constructor(filePath, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.AUDIO_FILE_NOT_FOUND, [filePath], cause));
+    }
+}
+export class TranslationFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.TRANSLATION_FAILED, details ? [details] : undefined, cause));
+    }
+}
+export class CompletionFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.COMPLETION_FAILED, details ? [details] : undefined, cause));
+    }
+}
+function normalizeContextOverflowArgs(sizesOrPromptTokens, modelIdOrCtxSize, causeOrModelId, cause, extraSizes) {
+    if (typeof sizesOrPromptTokens === 'object' && sizesOrPromptTokens !== null) {
+        return {
+            ...sizesOrPromptTokens,
+            modelId: modelIdOrCtxSize,
+            cause: causeOrModelId
+        };
+    }
+    // Only the two supported extra fields — a spread would let a wider,
+    // structurally assignable extras object override the positional args.
+    return {
+        promptTokens: sizesOrPromptTokens,
+        ctxSize: modelIdOrCtxSize,
+        modelId: causeOrModelId,
+        cause,
+        cachedTokens: extraSizes?.cachedTokens,
+        requiredTokens: extraSizes?.requiredTokens
+    };
+}
+/**
+ * Thrown when a request no longer fits the model's effective context
+ * capacity — distinct from a generic `CompletionFailedError` so consumers
+ * can drive UX (truncate, summarize, or surface a "increase ctx_size /
+ * start a new thread" CTA) instead of treating it as an opaque failure.
+ *
+ * All size fields are optional: they carry whatever the addon guard
+ * reported (a cold prompt, a warm cached-plus-prompt split, or a bare
+ * overflow with no numbers). `modelId` is supplied by the server-side
+ * handler that wraps the addon error.
+ *
+ * Round-trips the RPC boundary via the typed-error reconstructor in
+ * `client/rpc/rpc-error.ts`, so `err instanceof ContextOverflowError`
+ * works on the consumer side.
+ */
+export class ContextOverflowError extends QvacErrorBase {
+    /** The prompt alone, in tokens; unset when the source reported KV cells. */
+    promptTokens;
+    /** Cached conversation on a warm-cache overflow, in `ctxSize` units. */
+    cachedTokens;
+    /** Total the failing guard reported, in `ctxSize` units; can equal the window (`>=` triggers). */
+    requiredTokens;
+    /** Effective per-request ceiling: `ctx_size` split across slots at `parallel > 1`. */
+    ctxSize;
+    modelId;
+    constructor(sizesOrPromptTokens, modelIdOrCtxSize, causeOrModelId, cause, extraSizes) {
+        const n = normalizeContextOverflowArgs(sizesOrPromptTokens, modelIdOrCtxSize, causeOrModelId, cause, extraSizes);
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.CONTEXT_OVERFLOW, [
+            n.promptTokens !== undefined ? String(n.promptTokens) : '',
+            n.ctxSize !== undefined ? String(n.ctxSize) : '',
+            n.modelId ?? '',
+            n.cachedTokens !== undefined ? String(n.cachedTokens) : '',
+            n.requiredTokens !== undefined ? String(n.requiredTokens) : ''
+        ], n.cause));
+        if (n.promptTokens !== undefined)
+            this.promptTokens = n.promptTokens;
+        if (n.ctxSize !== undefined)
+            this.ctxSize = n.ctxSize;
+        if (n.modelId !== undefined)
+            this.modelId = n.modelId;
+        if (n.cachedTokens !== undefined)
+            this.cachedTokens = n.cachedTokens;
+        if (n.requiredTokens !== undefined)
+            this.requiredTokens = n.requiredTokens;
+    }
+    toErrorResponseFields() {
+        return {
+            ...(this.promptTokens !== undefined && { promptTokens: this.promptTokens }),
+            ...(this.cachedTokens !== undefined && { cachedTokens: this.cachedTokens }),
+            ...(this.requiredTokens !== undefined && { requiredTokens: this.requiredTokens }),
+            ...(this.ctxSize !== undefined && { ctxSize: this.ctxSize }),
+            ...(this.modelId !== undefined && { modelId: this.modelId })
+        };
+    }
+}
+export class AttachmentNotFoundError extends QvacErrorBase {
+    constructor(path, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.ATTACHMENT_NOT_FOUND, [path], cause));
+    }
+}
+export class CancelFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.CANCEL_FAILED, details ? [details] : undefined, cause));
+    }
+}
+export class RequestIdConflictError extends QvacErrorBase {
+    requestId;
+    constructor(requestId, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.REQUEST_ID_CONFLICT, [requestId], cause));
+        this.requestId = requestId;
+    }
+    /**
+     * Surface typed fields on the RPC error envelope so the client-side
+     * reconstructor in `client/rpc/rpc-error.ts` can rebuild this exact
+     * class on the consumer side. Without this, `err instanceof
+     * RequestIdConflictError` would always be `false` after the error
+     * crosses the worker boundary.
+     */
+    toErrorResponseFields() {
+        return { requestId: this.requestId };
+    }
+}
+export class RequestNotFoundError extends QvacErrorBase {
+    requestId;
+    constructor(requestId, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.REQUEST_NOT_FOUND, [requestId], cause));
+        this.requestId = requestId;
+    }
+    toErrorResponseFields() {
+        return { requestId: this.requestId };
+    }
+}
+/**
+ * Thrown by `await RequestRegistry.begin(...)` when a registered concurrency
+ * policy refuses the request. Under the default queue policy a same-model
+ * request waits FIFO rather than rejecting, so this fires on the bounded-queue
+ * cases: an explicit `onOverflow: "reject"`, the per-model queue-depth cap, or
+ * a `queueTimeoutMs` elapsing while waiting. Distinct from
+ * `RequestIdConflictError`, which only fires on UUID collisions.
+ */
+export class RequestRejectedByPolicyError extends QvacErrorBase {
+    requestId;
+    kind;
+    modelId;
+    reason;
+    constructor(requestId, kind, modelId, reason, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.REQUEST_REJECTED_BY_POLICY, [requestId, kind, modelId, reason], cause));
+        this.requestId = requestId;
+        this.kind = kind;
+        this.modelId = modelId;
+        this.reason = reason;
+    }
+    toErrorResponseFields() {
+        return {
+            requestId: this.requestId,
+            kind: this.kind,
+            modelId: this.modelId,
+            reason: this.reason
+        };
+    }
+}
+/**
+ * Thrown when a long-running inference request was cancelled before
+ * completion. The `events` stream on `CompletionRun` ends normally with
+ * `stopReason: "cancelled"` on the last `completionDone`, but the
+ * promise-aggregates on the same run (`final` / `text` / `toolCalls` /
+ * `stats`) reject with this error so callers can't accidentally treat a
+ * cancelled run as a successful one.
+ *
+ * Carries:
+ *  - `requestId` — correlates with `run.requestId` so callers know which
+ *    in-flight request was cancelled when they fan out multiple cancels.
+ *  - `partial` — whatever the aggregator accumulated up to the cancel
+ *    point. Optional fields so consumers can opt into "show partial":
+ *
+ *      try { await run.text } catch (err) {
+ *        if (err instanceof InferenceCancelledError) {
+ *          renderPartial(err.partial.text);
+ *        }
+ *      }
+ *
+ * The error is constructed client-side in
+ * `client/api/completion-stream.ts` when the wire stream ends with
+ * `stopReason: "cancelled"` — the partial payload comes from the
+ * client's own event aggregator. The class lives in `errors-server.ts`
+ * (and is re-exported from the package root) because the *semantic*
+ * origin of the cancel is server-side, and other handlers
+ * (embeddings, transcribe, …) will reuse the same class once their
+ * cancel surface lands.
+ */
+export class InferenceCancelledError extends QvacErrorBase {
+    requestId;
+    partial;
+    constructor(requestId, partial = {}, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.INFERENCE_CANCELLED, [requestId], cause));
+        this.requestId = requestId;
+        this.partial = partial;
+    }
+}
+export class AsyncDisposeUnavailableError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.ASYNC_DISPOSE_UNAVAILABLE, [], cause));
+    }
+}
+export class TextToSpeechFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.TEXT_TO_SPEECH_FAILED, details ? [details] : undefined, cause));
+    }
+}
+export class TextToSpeechStreamFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.TEXT_TO_SPEECH_STREAM_FAILED, details ? [details] : undefined, cause));
+    }
+}
+export class ConfigReloadNotSupportedError extends QvacErrorBase {
+    constructor(modelId, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.CONFIG_RELOAD_NOT_SUPPORTED, [modelId], cause));
+    }
+}
+export class ModelTypeMismatchError extends QvacErrorBase {
+    constructor(expectedType, providedType, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.MODEL_TYPE_MISMATCH, [expectedType, providedType], cause));
+    }
+}
+export class ModelOperationNotSupportedError extends QvacErrorBase {
+    modelId;
+    modelType;
+    operation;
+    supportedOperations;
+    suggestedModelTypes;
+    constructor(modelId, modelType, operation, supportedOperations, suggestedModelTypes, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.MODEL_OPERATION_NOT_SUPPORTED, [
+            modelId,
+            modelType,
+            operation,
+            supportedOperations.join(', '),
+            suggestedModelTypes.join(', ')
+        ], cause));
+        this.modelId = modelId;
+        this.modelType = modelType;
+        this.operation = operation;
+        this.supportedOperations = supportedOperations;
+        this.suggestedModelTypes = suggestedModelTypes;
+    }
+}
+export class OCRFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.OCR_FAILED, details ? [details] : undefined, cause));
+    }
+}
+export class ImageFileNotFoundError extends QvacErrorBase {
+    constructor(filePath, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.IMAGE_FILE_NOT_FOUND, [filePath], cause));
+    }
+}
+export class InvalidImageInputError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.INVALID_IMAGE_INPUT, undefined, cause));
+    }
+}
+export class InvalidAudioInputError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.INVALID_AUDIO_INPUT, details ? [details] : undefined, cause));
+    }
+}
+// ============== RAG Operation Errors ==============
+export class RAGSaveFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.RAG_SAVE_FAILED, details ? [details] : undefined, cause));
+    }
+}
+export class RAGSearchFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.RAG_SEARCH_FAILED, details ? [details] : undefined, cause));
+    }
+}
+export class RAGDeleteFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.RAG_DELETE_FAILED, details ? [details] : undefined, cause));
+    }
+}
+export class RAGUnknownOperationError extends QvacErrorBase {
+    constructor(operation, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.RAG_UNKNOWN_OPERATION, [operation], cause));
+    }
+}
+export class RAGHyperDBFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.RAG_HYPERDB_FAILED, [details], cause));
+    }
+}
+// ============== Download/Resource Errors ==============
+export class FileNotFoundError extends QvacErrorBase {
+    constructor(path, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.FILE_NOT_FOUND, [path], cause));
+    }
+}
+export class DownloadCancelledError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.DOWNLOAD_CANCELLED, undefined, cause));
+    }
+}
+export class ChecksumValidationFailedError extends QvacErrorBase {
+    constructor(fileName, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.CHECKSUM_VALIDATION_FAILED, [fileName], cause));
+    }
+}
+export class HTTPError extends QvacErrorBase {
+    /** HTTP status code; `0` denotes a connection/network failure (no response). */
+    httpStatus;
+    constructor(status, statusText, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.HTTP_ERROR, [status, statusText], cause));
+        this.httpStatus = status;
+    }
+}
+export class NoResponseBodyError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.NO_RESPONSE_BODY, undefined, cause));
+    }
+}
+export class ResponseBodyNotReadableError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.RESPONSE_BODY_NOT_READABLE, undefined, cause));
+    }
+}
+export class NoBlobFoundError extends QvacErrorBase {
+    constructor(fileName, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.NO_BLOB_FOUND, [fileName], cause));
+    }
+}
+export class DownloadAssetFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.DOWNLOAD_ASSET_FAILED, details ? [details] : undefined, cause));
+    }
+}
+export class SeedingNotSupportedError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.SEEDING_NOT_SUPPORTED, undefined, cause));
+    }
+}
+export class HyperdriveDownloadFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.HYPERDRIVE_DOWNLOAD_FAILED, [details], cause));
+    }
+}
+export class RegistryDownloadFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.REGISTRY_DOWNLOAD_FAILED, [details], cause));
+    }
+}
+export class InvalidShardUrlPatternError extends QvacErrorBase {
+    constructor(url, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.INVALID_SHARD_URL_PATTERN, [url], cause));
+    }
+}
+export class ArchiveExtractionFailedError extends QvacErrorBase {
+    constructor(archivePath, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.ARCHIVE_EXTRACTION_FAILED, [archivePath], cause));
+    }
+}
+export class ArchiveUnsupportedTypeError extends QvacErrorBase {
+    constructor(archivePath, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.ARCHIVE_UNSUPPORTED_TYPE, [archivePath], cause));
+    }
+}
+export class ArchiveMissingShardsError extends QvacErrorBase {
+    constructor(missingFile, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.ARCHIVE_MISSING_SHARDS, [missingFile], cause));
+    }
+}
+export class PartialDownloadOfflineError extends QvacErrorBase {
+    constructor(url, downloadedBytes, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PARTIAL_DOWNLOAD_OFFLINE, [url, String(downloadedBytes)], cause));
+    }
+}
+// ============== Cache Operation Errors ==============
+export class DeleteCacheFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.DELETE_CACHE_FAILED, details ? [details] : undefined, cause));
+    }
+}
+export class InvalidDeleteCacheParamsError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.INVALID_DELETE_CACHE_PARAMS, undefined, cause));
+    }
+}
+export class CacheDirNotAbsoluteError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.CACHE_DIR_NOT_ABSOLUTE, undefined, cause));
+    }
+}
+export class CacheDirNotWritableError extends QvacErrorBase {
+    constructor(cacheDir, details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.CACHE_DIR_NOT_WRITABLE, details ? [cacheDir, details] : [cacheDir], cause));
+    }
+}
+// ============== Config Operations Errors ==============
+export class ConfigAlreadySetError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.CONFIG_ALREADY_SET, undefined, cause));
+    }
+}
+// ============== System/Runtime Errors ==============
+export class FFmpegNotAvailableError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.FFMPEG_NOT_AVAILABLE, undefined, cause));
+    }
+}
+export class AudioPlayerFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.AUDIO_PLAYER_FAILED, [details], cause));
+    }
+}
+export class InvalidAudioChunkError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.INVALID_AUDIO_CHUNK_TYPE, undefined, cause));
+    }
+}
+// ============== RAG Workspace Errors ==============
+export class RAGWorkspaceModelMismatchError extends QvacErrorBase {
+    constructor(workspace, existingModelId, newModelId, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.RAG_WORKSPACE_MODEL_MISMATCH, [workspace, existingModelId, newModelId], cause));
+    }
+}
+export class RAGWorkspaceNotFoundError extends QvacErrorBase {
+    constructor(workspace, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.RAG_WORKSPACE_NOT_FOUND, [workspace], cause));
+    }
+}
+export class RAGWorkspaceInUseError extends QvacErrorBase {
+    constructor(workspace, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.RAG_WORKSPACE_IN_USE, [workspace], cause));
+    }
+}
+export class RAGWorkspaceNotOpenError extends QvacErrorBase {
+    constructor(workspace, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.RAG_WORKSPACE_NOT_OPEN, [workspace], cause));
+    }
+}
+// ============== RPC Errors (Server-side) ==============
+export class RPCNoDataReceivedError extends QvacErrorBase {
+    constructor(cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.RPC_NO_DATA_RECEIVED, undefined, cause));
+    }
+}
+export class RPCUnknownRequestTypeError extends QvacErrorBase {
+    constructor(requestType, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.RPC_UNKNOWN_REQUEST_TYPE, [requestType], cause));
+    }
+}
+// ============== Plugin Errors ==============
+export class PluginNotFoundError extends QvacErrorBase {
+    constructor(modelType, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PLUGIN_NOT_FOUND, [modelType], cause));
+    }
+}
+export class PluginHandlerNotFoundError extends QvacErrorBase {
+    constructor(modelType, handler, availableHandlers, cause) {
+        const serializedHandlers = availableHandlers?.join(', ') ?? '';
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PLUGIN_HANDLER_NOT_FOUND, [modelType, handler, serializedHandlers], cause));
+    }
+}
+export class PluginRequestValidationFailedError extends QvacErrorBase {
+    constructor(handler, details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PLUGIN_REQUEST_VALIDATION_FAILED, details ? [handler, details] : [handler], cause));
+    }
+}
+export class PluginResponseValidationFailedError extends QvacErrorBase {
+    constructor(handler, details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PLUGIN_RESPONSE_VALIDATION_FAILED, details ? [handler, details] : [handler], cause));
+    }
+}
+export class PluginAlreadyRegisteredError extends QvacErrorBase {
+    constructor(modelType, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PLUGIN_ALREADY_REGISTERED, [modelType], cause));
+    }
+}
+export class PluginModelTypeReservedError extends QvacErrorBase {
+    constructor(modelType, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PLUGIN_MODEL_TYPE_RESERVED, [modelType], cause));
+    }
+}
+export class PluginLoadConfigValidationFailedError extends QvacErrorBase {
+    constructor(modelType, details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PLUGIN_LOAD_CONFIG_VALIDATION_FAILED, [modelType, details], cause));
+    }
+}
+export class PluginHandlerTypeMismatchError extends QvacErrorBase {
+    constructor(handlerName, expected, actual, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PLUGIN_HANDLER_TYPE_MISMATCH, [handlerName, expected, actual], cause));
+    }
+}
+export class PluginLoggingInvalidError extends QvacErrorBase {
+    constructor(modelType, reason, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PLUGIN_LOGGING_INVALID, [modelType, reason], cause));
+    }
+}
+export class PluginDefinitionInvalidError extends QvacErrorBase {
+    constructor(modelType, details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PLUGIN_DEFINITION_INVALID, [modelType, details], cause));
+    }
+}
+// ============== Lifecycle Errors ==============
+export class LifecycleSuspendFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.LIFECYCLE_SUSPEND_FAILED, details ? [details] : undefined, cause));
+    }
+}
+export class LifecycleResumeFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.LIFECYCLE_RESUME_FAILED, details ? [details] : undefined, cause));
+    }
+}
+export class LifecycleOperationBlockedError extends QvacErrorBase {
+    constructor(requestType, lifecycleState) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.LIFECYCLE_OPERATION_BLOCKED, [
+            requestType,
+            lifecycleState
+        ]));
+    }
+}
+// ============== Security Errors ==============
+export class PathTraversalError extends QvacErrorBase {
+    constructor(component, basePath, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.PATH_TRAVERSAL, [component, basePath], cause));
+    }
+}
+// ============== QVAC Model Registry Operation Errors ==============
+// Registry client errors (19,001-20,000) are re-thrown directly from @qvac/registry-client
+// Only SDK-specific errors are defined here
+export class ModelRegistryQueryFailedError extends QvacErrorBase {
+    constructor(details, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.QVAC_MODEL_REGISTRY_QUERY_FAILED, details ? [details] : undefined, cause));
+    }
+}

package/dist/src/utils/load-model-validation.js

@@ -0,0 +1,17 @@
+import { inferModelTypeFromModelSrc, normalizeModelType } from '@qvac/inference/surface';
+import { ModelSrcTypeMismatchError } from './errors-client.js';
+/**
+ * Throws {@link ModelSrcTypeMismatchError} when explicit
+ * `modelType` disagrees with the type inferred from `modelSrc`.
+ * No-op when nothing can be inferred.
+ */
+export function assertModelSrcMatchesModelType(modelSrc, explicitModelType) {
+    const inferred = inferModelTypeFromModelSrc(modelSrc);
+    if (!inferred)
+        return;
+    const normalizedInferred = normalizeModelType(inferred);
+    const normalizedExplicit = normalizeModelType(explicitModelType);
+    if (normalizedInferred !== normalizedExplicit) {
+        throw new ModelSrcTypeMismatchError(normalizedInferred, normalizedExplicit);
+    }
+}

package/dist/src/utils/mcp-adapter.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from '@qvac/inference/surface';
+import type { McpClientInput } from '@qvac/inference/surface';
+import type { ToolHandler } from './tool-helpers.js';
+export type { McpClient, McpClientInput } from '@qvac/inference/surface';
+export type ToolHandlerMap = Map<string, ToolHandler>;
+export type McpToolsResult = {
+    tools: Tool[];
+    handlers: ToolHandlerMap;
+};
+export declare function getMcpToolsWithHandlers(clients: McpClientInput[]): Promise<McpToolsResult>;
+export declare function getMcpTools(clients: McpClientInput[]): Promise<Tool[]>;
+//# sourceMappingURL=mcp-adapter.d.ts.map