@atomic-chat/core 0.5.1 → 0.13.2

package/dist/runtime/container/operations.js

@@ -0,0 +1,233 @@
+/**
+ * The docker operations the core needs to run a model container: pull-adjacent inspection, create,
+ * start, a confirmed stop, rm, a log tail, and a one-shot `run` probe. Each one builds its argv
+ * through `argv.ts` and runs it through an injected `DockerExec` (`exec.ts`'s `createDockerExec` in
+ * production, a fake in tests) — this file never spawns anything itself.
+ *
+ * `docker ... inspect` and `docker rm` both treat "the thing is already gone" as a normal outcome,
+ * not a failure: an inspect reports `found: false` and an `rm` of an already-removed container
+ * resolves. Every other non-zero exit becomes `AtomicCoreError('IO_ERROR', ...)` with docker's own
+ * stderr as the detail.
+ *
+ * `createContainer` is also where symlinks get resolved (review round 2, item 2): it is the one
+ * function in this module that does filesystem I/O of its own, `realpath`-ing every mount source and
+ * `selinuxDataRoot` before handing them to `argv.ts`'s pure (and therefore symlink-blind) checks.
+ */
+import { realpath as fsRealpath } from 'node:fs/promises';
+import { AtomicCoreError } from '../../contracts/index.js';
+import { buildCreateModelContainerArgv, buildInspectContainerArgv, buildInspectImageArgv, buildListContainersByImageArgv, buildLogsArgv, buildPortArgv, buildRemoveImageArgv, buildRmArgv, buildRunOnceArgv, buildStartArgv, buildStopArgv, } from './argv.js';
+const ABSENT_PATTERN = /no such (image|container)/i;
+function ioError(operation, result) {
+    throw new AtomicCoreError('IO_ERROR', `docker ${operation} failed.`, result.stderr || result.stdout);
+}
+async function inspect(exec, argv, operation) {
+    const result = await exec(argv);
+    if (result.code === 0) {
+        let parsed;
+        try {
+            parsed = JSON.parse(result.stdout || '[]');
+        }
+        catch (error) {
+            // A 0 exit with unparseable stdout is not "the thing is absent" — it is docker (or a fake in
+            // tests) answering in a shape this module does not understand; surface it as our own error
+            // rather than letting a raw SyntaxError escape (review round 1, item 12).
+            throw new AtomicCoreError('IO_ERROR', `docker ${operation} produced output that is not valid JSON.`, `${error.message}\n${result.stdout}`);
+        }
+        return { found: parsed.length > 0, value: parsed[0] ?? null };
+    }
+    if (ABSENT_PATTERN.test(result.stderr))
+        return { found: false, value: null };
+    ioError(operation, result);
+}
+/**
+ * The host port Docker published `containerPort` on, for a container created with a Docker-chosen
+ * port (`host_port: 0`). Only a `127.0.0.1` publication is accepted, whatever Docker answers.
+ */
+export async function publishedHostPort(exec, containerId, containerPort) {
+    const result = await exec(buildPortArgv(containerId, containerPort));
+    if (result.code !== 0)
+        ioError('port', result);
+    const line = result.stdout
+        .split('\n')
+        .map((entry) => entry.trim())
+        .find((entry) => entry !== '') ?? '';
+    const match = /^(.+):(\d+)$/.exec(line);
+    if (match === null) {
+        throw new AtomicCoreError('IO_ERROR', 'docker port did not name a published port.', line);
+    }
+    if (match[1] !== '127.0.0.1') {
+        throw new AtomicCoreError('FORBIDDEN_HOST', 'The container port was published on something other than 127.0.0.1.', line);
+    }
+    return Number(match[2]);
+}
+export function inspectImage(exec, image) {
+    return inspect(exec, buildInspectImageArgv(image), 'image inspect');
+}
+export function inspectContainer(exec, containerId) {
+    return inspect(exec, buildInspectContainerArgv(containerId), 'container inspect');
+}
+async function resolveOrThrow(realpath, path, what) {
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        throw new AtomicCoreError('IO_ERROR', `${what} could not be resolved to a real path.`, `${path}: ${error.message}`);
+    }
+}
+/**
+ * Resolves every mount source and `selinuxDataRoot` to their canonical, symlink-free real path
+ * before argv is built (review round 2, item 2, controller ruling). `argv.ts`'s
+ * `assertMountSource`/`assertWithinDataRoot` are pure lexical string checks — a mount source that is
+ * a symlink *inside* an allowed SELinux data root but that points *outside* it would pass those
+ * checks unresolved, while Docker's actual bind mount (and its `:z` relabel) act on the resolved
+ * target, not the symlink's own path. Running every source through `realpath` here, before it ever
+ * reaches the pure argv layer, means the checks there always see what Docker will actually mount.
+ */
+async function canonicalizeCreateSpec(spec, realpath) {
+    const [model, engineCache, entrypoint, heartbeat, selinuxDataRoot] = await Promise.all([
+        resolveOrThrow(realpath, spec.mounts.model.source, 'model mount source'),
+        resolveOrThrow(realpath, spec.mounts.engineCache.source, 'engine cache mount source'),
+        resolveOrThrow(realpath, spec.mounts.entrypoint.source, 'entrypoint mount source'),
+        resolveOrThrow(realpath, spec.mounts.heartbeat.source, 'heartbeat mount source'),
+        spec.selinuxDataRoot === undefined
+            ? Promise.resolve(undefined)
+            : resolveOrThrow(realpath, spec.selinuxDataRoot, 'selinuxDataRoot'),
+    ]);
+    return {
+        ...spec,
+        mounts: {
+            model: { source: model },
+            engineCache: { source: engineCache },
+            entrypoint: { source: entrypoint },
+            heartbeat: { source: heartbeat },
+        },
+        // `exactOptionalPropertyTypes`: only set the key at all when there is a value, rather than
+        // assigning `selinuxDataRoot: undefined` (a real, if empty, distinct state under that setting).
+        ...(selinuxDataRoot === undefined ? {} : { selinuxDataRoot }),
+    };
+}
+/** Creates (but does not start) the model container; returns the id docker printed to stdout. */
+export async function createContainer(exec, spec, deps = {}) {
+    const realpath = deps.realpath ?? fsRealpath;
+    const canonicalSpec = await canonicalizeCreateSpec(spec, realpath);
+    const result = await exec(buildCreateModelContainerArgv(canonicalSpec));
+    if (result.code !== 0)
+        ioError('create', result);
+    const containerId = result.stdout.trim().split('\n').pop()?.trim() ?? '';
+    if (containerId === '') {
+        throw new AtomicCoreError('IO_ERROR', 'docker create produced no container id.', result.stdout);
+    }
+    return { containerId };
+}
+export async function startContainer(exec, containerId) {
+    const result = await exec(buildStartArgv(containerId));
+    if (result.code !== 0)
+        ioError('start', result);
+}
+/**
+ * Extra time given to the *exec call itself* beyond `docker stop`'s own `--time <timeoutSeconds>`
+ * (review round 1, item 3). `exec.ts`'s default exec deadline is 30 s; without this, any
+ * `timeoutSeconds` beyond ~30 would have our own exec call killed and reported unconfirmed before
+ * Docker's own `--time` even elapsed, which is not "unconfirmed" — it is this module cutting the
+ * call short before Docker had a chance to answer.
+ */
+const STOP_EXEC_MARGIN_MS = 5_000;
+/**
+ * Stops the container and waits for Docker to confirm it exited (or was already absent) — never
+ * treats "our own exec call did not get an answer" as a stop (spec `tensorrt-llm-runtime`,
+ * requirement "unloading waits for a confirmed stop"). `confirmed: false` is what a caller maps to
+ * `MANAGED_STOP_UNCONFIRMED` and a held GPU reservation.
+ */
+export async function stopContainer(exec, containerId, timeoutSeconds) {
+    // Built outside the try: an INVALID_ARGUMENT from a bad timeout is a programming error this
+    // caller should see directly, not a report that the stop went unconfirmed (review round 1, item 9).
+    const argv = buildStopArgv(containerId, timeoutSeconds);
+    let result;
+    try {
+        result = await exec(argv, { timeoutMs: timeoutSeconds * 1000 + STOP_EXEC_MARGIN_MS });
+    }
+    catch (error) {
+        return { confirmed: false, reason: error.message };
+    }
+    if (result.code === 0)
+        return { confirmed: true, status: 'exited' };
+    if (ABSENT_PATTERN.test(result.stderr))
+        return { confirmed: true, status: 'absent' };
+    return {
+        confirmed: false,
+        reason: result.stderr || result.stdout || `docker stop exited with code ${String(result.code)}`,
+    };
+}
+/** Idempotent: a container already removed (or never created) is success, not an error. */
+export async function removeContainer(exec, containerId) {
+    const result = await exec(buildRmArgv(containerId));
+    if (result.code === 0)
+        return;
+    if (ABSENT_PATTERN.test(result.stderr))
+        return;
+    ioError('rm', result);
+}
+/** Ids of every container, running or stopped, created from `image`. Fails when docker cannot answer. */
+export async function containersUsingImage(exec, image) {
+    const result = await exec(buildListContainersByImageArgv(image));
+    if (result.code !== 0)
+        ioError('ps', result);
+    return result.stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== '');
+}
+/** Removes the digest reference; an image already gone is `absent`, anything else docker refuses throws. */
+export async function removeImage(exec, image) {
+    const result = await exec(buildRemoveImageArgv(image));
+    if (result.code === 0)
+        return 'removed';
+    if (ABSENT_PATTERN.test(result.stderr))
+        return 'absent';
+    ioError('image rm', result);
+}
+/**
+ * Docker writes a container's stdout and stderr to two separate file descriptors; `buildLogsArgv`
+ * asks for `--timestamps` on both so they can be merged back into one chronologically ordered log
+ * (review round 1, item 2 — the lifecycle needs a combined tail to classify an OOM exit, which
+ * `trtllm-serve` can report on either stream). Each line is expected to start with Docker's
+ * RFC3339Nano timestamp followed by a space; timestamps in that spelling sort correctly as plain
+ * strings, so this is a stable two-way merge, not a `Date` parse. A line with no recognizable
+ * timestamp (should not happen with `--timestamps`, but this must not crash on one) sorts using its
+ * own text, which only affects placement relative to other such lines.
+ */
+function timestampOf(line) {
+    const spaceIndex = line.indexOf(' ');
+    return spaceIndex === -1 ? line : line.slice(0, spaceIndex);
+}
+function mergeTimestampedLogs(stdout, stderr) {
+    const stdoutLines = stdout.split('\n').filter((line) => line !== '');
+    const stderrLines = stderr.split('\n').filter((line) => line !== '');
+    const merged = [];
+    let i = 0;
+    let j = 0;
+    while (i < stdoutLines.length && j < stderrLines.length) {
+        if (timestampOf(stdoutLines[i]) <= timestampOf(stderrLines[j]))
+            merged.push(stdoutLines[i++]);
+        else
+            merged.push(stderrLines[j++]);
+    }
+    while (i < stdoutLines.length)
+        merged.push(stdoutLines[i++]);
+    while (j < stderrLines.length)
+        merged.push(stderrLines[j++]);
+    return merged.length === 0 ? '' : merged.join('\n') + '\n';
+}
+/** The last `tailLines` lines (or, with `'all'`, every line) of the container's combined,
+ *  chronologically merged stdout+stderr log. The exec's own per-stream output cap still bounds it. */
+export async function containerLogs(exec, containerId, tailLines) {
+    const result = await exec(buildLogsArgv(containerId, tailLines));
+    if (result.code !== 0)
+        ioError('logs', result);
+    return mergeTimestampedLogs(result.stdout, result.stderr);
+}
+/** A one-shot `docker run --rm` probe (task 2.x's GPU check): the raw result, never thrown — the caller classifies it. */
+export function runOnce(exec, spec) {
+    return exec(buildRunOnceArgv(spec));
+}
+//# sourceMappingURL=operations.js.map

