@qvac/sdk 0.9.2 → 0.10.0

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

@@ -1,22 +1,4 @@
 import type { ModelProgressUpdate } from "../../../../schemas/index";
-import { type RegistryItem } from "../../../../models/registry/index";
-import type { DownloadMetricsHooks } from "./types";
-/**
- * Find companion ONNX data file in registry.
- * ONNX models with external data may use either .onnx_data or .onnx.data.
- */
-export declare function findOnnxCompanionDataFile(registryPath: string): RegistryItem | undefined;
-/**
- * Resolve the main ONNX registry path from a companion data registry path.
- * Supports both .onnx_data and .onnx.data naming conventions.
- */
-export declare function getPairedOnnxRegistryPath(registryPath: string): string | undefined;
-/**
- * Download a model from the QVAC Registry.
- *
- * For known models (present in models.ts), uses direct blob download which
- * skips the registry metadata sync entirely. Falls back to metadata-based
- * download for unknown models.
- */
-export declare function downloadModelFromRegistry(registryPath: string, registrySource: string, progressCallback?: (progress: ModelProgressUpdate) => void, expectedChecksum?: string, hooks?: DownloadMetricsHooks): Promise<string>;
+import type { DownloadHooks } from "./types";
+export declare function downloadModelFromRegistry(registryPath: string, registrySource: string, progressCallback?: (progress: ModelProgressUpdate) => void, expectedChecksum?: string, hooks?: DownloadHooks): Promise<string>;
 //# sourceMappingURL=registry.d.ts.map

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

@@ -1,124 +1,14 @@
 import { promises as fsPromises } from "bare-fs";
-import path from "bare-path";
-import { AbortController } from "bare-abort-controller";
-import { getModelsCacheDir, generateShortHash, detectShardedModel, getShardedModelCacheDir, getShardPath, getOnnxModelPath, measureChecksum, extractTensorsFromShards, calculatePercentage, } from "../../../utils/index.js";
+import { generateShortHash, detectShardedModel, getShardedModelCacheDir, getShardPath, extractTensorsFromShards, calculatePercentage, } from "../../../utils/index.js";
+import { getSingleFileCachePath } from "../../../utils/cache/paths.js";
 import { getModelByPath } from "../../../../models/registry/index.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 { createRegistryDownloadKey, startOrJoinDownload, applyJoinedDownloadStats, } from "./download-manager.js";
+import { buildBlobBinding, validateCachedFile, downloadSingleFileFromRegistry, } from "./registry-download-utils.js";
+import { downloadCompanionSetFromRegistry } from "./registry-companion-set.js";
+import { DownloadCancelledError, ModelNotFoundError, RegistryDownloadFailedError, } from "../../../../utils/errors-server.js";
 import { getServerLogger } from "../../../../logging/index.js";
 const logger = getServerLogger();
