@atomic-chat/core 0.13.2 → 0.13.6

package/dist/runtime/tensorrt-llm/guest-files.js

@@ -0,0 +1,49 @@
+/**
+ * The files of `tensorrt-llm` models and engine caches on Windows (change `add-tensorrt-llm-windows`,
+ * task 2.8, design D5): they live in the WSL guest's ext4, and core sees them through
+ * `\\wsl.localhost`. Listing and reading a `model.yml` through that path is fine; sizing or deleting
+ * tens of gigabytes through it is not — thousands of 9p round trips for what `du` and `rm` do in the
+ * guest at once. So sizes and removals run as commands in the guest, as root, with the guest paths
+ * behind the UNC ones (`guestPathFor`, which refuses anything outside the distribution). One `du`
+ * call for every path counts a hard-linked file once, as the Linux walk does.
+ */
+import { AtomicCoreError } from '../../contracts/index.js';
+import { WSL_LOCALHOST_MOUNT } from '../wsl/index.js';
+const TIMEOUT_MS = 30 * 60_000;
+export function guestModelFiles(transport, mount = WSL_LOCALHOST_MOUNT) {
+    const toGuest = (paths) => paths.map((path) => mount.guestPath(transport.name, path));
+    return {
+        sizes: async (paths) => {
+            const sizes = new Map(paths.map((path) => [path, 0]));
+            if (paths.length === 0)
+                return sizes;
+            const guest = toGuest(paths);
+            const answer = await transport.exec(['du', '-s', '-b', '--', ...guest], {
+                user: 'root',
+                timeoutMs: TIMEOUT_MS,
+            });
+            // `du` exits 1 when one path is missing, and still prints every other.
+            for (const line of answer.stdout.split('\n')) {
+                const match = /^(\d+)\t(.+)$/.exec(line);
+                if (match === null)
+                    continue;
+                const index = guest.indexOf(match[2]);
+                if (index !== -1)
+                    sizes.set(paths[index], Number(match[1]));
+            }
+            return sizes;
+        },
+        remove: async (paths) => {
+            if (paths.length === 0)
+                return;
+            const answer = await transport.exec(['rm', '-rf', '--', ...toGuest(paths)], {
+                user: 'root',
+                timeoutMs: TIMEOUT_MS,
+            });
+            if (answer.code !== 0) {
+                throw new AtomicCoreError('IO_ERROR', 'The files could not be removed in the Atomic Chat distribution.', answer.stderr.trim());
+            }
+        },
+    };
+}
+//# sourceMappingURL=guest-files.js.map

package/dist/runtime/tensorrt-llm/guest-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guest-files.js","sourceRoot":"","sources":["../../../src/runtime/tensorrt-llm/guest-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAC1D,OAAO,EAAE,mBAAmB,EAAkD,MAAM,iBAAiB,CAAA;AASrG,MAAM,UAAU,GAAG,EAAE,GAAG,MAAM,CAAA;AAE9B,MAAM,UAAU,eAAe,CAC7B,SAAmC,EACnC,QAAoB,mBAAmB;IAEvC,MAAM,OAAO,GAAG,CAAC,KAAe,EAAY,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;IACzG,OAAO;QACL,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YACrB,MAAM,KAAK,GAAG,IAAI,GAAG,CAAiB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;YACrE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAA;YACpC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;YAC5B,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC,EAAE;gBACtE,IAAI,EAAE,MAAM;gBACZ,SAAS,EAAE,UAAU;aACtB,CAAC,CAAA;YACF,uEAAuE;YACvE,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC7C,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBACxC,IAAI,KAAK,KAAK,IAAI;oBAAE,SAAQ;gBAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAW,CAAC,CAAA;gBAC/C,IAAI,KAAK,KAAK,CAAC,CAAC;oBAAE,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAW,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;YACvE,CAAC;YACD,OAAO,KAAK,CAAA;QACd,CAAC;QACD,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YACtB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAM;YAC9B,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE;gBAC1E,IAAI,EAAE,MAAM;gBACZ,SAAS,EAAE,UAAU;aACtB,CAAC,CAAA;YACF,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBACtB,MAAM,IAAI,eAAe,CACvB,UAAU,EACV,iEAAiE,EACjE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CACrB,CAAA;YACH,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/runtime/tensorrt-llm/kv-cache.d.ts

@@ -16,6 +16,22 @@ export declare const TENSORRT_LLM_DEFAULT_KV_CACHE_FREE_FRACTION = 0.8;
  * unified-memory-kv-cache-bounded-by-tokens.md).
  */
 export declare const TENSORRT_LLM_UNIFIED_KV_CONTEXTS = 2;