package/dist/runtime/container/operations.js.map

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

package/dist/runtime/container/pull.d.ts

@@ -0,0 +1,48 @@
+import type { DockerExec, ImageRef, PullProgressCallback } from './types.js';
+export interface PullImageOptions {
+    /** Default derived from `argv.ts`'s `DOCKER_SOCKET_PATH` (review round 1, item 15 — one socket path constant); tests point this at a fake Engine API. */
+    socketPath?: string;
+    onProgress?: PullProgressCallback;
+    signal?: AbortSignal;
+    /**
+     * A known total byte size (e.g. the descriptor's `download_bytes`) used instead of the stream's
+     * own running total whenever it is larger. The stream's total only sums layers that have already
+     * reported at least one `Downloading` line, so early in a pull it always undercounts (review round
+     * 1, item 4).
+     */
+    knownTotalBytes?: number;
+    /**
+     * After a successful pull, confirm `image` is actually present locally via `operations.ts`'s
+     * `inspectImage` (review round 1, item 10). Optional: a caller that only has the Engine API socket
+     * and no `DockerExec` yet (as every test in this file does) can omit it and skip verification.
+     */
+    verify?: DockerExec;
+}
+/**
+ * Pulls `image.repository@image.digest`. Resolves once the daemon's response stream ends without an
+ * `error` line (and, if `options.verify` is given, once `inspectImage` confirms the image is present
+ * locally); rejects with `AtomicCoreError('IO_ERROR', ...)` for a non-200 response, an `error` line,
+ * a stream failure, an unreachable socket, or a failed post-pull verification.
+ */
+export declare function pullImage(image: ImageRef, options?: PullImageOptions): Promise<void>;
+/** Runs one argv somewhere the Engine API socket is (a WSL guest), streaming its stdout as it comes. */
+export type EngineApiCommand = (argv: string[], call: {
+    onStdout: (text: string) => void;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}) => Promise<{
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}>;
+export interface PullImageWithCurlOptions extends Omit<PullImageOptions, 'socketPath'> {
+    run: EngineApiCommand;
+    /** How long the whole pull may take; generous by default, an engine image is tens of gigabytes. */
+    timeoutMs?: number;
+}
+/**
+ * `pullImage` from inside a WSL guest: `curl --unix-socket /var/run/docker.sock -X POST
+ * http://localhost/images/create?…` streams the same NDJSON, which the same tracker reads. `--fail-with-body`
+ * turns a non-200 answer into a nonzero exit with the daemon's message on stdout.
+ */
+export declare function pullImageWithCurl(image: ImageRef, options: PullImageWithCurlOptions): Promise<void>;

