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

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

@@ -0,0 +1,16 @@
+export * from "./types.js";
+export { SYNTHETIC_REPOSITORY_CASE_FIELDS, SYNTHETIC_REPOSITORY_LIMITS, compareCodeUnits, maxImportEdges, normalizeSyntheticRepositoryConfig, validateSyntheticRepositoryCaseSpec, validateSyntheticRepositoryConfig, } from "./config.js";
+export { canonicalSyntheticRepositoryCaseText, canonicalSyntheticRepositoryConfigText, computeSyntheticRepositoryCaseIdentity, computeSyntheticRepositoryConfigIdentity, } from "./identity.js";
+export { createSyntheticRepositoryPrng, syntheticRepositoryPrngInitialState } from "./prng.js";
+export { planTopology } from "./topology.js";
+export { planSyntheticRepositories, planSyntheticRepositoryCase, verifySyntheticRepositoryPlan } from "./planning.js";
+export { SyntheticRepositoryRenderError } from "./renderShared.js";
+export { renderTypeScriptRepository } from "./renderTypeScript.js";
+export { pythonModuleName, renderPythonRepository } from "./renderPython.js";
+export { renderSyntheticRepository } from "./renderRepository.js";
+export { inspectRepositoryFiles } from "./inspection.js";
+export { deriveSyntheticRepositoryLayout, describeSyntheticTask } from "./layout.js";
+export { SYNTHETIC_REPOSITORY_MANIFEST_FILE_NAME, SYNTHETIC_REPOSITORY_MANIFEST_SCHEMA_ID, SYNTHETIC_REPOSITORY_MANIFEST_SCHEMA_VERSION, SYNTHETIC_REPOSITORY_REPOSITORY_DIRECTORY, buildSyntheticRepositoryManifest, computeRepositoryContentIdentity, serializeSyntheticRepositoryManifest, validateSyntheticRepositoryManifest, } from "./manifest.js";
+export { verifySyntheticRepositoryMaterialization } from "./manifestVerification.js";
+export { buildSyntheticAnswerKey, buildSyntheticEvaluationCase } from "./evaluationCase.js";
+export { SyntheticRepositoryMaterializationError, materializeSyntheticRepository } from "./materialize.js";

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

