@atomic-chat/core 0.5.1 → 0.13.2

package/dist/runtime/environment/index.js

@@ -0,0 +1,57 @@
+/**
+ * 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';
+//# sourceMappingURL=index.js.map

package/dist/runtime/environment/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime/environment/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,0BAA0B,CAAA;AACxC,cAAc,kBAAkB,CAAA;AAChC,cAAc,2BAA2B,CAAA;AACzC,cAAc,oCAAoC,CAAA;AAClD,cAAc,sBAAsB,CAAA;AACpC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,yBAAyB,CAAA;AACvC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,wBAAwB,CAAA;AACtC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,8BAA8B,CAAA;AAC5C,cAAc,iCAAiC,CAAA;AAC/C,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AACjC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA"}

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

@@ -0,0 +1,25 @@
+import type { PlatformImage, RuntimeInstallation } from '../../contracts/index.js';
+export interface InstallationRecord {
+    schema_version: 1;
+    installation: RuntimeInstallation;
+    /** The image this installation runs, pulled by digest for `platform`. */
+    image: PlatformImage;
+    /**
+     * The GPU-check image the setup pulled for this installation, removed with it unless something
+     * else still uses it. Absent in a record from before it was kept.
+     */
+    probe_image?: PlatformImage;
+    platform: 'linux/amd64' | 'linux/arm64';
+    installed_at: string;
+}
+export declare class InstallationStore {
+    private readonly paths;
+    constructor(root: string);
+    read(installationId: string): Promise<InstallationRecord | null>;
+    /** Every readable installation. A torn or foreign file is skipped, never guessed at. */
+    list(): Promise<InstallationRecord[]>;
+    write(record: InstallationRecord): Promise<void>;
+    /** Idempotent: an installation already gone is removed. */
+    remove(installationId: string): Promise<void>;
+    private readPath;
+}

package/dist/runtime/environment/installations.js

