@atomic-chat/core 0.5.1 → 0.13.2

package/dist/runtime/managed-models/check.js

@@ -0,0 +1,157 @@
+/**
+ * `POST /atomic/v1/models/:provider/check` for every managed engine (spec `managed-model-store`,
+ * "Проверка совместимости одинакова по форме для всех managed-движков"; change `add-vllm-runtime`,
+ * task 2.3): wires the pure `checkCheckpoint` (`compatibility.ts`) to the pinned descriptor of that
+ * engine's ready installation — or, "если движок не установлен", that engine's latest accepted cached
+ * descriptor (`descriptors.cachedForNewSetup(engine)`), never another engine's — and to the host's
+ * GPUs and memory. Never fetches: `descriptorForCheck` below only ever reads
+ * `forInstallation`/`cachedForNewSetup`, both cache-only (`descriptor-provider.ts`), and `hostFacts`
+ * is the check route's own Docker-free probe — matching the spec's "Core MUST NOT обращаться в сеть
+ * при проверке".
+ *
+ * Body validation lives here, not in the pure module: `checkCheckpoint` trusts its typed input
+ * completely, so an HTTP body that does not even shape up as one is refused with `INVALID_ARGUMENT`
+ * before it ever reaches that function, the same way `routes/environments.ts` validates its own
+ * request bodies.
+ */
+import { AtomicCoreError } from '../../contracts/index.js';
+import { checkCheckpoint, normalizeWeightNames } from './compatibility.js';
+const invalid = (why, details) => {
+    throw new AtomicCoreError('INVALID_ARGUMENT', why, details);
+};
+const object = (value, at) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : invalid(`${at} must be an object.`);
+const known = (source, at, keys) => {
+    const extra = Object.keys(source).filter((key) => !keys.includes(key));
+    if (extra.length > 0)
+        invalid(`${at} has fields this core does not know.`, extra.sort().join(', '));
+};
+const nonEmptyString = (value, at) => typeof value === 'string' && value !== '' ? value : invalid(`${at} must be a non-empty string.`);
+const jsonObject = (value, at) => object(value, at);
+const nullableJsonObject = (value, at) => value === null || value === undefined ? null : object(value, at);
+const fileSize = (value, at) => typeof value === 'number' && Number.isFinite(value) && value >= 0
+    ? value
+    : invalid(`${at} must be a non-negative number.`);
+const fileSha256 = (value, at) => {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string')
+        return value;
+    return invalid(`${at} must be a string or null.`);
+};
+const checkpointFile = (value, at) => {
+    const raw = object(value, at);
+    return {
+        path: nonEmptyString(raw['path'], `${at}.path`),
+        size: fileSize(raw['size'], `${at}.size`),
+        sha256: fileSha256(raw['sha256'], `${at}.sha256`),
+    };
+};
+const files = (value, at) => Array.isArray(value)
+    ? value.map((entry, index) => checkpointFile(entry, `${at}[${index}]`))
+    : invalid(`${at} must be an array.`);
+const optionalGpuId = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    return invalid('gpu_id must be a string.');
+};
+/** Folded and de-duplicated here as well, so a caller that sends the raw index keys costs no more. */
+const optionalWeightNames = (value) => {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Array.isArray(value))
+        return invalid('weight_names must be an array of strings.');
+    return normalizeWeightNames(value.map((name, index) => nonEmptyString(name, `weight_names[${index}]`)));
+};
+/** `INVALID_ARGUMENT` for anything that does not shape up as `ModelCheckInput`; every field the spec names. */
+export function parseModelCheckInput(body) {
+    const raw = object(body, 'the request');
+    known(raw, 'the request', [
+        'repository',
+        'revision',
+        'config_json',
+        'hf_quant_config_json',
+        'files',
+        'gpu_id',
+        'weight_names',
+    ]);
+    const gpuId = optionalGpuId(raw['gpu_id']);
+    const weightNames = optionalWeightNames(raw['weight_names']);
+    return {
+        repository: nonEmptyString(raw['repository'], 'repository'),
+        revision: nonEmptyString(raw['revision'], 'revision'),
+        config_json: jsonObject(raw['config_json'], 'config_json'),
+        hf_quant_config_json: nullableJsonObject(raw['hf_quant_config_json'], 'hf_quant_config_json'),
+        files: files(raw['files'], 'files'),
+        ...(gpuId === undefined ? {} : { gpu_id: gpuId }),
+        ...(weightNames === undefined ? {} : { weight_names: weightNames }),
+    };
+}
+/**
+ * The descriptor to check against: the `ready` installation of `engineId` with its pinned descriptor
+ * when there is one, else that engine's latest accepted cached descriptor — spec "по закреплённому
+ * дескриптору установки этого движка (или по актуальному дескриптору этого движка, если движок не
+ * установлен)". Throws the descriptor provider's own `MANAGED_METADATA_INVALID` when neither is
+ * available (nothing has ever been cached for this engine).
+ */
+export async function descriptorForCheck(engineId, deps) {
+    const ours = (await deps.installations.list())
+        .map((record) => record.installation)
+        .filter((installation) => installation.engine_id === engineId);
+    const ready = ours.find((installation) => installation.status === 'ready' && installation.active_descriptor_id !== null);
+    const resolved = ready !== undefined
+        ? await deps.descriptors.forInstallation(ready.active_descriptor_id)
+        : await deps.descriptors.cachedForNewSetup(engineId);
+    if (resolved.kind !== 'available')
+        throw resolved.error;
+    return resolved.descriptor;
+}
+/**
+ * The full route for one engine: validate, resolve the descriptor and host facts (in parallel), then
+ * the pure check. Without an explicit `gpu_id` in the request, checks against the card a real load
+ * would pick — the provider's own stored `gpu_id` setting, falling back to `selectLaunchGpu`'s "most
+ * free memory, then most total memory" rule only when nothing is saved or the saved card is gone
+ * (design D12b of change `add-tensorrt-llm-linux`) — so the verdict and the launch cannot be about
+ * different cards.
+ */
+export async function checkManagedModel(engine, body, deps) {
+    const input = parseModelCheckInput(body);
+    const [descriptor, facts] = await Promise.all([descriptorForCheck(engine.engineId, deps), deps.hostFacts()]);
+    const settings = deps.settings();
+    const gpuId = input.gpu_id ?? engine.gpuIdOf(settings) ?? undefined;
+    const verdict = checkCheckpoint({ ...input, ...(gpuId === undefined ? {} : { gpu_id: gpuId }) }, descriptor, facts.gpus, facts.memory, engine.checkEngineOf(settings));
+    return deps.wslVm === undefined ? verdict : withVmMemoryWarning(verdict, facts.memory, await deps.wslVm());
+}
+const GIB = 1024 ** 3;
+const gib = (bytes) => `${(bytes / GIB).toFixed(1)} GiB`;
+/**
+ * On Windows the weights are read into the WSL VM, whose memory is by default half of the RAM (design
+ * D11): fewer bytes of VM than of weights is a warning — they stream, slower — never a refusal, which
+ * would cut off models that do run.
+ */
+function withVmMemoryWarning(verdict, memory, vm) {
+    if (!verdict.verdict.ok || memory.totalBytes <= 0 || memory.totalBytes >= verdict.weight_bytes)
+        return verdict;
+    const setting = vm.memory_setting === null
+        ? 'It is not set in %UserProfile%\\.wslconfig, so WSL uses half of this computer’s memory.'
+        : `%UserProfile%\\.wslconfig sets it to ${vm.memory_setting}.`;
+    return {
+        ...verdict,
+        warnings: [
+            {
+                code: 'wsl-vm-memory',
+                message: `The WSL VM has ${gib(memory.totalBytes)} of memory, less than this model’s ${gib(verdict.weight_bytes)} of weights: ` +
+                    `it should still load, but more slowly. ${setting} You can raise it with memory= in the [wsl2] section of that file, then run wsl --shutdown.`,
+                params: {
+                    vm_memory_bytes: String(memory.totalBytes),
+                    weight_bytes: String(verdict.weight_bytes),
+                    wslconfig_memory: vm.memory_setting ?? '',
+                },
+            },
+        ],
+    };
+}
+//# sourceMappingURL=check.js.map

