@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/providers/llama-cpp/models.js

@@ -0,0 +1,1011 @@
+/**
+ * Local llama.cpp model storage + install pipeline.
+ *
+ * Storage layout:
+ *
+ *   <home>/engines/llama-cpp/
+ *   └── models/
+ *       └── <model-id>/
+ *           ├── manifest.json   (snapshot of catalog metadata + install info)
+ *           └── <weights>.gguf  (the actual weights, original filename preserved)
+ *
+ * Install flow:
+ *   1. Look up the chat-model entry in the catalog.
+ *   2. Stream the GGUF from
+ *      `huggingface.co/<repo>/resolve/<revision>/<filename>` (the pinned
+ *      commit SHA, or `main` for legacy manifests) to a `.partial`
+ *      file, hashing as we go.
+ *   3. Verify the computed sha256 against the manifest's expected value.
+ *   4. Run the GGUF header parser to extract context window + chat-template
+ *      presence. Surface a non-fatal warning when `tokenizer.chat_template`
+ *      is missing — llama-server otherwise silently uses the wrong
+ *      template (the gemma4 footgun the Phase-0 spike caught).
+ *   5. Atomically rename `.partial` → final filename and write
+ *      `manifest.json`.
+ *
+ * Delete flow:
+ *   - Remove the per-model directory in one shot.
+ *
+ * Resolve-current flow:
+ *   - Pick the first installed model (alphabetical) when ChatManager
+ *     wants a default model path. Phase 2 keeps "current" implicit; a
+ *     proper picker lives in the UI.
+ */
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { createLogger } from '@bendyline/gezel';
+import { listBundleModelFiles, publishStagedModel, safeBundleModelPath, } from '../../models/bundle-storage.js';
+import { evaluateCatalogDrift } from '../../models/catalog-drift.js';
+import { catalogPayloadFingerprint, describeCatalogPayload, } from '../../models/catalog-payload-identity.js';
+import { MODEL_HASH_READ_BUFFER_BYTES, assertModelStorePathSafe, findModelRoot, findRenamedModelId, hashModelPayloadFiles, inspectModelDirectory, listIncompleteModelDownloads, listOverlayModelIds, makeSharedModelReadable, modelExistsOnlyReadOnly, modelStorageRoots, pruneModelPayloadFiles, readOnlyModelError, removeModelDir, verifyReadOnlyModelPayload, } from '../../models/storage-roots.js';
+import { checkDiskSpace, describeDiskShortfall } from '../../utils/disk-space.js';
+import { downloadWithRetry } from '../../utils/download-with-retry.js';
+import { ggufQuantizationTag, readGgufSummary } from './gguf-metadata.js';
+import { backfillGgufQuantization } from './gguf-quantization-backfill.js';
+/**
+ * How often to emit a `progress` event during a download. Anything
+ * shorter than 250ms wastes CPU on JSON serialization for the SSE
+ * stream; anything longer feels laggy in the UI's progress bar.
+ */
+const PROGRESS_INTERVAL_MS = 250;
+const log = createLogger('models');
+export class LlamaCppModelManager {
+    modelsRoot;
+    storageRoots;
+    catalog;
+    fetchImpl;
+    engine;
+    onInstalled;
+    /**
+     * In-flight installs. `install()` registers an entry on first yield
+     * and clears it in the iterator's `finally` block, so consumers
+     * (HTTP `/active-installs`, polling React UI) always see the live
+     * subset regardless of which code path drove the install.
+     */
+    activeInstalls = new Map();
+    /**
+     * Model directories we've already warned about skipping. `listInstalled`
+     * runs on every picker/settings poll; a broken directory should be loud
+     * exactly once per process, not once per poll.
+     */
+    skipWarned = new Set();
+    constructor(opts) {
+        this.engine = opts.engine ?? 'llama-cpp';
+        this.storageRoots = modelStorageRoots({ home: opts.home, engine: this.engine });
+        this.modelsRoot = this.storageRoots.writableRoot;
+        this.catalog = opts.catalog;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.onInstalled = opts.onInstalled;
+    }
+    /**
+     * The catalog source block this manager downloads from — `ds4` for the
+     * DwarfStar engine, `llamaCpp` otherwise. Cast to the llama.cpp source
+     * shape. The common downloader accepts the union directly so engine-specific
+     * sidecars (`mmproj` versus `visionEncoder`) keep their honest catalog names.
+     */
+    srcBlock(manifest) {
+        return this.engine === 'ds4' ? manifest.ds4 : manifest.llamaCpp;
+    }
+    /**
+     * Snapshot of installs currently running. Used by the Settings UI to
+     * mirror background bootstrap installs into its progress view — the
+     * first-run download fires server-side via direct method call (not
+     * the HTTP install route), so the React component has no live SSE
+     * stream to consume; polling this surface fills the gap.
+     */
+    getActiveInstalls() {
+        // Return shallow copies so the caller can't mutate our state.
+        return Array.from(this.activeInstalls.values()).map((entry) => ({ ...entry }));
+    }
+    /**
+     * List installed models in alphabetical order. Tolerates malformed or
+     * partial directories — they're skipped, not surfaced as errors.
+     */
+    async listInstalled() {
+        const entries = await listOverlayModelIds(this.storageRoots);
+        const out = [];
+        for (const id of entries) {
+            const summary = await this.loadInstalled(id);
+            if (!summary) {
+                this.warnSkip(id, 'no readable manifest.json (incomplete or interrupted download?)');
+                continue;
+            }
+            // Drift flag: does the catalog now describe different weights than the
+            // ones on disk? Best-effort — a catalog miss (third-party / removed
+            // entry) leaves it un-flagged.
+            const status = await this.evaluateDrift(id, summary).catch(() => null);
+            if (status?.updateAvailable) {
+                summary.updateAvailable = true;
+                if (status.availableVersion)
+                    summary.availableVersion = status.availableVersion;
+                if (status.reason)
+                    summary.updateReason = status.reason;
+            }
+            out.push(summary);
+        }
+        out.sort((a, b) => a.name.localeCompare(b.name));
+        return out;
+    }
+    /**
+     * List incomplete downloads for this engine — interrupted or unverified
+     * downloads that hold bytes on disk but have no `manifest.json`, so they
+     * never appear in {@link listInstalled}. Each is tagged `resumable` when
+     * its id still resolves to a catalog entry this engine can source, so the
+     * UI can offer resume (re-install picks up from the `.partial`) vs
+     * delete-only for stale ids. In-flight installs are excluded.
+     */
+    async listIncomplete() {
+        const activeIds = new Set(this.activeInstalls.keys());
+        const rows = await listIncompleteModelDownloads({ writableRoot: this.modelsRoot, activeIds });
+        const out = [];
+        for (const row of rows) {
+            let resumable = false;
+            let name;
+            if (isSafeId(row.id)) {
+                const detail = await this.catalog.get('chat-model', row.id).catch(() => null);
+                if (detail && detail.manifest.kind === 'chat-model' && this.srcBlock(detail.manifest)) {
+                    resumable = true;
+                    name = detail.manifest.name;
+                }
+            }
+            out.push({ ...row, resumable, ...(name ? { name } : {}) });
+        }
+        return out;
+    }
+    /**
+     * Model directories that do have a manifest, but whose metadata cannot be
+     * loaded by this build. These used to disappear from every inventory
+     * surface: `listInstalled()` correctly refused to run them, while the
+     * incomplete-download scan correctly ignored anything with a manifest.
+     * Keep that safety boundary, but return a management-only row so Settings
+     * can update a known catalog id or explicitly remove the held bytes.
+     */
+    async listUnrecognized() {
+        const rows = [];
+        for (const id of await listOverlayModelIds(this.storageRoots)) {
+            if (!isSafeId(id))
+                continue;
+            const root = await findModelRoot(this.storageRoots, id);
+            // Manifestless directories belong to listIncomplete(), not this state.
+            if (!root)
+                continue;
+            if (await this.loadInstalled(id))
+                continue;
+            const profile = await inspectModelDirectory(join(root, id));
+            if (!profile || profile.bytes === 0)
+                continue;
+            const raw = await readFile(join(root, id, 'manifest.json'), 'utf8').catch(() => null);
+            let legacyName;
+            let reason = "Gezel couldn't read this model's metadata.";
+            if (raw !== null) {
+                try {
+                    const parsed = JSON.parse(raw);
+                    if (typeof parsed.name === 'string' && parsed.name.trim())
+                        legacyName = parsed.name;
+                    reason =
+                        typeof parsed.filename === 'string' && typeof parsed.weightsFilename !== 'string'
+                            ? 'This model was installed by an older version of Gezel and its metadata needs updating.'
+                            : 'This model metadata is incomplete or does not match the current format.';
+                }
+                catch {
+                    reason = "This model's metadata file is not valid JSON.";
+                }
+            }
+            const detail = await this.catalog.get('chat-model', id).catch(() => null);
+            const catalogManifest = detail?.manifest.kind === 'chat-model' ? detail.manifest : undefined;
+            const canUpdate = Boolean(catalogManifest && this.srcBlock(catalogManifest));
+            const name = catalogManifest?.name ?? legacyName;
+            rows.push({
+                id,
+                ...(name ? { name } : {}),
+                bytes: profile.bytes,
+                updatedAt: profile.updatedAt,
+                reason,
+                canUpdate,
+                ...(resolve(root) !== resolve(this.storageRoots.writableRoot) ? { readOnly: true } : {}),
+            });
+        }
+        rows.sort((a, b) => b.bytes - a.bytes);
+        return rows;
+    }
+    /**
+     * Path of the first installed model, or null when none exist. Phase 2
+     * uses this to pick a default `--model` arg for the supervised
+     * llama-server when the user hasn't explicitly chosen one. A "default
+     * model" UI lives in Phase 3.
+     */
+    async resolveDefaultModelPath() {
+        const model = await this.resolveDefaultModel();
+        return model?.weightsPath ?? null;
+    }
+    /**
+     * Summary of the first installed model (or null). Same fall-through
+     * rule as {@link resolveDefaultModelPath}; returns the full summary
+     * so callers like `buildLlamaCppProvider` can pick up the manifest's
+     * `contextWindow` along with the path.
+     */
+    async resolveDefaultModel() {
+        const models = await this.listInstalled();
+        return models[0] ?? null;
+    }
+    /**
+     * Path of a specific installed model, or null when not installed.
+     * Used by ChatManager when the user has picked a model explicitly.
+     */
+    async resolveModelPath(id) {
+        const summary = await this.loadInstalled(id);
+        return summary?.weightsPath ?? null;
+    }
+    /**
+     * Full summary for a specific installed model, or null when not
+     * installed. Used when the user has pinned a default model via
+     * `config.defaultModel['llama-cpp']` — `buildLlamaCppProvider`
+     * needs the `contextWindow` to set `--ctx-size` correctly.
+     */
+    async resolveModel(id) {
+        return this.loadInstalled(id);
+    }
+    /**
+     * Whether a genuinely newer build of one installed model exists. Null when
+     * the id isn't installed for this engine. Shared with the chat manager's
+     * per-session staleness notice so a user is never told to re-download for a
+     * change that only touched metadata.
+     */
+    async getUpdateStatus(id) {
+        const summary = await this.loadInstalled(id);
+        if (!summary)
+            return null;
+        return this.evaluateDrift(id, summary).catch(() => ({ updateAvailable: false }));
+    }
+    /**
+     * Compare one installed copy against the live catalog. The catalog lookup
+     * runs for every model on every inventory poll; the manifest re-read only
+     * happens for the few whose version actually moved.
+     */
+    async evaluateDrift(id, summary) {
+        const installedVersion = summary.catalogVersion;
+        if (!installedVersion)
+            return { updateAvailable: false };
+        const detail = await this.catalog.get('chat-model', id).catch(() => null);
+        if (!detail || detail.manifest.kind !== 'chat-model')
+            return { updateAvailable: false };
+        if (detail.manifest.version === installedVersion)
+            return { updateAvailable: false };
+        const root = await findModelRoot(this.storageRoots, id);
+        if (!root)
+            return { updateAvailable: false };
+        const modelDir = join(root, id);
+        const parsed = await readFile(join(modelDir, 'manifest.json'), 'utf8')
+            .then((raw) => JSON.parse(raw))
+            .catch(() => null);
+        if (!parsed)
+            return { updateAvailable: false };
+        return evaluateCatalogDrift({
+            engine: this.engine,
+            id,
+            modelDir,
+            manifest: detail.manifest,
+            installedVersion,
+            installed: {
+                ...(parsed.huggingfaceRepo ? { huggingfaceRepo: parsed.huggingfaceRepo } : {}),
+                ...(parsed.payloadFingerprint ? { payloadFingerprint: parsed.payloadFingerprint } : {}),
+                ...(parsed.fileSha256 ? { fileSha256: parsed.fileSha256 } : {}),
+            },
+            healable: !summary.readOnly && !this.activeInstalls.has(id),
+        });
+    }
+    async delete(id) {
+        if (!isSafeId(id))
+            throw new Error(`refusing to delete with unsafe id: ${id}`);
+        if (await modelExistsOnlyReadOnly(this.storageRoots, id)) {
+            throw readOnlyModelError(id);
+        }
+        await removeModelDir(join(this.modelsRoot, id), this.modelsRoot);
+    }
+    /** Provider-owned snapshot used by the streaming `.gezmodel` exporter. */
+    async getModelBundleSource(id) {
+        if (!isSafeId(id))
+            throw new Error(`unsafe model id: ${id}`);
+        const summary = await this.loadInstalled(id);
+        if (!summary)
+            throw new Error(`model "${id}" is not available locally for ${this.engine}`);
+        const root = await findModelRoot(this.storageRoots, id);
+        if (!root)
+            throw new Error(`model "${id}" is not available locally for ${this.engine}`);
+        const modelDir = join(root, id);
+        const installedManifest = JSON.parse(await readFile(join(modelDir, 'manifest.json'), 'utf8'));
+        return {
+            id,
+            name: summary.name,
+            modelDir,
+            installedManifest,
+            modelFiles: await listBundleModelFiles(modelDir),
+            ...(summary.catalogVersion ? { catalogVersion: summary.catalogVersion } : {}),
+        };
+    }
+    /**
+     * Validate provider-specific invariants, write the local install manifest,
+     * and atomically publish a security-scanned staged bundle.
+     */
+    async importModelBundle(opts) {
+        if (!isSafeId(opts.id))
+            throw new Error(`unsafe model id: ${opts.id}`);
+        const parsed = opts.installedManifest;
+        if (parsed.id !== opts.id || !parsed.name || !parsed.weightsFilename || !parsed.installedAt) {
+            throw new Error('installed manifest does not describe the bundled model');
+        }
+        const files = await listBundleModelFiles(opts.stagedModelDir);
+        if (files.length === 0 || files.some((file) => !file.toLowerCase().endsWith('.gguf'))) {
+            throw new Error(`${this.engine} bundles may contain only GGUF model files`);
+        }
+        if (!files.includes(parsed.weightsFilename)) {
+            throw new Error(`installed manifest references missing weights: ${parsed.weightsFilename}`);
+        }
+        if (parsed.shards?.some((shard) => !files.includes(shard.filename))) {
+            throw new Error('installed manifest references a missing GGUF shard');
+        }
+        if (parsed.mmprojFilename && !files.includes(parsed.mmprojFilename)) {
+            throw new Error('installed manifest references a missing multimodal projector');
+        }
+        if (parsed.visionEncoderFilename && !files.includes(parsed.visionEncoderFilename)) {
+            throw new Error('installed manifest references a missing ds4 vision encoder');
+        }
+        if (parsed.draftModelFilename && !files.includes(parsed.draftModelFilename)) {
+            throw new Error('installed manifest references a missing speculative draft model');
+        }
+        // Parsing the GGUF header is the same final usability check a network
+        // install performs after checksum verification.
+        readGgufSummary(safeBundleModelPath(opts.stagedModelDir, parsed.weightsFilename));
+        const importedManifest = {
+            ...parsed,
+            fileSha256: await hashModelPayloadFiles(opts.stagedModelDir),
+        };
+        await writeFile(join(opts.stagedModelDir, 'manifest.json'), `${JSON.stringify(importedManifest, null, 2)}\n`, 'utf8');
+        await publishStagedModel({
+            modelsRoot: this.modelsRoot,
+            id: opts.id,
+            stagedModelDir: opts.stagedModelDir,
+            replace: opts.replace,
+        });
+        await makeSharedModelReadable(join(this.modelsRoot, opts.id));
+        try {
+            this.onInstalled?.({ engine: this.engine, id: opts.id });
+        }
+        catch {
+            // A post-install fitness hook is best-effort, as in the download path.
+        }
+    }
+    /**
+     * Install a model from the catalog. Yields progress / verifying /
+     * extracting-metadata / done events. Yields exactly one terminal
+     * event (`done` or `error`) and is safe to consume to completion.
+     *
+     * Existing weights at the target id are atomically replaced — the
+     * download writes to a `.partial` sibling and renames into place
+     * only after sha256 verification passes. Failed installs leave the
+     * previous weights untouched.
+     */
+    async *install(catalogId, options) {
+        const skipSha = options?.skipSha === true;
+        // Default ON — see `planDownloads`. ds4 passes `false` because it has no
+        // llama.cpp mmproj; its own `visionEncoder` remains mandatory and is not
+        // governed by this flag.
+        const includeMmproj = options?.includeMmproj !== false;
+        if (!isSafeId(catalogId)) {
+            yield { type: 'error', error: `unsafe catalog id: ${catalogId}` };
+            return;
+        }
+        // Two concurrent installs of the same catalog id would both write
+        // to the same `weights.gguf.partial` and produce a corrupt
+        // (sha-mismatched) file. Claim the slot SYNCHRONOUSLY (before any
+        // `await`) so a parallel call observing `has(...) === false` and
+        // entering the same window can't slip in between our check and
+        // set. The placeholder snapshot is filled in once the catalog
+        // lookup succeeds. Hits when the first-run bootstrap and the
+        // Home banner's limbo recovery fire on the same boot.
+        if (this.activeInstalls.has(catalogId)) {
+            yield {
+                type: 'error',
+                error: `install for "${catalogId}" is already in progress`,
+            };
+            return;
+        }
+        const tracked = {
+            catalogId,
+            bytesWritten: 0,
+            totalBytes: 0,
+            phase: 'downloading',
+            startedAt: new Date().toISOString(),
+        };
+        this.activeInstalls.set(catalogId, tracked);
+        try {
+            const detail = await this.catalog.get('chat-model', catalogId);
+            if (!detail || detail.manifest.kind !== 'chat-model') {
+                yield { type: 'error', error: `chat-model "${catalogId}" not in catalog` };
+                return;
+            }
+            const manifest = detail.manifest;
+            const installSrc = this.srcBlock(manifest);
+            if (!installSrc) {
+                yield {
+                    type: 'error',
+                    error: `chat-model "${catalogId}" has no ${this.engine} source`,
+                };
+                return;
+            }
+            tracked.totalBytes = installSrc.approxSizeBytes;
+            yield* this.runInstall(catalogId, manifest, tracked, skipSha, includeMmproj);
+        }
+        finally {
+            this.activeInstalls.delete(catalogId);
+        }
+    }
+    /**
+     * Inner install loop. Splitting it out lets {@link install} wrap the
+     * generator in a `try/finally` that clears the active-install
+     * registration on every exit path, including caller break/throw —
+     * the equivalent inline construction would require interleaving the
+     * cleanup with each early `return` and silently rot.
+     */
+    async *runInstall(catalogId, manifest, tracked, skipSha, includeMmproj) {
+        const src = this.srcBlock(manifest);
+        if (!src) {
+            yield { type: 'error', error: `chat-model "${catalogId}" has no ${this.engine} source` };
+            return;
+        }
+        const itemDir = join(this.modelsRoot, catalogId);
+        await mkdir(this.modelsRoot, { recursive: true });
+        await assertModelStorePathSafe(this.modelsRoot, itemDir);
+        await mkdir(itemDir, { recursive: true });
+        await assertModelStorePathSafe(this.modelsRoot, itemDir);
+        const plan = planDownloads(src, includeMmproj);
+        if (plan.length === 0) {
+            yield {
+                type: 'error',
+                error: `chat-model "${catalogId}" ${this.engine} source has neither filename nor shards`,
+            };
+            return;
+        }
+        const totalPlanned = plan.reduce((sum, e) => sum + e.sizeBytes, 0) || src.approxSizeBytes;
+        tracked.totalBytes = totalPlanned;
+        // sha256 of each verified file, keyed by its final relative path (flat,
+        // since planDownloads uses basename). Reused to build the fileSha256 map
+        // after publish so we don't re-hash the whole payload from disk a second
+        // time. `actual` (not the catalog hash) is stored so the skipSha path
+        // still records the true on-disk identity.
+        const verifiedDigests = {};
+        // Files this update doesn't have to fetch because the copy on disk is
+        // already the copy the catalog pins. They count as completed bytes from
+        // the start, keep their digests, and are left untouched by the publish
+        // rename below.
+        const reusable = await this.planReusableFiles(itemDir, plan);
+        let bytesCompleted = 0;
+        for (const entry of plan) {
+            const sha = reusable.get(entry.destFilename);
+            if (!sha)
+                continue;
+            verifiedDigests[entry.destFilename] = sha;
+            bytesCompleted += entry.sizeBytes;
+        }
+        if (reusable.size > 0) {
+            log.info(`[models] [${this.engine}] "${catalogId}": ${reusable.size} of ${plan.length} file(s) already match the catalog and will not be downloaded`);
+            tracked.bytesWritten = bytesCompleted;
+        }
+        const toFetch = plan.filter((entry) => !reusable.has(entry.destFilename));
+        // Preflight the disk before writing a byte. ds4 GGUFs run to 200+ GiB, so
+        // discovering ENOSPC at 95% costs hours and leaves a `.partial` occupying
+        // the disk it just filled. Only what we actually have to fetch is charged,
+        // less any `.partial` already holding part of it, so a resumed install
+        // isn't refused for space it already holds. A file being REPLACED is
+        // charged in full: its `.partial` lives beside the old copy and the old
+        // copy is only deleted at publish, so the update transiently needs room
+        // for both.
+        const remainingBytes = Math.max(0, toFetch.reduce((sum, e) => sum + e.sizeBytes, 0) -
+            (await partialBytesOnDisk(itemDir, toFetch)));
+        const space = await checkDiskSpace(itemDir, remainingBytes);
+        if (!space.ok) {
+            yield { type: 'error', error: describeDiskShortfall(space, manifest.name) };
+            return;
+        }
+        for (let i = 0; i < plan.length; i++) {
+            const entry = plan[i];
+            if (!entry)
+                continue;
+            if (reusable.has(entry.destFilename)) {
+                yield { type: 'progress', bytesWritten: bytesCompleted, totalBytes: totalPlanned };
+                continue;
+            }
+            const destPath = join(itemDir, entry.destFilename);
+            const tmpPath = `${destPath}.partial`;
+            // Pin to this payload's catalog revision when present. A model-matched
+            // vision encoder may live in a different repository from the language
+            // GGUF and therefore carries its own repo + revision. Fall back to the
+            // parent source and finally `main` for legacy manifests.
+            const repo = entry.huggingfaceRepo ?? src.huggingfaceRepo;
+            const ref = entry.revision ?? src.revision ?? 'main';
+            const url = `https://huggingface.co/${repo}/resolve/${encodeURIComponent(ref)}/${entry.repoPath.split('/').map(encodeURIComponent).join('/')}?download=true`;
+            const dlGen = downloadWithRetry({
+                url,
+                destPath,
+                approxSizeBytes: entry.sizeBytes,
+                fetchImpl: this.fetchImpl,
+            });
+            let entryBytesWritten = 0;
+            let inlineSha;
+            while (true) {
+                const step = await dlGen.next();
+                if (step.done) {
+                    if (step.value.kind === 'aborted') {
+                        yield { type: 'error', error: 'download aborted' };
+                        return;
+                    }
+                    if (step.value.kind === 'error') {
+                        yield {
+                            type: 'error',
+                            error: plan.length > 1
+                                ? `shard ${i + 1}/${plan.length} (${entry.destFilename}): ${step.value.error}`
+                                : step.value.error,
+                        };
+                        return;
+                    }
+                    entryBytesWritten = step.value.bytesWritten || entryBytesWritten;
+                    inlineSha = step.value.sha256;
+                    break;
+                }
+                const ev = step.value;
+                if (ev.type === 'progress') {
+                    entryBytesWritten = ev.bytesWritten;
+                    tracked.bytesWritten = bytesCompleted + entryBytesWritten;
+                    yield {
+                        type: 'progress',
+                        bytesWritten: bytesCompleted + entryBytesWritten,
+                        totalBytes: totalPlanned,
+                    };
+                }
+                else if (ev.type === 'retrying') {
+                    yield {
+                        type: 'retrying',
+                        attempt: ev.attempt,
+                        maxAttempts: ev.maxAttempts,
+                        delayMs: ev.delayMs,
+                        reason: ev.reason,
+                    };
+                }
+            }
+            tracked.phase = 'verifying';
+            yield { type: 'verifying' };
+            // Prefer the digest the downloader computed inline while streaming —
+            // a clean single-pass (HTTP 200) transfer already hashed every byte,
+            // so re-reading a multi-GB file off disk just to hash it again is pure
+            // waste. Only fall back to the read-back pass when the inline digest
+            // is absent (a resumed/appended download, or the Xet path, where the
+            // hasher never saw the earlier bytes).
+            let actual = inlineSha;
+            if (!actual) {
+                const hasher = createHash('sha256');
+                await new Promise((resolve, reject) => {
+                    // Big read buffer: a 64 KB stream starves inside the busy daemon
+                    // event loop (~110k turns for a 7 GB file → 15+ min). See
+                    // MODEL_HASH_READ_BUFFER_BYTES.
+                    const stream = createReadStream(tmpPath, {
+                        highWaterMark: MODEL_HASH_READ_BUFFER_BYTES,
+                    });
+                    stream.on('data', (chunk) => hasher.update(chunk));
+                    stream.on('end', () => resolve());
+                    stream.on('error', reject);
+                });
+                actual = hasher.digest('hex');
+            }
+            verifiedDigests[entry.destFilename] = actual;
+            if (actual !== entry.sha256.toLowerCase()) {
+                if (skipSha) {
+                    // User opted in after a previous mismatch surfaced. Keep the
+                    // `.partial` so the post-loop rename still has something to
+                    // commit; just stop treating the catalog sha as authoritative.
+                }
+                else {
+                    await rm(tmpPath, { force: true });
+                    yield {
+                        type: 'error',
+                        error: `The file '${entry.destFilename}' on Hugging Face has changed since this version of Gezel was published. Expected sha256 ${entry.sha256}, got ${actual}.`,
+                        mismatch: { file: entry.destFilename, expected: entry.sha256, actual },
+                    };
+                    return;
+                }
+            }
+            bytesCompleted += entryBytesWritten;
+            tracked.bytesWritten = bytesCompleted;
+            // Reset phase back to downloading for the next shard (or stays as
+            // verifying if this was the last; the next yielded phase is
+            // extracting-metadata below). Keeps the UI's phase pill accurate
+            // mid-iteration.
+            if (i < plan.length - 1)
+                tracked.phase = 'downloading';
+        }
+        // Parse metadata from the first weights entry (first shard for a
+        // sharded install, or the only file for single-file). Sidecars have
+        // their own GGUF headers but aren't what llama-server probes for the
+        // target model's context length / chat template.
+        tracked.phase = 'extracting-metadata';
+        yield { type: 'extracting-metadata' };
+        const firstWeights = plan.find((e) => e.role === 'weights');
+        if (!firstWeights) {
+            // Unreachable: planDownloads always emits at least one weights
+            // entry when the source is well-formed, and we already errored
+            // above when it returned [].
+            yield { type: 'error', error: 'internal: download plan has no weights entry' };
+            return;
+        }
+        // A reused file was never re-downloaded, so it has no `.partial` — read
+        // the published copy instead.
+        const firstWeightsPath = join(itemDir, firstWeights.destFilename);
+        const firstTmpPath = reusable.has(firstWeights.destFilename)
+            ? firstWeightsPath
+            : `${firstWeightsPath}.partial`;
+        let summary = null;
+        try {
+            summary = readGgufSummary(firstTmpPath);
+        }
+        catch (err) {
+            // Hash matched but the parser couldn't read the metadata — this
+            // should not happen with a real GGUF, but we don't want to leave
+            // downloaded-but-unusable files around. Bail loudly.
+            for (const entry of plan) {
+                await rm(`${join(itemDir, entry.destFilename)}.partial`, { force: true });
+            }
+            yield {
+                type: 'error',
+                error: `GGUF metadata parse failed (file is unusable): ${describeError(err)}`,
+            };
+            return;
+        }
+        // Atomic publish: rename each .partial into place. If a rename
+        // fails partway through, the renamed-already weights stay, the
+        // remaining .partials stay; the next install attempt resumes the
+        // rest. We bail loudly rather than try to roll back, because
+        // partial state is what we already accept on download failure.
+        try {
+            for (const entry of plan) {
+                if (reusable.has(entry.destFilename))
+                    continue;
+                const finalPath = join(itemDir, entry.destFilename);
+                await rm(finalPath, { force: true });
+                await rename(`${finalPath}.partial`, finalPath);
+            }
+        }
+        catch (err) {
+            yield { type: 'error', error: `rename failed: ${describeError(err)}` };
+            return;
+        }
+        // Drop weights left behind by a previous install of this id that used a
+        // different quant/filename — otherwise the old GGUF lingers alongside the
+        // new one (tens of GB for one slot). Runs before the fileSha256 map is
+        // built so the map describes exactly the current payload.
+        const pruned = await pruneModelPayloadFiles(itemDir, new Set(plan.map((entry) => entry.destFilename)));
+        if (pruned.length > 0) {
+            log.info(`[models] [${this.engine}] pruned ${pruned.length} stale file(s) from "${catalogId}": ${pruned.join(', ')}`);
+        }
+        const weightsShards = plan.filter((e) => e.role === 'weights' || e.role === 'weights-shard');
+        const mmprojEntry = plan.find((e) => e.role === 'mmproj');
+        const visionEncoderEntry = plan.find((e) => e.role === 'vision-encoder');
+        const draftModelEntry = plan.find((e) => e.role === 'draft-model');
+        // Snapshot what the catalog said this payload IS, so a later version bump
+        // that only edits metadata can be recognized as such without re-reading a
+        // byte. Skipped for a skipSha install: those bytes are knowingly not the
+        // ones the catalog describes.
+        const catalogPayload = describeCatalogPayload(manifest, this.engine);
+        const payloadFingerprint = catalogPayload && !skipSha ? catalogPayloadFingerprint(catalogPayload) : undefined;
+        // Recorded next to the catalog's tag, never instead of it: the catalog
+        // names the build a user chose, the header names what the bytes are.
+        const declaredQuantization = ggufQuantizationTag(summary);
+        const installed = {
+            id: catalogId,
+            name: manifest.name,
+            // Language weights only. Sidecars are surfaced and budgeted separately;
+            // folding them in here makes every vision launch count the encoder twice.
+            approxSizeBytes: src.approxSizeBytes,
+            weightsFilename: firstWeights.destFilename,
+            sha256: firstWeights.sha256.toLowerCase(),
+            installedAt: new Date().toISOString(),
+            catalogId,
+            catalogVersion: manifest.version,
+            huggingfaceRepo: src.huggingfaceRepo,
+            ...(weightsShards.length > 1
+                ? {
+                    shards: weightsShards.map((entry) => ({
+                        filename: entry.destFilename,
+                        sha256: entry.sha256.toLowerCase(),
+                        sizeBytes: entry.sizeBytes,
+                    })),
+                }
+                : {}),
+            ...(mmprojEntry ? { mmprojFilename: mmprojEntry.destFilename } : {}),
+            ...(visionEncoderEntry ? { visionEncoderFilename: visionEncoderEntry.destFilename } : {}),
+            ...(draftModelEntry ? { draftModelFilename: draftModelEntry.destFilename } : {}),
+            ...(src.quantization ? { quantization: src.quantization } : {}),
+            ...(declaredQuantization ? { ggufQuantization: declaredQuantization } : {}),
+            ...(summary.contextLength ? { contextWindow: Number(summary.contextLength) } : {}),
+            ...(summary.architecture ? { architecture: summary.architecture } : {}),
+            chatTemplatePresent: !summary.chatTemplateMissing,
+            ...(payloadFingerprint ? { payloadFingerprint } : {}),
+        };
+        installed.fileSha256 = await hashModelPayloadFiles(itemDir, verifiedDigests);
+        await writeFile(join(itemDir, 'manifest.json'), JSON.stringify(installed, null, 2), 'utf8');
+        await makeSharedModelReadable(itemDir);
+        const warning = summary.chatTemplateMissing
+            ? 'Model has no embedded chat template (tokenizer.chat_template is missing). llama-server will fall back to a generic template that may not match this model — replies may be incoherent. Consider a different quant of the same model.'
+            : undefined;
+        try {
+            this.onInstalled?.({ engine: this.engine, id: catalogId });
+        }
+        catch {
+            // Fire-and-forget: a hook failure must never fail a completed install.
+        }
+        yield { type: 'done', id: catalogId, ...(warning ? { warning } : {}) };
+    }
+    /**
+     * Files the plan asks for that are already on disk as exactly the bytes the
+     * catalog pins, keyed by filename with the digest to carry forward.
+     *
+     * An update usually rotates one thing — a quant, one shard, an added draft
+     * companion — and re-fetching the rest is pure waste. The install manifest
+     * records a sha256 for every file it published, each verified against the
+     * catalog when it landed; where that digest equals the pin we are about to
+     * download and the file is still its full length, the bytes on disk ARE the
+     * bytes we would fetch. Same trust model as the shared-store adoption cache:
+     * a recorded digest plus an unchanged stat is identity.
+     */
+    async planReusableFiles(itemDir, plan) {
+        const reusable = new Map();
+        const parsed = await readFile(join(itemDir, 'manifest.json'), 'utf8')
+            .then((raw) => JSON.parse(raw))
+            .catch(() => null);
+        const recorded = parsed?.fileSha256;
+        if (!recorded)
+            return reusable;
+        for (const entry of plan) {
+            const sha = recorded[entry.destFilename]?.toLowerCase();
+            if (!sha || sha !== entry.sha256.toLowerCase())
+                continue;
+            const size = await stat(join(itemDir, entry.destFilename))
+                .then((info) => (info.isFile() ? info.size : -1))
+                .catch(() => -1);
+            if (size !== entry.sizeBytes)
+                continue;
+            reusable.set(entry.destFilename, sha);
+        }
+        return reusable;
+    }
+    /** Warn once per model directory per process, then stay quiet. */
+    warnSkip(id, reason) {
+        if (this.skipWarned.has(id))
+            return;
+        this.skipWarned.add(id);
+        log.warn(`[${this.engine}] model directory "${id}" is not runnable: ${reason}`);
+    }
+    async loadInstalled(requestedId) {
+        let id = requestedId;
+        let root = await findModelRoot(this.storageRoots, id);
+        if (!root) {
+            // A pin written before the quant-suffix rename still names the old id.
+            // Config, gezel frontmatter, eval caches, and session records all hold
+            // whatever id was current when they were written.
+            const renamed = await findRenamedModelId(this.storageRoots, requestedId);
+            if (!renamed)
+                return null;
+            id = renamed;
+            root = await findModelRoot(this.storageRoots, id);
+            if (!root)
+                return null;
+        }
+        const metaPath = join(root, id, 'manifest.json');
+        let raw;
+        try {
+            raw = await readFile(metaPath, 'utf8');
+        }
+        catch {
+            this.warnSkip(id, `manifest.json is unreadable at ${metaPath}`);
+            return null;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            this.warnSkip(id, `manifest.json is not valid JSON at ${metaPath}`);
+            return null;
+        }
+        if (!parsed.id || !parsed.name || !parsed.weightsFilename || !parsed.installedAt) {
+            this.warnSkip(id, 'manifest.json is missing required fields (id/name/weightsFilename/installedAt)');
+            return null;
+        }
+        if (!(await verifyReadOnlyModelPayload(this.storageRoots, root, id, parsed.fileSha256, (reason) => this.warnSkip(id, reason)))) {
+            return null;
+        }
+        // Read from disk, not the manifest: `approxSizeBytes` recorded at install
+        // is the weights alone whenever the payload was adopted or resumed rather
+        // than freshly downloaded, so it cannot be trusted to include the projector.
+        const mmprojSizeBytes = parsed.mmprojFilename
+            ? await stat(join(root, id, parsed.mmprojFilename))
+                .then((s) => s.size)
+                .catch(() => 0)
+            : 0;
+        const visionEncoderSizeBytes = parsed.visionEncoderFilename
+            ? await stat(join(root, id, parsed.visionEncoderFilename))
+                .then((s) => s.size)
+                .catch(() => 0)
+            : 0;
+        // Absent on every copy installed before the field existed, and on those
+        // the catalog tag is the only thing the table has to show.
+        const ggufQuantization = parsed.ggufQuantization ??
+            (await backfillGgufQuantization({
+                engine: this.engine,
+                id,
+                modelDir: join(root, id),
+                weightsFilename: parsed.weightsFilename,
+                ...(parsed.quantization ? { catalogQuantization: parsed.quantization } : {}),
+                writable: resolve(root) === resolve(this.storageRoots.writableRoot),
+            }));
+        return {
+            id: parsed.id,
+            name: parsed.name,
+            approxSizeBytes: parsed.approxSizeBytes ?? 0,
+            installedAt: parsed.installedAt,
+            weightsPath: join(root, id, parsed.weightsFilename),
+            ...(parsed.mmprojFilename
+                ? {
+                    mmprojPath: join(root, id, parsed.mmprojFilename),
+                    ...(mmprojSizeBytes > 0 ? { mmprojSizeBytes } : {}),
+                }
+                : {}),
+            ...(parsed.visionEncoderFilename
+                ? {
+                    visionEncoderPath: join(root, id, parsed.visionEncoderFilename),
+                    ...(visionEncoderSizeBytes > 0 ? { visionEncoderSizeBytes } : {}),
+                }
+                : {}),
+            ...(parsed.draftModelFilename
+                ? { draftModelPath: join(root, id, parsed.draftModelFilename) }
+                : {}),
+            ...(parsed.contextWindow ? { contextWindow: parsed.contextWindow } : {}),
+            ...(parsed.quantization ? { quantization: parsed.quantization } : {}),
+            ...(ggufQuantization ? { ggufQuantization } : {}),
+            chatTemplatePresent: parsed.chatTemplatePresent ?? true,
+            ...(parsed.architecture ? { architecture: parsed.architecture } : {}),
+            ...(parsed.catalogVersion ? { catalogVersion: parsed.catalogVersion } : {}),
+            ...(parsed.sha256 ? { sha256: parsed.sha256 } : {}),
+            // Read-only when it lives in a machine/shared overlay rather than this
+            // daemon's writable root — the delete endpoint refuses it, so the UI
+            // must not offer a Delete action that can only 400.
+            ...(resolve(root) !== resolve(this.storageRoots.writableRoot) ? { readOnly: true } : {}),
+        };
+    }
+}
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Translate a catalog `llamaCpp` source into the ordered list of files
+ * to download. Single-file sources collapse to one entry. Sharded
+ * sources expand to one entry per shard, flattening any subdirectory
+ * in the HF tree to a basename on disk (so `Q4_K_M/foo-00001-of-NNN.gguf`
+ * lands as `foo-00001-of-NNN.gguf` next to its siblings — llama-server
+ * needs them all in the same directory to auto-discover splits).
+ */
+function planDownloads(src, 
+/**
+ * Whether to also fetch the vision projector. On by default: fetch what the
+ * catalog ships, and let the *runtime* decide whether to load it.
+ *
+ * This used to be off, on the reasoning that an mmproj-backed server 501s
+ * on slot save/restore and so shouldn't be imposed by an install. But the
+ * cost is paid at `--mmproj` on the command line, not at download — so
+ * withholding the file bought nothing and cost a lot: a user who enabled
+ * vision got a model that silently could not see, because the projector
+ * had never been fetched and nothing re-fetched it. Turning the toggle on
+ * now works immediately instead of requiring a re-install nobody knew to
+ * run.
+ *
+ * This option only governs llama.cpp's `mmproj`; a declared ds4
+ * `visionEncoder` is part of that model's install and is always fetched.
+ */
+includeMmproj = true) {
+    const out = [];
+    if (src.shards && src.shards.length > 0) {
+        src.shards.forEach((shard, i) => {
+            out.push({
+                repoPath: shard.name,
+                destFilename: basename(shard.name),
+                sha256: shard.sha256,
+                sizeBytes: shard.sizeBytes,
+                role: i === 0 ? 'weights' : 'weights-shard',
+            });
+        });
+    }
+    else if (src.filename && src.sha256) {
+        out.push({
+            repoPath: src.filename,
+            destFilename: basename(src.filename),
+            sha256: src.sha256,
+            sizeBytes: src.approxSizeBytes,
+            role: 'weights',
+        });
+    }
+    else {
+        return [];
+    }
+    if (src.mmproj && includeMmproj) {
+        out.push({
+            repoPath: src.mmproj.filename,
+            destFilename: basename(src.mmproj.filename),
+            sha256: src.mmproj.sha256,
+            sizeBytes: src.mmproj.sizeBytes,
+            role: 'mmproj',
+        });
+    }
+    if (src.visionEncoder) {
+        out.push({
+            ...(src.visionEncoder.huggingfaceRepo
+                ? { huggingfaceRepo: src.visionEncoder.huggingfaceRepo }
+                : {}),
+            ...(src.visionEncoder.revision ? { revision: src.visionEncoder.revision } : {}),
+            repoPath: src.visionEncoder.filename,
+            destFilename: basename(src.visionEncoder.filename),
+            sha256: src.visionEncoder.sha256,
+            sizeBytes: src.visionEncoder.sizeBytes,
+            role: 'vision-encoder',
+        });
+    }
+    // Draft companions are part of the model's selected decoding path, not
+    // an optional modality. Download them whenever the catalog ships one so
+    // an explicitly selected `draft-mtp`/other draft mode can work immediately
+    // after install without a second download.
+    if (src.draftModel) {
+        out.push({
+            repoPath: src.draftModel.filename,
+            destFilename: basename(src.draftModel.filename),
+            sha256: src.draftModel.sha256,
+            sizeBytes: src.draftModel.sizeBytes,
+            role: 'draft-model',
+        });
+    }
+    return out;
+}
+/**
+ * Bytes of a still-to-fetch download that a `.partial` already holds — resume
+ * credit, so retrying a 200 GiB download that's 90% done isn't refused for
+ * space it is already occupying.
+ *
+ * Deliberately blind to finished files. A previous install's copy of the same
+ * filename is NOT credit: the new bytes stream into a `.partial` beside it and
+ * the old copy is only removed at publish, so both are on disk at once. (This
+ * counted the finished file, which meant an in-place replacement was preflighted
+ * as needing nothing at all, and a half-full disk failed with ENOSPC deep into
+ * the transfer instead of being refused up front.) Files that don't need
+ * fetching at all are excluded by the caller, not credited here.
+ */
+async function partialBytesOnDisk(itemDir, plan) {
+    let total = 0;
+    for (const entry of plan) {
+        const size = await stat(`${join(itemDir, entry.destFilename)}.partial`)
+            .then((st) => st.size)
+            .catch(() => 0);
+        if (size > 0)
+            total += Math.min(size, entry.sizeBytes);
+    }
+    return total;
+}
+/**
+ * Permissive id check — must be a relative single-segment id, no
+ * traversal. Catalog ids match `[a-z0-9][a-z0-9.\-:]{1,63}` per the
+ * core schema, so anything that flunks this is malicious.
+ */
+function isSafeId(id) {
+    if (id.length === 0 || id.length > 64)
+        return false;
+    if (id.includes('/') || id.includes('\\') || id.startsWith('.'))
+        return false;
+    return /^[a-z0-9][a-z0-9.\-:]{0,63}$/i.test(id);
+}