@bendyline/gezel-inference 0.0.0-stage → 1.0.0

package/dist/model-profile/runtime.js

@@ -0,0 +1,131 @@
+/**
+ * Helpers for the runtime points where local-model providers (Ollama,
+ * llama-cpp, mlx, ds4) gate features on the resolved profile. The bridge +
+ * chat-manager-side wiring composes hooks naturally; the providers
+ * have a different shape — they instantiate stateful machinery
+ * (RambleDetector class, foldPreToolPreamble call site, Gemma
+ * special-token salvage) that doesn't fit the hook surface. These
+ * helpers translate "is behavior X opted in?" + "what's its config?"
+ * into the data the providers actually need.
+ *
+ * Each helper accepts an optional profile and degrades gracefully
+ * (returns `false` / `null` / config defaults) when undefined, so
+ * legacy code paths that don't yet thread a profile keep working.
+ */
+import { createLogger } from '@bendyline/gezel';
+import { lookupBehavior } from './registry.js';
+// The profile reads the local loop makes live in core with the loop itself.
+export { extractReasoningWithProfile, profileBehaviorConfig, profileHasBehavior, } from '@bendyline/gezel/local-loop';
+import { profileHasBehavior } from '@bendyline/gezel/local-loop';
+const log = createLogger('model-profile');
+function parseBehaviorIdList(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Apply per-run behavior overrides from the environment to a resolved
+ * profile. Feature-agnostic and reusable for any A/B:
+ *
+ *   - `GEZEL_FORCE_BEHAVIORS` — comma-separated behavior ids to ADD
+ *     (e.g. `tools.gezels-as-roles`). Already-present ids are skipped;
+ *     unknown ids are logged and ignored; parameterized behaviors get
+ *     their validated `defaultConfig`.
+ *   - `GEZEL_REMOVE_BEHAVIORS` — comma-separated ids to remove.
+ *
+ * Returns the same profile reference when no override applies (so the
+ * common path is allocation-free), otherwise a shallow copy with a new
+ * `behaviors` array. The eval runner injects these env vars per-run via
+ * the daemon spawn `extraEnv`, so control vs treatment is one flag — no
+ * catalog edits or rebuilds between runs.
+ */
+export function applyBehaviorEnvOverrides(profile) {
+    const add = parseBehaviorIdList(process.env.GEZEL_FORCE_BEHAVIORS);
+    const remove = parseBehaviorIdList(process.env.GEZEL_REMOVE_BEHAVIORS);
+    if (add.length === 0 && remove.length === 0)
+        return profile;
+    let behaviors = profile.behaviors;
+    if (remove.length > 0) {
+        const removeSet = new Set(remove);
+        const before = new Set(behaviors.map((e) => e.id));
+        for (const id of remove) {
+            if (!before.has(id)) {
+                // Loud no-op: an A/B "removal" arm that names a behavior the
+                // profile never had is control-vs-control. Same class as the
+                // vacuous round below.
+                log.warn(`[model-profile] GEZEL_REMOVE_BEHAVIORS named "${id}" but the resolved profile for ${profile.catalogId ?? '(unknown)'} does not carry it — no-op.`);
+            }
+        }
+        behaviors = behaviors.filter((e) => !removeSet.has(e.id));
+    }
+    if (add.length > 0) {
+        const present = new Set(behaviors.map((e) => e.id));
+        const additions = [];
+        for (const id of add) {
+            if (present.has(id)) {
+                // Loud no-op: forcing a behavior the manifest already declares
+                // silently converges the A/B arms (wild-caught:
+                // qwen3.6-27b-q4 declares prompt.tool-cookbook-condensed, so a
+                // force-add round ran control-vs-control — identical prompts,
+                // 36 trials of noise).
+                log.warn(`[model-profile] GEZEL_FORCE_BEHAVIORS named "${id}" but the resolved profile for ${profile.catalogId ?? '(unknown)'} already carries it — no-op.`);
+                continue;
+            }
+            const behavior = lookupBehavior(id);
+            if (!behavior) {
+                log.warn(`[model-profile] GEZEL_FORCE_BEHAVIORS named unknown behavior "${id}"; skipping (typo, or not registered in ALL_BEHAVIORS).`);
+                continue;
+            }
+            let config;
+            if (behavior.configSchema) {
+                const parsed = behavior.configSchema.safeParse(behavior.defaultConfig);
+                if (!parsed.success) {
+                    log.warn(`[model-profile] GEZEL_FORCE_BEHAVIORS could not apply "${id}" — defaultConfig failed validation; skipping.`);
+                    continue;
+                }
+                config = parsed.data;
+            }
+            additions.push({ id, config, behavior });
+            present.add(id);
+        }
+        if (additions.length > 0)
+            behaviors = [...behaviors, ...additions];
+    }
+    if (behaviors === profile.behaviors)
+        return profile;
+    return { ...profile, behaviors };
+}
+/**
+ * Walk `numPredict` hooks on the profile and return the first
+ * non-null value. Used by Ollama / llama-cpp / mlx in place of the
+ * legacy `pickOllamaNumPredict` substring matcher; replicates the
+ * "verbose-family models bumped to 16384" behavior via the registered
+ * `turn.ollama-num-predict-bumped` behavior's `numPredict` hook.
+ *
+ * Returns `null` when no behavior fires; the caller falls back to its
+ * own default (`DEFAULT_OLLAMA_NUM_PREDICT`) or to a user-configured
+ * override.
+ */
+export function profileNumPredict(profile, ctxArgs) {
+    if (!profile)
+        return null;
+    for (const entry of profile.behaviors) {
+        const hook = entry.behavior.numPredict;
+        if (!hook)
+            continue;
+        const ctx = {
+            catalogId: profile.catalogId,
+            tier: profile.tier,
+            family: profile.style.family,
+            modelId: ctxArgs.modelId,
+            providerName: ctxArgs.providerName,
+        };
+        const value = hook(ctx, entry.config);
+        if (typeof value === 'number')
+            return value;
+    }
+    return null;
+}

package/dist/model-profile/tool-grammar.d.ts

@@ -0,0 +1 @@
+export * from '@bendyline/gezel/local-loop';

package/dist/model-profile/tool-grammar.js

@@ -0,0 +1,2 @@
+// Moved to core so the portable runtime resolves profiles the same way; see core/src/model-profile.
+export * from '@bendyline/gezel/local-loop';

package/dist/model-profile/tuning.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve + apply per-model sampling / reasoning / structured-output knobs.
+ *
+ * Resolution order (highest wins):
+ *   1. Gezel frontmatter `tuning` — sparse, deep-merged on top of (2).
+ *   2. Catalog manifest `tuning` — recommended defaults from the gilde.
+ *   3. Provider built-in default — left untouched in this module; caller
+ *      is responsible for whatever the engine emits when a field is absent.
+ *
+ * Dual-mode sampling (Qwen3+, Nemotron Nano): `samplingWhenThinking` is a
+ * sparse override of `sampling`, merged shallow when reasoning is engaged.
+ * The runtime determines "is this a thinking turn" via
+ * {@link isReasoningEngaged}.
+ *
+ * The {@link applyTuning} helper writes a `ResolvedTuning` into a request
+ * body using a per-provider {@link TuningMap}. Fields a provider doesn't
+ * support are silently dropped — the map's `null` entry signals "drop".
+ */
+export { ANTHROPIC_TUNING_MAP, applyTuning, COPILOT_TUNING_MAP, isReasoningEngaged, LLAMA_CPP_TUNING_MAP, MLX_TUNING_MAP, OLLAMA_BODY_TUNING_MAP, OLLAMA_OPTIONS_TUNING_MAP, OLLAMA_TUNING_MAP, OPENAI_TUNING_MAP, type ResolvedTuning, type ResolveTuningInput, resolveTuning, type TuningMap, type TuningMapEntry, tuningMapFor, type TuningPath, } from '@bendyline/gezel';

package/dist/model-profile/tuning.js

@@ -0,0 +1,21 @@
+/**
+ * Resolve + apply per-model sampling / reasoning / structured-output knobs.
+ *
+ * Resolution order (highest wins):
+ *   1. Gezel frontmatter `tuning` — sparse, deep-merged on top of (2).
+ *   2. Catalog manifest `tuning` — recommended defaults from the gilde.
+ *   3. Provider built-in default — left untouched in this module; caller
+ *      is responsible for whatever the engine emits when a field is absent.
+ *
+ * Dual-mode sampling (Qwen3+, Nemotron Nano): `samplingWhenThinking` is a
+ * sparse override of `sampling`, merged shallow when reasoning is engaged.
+ * The runtime determines "is this a thinking turn" via
+ * {@link isReasoningEngaged}.
+ *
+ * The {@link applyTuning} helper writes a `ResolvedTuning` into a request
+ * body using a per-provider {@link TuningMap}. Fields a provider doesn't
+ * support are silently dropped — the map's `null` entry signals "drop".
+ */
+// Resolution and the request writer live in core so the portable runtime
+// shares them; re-exported so service callers keep their import path.
+export { ANTHROPIC_TUNING_MAP, applyTuning, COPILOT_TUNING_MAP, isReasoningEngaged, LLAMA_CPP_TUNING_MAP, MLX_TUNING_MAP, OLLAMA_BODY_TUNING_MAP, OLLAMA_OPTIONS_TUNING_MAP, OLLAMA_TUNING_MAP, OPENAI_TUNING_MAP, resolveTuning, tuningMapFor, } from '@bendyline/gezel';

package/dist/model-profile/types.d.ts

@@ -0,0 +1 @@
+export * from '@bendyline/gezel/local-loop';

package/dist/model-profile/types.js

@@ -0,0 +1,2 @@
+// Moved to core so the portable runtime resolves profiles the same way; see core/src/model-profile.
+export * from '@bendyline/gezel/local-loop';

package/dist/models/bundle-storage.d.ts

@@ -0,0 +1,28 @@
+/** Provider-owned view of an installed model used by the bundle exporter. */
+export interface ModelBundleSource {
+    id: string;
+    name: string;
+    modelDir: string;
+    installedManifest: Record<string, unknown>;
+    /** Model-dir-relative POSIX paths. `manifest.json` is intentionally absent. */
+    modelFiles: string[];
+    catalogVersion?: string;
+}
+/**
+ * Enumerate only ordinary files below `root`. Symbolic links and other special
+ * entries are refused rather than followed; a model export must never smuggle
+ * bytes from outside its provider-owned directory into a share bundle.
+ */
+export declare function listBundleModelFiles(root: string): Promise<string[]>;
+export declare function safeBundleModelPath(root: string, rel: string): string;
+/**
+ * Atomically publish a fully-scanned staged model directory. Replacement keeps
+ * the old install beside the target until the final rename succeeds, then
+ * removes the backup. A failed publish restores the old directory.
+ */
+export declare function publishStagedModel(opts: {
+    modelsRoot: string;
+    id: string;
+    stagedModelDir: string;
+    replace: boolean;
+}): Promise<void>;

package/dist/models/bundle-storage.js

@@ -0,0 +1,80 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readdir, rename, rm, stat } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+import { safeJoin } from '../fs/safe-paths.js';
+import { assertModelStorePathSafe } from './storage-roots.js';
+/**
+ * Enumerate only ordinary files below `root`. Symbolic links and other special
+ * entries are refused rather than followed; a model export must never smuggle
+ * bytes from outside its provider-owned directory into a share bundle.
+ */
+export async function listBundleModelFiles(root) {
+    const out = [];
+    const walk = async (dir) => {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            if (entry.isSymbolicLink()) {
+                throw new Error(`model contains a symbolic link, which cannot be exported: ${entry.name}`);
+            }
+            if (entry.isDirectory()) {
+                await walk(full);
+                continue;
+            }
+            if (!entry.isFile()) {
+                throw new Error(`model contains a non-regular file, which cannot be exported: ${entry.name}`);
+            }
+            const rel = relative(root, full).split(sep).join('/');
+            if (rel === 'manifest.json' || rel.endsWith('.partial'))
+                continue;
+            out.push(rel);
+        }
+    };
+    await walk(root);
+    return out.sort();
+}
+export function safeBundleModelPath(root, rel) {
+    const resolved = safeJoin(root, rel);
+    if (!resolved)
+        throw new Error(`unsafe model file path: ${rel}`);
+    return resolved;
+}
+/**
+ * Atomically publish a fully-scanned staged model directory. Replacement keeps
+ * the old install beside the target until the final rename succeeds, then
+ * removes the backup. A failed publish restores the old directory.
+ */
+export async function publishStagedModel(opts) {
+    await mkdir(opts.modelsRoot, { recursive: true });
+    const target = safeJoin(opts.modelsRoot, opts.id);
+    if (!target)
+        throw new Error(`unsafe model id: ${opts.id}`);
+    await assertModelStorePathSafe(opts.modelsRoot, target);
+    let exists = false;
+    try {
+        exists = (await stat(target)).isDirectory();
+    }
+    catch {
+        exists = false;
+    }
+    if (exists && !opts.replace) {
+        throw new Error(`model "${opts.id}" already exists locally`);
+    }
+    const backup = join(dirname(target), `.${opts.id}.gezmodel-backup-${randomUUID()}`);
+    if (exists)
+        await rename(target, backup);
+    let published = false;
+    try {
+        await rename(opts.stagedModelDir, target);
+        published = true;
+        await assertModelStorePathSafe(opts.modelsRoot, target);
+    }
+    catch (err) {
+        if (published)
+            await rm(target, { recursive: true, force: true }).catch(() => { });
+        if (exists)
+            await rename(backup, target).catch(() => { });
+        throw err;
+    }
+    if (exists)
+        await rm(backup, { recursive: true, force: true });
+}

