spawnfile 0.1.14 → 0.1.18

package/dist/compiler/training/preparation/files.js

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { copyFile, lstat, mkdir, readdir, readlink, realpath, chmod, symlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+export const within = (root, file) => file === root || file.startsWith(root + path.sep);
+export const hashJson = (value) => `sha256:${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+const ignored = new Set(["node_modules", ".venv", ".git", "__pycache__", "coverage", "coverage.json", ".coverage", ".pytest_cache", ".runtime", "AGENTS.md", "CLAUDE.md"]);
+export function assertInputRoot(source, auth) {
+    const home = os.homedir();
+    if (["/", "/etc", "/var", "/run", "/tmp", "/opt", "/usr", "/Users", "/home", home].includes(source) ||
+        [".codex", ".claude", ".grok", ".ssh", ".config"].some(name => within(path.join(home, name), source)) ||
+        auth.some(leaf => within(source, leaf) || within(leaf, source)))
+        throw Error("Training input exposes a protected host root or auth leaf");
+}
+export async function exactPath(source) {
+    const absolute = path.resolve(source);
+    if (await realpath(absolute) !== absolute || (await lstat(absolute)).isSymbolicLink())
+        throw Error("Training source must be canonical, without symlink aliases");
+    return absolute;
+}
+export async function sealFile(source, destination) {
+    await exactPath(source);
+    const before = await lstat(source, { bigint: true });
+    if (!before.isFile() || before.size > 536870912n)
+        throw Error("Training source must be a regular file no larger than 512 MiB");
+    const digest = createHash("sha256");
+    let size = 0;
+    for await (const chunk of createReadStream(source)) {
+        size += chunk.length;
+        if (size > 536_870_912)
+            throw Error("Training source exceeded its size limit");
+        digest.update(chunk);
+    }
+    const after = await lstat(source, { bigint: true });
+    if (BigInt(size) !== before.size || after.size !== before.size || after.ino !== before.ino || after.ctimeNs !== before.ctimeNs || after.dev !== before.dev)
+        throw Error("Training source changed while hashing");
+    return { source, destination, sha256: `sha256:${digest.digest("hex")}`, mode: Number(before.mode & 511n), size };
+}
+function assertLink(root, file, target) {
+    // Absolute host paths cannot reproduce a confined link in a relocated snapshot.
+    if (!target || path.isAbsolute(target) || !within(root, path.resolve(path.dirname(file), target))) {
+        throw Error("Training source trees must not contain escaping symlinks");
+    }
+}
+async function sealLink(source, destination) {
+    const before = await lstat(source, { bigint: true }), target = await readlink(source);
+    const after = await lstat(source, { bigint: true });
+    if (!before.isSymbolicLink() || !after.isSymbolicLink() || after.ino !== before.ino ||
+        after.ctimeNs !== before.ctimeNs || after.dev !== before.dev)
+        throw Error("Training source changed while hashing");
+    return { source, destination, target, sha256: hashJson({ type: "symlink", target }), mode: 0o777, size: Buffer.byteLength(target) };
+}
+/** Only physical entries are walked; confined input links retain their own identity. */
+export async function sealTree(source, destination, options = {}) {
+    await exactPath(source);
+    const files = [];
+    let entries = 0;
+    const walk = async (root, target, depth) => {
+        if (depth > 32)
+            throw Error("Training source tree exceeds bounds");
+        const stat = await lstat(root);
+        if ((depth > 0 || !stat.isDirectory()) && ++entries > 10000)
+            throw Error("Training source tree exceeds bounds");
+        if (stat.isSymbolicLink()) {
+            if (!options.internalSymlinks)
+                throw Error("Training source trees must not contain escaping symlinks");
+            const link = await sealLink(root, target);
+            assertLink(source, root, link.target);
+            // Resolve only for containment validation, never to enumerate or copy the target.
+            if (!within(source, await realpath(root)))
+                throw Error("Training source trees must not contain escaping symlinks");
+            files.push(link);
+            return;
+        }
+        if (stat.isDirectory()) {
+            const children = (await readdir(root)).sort().filter(entry => !(options.ignoreGit && entry === ".git") &&
+                !(options.ignoreDevelopment && (ignored.has(entry) || /(?:\.test\.[cm]?[jt]s|_test\.py|\.pyc)$/u.test(entry))));
+            // Retain empty input directories so their preserved links still resolve after relocation.
+            if (options.internalSymlinks && !children.length && target)
+                files.push({ source: root, destination: target,
+                    directory: true, sha256: hashJson({ type: "directory" }), mode: stat.mode & 0o777, size: 0 });
+            for (const entry of children) {
+                await walk(path.join(root, entry), path.posix.join(target, entry), depth + 1);
+            }
+        }
+        else
+            files.push(await sealFile(root, target));
+    };
+    await walk(source, destination, 0);
+    if (files.length > 10000 || files.reduce((sum, file) => sum + file.size, 0) > 1_073_741_824)
+        throw Error("Training source tree exceeds bounds");
+    return files;
+}
+export async function copySealed(files, root) {
+    const directories = new Set();
+    const ensureDirectory = async (directory) => {
+        if (directories.has(directory))
+            return;
+        const parent = path.dirname(directory);
+        if (parent !== directory) {
+            await ensureDirectory(parent);
+            await mkdir(directory, { mode: 0o700 }).catch((error) => { if (error.code !== "EEXIST")
+                throw error; });
+        }
+        await exactPath(directory);
+        if (!(await lstat(directory)).isDirectory())
+            throw Error("Training staging parent must be a directory");
+        directories.add(directory);
+    };
+    await ensureDirectory(root);
+    for (const file of files) {
+        const target = path.resolve(root, file.destination);
+        if (!within(root, target) || target === root)
+            throw Error("Training destination escapes owned staging");
+        await ensureDirectory(path.dirname(target));
+        if (file.directory) {
+            await ensureDirectory(target);
+            await chmod(target, file.mode);
+            continue;
+        }
+        if (file.target !== undefined) {
+            assertLink(root, target, file.target);
+            const current = await sealLink(file.source, file.destination);
+            if (hashJson(fileIdentity([current])) !== hashJson(fileIdentity([file])))
+                throw Error("Training source changed during staging");
+            await symlink(file.target, target);
+            if (await readlink(target) !== file.target)
+                throw Error("Training source changed during staging");
+            continue;
+        }
+        await exactPath(file.source);
+        await copyFile(file.source, target, 1);
+        await chmod(target, file.mode);
+        const copied = await sealFile(target, file.destination);
+        if (copied.sha256 !== file.sha256 || copied.size !== file.size)
+            throw Error("Training source changed during staging");
+    }
+    // Validate chains after every target has been staged, including links ordered before files.
+    for (const file of files.filter(file => file.target !== undefined)) {
+        if (!within(root, await realpath(path.join(root, file.destination))))
+            throw Error("Training staged symlink escapes owned staging");
+    }
+}
+export const fileIdentity = (files) => files.map(({ destination, sha256, mode, size, target, directory }) => ({ destination, sha256, mode, size, ...(target !== undefined ? { type: "symlink", target } : {}),
+    ...(directory ? { type: "directory" } : {}) }));

package/dist/compiler/training/preparation/image.d.ts

@@ -0,0 +1,28 @@
+import type { TrainingDockerProcess } from "../container/process.js";
+import type { TrainingImageBuild } from "./contract.js";
+import { type SealedFile } from "./files.js";
+export declare const trainingAssets: string;
+export interface TrainingImagePlan {
+    digest: string;
+    files: SealedFile[];
+    dockerfile: string;
+    entry: string;
+    brokerEntry: string;
+    build: TrainingImageBuild;
+}
+export declare function planTrainingImage(build: TrainingImageBuild, root: string, auth: readonly string[], ownRoot?: string, declarationPath?: string): Promise<TrainingImagePlan>;
+/** Cache is content-addressed and still requires a matching immutable image and label. */
+export declare function buildTrainingImage(plan: TrainingImagePlan, options: {
+    parent: string;
+    dockerContext: string;
+    process: TrainingDockerProcess;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    streams: {
+        stdout(line: string): void;
+        stderr(line: string): void;
+    };
+}): Promise<{
+    imageId: string;
+    cached: boolean;
+}>;

package/dist/compiler/training/preparation/image.js

@@ -0,0 +1,107 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { TRAINING_EXECUTION_CAPABILITY_LABEL } from "../contract.js";
+import { assertInputRoot, copySealed, fileIdentity, hashJson, sealFile, sealTree } from "./files.js";
+import { bindDaimonParentVerification, resolveTrainingDaimonParent } from "./daimonParent.js";
+import { normalizeTrainingContext } from "./contextModes.js";
+const packageRoot = fileURLToPath(new URL("../../../../", import.meta.url));
+export const trainingAssets = path.extname(fileURLToPath(import.meta.url)) === ".ts"
+    ? path.join(packageRoot, "runtime-images/training") : fileURLToPath(new URL("./assets/", import.meta.url));
+async function packageFiles(root, target, withDist, lockSource = path.join(root, "package-lock.json")) {
+    const manifest = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+    const lock = JSON.parse(await readFile(lockSource, "utf8"));
+    if (![2, 3].includes(lock.lockfileVersion) || !lock.packages?.[""] ||
+        JSON.stringify(manifest.dependencies ?? {}) !== JSON.stringify(lock.packages[""].dependencies ?? {}))
+        throw Error(`Training package manifest/lock mismatch: ${target}`);
+    if (Object.values(lock.packages).some(entry => {
+        const item = entry;
+        return item.link || item.resolved?.startsWith("file:") || item.resolved?.startsWith("../");
+    }))
+        throw Error(`Training package ${target} has unsupported local dependencies; provide a complete registry-locked distribution`);
+    return [await sealFile(path.join(root, "package.json"), `${target}/package.json`),
+        await sealFile(lockSource, `${target}/package-lock.json`),
+        ...withDist ? await sealTree(path.join(root, "dist"), `${target}/dist`, { ignoreDevelopment: true }) : []];
+}
+export async function planTrainingImage(build, root, auth, ownRoot = packageRoot, declarationPath = root) {
+    const resolve = (value) => path.resolve(root, value);
+    // Before any Docker call, including --dry-run: the attested Daimon runtime identity
+    // and the declared native parent must name one rebuild (see daimonParent.ts).
+    const daimonParent = await resolveTrainingDaimonParent(build, declarationPath);
+    assertInputRoot(ownRoot, auth);
+    for (const source of [build.paideia, build.bridge, build.claude, build.integration.source, ...build.compiler ? [build.compiler] : [], ...build.bootstrap ? [build.bootstrap] : []])
+        assertInputRoot(resolve(source), auth);
+    const assets = ownRoot === packageRoot ? trainingAssets : path.join(ownRoot, "runtime-images/training");
+    assertInputRoot(assets, auth);
+    const recipe = await readFile(path.join(assets, "Dockerfile"), "utf8");
+    // Always override the parent's label: compatibility belongs to this installed integration.
+    const capability = build.integration.execution ?? "";
+    const dockerfile = `${daimonParent ? bindDaimonParentVerification(recipe, daimonParent) : recipe}\nLABEL ${TRAINING_EXECUTION_CAPABILITY_LABEL}=${JSON.stringify(capability)}\n`;
+    const ownLock = path.extname(fileURLToPath(import.meta.url)) === ".ts" || ownRoot !== packageRoot
+        ? path.join(ownRoot, "package-lock.json") : path.join(assets, "package-lock.json");
+    const files = [
+        ...await packageFiles(resolve(build.paideia), "paideia", true),
+        ...await packageFiles(ownRoot, "spawnfile", true, ownLock),
+        ...await packageFiles(build.compiler ? resolve(build.compiler) : ownRoot, "compiler", true, build.compiler ? path.join(resolve(build.compiler), "package-lock.json") : ownLock),
+        ...await packageFiles(resolve(build.claude), "claude", false),
+        ...await sealTree(resolve(build.bridge), "bridge", { ignoreDevelopment: true }),
+        ...await sealTree(resolve(build.integration.source), "integration", { ignoreDevelopment: true }),
+        ...build.bootstrap ? await sealTree(resolve(build.bootstrap), "bootstrap", { ignoreDevelopment: true }) : [],
+        await sealFile(path.join(ownRoot, "runtimes.yaml"), "spawnfile/runtimes.yaml"),
+        await sealFile(path.join(ownRoot, "moltnet-releases.json"), "spawnfile/moltnet-releases.json"),
+        ...await Promise.all(["runtimes.yaml", "moltnet-releases.json"].map(name => sealFile(path.join(build.compiler ? resolve(build.compiler) : ownRoot, name), `compiler/${name}`)))
+    ];
+    for (const required of [`integration/${build.integration.entry}`, "bridge/pyproject.toml", "bridge/requirements.lock", "bridge/paideia_dspy/__init__.py", "paideia/dist/src/cli/main.js", "spawnfile/dist/cli/index.js", "compiler/dist/cli/index.js"]) {
+        if (!files.some(file => file.destination === required))
+            throw Error(`Training distribution is missing ${required}`);
+    }
+    const entry = `#!/bin/sh\nexec /usr/local/bin/node --experimental-strip-types ${JSON.stringify(`/opt/training/integration/${build.integration.entry}`)} "$@"\n`;
+    // The broker-capable entrypoint is the image's own Spawnfile distribution, never a host-written script.
+    const brokerEntry = `#!/bin/sh\nexec /usr/local/bin/node /opt/training/spawnfile/dist/compiler/training/broker/main.js "$@"\n`;
+    const digest = hashJson({ recipe: build.recipe, nativeImage: build.nativeImage, pythonImage: build.pythonImage, platform: build.platform,
+        files: fileIdentity(files), dockerfile, entry, brokerEntry });
+    return { digest, files, dockerfile, entry, brokerEntry, build };
+}
+/** Cache is content-addressed and still requires a matching immutable image and label. */
+export async function buildTrainingImage(plan, options) {
+    const tag = `spawnfile-training:${plan.digest.slice(7)}`;
+    const call = (args, stream = false) => options.process(["--context", options.dockerContext, ...args], {
+        timeoutMs: options.timeoutMs, signal: options.signal, ...stream ? options.streams : {}
+    });
+    const inspect = async () => {
+        const result = await call(["image", "inspect", tag, "--format", `{{json .Id}}\n{{json (index .Config.Labels "com.spawnfile.training.recipe")}}\n{{json (index .Config.Labels "${TRAINING_EXECUTION_CAPABILITY_LABEL}")}}`]);
+        if (result.code !== 0)
+            return undefined;
+        try {
+            const [id, digest, capability] = result.stdout.trim().split("\n").map(line => JSON.parse(line));
+            return /^sha256:[a-f0-9]{64}$/u.test(id) && digest === plan.digest && capability === (plan.build.integration.execution ?? "") ? id : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const cached = await inspect();
+    if (cached)
+        return { imageId: cached, cached: true };
+    const staging = await mkdtemp(path.join(options.parent, ".spawnfile-training-image-"));
+    try {
+        await copySealed(plan.files, staging);
+        await mkdir(path.join(staging, "bootstrap"), { recursive: true, mode: 0o700 });
+        await writeFile(path.join(staging, "Dockerfile"), `${plan.dockerfile}\nLABEL com.spawnfile.training.recipe=${JSON.stringify(plan.digest)}\n`, { mode: 0o600 });
+        await writeFile(path.join(staging, "train"), plan.entry, { mode: 0o755 });
+        await writeFile(path.join(staging, "train-broker"), plan.brokerEntry, { mode: 0o755 });
+        // Last, after every staged file exists: it fixes the modes and mtimes COPY will reproduce in the image.
+        await normalizeTrainingContext(staging);
+        const result = await call(["build", "--platform", plan.build.platform, "--build-arg", `NATIVE_IMAGE=${plan.build.nativeImage}`,
+            "--build-arg", `PYTHON_IMAGE=${plan.build.pythonImage}`, "--tag", tag, staging], true);
+        if (result.code !== 0)
+            throw Error("Training image build failed; inspect the streamed build diagnostic");
+        const imageId = await inspect();
+        if (!imageId)
+            throw Error("Training image build did not produce a verified immutable image");
+        return { imageId, cached: false };
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}

package/dist/compiler/training/preparation/index.d.ts

@@ -0,0 +1,3 @@
+export { prepareTraining } from "./prepare.js";
+export { trainingPreparationSchema, parseTrainingMappedPreparation } from "./contract.js";
+export type { TrainingMappedPreparation, TrainingPreparationConfig } from "./contract.js";

package/dist/compiler/training/preparation/index.js

@@ -0,0 +1,2 @@
+export { prepareTraining } from "./prepare.js";
+export { trainingPreparationSchema, parseTrainingMappedPreparation } from "./contract.js";

package/dist/compiler/training/preparation/inputs.d.ts

@@ -0,0 +1,24 @@
+import type { TrainingPreparationConfig } from "./contract.js";
+import { type SealedFile } from "./files.js";
+export interface PlannedInput {
+    id: string;
+    source: string;
+    destination: string;
+    digest: string;
+    files?: SealedFile[];
+    git?: {
+        revision: string;
+        tree: string;
+        common: string;
+        overlays: SealedFile[];
+        paths: string[];
+    };
+}
+export declare function planInputs(config: TrainingPreparationConfig, root: string, auth: string[]): Promise<PlannedInput[]>;
+/** A real self-contained Git object store, never a copied worktree pointer. */
+export declare function stageInput(input: PlannedInput, target: string): Promise<string>;
+export declare function verifyCanonicalPins(inputs: PlannedInput[], sources: readonly {
+    sourcePath: string;
+    sha256: string;
+}[], staged: readonly string[]): Promise<void>;
+export declare function readBoundedJson(file: string): Promise<unknown>;

package/dist/compiler/training/preparation/inputs.js

@@ -0,0 +1,101 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { pathToFileURL } from "node:url";
+import { assertInputRoot, copySealed, exactPath, fileIdentity, hashJson, sealFile, sealTree, within } from "./files.js";
+const execute = promisify(execFile);
+const git = async (cwd, args, input) => {
+    const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_")));
+    const operation = execute("git", ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", ...args], {
+        cwd, env: { ...env, GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_ATTR_NOSYSTEM: "1", GIT_TERMINAL_PROMPT: "0" },
+        timeout: 120000, maxBuffer: 8 * 1024 * 1024
+    });
+    operation.child.stdin?.end(input);
+    return (await operation).stdout;
+};
+export async function planInputs(config, root, auth) {
+    return Promise.all(config.inputs.map(async (input) => {
+        const source = await exactPath(path.resolve(root, input.source));
+        assertInputRoot(source, auth);
+        if (input.include) {
+            const files = [];
+            for (const selected of input.include)
+                files.push(...await sealTree(path.join(source, selected), selected, { internalSymlinks: true }));
+            if (new Set(files.map(file => file.destination)).size !== files.length)
+                throw Error("Selected training input paths overlap");
+            return { id: input.id, source, destination: input.destination, files, digest: hashJson(fileIdentity(files)) };
+        }
+        if (!input.git)
+            return { id: input.id, source, destination: input.destination, digest: hashJson(fileIdentity(await sealTree(source, "input", { ignoreGit: true, internalSymlinks: true }))) };
+        if ((await git(source, ["rev-parse", "--show-prefix"])).trim())
+            throw Error("Pinned Git input source must be a repository root");
+        const common = await exactPath((await git(source, ["rev-parse", "--path-format=absolute", "--git-common-dir"])).trim());
+        const tree = (await git(source, ["rev-parse", `${input.git.revision}^{tree}`])).trim();
+        const entries = (await git(source, ["ls-tree", "-rz", "--full-tree", input.git.revision])).split("\0").filter(Boolean);
+        if (!/^[a-f0-9]{40}$/u.test(tree) || entries.some(entry => !/^(100644|100755|120000) blob [a-f0-9]{40}\t/u.test(entry)))
+            throw Error("Pinned Git inputs require regular files or confined links; submodules are unsupported");
+        for (const entry of entries.filter(entry => entry.startsWith("120000"))) {
+            const split = entry.indexOf("\t"), file = entry.slice(split + 1), object = entry.slice(0, split).split(" ")[2];
+            const link = (await git(source, ["cat-file", "blob", object])).trim();
+            const target = path.posix.normalize(path.posix.join(path.posix.dirname(file), link));
+            if (!link || path.posix.isAbsolute(link) || link.includes("\\") || target === ".." || target.startsWith("../") || target.split("/").includes(".git"))
+                throw Error("Git symlink escapes the pinned input tree");
+        }
+        const overlays = [];
+        for (const overlay of input.git.overlays) {
+            const overlaySource = path.resolve(root, overlay.source);
+            assertInputRoot(overlaySource, auth);
+            const file = await sealFile(overlaySource, overlay.path);
+            if (file.sha256 !== overlay.sha256 || overlays.some(previous => previous.destination === file.destination))
+                throw Error("Git overlay digest mismatch or duplicate destination");
+            overlays.push(file);
+        }
+        return { id: input.id, source, destination: input.destination, git: { revision: input.git.revision, tree, common, overlays, paths: entries.map(entry => entry.slice(entry.indexOf("\t") + 1)) },
+            digest: hashJson({ revision: input.git.revision, tree, overlays: fileIdentity(overlays) }) };
+    }));
+}
+/** A real self-contained Git object store, never a copied worktree pointer. */
+export async function stageInput(input, target) {
+    if (input.files) {
+        await mkdir(target, { mode: 0o700 });
+        await copySealed(input.files, target);
+        return target;
+    }
+    if (!input.git)
+        return input.source;
+    await mkdir(target, { mode: 0o700 });
+    await git(target, ["init", "--quiet", "--template="]);
+    await git(target, ["-c", "protocol.file.allow=always", "fetch", "--quiet", "--depth=1", pathToFileURL(input.git.common).href, input.git.revision]);
+    // Populate the index/HEAD without writing paths that the overlay owns.
+    await git(target, ["update-ref", "--no-deref", "HEAD", input.git.revision]);
+    await git(target, ["read-tree", input.git.revision]);
+    const overlayPaths = new Set(input.git.overlays.map(file => file.destination));
+    const basePaths = input.git.paths.filter(file => !overlayPaths.has(file));
+    await git(target, ["checkout-index", "--stdin", "-z"], basePaths.map(file => `${file}\0`).join(""));
+    if ((await git(target, ["rev-parse", "HEAD^{tree}"])).trim() !== input.git.tree ||
+        (await git(target, ["rev-parse", "--path-format=absolute", "--git-common-dir"])).trim() !== path.join(target, ".git"))
+        throw Error("Git training snapshot identity mismatch");
+    await git(target, ["fsck", "--full", "--no-dangling"]);
+    await copySealed(input.git.overlays, target);
+    return target;
+}
+export async function verifyCanonicalPins(inputs, sources, staged) {
+    for (const source of sources) {
+        const index = inputs.findIndex(input => source.sourcePath === input.source || source.sourcePath.startsWith(input.source + path.sep));
+        if (index < 0)
+            throw Error("Canonical training source is outside declared inputs");
+        const file = path.join(staged[index], path.relative(inputs[index].source, source.sourcePath));
+        const canonicalFile = await realpath(file);
+        if (!within(staged[index], canonicalFile))
+            throw Error("Canonical training source escapes its staged input");
+        if ((await sealFile(canonicalFile, "pin")).sha256 !== source.sha256)
+            throw Error("Pinned Git snapshot differs from the selected canonical agent");
+    }
+}
+export async function readBoundedJson(file) {
+    const source = await readFile(file, "utf8");
+    if (Buffer.byteLength(source) > 1024 * 1024)
+        throw Error("Training preparation JSON exceeds 1 MiB");
+    return JSON.parse(source);
+}

package/dist/compiler/training/preparation/prepare.d.ts

@@ -0,0 +1,38 @@
+import { type TrainingExecution } from "../execution.js";
+import type { TrainingContext } from "../contract.js";
+import type { TrainingDockerProcess } from "../container/process.js";
+export interface PrepareTrainingOptions {
+    execution?: TrainingExecution;
+    outputOverride?: string;
+    imageOverride?: string;
+    configPath: string;
+    context: TrainingContext;
+    args: readonly string[];
+    dryRun: boolean;
+    process: TrainingDockerProcess;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    streams: {
+        stdout(line: string): void;
+        stderr(line: string): void;
+    };
+    /** Test-only package fixture; production always resolves its own installed distribution. */
+    packageRoot?: string;
+    repairMeasurements?: string;
+    repairWitness?: string;
+}
+export interface PreparedTraining {
+    execution?: TrainingExecution;
+    digest: string;
+    image: string;
+    configPath: string;
+    preparationPath: string;
+    repairPath?: string;
+    context: TrainingContext;
+    args: string[];
+}
+/** Reads only until the explicit dry-run boundary; preparation never executes project code. */
+export declare function prepareTraining(options: PrepareTrainingOptions): Promise<PreparedTraining | {
+    digest: string;
+    dryRun: true;
+}>;