@qvac/sdk 0.7.1 → 0.8.1

package/dist/server/rpc/handlers/load-model/registry.js

@@ -1,10 +1,9 @@
-import fs, { promises as fsPromises } from "bare-fs";
+import { promises as fsPromises } from "bare-fs";
 import path from "bare-path";
-import {} from "bare-stream";
 import { AbortController } from "bare-abort-controller";
-import { getModelsCacheDir, generateShortHash, detectShardedModel, getShardedModelCacheDir, getShardPath, getOnnxModelPath, calculateFileChecksum, extractTensorsFromShards, calculatePercentage, } from "../../../utils/index.js";
+import { getModelsCacheDir, generateShortHash, detectShardedModel, getShardedModelCacheDir, getShardPath, getOnnxModelPath, measureChecksum, extractTensorsFromShards, calculatePercentage, } from "../../../utils/index.js";
 import { getModelByPath } from "../../../../models/registry/index.js";
-import { getRegistryClient, closeRegistryClient, } from "../../../bare/registry/registry-client.js";
+import { getRegistryClient } from "../../../bare/registry/registry-client.js";
 import { getActiveDownload, registerDownload, unregisterDownload, createRegistryDownloadKey, clearClearCacheFlag, } from "./download-manager.js";
 import { ChecksumValidationFailedError, DownloadCancelledError, ModelNotFoundError, RegistryDownloadFailedError, } from "../../../../utils/errors-server.js";
 import { getServerLogger } from "../../../../logging/index.js";