package/dist/models/catalog-drift.d.ts

@@ -0,0 +1,48 @@
+/**
+ * "Is a newer build of this model available?" — asked of the payload, not of
+ * the version string.
+ *
+ * Both engine managers (llama.cpp/ds4 and MLX) and the chat manager's
+ * per-session staleness notice used to answer this by comparing the installed
+ * `catalogVersion` to the catalog's current one. That flags every catalog
+ * edit, including the metadata-only ones the runtime has already picked up,
+ * and the only remedy any surface offers is a multi-gigabyte re-download. Here
+ * the version difference is the *trigger* for a check, and
+ * {@link comparePayloadIdentity} is the answer.
+ *
+ * When the payload turns out to be unchanged we record that finding in the
+ * install manifest (a `payloadFingerprint`) so later checks are a string
+ * compare. `catalogVersion` is deliberately left alone: it means "the version
+ * whose description these bytes were downloaded against", which is what the
+ * `.gezmodel` exporter pins and what model-fitness records compare, and
+ * rewriting it would silently invalidate both.
+ */
+import { type ChatModelManifest, type GezmodelEngine } from '@bendyline/gezel';
+import { type InstalledPayloadRecord } from './catalog-payload-identity.js';
+export interface ModelUpdateStatus {
+    /** True only when the catalog's payload differs from the copy on disk. */
+    updateAvailable: boolean;
+    /** The catalog's current version, when it differs from the installed one. */
+    availableVersion?: string;
+    /** Why, in one sentence — surfaced in the model manager's tooltip. */
+    reason?: string;
+}
+export interface EvaluateCatalogDriftOptions {
+    engine: GezmodelEngine;
+    id: string;
+    /** Absolute model directory, for the size fallback and the fingerprint write. */
+    modelDir: string;
+    /** Version recorded at install. No version → nothing to compare. */
+    installedVersion?: string;
+    installed: InstalledPayloadRecord;
+    manifest: ChatModelManifest;
+    /**
+     * False for models resolved out of a read-only overlay (the machine asset
+     * store) and while an install is in flight for this id — the verdict still
+     * stands, we just don't write it down.
+     */
+    healable: boolean;
+}
+export declare function evaluateCatalogDrift(opts: EvaluateCatalogDriftOptions): Promise<ModelUpdateStatus>;
+/** Test seam — the dedupe set is process-global. */
+export declare function resetPayloadFingerprintHealsForTest(): void;

