@qvac/sdk 0.18.2 → 0.19.1

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

@@ -1,298 +0,0 @@
-import { promises as fsPromises } from 'bare-fs';
-import { generateShortHash, detectShardedModel, getShardedModelCacheDir, getShardPath, extractTensorsFromShards, calculatePercentage } from '../../../../server/utils/index.js';
-import { getSingleFileCachePath } from '../../../../server/utils/cache/paths.js';
-import { getModelByPath } from '../../../../models/registry/index.js';
-import { getRegistryClient } from '../../../../server/bare/registry/registry-client.js';
-import { createRegistryDownloadKey, startOrJoinDownload, applyJoinedDownloadStats } from '../../../../server/rpc/handlers/load-model/download-manager.js';
-import { buildBlobBinding, validateCachedFile, downloadSingleFileFromRegistry } from '../../../../server/rpc/handlers/load-model/registry-download-utils.js';
-import { downloadCompanionSetFromRegistry } from '../../../../server/rpc/handlers/load-model/registry-companion-set.js';
-import { DownloadCancelledError, ModelNotFoundError, RegistryDownloadFailedError } from '../../../../utils/errors-server.js';
-import { getServerLogger } from '../../../../logging/index.js';
-import { resolveRegistryDownloadMetadata } from './registry-metadata.js';
-const logger = getServerLogger();
-/**
- * Find all shards for a model using path prefix query.
- */
-async function findModelShards(registryPath) {
-    const client = await getRegistryClient();
-    const shardInfo = detectShardedModel(registryPath.split('/').pop() || '');
-    if (!shardInfo.isSharded) {
-        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('.'));
-    logger.info(`🔍 Finding shards with prefix: ${basePath}`);
-    const shards = await client.findModels({
-        gte: { path: basePath },
-        lte: { path: basePath + '\uffff' }
-    });
-    const sortedShards = shards
-        .filter((s) => {
-        const info = detectShardedModel(s.path.split('/').pop() || '');
-        return info.isSharded;
-    })
-        .sort((a, b) => {
-        const aInfo = detectShardedModel(a.path.split('/').pop() || '');
-        const bInfo = detectShardedModel(b.path.split('/').pop() || '');
-        return (aInfo.currentShard || 0) - (bInfo.currentShard || 0);
-    })
-        .map((s) => ({
-        path: s.path,
-        source: s.source,
-        size: s.blobBinding?.byteLength || 0,
-        checksum: s.blobBinding?.['sha256'] || s.sha256 || ''
-    }));
-    logger.info(`📦 Found ${sortedShards.length} shards`);
-    return sortedShards;
-}
-/**
- * Download sharded model files from registry.
- * When localShardMetadata is provided, uses pre-computed metadata + blob direct download
- * instead of querying the registry for shard info.
- */
-async function downloadShardedFilesFromRegistry(registryPath, registrySource, cacheKey, progressCallback, signal, localShardMetadata, hooks) {
-    if (signal?.aborted) {
-        throw new DownloadCancelledError();
-    }
-    let shards;
-    if (localShardMetadata?.length) {
-        shards = localShardMetadata.map((shard) => ({
-            filename: shard.filename,
-            size: shard.expectedSize,
-            checksum: shard.sha256Checksum,
-            path: registryPath,
-            source: registrySource,
-            blobBinding: buildBlobBinding(shard)
-        }));
-    }
-    else {
-        const filename = registryPath.split('/').pop() || registryPath;
-        const shardInfo = detectShardedModel(filename);
-        if (!shardInfo.isSharded || !shardInfo.totalShards) {
-            throw new RegistryDownloadFailedError(`Not a sharded model: ${filename}`);
-        }
-        const remoteShards = await findModelShards(registryPath);
-        if (remoteShards.length === 0) {
-            throw new ModelNotFoundError(`No shards found for ${registryPath}`);
-        }
-        if (remoteShards.length !== shardInfo.totalShards) {
-            logger.warn(`⚠️ Expected ${shardInfo.totalShards} shards but found ${remoteShards.length}`);
-        }
-        shards = remoteShards.map((s) => ({
-            filename: s.path.split('/').pop() || '',
-            size: s.size,
-            checksum: s.checksum,
-            path: s.path,
-            source: s.source
-        }));
-    }
-    const shardDir = getShardedModelCacheDir(cacheKey);
-    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;
-    for (let i = 0; i < shards.length; i++) {
-        if (signal?.aborted) {
-            throw new DownloadCancelledError();
-        }
-        const shard = shards[i];
-        const shardPath = getShardPath(cacheKey, shard.filename);
-        const cachedPath = await validateCachedFile(shardPath, shard.filename, shard.size, shard.checksum, hooks);
-        if (cachedPath) {
-            logger.debug(`✅ Shard ${i + 1}/${shards.length} already cached`);
-            overallDownloaded += shard.size;
-            if (progressCallback) {
-                progressCallback({
-                    type: 'modelProgress',
-                    downloaded: shard.size,
-                    total: shard.size,
-                    percentage: 100,
-                    downloadKey,
-                    shardInfo: {
-                        currentShard: i + 1,
-                        totalShards: shards.length,
-                        shardName: shard.filename,
-                        overallDownloaded,
-                        overallTotal,
-                        overallPercentage: calculatePercentage(overallDownloaded, overallTotal)
-                    }
-                });
-            }
-            continue;
-        }
-        logger.info(`📥 Downloading shard ${i + 1}/${shards.length}: ${shard.filename}`);
-        const shardProgressCallback = progressCallback
-            ? (progress) => {
-                const currentOverall = overallDownloaded + progress.downloaded;
-                progressCallback({
-                    ...progress,
-                    downloadKey,
-                    shardInfo: {
-                        currentShard: i + 1,
-                        totalShards: shards.length,
-                        shardName: shard.filename,
-                        overallDownloaded: currentOverall,
-                        overallTotal,
-                        overallPercentage: calculatePercentage(currentOverall, overallTotal)
-                    }
-                });
-            }
-            : undefined;
-        await downloadSingleFileFromRegistry(shard.path, shard.source, shardPath, shard.filename, downloadKey, shard.size, shard.checksum, shardProgressCallback, signal, shard.blobBinding, hooks);
-        overallDownloaded += shard.size;
-        logger.info(`✅ Shard ${i + 1}/${shards.length} downloaded`);
-    }
-    const firstShardFilename = shards[0].filename;
-    await extractTensorsFromShards(shardDir, firstShardFilename);
-    if (progressCallback) {
-        const lastShard = shards[shards.length - 1];
-        progressCallback({
-            type: 'modelProgress',
-            downloaded: overallTotal,
-            total: overallTotal,
-            percentage: 100,
-            downloadKey,
-            shardInfo: {
-                currentShard: shards.length,
-                totalShards: shards.length,
-                shardName: lastShard.filename,
-                overallDownloaded: overallTotal,
-                overallTotal,
-                overallPercentage: 100
-            }
-        });
-    }
-    return getShardPath(cacheKey, firstShardFilename);
-}
-export async function downloadModelFromRegistry(registryPath, registrySource, progressCallback, expectedChecksum, hooks, explicitMetadata) {
-    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);
-    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?.();
-                    ctx.setCacheHit(true);
-                    const overallTotal = localShardMeta.reduce((sum, s) => sum + s.expectedSize, 0);
-                    ctx.broadcastProgress({
-                        type: 'modelProgress',
-                        downloaded: overallTotal,
-                        total: overallTotal,
-                        percentage: 100,
-                        downloadKey,
-                        shardInfo: {
-                            currentShard: localShardMeta.length,
-                            totalShards: localShardMeta.length,
-                            shardName: firstShardFilename,
-                            overallDownloaded: overallTotal,
-                            overallTotal,
-                            overallPercentage: 100
-                        }
-                    });
-                    return getShardPath(cacheKey, firstShardFilename);
-                }
-            }
-            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;
-            }
-        }
-        // 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,
-                allowLegacyFlatCache: modelMetadata.addon === 'nmt',
-                progressCallback: ctx.broadcastProgress,
-                signal: ctx.signal,
-                hooks: companionHooks,
-                shouldClearCache: ctx.shouldClearCache
-            });
-        }
-        const modelPath = getSingleFileCachePath(registryPath);
-        const { expectedSize, checksum } = resolveRegistryDownloadMetadata(modelMetadata, explicitMetadata, expectedChecksum);
-        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 modelPath;
-    }, progressCallback, hooks?.requestBinding);
-    return applyJoinedDownloadStats(result, hooks);
-}

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

