@atomic-chat/core 0.5.1 → 0.13.6

package/dist/runtime/tensorrt-llm/model-dir.js

@@ -0,0 +1,137 @@
+/**
+ * Reading an installed `tensorrt-llm` model's directory under `<data>/tensorrt-llm/models/`: its
+ * `model.yml` (`parseTensorrtLlmModelYml`, task 2.16 — the TRT-specific schema documented in
+ * `docs/contracts.md`: `repository`, `revision`, `architectures`, `quantization`, `files` with
+ * `path`/`size`/`sha256`) and the few derived facts a load needs — the first architecture (for the
+ * descriptor's `model_families` entry) and the weight bytes (for the readiness timeout). The app and
+ * the CLI write the directory and its `model.yml` last (spec `tensorrt-llm-models`); a directory
+ * without one is a download still in progress and is not a model.
+ *
+ * `readTensorrtLlmModel` is the single-id lookup `TensorrtLlmRuntime.load` uses (task 2.14); the full
+ * `ModelRegistry` scan across every installed model (`registry.ts`, task 2.16) shares
+ * `parseTensorrtLlmModelYml` with it, so both agree about what `model.yml` means.
+ */
+import { readFile } from 'node:fs/promises';
+import { join, relative, isAbsolute } from 'node:path';
+import { parse } from 'yaml';
+import { AtomicCoreError } from '../../contracts/index.js';
+import { MODEL_YML, modelDirFromId } from '../../config/index.js';
+import { weightBytes } from './compatibility.js';
+/** An id is one or more `/`-separated path segments inside the models directory, never out of it. */
+function assertModelId(modelsDir, modelId) {
+    const segments = modelId.split('/');
+    if (modelId === '' || segments.some((s) => s === '' || s === '.' || s === '..' || s.includes('\\'))) {
+        throw new AtomicCoreError('INVALID_ARGUMENT', 'Not a tensorrt-llm model id.', modelId);
+    }
+    const dir = modelDirFromId(modelsDir, modelId);
+    const inside = relative(modelsDir, dir);
+    if (inside === '' || inside.startsWith('..') || isAbsolute(inside)) {
+        throw new AtomicCoreError('INVALID_ARGUMENT', 'Not a tensorrt-llm model id.', modelId);
+    }
+    return dir;
+}
+/**
+ * A relative file path safe to join onto the model directory and mount read-only into a container:
+ * forward-slash separated, never absolute, no empty/`.`/`..` segment and no backslash (which some
+ * shells would treat as an escape on the file's own leaf name).
+ */
+function isSafeRelativePath(path) {
+    if (path === '' || path.startsWith('/') || path.includes('\\'))
+        return false;
+    return path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}
+/**
+ * One `model.yml` `files[]` entry, strictly: `MANAGED_METADATA_INVALID` for anything malformed
+ * (task 2.16w round 1, finding 4) — a non-string or unsafe `path`, a `size` that is not a finite
+ * non-negative integer, a `sha256` that is neither a string nor `null`. The previous, lenient
+ * parsing silently dropped a malformed entry instead: an unverified shard the pre-launch check would
+ * never even look for, a checkpoint's weight bytes under-counted, or an `hf_quant_config.json` entry
+ * quietly lost — every one of those is worse than refusing the model outright and naming why.
+ */
+function parseFileEntry(raw, index, path) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new AtomicCoreError('MANAGED_METADATA_INVALID', `${path}: files[${index}] is not a mapping.`, JSON.stringify(raw));
+    }
+    const entry = raw;
+    if (typeof entry.path !== 'string' || !isSafeRelativePath(entry.path)) {
+        throw new AtomicCoreError('MANAGED_METADATA_INVALID', `${path}: files[${index}].path is not a safe relative path.`, String(entry.path));
+    }
+    if (typeof entry.size !== 'number' || !Number.isInteger(entry.size) || entry.size < 0) {
+        throw new AtomicCoreError('MANAGED_METADATA_INVALID', `${path}: files[${index}].size must be a non-negative integer.`, String(entry.size));
+    }
+    if (entry.sha256 !== undefined && entry.sha256 !== null && typeof entry.sha256 !== 'string') {
+        throw new AtomicCoreError('MANAGED_METADATA_INVALID', `${path}: files[${index}].sha256 must be a string or null.`, String(entry.sha256));
+    }
+    return {
+        path: entry.path,
+        size: entry.size,
+        sha256: typeof entry.sha256 === 'string' ? entry.sha256 : null,
+    };
+}
+/** `files` absent entirely is tolerated as `[]` (a bare `model.yml` is still a model); once present, every entry must be well-formed. */
+function fileList(raw, path) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new AtomicCoreError('MANAGED_METADATA_INVALID', `${path}: files must be an array.`, JSON.stringify(raw));
+    }
+    return raw.map((entry, index) => parseFileEntry(entry, index, path));
+}
+/**
+ * `model.yml`'s codec (`parse` only — the app and the CLI write it, core never does, spec
+ * `tensorrt-llm-models`): `MANAGED_METADATA_INVALID` when `text` is not valid YAML or not a mapping.
+ * `repository`/`revision`/`architectures`/`quantization` tolerate absence or the wrong type by
+ * reading as `null`/`[]`, the same way `readTensorrtLlmModel`'s own tests already expect for a bare
+ * `model.yml` — a model missing optional metadata is still a model, not a broken one. `files` is the
+ * one field held to a stricter rule (task 2.16w round 1, finding 4): the array itself may be absent
+ * (`[]`), but once present every entry must be well-formed (`fileList`/`parseFileEntry`) —
+ * silently dropping a malformed entry would leave a shard unverified, a checkpoint's weight bytes
+ * under-counted, or an `hf_quant_config.json` entry quietly lost.
+ */
+export function parseTensorrtLlmModelYml(text, path) {
+    let yml;
+    try {
+        yml = parse(text);
+    }
+    catch (error) {
+        throw new AtomicCoreError('MANAGED_METADATA_INVALID', `${path} is not valid YAML.`, String(error));
+    }
+    if (yml === null || typeof yml !== 'object' || Array.isArray(yml)) {
+        throw new AtomicCoreError('MANAGED_METADATA_INVALID', `${path} does not describe a model.`, path);
+    }
+    const doc = yml;
+    const architectures = Array.isArray(doc['architectures'])
+        ? doc['architectures'].filter((entry) => typeof entry === 'string' && entry !== '')
+        : [];
+    return {
+        repository: typeof doc['repository'] === 'string' ? doc['repository'] : null,
+        revision: typeof doc['revision'] === 'string' ? doc['revision'] : null,
+        architectures,
+        quantization: typeof doc['quantization'] === 'string' ? doc['quantization'] : null,
+        files: fileList(doc['files'], path),
+    };
+}
+/** `MODEL_NOT_FOUND` without a readable `model.yml`; `MANAGED_METADATA_INVALID` when it is not a mapping. */
+export async function readTensorrtLlmModel(modelsDir, modelId) {
+    const dir = assertModelId(modelsDir, modelId);
+    const path = join(dir, MODEL_YML);
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch {
+        throw new AtomicCoreError('MODEL_NOT_FOUND', `The tensorrt-llm model '${modelId}' is not installed.`, path);
+    }
+    const yml = parseTensorrtLlmModelYml(text, path);
+    return {
+        id: modelId,
+        dir,
+        repository: yml.repository,
+        revision: yml.revision,
+        architecture: yml.architectures[0] ?? null,
+        quantization: yml.quantization,
+        files: yml.files,
+        weightBytes: weightBytes(yml.files),
+    };
+}
+//# sourceMappingURL=model-dir.js.map

