@automaton-labs/aib 0.0.6 → 0.0.8

package/dist/mutation/semantic-move-owner-divergence-harness.js

@@ -0,0 +1,474 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.investigateSemanticMoveOwnerDivergence = investigateSemanticMoveOwnerDivergence;
+exports.compareSemanticMoveProgramScopes = compareSemanticMoveProgramScopes;
+exports.compareProgramScopeResults = compareProgramScopeResults;
+exports.summarizeSemanticMoveProgramScopeComparison = summarizeSemanticMoveProgramScopeComparison;
+exports.classifySemanticMoveOwnerCandidates = classifySemanticMoveOwnerCandidates;
+exports.summarizeSemanticMoveOwnerDivergence = summarizeSemanticMoveOwnerDivergence;
+exports.materializeSemanticMoveOwnerCandidate = materializeSemanticMoveOwnerCandidate;
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const file_mutation_discovery_1 = require("./file-mutation-discovery");
+const semantic_move_policy_1 = require("./semantic-move-policy");
+const semantic_move_standalone_planner_1 = require("./semantic-move-standalone-planner");
+const semantic_move_process_1 = require("./semantic-move-process");
+const semantic_program_roots_1 = require("./semantic-program-roots");
+const defaultDependencies = {
+    discover: file_mutation_discovery_1.discoverFileMutationConsumers,
+    fingerprint: file_mutation_discovery_1.computeFileMutationWorkspaceFingerprint,
+    runConfig: semantic_move_process_1.runSemanticMoveConfigWorker
+};
+async function investigateSemanticMoveOwnerDivergence(input, dependencies = defaultDependencies, options = {}) {
+    const workspaceRoot = path.resolve(input.workspaceRoot);
+    let discovery = input.discovery ?? null;
+    const configResults = [];
+    const planner = await (0, semantic_move_standalone_planner_1.planStandaloneSemanticMove)({
+        ...input,
+        metrics: input.metrics ?? createInvestigationMetrics()
+    }, {
+        discover: (request) => {
+            discovery = dependencies.discover(request);
+            return discovery;
+        },
+        fingerprint: dependencies.fingerprint,
+        runConfig: (workerInput) => dependencies.runConfig({
+            ...workerInput,
+            request: withProgramScope(workerInput.request, discovery, options.programScope ?? "focused")
+        }),
+        observeConfigResult: (result) => configResults.push(cloneConfigResult(result))
+    });
+    const { candidateClasses, classByOwner } = classifySemanticMoveOwnerCandidates({
+        workspaceRoot,
+        importRules: input.importRules ?? [],
+        results: configResults
+    });
+    return {
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        workspaceRoot,
+        sourceFile: path.resolve(workspaceRoot, input.sourceFile),
+        targetFile: path.resolve(workspaceRoot, input.targetFile),
+        planner,
+        discoveryDurationMs: discovery?.durationMs ?? 0,
+        ...(discovery?.timings ? { discoveryTimings: discovery.timings } : {}),
+        endingRssMiB: bytesToMiB(process.memoryUsage().rss),
+        owners: configResults.map((result) => {
+            const classId = classByOwner.get(pathKey(result.configFilePath));
+            return {
+                configFilePath: path.relative(workspaceRoot, result.configFilePath),
+                ok: result.ok,
+                containsSource: result.containsSource,
+                ...(result.failureKind ? { failureKind: result.failureKind } : {}),
+                ...(result.providerCode ? { providerCode: result.providerCode } : {}),
+                ...(result.error ? { error: result.error } : {}),
+                ...(classId ? { classId } : {}),
+                ...(result.ok ? { editHash: hashOwnerEdits(workspaceRoot, result.edits) } : {}),
+                fileEditCount: result.edits.length,
+                textChangeCount: countTextChanges(result.edits),
+                rssMiB: result.rssMiB,
+                ...(result.metrics?.phasesMs ? { phasesMs: { ...result.metrics.phasesMs } } : {}),
+                ...(result.metrics?.programFiles ? { programFiles: { ...result.metrics.programFiles } } : {})
+            };
+        }),
+        candidateClasses
+    };
+}
+async function compareSemanticMoveProgramScopes(input, dependencies = defaultDependencies, options = {}) {
+    const workspaceRoot = path.resolve(input.workspaceRoot);
+    const sourceFile = path.resolve(workspaceRoot, input.sourceFile);
+    const discovery = input.discovery ?? dependencies.discover({ workspaceRoot, sourceFiles: [sourceFile] });
+    const sharedInput = { ...input, workspaceRoot, sourceFile, discovery };
+    const firstScope = options.firstScope ?? "full";
+    const secondScope = firstScope === "full" ? "focused" : "full";
+    const first = await investigateSemanticMoveOwnerDivergence(sharedInput, dependencies, { programScope: firstScope });
+    const second = await investigateSemanticMoveOwnerDivergence(sharedInput, dependencies, { programScope: secondScope });
+    const full = firstScope === "full" ? first : second;
+    const focused = firstScope === "focused" ? first : second;
+    return {
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        workspaceRoot,
+        sourceFile,
+        targetFile: path.resolve(workspaceRoot, input.targetFile),
+        parity: compareProgramScopeResults(full, focused),
+        metrics: {
+            full: aggregateProgramScopeMetrics(full),
+            focused: aggregateProgramScopeMetrics(focused)
+        },
+        full,
+        focused
+    };
+}
+function compareProgramScopeResults(full, focused) {
+    const plannerEdits = stableJson(plannerEvidence(full)) === stableJson(plannerEvidence(focused));
+    const ownerEdits = stableJson(ownerEvidence(full)) === stableJson(ownerEvidence(focused));
+    const candidateClasses = stableJson(candidateEvidence(full)) === stableJson(candidateEvidence(focused));
+    const differences = [
+        ...(!plannerEdits ? ["planner-edits"] : []),
+        ...(!ownerEdits ? ["owner-edits"] : []),
+        ...(!candidateClasses ? ["candidate-classes"] : [])
+    ];
+    return { exact: differences.length === 0, plannerEdits, ownerEdits, candidateClasses, differences };
+}
+function summarizeSemanticMoveProgramScopeComparison(comparison) {
+    return {
+        schemaVersion: comparison.schemaVersion,
+        generatedAt: comparison.generatedAt,
+        workspaceRoot: comparison.workspaceRoot,
+        sourceFile: comparison.sourceFile,
+        targetFile: comparison.targetFile,
+        parity: comparison.parity,
+        metrics: comparison.metrics,
+        full: summarizeSemanticMoveOwnerDivergence(comparison.full),
+        focused: summarizeSemanticMoveOwnerDivergence(comparison.focused)
+    };
+}
+function withProgramScope(request, discovery, scope) {
+    if (scope === "full") {
+        const { programRootFiles: _programRootFiles, ...fullRequest } = request;
+        return fullRequest;
+    }
+    if (!discovery)
+        throw new Error("Focused Program investigation requires a completed discovery snapshot.");
+    return {
+        ...request,
+        programRootFiles: (0, semantic_program_roots_1.focusedSemanticProgramRootFiles)({
+            discovery,
+            configFilePath: request.configFilePath,
+            requiredFiles: [request.sourceFile, request.targetFile]
+        })
+    };
+}
+function aggregateProgramScopeMetrics(investigation) {
+    return investigation.owners.reduce((total, owner) => ({
+        plannerTotalMs: investigation.planner.totalMs,
+        workerProgramMs: total.workerProgramMs + (owner.phasesMs?.program ?? 0),
+        workerMaxRssMiB: Math.max(total.workerMaxRssMiB, owner.rssMiB),
+        programRootFiles: total.programRootFiles + (owner.programFiles?.root ?? 0),
+        programTotalFiles: total.programTotalFiles + (owner.programFiles?.total ?? 0),
+        programWorkspaceFiles: total.programWorkspaceFiles + (owner.programFiles?.workspace ?? 0)
+    }), {
+        plannerTotalMs: investigation.planner.totalMs,
+        workerProgramMs: 0,
+        workerMaxRssMiB: 0,
+        programRootFiles: 0,
+        programTotalFiles: 0,
+        programWorkspaceFiles: 0
+    });
+}
+function plannerEvidence(investigation) {
+    return {
+        complete: investigation.planner.complete,
+        code: investigation.planner.code,
+        error: investigation.planner.error ?? null,
+        edits: investigation.planner.edits.map((edit) => ({
+            fileName: path.relative(investigation.workspaceRoot, edit.fileName).replaceAll("\\", "/"),
+            isNewFile: edit.isNewFile,
+            expectedExists: edit.expectedExists,
+            expectedHash: edit.expectedHash,
+            textChanges: edit.textChanges.map((change) => ({
+                span: change.span,
+                newText: change.newText
+            }))
+        }))
+    };
+}
+function ownerEvidence(investigation) {
+    return investigation.owners.map((owner) => ({
+        configFilePath: owner.configFilePath.replaceAll("\\", "/"),
+        ok: owner.ok,
+        containsSource: owner.containsSource,
+        failureKind: owner.failureKind ?? null,
+        providerCode: owner.providerCode ?? null,
+        classId: owner.classId ?? null,
+        editHash: owner.editHash ?? null
+    })).sort((left, right) => left.configFilePath.localeCompare(right.configFilePath));
+}
+function candidateEvidence(investigation) {
+    return investigation.candidateClasses.map((candidate) => ({
+        id: candidate.id,
+        ownerConfigs: [...candidate.ownerConfigs].map((config) => config.replaceAll("\\", "/")).sort(),
+        files: candidate.files.map((file) => ({
+            relativePath: file.relativePath.replaceAll("\\", "/"),
+            expectedExists: file.expectedExists,
+            expectedHash: file.expectedHash,
+            finalHash: file.finalHash
+        })).sort((left, right) => left.relativePath.localeCompare(right.relativePath))
+    })).sort((left, right) => left.id.localeCompare(right.id));
+}
+function hashOwnerEdits(workspaceRoot, edits) {
+    const normalized = edits.map((edit) => ({
+        fileName: path.relative(workspaceRoot, edit.fileName).replaceAll("\\", "/"),
+        isNewFile: edit.isNewFile,
+        textChanges: edit.textChanges.map((change) => ({ span: change.span, newText: change.newText }))
+    })).sort((left, right) => left.fileName.localeCompare(right.fileName));
+    return hash(Buffer.from(stableJson(normalized), "utf8"));
+}
+function stableJson(value) {
+    return JSON.stringify(value);
+}
+function classifySemanticMoveOwnerCandidates(input) {
+    const root = path.resolve(input.workspaceRoot);
+    const classes = new Map();
+    const classByOwner = new Map();
+    for (const result of input.results) {
+        if (!result.ok || !result.containsSource)
+            continue;
+        const planned = prepareOwnerEdits(root, result.edits);
+        if (!planned)
+            continue;
+        const policyEdits = (0, semantic_move_policy_1.applySemanticMoveImportPolicies)({
+            workspaceRoot: root,
+            edits: planned,
+            importRules: input.importRules ?? []
+        });
+        const files = renderChangedFiles(root, policyEdits);
+        const id = candidateId(files);
+        const owner = path.relative(root, result.configFilePath);
+        const existing = classes.get(id);
+        if (existing) {
+            existing.ownerConfigs.push(owner);
+            existing.textChangeCount += countTextChanges(result.edits);
+        }
+        else {
+            classes.set(id, {
+                id,
+                ownerConfigs: [owner],
+                files,
+                fileCount: files.length,
+                textChangeCount: countTextChanges(result.edits)
+            });
+        }
+        classByOwner.set(pathKey(result.configFilePath), id);
+    }
+    return {
+        candidateClasses: [...classes.values()]
+            .map((candidate) => ({ ...candidate, ownerConfigs: candidate.ownerConfigs.sort() }))
+            .sort((left, right) => left.id.localeCompare(right.id)),
+        classByOwner
+    };
+}
+function summarizeSemanticMoveOwnerDivergence(investigation) {
+    const raw = JSON.stringify(investigation);
+    return {
+        ...investigation,
+        planner: {
+            ...investigation.planner,
+            edits: investigation.planner.edits.map((edit) => ({
+                relativePath: path.relative(investigation.workspaceRoot, edit.fileName),
+                isNewFile: edit.isNewFile,
+                textChangeCount: edit.textChanges.length
+            }))
+        },
+        candidateClasses: investigation.candidateClasses.map((candidate) => ({
+            ...candidate,
+            files: candidate.files.map(({ finalText: _finalText, ...file }) => file)
+        })),
+        outputBytes: Buffer.byteLength(raw)
+    };
+}
+function materializeSemanticMoveOwnerCandidate(input) {
+    const sourceRoot = path.resolve(input.sourceRoot);
+    const targetRoot = path.resolve(input.targetRoot);
+    if (samePath(sourceRoot, targetRoot)) {
+        throw new Error("Investigation candidates may only be materialized into a separate disposable checkout.");
+    }
+    const writes = [];
+    for (const file of input.candidate.files) {
+        const source = path.resolve(sourceRoot, file.relativePath);
+        const target = path.resolve(targetRoot, file.relativePath);
+        if (!isInside(sourceRoot, source) || !isInside(targetRoot, target)) {
+            throw new Error(`Candidate file escapes its workspace: ${file.relativePath}`);
+        }
+        verifyExpectedFile(source, file);
+        verifyExpectedFile(target, file);
+        writes.push({ target, text: file.finalText });
+    }
+    for (const write of writes) {
+        fs.mkdirSync(path.dirname(write.target), { recursive: true });
+        fs.writeFileSync(write.target, write.text, "utf8");
+    }
+    return writes.map((write) => path.relative(targetRoot, write.target));
+}
+function prepareOwnerEdits(root, edits) {
+    const seen = new Set();
+    const planned = [];
+    for (const edit of edits) {
+        const fileName = path.resolve(edit.fileName);
+        const key = pathKey(fileName);
+        if (!isInside(root, fileName) || seen.has(key))
+            return null;
+        seen.add(key);
+        const expectedExists = fs.existsSync(fileName);
+        if (expectedExists && !fs.statSync(fileName).isFile())
+            return null;
+        if (edit.isNewFile === expectedExists)
+            return null;
+        const expectedBytes = expectedExists ? fs.readFileSync(fileName) : Buffer.alloc(0);
+        const expectedText = expectedBytes.toString("utf8");
+        if (!validTextChanges(expectedText, edit.textChanges))
+            return null;
+        planned.push({
+            fileName,
+            isNewFile: edit.isNewFile,
+            textChanges: edit.textChanges.map((change) => ({
+                span: { start: change.span.start, length: change.span.length },
+                newText: change.newText
+            })),
+            expectedExists,
+            expectedText,
+            expectedHash: hash(expectedBytes)
+        });
+    }
+    return planned;
+}
+function renderChangedFiles(root, edits) {
+    const files = [];
+    for (const edit of edits) {
+        const finalText = applyTextChanges(edit.expectedText, edit.textChanges);
+        if (edit.expectedExists && finalText === edit.expectedText)
+            continue;
+        files.push({
+            relativePath: path.relative(root, edit.fileName),
+            expectedExists: edit.expectedExists,
+            expectedHash: edit.expectedHash,
+            finalHash: hash(Buffer.from(finalText, "utf8")),
+            finalText
+        });
+    }
+    return files.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+function candidateId(files) {
+    const value = files.map((file) => ({
+        path: file.relativePath.replaceAll("\\", "/"),
+        expectedExists: file.expectedExists,
+        finalHash: file.finalHash
+    }));
+    return hash(Buffer.from(JSON.stringify(value), "utf8")).slice(0, 16);
+}
+function validTextChanges(text, changes) {
+    const ordered = [...changes].sort((left, right) => left.span.start - right.span.start || left.span.length - right.span.length);
+    let end = 0;
+    for (const change of ordered) {
+        if (!Number.isInteger(change.span.start) || !Number.isInteger(change.span.length) ||
+            change.span.start < end || change.span.length < 0 || change.span.start + change.span.length > text.length) {
+            return false;
+        }
+        end = change.span.start + change.span.length;
+    }
+    return true;
+}
+function applyTextChanges(text, changes) {
+    let output = text;
+    for (const change of [...changes].sort((left, right) => right.span.start - left.span.start || right.span.length - left.span.length)) {
+        output = `${output.slice(0, change.span.start)}${change.newText}${output.slice(change.span.start + change.span.length)}`;
+    }
+    return output;
+}
+function verifyExpectedFile(fileName, file) {
+    const exists = fs.existsSync(fileName);
+    if (exists !== file.expectedExists)
+        throw new Error(`Candidate baseline existence changed: ${file.relativePath}`);
+    const bytes = exists ? fs.readFileSync(fileName) : Buffer.alloc(0);
+    if (hash(bytes) !== file.expectedHash)
+        throw new Error(`Candidate baseline bytes changed: ${file.relativePath}`);
+}
+function cloneConfigResult(result) {
+    return {
+        ...result,
+        rootFiles: [...result.rootFiles],
+        edits: result.edits.map((edit) => ({
+            ...edit,
+            textChanges: edit.textChanges.map((change) => ({
+                span: { ...change.span },
+                newText: change.newText
+            }))
+        })),
+        beforeHashes: { ...result.beforeHashes },
+        ...(result.metrics ? {
+            metrics: {
+                ...result.metrics,
+                phasesMs: { ...result.metrics.phasesMs },
+                ...(result.metrics.programFiles ? { programFiles: { ...result.metrics.programFiles } } : {})
+            }
+        } : {})
+    };
+}
+function createInvestigationMetrics() {
+    return {
+        start: () => Date.now(),
+        end: () => undefined,
+        add: () => undefined,
+        observeWorker: () => undefined,
+        observeDivergence: () => undefined,
+        finish: () => undefined
+    };
+}
+function countTextChanges(edits) {
+    return edits.reduce((sum, edit) => sum + edit.textChanges.length, 0);
+}
+function hash(bytes) {
+    return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+function bytesToMiB(bytes) {
+    return Math.round(bytes / 1024 / 1024 * 10) / 10;
+}
+function isInside(root, file) {
+    const relative = path.relative(root, file);
+    return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function samePath(left, right) {
+    return pathKey(left) === pathKey(right);
+}
+function pathKey(file) {
+    const normalized = path.resolve(file);
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function uniquePaths(files) {
+    const seen = new Set();
+    const output = [];
+    for (const file of files) {
+        const resolved = path.resolve(file);
+        const key = pathKey(resolved);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        output.push(resolved);
+    }
+    return output;
+}

package/dist/mutation/semantic-move-owner-divergence-runner.js

@@ -0,0 +1,162 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const semantic_move_owner_divergence_harness_1 = require("./semantic-move-owner-divergence-harness");
+async function main(argv) {
+    const command = argv[0];
+    const args = parseArgs(argv.slice(1));
+    if (command === "probe") {
+        const workspaceRoot = required(args, "workspace");
+        const sourceFile = required(args, "source");
+        const targetFile = required(args, "target");
+        const entities = values(args, "entity");
+        if (entities.length === 0)
+            throw new Error("At least one --entity is required.");
+        const result = await (0, semantic_move_owner_divergence_harness_1.investigateSemanticMoveOwnerDivergence)({
+            workspaceRoot,
+            sourceFile,
+            targetFile,
+            entities: entities.map((name) => ({ name })),
+            ...(optional(args, "deadline-ms") ? { deadlineMs: Number(optional(args, "deadline-ms")) } : {})
+        });
+        const output = path.resolve(required(args, "output"));
+        const summary = path.resolve(optional(args, "summary") ?? `${output}.summary.json`);
+        fs.mkdirSync(path.dirname(output), { recursive: true });
+        fs.writeFileSync(output, `${JSON.stringify(result, null, 2)}\n`, "utf8");
+        fs.writeFileSync(summary, `${JSON.stringify((0, semantic_move_owner_divergence_harness_1.summarizeSemanticMoveOwnerDivergence)(result), null, 2)}\n`, "utf8");
+        process.stdout.write(`${JSON.stringify({
+            output,
+            summary,
+            plannerCode: result.planner.code,
+            ownerCount: result.owners.length,
+            candidateClassCount: result.candidateClasses.length
+        })}\n`);
+        return;
+    }
+    if (command === "compare-programs") {
+        const workspaceRoot = required(args, "workspace");
+        const sourceFile = required(args, "source");
+        const targetFile = required(args, "target");
+        const entities = values(args, "entity");
+        if (entities.length === 0)
+            throw new Error("At least one --entity is required.");
+        const firstScopeValue = optional(args, "first-scope");
+        if (firstScopeValue && firstScopeValue !== "full" && firstScopeValue !== "focused") {
+            throw new Error("--first-scope must be full or focused.");
+        }
+        const firstScope = firstScopeValue;
+        const result = await (0, semantic_move_owner_divergence_harness_1.compareSemanticMoveProgramScopes)({
+            workspaceRoot,
+            sourceFile,
+            targetFile,
+            entities: entities.map((name) => ({ name })),
+            ...(optional(args, "deadline-ms") ? { deadlineMs: Number(optional(args, "deadline-ms")) } : {})
+        }, undefined, firstScope ? { firstScope } : {});
+        const output = path.resolve(required(args, "output"));
+        const summary = path.resolve(optional(args, "summary") ?? `${output}.summary.json`);
+        fs.mkdirSync(path.dirname(output), { recursive: true });
+        fs.writeFileSync(output, `${JSON.stringify(result, null, 2)}\n`, "utf8");
+        fs.writeFileSync(summary, `${JSON.stringify((0, semantic_move_owner_divergence_harness_1.summarizeSemanticMoveProgramScopeComparison)(result), null, 2)}\n`, "utf8");
+        process.stdout.write(`${JSON.stringify({
+            output,
+            summary,
+            exactParity: result.parity.exact,
+            differences: result.parity.differences,
+            full: result.metrics.full,
+            focused: result.metrics.focused
+        })}\n`);
+        return;
+    }
+    if (command === "materialize") {
+        const investigation = JSON.parse(fs.readFileSync(required(args, "input"), "utf8"));
+        const classId = required(args, "class");
+        const candidate = investigation.candidateClasses.find((item) => item.id === classId);
+        if (!candidate)
+            throw new Error(`Unknown candidate class: ${classId}`);
+        const files = (0, semantic_move_owner_divergence_harness_1.materializeSemanticMoveOwnerCandidate)({
+            sourceRoot: investigation.workspaceRoot,
+            targetRoot: required(args, "target-root"),
+            candidate
+        });
+        process.stdout.write(`${JSON.stringify({ classId, filesWritten: files.length, files })}\n`);
+        return;
+    }
+    if (command === "summarize") {
+        const input = path.resolve(required(args, "input"));
+        const output = path.resolve(required(args, "output"));
+        const investigation = JSON.parse(fs.readFileSync(input, "utf8"));
+        fs.mkdirSync(path.dirname(output), { recursive: true });
+        fs.writeFileSync(output, `${JSON.stringify((0, semantic_move_owner_divergence_harness_1.summarizeSemanticMoveOwnerDivergence)(investigation), null, 2)}\n`, "utf8");
+        process.stdout.write(`${JSON.stringify({ input, output })}\n`);
+        return;
+    }
+    throw new Error("Usage: runner probe|compare-programs --workspace ... --source ... --target ... --entity ... --output ... | materialize --input ... --class ... --target-root ... | summarize --input ... --output ...");
+}
+function parseArgs(argv) {
+    const output = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token?.startsWith("--") || token.length === 2)
+            throw new Error(`Invalid argument: ${String(token)}`);
+        const key = token.slice(2);
+        const value = argv[index + 1];
+        if (!value || value.startsWith("--"))
+            throw new Error(`Missing value for --${key}`);
+        (output[key] ??= []).push(value);
+        index += 1;
+    }
+    return output;
+}
+function values(args, key) {
+    return args[key] ?? [];
+}
+function optional(args, key) {
+    const entries = values(args, key);
+    if (entries.length > 1 && key !== "entity")
+        throw new Error(`Option --${key} may only be provided once.`);
+    return entries[0];
+}
+function required(args, key) {
+    const value = optional(args, key);
+    if (!value)
+        throw new Error(`Missing --${key}.`);
+    return value;
+}
+void main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/mutation/semantic-move-plan-hash.js

@@ -0,0 +1,56 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeSemanticMovePlanHash = computeSemanticMovePlanHash;
+const crypto = __importStar(require("node:crypto"));
+const path = __importStar(require("node:path"));
+function computeSemanticMovePlanHash(plan) {
+    return crypto.createHash("sha256").update(JSON.stringify({
+        workspaceRoot: path.normalize(plan.workspaceRoot),
+        sourceFile: path.normalize(plan.sourceFile),
+        targetFile: path.normalize(plan.targetFile),
+        entities: plan.entities,
+        edits: plan.edits.map((edit) => ({
+            fileName: path.normalize(edit.fileName),
+            isNewFile: edit.isNewFile,
+            expectedExists: edit.expectedExists,
+            expectedText: edit.expectedText,
+            expectedHash: edit.expectedHash,
+            textChanges: edit.textChanges
+        })),
+        discoveryFingerprint: plan.discovery.workspaceFingerprint,
+        snapshotHash: plan.snapshotHash
+    })).digest("hex");
+}