@qvac/sdk 0.3.0 → 0.4.0

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

@@ -1,39 +1,36 @@
 import fs, { promises as fsPromises } from "bare-fs";
 import path from "bare-path";
-import crypto from "bare-crypto";
 import Corestore from "corestore";
 import Hyperswarm, {} from "hyperswarm";
 import Hyperdrive from "hyperdrive";
 import {} from "bare-stream";
 import { AbortController } from "bare-abort-controller";
 import { getEnv } from "../../../worker.js";
-import { getModelsCacheDir, generateShortHash } from "../../../utils/index.js";
+import { getModelsCacheDir, generateShortHash, detectShardedModel, getShardedModelCacheDir, getShardPath, checkShardCompleteness, calculateFileChecksum, } from "../../../utils/index.js";
 import { getModelBySrc } from "../../../../models/hyperdrive/index.js";
 import { getActiveDownload, registerDownload, unregisterDownload, createHyperdriveDownloadKey, shouldClearCache, clearClearCacheFlag, } from "./download-manager.js";
-function createProgressHandler(blob, progressCallback, downloadKey, initialBytes = 0) {
-    let downloadedBytes = initialBytes;
-    return (index, bytes) => {
-        if (index >= blob.blockOffset &&
-            index < blob.blockOffset + blob.blockLength) {
-            downloadedBytes += bytes;
-            if (progressCallback && downloadKey) {
-                progressCallback({
-                    type: "modelProgress",
-                    downloaded: downloadedBytes,
-                    total: blob.byteLength,
-                    percentage: blob.byteLength > 0 ? (downloadedBytes / blob.byteLength) * 100 : 0,
-                    downloadKey,
-                });
-            }
-        }
-    };
+import { getSDKConfig } from "../../../bare/registry/config-registry.js";
+import { FileNotFoundError, ChecksumValidationFailedError, DownloadCancelledError, HyperdriveDownloadFailedError, ModelLoadFailedError, NoBlobFoundError, } from "../../../../utils/errors-server.js";
+function getCorestoreDir(hyperdriveKey) {
+    return path.join(getEnv().HOME_DIR, ".qvac", "corestore", hyperdriveKey);
 }
 async function setupHyperdrive(hyperdriveKey, corestoreDir) {
     const corestore = new Corestore(corestoreDir);
     await corestore.ready();
     const drive = new Hyperdrive(corestore, Buffer.from(hyperdriveKey, "hex"));
     await drive.ready();
-    const swarm = new Hyperswarm();
+    const getRelays = () => {
+        const config = getSDKConfig();
+        const relayPublicKeys = config.swarmRelays;
+        if (!relayPublicKeys || relayPublicKeys.length === 0) {
+            return null;
+        }
+        return relayPublicKeys.map((key) => Buffer.from(key, "hex"));
+    };
+    const swarmOptions = {
+        relayThrough: getRelays,
+    };
+    const swarm = new Hyperswarm(swarmOptions);
     const doneFindingPeers = drive.findingPeers();
     swarm.on("connection", (connection) => {
         console.log(`🤝 Connected to peer for hyperdrive download`);
@@ -103,7 +100,7 @@ async function findFileInHyperdrive(drive, modelFileName) {
     const filesInfo = availableFiles.length > 0
         ? `Available files: ${availableFiles.join(", ")}`
         : "Could not list available files";
-    throw new Error(`File ${modelFileName} not found in hyperdrive. ${filesInfo}`);
+    throw new FileNotFoundError(`${modelFileName} in hyperdrive. ${filesInfo}`);
 }
 async function checkFileDownloaded(drive, entry) {
     const blobs = await drive.getBlobs();
@@ -143,39 +140,6 @@ async function validateFileExistence(drive, file) {
         totalBytes,
     };
 }
-async function validateFileChecksum(filePath, expectedChecksum) {
-    console.log(`🔍 Validating SHA256 checksum...`);
-    return new Promise((resolve) => {
-        try {
-            const hash = crypto.createHash("sha256");
-            const stream = fs.createReadStream(filePath);
-            stream.on("data", (chunk) => {
-                hash.update(chunk);
-            });
-            stream.on("end", () => {
-                const actualChecksum = hash.digest("hex");
-                console.log(`Expected: ${String(expectedChecksum)}`);
-                console.log(`Actual:   ${String(actualChecksum)}`);
-                const isValid = actualChecksum === expectedChecksum;
-                if (isValid) {
-                    console.log(`✅ Checksum validation passed!`);
-                }
-                else {
-                    console.log(`❌ Checksum validation FAILED! File may be corrupted.`);
-                }
-                resolve(isValid);
-            });
-            stream.on("error", (error) => {
-                console.error(`❌ Error validating checksum: ${error.message}`);
-                resolve(false);
-            });
-        }
-        catch (error) {
-            console.error(`❌ Error validating checksum: ${error instanceof Error ? error.message : String(error)}`);
-            resolve(false);
-        }
-    });
-}
 async function validateCachedFile(modelPath, modelFileName, expectedSize, expectedChecksum) {
     try {
         await fsPromises.access(modelPath);
@@ -187,18 +151,13 @@ async function validateCachedFile(modelPath, modelFileName, expectedSize, expect
             console.log(`✅ Model cached with correct size: ${modelPath}`);
             // Always validate checksum if provided, even when size matches
             if (expectedChecksum && expectedChecksum.length === 64) {
-                const isValid = await validateFileChecksum(modelPath, expectedChecksum);
-                if (isValid) {
-                    return modelPath;
+                const checksum = await calculateFileChecksum(modelPath);
+                if (checksum !== expectedChecksum) {
+                    throw new ChecksumValidationFailedError(`${modelFileName}. Expected: ${expectedChecksum}. Actual: ${checksum}. File may be corrupted`);
                 }
-                else {
-                    throw new Error(`File ${modelFileName} is fully downloaded but checksum validation failed. Expected: ${expectedChecksum}. File may be corrupted.`);
-                }
-            }
-            else {
-                console.log(`✅ Model already cached and size validated: ${modelPath}`);
-                return modelPath;
             }
+            console.log(`✅ Model already cached and size validated: ${modelPath}`);
+            return modelPath;
         }
         // File exists but incomplete - will be overwritten during download
         // Resume state will be determined by corestore blocks, not file size
@@ -209,65 +168,47 @@ async function validateCachedFile(modelPath, modelFileName, expectedSize, expect
         return null;
     }
 }
-async function performHyperdriveDownload(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, progressCallback, seed, signal) {
+async function downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, expectedChecksum, progressCallback, seed, signal) {
     // Check if already aborted
     if (signal?.aborted) {
-        throw new Error("Download cancelled");
+        throw new DownloadCancelledError();
     }
     console.log(`Downloading model from hyperdrive ${hyperdriveKey} to ${modelPath}`);
     const setup = await setupHyperdrive(hyperdriveKey, corestoreDir);
-    // Set up abort handler
-    let readStream;
-    let writeStream;
     const cleanup = () => {
         console.log("🛑 Aborting hyperdrive download...");
         setup.swarm.suspended = true;
         setup.swarm.suspend().catch(() => {
             // Ignore errors during emergency suspend
         });
-        // Destroy streams if they exist
-        if (readStream) {
-            readStream.destroy();
-        }
-        if (writeStream) {
-            writeStream.destroy();
-        }
     };
     signal?.addEventListener("abort", cleanup);
-    let downloadHandler;
     try {
-        const { entry, blobs, targetPath, blocksDownloaded, totalBlocks, totalBytes, } = await validateFileExistence(setup.drive, modelFileName);
-        const blob = entry?.value?.blob;
-        if (!blob) {
-            throw new Error(`No blob found for ${modelFileName}`);
-        }
-        // Calculate already downloaded bytes for resuming
-        const bytesPerBlock = totalBlocks > 0 ? totalBytes / totalBlocks : 0;
-        const initialBytes = Math.floor(blocksDownloaded * bytesPerBlock);
-        // Track only downloads for blocks within our file's blob range
-        downloadHandler = createProgressHandler(blob, progressCallback, downloadKey, initialBytes);
-        blobs.core.on("download", downloadHandler);
-        // Check if aborted before starting streams
-        if (signal?.aborted) {
-            throw new Error("Download cancelled");
-        }
-        // Trigger download for this file (hyperdrive will only download missing blocks)
-        setup.drive.download(targetPath);
-        readStream = setup.drive.createReadStream(targetPath);
-        writeStream = fs.createWriteStream(modelPath);
-        // Pipe the streams
-        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);
-            // Also reject on abort
-            signal?.addEventListener("abort", () => {
-                reject(new Error("Download cancelled"));
-            }, { once: true });
-        });
+        const progressContext = progressCallback
+            ? {
+                downloadKey,
+                callback: progressCallback,
+            }
+            : undefined;
+        await downloadAndValidateFile(setup.drive, modelFileName, modelPath, 0, // Size will be determined from drive
+        expectedChecksum, progressContext, signal);
         console.log(`✅ Model downloaded successfully to ${modelPath}`);
+        // Send final 100% progress update
+        if (progressCallback) {
+            try {
+                const stats = await fsPromises.stat(modelPath);
+                progressCallback({
+                    type: "modelProgress",
+                    downloaded: stats.size,
+                    total: stats.size,
+                    percentage: 100,
+                    downloadKey,
+                });
+            }
+            catch {
+                // Ignore stat errors
+            }
+        }
         // Delete corestore directory after successful download (only when not seeding, to save space)
         if (!seed) {
             await deleteCorestoreDirectory(setup.corestoreDir);
@@ -279,19 +220,10 @@ async function performHyperdriveDownload(modelPath, modelFileName, hyperdriveKey
         if (error instanceof Error && error.message === "Download cancelled") {
             throw error;
         }
-        throw new Error(`Download failed for ${modelFileName} from hyperdrive: ${hyperdriveKey}`);
+        throw new HyperdriveDownloadFailedError(`Download failed for ${modelFileName} from hyperdrive: ${hyperdriveKey}`, error);
     }
     finally {
         signal?.removeEventListener("abort", cleanup);
-        if (downloadHandler) {
-            try {
-                const { blobs } = await validateFileExistence(setup.drive, modelFileName);
-                blobs.core.off("download", downloadHandler);
-            }
-            catch {
-                // If we can't get blobs, setup is already closed
-            }
-        }
         if (!seed) {
             await cleanupHyperdrive(setup);
         }
@@ -308,56 +240,110 @@ async function performHyperdriveDownload(modelPath, modelFileName, hyperdriveKey
         clearClearCacheFlag(downloadKey);
     }
 }
-export async function downloadModelFromHyperdrive(hyperdriveKey, modelFileName, seed, progressCallback, expectedChecksum) {
-    const downloadKey = createHyperdriveDownloadKey(hyperdriveKey, modelFileName);
-    // Check if already downloading
-    const existing = getActiveDownload(downloadKey);
-    if (existing) {
-        return existing.promise;
+async function downloadAndValidateFile(drive, sourceFileName, targetFilePath, expectedSize, expectedChecksum, progressContext, signal) {
+    const { entry, blobs, targetPath, blocksDownloaded, totalBlocks, totalBytes, } = await validateFileExistence(drive, sourceFileName);
+    const blob = entry?.value?.blob;
+    if (!blob) {
+        throw new NoBlobFoundError(sourceFileName);
     }
-    const corestoreDir = path.join(getEnv().HOME_DIR, ".qvac", "corestore", hyperdriveKey);
-    const cacheDir = getModelsCacheDir();
-    const sourceHash = generateShortHash(`${hyperdriveKey}/${modelFileName}`);
-    const modelPath = path.join(cacheDir, `${sourceHash}_${modelFileName}`);
-    // Get model definition to get expected size (if it's a known model)
-    const model = getModelBySrc(modelFileName, hyperdriveKey);
-    // First, check if we already have a valid cached file (only if we have model metadata)
-    if (model) {
-        const cachedPath = await validateCachedFile(modelPath, modelFileName, model.expectedSize, expectedChecksum || model.sha256Checksum);
-        if (cachedPath) {
-            // Delete any leftover corestore directory from previous runs (only when not seeding)
-            if (!seed) {
-                await deleteCorestoreDirectory(corestoreDir);
+    // Use actual file size from drive if expectedSize is 0
+    const fileSizeToValidate = expectedSize || totalBytes;
+    // Setup progress tracking
+    let downloadedBytes = 0;
+    const bytesPerBlock = totalBlocks > 0 ? totalBytes / totalBlocks : 0;
+    const initialBytes = Math.floor(blocksDownloaded * bytesPerBlock);
+    downloadedBytes = initialBytes;
+    const progressHandler = (index, bytes) => {
+        if (index >= blob.blockOffset &&
+            index < blob.blockOffset + blob.blockLength) {
+            downloadedBytes += bytes;
+            const cappedDownloaded = Math.min(downloadedBytes, totalBytes);
+            if (progressContext) {
+                const baseProgress = {
+                    type: "modelProgress",
+                    downloaded: cappedDownloaded,
+                    total: totalBytes,
+                    percentage: totalBytes > 0 ? (cappedDownloaded / totalBytes) * 100 : 0,
+                    downloadKey: progressContext.downloadKey,
+                };
+                if (progressContext.shardInfo) {
+                    const currentOverall = progressContext.shardInfo.overallDownloaded + cappedDownloaded;
+                    progressContext.callback({
+                        ...baseProgress,
+                        shardInfo: {
+                            currentShard: progressContext.shardInfo.currentShard,
+                            totalShards: progressContext.shardInfo.totalShards,
+                            shardName: progressContext.shardInfo.shardName,
+                            overallDownloaded: currentOverall,
+                            overallTotal: progressContext.shardInfo.overallTotal,
+                            overallPercentage: progressContext.shardInfo.overallTotal > 0
+                                ? (currentOverall / progressContext.shardInfo.overallTotal) *
+                                    100
+                                : 0,
+                        },
+                    });
+                }
+                else {
+                    progressContext.callback(baseProgress);
+                }
             }
-            return cachedPath;
         }
+    };
+    blobs.core.on("download", progressHandler);
+    let readStream;
+    let writeStream;
+    try {
+        // Download blocks and stream to file
+        drive.download(targetPath);
+        readStream = drive.createReadStream(targetPath);
+        writeStream = fs.createWriteStream(targetFilePath);
+        readStream.pipe(writeStream);
+        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 });
+        });
+        blobs.core.off("download", progressHandler);
+        // Validate file size
+        const stats = await fsPromises.stat(targetFilePath);
+        if (stats.size !== fileSizeToValidate) {
+            throw new ChecksumValidationFailedError(`${path.basename(targetFilePath)}. File size mismatch: expected ${fileSizeToValidate}, got ${stats.size}`);
+        }
+        // Validate checksum
+        if (expectedChecksum && expectedChecksum.length === 64) {
+            const checksum = await calculateFileChecksum(targetFilePath);
+            if (checksum !== expectedChecksum) {
+                await fsPromises.unlink(targetFilePath);
+                throw new ChecksumValidationFailedError(`${path.basename(targetFilePath)}. Expected: ${expectedChecksum}. Actual: ${checksum}`);
+            }
+        }
+        else if (!expectedChecksum) {
+            console.log(`⚠️  No checksum available for validation`);
+        }
+    }
+    catch (error) {
+        if (readStream) {
+            readStream.destroy();
+        }
+        if (writeStream) {
+            writeStream.destroy();
+        }
+        blobs.core.off("download", progressHandler);
+        throw error;
     }
-    // Create managed download with AbortController
+}
+function createManagedDownload(downloadKey, hyperdriveKey, modelFileName, downloadFn, progressCallback) {
     const abortController = new AbortController();
     const downloadPromise = (async () => {
         try {
-            // Download the file from hyperdrive
-            await performHyperdriveDownload(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, progressCallback, seed, abortController.signal);
-            // Validate checksum using provided checksum or model's checksum (if available)
-            const checksumToValidate = expectedChecksum || model?.sha256Checksum;
-            if (checksumToValidate && checksumToValidate.length === 64) {
-                const isValid = await validateFileChecksum(modelPath, checksumToValidate);
-                if (!isValid) {
-                    await fsPromises.unlink(modelPath);
-                    throw new Error(`Checksum validation failed for ${modelFileName}`);
-                }
-            }
-            else {
-                console.log(`⚠️  No valid checksum available for validation`);
-            }
-            return modelPath;
+            return await downloadFn(abortController.signal);
         }
         finally {
-            // Cleanup from download manager
             unregisterDownload(downloadKey);
+            clearClearCacheFlag(downloadKey);
         }
     })();
-    // Register download
     const downloadEntry = {
         key: downloadKey,
         promise: downloadPromise,
@@ -371,3 +357,197 @@ export async function downloadModelFromHyperdrive(hyperdriveKey, modelFileName,
     registerDownload(downloadKey, downloadEntry);
     return downloadPromise;
 }
+async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileName, shardMetadata, progressCallback, seed, signal) {
+    if (signal?.aborted) {
+        throw new DownloadCancelledError();
+    }
+    const shardInfo = detectShardedModel(firstShardFileName);
+    if (!shardInfo.isSharded || !shardInfo.totalShards) {
+        throw new ModelLoadFailedError(`Not a sharded model: ${firstShardFileName}`);
+    }
+    const shardDir = getShardedModelCacheDir(hyperdriveKey);
+    const allFiles = shardMetadata.map((s) => s.filename);
+    const numberedShardCount = shardInfo.totalShards;
+    console.log(`Downloading sharded model with ${numberedShardCount} numbered shards + ${allFiles.length - numberedShardCount} companion files to ${shardDir}`);
+    // Check which files need to be downloaded
+    const invalidIndices = await checkShardCompleteness(hyperdriveKey, allFiles, shardMetadata);
+    if (invalidIndices.length === 0) {
+        console.log(`✅ All ${allFiles.length} files already downloaded and validated`);
+        if (progressCallback) {
+            const overallTotal = shardMetadata.reduce((sum, shard) => sum + shard.expectedSize, 0);
+            const lastFile = allFiles[allFiles.length - 1];
+            progressCallback({
+                type: "modelProgress",
+                downloaded: overallTotal,
+                total: overallTotal,
+                percentage: 100,
+                downloadKey: createHyperdriveDownloadKey(hyperdriveKey, firstShardFileName),
+                shardInfo: {
+                    currentShard: allFiles.length,
+                    totalShards: allFiles.length,
+                    shardName: lastFile,
+                    overallDownloaded: overallTotal,
+                    overallTotal,
+                    overallPercentage: 100,
+                },
+            });
+        }
+        return getShardPath(hyperdriveKey, allFiles[0]);
+    }
+    console.log(`📥 Need to download ${invalidIndices.length} of ${allFiles.length} files`);
+    // Setup hyperdrive once for all shards
+    const corestoreDir = getCorestoreDir(hyperdriveKey);
+    const setup = await setupHyperdrive(hyperdriveKey, corestoreDir);
+    const cleanup = () => {
+        console.log("🛑 Aborting sharded hyperdrive download...");
+        setup.swarm.suspended = true;
+        setup.swarm.suspend().catch(() => {
+            // Ignore errors during emergency suspend
+        });
+    };
+    signal?.addEventListener("abort", cleanup);
+    try {
+        // Calculate overall progress
+        const overallTotal = shardMetadata.reduce((sum, shard) => sum + shard.expectedSize, 0);
+        let overallDownloaded = 0;
+        // Download each file sequentially
+        for (let i = 0; i < allFiles.length; i++) {
+            if (signal?.aborted) {
+                throw new DownloadCancelledError();
+            }
+            const file = allFiles[i];
+            const fileMeta = shardMetadata[i];
+            const filePath = getShardPath(hyperdriveKey, file);
+            // Skip if already valid
+            if (!invalidIndices.includes(i)) {
+                console.log(`✅ File ${i + 1}/${allFiles.length} already valid: ${file}`);
+                overallDownloaded += fileMeta.expectedSize;
+                // Report progress for skipped files
+                if (progressCallback) {
+                    progressCallback({
+                        type: "modelProgress",
+                        downloaded: fileMeta.expectedSize,
+                        total: fileMeta.expectedSize,
+                        percentage: 100,
+                        downloadKey: createHyperdriveDownloadKey(hyperdriveKey, firstShardFileName),
+                        shardInfo: {
+                            currentShard: i + 1,
+                            totalShards: allFiles.length,
+                            shardName: file,
+                            overallDownloaded,
+                            overallTotal,
+                            overallPercentage: overallTotal > 0 ? (overallDownloaded / overallTotal) * 100 : 0,
+                        },
+                    });
+                }
+                continue;
+            }
+            console.log(`📥 Downloading file ${i + 1}/${allFiles.length}: ${file}`);
+            const progressContext = progressCallback
+                ? {
+                    downloadKey: createHyperdriveDownloadKey(hyperdriveKey, firstShardFileName),
+                    callback: progressCallback,
+                    shardInfo: {
+                        currentShard: i + 1,
+                        totalShards: allFiles.length,
+                        shardName: file,
+                        overallDownloaded,
+                        overallTotal,
+                    },
+                }
+                : undefined;
+            await downloadAndValidateFile(setup.drive, file, filePath, fileMeta.expectedSize, fileMeta.sha256Checksum, progressContext, signal);
+            if (signal?.aborted) {
+                throw new DownloadCancelledError();
+            }
+            console.log(`✅ File ${i + 1}/${allFiles.length} downloaded and validated`);
+            overallDownloaded += fileMeta.expectedSize;
+        }
+        if (progressCallback && overallDownloaded === overallTotal) {
+            const lastFile = allFiles[allFiles.length - 1];
+            progressCallback({
+                type: "modelProgress",
+                downloaded: overallTotal,
+                total: overallTotal,
+                percentage: 100,
+                downloadKey: createHyperdriveDownloadKey(hyperdriveKey, firstShardFileName),
+                shardInfo: {
+                    currentShard: allFiles.length,
+                    totalShards: allFiles.length,
+                    shardName: lastFile,
+                    overallDownloaded,
+                    overallTotal,
+                    overallPercentage: 100,
+                },
+            });
+        }
+        // Delete corestore directory after successful download (only when not seeding)
+        if (!seed) {
+            await deleteCorestoreDirectory(corestoreDir);
+        }
+    }
+    catch (error) {
+        console.error("❌ Error during sharded hyperdrive download:", error instanceof Error ? error.message : String(error));
+        // Preserve cancellation errors
+        if (error instanceof Error && error.message === "Download cancelled") {
+            throw error;
+        }
+        throw new HyperdriveDownloadFailedError(`Sharded download failed for ${firstShardFileName} from hyperdrive: ${hyperdriveKey}`, error);
+    }
+    finally {
+        signal?.removeEventListener("abort", cleanup);
+        if (!seed) {
+            await cleanupHyperdrive(setup);
+        }
+        // Only delete corestore and partial files if user explicitly requested clearCache
+        const downloadKey = createHyperdriveDownloadKey(hyperdriveKey, firstShardFileName);
+        if (signal?.aborted && shouldClearCache(downloadKey)) {
+            await deleteCorestoreDirectory(corestoreDir);
+        }
+        clearClearCacheFlag(downloadKey);
+    }
+    return getShardPath(hyperdriveKey, allFiles[0]);
+}
+export async function downloadModelFromHyperdrive(hyperdriveKey, modelFileName, seed, progressCallback, expectedChecksum) {
+    const downloadKey = createHyperdriveDownloadKey(hyperdriveKey, modelFileName);
+    // Check if already downloading
+    const existing = getActiveDownload(downloadKey);
+    if (existing) {
+        return existing.promise;
+    }
+    const shardInfo = detectShardedModel(modelFileName);
+    const model = getModelBySrc(modelFileName, hyperdriveKey);
+    if (shardInfo.isSharded && model?.shardMetadata) {
+        return createManagedDownload(downloadKey, hyperdriveKey, modelFileName, (signal) => downloadShardedFilesToFilesystem(hyperdriveKey, modelFileName, model.shardMetadata, progressCallback, seed, signal), progressCallback);
+    }
+    // Non-sharded model download
+    const corestoreDir = getCorestoreDir(hyperdriveKey);
+    const cacheDir = getModelsCacheDir();
+    const sourceHash = generateShortHash(`${hyperdriveKey}/${modelFileName}`);
+    const modelPath = path.join(cacheDir, `${sourceHash}_${modelFileName}`);
+    // First, check if we already have a valid cached file (only if we have model metadata)
+    if (model) {
+        const cachedPath = await validateCachedFile(modelPath, modelFileName, model.expectedSize, expectedChecksum || model.sha256Checksum);
+        if (cachedPath) {
+            if (progressCallback) {
+                progressCallback({
+                    type: "modelProgress",
+                    downloaded: model.expectedSize,
+                    total: model.expectedSize,
+                    percentage: 100,
+                    downloadKey,
+                });
+            }
+            // Delete any leftover corestore directory from previous runs (only when not seeding)
+            if (!seed) {
+                await deleteCorestoreDirectory(corestoreDir);
+            }
+            return cachedPath;
+        }
+    }
+    return createManagedDownload(downloadKey, hyperdriveKey, modelFileName, async (signal) => {
+        const checksumToValidate = expectedChecksum || model?.sha256Checksum || "";
+        await downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, checksumToValidate, progressCallback, seed, signal);
+        return modelPath;
+    }, progressCallback);
+}

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

@@ -1,3 +1,3 @@
-export { handleLoadModel } from "../load-model";
+export { handleLoadModel } from "../load-model.js";
 export { downloadModelFromHyperdrive } from "./hyperdrive.js";
 export { resolveModelPath } from "./resolve.js";

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

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

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

@@ -5,6 +5,7 @@ import { promises as fsPromises } from "bare-fs";
 import path from "bare-path";
 import { downloadModelFromHttp } from "./http.js";
 import { downloadModelFromHyperdrive } from "./hyperdrive.js";
+import { ModelLoadFailedError, ModelNotFoundError, SeedingNotSupportedError, } from "../../../../utils/errors-server.js";
 /**
  * Resolves a local file path or cached file
  */
@@ -12,7 +13,7 @@ async function resolveLocalOrCachedFile(modelIdOrPath) {
     // Check if it's a hex string (arbitrary hyperdrive key)
     const isHexString = /^[0-9a-fA-F]{64}$/.test(modelIdOrPath);
     if (isHexString) {
-        throw new Error(`Direct hyperdrive keys not supported. Use hyperdriveKey parameter instead. Example: loadModel("model.gguf", "${modelIdOrPath}")`);
+        throw new ModelLoadFailedError(`Direct hyperdrive keys not supported. Use hyperdriveKey parameter instead. Example: loadModel("model.gguf", "${modelIdOrPath}")`);
     }
     // Check if it's a cached file or local file
     const cacheDir = getModelsCacheDir();
@@ -32,23 +33,26 @@ async function resolveLocalOrCachedFile(modelIdOrPath) {
         catch {
             // Invalid model ID - provide helpful error
             const availableModels = models.map((m) => m.modelId);
-            throw new Error(`Invalid model ID: "${modelIdOrPath}". Available models: ${availableModels.join(", ")}`);
+            throw new ModelNotFoundError(`${modelIdOrPath}". Available models: ${availableModels.join(", ")}`);
         }
     }
 }
+import { modelInputToSrcSchema } from "../../../../schemas/index.js";
 export async function resolveModelPath(modelSrc, progressCallback, seed) {
+    // Extract src and validate using Zod schema transform
+    const srcString = modelInputToSrcSchema.parse(modelSrc);
     // Parse hyperdrive URLs if present
     let hyperdriveKey;
-    let actualModelSrc = modelSrc;
-    if (modelSrc.startsWith("pear://")) {
-        const { key, path } = hyperdriveUrlSchema.parse(modelSrc);
+    let actualModelSrc = srcString;
+    if (srcString.startsWith("pear://")) {
+        const { key, path } = hyperdriveUrlSchema.parse(srcString);
         hyperdriveKey = key;
         actualModelSrc = path;
     }
     let actualPath;
     // Validate seeding is only used with hyperdrive models
     if (seed && !hyperdriveKey) {
-        throw new Error("Seeding is only supported for hyperdrive models");
+        throw new SeedingNotSupportedError();
     }
     // Check if it's an HTTP/HTTPS URL
     if (actualModelSrc.startsWith("http://") ||