package/dist/runtime/tensorrt-llm/model-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-dir.js","sourceRoot":"","sources":["../../../src/runtime/tensorrt-llm/model-dir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAA;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAC1D,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AA4BhD,qGAAqG;AACrG,SAAS,aAAa,CAAC,SAAiB,EAAE,OAAe;IACvD,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACnC,IAAI,OAAO,KAAK,EAAE,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QACpG,MAAM,IAAI,eAAe,CAAC,kBAAkB,EAAE,8BAA8B,EAAE,OAAO,CAAC,CAAA;IACxF,CAAC;IACD,MAAM,GAAG,GAAG,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;IAC9C,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,CAAA;IACvC,IAAI,MAAM,KAAK,EAAE,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,eAAe,CAAC,kBAAkB,EAAE,8BAA8B,EAAE,OAAO,CAAC,CAAA;IACxF,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;GAIG;AACH,SAAS,kBAAkB,CAAC,IAAY;IACtC,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAA;IAC5E,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI,CAAC,CAAA;AAClG,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,cAAc,CAAC,GAAY,EAAE,KAAa,EAAE,IAAY;IAC/D,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,eAAe,CACvB,0BAA0B,EAC1B,GAAG,IAAI,WAAW,KAAK,qBAAqB,EAC5C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CACpB,CAAA;IACH,CAAC;IACD,MAAM,KAAK,GAAG,GAA2D,CAAA;IACzE,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,eAAe,CACvB,0BAA0B,EAC1B,GAAG,IAAI,WAAW,KAAK,qCAAqC,EAC5D,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CACnB,CAAA;IACH,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QACtF,MAAM,IAAI,eAAe,CACvB,0BAA0B,EAC1B,GAAG,IAAI,WAAW,KAAK,wCAAwC,EAC/D,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CACnB,CAAA;IACH,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC5F,MAAM,IAAI,eAAe,CACvB,0BAA0B,EAC1B,GAAG,IAAI,WAAW,KAAK,oCAAoC,EAC3D,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CACrB,CAAA;IACH,CAAC;IACD,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM,EAAE,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI;KAC/D,CAAA;AACH,CAAC;AAED,yIAAyI;AACzI,SAAS,QAAQ,CAAC,GAAY,EAAE,IAAY;IAC1C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,CAAA;IAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,eAAe,CACvB,0BAA0B,EAC1B,GAAG,IAAI,2BAA2B,EAClC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CACpB,CAAA;IACH,CAAC;IACD,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAA;AACtE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAY,EAAE,IAAY;IACjE,IAAI,GAAY,CAAA;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAA;IACnB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,eAAe,CAAC,0BAA0B,EAAE,GAAG,IAAI,qBAAqB,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;IACpG,CAAC;IACD,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,eAAe,CAAC,0BAA0B,EAAE,GAAG,IAAI,6BAA6B,EAAE,IAAI,CAAC,CAAA;IACnG,CAAC;IACD,MAAM,GAAG,GAAG,GAA8B,CAAA;IAC1C,MAAM,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;QACvD,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC;QACpG,CAAC,CAAC,EAAE,CAAA;IACN,OAAO;QACL,UAAU,EAAE,OAAO,GAAG,CAAC,YAAY,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI;QAC5E,QAAQ,EAAE,OAAO,GAAG,CAAC,UAAU,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI;QACtE,aAAa;QACb,YAAY,EAAE,OAAO,GAAG,CAAC,cAAc,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,IAAI;QAClF,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;KACpC,CAAA;AACH,CAAC;AAED,6GAA6G;AAC7G,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,SAAiB,EAAE,OAAe;IAC3E,MAAM,GAAG,GAAG,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;IAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;IACjC,IAAI,IAAY,CAAA;IAChB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,eAAe,CACvB,iBAAiB,EACjB,2BAA2B,OAAO,qBAAqB,EACvD,IAAI,CACL,CAAA;IACH,CAAC;IACD,MAAM,GAAG,GAAG,wBAAwB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IAChD,OAAO;QACL,EAAE,EAAE,OAAO;QACX,GAAG;QACH,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,YAAY,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,IAAI;QAC1C,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,WAAW,EAAE,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC;KACpC,CAAA;AACH,CAAC"}

