spawnfile 0.1.14 → 0.1.18

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);

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

@@ -0,0 +1,19 @@
+import type { CompilePlan, ResolvedAgentNode } from "../../types.js";
+import type { ResolvedWorkspaceResource } from "../../workspaceResources.js";
+import type { TrainingPlanOverride } from "./contract.js";
+import type { TrainingAgentNode } from "./types.js";
+export declare const invalidTraining: (message: string) => never;
+export declare const lexical: (left: string, right: string) => number;
+/** Shared selection for the authoring plan and runtime recording; resolved visibility is authoritative. */
+export declare const resolveTrainingRecordVolumes: (agent: {
+    id: string;
+    value: ResolvedAgentNode;
+}) => Array<ResolvedWorkspaceResource & {
+    kind: "volume";
+}>;
+export declare const resolveTrainingResource: (plan: CompilePlan, agent: TrainingAgentNode, id: string, context: string) => {
+    resource: ResolvedWorkspaceResource;
+    declaredBy: string;
+};
+/** Uses compiler-resolved visibility, including shared banks and representative attachments. */
+export declare const resolveTrainingOverride: (plan: CompilePlan, agent: TrainingAgentNode, section: TrainingPlanOverride["section"], id: string, context: string) => TrainingPlanOverride;

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

@@ -0,0 +1,57 @@
+import { SpawnfileError } from "../../../shared/index.js";
+export const invalidTraining = (message) => {
+    throw new SpawnfileError("validation_error", message);
+};
+export const lexical = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const declaredId = (plan, source) => plan.nodes.find((node) => node.value.source === source)?.id
+    ?? invalidTraining(`Training reference has no declaring node: ${source}`);
+const one = (matches, id, context) => {
+    if (matches.length === 0)
+        invalidTraining(`${context}: unknown id ${id}`);
+    if (matches.length > 1)
+        invalidTraining(`${context}: ambiguous id ${id}`);
+    return matches[0];
+};
+/** Shared selection for the authoring plan and runtime recording; resolved visibility is authoritative. */
+export const resolveTrainingRecordVolumes = (agent) => (agent.value.training?.record?.volumes ?? []).map((id) => {
+    const context = `Training record.volumes for ${agent.id}`;
+    const resource = one((agent.value.workspaceResources ?? []).filter((entry) => entry.id === id), id, context);
+    if (resource.kind !== "volume")
+        return invalidTraining(`${context}: ${id} must be a volume`);
+    if (resource.feed)
+        return invalidTraining(`${context}: fed volume ${id} is recorded through its landing log`);
+    return resource;
+}).sort((left, right) => lexical(left.id, right.id));
+export const resolveTrainingResource = (plan, agent, id, context) => {
+    const resource = one((agent.value.workspaceResources ?? []).filter((entry) => entry.id === id), id, context);
+    return { resource, declaredBy: declaredId(plan, resource.scope.key) };
+};
+/** Uses compiler-resolved visibility, including shared banks and representative attachments. */
+export const resolveTrainingOverride = (plan, agent, section, id, context) => {
+    let declaredBy;
+    if (section === "resources") {
+        declaredBy = resolveTrainingResource(plan, agent, id, context).declaredBy;
+    }
+    else if (section === "memory") {
+        // Multiple member slots can expose the same bank. They are one item, not ambiguity.
+        const sources = [...new Set((agent.value.memoryAccess ?? [])
+                .filter((entry) => entry.bank.id === id).map((entry) => entry.source))];
+        declaredBy = declaredId(plan, one(sources, id, context));
+    }
+    else {
+        const attachedSources = new Set();
+        for (const attachment of agent.value.surfaces?.moltnet ?? []) {
+            if (attachment.network !== id)
+                continue;
+            if (attachment.teamSource)
+                attachedSources.add(attachment.teamSource);
+            for (const source of Object.keys(attachment.contextRooms ?? {}))
+                attachedSources.add(source);
+        }
+        const matches = plan.nodes.filter((node) => node.value.kind === "team"
+            && attachedSources.has(node.value.source)
+            && node.value.networks?.some((network) => network.id === id));
+        declaredBy = one(matches, id, context).id;
+    }
+    return { section, id, declaredBy };
+};

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

