@atomic-chat/core 0.5.1 → 0.13.2

package/dist/runtime/environment/windows-provisioner.js

@@ -0,0 +1,782 @@
+/**
+ * The Windows host recipe behind `EnvironmentService` (change `add-tensorrt-llm-windows`; spec
+ * `wsl-runtime-environment`): what a setup and a removal of a managed engine do on Windows, where the
+ * engine runs in a WSL distribution Atomic Chat imports and owns — one method per effect the reducer
+ * (`state.ts`) can ask for, like the Linux provisioner, over the same descriptor, installations and
+ * operation machinery.
+ *
+ * - **probe** reads Windows (`probeWindowsHost`), Atomic Chat's own environment record, and — when its
+ *   distribution is registered — the guest as a Linux host (`guest-host.ts`, design D1), and judges
+ *   them (`assessWindowsHost`) against the descriptor and the Windows environment manifest. An
+ *   environment that exists keeps the manifest it was imported by (spec "Окружение Windows закрепляет
+ *   свой манифест"); a new one is judged by the newest.
+ *
+ * Nothing here runs `wsl.exe` from an elevated process: the core is the user's own, and a core started
+ * elevated is blocked before anything is imported (`elevated-process`).
+ */
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { AtomicCoreError } from '../../contracts/index.js';
+import { containersUsingImage, inspectImage, pullImageWithCurl, removeContainer, removeImage, runOnce, stopContainer, } from '../container/index.js';
+import { GUEST_SCOPES_ROOT } from '../wsl/index.js';
+import { canonicalDigest } from './canonical-json.js';
+import { GUEST_DOCKER, GUEST_ROOT, guestLinuxHost, probeGuestExtras } from './guest-host.js';
+import { imageMatchesDigest, NOTHING_LOADED, ownedImageId, pickGpu, } from './linux-provisioner.js';
+import { probeLinux } from './linux-probe.js';
+import { descriptorForProbe, pinnedDescriptor } from './provisioner-descriptors.js';
+import { otherEngines } from './store-models.js';
+import { ATOMIC_CHAT_DISTRIBUTION, distributionDirectory, distributionDisk, } from './windows-host.js';
+import { checkLocalhostForwarding } from './windows-forwarding.js';
+import { importDistribution, restoreDefaultDistribution, setupGuest } from './windows-guest-setup.js';
+import { assessWindowsHost } from './windows-plan.js';
+import { normalizeWindowsArchitecture, parseRebootPending, parseWslDistributions, probeWindowsHost, REBOOT_PENDING_KEY, } from './windows-probe.js';
+const ZERO_DIGEST = `sha256:${'0'.repeat(64)}`;
+/** Checkpoints at which part or all of the engine image is already in the guest's layer store. */
+const PULL_PHASES = ['pulling-image', 'verifying', 'activating'];
+/**
+ * The image platform of Atomic Chat's distribution: the machine's own architecture, which is also the
+ * architecture of the rootfs its manifest imports (`windows.json` x86_64, `windows-arm64.json`
+ * aarch64). An x86_64 constant here pulled the amd64 GPU-check image onto Windows on Arm, where its
+ * `nvidia-smi` cannot run (NVIDIA RTX Spark N1X, 2026-10-06). Another architecture never gets this
+ * far: the plan blocks it as `unsupported-architecture`.
+ */
+export function windowsGuestPlatform(machine) {
+    return normalizeWindowsArchitecture(machine) === 'aarch64' ? 'linux/arm64' : 'linux/amd64';
+}
+const STOP_TIMEOUT_SECONDS = 10;
+/** The unsupported verdicts: what hides the provider rather than blocking a plan. */
+const METADATA_REASONS = ['environment-manifest-unavailable'];
+/** A `WindowsBlocker` on the wire, the same shape a Linux blocker takes (`toManagedBlocker`). */
+export function toWindowsManagedBlocker(entry) {
+    return {
+        code: METADATA_REASONS.includes(entry.reason)
+            ? 'MANAGED_METADATA_INVALID'
+            : 'MANAGED_PREREQUISITE_BLOCKED',
+        message: entry.message,
+        details: entry.reason,
+        reason: entry.reason,
+        ...(entry.params === undefined ? {} : { params: entry.params }),
+        ...(entry.commands === undefined ? {} : { commands: entry.commands }),
+    };
+}
+export function createWindowsProvisioner(deps) {
+    const newId = deps.newId ?? randomUUID;
+    const now = deps.now ?? (() => new Date());
+    const wsl = deps.host.probeDeps.wsl;
+    const guestPlatform = windowsGuestPlatform(deps.host.probeDeps.machine());
+    /** The guest's docker CLI, as root, by its absolute path, over the transport (design D3). */
+    const guestDocker = (transport) => (args, call) => transport.exec([GUEST_DOCKER, ...args], {
+        user: GUEST_ROOT,
+        ...(call?.timeoutMs === undefined ? {} : { timeoutMs: call.timeoutMs }),
+    });
+    /** Read Windows, the record, and the guest when ours is there and can start. Changes nothing. */
+    const look = async () => {
+        const [facts, record] = await Promise.all([probeWindowsHost(deps.host.probeDeps), deps.records.read()]);
+        const name = record?.distribution.name ?? ATOMIC_CHAT_DISTRIBUTION;
+        const path = record?.distribution.path ?? distributionDirectory(deps.host.localAppData, name);
+        const registered = facts.distributions.find((entry) => entry.name === name) ?? null;
+        const owned = record === null ? null : registered;
+        const foreign = record === null && registered !== null;
+        let guest = null;
+        if (owned !== null && owned.version === 2 && facts.wsl.ready === true) {
+            const transport = wsl.distribution(owned.name);
+            const host = guestLinuxHost(transport);
+            const [linux, extras] = await Promise.all([
+                probeLinux(host.probeDeps, host.options()),
+                probeGuestExtras(transport),
+            ]);
+            guest = { facts: linux, extras };
+        }
+        return { facts, record, owned, foreign, distribution: { name, path }, guest };
+    };
+    /**
+     * The manifest a probe judges by. An existing environment keeps the one it was imported by, from
+     * the cache — or, when the cache lost it, conf's only if it still serves that very id. Before an
+     * import: the consented one once work began, otherwise the newest.
+     */
+    const manifestFor = async (record, environment) => {
+        const pinnedId = environment?.manifest_id ?? record.machine.consented?.environment_manifest_id ?? null;
+        if (environment !== null || record.machine.consented != null) {
+            if (pinnedId === null)
+                return null;
+            const pinned = await deps.environmentManifests.pinned(pinnedId);
+            if (pinned.kind === 'available')
+                return pinned.manifest;
+            const again = await deps.environmentManifests.latest();
+            return again.kind === 'available' && again.manifest.manifest_id === pinnedId ? again.manifest : null;
+        }
+        const latest = await deps.environmentManifests.latest();
+        return latest.kind === 'available' ? latest.manifest : null;
+    };
+    const imagePresent = async (transport, image) => {
+        const inspected = await inspectImage(guestDocker(transport), image).catch(() => null);
+        return inspected !== null && inspected.found && imageMatchesDigest(inspected.value, image);
+    };
+    const blockedPlan = (record, availability, blockers) => ({
+        plan_digest: canonicalDigest({ blocked: blockers.map((entry) => entry.reason ?? entry.code) }),
+        environment_id: deps.environmentId,
+        target: record.machine.operation.target,
+        availability,
+        recipe_id: 'none',
+        recipe_digest: ZERO_DIGEST,
+        descriptor_id: null,
+        environment_manifest_id: null,
+        image_digest: null,
+        adopts_existing_engine: false,
+        system_changes: [],
+        download_bytes: null,
+        required_disk_bytes: null,
+        docker_root_dir: null,
+        free_disk_bytes: null,
+        requires_elevation: false,
+        may_require_relogin: false,
+        may_require_reboot: false,
+        blockers,
+        warnings: [],
+    });
+    const setupProbe = async (record) => {
+        const resolved = await descriptorForProbe(deps.descriptors, record);
+        if ('blocker' in resolved) {
+            const plan = blockedPlan(record, 'unsupported', [resolved.blocker]);
+            deps.onAssessment?.({ availability: 'unsupported', gpus: [], blockers: plan.blockers, selinux: null });
+            return { plan, host_step: null };
+        }
+        const descriptor = resolved.descriptor;
+        const target = record.machine.operation.target;
+        const seen = await look();
+        const manifest = await manifestFor(record, seen.record);
+        const image = descriptor.image[guestPlatform];
+        const transport = seen.owned === null ? null : wsl.distribution(seen.owned.name);
+        const existing = target.kind === 'runtime' ? await deps.installations.read(target.installation_id) : null;
+        const present = target.kind === 'runtime' && transport !== null && seen.guest?.facts.docker.daemon_reachable === true
+            ? await imagePresent(transport, image)
+            : false;
+        const readyInstallation = existing !== null &&
+            existing.installation.status === 'ready' &&
+            existing.installation.active_descriptor_id === descriptor.descriptor_id;
+        const pullStarted = PULL_PHASES.includes(record.machine.checkpoint ?? 'checking');
+        const stillNeeded = target.kind !== 'runtime' || present || pullStarted || readyInstallation
+            ? null
+            : descriptor.required_disk_bytes;
+        const volumeFree = await deps.host.freeDiskBytes(seen.distribution.path).catch(() => null);
+        const assessment = assessWindowsHost({
+            facts: seen.facts,
+            manifest,
+            owned: seen.owned,
+            foreign: seen.foreign,
+            distribution: seen.distribution,
+            volumeFreeBytes: volumeFree,
+            guest: seen.guest,
+            guestRecipeId: manifest?.guest_recipe_id ?? deps.guestRecipe.recipe_id,
+            minimumDriverVersion: descriptor.minimum_driver_version,
+            minimumComputeCapability: descriptor.minimum_compute_capability,
+            requiredDiskBytes: stillNeeded,
+        });
+        const blockers = assessment.blockers.map(toWindowsManagedBlocker);
+        if (target.kind === 'runtime' && target.engine_id !== descriptor.engine_id) {
+            blockers.push({
+                code: 'MANAGED_METADATA_INVALID',
+                message: `The descriptor ${descriptor.descriptor_id} is for ${descriptor.engine_id}, not ${target.engine_id}.`,
+                reason: 'engine-mismatch',
+            });
+        }
+        if (existing !== null && existing.installation.active_descriptor_id !== descriptor.descriptor_id) {
+            blockers.push({
+                code: 'MANAGED_OPERATION_CONFLICT',
+                message: `This engine is already installed from ${String(existing.installation.active_descriptor_id)}; remove it before setting up ${descriptor.descriptor_id}.`,
+                reason: 'installed-with-other-descriptor',
+            });
+        }
+        const availability = assessment.availability === 'unsupported'
+            ? 'unsupported'
+            : blockers.length > 0
+                ? 'prerequisite-blocked'
+                : readyInstallation && assessment.adopts_existing_engine
+                    ? 'supported'
+                    : 'setup-required';
+        const systemChanges = blockers.length > 0 ? [] : assessment.system_changes;
+        const requiresElevation = blockers.length === 0 && assessment.enable_wsl;
+        const manifestId = manifest?.manifest_id ?? null;
+        const plan = {
+            plan_digest: canonicalDigest({
+                platform: 'windows',
+                target,
+                recipe_id: deps.guestRecipe.recipe_id,
+                recipe_digest: deps.guestRecipe.recipe_digest,
+                adopts_existing_engine: assessment.adopts_existing_engine,
+                system_changes: systemChanges,
+                requires_elevation: requiresElevation,
+                may_require_reboot: requiresElevation,
+                enable_wsl: requiresElevation ? deps.enableWsl.recipe_digest : null,
+                descriptor: { descriptor_id: descriptor.descriptor_id, image_digest: image.digest },
+                environment_manifest_id: manifestId,
+                host: {
+                    gpu_ids: seen.facts.gpus.map((gpu) => gpu.gpu_id).sort(),
+                    disk_sufficient: assessment.disk_sufficient,
+                    distribution: seen.distribution.name,
+                },
+                blockers: blockers.map((entry) => entry.reason ?? entry.code),
+            }),
+            environment_id: deps.environmentId,
+            target,
+            availability,
+            recipe_id: deps.guestRecipe.recipe_id,
+            recipe_digest: deps.guestRecipe.recipe_digest,
+            descriptor_id: descriptor.descriptor_id,
+            environment_manifest_id: manifestId,
+            image_digest: target.kind === 'runtime' ? image.digest : null,
+            adopts_existing_engine: assessment.adopts_existing_engine,
+            system_changes: systemChanges,
+            download_bytes: descriptor.download_bytes,
+            required_disk_bytes: descriptor.required_disk_bytes,
+            // The distribution's own directory and the space its disk can still take (ruling core 2.1).
+            docker_root_dir: assessment.free_disk_bytes === null ? null : seen.distribution.path,
+            free_disk_bytes: assessment.free_disk_bytes,
+            requires_elevation: requiresElevation,
+            may_require_relogin: false,
+            may_require_reboot: requiresElevation,
+            blockers,
+            warnings: [],
+        };
+        deps.onAssessment?.({
+            availability,
+            gpus: seen.facts.gpus,
+            blockers,
+            selinux: seen.guest?.facts.docker.daemon_reachable === true ? seen.guest.facts.docker.selinux : null,
+            distribution: seen.owned === null
+                ? null
+                : {
+                    name: seen.owned.name,
+                    path: seen.distribution.path,
+                    size_bytes: await deps.host
+                        .fileSize(distributionDisk(seen.distribution.path))
+                        .catch(() => null),
+                },
+            memory_bytes: seen.guest?.extras.memory_bytes ?? null,
+        });
+        // The one elevated step, with nothing in it a client could choose (design D2).
+        const hostStep = requiresElevation
+            ? {
+                step_id: `host-step-${newId()}`,
+                action: 'windows.enable-wsl',
+                recipe_id: deps.enableWsl.recipe_id,
+                recipe_digest: deps.enableWsl.recipe_digest,
+                parameters_digest: deps.enableWsl.parameters_digest,
+                parameters: {},
+                nonce: newId(),
+                // Stamped with the real revision when the step is issued (`state.ts`, `afterConsent`).
+                expected_operation_revision: 0,
+            }
+            : null;
+        return { plan, host_step: hostStep, image_present: present };
+    };
+    /**
+     * WSL answers `--version` and `--status`, and Windows is not waiting for a restart: the elevated
+     * step's work is in effect. `--status` exits 0 right after the install even though a WSL 2 VM cannot
+     * start until the restart, so the CBS restart flag decides that part.
+     */
+    const wslReady = async () => {
+        if ((await wsl.command(['--version'], { timeoutMs: 30_000 })).code !== 0)
+            return false;
+        if ((await wsl.command(['--status'], { timeoutMs: 30_000 })).code !== 0)
+            return false;
+        const system32 = `${deps.host.probeDeps.systemRoot.replace(/[\\/]+$/, '')}\\System32`;
+        const pending = parseRebootPending(await deps.host.probeDeps.exec(`${system32}\\reg.exe`, ['query', REBOOT_PENDING_KEY]));
+        return pending !== true;
+    };
+    const blocked = (message, reason) => new AtomicCoreError('MANAGED_PREREQUISITE_BLOCKED', message, reason);
+    const sleep = deps.sleep ??
+        ((ms, signal) => new Promise((resolve) => {
+            const timer = setTimeout(resolve, ms);
+            signal.addEventListener('abort', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        }));
+    /** The manifest the import uses: exactly the consented one, from the cache. */
+    const consentedManifest = async (record) => {
+        const id = record.machine.consented?.environment_manifest_id ??
+            record.requirement_plan?.environment_manifest_id ??
+            null;
+        if (id === null) {
+            throw new AtomicCoreError('MANAGED_METADATA_INVALID', 'This operation has no approved Windows environment manifest.');
+        }
+        const pinned = await deps.environmentManifests.pinned(id);
+        if (pinned.kind !== 'available')
+            throw new AtomicCoreError('MANAGED_METADATA_INVALID', pinned.error.message, id);
+        return pinned.manifest;
+    };
+    /**
+     * Import Atomic Chat's own distribution (D9): the rootfs downloaded and checked against the manifest's
+     * sha256 before it is used, the record written before `wsl --import` — so a core that dies mid-import
+     * still knows the name is ours — the download deleted afterwards, the user's default put back.
+     */
+    const importOwn = async (record, seen, signal) => {
+        const manifest = await consentedManifest(record);
+        const { name, path } = seen.distribution;
+        const previousDefault = seen.facts.distributions.find((entry) => entry.is_default)?.name ?? null;
+        const rootfs = join(deps.host.localAppData, 'AtomicChat', 'wsl', 'downloads', `${manifest.rootfs.sha256}.wsl`);
+        await deps.downloadRootfs(manifest.rootfs, rootfs, signal);
+        const environment = {
+            schema_version: 1,
+            executor: 'wsl-docker',
+            distribution: { name, path },
+            manifest_id: manifest.manifest_id,
+            imported_at: now().toISOString(),
+            marker: newId(),
+        };
+        await deps.records.write(environment);
+        try {
+            await importDistribution(wsl, { name, path, rootfs }, signal);
+        }
+        finally {
+            await deps.removeFile(rootfs).catch(() => undefined);
+        }
+        await restoreDefaultDistribution(wsl, previousDefault, signal);
+        return environment;
+    };
+    /** Docker and the toolkit in the guest by the Linux recipe, as guest root, when the guest still needs them. */
+    const provisionGuest = async (transport, manifest, descriptor, signal) => {
+        const seen = await look();
+        const assessment = assessWindowsHost({
+            facts: seen.facts,
+            manifest,
+            owned: seen.owned,
+            foreign: false,
+            distribution: seen.distribution,
+            volumeFreeBytes: null,
+            guest: seen.guest,
+            guestRecipeId: deps.guestRecipe.recipe_id,
+            minimumDriverVersion: descriptor.minimum_driver_version,
+            minimumComputeCapability: descriptor.minimum_compute_capability,
+            requiredDiskBytes: null,
+        });
+        if (assessment.blockers.length > 0) {
+            const first = assessment.blockers[0];
+            throw blocked(assessment.blockers.map((entry) => entry.message).join(' '), first.reason);
+        }
+        const plan = assessment.guest_plan;
+        if (plan === null)
+            return;
+        const distribution = seen.guest?.facts.distribution;
+        if (distribution === null || distribution === undefined || distribution.family !== 'apt') {
+            throw blocked('The Atomic Chat distribution is not the Ubuntu it was imported as.', 'distribution-not-in-recipe');
+        }
+        const parameters = deps.guestRecipe.parameters(plan, {
+            user: GUEST_ROOT,
+            // The plan let only a guest of the machine's own architecture this far.
+            arch: seen.facts.architecture === 'aarch64' ? 'aarch64' : 'x86_64',
+            family: 'apt',
+            distro_id: distribution.id,
+            version_id: distribution.version_id,
+        });
+        const ran = await deps.runGuestRecipe(transport, {
+            recipe_id: deps.guestRecipe.recipe_id,
+            recipe_digest: deps.guestRecipe.recipe_digest,
+            parameters,
+            parameters_digest: deps.guestRecipe.parametersDigest(parameters),
+        }, signal);
+        if (ran.outcome !== 'completed') {
+            throw blocked(`Installing Docker and the NVIDIA Container Toolkit in the distribution failed: ${ran.log_tail}`, 'guest-recipe-failed');
+        }
+    };
+    /** The GPU-check image through the guest's Engine API, then `nvidia-smi` in it on the chosen card (design D6). */
+    const checkGpu = async (transport, descriptor, seen, signal, own) => {
+        const gpu = pickGpu(seen.facts.gpus, descriptor.minimum_compute_capability);
+        if (gpu === null) {
+            throw blocked(`No GPU with compute capability ${descriptor.minimum_compute_capability} or newer was found.`, 'compute-capability-too-low');
+        }
+        const docker = guestDocker(transport);
+        const probeImage = descriptor.probe_image[guestPlatform];
+        // Only a GPU-check image this setup pulls itself is its to remove later (as on Linux).
+        const inspected = await inspectImage(docker, probeImage).catch(() => null);
+        if (inspected !== null && !inspected.found)
+            await own([ownedImageId(probeImage)]);
+        await pullImageWithCurl(probeImage, {
+            run: (argv, call) => transport.exec(argv, { user: GUEST_ROOT, ...call }),
+            signal,
+            verify: docker,
+        });
+        const result = await runOnce(docker, {
+            image: probeImage,
+            gpuUuid: gpu.gpu_id,
+            command: ['nvidia-smi', '--query-gpu=uuid', '--format=csv,noheader'],
+        });
+        if (result.code !== 0 || !result.stdout.includes(gpu.gpu_id)) {
+            throw new AtomicCoreError('MANAGED_PREREQUISITE_BLOCKED', `The GPU ${gpu.name} is not visible inside a container in the Atomic Chat distribution: the NVIDIA Container Toolkit did not pass it through. The engine image was not downloaded.`, [
+                `gpu=${gpu.gpu_id}`,
+                `exit=${String(result.code)}`,
+                `stdout=${result.stdout.trim().slice(-1000)}`,
+                `stderr=${result.stderr.trim().slice(-1000)}`,
+            ].join('\n'));
+        }
+    };
+    /** Atomic Chat's own distribution, as its record names it; no record is no environment. */
+    const ownTransport = async () => {
+        const environment = await deps.records.read();
+        if (environment === null) {
+            throw blocked('The Atomic Chat distribution is not set up on this computer.', 'no-distribution');
+        }
+        return wsl.distribution(environment.distribution.name);
+    };
+    const unload = deps.unloadEngineSessions ?? NOTHING_LOADED;
+    /** Runs one step of an operation with the distribution held, and lets go whatever happens. */
+    const held = async (what, step) => {
+        const lease = deps.keeper?.acquire(what);
+        try {
+            return await step();
+        }
+        finally {
+            lease?.release();
+        }
+    };
+    /** Engines installed in this environment: what an environment removal must refuse while any is. */
+    const installedEngines = async () => [...new Set((await deps.installations.list()).map((entry) => entry.installation.engine_id))].sort();
+    /** Every model in the distribution, of every scope (app and CLI share it), with its size in the guest. */
+    const guestModels = async (transport) => {
+        const found = await transport.exec(['find', GUEST_SCOPES_ROOT, '-name', 'model.yml', '-printf', '%h\n'], {
+            user: GUEST_ROOT,
+            timeoutMs: 120_000,
+        });
+        const dirs = found.stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => /\/models\/[^/]+\/.+/.test(line))
+            .sort();
+        if (dirs.length === 0)
+            return { ids: [], bytes: 0 };
+        const du = await transport.exec(['du', '-s', '-b', '--', ...dirs], {
+            user: GUEST_ROOT,
+            timeoutMs: 30 * 60_000,
+        });
+        const sizes = du.stdout
+            .split('\n')
+            .map((line) => /^(\d+)\t/.exec(line))
+            .filter((match) => match !== null)
+            .map((match) => Number(match[1]));
+        const ids = dirs.map((dir) => /\/models\/[^/]+\/(.+)$/.exec(dir)[1]);
+        return { ids, bytes: sizes.length === dirs.length ? sizes.reduce((sum, value) => sum + value, 0) : null };
+    };
+    /**
+     * The plan of an environment removal (design D12; spec "Окружение Windows удаляется целиком и только
+     * с согласием"): refused while an engine is installed; otherwise what goes — the distribution with
+     * its disk image and its size, and every model in it with their total — never another distribution.
+     */
+    const environmentRemovalProbe = async (record) => {
+        const target = record.machine.operation.target;
+        const engines = await installedEngines();
+        if (engines.length > 0) {
+            return {
+                plan: blockedPlan(record, 'prerequisite-blocked', [
+                    {
+                        code: 'MANAGED_PREREQUISITE_BLOCKED',
+                        message: `Remove ${engines.join(', ')} first: the environment is removed only once no engine is installed in it.`,
+                        details: 'engines-installed',
+                        reason: 'engines-installed',
+                        params: { engines: engines.join(',') },
+                    },
+                ]),
+                host_step: null,
+            };
+        }
+        const environment = await deps.records.read();
+        const changes = [];
+        if (environment !== null) {
+            const transport = wsl.distribution(environment.distribution.name);
+            const models = await guestModels(transport);
+            const size = await deps.host.fileSize(distributionDisk(environment.distribution.path)).catch(() => null);
+            if (models.ids.length > 0) {
+                changes.push({
+                    code: 'delete-models',
+                    text: `Delete the ${models.ids.length} model(s) in it${models.bytes === null ? '' : ` (${models.bytes} bytes)`}: ${models.ids.join(', ')}.`,
+                    params: { models: models.ids.join(','), bytes: models.bytes === null ? '' : String(models.bytes) },
+                });
+            }
+            changes.unshift({
+                code: 'unregister-distribution',
+                text: `Remove Atomic Chat’s WSL distribution "${environment.distribution.name}" (wsl --unregister) and everything in it, freeing its disk image in ${environment.distribution.path}. Your other distributions are not touched.`,
+                params: {
+                    name: environment.distribution.name,
+                    path: environment.distribution.path,
+                    size_bytes: size === null ? '' : String(size),
+                },
+            });
+        }
+        const plan = {
+            plan_digest: canonicalDigest({ kind: 'remove', platform: 'windows', target, system_changes: changes }),
+            environment_id: deps.environmentId,
+            target,
+            availability: environment === null ? 'setup-required' : 'supported',
+            recipe_id: 'none',
+            recipe_digest: ZERO_DIGEST,
+            descriptor_id: null,
+            environment_manifest_id: null,
+            image_digest: null,
+            adopts_existing_engine: true,
+            system_changes: changes,
+            download_bytes: null,
+            required_disk_bytes: null,
+            docker_root_dir: null,
+            free_disk_bytes: null,
+            requires_elevation: false,
+            may_require_relogin: false,
+            may_require_reboot: false,
+            blockers: [],
+            warnings: [],
+        };
+        return { plan, host_step: null };
+    };
+    /** `wsl --unregister` of exactly the recorded distribution, then the record; refused while an engine is installed. */
+    const removeEnvironment = async () => {
+        const engines = await installedEngines();
+        if (engines.length > 0) {
+            throw blocked(`Remove ${engines.join(', ')} first: the environment is removed only once no engine is installed in it.`, 'engines-installed');
+        }
+        const environment = await deps.records.read();
+        if (environment === null)
+            return;
+        const name = environment.distribution.name;
+        const registered = parseWslDistributions(await wsl.command(['--list', '--verbose'])).some((entry) => entry.name === name);
+        if (registered) {
+            const unregistered = await wsl.command(['--unregister', name], { timeoutMs: 10 * 60_000 });
+            if (unregistered.code !== 0) {
+                throw new AtomicCoreError('IO_ERROR', `WSL could not remove the distribution "${name}".`, `${unregistered.stdout.trim()} ${unregistered.stderr.trim()}`.trim());
+            }
+        }
+        await deps.records.remove();
+    };
+    const inventory = {
+        async inspect(effect, record) {
+            if (record.request.kind === 'remove')
+                return { kind: 'absent' };
+            try {
+                if (effect.kind === 'pull-image' || effect.kind === 'verify') {
+                    const descriptor = await pinnedDescriptor(deps.descriptors, record);
+                    return (await imagePresent(await ownTransport(), descriptor.image[guestPlatform]))
+                        ? { kind: 'completed', owned_resource_ids: [] }
+                        : { kind: 'absent' };
+                }
+                if (effect.kind === 'activate') {
+                    const target = record.machine.operation.target;
+                    const existing = target.kind === 'runtime' ? await deps.installations.read(target.installation_id) : null;
+                    const planned = record.machine.consented?.descriptor_id ?? record.requirement_plan?.descriptor_id ?? null;
+                    return existing !== null &&
+                        existing.installation.active_descriptor_id === planned &&
+                        existing.installation.status === 'ready'
+                        ? { kind: 'completed', owned_resource_ids: [] }
+                        : { kind: 'absent' };
+                }
+            }
+            catch {
+                // Nothing this core can check: the effect runs again, and fails there with its own reason.
+            }
+            return { kind: 'absent' };
+        },
+        needsRelogin: async () => false,
+        // Asked at every core start (`recovery.ts`): an operation waiting on a restart keeps waiting until
+        // WSL can start; then the probe that follows continues it under the consent it already has.
+        needsReboot: async (record) => record.machine.operation.phase === 'reboot-required' && !(await wslReady().catch(() => false)),
+        verifyCompletedSteps: async (record) => {
+            const steps = record.machine.operation.completed_step_ids;
+            if (steps.length === 0)
+                return [];
+            return (await wslReady().catch(() => false)) ? steps : [];
+        },
+        currentPlanDigest: async (record) => (await setupProbe(record).catch(() => null))?.plan.plan_digest ?? null,
+    };
+    return {
+        probe: (record) => record.request.kind === 'remove' && record.machine.operation.target.kind === 'environment'
+            ? environmentRemovalProbe(record)
+            : setupProbe(record),
+        async verifyHostStep(record) {
+            // The receipt is an assertion; the machine is the evidence (task 2.6's rule, on Windows too).
+            const answer = await setupProbe(record);
+            const { blockers } = answer.plan;
+            if (blockers.length > 0) {
+                return {
+                    prerequisites_met: false,
+                    needs_relogin: false,
+                    error: {
+                        code: blockers[0].code,
+                        message: `WSL was reported as enabled, but the machine says: ${blockers.map((entry) => entry.message).join(' ')}`,
+                        details: blockers.map((entry) => entry.reason ?? entry.code).join(','),
+                    },
+                };
+            }
+            if (answer.host_step !== null) {
+                const missing = {
+                    code: 'MANAGED_PREREQUISITE_BLOCKED',
+                    message: 'WSL was reported as enabled, but it does not start yet; Windows may need a restart.',
+                    details: 'enable-wsl',
+                };
+                return { prerequisites_met: false, needs_relogin: false, error: missing };
+            }
+            return { prerequisites_met: true, needs_relogin: false, error: null };
+        },
+        async prepare(record, signal, own) {
+            return held('preparing the environment', async () => {
+                const descriptor = await pinnedDescriptor(deps.descriptors, record);
+                const seen = await look();
+                if (seen.foreign) {
+                    throw blocked(`A WSL distribution named "${seen.distribution.name}" exists that Atomic Chat did not create; it is not used or changed.`, 'foreign-distribution');
+                }
+                if (seen.facts.wsl.installed !== true || seen.facts.wsl.ready !== true) {
+                    throw blocked('WSL is not ready on this computer yet.', 'wsl-not-ready');
+                }
+                const environment = seen.owned === null
+                    ? await importOwn(record, seen, signal)
+                    : seen.record;
+                const transport = wsl.distribution(environment.distribution.name);
+                await setupGuest({ wsl, sleep }, transport, environment.marker, signal);
+                const manifest = await deps.environmentManifests.pinned(environment.manifest_id);
+                await provisionGuest(transport, manifest.kind === 'available' ? manifest.manifest : null, descriptor, signal);
+                await checkGpu(transport, descriptor, seen, signal, own);
+            });
+        },
+        async pull(record, onProgress, signal) {
+            return held('pulling the engine image', async () => {
+                const descriptor = await pinnedDescriptor(deps.descriptors, record);
+                const image = descriptor.image[guestPlatform];
+                const transport = await ownTransport();
+                const label = 'Downloading the engine image';
+                onProgress({ label, completed: 0, total: descriptor.download_bytes, unit: 'bytes' });
+                // Inside the guest, through its own socket: the Engine API never leaves the distribution (D4).
+                await pullImageWithCurl(image, {
+                    run: (argv, call) => transport.exec(argv, { user: GUEST_ROOT, ...call }),
+                    signal,
+                    knownTotalBytes: descriptor.download_bytes,
+                    verify: guestDocker(transport),
+                    onProgress: (progress) => onProgress({ label, completed: progress.current, total: progress.total, unit: 'bytes' }),
+                });
+            });
+        },
+        async verify(record, signal) {
+            return held('verifying the installation', async () => {
+                const target = record.machine.operation.target;
+                if (target.kind === 'environment') {
+                    const seen = await look();
+                    const docker = seen.guest?.facts.docker;
+                    if (docker === undefined || !docker.daemon_reachable || !docker.gpu_runtime) {
+                        throw blocked('Docker in the Atomic Chat distribution does not answer with a GPU runtime.', 'docker-unreachable');
+                    }
+                    return;
+                }
+                const descriptor = await pinnedDescriptor(deps.descriptors, record);
+                const image = descriptor.image[guestPlatform];
+                const transport = await ownTransport();
+                if (!(await imagePresent(transport, image))) {
+                    throw new AtomicCoreError('MANAGED_IDENTITY_MISMATCH', 'The engine image in the Atomic Chat distribution does not carry the digest the descriptor pins.', `${image.repository}@${image.digest}`);
+                }
+                // Windows must reach what the guest publishes on its loopback (design D7): checked here, before
+                // the installation is called ready, and again at every load.
+                const facts = await probeWindowsHost(deps.host.probeDeps);
+                await checkLocalhostForwarding({
+                    transport,
+                    fetch: deps.fetch ?? fetch,
+                    sleep,
+                    wslconfig: facts.wslconfig,
+                    signal,
+                });
+            });
+        },
+        unloadResident: async () => undefined,
+        async activate(record) {
+            const target = record.machine.operation.target;
+            if (target.kind !== 'runtime')
+                return;
+            const descriptor = await pinnedDescriptor(deps.descriptors, record);
+            const probeImage = descriptor.probe_image[guestPlatform];
+            const previous = await deps.installations.read(target.installation_id);
+            const ownsProbe = record.owned_resource_ids.includes(ownedImageId(probeImage)) ||
+                previous?.probe_image?.digest === probeImage.digest;
+            const installation = {
+                schema_version: 1,
+                installation: {
+                    installation_id: target.installation_id,
+                    engine_id: target.engine_id,
+                    environment_id: record.machine.operation.environment_id,
+                    active_descriptor_id: descriptor.descriptor_id,
+                    candidate_descriptor_id: null,
+                    availability: 'supported',
+                    status: 'ready',
+                },
+                image: descriptor.image[guestPlatform],
+                ...(ownsProbe ? { probe_image: probeImage } : {}),
+                platform: guestPlatform,
+                installed_at: now().toISOString(),
+            };
+            await deps.installations.write(installation);
+        },
+        async remove(record) {
+            const target = record.machine.operation.target;
+            if (target.kind !== 'runtime') {
+                await removeEnvironment();
+                // The snapshot names the distribution until something probes again, and the app would offer
+                // to remove it a second time (live acceptance): say at once that it is gone.
+                const facts = await probeWindowsHost(deps.host.probeDeps).catch(() => null);
+                deps.onAssessment?.({
+                    availability: 'setup-required',
+                    gpus: facts?.gpus ?? [],
+                    blockers: [],
+                    selinux: null,
+                    distribution: null,
+                    memory_bytes: null,
+                });
+                return;
+            }
+            const existing = await deps.installations.read(target.installation_id);
+            // As on Linux: a loaded model first, its container confirmed stopped; loads held off till the end.
+            const hold = await unload(target.engine_id);
+            const lease = deps.keeper?.acquire('removing an engine');
+            try {
+                const environment = await deps.records.read();
+                if (environment !== null) {
+                    const docker = guestDocker(wsl.distribution(environment.distribution.name));
+                    for (const container of deps.journal
+                        .list()
+                        .filter((entry) => entry.engine_id === target.engine_id)) {
+                        const stopped = await stopContainer(docker, container.container_id, STOP_TIMEOUT_SECONDS);
+                        if (!stopped.confirmed) {
+                            throw new AtomicCoreError('MANAGED_STOP_UNCONFIRMED', 'A container of this engine could not be confirmed stopped, so nothing was removed.', `${container.container_id}: ${stopped.reason}`);
+                        }
+                        await removeContainer(docker, container.container_id);
+                        await deps.journal.remove(container.container_id);
+                    }
+                    if (existing !== null) {
+                        if (existing.installation.status !== 'removing') {
+                            await deps.installations.write({
+                                ...existing,
+                                installation: { ...existing.installation, status: 'removing' },
+                            });
+                        }
+                        if ((await containersUsingImage(docker, existing.image)).length === 0)
+                            await removeImage(docker, existing.image);
+                        const probe = existing.probe_image;
+                        if (probe !== undefined) {
+                            const others = (await deps.installations.list()).filter((entry) => entry.installation.installation_id !== target.installation_id &&
+                                entry.probe_image?.digest === probe.digest);
+                            if (others.length === 0 && (await containersUsingImage(docker, probe)).length === 0) {
+                                await removeImage(docker, probe);
+                            }
+                        }
+                    }
+                }
+                const descriptorId = existing?.installation.active_descriptor_id ?? null;
+                if (descriptorId !== null)
+                    await deps.removeEngineCaches(descriptorId);
+                if (record.request.retain_models === false &&
+                    (await otherEngines(deps.installations, target)).length === 0) {
+                    await deps.removeStoreModels();
+                }
+                await deps.installations.remove(target.installation_id);
+            }
+            finally {
+                lease?.release();
+                hold.release?.();
+            }
+        },
+        cleanup: async () => undefined,
+        inventory,
+    };
+}
+//# sourceMappingURL=windows-provisioner.js.map