@atomic-chat/core 0.5.1 → 0.13.2

package/dist/runtime/environment/environment-manifest.js

@@ -0,0 +1,131 @@
+/**
+ * Reading an environment manifest (openspec change `extract-environment-manifest`, task 2.1; spec
+ * `runtime-environment-manifest`): the data about the foundation every managed engine runs on,
+ * published in conf apart from any engine descriptor, one file per platform. One parser per platform
+ * (change `add-tensorrt-llm-windows`, task 2.1): Linux's lists which install recipes exist and on
+ * which distributions each is qualified; Windows' pins the rootfs core imports as its own WSL
+ * distribution and names the recipe that prepares the guest. A core picks the parser of its own
+ * platform (`environmentManifestParser`), and each parser accepts nothing but its own `platform`, so
+ * another platform's manifest never reaches it.
+ *
+ * Each shape follows its conf schema (`atomic-chat-conf/runtimes/environments/<platform>.schema.json`)
+ * exactly, with the same strictness as the descriptor parser (`document-fields.ts`): every level
+ * refuses an unknown field, so a command or a script added anywhere refuses the whole document. Conf
+ * CI's integrity checks — `recipe_id` unique, a distribution unique by `(id, version_id, arch)` within
+ * its recipe, `manifest_id` prefixed by its platform — hold here too. An empty `recipes` list is a
+ * valid Linux manifest (conf ruling 1.1): it qualifies no distribution for automatic setup.
+ */
+import { DOCUMENT_ID, DOCUMENT_ID_LABEL, DOCUMENT_SEMVER, documentFields, installRecipe, } from './document-fields.js';
+/** `manifest_id`: `<platform>-r<N>` (schema `properties.manifest_id.pattern`). */
+const LINUX_MANIFEST_ID = /^linux-r[0-9]+$/;
+/**
+ * `windows-r<N>` for x64 (`windows.json`), `windows-arm64-r<N>` for Windows on Arm
+ * (`windows-arm64.json`, its own file: every released core parses `windows.json` strictly and would
+ * refuse an arm64 rootfs there). The id names the architecture its rootfs is for.
+ */
+export const WINDOWS_MANIFEST_ID = /^windows(-arm64)?-r[0-9]+$/;
+// Copied character-for-character from `windows.schema.json`'s `definitions.rootfs`.
+/** `rootfs.url`: HTTPS only, no whitespace. */
+const ROOTFS_URL = /^https:\/\/[^\s]+$/;
+/** `rootfs.sha256`: lowercase hex, 64 characters. */
+const ROOTFS_SHA256 = /^[0-9a-f]{64}$/;
+const DISTRIBUTION_ID = /^[a-z0-9._-]+$/;
+const VERSION_ID = /^[0-9][0-9.]*$/;
+const SEMVER_LABEL = 'a semver version (major.minor.patch)';
+const LINUX_KEYS = ['schema_version', 'manifest_id', 'platform', 'minimum_core_version', 'recipes'];
+const WINDOWS_KEYS = [
+    'schema_version',
+    'manifest_id',
+    'platform',
+    'minimum_core_version',
+    'minimum_windows_build',
+    'minimum_wsl_version',
+    'rootfs',
+    'guest_recipe_id',
+];
+const ROOTFS_KEYS = ['url', 'sha256', 'distribution'];
+const ROOTFS_DISTRIBUTION_KEYS = ['id', 'version_id', 'arch'];
+const fields = documentFields('environment manifest');
+/** The checks every platform's manifest starts with: an object, known keys, version 1, its own platform. */
+function manifestObject(input, keys, platform) {
+    const raw = fields.object(input, 'the manifest');
+    fields.known(raw, 'the manifest', keys);
+    if (raw['schema_version'] !== 1) {
+        fields.fail('schema_version is not 1', JSON.stringify(raw['schema_version']));
+    }
+    if (raw['platform'] !== platform) {
+        fields.fail(`platform is not ${platform}`, JSON.stringify(raw['platform']));
+    }
+    return raw;
+}
+/** Validate one Linux environment manifest; throws `MANAGED_METADATA_INVALID` naming the first misfit. */
+export function parseLinuxEnvironmentManifest(input) {
+    const raw = manifestObject(input, LINUX_KEYS, 'linux');
+    const recipes = fields
+        .list(raw['recipes'], 'recipes')
+        .map((item, i) => installRecipe(fields, item, `recipes[${i}]`));
+    fields.unique(recipes.map((recipe) => recipe.recipe_id), 'recipes', 'a recipe id');
+    return {
+        schema_version: 1,
+        manifest_id: fields.pattern(LINUX_MANIFEST_ID, 'a Linux manifest id (linux-r<N>)')(raw['manifest_id'], 'manifest_id'),
+        platform: 'linux',
+        minimum_core_version: fields.pattern(DOCUMENT_SEMVER, SEMVER_LABEL)(raw['minimum_core_version'], 'minimum_core_version'),
+        recipes,
+    };
+}
+/** Validate one Windows environment manifest; throws `MANAGED_METADATA_INVALID` naming the first misfit. */
+export function parseWindowsEnvironmentManifest(input) {
+    const raw = manifestObject(input, WINDOWS_KEYS, 'windows');
+    const build = raw['minimum_windows_build'];
+    if (typeof build !== 'number' || !Number.isSafeInteger(build) || build < 1) {
+        fields.fail('minimum_windows_build is not a whole number >= 1', JSON.stringify(build));
+    }
+    const manifestId = fields.pattern(WINDOWS_MANIFEST_ID, 'a Windows manifest id (windows-r<N> or windows-arm64-r<N>)')(raw['manifest_id'], 'manifest_id');
+    return {
+        schema_version: 1,
+        manifest_id: manifestId,
+        platform: 'windows',
+        minimum_core_version: fields.pattern(DOCUMENT_SEMVER, SEMVER_LABEL)(raw['minimum_core_version'], 'minimum_core_version'),
+        minimum_windows_build: build,
+        minimum_wsl_version: fields.pattern(DOCUMENT_SEMVER, SEMVER_LABEL)(raw['minimum_wsl_version'], 'minimum_wsl_version'),
+        rootfs: rootfsFor(manifestId, rootfs(fields, raw['rootfs'])),
+        guest_recipe_id: fields.pattern(DOCUMENT_ID, DOCUMENT_ID_LABEL)(raw['guest_recipe_id'], 'guest_recipe_id'),
+    };
+}
+/** An arm64 manifest carries an aarch64 guest and an x64 one an x86_64 guest — never the other. */
+function rootfsFor(manifestId, entry) {
+    const expected = manifestId.startsWith('windows-arm64-') ? 'aarch64' : 'x86_64';
+    if (entry.distribution.arch !== expected) {
+        fields.fail(`rootfs.distribution.arch is not ${expected} for ${manifestId}`, entry.distribution.arch);
+    }
+    return entry;
+}
+/** `#/definitions/rootfs`: where the guest comes from and what it is — never how to import it. */
+function rootfs(fields, value) {
+    const entry = fields.object(value, 'rootfs');
+    fields.known(entry, 'rootfs', ROOTFS_KEYS);
+    const distribution = fields.object(entry['distribution'], 'rootfs.distribution');
+    fields.known(distribution, 'rootfs.distribution', ROOTFS_DISTRIBUTION_KEYS);
+    const arch = distribution['arch'];
+    if (arch !== 'x86_64' && arch !== 'aarch64') {
+        fields.fail('rootfs.distribution.arch is not x86_64 or aarch64', JSON.stringify(arch));
+    }
+    return {
+        url: fields.pattern(ROOTFS_URL, 'an https:// URL')(entry['url'], 'rootfs.url'),
+        sha256: fields.pattern(ROOTFS_SHA256, '64 lowercase hex characters')(entry['sha256'], 'rootfs.sha256'),
+        distribution: {
+            id: fields.pattern(DISTRIBUTION_ID, 'an os-release id')(distribution['id'], 'rootfs.distribution.id'),
+            version_id: fields.pattern(VERSION_ID, 'an os-release version id')(distribution['version_id'], 'rootfs.distribution.version_id'),
+            arch: arch,
+        },
+    };
+}
+/** The parser of one platform's manifest: it refuses every other platform's document. */
+export function environmentManifestParser(platform) {
+    const parsers = {
+        linux: parseLinuxEnvironmentManifest,
+        windows: parseWindowsEnvironmentManifest,
+    };
+    return parsers[platform];
+}
+//# sourceMappingURL=environment-manifest.js.map

