spawnfile 0.1.17 → 0.1.18

package/dist/compiler/training/execution.d.ts

@@ -0,0 +1,417 @@
+import { z } from "zod";
+import { type TrainingPlan } from "./plan/contract.js";
+import type { LoadedTrainingProject } from "./plan/types.js";
+export declare const TRAINING_EXECUTION_FILE = "/run/paideia/execution.json";
+export { TRAINING_EXECUTION_CAPABILITY_LABEL, TRAINING_EXECUTION_VERSION } from "./contract.js";
+export declare const trainingExecutionSchema: z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.training-execution.v1">;
+    authoring: z.ZodObject<{
+        version: z.ZodLiteral<"spawnfile.training-plan.v1">;
+        producer: z.ZodObject<{
+            package: z.ZodLiteral<"spawnfile">;
+            version: z.ZodString;
+        }, z.core.$strict>;
+        project: z.ZodObject<{
+            root: z.ZodString;
+            manifest: z.ZodString;
+        }, z.core.$strict>;
+        agent: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strict>;
+        deadlines: z.ZodOptional<z.ZodObject<{
+            experiment_ms: z.ZodNumber;
+            trial_ms: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        preparation: z.ZodOptional<z.ZodObject<{
+            hook: z.ZodString;
+            history: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        record: z.ZodNullable<z.ZodObject<{
+            keep: z.ZodNullable<z.ZodString>;
+            volumes: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                declaredBy: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        optimizer: z.ZodNullable<z.ZodObject<{
+            method: z.ZodString;
+            model: z.ZodString;
+            variants: z.ZodNumber;
+            keep: z.ZodNumber;
+            budget: z.ZodObject<{
+                rounds: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+        graders: z.ZodArray<z.ZodObject<{
+            sourcePath: z.ZodString;
+            path: z.ZodString;
+            name: z.ZodString;
+            declaredBy: z.ZodString;
+        }, z.core.$strict>>;
+        targets: z.ZodArray<z.ZodObject<{
+            declaredBy: z.ZodString;
+            grader: z.ZodString;
+            files: z.ZodArray<z.ZodObject<{
+                sourcePath: z.ZodString;
+                path: z.ZodString;
+                consumers: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+            datasets: z.ZodObject<{
+                train: z.ZodObject<{
+                    sourcePath: z.ZodString;
+                    path: z.ZodString;
+                    examples: z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        at: z.ZodISODateTime;
+                        wake: z.ZodObject<{
+                            surface: z.ZodLiteral<"moltnet">;
+                            room: z.ZodString;
+                            from: z.ZodString;
+                            text: z.ZodString;
+                        }, z.core.$strict>;
+                        overrides: z.ZodArray<z.ZodObject<{
+                            id: z.ZodString;
+                            declaredBy: z.ZodString;
+                            section: z.ZodEnum<{
+                                memory: "memory";
+                                resources: "resources";
+                                networks: "networks";
+                            }>;
+                        }, z.core.$strict>>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>;
+                validation: z.ZodNullable<z.ZodObject<{
+                    sourcePath: z.ZodString;
+                    path: z.ZodString;
+                    examples: z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        at: z.ZodISODateTime;
+                        wake: z.ZodObject<{
+                            surface: z.ZodLiteral<"moltnet">;
+                            room: z.ZodString;
+                            from: z.ZodString;
+                            text: z.ZodString;
+                        }, z.core.$strict>;
+                        overrides: z.ZodArray<z.ZodObject<{
+                            id: z.ZodString;
+                            declaredBy: z.ZodString;
+                            section: z.ZodEnum<{
+                                memory: "memory";
+                                resources: "resources";
+                                networks: "networks";
+                            }>;
+                        }, z.core.$strict>>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
+                test: z.ZodObject<{
+                    sourcePath: z.ZodString;
+                    path: z.ZodString;
+                    examples: z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        at: z.ZodISODateTime;
+                        wake: z.ZodObject<{
+                            surface: z.ZodLiteral<"moltnet">;
+                            room: z.ZodString;
+                            from: z.ZodString;
+                            text: z.ZodString;
+                        }, z.core.$strict>;
+                        overrides: z.ZodArray<z.ZodObject<{
+                            id: z.ZodString;
+                            declaredBy: z.ZodString;
+                            section: z.ZodEnum<{
+                                memory: "memory";
+                                resources: "resources";
+                                networks: "networks";
+                            }>;
+                        }, z.core.$strict>>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    datasetPins: z.ZodArray<z.ZodObject<{
+        sourcePath: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+    optimizer: z.ZodObject<{
+        method: z.ZodString;
+        model: z.ZodString;
+        variants: z.ZodNumber;
+        keep: z.ZodNumber;
+        budget: z.ZodObject<{
+            rounds: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    args: z.ZodArray<z.ZodString>;
+    output: z.ZodString;
+}, z.core.$strict>;
+export type TrainingExecution = z.infer<typeof trainingExecutionSchema>;
+export interface LowerTrainingExecutionOptions {
+    project: LoadedTrainingProject;
+    plan: TrainingPlan;
+    args: readonly string[];
+    trainingConfig?: string;
+    trainingImage?: string;
+}
+/** Resolve local declaration and authoring defaults; no writes, auth reads or execution. */
+export declare const lowerTrainingExecution: (options: LowerTrainingExecutionOptions) => Promise<{
+    execution: {
+        version: "spawnfile.training-execution.v1";
+        authoring: {
+            version: "spawnfile.training-plan.v1";
+            producer: {
+                package: "spawnfile";
+                version: string;
+            };
+            project: {
+                root: string;
+                manifest: string;
+            };
+            agent: {
+                id: string;
+                name: string;
+            };
+            record: {
+                keep: string | null;
+                volumes: {
+                    id: string;
+                    declaredBy: string;
+                }[];
+            } | null;
+            optimizer: {
+                method: string;
+                model: string;
+                variants: number;
+                keep: number;
+                budget: {
+                    rounds: number;
+                };
+            } | null;
+            graders: {
+                sourcePath: string;
+                path: string;
+                name: string;
+                declaredBy: string;
+            }[];
+            targets: {
+                declaredBy: string;
+                grader: string;
+                files: {
+                    sourcePath: string;
+                    path: string;
+                    consumers: string[];
+                }[];
+                datasets: {
+                    train: {
+                        sourcePath: string;
+                        path: string;
+                        examples: {
+                            id: string;
+                            at: string;
+                            wake: {
+                                surface: "moltnet";
+                                room: string;
+                                from: string;
+                                text: string;
+                            };
+                            overrides: {
+                                id: string;
+                                declaredBy: string;
+                                section: "memory" | "resources" | "networks";
+                            }[];
+                        }[];
+                    };
+                    validation: {
+                        sourcePath: string;
+                        path: string;
+                        examples: {
+                            id: string;
+                            at: string;
+                            wake: {
+                                surface: "moltnet";
+                                room: string;
+                                from: string;
+                                text: string;
+                            };
+                            overrides: {
+                                id: string;
+                                declaredBy: string;
+                                section: "memory" | "resources" | "networks";
+                            }[];
+                        }[];
+                    } | null;
+                    test: {
+                        sourcePath: string;
+                        path: string;
+                        examples: {
+                            id: string;
+                            at: string;
+                            wake: {
+                                surface: "moltnet";
+                                room: string;
+                                from: string;
+                                text: string;
+                            };
+                            overrides: {
+                                id: string;
+                                declaredBy: string;
+                                section: "memory" | "resources" | "networks";
+                            }[];
+                        }[];
+                    };
+                };
+            }[];
+            deadlines?: {
+                experiment_ms: number;
+                trial_ms?: number | undefined;
+            } | undefined;
+            preparation?: {
+                hook: string;
+                history?: string | undefined;
+            } | undefined;
+        };
+        datasetPins: {
+            sourcePath: string;
+            sha256: string;
+        }[];
+        optimizer: {
+            method: string;
+            model: string;
+            variants: number;
+            keep: number;
+            budget: {
+                rounds: number;
+            };
+        };
+        args: string[];
+        output: string;
+    };
+    trainingConfig: string;
+    trainingImage: string | undefined;
+    declaration: {
+        version: "spawnfile.training-container.v1" | "spawnfile.training-container.v3" | "spawnfile.training-container.v4";
+        slots: number;
+        dockerContext: string;
+        inputs: {
+            source: string;
+            destination: string;
+        }[];
+        output: {
+            source: string;
+            destination: "/run/training/output";
+        };
+        auth: {
+            source: string;
+            provider: "codex" | "claude";
+        }[];
+        evaluatorRoutes?: {
+            purpose: "decisions" | "extraction" | "proposals";
+            provider: "codex-subscription" | "typesafe";
+            model: string;
+            maxRequests: number;
+            maxSpendUsd?: number | undefined;
+        }[] | undefined;
+        evaluatorSecrets?: {
+            provider: "typesafe";
+            source: string;
+        }[] | undefined;
+        subjectIsolation?: "codex-native-sandbox" | undefined;
+        broker?: {
+            engine: "grok";
+            realmVolume: string;
+            bootstrap: string;
+            declaration: string;
+        } | undefined;
+    } | {
+        version: "spawnfile.training-container.v3" | "spawnfile.training-container.v4" | "spawnfile.training-container.v2";
+        slots: number;
+        dockerContext: string;
+        image: {
+            ref: string;
+        } | {
+            build: {
+                recipe: "daimon-dspy.v1";
+                nativeImage: string;
+                pythonImage: string;
+                platform: "linux/amd64" | "linux/arm64";
+                paideia: string;
+                bridge: string;
+                claude: string;
+                integration: {
+                    source: string;
+                    entry: string;
+                    execution?: "spawnfile.training-execution.v1" | undefined;
+                };
+                compiler?: string | undefined;
+                grok?: {
+                    source: string;
+                    sha256: string;
+                } | undefined;
+                bootstrap?: string | undefined;
+            };
+        };
+        integration: {
+            settings: {
+                input: string;
+                path: string;
+            };
+        };
+        inputs: {
+            id: string;
+            source: string;
+            destination: string;
+            include?: string[] | undefined;
+            git?: {
+                revision: string;
+                overlays: {
+                    source: string;
+                    path: string;
+                    sha256: string;
+                }[];
+            } | undefined;
+        }[];
+        output: {
+            source: string;
+            destination: "/run/training/output";
+        };
+        auth: {
+            source: string;
+            provider: "codex" | "claude";
+        }[];
+        evaluatorRoutes?: {
+            purpose: "decisions" | "extraction" | "proposals";
+            provider: "codex-subscription" | "typesafe";
+            model: string;
+            maxRequests: number;
+            maxSpendUsd?: number | undefined;
+        }[] | undefined;
+        evaluatorSecrets?: {
+            provider: "typesafe";
+            source: string;
+        }[] | undefined;
+        subjectIsolation?: "codex-native-sandbox" | undefined;
+        broker?: {
+            maxRunRequests: number;
+            engine: "grok";
+            agentId: string;
+            model: "grok-4.6" | "grok-4.5" | "grok-build";
+            reasoningEffort: "high" | "medium" | "low";
+            architecture: "arm64" | "x64";
+            limits: {
+                maxRequests: number;
+                maxTokens: number;
+                timeoutMs: number;
+            };
+            realmVolume: string;
+            bootstrap: string;
+            unenforcedBindPolicy?: "refuse" | "profile-only" | undefined;
+        } | undefined;
+    };
+}>;
+/** Allocation is separate so dry-run never creates a directory, and aliases fail before writes. */
+export declare const allocateTrainingOutputParent: (output: string) => Promise<void>;
+/** Preserve identities and all dataset roles while projecting only filesystem addresses. */
+export declare const mapTrainingExecution: (execution: TrainingExecution, map: (file: string) => string) => TrainingExecution;
+/** Resume changes position/presence of --resume, not the experiment's effective inputs. */
+export declare const trainingExecutionIdentity: (execution: TrainingExecution) => unknown;

package/dist/compiler/training/execution.js

@@ -0,0 +1,160 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { defaultTrainingOutputRoot } from "./output.js";
+import { SpawnfileError } from "../../shared/index.js";
+import { trainingPlanSchema, trainingPlanOptimizerSchema } from "./plan/contract.js";
+import { trainingPreparationSchema } from "./preparation/contract.js";
+import { readBoundedJson } from "./preparation/inputs.js";
+import { trainingContainerConfigSchema, trainingImageSchema } from "./container/contract.js";
+export const TRAINING_EXECUTION_FILE = "/run/paideia/execution.json";
+export { TRAINING_EXECUTION_CAPABILITY_LABEL, TRAINING_EXECUTION_VERSION } from "./contract.js";
+export const trainingExecutionSchema = z.object({
+    version: z.literal("spawnfile.training-execution.v1"),
+    authoring: trainingPlanSchema,
+    datasetPins: z.array(z.object({ sourcePath: z.string().min(1), sha256: z.string().regex(/^sha256:[a-f0-9]{64}$/u) }).strict()),
+    optimizer: trainingPlanOptimizerSchema,
+    args: z.array(z.string().min(1)),
+    output: z.string().min(1)
+}).strict();
+const invalid = (message) => { throw new SpawnfileError("validation_error", message); };
+const option = (args, flag) => {
+    const index = args.indexOf(flag);
+    return index < 0 ? undefined : args[index + 1];
+};
+const exists = async (file) => {
+    try {
+        await lstat(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+};
+/** Resolve local declaration and authoring defaults; no writes, auth reads or execution. */
+export const lowerTrainingExecution = async (options) => {
+    const { project, plan } = options;
+    if (!plan.targets.length || !plan.optimizer)
+        return invalid(`Agent ${plan.agent.id} has no executable training targets`);
+    const agent = project.compilePlan.nodes.find(node => node.id === plan.agent.id);
+    const agentDirectory = path.dirname(agent.value.kind === "agent" ? agent.value.sourcePath ?? agent.value.source : agent.value.source);
+    const candidates = [...new Set([agentDirectory, project.root].map(root => path.join(root, "training/container.json")))];
+    let trainingConfig = options.trainingConfig === undefined ? undefined : path.resolve(options.trainingConfig);
+    if (trainingConfig === undefined)
+        for (const file of candidates)
+            if (await exists(file)) {
+                trainingConfig = file;
+                break;
+            }
+    if (trainingConfig === undefined)
+        return invalid(`Training requires a container declaration at ${candidates.join(" or ")}, or --training-config`);
+    trainingConfig = await realpath(trainingConfig);
+    const raw = await readBoundedJson(trainingConfig);
+    const preparation = raw.version === "spawnfile.training-container.v2" ||
+        (["spawnfile.training-container.v3", "spawnfile.training-container.v4"].includes(String(raw.version)) && raw.image !== undefined);
+    const declaration = preparation ? trainingPreparationSchema.parse(raw) : trainingContainerConfigSchema.parse(raw);
+    const trainingImage = options.trainingImage === undefined ? undefined : trainingImageSchema.parse(options.trainingImage);
+    if (!preparation && trainingImage === undefined) {
+        return invalid("A lowered container launch configuration requires --training-image; use a v2/v4 preparation declaration for a declared image");
+    }
+    const args = [...options.args];
+    if (!args.includes("--experiment-timeout-ms") && !args.includes("--timeout-ms")) {
+        args.push("--experiment-timeout-ms", String(plan.deadlines?.experiment_ms ?? 43_200_000));
+    }
+    if (!args.includes("--trial-timeout-ms") && plan.deadlines?.trial_ms !== undefined) {
+        args.push("--trial-timeout-ms", String(plan.deadlines.trial_ms));
+    }
+    // These are authoring locators. The receipt consumer lowers ALL target datasets into one file per role.
+    for (const role of ["train", "validation", "test"]) {
+        if (option(args, `--${role}`) !== undefined)
+            continue;
+        const sources = [...new Set(plan.targets.flatMap(target => target.datasets[role] ? [target.datasets[role].sourcePath] : []))];
+        if (role === "validation" && sources.length === 0)
+            continue;
+        args.push(`--${role}`, sources[0]);
+    }
+    if (!args.includes("--editable"))
+        for (const file of [...new Set(plan.targets.flatMap(target => target.files.map(file => file.path)))]) {
+            args.push("--editable", file);
+        }
+    if (!args.includes("--optimizer-model"))
+        args.push("--optimizer-model", plan.optimizer.model);
+    if (args.includes("--resume") && option(args, "--out") === undefined)
+        return invalid("--resume requires --out identifying the exact prior experiment");
+    const output = path.resolve(option(args, "--out") ?? path.join(defaultTrainingOutputRoot(project.root, declaration.inputs.map(input => path.resolve(path.dirname(trainingConfig), input.source))), encodeURIComponent(plan.agent.id), `${new Date().toISOString().replace(/[:.]/gu, "-")}-${randomUUID().slice(0, 8)}`));
+    if (!args.includes("--out"))
+        args.push("--out", output);
+    else
+        args[args.indexOf("--out") + 1] = output;
+    const datasetPins = [...new Set(plan.targets.flatMap(target => Object.values(target.datasets)
+            .filter(dataset => dataset !== null).map(dataset => dataset.sourcePath)))].map(sourcePath => {
+        const loaded = project.datasets[sourcePath];
+        if (!loaded)
+            return invalid(`Authored dataset was not captured during plan loading: ${sourcePath}`);
+        return { sourcePath, sha256: loaded.sha256 };
+    });
+    const execution = trainingExecutionSchema.parse({ version: "spawnfile.training-execution.v1", authoring: plan, datasetPins,
+        optimizer: { ...plan.optimizer, model: option(args, "--optimizer-model") }, args, output });
+    return { execution, trainingConfig, trainingImage, declaration };
+};
+/** Allocation is separate so dry-run never creates a directory, and aliases fail before writes. */
+export const allocateTrainingOutputParent = async (output) => {
+    const parent = path.dirname(path.resolve(output));
+    const missing = [];
+    let ancestor = parent;
+    while (!await exists(ancestor)) {
+        missing.unshift(ancestor);
+        ancestor = path.dirname(ancestor);
+    }
+    if (await realpath(ancestor) !== ancestor || !(await lstat(ancestor)).isDirectory())
+        invalid("Training output parent must be a canonical directory");
+    for (const directory of missing) {
+        try {
+            await mkdir(directory, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        if (await realpath(directory) !== directory || !(await lstat(directory)).isDirectory())
+            invalid("Training output parent must be a canonical directory");
+    }
+};
+/** Preserve identities and all dataset roles while projecting only filesystem addresses. */
+export const mapTrainingExecution = (execution, map) => {
+    const source = (value) => ({ ...value, sourcePath: map(value.sourcePath) });
+    const args = [...execution.args];
+    for (let index = 0; index < args.length; index++) {
+        if (["--train", "--validation", "--test", "--out", "--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))}`;
+        }
+    }
+    return trainingExecutionSchema.parse({ ...execution, datasetPins: execution.datasetPins.map(source), args, output: map(execution.output), authoring: {
+            ...execution.authoring,
+            ...(execution.authoring.preparation ? { preparation: { ...execution.authoring.preparation,
+                    ...(execution.authoring.preparation.history ? { history: map(execution.authoring.preparation.history) } : {}) } } : {}),
+            project: { root: map(execution.authoring.project.root), manifest: map(execution.authoring.project.manifest) },
+            graders: execution.authoring.graders.map(source),
+            targets: execution.authoring.targets.map(target => ({ ...target, files: target.files.map(source), datasets: {
+                    train: source(target.datasets.train), test: source(target.datasets.test),
+                    validation: target.datasets.validation === null ? null : source(target.datasets.validation)
+                } }))
+        } });
+};
+/** Resume changes position/presence of --resume, not the experiment's effective inputs. */
+export const trainingExecutionIdentity = (execution) => {
+    const flags = [];
+    for (let index = 0; index < execution.args.length; index++) {
+        const flag = execution.args[index];
+        if (flag === "--resume")
+            continue;
+        flags.push(flag === "--dry-run" ? [flag] : [flag, execution.args[++index]]);
+    }
+    return { ...execution, args: flags.sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0) };
+};

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

@@ -1,4 +1,12 @@
 export * from "./contract.js";
 export * from "./context.js";
+export * from "./plan/index.js";
+export * from "./rewind/index.js";
+export type { ResolvedTraining, ResolvedTrainingGrader } from "./resolution.js";
 export { parseTrainingMappedPreparation } from "./preparation/contract.js";
 export type { TrainingMappedPreparation } from "./preparation/contract.js";
+export { TRAINING_SLOTS_FILE, TRAINING_SLOTS_VERSION, trainingSlotPaths, trainingSlotDescriptors, trainingSlotsDocument, type TrainingSlotsDocument, type TrainingSlotPaths, type TrainingSlotDescriptor } from "./broker/paths.js";
+export * from "./execution.js";
+export * from "./moments.js";
+export * from "./compiledAgent.js";
+export { TRAINING_FAKETIME_LIBRARY_PATH } from "./container/contract.js";

package/dist/compiler/training/index.js

@@ -1,3 +1,10 @@
 export * from "./contract.js";
 export * from "./context.js";
+export * from "./plan/index.js";
+export * from "./rewind/index.js";
 export { parseTrainingMappedPreparation } from "./preparation/contract.js";
+export { TRAINING_SLOTS_FILE, TRAINING_SLOTS_VERSION, trainingSlotPaths, trainingSlotDescriptors, trainingSlotsDocument } from "./broker/paths.js";
+export * from "./execution.js";
+export * from "./moments.js";
+export * from "./compiledAgent.js";
+export { TRAINING_FAKETIME_LIBRARY_PATH } from "./container/contract.js";

package/dist/compiler/training/moments.d.ts

@@ -0,0 +1,80 @@
+import type { LoadedTrainingProject, TrainingPlan } from "./plan/index.js";
+import { type MaterializedMoment } from "./rewind/contract.js";
+export type TrainingDatasetRole = "train" | "validation" | "test";
+type Example = TrainingPlan["targets"][number]["datasets"]["train"]["examples"][number];
+export interface TrainingMomentCase {
+    version: "spawnfile.training-moment-case.v1";
+    projectRoot: string;
+    agent: string;
+    example: string;
+    role: TrainingDatasetRole;
+    dataset: string;
+    at: string;
+    effectiveAt: string;
+    wake: Example["wake"];
+    group: string;
+    lineage: string;
+    momentRoot: string;
+    historyDir?: string;
+    hook: string;
+}
+export interface PreparedTrainingCase {
+    setup?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+    reference?: Record<string, unknown>;
+    outputs?: Record<string, string>;
+    checks?: unknown[];
+    stages?: unknown[];
+}
+export interface TrainingCasePreparation {
+    moment: MaterializedMoment;
+    momentRoot: string;
+    example: Example;
+    role: TrainingDatasetRole;
+    dataset: string;
+    group: string;
+    lineage: string;
+}
+export interface LowerTrainingMomentsOptions {
+    project: LoadedTrainingProject;
+    plan: TrainingPlan;
+    out: string;
+    historyDir?: string;
+    /** Named integration's case authoring only; never credentials or live subject execution. */
+    prepareCase?: (context: TrainingCasePreparation) => Promise<PreparedTrainingCase>;
+}
+export interface TrainingMomentLoweringEntry {
+    id: string;
+    role: TrainingDatasetRole;
+    dataset: string;
+    at: string;
+    wake: Example["wake"];
+    group: string;
+    lineage: string | null;
+    momentRoot: string;
+    status: "materialized" | "refused";
+    moment?: MaterializedMoment;
+    reason?: string;
+}
+/** Rewind each authored example exactly once; repeated target references share one case. */
+export declare const lowerTrainingMoments: (options: LowerTrainingMomentsOptions) => Promise<{
+    datasets: {
+        train: string;
+        validation?: string;
+        test: string;
+    };
+    report: {
+        version: "spawnfile.training-moment-lowering.v1";
+        agent: string;
+        entries: TrainingMomentLoweringEntry[];
+    };
+}>;
+/** Trial hooks call this on fresh paths; historical identity must match the accepted lowering. */
+export declare const materializeTrainingCase: (options: {
+    project: LoadedTrainingProject;
+    plan: TrainingPlan;
+    moment: TrainingMomentCase;
+    out: string;
+    expected?: MaterializedMoment;
+}) => Promise<MaterializedMoment>;
+export {};