package/dist/runtime/container/pull.js

@@ -0,0 +1,280 @@
+/**
+ * Pulling the model image by digest, over the Docker Engine API rather than `docker pull` (task 2.8
+ * controller ruling). The `docker` CLI prints no byte progress at all unless attached to a TTY —
+ * `distribution/pull.go`'s progress writer special-cases an interactive terminal, and this core
+ * never runs one — but spec `tensorrt-llm-runtime` needs byte progress for an image tens of
+ * gigabytes large. `POST /images/create?fromImage=<repo>&tag=<digest>` streams one JSON object per
+ * line, one per layer per progress tick; this aggregates every layer's `progressDetail.current`/
+ * `.total` into a single running total and reports it after each update. See
+ * `docs/decisions/2026-09-28-pull-the-model-image-over-the-docker-engine-api.md`.
+ *
+ * On Windows the Engine API is inside Atomic Chat's WSL distribution, and its socket never leaves it
+ * (change `add-tensorrt-llm-windows`, design D4): `pullImageWithCurl` asks the same endpoint from
+ * inside the guest — `curl --unix-socket` as one argv through the WSL transport, its stdout streamed
+ * back — and reads the stream with the same tracker, so progress and failures mean the same thing.
+ *
+ * This talks to the Engine API directly over its unix socket (`node:http`'s `socketPath`, injectable
+ * for tests) rather than through `exec.ts`'s `DockerExec` — there is no docker CLI subcommand that
+ * streams byte counts, so there is no argv to build for this one operation. The default socket path
+ * is `argv.ts`'s `DOCKER_SOCKET_PATH`, not a separate literal (review round 1, item 15).
+ */
+import http from 'node:http';
+import { AtomicCoreError } from '../../contracts/index.js';
+import { DOCKER_SOCKET_PATH, assertDigest, assertSafeArgvValue } from './argv.js';
+import { inspectImage } from './operations.js';
+function ioError(message, details) {
+    return new AtomicCoreError('IO_ERROR', message, details);
+}
+/**
+ * Pulls `image.repository@image.digest`. Resolves once the daemon's response stream ends without an
+ * `error` line (and, if `options.verify` is given, once `inspectImage` confirms the image is present
+ * locally); rejects with `AtomicCoreError('IO_ERROR', ...)` for a non-200 response, an `error` line,
+ * a stream failure, an unreachable socket, or a failed post-pull verification.
+ */
+export async function pullImage(image, options = {}) {
+    // An `async` function: a validation failure below becomes a rejected promise, never a synchronous
+    // throw, so every caller can treat `pullImage` uniformly as `.catch`/`await`-able I/O.
+    const repository = assertSafeArgvValue(image.repository, 'image repository');
+    const digest = assertDigest(image.digest, 'image digest');
+    const socketPath = options.socketPath ?? DOCKER_SOCKET_PATH;
+    const path = `/images/create?fromImage=${encodeURIComponent(repository)}&tag=${encodeURIComponent(digest)}`;
+    await streamPull(path, socketPath, options);
+    if (options.verify) {
+        const { found } = await inspectImage(options.verify, image);
+        if (!found) {
+            throw ioError('Docker image pull completed but the image is not present locally.', `${repository}@${digest}`);
+        }
+    }
+}
+/**
+ * Aggregates byte progress across layers. Only a `status: 'Downloading'` line counts: the same layer
+ * `id` is reused for `Extracting` (and other phases) with its *own*, unrelated `progressDetail`, so
+ * folding every phase into one sum makes the total regress as a layer moves from "fully downloaded"
+ * to "partway extracted" (review round 1, item 4 — the non-monotonic bug). Each layer's contribution
+ * is the running *max* ever reported for it (defensive: a real `Downloading` sequence is already
+ * monotonic, but this does not trust that), clamped to that layer's own total.
+ */
+class PullProgressTracker {
+    knownTotalBytes;
+    layers = new Map();
+    constructor(knownTotalBytes) {
+        this.knownTotalBytes = knownTotalBytes;
+    }
+    /** Returns the new aggregate to report, or `undefined` if this line contributes nothing. */
+    observe(parsed) {
+        if (parsed.status !== 'Downloading')
+            return undefined;
+        if (!parsed.id || !parsed.progressDetail || typeof parsed.progressDetail.current !== 'number')
+            return undefined;
+        const rawCurrent = parsed.progressDetail.current;
+        const reportedTotal = parsed.progressDetail.total ?? 0;
+        // A layer's own total must never be smaller than its own current: when Docker reports no size (or
+        // a 0 size) for this layer, treat its total as "however much has been downloaded so far" instead
+        // of letting an unclamped current outrun a phantom total (review round 2, item 1 — the earlier
+        // `total > 0 ? clamp : don't` left current > total whenever a line had no/zero total).
+        const total = Math.max(reportedTotal, rawCurrent);
+        const current = Math.min(rawCurrent, total);
+        const existing = this.layers.get(parsed.id);
+        this.layers.set(parsed.id, {
+            current: existing ? Math.max(existing.current, current) : current,
+            total: existing ? Math.max(existing.total, total) : total,
+        });
+        return this.aggregate();
+    }
+    aggregate() {
+        let current = 0;
+        let streamTotal = 0;
+        for (const layer of this.layers.values()) {
+            current += layer.current;
+            streamTotal += layer.total;
+        }
+        const total = this.knownTotalBytes !== undefined ? Math.max(streamTotal, this.knownTotalBytes) : streamTotal;
+        // Unconditional (review round 2, item 1): with the per-layer invariant above, `current` can never
+        // actually exceed `total` here, but this clamp is the property itself, stated directly, rather
+        // than something that merely follows from the per-layer bookkeeping being correct.
+        return { current: Math.min(current, total), total };
+    }
+}
+const CURL_PULL_TIMEOUT_MS = 12 * 60 * 60_000;
+/**
+ * `pullImage` from inside a WSL guest: `curl --unix-socket /var/run/docker.sock -X POST
+ * http://localhost/images/create?…` streams the same NDJSON, which the same tracker reads. `--fail-with-body`
+ * turns a non-200 answer into a nonzero exit with the daemon's message on stdout.
+ */
+export async function pullImageWithCurl(image, options) {
+    const repository = assertSafeArgvValue(image.repository, 'image repository');
+    const digest = assertDigest(image.digest, 'image digest');
+    const cancelled = () => options.signal?.aborted === true;
+    if (cancelled())
+        throw new AtomicCoreError('MODEL_LOAD_CANCELLED', 'Image pull was cancelled.');
+    const path = `/images/create?fromImage=${encodeURIComponent(repository)}&tag=${encodeURIComponent(digest)}`;
+    const tracker = new PullProgressTracker(options.knownTotalBytes);
+    let buffer = '';
+    let failure = null;
+    const handleLine = (line) => {
+        if (failure !== null || line.trim() === '')
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return; // a partial/non-JSON line; one bad line should not fail the whole pull
+        }
+        if (parsed.error) {
+            failure = ioError('Docker image pull failed.', parsed.errorDetail?.message ?? parsed.error);
+            return;
+        }
+        const progress = tracker.observe(parsed);
+        if (progress && options.onProgress) {
+            try {
+                options.onProgress(progress);
+            }
+            catch {
+                // A misbehaving progress callback must not abort the pull (review round 1, item 11).
+            }
+        }
+    };
+    const answer = await options.run([
+        'curl',
+        '--silent',
+        '--show-error',
+        '--no-buffer',
+        '--fail-with-body',
+        '--unix-socket',
+        DOCKER_SOCKET_PATH,
+        '-X',
+        'POST',
+        `http://localhost${path}`,
+    ], {
+        onStdout: (text) => {
+            buffer += text;
+            let newline;
+            while ((newline = buffer.indexOf('\n')) >= 0) {
+                handleLine(buffer.slice(0, newline));
+                buffer = buffer.slice(newline + 1);
+            }
+        },
+        timeoutMs: options.timeoutMs ?? CURL_PULL_TIMEOUT_MS,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    if (buffer.trim() !== '')
+        handleLine(buffer);
+    if (cancelled())
+        throw new AtomicCoreError('MODEL_LOAD_CANCELLED', 'Image pull was cancelled.');
+    if (failure !== null)
+        throw failure;
+    if (answer.code !== 0) {
+        throw ioError(answer.code === null
+            ? 'Could not reach the Docker daemon.'
+            : `Docker image pull failed (curl exited ${answer.code}).`, `${answer.stderr.trim()}\n${answer.stdout.trim().slice(-2000)}`.trim());
+    }
+    if (options.verify) {
+        const { found } = await inspectImage(options.verify, image);
+        if (!found) {
+            throw ioError('Docker image pull completed but the image is not present locally.', `${repository}@${digest}`);
+        }
+    }
+}
+function streamPull(path, socketPath, options) {
+    return new Promise((resolve, reject) => {
+        const tracker = new PullProgressTracker(options.knownTotalBytes);
+        let buffer = '';
+        let settled = false;
+        const finish = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            if (options.signal)
+                options.signal.removeEventListener('abort', onAbort);
+            if (outcome.ok)
+                resolve();
+            else
+                reject(outcome.error);
+        };
+        const reportProgress = (progress) => {
+            if (!options.onProgress)
+                return;
+            try {
+                options.onProgress(progress);
+            }
+            catch {
+                // A caller's progress callback misbehaving must not abort a multi-gigabyte pull that is
+                // otherwise proceeding fine (review round 1, item 11).
+            }
+        };
+        const handleLine = (line, req) => {
+            if (line.trim() === '')
+                return;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                return; // a partial/non-JSON line; one bad line should not fail the whole pull
+            }
+            if (parsed.error) {
+                finish({
+                    ok: false,
+                    error: ioError('Docker image pull failed.', parsed.errorDetail?.message ?? parsed.error),
+                });
+                req.destroy();
+                return;
+            }
+            const progress = tracker.observe(parsed);
+            if (progress)
+                reportProgress(progress);
+        };
+        const req = http.request({ socketPath, path, method: 'POST' }, (res) => {
+            if (res.statusCode !== 200) {
+                let body = '';
+                res.setEncoding('utf8');
+                res.on('data', (chunk) => {
+                    body += chunk;
+                });
+                res.on('end', () => {
+                    finish({
+                        ok: false,
+                        error: ioError(`Docker image pull failed with status ${res.statusCode}.`, body),
+                    });
+                });
+                return;
+            }
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => {
+                buffer += chunk;
+                let newlineIndex;
+                while ((newlineIndex = buffer.indexOf('\n')) >= 0) {
+                    const line = buffer.slice(0, newlineIndex);
+                    buffer = buffer.slice(newlineIndex + 1);
+                    handleLine(line, req);
+                    if (settled)
+                        return;
+                }
+            });
+            res.on('end', () => {
+                // The stream can end with a final line that never got a trailing `\n` (review round 1, item
+                // 10): flush whatever is left in `buffer` before declaring the pull done.
+                if (!settled && buffer.trim() !== '')
+                    handleLine(buffer, req);
+                buffer = '';
+                finish({ ok: true });
+            });
+            res.on('error', (error) => finish({ ok: false, error: ioError('Docker image pull stream failed.', error.message) }));
+        });
+        req.on('error', (error) => finish({ ok: false, error: ioError('Could not reach the Docker daemon.', error.message) }));
+        const onAbort = () => {
+            req.destroy();
+            finish({ ok: false, error: new AtomicCoreError('MODEL_LOAD_CANCELLED', 'Image pull was cancelled.') });
+        };
+        if (options.signal) {
+            if (options.signal.aborted) {
+                onAbort();
+                return;
+            }
+            options.signal.addEventListener('abort', onAbort, { once: true });
+        }
+        req.end();
+    });
+}
+//# sourceMappingURL=pull.js.map