@@ -0,0 +1,4 @@
+import { type TrainingPlan } from "./contract.js";
+import type { LoadedTrainingProject } from "./types.js";
+/** Pure projection over loaded facts: no filesystem, clock, execution, or mutation. */
+export declare const resolveTrainingPlan: (project: LoadedTrainingProject, agentId: string | undefined, producerVersion: string) => TrainingPlan;

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

@@ -0,0 +1,73 @@
+import { selectTrainingAgent } from "../selection.js";
+import { TRAINING_PLAN_VERSION, trainingPlanSchema } from "./contract.js";
+import { invalidTraining, lexical, resolveTrainingRecordVolumes, resolveTrainingResource } from "./references.js";
+import { planGrader, resolveTrainingTarget, trainingAgents } from "./targets.js";
+const optimizerFor = (agent, hasTargets) => {
+    const optimizer = agent.value.training?.optimizer;
+    const required = ["method", "model", "variants", "keep"];
+    const missing = required.filter((key) => optimizer?.[key] === undefined);
+    if (optimizer?.budget?.rounds === undefined)
+        missing.push("budget.rounds");
+    if (missing.length > 0) {
+        if (hasTargets)
+            invalidTraining(`Training optimizer for ${agent.id} is missing fields: ${missing.join(", ")}`);
+        return null;
+    }
+    if (hasTargets && optimizer.keep > optimizer.variants) {
+        invalidTraining(`Training optimizer for ${agent.id} requires keep <= variants`);
+    }
+    return {
+        method: optimizer.method, model: optimizer.model, variants: optimizer.variants, keep: optimizer.keep,
+        budget: { rounds: optimizer.budget.rounds }
+    };
+};
+const recordFor = (project, agent) => {
+    const record = agent.value.training?.record;
+    if (record === undefined)
+        return null;
+    return {
+        keep: record.keep ?? null,
+        volumes: resolveTrainingRecordVolumes(agent).map(({ id }) => {
+            const context = `Training record.volumes for ${agent.id}`;
+            const { declaredBy } = resolveTrainingResource(project.compilePlan, agent, id, context);
+            return { id, declaredBy };
+        })
+    };
+};
+/** JSON key ordering is part of the deterministic public representation. */
+const sortKeys = (value) => {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).sort(([left], [right]) => lexical(left, right)).map(([key, item]) => [key, sortKeys(item)]));
+    return value;
+};
+/** Pure projection over loaded facts: no filesystem, clock, execution, or mutation. */
+export const resolveTrainingPlan = (project, agentId, producerVersion) => {
+    const agents = trainingAgents(project);
+    const selected = selectTrainingAgent(agents, agentId);
+    const graders = Object.entries(selected.value.training?.graders ?? {})
+        .map(([name, grader]) => planGrader(project, name, grader));
+    const targets = [];
+    for (const target of project.targets) {
+        const resolved = resolveTrainingTarget(project, target, selected.id);
+        if (!resolved)
+            continue;
+        targets.push(resolved.target);
+        graders.push(resolved.grader);
+    }
+    const uniqueGraders = [...new Map(graders.map((grader) => [JSON.stringify(sortKeys(grader)), grader])).values()];
+    uniqueGraders.sort((left, right) => lexical(`${left.name}:${left.declaredBy}:${left.path}`, `${right.name}:${right.declaredBy}:${right.path}`));
+    targets.sort((left, right) => lexical(JSON.stringify(sortKeys(left)), JSON.stringify(sortKeys(right))));
+    const plan = trainingPlanSchema.parse({
+        version: TRAINING_PLAN_VERSION,
+        producer: { package: "spawnfile", version: producerVersion },
+        project: { root: project.root, manifest: project.manifest },
+        agent: { id: selected.id, name: selected.value.name },
+        deadlines: { experiment_ms: 43_200_000, ...selected.value.training?.deadlines },
+        ...(selected.value.training?.preparation ? { preparation: selected.value.training.preparation } : {}),
+        record: recordFor(project, selected), optimizer: optimizerFor(selected, targets.length > 0),
+        graders: uniqueGraders, targets
+    });
+    return sortKeys(plan);
+};