package/dist/runtime/environment/environment-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-manifest.js","sourceRoot":"","sources":["../../../src/runtime/environment/environment-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,GAEd,MAAM,sBAAsB,CAAA;AAE7B,kFAAkF;AAClF,MAAM,iBAAiB,GAAG,iBAAiB,CAAA;AAC3C;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,4BAA4B,CAAA;AAE/D,oFAAoF;AACpF,+CAA+C;AAC/C,MAAM,UAAU,GAAG,oBAAoB,CAAA;AACvC,qDAAqD;AACrD,MAAM,aAAa,GAAG,gBAAgB,CAAA;AACtC,MAAM,eAAe,GAAG,gBAAgB,CAAA;AACxC,MAAM,UAAU,GAAG,gBAAgB,CAAA;AAEnC,MAAM,YAAY,GAAG,sCAAsC,CAAA;AAE3D,MAAM,UAAU,GAAG,CAAC,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,sBAAsB,EAAE,SAAS,CAAU,CAAA;AAC5G,MAAM,YAAY,GAAG;IACnB,gBAAgB;IAChB,aAAa;IACb,UAAU;IACV,sBAAsB;IACtB,uBAAuB;IACvB,qBAAqB;IACrB,QAAQ;IACR,iBAAiB;CACT,CAAA;AACV,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,cAAc,CAAU,CAAA;AAC9D,MAAM,wBAAwB,GAAG,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,CAAU,CAAA;AAEtE,MAAM,MAAM,GAAG,cAAc,CAAC,sBAAsB,CAAC,CAAA;AAErD,4GAA4G;AAC5G,SAAS,cAAc,CACrB,KAAc,EACd,IAAuB,EACvB,QAA6B;IAE7B,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,cAAc,CAAC,CAAA;IAChD,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,CAAC,CAAA;IACvC,IAAI,GAAG,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,CAAC,IAAI,CAAC,yBAAyB,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAA;IAC/E,CAAC;IACD,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,QAAQ,EAAE,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,mBAAmB,QAAQ,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;IAC7E,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,6BAA6B,CAAC,KAAc;IAC1D,MAAM,GAAG,GAAG,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,CAAA;IAEtD,MAAM,OAAO,GAAG,MAAM;SACnB,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;SAC/B,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAA;IACjE,MAAM,CAAC,MAAM,CACX,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,EACzC,SAAS,EACT,aAAa,CACd,CAAA;IAED,OAAO;QACL,cAAc,EAAE,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,iBAAiB,EAAE,kCAAkC,CAAC,CAChF,GAAG,CAAC,aAAa,CAAC,EAClB,aAAa,CACd;QACD,QAAQ,EAAE,OAAO;QACjB,oBAAoB,EAAE,MAAM,CAAC,OAAO,CAAC,eAAe,EAAE,YAAY,CAAC,CACjE,GAAG,CAAC,sBAAsB,CAAC,EAC3B,sBAAsB,CACvB;QACD,OAAO;KACR,CAAA;AACH,CAAC;AAED,4GAA4G;AAC5G,MAAM,UAAU,+BAA+B,CAAC,KAAc;IAC5D,MAAM,GAAG,GAAG,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,SAAS,CAAC,CAAA;IAE1D,MAAM,KAAK,GAAG,GAAG,CAAC,uBAAuB,CAAC,CAAA;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC3E,MAAM,CAAC,IAAI,CAAC,kDAAkD,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAA;IACxF,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAC/B,mBAAmB,EACnB,4DAA4D,CAC7D,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,CAAA;IAEpC,OAAO;QACL,cAAc,EAAE,CAAC;QACjB,WAAW,EAAE,UAAU;QACvB,QAAQ,EAAE,SAAS;QACnB,oBAAoB,EAAE,MAAM,CAAC,OAAO,CAAC,eAAe,EAAE,YAAY,CAAC,CACjE,GAAG,CAAC,sBAAsB,CAAC,EAC3B,sBAAsB,CACvB;QACD,qBAAqB,EAAE,KAAe;QACtC,mBAAmB,EAAE,MAAM,CAAC,OAAO,CAAC,eAAe,EAAE,YAAY,CAAC,CAChE,GAAG,CAAC,qBAAqB,CAAC,EAC1B,qBAAqB,CACtB;QACD,MAAM,EAAE,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC5D,eAAe,EAAE,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAC7D,GAAG,CAAC,iBAAiB,CAAC,EACtB,iBAAiB,CAClB;KACF,CAAA;AACH,CAAC;AAED,mGAAmG;AACnG,SAAS,SAAS,CAAC,UAAkB,EAAE,KAAgB;IACrD,MAAM,QAAQ,GAAG,UAAU,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAA;IAC/E,IAAI,KAAK,CAAC,YAAY,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC,mCAAmC,QAAQ,QAAQ,UAAU,EAAE,EAAE,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,CAAA;IACvG,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,kGAAkG;AAClG,SAAS,MAAM,CAAC,MAAsB,EAAE,KAAc;IACpD,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IAC5C,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAA;IAC1C,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,EAAE,qBAAqB,CAAC,CAAA;IAChF,MAAM,CAAC,KAAK,CAAC,YAAY,EAAE,qBAAqB,EAAE,wBAAwB,CAAC,CAAA;IAC3E,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,CAAC,CAAA;IACjC,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,mDAAmD,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAA;IACxF,CAAC;IACD,OAAO;QACL,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;QAC9E,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,aAAa,EAAE,6BAA6B,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;QACtG,YAAY,EAAE;YACZ,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,eAAe,EAAE,kBAAkB,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,wBAAwB,CAAC;YACrG,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,0BAA0B,CAAC,CAChE,YAAY,CAAC,YAAY,CAAC,EAC1B,gCAAgC,CACjC;YACD,IAAI,EAAE,IAA4B;SACnC;KACF,CAAA;AACH,CAAC;AAQD,yFAAyF;AACzF,MAAM,UAAU,yBAAyB,CACvC,QAAW;IAEX,MAAM,OAAO,GAAyF;QACpG,KAAK,EAAE,6BAA6B;QACpC,OAAO,EAAE,+BAA+B;KACzC,CAAA;IACD,OAAO,OAAO,CAAC,QAAQ,CAAyD,CAAA;AAClF,CAAC"}

