@funnelsgrove/cli 0.1.14 → 0.1.18

package/dist/stepContractMigration.js

@@ -0,0 +1,1323 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { chmod, cp, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile, } from 'node:fs/promises';
+import path from 'node:path';
+import ts from 'typescript';
+import { createFunnelContractDiagnostic, FUNNEL_CHOICE_STEP_TYPES, planStepContractV2Migration, } from '@funnelsgrove/runtime';
+const MANIFEST_PATH = 'src/config/funnel.manifest.ts';
+const STATE_DIRECTORY = '.funnelsgrove';
+const MIGRATIONS_DIRECTORY = `${STATE_DIRECTORY}/migrations`;
+const BACKUPS_DIRECTORY = `${MIGRATIONS_DIRECTORY}/backups`;
+const DOCS_TRANSACTION_PREFIX = 'docs-transaction';
+const GUIDE = 'docs/funnelsgrove/migrations/step-contract-v3.md';
+const METADATA_FIELDS = ['id', 'name', 'type', 'kind', 'choice'];
+const CHOICE_STEP_TYPES = new Set(FUNNEL_CHOICE_STEP_TYPES);
+export const STEP_CONTRACT_V2_REPORT_PATH = `${MIGRATIONS_DIRECTORY}/step-contract-v2-report.json`;
+const transactionDirectory = (targetVersion) => `${MIGRATIONS_DIRECTORY}/step-contract-v${targetVersion}-transaction`;
+export const stepContractMigrationReportPath = (targetVersion) => `${MIGRATIONS_DIRECTORY}/step-contract-v${targetVersion}-report.json`;
+export class StepContractMigrationError extends Error {
+    report;
+    constructor(message, report) {
+        super(message);
+        this.name = 'StepContractMigrationError';
+        this.report = report;
+    }
+}
+export const resolveStepContractMigrationMode = (flags) => {
+    if (flags.check && flags.apply) {
+        throw new StepContractMigrationError('--check and --apply are mutually exclusive');
+    }
+    return flags.apply ? 'apply' : 'check';
+};
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isSafeRelativePath = (relativePath) => {
+    if (relativePath.length === 0
+        || relativePath.includes('\\')
+        || relativePath.includes('\0')
+        || path.posix.isAbsolute(relativePath)
+        || /^[a-zA-Z]:/.test(relativePath))
+        return false;
+    const normalized = path.posix.normalize(relativePath);
+    return normalized === relativePath
+        && normalized !== '..'
+        && !normalized.startsWith('../');
+};
+const absoluteProjectPath = (projectDir, relativePath) => {
+    if (!isSafeRelativePath(relativePath)) {
+        throw new StepContractMigrationError(`Unsafe migration path: ${relativePath}`);
+    }
+    return path.join(projectDir, ...relativePath.split('/'));
+};
+const migrationDiagnostic = (code, input) => createFunnelContractDiagnostic({
+    code,
+    file: input.file,
+    stepId: input.stepId,
+    expected: input.expected,
+    received: input.received,
+    reason: input.reason,
+    guide: GUIDE,
+    repair: input.repair,
+});
+const candidateDiagnostic = (file, received, reason) => migrationDiagnostic('FG-CANDIDATE-001', {
+    file,
+    expected: 'one static, unique, safely editable metadata object',
+    received,
+    reason,
+    repair: 'Make the manifest and component metadata explicit object literals, then rerun the check.',
+});
+const parseSource = (relativePath, source) => {
+    const sourceFile = ts.createSourceFile(relativePath, source, ts.ScriptTarget.Latest, true, relativePath.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const diagnostics = sourceFile.parseDiagnostics;
+    if (diagnostics?.length) {
+        throw new StepContractMigrationError(`Unable to parse ${relativePath}`);
+    }
+    return sourceFile;
+};
+const unwrapExpression = (input) => {
+    let expression = input;
+    while (ts.isParenthesizedExpression(expression)
+        || ts.isAsExpression(expression)
+        || ts.isSatisfiesExpression(expression)
+        || ts.isTypeAssertionExpression(expression)) {
+        expression = expression.expression;
+    }
+    return expression;
+};
+const collectBindings = (sourceFile) => {
+    const bindings = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || !declaration.initializer)
+                continue;
+            const values = bindings.get(declaration.name.text) ?? [];
+            values.push(declaration.initializer);
+            bindings.set(declaration.name.text, values);
+        }
+    }
+    return bindings;
+};
+const propertyName = (property) => {
+    if (!('name' in property) || !property.name)
+        return null;
+    if (ts.isComputedPropertyName(property.name))
+        return null;
+    if (ts.isIdentifier(property.name)
+        || ts.isStringLiteral(property.name)
+        || ts.isNumericLiteral(property.name))
+        return property.name.text;
+    return null;
+};
+const readStaticValue = (input, bindings, seen = new Set()) => {
+    const expression = unwrapExpression(input);
+    if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)) {
+        return { status: 'ok', value: expression.text };
+    }
+    if (ts.isNumericLiteral(expression)) {
+        return { status: 'ok', value: Number(expression.text) };
+    }
+    if (expression.kind === ts.SyntaxKind.TrueKeyword)
+        return { status: 'ok', value: true };
+    if (expression.kind === ts.SyntaxKind.FalseKeyword)
+        return { status: 'ok', value: false };
+    if (expression.kind === ts.SyntaxKind.NullKeyword)
+        return { status: 'ok', value: null };
+    if (ts.isIdentifier(expression)) {
+        if (expression.text === 'undefined')
+            return { status: 'ok', value: undefined };
+        const candidates = bindings.get(expression.text) ?? [];
+        if (candidates.length > 1)
+            return { status: 'multiple' };
+        if (candidates.length !== 1 || seen.has(expression.text))
+            return { status: 'dynamic' };
+        return readStaticValue(candidates[0], bindings, new Set([...seen, expression.text]));
+    }
+    if (ts.isObjectLiteralExpression(expression)) {
+        if (expression.properties.some(ts.isSpreadAssignment))
+            return { status: 'spread' };
+        if (expression.properties.some((property) => 'name' in property && property.name && ts.isComputedPropertyName(property.name))) {
+            return { status: 'computed' };
+        }
+        const value = {};
+        const names = new Set();
+        for (const property of expression.properties) {
+            const name = propertyName(property);
+            if (!name || !ts.isPropertyAssignment(property))
+                return { status: 'dynamic' };
+            if (names.has(name))
+                return { status: 'multiple' };
+            names.add(name);
+            const result = readStaticValue(property.initializer, bindings, seen);
+            if (result.status !== 'ok')
+                return result;
+            value[name] = result.value;
+        }
+        return { status: 'ok', value };
+    }
+    return { status: 'dynamic' };
+};
+const ambiguousLocatedSource = (status, sourceId, file) => ({ semantic: { status, sourceId, file } });
+const inspectMetadataObject = (input) => {
+    if (input.object.properties.some(ts.isSpreadAssignment)) {
+        return ambiguousLocatedSource('spread', input.sourceId, input.path);
+    }
+    if (input.object.properties.some((property) => 'name' in property && property.name && ts.isComputedPropertyName(property.name))) {
+        return ambiguousLocatedSource('computed', input.sourceId, input.path);
+    }
+    const grouped = new Map();
+    for (const property of input.object.properties) {
+        const name = propertyName(property);
+        if (!name || !METADATA_FIELDS.includes(name))
+            continue;
+        const values = grouped.get(name) ?? [];
+        values.push(property);
+        grouped.set(name, values);
+    }
+    if ([...grouped.values()].some((properties) => properties.length > 1)) {
+        return ambiguousLocatedSource('multiple', input.sourceId, input.path);
+    }
+    const properties = new Map();
+    const metadata = {
+        id: undefined,
+        name: undefined,
+        type: undefined,
+        kind: undefined,
+        choice: undefined,
+    };
+    for (const field of METADATA_FIELDS) {
+        const property = grouped.get(field)?.[0];
+        if (!property)
+            continue;
+        if (!ts.isPropertyAssignment(property)) {
+            return ambiguousLocatedSource('dynamic', input.sourceId, input.path);
+        }
+        const value = readStaticValue(property.initializer, input.bindings);
+        if (value.status !== 'ok') {
+            return ambiguousLocatedSource(value.status, input.sourceId, input.path);
+        }
+        properties.set(field, property);
+        metadata[field] = value.value;
+    }
+    const located = {
+        sourceId: input.sourceId,
+        path: input.path,
+        source: input.source,
+        sourceFile: input.sourceFile,
+        object: input.object,
+        properties,
+        metadata,
+    };
+    return {
+        semantic: {
+            status: 'unique',
+            sourceId: input.sourceId,
+            file: input.path,
+            metadata,
+        },
+        located,
+    };
+};
+const findVariableDeclarations = (sourceFile, name) => {
+    const declarations = [];
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name)
+                || declaration.name.text !== name)
+                continue;
+            declarations.push(declaration);
+        }
+    }
+    return declarations;
+};
+const objectFromDeclaration = (declaration) => {
+    if (!declaration.initializer)
+        return null;
+    const initializer = unwrapExpression(declaration.initializer);
+    return ts.isObjectLiteralExpression(initializer) ? initializer : null;
+};
+const propertyAssignments = (object, name) => object.properties.filter((property) => propertyName(property) === name && ts.isPropertyAssignment(property));
+const inspectManifest = (source, targetVersion) => {
+    let sourceFile;
+    try {
+        sourceFile = parseSource(MANIFEST_PATH, source);
+    }
+    catch {
+        return {
+            source,
+            sourceFile: ts.createSourceFile(MANIFEST_PATH, source, ts.ScriptTarget.Latest),
+            root: null,
+            fromVersion: null,
+            versionProperty: null,
+            steps: [],
+            diagnostics: [candidateDiagnostic(MANIFEST_PATH, 'malformed TypeScript', 'The authored manifest cannot be parsed without evaluating project code.')],
+        };
+    }
+    const rootDeclarations = findVariableDeclarations(sourceFile, 'rawFunnelManifest');
+    const root = rootDeclarations.length === 1
+        ? objectFromDeclaration(rootDeclarations[0])
+        : null;
+    if (!root) {
+        return {
+            source,
+            sourceFile,
+            root: null,
+            fromVersion: null,
+            versionProperty: null,
+            steps: [],
+            diagnostics: [candidateDiagnostic(MANIFEST_PATH, rootDeclarations.length === 0
+                    ? 'missing rawFunnelManifest'
+                    : rootDeclarations.length > 1
+                        ? 'multiple rawFunnelManifest declarations'
+                        : 'dynamic rawFunnelManifest declaration', 'The project must expose one authored rawFunnelManifest object literal.')],
+        };
+    }
+    const diagnostics = [];
+    if (root.properties.some(ts.isSpreadAssignment)
+        || root.properties.some((property) => 'name' in property && property.name && ts.isComputedPropertyName(property.name))) {
+        diagnostics.push(candidateDiagnostic(MANIFEST_PATH, 'computed or spread root manifest properties', 'The root manifest may override migration-owned properties dynamically.'));
+    }
+    const versionProperties = propertyAssignments(root, 'stepContractVersion');
+    let fromVersion = null;
+    let versionProperty = null;
+    if (versionProperties.length > 1) {
+        diagnostics.push(candidateDiagnostic(MANIFEST_PATH, 'multiple stepContractVersion properties', 'The source contract version is ambiguous.'));
+    }
+    else if (versionProperties.length === 1) {
+        versionProperty = versionProperties[0];
+        const version = readStaticValue(versionProperty.initializer, collectBindings(sourceFile));
+        const supportedSourceVersions = targetVersion === 3 ? [1, 2] : [1];
+        if (version.status !== 'ok'
+            || typeof version.value !== 'number'
+            || !supportedSourceVersions.includes(version.value)) {
+            diagnostics.push(migrationDiagnostic('FG-VERSION-002', {
+                file: MANIFEST_PATH,
+                expected: targetVersion === 3
+                    ? 'missing stepContractVersion or the literal 1 or 2'
+                    : 'missing stepContractVersion or the literal 1',
+                received: version.status === 'ok' ? version.value : version.status,
+                reason: `Only a legacy contract can migrate to version ${targetVersion}.`,
+                repair: 'Use a compatible CLI or restore the authored legacy version before migrating.',
+            }));
+        }
+        else {
+            fromVersion = version.value;
+        }
+    }
+    const stepsProperties = propertyAssignments(root, 'steps');
+    const steps = [];
+    if (stepsProperties.length !== 1) {
+        diagnostics.push(candidateDiagnostic(MANIFEST_PATH, stepsProperties.length === 0 ? 'missing steps property' : 'multiple steps properties', 'The manifest steps array must have one static property assignment.'));
+    }
+    else {
+        const stepsExpression = unwrapExpression(stepsProperties[0].initializer);
+        if (!ts.isArrayLiteralExpression(stepsExpression)) {
+            diagnostics.push(candidateDiagnostic(MANIFEST_PATH, 'dynamic steps value', 'The manifest steps value must be a static array literal.'));
+        }
+        else {
+            const bindings = collectBindings(sourceFile);
+            stepsExpression.elements.forEach((element, index) => {
+                const expression = unwrapExpression(element);
+                const sourceId = `manifest:${index}`;
+                if (!ts.isObjectLiteralExpression(expression)) {
+                    steps.push({
+                        stepKey: `step-${index}`,
+                        manifest: ambiguousLocatedSource('dynamic', sourceId, MANIFEST_PATH),
+                        componentPath: null,
+                        componentKey: null,
+                    });
+                    return;
+                }
+                const manifest = inspectMetadataObject({
+                    sourceId,
+                    path: MANIFEST_PATH,
+                    source,
+                    sourceFile,
+                    object: expression,
+                    bindings,
+                });
+                const filePathProperty = propertyAssignments(expression, 'filePath');
+                const componentKeyProperty = propertyAssignments(expression, 'componentKey');
+                const filePathValue = filePathProperty.length === 1
+                    ? readStaticValue(filePathProperty[0].initializer, bindings)
+                    : { status: 'multiple' };
+                const componentKeyValue = componentKeyProperty.length === 1
+                    ? readStaticValue(componentKeyProperty[0].initializer, bindings)
+                    : { status: 'multiple' };
+                const componentPath = filePathValue.status === 'ok'
+                    && typeof filePathValue.value === 'string'
+                    && isSafeRelativePath(filePathValue.value)
+                    && filePathValue.value.startsWith('src/steps/')
+                    ? filePathValue.value
+                    : null;
+                const componentKey = componentKeyValue.status === 'ok'
+                    && typeof componentKeyValue.value === 'string'
+                    && /^[A-Za-z_$][\w$]*$/.test(componentKeyValue.value)
+                    ? componentKeyValue.value
+                    : null;
+                const metadata = manifest.semantic.status === 'unique'
+                    ? manifest.semantic.metadata
+                    : null;
+                steps.push({
+                    stepKey: componentKey
+                        ?? (typeof metadata?.id === 'string' ? metadata.id : `step-${index}`),
+                    manifest,
+                    componentPath,
+                    componentKey,
+                });
+            });
+        }
+    }
+    return {
+        source,
+        sourceFile,
+        root,
+        fromVersion,
+        versionProperty,
+        steps,
+        diagnostics,
+    };
+};
+const readComponentSource = async (projectDir, descriptor) => {
+    const sourceId = `component:${descriptor.stepKey}`;
+    if (!descriptor.componentPath || !descriptor.componentKey) {
+        return ambiguousLocatedSource('dynamic', sourceId, descriptor.componentPath ?? MANIFEST_PATH);
+    }
+    let source;
+    try {
+        const info = await lstat(absoluteProjectPath(projectDir, descriptor.componentPath));
+        if (!info.isFile() || info.isSymbolicLink()) {
+            return ambiguousLocatedSource('missing', sourceId, descriptor.componentPath);
+        }
+        source = await readFile(absoluteProjectPath(projectDir, descriptor.componentPath), 'utf8');
+    }
+    catch {
+        return ambiguousLocatedSource('missing', sourceId, descriptor.componentPath);
+    }
+    let sourceFile;
+    try {
+        sourceFile = parseSource(descriptor.componentPath, source);
+    }
+    catch {
+        return ambiguousLocatedSource('dynamic', sourceId, descriptor.componentPath);
+    }
+    const declarations = findVariableDeclarations(sourceFile, descriptor.componentKey);
+    const object = declarations.length === 1 ? objectFromDeclaration(declarations[0]) : null;
+    if (!object) {
+        return ambiguousLocatedSource(declarations.length === 0 ? 'missing' : declarations.length > 1 ? 'multiple' : 'dynamic', sourceId, descriptor.componentPath);
+    }
+    return inspectMetadataObject({
+        sourceId,
+        path: descriptor.componentPath,
+        source,
+        sourceFile,
+        object,
+        bindings: collectBindings(sourceFile),
+    });
+};
+const resolveStaticOptionIds = (input, bindings, seen = new Set()) => {
+    const expression = unwrapExpression(input);
+    if (ts.isIdentifier(expression)) {
+        const candidates = bindings.get(expression.text) ?? [];
+        if (candidates.length !== 1 || seen.has(expression.text))
+            return null;
+        return resolveStaticOptionIds(candidates[0], bindings, new Set([...seen, expression.text]));
+    }
+    if (ts.isCallExpression(expression)
+        && ts.isPropertyAccessExpression(expression.expression)
+        && ts.isIdentifier(expression.expression.expression)
+        && expression.expression.expression.text === 'Object'
+        && expression.expression.name.text === 'freeze'
+        && expression.arguments.length === 1)
+        return resolveStaticOptionIds(expression.arguments[0], bindings, seen);
+    if (!ts.isArrayLiteralExpression(expression) || expression.elements.length === 0)
+        return null;
+    const ids = [];
+    for (const element of expression.elements) {
+        const option = unwrapExpression(element);
+        if (!ts.isObjectLiteralExpression(option)
+            || option.properties.some(ts.isSpreadAssignment)
+            || option.properties.some((property) => 'name' in property && property.name && ts.isComputedPropertyName(property.name)))
+            return null;
+        const idProperties = propertyAssignments(option, 'id');
+        if (idProperties.length !== 1)
+            return null;
+        const id = readStaticValue(idProperties[0].initializer, bindings);
+        if (id.status !== 'ok' || typeof id.value !== 'string' || id.value.length === 0)
+            return null;
+        ids.push(id.value);
+    }
+    return new Set(ids).size === ids.length ? ids : null;
+};
+const optionIdEvidence = (located, componentKey) => {
+    const validatorNames = new Set(['useStepChoices']);
+    for (const statement of located.sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement)
+            || !ts.isStringLiteral(statement.moduleSpecifier)
+            || statement.moduleSpecifier.text !== '@funnelsgrove/runtime'
+            || !statement.importClause?.namedBindings
+            || !ts.isNamedImports(statement.importClause.namedBindings))
+            continue;
+        for (const element of statement.importClause.namedBindings.elements) {
+            if ((element.propertyName?.text ?? element.name.text) === 'useStepChoices') {
+                validatorNames.add(element.name.text);
+            }
+        }
+    }
+    const matches = [];
+    const visit = (node) => {
+        if (ts.isCallExpression(node)
+            && ts.isIdentifier(node.expression)
+            && validatorNames.has(node.expression.text)
+            && node.arguments.length >= 2) {
+            const metadataArgument = unwrapExpression(node.arguments[0]);
+            if (ts.isIdentifier(metadataArgument) && metadataArgument.text === componentKey) {
+                matches.push(node);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(located.sourceFile);
+    if (matches.length !== 1)
+        return 'ambiguous';
+    return resolveStaticOptionIds(matches[0].arguments[1], collectBindings(located.sourceFile))
+        ? 'stable'
+        : 'ambiguous';
+};
+const indentationAt = (source, position) => {
+    const lineStart = source.lastIndexOf('\n', Math.max(0, position - 1)) + 1;
+    const prefix = source.slice(lineStart, position);
+    return /^\s*$/.test(prefix) ? prefix : '';
+};
+const quoteValue = (value, located) => {
+    if (typeof value !== 'string')
+        return JSON.stringify(value);
+    const stringProperty = [...located.properties.values()].find((property) => {
+        const expression = unwrapExpression(property.initializer);
+        return ts.isStringLiteral(expression);
+    });
+    if (stringProperty) {
+        const text = stringProperty.initializer.getText(located.sourceFile).trim();
+        if (text.startsWith("'"))
+            return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`;
+    }
+    return JSON.stringify(value);
+};
+const propertyRemovalRange = (located, property) => {
+    const start = property.getStart(located.sourceFile);
+    let cursor = property.end;
+    while (cursor < located.object.end && /\s/.test(located.source[cursor] ?? ''))
+        cursor += 1;
+    if (located.source[cursor] === ',')
+        return { start, end: cursor + 1 };
+    let previous = start - 1;
+    while (previous >= located.object.getStart(located.sourceFile) && /\s/.test(located.source[previous] ?? ''))
+        previous -= 1;
+    return located.source[previous] === ','
+        ? { start: previous, end: property.end }
+        : { start, end: property.end };
+};
+const propertyInsertion = (located, entries) => {
+    if (entries.length === 0) {
+        throw new StepContractMigrationError('Missing property insertion');
+    }
+    const close = located.object.end - 1;
+    const closeIndent = indentationAt(located.source, close);
+    const first = located.object.properties[0];
+    const propertyIndent = first
+        ? indentationAt(located.source, first.getStart(located.sourceFile))
+        : `${closeIndent}  `;
+    if (located.object.properties.hasTrailingComma) {
+        const extraIndent = propertyIndent.startsWith(closeIndent)
+            ? propertyIndent.slice(closeIndent.length)
+            : propertyIndent;
+        return {
+            start: close,
+            end: close,
+            replacement: entries.map(({ field, value }) => (`${extraIndent}${field}: ${quoteValue(value, located)},\n${closeIndent}`)).join(''),
+        };
+    }
+    const last = located.object.properties.at(-1);
+    if (!last) {
+        return {
+            start: close,
+            end: close,
+            replacement: `\n${entries.map(({ field, value }) => (`${propertyIndent}${field}: ${quoteValue(value, located)}`)).join(',\n')},\n${closeIndent}`,
+        };
+    }
+    return {
+        start: last.end,
+        end: last.end,
+        replacement: `,\n${entries.map(({ field, value }) => (`${propertyIndent}${field}: ${quoteValue(value, located)}`)).join(',\n')}`,
+    };
+};
+const editForSemanticOperation = (operation, located) => {
+    const property = located.properties.get(operation.field);
+    let start;
+    let end;
+    let replacement;
+    if (operation.action === 'remove') {
+        if (!property)
+            throw new StepContractMigrationError(`Missing ${operation.field} range`);
+        ({ start, end } = propertyRemovalRange(located, property));
+        replacement = '';
+    }
+    else if (property) {
+        start = property.initializer.getStart(located.sourceFile);
+        end = property.initializer.end;
+        replacement = quoteValue(operation.after, located);
+    }
+    else {
+        ({ start, end, replacement } = propertyInsertion(located, [{ field: operation.field, value: operation.after }]));
+    }
+    return {
+        path: located.path,
+        start,
+        end,
+        beforeHash: sha256(located.source.slice(start, end)),
+        afterHash: sha256(replacement),
+        replacement,
+        rule: operation.rule,
+    };
+};
+const editForSemanticInsertions = (operations, located) => {
+    if (operations.length < 2
+        || operations.some((operation) => (operation.action !== 'set'
+            || located.properties.has(operation.field)))) {
+        throw new StepContractMigrationError('Invalid grouped property insertion');
+    }
+    const rules = [...new Set(operations.map((operation) => operation.rule))].sort();
+    const rule = rules.length === 1
+        ? rules[0]
+        : rules.join('+') === 'add-name-from-id+restore-reserved-step'
+            ? 'add-name-from-id+restore-reserved-step'
+            : (() => {
+                throw new StepContractMigrationError(`Unsupported composite migration rules: ${rules.join(', ')}`);
+            })();
+    const { start, end, replacement } = propertyInsertion(located, operations.map((operation) => ({
+        field: operation.field,
+        value: operation.after,
+    })));
+    return {
+        path: located.path,
+        start,
+        end,
+        beforeHash: sha256(located.source.slice(start, end)),
+        afterHash: sha256(replacement),
+        replacement,
+        rule,
+    };
+};
+const versionEdit = (manifest, targetVersion) => {
+    if (!manifest.root || manifest.diagnostics.length > 0)
+        return null;
+    const located = {
+        sourceId: 'manifest:root',
+        path: MANIFEST_PATH,
+        source: manifest.source,
+        sourceFile: manifest.sourceFile,
+        object: manifest.root,
+        properties: new Map(manifest.versionProperty ? [['stepContractVersion', manifest.versionProperty]] : []),
+        metadata: { id: undefined, name: undefined, type: undefined, kind: undefined, choice: undefined },
+    };
+    let start;
+    let end;
+    let replacement;
+    if (manifest.versionProperty) {
+        start = manifest.versionProperty.initializer.getStart(manifest.sourceFile);
+        end = manifest.versionProperty.initializer.end;
+        replacement = String(targetVersion);
+    }
+    else {
+        ({ start, end, replacement } = propertyInsertion(located, [{ field: 'stepContractVersion', value: targetVersion }]));
+    }
+    return {
+        path: MANIFEST_PATH,
+        start,
+        end,
+        beforeHash: sha256(manifest.source.slice(start, end)),
+        afterHash: sha256(replacement),
+        replacement,
+        rule: 'set-step-contract-version',
+    };
+};
+const compareEdits = (left, right) => left.path.localeCompare(right.path)
+    || left.start - right.start
+    || left.end - right.end
+    || left.rule.localeCompare(right.rule);
+const publicOperation = ({ replacement: _replacement, ...operation }) => operation;
+const emptyReport = (options, diagnostics) => {
+    const projectDir = path.resolve(options.projectDir);
+    const targetVersion = options.targetVersion ?? 2;
+    return {
+        reportPath: path.join(projectDir, stepContractMigrationReportPath(targetVersion)),
+        report: {
+            schemaVersion: 1,
+            fromVersion: null,
+            toVersion: targetVersion,
+            checkedAt: options.checkedAt ?? new Date().toISOString(),
+            operations: [],
+            protectedChanges: [],
+            diagnostics,
+            valid: false,
+        },
+        edits: [],
+    };
+};
+const pathIsRegularFile = async (target) => {
+    try {
+        const info = await lstat(target);
+        return info.isFile() && !info.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+};
+const openDocsState = async (projectDir) => {
+    try {
+        const entries = await readdir(path.join(projectDir, STATE_DIRECTORY));
+        return entries.find((entry) => entry === DOCS_TRANSACTION_PREFIX
+            || entry.startsWith(`${DOCS_TRANSACTION_PREFIX}-`)) ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+const pathExists = async (target) => {
+    try {
+        await lstat(target);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+};
+const checkPreconditions = async (options) => {
+    const projectDir = path.resolve(options.projectDir);
+    const diagnostics = [];
+    if (!await pathIsRegularFile(path.join(projectDir, 'package.json'))) {
+        diagnostics.push(candidateDiagnostic('package.json', 'missing or unsafe project package', 'The migration target is not a supported funnel project root.'));
+    }
+    if (!await pathIsRegularFile(path.join(projectDir, MANIFEST_PATH))) {
+        diagnostics.push(candidateDiagnostic(MANIFEST_PATH, 'missing or unsafe authored manifest', 'The migration target does not contain the supported authored manifest.'));
+    }
+    if (!options.managedBundleAvailable) {
+        diagnostics.push(migrationDiagnostic('FG-DOC-001', {
+            file: null,
+            expected: 'the current managed documentation and validator bundle',
+            received: 'unavailable',
+            reason: 'The current managed documentation and validator bundle is required before planning migration.',
+            repair: 'Restore the packaged CLI bundle and rerun the migration check.',
+        }));
+    }
+    const docsState = await openDocsState(projectDir);
+    if (docsState) {
+        diagnostics.push(migrationDiagnostic('FG-DOC-001', {
+            file: `${STATE_DIRECTORY}/${docsState}`,
+            expected: 'no open documentation transaction',
+            received: docsState,
+            reason: 'A documentation update or recovery is still open.',
+            repair: 'Recover or finish the documentation transaction before migrating.',
+        }));
+    }
+    const targetVersion = options.targetVersion ?? 2;
+    const currentTransactionOpen = await pathExists(path.join(projectDir, transactionDirectory(targetVersion)));
+    const v2TransactionOpen = targetVersion === 3 && await pathExists(path.join(projectDir, transactionDirectory(2)));
+    if (currentTransactionOpen || v2TransactionOpen) {
+        diagnostics.push(candidateDiagnostic(transactionDirectory(v2TransactionOpen ? 2 : targetVersion), 'open step-contract migration transaction', 'An earlier migration must be recovered before another plan is created.'));
+    }
+    return diagnostics;
+};
+const buildProjectPlan = async (options) => {
+    const projectDir = path.resolve(options.projectDir);
+    const targetVersion = options.targetVersion ?? 2;
+    const preconditions = await checkPreconditions(options);
+    if (preconditions.length > 0)
+        return emptyReport(options, preconditions);
+    const manifestSource = await readFile(path.join(projectDir, MANIFEST_PATH), 'utf8');
+    const manifest = inspectManifest(manifestSource, targetVersion);
+    if (manifest.diagnostics.length > 0) {
+        return {
+            reportPath: path.join(projectDir, stepContractMigrationReportPath(targetVersion)),
+            report: {
+                schemaVersion: 1,
+                fromVersion: manifest.fromVersion,
+                toVersion: targetVersion,
+                checkedAt: options.checkedAt ?? new Date().toISOString(),
+                operations: [],
+                protectedChanges: [],
+                diagnostics: manifest.diagnostics,
+                valid: false,
+            },
+            edits: [],
+        };
+    }
+    const locatedBySourceId = new Map();
+    const steps = [];
+    for (const descriptor of manifest.steps) {
+        const component = await readComponentSource(projectDir, descriptor);
+        if (descriptor.manifest.located) {
+            locatedBySourceId.set(descriptor.manifest.located.sourceId, descriptor.manifest.located);
+        }
+        if (component.located)
+            locatedBySourceId.set(component.located.sourceId, component.located);
+        const manifestType = descriptor.manifest.semantic.status === 'unique'
+            ? descriptor.manifest.semantic.metadata.type
+            : undefined;
+        const componentType = component.semantic.status === 'unique'
+            ? component.semantic.metadata.type
+            : undefined;
+        const choiceStep = [manifestType, componentType].some((value) => typeof value === 'string' && CHOICE_STEP_TYPES.has(value));
+        steps.push({
+            stepKey: descriptor.stepKey,
+            manifest: descriptor.manifest.semantic,
+            component: component.semantic,
+            optionIds: choiceStep
+                ? component.located && descriptor.componentKey
+                    ? optionIdEvidence(component.located, descriptor.componentKey)
+                    : 'ambiguous'
+                : 'not-applicable',
+        });
+    }
+    const semantic = planStepContractV2Migration({ steps });
+    const diagnostics = [...manifest.diagnostics, ...semantic.diagnostics];
+    const edits = [];
+    const semanticEdits = [];
+    if (!manifest.diagnostics.some((diagnostic) => diagnostic.code === 'FG-VERSION-002')) {
+        const edit = versionEdit(manifest, targetVersion);
+        if (edit)
+            edits.push(edit);
+    }
+    const operationsBySource = new Map();
+    for (const operation of semantic.operations) {
+        const sourceOperations = operationsBySource.get(operation.sourceId) ?? [];
+        sourceOperations.push(operation);
+        operationsBySource.set(operation.sourceId, sourceOperations);
+    }
+    const purchaseTerminalSources = new Set();
+    if (targetVersion === 3) {
+        for (const [sourceId, located] of locatedBySourceId) {
+            const sourceOperations = operationsBySource.get(sourceId) ?? [];
+            const migrated = { ...located.metadata };
+            for (const operation of sourceOperations) {
+                migrated[operation.field] = operation.action === 'remove' ? undefined : operation.after;
+            }
+            if (migrated.id !== 'subscription-started'
+                || migrated.name !== 'subscription-started'
+                || migrated.type !== 'complete_registration'
+                || migrated.kind !== 'subscription-handoff')
+                continue;
+            purchaseTerminalSources.add(sourceId);
+            const typeOperation = sourceOperations.find((operation) => operation.field === 'type');
+            if (typeOperation) {
+                operationsBySource.set(sourceId, sourceOperations.map((operation) => (operation === typeOperation
+                    ? { ...operation, after: 'purchase_completed' }
+                    : operation)));
+            }
+            else {
+                operationsBySource.set(sourceId, [...sourceOperations, {
+                        source: sourceId.startsWith('manifest:') ? 'manifest' : 'component',
+                        sourceId,
+                        stepKey: sourceId.slice(sourceId.indexOf(':') + 1),
+                        stepId: 'subscription-started',
+                        field: 'type',
+                        action: 'set',
+                        before: 'complete_registration',
+                        after: 'purchase_completed',
+                        rule: 'restore-reserved-step',
+                    }]);
+            }
+        }
+    }
+    for (const sourceOperations of operationsBySource.values()) {
+        const firstOperation = sourceOperations[0];
+        const located = locatedBySourceId.get(firstOperation.sourceId);
+        if (!located) {
+            diagnostics.push(candidateDiagnostic(firstOperation.source === 'manifest' ? MANIFEST_PATH : null, {
+                sourceId: firstOperation.sourceId,
+                fields: sourceOperations.map((operation) => operation.field),
+            }, 'A safe semantic change did not have one exact source range.'));
+            continue;
+        }
+        const insertions = sourceOperations.filter((operation) => (operation.action === 'set' && !located.properties.has(operation.field)));
+        const groupedOperations = new Map();
+        if (insertions.length > 1) {
+            for (const operation of insertions)
+                groupedOperations.set(operation, insertions);
+        }
+        for (const operation of sourceOperations) {
+            const operationGroup = groupedOperations.get(operation) ?? [operation];
+            if (operationGroup[0] !== operation)
+                continue;
+            try {
+                const edit = operationGroup.length > 1
+                    ? editForSemanticInsertions(operationGroup, located)
+                    : editForSemanticOperation(operation, located);
+                if (purchaseTerminalSources.has(operation.sourceId)
+                    && operationGroup.some((candidate) => candidate.field === 'type'))
+                    edit.rule = 'upgrade-purchase-terminal';
+                edits.push(edit);
+                semanticEdits.push({ operations: operationGroup, edit });
+            }
+            catch (error) {
+                diagnostics.push(candidateDiagnostic(located.path, {
+                    sourceId: operation.sourceId,
+                    fields: operationGroup.map((candidate) => candidate.field),
+                }, error instanceof Error ? error.message : 'Unable to locate the source range.'));
+            }
+        }
+    }
+    edits.sort(compareEdits);
+    const protectedKeys = new Set(semantic.protectedChanges.map((operation) => `${operation.sourceId}\0${operation.field}\0${operation.rule}`));
+    const protectedChanges = semanticEdits.flatMap(({ operations, edit }) => {
+        if (edit.rule !== 'upgrade-purchase-terminal'
+            && !operations.some((operation) => protectedKeys.has(`${operation.sourceId}\0${operation.field}\0${operation.rule}`)))
+            return [];
+        return [publicOperation(edit)];
+    }).sort((left, right) => left.path.localeCompare(right.path) || left.start - right.start || left.rule.localeCompare(right.rule));
+    const report = {
+        schemaVersion: 1,
+        fromVersion: manifest.fromVersion,
+        toVersion: targetVersion,
+        checkedAt: options.checkedAt ?? new Date().toISOString(),
+        operations: edits.map(publicOperation),
+        protectedChanges,
+        diagnostics,
+        valid: diagnostics.length === 0,
+    };
+    return {
+        reportPath: path.join(projectDir, stepContractMigrationReportPath(targetVersion)),
+        report,
+        edits,
+    };
+};
+export const checkStepContractV2Migration = async (options) => {
+    const { edits: _edits, ...result } = await buildProjectPlan(options);
+    return result;
+};
+const writeAtomicFile = async (target, bytes, mode = 0o644) => {
+    await mkdir(path.dirname(target), { recursive: true });
+    const temporary = `${target}.tmp-${process.pid}-${randomUUID()}`;
+    try {
+        await writeFile(temporary, bytes);
+        await chmod(temporary, mode);
+        await rename(temporary, target);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+};
+const writeReport = async (reportPath, report) => writeAtomicFile(reportPath, `${JSON.stringify(report, null, 2)}\n`);
+const EXCLUDED_TREE_NAMES = new Set([
+    '.git',
+    STATE_DIRECTORY,
+    'node_modules',
+    '.next',
+    'out',
+]);
+const snapshotTree = async (root) => {
+    const snapshot = new Map();
+    const visit = async (relativeDirectory) => {
+        const directory = relativeDirectory
+            ? absoluteProjectPath(root, relativeDirectory)
+            : root;
+        const entries = await readdir(directory, { withFileTypes: true });
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+            if (!relativeDirectory && EXCLUDED_TREE_NAMES.has(entry.name))
+                continue;
+            const relativePath = relativeDirectory
+                ? `${relativeDirectory}/${entry.name}`
+                : entry.name;
+            if (!isSafeRelativePath(relativePath) || entry.isSymbolicLink()) {
+                throw new StepContractMigrationError(`Unsafe project entry: ${relativePath}`);
+            }
+            if (entry.isDirectory()) {
+                await visit(relativePath);
+            }
+            else if (entry.isFile()) {
+                const absolutePath = absoluteProjectPath(root, relativePath);
+                const [bytes, info] = await Promise.all([readFile(absolutePath), stat(absolutePath)]);
+                snapshot.set(relativePath, {
+                    bytes,
+                    hash: sha256(bytes),
+                    mode: info.mode & 0o777,
+                });
+            }
+            else {
+                throw new StepContractMigrationError(`Unsupported project entry: ${relativePath}`);
+            }
+        }
+    };
+    await visit('');
+    return snapshot;
+};
+const snapshotsEqual = (left, right) => {
+    if (left.size !== right.size)
+        return false;
+    for (const [relativePath, value] of left) {
+        const candidate = right.get(relativePath);
+        if (!candidate || candidate.hash !== value.hash || candidate.mode !== value.mode)
+            return false;
+    }
+    return true;
+};
+const applySourceEdits = async (candidateDir, edits) => {
+    const byPath = new Map();
+    for (const edit of edits) {
+        const values = byPath.get(edit.path) ?? [];
+        values.push(edit);
+        byPath.set(edit.path, values);
+    }
+    for (const [relativePath, fileEdits] of [...byPath].sort(([left], [right]) => left.localeCompare(right))) {
+        let source = await readFile(absoluteProjectPath(candidateDir, relativePath), 'utf8');
+        const descending = [...fileEdits].sort((left, right) => right.start - left.start);
+        let previousStart = source.length + 1;
+        for (const edit of descending) {
+            if (edit.end > previousStart) {
+                throw new StepContractMigrationError(`Overlapping migration ranges in ${relativePath}`);
+            }
+            const before = source.slice(edit.start, edit.end);
+            if (sha256(before) !== edit.beforeHash || sha256(edit.replacement) !== edit.afterHash) {
+                throw new StepContractMigrationError(`Stale migration range in ${relativePath}`);
+            }
+            source = `${source.slice(0, edit.start)}${edit.replacement}${source.slice(edit.end)}`;
+            previousStart = edit.start;
+        }
+        const mode = (await stat(absoluteProjectPath(candidateDir, relativePath))).mode & 0o777;
+        await writeAtomicFile(absoluteProjectPath(candidateDir, relativePath), source, mode);
+    }
+};
+const stateFromSnapshot = (snapshot) => snapshot
+    ? { exists: true, hash: snapshot.hash, mode: snapshot.mode }
+    : { exists: false, hash: null, mode: null };
+const changedOperations = (before, after) => {
+    const paths = [...new Set([...before.keys(), ...after.keys()])].sort((left, right) => {
+        if (left === MANIFEST_PATH)
+            return 1;
+        if (right === MANIFEST_PATH)
+            return -1;
+        return left.localeCompare(right);
+    });
+    return paths.flatMap((relativePath) => {
+        const previous = before.get(relativePath);
+        const next = after.get(relativePath);
+        if (previous && next && previous.hash === next.hash && previous.mode === next.mode)
+            return [];
+        return [{
+                path: relativePath,
+                before: stateFromSnapshot(previous),
+                after: stateFromSnapshot(next),
+                stagedPath: next ? `staged/${relativePath}` : null,
+                backupPath: previous ? `${BACKUPS_DIRECTORY}/PENDING/${relativePath}` : null,
+                applied: false,
+            }];
+    });
+};
+const writeJournal = async (transactionRoot, journal) => writeAtomicFile(path.join(transactionRoot, 'journal.json'), `${JSON.stringify(journal, null, 2)}\n`);
+const stageJournal = async (projectDir, candidate, baseline, targetVersion, faultInjector) => {
+    const transactionId = randomUUID();
+    const transactionRoot = path.join(projectDir, transactionDirectory(targetVersion));
+    await mkdir(transactionRoot, { recursive: false });
+    try {
+        const operations = changedOperations(baseline, candidate).map((operation) => ({
+            ...operation,
+            backupPath: operation.backupPath?.replace('/PENDING/', `/${transactionId}/`) ?? null,
+        }));
+        if (operations.length === 0 || operations.at(-1)?.path !== MANIFEST_PATH) {
+            throw new StepContractMigrationError('The complete candidate did not stage the version manifest last');
+        }
+        const journal = {
+            schemaVersion: 1,
+            transactionId,
+            ownerPid: process.pid,
+            targetRoot: projectDir,
+            operations,
+        };
+        for (const operation of operations) {
+            await faultInjector?.('before-stage-file', { path: operation.path });
+            if (operation.before.exists && operation.backupPath) {
+                const before = baseline.get(operation.path);
+                if (!before)
+                    throw new StepContractMigrationError(`Missing baseline for ${operation.path}`);
+                await writeAtomicFile(absoluteProjectPath(projectDir, operation.backupPath), before.bytes, before.mode);
+            }
+            if (operation.after.exists && operation.stagedPath) {
+                const after = candidate.get(operation.path);
+                if (!after)
+                    throw new StepContractMigrationError(`Missing candidate for ${operation.path}`);
+                await writeAtomicFile(path.join(transactionRoot, ...operation.stagedPath.split('/')), after.bytes, after.mode);
+            }
+            await faultInjector?.('after-stage-file', { path: operation.path });
+        }
+        await writeJournal(transactionRoot, journal);
+        return { transactionRoot, journal };
+    }
+    catch (error) {
+        await rm(transactionRoot, { recursive: true, force: true });
+        throw error;
+    }
+};
+const currentFileState = async (projectDir, relativePath) => {
+    try {
+        const absolutePath = absoluteProjectPath(projectDir, relativePath);
+        const info = await lstat(absolutePath);
+        if (!info.isFile() || info.isSymbolicLink()) {
+            throw new StepContractMigrationError(`Unsafe migration target: ${relativePath}`);
+        }
+        const bytes = await readFile(absolutePath);
+        return { exists: true, hash: sha256(bytes), mode: info.mode & 0o777 };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { exists: false, hash: null, mode: null };
+        }
+        throw error;
+    }
+};
+const statesEqual = (left, right) => left.exists === right.exists && left.hash === right.hash && left.mode === right.mode;
+const commitOperation = async (projectDir, transactionRoot, operation) => {
+    const current = await currentFileState(projectDir, operation.path);
+    if (!statesEqual(current, operation.before)) {
+        throw new StepContractMigrationError(`${operation.path} changed while the migration candidate was prepared`);
+    }
+    const target = absoluteProjectPath(projectDir, operation.path);
+    if (!operation.after.exists) {
+        await rm(target);
+        return;
+    }
+    if (!operation.stagedPath || operation.after.mode === null) {
+        throw new StepContractMigrationError(`Missing staged state for ${operation.path}`);
+    }
+    const staged = path.join(transactionRoot, ...operation.stagedPath.split('/'));
+    const bytes = await readFile(staged);
+    if (sha256(bytes) !== operation.after.hash) {
+        throw new StepContractMigrationError(`Corrupt staged state for ${operation.path}`);
+    }
+    await writeAtomicFile(target, bytes, operation.after.mode);
+};
+const restoreOperation = async (projectDir, operation) => {
+    const current = await currentFileState(projectDir, operation.path);
+    if (statesEqual(current, operation.before))
+        return;
+    if (!statesEqual(current, operation.after)) {
+        throw new StepContractMigrationError(`Cannot restore ${operation.path} because it changed outside the migration`);
+    }
+    const target = absoluteProjectPath(projectDir, operation.path);
+    if (!operation.before.exists) {
+        await rm(target, { force: true });
+        return;
+    }
+    if (!operation.backupPath || operation.before.mode === null) {
+        throw new StepContractMigrationError(`Missing backup state for ${operation.path}`);
+    }
+    const backup = absoluteProjectPath(projectDir, operation.backupPath);
+    const bytes = await readFile(backup);
+    if (sha256(bytes) !== operation.before.hash) {
+        throw new StepContractMigrationError(`Corrupt backup state for ${operation.path}`);
+    }
+    await writeAtomicFile(target, bytes, operation.before.mode);
+};
+const restoreJournal = async (transactionRoot, journal) => {
+    for (const operation of [...journal.operations].reverse()) {
+        await restoreOperation(journal.targetRoot, operation);
+    }
+    await rm(transactionRoot, { recursive: true, force: true });
+};
+const validationFailureDiagnostic = (received, reason) => migrationDiagnostic('FG-CLIENT-001', {
+    file: null,
+    expected: 'a complete target-version candidate that passes authoritative validation',
+    received,
+    reason,
+    repair: 'Resolve the reported candidate failure and rerun the migration.',
+});
+const reportWithFailure = (report, diagnostics) => ({
+    ...report,
+    diagnostics: [...report.diagnostics, ...diagnostics],
+    valid: false,
+});
+const invokeFault = async (options, point, context = {}) => options.faultInjector?.(point, context);
+export const applyStepContractV2Migration = async (options) => {
+    const projectDir = path.resolve(options.projectDir);
+    const targetVersion = options.targetVersion ?? 2;
+    const plan = await buildProjectPlan({ ...options, projectDir });
+    let report = plan.report;
+    await writeReport(plan.reportPath, report);
+    if (!report.valid) {
+        throw new StepContractMigrationError('Step-contract migration check is blocked', report);
+    }
+    let shadowRoot = null;
+    let preparedJournal = null;
+    try {
+        await invokeFault(options, 'after-report');
+        const baseline = await snapshotTree(projectDir);
+        shadowRoot = await mkdtemp(path.join(path.dirname(projectDir), `.fgrove-step-contract-v${targetVersion}-shadow-`));
+        const candidateDir = path.join(shadowRoot, 'project');
+        await cp(projectDir, candidateDir, {
+            recursive: true,
+            preserveTimestamps: true,
+            filter: (source) => {
+                const relativePath = path.relative(projectDir, source);
+                if (!relativePath)
+                    return true;
+                const topLevel = relativePath.split(path.sep)[0];
+                return !EXCLUDED_TREE_NAMES.has(topLevel);
+            },
+        });
+        await invokeFault(options, 'after-shadow-created');
+        await applySourceEdits(candidateDir, plan.edits);
+        await invokeFault(options, 'after-source-edits');
+        await options.installManagedCandidate({ candidateDir, report });
+        await invokeFault(options, 'after-managed-install');
+        const shadowValidation = await options.validateCandidate({
+            candidateDir,
+            phase: 'shadow',
+            authoringContractVersion: targetVersion,
+        });
+        if (!shadowValidation.valid || shadowValidation.diagnostics.length > 0) {
+            report = reportWithFailure(report, shadowValidation.diagnostics.length > 0
+                ? shadowValidation.diagnostics
+                : [validationFailureDiagnostic('invalid shadow candidate', 'Shadow validation blocked.')]);
+            await writeReport(plan.reportPath, report);
+            throw new StepContractMigrationError('Shadow candidate validation failed', report);
+        }
+        await invokeFault(options, 'after-shadow-validation');
+        const current = await snapshotTree(projectDir);
+        if (!snapshotsEqual(current, baseline)) {
+            throw new StepContractMigrationError('A project file changed while the migration candidate was prepared', report);
+        }
+        const candidate = await snapshotTree(candidateDir);
+        preparedJournal = await stageJournal(projectDir, candidate, baseline, targetVersion, (point, context) => invokeFault(options, point, context));
+        await invokeFault(options, 'after-journal-staged');
+        for (const operation of preparedJournal.journal.operations) {
+            await invokeFault(options, 'before-commit-file', { path: operation.path });
+            await commitOperation(projectDir, preparedJournal.transactionRoot, operation);
+            operation.applied = true;
+            await writeJournal(preparedJournal.transactionRoot, preparedJournal.journal);
+            await invokeFault(options, 'after-commit-file', { path: operation.path });
+        }
+        await invokeFault(options, 'after-manifest-commit', { path: MANIFEST_PATH });
+        await invokeFault(options, 'before-committed-validation');
+        const committedValidation = await options.validateCandidate({
+            candidateDir: projectDir,
+            phase: 'committed',
+            authoringContractVersion: targetVersion,
+        });
+        if (!committedValidation.valid || committedValidation.diagnostics.length > 0) {
+            report = reportWithFailure(report, committedValidation.diagnostics.length > 0
+                ? committedValidation.diagnostics
+                : [validationFailureDiagnostic('invalid committed candidate', 'Committed validation blocked.')]);
+            await writeReport(plan.reportPath, report);
+            throw new StepContractMigrationError('Committed candidate validation failed', report);
+        }
+        await invokeFault(options, 'after-committed-validation');
+        await rm(preparedJournal.transactionRoot, { recursive: true, force: true });
+        preparedJournal = null;
+        return { reportPath: plan.reportPath, report, applied: true };
+    }
+    catch (error) {
+        if (!(error instanceof StepContractMigrationError) || !error.report) {
+            report = reportWithFailure(report, [validationFailureDiagnostic(error instanceof Error ? error.message : String(error), 'The migration did not complete and its committed changes were restored.')]);
+            await writeReport(plan.reportPath, report);
+        }
+        if (preparedJournal) {
+            preparedJournal.journal.ownerPid = null;
+            await writeJournal(preparedJournal.transactionRoot, preparedJournal.journal);
+            await restoreJournal(preparedJournal.transactionRoot, preparedJournal.journal);
+            preparedJournal = null;
+        }
+        throw error;
+    }
+    finally {
+        if (shadowRoot)
+            await rm(shadowRoot, { recursive: true, force: true });
+    }
+};
+const parseJournal = (value, projectDir) => {
+    if (!isRecord(value) || value.schemaVersion !== 1 || !Array.isArray(value.operations)) {
+        throw new StepContractMigrationError('Migration journal is corrupt');
+    }
+    if (typeof value.transactionId !== 'string'
+        || !/^[a-f0-9-]{16,}$/.test(value.transactionId)
+        || value.targetRoot !== projectDir
+        || !(value.ownerPid === null || Number.isSafeInteger(value.ownerPid)))
+        throw new StepContractMigrationError('Migration journal identity is corrupt');
+    const operations = value.operations.map((raw) => {
+        if (!isRecord(raw) || typeof raw.path !== 'string' || !isSafeRelativePath(raw.path)) {
+            throw new StepContractMigrationError('Migration journal operation is corrupt');
+        }
+        const parseState = (state) => {
+            if (!isRecord(state) || typeof state.exists !== 'boolean') {
+                throw new StepContractMigrationError('Migration journal file state is corrupt');
+            }
+            if (state.exists) {
+                if (typeof state.hash !== 'string'
+                    || !/^[a-f0-9]{64}$/.test(state.hash)
+                    || !Number.isInteger(state.mode))
+                    throw new StepContractMigrationError('Migration journal file state is corrupt');
+                return { exists: true, hash: state.hash, mode: state.mode };
+            }
+            if (state.hash !== null || state.mode !== null) {
+                throw new StepContractMigrationError('Migration journal absent state is corrupt');
+            }
+            return { exists: false, hash: null, mode: null };
+        };
+        const before = parseState(raw.before);
+        const after = parseState(raw.after);
+        if (typeof raw.applied !== 'boolean'
+            || !(raw.stagedPath === null || (typeof raw.stagedPath === 'string'
+                && isSafeRelativePath(raw.stagedPath)
+                && raw.stagedPath.startsWith('staged/')))
+            || !(raw.backupPath === null || (typeof raw.backupPath === 'string'
+                && isSafeRelativePath(raw.backupPath)
+                && raw.backupPath.startsWith(`${BACKUPS_DIRECTORY}/`)))
+            || after.exists !== (raw.stagedPath !== null)
+            || before.exists !== (raw.backupPath !== null))
+            throw new StepContractMigrationError('Migration journal operation semantics are corrupt');
+        return {
+            path: raw.path,
+            before,
+            after,
+            stagedPath: raw.stagedPath,
+            backupPath: raw.backupPath,
+            applied: raw.applied,
+        };
+    });
+    return {
+        schemaVersion: 1,
+        transactionId: value.transactionId,
+        ownerPid: value.ownerPid,
+        targetRoot: projectDir,
+        operations,
+    };
+};
+const processIsAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+};
+export const recoverStepContractV2Migration = async (projectDirectory, targetVersion = 2) => {
+    const projectDir = path.resolve(projectDirectory);
+    let restored = false;
+    const versions = targetVersion === 3 ? [2, 3] : [2];
+    for (const version of versions) {
+        const transactionRoot = path.join(projectDir, transactionDirectory(version));
+        if (!await pathExists(transactionRoot))
+            continue;
+        const raw = JSON.parse(await readFile(path.join(transactionRoot, 'journal.json'), 'utf8'));
+        const journal = parseJournal(raw, projectDir);
+        if (journal.ownerPid !== null && processIsAlive(journal.ownerPid)) {
+            throw new StepContractMigrationError(`Migration transaction is still owned by process ${journal.ownerPid}`);
+        }
+        await restoreJournal(transactionRoot, journal);
+        restored = true;
+    }
+    return restored ? 'restored' : 'none';
+};