@qvac/sdk 0.18.2 → 0.19.0

package/dist/src/schemas/sdk-errors-server.js

@@ -0,0 +1,540 @@
+import { addCodes, isCodeRegistered } from '@qvac/error';
+// Load @qvac/inference's registration first, then add only codes not already present, so a
+// shared @qvac/error instance (packed consumers, the Bare worker) is not double-registered.
+import '@qvac/inference/surface';
+// Server-side error codes (52,001-54,000 range for this SDK)
+export const SDK_SERVER_ERROR_CODES = {
+    // Model Registry Errors (52,001-52,199)
+    MODEL_ALREADY_REGISTERED: 52001,
+    MODEL_NOT_FOUND: 52002,
+    MODEL_NOT_LOADED: 52003,
+    UNKNOWN_MODEL_TYPE: 52005,
+    // Model Loading Errors (52,200-52,399)
+    MODEL_LOAD_FAILED: 52200,
+    MODEL_FILE_NOT_FOUND: 52201,
+    MODEL_FILE_NOT_FOUND_IN_DIR: 52202,
+    MODEL_FILE_LOCATE_FAILED: 52203,
+    PROJECTION_MODEL_REQUIRED: 52204,
+    VAD_MODEL_REQUIRED: 52205,
+    TTS_ARTIFACTS_REQUIRED: 52208,
+    TTS_REFERENCE_AUDIO_REQUIRED: 52209,
+    LEGACY_PARAKEET_MODEL_DEPRECATED: 52210,
+    LEGACY_TTS_MODEL_DEPRECATED: 52211,
+    // Model Operations (52,400-52,799)
+    MODEL_UNLOAD_FAILED: 52400,
+    EMBED_FAILED: 52401,
+    EMBED_NO_EMBEDDINGS: 52402,
+    TRANSCRIPTION_FAILED: 52403,
+    AUDIO_FILE_NOT_FOUND: 52404,
+    TRANSLATION_FAILED: 52405,
+    COMPLETION_FAILED: 52406,
+    ATTACHMENT_NOT_FOUND: 52407,
+    CANCEL_FAILED: 52408,
+    TEXT_TO_SPEECH_FAILED: 52409,
+    CONFIG_RELOAD_NOT_SUPPORTED: 52410,
+    MODEL_TYPE_MISMATCH: 52411,
+    OCR_FAILED: 52412,
+    IMAGE_FILE_NOT_FOUND: 52413,
+    INVALID_IMAGE_INPUT: 52414,
+    TEXT_TO_SPEECH_STREAM_FAILED: 52415,
+    MODEL_OPERATION_NOT_SUPPORTED: 52416,
+    REQUEST_ID_CONFLICT: 52417,
+    REQUEST_NOT_FOUND: 52418,
+    INFERENCE_CANCELLED: 52419,
+    REQUEST_REJECTED_BY_POLICY: 52420,
+    CONTEXT_OVERFLOW: 52421,
+    INVALID_AUDIO_INPUT: 52422,
+    // RAG Operations (52,800-52,999)
+    RAG_SAVE_FAILED: 52800,
+    RAG_SEARCH_FAILED: 52801,
+    RAG_DELETE_FAILED: 52802,
+    RAG_UNKNOWN_OPERATION: 52803,
+    RAG_HYPERDB_FAILED: 52804,
+    RAG_WORKSPACE_MODEL_MISMATCH: 52805,
+    RAG_WORKSPACE_NOT_FOUND: 52806,
+    RAG_WORKSPACE_IN_USE: 52807,
+    RAG_WORKSPACE_CLOSE_FAILED: 52808,
+    RAG_LIST_WORKSPACES_FAILED: 52809,
+    RAG_CHUNK_FAILED: 52810,
+    RAG_WORKSPACE_NOT_OPEN: 52811,
+    // Download/Resource Errors (53,000-53,199)
+    FILE_NOT_FOUND: 53000,
+    DOWNLOAD_CANCELLED: 53001,
+    CHECKSUM_VALIDATION_FAILED: 53002,
+    HTTP_ERROR: 53003,
+    NO_RESPONSE_BODY: 53004,
+    RESPONSE_BODY_NOT_READABLE: 53005,
+    NO_BLOB_FOUND: 53006,
+    DOWNLOAD_ASSET_FAILED: 53007,
+    SEEDING_NOT_SUPPORTED: 53008,
+    HYPERDRIVE_DOWNLOAD_FAILED: 53009,
+    INVALID_SHARD_URL_PATTERN: 53010,
+    ARCHIVE_EXTRACTION_FAILED: 53011,
+    ARCHIVE_UNSUPPORTED_TYPE: 53012,
+    ARCHIVE_MISSING_SHARDS: 53013,
+    PARTIAL_DOWNLOAD_OFFLINE: 53014,
+    REGISTRY_DOWNLOAD_FAILED: 53015,
+    INSECURE_MODEL_SOURCE: 53016,
+    CHECKSUM_UNAVAILABLE: 53017,
+    // Cache Operations (53,200-53,349)
+    DELETE_CACHE_FAILED: 53200,
+    INVALID_DELETE_CACHE_PARAMS: 53201,
+    CACHE_DIR_NOT_ABSOLUTE: 53202,
+    CACHE_DIR_NOT_WRITABLE: 53203,
+    // Config Operations (53,350-53,499)
+    SET_CONFIG_FAILED: 53350,
+    CONFIG_ALREADY_SET: 53351,
+    // System/Runtime (53,500-53,699)
+    FFMPEG_NOT_AVAILABLE: 53500,
+    AUDIO_PLAYER_FAILED: 53501,
+    INVALID_AUDIO_CHUNK_TYPE: 53502,
+    ASYNC_DISPOSE_UNAVAILABLE: 53503,
+    // RPC (Server-side) (53,700-53,849)
+    RPC_NO_DATA_RECEIVED: 53703,
+    RPC_UNKNOWN_REQUEST_TYPE: 53704,
+    // Plugin Errors (53,850-53,899)
+    PLUGIN_NOT_FOUND: 53850,
+    PLUGIN_HANDLER_NOT_FOUND: 53851,
+    PLUGIN_REQUEST_VALIDATION_FAILED: 53852,
+    PLUGIN_RESPONSE_VALIDATION_FAILED: 53853,
+    PLUGIN_ALREADY_REGISTERED: 53854,
+    PLUGIN_HANDLER_TYPE_MISMATCH: 53855,
+    PLUGIN_LOGGING_INVALID: 53856,
+    PLUGIN_DEFINITION_INVALID: 53857,
+    PLUGIN_MODEL_TYPE_RESERVED: 53858,
+    PLUGIN_LOAD_CONFIG_VALIDATION_FAILED: 53859,
+    // Lifecycle (53,600-53,610)
+    LIFECYCLE_SUSPEND_FAILED: 53600,
+    LIFECYCLE_RESUME_FAILED: 53601,
+    LIFECYCLE_OPERATION_BLOCKED: 53602,
+    // Security (53,900-53,949)
+    PATH_TRAVERSAL: 53900,
+    // QVAC Model Registry Operations (53,950-54,000)
+    // Note: Registry client errors (19,001-20,000) are re-thrown directly
+    QVAC_MODEL_REGISTRY_QUERY_FAILED: 53950
+};
+const serverErrorDefinitions = {
+    // Model Registry Errors (52,001-52,199)
+    [SDK_SERVER_ERROR_CODES.MODEL_ALREADY_REGISTERED]: {
+        name: 'MODEL_ALREADY_REGISTERED',
+        message: (modelId) => `Model with ID "${modelId}" is already registered`
+    },
+    [SDK_SERVER_ERROR_CODES.MODEL_NOT_FOUND]: {
+        name: 'MODEL_NOT_FOUND',
+        message: (modelId) => `Model with ID "${modelId}" not found`
+    },
+    [SDK_SERVER_ERROR_CODES.MODEL_NOT_LOADED]: {
+        name: 'MODEL_NOT_LOADED',
+        message: (modelId) => `Model with ID "${modelId}" is not loaded`
+    },
+    [SDK_SERVER_ERROR_CODES.UNKNOWN_MODEL_TYPE]: {
+        name: 'UNKNOWN_MODEL_TYPE',
+        message: (modelType) => `Unknown model type: ${modelType}. If using a custom worker bundle, ensure the plugin for "${modelType}" is included in your qvac.config plugins array and rebuild with "npx qvac bundle sdk".`
+    },
+    // Model Loading Errors (52,200-52,399)
+    [SDK_SERVER_ERROR_CODES.MODEL_LOAD_FAILED]: {
+        name: 'MODEL_LOAD_FAILED',
+        message: (details) => `Failed to load model${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.MODEL_FILE_NOT_FOUND]: {
+        name: 'MODEL_FILE_NOT_FOUND',
+        message: (modelPath) => `Model file not found: ${modelPath}`
+    },
+    [SDK_SERVER_ERROR_CODES.MODEL_FILE_NOT_FOUND_IN_DIR]: {
+        name: 'MODEL_FILE_NOT_FOUND_IN_DIR',
+        message: (modelFile, modelDir, modelType) => `${modelType} model file ${modelFile} not found in directory ${modelDir}`
+    },
+    [SDK_SERVER_ERROR_CODES.MODEL_FILE_LOCATE_FAILED]: {
+        name: 'MODEL_FILE_LOCATE_FAILED',
+        message: (modelType, modelPath) => `Failed to locate ${modelType} model file: ${modelPath}`
+    },
+    [SDK_SERVER_ERROR_CODES.PROJECTION_MODEL_REQUIRED]: {
+        name: 'PROJECTION_MODEL_REQUIRED',
+        message: 'Projection model source is required for multimodal LLM models'
+    },
+    [SDK_SERVER_ERROR_CODES.VAD_MODEL_REQUIRED]: {
+        name: 'VAD_MODEL_REQUIRED',
+        message: 'VAD model source is required for this configuration'
+    },
+    [SDK_SERVER_ERROR_CODES.TTS_ARTIFACTS_REQUIRED]: {
+        name: 'TTS_ARTIFACTS_REQUIRED',
+        message: 'TTS (Chatterbox) requires s3genModelSrc in modelConfig (companion S3Gen GGUF) and the primary T3 GGUF via modelSrc'
+    },
+    [SDK_SERVER_ERROR_CODES.TTS_REFERENCE_AUDIO_REQUIRED]: {
+        name: 'TTS_REFERENCE_AUDIO_REQUIRED',
+        message: 'TTS (Chatterbox) requires referenceAudioSrc (path or URL to a WAV file for voice cloning)'
+    },
+    [SDK_SERVER_ERROR_CODES.LEGACY_PARAKEET_MODEL_DEPRECATED]: {
+        name: 'LEGACY_PARAKEET_MODEL_DEPRECATED',
+        message: (legacyFields) => `Legacy parakeet ONNX modelConfig fields are no longer supported (${legacyFields ?? 'unknown fields'}). As of @qvac/transcription-parakeet 0.6.0 the addon ships as a single GGUF that auto-detects TDT / CTC / EOU / Sortformer from GGUF metadata. Supply the GGUF via the top-level modelSrc (e.g. loadModel({ modelSrc: PARAKEET_TDT_0_6B_V3_Q8_0, modelType: "parakeet" })).`
+    },
+    [SDK_SERVER_ERROR_CODES.LEGACY_TTS_MODEL_DEPRECATED]: {
+        name: 'LEGACY_TTS_MODEL_DEPRECATED',
+        message: (legacyFields) => `Legacy ONNX TTS modelConfig fields are no longer supported (${legacyFields ?? 'unknown fields'}). As of @qvac/tts-ggml the addon uses GGUF bundles: supply the primary GGUF via modelSrc, set language in modelConfig, and for Chatterbox add s3genModelSrc (e.g. loadModel({ modelSrc: TTS_T3_TURBO_EN_CHATTERBOX_Q8_0, modelType: "tts", modelConfig: { ttsEngine: "chatterbox", language: "en", s3genModelSrc: TTS_S3GEN_EN_CHATTERBOX } })). Supertonic multilingual mode is selected by the GGUF (e.g. TTS_MULTILINGUAL_SUPERTONIC2_Q8_0) plus language — not ttsSupertonicMultilingual.`
+    },
+    // Model Operations (52,400-52,799)
+    [SDK_SERVER_ERROR_CODES.MODEL_UNLOAD_FAILED]: {
+        name: 'MODEL_UNLOAD_FAILED',
+        message: (modelId) => `Failed to unload model${modelId ? ` "${modelId}"` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.EMBED_FAILED]: {
+        name: 'EMBED_FAILED',
+        message: (details) => `Failed to generate embeddings${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.EMBED_NO_EMBEDDINGS]: {
+        name: 'EMBED_NO_EMBEDDINGS',
+        message: 'No embeddings returned from model'
+    },
+    [SDK_SERVER_ERROR_CODES.TRANSCRIPTION_FAILED]: {
+        name: 'TRANSCRIPTION_FAILED',
+        message: (details) => `Transcription failed${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.AUDIO_FILE_NOT_FOUND]: {
+        name: 'AUDIO_FILE_NOT_FOUND',
+        message: (filePath) => `Audio file not found or not accessible: ${filePath}`
+    },
+    [SDK_SERVER_ERROR_CODES.TRANSLATION_FAILED]: {
+        name: 'TRANSLATION_FAILED',
+        message: (details) => `Translation failed${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.COMPLETION_FAILED]: {
+        name: 'COMPLETION_FAILED',
+        message: (details) => `Completion failed${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.ATTACHMENT_NOT_FOUND]: {
+        name: 'ATTACHMENT_NOT_FOUND',
+        message: (path) => `Attachment not found at path: ${path}`
+    },
+    [SDK_SERVER_ERROR_CODES.CANCEL_FAILED]: {
+        name: 'CANCEL_FAILED',
+        message: (details) => `Failed to cancel operation${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.TEXT_TO_SPEECH_FAILED]: {
+        name: 'TEXT_TO_SPEECH_FAILED',
+        message: (details) => `Text-to-speech operation failed${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.TEXT_TO_SPEECH_STREAM_FAILED]: {
+        name: 'TEXT_TO_SPEECH_STREAM_FAILED',
+        message: (details) => `Text-to-speech stream operation failed${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.CONFIG_RELOAD_NOT_SUPPORTED]: {
+        name: 'CONFIG_RELOAD_NOT_SUPPORTED',
+        message: (modelId) => `Model "${modelId}" does not support hot config reload`
+    },
+    [SDK_SERVER_ERROR_CODES.MODEL_TYPE_MISMATCH]: {
+        name: 'MODEL_TYPE_MISMATCH',
+        message: (expectedType, providedType) => `Model type mismatch: expected "${expectedType}", got "${providedType}"`
+    },
+    [SDK_SERVER_ERROR_CODES.OCR_FAILED]: {
+        name: 'OCR_FAILED',
+        message: (details) => `OCR operation failed${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.IMAGE_FILE_NOT_FOUND]: {
+        name: 'IMAGE_FILE_NOT_FOUND',
+        message: (filePath) => `Image file not found or not accessible: ${filePath}`
+    },
+    [SDK_SERVER_ERROR_CODES.INVALID_IMAGE_INPUT]: {
+        name: 'INVALID_IMAGE_INPUT',
+        message: 'Invalid image input type provided'
+    },
+    [SDK_SERVER_ERROR_CODES.MODEL_OPERATION_NOT_SUPPORTED]: {
+        name: 'MODEL_OPERATION_NOT_SUPPORTED',
+        message: (modelId, modelType, operation, supportedOperations, suggestedModelTypes) => {
+            const supportedClause = supportedOperations
+                ? ` Supported operations on this model: ${supportedOperations}.`
+                : ' This model does not expose any operations.';
+            const suggestionClause = suggestedModelTypes
+                ? ` To use ${operation}, load a model of type: ${suggestedModelTypes}.`
+                : ` No model registered in this worker bundle exposes ${operation}.`;
+            return `Model "${modelId}" (type: ${modelType}) does not support ${operation}.${supportedClause}${suggestionClause}`;
+        }
+    },
+    [SDK_SERVER_ERROR_CODES.REQUEST_ID_CONFLICT]: {
+        name: 'REQUEST_ID_CONFLICT',
+        message: (requestId) => `Request id "${requestId}" is already in flight; refusing to overwrite the existing context`
+    },
+    [SDK_SERVER_ERROR_CODES.REQUEST_NOT_FOUND]: {
+        name: 'REQUEST_NOT_FOUND',
+        message: (requestId) => `No in-flight request with id "${requestId}"`
+    },
+    [SDK_SERVER_ERROR_CODES.INFERENCE_CANCELLED]: {
+        name: 'INFERENCE_CANCELLED',
+        message: (requestId) => `Inference request "${requestId}" was cancelled before it could complete`
+    },
+    [SDK_SERVER_ERROR_CODES.REQUEST_REJECTED_BY_POLICY]: {
+        name: 'REQUEST_REJECTED_BY_POLICY',
+        message: (requestId, kind, modelId, reason) => `Request "${requestId}" (kind: ${kind}, modelId: ${modelId}) was rejected by registry concurrency policy: ${reason}`
+    },
+    [SDK_SERVER_ERROR_CODES.CONTEXT_OVERFLOW]: {
+        name: 'CONTEXT_OVERFLOW',
+        message: (promptTokens, ctxSize, modelId, cachedTokens, requiredTokens) => {
+            const model = modelId ? ` for model "${modelId}"` : '';
+            // Ambiguous totals can be KV cells, and the guards trigger at equality —
+            // unit-neutral wording, phrased as leaving no room rather than exceeding.
+            const capacity = ctxSize
+                ? `the effective context capacity (${ctxSize} units)`
+                : "the model's context capacity";
+            if (requiredTokens && cachedTokens) {
+                return `Conversation uses ${requiredTokens} context units (${cachedTokens} already cached) and leaves no room to generate within ${capacity}${model}. Start a new conversation or raise ctx_size.`;
+            }
+            if (requiredTokens) {
+                return `Request uses ${requiredTokens} context units and leaves no room to generate within ${capacity}${model}. Reduce the prompt size, start a new conversation, or raise ctx_size.`;
+            }
+            const window = ctxSize ? `the ${ctxSize}-token context window` : "the model's context window";
+            // The prompt-only branch below is reachable only through the public
+            // constructors — the parser always pairs promptTokens with requiredTokens.
+            const prompt = promptTokens ? `${promptTokens} prompt tokens` : 'prompt';
+            return `${prompt} exceeds ${window}${model}. Reduce the prompt size or start a new conversation.`;
+        }
+    },
+    [SDK_SERVER_ERROR_CODES.INVALID_AUDIO_INPUT]: {
+        name: 'INVALID_AUDIO_INPUT',
+        message: (details) => `Invalid audio input${details ? `: ${details}` : ''}`
+    },
+    // RAG Operations (52,800-52,999)
+    [SDK_SERVER_ERROR_CODES.RAG_SAVE_FAILED]: {
+        name: 'RAG_SAVE_FAILED',
+        message: (details) => `Failed to save embeddings${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.RAG_SEARCH_FAILED]: {
+        name: 'RAG_SEARCH_FAILED',
+        message: (details) => `Failed to search embeddings${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.RAG_DELETE_FAILED]: {
+        name: 'RAG_DELETE_FAILED',
+        message: (details) => `Failed to delete embeddings${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.RAG_UNKNOWN_OPERATION]: {
+        name: 'RAG_UNKNOWN_OPERATION',
+        message: (operation) => `Unknown RAG operation: ${operation}`
+    },
+    [SDK_SERVER_ERROR_CODES.RAG_HYPERDB_FAILED]: {
+        name: 'RAG_HYPERDB_FAILED',
+        message: (details) => `HyperDB RAG operation failed: ${details}`
+    },
+    [SDK_SERVER_ERROR_CODES.RAG_WORKSPACE_MODEL_MISMATCH]: {
+        name: 'RAG_WORKSPACE_MODEL_MISMATCH',
+        message: (workspace, existingModelId, newModelId) => `Workspace "${workspace}" is configured for model "${existingModelId}", but you're trying to use model "${newModelId}". Use a different workspace or the same model`
+    },
+    [SDK_SERVER_ERROR_CODES.RAG_WORKSPACE_NOT_FOUND]: {
+        name: 'RAG_WORKSPACE_NOT_FOUND',
+        message: (workspace) => `RAG workspace not found: ${workspace}`
+    },
+    [SDK_SERVER_ERROR_CODES.RAG_WORKSPACE_IN_USE]: {
+        name: 'RAG_WORKSPACE_IN_USE',
+        message: (workspace) => `RAG workspace '${workspace}' is currently in use. Close it first.`
+    },
+    [SDK_SERVER_ERROR_CODES.RAG_WORKSPACE_CLOSE_FAILED]: {
+        name: 'RAG_WORKSPACE_CLOSE_FAILED',
+        message: (details) => `Failed to close RAG workspace${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.RAG_LIST_WORKSPACES_FAILED]: {
+        name: 'RAG_LIST_WORKSPACES_FAILED',
+        message: (details) => `Failed to list RAG workspaces${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.RAG_CHUNK_FAILED]: {
+        name: 'RAG_CHUNK_FAILED',
+        message: (details) => `Failed to chunk documents${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.RAG_WORKSPACE_NOT_OPEN]: {
+        name: 'RAG_WORKSPACE_NOT_OPEN',
+        message: (workspace) => `RAG workspace '${workspace}' is not open`
+    },
+    // Download/Resource Errors (53,000-53,199)
+    [SDK_SERVER_ERROR_CODES.FILE_NOT_FOUND]: {
+        name: 'FILE_NOT_FOUND',
+        message: (path) => `File not found: ${path}`
+    },
+    [SDK_SERVER_ERROR_CODES.DOWNLOAD_CANCELLED]: {
+        name: 'DOWNLOAD_CANCELLED',
+        message: 'Download was cancelled'
+    },
+    [SDK_SERVER_ERROR_CODES.CHECKSUM_VALIDATION_FAILED]: {
+        name: 'CHECKSUM_VALIDATION_FAILED',
+        message: (fileName) => `Checksum validation failed for ${fileName}`
+    },
+    [SDK_SERVER_ERROR_CODES.HTTP_ERROR]: {
+        name: 'HTTP_ERROR',
+        message: (status, statusText) => `HTTP error: ${status} ${statusText}`
+    },
+    [SDK_SERVER_ERROR_CODES.NO_RESPONSE_BODY]: {
+        name: 'NO_RESPONSE_BODY',
+        message: 'No response body received from HTTP request'
+    },
+    [SDK_SERVER_ERROR_CODES.RESPONSE_BODY_NOT_READABLE]: {
+        name: 'RESPONSE_BODY_NOT_READABLE',
+        message: 'Response body is not readable'
+    },
+    [SDK_SERVER_ERROR_CODES.NO_BLOB_FOUND]: {
+        name: 'NO_BLOB_FOUND',
+        message: (fileName) => `No blob found for ${fileName}`
+    },
+    [SDK_SERVER_ERROR_CODES.DOWNLOAD_ASSET_FAILED]: {
+        name: 'DOWNLOAD_ASSET_FAILED',
+        message: (details) => `Failed to download asset${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.SEEDING_NOT_SUPPORTED]: {
+        name: 'SEEDING_NOT_SUPPORTED',
+        message: 'Seeding is only supported for hyperdrive models'
+    },
+    [SDK_SERVER_ERROR_CODES.HYPERDRIVE_DOWNLOAD_FAILED]: {
+        name: 'HYPERDRIVE_DOWNLOAD_FAILED',
+        message: (details) => `Hyperdrive download failed: ${details}`
+    },
+    [SDK_SERVER_ERROR_CODES.REGISTRY_DOWNLOAD_FAILED]: {
+        name: 'REGISTRY_DOWNLOAD_FAILED',
+        message: (details) => `Registry download failed: ${details}`
+    },
+    [SDK_SERVER_ERROR_CODES.INSECURE_MODEL_SOURCE]: {
+        name: 'INSECURE_MODEL_SOURCE',
+        message: (url, reason) => `Refusing insecure model download from ${url}: ${reason}`
+    },
+    [SDK_SERVER_ERROR_CODES.CHECKSUM_UNAVAILABLE]: {
+        name: 'CHECKSUM_UNAVAILABLE',
+        message: (url) => `Model download from ${url} could not be verified against a trusted checksum ` +
+            `and requireHttpChecksum is enabled`
+    },
+    [SDK_SERVER_ERROR_CODES.INVALID_SHARD_URL_PATTERN]: {
+        name: 'INVALID_SHARD_URL_PATTERN',
+        message: (url) => `URL does not contain a valid sharded model pattern: ${url}`
+    },
+    [SDK_SERVER_ERROR_CODES.ARCHIVE_EXTRACTION_FAILED]: {
+        name: 'ARCHIVE_EXTRACTION_FAILED',
+        message: (archivePath) => `Failed to extract archive: ${archivePath}`
+    },
+    [SDK_SERVER_ERROR_CODES.ARCHIVE_UNSUPPORTED_TYPE]: {
+        name: 'ARCHIVE_UNSUPPORTED_TYPE',
+        message: (archivePath) => `Unsupported archive type: ${archivePath}`
+    },
+    [SDK_SERVER_ERROR_CODES.ARCHIVE_MISSING_SHARDS]: {
+        name: 'ARCHIVE_MISSING_SHARDS',
+        message: (missingFile) => `Archive is missing required shard file: ${missingFile}`
+    },
+    [SDK_SERVER_ERROR_CODES.PARTIAL_DOWNLOAD_OFFLINE]: {
+        name: 'PARTIAL_DOWNLOAD_OFFLINE',
+        message: (url, downloadedBytes) => `Cannot resume partial download (${downloadedBytes} bytes downloaded) - unable to connect. URL: ${url}`
+    },
+    // Cache Operations (53,200-53,349)
+    [SDK_SERVER_ERROR_CODES.DELETE_CACHE_FAILED]: {
+        name: 'DELETE_CACHE_FAILED',
+        message: (details) => `Failed to delete cache${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.INVALID_DELETE_CACHE_PARAMS]: {
+        name: 'INVALID_DELETE_CACHE_PARAMS',
+        message: 'Invalid deleteCache parameters - provide either modelId or cacheKey'
+    },
+    [SDK_SERVER_ERROR_CODES.CACHE_DIR_NOT_ABSOLUTE]: {
+        name: 'CACHE_DIR_NOT_ABSOLUTE',
+        message: 'Cache directory must be an absolute path'
+    },
+    [SDK_SERVER_ERROR_CODES.CACHE_DIR_NOT_WRITABLE]: {
+        name: 'CACHE_DIR_NOT_WRITABLE',
+        message: (cacheDir, details) => `Cache directory is not writable: ${cacheDir}${details ? `. ${details}` : ''}`
+    },
+    // Config Operations (53,350-53,499)
+    [SDK_SERVER_ERROR_CODES.SET_CONFIG_FAILED]: {
+        name: 'SET_CONFIG_FAILED',
+        message: (details) => `Failed to set config${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.CONFIG_ALREADY_SET]: {
+        name: 'CONFIG_ALREADY_SET',
+        message: 'Config has already been set and is immutable. Config can only be set once during SDK initialization.'
+    },
+    // System/Runtime (53,500-53,699)
+    [SDK_SERVER_ERROR_CODES.FFMPEG_NOT_AVAILABLE]: {
+        name: 'FFMPEG_NOT_AVAILABLE',
+        message: 'FFmpeg is not available on this system'
+    },
+    [SDK_SERVER_ERROR_CODES.AUDIO_PLAYER_FAILED]: {
+        name: 'AUDIO_PLAYER_FAILED',
+        message: (details) => `Audio player failed: ${details}`
+    },
+    [SDK_SERVER_ERROR_CODES.INVALID_AUDIO_CHUNK_TYPE]: {
+        name: 'INVALID_AUDIO_CHUNK_TYPE',
+        message: 'Invalid audio chunk type'
+    },
+    [SDK_SERVER_ERROR_CODES.ASYNC_DISPOSE_UNAVAILABLE]: {
+        name: 'ASYNC_DISPOSE_UNAVAILABLE',
+        message: 'Host runtime does not expose Symbol.asyncDispose; the SDK request-lifecycle primitives require ES2024 `using`/`asyncDispose` support. Verify your runtime (Bare/Expo/Node ≥ 20.4) and any polyfill registration.'
+    },
+    // RPC (Server-side) (53,700-53,899)
+    [SDK_SERVER_ERROR_CODES.RPC_NO_DATA_RECEIVED]: {
+        name: 'RPC_NO_DATA_RECEIVED',
+        message: 'No data received from request'
+    },
+    [SDK_SERVER_ERROR_CODES.RPC_UNKNOWN_REQUEST_TYPE]: {
+        name: 'RPC_UNKNOWN_REQUEST_TYPE',
+        message: (requestType) => `Unknown request type received: ${requestType}`
+    },
+    // Plugin Errors (53,850-53,899)
+    [SDK_SERVER_ERROR_CODES.PLUGIN_NOT_FOUND]: {
+        name: 'PLUGIN_NOT_FOUND',
+        message: (modelType) => modelType === 'onnx-ocr'
+            ? 'Plugin not found for model type "onnx-ocr": the ONNX OCR engine was removed in @qvac/sdk 0.15.0. Use modelType "ggml-ocr" with GGUF registry models instead (EasyOCR: OCR_LATIN; DocTR: OCR_DOCTR).'
+            : `Plugin not found for model type "${modelType}". If using a custom worker bundle, ensure the plugin is included in your qvac.config plugins array and rebuild with "npx qvac bundle sdk".`
+    },
+    [SDK_SERVER_ERROR_CODES.PLUGIN_HANDLER_NOT_FOUND]: {
+        name: 'PLUGIN_HANDLER_NOT_FOUND',
+        message: (modelType, handler, availableHandlers) => `Handler "${handler}" not found in plugin "${modelType}"` +
+            (availableHandlers ? `. Available handlers: ${availableHandlers}` : '')
+    },
+    [SDK_SERVER_ERROR_CODES.PLUGIN_REQUEST_VALIDATION_FAILED]: {
+        name: 'PLUGIN_REQUEST_VALIDATION_FAILED',
+        message: (handler, details) => `Request validation failed for handler "${handler}"${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.PLUGIN_RESPONSE_VALIDATION_FAILED]: {
+        name: 'PLUGIN_RESPONSE_VALIDATION_FAILED',
+        message: (handler, details) => `Response validation failed for handler "${handler}"${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.PLUGIN_ALREADY_REGISTERED]: {
+        name: 'PLUGIN_ALREADY_REGISTERED',
+        message: (modelType) => `Plugin already registered for modelType: ${modelType}`
+    },
+    [SDK_SERVER_ERROR_CODES.PLUGIN_HANDLER_TYPE_MISMATCH]: {
+        name: 'PLUGIN_HANDLER_TYPE_MISMATCH',
+        message: (handlerName, expected, actual) => `Handler "${handlerName}" is ${actual}, but was called as ${expected}. Use invokePlugin() for reply handlers and invokePluginStream() for streaming handlers.`
+    },
+    [SDK_SERVER_ERROR_CODES.PLUGIN_LOGGING_INVALID]: {
+        name: 'PLUGIN_LOGGING_INVALID',
+        message: (modelType, reason) => `Plugin "${modelType}" has invalid logging configuration: ${reason}`
+    },
+    [SDK_SERVER_ERROR_CODES.PLUGIN_DEFINITION_INVALID]: {
+        name: 'PLUGIN_DEFINITION_INVALID',
+        message: (modelType, details) => `Plugin definition invalid for "${modelType}": ${details}`
+    },
+    [SDK_SERVER_ERROR_CODES.PLUGIN_MODEL_TYPE_RESERVED]: {
+        name: 'PLUGIN_MODEL_TYPE_RESERVED',
+        message: (modelType) => `modelType "${modelType}" is reserved for built-in plugins`
+    },
+    [SDK_SERVER_ERROR_CODES.PLUGIN_LOAD_CONFIG_VALIDATION_FAILED]: {
+        name: 'PLUGIN_LOAD_CONFIG_VALIDATION_FAILED',
+        message: (modelType, details) => `modelConfig validation failed for "${modelType}": ${details}`
+    },
+    // Lifecycle (53,600-53,610)
+    [SDK_SERVER_ERROR_CODES.LIFECYCLE_SUSPEND_FAILED]: {
+        name: 'LIFECYCLE_SUSPEND_FAILED',
+        message: (details) => `Runtime suspend failed${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.LIFECYCLE_RESUME_FAILED]: {
+        name: 'LIFECYCLE_RESUME_FAILED',
+        message: (details) => `Runtime resume failed${details ? `: ${details}` : ''}`
+    },
+    [SDK_SERVER_ERROR_CODES.LIFECYCLE_OPERATION_BLOCKED]: {
+        name: 'LIFECYCLE_OPERATION_BLOCKED',
+        message: (requestType, lifecycleState) => `Operation "${requestType}" is blocked while runtime state is "${lifecycleState}"`
+    },
+    // Security (53,900-53,949)
+    [SDK_SERVER_ERROR_CODES.PATH_TRAVERSAL]: {
+        name: 'PATH_TRAVERSAL',
+        message: (component, basePath) => `Path traversal detected: "${component}" escapes base directory "${basePath}"`
+    },
+    // QVAC Model Registry Operations (53,950-54,000)
+    // Note: Registry client errors (19,001-20,000) are re-thrown directly
+    [SDK_SERVER_ERROR_CODES.QVAC_MODEL_REGISTRY_QUERY_FAILED]: {
+        name: 'QVAC_MODEL_REGISTRY_QUERY_FAILED',
+        message: (details) => `QVAC model registry query failed${details ? `: ${details}` : ''}`
+    }
+};
+const serverDefinitionsToRegister = Object.fromEntries(Object.entries(serverErrorDefinitions).filter(([code]) => !isCodeRegistered(Number(code))));
+addCodes(serverDefinitionsToRegister, { name: 'qvac-sdk-server', version: '1.1.0' });
+export { serverErrorDefinitions as SDK_SERVER_ERROR_DEFINITIONS };

package/dist/src/server/error-handlers.js

@@ -0,0 +1,32 @@
+import { createErrorResponse, responseSchema } from '@qvac/inference/surface';
+import { getServerLogger } from '../logging/index.js';
+import {} from './rpc/profiling/index.js';
+const logger = getServerLogger();
+function buildErrorResponseData(error, profiler) {
+    const errorResponse = createErrorResponse(error);
+    const validated = responseSchema.parse(errorResponse);
+    const json = JSON.stringify(validated);
+    return profiler ? profiler.serializeError(json) : json;
+}
+export function sendErrorResponse(req, error, profiler) {
+    try {
+        req.reply(buildErrorResponseData(error, profiler), 'utf-8');
+    }
+    catch (responseError) {
+        logger.error('Failed to create error response:', responseError);
+        const fallbackError = createErrorResponse(new Error('Internal server error'));
+        req.reply(JSON.stringify(fallbackError), 'utf-8');
+    }
+}
+export function sendStreamErrorResponse(stream, error, profiler) {
+    try {
+        stream.write(buildErrorResponseData(error, profiler) + '\n', 'utf-8');
+        stream.end();
+    }
+    catch (responseError) {
+        logger.error('Failed to create stream error response:', responseError);
+        const fallbackError = createErrorResponse(new Error('Internal server error'));
+        stream.write(JSON.stringify(fallbackError) + '\n', 'utf-8');
+        stream.end();
+    }
+}

package/dist/src/server/plugins/index.d.ts

@@ -0,0 +1,2 @@
+export { registerPlugin, registerPlugins, getPlugin, getPluginHandler, hasPlugin, getAllPlugins, clearPlugins, unregisterPlugin } from '@qvac/inference/plugin-registry';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/server/plugins/index.js

@@ -0,0 +1 @@
+export { registerPlugin, registerPlugins, getPlugin, getPluginHandler, hasPlugin, getAllPlugins, clearPlugins, unregisterPlugin } from '@qvac/inference/plugin-registry';

package/dist/src/server/rpc/profiling/context.d.ts

@@ -0,0 +1,17 @@
+import { type ProfilingRequestMeta, type OperationEvent } from '@qvac/inference/surface';
+export interface ServerProfilingContext {
+    meta: ProfilingRequestMeta;
+    requestStart: number;
+    jsonParseMs?: number;
+    zodValidationMs?: number;
+    handlerExecutionMs?: number;
+    responseZodValidationMs?: number;
+    responseStringifyMs?: number;
+}
+export declare function createProfilingContext(meta: ProfilingRequestMeta): ServerProfilingContext;
+export interface ProfilingInjectionOptions {
+    ctx?: ServerProfilingContext;
+    operation?: OperationEvent;
+}
+export declare function injectProfilingIntoString(jsonString: string, options: ProfilingInjectionOptions): string;
+//# sourceMappingURL=context.d.ts.map

package/dist/src/server/rpc/profiling/context.js

@@ -0,0 +1,31 @@
+import { PROFILING_KEY, nowMs } from '@qvac/inference/surface';
+export function createProfilingContext(meta) {
+    return { meta, requestStart: nowMs() };
+}
+function buildServerBreakdown(ctx) {
+    return {
+        requestJsonParseMs: ctx.jsonParseMs,
+        requestZodValidationMs: ctx.zodValidationMs,
+        handlerExecutionMs: ctx.handlerExecutionMs,
+        responseZodValidationMs: ctx.responseZodValidationMs,
+        responseStringifyMs: ctx.responseStringifyMs,
+        totalServerMs: nowMs() - ctx.requestStart
+    };
+}
+export function injectProfilingIntoString(jsonString, options) {
+    const { ctx, operation } = options;
+    const includeServer = ctx?.meta.includeServer ?? false;
+    const hasContent = includeServer || !!operation;
+    if (!hasContent || !jsonString.endsWith('}')) {
+        return jsonString;
+    }
+    const id = ctx?.meta.id ?? operation?.profileId ?? '';
+    const profilingMeta = { id };
+    if (includeServer && ctx) {
+        profilingMeta['server'] = buildServerBreakdown(ctx);
+    }
+    if (operation) {
+        profilingMeta['operation'] = operation;
+    }
+    return jsonString.slice(0, -1) + `,"${PROFILING_KEY}":${JSON.stringify(profilingMeta)}}`;
+}

package/dist/src/server/rpc/profiling/index.d.ts

@@ -0,0 +1,2 @@
+export { createServerProfiler, type ServerProfiler } from './profiler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/server/rpc/profiling/index.js

@@ -0,0 +1 @@
+export { createServerProfiler } from './profiler.js';

package/dist/src/server/rpc/profiling/profiler.d.ts

@@ -0,0 +1,13 @@
+import { type Response, type ProfilingRequestMeta } from '@qvac/inference/surface';
+import { type ServerProfilingContext } from './context.js';
+export type ServerProfiler = {
+    markRequestParsed: (ms: number) => void;
+    markRequestValidated: (ms: number) => void;
+    startHandler: () => void;
+    endHandler: () => void;
+    serialize: (response?: Response, final?: boolean) => string;
+    serializeError: (json: string) => string;
+    getContext: () => ServerProfilingContext | undefined;
+};
+export declare function createServerProfiler(meta?: ProfilingRequestMeta): ServerProfiler;
+//# sourceMappingURL=profiler.d.ts.map