package/dist/runtime/environment/guest-host.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Atomic Chat's own WSL distribution, seen as a Linux host (change `add-tensorrt-llm-windows`,
+ * design D1): the same `LinuxProbeDeps` the Linux provisioner reads a machine through, answered by
+ * commands run in the guest through the WSL transport — so `probeLinux` and `assessLinux` judge the
+ * guest exactly as they judge a Linux host, and nothing about Docker or the toolkit is written twice.
+ *
+ * Everything runs as the guest's root (design D3): root in a distribution the user owns gives no
+ * rights on Windows, and Docker is reached through its system socket without a `docker` group. No
+ * command goes through a shell: a file is read with `cat`, its existence checked with `test -e`, free
+ * space with `df`, each as its own argv.
+ *
+ * Two facts only the guest has (spec "Память и драйвер оцениваются по гостю"): the version of the
+ * NVIDIA user-space libraries WSL hands the guest (`/usr/lib/wsl/lib`), in Linux numbering — the guest's
+ * `nvidia-smi` reports the *Windows* driver's number (591.xx), which is not comparable with a
+ * descriptor's `minimum_driver_version`, while the NVML library's own version is (design D10:
+ * `nvidia-smi --version`'s `NVML version` line) — and the VM's memory, from the guest's
+ * `/proc/meminfo` (by default half of the Windows RAM).
+ */
+import type { WslDistributionTransport } from '../wsl/index.js';
+import type { LinuxHost } from './linux-host.js';
+import type { CommandOutput, LinuxProbeDeps } from './linux-probe.js';
+/** The guest account every probe, recipe and docker call runs as. */
+export declare const GUEST_ROOT = "root";
+/** The docker CLI the guest recipe installs; never whatever `PATH` would find (a Windows `docker.exe`). */
+export declare const GUEST_DOCKER = "/usr/bin/docker";
+/** `df --output=avail -B1 <path>`: a header line, then the bytes. */
+export declare function parseDfAvail(output: CommandOutput): number | null;
+/** `nvidia-smi --version`'s `NVML version : 580.95.02` — the library version, Linux numbering. */
+export declare function parseNvmlVersion(output: CommandOutput): string | null;
+/** `/proc/meminfo`'s `MemTotal:  16303452 kB`, in bytes. */
+export declare function parseMemTotal(text: string | null): number | null;
+/** The guest's `LinuxProbeDeps`, honouring their contracts: `null`/`false` only for "not there". */
+export declare function guestProbeDeps(transport: WslDistributionTransport): LinuxProbeDeps;
+/** The guest as `probeLinux` reads it: root, no session runtime directory. */
+export declare function guestLinuxHost(transport: WslDistributionTransport): LinuxHost;
+/** What only the guest knows, read alongside `probeLinux`. */
+export interface GuestExtras {
+    /** The NVIDIA libraries WSL provides, Linux numbering; null when unread. */
+    nvidia_library_version: string | null;
+    /** The VM's memory, bytes; null when unread. */
+    memory_bytes: number | null;
+}
+export declare function probeGuestExtras(transport: WslDistributionTransport): Promise<GuestExtras>;

package/dist/runtime/environment/guest-host.js

@@ -0,0 +1,88 @@
+/**
+ * Atomic Chat's own WSL distribution, seen as a Linux host (change `add-tensorrt-llm-windows`,
+ * design D1): the same `LinuxProbeDeps` the Linux provisioner reads a machine through, answered by
+ * commands run in the guest through the WSL transport — so `probeLinux` and `assessLinux` judge the
+ * guest exactly as they judge a Linux host, and nothing about Docker or the toolkit is written twice.
+ *
+ * Everything runs as the guest's root (design D3): root in a distribution the user owns gives no
+ * rights on Windows, and Docker is reached through its system socket without a `docker` group. No
+ * command goes through a shell: a file is read with `cat`, its existence checked with `test -e`, free
+ * space with `df`, each as its own argv.
+ *
+ * Two facts only the guest has (spec "Память и драйвер оцениваются по гостю"): the version of the
+ * NVIDIA user-space libraries WSL hands the guest (`/usr/lib/wsl/lib`), in Linux numbering — the guest's
+ * `nvidia-smi` reports the *Windows* driver's number (591.xx), which is not comparable with a
+ * descriptor's `minimum_driver_version`, while the NVML library's own version is (design D10:
+ * `nvidia-smi --version`'s `NVML version` line) — and the VM's memory, from the guest's
+ * `/proc/meminfo` (by default half of the Windows RAM).
+ */
+/** The guest account every probe, recipe and docker call runs as. */
+export const GUEST_ROOT = 'root';
+/** The docker CLI the guest recipe installs; never whatever `PATH` would find (a Windows `docker.exe`). */
+export const GUEST_DOCKER = '/usr/bin/docker';
+/** How long one guest command may take: the first one also boots the distribution. */
+const GUEST_TIMEOUT_MS = 120_000;
+const run = (transport, argv) => transport.exec(argv, { user: GUEST_ROOT, timeoutMs: GUEST_TIMEOUT_MS });
+/** `df --output=avail -B1 <path>`: a header line, then the bytes. */
+export function parseDfAvail(output) {
+    if (output.code !== 0)
+        return null;
+    const lines = output.stdout.trim().split('\n');
+    const value = Number(lines[lines.length - 1]?.trim());
+    return lines.length >= 2 && Number.isSafeInteger(value) ? value : null;
+}
+/** `nvidia-smi --version`'s `NVML version : 580.95.02` — the library version, Linux numbering. */
+export function parseNvmlVersion(output) {
+    if (output.code !== 0)
+        return null;
+    const match = /^\s*NVML version\s*:\s*([0-9][0-9.]*)\s*$/im.exec(output.stdout);
+    return match === null ? null : match[1];
+}
+/** `/proc/meminfo`'s `MemTotal:  16303452 kB`, in bytes. */
+export function parseMemTotal(text) {
+    if (text === null)
+        return null;
+    const match = /^MemTotal:\s+(\d+)\s*kB\s*$/m.exec(text);
+    return match === null ? null : Number(match[1]) * 1024;
+}
+/** The guest's `LinuxProbeDeps`, honouring their contracts: `null`/`false` only for "not there". */
+export function guestProbeDeps(transport) {
+    const exists = async (path) => {
+        const tested = await run(transport, ['test', '-e', path]);
+        if (tested.code === 0)
+            return true;
+        if (tested.code === 1)
+            return false;
+        throw new Error(`could not check ${path} in the distribution: ${tested.stderr.trim()}`);
+    };
+    return {
+        // The guest's own environment is not this process's: an `env` overlay has nothing to apply to.
+        exec: (command, args) => run(transport, [command === 'docker' ? GUEST_DOCKER : command, ...args]),
+        readFile: async (path) => {
+            if (!(await exists(path)))
+                return null;
+            const read = await run(transport, ['cat', '--', path]);
+            if (read.code !== 0)
+                throw new Error(`could not read ${path} in the distribution: ${read.stderr.trim()}`);
+            return read.stdout;
+        },
+        pathExists: exists,
+        freeDiskBytes: async (path) => parseDfAvail(await run(transport, ['df', '--output=avail', '-B1', path])),
+    };
+}
+/** The guest as `probeLinux` reads it: root, no session runtime directory. */
+export function guestLinuxHost(transport) {
+    return {
+        probeDeps: guestProbeDeps(transport),
+        options: () => ({ user: GUEST_ROOT, xdgRuntimeDir: null }),
+    };
+}
+export async function probeGuestExtras(transport) {
+    const deps = guestProbeDeps(transport);
+    const [smi, meminfo] = await Promise.all([
+        run(transport, ['nvidia-smi', '--version']),
+        deps.readFile('/proc/meminfo').catch(() => null),
+    ]);
+    return { nvidia_library_version: parseNvmlVersion(smi), memory_bytes: parseMemTotal(meminfo) };
+}
+//# sourceMappingURL=guest-host.js.map

package/dist/runtime/environment/guest-host.js.map

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

package/dist/runtime/environment/host-exec.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Running a read-only probe command on the real machine.
+ *
+ * The probes (`linux-probe`, `windows-probe`) are pure over an injected `exec`; this is the one that
+ * actually spawns. Three things about it are deliberate.
+ *
+ * There is no shell. The command and every argument go to `spawn` as they are, so nothing in a path,
+ * a user name or a registry value is ever interpreted.
+ *
+ * A command that could not answer is reported as `code: null`, the same as one that is not on the
+ * machine at all. That covers a missing binary, a spawn that failed and a command that hung past the
+ * deadline. The probes turn `null` into "unknown", and unknown blocks a setup rather than being read
+ * as "absent": a hung `nvidia-smi` is not evidence that there is no driver, and treating it as such
+ * would tell the user to install one they already have.
+ *
+ * Output is capped. A probe reads a few lines; a process that floods stdout is not allowed to fill
+ * the core's memory on the way to being ignored.
+ */
+import { spawn } from 'node:child_process';
+import type { CommandOutput } from './linux-probe.js';
+export interface HostExecOptions {
+    /** How long one command may take before it counts as unanswered. */
+    timeoutMs?: number;
+    /** Per stream. Anything past it is dropped, and the command still counts as answered. */
+    maxOutputBytes?: number;
+    /** Base environment every call spawns with. Defaults to inheriting `process.env` when omitted. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * When set, a command past its deadline gets SIGTERM first and this long to exit before SIGKILL,
+     * and the answer waits for it to exit. For a package manager: killed outright, dpkg can be left
+     * half-configured. Unset (the default for probes): SIGKILL and answer at once.
+     */
+    terminateGraceMs?: number;
+    /** Tests only: stands in for `child_process.spawn`. */
+    spawnProcess?: typeof spawn;
+}
+export type HostExec = (command: string, args: string[], env?: Record<string, string | undefined>) => Promise<CommandOutput>;
+export declare function hostExec(options?: HostExecOptions): HostExec;

package/dist/runtime/environment/host-exec.js

@@ -0,0 +1,145 @@
+/**
+ * Running a read-only probe command on the real machine.
+ *
+ * The probes (`linux-probe`, `windows-probe`) are pure over an injected `exec`; this is the one that
+ * actually spawns. Three things about it are deliberate.
+ *
+ * There is no shell. The command and every argument go to `spawn` as they are, so nothing in a path,
+ * a user name or a registry value is ever interpreted.
+ *
+ * A command that could not answer is reported as `code: null`, the same as one that is not on the
+ * machine at all. That covers a missing binary, a spawn that failed and a command that hung past the
+ * deadline. The probes turn `null` into "unknown", and unknown blocks a setup rather than being read
+ * as "absent": a hung `nvidia-smi` is not evidence that there is no driver, and treating it as such
+ * would tell the user to install one they already have.
+ *
+ * Output is capped. A probe reads a few lines; a process that floods stdout is not allowed to fill
+ * the core's memory on the way to being ignored.
+ */
+import { spawn } from 'node:child_process';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
+/**
+ * After a timed-out command has exited, how long to wait for its output pipes to close. A leftover
+ * grandchild can hold them open indefinitely, and `close` would wait for it.
+ */
+const PIPE_SETTLE_MS = 1_000;
+/** After SIGKILL, answer at the latest this much later, whatever the process table says. */
+const KILL_SETTLE_MS = 5_000;
+/**
+ * Overlays `overlay` onto `base` — a key mapped to a string sets it, a key mapped to `undefined`
+ * strips it, and every other key of `base` passes through untouched. This is the "merge, not
+ * replace" semantics `LinuxProbeDeps.exec`'s own `env` parameter documents (round 2, item 10): a
+ * caller stripping `DOCKER_HOST` for one call must not also lose `PATH` for it.
+ */
+function overlayEnv(base, overlay) {
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(overlay)) {
+        if (value === undefined)
+            delete merged[key];
+        else
+            merged[key] = value;
+    }
+    return merged;
+}
+export function hostExec(options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const limit = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    return (command, args, envOverlay) => new Promise((resolve) => {
+        let settled = false;
+        const stdout = [];
+        const stderr = [];
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        // Unset until spawn succeeds: a spawn that throws leaves nothing to kill.
+        let child;
+        // Armed before the spawn, so every way of finishing — including a spawn that throws on the
+        // spot — has a real timer to clear, and none of them can reach it before it exists.
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            if (options.terminateGraceMs === undefined || child === undefined) {
+                child?.kill('SIGKILL');
+                finish({ code: null, stdout: '', stderr: `timed out after ${timeoutMs} ms` });
+                releasePipes();
+                return;
+            }
+            // Ask first, then insist. The answer comes when the process is gone (`exit`, then a moment
+            // for the pipes), or at the latest shortly after SIGKILL — never only on `close`.
+            timedOut = true;
+            child.kill('SIGTERM');
+            setTimeout(() => {
+                child?.kill('SIGKILL');
+                setTimeout(finishTimedOut, KILL_SETTLE_MS).unref();
+            }, options.terminateGraceMs).unref();
+        }, timeoutMs);
+        timer.unref();
+        /**
+         * After a timeout has been answered: release our ends of the pipes, so a grandchild still
+         * holding theirs cannot keep this (possibly root) process alive.
+         */
+        const releasePipes = () => {
+            child?.stdout?.destroy();
+            child?.stderr?.destroy();
+        };
+        const finishTimedOut = () => {
+            const said = Buffer.concat(stderr).toString('utf8');
+            finish({ code: null, stdout: '', stderr: `${said}\ntimed out after ${timeoutMs} ms` });
+            releasePipes();
+        };
+        const finish = (output) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(output);
+        };
+        // No overlay for this call and no configured base: `spawn` gets no `env` key at all, which is
+        // how Node inherits `process.env` on its own — the same as before this parameter existed.
+        const spawnEnv = envOverlay === undefined ? options.env : overlayEnv(options.env ?? process.env, envOverlay);
+        try {
+            child = (options.spawnProcess ?? spawn)(command, args, {
+                shell: false,
+                windowsHide: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                ...(spawnEnv === undefined ? {} : { env: spawnEnv }),
+            });
+        }
+        catch (error) {
+            // `spawn` throws synchronously for some malformed calls; that is an unanswered command.
+            finish({ code: null, stdout: '', stderr: error.message });
+            return;
+        }
+        child.stdout?.on('data', (chunk) => {
+            if (stdoutBytes >= limit)
+                return;
+            const take = chunk.subarray(0, limit - stdoutBytes);
+            stdout.push(take);
+            stdoutBytes += take.length;
+        });
+        child.stderr?.on('data', (chunk) => {
+            if (stderrBytes >= limit)
+                return;
+            const take = chunk.subarray(0, limit - stderrBytes);
+            stderr.push(take);
+            stderrBytes += take.length;
+        });
+        // A binary that is not on the machine arrives here as ENOENT, not as an exit code.
+        child.on('error', (error) => finish({ code: null, stdout: '', stderr: error.message }));
+        child.on('exit', () => {
+            if (timedOut)
+                setTimeout(finishTimedOut, PIPE_SETTLE_MS).unref();
+        });
+        child.on('close', (code) => {
+            if (timedOut) {
+                finishTimedOut();
+                return;
+            }
+            finish({
+                code,
+                stdout: Buffer.concat(stdout).toString('utf8'),
+                stderr: Buffer.concat(stderr).toString('utf8'),
+            });
+        });
+    });
+}
+//# sourceMappingURL=host-exec.js.map