package/dist/runtime/tensorrt-llm/prelaunch.d.ts

@@ -0,0 +1,20 @@
+import type { GpuFacts, RuntimeDescriptor } from '../../contracts/index.js';
+import type { HostMemory, ManagedCheckEngine, ResolvedCheckpoint } from '../managed-models/compatibility.js';
+import type { ManagedModel } from '../managed-models/model-dir.js';
+export interface VerifyModelFilesOptions {
+    /** The card this load is about to use; already resolved (and possibly substituted) by the caller. */
+    gpuId: string;
+    /** The engine's hooks for the shared check (its memory rule, its checkpoint quirks). */
+    engine: ManagedCheckEngine;
+}
+/**
+ * The pre-`stopPrevious` half of the pre-launch check: files, architecture, format and compute
+ * capability — never memory (see the file banner). Throws `MODEL_FILE_NOT_FOUND`/`MODEL_FILE_CORRUPT`
+ * for a missing or resized checkpoint file, or the pure check's own error
+ * (`MODEL_INCOMPATIBLE`/`MANAGED_METADATA_INVALID`/`MANAGED_PREREQUISITE_BLOCKED`) for a checkpoint
+ * that no longer checks out. On success, returns the `ResolvedCheckpoint` `checkModelMemory` needs
+ * for the memory half — including `config.json`'s own verified `architectures`, which is what
+ * `runtime.ts` now looks the descriptor's `model_families` entry up by (finding 5), never
+ * `model.yml`'s possibly-stale copy.
+ */
+export declare function verifyModelFilesAndCompatibility(model: Pick<ManagedModel, 'dir' | 'repository' | 'revision' | 'files'>, descriptor: RuntimeDescriptor, gpus: readonly GpuFacts[], hostMemory: HostMemory, options: VerifyModelFilesOptions): Promise<ResolvedCheckpoint>;

package/dist/runtime/tensorrt-llm/prelaunch.js

