@qvac/sdk 0.6.1 → 0.7.0

package/dist/server/utils/shard-utils.js

@@ -1,8 +1,8 @@
 import { ModelLoadFailedError, InvalidShardUrlPatternError, } from "../../utils/errors-server.js";
 import { generateShortHash } from "./formatting.js";
+import { validateAndJoinPath } from "./path-security.js";
 import { extractAndWriteTensorsFile } from "./gguf-tensor-extractor.js";
 import { promises as fsPromises } from "bare-fs";
-import path from "bare-path";
 /**
  * Detect if model filename follows shard pattern (00001-of-0000x)
  */
@@ -96,7 +96,7 @@ export async function checkAllShardsExist(shardDir, shardFilename) {
     }
     const shardFilenames = generateShardFilenames(shardFilename);
     const allShardsExist = await Promise.all(shardFilenames.map((f) => fsPromises
-        .access(path.join(shardDir, f))
+        .access(validateAndJoinPath(shardDir, f))
         .then(() => true)
         .catch(() => false))).then((results) => results.every((exists) => exists));
     return allShardsExist;
@@ -118,7 +118,7 @@ export async function validateShardedModelCache(shardDir, shardFilename) {
     }
     const tensorsFile = `${shardInfo.baseFilename}.tensors.txt`;
     const tensorsExist = await fsPromises
-        .access(path.join(shardDir, tensorsFile))
+        .access(validateAndJoinPath(shardDir, tensorsFile))
         .then(() => true)
         .catch(() => false);
     return tensorsExist;

package/dist/server/worker-core.d.ts

@@ -0,0 +1,6 @@
+export declare function initializeWorkerCore(): {
+    hasRPCConfig: boolean;
+};
+export declare function ensureRPCSetup(): void;
+export declare function isCoreInitialized(): boolean;
+//# sourceMappingURL=worker-core.d.ts.map

package/dist/server/worker-core.js

@@ -0,0 +1,88 @@
+import process from "bare-process";
+import { createBareKitRPCServer, createIPCClient, } from "./rpc/create-server.js";
+import { destroySwarm } from "./bare/hyperswarm.js";
+import { initEnv, getValidatedEnv } from "./env.js";
+import { closeAllRagInstances } from "./bare/rag-hyperdb/index.js";
+import { cleanupDownloads } from "./rpc/handlers/load-model/download-manager.js";
+import { unloadAllModels } from "./bare/registry/model-registry.js";
+import { closeRegistryClient } from "./bare/registry/registry-client.js";
+import { clearAllLoggingStreams, startLogBuffering, } from "./bare/registry/logging-stream-registry.js";
+import { clearAllAddonLoggers, getServerLogger, SDK_LOG_ID } from "../logging/index.js";
+import { clearPlugins } from "./plugins/index.js";
+let coreInitialized = false;
+let rpcInitialized = false;
+let isShuttingDown = false;
+const logger = getServerLogger();
+export function initializeWorkerCore() {
+    if (coreInitialized) {
+        const validatedEnv = getValidatedEnv();
+        return { hasRPCConfig: !!validatedEnv.QVAC_IPC_SOCKET_PATH };
+    }
+    startLogBuffering(SDK_LOG_ID);
+    const { hasRPCConfig } = initEnv();
+    setupShutdownHandlers();
+    coreInitialized = true;
+    logger.debug("Worker core initialized");
+    logger.debug("Arguments to worker:", process.argv);
+    return { hasRPCConfig };
+}
+export function ensureRPCSetup() {
+    if (rpcInitialized)
+        return;
+    if (!coreInitialized) {
+        initializeWorkerCore();
+    }
+    try {
+        const validatedEnv = getValidatedEnv();
+        const ipcSocketPath = validatedEnv.QVAC_IPC_SOCKET_PATH;
+        if (ipcSocketPath) {
+            logger.info(`Running in desktop mode, connecting to IPC socket: ${ipcSocketPath}`);
+            const rpc = createIPCClient(ipcSocketPath);
+            logger.debug("Desktop IPC client created?", !!rpc);
+        }
+        else {
+            logger.info("Running in BareKit IPC mode");
+            createBareKitRPCServer();
+        }
+        logger.info("Bare worker started and listening for RPC requests");
+        logger.debug("Working directory:", process.cwd());
+        rpcInitialized = true;
+    }
+    catch (error) {
+        logger.error("Worker error:", error);
+        process.exit(1);
+    }
+}
+export function isCoreInitialized() {
+    return coreInitialized;
+}
+function clearRegistries() {
+    clearAllLoggingStreams();
+    clearAllAddonLoggers();
+    clearPlugins();
+}
+function setupShutdownHandlers() {
+    const shutdownHandler = async () => {
+        if (isShuttingDown)
+            return;
+        isShuttingDown = true;
+        logger.info("🐻 Bare worker shutdown signal received, cleaning up...");
+        try {
+            clearRegistries();
+            await Promise.allSettled([
+                destroySwarm(),
+                closeAllRagInstances(),
+                cleanupDownloads(),
+                unloadAllModels(),
+                closeRegistryClient(),
+            ]);
+            logger.info("✅ Cleanup completed successfully");
+        }
+        catch (error) {
+            logger.error("❌ Error during shutdown cleanup:", error);
+        }
+        process.exit(0);
+    };
+    process.once("SIGTERM", () => void shutdownHandler());
+    process.once("SIGINT", () => void shutdownHandler());
+}