package/dist/runtime/environment/host-exec.js.map

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

package/dist/runtime/environment/host-step-failure.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What a `failed` host-step receipt becomes as the operation's error (task 2.23, finding F-4).
+ *
+ * The privileged step runs outside the core, as root; all the core gets back is the app's receipt.
+ * Since task 2.23 the receipt may carry the step's own `log_tail` (the executor's summary of the
+ * failed step, with the tail of docker.service's journal when Docker did not start, aeef103). The
+ * core never believes it as evidence of anything done, but it does read it for a cause it knows how
+ * to explain: dockerd finding no free address pool for its bridge. That failure otherwise reaches the
+ * user as "did not finish", with the real reason buried in the journal (3.10 acceptance run, F-2/F-4).
+ *
+ * Docker prints the same words for two causes, and the message follows what `daemon.json` says
+ * (review round 1): with no `bip`/`default-address-pools` there, its default pools are covered by the
+ * host's routes — typically a full-tunnel VPN; with one of them set, the ranges the user configured
+ * are the ones used up or overlapped. When `daemon.json` could not be read, the message says which is
+ * the likely one rather than asserting it.
+ *
+ * The cause is recognised by Docker's own words wherever they appear in the tail: `docker-service`
+ * (`enable --now`) is where the 3.10 host hit it, and the approved restart after the runtime
+ * configuration fails the same way on the same host. Nothing here runs as root or changes the
+ * executor; the raw tail stays in `details` either way.
+ */
+import type { ErrorBody, ManagedHostReceipt } from '../../contracts/index.js';
+/** dockerd's own message when no address pool is free (libnetwork `ipamutils`). */
+export declare const DOCKER_POOLS_EXHAUSTED = "all predefined address pools have been fully subnetted";
+/** Whether a step's log tail shows dockerd finding no free address pool. */
+export declare function poolsExhaustedIn(logTail: string | undefined): boolean;
+/**
+ * The operation error for a `failed` receipt: `MANAGED_PREREQUISITE_BLOCKED`, a message that names a
+ * recognised cause and its fix, and `details` holding the raw log tail (or, without one, the
+ * receipt id, as before task 2.23). `addressPoolsConfigured` is what `/etc/docker/daemon.json` says
+ * when the receipt arrived (`bip` or `default-address-pools` set); undefined when nobody read it.
+ */
+export declare function hostStepFailureError(receipt: Pick<ManagedHostReceipt, 'receipt_id' | 'log_tail'>, addressPoolsConfigured?: boolean | 'unknown'): ErrorBody;