@@ -0,0 +1,70 @@
+/**
+ * Which engines are installed in the environment (task 2.6): one record per installation under the
+ * shared per-user root, `installations/<installation_id>/installation.json`, written by the setup
+ * operation's activation and deleted by its removal. App and CLI cores read the same files, so a
+ * setup finished in one is `ready` in the other (spec "Окружение общее для app и cli…").
+ *
+ * The record pins the installation to its descriptor (`active_descriptor_id`, design D7) and keeps
+ * the exact platform image it pulled, so a removal can delete that image even when the cached
+ * descriptor is unreadable. Writes are atomic (a temp file per write, then a rename), and only one
+ * operation per environment runs at a time (`OperationStore`'s busy check), so no lock is needed
+ * beyond that.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { managedSharedPaths } from '../../config/index.js';
+const isRecord = (value) => {
+    const raw = value;
+    return (raw !== null &&
+        typeof raw === 'object' &&
+        raw.schema_version === 1 &&
+        typeof raw.installation?.installation_id === 'string' &&
+        typeof raw.installation.engine_id === 'string' &&
+        typeof raw.image?.repository === 'string' &&
+        typeof raw.image.digest === 'string');
+};
+export class InstallationStore {
+    paths;
+    constructor(root) {
+        this.paths = managedSharedPaths(root);
+    }
+    async read(installationId) {
+        return this.readPath(this.paths.installationFile(installationId));
+    }
+    /** Every readable installation. A torn or foreign file is skipped, never guessed at. */
+    async list() {
+        const names = await readdir(this.paths.installationsDir).catch(() => []);
+        const records = [];
+        for (const name of names.sort()) {
+            const record = await this.readPath(join(this.paths.installationsDir, name, 'installation.json'));
+            if (record !== null)
+                records.push(record);
+        }
+        return records;
+    }
+    async write(record) {
+        const path = this.paths.installationFile(record.installation.installation_id);
+        await mkdir(dirname(path), { recursive: true });
+        const tmp = `${path}.${randomUUID()}.tmp`;
+        await writeFile(tmp, `${JSON.stringify(record, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+        await rename(tmp, path).catch(async (error) => {
+            await rm(tmp, { force: true }).catch(() => undefined);
+            throw error;
+        });
+    }
+    /** Idempotent: an installation already gone is removed. */
+    async remove(installationId) {
+        await rm(dirname(this.paths.installationFile(installationId)), { recursive: true, force: true });
+    }
+    async readPath(path) {
+        try {
+            const parsed = JSON.parse(await readFile(path, 'utf8'));
+            return isRecord(parsed) ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=installations.js.map

package/dist/runtime/environment/installations.js.map

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

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

@@ -0,0 +1,42 @@
+/**
+ * What makes two listings of a checkpoint's files the same inventory.
+ *
+ * `RuntimeDescriptor.curated_models[].inventory_digest` (`src/contracts/environment.ts`) pins a
+ * curated entry to an exact Hugging Face file listing, not just a repository and revision: a branch
+ * name moves, a revision can be re-tagged, and a repository can be re-uploaded with a file added or
+ * a shard replaced, so the digest is what a `ModelCompatibility` check (spec `tensorrt-llm-models`)
+ * actually compares against a submitted file list to decide `curated: true`.
+ *
+ * The algorithm has to be byte-for-byte identical with `atomic-chat-conf`'s own
+ * `.github/scripts/inventory-digest.mjs`, which computes it the same way to publish a descriptor's
+ * `curated_models[].inventory_digest` in the first place (see that repo's README, "Runtime
+ * descriptors"). Neither side may drift from the other: a mismatch would mean a curated checkpoint
+ * that this core can never recognise as the one the descriptor pinned.
+ *
+ * Design D12 keeps this to the pure digest only. Fetching a repository's file listing, resolving
+ * which storage domain a downloaded artifact lives in and naming the bytes on disk are the
+ * app's/CLI's job now, not core's — core never downloads model weights, so there is nothing here
+ * about a storage domain, an artifact id or a download plan, unlike the branch this was ported from
+ * (`origin/feat/tenzor-rt` @ `632b934`'s `src/models/snapshot-plan.ts`, which combined the digest
+ * with exactly that machinery for a design core no longer has).
+ */
+import type { Sha256Digest } from '../../contracts/index.js';
+/**
+ * One file of a checkpoint, as the repository lists it. Every file counts, not only weights: an
+ * engine's own file-type selection happens later and is not part of a checkpoint's identity (conf
+ * README, "Runtime descriptors").
+ */
+export interface InventoryFile {
+    /** Repository-relative, forward slashes, as Hugging Face spells it. */
+    path: string;
+    bytes: number;
+    /** The repository's own digest where it publishes one; absent is normal and not an error. */
+    sha256?: string;
+}
+/**
+ * The digest of a file listing: every file's path, size and published digest, in path order.
+ *
+ * Sorted because a registry may list the same files in any order and that is not a difference.
+ * Length-prefixed because `a`+`bc` and `ab`+`c` must not collide.
+ */
+export declare function inventoryDigest(files: readonly InventoryFile[]): Sha256Digest;

package/dist/runtime/environment/inventory.js

@@ -0,0 +1,57 @@
+/**
+ * What makes two listings of a checkpoint's files the same inventory.
+ *
+ * `RuntimeDescriptor.curated_models[].inventory_digest` (`src/contracts/environment.ts`) pins a
+ * curated entry to an exact Hugging Face file listing, not just a repository and revision: a branch
+ * name moves, a revision can be re-tagged, and a repository can be re-uploaded with a file added or
+ * a shard replaced, so the digest is what a `ModelCompatibility` check (spec `tensorrt-llm-models`)
+ * actually compares against a submitted file list to decide `curated: true`.
+ *
+ * The algorithm has to be byte-for-byte identical with `atomic-chat-conf`'s own
+ * `.github/scripts/inventory-digest.mjs`, which computes it the same way to publish a descriptor's
+ * `curated_models[].inventory_digest` in the first place (see that repo's README, "Runtime
+ * descriptors"). Neither side may drift from the other: a mismatch would mean a curated checkpoint
+ * that this core can never recognise as the one the descriptor pinned.
+ *
+ * Design D12 keeps this to the pure digest only. Fetching a repository's file listing, resolving
+ * which storage domain a downloaded artifact lives in and naming the bytes on disk are the
+ * app's/CLI's job now, not core's — core never downloads model weights, so there is nothing here
+ * about a storage domain, an artifact id or a download plan, unlike the branch this was ported from
+ * (`origin/feat/tenzor-rt` @ `632b934`'s `src/models/snapshot-plan.ts`, which combined the digest
+ * with exactly that machinery for a design core no longer has).
+ */
+import { createHash } from 'node:crypto';
+import { AtomicCoreError } from '../../contracts/index.js';
+const NUL = String.fromCharCode(0);
+/**
+ * The digest of a file listing: every file's path, size and published digest, in path order.
+ *
+ * Sorted because a registry may list the same files in any order and that is not a difference.
+ * Length-prefixed because `a`+`bc` and `ab`+`c` must not collide.
+ */
+export function inventoryDigest(files) {
+    if (files.length === 0) {
+        throw new AtomicCoreError('MANAGED_METADATA_INVALID', 'A checkpoint with no files is not a checkpoint.');
+    }
+    const seen = new Set();
+    const hash = createHash('sha256');
+    const sorted = [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    for (const file of sorted) {
+        if (file.path === '' || file.path.includes(NUL)) {
+            throw new AtomicCoreError('MANAGED_METADATA_INVALID', "An artifact's file path cannot be empty.", file.path);
+        }
+        if (seen.has(file.path)) {
+            throw new AtomicCoreError('MANAGED_METADATA_INVALID', 'The inventory lists a file twice.', file.path);
+        }
+        seen.add(file.path);
+        if (!Number.isSafeInteger(file.bytes) || file.bytes < 0) {
+            throw new AtomicCoreError('MANAGED_METADATA_INVALID', 'A file size is not a whole number.', file.path);
+        }
+        hash.update(`${file.path.length}:${file.path}`);
+        hash.update(`|${file.bytes}|`);
+        hash.update(file.sha256 ?? '');
+        hash.update(NUL);
+    }
+    return `sha256:${hash.digest('hex')}`;
+}
+//# sourceMappingURL=inventory.js.map

package/dist/runtime/environment/inventory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inventory.js","sourceRoot":"","sources":["../../../src/runtime/environment/inventory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAgB1D,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA;AAElC;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAA+B;IAC7D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,eAAe,CAAC,0BAA0B,EAAE,iDAAiD,CAAC,CAAA;IAC1G,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAA;IACjC,MAAM,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC1F,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,eAAe,CACvB,0BAA0B,EAC1B,0CAA0C,EAC1C,IAAI,CAAC,IAAI,CACV,CAAA;QACH,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,eAAe,CAAC,0BAA0B,EAAE,mCAAmC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAA;QACvG,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACnB,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,eAAe,CAAC,0BAA0B,EAAE,oCAAoC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAA;QACxG,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;QAC/C,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,CAAA;QAC9B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAA;QAC9B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAClB,CAAC;IACD,OAAO,UAAU,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;AACvC,CAAC"}

package/dist/runtime/environment/linux-blockers.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The structured reasons `assessLinux` (`linux-plan.ts`) refuses a host — split out of that file
+ * once it grew past the ~500-line guidance for this module (task 2.4 fix round 2). Everything here
+ * is pure: a reason code, the message a person reads, and the machine-checkable specifics. A few
+ * small, self-contained decision helpers moved in alongside them in round 3, for the same reason
+ * (`linux-plan.ts` growing past the guidance again): `effectiveGpuRuntime` and the two exact-command
+ * builders (`archCommands`, `groupOnlyCommands`) that blockers built here actually use. Round 4 moved
+ * the install-gate blockers here too (`gateBlocker`), and added the relogin path's per-component
+ * blockers (`missingComponentBlockers`).
+ */
+import type { LinuxDistribution, LinuxFacts } from './linux-probe.js';
+/**
+ * A stable, machine-readable reason a host is blocked — for a client to switch on, or a test to
+ * assert against, instead of matching on `message` text (item 8).
+ */
+export type LinuxBlockerReason = 'unknown-fact' | 'unsupported-architecture' | 'driver-missing' | 'driver-too-old' | 'no-gpu' | 'compute-capability-too-low' | 'docker-snap' | 'docker-rootless' | 'docker-desktop-only' | 'podman-docker' | 'docker-unrecognised' | 'immutable-os' | 'distribution-not-in-recipe'
+/** The environment manifest — the recipe's distribution list — could not be had (change `extract-environment-manifest`, D5). */
+ | 'environment-manifest-unavailable' | 'arch-manual-install' | 'insufficient-disk' | 'daemon-json-unreadable'
+/** Group membership confirmed and effective, service active, daemon still unreachable (round 2, item 2). */
+ | 'docker-access-unexplained'
+/** Everything but group membership is ready, and automatic elevation is not offered here (round 2, item 5). */
+ | 'docker-group-manual'
+/** Group membership confirmed but this session predates it — a relogin, never an install plan, on any distro (round 3, ruling 4). */
+ | 'relogin-required'
+/** Emitted next to `relogin-required` for each other component offline evidence shows missing (round 4, item 1). */
+ | 'docker-cli-missing' | 'toolkit-missing' | 'gpu-runtime-not-configured' | 'docker-service-inactive'
+/** No systemd (`/run/systemd/system` absent): the recipe's service steps would fail after consent. */
+ | 'init-not-systemd';
+/**
+ * One reason a host cannot proceed. `params` carries the machine-checkable specifics (required vs.
+ * actual version, the distro tuple, ...); `commands`, when present, are exact, copyable shell
+ * commands (Arch's manual install, or the single `usermod` a group-only host needs); `message` is
+ * what a person reads.
+ */
+export interface LinuxBlocker {
+    reason: LinuxBlockerReason;
+    message: string;
+    params?: Record<string, string>;
+    commands?: string[];
+}
+export declare function blocker(reason: LinuxBlockerReason, message: string, params?: Record<string, string>, commands?: string[]): LinuxBlocker;
+/**
+ * A Docker install this integration will never adopt or install over, regardless of whether it
+ * happens to expose a GPU runtime — there is no safe way to lay `docker-ce` next to or over it.
+ */
+export declare function installMethodBlocker(method: LinuxFacts['docker']['install_method']): LinuxBlocker | null;
+/**
+ * Whether the GPU reaches a container: a listed NVIDIA CDI device (task 2.23, F-5), from `docker
+ * info`'s side when the daemon answered, from `nvidia-ctk cdi list` alone when it did not (item 3).
+ */
+export declare function effectiveGpuRuntime(facts: LinuxFacts): boolean;
+/**
+ * The commands a host missing only its `docker` group membership needs — everything else is
+ * already ready. An rpm-ostree host (Silverblue/Kinoite/Bazzite) needs one step first: package
+ * layering puts the `docker` group's line in `/usr/lib/group` (the vendor/OS-tree database), but
+ * `/etc/group` — what `usermod`/`getent` actually consult — does not inherit it automatically, so
+ * `usermod -aG docker` alone would fail with "group 'docker' does not exist" (round 3, ruling 6).
+ * Never called for root (D4): root needs no group membership, and the caller never reaches here for it.
+ */
+export declare function groupOnlyCommands(immutableOs: boolean, user: string): string[];
+/**
+ * Arch never supports a partial `pacman -S` of just these two packages (design D2): installing a
+ * package without syncing the whole system can leave it inconsistent, so the commands run a full
+ * `-Syu` instead — which may itself bring in a newer kernel and NVIDIA driver, hence the reboot
+ * note. The CDI spec is generated too (task 2.23, F-5: Docker 28.2+ passes `--gpus` through it).
+ * `nvidia-ctk runtime configure` changes `/etc/docker/daemon.json`, so Docker is explicitly
+ * restarted afterward rather than relying on `enable --now` to notice the new config on its own
+ * (item 12). The `usermod` line uses the actual probed account, never the literal `$USER`, and is
+ * omitted entirely for root, which needs no group membership at all (round 3, ruling 8), and for an
+ * account that is already a member (round 5, item 1: `groupNeeded` false).
+ */
+export declare function archCommands(user: string, groupNeeded?: boolean): string[];
+/** Group membership confirmed, but this login session predates it (round 3, ruling 4). */
+export declare function reloginRequiredBlocker(): LinuxBlocker;
+/**
+ * How far automatic setup can go on this host, decided in this order: an immutable base, Arch and its
+ * derivatives, a `docker` command no package database recognises, no environment manifest to read the
+ * recipe's distributions from (`'manifest-unavailable'`, change `extract-environment-manifest` D5 — a
+ * different cause from `'unqualified'`, with a different fix), a distribution/version/architecture not
+ * on the manifest's recipe — or `'recipe'` when none of those applies and a plan may be offered.
+ * `assessLinux` computes it once and uses it on every path (group-only, relogin, full install), so the
+ * paths cannot drift apart (round 4).
+ */
+export type InstallGate = 'recipe' | 'immutable' | 'pacman' | 'unrecognised' | 'manifest-unavailable' | 'unqualified';
+/**
+ * Whether the gate's own blocker applies to this host — one decision, read by the relogin path and the
+ * full-install path alike (round 5, item 2). Never on a recipe distribution. On an immutable base only
+ * when a package (Docker or the toolkit) is missing, since layering packages is what the gate is about
+ * (spec: "система неизменяемая … и Docker или toolkit нет"); a missing runtime configuration or a
+ * stopped service is an ordinary step there, reported per component. Every other gate always applies.
+ */
+export declare function gateBlockerApplies(gate: InstallGate, facts: LinuxFacts): boolean;
+/**
+ * The exact commands for joining the `docker` group, for a host where automatic setup is not offered.
+ * `everythingElseReady` picks the wording: the only step left, or one step among others (round 5).
+ */
+export declare function dockerGroupManualBlocker(immutableOs: boolean, user: string, everythingElseReady: boolean): LinuxBlocker;
+/** Why automatic setup is not offered, for every gate but `'recipe'`. */
+export declare function gateBlocker(gate: Exclude<InstallGate, 'recipe'>, facts: LinuxFacts, distribution: LinuxDistribution, user: string): LinuxBlocker;
+/**
+ * No environment manifest: which distributions the install recipe is qualified for is unknown, so no
+ * automatic setup is offered — not because this distribution is unsupported, but because the list
+ * could not be had (no network and nothing cached, or none this core accepts). Retrying with a
+ * network is the fix; a ready host never sees this (it is adopted before any gate).
+ */
+export declare function environmentManifestUnavailableBlocker(): LinuxBlocker;
+/** Refuses to write next to a daemon.json this probe could not read or parse (round 2, item 6). */
+/**
+ * The recipe installs and starts Docker through systemd (`systemctl enable --now docker`, a restart
+ * after `nvidia-ctk runtime configure`), so on a host that does not run it — a container whose PID 1
+ * is a shell, as the vast.ai GB10 instance was — every such plan would fail only at the privileged
+ * step, after the user consented. Whether systemd runs could not be read is the unread fact
+ * `init-system` instead (`unknown-fact`), never this.
+ */
+export declare function initNotSystemdBlocker(): LinuxBlocker;
+export declare function daemonJsonUnreadableBlocker(): LinuxBlocker;
+/**
+ * One blocker per component offline evidence shows missing, for a host that also has to relogin
+ * (round 4, item 1 — the refined ruling 4): the Docker CLI, the NVIDIA Container Toolkit, the GPU
+ * runtime in Docker (or `daemon-json-unreadable` when that cannot be told), and `docker.service`
+ * when `systemctl` says it is not active. An `'unknown'` service state is not evidence of anything and
+ * is not reported. Empty when the relogin alone is the fix.
+ *
+ * What each one tells the person depends on the gate: on a recipe distribution setup will do it after
+ * the relogin, so there is nothing to run by hand; on Arch each carries its exact commands (a full
+ * `pacman -Syu` for packages, design D2); anywhere else the package steps have no command this
+ * integration can vouch for (the caller adds the gate's own blocker), while the runtime and service
+ * steps are the same `nvidia-ctk`/`systemctl` commands on every distribution.
+ */
+export declare function missingComponentBlockers(facts: LinuxFacts, gate: InstallGate): LinuxBlocker[];