package/dist/server/worker.d.ts

@@ -1,6 +1,5 @@
-export declare function getEnv(): {
-    HOME_DIR: string;
-    QVAC_IPC_SOCKET_PATH?: string | undefined;
-};
-export declare function ensureRPCSetup(): void;
+/**
+ * Default worker entry point that registers ALL built-in plugins.
+ */
+export {};
 //# sourceMappingURL=worker.d.ts.map

package/dist/server/worker.js

@@ -1,87 +1,23 @@
-import process from "bare-process";
-import { isBareKit } from "which-runtime";
-import { createBareKitRPCServer, createIPCClient, } from "./rpc/create-server.js";
-import { z } from "zod";
-import { destroySwarm } from "./bare/hyperswarm.js";
-import { closeAllRagInstances } from "./bare/rag-hyperdb/index.js";
-import { cleanupDownloads } from "./rpc/handlers/load-model/download-manager.js";
-import { unloadAllModels } from "./bare/registry/model-registry.js";
-import { clearAllLoggingStreams, startLogBuffering, } from "./bare/registry/logging-stream-registry.js";
-import { ADDON_NAMESPACES, createAddonLoggerCallback, clearAllAddonLoggers, getServerLogger, SDK_LOG_ID, } from "../logging/index.js";
-import llmAddonLogging from "@qvac/llm-llamacpp/addonLogging.js";
-import embedAddonLogging from "@qvac/embed-llamacpp/addonLogging.js";
-import ttsAddonLogging from "@qvac/tts-onnx/addonLogging.js";
-import whisperAddonLogging from "@qvac/transcription-whispercpp/addonLogging.js";
-import nmtAddonLogging from "@qvac/translation-nmtcpp/addonLogging.js";
-// Buffer SDK logs from startup so clients can receive them when they subscribe
-startLogBuffering(SDK_LOG_ID);
+/**
+ * Default worker entry point that registers ALL built-in plugins.
+ */
+import { initializeWorkerCore, ensureRPCSetup } from "./worker-core.js";
+import { registerPlugin } from "./plugins/index.js";
+import { getServerLogger } from "../logging/index.js";
+import { llmPlugin, embeddingsPlugin, whisperPlugin, nmtPlugin, ttsPlugin, ocrPlugin, } from "./bare/plugins/index.js";
+const { hasRPCConfig } = initializeWorkerCore();
 const logger = getServerLogger();
 logger.info("🐻 Hello from Bare");