package/dist/runtime/environment/host-step-failure.js

@@ -0,0 +1,34 @@
+import { DOCKER_ADDRESS_POOLS_INSTRUCTION } from './linux-docker-network.js';
+/** dockerd's own message when no address pool is free (libnetwork `ipamutils`). */
+export const DOCKER_POOLS_EXHAUSTED = 'all predefined address pools have been fully subnetted';
+/** Whether a step's log tail shows dockerd finding no free address pool. */
+export function poolsExhaustedIn(logTail) {
+    return (logTail ?? '').toLowerCase().includes(DOCKER_POOLS_EXHAUSTED);
+}
+/**
+ * The operation error for a `failed` receipt: `MANAGED_PREREQUISITE_BLOCKED`, a message that names a
+ * recognised cause and its fix, and `details` holding the raw log tail (or, without one, the
+ * receipt id, as before task 2.23). `addressPoolsConfigured` is what `/etc/docker/daemon.json` says
+ * when the receipt arrived (`bip` or `default-address-pools` set); undefined when nobody read it.
+ */
+export function hostStepFailureError(receipt, addressPoolsConfigured) {
+    const tail = receipt.log_tail?.trim() ?? '';
+    const details = tail === '' ? receipt.receipt_id : tail;
+    const failed = 'Preparing the system did not finish: Docker could not start';
+    if (!poolsExhaustedIn(tail)) {
+        return { code: 'MANAGED_PREREQUISITE_BLOCKED', message: 'Preparing the system did not finish.', details };
+    }
+    const words = `("${DOCKER_POOLS_EXHAUSTED}")`;
+    const message = addressPoolsConfigured === true
+        ? `${failed}: the address ranges set in /etc/docker/daemon.json ("default-address-pools" or ` +
+            `"bip") are used up or overlap routes on this machine ${words}. Set ranges there that no route ` +
+            'uses, then try again.'
+        : addressPoolsConfigured === false
+            ? `${failed}, because the routes on this machine (often a full-tunnel VPN) cover every address ` +
+                `range Docker uses for its networks by default ${words}. ${DOCKER_ADDRESS_POOLS_INSTRUCTION}`
+            : `${failed}: it found no free address range for its networks ${words}, most often because the ` +
+                'routes on this machine (a full-tunnel VPN) cover its default ranges, or because the ranges set ' +
+                `in /etc/docker/daemon.json are used up. ${DOCKER_ADDRESS_POOLS_INSTRUCTION}`;
+    return { code: 'MANAGED_PREREQUISITE_BLOCKED', message, details };
+}
+//# sourceMappingURL=host-step-failure.js.map

