spawnfile 0.1.13 → 0.1.17

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

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { copyFile, lstat, mkdir, readdir, realpath, chmod } 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 };
+}
+/** Only explicitly selected trees are traversed. Symlinks never enter Docker context. */
+export async function sealTree(source, destination, options = {}) {
+    await exactPath(source);
+    const files = [];
+    const walk = async (root, target, depth) => {
+        if (depth > 32 || files.length > 10000)
+            throw Error("Training source tree exceeds bounds");
+        let stat = await lstat(root);
+        if (stat.isSymbolicLink()) {
+            const actual = await realpath(root);
+            if (!options.internalSymlinks || !within(source, actual))
+                throw Error("Training source trees must not contain escaping symlinks");
+            root = actual;
+            stat = await lstat(root);
+        }
+        if (stat.isDirectory()) {
+            for (const entry of (await readdir(root)).sort()) {
+                if (options.ignoreGit && entry === ".git")
+                    continue;
+                if (options.ignoreDevelopment && (ignored.has(entry) || /(?:\.test\.[cm]?[jt]s|_test\.py|\.pyc)$/u.test(entry)))
+                    continue;
+                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) {
+    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 mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+        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");
+    }
+}
+export const fileIdentity = (files) => files.map(({ destination, sha256, mode, size }) => ({ destination, sha256, mode, size }));

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,102 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+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);
+    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");
+    const recipe = await readFile(path.join(assets, "Dockerfile"), "utf8");
+    const dockerfile = daimonParent ? bindDaimonParentVerification(recipe, daimonParent) : recipe;
+    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")}}']);
+        if (result.code !== 0)
+            return undefined;
+        try {
+            const [id, digest] = result.stdout.trim().split("\n").map(line => JSON.parse(line));
+            return /^sha256:[a-f0-9]{64}$/u.test(id) && digest === plan.digest ? 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,23 @@
+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[];
+    };
+}
+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,93 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile } 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 } from "./files.js";
+const execute = promisify(execFile);
+const git = async (cwd, args) => {
+    const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_")));
+    return (await 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
+    })).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 },
+            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]);
+    await git(target, ["-c", "advice.detachedHead=false", "checkout", "--quiet", "--detach", input.git.revision]);
+    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");
+        if (!inputs[index].git && !inputs[index].files)
+            continue;
+        const file = path.join(staged[index], path.relative(inputs[index].source, source.sourcePath));
+        if ((await sealFile(file, "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,33 @@
+import type { TrainingContext } from "../contract.js";
+import type { TrainingDockerProcess } from "../container/process.js";
+export interface PrepareTrainingOptions {
+    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 {
+    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;
+}>;

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

@@ -0,0 +1,186 @@
+import { lstat, mkdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { trainingContainerConfigSchema } from "../container/contract.js";
+import { trainingPreparationSchema, parseTrainingMappedPreparation } from "./contract.js";
+import { assertInputRoot, exactPath, fileIdentity, hashJson, sealTree, within } from "./files.js";
+import { planInputs, readBoundedJson, stageInput, verifyCanonicalPins } from "./inputs.js";
+import { planTrainingImage, buildTrainingImage } from "./image.js";
+import { planMeasurementRepair, stageMeasurementRepair, writeTrainingWitness } from "../repair/index.js";
+import { prepareTrainingBroker } from "./broker.js";
+import { claimTrainingPreparationScratch } from "./scratch.js";
+function mappedReceipt(digest, image, config) {
+    return parseTrainingMappedPreparation({ version: "spawnfile.training-preparation.v1", preparationDigest: digest, imageId: image,
+        bindings: config.inputs.map(input => ({ inputId: input.id, destination: input.destination })), outputRoot: "/run/training/output",
+        packagePaths: { spawnfile: "build" in config.image && config.image.build.compiler
+                ? "/opt/training/compiler/dist/cli/index.js" : "/opt/training/spawnfile/dist/cli/index.js", paideia: "/opt/training/paideia", bridge: "/opt/training/paideia/bridges/dspy",
+            nativeWorker: "/opt/training/paideia/dist/src/adapters/daimon-native", integration: "/opt/training/integration", bootstrap: "/opt/training/bootstrap" }, integration: config.integration });
+}
+/** Reads only until the explicit dry-run boundary; preparation never executes project code. */
+export async function prepareTraining(options) {
+    const config = trainingPreparationSchema.parse(await readBoundedJson(options.configPath));
+    // A v2 declaration still lowers to the unchanged v1 launch config; only v3 carries a broker slot into Docker.
+    const launchVersion = config.version === "spawnfile.training-container.v3" ? config.version : "spawnfile.training-container.v1";
+    const root = path.dirname(path.resolve(options.configPath));
+    const auth = config.auth.map(entry => ({ ...entry, source: path.resolve(root, entry.source) }));
+    const output = path.resolve(root, config.output.source), parent = path.dirname(output);
+    for (let index = 0; index < options.args.length; index++) {
+        if (options.args[index] !== "--out")
+            continue;
+        const declared = options.args[++index];
+        if (declared === undefined || path.resolve(declared) !== output)
+            throw Error("Training --out must match configured output");
+    }
+    assertInputRoot(output, auth.map(entry => entry.source));
+    if (await realpath(parent) !== parent)
+        throw Error("Training output parent must be canonical and already exist");
+    const inputs = await planInputs(config, root, auth.map(entry => entry.source));
+    const roots = inputs.map(input => input.source);
+    for (let index = 0; index < inputs.length; index++) {
+        const input = inputs[index];
+        if (within(input.source, output) || within(output, input.source))
+            throw Error("Training output overlaps readonly input");
+        for (const other of inputs.slice(index + 1))
+            if (within(input.source, other.source) || within(other.source, input.source) ||
+                within(input.destination, other.destination) || within(other.destination, input.destination))
+                throw Error("Training inputs overlap");
+    }
+    const imagePlan = "build" in config.image
+        ? await planTrainingImage(config.image.build, root, auth.map(entry => entry.source), options.packageRoot, path.resolve(options.configPath))
+        : undefined;
+    if (options.repairWitness && !options.repairMeasurements)
+        throw Error("A repair witness requires --repair-measurements");
+    if (options.repairMeasurements && !imagePlan)
+        throw Error("Measurement repair requires a verifiable image build recipe");
+    const repair = options.repairMeasurements ? await planMeasurementRepair({ parent: options.repairMeasurements,
+        witness: options.repairWitness, output, auth: auth.map(entry => entry.source), image: imagePlan, inputs,
+        context: options.context, resume: options.args.includes("--resume") }) : undefined;
+    if (repair && hashJson(config.integration) !== hashJson(repair.witness.manifest.config.integration))
+        throw Error("Repair integration settings binding changed");
+    const digest = hashJson({ config, sources: inputs.map(input => ({ id: input.id, digest: input.digest })), image: imagePlan?.digest ?? config.image,
+        canonical: options.context.project.sourceDigest, ...(repair ? { repair: { witness: repair.witness.digest, parent: repair.manifestDigest } } : {}) });
+    if (config.broker)
+        await prepareTrainingBroker(config.broker, root, path.dirname(path.resolve(options.configPath)), false);
+    if (options.dryRun)
+        return { digest, dryRun: true };
+    options.signal?.throwIfAborted();
+    for (const entry of auth)
+        if (await exactPath(entry.source) !== entry.source || !(await lstat(entry.source)).isFile())
+            throw Error("Training auth must be a canonical regular leaf");
+    const execute = (args) => options.process(args, { timeoutMs: options.timeoutMs, signal: options.signal });
+    const endpoint = await execute(["context", "inspect", config.dockerContext, "--format", "{{json .Endpoints.docker.Host}}"]);
+    if (endpoint.code !== 0 || !/^unix:\/\//u.test(JSON.parse(endpoint.stdout)))
+        throw Error("Training preparation requires a local Unix Docker context");
+    if (repair) {
+        const label = await execute(["--context", config.dockerContext, "image", "inspect", repair.witness.manifest.parentImage,
+            "--format", '{{json .Id}}\n{{json (index .Config.Labels "com.spawnfile.training.recipe")}}']);
+        const values = label.stdout.trim().split("\n").map(value => JSON.parse(value));
+        if (label.code !== 0 || values[0] !== repair.witness.manifest.parentImage || values[1] !== repair.witness.manifest.imagePlanDigest)
+            throw Error("Parent image recipe witness is unverified");
+    }
+    const staging = path.join(parent, `.spawnfile-training-preparation-${hashJson(output).slice(7, 23)}`);
+    const configPath = path.join(staging, "launch.json"), preparationPath = path.join(staging, "mapped.json"), statePath = path.join(staging, "state.json");
+    const resume = options.args.includes("--resume");
+    let image, staged;
+    if (resume) {
+        const previous = JSON.parse(await readFile(statePath, "utf8"));
+        if (previous.digest !== digest || !/^sha256:[a-f0-9]{64}$/u.test(previous.image) ||
+            JSON.stringify(previous.staged) !== JSON.stringify(inputs.map(input => input.git || input.files ? path.join(staging, input.id) : input.source)))
+            throw Error("Training preparation changed; exact resume rejected");
+        image = previous.image;
+        staged = previous.staged;
+        const snapshots = await Promise.all(inputs.map(async (input, index) => input.git || input.files ? hashJson(fileIdentity(await sealTree(staged[index], "input", { ignoreGit: true, internalSymlinks: true }))) : null));
+        if (JSON.stringify(previous.snapshots) !== JSON.stringify(snapshots))
+            throw Error("Persisted training input snapshot changed");
+        const mapped = parseTrainingMappedPreparation(await readBoundedJson(preparationPath));
+        if (mapped.preparationDigest !== digest || mapped.imageId !== image)
+            throw Error("Persisted training preparation identity mismatch");
+        await verifyCanonicalPins(inputs, options.context.sources, staged);
+    }
+    else {
+        let owned = false;
+        try {
+            await claimTrainingPreparationScratch(staging, digest, options.streams.stderr);
+            owned = true;
+            try {
+                await mkdir(output, { mode: 0o700 });
+            }
+            catch (error) {
+                if (error.code !== "EEXIST" || !(await lstat(output)).isDirectory() || await realpath(output) !== output)
+                    throw error;
+            }
+            staged = await Promise.all(inputs.map(input => stageInput(input, path.join(staging, input.id))));
+            await verifyCanonicalPins(inputs, options.context.sources, staged);
+            image = imagePlan ? (await buildTrainingImage(imagePlan, { parent, dockerContext: config.dockerContext, process: options.process,
+                timeoutMs: options.timeoutMs, signal: options.signal, streams: options.streams })).imageId : "ref" in config.image ? config.image.ref : "";
+            if (!image.startsWith("sha256:")) {
+                const inspected = await execute(["--context", config.dockerContext, "image", "inspect", image, "--format", "{{.Id}}"]);
+                if (inspected.code !== 0)
+                    throw Error("Training image is unavailable");
+                image = inspected.stdout.trim();
+            }
+            const mapped = mappedReceipt(digest, image, config);
+            const preparedBroker = config.broker ? await prepareTrainingBroker(config.broker, root, staging, true) : undefined;
+            const launch = trainingContainerConfigSchema.parse({ version: launchVersion, dockerContext: config.dockerContext,
+                inputs: inputs.map((input, index) => ({ source: staged[index], destination: input.destination })), output: { source: output, destination: "/run/training/output" }, auth,
+                ...(preparedBroker ? { broker: preparedBroker.launch } : {}) });
+            await writeFile(configPath, JSON.stringify(launch), { flag: "wx", mode: 0o600 });
+            await writeFile(preparationPath, JSON.stringify(parseTrainingMappedPreparation(mapped)), { flag: "wx", mode: 0o400 });
+            const snapshots = await Promise.all(inputs.map(async (input, index) => input.git || input.files ? hashJson(fileIdentity(await sealTree(staged[index], "input", { ignoreGit: true, internalSymlinks: true }))) : null));
+            await writeFile(statePath, JSON.stringify({ digest, image, staged, snapshots }), { flag: "wx", mode: 0o600 });
+            if (imagePlan)
+                await writeTrainingWitness({ directory: staging, digest, image, config, context: options.context,
+                    args: options.args, inputs, staged, snapshots, plan: imagePlan,
+                    ...(repair ? { repair: { witness: repair.witness.digest, parent: repair.manifestDigest } } : {}) });
+        }
+        catch (error) {
+            if (owned)
+                await rm(staging, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    const expectedBroker = config.broker ? await prepareTrainingBroker(config.broker, root, staging, false) : undefined;
+    const expectedLaunch = trainingContainerConfigSchema.parse({ version: launchVersion, dockerContext: config.dockerContext,
+        inputs: inputs.map((input, index) => ({ source: staged[index], destination: input.destination })), output: { source: output, destination: "/run/training/output" }, auth,
+        ...(expectedBroker ? { broker: expectedBroker.launch } : {}) });
+    if (hashJson(await readBoundedJson(configPath)) !== hashJson(expectedLaunch) ||
+        hashJson(await readBoundedJson(preparationPath)) !== hashJson(mappedReceipt(digest, image, config)))
+        throw Error("Saved training launch or mapped receipt changed");
+    const inspected = await execute(["--context", config.dockerContext, "image", "inspect", image, "--format", "{{.Id}}"]);
+    if (inspected.code !== 0 || inspected.stdout.trim() !== image)
+        throw Error("Saved training image is missing or changed");
+    const map = (file) => {
+        const absolute = path.resolve(file);
+        const index = roots.findIndex(source => within(source, absolute));
+        return index < 0 ? absolute : path.join(staged[index], path.relative(roots[index], absolute));
+    };
+    const context = { ...options.context,
+        project: { ...options.context.project, root: map(options.context.project.root), manifest: map(options.context.project.manifest) },
+        agent: { ...options.context.agent, source: map(options.context.agent.source) },
+        sources: options.context.sources.map(source => ({ ...source, sourcePath: map(source.sourcePath) })),
+        documents: options.context.documents.map(source => ({ ...source, sourcePath: map(source.sourcePath) })),
+        skills: options.context.skills.map(source => ({ ...source, sourcePath: map(source.sourcePath) })) };
+    const args = [...options.args];
+    for (let index = 0; index < args.length; index++) {
+        if (["--train", "--test", "--cost-config"].includes(args[index]))
+            args[++index] = map(args[index]);
+        else if (args[index] === "--resource") {
+            const value = args[++index], split = value.indexOf("=");
+            args[index] = `${value.slice(0, split)}=${map(value.slice(split + 1))}`;
+        }
+    }
+    if (repair) {
+        const projected = await stageMeasurementRepair(repair, staging, image, options.context.project.sourceDigest, resume);
+        const repairLaunch = { ...expectedLaunch, inputs: [...expectedLaunch.inputs,
+                { source: projected.root, destination: "/run/training/inputs/repair-parent" }] };
+        const repairConfig = path.join(staging, "repair-launch.json");
+        if (resume) {
+            if (hashJson(await readBoundedJson(repairConfig)) !== hashJson(repairLaunch))
+                throw Error("Saved repair launch changed");
+        }
+        else
+            await writeFile(repairConfig, JSON.stringify(repairLaunch), { flag: "wx", mode: 0o600 });
+        return { digest, image, configPath: repairConfig, preparationPath, repairPath: projected.repairPath, context,
+            args: [...args, "--repair-measurements", "/run/training/inputs/repair-parent", "--repair-context", "/run/paideia/repair.json"] };
+    }
+    return { digest, image, configPath, preparationPath, context, args };
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Claims the private preparation scratch directory for one launch.
+ *
+ * A launch that fails anywhere past staging — a failed build, a container that
+ * aborted in its entrypoint — leaves this directory behind, and the next
+ * attempt used to die on `EEXIST: mkdir '.spawnfile-training-preparation-…'`
+ * before it could report anything useful. A live P8 run lost its second attempt
+ * to exactly that.
+ *
+ * Leftovers from the *same* preparation are reclaimed: `state.json` records the
+ * preparation digest, which pins the config, every input identity, the image
+ * plan and the canonical source digest, so a matching one can only have staged
+ * the same bytes and nothing is lost by staging them again (the image is
+ * content-addressed and resolves from its tag). Anything else — a different
+ * digest, or a run that aborted before it wrote its state — is left untouched
+ * and reported by name, because only the operator can know whether it is
+ * wanted or whether another launch is still using it.
+ */
+export declare const claimTrainingPreparationScratch: (staging: string, digest: string, notify: (line: string) => void) => Promise<void>;

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

@@ -0,0 +1,48 @@
+import { lstat, mkdir, readFile, realpath, rm } from "node:fs/promises";
+/**
+ * Claims the private preparation scratch directory for one launch.
+ *
+ * A launch that fails anywhere past staging — a failed build, a container that
+ * aborted in its entrypoint — leaves this directory behind, and the next
+ * attempt used to die on `EEXIST: mkdir '.spawnfile-training-preparation-…'`
+ * before it could report anything useful. A live P8 run lost its second attempt
+ * to exactly that.
+ *
+ * Leftovers from the *same* preparation are reclaimed: `state.json` records the
+ * preparation digest, which pins the config, every input identity, the image
+ * plan and the canonical source digest, so a matching one can only have staged
+ * the same bytes and nothing is lost by staging them again (the image is
+ * content-addressed and resolves from its tag). Anything else — a different
+ * digest, or a run that aborted before it wrote its state — is left untouched
+ * and reported by name, because only the operator can know whether it is
+ * wanted or whether another launch is still using it.
+ */
+export const claimTrainingPreparationScratch = async (staging, digest, notify) => {
+    try {
+        await mkdir(staging, { mode: 0o700 });
+        return;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    const info = await lstat(staging);
+    if (!info.isDirectory() || info.isSymbolicLink() || await realpath(staging) !== staging) {
+        throw Error(`Training preparation scratch ${staging} is not a canonical directory; remove it and retry`);
+    }
+    let previous;
+    try {
+        previous = JSON.parse(await readFile(`${staging}/state.json`, "utf8"));
+    }
+    catch {
+        previous = undefined;
+    }
+    if (previous?.digest !== digest) {
+        throw Error(previous === undefined
+            ? `Training preparation scratch ${staging} is left over from an interrupted launch that never recorded its identity; remove it to retry: rm -rf ${JSON.stringify(staging)}`
+            : `Training preparation scratch ${staging} belongs to a different preparation (${String(previous.digest)}); remove it to retry: rm -rf ${JSON.stringify(staging)}`);
+    }
+    notify(`Reusing the preparation scratch left by an earlier launch of this exact preparation: ${staging}`);
+    await rm(staging, { recursive: true, force: true });
+    await mkdir(staging, { mode: 0o700 });
+};