-const REGISTRY_STREAM_TIMEOUT_MS = 60_000;
-function buildBlobBinding(meta) {
-    return {
-        coreKey: meta.blobCoreKey,
-        blockOffset: meta.blobBlockOffset,
-        blockLength: meta.blobBlockLength,
-        byteOffset: meta.blobByteOffset,
-        byteLength: meta.expectedSize,
-    };
-}
-/**
- * Validate a cached file against expected size and checksum.
- */
-async function validateCachedFile(modelPath, modelFileName, expectedSize, expectedChecksum, hooks) {
-    try {
-        await fsPromises.access(modelPath);
-        const localStats = await fsPromises.stat(modelPath);
-        const localSize = localStats.size;
-        if (localSize === expectedSize) {
-            logger.info(`✅ Model cached with correct size: ${modelPath}`);
-            // Validate checksum if provided
-            if (expectedChecksum && expectedChecksum.length === 64) {
-                const checksum = await measureChecksum(modelPath, hooks);
-                if (checksum !== expectedChecksum) {
-                    throw new ChecksumValidationFailedError(`${modelFileName}. Expected: ${expectedChecksum}. Actual: ${checksum}. File may be corrupted`);
-                }
-            }
-            logger.info(`✅ Model already cached and validated: ${modelPath}`);
-            return modelPath;
-        }
-        // File exists but wrong size (incomplete/corrupted) - remove it
-        logger.warn(`🗑️ Removing incomplete cached file (expected ${expectedSize}, got ${localSize}): ${modelPath}`);
-        await fsPromises.unlink(modelPath);
-        return null;
-    }
-    catch (error) {
-        if (error instanceof ChecksumValidationFailedError) {
-            // Corrupted file - remove it so next download starts fresh
-            logger.warn(`🗑️ Removing corrupted cached file: ${modelPath}`);
-            await fsPromises.unlink(modelPath).catch(() => { });
-        }
-        // File doesn't exist or was cleaned up - need to download
-        return null;
-    }
-}
-/**
- * Download a single file from the registry to filesystem.
- * 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, hooks) {
-    if (signal?.aborted) {
-        throw new DownloadCancelledError();
-    }
-    const client = await getRegistryClient();
-    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: 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}`);
-    }
-    if (progressCallback) {
-        progressCallback({
-            type: "modelProgress",
-            downloaded: stats.size,
-            total: stats.size,
-            percentage: 100,
-            downloadKey,
-        });
-    }
-}
 /**
  * Find all shards for a model using path prefix query.
  */
@@ -126,7 +16,7 @@ async function findModelShards(registryPath) {
     const client = await getRegistryClient();
     const shardInfo = detectShardedModel(registryPath.split("/").pop() || "");
     if (!shardInfo.isSharded) {
-        throw new Error(`Not a sharded model path: ${registryPath}`);
+        throw new RegistryDownloadFailedError(`Not a sharded model path: ${registryPath}`);
     }
     const pathPrefix = registryPath.replace(/-\d{5}-of-\d{5}\./, ".");
     const basePath = pathPrefix.substring(0, pathPrefix.lastIndexOf("."));
@@ -198,7 +88,7 @@ async function downloadShardedFilesFromRegistry(registryPath, registrySource, ca
         }));
     }
     const shardDir = getShardedModelCacheDir(cacheKey);
-    const downloadKey = createRegistryDownloadKey(registryPath);
+    const downloadKey = createRegistryDownloadKey(registrySource, registryPath);
     logger.info(`📥 Downloading sharded model: ${shards.length} shards to ${shardDir}`);
     const overallTotal = shards.reduce((sum, s) => sum + s.size, 0);
     let overallDownloaded = 0;
@@ -275,209 +165,35 @@ async function downloadShardedFilesFromRegistry(registryPath, registrySource, ca
     }
     return getShardPath(cacheKey, firstShardFilename);
 }