+/**
+ * Tokens in one KV-cache block: `KvCacheConfig.tokens_per_block`'s default in 1.3.0rc29, logged by
+ * both cache managers ("tokens per block=32", "KVCacheV2Scheduler: tokens_per_block=32"). The engine
+ * turns `kv_cache_config.max_tokens` into whole blocks, rounding down: 2096 tokens became 65 blocks,
+ * a 2080-token sequence for a 2096-token context, and the readiness check refused the load as out of
+ * memory on a card with 17 GiB free (RTX 5090 Laptop, 2026-10-09). Re-check with each engine image.
+ */
+export declare const TENSORRT_LLM_TOKENS_PER_BLOCK = 32;
+/** `tokens` rounded up to whole KV-cache blocks: what the engine keeps when asked for at least that many. */
+export declare function tensorrtLlmWholeBlockTokens(tokens: number): number;
+/**
+ * The `kv_cache_config.max_tokens` that holds `sequences` sequences at full context at once: each
+ * sequence takes whole blocks of its own, so the blocks are counted per sequence before multiplying
+ * (2 × 2096 tokens is 131 blocks, but two 2096-token sequences need 66 each).
+ */
+export declare function tensorrtLlmKvTokens(contextLength: number, sequences: number): number;
 /**
  * The `kv_cache_config.max_tokens` a unified-memory launch writes, and the token count its memory
  * check reserves KV for. On a unified-memory card (GB10/DGX Spark) "free GPU memory" is the system's

package/dist/runtime/tensorrt-llm/kv-cache.js

@@ -16,6 +16,26 @@ export const TENSORRT_LLM_DEFAULT_KV_CACHE_FREE_FRACTION = 0.8;
  * unified-memory-kv-cache-bounded-by-tokens.md).
  */
 export const TENSORRT_LLM_UNIFIED_KV_CONTEXTS = 2;
+/**
+ * Tokens in one KV-cache block: `KvCacheConfig.tokens_per_block`'s default in 1.3.0rc29, logged by
+ * both cache managers ("tokens per block=32", "KVCacheV2Scheduler: tokens_per_block=32"). The engine
+ * turns `kv_cache_config.max_tokens` into whole blocks, rounding down: 2096 tokens became 65 blocks,
+ * a 2080-token sequence for a 2096-token context, and the readiness check refused the load as out of
+ * memory on a card with 17 GiB free (RTX 5090 Laptop, 2026-10-09). Re-check with each engine image.
+ */
+export const TENSORRT_LLM_TOKENS_PER_BLOCK = 32;
+/** `tokens` rounded up to whole KV-cache blocks: what the engine keeps when asked for at least that many. */
+export function tensorrtLlmWholeBlockTokens(tokens) {
+    return Math.ceil(tokens / TENSORRT_LLM_TOKENS_PER_BLOCK) * TENSORRT_LLM_TOKENS_PER_BLOCK;
+}
+/**
+ * The `kv_cache_config.max_tokens` that holds `sequences` sequences at full context at once: each
+ * sequence takes whole blocks of its own, so the blocks are counted per sequence before multiplying
+ * (2 × 2096 tokens is 131 blocks, but two 2096-token sequences need 66 each).
+ */
+export function tensorrtLlmKvTokens(contextLength, sequences) {
+    return sequences * tensorrtLlmWholeBlockTokens(contextLength);
+}
 /**
  * The `kv_cache_config.max_tokens` a unified-memory launch writes, and the token count its memory
  * check reserves KV for. On a unified-memory card (GB10/DGX Spark) "free GPU memory" is the system's
@@ -23,6 +43,6 @@ export const TENSORRT_LLM_UNIFIED_KV_CONTEXTS = 2;
  * the KV cache whatever the context length; this bounds it to what the configured context needs.
  */
 export function tensorrtLlmUnifiedKvMaxTokens(contextLength) {
-    return contextLength * TENSORRT_LLM_UNIFIED_KV_CONTEXTS;
+    return tensorrtLlmKvTokens(contextLength, TENSORRT_LLM_UNIFIED_KV_CONTEXTS);
 }
 //# sourceMappingURL=kv-cache.js.map

