@dailephd/my-dev-kit-lab 0.7.0 → 0.7.2

package/dist/src/evaluation/syntheticRepository/materialize.js

@@ -0,0 +1,170 @@
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { relativeWithinRoot, resolveWithinRoot } from "../../core/pathSafety.js";
+import { buildSyntheticEvaluationCase } from "./evaluationCase.js";
+import { SYNTHETIC_REPOSITORY_MANIFEST_FILE_NAME, SYNTHETIC_REPOSITORY_REPOSITORY_DIRECTORY, buildSyntheticRepositoryManifest, serializeSyntheticRepositoryManifest, } from "./manifest.js";
+import { verifySyntheticRepositoryMaterialization } from "./manifestVerification.js";
+import { renderSyntheticRepository } from "./renderRepository.js";
+import { SyntheticRepositoryRenderError } from "./renderShared.js";
+import { SyntheticRepositoryPlanningError } from "./types.js";
+import { verifySyntheticRepositoryPlan } from "./planning.js";
+/** Thrown for every materialization failure; `code` classifies it and `errors` carries bounded evidence. */
+export class SyntheticRepositoryMaterializationError extends Error {
+    code;
+    errors;
+    constructor(code, errors) {
+        super(`Synthetic repository materialization failed (${code}): ${errors.join("; ")}`);
+        this.name = "SyntheticRepositoryMaterializationError";
+        this.code = code;
+        this.errors = [...errors];
+    }
+}
+const STAGING_PREFIX = ".synthetic-staging-";
+function withinRealRoot(realRoot, candidate) {
+    try {
+        relativeWithinRoot(realRoot, realpathSync(candidate));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function exists(target) {
+    try {
+        lstatSync(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function describeExisting(caseDirectory, expectedManifestText) {
+    const stats = lstatSync(caseDirectory);
+    if (stats.isSymbolicLink() || !stats.isDirectory())
+        return { reusable: false, reasons: ["existing output child is not a plain directory."] };
+    const manifestPath = path.join(caseDirectory, SYNTHETIC_REPOSITORY_MANIFEST_FILE_NAME);
+    const repositoryRoot = path.join(caseDirectory, SYNTHETIC_REPOSITORY_REPOSITORY_DIRECTORY);
+    let manifestText;
+    try {
+        manifestText = readFileSync(manifestPath, "utf8");
+    }
+    catch {
+        return { reusable: false, reasons: ["existing output child has no readable synthetic manifest."] };
+    }
+    if (manifestText !== expectedManifestText) {
+        return { reusable: false, reasons: ["existing manifest differs from the manifest of the requested generation."] };
+    }
+    const repositoryStats = exists(repositoryRoot) ? lstatSync(repositoryRoot) : undefined;
+    if (!repositoryStats || repositoryStats.isSymbolicLink() || !repositoryStats.isDirectory()) {
+        return { reusable: false, reasons: ["existing repository directory is missing or not a plain directory."] };
+    }
+    const verification = verifySyntheticRepositoryMaterialization({ manifestPath, repositoryRoot });
+    if (!verification.ok)
+        return { reusable: false, reasons: verification.issues };
+    return { reusable: true };
+}
+/**
+ * Materializes a frozen Batch 1 plan below `outputRoot/<caseId>/` as `repository/` plus a sibling
+ * `synthetic-repository-manifest.json`. The plan is the single semantic source of truth: it is verified, never
+ * re-planned or repaired. A deterministic existing directory is reused only when its manifest and every file
+ * match the requested generation exactly; any other existing child is a collision. Writes go to an owned staging
+ * directory that is verified and then renamed into place; on failure only that staging directory is removed.
+ */
+export function materializeSyntheticRepository(plan, outputRoot, io = {}) {
+    try {
+        verifySyntheticRepositoryPlan(plan);
+    }
+    catch (error) {
+        if (error instanceof SyntheticRepositoryPlanningError)
+            throw new SyntheticRepositoryMaterializationError("invalid-plan", error.errors);
+        throw error;
+    }
+    let files;
+    try {
+        files = renderSyntheticRepository(plan);
+    }
+    catch (error) {
+        if (error instanceof SyntheticRepositoryRenderError)
+            throw new SyntheticRepositoryMaterializationError("render-failed", error.errors);
+        throw error;
+    }
+    const manifest = buildSyntheticRepositoryManifest(plan, files);
+    const manifestText = serializeSyntheticRepositoryManifest(manifest);
+    let realRoot;
+    try {
+        mkdirSync(path.resolve(outputRoot), { recursive: true });
+        realRoot = realpathSync(path.resolve(outputRoot));
+    }
+    catch (error) {
+        throw new SyntheticRepositoryMaterializationError("io-failure", [`output root is not usable: ${error instanceof Error ? error.message : String(error)}`]);
+    }
+    let caseDirectory;
+    try {
+        caseDirectory = resolveWithinRoot(realRoot, plan.caseId);
+    }
+    catch (error) {
+        throw new SyntheticRepositoryMaterializationError("path-escape", [error instanceof Error ? error.message : String(error)]);
+    }
+    const result = (reused) => {
+        const repositoryRoot = path.join(caseDirectory, SYNTHETIC_REPOSITORY_REPOSITORY_DIRECTORY);
+        return {
+            plan,
+            manifest,
+            manifestPath: path.join(caseDirectory, SYNTHETIC_REPOSITORY_MANIFEST_FILE_NAME),
+            repositoryRoot,
+            evaluationCase: buildSyntheticEvaluationCase(plan, manifest, repositoryRoot),
+            reusedExistingMaterialization: reused,
+        };
+    };
+    if (exists(caseDirectory)) {
+        if (!withinRealRoot(realRoot, caseDirectory)) {
+            throw new SyntheticRepositoryMaterializationError("path-escape", ["existing output child resolves outside the output root."]);
+        }
+        const existing = describeExisting(caseDirectory, manifestText);
+        if (!existing.reusable) {
+            throw new SyntheticRepositoryMaterializationError("collision", [
+                `output child ${plan.caseId} already exists and is not an exact materialization of this generation; nothing was changed.`,
+                ...existing.reasons,
+            ]);
+        }
+        return result(true);
+    }
+    const writeFile = io.writeFile ?? ((absolutePath, bytes) => writeFileSync(absolutePath, bytes, { flag: "wx" }));
+    let staging;
+    try {
+        staging = mkdtempSync(path.join(realRoot, STAGING_PREFIX));
+        if (!withinRealRoot(realRoot, staging))
+            throw new SyntheticRepositoryMaterializationError("path-escape", ["staging directory resolves outside the output root."]);
+        const stagedRepository = path.join(staging, SYNTHETIC_REPOSITORY_REPOSITORY_DIRECTORY);
+        mkdirSync(stagedRepository);
+        for (const file of files) {
+            let target;
+            try {
+                target = resolveWithinRoot(stagedRepository, file.path);
+            }
+            catch (error) {
+                throw new SyntheticRepositoryMaterializationError("path-escape", [error instanceof Error ? error.message : String(error)]);
+            }
+            mkdirSync(path.dirname(target), { recursive: true });
+            writeFile(target, Buffer.from(file.content, "utf8"));
+        }
+        const stagedManifest = path.join(staging, SYNTHETIC_REPOSITORY_MANIFEST_FILE_NAME);
+        writeFile(stagedManifest, Buffer.from(manifestText, "utf8"));
+        const verification = verifySyntheticRepositoryMaterialization({ manifestPath: stagedManifest, repositoryRoot: stagedRepository });
+        if (!verification.ok)
+            throw new SyntheticRepositoryMaterializationError("io-failure", ["staged files failed manifest verification.", ...verification.issues]);
+        if (exists(caseDirectory)) {
+            throw new SyntheticRepositoryMaterializationError("collision", [`output child ${plan.caseId} appeared during materialization; nothing was overwritten.`]);
+        }
+        renameSync(staging, caseDirectory);
+        staging = undefined;
+    }
+    catch (error) {
+        if (staging !== undefined)
+            rmSync(staging, { recursive: true, force: true });
+        if (error instanceof SyntheticRepositoryMaterializationError)
+            throw error;
+        throw new SyntheticRepositoryMaterializationError("io-failure", [error instanceof Error ? error.message : String(error)]);
+    }
+    return result(false);
+}

package/dist/src/evaluation/syntheticRepository/planning.js

@@ -0,0 +1,479 @@
+import { normalizeSyntheticRepositoryConfig, validateSyntheticRepositoryCaseSpec } from "./config.js";
+import { computeSyntheticRepositoryCaseIdentity } from "./identity.js";
+import { createSyntheticRepositoryPrng } from "./prng.js";
+import { planTopology } from "./topology.js";
+import { SYNTHETIC_REPOSITORY_IDENTITY_ALGORITHM_VERSION, SYNTHETIC_REPOSITORY_PATTERN_ROLES, SYNTHETIC_REPOSITORY_PLAN_SCHEMA_ID, SYNTHETIC_REPOSITORY_PLAN_SCHEMA_VERSION, SYNTHETIC_REPOSITORY_PRNG_VERSION, SyntheticRepositoryConfigError, SyntheticRepositoryPlanningError, } from "./types.js";
+const REQUIRED_FACT_WEIGHT = 2;
+const OPTIONAL_FACT_WEIGHT = 1;
+const MAX_TASK_SYMBOLS_PER_MODULE = 3;
+const BROAD_CHANGE_MODULE_COUNT = 4;
+const SAFE_PLANNED_PATH_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_.-]*(\/[A-Za-z0-9_][A-Za-z0-9_.-]*)*$/;
+function pad(value, width) {
+    return String(value).padStart(width, "0");
+}
+function requestedDimensions(spec) {
+    return {
+        sourceFileCount: spec.sourceFileCount,
+        moduleDepth: spec.moduleDepth,
+        internalImportCount: spec.internalImportCount,
+        symbolCount: spec.symbolCount,
+        testFileCount: spec.testFileCount,
+        repeatedPatternCount: spec.repeatedPatternCount,
+        taskLocality: spec.taskLocality,
+    };
+}
+function planModules(spec, levelOfModule, prng) {
+    const moduleCount = spec.sourceFileCount;
+    const extension = spec.language === "typescript" ? ".ts" : ".py";
+    const symbolCounts = new Array(moduleCount).fill(1);
+    for (let extra = moduleCount; extra < spec.symbolCount; extra += 1) {
+        symbolCounts[prng.nextInt(moduleCount)] += 1;
+    }
+    const modules = [];
+    const symbols = [];
+    const symbolsByModule = [];
+    let ordinal = 0;
+    for (let index = 0; index < moduleCount; index += 1) {
+        const moduleId = `mod_${pad(index + 1, 5)}`;
+        const own = [];
+        for (let count = 0; count < symbolCounts[index]; count += 1) {
+            ordinal += 1;
+            const name = `sym_${pad(ordinal, 6)}`;
+            own.push({ symbolId: `${moduleId}#${name}`, name, ordinal, moduleId });
+        }
+        symbols.push(...own);
+        symbolsByModule.push(own);
+        modules.push({
+            moduleId,
+            index,
+            level: levelOfModule[index],
+            path: `src/group_${pad(Math.floor(index / 100) + 1, 3)}/${moduleId}${extension}`,
+            symbolIds: own.map((symbol) => symbol.symbolId),
+        });
+    }
+    return { modules, symbols, symbolsByModule };
+}
+function pickConsecutiveSymbols(own, maxCount, prng) {
+    const count = 1 + prng.nextInt(Math.min(maxCount, own.length));
+    const start = prng.nextInt(own.length);
+    const indices = new Set();
+    for (let offset = 0; offset < count; offset += 1)
+        indices.add((start + offset) % own.length);
+    return [...indices].sort((left, right) => left - right).map((index) => own[index]);
+}
+function planTestFiles(spec, modules, symbolsByModule, prng) {
+    if (spec.testFileCount === 0)
+        return [];
+    const suffix = spec.language === "typescript" ? ".test.ts" : ".py";
+    const order = prng.shuffle(Array.from({ length: modules.length }, (_, index) => index));
+    const tests = [];
+    for (let position = 0; position < spec.testFileCount; position += 1) {
+        const target = order[position % modules.length];
+        const testId = `test_${pad(position + 1, 5)}`;
+        tests.push({
+            testId,
+            path: `tests/${testId}${suffix}`,
+            targetModuleId: modules[target].moduleId,
+            targetSymbolIds: pickConsecutiveSymbols(symbolsByModule[target], MAX_TASK_SYMBOLS_PER_MODULE, prng).map((symbol) => symbol.symbolId),
+        });
+    }
+    return tests;
+}
+function planRepeatedPatterns(spec, modules, prng) {
+    const patterns = [];
+    for (let position = 0; position < spec.repeatedPatternCount; position += 1) {
+        const target = prng.nextInt(modules.length);
+        const role = SYNTHETIC_REPOSITORY_PATTERN_ROLES[prng.nextInt(SYNTHETIC_REPOSITORY_PATTERN_ROLES.length)];
+        patterns.push({
+            patternId: `pattern_${pad(position + 1, 6)}`,
+            ordinal: position + 1,
+            role,
+            targetModuleId: modules[target].moduleId,
+        });
+    }
+    return patterns;
+}
+function planTask(spec, modules, symbolsByModule, edges, tests, prng) {
+    const taskId = `${spec.id}-task`;
+    const moduleIndexById = new Map(modules.map((module) => [module.moduleId, module.index]));
+    if (spec.taskLocality === "localized") {
+        const owner = prng.nextInt(modules.length);
+        const symbols = pickConsecutiveSymbols(symbolsByModule[owner], MAX_TASK_SYMBOLS_PER_MODULE, prng);
+        const symbolIds = symbols.map((symbol) => symbol.symbolId);
+        return {
+            taskId,
+            locality: "localized",
+            ownerModuleIds: [modules[owner].moduleId],
+            symbolIds,
+            relationEdge: null,
+            associatedTestIds: tests.filter((test) => test.targetModuleId === modules[owner].moduleId).map((test) => test.testId),
+            queryPlan: { kind: "locate-symbols", subjectSymbolIds: symbolIds },
+        };
+    }
+    let selected;
+    let relationEdge = null;
+    if (spec.taskLocality === "cross-module") {
+        if (edges.length === 0 || modules.length < 2) {
+            throw new SyntheticRepositoryPlanningError(["cross-module task requires at least two modules and one import edge."]);
+        }
+        relationEdge = edges[prng.nextInt(edges.length)];
+        selected = [moduleIndexById.get(relationEdge.from), moduleIndexById.get(relationEdge.to)];
+    }
+    else {
+        if (modules.length < BROAD_CHANGE_MODULE_COUNT) {
+            throw new SyntheticRepositoryPlanningError(["broad-change task requires at least four modules."]);
+        }
+        selected = [];
+        for (let stratum = 0; stratum < BROAD_CHANGE_MODULE_COUNT; stratum += 1) {
+            const low = Math.floor((stratum * modules.length) / BROAD_CHANGE_MODULE_COUNT);
+            const high = Math.floor(((stratum + 1) * modules.length) / BROAD_CHANGE_MODULE_COUNT);
+            selected.push(low + prng.nextInt(high - low));
+        }
+    }
+    selected.sort((left, right) => left - right);
+    const symbolIds = selected.map((index) => {
+        const own = symbolsByModule[index];
+        return own[prng.nextInt(own.length)].symbolId;
+    });
+    return {
+        taskId,
+        locality: spec.taskLocality,
+        ownerModuleIds: selected.map((index) => modules[index].moduleId),
+        symbolIds,
+        relationEdge,
+        associatedTestIds: [],
+        queryPlan: {
+            kind: spec.taskLocality === "cross-module" ? "trace-import" : "broad-change-survey",
+            subjectSymbolIds: symbolIds,
+        },
+    };
+}
+function planAnswerKey(task, modules, symbols) {
+    const moduleById = new Map(modules.map((module) => [module.moduleId, module]));
+    const symbolById = new Map(symbols.map((symbol) => [symbol.symbolId, symbol]));
+    const taskSymbols = task.symbolIds.map((symbolId) => symbolById.get(symbolId));
+    const facts = [];
+    const addFact = (fact) => {
+        facts.push({
+            factId: `fact_${pad(facts.length + 1, 3)}`,
+            weight: fact.required ? REQUIRED_FACT_WEIGHT : OPTIONAL_FACT_WEIGHT,
+            ...fact,
+        });
+    };
+    for (const symbol of taskSymbols) {
+        addFact({ role: "symbol-definition", required: true, symbolIds: [symbol.symbolId], edge: null, testId: null });
+    }
+    if (task.relationEdge) {
+        addFact({ role: "import-relation", required: true, symbolIds: [], edge: task.relationEdge, testId: null });
+    }
+    for (const testId of task.associatedTestIds) {
+        addFact({ role: "associated-test", required: false, symbolIds: [], edge: null, testId });
+    }
+    return {
+        expectedFiles: task.ownerModuleIds.map((moduleId) => moduleById.get(moduleId).path),
+        expectedSymbols: taskSymbols.map((symbol) => symbol.name),
+        expectedSymbolIds: [...task.symbolIds],
+        facts,
+        minimumCorrectFacts: facts.filter((fact) => fact.required).length,
+        expectedContextTargets: task.ownerModuleIds.map((moduleId) => ({
+            file: moduleById.get(moduleId).path,
+            symbols: taskSymbols.filter((symbol) => symbol.moduleId === moduleId).map((symbol) => symbol.name),
+            required: true,
+        })),
+    };
+}
+/** Broad-change stratum boundaries: stratum s starts at floor(s * moduleCount / 4). */
+function stratumOf(moduleIndex, moduleCount) {
+    for (let stratum = BROAD_CHANGE_MODULE_COUNT - 1; stratum > 0; stratum -= 1) {
+        if (moduleIndex >= Math.floor((stratum * moduleCount) / BROAD_CHANGE_MODULE_COUNT))
+            return stratum;
+    }
+    return 0;
+}
+function classifyLocality(ownerCount) {
+    if (ownerCount === 1)
+        return "localized";
+    if (ownerCount >= BROAD_CHANGE_MODULE_COUNT)
+        return "broad-change";
+    if (ownerCount >= 2)
+        return "cross-module";
+    return undefined;
+}
+/**
+ * Recomputes every measurable dimension of a plan from its own arrays and checks reference integrity, path
+ * safety, graph shape, locality semantics and answer-key satisfiability. Returns what was found; never throws.
+ */
+function inspectPlan(plan) {
+    const errors = [];
+    const moduleCount = plan.modules.length;
+    const moduleIndexById = new Map();
+    plan.modules.forEach((module, index) => {
+        if (moduleIndexById.has(module.moduleId))
+            errors.push(`duplicate module id ${module.moduleId}.`);
+        moduleIndexById.set(module.moduleId, index);
+        if (module.index !== index)
+            errors.push(`module ${module.moduleId} index ${module.index} does not match its position ${index}.`);
+    });
+    const seenPaths = new Set();
+    for (const path of [...plan.modules.map((module) => module.path), ...plan.testFiles.map((test) => test.path)]) {
+        if (!SAFE_PLANNED_PATH_PATTERN.test(path))
+            errors.push(`unsafe planned path ${JSON.stringify(path)}.`);
+        if (seenPaths.has(path))
+            errors.push(`duplicate planned path ${path}.`);
+        seenPaths.add(path);
+    }
+    const symbolById = new Map();
+    const symbolNames = new Set();
+    const symbolsPerModule = new Map();
+    for (const symbol of plan.symbols) {
+        if (symbolById.has(symbol.symbolId))
+            errors.push(`duplicate symbol id ${symbol.symbolId}.`);
+        if (symbolNames.has(symbol.name))
+            errors.push(`duplicate symbol name ${symbol.name}.`);
+        symbolById.set(symbol.symbolId, symbol);
+        symbolNames.add(symbol.name);
+        if (!moduleIndexById.has(symbol.moduleId)) {
+            errors.push(`symbol ${symbol.symbolId} references missing module ${symbol.moduleId}.`);
+            continue;
+        }
+        const list = symbolsPerModule.get(symbol.moduleId) ?? [];
+        list.push(symbol.symbolId);
+        symbolsPerModule.set(symbol.moduleId, list);
+    }
+    for (const module of plan.modules) {
+        const owned = symbolsPerModule.get(module.moduleId) ?? [];
+        if (owned.length === 0)
+            errors.push(`module ${module.moduleId} owns no symbol.`);
+        if (owned.length !== module.symbolIds.length || owned.some((symbolId, index) => symbolId !== module.symbolIds[index])) {
+            errors.push(`module ${module.moduleId} symbolIds do not match the symbols that reference it.`);
+        }
+    }
+    const adjacency = Array.from({ length: moduleCount }, () => []);
+    const indegree = new Array(moduleCount).fill(0);
+    const edgeKeys = new Set();
+    for (const edge of plan.importEdges) {
+        const from = moduleIndexById.get(edge.from);
+        const to = moduleIndexById.get(edge.to);
+        if (from === undefined || to === undefined) {
+            errors.push(`edge ${edge.from} -> ${edge.to} references a missing module.`);
+            continue;
+        }
+        if (from === to)
+            errors.push(`self edge on ${edge.from}.`);
+        const key = `${edge.from}>${edge.to}`;
+        if (edgeKeys.has(key))
+            errors.push(`duplicate edge ${edge.from} -> ${edge.to}.`);
+        edgeKeys.add(key);
+        adjacency[from].push(to);
+        indegree[to] += 1;
+    }
+    // Longest chain (in modules) via Kahn's algorithm; a short count means the graph has a cycle.
+    const chainLength = new Array(moduleCount).fill(1);
+    const queue = [];
+    for (let index = 0; index < moduleCount; index += 1)
+        if (indegree[index] === 0)
+            queue.push(index);
+    let processed = 0;
+    let moduleDepth = 0;
+    for (let head = 0; head < queue.length; head += 1) {
+        const current = queue[head];
+        processed += 1;
+        moduleDepth = Math.max(moduleDepth, chainLength[current]);
+        for (const next of adjacency[current]) {
+            chainLength[next] = Math.max(chainLength[next], chainLength[current] + 1);
+            indegree[next] -= 1;
+            if (indegree[next] === 0)
+                queue.push(next);
+        }
+    }
+    if (processed < moduleCount)
+        errors.push("import graph contains a cycle.");
+    const testIds = new Set();
+    for (const test of plan.testFiles) {
+        if (testIds.has(test.testId))
+            errors.push(`duplicate test id ${test.testId}.`);
+        testIds.add(test.testId);
+        if (!moduleIndexById.has(test.targetModuleId))
+            errors.push(`test ${test.testId} targets missing module ${test.targetModuleId}.`);
+        if (test.targetSymbolIds.length === 0)
+            errors.push(`test ${test.testId} references no symbol.`);
+        for (const symbolId of test.targetSymbolIds) {
+            if (symbolById.get(symbolId)?.moduleId !== test.targetModuleId) {
+                errors.push(`test ${test.testId} references symbol ${symbolId} that is not owned by ${test.targetModuleId}.`);
+            }
+        }
+    }
+    const patternIds = new Set();
+    for (const pattern of plan.repeatedPatterns) {
+        if (patternIds.has(pattern.patternId))
+            errors.push(`duplicate pattern id ${pattern.patternId}.`);
+        patternIds.add(pattern.patternId);
+        if (!moduleIndexById.has(pattern.targetModuleId)) {
+            errors.push(`pattern ${pattern.patternId} targets missing module ${pattern.targetModuleId}.`);
+        }
+        if (!SYNTHETIC_REPOSITORY_PATTERN_ROLES.includes(pattern.role)) {
+            errors.push(`pattern ${pattern.patternId} has unknown role ${pattern.role}.`);
+        }
+    }
+    const { task, answerKey } = plan;
+    const ownerSet = new Set(task.ownerModuleIds);
+    if (ownerSet.size !== task.ownerModuleIds.length)
+        errors.push("task owner modules are not unique.");
+    const symbolOwners = new Set();
+    for (const symbolId of task.symbolIds) {
+        const symbol = symbolById.get(symbolId);
+        if (!symbol) {
+            errors.push(`task references missing symbol ${symbolId}.`);
+            continue;
+        }
+        symbolOwners.add(symbol.moduleId);
+        if (!ownerSet.has(symbol.moduleId))
+            errors.push(`task symbol ${symbolId} is outside the task owner modules.`);
+    }
+    for (const owner of task.ownerModuleIds) {
+        if (!moduleIndexById.has(owner))
+            errors.push(`task owner ${owner} is missing from the plan.`);
+        if (!symbolOwners.has(owner))
+            errors.push(`task owner ${owner} has no task symbol.`);
+    }
+    let taskLocality = classifyLocality(symbolOwners.size);
+    if (taskLocality === undefined) {
+        errors.push("task spans no source module.");
+        taskLocality = task.locality;
+    }
+    if (task.locality !== taskLocality) {
+        errors.push(`task locality ${task.locality} does not match its structure (${taskLocality}).`);
+    }
+    if (taskLocality === "cross-module") {
+        const relation = task.relationEdge;
+        if (!relation || !edgeKeys.has(`${relation.from}>${relation.to}`) || !ownerSet.has(relation.from) || !ownerSet.has(relation.to)) {
+            errors.push("cross-module task owners are not connected by a planned import edge.");
+        }
+    }
+    if (taskLocality === "broad-change") {
+        const strata = new Set(task.ownerModuleIds.map((owner) => stratumOf(moduleIndexById.get(owner) ?? 0, moduleCount)));
+        if (strata.size < BROAD_CHANGE_MODULE_COUNT)
+            errors.push("broad-change task owners are not spread over four module strata.");
+    }
+    for (const testId of task.associatedTestIds) {
+        const test = plan.testFiles.find((candidate) => candidate.testId === testId);
+        if (!test || !ownerSet.has(test.targetModuleId))
+            errors.push(`task associated test ${testId} does not resolve to a task owner.`);
+    }
+    const modulePathById = new Map(plan.modules.map((module) => [module.moduleId, module.path]));
+    const expectedFiles = task.ownerModuleIds.map((owner) => modulePathById.get(owner));
+    if (answerKey.expectedFiles.length === 0 || answerKey.expectedFiles.join("\n") !== expectedFiles.join("\n")) {
+        errors.push("answer key expectedFiles do not match the task owner modules.");
+    }
+    const expectedNames = task.symbolIds.map((symbolId) => symbolById.get(symbolId)?.name);
+    if (answerKey.expectedSymbols.length === 0 || answerKey.expectedSymbols.join("\n") !== expectedNames.join("\n")) {
+        errors.push("answer key expectedSymbols do not match the task symbols.");
+    }
+    if (answerKey.expectedSymbolIds.join("\n") !== task.symbolIds.join("\n")) {
+        errors.push("answer key expectedSymbolIds do not match the task symbols.");
+    }
+    for (const target of answerKey.expectedContextTargets) {
+        if (!seenPaths.has(target.file))
+            errors.push(`context target file ${target.file} is not planned.`);
+        for (const name of target.symbols)
+            if (!symbolNames.has(name))
+                errors.push(`context target symbol ${name} is not planned.`);
+    }
+    const factIds = new Set();
+    let requiredFacts = 0;
+    for (const fact of answerKey.facts) {
+        if (factIds.has(fact.factId))
+            errors.push(`duplicate fact id ${fact.factId}.`);
+        factIds.add(fact.factId);
+        if (!(fact.weight > 0))
+            errors.push(`fact ${fact.factId} must have a positive weight.`);
+        if (fact.required)
+            requiredFacts += 1;
+        for (const symbolId of fact.symbolIds) {
+            if (!task.symbolIds.includes(symbolId))
+                errors.push(`fact ${fact.factId} references symbol ${symbolId} outside the task.`);
+        }
+        if (fact.edge && !edgeKeys.has(`${fact.edge.from}>${fact.edge.to}`))
+            errors.push(`fact ${fact.factId} references a missing edge.`);
+        if (fact.testId !== null && !testIds.has(fact.testId))
+            errors.push(`fact ${fact.factId} references missing test ${fact.testId}.`);
+    }
+    if (!Number.isInteger(answerKey.minimumCorrectFacts) ||
+        answerKey.minimumCorrectFacts < 1 ||
+        answerKey.minimumCorrectFacts > requiredFacts) {
+        errors.push("answer key minimumCorrectFacts is not satisfiable by the required facts.");
+    }
+    return {
+        errors,
+        realized: {
+            sourceFileCount: moduleCount,
+            moduleDepth,
+            internalImportCount: plan.importEdges.length,
+            symbolCount: plan.symbols.length,
+            testFileCount: plan.testFiles.length,
+            repeatedPatternCount: plan.repeatedPatterns.length,
+            taskLocality,
+        },
+    };
+}
+/** Verifies a plan against its own structure and its requested dimensions; throws on any mismatch. */
+export function verifySyntheticRepositoryPlan(plan) {
+    const { realized, errors } = inspectPlan(plan);
+    for (const key of Object.keys(plan.requested)) {
+        if (plan.requested[key] !== realized[key]) {
+            errors.push(`realized ${key} ${String(realized[key])} does not equal requested ${String(plan.requested[key])}.`);
+        }
+        if (plan.realized[key] !== realized[key]) {
+            errors.push(`recorded realized ${key} ${String(plan.realized[key])} does not match the plan (${String(realized[key])}).`);
+        }
+    }
+    if (errors.length > 0)
+        throw new SyntheticRepositoryPlanningError(errors);
+    return realized;
+}
+/** Plans one repository. Re-validates the case, never repairs, and never returns a partial plan. */
+export function planSyntheticRepositoryCase(input) {
+    const validation = validateSyntheticRepositoryCaseSpec(input);
+    if (!validation.ok)
+        throw new SyntheticRepositoryConfigError(validation.errors);
+    const spec = validation.spec;
+    const generationIdentity = computeSyntheticRepositoryCaseIdentity(spec);
+    const prng = createSyntheticRepositoryPrng(generationIdentity);
+    const topology = planTopology(spec, prng);
+    const { modules, symbols, symbolsByModule } = planModules(spec, topology.levelOfModule, prng);
+    const importEdges = topology.edges.map(([from, to]) => ({
+        from: modules[from].moduleId,
+        to: modules[to].moduleId,
+    }));
+    const testFiles = planTestFiles(spec, modules, symbolsByModule, prng);
+    const repeatedPatterns = planRepeatedPatterns(spec, modules, prng);
+    const task = planTask(spec, modules, symbolsByModule, importEdges, testFiles, prng);
+    const answerKey = planAnswerKey(task, modules, symbols);
+    const requested = requestedDimensions(spec);
+    const plan = {
+        schemaId: SYNTHETIC_REPOSITORY_PLAN_SCHEMA_ID,
+        schemaVersion: SYNTHETIC_REPOSITORY_PLAN_SCHEMA_VERSION,
+        prngVersion: SYNTHETIC_REPOSITORY_PRNG_VERSION,
+        identityAlgorithmVersion: SYNTHETIC_REPOSITORY_IDENTITY_ALGORITHM_VERSION,
+        caseId: spec.id,
+        generationIdentity,
+        language: spec.language,
+        logicalProjectId: `synthetic-${spec.id}`,
+        requested,
+        realized: requested,
+        modules,
+        symbols,
+        importEdges,
+        testFiles,
+        repeatedPatterns,
+        task,
+        answerKey,
+    };
+    plan.realized = inspectPlan(plan).realized;
+    verifySyntheticRepositoryPlan(plan);
+    return plan;
+}
+/** Normalizes a configuration (throwing on invalid input) and plans every case in canonical id order. */
+export function planSyntheticRepositories(input) {
+    return normalizeSyntheticRepositoryConfig(input).cases.map((spec) => planSyntheticRepositoryCase(spec));
+}