package/dist/models/catalog-drift.js

@@ -0,0 +1,94 @@
+/**
+ * "Is a newer build of this model available?" — asked of the payload, not of
+ * the version string.
+ *
+ * Both engine managers (llama.cpp/ds4 and MLX) and the chat manager's
+ * per-session staleness notice used to answer this by comparing the installed
+ * `catalogVersion` to the catalog's current one. That flags every catalog
+ * edit, including the metadata-only ones the runtime has already picked up,
+ * and the only remedy any surface offers is a multi-gigabyte re-download. Here
+ * the version difference is the *trigger* for a check, and
+ * {@link comparePayloadIdentity} is the answer.
+ *
+ * When the payload turns out to be unchanged we record that finding in the
+ * install manifest (a `payloadFingerprint`) so later checks are a string
+ * compare. `catalogVersion` is deliberately left alone: it means "the version
+ * whose description these bytes were downloaded against", which is what the
+ * `.gezmodel` exporter pins and what model-fitness records compare, and
+ * rewriting it would silently invalidate both.
+ */
+import { readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createLogger } from '@bendyline/gezel';
+import { catalogPayloadFingerprint, comparePayloadIdentity, describeCatalogPayload, } from './catalog-payload-identity.js';
+import { makeSharedModelReadable } from './storage-roots.js';
+const log = createLogger('models');
+/** In-process dedupe: model inventory is polled, and one heal per copy is enough. */
+const healed = new Set();
+export async function evaluateCatalogDrift(opts) {
+    const currentVersion = opts.manifest.version;
+    if (!opts.installedVersion || !currentVersion || opts.installedVersion === currentVersion) {
+        return { updateAvailable: false };
+    }
+    const catalog = describeCatalogPayload(opts.manifest, opts.engine);
+    if (!catalog) {
+        // The catalog no longer describes this engine's payload at all (a source
+        // block was pulled). Nothing to download, so nothing to offer.
+        return { updateAvailable: false };
+    }
+    const result = await comparePayloadIdentity({
+        catalog,
+        installed: opts.installed,
+        modelDir: opts.modelDir,
+    });
+    if (result.identity === 'same') {
+        if (opts.healable && result.provenByHash && !opts.installed.payloadFingerprint) {
+            await recordPayloadFingerprint(opts, catalogPayloadFingerprint(catalog), result);
+        }
+        return { updateAvailable: false };
+    }
+    if (result.identity === 'unknown') {
+        // Can't prove either way, so fall back to what the version string says.
+        // Being wrong here costs the user a badge, not their bandwidth — the
+        // update action stays theirs to take.
+        return {
+            updateAvailable: true,
+            availableVersion: currentVersion,
+            reason: `The catalog has moved to v${currentVersion} and Gezel could not confirm whether this copy's files changed (${result.reason}).`,
+        };
+    }
+    return {
+        updateAvailable: true,
+        availableVersion: currentVersion,
+        reason: `${result.reason}. Updating downloads only the files that differ.`,
+    };
+}
+async function recordPayloadFingerprint(opts, fingerprint, result) {
+    const manifestPath = join(opts.modelDir, 'manifest.json');
+    if (healed.has(manifestPath))
+        return;
+    healed.add(manifestPath);
+    try {
+        const parsed = JSON.parse(await readFile(manifestPath, 'utf8'));
+        if (parsed.payloadFingerprint === fingerprint)
+            return;
+        const tmpPath = `${manifestPath}.heal.tmp`;
+        await writeFile(tmpPath, `${JSON.stringify({ ...parsed, payloadFingerprint: fingerprint }, null, 2)}\n`, { encoding: 'utf8' });
+        await rename(tmpPath, manifestPath);
+        // A machine service writes into the shared asset store under a private
+        // umask; without this the healed manifest becomes unreadable to the very
+        // desktop clients that list the model.
+        await makeSharedModelReadable(opts.modelDir);
+        log.info(`[${opts.engine}] "${opts.id}" is current with catalog v${opts.manifest.version} despite installing at v${opts.installedVersion} — ${result.reason}; recorded payload fingerprint`);
+    }
+    catch (err) {
+        // A heal we couldn't write is a heal we redo next boot. Never let it
+        // break a listing.
+        healed.delete(manifestPath);
+        log.debug(`[${opts.engine}] could not record payload fingerprint for "${opts.id}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Test seam — the dedupe set is process-global. */
+export function resetPayloadFingerprintHealsForTest() {
+    healed.clear();
+}

package/dist/models/catalog-payload-identity.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Does the catalog still describe the bytes this model was installed from?
+ *
+ * A catalog version bump means one of two very different things. Either the
+ * payload moved — new repo, new quant, rotated shas, an added shard — and the
+ * user really is running an older build; or only metadata changed (tuning,
+ * sizing hints, release date, wording), which the runtime already resolves
+ * live from the catalog on every turn and which nothing on disk has to catch
+ * up with. Comparing version strings cannot tell those apart, so a metadata
+ * edit asked every installed model to re-download itself: five models, ~100 GB
+ * of transfer, to adopt a `residentBytes` removal that had already taken
+ * effect. This module asks the question the version string was standing in
+ * for.
+ *
+ * Three tiers, most conclusive first:
+ *
+ *   1. `payloadFingerprint` — a hash of the catalog's own payload description,
+ *      snapshotted into the install manifest at download time. Recomputing it
+ *      from the current catalog is an exact answer for free.
+ *   2. `fileSha256` — the per-file digests every install records. Compare them
+ *      to the catalog's pins file by file.
+ *   3. On-disk sizes vs the catalog's `sizeBytes`. All that installs predating
+ *      the hash map can offer; strong evidence across a multi-shard payload,
+ *      but evidence, not proof — so it never upgrades an install to tier 1.
+ *
+ * A sibling check lives in `shared-model-migration.ts`
+ * (`assertCatalogPayloadIntegrity`). It answers a different question — may
+ * these bytes be admitted to the machine-wide store — and stays a hard
+ * assertion over a freshly-hashed bundle. This one is a read-only comparison
+ * over what the install already recorded, and its answers steer UI, never
+ * trust.
+ */
+import type { ChatModelManifest, GezmodelEngine } from '@bendyline/gezel';
+/** One file the catalog expects to land in the model directory. */
+export interface CatalogPayloadFile {
+    /** Name as it lands on disk ('/'-joined for nested files, as in `fileSha256`). */
+    name: string;
+    sha256: string;
+    sizeBytes?: number;
+    /**
+     * Absent-on-disk is legitimate for this file. llama.cpp's vision projector
+     * is only fetched when the user opts into it, so a text-only install of a
+     * multimodal model is complete without it.
+     */
+    optional?: boolean;
+    /**
+     * Install rewrites this file after verifying it, so its recorded hash is
+     * ours rather than the catalog's. Only presence can be asserted. Today
+     * that is `tokenizer_config.json` on MLX entries that carry a chat-template
+     * fallback.
+     */
+    transformed?: boolean;
+}
+/** The catalog's description of one engine's payload for one model. */
+export interface CatalogPayload {
+    huggingfaceRepo: string;
+    files: CatalogPayloadFile[];
+    /**
+     * Catalog-pinned chat template. Part of the payload's identity because
+     * installing it mutates a file on disk — a change here is a change to what
+     * a fresh install would produce.
+     */
+    chatTemplate?: string;
+}
+export type PayloadIdentity = 'same' | 'changed' | 'unknown';
+/** Which tier answered — recorded in logs so a surprising verdict is traceable. */
+export type PayloadIdentityBasis = 'fingerprint' | 'hashes' | 'sizes' | 'repo' | 'none';
+export interface PayloadIdentityResult {
+    identity: PayloadIdentity;
+    basis: PayloadIdentityBasis;
+    /** One sentence, safe to log and to show in a tooltip. */
+    reason: string;
+    /**
+     * True when the verdict is `same` and was proven by hash — the caller may
+     * record the fingerprint so later checks land on tier 1. A size-only match
+     * never sets this.
+     */
+    provenByHash?: boolean;
+}
+/** The fields an install manifest contributes to the comparison. */
+export interface InstalledPayloadRecord {
+    huggingfaceRepo?: string;
+    payloadFingerprint?: string;
+    /** sha256 by '/'-joined relative path, recorded at install time. */
+    fileSha256?: Record<string, string>;
+}
+export interface ComparePayloadOptions {
+    catalog: CatalogPayload;
+    installed: InstalledPayloadRecord;
+    /** Model directory on disk. Without it the size fallback cannot run. */
+    modelDir?: string;
+    /** Test seam; returns null when the file is absent. */
+    statSize?: (absolutePath: string) => Promise<number | null>;
+}
+/**
+ * Stable hash of a catalog payload description. Deliberately excludes
+ * `revision`: it is a fetch coordinate, and identical hashes mean identical
+ * bytes no matter which commit served them.
+ */
+export declare function catalogPayloadFingerprint(payload: CatalogPayload): string;
+/**
+ * Translate a catalog manifest into the payload one engine would install.
+ * The single place that knows each source block's shape, so callers compare
+ * like for like without re-deriving filenames.
+ */
+export declare function describeCatalogPayload(manifest: ChatModelManifest, engine: GezmodelEngine): CatalogPayload | null;
+export declare function comparePayloadIdentity(opts: ComparePayloadOptions): Promise<PayloadIdentityResult>;