package/dist/runtime/container/pull.js.map

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

package/dist/runtime/container/reconcile.d.ts

@@ -0,0 +1,34 @@
+import type { ExecutionJournal, ExecutionRecord } from './execution-journal.js';
+import type { DockerExec } from './types.js';
+/** Structurally compatible with `core/types.ts`'s `CoreLogger`; kept local so this module never imports `core/`. */
+export type ReconcileLogger = (level: 'info' | 'warn' | 'error', message: string) => void;
+/** `docker stop --time` for a reconciled orphan: generous, since nothing is waiting on this container. */
+export declare const RECONCILE_STOP_TIMEOUT_SECONDS = 10;
+export interface ExecutionReconcileResult {
+    /** Found (running or already exited) and successfully stopped, removed, and dropped from the journal. */
+    stopped: ExecutionRecord[];
+    /** Already gone by the time reconcile looked: the record was dropped, nothing to stop or remove. */
+    absent: ExecutionRecord[];
+    /** The stop could not be confirmed: the record — and the container — are left alone, and reported. */
+    unconfirmed: ExecutionRecord[];
+    /**
+     * `inspectContainer`, `stopContainer` or `removeContainer` threw for this record (an `IO_ERROR` the
+     * executor could not classify as "absent" or "unconfirmed"): the record — and the container — are
+     * left alone, exactly like `unconfirmed`, so one bad record can never stop reconcile from reaching
+     * the rest of the journal.
+     */
+    failed: ExecutionRecord[];
+    /**
+     * Never looked at because `signal` aborted first (core startup's time budget ran out, task 2.12
+     * review round 1): the record — and the container — are left for the next startup.
+     */
+    skipped: ExecutionRecord[];
+}
+/**
+ * Reconciles every record in `journal` that does not belong to `currentInstanceId` against the host
+ * through `exec`. Safe to call with an empty journal (a no-op) or before the journal's directory
+ * exists (`ExecutionJournal.open` already handles that).
+ */
+export declare function reconcileExecutions(journal: ExecutionJournal, currentInstanceId: string, exec: DockerExec, log: ReconcileLogger, stopTimeoutSeconds?: number, 
+/** Checked before each record: once aborted, the rest are reported as `skipped` and left alone. */
+signal?: AbortSignal): Promise<ExecutionReconcileResult>;