@qvac/sdk 0.7.1 → 0.8.0

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

@@ -1,112 +1,135 @@
-import { normalizeModelType, ModelType } from "../../../../schemas/index.js";
-import { hyperdriveUrlSchema } from "../../../../schemas/load-model.js";
+import { normalizeModelType, PROFILING_KEY, OPERATION_EVENT_KEY, } from "../../../../schemas/index.js";
 import { loadModel } from "../../../bare/ops/load-model.js";
-import { resolveModelPath } from "./resolve.js";
+import { resolveModelPath, resolveModelPathWithStats, } from "./resolve.js";
+import { nowMs, generateProfileId } from "../../../../profiling/clock.js";
 import { getModelEntry, updateModelConfig, } from "../../../bare/registry/model-registry.js";
-import { generateShortHash, transformConfigForReload } from "../../../utils/index.js";
-import { ConfigReloadNotSupportedError, ModelTypeMismatchError, ModelIsDelegatedError, ModelNotFoundError, } from "../../../../utils/errors-server.js";
+import { generateShortHash, canonicalConfigString, transformConfigForReload, } from "../../../utils/index.js";
+import { ConfigReloadNotSupportedError, ModelTypeMismatchError, ModelIsDelegatedError, ModelNotFoundError, ModelLoadFailedError, PluginLoadConfigValidationFailedError, PluginNotFoundError, } from "../../../../utils/errors-server.js";
 import { getServerLogger } from "../../../../logging/index.js";
-import { OCR_CRAFT_DETECTOR } from "../../../../models/registry/index.js";
 import { getPlugin } from "../../../plugins/index.js";
 const logger = getServerLogger();