package/dist/runtime/environment/host-step-failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-step-failure.js","sourceRoot":"","sources":["../../../src/runtime/environment/host-step-failure.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,gCAAgC,EAAE,MAAM,2BAA2B,CAAA;AAE5E,mFAAmF;AACnF,MAAM,CAAC,MAAM,sBAAsB,GAAG,wDAAwD,CAAA;AAE9F,4EAA4E;AAC5E,MAAM,UAAU,gBAAgB,CAAC,OAA2B;IAC1D,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAAA;AACvE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAA4D,EAC5D,sBAA4C;IAE5C,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IAC3C,MAAM,OAAO,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAA;IACvD,MAAM,MAAM,GAAG,6DAA6D,CAAA;IAC5E,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,8BAA8B,EAAE,OAAO,EAAE,sCAAsC,EAAE,OAAO,EAAE,CAAA;IAC3G,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,sBAAsB,IAAI,CAAA;IAC7C,MAAM,OAAO,GACX,sBAAsB,KAAK,IAAI;QAC7B,CAAC,CAAC,GAAG,MAAM,kFAAkF;YAC3F,wDAAwD,KAAK,mCAAmC;YAChG,uBAAuB;QACzB,CAAC,CAAC,sBAAsB,KAAK,KAAK;YAChC,CAAC,CAAC,GAAG,MAAM,qFAAqF;gBAC9F,iDAAiD,KAAK,KAAK,gCAAgC,EAAE;YAC/F,CAAC,CAAC,GAAG,MAAM,qDAAqD,KAAK,2BAA2B;gBAC9F,iGAAiG;gBACjG,2CAA2C,gCAAgC,EAAE,CAAA;IACrF,OAAO,EAAE,IAAI,EAAE,8BAA8B,EAAE,OAAO,EAAE,OAAO,EAAE,CAAA;AACnE,CAAC"}