@@ -0,0 +1,92 @@
+import path from "node:path";
+import { REPEATED_PATTERN_MARKER } from "./renderShared.js";
+import { pythonModuleName } from "./renderPython.js";
+const TS_SYMBOL = /^export function (sym_\d+)\(/gm;
+const PY_SYMBOL = /^def (sym_\d+)\(/gm;
+const TS_IMPORT = /^import \{ (sym_\d+) \} from "([^"]+)";$/gm;
+const PY_IMPORT = /^from ([A-Za-z0-9_.]+) import (sym_\d+)$/gm;
+const PATTERN = new RegExp(`${REPEATED_PATTERN_MARKER} (pattern_\\d+) `, "g");
+function matchAll(pattern, text) {
+    return [...text.matchAll(new RegExp(pattern.source, pattern.flags))];
+}
+/**
+ * Measures a generated repository from its file bytes alone (no plan): file roles, `sym_` definitions,
+ * resolved internal imports, repeated-pattern markers and the longest dependency chain. The verifier and the
+ * renderer self-check use it so requested dimensions are compared with what the files really contain.
+ */
+export function inspectRepositoryFiles(language, files) {
+    const issues = [];
+    const sources = files.filter((file) => file.role === "source");
+    const tests = files.filter((file) => file.role === "test");
+    const sourcePaths = new Set(sources.map((file) => file.path));
+    const pathByModuleName = new Map();
+    if (language === "python") {
+        for (const source of sources)
+            pathByModuleName.set(pythonModuleName(source.path), source.path);
+    }
+    const symbolNames = [];
+    let patterns = 0;
+    const edges = new Set();
+    const outgoing = new Map(sources.map((file) => [file.path, []]));
+    for (const source of sources) {
+        for (const match of matchAll(language === "typescript" ? TS_SYMBOL : PY_SYMBOL, source.content))
+            symbolNames.push(match[1]);
+        patterns += matchAll(PATTERN, source.content).length;
+        for (const match of matchAll(language === "typescript" ? TS_IMPORT : PY_IMPORT, source.content)) {
+            const target = language === "typescript"
+                ? path.posix.join(path.posix.dirname(source.path), match[2]).replace(/\.js$/, ".ts")
+                : pathByModuleName.get(match[1]);
+            if (target === undefined || !sourcePaths.has(target)) {
+                issues.push(`${source.path}: import ${JSON.stringify(match[0])} does not resolve to a source module.`);
+                continue;
+            }
+            if (target === source.path)
+                issues.push(`${source.path}: imports itself.`);
+            const key = `${source.path} -> ${target}`;
+            if (edges.has(key))
+                issues.push(`${source.path}: duplicate import of ${target}.`);
+            edges.add(key);
+            outgoing.get(source.path)?.push(target);
+        }
+    }
+    for (const other of [...tests, ...files.filter((file) => file.role === "support")]) {
+        if (matchAll(PATTERN, other.content).length > 0)
+            issues.push(`${other.path}: ${other.role} file contains a repeated-pattern marker.`);
+    }
+    if (new Set(symbolNames).size !== symbolNames.length)
+        issues.push("duplicate sym_ definition names.");
+    const longest = new Map();
+    const visiting = new Set();
+    const visit = (node) => {
+        const known = longest.get(node);
+        if (known !== undefined)
+            return known;
+        if (visiting.has(node)) {
+            issues.push("import graph contains a cycle.");
+            return 0;
+        }
+        visiting.add(node);
+        let best = 1;
+        for (const next of outgoing.get(node) ?? [])
+            best = Math.max(best, 1 + visit(next));
+        visiting.delete(node);
+        longest.set(node, best);
+        return best;
+    };
+    let moduleDepth = 0;
+    for (const source of sources)
+        moduleDepth = Math.max(moduleDepth, visit(source.path));
+    return {
+        dimensions: {
+            sourceFileCount: sources.length,
+            moduleDepth,
+            internalImportCount: edges.size,
+            symbolCount: symbolNames.length,
+            testFileCount: tests.length,
+            repeatedPatternCount: patterns,
+        },
+        importEdges: [...edges].sort(),
+        symbolNames,
+        issues,
+    };
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Pure derivation of the generated repository layout from a plan. Globs list only roots that exist: the
+ * existing glob collector fails when a glob base directory is missing, so `tests/` appears only when the
+ * plan has test files. Support files (package.json, tsconfig.json, pyproject.toml) match no glob.
+ */
+export function deriveSyntheticRepositoryLayout(plan) {
+    const hasTests = plan.requested.testFileCount > 0;
+    const sourceGlob = plan.language === "typescript" ? "src/**/*.ts" : "src/**/*.py";
+    return {
+        logicalTargetRoot: `synthetic/${plan.caseId}/repository`,
+        sourceRoots: hasTests ? ["src", "tests"] : ["src"],
+        testRoots: hasTests ? ["tests"] : [],
+        rawIncludeGlobs: hasTests ? [sourceGlob, "tests/**/*"] : [sourceGlob],
+    };
+}
+function describeFact(fact, moduleById, symbolById, testPathById) {
+    if (fact.role === "symbol-definition") {
+        const symbol = symbolById.get(fact.symbolIds[0]);
+        return `${symbol.name} is defined in ${moduleById.get(symbol.moduleId).path}.`;
+    }
+    if (fact.role === "import-relation") {
+        const edge = fact.edge;
+        return `${moduleById.get(edge.from).path} imports ${moduleById.get(edge.to).path}.`;
+    }
+    return `${testPathById.get(fact.testId)} exercises code in the task module.`;
+}
+/** Deterministic task title, query and fact prose from the plan's task and answer-key plan. */
+export function describeSyntheticTask(plan) {
+    const moduleById = new Map(plan.modules.map((module) => [module.moduleId, module]));
+    const symbolById = new Map(plan.symbols.map((symbol) => [symbol.symbolId, symbol]));
+    const testPathById = new Map(plan.testFiles.map((test) => [test.testId, test.path]));
+    const names = plan.answerKey.expectedSymbols.join(", ");
+    const pathOf = (moduleId) => moduleById.get(moduleId).path;
+    let query;
+    if (plan.task.queryPlan.kind === "locate-symbols") {
+        query = `Locate the source file that defines the symbols ${names}.`;
+    }
+    else if (plan.task.queryPlan.kind === "trace-import") {
+        const edge = plan.task.relationEdge;
+        query = `Trace how ${pathOf(edge.from)} depends on ${pathOf(edge.to)} and identify the symbols ${names}.`;
+    }
+    else {
+        query = `Survey the repository and list the files and symbols (${names}) involved in a change that spans ${plan.task.ownerModuleIds.length} separate modules.`;
+    }
+    return {
+        title: `Synthetic ${plan.task.locality} task for ${plan.caseId}`,
+        query,
+        factTextById: new Map(plan.answerKey.facts.map((fact) => [fact.factId, describeFact(fact, moduleById, symbolById, testPathById)])),
+    };
+}

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

@@ -0,0 +1,281 @@
+import { createHash } from "node:crypto";
+import { countEstimatedTokens, countTextChars, tokenCountMethod } from "../../core/countTokens.js";
+import { deriveSyntheticRepositoryLayout } from "./layout.js";
+export const SYNTHETIC_REPOSITORY_MANIFEST_SCHEMA_ID = "my-dev-kit-lab-synthetic-repository-manifest-v1";
+export const SYNTHETIC_REPOSITORY_MANIFEST_SCHEMA_VERSION = "1.0.0";
+export const SYNTHETIC_REPOSITORY_MANIFEST_FILE_NAME = "synthetic-repository-manifest.json";
+export const SYNTHETIC_REPOSITORY_REPOSITORY_DIRECTORY = "repository";
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+export function describeContent(content) {
+    const bytes = Buffer.from(content, "utf8");
+    return {
+        byteLength: bytes.length,
+        charCount: countTextChars(content),
+        estimatedContentTokens: countEstimatedTokens(content),
+        sha256: sha256Hex(bytes),
+    };
+}
+export function describeRenderedFile(file) {
+    const metrics = describeContent(file.content);
+    return {
+        path: file.path,
+        role: file.role,
+        ...(file.language ? { language: file.language } : {}),
+        ...metrics,
+    };
+}
+/** SHA-256 over canonical JSON of the path-ordered {path, role, byteLength, sha256} records. */
+export function computeRepositoryContentIdentity(records) {
+    const canonical = [...records]
+        .sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0))
+        .map((record) => ({ path: record.path, role: record.role, byteLength: record.byteLength, sha256: record.sha256 }));
+    return sha256Hex(Buffer.from(JSON.stringify(canonical), "utf8"));
+}
+/** Aggregate over files in the given order; the token estimate uses the existing estimator on the canonical concatenation. */
+export function computeAggregate(records, concatenatedContent) {
+    return {
+        fileCount: records.length,
+        sourceFileCount: records.filter((record) => record.role === "source").length,
+        testFileCount: records.filter((record) => record.role === "test").length,
+        supportFileCount: records.filter((record) => record.role === "support").length,
+        totalBytes: records.reduce((total, record) => total + record.byteLength, 0),
+        totalChars: records.reduce((total, record) => total + record.charCount, 0),
+        estimatedContentTokens: countEstimatedTokens(concatenatedContent),
+        tokenCountMethod,
+    };
+}
+function dimensionsOf(source) {
+    return {
+        sourceFileCount: source.sourceFileCount,
+        moduleDepth: source.moduleDepth,
+        internalImportCount: source.internalImportCount,
+        symbolCount: source.symbolCount,
+        testFileCount: source.testFileCount,
+        repeatedPatternCount: source.repeatedPatternCount,
+    };
+}
+/** Pure manifest construction from a frozen plan and its rendered files (already in path order). No host data. */
+export function buildSyntheticRepositoryManifest(plan, files) {
+    const records = files.map(describeRenderedFile);
+    const layout = deriveSyntheticRepositoryLayout(plan);
+    return {
+        schemaId: SYNTHETIC_REPOSITORY_MANIFEST_SCHEMA_ID,
+        schemaVersion: SYNTHETIC_REPOSITORY_MANIFEST_SCHEMA_VERSION,
+        generationIdentity: plan.generationIdentity,
+        caseId: plan.caseId,
+        language: plan.language,
+        taskLocality: plan.task.locality,
+        logicalTargetRoot: layout.logicalTargetRoot,
+        requestedDimensions: dimensionsOf(plan.requested),
+        realizedDimensions: dimensionsOf(plan.realized),
+        repositoryContentIdentity: computeRepositoryContentIdentity(records),
+        sourceRoots: layout.sourceRoots,
+        testRoots: layout.testRoots,
+        rawIncludeGlobs: layout.rawIncludeGlobs,
+        files: records,
+        aggregate: computeAggregate(records, files.map((file) => file.content).join("")),
+        task: {
+            taskId: plan.task.taskId,
+            expectedFiles: [...plan.answerKey.expectedFiles],
+            expectedSymbols: [...plan.answerKey.expectedSymbols],
+            expectedFactIds: plan.answerKey.facts.map((fact) => fact.factId),
+        },
+    };
+}
+/** Canonical manifest bytes: two-space JSON, LF, one trailing newline. */
+export function serializeSyntheticRepositoryManifest(manifest) {
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+const HEX64 = /^[0-9a-f]{64}$/;
+const FILE_KEYS = ["path", "role", "language", "byteLength", "charCount", "estimatedContentTokens", "sha256"];
+const TOP_KEYS = [
+    "schemaId",
+    "schemaVersion",
+    "generationIdentity",
+    "caseId",
+    "language",
+    "taskLocality",
+    "logicalTargetRoot",
+    "requestedDimensions",
+    "realizedDimensions",
+    "repositoryContentIdentity",
+    "sourceRoots",
+    "testRoots",
+    "rawIncludeGlobs",
+    "files",
+    "aggregate",
+    "task",
+];
+const DIMENSION_KEYS = ["sourceFileCount", "moduleDepth", "internalImportCount", "symbolCount", "testFileCount", "repeatedPatternCount"];
+const AGGREGATE_KEYS = [
+    "fileCount",
+    "sourceFileCount",
+    "testFileCount",
+    "supportFileCount",
+    "totalBytes",
+    "totalChars",
+    "estimatedContentTokens",
+    "tokenCountMethod",
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/** True for a plain relative POSIX logical path with no "." / ".." / empty segment, drive, UNC or backslash form. */
+export function isSafeManifestPath(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return false;
+    if (value.startsWith("/") || value.includes("\\") || value.includes(":") || value.includes("\0"))
+        return false;
+    return value.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}
+function checkKeys(label, value, allowed, required, issues) {
+    for (const key of Object.keys(value).sort())
+        if (!allowed.includes(key))
+            issues.push(`${label}: unknown field ${JSON.stringify(key)}.`);
+    for (const key of required)
+        if (!(key in value))
+            issues.push(`${label}: missing field ${key}.`);
+}
+function checkDimensions(label, value, issues) {
+    if (!isRecord(value)) {
+        issues.push(`${label}: must be an object.`);
+        return;
+    }
+    checkKeys(label, value, DIMENSION_KEYS, DIMENSION_KEYS, issues);
+    for (const key of DIMENSION_KEYS)
+        if (key in value && !isCount(value[key]))
+            issues.push(`${label}.${key}: must be a nonnegative integer.`);
+}
+/**
+ * Pure structural validation of an untrusted manifest value. Closed schema (unknown fields rejected),
+ * supported major version only, safe unique path-ordered file records, and aggregates that agree with the
+ * file records. Content-derived checks (hashes, tokens, identity of bytes) belong to the verifier.
+ */
+export function validateSyntheticRepositoryManifest(input) {
+    const issues = [];
+    if (!isRecord(input))
+        return { ok: false, issues: ["manifest: must be an object."] };
+    checkKeys("manifest", input, TOP_KEYS, TOP_KEYS, issues);
+    if (input.schemaId !== SYNTHETIC_REPOSITORY_MANIFEST_SCHEMA_ID)
+        issues.push("manifest.schemaId: unsupported manifest schema.");
+    if (typeof input.schemaVersion !== "string" || !/^1\.\d+\.\d+$/.test(input.schemaVersion)) {
+        issues.push(`manifest.schemaVersion: unsupported schema major (received ${JSON.stringify(input.schemaVersion)}).`);
+    }
+    else if (input.schemaVersion !== SYNTHETIC_REPOSITORY_MANIFEST_SCHEMA_VERSION) {
+        issues.push(`manifest.schemaVersion: only ${SYNTHETIC_REPOSITORY_MANIFEST_SCHEMA_VERSION} is understood (received ${input.schemaVersion}).`);
+    }
+    for (const key of ["generationIdentity", "repositoryContentIdentity"]) {
+        if (typeof input[key] !== "string" || !HEX64.test(input[key]))
+            issues.push(`manifest.${key}: must be lowercase 64-hex SHA-256.`);
+    }
+    if (typeof input.caseId !== "string" || input.caseId.length === 0)
+        issues.push("manifest.caseId: must be a nonempty string.");
+    if (input.language !== "typescript" && input.language !== "python")
+        issues.push("manifest.language: must be typescript or python.");
+    if (!isSafeManifestPath(input.logicalTargetRoot))
+        issues.push("manifest.logicalTargetRoot: must be a safe relative logical path.");
+    checkDimensions("manifest.requestedDimensions", input.requestedDimensions, issues);
+    checkDimensions("manifest.realizedDimensions", input.realizedDimensions, issues);
+    for (const key of ["sourceRoots", "testRoots", "rawIncludeGlobs"]) {
+        const list = input[key];
+        if (!Array.isArray(list) || list.some((entry) => typeof entry !== "string" || entry.includes("\\") || entry.startsWith("/") || entry.includes(".."))) {
+            issues.push(`manifest.${key}: must be an array of safe relative strings.`);
+        }
+    }
+    const files = input.files;
+    if (!Array.isArray(files) || files.length === 0) {
+        issues.push("manifest.files: must be a nonempty array.");
+    }
+    else {
+        const seen = new Set();
+        let previous;
+        files.forEach((record, index) => {
+            const label = `manifest.files[${index}]`;
+            if (!isRecord(record)) {
+                issues.push(`${label}: must be an object.`);
+                return;
+            }
+            checkKeys(label, record, FILE_KEYS, FILE_KEYS.filter((key) => key !== "language"), issues);
+            if (!isSafeManifestPath(record.path)) {
+                issues.push(`${label}.path: must be a safe relative logical path.`);
+            }
+            else {
+                if (seen.has(record.path))
+                    issues.push(`${label}.path: duplicate path ${record.path}.`);
+                seen.add(record.path);
+                if (previous !== undefined && record.path < previous)
+                    issues.push(`${label}.path: files are not in ascending path order.`);
+                previous = record.path;
+            }
+            if (record.role !== "source" && record.role !== "test" && record.role !== "support")
+                issues.push(`${label}.role: must be source, test or support.`);
+            if ("language" in record && record.language !== "typescript" && record.language !== "python")
+                issues.push(`${label}.language: must be typescript or python.`);
+            for (const key of ["byteLength", "charCount", "estimatedContentTokens"])
+                if (!isCount(record[key]))
+                    issues.push(`${label}.${key}: must be a nonnegative integer.`);
+            if (typeof record.sha256 !== "string" || !HEX64.test(record.sha256))
+                issues.push(`${label}.sha256: must be lowercase 64-hex SHA-256.`);
+        });
+    }
+    const aggregate = input.aggregate;
+    if (!isRecord(aggregate)) {
+        issues.push("manifest.aggregate: must be an object.");
+    }
+    else {
+        checkKeys("manifest.aggregate", aggregate, AGGREGATE_KEYS, AGGREGATE_KEYS, issues);
+        if (aggregate.tokenCountMethod !== tokenCountMethod)
+            issues.push(`manifest.aggregate.tokenCountMethod: must be ${tokenCountMethod}.`);
+    }
+    const task = input.task;
+    if (!isRecord(task)) {
+        issues.push("manifest.task: must be an object.");
+    }
+    else {
+        checkKeys("manifest.task", task, ["taskId", "expectedFiles", "expectedSymbols", "expectedFactIds"], ["taskId", "expectedFiles", "expectedSymbols", "expectedFactIds"], issues);
+        for (const key of ["expectedFiles", "expectedSymbols", "expectedFactIds"]) {
+            if (!Array.isArray(task[key]) || task[key].some((entry) => typeof entry !== "string"))
+                issues.push(`manifest.task.${key}: must be an array of strings.`);
+        }
+        if (Array.isArray(task.expectedFiles)) {
+            for (const expected of task.expectedFiles)
+                if (!isSafeManifestPath(expected))
+                    issues.push(`manifest.task.expectedFiles: unsafe path ${JSON.stringify(expected)}.`);
+        }
+    }
+    if (issues.length > 0)
+        return { ok: false, issues };
+    const manifest = input;
+    const records = manifest.files;
+    const consistency = [];
+    const expectedAggregate = {
+        fileCount: records.length,
+        sourceFileCount: records.filter((record) => record.role === "source").length,
+        testFileCount: records.filter((record) => record.role === "test").length,
+        supportFileCount: records.filter((record) => record.role === "support").length,
+        totalBytes: records.reduce((total, record) => total + record.byteLength, 0),
+        totalChars: records.reduce((total, record) => total + record.charCount, 0),
+    };
+    for (const key of Object.keys(expectedAggregate)) {
+        if (manifest.aggregate[key] !== expectedAggregate[key])
+            consistency.push(`manifest.aggregate.${key}: ${manifest.aggregate[key]} does not match the file records (${expectedAggregate[key]}).`);
+    }
+    if (manifest.realizedDimensions.sourceFileCount !== expectedAggregate.sourceFileCount)
+        consistency.push("manifest.realizedDimensions.sourceFileCount does not match source file records.");
+    if (manifest.realizedDimensions.testFileCount !== expectedAggregate.testFileCount)
+        consistency.push("manifest.realizedDimensions.testFileCount does not match test file records.");
+    if (manifest.repositoryContentIdentity !== computeRepositoryContentIdentity(records))
+        consistency.push("manifest.repositoryContentIdentity does not match the file records.");
+    const paths = new Set(records.map((record) => record.path));
+    for (const expected of manifest.task.expectedFiles)
+        if (!paths.has(expected))
+            consistency.push(`manifest.task.expectedFiles: ${expected} is not a listed file.`);
+    if (consistency.length > 0)
+        return { ok: false, issues: consistency };
+    return { ok: true, issues: [], manifest };
+}

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

@@ -0,0 +1,112 @@
+import { lstatSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { relativeWithinRoot, resolveWithinRoot } from "../../core/pathSafety.js";
+import { inspectRepositoryFiles } from "./inspection.js";
+import { computeAggregate, computeRepositoryContentIdentity, describeContent, validateSyntheticRepositoryManifest } from "./manifest.js";
+const MAX_REPORTED_ISSUES = 50;
+function walk(root, directory, found, issues) {
+    for (const entry of readdirSync(directory, { withFileTypes: true }).sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))) {
+        const full = path.join(directory, entry.name);
+        if (entry.isSymbolicLink()) {
+            issues.push(`unexpected symbolic link ${relativeWithinRoot(root, full)}.`);
+        }
+        else if (entry.isDirectory()) {
+            walk(root, full, found, issues);
+        }
+        else {
+            found.push(relativeWithinRoot(root, full));
+        }
+    }
+}
+function bounded(issues) {
+    if (issues.length <= MAX_REPORTED_ISSUES)
+        return issues;
+    return [...issues.slice(0, MAX_REPORTED_ISSUES), `... ${issues.length - MAX_REPORTED_ISSUES} more issue(s) omitted.`];
+}
+/**
+ * Read-only verification of an existing materialization against its manifest. Re-measures every listed file
+ * (bytes, chars, estimated tokens, SHA-256), the repository content identity, the aggregate metrics and the
+ * realized dimensions (from the files' own content), checks that no unlisted file exists and that the answer-key
+ * files exist. Never writes, repairs or deletes. Issues are reported in manifest (path) order.
+ */
+export function verifySyntheticRepositoryMaterialization(options) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(options.manifestPath, "utf8"));
+    }
+    catch (error) {
+        return { ok: false, issues: [`manifest cannot be read as JSON: ${error instanceof Error ? error.message : String(error)}`] };
+    }
+    const validation = validateSyntheticRepositoryManifest(parsed);
+    if (!validation.ok)
+        return { ok: false, issues: bounded(validation.issues) };
+    const manifest = validation.manifest;
+    const issues = [];
+    const inspectable = [];
+    const measured = [];
+    const contents = [];
+    for (const record of manifest.files) {
+        let absolute;
+        try {
+            absolute = resolveWithinRoot(options.repositoryRoot, record.path);
+        }
+        catch (error) {
+            issues.push(`${record.path}: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        let content;
+        try {
+            const stats = lstatSync(absolute);
+            if (!stats.isFile()) {
+                issues.push(`${record.path}: is not a regular file.`);
+                continue;
+            }
+            content = readFileSync(absolute, "utf8");
+        }
+        catch {
+            issues.push(`${record.path}: listed file is missing or unreadable.`);
+            continue;
+        }
+        if (content.includes("\r") || content.startsWith(""))
+            issues.push(`${record.path}: contains a carriage return or byte-order mark.`);
+        const metrics = describeContent(content);
+        for (const key of ["byteLength", "charCount", "estimatedContentTokens", "sha256"]) {
+            if (metrics[key] !== record[key])
+                issues.push(`${record.path}: ${key} ${String(metrics[key])} does not match the manifest (${String(record[key])}).`);
+        }
+        measured.push({ ...record, ...metrics });
+        contents.push(content);
+        inspectable.push({ path: record.path, role: record.role, content });
+    }
+    const found = [];
+    try {
+        walk(options.repositoryRoot, options.repositoryRoot, found, issues);
+    }
+    catch {
+        issues.push("repository root cannot be enumerated.");
+    }
+    const listed = new Set(manifest.files.map((record) => record.path));
+    for (const file of found.sort())
+        if (!listed.has(file))
+            issues.push(`${file}: file exists but is not listed in the manifest.`);
+    if (issues.length === 0) {
+        if (computeRepositoryContentIdentity(measured) !== manifest.repositoryContentIdentity)
+            issues.push("repositoryContentIdentity does not match the files.");
+        const aggregate = computeAggregate(measured, contents.join(""));
+        for (const key of Object.keys(aggregate)) {
+            if (aggregate[key] !== manifest.aggregate[key])
+                issues.push(`aggregate.${key} ${String(aggregate[key])} does not match the manifest (${String(manifest.aggregate[key])}).`);
+        }
+        const inspection = inspectRepositoryFiles(manifest.language, inspectable);
+        issues.push(...inspection.issues);
+        for (const key of Object.keys(inspection.dimensions)) {
+            if (inspection.dimensions[key] !== manifest.realizedDimensions[key])
+                issues.push(`realized ${key} ${inspection.dimensions[key]} measured from files does not match the manifest (${manifest.realizedDimensions[key]}).`);
+            if (manifest.requestedDimensions[key] !== manifest.realizedDimensions[key])
+                issues.push(`requested ${key} ${manifest.requestedDimensions[key]} does not equal realized ${manifest.realizedDimensions[key]}.`);
+        }
+    }
+    if (issues.length > 0)
+        return { ok: false, issues: bounded(issues), manifest };
+    return { ok: true, issues: [], manifest };
+}