-const OCR_DETECTOR_FILENAME = "detector_craft.onnx";
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
 export async function handleLoadModel(request, progressCallback) {
-    // Handle reload config
     if (isReloadConfigRequest(request)) {
         return handleConfigReload(request);
     }
-    // Handle load new model from source
-    const { modelSrc, modelName, seed, projectionModelSrc, vadModelSrc } = request;
+    const { modelSrc, modelName, seed } = request;
     const canonicalModelType = normalizeModelType(request.modelType);
-    const srcVocabSrc = canonicalModelType === ModelType.nmtcppTranslation
-        ? request.srcVocabSrc
-        : undefined;
-    const dstVocabSrc = canonicalModelType === ModelType.nmtcppTranslation
-        ? request.dstVocabSrc
-        : undefined;
-    const detectorModelSrc = canonicalModelType === ModelType.onnxOcr
-        ? request.detectorModelSrc
-        : undefined;
+    const profilingMeta = request[PROFILING_KEY];
+    const profilingEnabled = profilingMeta?.enabled !== false && !!profilingMeta;
     try {
-        const modelPath = await resolveModelPath(modelSrc, progressCallback, seed);
-        let projectionModelPath;
-        if (projectionModelSrc) {
-            projectionModelPath = await resolveModelPath(projectionModelSrc, progressCallback, seed);
+        const plugin = getPlugin(canonicalModelType);
+        if (!plugin) {
+            throw new PluginNotFoundError(canonicalModelType);
         }
-        let vadModelPath;
-        if (vadModelSrc) {
-            vadModelPath = await resolveModelPath(vadModelSrc, progressCallback, seed);
+        let resolvedModelConfig = (request.modelConfig ?? {});
+        const parseResult = plugin.loadConfigSchema.safeParse(resolvedModelConfig);
+        if (!parseResult.success) {
+            const details = parseResult.error.issues
+                .map((i) => `${String(i.path.join("."))}: ${i.message}`)
+                .join(", ");
+            throw new PluginLoadConfigValidationFailedError(canonicalModelType, details);
         }
-        // For OCR models: use provided detectorModelSrc or auto-derive
-        let detectorModelPath;
-        if (canonicalModelType === ModelType.onnxOcr) {
-            if (detectorModelSrc) {
-                detectorModelPath = await resolveModelPath(detectorModelSrc, progressCallback, seed);
-            }
-            else if (modelSrc.startsWith("pear://")) {
-                const { key } = hyperdriveUrlSchema.parse(modelSrc);
-                const derivedDetectorSrc = `pear://${key}/${OCR_DETECTOR_FILENAME}`;
-                detectorModelPath = await resolveModelPath(derivedDetectorSrc, progressCallback, seed);
-            }
-            else if (modelSrc.startsWith("registry://")) {
-                detectorModelPath = await resolveModelPath(OCR_CRAFT_DETECTOR, progressCallback, seed);
-            }
+        resolvedModelConfig = parseResult.data;
+        const totalLoadStart = profilingEnabled ? nowMs() : 0;
+        let resolveResult;
+        let resolvedModelPath;
+        if (profilingEnabled) {
+            resolveResult = await resolveModelPathWithStats(modelSrc, progressCallback, seed);
+            resolvedModelPath = resolveResult.path;
         }
-        // For Bergamot models, resolve vocabulary sources to local paths
-        if (canonicalModelType === ModelType.nmtcppTranslation &&
-            request.modelConfig) {
-            const nmtConfig = request.modelConfig;
-            if (nmtConfig.engine === "Bergamot") {
-                let resolvedSrcVocabSrc = srcVocabSrc;
-                let resolvedDstVocabSrc = dstVocabSrc;
-                if (!srcVocabSrc || !dstVocabSrc) {
-                    const derivedVocabSrcs = modelSrc.startsWith("pear://")
-                        ? deriveBergamotVocabSources(modelSrc)
-                        : modelSrc.startsWith("registry://")
-                            ? deriveBergamotRegistryVocabSources(modelSrc)
-                            : null;
-                    if (derivedVocabSrcs) {
-                        resolvedSrcVocabSrc = srcVocabSrc ?? derivedVocabSrcs.srcVocabSrc;
-                        resolvedDstVocabSrc = dstVocabSrc ?? derivedVocabSrcs.dstVocabSrc;
-                    }
-                }
-                if (resolvedSrcVocabSrc) {
-                    nmtConfig.srcVocabPath = await resolveModelPath(resolvedSrcVocabSrc, progressCallback, seed);
-                }
-                if (resolvedDstVocabSrc) {
-                    nmtConfig.dstVocabPath = await resolveModelPath(resolvedDstVocabSrc, progressCallback, seed);
-                }
-            }
+        else {
+            resolvedModelPath = await resolveModelPath(modelSrc, progressCallback, seed);
         }
-        // Use plugin's resolveConfig hook if available to resolve model sources
-        let resolvedModelConfig = request.modelConfig;
-        const plugin = getPlugin(canonicalModelType);
-        if (plugin?.resolveConfig && resolvedModelConfig) {
-            const resolve = (src) => resolveModelPath(src, progressCallback, seed);
-            resolvedModelConfig = await plugin.resolveConfig(resolvedModelConfig, resolve);
+        let pluginArtifacts = {};
+        if (plugin.resolveConfig) {
+            const ctx = {
+                resolveModelPath: (src) => resolveModelPath(src, progressCallback, seed),
+                modelSrc,
+                modelType: canonicalModelType,
+                ...(modelName !== undefined && { modelName }),
+            };
+            const result = await plugin.resolveConfig(resolvedModelConfig, ctx);
+            resolvedModelConfig = result.config;
+            if (result.artifacts) {
+                pluginArtifacts = result.artifacts;
+            }
         }
-        // Generate hash-based modelId from modelConfig (includes all sources for TTS)
-        const configStr = JSON.stringify(request.modelConfig, Object.keys(request.modelConfig).sort());
+        const configStr = canonicalConfigString(request.modelConfig);
         const modelHashInput = `${request.modelType}:${modelSrc}:${configStr}`;
         const modelId = generateShortHash(modelHashInput);
-        const loadModelOptions = {
-            ...request,
-            modelConfig: resolvedModelConfig,
-        };
-        await loadModel({
+        if ("modelPath" in pluginArtifacts) {
+            logger.warn("Plugin returned 'modelPath' artifact which was overridden by core");
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { modelPath: _, ...artifacts } = pluginArtifacts;
+        if (!resolvedModelPath) {
+            throw new ModelLoadFailedError("modelPath resolution failed");
+        }
+        const loadResult = await loadModel({
             modelId,
-            modelPath,
-            options: loadModelOptions,
-            projectionModelPath,
-            vadModelPath,
-            detectorModelPath,
+            modelPath: resolvedModelPath,
+            options: {
+                ...request,
+                modelType: canonicalModelType,
+                modelConfig: resolvedModelConfig,
+            },
+            artifacts: Object.keys(artifacts).length > 0 ? artifacts : undefined,
             modelName,
-        });
-        return {
+        }, profilingEnabled ? { collectTiming: true } : undefined);
+        const response = {
             type: "loadModel",
             success: true,
             modelId,
         };
+        if (profilingEnabled) {
+            const totalLoadTimeMs = nowMs() - totalLoadStart;
+            const profileId = profilingMeta?.id ?? generateProfileId();
+            const gauges = {
+                totalLoadTime: totalLoadTimeMs,
+            };
+            if (loadResult.timing?.modelInitializationTimeMs !== undefined) {
+                gauges["modelInitializationTime"] =
+                    loadResult.timing.modelInitializationTimeMs;
+            }
+            if (resolveResult?.downloadStats) {
+                const ds = resolveResult.downloadStats;
+                if (ds.downloadTimeMs !== undefined) {
+                    gauges["downloadTime"] = ds.downloadTimeMs;
+                }
+                if (ds.totalBytesDownloaded !== undefined) {
+                    gauges["totalBytesDownloaded"] = ds.totalBytesDownloaded;
+                }
+                if (ds.downloadSpeedBps !== undefined) {
+                    gauges["downloadSpeedBps"] = ds.downloadSpeedBps;
+                }
+                if (ds.checksumValidationTimeMs !== undefined) {
+                    gauges["checksumValidationTime"] = ds.checksumValidationTimeMs;
+                }
+            }
+            const tags = {};
+            if (canonicalModelType) {
+                tags["modelType"] = canonicalModelType;
+            }
+            if (resolveResult?.sourceType) {
+                tags["sourceType"] = resolveResult.sourceType;
+            }
+            if (resolveResult?.downloadStats?.cacheHit !== undefined) {
+                tags["cacheHit"] = resolveResult.downloadStats.cacheHit ? "true" : "false";
+            }
+            const operationEvent = {
+                op: "loadModel",
+                kind: "handler",
+                ms: totalLoadTimeMs,
+                profileId,
+                gauges: Object.keys(gauges).length > 0 ? gauges : undefined,
+                tags: Object.keys(tags).length > 0 ? tags : undefined,
+            };
+            response[OPERATION_EVENT_KEY] = operationEvent;
+        }
+        return response;
     }
     catch (error) {
         logger.error("Error loading model:", error);
@@ -162,41 +185,3 @@ async function handleConfigReload(request) {
 function isReloadConfigRequest(request) {
     return "modelId" in request && !("modelSrc" in request);
 }
-const BERGAMOT_CJK_LANG_PAIRS = ["enja", "enko", "enzh"];
-function deriveBergamotVocabSources(modelSrc) {
-    const match = modelSrc.match(/^pear:\/\/([a-f0-9]+)\/model\.([a-z]+)\.intgemm\.alphas\.bin$/);
-    if (!match || !match[1] || !match[2])
-        return null;
-    const key = match[1];
-    const langPair = match[2];
-    if (BERGAMOT_CJK_LANG_PAIRS.includes(langPair)) {
-        return {
-            srcVocabSrc: `pear://${key}/srcvocab.${langPair}.spm`,
-            dstVocabSrc: `pear://${key}/trgvocab.${langPair}.spm`,
-        };
-    }
-    const sharedVocab = `pear://${key}/vocab.${langPair}.spm`;
-    return {
-        srcVocabSrc: sharedVocab,
-        dstVocabSrc: sharedVocab,
-    };
-}
-function deriveBergamotRegistryVocabSources(modelSrc) {
-    // registry://s3/path/to/model.enfr.intgemm.alphas.bin
-    const match = modelSrc.match(/^(registry:\/\/.+\/)model\.([a-z]+)\.intgemm\.alphas\.bin$/);
-    if (!match || !match[1] || !match[2])
-        return null;
-    const basePath = match[1];
-    const langPair = match[2];
-    if (BERGAMOT_CJK_LANG_PAIRS.includes(langPair)) {
-        return {
-            srcVocabSrc: `${basePath}srcvocab.${langPair}.spm`,
-            dstVocabSrc: `${basePath}trgvocab.${langPair}.spm`,
-        };
-    }
-    const sharedVocab = `${basePath}vocab.${langPair}.spm`;
-    return {
-        srcVocabSrc: sharedVocab,
-        dstVocabSrc: sharedVocab,
-    };
-}

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

@@ -1,3 +1,4 @@
 import type { ModelProgressUpdate } from "../../../../schemas/index";
-export declare function downloadModelFromHttp(url: string, progressCallback?: (progress: ModelProgressUpdate) => void): Promise<string>;
+import type { DownloadMetricsHooks } from "./types";
+export declare function downloadModelFromHttp(url: string, progressCallback?: (progress: ModelProgressUpdate) => void, hooks?: DownloadMetricsHooks): Promise<string>;
 //# sourceMappingURL=http.d.ts.map

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

@@ -314,19 +314,20 @@ async function performHttpDownload(url, modelPath, downloadKey, progressCallback
         throw error instanceof Error ? error : new Error(String(error));
     }
 }
-export async function downloadModelFromHttp(url, progressCallback) {
+export async function downloadModelFromHttp(url, progressCallback, hooks) {
     const filename = extractFilenameFromUrl(url);
     if (isArchiveUrl(url)) {
-        return downloadShardedModelFromArchive(url, progressCallback);
+        return downloadShardedModelFromArchive(url, progressCallback, hooks);
     }
     const shardInfo = detectShardedModel(filename);
     if (shardInfo.isSharded && shardInfo.totalShards) {
-        return downloadShardedModelFromHttp(url, progressCallback);
+        return downloadShardedModelFromHttp(url, progressCallback, hooks);
     }
     const downloadKey = createHttpDownloadKey(url);
     const existing = getActiveDownload(downloadKey);
     if (existing) {
         logger.info(`📥 Reusing existing download for: ${downloadKey}`);
+        hooks?.markCacheMiss();
         return existing.promise;
     }
     const cacheDir = getModelsCacheDir();
@@ -339,6 +340,7 @@ export async function downloadModelFromHttp(url, progressCallback) {
             // Check if already cached
             const cachedPath = await validateCachedFile(modelPath, url, abortController.signal);
             if (cachedPath) {
+                hooks?.markCacheHit();
                 if (progressCallback) {
                     try {
                         const stats = await fsPromises.stat(cachedPath);
@@ -360,6 +362,7 @@ export async function downloadModelFromHttp(url, progressCallback) {
                 return cachedPath;
             }
             // Download the file
+            hooks?.markCacheMiss();
             await performHttpDownload(url, modelPath, downloadKey, progressCallback, abortController.signal);
             // Send final 100% progress update
             if (progressCallback) {
@@ -426,7 +429,7 @@ export async function downloadModelFromHttp(url, progressCallback) {
     registerDownload(downloadKey, downloadEntry);
     return downloadPromise;
 }
-async function downloadShardedModelFromHttp(shardUrl, progressCallback) {
+async function downloadShardedModelFromHttp(shardUrl, progressCallback, hooks) {
     const config = getSDKConfig();
     const concurrency = config.httpDownloadConcurrency ?? DEFAULT_CONCURRENCY;
     const { shardUrls: shardInfos, cacheKey } = parsePatternBasedShardUrl(shardUrl);
@@ -435,6 +438,7 @@ async function downloadShardedModelFromHttp(shardUrl, progressCallback) {
     const existing = getActiveDownload(downloadKey);
     if (existing) {
         logger.info(`📥 Reusing existing sharded download for: ${downloadKey}`);
+        hooks?.markCacheMiss();
         return existing.promise;
     }
     const abortController = new AbortController();
@@ -483,6 +487,12 @@ async function downloadShardedModelFromHttp(shardUrl, progressCallback) {
                 }
             }
             logger.info(`📥 ${shardsToDownload.length} of ${shardInfos.length} shards need downloading`);
+            if (shardsToDownload.length === 0) {
+                hooks?.markCacheHit();
+            }
+            else {
+                hooks?.markCacheMiss();
+            }
             await downloadShardsWithConcurrency(shardsToDownload, shardStates, concurrency, abortController.signal, downloadKey, overallTotal, progressCallback);
             logger.info(`✅ All ${shardInfos.length} shards downloaded successfully`);
             await extractTensorsFromShards(shardDir, shardInfos[0].filename);
@@ -523,7 +533,7 @@ async function downloadShardedModelFromHttp(shardUrl, progressCallback) {
     });
     return downloadPromise;
 }
-async function downloadShardedModelFromArchive(archiveUrl, progressCallback) {
+async function downloadShardedModelFromArchive(archiveUrl, progressCallback, hooks) {
     const filename = extractFilenameFromUrl(archiveUrl);
     const sourceHash = generateShortHash(archiveUrl);
     const downloadKey = `http-archive:${sourceHash}`;
@@ -531,6 +541,7 @@ async function downloadShardedModelFromArchive(archiveUrl, progressCallback) {
     const existing = getActiveDownload(downloadKey);
     if (existing) {
         logger.info(`📥 Reusing existing archive download for: ${downloadKey}`);
+        hooks?.markCacheMiss();
         return existing.promise;
     }
     const abortController = new AbortController();
@@ -542,12 +553,14 @@ async function downloadShardedModelFromArchive(archiveUrl, progressCallback) {
             const files = await fsPromises.readdir(extractDir);
             const shardedFile = files.find((f) => detectShardedModel(String(f)).isSharded);
             if (!shardedFile) {
+                hooks?.markCacheMiss();
                 return downloadAndExtractArchive();
             }
             const shardFilename = String(shardedFile);
             const allShardsExist = await checkAllShardsExist(extractDir, shardFilename);
             if (!allShardsExist) {
                 logger.warn(`⚠️ Incomplete shards found, re-downloading archive`);
+                hooks?.markCacheMiss();
                 return downloadAndExtractArchive();
             }
             const shardFilenames = generateShardFilenames(shardFilename);
@@ -555,6 +568,7 @@ async function downloadShardedModelFromArchive(archiveUrl, progressCallback) {
             const isComplete = await validateShardedModelCache(extractDir, shardFilename);
             if (isComplete) {
                 logger.info(`✅ Archive already extracted: ${extractDir}`);
+                hooks?.markCacheHit();
                 if (progressCallback) {
                     progressCallback({
                         type: "modelProgress",
@@ -570,6 +584,7 @@ async function downloadShardedModelFromArchive(archiveUrl, progressCallback) {
             try {
                 await extractTensorsFromShards(extractDir, shardFilename);
                 logger.info(`✅ Tensors extracted successfully`);
+                hooks?.markCacheHit();
                 if (progressCallback) {
                     progressCallback({
                         type: "modelProgress",
@@ -585,6 +600,7 @@ async function downloadShardedModelFromArchive(archiveUrl, progressCallback) {
                 logger.warn(`Failed to extract tensors, will re-download archive`, {
                     error,
                 });
+                hooks?.markCacheMiss();
                 return downloadAndExtractArchive();
             }
         }

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

@@ -1,4 +1,5 @@
 import type { ModelProgressUpdate } from "../../../../schemas/index";
+import type { DownloadMetricsHooks } from "./types";
 export declare function deleteCorestoreDirectory(corestoreDir: string): Promise<void>;
-export declare function downloadModelFromHyperdrive(hyperdriveKey: string, modelFileName: string, seed?: boolean, progressCallback?: (progress: ModelProgressUpdate) => void, expectedChecksum?: string): Promise<string>;
+export declare function downloadModelFromHyperdrive(hyperdriveKey: string, modelFileName: string, seed?: boolean, progressCallback?: (progress: ModelProgressUpdate) => void, hooks?: DownloadMetricsHooks, expectedChecksum?: string): Promise<string>;
 //# sourceMappingURL=hyperdrive.d.ts.map

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

@@ -6,7 +6,7 @@ import Hyperdrive from "hyperdrive";
 import {} from "bare-stream";
 import { AbortController } from "bare-abort-controller";
 import { getEnv } from "../../../env.js";
-import { getModelsCacheDir, generateShortHash, detectShardedModel, getShardedModelCacheDir, getShardPath, checkShardCompleteness, calculateFileChecksum, extractTensorsFromShards, calculatePercentage, } from "../../../utils/index.js";
+import { getModelsCacheDir, generateShortHash, detectShardedModel, getShardedModelCacheDir, getShardPath, checkShardCompleteness, measureChecksum, extractTensorsFromShards, calculatePercentage, } from "../../../utils/index.js";
 import { getModelBySrc } from "../../../../models/registry/index.js";
 import { getActiveDownload, registerDownload, unregisterDownload, createHyperdriveDownloadKey, shouldClearCache, clearClearCacheFlag, } from "./download-manager.js";
 import { getSDKConfig } from "../../../bare/registry/config-registry.js";
@@ -142,7 +142,7 @@ async function validateFileExistence(drive, file) {
         totalBytes,
     };
 }
-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);
@@ -153,7 +153,7 @@ async function validateCachedFile(modelPath, modelFileName, expectedSize, expect
             logger.info(`✅ Model cached with correct size: ${modelPath}`);
             // Always validate checksum if provided, even when size matches
             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`);
                 }
@@ -170,7 +170,7 @@ async function validateCachedFile(modelPath, modelFileName, expectedSize, expect
         return null;
     }
 }
-async function downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, expectedChecksum, progressCallback, seed, signal) {
+async function downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, expectedChecksum, progressCallback, seed, signal, hooks) {
     // Check if already aborted
     if (signal?.aborted) {
         throw new DownloadCancelledError();
@@ -194,7 +194,7 @@ async function downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdri
             }
             : undefined;
         await downloadAndValidateFile(setup.drive, modelFileName, modelPath, 0, // Size will be determined from drive
-        expectedChecksum, progressContext, signal);
+        expectedChecksum, progressContext, signal, hooks);
         logger.info(`✅ Model downloaded successfully to ${modelPath}`);
         // Send final 100% progress update
         if (progressCallback) {
@@ -244,7 +244,7 @@ async function downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdri
         clearClearCacheFlag(downloadKey);
     }
 }
-async function downloadAndValidateFile(drive, sourceFileName, targetFilePath, expectedSize, expectedChecksum, progressContext, signal) {
+async function downloadAndValidateFile(drive, sourceFileName, targetFilePath, expectedSize, expectedChecksum, progressContext, signal, hooks) {
     const { entry, blobs, targetPath, blocksDownloaded, totalBlocks, totalBytes, } = await validateFileExistence(drive, sourceFileName);
     const blob = entry?.value?.blob;
     if (!blob) {
@@ -316,7 +316,7 @@ async function downloadAndValidateFile(drive, sourceFileName, targetFilePath, ex
         }
         // Validate checksum
         if (expectedChecksum && expectedChecksum.length === 64) {
-            const checksum = await calculateFileChecksum(targetFilePath);
+            const checksum = await measureChecksum(targetFilePath, hooks);
             if (checksum !== expectedChecksum) {
                 await fsPromises.unlink(targetFilePath);
                 throw new ChecksumValidationFailedError(`${path.basename(targetFilePath)}. Expected: ${expectedChecksum}. Actual: ${checksum}`);
@@ -361,7 +361,7 @@ function createManagedDownload(downloadKey, hyperdriveKey, modelFileName, downlo
     registerDownload(downloadKey, downloadEntry);
     return downloadPromise;
 }
-async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileName, shardMetadata, progressCallback, seed, signal) {
+async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileName, shardMetadata, progressCallback, seed, signal, hooks) {
     if (signal?.aborted) {
         throw new DownloadCancelledError();
     }
@@ -374,9 +374,10 @@ async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileNam
     const numberedShardCount = shardInfo.totalShards;
     logger.info(`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);
+    const invalidIndices = await checkShardCompleteness(hyperdriveKey, allFiles, shardMetadata, hooks ? (ms) => hooks.addChecksumValidationTimeMs(ms) : undefined);
     if (invalidIndices.length === 0) {
         logger.info(`✅ All ${allFiles.length} files already downloaded and validated`);
+        hooks?.markCacheHit();
         if (progressCallback) {
             const overallTotal = shardMetadata.reduce((sum, shard) => sum + shard.expectedSize, 0);
             const lastFile = allFiles[allFiles.length - 1];
@@ -400,6 +401,7 @@ async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileNam
         return getShardPath(hyperdriveKey, allFiles[0]);
     }
     logger.info(`📥 Need to download ${invalidIndices.length} of ${allFiles.length} files`);
+    hooks?.markCacheMiss();
     // Setup hyperdrive once for all shards
     const corestoreDir = getCorestoreDir(hyperdriveKey);
     const setup = await setupHyperdrive(hyperdriveKey, corestoreDir);
@@ -462,7 +464,7 @@ async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileNam
                     },
                 }
                 : undefined;
-            await downloadAndValidateFile(setup.drive, file, filePath, fileMeta.expectedSize, fileMeta.sha256Checksum, progressContext, signal);
+            await downloadAndValidateFile(setup.drive, file, filePath, fileMeta.expectedSize, fileMeta.sha256Checksum, progressContext, signal, hooks);
             if (signal?.aborted) {
                 throw new DownloadCancelledError();
             }
@@ -516,17 +518,18 @@ async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileNam
     }
     return getShardPath(hyperdriveKey, allFiles[0]);
 }
-export async function downloadModelFromHyperdrive(hyperdriveKey, modelFileName, seed, progressCallback, expectedChecksum) {
+export async function downloadModelFromHyperdrive(hyperdriveKey, modelFileName, seed, progressCallback, hooks, expectedChecksum) {
     const downloadKey = createHyperdriveDownloadKey(hyperdriveKey, modelFileName);
     // Check if already downloading
     const existing = getActiveDownload(downloadKey);
     if (existing) {
+        hooks?.markCacheMiss();
         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);
+        return createManagedDownload(downloadKey, hyperdriveKey, modelFileName, (signal) => downloadShardedFilesToFilesystem(hyperdriveKey, modelFileName, model.shardMetadata, progressCallback, seed, signal, hooks), progressCallback);
     }
     // Non-sharded model download
     const corestoreDir = getCorestoreDir(hyperdriveKey);
@@ -535,8 +538,9 @@ export async function downloadModelFromHyperdrive(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);
+        const cachedPath = await validateCachedFile(modelPath, modelFileName, model.expectedSize, expectedChecksum || model.sha256Checksum, hooks);
         if (cachedPath) {
+            hooks?.markCacheHit();
             if (progressCallback) {
                 progressCallback({
                     type: "modelProgress",
@@ -553,9 +557,10 @@ export async function downloadModelFromHyperdrive(hyperdriveKey, modelFileName,
             return cachedPath;
         }
     }
+    hooks?.markCacheMiss();
     return createManagedDownload(downloadKey, hyperdriveKey, modelFileName, async (signal) => {
         const checksumToValidate = expectedChecksum || model?.sha256Checksum || "";
-        await downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, checksumToValidate, progressCallback, seed, signal);
+        await downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, checksumToValidate, progressCallback, seed, signal, hooks);
         return modelPath;
     }, progressCallback);
 }

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

@@ -1,4 +1,5 @@
 import type { ModelProgressUpdate } from "../../../../schemas/index";
+import type { DownloadMetricsHooks } from "./types";
 /**
  * Download a model from the QVAC Registry.
  *
@@ -6,5 +7,5 @@ import type { ModelProgressUpdate } from "../../../../schemas/index";
  * 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): Promise<string>;
+export declare function downloadModelFromRegistry(registryPath: string, registrySource: string, progressCallback?: (progress: ModelProgressUpdate) => void, expectedChecksum?: string, hooks?: DownloadMetricsHooks): Promise<string>;
 //# sourceMappingURL=registry.d.ts.map