@@ -22,7 +21,7 @@ function buildBlobBinding(meta) {
 /**
  * Validate a cached file against expected size and checksum.
  */
-async function validateCachedFile(modelPath, modelFileName, expectedSize, expectedChecksum) {
+async function validateCachedFile(modelPath, modelFileName, expectedSize, expectedChecksum, hooks) {
     try {
         await fsPromises.access(modelPath);
         const localStats = await fsPromises.stat(modelPath);
@@ -31,7 +30,7 @@ async function validateCachedFile(modelPath, modelFileName, expectedSize, expect
             logger.info(`✅ Model cached with correct size: ${modelPath}`);
             // Validate checksum if provided
             if (expectedChecksum && expectedChecksum.length === 64) {
-                const checksum = await calculateFileChecksum(modelPath);
+                const checksum = await measureChecksum(modelPath, hooks);
                 if (checksum !== expectedChecksum) {
                     throw new ChecksumValidationFailedError(`${modelFileName}. Expected: ${expectedChecksum}. Actual: ${checksum}. File may be corrupted`);
                 }
@@ -59,89 +58,65 @@ async function validateCachedFile(modelPath, modelFileName, expectedSize, expect
  * When blobBinding is provided, uses direct blob download (skips metadata sync).
  * Otherwise falls back to metadata-based downloadModel.
  */
-async function downloadSingleFileFromRegistry(registryPath, registrySource, modelPath, modelFileName, downloadKey, expectedSize, expectedChecksum, progressCallback, signal, blobBinding) {
+async function downloadSingleFileFromRegistry(registryPath, registrySource, modelPath, modelFileName, downloadKey, expectedSize, expectedChecksum, progressCallback, signal, blobBinding, hooks) {
     if (signal?.aborted) {
         throw new DownloadCancelledError();
     }
     const client = await getRegistryClient();
-    try {
-        let readStream;
-        if (blobBinding) {
-            logger.info(`📥 Downloading blob directly: ${modelFileName}`);
-            const result = await client.downloadBlob(blobBinding, { timeout: REGISTRY_STREAM_TIMEOUT_MS });
-            if (!("stream" in result.artifact)) {
-                throw new RegistryDownloadFailedError(`No stream returned for blob ${modelFileName}`);
-            }
-            readStream = result.artifact.stream;
-        }
-        else {
-            logger.info(`📥 Downloading from registry: ${registryPath}`);
-            const result = await client.downloadModel(registryPath, registrySource, {
-                timeout: REGISTRY_STREAM_TIMEOUT_MS,
-            });
-            if (!("stream" in result.artifact)) {
-                throw new RegistryDownloadFailedError(`No stream returned for ${registryPath}`);
-            }
-            readStream = result.artifact.stream;
-        }
-        const dir = path.dirname(modelPath);
-        await fsPromises.mkdir(dir, { recursive: true });
-        const writeStream = fs.createWriteStream(modelPath);
-        // Track progress
-        let downloadedBytes = 0;
-        readStream.on("data", (chunk) => {
-            const buffer = chunk;
-            downloadedBytes += buffer.length;
-            if (progressCallback) {
-                progressCallback({
-                    type: "modelProgress",
-                    downloaded: downloadedBytes,
-                    total: expectedSize || downloadedBytes,
-                    percentage: expectedSize
-                        ? calculatePercentage(downloadedBytes, expectedSize)
-                        : 0,
-                    downloadKey,
-                });
-            }
-        });
-        // Pipe stream to file
-        readStream.pipe(writeStream);
-        // Wait for download to complete
-        await new Promise((resolve, reject) => {
-            writeStream.on("finish", resolve);
-            writeStream.on("error", reject);
-            readStream.on("error", reject);
-            signal?.addEventListener("abort", () => reject(new Error("Download cancelled")), { once: true });
-        });
-        logger.info(`✅ Downloaded to ${modelPath}`);
-        // Validate file size
-        const stats = await fsPromises.stat(modelPath);
-        if (expectedSize && stats.size !== expectedSize) {
-            await fsPromises.unlink(modelPath).catch(() => { });
-            throw new ChecksumValidationFailedError(`${modelFileName}. File size mismatch: expected ${expectedSize}, got ${stats.size}`);
-        }
-        // Validate checksum
-        if (expectedChecksum && expectedChecksum.length === 64) {
-            const checksum = await calculateFileChecksum(modelPath);
-            if (checksum !== expectedChecksum) {
-                await fsPromises.unlink(modelPath);
-                throw new ChecksumValidationFailedError(`${modelFileName}. Expected: ${expectedChecksum}. Actual: ${checksum}`);
-            }
-            logger.info(`✅ Checksum validated for ${modelFileName}`);
-        }
-        // Send final 100% progress
-        if (progressCallback) {
+    const dir = path.dirname(modelPath);
+    await fsPromises.mkdir(dir, { recursive: true });
+    // Adapt registry client's core.on("download") progress to SDK ModelProgressUpdate.
+    // This reports network-layer bytes, decoupled from disk I/O backpressure.
+    const onProgress = progressCallback
+        ? (progress) => {
+            const total = progress.total || expectedSize || progress.downloaded;
             progressCallback({
                 type: "modelProgress",
-                downloaded: stats.size,
-                total: stats.size,
-                percentage: 100,
+                downloaded: progress.downloaded,
+                total,
+                percentage: total > 0
+                    ? calculatePercentage(progress.downloaded, total)
+                    : 0,
                 downloadKey,
             });
         }
+        : undefined;
+    const clientOptions = {
+        timeout: REGISTRY_STREAM_TIMEOUT_MS,
+        outputFile: modelPath,
+        ...(onProgress && { onProgress }),
+        ...(signal && { signal: signal }),
+    };
+    if (blobBinding) {
+        logger.info(`📥 Downloading blob directly: ${modelFileName}`);
+        await client.downloadBlob(blobBinding, clientOptions);
+    }
+    else {
+        logger.info(`📥 Downloading from registry: ${registryPath}`);
+        await client.downloadModel(registryPath, registrySource, clientOptions);
+    }
+    logger.info(`✅ Downloaded to ${modelPath}`);
+    const stats = await fsPromises.stat(modelPath);
+    if (expectedSize && stats.size !== expectedSize) {
+        await fsPromises.unlink(modelPath).catch(() => { });
+        throw new ChecksumValidationFailedError(`${modelFileName}. File size mismatch: expected ${expectedSize}, got ${stats.size}`);
+    }
+    if (expectedChecksum && expectedChecksum.length === 64) {
+        const checksum = await measureChecksum(modelPath, hooks);
+        if (checksum !== expectedChecksum) {
+            await fsPromises.unlink(modelPath);
+            throw new ChecksumValidationFailedError(`${modelFileName}. Expected: ${expectedChecksum}. Actual: ${checksum}`);
+        }
+        logger.info(`✅ Checksum validated for ${modelFileName}`);
     }
-    finally {
-        await closeRegistryClient();
+    if (progressCallback) {
+        progressCallback({
+            type: "modelProgress",
+            downloaded: stats.size,
+            total: stats.size,
+            percentage: 100,
+            downloadKey,
+        });
     }
 }
 /**
@@ -149,53 +124,44 @@ async function downloadSingleFileFromRegistry(registryPath, registrySource, mode
  */
 async function findModelShards(registryPath) {
     const client = await getRegistryClient();
-    try {
-        // Extract the base path without the shard suffix
-        const shardInfo = detectShardedModel(registryPath.split("/").pop() || "");
-        if (!shardInfo.isSharded) {
-            throw new Error(`Not a sharded model path: ${registryPath}`);
-        }
-        // Get path prefix by removing the shard suffix
-        const pathPrefix = registryPath.replace(/-\d{5}-of-\d{5}\./, ".");
-        const basePath = pathPrefix.substring(0, pathPrefix.lastIndexOf("."));
-        logger.info(`🔍 Finding shards with prefix: ${basePath}`);
-        // Use indexed path range query instead of fetching all models
-        const shards = await client.findModels({
-            gte: { path: basePath },
-            lte: { path: basePath + "\uffff" },
-        });
-        // Sort shards by shard number
-        const sortedShards = shards
-            .filter((s) => {
-            const info = detectShardedModel(s.path.split("/").pop() || "");
-            return info.isSharded;
-        })
-            .sort((a, b) => {
-            const aInfo = detectShardedModel(a.path.split("/").pop() || "");
-            const bInfo = detectShardedModel(b.path.split("/").pop() || "");
-            return (aInfo.currentShard || 0) - (bInfo.currentShard || 0);
-        })
-            .map((s) => ({
-            path: s.path,
-            source: s.source,
-            size: s.blobBinding?.byteLength || 0,
-            checksum: s.blobBinding?.["sha256"] ||
-                s.sha256 ||
-                "",
-        }));
-        logger.info(`📦 Found ${sortedShards.length} shards`);
-        return sortedShards;
-    }
-    finally {
-        await closeRegistryClient();
+    const shardInfo = detectShardedModel(registryPath.split("/").pop() || "");
+    if (!shardInfo.isSharded) {
+        throw new Error(`Not a sharded model path: ${registryPath}`);
     }
+    const pathPrefix = registryPath.replace(/-\d{5}-of-\d{5}\./, ".");
+    const basePath = pathPrefix.substring(0, pathPrefix.lastIndexOf("."));
+    logger.info(`🔍 Finding shards with prefix: ${basePath}`);
+    const shards = await client.findModels({
+        gte: { path: basePath },
+        lte: { path: basePath + "\uffff" },
+    });
+    const sortedShards = shards
+        .filter((s) => {
+        const info = detectShardedModel(s.path.split("/").pop() || "");
+        return info.isSharded;
+    })
+        .sort((a, b) => {
+        const aInfo = detectShardedModel(a.path.split("/").pop() || "");
+        const bInfo = detectShardedModel(b.path.split("/").pop() || "");
+        return (aInfo.currentShard || 0) - (bInfo.currentShard || 0);
+    })
+        .map((s) => ({
+        path: s.path,
+        source: s.source,
+        size: s.blobBinding?.byteLength || 0,
+        checksum: s.blobBinding?.["sha256"] ||
+            s.sha256 ||
+            "",
+    }));
+    logger.info(`📦 Found ${sortedShards.length} shards`);
+    return sortedShards;
 }
 /**
  * Download sharded model files from registry.
  * When localShardMetadata is provided, uses pre-computed metadata + blob direct download
  * instead of querying the registry for shard info.
  */
-async function downloadShardedFilesFromRegistry(registryPath, registrySource, cacheKey, progressCallback, signal, localShardMetadata) {
+async function downloadShardedFilesFromRegistry(registryPath, registrySource, cacheKey, progressCallback, signal, localShardMetadata, hooks) {
     if (signal?.aborted) {
         throw new DownloadCancelledError();
     }
@@ -242,7 +208,7 @@ async function downloadShardedFilesFromRegistry(registryPath, registrySource, ca
         }
         const shard = shards[i];
         const shardPath = getShardPath(cacheKey, shard.filename);
-        const cachedPath = await validateCachedFile(shardPath, shard.filename, shard.size, shard.checksum);
+        const cachedPath = await validateCachedFile(shardPath, shard.filename, shard.size, shard.checksum, hooks);
         if (cachedPath) {
             logger.debug(`✅ Shard ${i + 1}/${shards.length} already cached`);
             overallDownloaded += shard.size;
@@ -283,7 +249,7 @@ async function downloadShardedFilesFromRegistry(registryPath, registrySource, ca
                 });
             }
             : undefined;
-        await downloadSingleFileFromRegistry(shard.path, shard.source, shardPath, shard.filename, downloadKey, shard.size, shard.checksum, shardProgressCallback, signal, shard.blobBinding);
+        await downloadSingleFileFromRegistry(shard.path, shard.source, shardPath, shard.filename, downloadKey, shard.size, shard.checksum, shardProgressCallback, signal, shard.blobBinding, hooks);
         overallDownloaded += shard.size;
         logger.info(`✅ Shard ${i + 1}/${shards.length} downloaded`);
     }
@@ -324,7 +290,7 @@ function findOnnxCompanionDataFile(registryPath) {
  * Both files are placed in the same directory to satisfy ONNX Runtime requirements.
  * When blob bindings are provided, uses direct blob download (skips metadata sync).
  */
-async function downloadOnnxWithDataFromRegistry(registryPath, registrySource, companionDataFile, cacheKey, progressCallback, signal, mainBlobBinding, dataBlobBinding) {
+async function downloadOnnxWithDataFromRegistry(registryPath, registrySource, companionDataFile, cacheKey, progressCallback, signal, mainBlobBinding, dataBlobBinding, hooks) {
     if (signal?.aborted) {
         throw new DownloadCancelledError();
     }
@@ -342,7 +308,7 @@ async function downloadOnnxWithDataFromRegistry(registryPath, registrySource, co
     const overallTotal = mainExpectedSize + dataExpectedSize;
     let overallDownloaded = 0;
     // Check if main file already cached
-    const cachedMainPath = await validateCachedFile(mainPath, mainFilename, mainExpectedSize, mainChecksum);
+    const cachedMainPath = await validateCachedFile(mainPath, mainFilename, mainExpectedSize, mainChecksum, hooks);
     if (cachedMainPath) {
         logger.info(`✅ Main ONNX file already cached: ${mainFilename}`);
         overallDownloaded += mainExpectedSize;
@@ -366,12 +332,12 @@ async function downloadOnnxWithDataFromRegistry(registryPath, registrySource, co
                 });
             }
             : undefined;
-        await downloadSingleFileFromRegistry(registryPath, registrySource, mainPath, mainFilename, downloadKey, mainExpectedSize, mainChecksum, mainProgressCallback, signal, mainBlobBinding);
+        await downloadSingleFileFromRegistry(registryPath, registrySource, mainPath, mainFilename, downloadKey, mainExpectedSize, mainChecksum, mainProgressCallback, signal, mainBlobBinding, hooks);
         overallDownloaded += mainExpectedSize;
         logger.info(`✅ Main ONNX file downloaded: ${mainFilename}`);
     }
     // Check if data file already cached
-    const cachedDataPath = await validateCachedFile(dataPath, dataFilename, dataExpectedSize, dataChecksum);
+    const cachedDataPath = await validateCachedFile(dataPath, dataFilename, dataExpectedSize, dataChecksum, hooks);
     if (cachedDataPath) {
         logger.info(`✅ ONNX data file already cached: ${dataFilename}`);
         overallDownloaded = overallTotal;
@@ -395,7 +361,7 @@ async function downloadOnnxWithDataFromRegistry(registryPath, registrySource, co
                 });
             }
             : undefined;
-        await downloadSingleFileFromRegistry(companionDataFile.registryPath, companionDataFile.registrySource, dataPath, dataFilename, downloadKey, dataExpectedSize, dataChecksum, dataProgressCallback, signal, dataBlobBinding);
+        await downloadSingleFileFromRegistry(companionDataFile.registryPath, companionDataFile.registrySource, dataPath, dataFilename, downloadKey, dataExpectedSize, dataChecksum, dataProgressCallback, signal, dataBlobBinding, hooks);
         logger.info(`✅ ONNX data file downloaded: ${dataFilename}`);
     }
     // Send final 100% progress
@@ -451,12 +417,13 @@ function createManagedDownload(downloadKey, registryPath, downloadFn, progressCa
  * skips the registry metadata sync entirely. Falls back to metadata-based
  * download for unknown models.
  */
-export async function downloadModelFromRegistry(registryPath, registrySource, progressCallback, expectedChecksum) {
+export async function downloadModelFromRegistry(registryPath, registrySource, progressCallback, expectedChecksum, hooks) {
     const downloadKey = createRegistryDownloadKey(registryPath);
     // Check if already downloading
     const existing = getActiveDownload(downloadKey);
     if (existing) {
         logger.info(`📥 Reusing existing download for: ${downloadKey}`);
+        hooks?.markCacheMiss();
         return existing.promise;
     }
     const filename = registryPath.split("/").pop() || registryPath;
@@ -471,7 +438,7 @@ export async function downloadModelFromRegistry(registryPath, registrySource, pr
             let allCached = true;
             for (const shard of localShardMeta) {
                 const shardPath = getShardPath(cacheKey, shard.filename);
-                const cached = await validateCachedFile(shardPath, shard.filename, shard.expectedSize, shard.sha256Checksum);
+                const cached = await validateCachedFile(shardPath, shard.filename, shard.expectedSize, shard.sha256Checksum, hooks);
                 if (!cached) {
                     allCached = false;
                     break;
@@ -480,6 +447,7 @@ export async function downloadModelFromRegistry(registryPath, registrySource, pr
             if (allCached) {
                 const firstShardFilename = localShardMeta[0].filename;
                 logger.info(`✅ All ${localShardMeta.length} shards cached`);
+                hooks?.markCacheHit();
                 if (progressCallback) {
                     const overallTotal = localShardMeta.reduce((sum, s) => sum + s.expectedSize, 0);
                     progressCallback({
@@ -501,7 +469,8 @@ export async function downloadModelFromRegistry(registryPath, registrySource, pr
                 return getShardPath(cacheKey, firstShardFilename);
             }
         }
-        return createManagedDownload(downloadKey, registryPath, (signal) => downloadShardedFilesFromRegistry(registryPath, registrySource, cacheKey, progressCallback, signal, localShardMeta), progressCallback);
+        hooks?.markCacheMiss();
+        return createManagedDownload(downloadKey, registryPath, (signal) => downloadShardedFilesFromRegistry(registryPath, registrySource, cacheKey, progressCallback, signal, localShardMeta, hooks), progressCallback);
     }
     // Check for ONNX with companion data file
     const companionDataFile = findOnnxCompanionDataFile(registryPath);
@@ -512,10 +481,11 @@ export async function downloadModelFromRegistry(registryPath, registrySource, pr
         const dataFilename = companionDataFile.registryPath.split("/").pop() || "";
         const mainPath = getOnnxModelPath(cacheKey, mainFilename);
         const dataPath = getOnnxModelPath(cacheKey, dataFilename);
-        const mainCached = await validateCachedFile(mainPath, mainFilename, modelMetadata?.expectedSize || 0, modelMetadata?.sha256Checksum);
-        const dataCached = await validateCachedFile(dataPath, dataFilename, companionDataFile.expectedSize, companionDataFile.sha256Checksum);
+        const mainCached = await validateCachedFile(mainPath, mainFilename, modelMetadata?.expectedSize || 0, modelMetadata?.sha256Checksum, hooks);
+        const dataCached = await validateCachedFile(dataPath, dataFilename, companionDataFile.expectedSize, companionDataFile.sha256Checksum, hooks);
         if (mainCached && dataCached) {
             logger.info(`✅ ONNX model and data file both cached`);
+            hooks?.markCacheHit();
             if (progressCallback) {
                 const total = (modelMetadata?.expectedSize || 0) + companionDataFile.expectedSize;
                 progressCallback({
@@ -536,11 +506,14 @@ export async function downloadModelFromRegistry(registryPath, registrySource, pr
             }
             return mainCached;
         }
-        const mainBlobBinding = modelMetadata ? buildBlobBinding(modelMetadata) : undefined;
+        const mainBlobBinding = modelMetadata
+            ? buildBlobBinding(modelMetadata)
+            : undefined;
         const dataBlobBinding = companionDataFile.blobCoreKey
             ? buildBlobBinding(companionDataFile)
             : undefined;
-        return createManagedDownload(downloadKey, registryPath, (signal) => downloadOnnxWithDataFromRegistry(registryPath, registrySource, companionDataFile, cacheKey, progressCallback, signal, mainBlobBinding, dataBlobBinding), progressCallback);
+        hooks?.markCacheMiss();
+        return createManagedDownload(downloadKey, registryPath, (signal) => downloadOnnxWithDataFromRegistry(registryPath, registrySource, companionDataFile, cacheKey, progressCallback, signal, mainBlobBinding, dataBlobBinding, hooks), progressCallback);
     }
     // Single file download
     const cacheDir = getModelsCacheDir();
@@ -549,9 +522,10 @@ export async function downloadModelFromRegistry(registryPath, registrySource, pr
     // Check if already cached
     const expectedSize = modelMetadata?.expectedSize || 0;
     const checksum = expectedChecksum || modelMetadata?.sha256Checksum || "";
-    const cachedPath = await validateCachedFile(modelPath, filename, expectedSize, checksum);
+    const cachedPath = await validateCachedFile(modelPath, filename, expectedSize, checksum, hooks);
     if (cachedPath) {
         logger.info(`✅ Using cached model: ${cachedPath}`);
+        hooks?.markCacheHit();
         if (progressCallback) {
             progressCallback({
                 type: "modelProgress",
@@ -563,9 +537,12 @@ export async function downloadModelFromRegistry(registryPath, registrySource, pr
         }
         return cachedPath;
     }
-    const blobBinding = modelMetadata ? buildBlobBinding(modelMetadata) : undefined;
+    const blobBinding = modelMetadata
+        ? buildBlobBinding(modelMetadata)
+        : undefined;
+    hooks?.markCacheMiss();
     return createManagedDownload(downloadKey, registryPath, async (signal) => {
-        await downloadSingleFileFromRegistry(registryPath, registrySource, modelPath, filename, downloadKey, expectedSize, checksum, progressCallback, signal, blobBinding);
+        await downloadSingleFileFromRegistry(registryPath, registrySource, modelPath, filename, downloadKey, expectedSize, checksum, progressCallback, signal, blobBinding, hooks);
         return modelPath;
     }, progressCallback);
 }

package/dist/server/rpc/handlers/load-model/resolve.d.ts

@@ -1,3 +1,5 @@
 import { type ModelProgressUpdate } from "../../../../schemas/index";
+import type { ResolveResult } from "./types";
 export declare function resolveModelPath(modelSrc: unknown, progressCallback?: (progress: ModelProgressUpdate) => void, seed?: boolean): Promise<string>;
+export declare function resolveModelPathWithStats(modelSrc: unknown, progressCallback?: (progress: ModelProgressUpdate) => void, seed?: boolean): Promise<ResolveResult>;
 //# sourceMappingURL=resolve.d.ts.map

package/dist/server/rpc/handlers/load-model/resolve.js

@@ -6,9 +6,11 @@ import path from "bare-path";
 import { downloadModelFromHttp } from "./http.js";
 import { downloadModelFromHyperdrive } from "./hyperdrive.js";
 import { downloadModelFromRegistry } from "./registry.js";
+import { downloadModelFromHttpWithStats, downloadModelFromHyperdriveWithStats, downloadModelFromRegistryWithStats, } from "./download-stats.js";
 import { ModelLoadFailedError, ModelNotFoundError, SeedingNotSupportedError, } from "../../../../utils/errors-server.js";
 import { validateAndJoinPath } from "../../../utils/path-security.js";
 import { getServerLogger } from "../../../../logging/index.js";
+import { modelInputToSrcSchema } from "../../../../schemas/index.js";
 const logger = getServerLogger();
 function isArchivePath(filePath) {
     const filename = path.basename(filePath).toLowerCase();
@@ -61,10 +63,34 @@ async function resolveLocalOrCachedFile(modelIdOrPath) {
         }
     }
 }
-import { modelInputToSrcSchema } from "../../../../schemas/index.js";
-export async function resolveModelPath(modelSrc, progressCallback, seed) {
-    // Extract src and validate using Zod schema transform
+function selectDownloaders(mode) {
+    if (mode === "stats") {
+        return {
+            http: downloadModelFromHttpWithStats,
+            registry: downloadModelFromRegistryWithStats,
+            hyperdrive: downloadModelFromHyperdriveWithStats,
+        };
+    }
+    return {
+        http: downloadModelFromHttp,
+        registry: downloadModelFromRegistry,
+        hyperdrive: downloadModelFromHyperdrive,
+    };
+}
+function isDownloadResult(value) {
+    return value !== null && typeof value === "object" && "path" in value;
+}
+function buildResult(pathOrResult, sourceType) {
+    if (isDownloadResult(pathOrResult)) {
+        return pathOrResult.stats
+            ? { path: pathOrResult.path, sourceType, downloadStats: pathOrResult.stats }
+            : { path: pathOrResult.path, sourceType };
+    }
+    return { path: pathOrResult, sourceType };
+}
+async function resolveModelPathCore(modelSrc, progressCallback, seed, mode) {
     const srcString = modelInputToSrcSchema.parse(modelSrc);
+    const downloaders = selectDownloaders(mode);
     // Parse hyperdrive URLs if present
     let hyperdriveKey;
     let actualModelSrc = srcString;
@@ -73,50 +99,57 @@ export async function resolveModelPath(modelSrc, progressCallback, seed) {
         hyperdriveKey = key;
         actualModelSrc = pathValue;
     }
-    // Handle registry:// URLs
+    // Registry source
     if (srcString.startsWith("registry://")) {
         const { registryPath, registrySource } = registryUrlSchema.parse(srcString);
         logger.info(`Loading from registry: ${registryPath}`);
         // Look up model metadata for checksum validation
         const modelMetadata = getModelByPath(registryPath);
         const expectedChecksum = modelMetadata?.sha256Checksum;
-        const actualPath = await downloadModelFromRegistry(registryPath, registrySource, progressCallback, expectedChecksum);
-        logger.info(`Loaded Model to ${actualPath}`);
-        return actualPath;
+        const result = await downloaders.registry(registryPath, registrySource, progressCallback, expectedChecksum);
+        logger.info(`Loaded Model to ${isDownloadResult(result) ? result.path : result}`);
+        return buildResult(result, "registry");
     }
-    let actualPath;
     // Validate seeding is only used with hyperdrive models
     if (seed && !hyperdriveKey) {
         throw new SeedingNotSupportedError();
     }
-    // Check if it's an HTTP/HTTPS URL
+    // HTTP source
     if (actualModelSrc.startsWith("http://") ||
         actualModelSrc.startsWith("https://")) {
         logger.info(`Loading from HTTP URL: ${actualModelSrc}`);
-        actualPath = await downloadModelFromHttp(actualModelSrc, progressCallback);
-        logger.info(`Loaded Model to ${actualPath}`);
+        const result = await downloaders.http(actualModelSrc, progressCallback);
+        logger.info(`Loaded Model to ${isDownloadResult(result) ? result.path : result}`);
+        return buildResult(result, "http");
     }
-    else if (hyperdriveKey) {
-        // Direct hyperdrive loading
+    // Hyperdrive source
+    if (hyperdriveKey) {
         logger.info(`Loading from hyperdrive: ${hyperdriveKey}`);
-        actualPath = await downloadModelFromHyperdrive(hyperdriveKey, actualModelSrc, seed, progressCallback);
+        const result = await downloaders.hyperdrive(hyperdriveKey, actualModelSrc, seed, progressCallback);
+        return buildResult(result, "hyperdrive");
     }
-    else if (actualModelSrc.includes("/") || actualModelSrc.includes("\\")) {
-        // Handle file paths (absolute or relative with slashes)
-        // Check if it's a local archive file
+    // Filesystem source (local files, cached files)
+    let resolvedPath;
+    if (actualModelSrc.includes("/") || actualModelSrc.includes("\\")) {
         if (isArchivePath(actualModelSrc)) {
             logger.info(`Extracting local archive: ${actualModelSrc}`);
             const archiveHash = generateShortHash(actualModelSrc);
             const extractDir = getShardedModelCacheDir(archiveHash);
-            actualPath = await extractAndValidateShardedArchive(actualModelSrc, extractDir);
+            resolvedPath = await extractAndValidateShardedArchive(actualModelSrc, extractDir);
         }
         else {
-            actualPath = actualModelSrc;
+            resolvedPath = actualModelSrc;
         }
     }
     else {
-        // Handle local files and cached files
-        actualPath = await resolveLocalOrCachedFile(actualModelSrc);
+        resolvedPath = await resolveLocalOrCachedFile(actualModelSrc);
     }
-    return actualPath;
+    return { path: resolvedPath, sourceType: "filesystem" };
+}
+export async function resolveModelPath(modelSrc, progressCallback, seed) {
+    const result = await resolveModelPathCore(modelSrc, progressCallback, seed, "base");
+    return result.path;
+}
+export async function resolveModelPathWithStats(modelSrc, progressCallback, seed) {
+    return resolveModelPathCore(modelSrc, progressCallback, seed, "stats");
 }

package/dist/server/rpc/handlers/load-model/types.d.ts

@@ -0,0 +1,29 @@
+import type { SourceType } from "../../../../schemas/index";
+export interface DownloadStats {
+    downloadTimeMs?: number;
+    totalBytesDownloaded?: number;
+    downloadSpeedBps?: number;
+    checksumValidationTimeMs?: number;
+    cacheHit?: boolean;
+}
+export interface ResolveResult {
+    path: string;
+    sourceType: SourceType;
+    downloadStats?: DownloadStats;
+}
+export interface DownloadResult {
+    path: string;
+    stats?: DownloadStats;
+}
+export interface DownloadMetricsHooks {
+    markCacheHit: () => void;
+    markCacheMiss: () => void;
+    addChecksumValidationTimeMs: (durationMs: number) => void;
+}
+export interface LoadModelProfilingMeta {
+    sourceType?: string;
+    downloadStats?: DownloadStats;
+    modelInitializationTimeMs?: number;
+    totalLoadTimeMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/server/rpc/handlers/load-model/types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/rpc/handlers/load-model-delegated.d.ts

@@ -1,3 +1,7 @@
 import type { LoadModelSrcRequest, LoadModelResponse, ModelProgressUpdate } from "../../../schemas/index";
-export declare function handleLoadModelDelegated(request: LoadModelSrcRequest, progressCallback?: (update: ModelProgressUpdate) => void): Promise<LoadModelResponse>;
+import type { DelegatedHandlerOptions } from "../profiling/index";
+export interface HandleLoadModelDelegatedOptions extends DelegatedHandlerOptions {
+    progressCallback?: (update: ModelProgressUpdate) => void;
+}
+export declare function handleLoadModelDelegated(request: LoadModelSrcRequest, options?: HandleLoadModelDelegatedOptions): Promise<LoadModelResponse>;
 //# sourceMappingURL=load-model-delegated.d.ts.map