-/**
- * Find companion ONNX data file in registry.
- * ONNX models with external data may use either .onnx_data or .onnx.data.
- */
-export function findOnnxCompanionDataFile(registryPath) {
-    if (!registryPath.endsWith(".onnx"))
-        return undefined;
-    return (getModelByPath(`${registryPath}_data`) ??
-        getModelByPath(`${registryPath}.data`));
-}
-/**
- * Resolve the main ONNX registry path from a companion data registry path.
- * Supports both .onnx_data and .onnx.data naming conventions.
- */
-export function getPairedOnnxRegistryPath(registryPath) {
-    if (registryPath.endsWith(".onnx_data")) {
-        return registryPath.slice(0, -"_data".length);
-    }
-    if (registryPath.endsWith(".onnx.data")) {
-        return registryPath.slice(0, -".data".length);
-    }
-    return undefined;
-}
-/**
- * Download ONNX model with companion data file from registry.
- * 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, hooks) {
-    if (signal?.aborted) {
-        throw new DownloadCancelledError();
-    }
-    const mainFilename = registryPath.split("/").pop() || registryPath;
-    const dataFilename = companionDataFile.registryPath.split("/").pop() || "";
-    const downloadKey = createRegistryDownloadKey(registryPath);
-    const mainModelMetadata = getModelByPath(registryPath);
-    const mainPath = getOnnxModelPath(cacheKey, mainFilename);
-    const dataPath = getOnnxModelPath(cacheKey, dataFilename);
-    logger.info(`📥 Downloading ONNX model with external data: ${mainFilename} + ${dataFilename}`);
-    const mainExpectedSize = mainModelMetadata?.expectedSize || 0;
-    const mainChecksum = mainModelMetadata?.sha256Checksum || "";
-    const dataExpectedSize = companionDataFile.expectedSize || 0;
-    const dataChecksum = companionDataFile.sha256Checksum || "";
-    const overallTotal = mainExpectedSize + dataExpectedSize;
-    let overallDownloaded = 0;
-    // Check if main file already cached
-    const cachedMainPath = await validateCachedFile(mainPath, mainFilename, mainExpectedSize, mainChecksum, hooks);
-    if (cachedMainPath) {
-        logger.info(`✅ Main ONNX file already cached: ${mainFilename}`);
-        overallDownloaded += mainExpectedSize;
-    }
-    else {
-        // Download main ONNX file
-        const mainProgressCallback = progressCallback
-            ? (progress) => {
-                const currentOverall = overallDownloaded + progress.downloaded;
-                progressCallback({
-                    ...progress,
-                    downloadKey,
-                    onnxInfo: {
-                        currentFile: mainFilename,
-                        fileIndex: 1,
-                        totalFiles: 2,
-                        overallDownloaded: currentOverall,
-                        overallTotal,
-                        overallPercentage: calculatePercentage(currentOverall, overallTotal),
-                    },
-                });
-            }
-            : undefined;
-        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, hooks);
-    if (cachedDataPath) {
-        logger.info(`✅ ONNX data file already cached: ${dataFilename}`);
-        overallDownloaded = overallTotal;
-    }
-    else {
-        // Download companion data file
-        const dataProgressCallback = progressCallback
-            ? (progress) => {
-                const currentOverall = overallDownloaded + progress.downloaded;
-                progressCallback({
-                    ...progress,
-                    downloadKey,
-                    onnxInfo: {
-                        currentFile: dataFilename,
-                        fileIndex: 2,
-                        totalFiles: 2,
-                        overallDownloaded: currentOverall,
-                        overallTotal,
-                        overallPercentage: calculatePercentage(currentOverall, overallTotal),
-                    },
-                });
-            }
-            : undefined;
-        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
-    if (progressCallback) {
-        progressCallback({
-            type: "modelProgress",
-            downloaded: overallTotal,
-            total: overallTotal,
-            percentage: 100,
-            downloadKey,
-            onnxInfo: {
-                currentFile: dataFilename,
-                fileIndex: 2,
-                totalFiles: 2,
-                overallDownloaded: overallTotal,
-                overallTotal,
-                overallPercentage: 100,
-            },
-        });
-    }
-    return mainPath;
-}
-/**
- * Create a managed download with abort controller support.
- */
-function createManagedDownload(downloadKey, registryPath, downloadFn, progressCallback) {
-    const abortController = new AbortController();
-    const downloadPromise = (async () => {
-        try {
-            return await downloadFn(abortController.signal);
-        }
-        finally {
-            unregisterDownload(downloadKey);
-            clearClearCacheFlag(downloadKey);
-        }
-    })();
-    const downloadEntry = {
-        key: downloadKey,
-        promise: downloadPromise,
-        abortController,
-        startTime: Date.now(),
-        type: "registry",
-        registryPath,
-        ...(progressCallback && { onProgress: progressCallback }),
-    };
-    registerDownload(downloadKey, downloadEntry);
-    return downloadPromise;
-}
-/**
- * Download a model from the QVAC Registry.
- *
- * For known models (present in models.ts), uses direct blob download which
- * skips the registry metadata sync entirely. Falls back to metadata-based
- * download for unknown models.
- */
 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 downloadKey = createRegistryDownloadKey(registrySource, registryPath);