@@ -1,34 +0,0 @@
-import type { AbortSignal } from 'bare-abort-controller';
-import type { ModelProgressUpdate, ResolveContext } from '../../../../schemas/index.js';
-import type { DownloadRequestBinding, ResolveResult } from '../../../../server/rpc/handlers/load-model/types.js';
-export interface ResolveSessionOptions {
-    progressCallback?: ((update: ModelProgressUpdate) => void) | undefined;
-    seed?: boolean | undefined;
-    profilingEnabled: boolean;
-    /**
-     * Optional cancel signal — typically `ctx.signal` from the surrounding
-     * `await using ctx = await registry.begin(...)` block. When provided,
-     * `resolveModelPath` short-circuits with `InferenceCancelledError` if the
-     * signal is already aborted on entry; the same signal also propagates
-     * to in-progress transfers via the request binding below so cancel
-     * tears them down end-to-end.
-     */
-    signal?: AbortSignal | undefined;
-    /**
-     * Optional per-request binding threaded into every `startOrJoinDownload`
-     * call. The download manager wires a per-subscriber abort listener
-     * against `binding.signal`, registers a scope-defer cleanup, and stamps
-     * the subscriber with `binding.requestId` so the legacy
-     * `cancelTransfer(downloadKey)` path can route through
-     * `registry.cancel({ requestId })`.
-     */
-    requestBinding?: DownloadRequestBinding | undefined;
-}
-export interface ResolveSession {
-    resolvePrimaryModelPath(modelSrc: unknown, fallbackSrc?: string): 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

@@ -1,62 +0,0 @@
-import { resolveModelPath, resolveModelPathWithStats } from '../../../../server/rpc/handlers/load-model/resolve.js';
-import { cancelTransfer } from '../../../../server/rpc/handlers/load-model/download-manager.js';
-import { mergeDownloadStats } from '../../../../server/rpc/handlers/load-model/download-stats.js';
-export function createResolveSession(options) {
-    const { progressCallback, seed, profilingEnabled, signal, requestBinding } = options;
-    let primaryResult;
-    const resolveResults = [];
-    const activeDownloadKeys = new Set();
-    const downloadHooks = {
-        onDownloadKey(key) {
-            activeDownloadKeys.add(key);
-        },
-        ...(requestBinding !== undefined && { requestBinding })
-    };
-    async function resolvePrimaryModelPath(modelSrc, fallbackSrc) {
-        if (profilingEnabled) {
-            const result = await resolveModelPathWithStats(modelSrc, progressCallback, seed, signal, downloadHooks, fallbackSrc);
-            primaryResult = result;
-            resolveResults.push(result);
-            return result.path;
-        }
-        return resolveModelPath(modelSrc, progressCallback, seed, signal, downloadHooks, fallbackSrc);
-    }
-    async function resolveForPlugin(src) {
-        if (profilingEnabled) {
-            const result = await resolveModelPathWithStats(src, progressCallback, seed, signal, downloadHooks);
-            resolveResults.push(result);
-            return result.path;
-        }
-        return resolveModelPath(src, progressCallback, seed, signal, 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,16 +0,0 @@
-import { type ModelProgressUpdate } from '../../../../schemas/index.js';
-import type { ResolveResult, DownloadHooks } from './types.js';
-import type { AbortSignal } from 'bare-abort-controller';
-type ResolveMode = 'base' | 'stats';
-export declare function resolveFallbackModel(fallbackSrc: string, expectedChecksum: string | undefined, progressCallback: ((progress: ModelProgressUpdate) => void) | undefined, mode: ResolveMode, signal: AbortSignal | undefined, hooks: DownloadHooks | undefined): Promise<ResolveResult>;
-export declare function resolveRegistryModel(params: {
-    hasFallback: boolean;
-    isKnownModel: boolean;
-    downloadPrimary: () => Promise<ResolveResult>;
-    resolveFallback: () => Promise<ResolveResult>;
-    buildUnreachableError: (cause: unknown) => Error;
-}): Promise<ResolveResult>;
-export declare function resolveModelPath(modelSrc: unknown, progressCallback?: (progress: ModelProgressUpdate) => void, seed?: boolean, signal?: AbortSignal, hooks?: DownloadHooks, fallbackSrc?: string): Promise<string>;
-export declare function resolveModelPathWithStats(modelSrc: unknown, progressCallback?: (progress: ModelProgressUpdate) => void, seed?: boolean, signal?: AbortSignal, hooks?: DownloadHooks, fallbackSrc?: string): Promise<ResolveResult>;
-export {};
-//# sourceMappingURL=resolve.d.ts.map

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

@@ -1,237 +0,0 @@
-import { models, getModelByPath } from '../../../../models/registry/models.js';
-import { hyperdriveUrlSchema, registryUrlSchema, SUPPORTED_ARCHIVE_EXTENSIONS } from '../../../../schemas/index.js';
-import { getModelsCacheDir, getShardedModelCacheDir, generateShortHash, extractAndValidateShardedArchive, measureChecksum } from '../../../../server/utils/index.js';
-import { promises as fsPromises } from 'bare-fs';
-import path from 'bare-path';
-import { downloadModelFromHttp } from './http.js';
-import { downloadModelFromHyperdrive } from './hyperdrive.js';
-import { downloadModelFromRegistry } from './registry.js';
-import { getExplicitRegistryMetadata } from './registry-metadata.js';
-import { downloadModelFromHttpWithStats, downloadModelFromHyperdriveWithStats, downloadModelFromRegistryWithStats } from './download-stats.js';
-import { ChecksumValidationFailedError, DownloadCancelledError, InferenceCancelledError, ModelFileNotFoundError, ModelLoadFailedError, ModelNotFoundError, SeedingNotSupportedError } from '../../../../utils/errors-server.js';
-import { validateAndJoinPath } from '../../../../server/utils/path-security.js';
-import { getServerLogger } from '../../../../logging/index.js';
-import { modelInputToSrcSchema } from '../../../../schemas/index.js';
-const logger = getServerLogger();
-function isArchivePath(filePath) {
-    const filename = path.basename(filePath).toLowerCase();
-    return SUPPORTED_ARCHIVE_EXTENSIONS.some((ext) => filename.endsWith(ext));
-}
-/**
- * Resolves a local file path or cached file
- */
-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 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();
-    const cachedPath = validateAndJoinPath(cacheDir, modelIdOrPath);
-    try {
-        await fsPromises.access(cachedPath);
-        logger.info(`Loading cached model: ${cachedPath}`);
-        // Check if cached file is an archive
-        if (isArchivePath(cachedPath)) {
-            logger.info(`Extracting cached archive: ${cachedPath}`);
-            const archiveHash = generateShortHash(cachedPath);
-            const extractDir = getShardedModelCacheDir(archiveHash);
-            const extractedPath = await extractAndValidateShardedArchive(cachedPath, extractDir);
-            return extractedPath;
-        }
-        return cachedPath;
-    }
-    catch {
-        // Try as local file in current directory
-        try {
-            await fsPromises.access(modelIdOrPath);
-            logger.info(`Loading local file: ${modelIdOrPath}`);
-            // Check if local file is an archive
-            if (isArchivePath(modelIdOrPath)) {
-                logger.info(`Extracting local archive: ${modelIdOrPath}`);
-                const archiveHash = generateShortHash(modelIdOrPath);
-                const extractDir = getShardedModelCacheDir(archiveHash);
-                const extractedPath = await extractAndValidateShardedArchive(modelIdOrPath, extractDir);
-                return extractedPath;
-            }
-            return modelIdOrPath;
-        }
-        catch {
-            // Invalid model ID - provide helpful error
-            const availableModels = models.map((m) => m.modelId);
-            throw new ModelNotFoundError(`${modelIdOrPath}". Available models: ${availableModels.join(', ')}`);
-        }
-    }
-}
-function isDownloadResult(value) {
-    return value !== null && typeof value === 'object' && 'path' in value;
-}
-function buildResult(pathOrResult, sourceType) {
-    if (isDownloadResult(pathOrResult)) {
-        return pathOrResult.stats
-            ? { path: pathOrResult.path, sourceType, downloadStats: pathOrResult.stats }
-            : { path: pathOrResult.path, sourceType };
-    }
-    return { path: pathOrResult, sourceType };
-}
-// A fallback is a non-P2P source: only HTTP URLs and file paths are valid.
-// registry:// and pear:// are rejected.
-export async function resolveFallbackModel(fallbackSrc, expectedChecksum, progressCallback, mode, signal, hooks) {
-    if (fallbackSrc.startsWith('registry://') || fallbackSrc.startsWith('pear://')) {
-        throw new ModelLoadFailedError('fallbackSrc must be an HTTP URL or a local file path.');
-    }
-    // seed applies only to hyperdrive sources, which a fallback can never be.
-    const result = await resolveModelPathCore(fallbackSrc, progressCallback, false, mode, signal, hooks);
-    // Report a missing fallback file as a not-found error before checksumming.
-    try {
-        await fsPromises.access(result.path);
-    }
-    catch {
-        throw new ModelFileNotFoundError(result.path);
-    }
-    if (expectedChecksum && expectedChecksum.length === 64) {
-        const actualChecksum = await measureChecksum(result.path, hooks);
-        if (actualChecksum !== expectedChecksum) {
-            // http downloads are cached under the models dir; drop a corrupt one.
-            if (result.sourceType === 'http') {
-                await fsPromises.unlink(result.path).catch(() => { });
-            }
-            throw new ChecksumValidationFailedError(fallbackSrc);
-        }
-    }
-    return result;
-}
-// Registry download with optional fallback. A user-initiated cancel always
-// propagates. On any other primary failure: a fallback is taken when present;
-// otherwise a known model surfaces a neutral error and an unknown one rethrows.
-export async function resolveRegistryModel(params) {
-    try {
-        return await params.downloadPrimary();
-    }
-    catch (error) {
-        if (error instanceof InferenceCancelledError || error instanceof DownloadCancelledError) {
-            throw error;
-        }
-        if (params.hasFallback) {
-            return params.resolveFallback();
-        }
-        const isCorrectnessError = error instanceof ChecksumValidationFailedError ||
-            error instanceof ModelNotFoundError ||
-            error instanceof ModelFileNotFoundError;
-        if (params.isKnownModel && !isCorrectnessError) {
-            throw params.buildUnreachableError(error);
-        }
-        throw error;
-    }
-}
-async function resolveModelPathCore(modelSrc, progressCallback, seed, mode, signal, hooks, fallbackSrc) {
-    if (signal?.aborted) {
-        throw new InferenceCancelledError(hooks?.requestBinding?.requestId ?? 'unknown');
-    }
-    const srcString = modelInputToSrcSchema.parse(modelSrc);
-    // A fallback is validated against the catalog checksum, which exists only for
-    // built-in registry models. Other sources have no checksum to validate against.
-    if (fallbackSrc !== undefined && !srcString.startsWith('registry://')) {
-        throw new ModelLoadFailedError('fallbackSrc is only supported when modelSrc is a built-in registry model.');
-    }
-    // Empty modelSrc is reserved for plugins that ship bundled weights
-    // (e.g. `@qvac/classification-ggml`). The handler skips this resolver
-    // for them when `skipPrimaryModelPathValidation` is set, but if it
-    // somehow gets called we return an empty path so the plugin's
-    // `params.modelPath` falls through to undefined instead of being set
-    // to the cache directory itself.
-    if (srcString === '') {
-        return { path: '', sourceType: 'filesystem' };
-    }
-    // Parse hyperdrive URLs if present
-    let hyperdriveKey;
-    let actualModelSrc = srcString;
-    if (srcString.startsWith('pear://')) {
-        const { key, path: pathValue } = hyperdriveUrlSchema.parse(srcString);
-        hyperdriveKey = key;
-        actualModelSrc = pathValue;
-    }
-    // Registry source
-    if (srcString.startsWith('registry://')) {
-        const { registryPath, registrySource } = registryUrlSchema.parse(srcString);
-        logger.info(`Loading from registry: ${registryPath}`);
-        // Look up model metadata for checksum validation
-        const modelMetadata = getModelByPath(registryPath);
-        const explicitMetadata = getExplicitRegistryMetadata(modelSrc);
-        const expectedChecksum = modelMetadata?.sha256Checksum ?? explicitMetadata?.sha256Checksum;
-        // An uncatalogued registry path carries no checksum to validate a fallback against.
-        if (fallbackSrc !== undefined && !modelMetadata) {
-            throw new ModelLoadFailedError('fallbackSrc is only supported when modelSrc is a built-in registry model.');
-        }
-        // A single-file fallback cannot satisfy a sharded or companion-set model.
-        if (fallbackSrc !== undefined &&
-            (modelMetadata?.shardMetadata || modelMetadata?.companionSet)) {
-            throw new ModelLoadFailedError('fallbackSrc is not supported for sharded or multi-file models.');
-        }
-        return resolveRegistryModel({
-            hasFallback: fallbackSrc !== undefined,
-            isKnownModel: modelMetadata !== undefined,
-            downloadPrimary: async () => {
-                const result = mode === 'stats'
-                    ? await downloadModelFromRegistryWithStats(registryPath, registrySource, progressCallback, expectedChecksum, hooks, explicitMetadata)
-                    : await downloadModelFromRegistry(registryPath, registrySource, progressCallback, expectedChecksum, hooks, explicitMetadata);
-                logger.info(`Loaded Model to ${isDownloadResult(result) ? result.path : result}`);
-                return buildResult(result, 'registry');
-            },
-            resolveFallback: () => {
-                logger.info(`Registry download failed for ${registryPath}; trying fallbackSrc: ${fallbackSrc}`);
-                return resolveFallbackModel(fallbackSrc, expectedChecksum, progressCallback, mode, signal, hooks);
-            },
-            buildUnreachableError: (cause) => new ModelLoadFailedError(`Could not download "${modelMetadata?.modelId}" from the registry on this network ` +
-                `(${cause instanceof Error ? cause.message : String(cause)}). ` +
-                'If the registry is not reliably reachable here, pass a fallbackSrc ' +
-                '(an HTTP URL or local file path) to load this model from an alternate source.', cause)
-        });
-    }
-    // Validate seeding is only used with hyperdrive models
-    if (seed && !hyperdriveKey) {
-        throw new SeedingNotSupportedError();
-    }
-    // HTTP source
-    if (actualModelSrc.startsWith('http://') || actualModelSrc.startsWith('https://')) {
-        logger.info(`Loading from HTTP URL: ${actualModelSrc}`);
-        const result = mode === 'stats'
-            ? await downloadModelFromHttpWithStats(actualModelSrc, progressCallback, hooks)
-            : await downloadModelFromHttp(actualModelSrc, progressCallback, hooks);
-        logger.info(`Loaded Model to ${isDownloadResult(result) ? result.path : result}`);
-        return buildResult(result, 'http');
-    }
-    // Hyperdrive source
-    if (hyperdriveKey) {
-        logger.info(`Loading from hyperdrive: ${hyperdriveKey}`);
-        const result = mode === 'stats'
-            ? await downloadModelFromHyperdriveWithStats(hyperdriveKey, actualModelSrc, seed, progressCallback, hooks)
-            : await downloadModelFromHyperdrive(hyperdriveKey, actualModelSrc, seed, progressCallback, hooks);
-        return buildResult(result, 'hyperdrive');
-    }
-    // Filesystem source (local files, cached files)
-    let resolvedPath;
-    if (actualModelSrc.includes('/') || actualModelSrc.includes('\\')) {
-        if (isArchivePath(actualModelSrc)) {
-            logger.info(`Extracting local archive: ${actualModelSrc}`);
-            const archiveHash = generateShortHash(actualModelSrc);
-            const extractDir = getShardedModelCacheDir(archiveHash);
-            resolvedPath = await extractAndValidateShardedArchive(actualModelSrc, extractDir);
-        }
-        else {
-            resolvedPath = actualModelSrc;
-        }
-    }
-    else {
-        resolvedPath = await resolveLocalOrCachedFile(actualModelSrc);
-    }
-    return { path: resolvedPath, sourceType: 'filesystem' };
-}
-export async function resolveModelPath(modelSrc, progressCallback, seed, signal, hooks, fallbackSrc) {
-    const result = await resolveModelPathCore(modelSrc, progressCallback, seed, 'base', signal, hooks, fallbackSrc);
-    return result.path;
-}
-export async function resolveModelPathWithStats(modelSrc, progressCallback, seed, signal, hooks, fallbackSrc) {
-    return resolveModelPathCore(modelSrc, progressCallback, seed, 'stats', signal, hooks, fallbackSrc);
-}