spawnfile 0.1.17 → 0.1.18

package/dist/compiler/training/moments.js

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { materializeTrainingMoment } from "./rewind/materialize.js";
+import { normalizeInstant } from "./rewind/instant.js";
+import { materializedMomentSchema } from "./rewind/contract.js";
+const roles = ["train", "validation", "test"];
+const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const save = (file, value) => writeFile(file, `${JSON.stringify(value, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+/** Rewind each authored example exactly once; repeated target references share one case. */
+export const lowerTrainingMoments = async (options) => {
+    const { project, plan } = options;
+    const out = path.resolve(options.out);
+    // A fresh root is intentional: resume must use the persisted lowered dataset, never overwrite it.
+    await mkdir(out, { mode: 0o700 });
+    const entries = [];
+    const records = { train: [], validation: [], test: [] };
+    const seen = new Set(), declared = new Set();
+    const historyDir = options.historyDir ?? plan.preparation?.history;
+    for (const role of roles)
+        for (const target of plan.targets) {
+            const dataset = target.datasets[role];
+            if (!dataset)
+                continue;
+            declared.add(role);
+            for (const example of dataset.examples) {
+                const identity = JSON.stringify([role, dataset.sourcePath, example.id]);
+                if (seen.has(identity))
+                    continue;
+                seen.add(identity);
+                // Group follows the authored example's identity, not its split, preventing split leakage.
+                const group = `moment:${hash([plan.agent.id, example.id])}`;
+                const momentRoot = path.join(out, "moments", role, hash(identity));
+                const entry = { id: example.id, role, dataset: dataset.path, at: example.at,
+                    wake: example.wake, group, lineage: null, momentRoot, status: "refused" };
+                entries.push(entry);
+                try {
+                    const lineage = `moment:${hash([plan.agent.id, normalizeInstant(example.at), example.wake])}`;
+                    entry.lineage = lineage;
+                    // Scope the selector to this dataset; different datasets may use the same example ID.
+                    const scoped = { ...plan, targets: [{ ...target, datasets: { ...target.datasets, [role]: dataset } }] };
+                    const moment = await materializeTrainingMoment({ project, plan: scoped, example: `${role}:${example.id}`, historyDir, out: momentRoot });
+                    entry.moment = moment;
+                    if (moment.status === "refused") {
+                        entry.reason = moment.inputs.flatMap(input => input.refusal ? [input.refusal] : []).join("; ") || "Rewind leak check refused the example";
+                        continue;
+                    }
+                    const prepared = await options.prepareCase?.({ moment, momentRoot, example, role, dataset: dataset.path, group, lineage }) ?? {};
+                    if (!prepared.checks?.length && !prepared.stages?.length)
+                        throw new Error("Moment case hook must supply terminal checks or stages");
+                    const trainingMoment = { version: "spawnfile.training-moment-case.v1", projectRoot: project.root,
+                        agent: plan.agent.id, example: `${role}:${example.id}`, role, dataset: dataset.path, at: moment.at, effectiveAt: moment.effectiveAt,
+                        wake: example.wake, group, lineage, momentRoot, ...(historyDir ? { historyDir } : {}),
+                        hook: plan.preparation?.hook ?? "spawnfile/rewind" };
+                    records[role].push({ ...prepared, id: example.id, group, lineage: [lineage],
+                        input: { message: { network: example.wake.surface, sender: example.wake.from,
+                                target: example.wake.room, text: example.wake.text } },
+                        setup: { ...prepared.setup, trainingMoment }, context: { ...prepared.context, trainingMomentProvenance: moment } });
+                    entry.status = "materialized";
+                }
+                catch (error) {
+                    entry.reason = error instanceof Error ? error.message : String(error);
+                }
+            }
+        }
+    const datasets = {};
+    for (const role of roles)
+        if (declared.has(role)) {
+            datasets[role] = path.join(out, `${role}.paideia.json`);
+            await save(datasets[role], { schema: "paideia.dataset.v1", id: `${plan.agent.id}:${role}`, subject: plan.agent.name,
+                setup: { profile: plan.preparation?.hook ?? "spawnfile/rewind" }, records: records[role] });
+        }
+    const report = { version: "spawnfile.training-moment-lowering.v1", agent: plan.agent.id, entries };
+    await save(path.join(out, "lowering.json"), report);
+    // Keep every refusal on disk, including an all-refused role. Never substitute another split.
+    for (const role of declared)
+        if (records[role].length === 0)
+            throw new Error(`No executable ${role} moments; see ${path.join(out, "lowering.json")}`);
+    for (const role of roles) {
+        const ids = records[role].map(record => record.id);
+        if (new Set(ids).size !== ids.length)
+            throw new Error(`Duplicate executable ${role} example IDs across datasets; use unique IDs`);
+    }
+    return { datasets: datasets, report };
+};
+/** Trial hooks call this on fresh paths; historical identity must match the accepted lowering. */
+export const materializeTrainingCase = async (options) => {
+    const { project, plan, moment } = options;
+    if (project.root !== moment.projectRoot || plan.agent.id !== moment.agent)
+        throw new Error("Trial moment project or agent differs from lowering");
+    const targets = plan.targets.filter(target => target.datasets[moment.role]?.path === moment.dataset);
+    if (!targets.length)
+        throw new Error("Trial moment dataset is not declared");
+    const example = targets[0].datasets[moment.role].examples.find(value => `${moment.role}:${value.id}` === moment.example);
+    if (!example || !isDeepStrictEqual(example.wake, moment.wake) || normalizeInstant(example.at) !== normalizeInstant(moment.at)) {
+        throw new Error("Trial moment wake or instant differs from lowering");
+    }
+    const file = path.join(moment.momentRoot, "moment.json");
+    if (!options.expected) {
+        const stat = await lstat(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 2_000_000)
+            throw new Error("Accepted moment provenance must be a bounded regular file");
+    }
+    const expected = materializedMomentSchema.parse(options.expected ?? JSON.parse(await readFile(file, "utf8")));
+    if (expected.status !== "materialized" || expected.agent !== moment.agent || expected.example.id !== example.id ||
+        expected.example.role !== moment.role || expected.example.dataset !== moment.dataset || expected.at !== moment.at ||
+        expected.effectiveAt !== moment.effectiveAt || !expected.leakCheck.ok)
+        throw new Error("Accepted moment provenance differs from lowering");
+    const result = await materializeTrainingMoment({ project, plan: { ...plan, targets }, example: moment.example,
+        historyDir: moment.historyDir, out: options.out });
+    if (result.status !== "materialized" || result.effectiveAt !== moment.effectiveAt)
+        throw new Error("Trial rewind refused or historical start instant changed");
+    if (!isDeepStrictEqual(result.inputs, expected.inputs) || !isDeepStrictEqual(result.record, expected.record)) {
+        throw new Error("Trial rewind provenance differs from accepted lowering");
+    }
+    return result;
+};

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

@@ -0,0 +1,2 @@
+/** Durable default namespace disjoint from every declared input, even a project ancestor. */
+export declare const defaultTrainingOutputRoot: (projectRoot: string, inputs?: readonly string[]) => string;

package/dist/compiler/training/output.js

@@ -0,0 +1,20 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { within } from "./preparation/files.js";
+/** Durable default namespace disjoint from every declared input, even a project ancestor. */
+export const defaultTrainingOutputRoot = (projectRoot, inputs = []) => {
+    const sources = [projectRoot, ...inputs].map(source => path.resolve(source));
+    if (sources.includes(path.parse(projectRoot).root))
+        throw Error("No training output location exists outside declared inputs; supply --out");
+    const identity = createHash("sha256").update(projectRoot).digest("hex").slice(0, 16);
+    let ancestor = path.dirname(projectRoot);
+    for (;;) {
+        const candidate = path.join(ancestor, ".spawn-training", `${path.basename(projectRoot)}-${identity}`);
+        if (!sources.some(source => within(source, candidate) || within(candidate, source)))
+            return candidate;
+        const parent = path.dirname(ancestor);
+        if (parent === ancestor)
+            throw Error("No training output location exists outside declared inputs; supply --out");
+        ancestor = parent;
+    }
+};

package/dist/compiler/training/plan/contract.d.ts

@@ -0,0 +1,287 @@
+import { z } from "zod";
+export declare const TRAINING_PLAN_VERSION: "spawnfile.training-plan.v1";
+export declare const trainingPlanDatasetSchema: 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>;
+export declare const trainingPlanOptimizerSchema: 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>;
+export declare const trainingPlanSchema: 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>;
+export type TrainingPlan = z.infer<typeof trainingPlanSchema>;
+export type TrainingPlanDataset = z.infer<typeof trainingPlanDatasetSchema>;
+export type TrainingPlanOverride = TrainingPlanDataset["examples"][number]["overrides"][number];
+export declare const trainingPlanJsonSchema: z.core.ZodStandardJSONSchemaPayload<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>>;

package/dist/compiler/training/plan/contract.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { trainingInstantSchema, trainingWakeSchema } from "../../../manifest/index.js";
+export const TRAINING_PLAN_VERSION = "spawnfile.training-plan.v1";
+const text = z.string().min(1);
+const absolutePath = text.regex(/^(?:\/|[A-Za-z]:[\\/])/u);
+const relativePath = text.regex(/^(?!\/)[^\\]+$/u);
+const source = z.object({ sourcePath: absolutePath, path: relativePath }).strict();
+const reference = z.object({ id: text, declaredBy: text }).strict();
+export const trainingPlanDatasetSchema = source.extend({
+    examples: z.array(z.object({
+        id: text.regex(/^[A-Za-z0-9._-]+$/u),
+        at: trainingInstantSchema,
+        wake: trainingWakeSchema,
+        overrides: z.array(reference.extend({ section: z.enum(["resources", "memory", "networks"]) }).strict())
+    }).strict()).min(1)
+}).strict();
+export const trainingPlanOptimizerSchema = z.object({
+    method: text, model: text, variants: z.number().int().min(1), keep: z.number().int().min(1),
+    budget: z.object({ rounds: z.number().int().min(1) }).strict()
+}).strict();
+export const trainingPlanSchema = z.object({
+    version: z.literal(TRAINING_PLAN_VERSION),
+    producer: z.object({ package: z.literal("spawnfile"), version: text }).strict(),
+    project: z.object({ root: absolutePath, manifest: absolutePath }).strict(),
+    agent: z.object({ id: text, name: text }).strict(),
+    deadlines: z.object({
+        experiment_ms: z.number().int().min(1).max(604_800_000),
+        trial_ms: z.number().int().min(1).max(86_400_000).optional()
+    }).strict().optional(),
+    preparation: z.object({ hook: text, history: absolutePath.optional() }).strict().optional(),
+    record: z.object({
+        keep: text.regex(/^[1-9][0-9]*[mhd]$/u).nullable(),
+        volumes: z.array(reference)
+    }).strict().nullable(),
+    optimizer: trainingPlanOptimizerSchema.nullable(),
+    graders: z.array(source.extend({
+        name: text.regex(/^[A-Za-z0-9_-]+$/u), declaredBy: text
+    }).strict()),
+    targets: z.array(z.object({
+        declaredBy: text, grader: text.regex(/^[A-Za-z0-9_-]+$/u),
+        files: z.array(source.extend({ consumers: z.array(text).min(1) }).strict()).min(1),
+        datasets: z.object({
+            train: trainingPlanDatasetSchema,
+            validation: trainingPlanDatasetSchema.nullable(),
+            test: trainingPlanDatasetSchema
+        }).strict()
+    }).strict())
+}).strict();
+export const trainingPlanJsonSchema = z.toJSONSchema(trainingPlanSchema);

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

@@ -0,0 +1,5 @@
+export * from "./contract.js";
+export * from "./load.js";
+export * from "./resolve.js";
+export { resolveTrainingRecordVolumes } from "./references.js";
+export type * from "./types.js";

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

@@ -0,0 +1,4 @@
+export * from "./contract.js";
+export * from "./load.js";
+export * from "./resolve.js";
+export { resolveTrainingRecordVolumes } from "./references.js";

package/dist/compiler/training/plan/load.d.ts

@@ -0,0 +1,9 @@
+import type { TrainingPlan } from "./contract.js";
+import type { LoadedTrainingProject } from "./types.js";
+/** Local reads only. Loading preserves complete declarations; resolution projects public identities. */
+export declare const loadTrainingProject: (inputPath: string) => Promise<LoadedTrainingProject>;
+export interface CreateTrainingPlanOptions {
+    agent?: string;
+    packageVersion: string;
+}
+export declare const createTrainingPlan: (inputPath: string, options: CreateTrainingPlanOptions) => Promise<TrainingPlan>;

package/dist/compiler/training/plan/load.js

@@ -0,0 +1,153 @@
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { getManifestPath, resolveProjectPath } from "../../../filesystem/index.js";
+import { isInlineAgentMember, isReferencedMember, trainingDatasetSchema } from "../../../manifest/index.js";
+import { parseManifest } from "../../../manifest/parseManifest.js";
+import { buildCompilePlan } from "../../buildCompilePlan.js";
+import { invalidTraining } from "./references.js";
+import { resolveTrainingPlan } from "./resolve.js";
+const source = (root, sourcePath) => ({
+    sourcePath, path: path.relative(root, sourcePath).split(path.sep).join("/")
+});
+const reason = (error) => error instanceof Error ? error.message : String(error);
+const inside = (root, file) => {
+    const relative = path.relative(root, file);
+    return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+};
+/** Training-only preflight preserves target diagnostics before the compiler reads docs/skills. */
+const validateTrainingTargetSources = async (manifestPath, visited = new Set()) => {
+    const realManifest = await realpath(manifestPath).catch((error) => invalidTraining(`Unable to load training manifest ${manifestPath}: ${reason(error)}`));
+    if (visited.has(realManifest))
+        return;
+    visited.add(realManifest);
+    const manifest = parseManifest(await readFile(manifestPath, "utf8"), manifestPath);
+    const declarations = manifest.kind === "agent"
+        ? [{ declaredBy: `agent:${manifest.name}`, training: manifest.training }]
+        : [
+            { declaredBy: `team:${manifest.name}`, training: manifest.shared?.training },
+            ...manifest.members.filter(isInlineAgentMember).map((member) => ({
+                declaredBy: `agent:${member.id}`, training: member.training
+            }))
+        ];
+    for (const { declaredBy, training } of declarations) {
+        for (const target of training?.targets ?? []) {
+            for (const file of target.files) {
+                const sourcePath = resolveProjectPath(manifestPath, file);
+                const context = `Training target ${sourcePath} declared by ${declaredBy} (${manifestPath})`;
+                const stats = await lstat(sourcePath).catch((error) => invalidTraining(`${context} must be an existing regular .md file: ${reason(error)}`));
+                if (stats.isSymbolicLink())
+                    invalidTraining(`${context} must not be a symlink`);
+                if (!stats.isFile())
+                    invalidTraining(`${context} must be an existing regular .md file`);
+            }
+        }
+    }
+    const refs = manifest.kind === "team"
+        ? manifest.members.filter(isReferencedMember).map((member) => member.ref)
+        : (manifest.subagents ?? []).map((subagent) => subagent.ref);
+    for (const ref of refs) {
+        await validateTrainingTargetSources(getManifestPath(resolveProjectPath(manifestPath, ref)), visited);
+    }
+};
+const readYaml = async (file, schema, declaredBy) => {
+    try {
+        const bytes = await readFile(file);
+        return { value: schema.parse(parseYaml(bytes.toString("utf8"), { strict: true, uniqueKeys: true })),
+            sha256: `sha256:${createHash("sha256").update(bytes).digest("hex")}` };
+    }
+    catch (error) {
+        return invalidTraining(`Invalid training file ${file} declared by ${declaredBy}: ${reason(error)}`);
+    }
+};
+const loadDataFileSource = async (root, file, declaredBy) => {
+    const context = `Invalid training file ${file} declared by ${declaredBy}:`;
+    if (!inside(root, file))
+        invalidTraining(`${context} must be inside project root ${root}`);
+    const realPath = await realpath(file).catch((error) => invalidTraining(`${context} must be an existing regular file: ${reason(error)}`));
+    if (!inside(root, realPath))
+        invalidTraining(`${context} must be inside project root ${root} (no symlink escape)`);
+    const stats = await stat(file).catch((error) => invalidTraining(`${context} must be an existing regular file: ${reason(error)}`));
+    if (!stats.isFile())
+        invalidTraining(`${context} must be an existing regular file`);
+    return source(root, file);
+};
+/** Inspect every ancestor, including unreferenced Spawnfiles outside the compiled graph. */
+const nestedManifests = async (directory, file) => {
+    if (!inside(directory, file))
+        return [];
+    const manifests = [];
+    for (let ancestor = path.dirname(file); ancestor !== directory; ancestor = path.dirname(ancestor)) {
+        const manifest = path.join(ancestor, "Spawnfile");
+        try {
+            if ((await stat(manifest)).isFile())
+                manifests.push(manifest);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                invalidTraining(`Unable to inspect nested Spawnfile ${manifest} for training target ${file}: ${reason(error)}`);
+            }
+        }
+    }
+    return manifests;
+};
+const loadTargetFile = async (root, directory, realDirectory, file) => {
+    const result = { ...source(root, file), realPath: null, regular: false, nestedManifests: [] };
+    try {
+        result.realPath = await realpath(file);
+        result.regular = (await stat(file)).isFile();
+    }
+    catch (error) {
+        result.error = reason(error);
+        return result;
+    }
+    result.nestedManifests = [...new Set([
+            ...await nestedManifests(directory, file),
+            ...await nestedManifests(realDirectory, result.realPath)
+        ])].sort();
+    return result;
+};
+/** Local reads only. Loading preserves complete declarations; resolution projects public identities. */
+export const loadTrainingProject = async (inputPath) => {
+    let manifest;
+    try {
+        manifest = await realpath(getManifestPath(inputPath));
+    }
+    catch (error) {
+        return invalidTraining(`Unable to load training project ${inputPath}: ${reason(error)}`);
+    }
+    await validateTrainingTargetSources(manifest);
+    const compilePlan = await buildCompilePlan(manifest);
+    const root = path.dirname(compilePlan.root);
+    const project = { root, manifest, compilePlan, targets: [], datasets: {}, graders: {} };
+    for (const node of compilePlan.nodes) {
+        const training = node.value.training;
+        if (!training)
+            continue;
+        const manifestPath = node.value.kind === "agent" ? node.value.sourcePath ?? node.value.source : node.value.source;
+        const directory = path.dirname(manifestPath);
+        const realDirectory = await realpath(directory);
+        for (const grader of Object.values(training.graders)) {
+            if (project.graders[grader.sourcePath])
+                continue;
+            project.graders[grader.sourcePath] = await loadDataFileSource(root, grader.sourcePath, grader.declaredBy);
+        }
+        for (const declaration of training.targets) {
+            const target = {
+                declaredBy: node.id, kind: node.kind, directory, realDirectory, declaration,
+                files: await Promise.all(declaration.files.map((file) => loadTargetFile(root, directory, realDirectory, file)))
+            };
+            project.targets.push(target);
+            for (const file of Object.values(declaration.datasets)) {
+                if (!file || project.datasets[file])
+                    continue;
+                project.datasets[file] = {
+                    ...await loadDataFileSource(root, file, node.id), ...await readYaml(file, trainingDatasetSchema, node.id)
+                };
+            }
+        }
+    }
+    return project;
+};
+export const createTrainingPlan = async (inputPath, options) => resolveTrainingPlan(await loadTrainingProject(inputPath), options.agent, options.packageVersion);