package/dist/runtime/environment/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The managed text-runtime environment: installing, updating and removing the container runtime a
+ * text engine needs, as an operation that survives the app closing, the core dying and the machine
+ * rebooting (openspec change `add-tensorrt-llm-linux`).
+ *
+ * The pieces, in the order a setup goes through them: `descriptor` reads the metadata that says
+ * what to install, `descriptor-provider` gets it from conf (or an override) over HTTPS, caches it by
+ * `descriptor_id`, applies the version gate, and pins an installation to the one it was set up with
+ * (task 2.3), `environment-manifest` and `environment-manifest-provider` do the same for the Linux
+ * environment manifest — the install recipe's qualified distributions, kept apart from any engine
+ * (change `extract-environment-manifest`) — over the mechanism both share (`cached-document`,
+ * `document-fields`), `canonical-json` hashes what consent and idempotency are decided on, `state` is
+ * the transition table, `store` keeps the record across restarts under a lock two cores respect,
+ * `recovery` reconciles a record against what the machine actually shows, and `service` turns each
+ * decision into one piece of injected external work. `host-exec` runs a read-only probe command for
+ * real; `linux-probe` and `windows-probe` are the pure assessments built on top of it — `wiring`
+ * only ever selects the Linux one (task 2.2): Windows is a non-goal of this change, so
+ * `windows-probe` is ported and tested but never registered. `linux-provisioner` is the Linux host
+ * recipe the service runs a setup and a removal through (task 2.6), over `linux-host` (the real
+ * machine, or the e2e test host) and `installations` (the records both scopes share). `inventory`
+ * is the one piece of the model-compatibility check (spec `tensorrt-llm-models`) that belongs
+ * here: the digest that pins a curated model's file listing.
+ *
+ * Public API of this module is exported from this file only.
+ */
+export * from './canonical-json.js';
+export * from './descriptor.js';
+export * from './descriptor-provider.js';
+export * from './diagnostics.js';
+export * from './environment-manifest.js';
+export * from './environment-manifest-provider.js';
+export * from './cached-document.js';
+export * from './host-exec.js';
+export * from './inventory.js';
+export * from './linux-docker-facts.js';
+export * from './linux-plan.js';
+export * from './linux-probe.js';
+export * from './recovery.js';
+export * from './service.js';
+export * from './state.js';
+export * from './store.js';
+export * from './wiring.js';
+export * from './windows-probe.js';
+export * from './installations.js';
+export * from './store-models.js';
+export * from './linux-host.js';
+export * from './linux-provisioner.js';
+export * from './guest-host.js';
+export * from './provisioner-descriptors.js';
+export * from './windows-environment-record.js';
+export * from './windows-host.js';
+export * from './windows-plan.js';
+export * from './windows-provisioner.js';
+export * from './windows-guest-setup.js';
+export * from './rootfs-download.js';
+export * from './windows-forwarding.js';