-logger.debug("Arguments to worker:", process.argv);
-// Initialize addon logger callbacks
-llmAddonLogging.setLogger(createAddonLoggerCallback(ADDON_NAMESPACES.LLAMACPP_LLM));
-embedAddonLogging.setLogger(createAddonLoggerCallback(ADDON_NAMESPACES.LLAMACPP_EMBED));
-ttsAddonLogging.setLogger(createAddonLoggerCallback(ADDON_NAMESPACES.TTS));
-whisperAddonLogging.setLogger(createAddonLoggerCallback(ADDON_NAMESPACES.WHISPERCPP));
-nmtAddonLogging.setLogger(createAddonLoggerCallback(ADDON_NAMESPACES.NMTCPP));
-const defaultHomeDir = process.env["HOME"] || process.env["USERPROFILE"] || "/tmp";
-let envConfig = { HOME_DIR: defaultHomeDir };
-let hasRPCConfig = false;
-if (isBareKit && process.argv[0]) {
-    logger.info("Running in BareKit mode");
-    envConfig["HOME_DIR"] = process.argv[0];
-}
-// Try to parse any argument as JSON config (fail gracefully)
-if (process.argv[2]) {
-    try {
-        const rpcArgs = JSON.parse(process.argv[2]);
-        envConfig = { ...envConfig, ...rpcArgs };
-        hasRPCConfig = true;
-        logger.info("Parsed RPC configuration from arguments");
-    }
-    catch {
-        // Not JSON or invalid - use defaults (direct mode)
-        logger.info("Using default configuration (direct mode)");
-    }
-}
-const validatedEnv = z
-    .object({
-    QVAC_IPC_SOCKET_PATH: z.string().optional(),
-    HOME_DIR: z.string(),
-})
-    .parse(envConfig);
-export function getEnv() {
-    return {
-        ...process.env,
-        ...validatedEnv,
-    };
-}
-let rpcInitialized = false;
-export function ensureRPCSetup() {
-    if (rpcInitialized)
-        return;
-    try {
-        const ipcSocketPath = validatedEnv.QVAC_IPC_SOCKET_PATH;
-        if (ipcSocketPath) {
-            logger.info(`Running in desktop mode, connecting to IPC socket: ${ipcSocketPath}`);
-            // Connect to the IPC server (Named Pipe or Unix Socket)
-            const rpc = createIPCClient(ipcSocketPath);
-            logger.debug("Desktop IPC client created?", !!rpc);
-        }
-        else {
-            logger.info("Running in BareKit IPC mode");
-            // Start the standard RPC server with BareKit IPC for mobile
-            createBareKitRPCServer();
-        }
-        logger.info("Bare worker started and listening for RPC requests");
-        logger.debug("Working directory:", process.cwd());
-        rpcInitialized = true;
-    }
-    catch (error) {
-        logger.error("Worker error:", error);
-        process.exit(1);
-    }
-}
+// Register all built-in plugins
+registerPlugin(llmPlugin);
+registerPlugin(embeddingsPlugin);
+registerPlugin(whisperPlugin);
+registerPlugin(nmtPlugin);
+registerPlugin(ttsPlugin);
+registerPlugin(ocrPlugin);
+logger.info(hasRPCConfig
+    ? "Parsed RPC configuration from arguments"
+    : "Using default configuration (direct mode)");
 // Auto-setup RPC only if we successfully parsed RPC configuration
 if (hasRPCConfig) {
     ensureRPCSetup();
@@ -89,37 +25,3 @@ if (hasRPCConfig) {
 else {
     logger.info("Running in direct mode - RPC setup will be lazy");
 }
-// Centralized logger cleanup
-function clearLoggers() {
-    clearAllLoggingStreams();
-    clearAllAddonLoggers();
-    llmAddonLogging.releaseLogger();
-    embedAddonLogging.releaseLogger();
-    ttsAddonLogging.releaseLogger();
-    whisperAddonLogging.releaseLogger();
-    nmtAddonLogging.releaseLogger();
-}
-// Centralized cleanup for graceful shutdown
-let isShuttingDown = false;
-async function shutdownHandler() {
-    if (isShuttingDown)
-        return;
-    isShuttingDown = true;
-    logger.info("🐻 Bare worker shutdown signal received, cleaning up...");
-    try {
-        clearLoggers();
-        await Promise.allSettled([
-            destroySwarm(),
-            closeAllRagInstances(),
-            cleanupDownloads(),
-            unloadAllModels(),
-        ]);
-        logger.info("✅ Cleanup completed successfully");
-    }
-    catch (error) {
-        logger.error("❌ Error during shutdown cleanup:", error);
-    }
-    process.exit(0);
-}
-process.once("SIGTERM", () => void shutdownHandler());
-process.once("SIGINT", () => void shutdownHandler());

package/dist/utils/errors-client.d.ts

@@ -8,9 +8,6 @@ export declare class InvalidOperationError extends QvacErrorBase {
 export declare class StreamEndedError extends QvacErrorBase {
     constructor(cause?: unknown);
 }
-export declare class NoDataReceivedError extends QvacErrorBase {
-    constructor(cause?: unknown);
-}
 export declare class InvalidAudioChunkError extends QvacErrorBase {
     constructor(cause?: unknown);
 }
@@ -35,9 +32,6 @@ export declare class RPCResponseStreamNotCreatedError extends QvacErrorBase {
 export declare class RPCConnectionFailedError extends QvacErrorBase {
     constructor(details: string, cause?: unknown);
 }
-export declare class UnknownRequestTypeError extends QvacErrorBase {
-    constructor(cause?: unknown);
-}
 export declare class ProviderStartFailedError extends QvacErrorBase {
     constructor(details?: string, cause?: unknown);
 }
@@ -56,9 +50,15 @@ export declare class DelegateConnectionFailedError extends QvacErrorBase {
 export declare class SDKNotFoundInNodeModulesError extends QvacErrorBase {
     constructor(cause?: unknown);
 }
+export declare class MultipleSDKInstallationsError extends QvacErrorBase {
+    constructor(packages: string, cause?: unknown);
+}
 export declare class WorkerFileNotFoundError extends QvacErrorBase {
     constructor(workerPath: string, cause?: unknown);
 }
+export declare class PearWorkerEntryRequiredError extends QvacErrorBase {
+    constructor(workerEntry: string, cause?: unknown);
+}
 export declare class ConfigFileNotFoundError extends QvacErrorBase {
     constructor(searchPaths: string, cause?: unknown);
 }
@@ -128,4 +128,7 @@ export declare class InvalidDeleteCacheParamsError extends QvacErrorBase {
 export declare class SetConfigFailedError extends QvacErrorBase {
     constructor(details?: string, cause?: unknown);
 }
+export declare class ModelRegistryQueryFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
 //# sourceMappingURL=errors-client.d.ts.map

package/dist/utils/errors-client.js

@@ -1,5 +1,6 @@
 import { QvacErrorBase } from "@qvac/error";
 import { SDK_CLIENT_ERROR_CODES } from "../schemas/sdk-errors-client.js";
+import { SDK_SERVER_ERROR_CODES } from "../schemas/sdk-errors-server.js";
 import { createErrorOptions } from "./errors-base.js";
 // ============== Response Validation Errors ==============
 export class InvalidResponseError extends QvacErrorBase {
@@ -17,11 +18,6 @@ export class StreamEndedError extends QvacErrorBase {
         super(createErrorOptions(SDK_CLIENT_ERROR_CODES.STREAM_ENDED_WITHOUT_RESPONSE, undefined, cause));
     }
 }
-export class NoDataReceivedError extends QvacErrorBase {
-    constructor(cause) {
-        super(createErrorOptions(SDK_CLIENT_ERROR_CODES.NO_DATA_RECEIVED, undefined, cause));
-    }
-}
 export class InvalidAudioChunkError extends QvacErrorBase {
     constructor(cause) {
         super(createErrorOptions(SDK_CLIENT_ERROR_CODES.INVALID_AUDIO_CHUNK_TYPE, undefined, cause));
@@ -63,11 +59,6 @@ export class RPCConnectionFailedError extends QvacErrorBase {
         super(createErrorOptions(SDK_CLIENT_ERROR_CODES.RPC_CONNECTION_FAILED, [details], cause));
     }
 }
-export class UnknownRequestTypeError extends QvacErrorBase {
-    constructor(cause) {
-        super(createErrorOptions(SDK_CLIENT_ERROR_CODES.UNKNOWN_REQUEST_TYPE, undefined, cause));
-    }
-}
 // ============== Provider/Delegation Errors ==============
 export class ProviderStartFailedError extends QvacErrorBase {
     constructor(details, cause) {
@@ -100,11 +91,21 @@ export class SDKNotFoundInNodeModulesError extends QvacErrorBase {
         super(createErrorOptions(SDK_CLIENT_ERROR_CODES.SDK_NOT_FOUND_IN_NODE_MODULES, undefined, cause));
     }
 }
+export class MultipleSDKInstallationsError extends QvacErrorBase {
+    constructor(packages, cause) {
+        super(createErrorOptions(SDK_CLIENT_ERROR_CODES.MULTIPLE_SDK_INSTALLATIONS, [packages], cause));
+    }
+}
 export class WorkerFileNotFoundError extends QvacErrorBase {
     constructor(workerPath, cause) {
         super(createErrorOptions(SDK_CLIENT_ERROR_CODES.WORKER_FILE_NOT_FOUND, [workerPath], cause));
     }
 }
+export class PearWorkerEntryRequiredError extends QvacErrorBase {
+    constructor(workerEntry, cause) {
+        super(createErrorOptions(SDK_CLIENT_ERROR_CODES.PEAR_WORKER_ENTRY_REQUIRED, [workerEntry], cause));
+    }
+}
 export class ConfigFileNotFoundError extends QvacErrorBase {
     constructor(searchPaths, cause) {
         super(createErrorOptions(SDK_CLIENT_ERROR_CODES.CONFIG_FILE_NOT_FOUND, [searchPaths], cause));
@@ -128,7 +129,6 @@ export class ConfigValidationFailedError extends QvacErrorBase {
 // ============== Operation Errors (Client-side wrappers for server operations) ==============
 // These are used by client API to throw errors based on server responses
 // They reference server error codes but are thrown on client side
-import { SDK_SERVER_ERROR_CODES } from "../schemas/sdk-errors-server.js";
 export class ModelUnloadFailedError extends QvacErrorBase {
     constructor(modelId, cause) {
         super(createErrorOptions(SDK_SERVER_ERROR_CODES.MODEL_UNLOAD_FAILED, modelId ? [modelId] : undefined, cause));
@@ -224,3 +224,11 @@ export class SetConfigFailedError extends QvacErrorBase {
         super(createErrorOptions(SDK_SERVER_ERROR_CODES.SET_CONFIG_FAILED, details ? [details] : undefined, 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/utils/errors-server.d.ts

@@ -11,9 +11,6 @@ export declare class ModelNotLoadedError extends QvacErrorBase {
 export declare class ModelIsDelegatedError extends QvacErrorBase {
     constructor(modelId: string, cause?: unknown);
 }
-export declare class UnknownModelTypeError extends QvacErrorBase {
-    constructor(modelType: string, cause?: unknown);
-}
 export declare class ModelLoadFailedError extends QvacErrorBase {
     constructor(details?: string, cause?: unknown);
 }
@@ -32,10 +29,10 @@ export declare class ProjectionModelRequiredError extends QvacErrorBase {
 export declare class VADModelRequiredError extends QvacErrorBase {
     constructor(cause?: unknown);
 }
-export declare class TTSConfigModelRequiredError extends QvacErrorBase {
+export declare class TtsArtifactsRequiredError extends QvacErrorBase {
     constructor(cause?: unknown);
 }
-export declare class ESpeakDataPathRequiredError extends QvacErrorBase {
+export declare class TtsReferenceAudioRequiredError extends QvacErrorBase {
     constructor(cause?: unknown);
 }
 export declare class ModelUnloadFailedError extends QvacErrorBase {
@@ -128,6 +125,9 @@ export declare class SeedingNotSupportedError extends QvacErrorBase {
 export declare class HyperdriveDownloadFailedError extends QvacErrorBase {
     constructor(details: string, cause?: unknown);
 }
+export declare class RegistryDownloadFailedError extends QvacErrorBase {
+    constructor(details: string, cause?: unknown);
+}
 export declare class InvalidShardUrlPatternError extends QvacErrorBase {
     constructor(url: string, cause?: unknown);
 }
@@ -185,4 +185,43 @@ export declare class DelegateNoFinalResponseError extends QvacErrorBase {
 export declare class DelegateConnectionFailedError extends QvacErrorBase {
     constructor(details: string, cause?: unknown);
 }
+export declare class DelegateProviderError extends QvacErrorBase {
+    constructor(details: string, providerCode?: number, cause?: unknown);
+}
+export declare class RPCNoDataReceivedError extends QvacErrorBase {
+    constructor(cause?: unknown);
+}
+export declare class RPCUnknownRequestTypeError extends QvacErrorBase {
+    constructor(requestType: string, cause?: unknown);
+}
+export declare class PluginNotFoundError extends QvacErrorBase {
+    constructor(modelType: string, cause?: unknown);
+}
+export declare class PluginHandlerNotFoundError extends QvacErrorBase {
+    constructor(modelType: string, handler: string, availableHandlers?: string[], cause?: unknown);
+}
+export declare class PluginRequestValidationFailedError extends QvacErrorBase {
+    constructor(handler: string, details?: string, cause?: unknown);
+}
+export declare class PluginResponseValidationFailedError extends QvacErrorBase {
+    constructor(handler: string, details?: string, cause?: unknown);
+}
+export declare class PluginAlreadyRegisteredError extends QvacErrorBase {
+    constructor(modelType: string, cause?: unknown);
+}
+export declare class PluginHandlerTypeMismatchError extends QvacErrorBase {
+    constructor(handlerName: string, expected: string, actual: string, cause?: unknown);
+}
+export declare class PluginLoggingInvalidError extends QvacErrorBase {
+    constructor(modelType: string, reason: string, cause?: unknown);
+}
+export declare class PluginDefinitionInvalidError extends QvacErrorBase {
+    constructor(modelType: string, details: string, cause?: unknown);
+}
+export declare class PathTraversalError extends QvacErrorBase {
+    constructor(component: string, basePath: string, cause?: unknown);
+}
+export declare class ModelRegistryQueryFailedError extends QvacErrorBase {
+    constructor(details?: string, cause?: unknown);
+}
 //# sourceMappingURL=errors-server.d.ts.map

package/dist/utils/errors-server.js

@@ -22,11 +22,6 @@ export class ModelIsDelegatedError extends QvacErrorBase {
         super(createErrorOptions(SDK_SERVER_ERROR_CODES.MODEL_IS_DELEGATED, [modelId], cause));
     }
 }
-export class UnknownModelTypeError extends QvacErrorBase {
-    constructor(modelType, cause) {
-        super(createErrorOptions(SDK_SERVER_ERROR_CODES.UNKNOWN_MODEL_TYPE, [modelType], cause));
-    }
-}
 // ============== Model Loading Errors ==============
 export class ModelLoadFailedError extends QvacErrorBase {
     constructor(details, cause) {
@@ -58,14 +53,14 @@ export class VADModelRequiredError extends QvacErrorBase {
         super(createErrorOptions(SDK_SERVER_ERROR_CODES.VAD_MODEL_REQUIRED, undefined, cause));
     }
 }
-export class TTSConfigModelRequiredError extends QvacErrorBase {
+export class TtsArtifactsRequiredError extends QvacErrorBase {
     constructor(cause) {
-        super(createErrorOptions(SDK_SERVER_ERROR_CODES.TTS_CONFIG_MODEL_REQUIRED, undefined, cause));
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.TTS_ARTIFACTS_REQUIRED, undefined, cause));
     }
 }
-export class ESpeakDataPathRequiredError extends QvacErrorBase {
+export class TtsReferenceAudioRequiredError extends QvacErrorBase {
     constructor(cause) {
-        super(createErrorOptions(SDK_SERVER_ERROR_CODES.ESPEAK_DATA_PATH_REQUIRED, undefined, cause));
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.TTS_REFERENCE_AUDIO_REQUIRED, undefined, cause));
     }
 }
 // ============== Model Unloading Errors ==============
@@ -222,6 +217,11 @@ export class HyperdriveDownloadFailedError extends QvacErrorBase {
         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));
@@ -322,3 +322,76 @@ export class DelegateConnectionFailedError extends QvacErrorBase {
         super(createErrorOptions(SDK_SERVER_ERROR_CODES.DELEGATE_CONNECTION_FAILED, [details], cause));
     }
 }
+export class DelegateProviderError extends QvacErrorBase {
+    constructor(details, providerCode, cause) {
+        super(createErrorOptions(SDK_SERVER_ERROR_CODES.DELEGATE_PROVIDER_ERROR, providerCode !== undefined
+            ? [details, String(providerCode)]
+            : [details], cause));
+    }
+}
+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 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));
+    }
+}
+// ============== 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/utils/path-sanitize.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pure string sanitization for path components. No runtime-specific dependencies.
+ * Safe to import from both Bare (server) and Bun/Node (tests, client).
+ */
+/**
+ * Sanitize a path component that will be joined to a base directory.
+ * Strips traversal sequences, absolute prefixes, and normalizes separators.
+ *
+ * Throws on null bytes (literal or URL-encoded).
+ */
+export declare function sanitizePathComponent(component: string): string;
+/**
+ * Check whether a resolved target path is contained within a base directory.
+ * Portable — caller provides the resolve function and separator for their runtime.
+ */
+export declare function checkPathWithinBase(basePath: string, targetPath: string, resolveFn: (...args: string[]) => string, sep: string): boolean;
+//# sourceMappingURL=path-sanitize.d.ts.map

package/dist/utils/path-sanitize.js

@@ -0,0 +1,54 @@
+/**
+ * Pure string sanitization for path components. No runtime-specific dependencies.
+ * Safe to import from both Bare (server) and Bun/Node (tests, client).
+ */
+/**
+ * Sanitize a path component that will be joined to a base directory.
+ * Strips traversal sequences, absolute prefixes, and normalizes separators.
+ *
+ * Throws on null bytes (literal or URL-encoded).
+ */
+export function sanitizePathComponent(component) {
+    if (component === "")
+        return "";
+    // Reject null bytes (literal and URL-encoded)
+    if (component.includes("\0") || component.includes("%00")) {
+        throw new Error(`Path component contains null byte: ${component}`);
+    }
+    let sanitized = component;
+    // Decode common URL-encoded traversal sequences
+    sanitized = sanitized
+        .replace(/%2e/gi, ".")
+        .replace(/%2f/gi, "/")
+        .replace(/%5c/gi, "\\");
+    // Normalize backslashes to forward slashes
+    sanitized = sanitized.replace(/\\/g, "/");
+    // Strip Windows drive letter prefixes (C:/, D:/, etc.)
+    sanitized = sanitized.replace(/^[A-Za-z]:\//, "");
+    // Strip leading slashes (absolute path prefixes)
+    sanitized = sanitized.replace(/^\/+/, "");
+    // Remove all ".." segments (start, middle, end) iteratively until stable
+    let prev = "";
+    while (prev !== sanitized) {
+        prev = sanitized;
+        sanitized = sanitized.replace(/^\.\.\//g, "");
+        sanitized = sanitized.replace(/\/\.\.$/g, "");
+        sanitized = sanitized.replace(/\/\.\.\//g, "/");
+        if (sanitized === "..")
+            sanitized = "";
+    }
+    // Strip any remaining leading slashes produced by stripping
+    sanitized = sanitized.replace(/^\/+/, "");
+    return sanitized;
+}
+/**
+ * Check whether a resolved target path is contained within a base directory.
+ * Portable — caller provides the resolve function and separator for their runtime.
+ */
+export function checkPathWithinBase(basePath, targetPath, resolveFn, sep) {
+    const resolvedBase = resolveFn(basePath);
+    const resolvedTarget = resolveFn(targetPath);
+    if (resolvedTarget === resolvedBase)
+        return true;
+    return resolvedTarget.startsWith(resolvedBase + sep);
+}