package/dist/runtime/managed-models/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../../src/runtime/managed-models/check.ts"],"names":[],"mappings":"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"}

package/dist/runtime/managed-models/compatibility.d.ts

@@ -0,0 +1,256 @@
+/**
+ * The compatibility check every managed engine shares (change `add-vllm-runtime`, design D7; spec
+ * `managed-model-store`, "Проверка совместимости одинакова по форме для всех managed-движков"):
+ * whether a Hugging Face checkpoint can run on one engine on this host, computed entirely from what
+ * the caller already has — `config.json`, `hf_quant_config.json` when the repository carries one, the
+ * revision's file listing, that engine's pinned `RuntimeDescriptor`, the host's `GpuFacts[]` and its
+ * `MemAvailable`/`MemTotal` (`HostMemory`) — before a single byte of the checkpoint is downloaded.
+ *
+ * The skeleton is the same for every engine; two things are the engine's own, passed in as a
+ * `ManagedCheckEngine`: `memoryNeed`, what the checkpoint needs on a card by that engine's own
+ * memory rule (TensorRT-LLM: its KV reserve divided by the free-memory fraction plus its runtime and
+ * activations; vLLM: weights plus KV in bytes plus its overhead), and `checkpointProblems`, shapes of
+ * a supported architecture the engine's loader cannot read. The engine's descriptor decides the rest:
+ * its architectures and its format matrix. Neither the hooks nor the adapter are the same thing — the
+ * check runs with no Docker and no load lifecycle at all.
+ *
+ * This is the pure verdict only: it never touches the network or the filesystem. `selectLaunchGpu` is
+ * exported on its own because a load picks the same card the same way.
+ *
+ * Check order: GGUF is rejected outright before anything else (spec: "for GGUF there is
+ * llama.cpp"), then a curated match's `inventory_digest` is verified — an integrity gate that is
+ * independent of whether the checkpoint would otherwise load, so a tampered curated listing is
+ * reported as `MANAGED_METADATA_INVALID` rather than whatever compatibility error the tampered
+ * files happen to also trigger. Only then: quantization format recognised by the shared naming rule,
+ * architecture supported, the engine's checkpoint problems, format present in this descriptor's own
+ * matrix, the file listing has at least one weight file, the format's compute-capability rule
+ * (minimum and exclusion list) — everything above is genuinely static, true or false regardless of
+ * what else is running on the host — and finally the engine's memory need against the selected
+ * card's free memory.
+ *
+ * `checkCheckpoint` runs every check as one call, for the check route's single live snapshot. The
+ * load path cannot: a pre-launch check runs before the previous session on the very same card is
+ * stopped, so reading that card's free memory then would refuse a same-card model switch outright.
+ * `checkCheckpointFiles` is every check above the memory line, and `checkCheckpointMemory` is the
+ * memory line alone, so a load can run the first before stopping the previous session and the second
+ * after it, against a freshly re-probed card.
+ */
+import type { GpuFacts, ModelCompatibility, RuntimeDescriptor } from '../../contracts/index.js';
+import type { JsonObject } from './quant-format.js';
+/** One file of the revision's listing, as the route contract carries it (spec `managed-model-store`). */
+export interface CheckpointFile {
+    /** Repository-relative, forward slashes, as Hugging Face spells it. */
+    path: string;
+    size: number;
+    /** The repository's own published digest, or `null` when it has none (a non-LFS file). */
+    sha256: string | null;
+}
+/** Input to `checkCheckpoint`, matching what `POST /models/:provider/check` accepts. */
+export interface ModelCheckInput {
+    repository: string;
+    revision: string;
+    config_json: JsonObject;
+    /** `null` when the repository does not carry the file at all. */
+    hf_quant_config_json: JsonObject | null;
+    files: CheckpointFile[];
+    /** Omitted or not found on this host falls back to `selectLaunchGpu`'s "most free memory" rule. */
+    gpu_id?: string;
+    /**
+     * The checkpoint's tensor names, read from the headers of its weight `.safetensors` files (never
+     * from `model.safetensors.index.json`, which can be stale or another model's), with numeric path
+     * segments optionally folded to `*` (`normalizeWeightName`). Omitted when the caller could not
+     * read the headers or predates the field: the checks that need tensor names are then skipped,
+     * never failed.
+     */
+    weight_names?: string[];
+}
+/**
+ * `model.layers.12.mlp.experts.7.w1.weight` → `model.layers.*.mlp.experts.*.w1.weight`: a large MoE
+ * index (DeepSeek-V3: ~90k names) folds to a few hundred, and no shape check here looks at indices.
+ */
+export declare function normalizeWeightName(name: string): string;
+/** Folded and de-duplicated tensor names, in a stable order. */
+export declare function normalizeWeightNames(names: Iterable<string>): string[];
+/** The header length a `.safetensors` file's first 8 bytes declare (little-endian u64); `undefined` if implausible. */
+export declare function safetensorsHeaderLength(prefix: Uint8Array): number | undefined;
+/** The tensor names a parsed safetensors header lists (its keys, minus `__metadata__`); `undefined` if it is not an object. */
+export declare function safetensorsTensorNames(header: unknown): string[] | undefined;
+/**
+ * Architectures whose MoE layers TensorRT-LLM builds with `DeepseekV3Gate`, which refuses to load
+ * without an `e_score_correction_bias` tensor next to the router weight (TensorRT-LLM v1.3.0rc29,
+ * `_torch/models/modeling_deepseekv3.py` `DeepseekV3Gate.load_weights`; `modeling_glm.py` builds
+ * `Glm4Moe` with the same gate). `NemotronH*` also uses the gate, but only in its MoE layers, and a
+ * dense Nemotron-H has none, so it is not listed: a rule here must never refuse a model that loads.
+ */
+/**
+ * The host's own memory, from `/proc/meminfo`: what a unified-memory card (design D13, GB10/DGX
+ * Spark — `nvidia-smi` reports no memory of its own) has instead of VRAM. `availableBytes` is
+ * `MemAvailable`, what such a card has free; `totalBytes` is `MemTotal`, its size. Either is `0`
+ * when the file could not be read — the safe direction: a unified-memory card then under-reports.
+ */
+export interface HostMemory {
+    availableBytes: number;
+    totalBytes: number;
+}
+/**
+ * The card a load runs on, and the card `POST /models/:provider/check` computes against when the
+ * caller names none — one function for both, so a verdict and a launch can never be about different
+ * cards (spec `tensorrt-llm-runtime` "Выбор карты и настройки провайдера", design D12b). `gpu_id`
+ * when given and present on the host; otherwise the card with the most FREE memory right now, ties
+ * broken by the most TOTAL memory, and a full tie by the order `nvidia-smi` lists the cards in (its
+ * own index, stable on a host), so equal cards always resolve the same way. `null` only when the host
+ * has no GPU at all.
+ *
+ * Free memory, not total: on a desktop with two equal cards the first is usually holding the
+ * desktop and a browser, and "the biggest card" would send the model there to run out of memory
+ * while the second card sits idle. Placement may therefore change between loads as the cards' load
+ * changes; the engine cache is keyed by model, not by card, so that only moves where it runs.
+ * Compute capability is deliberately not a filter here: the spec's rule is memory only, and a card
+ * the checkpoint's format cannot run on gets an honest `MODEL_INCOMPATIBLE` naming the other cards
+ * it would fit on (`fits_other_gpus`).
+ *
+ * A unified-memory card (`total_vram_bytes: null`) ranks by the host's memory — `MemAvailable` as
+ * its free memory and `MemTotal` as its total — the same figure `freeMemoryBytes` compares its
+ * memory need against.
+ */
+export declare function selectLaunchGpu(gpus: readonly GpuFacts[], host: HostMemory, gpuId?: string): GpuFacts | null;
+/** The weight files whose safetensors headers hold the checkpoint's tensor names (legacy `.bin`/`.pth` excluded). */
+export declare function weightSafetensorsFiles(files: readonly CheckpointFile[]): readonly CheckpointFile[];
+/** Weight bytes for the memory check: the sum of `selectWeightFiles(files)`. */
+export declare function weightBytes(files: readonly CheckpointFile[]): number;
+/**
+ * A finite, positive number read from `configJson[key]`; `undefined` for anything else (missing,
+ * the wrong type, zero, negative, `NaN`/`Infinity`) — every field the KV-cache formula below needs
+ * is a strictly positive count or dimension, and treating `0` or a negative value as "present" would
+ * size a KV cache of zero or negative bytes, silently passing a check that should have fallen back.
+ */
+export declare function positiveNumberField(configJson: JsonObject, key: string): number | undefined;
+export interface KvCacheShape {
+    numHiddenLayers: number;
+    numKeyValueHeads: number;
+    headDim: number;
+}
+/**
+ * The architecture fields a transformer's KV-cache size is computed from, with the two standard
+ * fallbacks: `num_key_value_heads` falls back to `num_attention_heads` (plain multi-head attention —
+ * every attention head is its own KV head, the GQA/MQA field simply absent) and `head_dim` falls
+ * back to `hidden_size / num_attention_heads` (the standard derivation, for a config that does not
+ * spell `head_dim` out explicitly). `undefined` when `config.json` lacks what even the fallbacks
+ * need — `kvCacheBytes` then has nothing to compute from, and `kvCacheReserveBytes` falls back to
+ * the older weight-proportional rule.
+ */
+export declare function readKvCacheShape(rootConfigJson: JsonObject): KvCacheShape | undefined;
+/**
+ * The KV cache's own footprint for one sequence at `contextLength` tokens:
+ * `2 × num_hidden_layers × num_key_value_heads × head_dim × kv_dtype_bytes × context_length` — one
+ * K tensor and one V tensor (the leading `2`) per layer, each holding `context_length` tokens of
+ * `num_key_value_heads × head_dim` values at `kv_dtype_bytes` each. `kv_dtype_bytes` is `1` when
+ * `kvCacheQuantAlgo` names `FP8`, else `2` (`bf16`/`fp16`, this engine's other supported weight
+ * dtypes). `undefined` when `config.json` lacks the architecture fields `readKvCacheShape` needs.
+ */
+export declare function kvCacheBytes(configJson: JsonObject, hfQuantConfigJson: JsonObject | null, contextLength: number): number | undefined;
+/** A card with no VRAM figure of its own (GB10/DGX Spark, design D13): its memory is the host's. */
+export declare function isUnifiedMemory(gpu: GpuFacts): boolean;
+/** Free memory to compare against for one card: `MemAvailable` for a unified-memory card (design D13). */
+export declare function freeMemoryBytes(gpu: GpuFacts, host: HostMemory): number;
+/** A card's size, for ranking only: `MemTotal` for a unified-memory card (design D13). */
+export declare function totalMemoryBytes(gpu: GpuFacts, host: HostMemory): number;
+/** How an engine sized a KV-cache reserve — carried into `ModelCompatibility.kv_reserve_basis`. */
+export type KvReserveBasis = 'config' | 'weight_fraction';
+/** The checkpoint as an engine's memory rule sees it. */
+export interface CheckpointMemoryInputs {
+    weightBytesTotal: number;
+    configJson: JsonObject;
+    hfQuantConfigJson: JsonObject | null;
+}
+/** What a checkpoint needs on one card by an engine's own memory rule. */
+export interface MemoryNeed {
+    neededBytes: number;
+    /** How the engine sized its KV cache, when it says (`kv_reserve_basis` of the verdict). */
+    kvReserveBasis?: KvReserveBasis;
+    /** `key=value` numbers for a refusal's `details`; the skeleton appends `free_bytes=…`. */
+    details: string;
+}
+/** A reason a supported architecture's checkpoint still cannot load on this engine. */
+export interface CheckpointProblem {
+    message: string;
+    details: string;
+}
+/**
+ * What one engine adds to the shared skeleton (design D7): its id for messages, its loader's
+ * checkpoint quirks and its memory rule. Part of the engine's spec, never of its adapter.
+ */
+export interface ManagedCheckEngine {
+    /** `tensorrt-llm`, `vllm`: the provider id, in messages. */
+    engineId: string;
+    checkpointProblems(architecture: string, configJson: JsonObject, weightNames: readonly string[] | undefined): CheckpointProblem | null;
+    memoryNeed(gpu: GpuFacts, checkpoint: CheckpointMemoryInputs, hostMemory: HostMemory): MemoryNeed;
+}
+/**
+ * Everything `checkCheckpointMemory` needs about the checkpoint once every non-memory check has passed.
+ * `configJson`/`hfQuantConfigJson` travel here (rather than being re-passed alongside `sizing`)
+ * because they are exactly `input.config_json`/`input.hf_quant_config_json` as
+ * `checkCheckpointFiles` already read them — carrying its own copy here means
+ * `checkCheckpointMemory` can never be called with a `config.json` that disagrees with the one the rest
+ * of the verdict was computed from.
+ */
+export interface ResolvedCheckpoint {
+    architectures: string[];
+    /** Never null here: `checkCheckpointFiles` only returns this once a format was recognised. */
+    quantizationFormat: string;
+    weightBytesTotal: number;
+    selected: GpuFacts;
+    curated: boolean;
+    configJson: JsonObject;
+    hfQuantConfigJson: JsonObject | null;
+}
+export type FilesCheckResult = {
+    ok: true;
+    resolved: ResolvedCheckpoint;
+} | {
+    ok: false;
+    verdict: ModelCompatibility;
+};
+/**
+ * Throws `AtomicCoreError` for two caller-input problems that are never a fact about the checkpoint
+ * itself: `INVALID_ARGUMENT` when the file listing names `hf_quant_config.json` while
+ * `hf_quant_config_json` is `null` (the caller said the file exists but did not send its content, so
+ * the format naming rule cannot be trusted), and `MANAGED_PREREQUISITE_BLOCKED` when the host has no
+ * GPU at all (`gpus` empty — the same code, and the same host condition, `runtime.ts`'s own
+ * `selectLaunchGpu` check already answers with for a real load; task 2.16w round 1, finding 11:
+ * an absent or failing `nvidia-smi` is a missing prerequisite, not a malformed request).
+ * `inventoryDigest` can also throw `AtomicCoreError('MANAGED_METADATA_INVALID', …)` for a curated
+ * match whose file listing is itself malformed (an empty or repeated path, a NUL byte, a
+ * non-integer size — see `src/runtime/environment/inventory.ts`), before this function gets a
+ * chance to compare digests. Every other input, however incompatible, is a normal `verdict.ok: false`
+ * answer, never a thrown error (design D12: the point of this check is to hand back numbers, not to
+ * fail the request).
+ *
+ * Every check above the memory line: GGUF, the curated digest, the quantization format, the
+ * architecture, the format's presence in this descriptor and its compute-capability rule. None of
+ * these can change by evicting whatever session currently holds the selected card, so all of them
+ * run before `stopPrevious` on the load path (task 2.16w round 1, finding 1). `fits_other_gpus` on a
+ * compute-capability failure is still computed here (`memory` sizes the reserve needed to report it),
+ * using whichever `gpus`/`hostMemory` snapshot the caller passed in — informational only,
+ * about *other* cards the eviction race does not touch.
+ */
+export declare function checkCheckpointFiles(input: ModelCheckInput, descriptor: RuntimeDescriptor, gpus: readonly GpuFacts[], hostMemory: HostMemory, engine: ManagedCheckEngine): FilesCheckResult;
+/**
+ * The memory line alone (task 2.16w round 1, finding 1): whether `resolved.weightBytesTotal` plus
+ * the KV-cache reserve fits the selected card's free memory. Callers pass a fresh `gpus`/
+ * `hostMemory` snapshot — the load path's `beforeCreate` hook re-probes the host after
+ * `stopPrevious` has run, so this sees whatever that freed, never a snapshot taken before it — and
+ * this function re-reads the free-memory figure for `resolved.selected.gpu_id` from *that* fresh
+ * `gpus`, rather than trusting `resolved.selected`'s own (possibly stale) copy: that stale copy is
+ * only a fallback for the case `gpus` no longer lists the card at all (it disappeared), which
+ * `runtime.ts`'s own `beforeCreate` hook checks for and reports as `MANAGED_PREREQUISITE_BLOCKED`
+ * before ever calling this. This never picks a *different* card — the caller already committed to
+ * this exact one (`checkModelCompatibilityFiles`, or a load's own `selectLaunchGpu`).
+ */
+export declare function checkCheckpointMemory(resolved: ResolvedCheckpoint, descriptor: RuntimeDescriptor, gpus: readonly GpuFacts[], hostMemory: HostMemory, engine: ManagedCheckEngine): ModelCompatibility;
+/**
+ * The full verdict: `checkCheckpointFiles` then, if it passed, `checkCheckpointMemory` — for the check
+ * route's single live snapshot, where there is no previous session on the selected card to evict
+ * first. The load path runs the two separately instead (see the file banner).
+ */
+export declare function checkCheckpoint(input: ModelCheckInput, descriptor: RuntimeDescriptor, gpus: readonly GpuFacts[], hostMemory: HostMemory, engine: ManagedCheckEngine): ModelCompatibility;