@@ -0,0 +1,168 @@
+/**
+ * The pre-launch check `TensorrtLlmRuntime.load` runs once `deps.model` has resolved an installed
+ * model (task 2.16, spec `tensorrt-llm-models`, "Проверка файлов при загрузке"): every file
+ * `model.yml` recorded is still on disk at its declared size — a shard deleted after download is
+ * refused by name, the way a corrupt GGUF already is for llama.cpp (`MODEL_FILE_NOT_FOUND`/
+ * `MODEL_FILE_CORRUPT`, `../llamacpp/load-plan.ts`'s own convention, reused here) — and the
+ * compatibility verdict is recomputed against `config.json` and `hf_quant_config.json` exactly as
+ * they sit in the model's directory right now, not as `model.yml` last recorded them, and against
+ * the card this load is about to use (its `gpu_id` is passed in, already resolved and possibly
+ * substituted by the caller — this never re-picks a card).
+ *
+ * `verifyModelFilesAndCompatibility` below is everything above the memory line only — files,
+ * architecture, format, compute capability — and returns a `ResolvedCheckpoint`
+ * (`compatibility.ts`) rather than a final verdict, on purpose: memory is checked separately, later,
+ * by `checkModelMemory` (re-exported from `compatibility.ts`) called from `runtime.ts`'s
+ * `beforeCreate` hook, once `stopPrevious` has actually freed the card (task 2.16w round 1, finding
+ * 1 (Critical) — reading free memory here, before eviction, would refuse a same-card model switch
+ * outright on a single-GPU host). No container exists before either call; a failure in either never
+ * creates one.
+ *
+ * `hf_quant_config.json` is read whenever it exists on disk (finding 4), independent of whether
+ * `model.yml`'s own `files` list happens to mention it — `model.yml` is a record the app/CLI wrote
+ * when the download finished, and can be stale or incomplete in ways the file itself on disk is not.
+ *
+ * Direct `node:fs/promises`, no injected `exec`/`readFile`: reading the model's own checkpoint
+ * directory is local disk I/O, the same convention `model-dir.ts` already uses for `model.yml`
+ * itself — nothing here is a shell command or a network call that would need faking on a non-Linux
+ * test host.
+ */
+import { open, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { AtomicCoreError } from '../../contracts/index.js';
+import { checkCheckpointFiles, normalizeWeightNames, safetensorsHeaderLength, safetensorsTensorNames, weightSafetensorsFiles, } from '../managed-models/compatibility.js';
+const CONFIG_FILE = 'config.json';
+const HF_QUANT_CONFIG_FILE = 'hf_quant_config.json';
+/** A `model.yml` file path, joined onto the model directory; refuses one that would climb out of it. */
+function safeJoin(dir, relativePath) {
+    const segments = relativePath.split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        throw new AtomicCoreError('MANAGED_METADATA_INVALID', `model.yml names an unsafe file path: ${relativePath}`, relativePath);
+    }
+    return join(dir, ...segments);
+}
+async function fileSizeOnDisk(path) {
+    try {
+        return (await stat(path)).size;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every file `model.yml` lists, present at its recorded size; a violation refuses by name. */
+async function assertFilesOnDisk(dir, files) {
+    for (const file of files) {
+        const path = safeJoin(dir, file.path);
+        const size = await fileSizeOnDisk(path);
+        if (size === undefined) {
+            throw new AtomicCoreError('MODEL_FILE_NOT_FOUND', `The model is missing a file recorded in model.yml: ${file.path}`, path);
+        }
+        if (size !== file.size) {
+            throw new AtomicCoreError('MODEL_FILE_CORRUPT', `${file.path} is ${size} bytes on disk, but model.yml recorded ${file.size}.`, path);
+        }
+    }
+}
+/** `null` when the file does not exist; throws `MANAGED_METADATA_INVALID` for one that exists but is not a JSON object. */
+async function readJsonObjectFile(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new AtomicCoreError('MANAGED_METADATA_INVALID', `${path} is not valid JSON.`, String(error));
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new AtomicCoreError('MANAGED_METADATA_INVALID', `${path} is not a JSON object.`, path);
+    }
+    return parsed;
+}
+/**
+ * The tensor names in one `.safetensors` file's own header (8-byte little-endian length, then JSON):
+ * what the file really holds, unlike `model.safetensors.index.json`, which a repository can ship
+ * stale or copied from another model (PrimeIntellect/GLM-0.5B: an 18k-name index over a 429-tensor
+ * file). `undefined` for a file that does not shape up as safetensors — the shape checks are then
+ * skipped, never failed on a header this core cannot read.
+ */
+async function tensorNamesOnDisk(path) {
+    const handle = await open(path, 'r').catch(() => undefined);
+    if (handle === undefined)
+        return undefined;
+    try {
+        const prefix = Buffer.alloc(8);
+        if ((await handle.read(prefix, 0, 8, 0)).bytesRead !== 8)
+            return undefined;
+        const length = safetensorsHeaderLength(prefix);
+        if (length === undefined)
+            return undefined;
+        const header = Buffer.alloc(length);
+        if ((await handle.read(header, 0, length, 8)).bytesRead !== length)
+            return undefined;
+        return safetensorsTensorNames(JSON.parse(header.toString('utf8')));
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Every weight file's tensor names, folded; `undefined` when there is none or any header is unreadable. */
+async function weightNamesOnDisk(dir, files) {
+    const weights = weightSafetensorsFiles(files);
+    if (weights.length === 0)
+        return undefined;
+    const names = [];
+    for (const file of weights) {
+        const own = await tensorNamesOnDisk(safeJoin(dir, file.path));
+        if (own === undefined)
+            return undefined;
+        names.push(...own);
+    }
+    return normalizeWeightNames(names);
+}
+/**
+ * The pre-`stopPrevious` half of the pre-launch check: files, architecture, format and compute
+ * capability — never memory (see the file banner). Throws `MODEL_FILE_NOT_FOUND`/`MODEL_FILE_CORRUPT`
+ * for a missing or resized checkpoint file, or the pure check's own error
+ * (`MODEL_INCOMPATIBLE`/`MANAGED_METADATA_INVALID`/`MANAGED_PREREQUISITE_BLOCKED`) for a checkpoint
+ * that no longer checks out. On success, returns the `ResolvedCheckpoint` `checkModelMemory` needs
+ * for the memory half — including `config.json`'s own verified `architectures`, which is what
+ * `runtime.ts` now looks the descriptor's `model_families` entry up by (finding 5), never
+ * `model.yml`'s possibly-stale copy.
+ */
+export async function verifyModelFilesAndCompatibility(model, descriptor, gpus, hostMemory, options) {
+    await assertFilesOnDisk(model.dir, model.files);
+    const configJson = await readJsonObjectFile(join(model.dir, CONFIG_FILE));
+    if (configJson === null) {
+        throw new AtomicCoreError('MODEL_FILE_NOT_FOUND', 'The model has no config.json in its directory.', join(model.dir, CONFIG_FILE));
+    }
+    // Read whenever the file is actually there, independent of model.yml's own files list (finding 4).
+    const hfQuantConfigJson = await readJsonObjectFile(join(model.dir, HF_QUANT_CONFIG_FILE));
+    // The same tensor names the download-time check gets from the app, so a checkpoint downloaded
+    // before that check knew to look (or by an older app) is refused here, before any container.
+    const weightNames = await weightNamesOnDisk(model.dir, model.files);
+    const input = {
+        repository: model.repository ?? '',
+        revision: model.revision ?? '',
+        config_json: configJson,
+        hf_quant_config_json: hfQuantConfigJson,
+        files: model.files,
+        gpu_id: options.gpuId,
+        ...(weightNames === undefined ? {} : { weight_names: weightNames }),
+    };
+    const result = checkCheckpointFiles(input, descriptor, gpus, hostMemory, options.engine);
+    if (!result.ok) {
+        // `FilesCheckResult`'s own type guarantees `result.verdict.verdict` is the failed branch here.
+        const { code, message, details } = result.verdict.verdict.error;
+        throw new AtomicCoreError(code, message, details);
+    }
+    return result.resolved;
+}
+//# sourceMappingURL=prelaunch.js.map

package/dist/runtime/tensorrt-llm/prelaunch.js.map

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

package/dist/runtime/tensorrt-llm/quant-format.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The quantization-format naming rule: a fixed checkpoint-metadata → format-name mapping that
+ * `RuntimeDescriptor.quantization[].format` (`src/contracts/environment.ts`) is keyed by. Ported
+ * verbatim from `atomic-chat-conf`'s README, "Runtime descriptors (`runtimes/`)" →
+ * `quantization[].format` names — this file *is* the core side of that conf↔core contract, so any
+ * change to the rule has to change both places together.
+ *
+ * The inputs are a checkpoint's `config.json` and, when the repository carries the file, its
+ * `hf_quant_config.json`. A checkpoint can be quantized with no `quantization_config` in
+ * `config.json` at all (e.g. `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-FP8`,
+ * `nvidia/Llama-3.3-70B-Instruct-NVFP4`), so `hf_quant_config.json` must always be checked before
+ * `dtype`/`torch_dtype` is trusted. Steps apply in order, stopping at the first that matches; `null`
+ * means the naming rule does not recognise the checkpoint (an unsupported `quant_method` such as
+ * `awq`/`gptq`, an `fp8` checkpoint without the block size this engine loads, or a `dtype` other
+ * than `bfloat16`/`float16`) — the caller rejects that as an unsupported format, never guesses.
+ *
+ * Pure and network-free, like every file in this module (design D12).
+ */
+/** A parsed JSON object, exactly as `config.json` / `hf_quant_config.json` arrive on the wire. */
+export type JsonObject = Record<string, unknown>;
+/**
+ * Every sibling that is a `.gguf` file. GGUF is not a case of the naming rule at all — this engine
+ * never loads a GGUF checkpoint's `config.json` — it is the separate, always-reject gate
+ * `compatibility.ts` applies before the naming rule runs at all (spec `tensorrt-llm-models`: "for
+ * GGUF there is llama.cpp"). A listing with even one `.gguf` file counts, which also covers a
+ * GGUF-only listing.
+ */
+export declare function isGgufCheckpoint(files: readonly {
+    path: string;
+}[]): boolean;
+/**
+ * The naming rule, applied in order. `null` means unrecognised: the caller must reject it as an
+ * unsupported format rather than reporting `bf16`/`fp16` by default.
+ *
+ * `hf_quant_config.json` being present at all stops the rule at step 1 — its own `null` (an
+ * unrecognised or missing `quant_algo`) is final and never falls through to `config.json`/`dtype`,
+ * matching the README: "if hf_quant_config.json is present ... the format is its quant_algo".
+ */
+export declare function quantizationFormat(configJson: JsonObject, hfQuantConfigJson: JsonObject | null): string | null;
+/**
+ * The KV-cache's own quantization algorithm — NVIDIA ModelOpt's `kv_cache_quant_algo`, a sibling
+ * field to `quant_algo` above, read the same way and from the same object: `hf_quant_config.json`'s
+ * `quantization` when the repository carries the file, else `config.json`'s `quantization_config`.
+ * Used by the KV-cache memory formula (`compatibility.ts`, task 2.16w round 1) to size a KV cache
+ * entry at 1 byte (`FP8`) instead of the engine's own default 2 bytes (`bf16`/`fp16`). `undefined`
+ * when neither object carries it — an unquantized KV cache, or a checkpoint this naming rule does
+ * not otherwise recognise.
+ */
+export declare function kvCacheQuantAlgo(configJson: JsonObject, hfQuantConfigJson: JsonObject | null): string | undefined;
+/**
+ * What the naming rule actually saw when it did not recognise a format, for error messages only —
+ * never consulted to decide the format itself (that is `quantizationFormat`'s job alone). Mirrors
+ * `quantizationFormat`'s own step order, so the two must be kept in sync.
+ */
+export declare function describeUnrecognizedQuantization(configJson: JsonObject, hfQuantConfigJson: JsonObject | null): string;
+/** What NVIDIA ModelOpt calls a checkpoint whose layers carry different formats. */
+export declare const MIXED_PRECISION = "mixed_precision";
+/**
+ * The formats a checkpoint actually needs the engine to load. One format for every checkpoint but a
+ * ModelOpt `MIXED_PRECISION` one, whose `hf_quant_config.json` lists a `quant_algo` per layer in
+ * `quantization.quantized_layers` (e.g. `NVFP4` + `FP8`, or `W4A16_NVFP4` + `FP8`): every distinct
+ * per-layer format, named by the same rule as a whole-checkpoint `quant_algo`. An empty list means
+ * the mixed checkpoint names no per-layer format at all, which the caller must reject.
+ */
+export declare function quantizationComponents(format: string, hfQuantConfigJson: JsonObject | null): string[];

package/dist/runtime/tensorrt-llm/quant-format.js

@@ -0,0 +1,189 @@
+/**
+ * The quantization-format naming rule: a fixed checkpoint-metadata → format-name mapping that
+ * `RuntimeDescriptor.quantization[].format` (`src/contracts/environment.ts`) is keyed by. Ported
+ * verbatim from `atomic-chat-conf`'s README, "Runtime descriptors (`runtimes/`)" →
+ * `quantization[].format` names — this file *is* the core side of that conf↔core contract, so any
+ * change to the rule has to change both places together.
+ *
+ * The inputs are a checkpoint's `config.json` and, when the repository carries the file, its
+ * `hf_quant_config.json`. A checkpoint can be quantized with no `quantization_config` in
+ * `config.json` at all (e.g. `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-FP8`,
+ * `nvidia/Llama-3.3-70B-Instruct-NVFP4`), so `hf_quant_config.json` must always be checked before
+ * `dtype`/`torch_dtype` is trusted. Steps apply in order, stopping at the first that matches; `null`
+ * means the naming rule does not recognise the checkpoint (an unsupported `quant_method` such as
+ * `awq`/`gptq`, an `fp8` checkpoint without the block size this engine loads, or a `dtype` other
+ * than `bfloat16`/`float16`) — the caller rejects that as an unsupported format, never guesses.
+ *
+ * Pure and network-free, like every file in this module (design D12).
+ */
+const FP8_PB_WO = 'fp8_pb_wo';
+const FP8_BLOCK_SCALES = 'fp8_block_scales';
+function asObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function asNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** `fp8_pb_wo` is what NVIDIA ModelOpt calls it; the engine itself calls the same format `fp8_block_scales`. */
+function renameFp8PbWo(quantAlgo) {
+    const lower = quantAlgo.toLowerCase();
+    return lower === FP8_PB_WO ? FP8_BLOCK_SCALES : lower;
+}
+/**
+ * Every sibling that is a `.gguf` file. GGUF is not a case of the naming rule at all — this engine
+ * never loads a GGUF checkpoint's `config.json` — it is the separate, always-reject gate
+ * `compatibility.ts` applies before the naming rule runs at all (spec `tensorrt-llm-models`: "for
+ * GGUF there is llama.cpp"). A listing with even one `.gguf` file counts, which also covers a
+ * GGUF-only listing.
+ */
+export function isGgufCheckpoint(files) {
+    return files.some((file) => file.path.toLowerCase().endsWith('.gguf'));
+}
+/**
+ * Step 1: `hf_quant_config.json` present (NVIDIA ModelOpt) → its `quantization.quant_algo`,
+ * lower-cased and renamed. The README rule stops here whenever the file is present at all — a
+ * present-but-empty/missing `quant_algo` (e.g. a ModelOpt KV-cache-only export) is `null`
+ * (unrecognised), never a reason to fall through to `config.json`/`dtype`.
+ */
+function fromHfQuantConfig(hfQuantConfigJson) {
+    const quantization = asObject(hfQuantConfigJson.quantization);
+    const quantAlgo = quantization === undefined ? undefined : asNonEmptyString(quantization.quant_algo);
+    return quantAlgo === undefined ? null : renameFp8PbWo(quantAlgo);
+}
+/**
+ * Step 2: `config.json`'s `quantization_config.quant_method`. Returns `null` (recognised as *not
+ * loadable*, distinct from `undefined` meaning "step 2 does not apply") for every `quant_method`
+ * this engine release cannot load, so the caller never falls through to reading `dtype` for a
+ * checkpoint that step 2 already identified as quantized.
+ */
+function fromConfigQuantizationConfig(configJson) {
+    const quantizationConfig = asObject(configJson.quantization_config);
+    if (quantizationConfig === undefined)
+        return undefined;
+    const quantMethod = quantizationConfig.quant_method;
+    if (quantMethod === 'modelopt') {
+        const quantAlgo = asNonEmptyString(quantizationConfig.quant_algo);
+        return quantAlgo === undefined ? null : renameFp8PbWo(quantAlgo);
+    }
+    if (quantMethod === 'fp8') {
+        const blockSize = quantizationConfig.weight_block_size;
+        const isFp8BlockScales = Array.isArray(blockSize) && blockSize.length === 2 && blockSize[0] === 128 && blockSize[1] === 128;
+        // `fp8` without that exact block size is not loadable by this engine release
+        // (`model_config.py:323`) and must not fall through to step 3 as `bf16`/`fp16`.
+        return isFp8BlockScales ? FP8_BLOCK_SCALES : null;
+    }
+    if (quantMethod === 'mxfp4')
+        return 'mxfp4';
+    // awq, gptq, anything else: not loadable by this engine release.
+    return null;
+}
+/**
+ * The checkpoint's weight dtype: `dtype` is what TensorRT-LLM itself reads, `torch_dtype` is the
+ * legacy fallback. A VLM-style config (Qwen3.5 and later) declares it only on `text_config`, which
+ * TensorRT-LLM 1.3 falls back to as well (`model_config.py`), so this does too.
+ */
+function configDtype(configJson) {
+    const textConfig = asObject(configJson.text_config);
+    return (asNonEmptyString(configJson.dtype) ??
+        asNonEmptyString(configJson.torch_dtype) ??
+        (textConfig === undefined
+            ? undefined
+            : (asNonEmptyString(textConfig.dtype) ?? asNonEmptyString(textConfig.torch_dtype))));
+}
+/** Step 3: unquantized, named by `configDtype`. */
+function fromDtype(configJson) {
+    const dtype = configDtype(configJson);
+    if (dtype === 'bfloat16')
+        return 'bf16';
+    if (dtype === 'float16')
+        return 'fp16';
+    return null;
+}
+/**
+ * The naming rule, applied in order. `null` means unrecognised: the caller must reject it as an
+ * unsupported format rather than reporting `bf16`/`fp16` by default.
+ *
+ * `hf_quant_config.json` being present at all stops the rule at step 1 — its own `null` (an
+ * unrecognised or missing `quant_algo`) is final and never falls through to `config.json`/`dtype`,
+ * matching the README: "if hf_quant_config.json is present ... the format is its quant_algo".
+ */
+export function quantizationFormat(configJson, hfQuantConfigJson) {
+    if (hfQuantConfigJson !== null) {
+        return fromHfQuantConfig(hfQuantConfigJson);
+    }
+    const fromConfig = fromConfigQuantizationConfig(configJson);
+    if (fromConfig !== undefined)
+        return fromConfig;
+    return fromDtype(configJson);
+}
+/**
+ * The KV-cache's own quantization algorithm — NVIDIA ModelOpt's `kv_cache_quant_algo`, a sibling
+ * field to `quant_algo` above, read the same way and from the same object: `hf_quant_config.json`'s
+ * `quantization` when the repository carries the file, else `config.json`'s `quantization_config`.
+ * Used by the KV-cache memory formula (`compatibility.ts`, task 2.16w round 1) to size a KV cache
+ * entry at 1 byte (`FP8`) instead of the engine's own default 2 bytes (`bf16`/`fp16`). `undefined`
+ * when neither object carries it — an unquantized KV cache, or a checkpoint this naming rule does
+ * not otherwise recognise.
+ */
+export function kvCacheQuantAlgo(configJson, hfQuantConfigJson) {
+    if (hfQuantConfigJson !== null) {
+        const quantization = asObject(hfQuantConfigJson.quantization);
+        return quantization === undefined ? undefined : asNonEmptyString(quantization.kv_cache_quant_algo);
+    }
+    const quantizationConfig = asObject(configJson.quantization_config);
+    return quantizationConfig === undefined
+        ? undefined
+        : asNonEmptyString(quantizationConfig.kv_cache_quant_algo);
+}
+/**
+ * What the naming rule actually saw when it did not recognise a format, for error messages only —
+ * never consulted to decide the format itself (that is `quantizationFormat`'s job alone). Mirrors
+ * `quantizationFormat`'s own step order, so the two must be kept in sync.
+ */
+export function describeUnrecognizedQuantization(configJson, hfQuantConfigJson) {
+    if (hfQuantConfigJson !== null) {
+        const quantization = asObject(hfQuantConfigJson.quantization);
+        const quantAlgo = quantization?.quant_algo;
+        return `hf_quant_config.json quantization.quant_algo=${JSON.stringify(quantAlgo ?? null)}`;
+    }
+    const quantizationConfig = asObject(configJson.quantization_config);
+    if (quantizationConfig !== undefined) {
+        const quantMethod = quantizationConfig.quant_method;
+        if (quantMethod === 'modelopt') {
+            return `config.json quantization_config.quant_method="modelopt" quant_algo=${JSON.stringify(quantizationConfig.quant_algo ?? null)}`;
+        }
+        if (quantMethod === 'fp8') {
+            return `config.json quantization_config.quant_method="fp8" weight_block_size=${JSON.stringify(quantizationConfig.weight_block_size ?? null)}`;
+        }
+        return `config.json quantization_config.quant_method=${JSON.stringify(quantMethod ?? null)}`;
+    }
+    return `config.json dtype=${JSON.stringify(configDtype(configJson) ?? null)}`;
+}
+/** What NVIDIA ModelOpt calls a checkpoint whose layers carry different formats. */
+export const MIXED_PRECISION = 'mixed_precision';
+/**
+ * The formats a checkpoint actually needs the engine to load. One format for every checkpoint but a
+ * ModelOpt `MIXED_PRECISION` one, whose `hf_quant_config.json` lists a `quant_algo` per layer in
+ * `quantization.quantized_layers` (e.g. `NVFP4` + `FP8`, or `W4A16_NVFP4` + `FP8`): every distinct
+ * per-layer format, named by the same rule as a whole-checkpoint `quant_algo`. An empty list means
+ * the mixed checkpoint names no per-layer format at all, which the caller must reject.
+ */
+export function quantizationComponents(format, hfQuantConfigJson) {
+    if (format !== MIXED_PRECISION)
+        return [format];
+    const quantization = hfQuantConfigJson === null ? undefined : asObject(hfQuantConfigJson.quantization);
+    const layers = quantization === undefined ? undefined : asObject(quantization.quantized_layers);
+    if (layers === undefined)
+        return [];
+    const formats = new Set();
+    for (const layer of Object.values(layers)) {
+        const quantAlgo = asNonEmptyString(asObject(layer)?.quant_algo);
+        if (quantAlgo === undefined)
+            return [];
+        formats.add(renameFp8PbWo(quantAlgo));
+    }
+    return [...formats].sort();
+}
+//# sourceMappingURL=quant-format.js.map

package/dist/runtime/tensorrt-llm/quant-format.js.map

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

package/dist/runtime/tensorrt-llm/registry.d.ts

@@ -0,0 +1,26 @@
+import type { TensorrtLlmModelYmlDocument } from './model-dir.js';
+export interface TensorrtLlmModelEntry {
+    id: string;
+    /** Directory holding `model.yml`. */
+    dir: string;
+    yml: TensorrtLlmModelYmlDocument;
+}
+/** Scan errors are collected rather than thrown: one broken model must not hide the rest of the list. */
+export interface TensorrtLlmScanResult {
+    entries: TensorrtLlmModelEntry[];
+    skipped: Array<{
+        dir: string;
+        error: string;
+    }>;
+}
+export declare class TensorrtLlmModelRegistry {
+    private readonly modelsDir;
+    /**
+     * The models root, or how to learn it at each scan (change `add-tensorrt-llm-windows`, task 2.8): on
+     * Windows it is a folder in Atomic Chat's WSL distribution, known only once that exists — `null`
+     * until then, which lists nothing.
+     */
+    constructor(modelsDir: string | (() => Promise<string | null>));
+    scan(): Promise<TensorrtLlmScanResult>;
+    list(): Promise<TensorrtLlmModelEntry[]>;
+}