+    hooks?.onDownloadKey?.(downloadKey);
     const filename = registryPath.split("/").pop() || registryPath;
     const shardInfo = detectShardedModel(filename);
     // Look up model metadata from our generated models.ts
     const modelMetadata = getModelByPath(registryPath);
-    // ONNX external data: check if already present in paired ONNX cache directory.
-    // Avoids redundant single-file downloads when the companion .onnx download already placed it.
-    const pairedOnnxRegistryPath = getPairedOnnxRegistryPath(registryPath);
-    if (pairedOnnxRegistryPath) {
-        const onnxRegistryPath = pairedOnnxRegistryPath;
-        const onnxCacheKey = generateShortHash(onnxRegistryPath);
-        const pairedPath = getOnnxModelPath(onnxCacheKey, filename);
-        const validated = await validateCachedFile(pairedPath, filename, modelMetadata?.expectedSize || 0, modelMetadata?.sha256Checksum, hooks);
-        if (validated) {
-            logger.info(`✅ ONNX data file found in paired cache: ${validated}`);
-            hooks?.markCacheHit();
-            return validated;
-        }
-    }
-    if (shardInfo.isSharded) {
-        const cacheKey = generateShortHash(registryPath);
-        const localShardMeta = modelMetadata?.shardMetadata;
-        // FS pre-check for known models: if all shards cached, return immediately
-        if (localShardMeta?.length) {
-            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, hooks);
-                if (!cached) {
-                    allCached = false;
-                    break;
+    const result = startOrJoinDownload(downloadKey, async (ctx) => {
+        if (shardInfo.isSharded) {
+            const cacheKey = generateShortHash(registryPath);
+            const localShardMeta = modelMetadata?.shardMetadata;
+            // FS pre-check for known models: if all shards cached, return immediately
+            if (localShardMeta?.length) {
+                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, hooks);
+                    if (!cached) {
+                        allCached = false;
+                        break;
+                    }
                 }
-            }
-            if (allCached) {
-                const firstShardFilename = localShardMeta[0].filename;
-                logger.info(`✅ All ${localShardMeta.length} shards cached`);
-                hooks?.markCacheHit();
-                if (progressCallback) {
+                if (allCached) {
+                    const firstShardFilename = localShardMeta[0].filename;
+                    logger.info(`✅ All ${localShardMeta.length} shards cached`);
+                    hooks?.markCacheHit?.();
+                    ctx.setCacheHit(true);
                     const overallTotal = localShardMeta.reduce((sum, s) => sum + s.expectedSize, 0);
-                    progressCallback({
+                    ctx.broadcastProgress({
                         type: "modelProgress",
                         downloaded: overallTotal,
                         total: overallTotal,
@@ -492,84 +208,96 @@ export async function downloadModelFromRegistry(registryPath, registrySource, pr
                             overallPercentage: 100,
                         },
                     });
+                    return getShardPath(cacheKey, firstShardFilename);
                 }
-                return getShardPath(cacheKey, firstShardFilename);
             }
-        }
-        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);
-    if (companionDataFile) {
-        const cacheKey = generateShortHash(registryPath);
-        // FS pre-check: if both files cached, return immediately
-        const mainFilename = registryPath.split("/").pop() || registryPath;
-        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, 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({
-                    type: "modelProgress",
-                    downloaded: total,
-                    total,
-                    percentage: 100,
-                    downloadKey,
-                    onnxInfo: {
-                        currentFile: dataFilename,
-                        fileIndex: 2,
-                        totalFiles: 2,
-                        overallDownloaded: total,
-                        overallTotal: total,
-                        overallPercentage: 100,
-                    },
-                });
+            hooks?.markCacheMiss?.();
+            ctx.setCacheHit(false);
+            try {
+                return await downloadShardedFilesFromRegistry(registryPath, registrySource, cacheKey, ctx.broadcastProgress, ctx.signal, localShardMeta, hooks);
+            }
+            catch (error) {
+                if (error instanceof DownloadCancelledError &&
+                    ctx.shouldClearCache()) {
+                    try {
+                        await fsPromises.rm(getShardedModelCacheDir(cacheKey), {
+                            recursive: true,
+                            force: true,
+                        });
+                    }
+                    catch (cleanupError) {
+                        logger.debug("Failed to delete shard cache dir during cleanup", {
+                            cacheKey,
+                            error: cleanupError,
+                        });
+                    }
+                }
+                throw error;
             }
-            return mainCached;
         }
-        const mainBlobBinding = modelMetadata
-            ? buildBlobBinding(modelMetadata)
-            : undefined;
-        const dataBlobBinding = companionDataFile.blobCoreKey
-            ? buildBlobBinding(companionDataFile)
-            : undefined;
-        hooks?.markCacheMiss();
-        return createManagedDownload(downloadKey, registryPath, (signal) => downloadOnnxWithDataFromRegistry(registryPath, registrySource, companionDataFile, cacheKey, progressCallback, signal, mainBlobBinding, dataBlobBinding, hooks), progressCallback);
-    }
-    // Single file download
-    const cacheDir = getModelsCacheDir();
-    const sourceHash = generateShortHash(registryPath);
-    const modelPath = path.join(cacheDir, `${sourceHash}_${filename}`);
-    // Check if already cached
-    const expectedSize = modelMetadata?.expectedSize || 0;
-    const checksum = expectedChecksum || modelMetadata?.sha256Checksum || "";
-    const cachedPath = await validateCachedFile(modelPath, filename, expectedSize, checksum, hooks);
-    if (cachedPath) {
-        logger.info(`✅ Using cached model: ${cachedPath}`);
-        hooks?.markCacheHit();
-        if (progressCallback) {
-            progressCallback({
+        // Generic companion set via generated metadata
+        if (modelMetadata?.companionSet) {
+            const companionHooks = {
+                ...hooks,
+                markCacheHit: () => {
+                    hooks?.markCacheHit?.();
+                    ctx.setCacheHit(true);
+                },
+                markCacheMiss: () => {
+                    hooks?.markCacheMiss?.();
+                    ctx.setCacheHit(false);
+                },
+            };
+            return await downloadCompanionSetFromRegistry({
+                companionSet: modelMetadata.companionSet,
+                downloadKey,
+                progressCallback: ctx.broadcastProgress,
+                signal: ctx.signal,
+                hooks: companionHooks,
+                shouldClearCache: ctx.shouldClearCache,
+            });
+        }
+        const modelPath = getSingleFileCachePath(registryPath);
+        const expectedSize = modelMetadata?.expectedSize || 0;
+        const checksum = expectedChecksum || modelMetadata?.sha256Checksum || "";
+        const cachedPath = await validateCachedFile(modelPath, filename, expectedSize, checksum, hooks);
+        if (cachedPath) {
+            logger.info(`✅ Using cached model: ${cachedPath}`);
+            hooks?.markCacheHit?.();
+            ctx.setCacheHit(true);
+            ctx.broadcastProgress({
                 type: "modelProgress",
                 downloaded: expectedSize,
                 total: expectedSize,
                 percentage: 100,
                 downloadKey,
             });
+            return cachedPath;
+        }
+        const blobBinding = modelMetadata
+            ? buildBlobBinding(modelMetadata)
+            : undefined;
+        hooks?.markCacheMiss?.();
+        ctx.setCacheHit(false);
+        try {
+            await downloadSingleFileFromRegistry(registryPath, registrySource, modelPath, filename, downloadKey, expectedSize, checksum, ctx.broadcastProgress, ctx.signal, blobBinding, hooks);
+        }
+        catch (error) {
+            if (error instanceof DownloadCancelledError &&
+                ctx.shouldClearCache()) {
+                try {
+                    await fsPromises.unlink(modelPath);
+                }
+                catch (cleanupError) {
+                    logger.debug("Failed to delete model file during cleanup", {
+                        path: modelPath,
+                        error: cleanupError,
+                    });
+                }
+            }
+            throw error;
         }
-        return cachedPath;
-    }
-    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, hooks);
         return modelPath;
     }, progressCallback);
+    return applyJoinedDownloadStats(result, hooks);
 }

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

@@ -0,0 +1,15 @@
+import type { ModelProgressUpdate, ResolveContext } from "../../../../schemas/index";
+import type { ResolveResult } from "./types";
+export interface ResolveSessionOptions {
+    progressCallback?: ((update: ModelProgressUpdate) => void) | undefined;
+    seed?: boolean | undefined;
+    profilingEnabled: boolean;
+}
+export interface ResolveSession {
+    resolvePrimaryModelPath(modelSrc: unknown): Promise<string>;
+    createResolveContext(modelSrc: string, modelType: string, modelName?: string): ResolveContext;
+    getAggregateResult(): ResolveResult | undefined;
+    cancelAll(): void;
+}
+export declare function createResolveSession(options: ResolveSessionOptions): ResolveSession;
+//# sourceMappingURL=resolve-session.d.ts.map

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

@@ -0,0 +1,61 @@
+import { resolveModelPath, resolveModelPathWithStats, } from "./resolve.js";
+import { cancelTransfer } from "./download-manager.js";
+import { mergeDownloadStats } from "./download-stats.js";
+export function createResolveSession(options) {
+    const { progressCallback, seed, profilingEnabled } = options;
+    let primaryResult;
+    const resolveResults = [];
+    const activeDownloadKeys = new Set();
+    const downloadHooks = {
+        onDownloadKey(key) {
+            activeDownloadKeys.add(key);
+        },
+    };
+    async function resolvePrimaryModelPath(modelSrc) {
+        if (profilingEnabled) {
+            const result = await resolveModelPathWithStats(modelSrc, progressCallback, seed, downloadHooks);
+            primaryResult = result;
+            resolveResults.push(result);
+            return result.path;
+        }
+        return resolveModelPath(modelSrc, progressCallback, seed, downloadHooks);
+    }
+    async function resolveForPlugin(src) {
+        if (profilingEnabled) {
+            const result = await resolveModelPathWithStats(src, progressCallback, seed, downloadHooks);
+            resolveResults.push(result);
+            return result.path;
+        }
+        return resolveModelPath(src, progressCallback, seed, downloadHooks);
+    }
+    function createResolveContext(modelSrc, modelType, modelName) {
+        return {
+            resolveModelPath: resolveForPlugin,
+            modelSrc,
+            modelType,
+            ...(modelName !== undefined && { modelName }),
+        };
+    }
+    function getAggregateResult() {
+        if (!profilingEnabled || resolveResults.length === 0)
+            return undefined;
+        const downloadStats = mergeDownloadStats(resolveResults);
+        return {
+            path: primaryResult?.path ?? resolveResults[0].path,
+            sourceType: primaryResult?.sourceType ?? resolveResults[0].sourceType,
+            ...(downloadStats !== undefined && { downloadStats }),
+        };
+    }
+    function cancelAll() {
+        for (const key of activeDownloadKeys) {
+            cancelTransfer(key);
+        }
+        activeDownloadKeys.clear();
+    }
+    return {
+        resolvePrimaryModelPath,
+        createResolveContext,
+        getAggregateResult,
+        cancelAll,
+    };
+}

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

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