package/dist/runtime/tensorrt-llm/kv-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"kv-cache.js","sourceRoot":"","sources":["../../../src/runtime/tensorrt-llm/kv-cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;8LAK8L;AAC9L,MAAM,CAAC,MAAM,2CAA2C,GAAG,GAAG,CAAA;AAE9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAA;AAEjD;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAAC,aAAqB;IACjE,OAAO,aAAa,GAAG,gCAAgC,CAAA;AACzD,CAAC"}
+{"version":3,"file":"kv-cache.js","sourceRoot":"","sources":["../../../src/runtime/tensorrt-llm/kv-cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;8LAK8L;AAC9L,MAAM,CAAC,MAAM,2CAA2C,GAAG,GAAG,CAAA;AAE9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAA;AAEjD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,EAAE,CAAA;AAE/C,6GAA6G;AAC7G,MAAM,UAAU,2BAA2B,CAAC,MAAc;IACxD,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,6BAA6B,CAAC,GAAG,6BAA6B,CAAA;AAC1F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,aAAqB,EAAE,SAAiB;IAC1E,OAAO,SAAS,GAAG,2BAA2B,CAAC,aAAa,CAAC,CAAA;AAC/D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAAC,aAAqB;IACjE,OAAO,mBAAmB,CAAC,aAAa,EAAE,gCAAgC,CAAC,CAAA;AAC7E,CAAC"}

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

@@ -0,0 +1,20 @@
+import type { TensorrtLlmModelLocation } from '../../contracts/index.js';
+import type { WindowsEnvironmentRecord } from '../environment/index.js';
+import { type GuestMount, type WslDistributionTransport } from '../wsl/index.js';
+/** Linux: `<data>/tensorrt-llm/models`, with the free space of the volume it is (or will be) on. */
+export declare function linuxModelLocation(root: string, freeBytes?: (path: string) => Promise<number | null>): Promise<TensorrtLlmModelLocation>;
+export interface WindowsModelLocationDeps {
+    records: {
+        read(): Promise<WindowsEnvironmentRecord | null>;
+    };
+    /** This scope's `scope_key` (`readOrCreateGuestScopeKey`). */
+    scopeKey: () => Promise<string>;
+    transport: (distribution: string) => WslDistributionTransport;
+    /** Free bytes on the Windows volume holding `path` (`WindowsHost.freeDiskBytes`). */
+    volumeFreeBytes: (path: string) => Promise<number | null>;
+    /** How core reaches the guest's files; `\\wsl.localhost` unless a test says otherwise. */
+    mount?: GuestMount;
+}
+/** The guest folder of this scope's `tensorrt-llm` models. */
+export declare function guestModelsRoot(scopeKey: string): string;
+export declare function windowsModelLocation(deps: WindowsModelLocationDeps): Promise<TensorrtLlmModelLocation>;

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

@@ -0,0 +1,48 @@
+/**
+ * Where `tensorrt-llm` models live, as clients must use it (change `add-tensorrt-llm-windows`, task
+ * 2.8, design D6; spec `tensorrt-llm-models` "Core сообщает расположение моделей"). One answer, from
+ * core, on every platform, so a client never derives the folder itself: on Linux the data folder's own
+ * `<data>/tensorrt-llm/models` as before; on Windows the scope's folder in Atomic Chat's WSL
+ * distribution, `\\wsl.localhost\<distribution>\var\lib\atomic-chat\scopes\<scope_key>\models\tensorrt-llm`,
+ * created (and handed to uid 1000) before a client writes into it. The free space on Windows is the
+ * smaller of the guest's own and the Windows volume's that holds the distribution's disk image: the
+ * guest's disk can grow only as far as that volume lets it. Before the distribution exists there is no
+ * such folder: `MANAGED_ADAPTER_UNAVAILABLE`, and no download starts.
+ */
+import { AtomicCoreError } from '../../contracts/index.js';
+import { freeBytesAtNearest, parseDfAvail } from '../environment/index.js';
+import { ensureGuestScope, guestScopeRoot, WSL_LOCALHOST_MOUNT, } from '../wsl/index.js';
+/** Linux: `<data>/tensorrt-llm/models`, with the free space of the volume it is (or will be) on. */
+export async function linuxModelLocation(root, freeBytes = freeBytesAtNearest) {
+    return { root, free_bytes: await freeBytes(root).catch(() => null) };
+}
+/** The guest folder of this scope's `tensorrt-llm` models. */
+export function guestModelsRoot(scopeKey) {
+    return `${guestScopeRoot(scopeKey)}/models/tensorrt-llm`;
+}
+export async function windowsModelLocation(deps) {
+    const record = await deps.records.read();
+    if (record === null) {
+        throw new AtomicCoreError('MANAGED_ADAPTER_UNAVAILABLE', 'TensorRT-LLM models live in Atomic Chat’s WSL distribution, which is not set up yet.');
+    }
+    const key = await deps.scopeKey();
+    const transport = deps.transport(record.distribution.name);
+    const guestRoot = guestModelsRoot(key);
+    // A distribution unregistered behind the app's back is no environment at all for a client.
+    await ensureGuestScope(transport, key).catch((error) => {
+        throw new AtomicCoreError('MANAGED_ADAPTER_UNAVAILABLE', 'Atomic Chat’s WSL distribution does not answer; set the environment up again.', error instanceof Error ? error.message : String(error));
+    });
+    const [guest, volume] = await Promise.all([
+        transport
+            .exec(['df', '--output=avail', '-B1', guestRoot], { user: 'root', timeoutMs: 120_000 })
+            .then(parseDfAvail)
+            .catch(() => null),
+        deps.volumeFreeBytes(record.distribution.path).catch(() => null),
+    ]);
+    const known = [guest, volume].filter((value) => value !== null);
+    return {
+        root: (deps.mount ?? WSL_LOCALHOST_MOUNT).hostPath(record.distribution.name, guestRoot),
+        free_bytes: known.length === 0 ? null : Math.min(...known),
+    };
+}
+//# sourceMappingURL=location.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"location.js","sourceRoot":"","sources":["../../../src/runtime/tensorrt-llm/location.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAE1D,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE1E,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,mBAAmB,GAGpB,MAAM,iBAAiB,CAAA;AAExB,oGAAoG;AACpG,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAY,EACZ,YAAsD,kBAAkB;IAExE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,CAAA;AACtE,CAAC;AAaD,8DAA8D;AAC9D,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,GAAG,cAAc,CAAC,QAAQ,CAAC,sBAAsB,CAAA;AAC1D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAA8B;IAE9B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAA;IACxC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,eAAe,CACvB,6BAA6B,EAC7B,sFAAsF,CACvF,CAAA;IACH,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAA;IACjC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAA;IAC1D,MAAM,SAAS,GAAG,eAAe,CAAC,GAAG,CAAC,CAAA;IACtC,2FAA2F;IAC3F,MAAM,gBAAgB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC9D,MAAM,IAAI,eAAe,CACvB,6BAA6B,EAC7B,+EAA+E,EAC/E,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAA;IACH,CAAC,CAAC,CAAA;IACF,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACxC,SAAS;aACN,IAAI,CAAC,CAAC,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;aACtF,IAAI,CAAC,YAAY,CAAC;aAClB,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;QACpB,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;KACjE,CAAC,CAAA;IACF,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,CAAA;IAChF,OAAO;QACL,IAAI,EAAE,CAAC,IAAI,CAAC,KAAK,IAAI,mBAAmB,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC;QACvF,UAAU,EAAE,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;KAC3D,CAAA;AACH,CAAC"}

package/dist/runtime/tensorrt-llm/model-dir.d.ts

@@ -0,0 +1,38 @@
+import type { CheckpointFile } from './compatibility.js';
+/** `model.yml`'s own fields, parsed and typed; nothing here is derived. */
+export interface TensorrtLlmModelYmlDocument {
+    /** `null` when `model.yml` does not carry one (tolerated: `readTensorrtLlmModel`'s own contract). */
+    repository: string | null;
+    revision: string | null;
+    architectures: string[];
+    quantization: string | null;
+    files: CheckpointFile[];
+}
+export interface TensorrtLlmModel {
+    id: string;
+    /** The checkpoint directory as core sees it; mounted read-only into the container. */
+    dir: string;
+    repository: string | null;
+    revision: string | null;
+    /** `architectures[0]`: the Hugging Face class name the descriptor's `model_families` is keyed by. */
+    architecture: string | null;
+    quantization: string | null;
+    /** The revision's file listing exactly as `model.yml` recorded it (the pre-launch check's input). */
+    files: CheckpointFile[];
+    /** Weight bytes of `files` (`weightBytes`), 0 when `model.yml` lists none. */
+    weightBytes: number;
+}
+/**
+ * `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 declare function parseTensorrtLlmModelYml(text: string, path: string): TensorrtLlmModelYmlDocument;
+/** `MODEL_NOT_FOUND` without a readable `model.yml`; `MANAGED_METADATA_INVALID` when it is not a mapping. */
+export declare function readTensorrtLlmModel(modelsDir: string, modelId: string): Promise<TensorrtLlmModel>;

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":"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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