@msn-control/liftoff 0.11.1 → 0.11.2

package/dist/application/update/use-case.js

@@ -1,600 +1,271 @@
 import path from 'node:path';
-import { applyProjectFileTransaction, captureProjectFileSnapshot } from '../../adapters/filesystem/project-transaction.js';
+import { consumeUpdatePreviewReceipt, createUpdateTransactionApprovalStore, issueUpdatePreviewReceipt, loadUpdatePreviewReceipt, resolveUpdatePreviewLocation } from '../../adapters/filesystem/update-previews.js';
+import { applyReviewedUpdateTransaction, inspectReviewedUpdateTransaction, recoverReviewedUpdateTransaction } from '../../adapters/filesystem/reviewed-update-transaction.js';
 import { findProjectRoot } from '../../adapters/filesystem/project-discovery.js';
-import { loadManifest, parseManifest } from '../project/manifest.js';
-import { manifestHadFilteredLegacyNonDurableOwnership } from '../../domain/project/manifest/reader.js';
 import { manifestDisplayPath } from '../../domain/project/paths.js';
-import { readProjectFile } from '../../adapters/filesystem/project-files.js';
-import { buildProjectPlan, loadConfigOptions } from '../project/planning.js';
-import { hasDrift, reconcileProject } from '../../reconcile.js';
-import { compareSemver } from '../../semver.js';
-import { buildManifest } from '../../templates.js';
-import { activationStateFilePathParts } from '../../governance-activation/activation-state.js';
-import { planHistoricalActivationStateMigration } from '../../governance-activation/migration.js';
-import { liftoffVersion } from '../../version.js';
-import { appendProvisionedProjectArtifacts, assertAuthorizedUpdateMutations, buildUpdateArtifacts, captureUpdateSnapshots, inspectProvisioningGroups, isUnownedUpdateConflict, planWithBlockedProvisioning, preflightUpdate, provisioningJson, requestedProvisioningGroups, sameWorkloadIntent, selectUpdatePreconditions } from './planning.js';
-import { activeChangeReconciliationReport, combineReconciliationReports, entryDisplay, entryMarker, isDirtyGitWorktree, manifestChanges, maybeInjectUpdateFailure, stateMigrationReconciliation, summarizeEntries } from './reporting.js';
-function preserveDiagnosticGovernanceIdentity(target, source) {
-    if (target.governance.profile === 'none' ||
-        target.governance.profile === 'unspecified' ||
-        source.governance.profile === 'none' ||
-        source.governance.profile === 'unspecified') {
-        return;
-    }
-    target.governance.policyVersion = source.governance.policyVersion;
-    if (source.governance.activationIdentity) {
-        target.governance.activationIdentity = source.governance.activationIdentity;
+import { loadManifest } from '../project/manifest.js';
+import { requestUpdateApproval } from './approval.js';
+import { formatUpdateCommand, formatUpdateValidationCommands } from './command-guidance.js';
+import { inspectProjectUpdate, UpdatePlanError } from './inspection.js';
+import { buildUpdateReport, renderUpdateApprovalScope, renderUpdatePreview, renderUpdateSkipped } from './output.js';
+import { assertAuthorizedUpdateMutations, preflightUpdate } from './planning.js';
+import { matchUpdatePreviewReceipt, UpdatePreviewError } from './preview.js';
+import { prepareUpdateReview } from './review-plan.js';
+import { entryDisplay, maybeInjectUpdateFailure } from './reporting.js';
+import { describeUpdateMigration, describeUpdateRevalidation, materializeUpdateMutations, runUpdateRevalidation, verifyHistoryBeforeReplacement } from './migration-runtime.js';
+function storeOptions(context, inspection) {
+    return {
+        ...context.updatePreview,
+        env: context.updatePreview?.env ?? context.env,
+        clock: context.updatePreview?.clock ?? context.updateNow,
+        ...(inspection?.repositoryRoot ? { repositoryRoot: inspection.repositoryRoot } : {})
+    };
+}
+function emit(context, jsonMode, report, inspection, review) {
+    if (jsonMode) {
+        context.presentation.rawStdout(`${JSON.stringify(buildUpdateReport(report, inspection, review?.writePlan), null, 2)}\n`);
     }
-    else {
-        delete target.governance.activationIdentity;
+    else if (report.message) {
+        if (report.status === 'blocked' || report.status === 'failed') {
+            context.presentation.error(report.message, report.remedy);
+        }
+        else {
+            context.presentation.status(report.status === 'partial' ? 'warning' : 'success', 'Project update', report.message);
+            if (report.remedy)
+                context.presentation.remedy(report.remedy);
+        }
     }
 }
 export async function updateProject(request, context) {
     const { presentation } = context;
-    const { check, force, jsonMode, project: explicit } = request;
-    presentation.commandIdentity('update', 'Reconcile Liftoff-managed core files');
-    if (force && check) {
-        presentation.error('--force cannot be combined with --check.', 'Run `liftoff update --check` to inspect drift or `liftoff update --force` to overwrite conflicts.');
-        return 1;
-    }
-    const projectRoot = explicit ? path.resolve(context.cwd, explicit) : await findProjectRoot(context.cwd);
-    if (!projectRoot) {
-        presentation.error(`No liftoff.manifest.json found in ${context.cwd} or any parent directory.`, 'Run this command inside a Liftoff project or provide its path explicitly.');
-        return 1;
-    }
-    const initialUpdateSnapshots = check
-        ? []
-        : await Promise.all([
-            captureProjectFileSnapshot(projectRoot, ['liftoff.manifest.json']),
-            captureProjectFileSnapshot(projectRoot, ['liftoff.config.json'])
-        ]);
-    const manifest = await loadManifest(projectRoot);
-    const oldByName = new Map(manifest.managedArtifacts.map((artifact) => [artifact.logicalName, artifact]));
-    if (compareSemver(manifest.liftoffVersion, liftoffVersion) > 0) {
-        presentation.error(`This project was written by Liftoff ${manifest.liftoffVersion}, which is newer than this CLI (${liftoffVersion}).`, 'Upgrade the CLI first.');
-        return 1;
-    }
-    const config = await loadConfigOptions('liftoff.config.json', projectRoot);
-    const recordedWorkload = manifest.project.workload;
-    if (config.cloud !== undefined && config.cloud !== recordedWorkload.cloud) {
-        presentation.error(`Cloud changes (${recordedWorkload.cloud} -> ${config.cloud}) are a migration, not an update.`, 'Restore liftoff.config.json or perform the cloud change through a separately reviewed project migration.');
-        return 1;
-    }
-    const plan = buildProjectPlan(config, { requireProjectName: true });
-    if (plan.projectName !== manifest.project.name) {
-        presentation.error(`Project name changes (${manifest.project.name} -> ${plan.projectName}) are a migration, not an update.`, 'Restore liftoff.config.json or perform the rename through a separately reviewed project migration.');
-        return 1;
-    }
-    if (plan.workload !== recordedWorkload.kind) {
-        presentation.error(`Project type changes (${recordedWorkload.kind} -> ${plan.workload}) are not supported by update.`, 'Initialize a fresh project and move production behavior through a reviewed project change.');
-        return 1;
-    }
-    {
-        if (plan.provider.id !== recordedWorkload.cloud) {
-            presentation.error(`Cloud changes (${recordedWorkload.cloud} -> ${plan.provider.id}) are a migration, not an update.`, 'Restore liftoff.config.json or perform the cloud change through a separately reviewed project migration.');
-            return 1;
-        }
-        if (plan.region.slug !== recordedWorkload.region) {
-            presentation.error(`Region changes (${recordedWorkload.region} -> ${plan.region.slug}) are a migration, not an update.`, 'Restore liftoff.config.json or perform the region change through a separately reviewed project migration.');
-            return 1;
+    const { check, force, jsonMode } = request;
+    presentation.commandIdentity('update', 'Preview and explicitly approve scoped project updates');
+    let projectRoot = request.project ? path.resolve(context.cwd, request.project) : context.cwd;
+    let inspection;
+    let selected;
+    let committed = false;
+    let migration;
+    let revalidation;
+    try {
+        if (check && (force || request.approvePlan !== undefined)) {
+            throw new UpdatePlanError('--check cannot be combined with --force or --approve-plan.', 'invalid-update-options', `Run ${formatUpdateCommand(projectRoot, 'check')} before explicitly approving an apply plan.`);
         }
-        if (plan.apiStack.id !== recordedWorkload.apiStack) {
-            presentation.error(`API stack changes (${recordedWorkload.apiStack} -> ${plan.apiStack.id}) are a migration, not an update.`, 'Initialize a fresh project and move production behavior through a reviewed project change.');
-            return 1;
+        const discovered = request.project ? projectRoot : await findProjectRoot(context.cwd);
+        if (!discovered) {
+            throw new UpdatePlanError(`No liftoff.manifest.json found in ${context.cwd} or any parent directory.`, 'project-not-found', 'Run inside a Liftoff project or supply its path.');
         }
-        const recordedPattern = recordedWorkload.kind === 'genai' ? recordedWorkload.pattern : undefined;
-        const desiredPattern = plan.workload === 'genai' ? plan.pattern.id : undefined;
-        if (desiredPattern !== recordedPattern) {
-            presentation.error(`Pattern changes (${recordedPattern ?? 'none'} -> ${desiredPattern ?? 'none'}) are a migration, not an update.`, 'Use a separately reviewed project migration; the existing migrate command only adopts non-Liftoff sources into a fresh target.');
-            return 1;
+        projectRoot = discovered;
+        await loadManifest(projectRoot);
+        const initialOptions = storeOptions(context);
+        const approvalStore = createUpdateTransactionApprovalStore(projectRoot, initialOptions);
+        const recovery = await inspectReviewedUpdateTransaction(projectRoot, { approvalStore });
+        if (recovery.status !== 'absent') {
+            if (check || recovery.status === 'blocked') {
+                emit(context, jsonMode, {
+                    mode: check ? 'check' : 'apply', status: 'blocked',
+                    reasonCode: 'transaction-recovery-required', projectRoot, committed: recovery.committed,
+                    message: recovery.reason ?? 'An interrupted approved update requires bounded recovery.',
+                    remedy: `Review the reported transaction and run ${formatUpdateCommand(projectRoot)} for recovery; then run ${formatUpdateCommand(projectRoot, 'check')}.`
+                });
+                return 1;
+            }
+            const outcome = await recoverReviewedUpdateTransaction(projectRoot, { approvalStore });
+            emit(context, jsonMode, {
+                mode: 'apply', status: outcome.status === 'blocked' ? 'failed' : 'partial',
+                reasonCode: 'transaction-recovery', projectRoot, committed: outcome.committed,
+                message: outcome.status === 'blocked'
+                    ? outcome.rollbackFailures.join('; ')
+                    : 'Recovered the previously approved transaction; no new update was started.',
+                warnings: outcome.cleanupFailures,
+                remedy: `Run ${formatUpdateCommand(projectRoot, 'check')} before approving new work.`
+            });
+            return outcome.status === 'blocked' ? 1 : 2;
         }
-    }
-    if (manifest.governance.profile !== 'none' &&
-        manifest.governance.profile !== 'unspecified' &&
-        plan.governanceProfile.id === 'none' &&
-        await readProjectFile(projectRoot, [...activationStateFilePathParts]) !== undefined) {
-        presentation.error('Repository governance cannot be disabled by update while governance/activation-state.json exists.', 'Restore liftoff.config.json or complete a separately supported deactivation and reconciliation workflow before disabling governance. This Liftoff release does not infer deactivation or the absence of live enforcement.');
-        return 1;
-    }
-    if (plan.specWorkflow.id !== manifest.project.specWorkflow) {
-        presentation.error(`Spec workflow changes (${manifest.project.specWorkflow} -> ${plan.specWorkflow.id}) require official framework initialization and are not supported by liftoff update.`, 'Restore the workflow recorded in liftoff.manifest.json or migrate into a fresh project.');
-        return 1;
-    }
-    const configuredAgents = plan.agents.map((agent) => agent.id);
-    if (manifest.framework.state === 'initialized' && (configuredAgents.length !== manifest.project.agents.length ||
-        configuredAgents.some((agent, index) => agent !== manifest.project.agents[index]) ||
-        plan.defaultAgent?.id !== manifest.project.defaultAgent)) {
-        presentation.error('AI agent or default-agent changes require official framework initialization and are not supported by liftoff update.', 'Restore liftoff.config.json to the integrations recorded in liftoff.manifest.json.');
-        return 1;
-    }
-    let desiredRenderPlan = manifest.framework.state === 'legacy'
-        ? { ...plan, agents: [], defaultAgent: undefined }
-        : plan;
-    const stateMigration = await planHistoricalActivationStateMigration(projectRoot);
-    const desiredRender = buildUpdateArtifacts(desiredRenderPlan, manifest);
-    let provisioningPlans = await inspectProvisioningGroups(projectRoot, desiredRender, requestedProvisioningGroups(manifest, desiredRenderPlan));
-    if (stateMigration.report.diagnosticOnly === true) {
-        provisioningPlans = provisioningPlans.map((group) => ({
-            ...group,
-            entries: [],
-            blocked: true,
-            reason: 'Historical activation v1 is diagnostic-only. This update may maintain managed core but cannot provision project-owned components.'
-        }));
-    }
-    const renderPlan = planWithBlockedProvisioning(desiredRenderPlan, recordedWorkload, provisioningPlans);
-    const render = buildUpdateArtifacts(renderPlan, manifest);
-    const scopedRender = [
-        ...render.filter((artifact) => artifact.lifecycle === 'managed-core'),
-        ...desiredRender.filter((artifact) => artifact.lifecycle === 'project' &&
-            provisioningPlans.some((group) => !group.blocked && group.group === artifact.provisioningGroup))
-    ];
-    const updateSnapshots = check
-        ? []
-        : await captureUpdateSnapshots(projectRoot, manifest, scopedRender, initialUpdateSnapshots);
-    const entries = await reconcileProject(manifest, render, projectRoot);
-    const summary = summarizeEntries(entries);
-    const ownershipMigrationPending = manifest.artifactVersion !== 7 ||
-        manifestHadFilteredLegacyNonDurableOwnership(manifest);
-    const plannedManifest = buildManifest(renderPlan, render, {
-        frameworkState: manifest.framework.state,
-        projectArtifacts: manifest.projectArtifacts
-    });
-    if (stateMigration.report.diagnosticOnly === true) {
-        preserveDiagnosticGovernanceIdentity(plannedManifest, manifest);
-    }
-    const plannedManifestChanges = manifestChanges(manifest, plannedManifest);
-    const reconciliation = combineReconciliationReports([
-        stateMigrationReconciliation(stateMigration),
-        await activeChangeReconciliationReport(projectRoot)
-    ]);
-    if (reconciliation.status === 'blocked') {
-        const blockedReport = {
-            schemaVersion: 2,
-            mode: check ? 'check' : 'apply',
-            scope: 'managed-core',
-            status: 'blocked',
-            cliVersion: liftoffVersion,
-            projectVersion: manifest.liftoffVersion,
-            entries: [],
-            removed: [],
-            provisioning: [],
-            ownershipMigrationPending: false,
-            manifestChanges: plannedManifestChanges,
-            activationStateMigration: stateMigration.report,
-            reconciliation,
-            summary
+        inspection = await inspectProjectUpdate(projectRoot, { runner: context.runner });
+        projectRoot = inspection.projectRoot;
+        const options = storeOptions(context, inspection);
+        const reviewOptions = { runner: context.runner, now: context.updateNow?.() ?? new Date() };
+        const normal = await prepareUpdateReview(inspection, false, reviewOptions);
+        const forced = await prepareUpdateReview(inspection, true, reviewOptions);
+        const variants = [normal, forced];
+        const hasWork = inspection.hasDrift || variants.some((entry) => entry.requiresApproval);
+        const plans = hasWork ? variants.map((entry) => entry.summary) : [];
+        selected = force ? forced : normal;
+        migration = describeUpdateMigration(inspection);
+        committed = migration.status === 'committed';
+        revalidation = describeUpdateRevalidation(selected);
+        const base = {
+            mode: check ? 'check' : 'apply', projectRoot,
+            plans, selectedPlanFingerprint: selected.descriptor.fingerprint, migration, revalidation
         };
-        if (jsonMode) {
-            presentation.rawStdout(`${JSON.stringify(blockedReport, null, 2)}\n`);
+        if (!selected.summary.eligible && (!check || !variants.some((entry) => entry.summary.eligible))) {
+            emit(context, jsonMode, {
+                ...base, status: 'blocked', reasonCode: 'incompatible-update',
+                message: selected.summary.blockers.join('; '),
+                remedy: inspection.reconciliation.remedy
+            }, inspection, selected);
+            return 1;
         }
-        else {
-            presentation.status('error', 'Managed update blocked', reconciliation.issues.join('; '));
-            if (reconciliation.remedy) {
-                presentation.remedy(reconciliation.remedy);
+        if (check) {
+            const stored = hasWork
+                ? await issueUpdatePreviewReceipt(projectRoot, variants.filter((entry) => entry.summary.eligible).map((entry) => entry.descriptor), options)
+                : undefined;
+            if (!jsonMode) {
+                renderUpdatePreview(presentation, inspection, plans, migration, revalidation, stored?.location.receiptPath);
+                if (!hasWork) {
+                    presentation.status('success', 'Liftoff core is current', `${inspection.summary.unchanged} managed-core artifacts match; project files are not compared`);
+                }
+                else {
+                    presentation.status('warning', 'Liftoff core maintenance available', `${inspection.summary.conflict + inspection.summary.retiredConflict} core conflict(s); review the exact plans before approval`);
+                }
             }
+            emit(context, jsonMode, {
+                ...base,
+                status: hasWork ? 'update-available' : 'current',
+                reasonCode: hasWork ? 'review-required' : 'no-update',
+                receipt: stored ? { status: 'issued', path: stored.location.receiptPath } : { status: 'not-required' }
+            }, inspection, selected);
+            return hasWork ? 2 : 0;
         }
-        return 1;
-    }
-    const workloadIntentChanged = !sameWorkloadIntent(plannedManifest.project.workload, manifest.project.workload);
-    const manifestRewritePending = ownershipMigrationPending ||
-        workloadIntentChanged;
-    const drift = hasDrift(entries) ||
-        manifestRewritePending ||
-        provisioningPlans.length > 0 ||
-        stateMigration.status === 'migrate';
-    const visible = entries.filter((entry) => entry.status !== 'unchanged' || entry.refreshHash);
-    if (!drift) {
-        if (jsonMode) {
-            presentation.rawStdout(`${JSON.stringify(check ? {
-                schemaVersion: 2,
-                mode: 'check',
-                scope: 'managed-core',
-                status: reconciliation.status === 'reconciliation-required' ? 'reconciliation-required' : 'current',
-                cliVersion: liftoffVersion,
-                projectVersion: manifest.liftoffVersion,
-                entries: [],
-                provisioning: [],
-                ownershipMigrationPending,
-                manifestChanges: plannedManifestChanges,
-                activationIdentity: manifest.governance.profile !== 'none' && manifest.governance.profile !== 'unspecified'
-                    ? manifest.governance.activationIdentity ?? null
-                    : null,
-                activationStateMigration: stateMigration.report,
-                reconciliation,
-                summary
-            } : {
-                schemaVersion: 2,
-                mode: 'apply',
-                scope: 'managed-core',
-                status: reconciliation.status === 'reconciliation-required' ? 'reconciliation-required' : 'current',
-                cliVersion: liftoffVersion,
-                projectVersion: manifest.liftoffVersion,
-                written: [],
-                removed: [],
-                skipped: [],
-                provisioning: [],
-                ownershipMigrationPending,
-                manifestChanges: plannedManifestChanges,
-                activationIdentity: manifest.governance.profile !== 'none' && manifest.governance.profile !== 'unspecified'
-                    ? manifest.governance.activationIdentity ?? null
-                    : null,
-                activationStateMigration: stateMigration.report,
-                reconciliation,
-                summary
-            }, null, 2)}\n`);
+        if (!selected.requiresApproval) {
+            if (!jsonMode)
+                renderUpdateSkipped(presentation, inspection, selected.writePlan);
+            emit(context, jsonMode, {
+                ...base, status: selected.writePlan.skipped.length ? 'partial' : 'current', reasonCode: 'no-update',
+                message: selected.writePlan.skipped.length
+                    ? 'No safe update writes are required; listed conflicts remain protected.'
+                    : 'Liftoff core is current; project files were not changed.'
+            }, inspection, selected);
             return 0;
         }
-        presentation.definitions('Project versions', [
-            { label: 'Liftoff CLI', value: liftoffVersion },
-            { label: 'Project generated by', value: manifest.liftoffVersion }
-        ]);
-        presentation.status('success', 'Liftoff core is current', `${summary.unchanged} managed-core artifacts match; project files are not compared`);
-        if (stateMigration.report.diagnosticOnly === true) {
-            presentation.status('warning', 'Historical activation remains diagnostic-only', 'Managed-core is current; activation v1 state and evidence were preserved without migration, retagging, or execution authority.');
+        const location = await resolveUpdatePreviewLocation(projectRoot, options);
+        const stored = await loadUpdatePreviewReceipt(projectRoot, options);
+        matchUpdatePreviewReceipt(stored.receipt, selected.descriptor);
+        if (inspection.repositoryRoot) {
+            const warning = 'If this worktree has uncommitted changes, consider committing or copying them before applying. Liftoff does not commit automatically.';
+            if (jsonMode)
+                presentation.rawStderr(`Warning: ${warning}\n`);
+            else
+                presentation.warning(warning);
         }
-        return 0;
-    }
-    if (check) {
-        if (jsonMode) {
-            presentation.rawStdout(`${JSON.stringify({
-                schemaVersion: 2,
-                mode: 'check',
-                scope: 'managed-core',
-                cliVersion: liftoffVersion,
-                projectVersion: manifest.liftoffVersion,
-                entries: visible.map((entry) => ({
-                    logicalName: entry.logicalName,
-                    status: entry.status,
-                    path: manifestDisplayPath(entry.pathParts),
-                    previousPath: entry.previousPathParts ? manifestDisplayPath(entry.previousPathParts) : undefined,
-                    fileDeleted: entry.status === 'retired' || entry.status === 'retired-conflict'
-                        ? entry.destinationOccupied !== false
-                        : undefined,
-                    reason: entry.reason
-                })),
-                provisioning: provisioningJson(provisioningPlans),
-                ownershipMigrationPending,
-                manifestChanges: plannedManifestChanges,
-                activationIdentity: plannedManifest.governance.profile !== 'none' && plannedManifest.governance.profile !== 'unspecified'
-                    ? plannedManifest.governance.activationIdentity ?? null
-                    : null,
-                activationStateMigration: stateMigration.report,
-                reconciliation,
-                summary
-            }, null, 2)}\n`);
-            return 2;
+        renderUpdateApprovalScope(presentation, jsonMode, selected.summary, selected.writePlan, migration, revalidation);
+        const approval = await requestUpdateApproval({
+            fingerprint: selected.descriptor.fingerprint, approvePlan: request.approvePlan
+        }, context);
+        if (approval.status !== 'approved') {
+            emit(context, jsonMode, {
+                ...base, status: 'blocked', reasonCode: `approval-${approval.status}`,
+                receipt: { status: 'matched', path: location.receiptPath }, approval,
+                message: approval.status === 'required'
+                    ? 'Explicit approval of this exact update plan is required.'
+                    : approval.status === 'mismatch'
+                        ? 'The approved fingerprint does not match the current effective plan.'
+                        : 'Update approval was declined or cancelled; no project files changed.',
+                remedy: `Review ${formatUpdateCommand(projectRoot, 'check')}, then approve interactively or use --approve-plan with its exact fingerprint.`
+            }, inspection, selected);
+            return 1;
         }
-        presentation.definitions('Project versions', [
-            { label: 'Liftoff CLI', value: liftoffVersion },
-            { label: 'Project generated by', value: manifest.liftoffVersion }
+        presentation.stage('Apply safe Liftoff core changes', projectRoot);
+        await preflightUpdate(projectRoot, inspection.entries, force, inspection.oldByName);
+        maybeInjectUpdateFailure(context.env, 'after-preflight');
+        const materialized = materializeUpdateMutations(inspection, selected, context.updateNow?.() ?? new Date());
+        const migrationPaths = inspection.historyMigration.status === 'eligible'
+            ? [
+                ...inspection.historyMigration.index.files.map((file) => file.copyPathParts),
+                ...inspection.historyMigration.requiredRetirements.map((entry) => entry.pathParts),
+                ['governance', 'history', inspection.historyMigration.index.snapshotId, 'index.json'],
+                ['governance', 'activation-state.json'], ['governance', 'migration-state.json']
+            ]
+            : [];
+        assertAuthorizedUpdateMutations(materialized.mutations, inspection.entries, inspection.provisioningPlans, [
+            ...inspection.stateMigration.mutations.map((mutation) => mutation.pathParts),
+            ...migrationPaths
         ]);
-        if (visible.length > 0) {
-            if (presentation.stdout.layout === 'plain') {
-                presentation.section('Liftoff core drift', visible.map((entry) => `${entryMarker(entry)} ${entryDisplay(entry)}  ${entry.reason}`));
-            }
-            else {
-                presentation.table('Liftoff core drift', ['Change', 'Artifact', 'Reason'], visible.map((entry) => [entryMarker(entry), entryDisplay(entry), entry.reason]));
+        const approvedFingerprint = selected.descriptor.fingerprint;
+        const validateReview = async () => {
+            const current = await prepareUpdateReview(await inspectProjectUpdate(projectRoot, { runner: context.runner }), force, { runner: context.runner, now: context.updateNow?.() ?? new Date() });
+            if (!current.summary.eligible || current.descriptor.fingerprint !== approvedFingerprint) {
+                throw new UpdatePlanError('The effective update plan changed after review.', 'preview-mismatch', `Run ${formatUpdateCommand(projectRoot, 'check')} again.`);
             }
-        }
-        for (const group of provisioningPlans) {
-            presentation.bullets(`Project component provisioning: ${group.group}`, [
-                ...(group.reason ? [group.reason] : []),
-                ...group.entries.map((entry) => `${entry.status} ${manifestDisplayPath(entry.rendered.pathParts)}  ${entry.reason}`)
-            ]);
-        }
-        const manifestMaintenance = [
-            ownershipMigrationPending
-                ? 'release legacy project artifacts from Liftoff update authority in manifest schema v7; no production file will be written'
-                : undefined,
-            workloadIntentChanged
-                ? 'record the requested project configuration intent after safe provisioning'
-                : undefined
-        ].filter((item) => item !== undefined);
-        if (manifestMaintenance.length > 0) {
-            presentation.bullets('Manifest maintenance', manifestMaintenance);
-        }
-        if (stateMigration.status === 'migrate') {
-            presentation.bullets('Activation-state migration', [
-                `${stateMigration.report.path}: explicit compatibility mapping preserves evidence bytes and stages ${stateMigration.report.reconciliationPath}`
-            ]);
-        }
-        if (reconciliation.status === 'reconciliation-required') {
-            presentation.bullets('Reconciliation required after update', [
-                ...reconciliation.changedIdentityFields.map((field) => `${field.field}: ${JSON.stringify(field.from)} -> ${JSON.stringify(field.to)}`),
-                `invalid phases: ${reconciliation.phaseImpact.invalidPhaseIds.join(', ') || 'none'}`,
-                reconciliation.remedy ?? 'Run governance status/verify before executing affected phases.'
-            ]);
-        }
-        const toWrite = summary.new +
-            summary.missing +
-            summary.upgrade +
-            summary.moved +
-            summary.refresh +
-            provisioningPlans.reduce((count, group) => count + (group.blocked
-                ? 0
-                : group.entries.filter((entry) => entry.status === 'create').length), 0) +
-            (manifestRewritePending ? 1 : 0) +
-            stateMigration.mutations.length;
-        const toRetire = summary.retired;
-        presentation.status('warning', 'Liftoff core maintenance available', `${toWrite} to write, ${toRetire} retired alias ownership record(s) to remove (${summary.retiredRemoved} file deletion(s)), ${summary.conflict + summary.retiredConflict} core conflict(s), ${summary.orphan} core orphan(s), ${summary.unchanged} core unchanged`);
-        if (toWrite > 0 || toRetire > 0) {
-            presentation.command('liftoff update');
-        }
-        const unownedConflicts = entries.filter((entry) => isUnownedUpdateConflict(entry, oldByName));
-        if (unownedConflicts.length > 0) {
-            presentation.bullets('Unowned destinations remain protected', unownedConflicts.map((entry) => `${entryDisplay(entry)}: review and resolve this unowned destination manually; --force cannot overwrite it`));
-        }
-        if (entries.some((entry) => !isUnownedUpdateConflict(entry, oldByName) &&
-            (entry.status === 'conflict' || entry.status === 'retired-conflict' ||
-                entry.status === 'moved' && !entry.cleanMove))) {
-            presentation.command('liftoff update --force');
-        }
-        return 2;
-    }
-    const blockedProvisioning = provisioningPlans.filter((group) => group.blocked);
-    if (isDirtyGitWorktree(projectRoot)) {
-        const warning = 'The project worktree has uncommitted changes; consider committing before applying.';
-        if (jsonMode) {
-            presentation.rawStderr(`Warning: ${warning}\n`);
-        }
-        else {
-            presentation.warning(warning);
-        }
-    }
-    presentation.stage('Apply safe Liftoff core changes', projectRoot);
-    await preflightUpdate(projectRoot, entries, force, oldByName);
-    maybeInjectUpdateFailure(context.env, 'after-preflight');
-    const written = [];
-    const retired = [];
-    const skipped = [];
-    const mutations = [];
-    for (const entry of entries) {
-        switch (entry.status) {
-            case 'new':
-            case 'missing':
-            case 'upgrade':
-                mutations.push({
-                    type: 'write',
-                    pathParts: entry.pathParts,
-                    content: entry.rendered.content
-                });
-                written.push(entry);
-                break;
-            case 'moved':
-                if (!isUnownedUpdateConflict(entry, oldByName) && (entry.cleanMove || force)) {
-                    if (!entry.destinationMatches) {
-                        mutations.push({
-                            type: 'write',
-                            pathParts: entry.pathParts,
-                            content: entry.rendered.content
-                        });
-                    }
-                    mutations.push({ type: 'delete', pathParts: entry.previousPathParts });
-                    written.push(entry);
-                }
-                else {
-                    skipped.push(entry);
-                }
-                break;
-            case 'retired':
-                mutations.push({ type: 'delete', pathParts: entry.pathParts });
-                retired.push(entry);
-                break;
-            case 'retired-conflict':
-                if (force) {
-                    mutations.push({ type: 'delete', pathParts: entry.pathParts });
-                    retired.push(entry);
-                }
-                else {
-                    skipped.push(entry);
-                }
-                break;
-            case 'conflict':
-                if (force && !isUnownedUpdateConflict(entry, oldByName)) {
-                    mutations.push({
-                        type: 'write',
-                        pathParts: entry.pathParts,
-                        content: entry.rendered.content
-                    });
-                    if (entry.previousPathParts) {
-                        mutations.push({ type: 'delete', pathParts: entry.previousPathParts });
-                    }
-                    written.push(entry);
-                }
-                else {
-                    skipped.push(entry);
+        };
+        const cleanupFailures = [];
+        if (materialized.mutations.length) {
+            const activeInspection = inspection;
+            const outcome = await applyReviewedUpdateTransaction(projectRoot, materialized.mutations, {
+                planFingerprint: approvedFingerprint,
+                approvalStore: createUpdateTransactionApprovalStore(projectRoot, options),
+                preconditions: selected.preconditions,
+                validatePlan: validateReview,
+                onBeforeMutation: async (mutation, index) => {
+                    maybeInjectUpdateFailure(context.env, `before-mutation:${index}`);
+                    maybeInjectUpdateFailure(context.env, `before-path:${mutation.pathParts.join('/')}`);
+                    await verifyHistoryBeforeReplacement(activeInspection, mutation);
                 }
-                break;
-            default:
-                break;
-        }
-    }
-    const provisioned = [];
-    for (const group of provisioningPlans) {
-        if (group.blocked) {
-            continue;
-        }
-        for (const entry of group.entries) {
-            if (entry.status === 'create') {
-                mutations.push({
-                    type: 'write',
-                    pathParts: entry.rendered.pathParts,
-                    content: entry.rendered.content
-                });
+            });
+            committed = outcome.committed;
+            cleanupFailures.push(...outcome.cleanupFailures);
+            if (!committed) {
+                throw new UpdatePlanError(outcome.rollbackFailures.join('; ') || 'The approved update did not commit.', 'transaction-failed', 'Review the recovery details before running a new check.');
             }
-            provisioned.push(entry);
+            if (migration.status === 'available')
+                migration = { ...migration, status: 'committed' };
         }
-    }
-    for (const mutation of stateMigration.mutations) {
-        mutations.push(mutation);
-    }
-    const skippedByName = new Map(skipped.map((entry) => [entry.logicalName, entry]));
-    const hasUnrecordedGovernanceConflict = skipped.some((entry) => entry.status === 'conflict' &&
-        entry.rendered?.category === 'governance' &&
-        !oldByName.has(entry.logicalName));
-    const hasProtectedRetiredAlias = skipped.some((entry) => entry.status === 'retired-conflict');
-    const nextProjectArtifacts = appendProvisionedProjectArtifacts(manifest.projectArtifacts, provisioningPlans);
-    const nextManifest = buildManifest(renderPlan, render.filter((artifact) => artifact.logicalName !== 'manifest'), {
-        frameworkState: manifest.framework.state,
-        projectArtifacts: nextProjectArtifacts
-    });
-    nextManifest.framework = manifest.framework;
-    nextManifest.project.specWorkflow = manifest.project.specWorkflow;
-    nextManifest.project.agents = manifest.project.agents;
-    if (manifest.project.defaultAgent) {
-        nextManifest.project.defaultAgent = manifest.project.defaultAgent;
-    }
-    else {
-        delete nextManifest.project.defaultAgent;
-    }
-    if ((hasUnrecordedGovernanceConflict || hasProtectedRetiredAlias) &&
-        nextManifest.governance.profile !== 'none') {
-        nextManifest.governance.state = 'handoff-partial';
-    }
-    if (stateMigration.report.diagnosticOnly === true) {
-        preserveDiagnosticGovernanceIdentity(nextManifest, manifest);
-    }
-    nextManifest.managedArtifacts = nextManifest.managedArtifacts.flatMap((artifact) => {
-        if (!skippedByName.has(artifact.logicalName)) {
-            return [artifact];
+        if (selected.needsRevalidation && !cleanupFailures.length) {
+            revalidation = await runUpdateRevalidation(inspection, selected, context, materialized.mutations.length ? undefined : validateReview);
         }
-        const previous = oldByName.get(artifact.logicalName);
-        if (!previous) {
-            return [];
-        }
-        return [{ ...artifact, pathParts: previous.pathParts, contentHash: previous.contentHash }];
-    });
-    for (const entry of entries) {
-        if (entry.status === 'orphan') {
-            const previous = oldByName.get(entry.logicalName);
-            if (plan.governanceProfile.id === 'none' &&
-                previous.category === 'governance') {
-                continue;
+        await consumeUpdatePreviewReceipt(projectRoot, stored.receipt, options);
+        const revalidationBlocked = revalidation.status === 'blocked';
+        const partial = revalidationBlocked || selected.writePlan.skipped.length > 0 ||
+            inspection.provisioningPlans.some((group) => group.blocked);
+        emit(context, jsonMode, {
+            ...base, migration, revalidation,
+            status: cleanupFailures.length ? 'failed' : partial ? 'partial' : 'applied',
+            reasonCode: cleanupFailures.length ? 'transaction-cleanup' :
+                revalidationBlocked ? 'revalidation-blocked' : 'approved-update-applied',
+            receipt: { status: 'consumed', path: location.receiptPath }, approval, committed,
+            warnings: cleanupFailures
+        }, inspection, selected);
+        if (!jsonMode) {
+            if (selected.writePlan.written.length) {
+                presentation.bullets('Applied Liftoff core changes', selected.writePlan.written.map((entry) => `wrote ${entryDisplay(entry)}`));
             }
-            nextManifest.managedArtifacts.push(previous);
-        }
-        if (entry.status === 'retired-conflict' && !force) {
-            const previous = oldByName.get(entry.logicalName);
-            if (plan.governanceProfile.id === 'none' &&
-                previous.category === 'governance') {
-                continue;
+            if (selected.writePlan.retired.length) {
+                presentation.bullets('Removed retired Liftoff aliases', selected.writePlan.retired.map((entry) => `removed ${manifestDisplayPath(entry.pathParts)}`));
+            }
+            renderUpdateSkipped(presentation, inspection, selected.writePlan);
+            if (migration.status === 'committed') {
+                presentation.status('success', 'Activation migration committed', 'Original v1 history remains preserved; active v2 readiness is reported separately.');
+            }
+            if (revalidationBlocked) {
+                presentation.bullets('V2 revalidation is blocked and resumable', [
+                    ...revalidation.issues,
+                    ...(revalidation.nextPhase ? [`Next incomplete phase: ${revalidation.nextPhase}`] : []),
+                    `Repair the blocker, run ${formatUpdateCommand(projectRoot, 'check')}, and approve the remaining local work.`
+                ]);
+            }
+            for (const failure of cleanupFailures)
+                presentation.error(failure);
+            if (!cleanupFailures.length && !revalidationBlocked) {
+                presentation.completion('Updated project', `${selected.writePlan.written.length} core written, ${selected.writePlan.skipped.length} core skipped`, [], formatUpdateValidationCommands(projectRoot));
             }
-            nextManifest.managedArtifacts.push(previous);
         }
+        return cleanupFailures.length ? 1 : revalidationBlocked ? 2 : 0;
+    }
+    catch (error) {
+        const reasonCode = error instanceof UpdatePlanError ? error.reasonCode :
+            error instanceof UpdatePreviewError ? error.code : 'update-failed';
+        const detail = error instanceof Error ? error.message : String(error);
+        const message = error instanceof UpdatePreviewError && !committed
+            ? `${detail} No new project update was performed.` : detail;
+        const remedy = error instanceof UpdatePlanError ? error.remedy :
+            error instanceof UpdatePreviewError
+                ? `Repair any reported preview-storage issue, then run ${formatUpdateCommand(projectRoot, 'check')} before applying.`
+                : `Review the reported failure. Preserve concurrent edits and run ${formatUpdateCommand(projectRoot, 'check')} after repair.`;
+        emit(context, jsonMode, {
+            mode: check ? 'check' : 'apply', status: 'failed', reasonCode, projectRoot,
+            committed, message, remedy, migration, revalidation
+        }, inspection, selected);
+        return 1;
     }
-    parseManifest(JSON.parse(JSON.stringify(nextManifest)));
-    mutations.push({
-        type: 'write',
-        pathParts: ['liftoff.manifest.json'],
-        content: `${JSON.stringify(nextManifest, null, 2)}\n`
-    });
-    assertAuthorizedUpdateMutations(mutations, entries, provisioningPlans, stateMigration.mutations.map((mutation) => mutation.pathParts));
-    await applyProjectFileTransaction(projectRoot, mutations, {
-        onBeforeMutation: async (mutation, index) => {
-            maybeInjectUpdateFailure(context.env, `before-mutation:${index}`);
-            maybeInjectUpdateFailure(context.env, `before-path:${mutation.pathParts.join('/')}`);
-        },
-        preconditions: [
-            ...selectUpdatePreconditions(updateSnapshots, entries, mutations, provisioned.map((entry) => entry.rendered.pathParts)),
-            ...stateMigration.preconditions
-        ]
-    });
-    if (jsonMode) {
-        presentation.rawStdout(`${JSON.stringify({
-            schemaVersion: 2,
-            mode: 'apply',
-            scope: 'managed-core',
-            status: blockedProvisioning.length > 0 || skipped.length > 0
-                ? 'partial'
-                : reconciliation.status === 'reconciliation-required'
-                    ? 'reconciliation-required'
-                    : 'applied',
-            cliVersion: liftoffVersion,
-            projectVersion: manifest.liftoffVersion,
-            written: written.map((entry) => manifestDisplayPath(entry.pathParts)),
-            removed: retired.map((entry) => ({
-                logicalName: entry.logicalName,
-                status: entry.status === 'retired-conflict'
-                    ? 'force-retired'
-                    : entry.destinationOccupied === false
-                        ? 'retired-absent'
-                        : 'retired',
-                path: manifestDisplayPath(entry.pathParts),
-                fileDeleted: entry.destinationOccupied !== false,
-                reason: entry.reason
-            })),
-            stateWritten: stateMigration.mutations.map((mutation) => manifestDisplayPath(mutation.pathParts)),
-            skipped: skipped.map((entry) => ({
-                logicalName: entry.logicalName,
-                status: entry.status,
-                path: manifestDisplayPath(entry.pathParts),
-                reason: entry.reason
-            })),
-            provisioning: provisioningJson(provisioningPlans),
-            ownershipMigrationPending,
-            manifestChanges: manifestChanges(manifest, nextManifest),
-            activationIdentity: nextManifest.governance.profile !== 'none' && nextManifest.governance.profile !== 'unspecified'
-                ? nextManifest.governance.activationIdentity ?? null
-                : null,
-            activationStateMigration: stateMigration.report,
-            reconciliation,
-            summary
-        }, null, 2)}\n`);
-        return 0;
-    }
-    if (written.length > 0) {
-        presentation.bullets('Applied Liftoff core changes', written.map((entry) => `wrote ${entryDisplay(entry)}`));
-    }
-    const retiredDeleted = retired.filter((entry) => entry.destinationOccupied !== false);
-    const retiredAbsent = retired.filter((entry) => entry.destinationOccupied === false);
-    if (retiredDeleted.length > 0) {
-        presentation.bullets('Removed retired Liftoff aliases', retiredDeleted.map((entry) => `removed ${entryDisplay(entry)}  ${entry.reason}`));
-    }
-    if (retiredAbsent.length > 0) {
-        presentation.bullets('Retired absent Liftoff alias ownership', retiredAbsent.map((entry) => `removed manifest ownership for ${entryDisplay(entry)}  ${entry.reason}`));
-    }
-    if (stateMigration.status === 'migrate') {
-        presentation.bullets('Migrated activation state', stateMigration.mutations.map((mutation) => `wrote ${manifestDisplayPath(mutation.pathParts)}; evidence bytes preserved`));
-    }
-    if (provisioned.length > 0) {
-        presentation.bullets('Provisioned project components', provisioned.map((entry) => `${entry.status === 'create' ? 'wrote' : 'adopted'} ${manifestDisplayPath(entry.rendered.pathParts)}`));
-    }
-    if (blockedProvisioning.length > 0) {
-        presentation.bullets('Blocked project component provisioning', blockedProvisioning.flatMap((group) => [
-            ...(group.reason ? [`${group.group}: ${group.reason}`] : []),
-            ...group.entries
-                .filter((entry) => entry.status === 'conflict')
-                .map((entry) => `${group.group}: preserved ${manifestDisplayPath(entry.rendered.pathParts)}; --force cannot overwrite project-owned bytes`)
-        ]));
-    }
-    if (skipped.length > 0) {
-        presentation.bullets('Skipped Liftoff core conflicts', skipped.map((entry) => isUnownedUpdateConflict(entry, oldByName)
-            ? `protected unowned destination ${entryDisplay(entry)}  ${entry.reason} (resolve manually; --force cannot overwrite it)`
-            : entry.status === 'retired-conflict'
-                ? `protected retired alias ${entryDisplay(entry)}  ${entry.reason}${force ? '' : ' (delete it manually or use --force to remove)'}`
-                : `skipped ${entryDisplay(entry)}  ${entry.reason}${force ? '' : ' (use --force to overwrite)'}`));
-    }
-    const orphans = entries.filter((entry) => entry.status === 'orphan');
-    if (orphans.length > 0) {
-        presentation.bullets('Orphaned Liftoff core artifacts', orphans.map((entry) => `orphan ${entryDisplay(entry)}  ${entry.reason}`));
-    }
-    if (reconciliation.status === 'reconciliation-required') {
-        presentation.bullets('Reconciliation required', [
-            ...reconciliation.changedIdentityFields.map((field) => `${field.field}: ${JSON.stringify(field.from)} -> ${JSON.stringify(field.to)}`),
-            `invalid phases: ${reconciliation.phaseImpact.invalidPhaseIds.join(', ') || 'none'}`,
-            reconciliation.remedy ?? 'Run governance status/verify before executing affected phases.'
-        ]);
-    }
-    presentation.completion('Updated project', [
-        `${written.length} core written`,
-        `${retired.length} retired ownership removed`,
-        `${retiredDeleted.length} retired file deleted`,
-        `${provisioned.length} project provisioned`,
-        ...(blockedProvisioning.length > 0
-            ? [`${blockedProvisioning.length} provisioning group(s) blocked`]
-            : []),
-        `${skipped.length} core skipped`
-    ].join(', '), [{ label: 'Manifest version', value: liftoffVersion }], 'liftoff validate && liftoff doctor');
-    return 0;
 }
 //# sourceMappingURL=use-case.js.map