@iwonz/ywtc 3.6.0 → 4.0.1

package/dist/migrator.js

@@ -5,10 +5,10 @@ import { pathToFileURL } from 'node:url';
 import PQueue from 'p-queue';
 import { createProviderAdapter } from './adapters/factory.js';
 import { secretValues } from './config.js';
-import { appendGridSnapshots, assertDestinationContent, emptyRendererFallbackReason, isLegacyTransferPlaceholder, normalizePageContent, normalizedPreviewHtml, rawContentFallback, renderedPreviewHtml, renderConfluenceStorage, renderYfm, setSourceResourceBinding, sourceResourceBindings, verifyDestinationContent, } from './content-model.js';
+import { appendGridSnapshots, assertDestinationContent, emptyRendererFallbackReason, normalizePageContent, normalizedPreviewHtml, rawContentFallback, renderedPreviewHtml, renderConfluenceStorage, renderYfm, setSourceResourceBinding, sourceResourceBindings, verifyDestinationContent, } from './content-model.js';
 import { commentAttachmentUses, createCommentArchiveZip, renderCommentArchive, renderCommentArchiveIndex, resolveCommentAttachmentReferences, verifyCommentArchive, } from './comments.js';
 import { ConfirmedDestinationMissingError, verifyConfirmedDestinationPage } from './consistency.js';
-import { DestinationTitleConflictError } from './domain.js';
+import { DestinationOwnershipConflictError, DestinationRevisionConflictError, DestinationTitleConflictError } from './domain.js';
 import { assertTransferCapabilities } from './domain.js';
 import { FilesystemExporter } from './filesystem-export.js';
 import { discoverPageGraph } from './graph.js';
@@ -105,6 +105,89 @@ function sourceDerivedTextMatches(expectedBody, actualBody, provider, page) {
     const text = (value) => renderedPreviewHtml(value, provider).replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim();
     return text(expectedBody) === text(actualBody);
 }
+const REVISION_RETRY_DELAYS_MS = [500, 1_000, 2_000];
+async function revisionDelay(attempt, options) {
+    const base = REVISION_RETRY_DELAYS_MS[attempt];
+    const random = options.random ?? Math.random;
+    const delay = Math.max(1, Math.round(base * (0.8 + random() * 0.4)));
+    await (options.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds))))(delay);
+    return delay;
+}
+async function updateMappedPage(input) {
+    let current = input.current;
+    let title = input.title;
+    let retainedMappedTitle = false;
+    for (let attempt = 0;; attempt += 1) {
+        const verification = verifyDestinationContent(input.body, current.content, input.destination.kind, input.sourcePage);
+        if (verification.status === 'complete' && current.title === title) {
+            return { page: current, updated: false, normalized: current.content !== input.body, verification };
+        }
+        try {
+            const result = await input.destination.updatePage({ page: current, title, body: input.body });
+            const confirmed = await verifyConfirmedDestinationPage(input.destination, result, input.consistencyOptions);
+            return {
+                page: confirmed,
+                updated: true,
+                normalized: confirmed.content !== input.body,
+                verification: verifyDestinationContent(input.body, confirmed.content, input.destination.kind, input.sourcePage),
+            };
+        }
+        catch (error) {
+            if (error instanceof DestinationTitleConflictError && !retainedMappedTitle && current.title !== title) {
+                title = current.title;
+                retainedMappedTitle = true;
+                input.report.issue({
+                    code: 'mapped-title-retained',
+                    severity: 'normalization',
+                    phase: 'page',
+                    pageId: input.sourcePage.canonicalId,
+                    retryable: false,
+                    message: `${input.sourcePage.title}: retained mapped destination title "${current.title}" because the source title is occupied`,
+                });
+                continue;
+            }
+            if (!(error instanceof DestinationRevisionConflictError) || attempt >= REVISION_RETRY_DELAYS_MS.length)
+                throw error;
+            const delay = await revisionDelay(attempt, input.consistencyOptions);
+            input.report.issue({
+                code: 'destination-revision-retry',
+                severity: 'normalization',
+                phase: 'page',
+                pageId: input.sourcePage.canonicalId,
+                retryable: true,
+                message: `${input.sourcePage.title}: destination revision changed concurrently; retry ${attempt + 1} after ${delay} ms`,
+            });
+            current = await verifyConfirmedDestinationPage(input.destination, current, input.consistencyOptions);
+        }
+    }
+}
+async function reparentMappedPage(input) {
+    if (!input.destination.reparentPage)
+        throw new Error(`${input.destination.profile.name} does not implement page moves`);
+    let current = input.current;
+    for (let attempt = 0;; attempt += 1) {
+        if (current.parentId === input.parent.id)
+            return current;
+        try {
+            const moved = await input.destination.reparentPage({ page: current, parent: input.parent });
+            return verifyConfirmedDestinationPage(input.destination, moved, input.consistencyOptions);
+        }
+        catch (error) {
+            if (!(error instanceof DestinationRevisionConflictError) || attempt >= REVISION_RETRY_DELAYS_MS.length)
+                throw error;
+            const delay = await revisionDelay(attempt, input.consistencyOptions);
+            input.report.issue({
+                code: 'destination-revision-retry',
+                severity: 'normalization',
+                phase: 'page',
+                pageId: input.sourcePage.canonicalId,
+                retryable: true,
+                message: `${input.sourcePage.title}: destination revision changed during hierarchy repair; retry ${attempt + 1} after ${delay} ms`,
+            });
+            current = await verifyConfirmedDestinationPage(input.destination, current, input.consistencyOptions);
+        }
+    }
+}
 function ambiguousCreateOutcome(error) {
     return error instanceof HttpRequestError
         && (error.status === undefined || error.status >= 500);
@@ -173,21 +256,23 @@ async function createPageWithAllocatedTitle(input) {
     throw new Error(`Confluence rejected all ${candidates.length} deterministic destination titles for ${input.sourcePage.title} because they are occupied`);
 }
 function destinationFromState(state, adapter) {
-    if (!state.destinationId || !state.destinationCanonicalId || !state.destinationLocator) {
+    if (!state.destinationId) {
         throw new Error(`Incomplete mapped destination for ${state.sourceTitle}`);
     }
     return {
         provider: adapter.kind,
         profile: adapter.profile.name,
         id: state.destinationId,
-        canonicalId: state.destinationCanonicalId,
+        canonicalId: state.destinationCanonicalId ?? `${adapter.profile.name}:${adapter.kind}:${state.destinationId}`,
         title: state.destinationTitle,
-        url: state.destinationLocator,
+        url: state.destinationLocator ?? state.destinationId,
         locator: state.destinationId,
         ...(state.destinationFingerprint ? { fingerprint: state.destinationFingerprint } : {}),
+        ...(state.destinationVersion ? { version: state.destinationVersion } : {}),
     };
 }
 function reportPage(input) {
+    const effectiveWarnings = input.warnings ?? input.document.warnings;
     const inventory = input.commentInventory;
     const commentResourceIds = new Set();
     for (const thread of inventory?.threads ?? []) {
@@ -290,11 +375,14 @@ function reportPage(input) {
         tables: input.document.metrics.tables,
         grids: input.resources.filter((resource) => resource.kind === 'grid').length,
         codeBlocks: input.document.metrics.codeBlocks,
-        degraded: input.document.degraded || (input.resourceFallbacks?.length ?? 0) > 0,
+        degraded: effectiveWarnings.length > 0 || (input.resourceFallbacks?.length ?? 0) > 0,
         resourceFallbacks: input.resourceFallbacks ?? [],
-        warnings: [...new Set([...input.document.warnings, ...(input.warnings ?? [])])],
+        warnings: [...new Set(effectiveWarnings)],
         normalizations: [...new Set([...(input.document.normalizations ?? []), ...(input.normalizations ?? [])])],
+        adaptations: [...new Set([...(input.document.adaptations ?? []), ...(input.adaptations ?? [])])],
+        preservedExternalReferences: input.preservedExternalReferences ?? input.document.metrics.preservedExternalReferences,
         ...(input.error ? { error: input.error } : {}),
+        ...(input.conflictEvidence ? { conflictEvidence: input.conflictEvidence } : {}),
         ...(input.status === 'blocked' && input.blockedBy ? input.blockedBy : {}),
         comments: {
             status: commentStatus,
@@ -354,13 +442,14 @@ function runStatus(errors, warnings, degradations) {
         return 'partial';
     return warnings + degradations > 0 ? 'completed-with-warnings' : 'completed';
 }
-function attentionCount(summary) {
-    return summary.warnings + summary.degradations;
-}
 function runOutcomeCounts(summary, pages) {
     return {
         pages,
-        warnings: attentionCount(summary),
+        warnings: summary.warnings,
+        degradations: summary.degradations,
+        adaptations: summary.adaptations,
+        normalizations: summary.normalizations,
+        preservedExternalReferences: summary.preservedExternalReferences,
         errors: summary.errors,
         rootErrors: summary.rootErrors,
         dependentPages: summary.dependentPages,
@@ -432,277 +521,282 @@ export class Migrator {
         });
         const store = new StateStore(stateLocation.filename);
         await store.load(identity, { fresh: options.fresh ?? false, dryRun: options.dryRun });
-        if (!options.dryRun)
-            await store.save();
-        const run = await store.beginRun(options.scope, options.dryRun, sourceStatus, commentsEnabled);
-        const report = new TransferReport({
-            secrets: secretValues(this.config),
-            dryRun: options.dryRun,
-            commentsEnabled,
-            scope: options.scope,
-            sourceStatus,
-            direction: `${source.kind} → ${options.destination.type === 'directory' ? options.destination.format : destination.kind}`,
-            source: { provider: source.kind, profile: source.profile.name, rootId: root.id, title: root.title, url: root.url },
-            destination: options.destination.type === 'directory'
-                ? { provider: 'filesystem', id: options.destination.path, format: options.destination.format }
-                : { provider: destination.kind, profile: destination.profile.name, id: container.id, url: container.url },
-            state: {
-                id: stateLocation.id,
-                path: stateLocation.filename,
-                mode: stateLocation.mode,
-                source: store.loadInfo.source,
-                ...(store.loadInfo.backupFilename ? { backupPath: store.loadInfo.backupFilename } : {}),
-            },
-        });
-        report.registerPages([{ ...root, depth: 0 }]);
-        let graph;
-        let sourceFingerprints;
         try {
-            status(`Discovering ${options.scope} scope from ${root.title}`);
-            graph = await discoverPageGraph({
-                adapter: source,
-                root,
+            if (!options.dryRun)
+                await store.save();
+            const run = await store.beginRun(options.scope, options.dryRun, sourceStatus, commentsEnabled);
+            const report = new TransferReport({
+                secrets: secretValues(this.config),
+                dryRun: options.dryRun,
+                commentsEnabled,
                 scope: options.scope,
                 sourceStatus,
-                ...(options.signal ? { signal: options.signal } : {}),
-                onProgress: (progress) => status(`Discovery: ${progress.pages} pages, ${progress.edges} links${progress.active ? ` · ${progress.active}` : ''}`),
-            });
-            report.registerPages(graph.pages);
-            report.setEdges(graph.edges);
-            report.setSelection(graph.selection);
-            await store.setRunSelection(run.id, graph.selection);
-            for (const warning of graph.warnings)
-                report.warning(warning);
-            if (container
-                && options.destination.type === 'remote'
-                && sameRemoteInstance(options.source.profile, options.destination.profile)
-                && graph.pages.some((page) => page.id === container.id)) {
-                throw new Error('The destination page belongs to the selected source graph. Choose a destination outside the transferred graph.');
-            }
-            status(`Source tree: root ${root.title} · ${graph.selection.returnedDescendants} descendants returned · ${graph.selection.selectedDescendants} selected · ${graph.selection.excluded.length} excluded · depth ${graph.selection.maximumDepth}`);
-            status(`Caching source content for ${graph.pages.length} pages`);
-            sourceFingerprints = await cacheDiscoveredPages(options.cacheDirectory, graph);
-            await store.setGraph(graph.rootId, graph.edges);
-        }
-        catch (error) {
-            const finalStatus = options.signal?.aborted ? 'cancelled' : 'failed';
-            const message = error instanceof Error ? error.message : String(error);
-            report.updatePage(root.canonicalId, { status: 'failed', inventoryStatus: 'failed', error: message });
-            report.issue({
-                code: 'source-discovery-failed',
-                severity: 'error',
-                phase: 'discovery',
-                pageId: root.canonicalId,
-                retryable: true,
-                message,
+                direction: `${source.kind} → ${options.destination.type === 'directory' ? options.destination.format : destination.kind}`,
+                source: { provider: source.kind, profile: source.profile.name, rootId: root.id, title: root.title, url: root.url },
+                destination: options.destination.type === 'directory'
+                    ? { provider: 'filesystem', id: options.destination.path, format: options.destination.format }
+                    : { provider: destination.kind, profile: destination.profile.name, id: container.id, url: container.url },
+                state: {
+                    id: stateLocation.id,
+                    path: stateLocation.filename,
+                    mode: stateLocation.mode,
+                    source: store.loadInfo.source,
+                    ...(store.loadInfo.backupFilename ? { backupPath: store.loadInfo.backupFilename } : {}),
+                },
             });
-            report.finish(finalStatus);
-            const reportPaths = await report.write(options.reportsDirectory);
-            if (!options.dryRun)
-                await store.finishRun(run.id, finalStatus, runOutcomeCounts(report.data.summary, 0));
-            throw new MigrationRunError(message, reportPaths, stateLocation.filename, { cause: error });
-        }
-        const resourcesByPage = new Map();
-        const commentsByPage = new Map();
-        const inventoryQueue = new PQueue({ concurrency: options.concurrency });
-        const inventory = { resources: 0, bytes: 0, unknownSizes: 0, grids: 0, links: 0, images: 0, tables: 0, codeBlocks: 0, commentThreads: 0, comments: 0, commentParticipants: 0, commentAttachments: 0, commentBytes: 0 };
-        status(`Inspecting content and resources for ${graph.pages.length} pages`);
-        const inventoryErrors = [];
-        await Promise.all(graph.pages.map((page) => inventoryQueue.add(async () => {
+            report.registerPages([{ ...root, depth: 0 }]);
+            let graph;
+            let sourceFingerprints;
             try {
-                if (options.signal?.aborted)
-                    throw options.signal.reason ?? new Error('Transfer cancelled');
-                const cachedPage = await loadCachedPage(options.cacheDirectory, page.canonicalId);
-                const resources = await source.listResources(page);
-                resourcesByPage.set(page.canonicalId, resources);
-                let commentInventory;
-                if (commentsEnabled) {
-                    try {
-                        if (!source.readComments)
-                            throw new Error(`${source.profile.name} does not implement comment reads`);
-                        commentInventory = await source.readComments(cachedPage);
-                        resolveCommentAttachmentReferences(commentInventory, resources);
-                        commentsByPage.set(page.canonicalId, commentInventory);
-                        inventory.commentThreads += commentInventory.threads.length;
-                        inventory.comments += commentInventory.comments;
-                        inventory.commentParticipants += commentInventory.participants;
-                        inventory.commentAttachments += commentInventory.attachments;
-                        inventory.commentBytes += commentInventory.knownBytes;
-                        for (const warning of commentInventory.warnings)
-                            report.issue({
-                                code: `comment-inventory-warning:${warning}`,
-                                severity: 'warning',
-                                phase: 'inventory',
-                                pageId: page.canonicalId,
-                                retryable: false,
-                                message: `${page.title}: ${warning}`,
-                            });
-                    }
-                    catch (error) {
-                        const message = `${page.title}: comments could not be read: ${error instanceof Error ? error.message : String(error)}`;
-                        commentInventory = { status: 'failed', threads: [], comments: 0, participants: 0, attachments: 0, knownBytes: 0, unknownSizes: 0, warnings: [], error: message };
-                        commentsByPage.set(page.canonicalId, commentInventory);
-                        report.issue({ code: 'comment-inventory-failed', severity: 'error', phase: 'inventory', pageId: page.canonicalId, retryable: true, message });
-                    }
+                status(`Discovering ${options.scope} scope from ${root.title}`);
+                graph = await discoverPageGraph({
+                    adapter: source,
+                    root,
+                    scope: options.scope,
+                    sourceStatus,
+                    ...(options.signal ? { signal: options.signal } : {}),
+                    onProgress: (progress) => status(`Discovery: ${progress.pages} pages, ${progress.edges} links${progress.active ? ` · ${progress.active}` : ''}`),
+                });
+                report.registerPages(graph.pages);
+                report.setEdges(graph.edges);
+                report.setSelection(graph.selection);
+                await store.setRunSelection(run.id, graph.selection);
+                for (const warning of graph.warnings)
+                    report.warning(warning);
+                if (container
+                    && options.destination.type === 'remote'
+                    && sameRemoteInstance(options.source.profile, options.destination.profile)
+                    && graph.pages.some((page) => page.id === container.id)) {
+                    throw new Error('The destination page belongs to the selected source graph. Choose a destination outside the transferred graph.');
                 }
-                const document = appendGridSnapshots(normalizePageContent(cachedPage), resources);
-                await cacheDocument(options.cacheDirectory, page.canonicalId, document);
-                inventory.resources += resources.filter((resource) => resource.kind !== 'grid').length;
-                inventory.bytes += resources.reduce((total, resource) => total + (resource.size ?? 0), 0);
-                inventory.unknownSizes += resources.filter((resource) => resource.kind !== 'grid' && resource.size === undefined).length;
-                inventory.grids += resources.filter((resource) => resource.kind === 'grid').length;
-                inventory.links += document.metrics.links;
-                inventory.images += document.metrics.images;
-                inventory.tables += document.metrics.tables;
-                inventory.codeBlocks += document.metrics.codeBlocks;
-                report.addPage(reportPage({
-                    page,
-                    status: 'planned',
-                    resources,
-                    document,
-                    commentsEnabled,
-                    ...(commentInventory ? { commentInventory } : {}),
-                }), undefined, false);
-                status(`Inspected ${page.title} · ${resources.length} resources`);
+                status(`Source tree: root ${root.title} · ${graph.selection.returnedDescendants} descendants returned · ${graph.selection.selectedDescendants} selected · ${graph.selection.excluded.length} excluded · depth ${graph.selection.maximumDepth}`);
+                status(`Caching source content for ${graph.pages.length} pages`);
+                sourceFingerprints = await cacheDiscoveredPages(options.cacheDirectory, graph);
+                await store.setGraph(graph.rootId, graph.edges);
             }
             catch (error) {
-                const message = `${page.title}: ${error instanceof Error ? error.message : String(error)}`;
-                inventoryErrors.push(message);
-                report.updatePage(page.canonicalId, { status: 'failed', inventoryStatus: 'failed', error: message });
+                const finalStatus = options.signal?.aborted ? 'cancelled' : 'failed';
+                const message = error instanceof Error ? error.message : String(error);
+                report.updatePage(root.canonicalId, { status: 'failed', inventoryStatus: 'failed', error: message });
                 report.issue({
-                    code: 'source-inventory-failed',
+                    code: 'source-discovery-failed',
                     severity: 'error',
-                    phase: 'inventory',
-                    pageId: page.canonicalId,
+                    phase: 'discovery',
+                    pageId: root.canonicalId,
                     retryable: true,
                     message,
                 });
+                report.finish(finalStatus);
+                const reportPaths = await report.write(options.reportsDirectory);
+                if (!options.dryRun)
+                    await store.finishRun(run.id, finalStatus, runOutcomeCounts(report.data.summary, 0));
+                throw new MigrationRunError(message, reportPaths, stateLocation.filename, { cause: error });
             }
-        })));
-        await store.setRunComments(run.id, { threads: inventory.commentThreads, comments: inventory.comments, attachments: inventory.commentAttachments });
-        if (inventoryErrors.length > 0) {
-            const finalStatus = options.signal?.aborted ? 'cancelled' : 'failed';
-            report.finish(finalStatus);
-            const reportPaths = await report.write(options.reportsDirectory);
-            if (!options.dryRun)
-                await store.finishRun(run.id, finalStatus, runOutcomeCounts(report.data.summary, graph.pages.length));
-            throw new MigrationRunError('Resource preflight failed before destination mutation', reportPaths, stateLocation.filename);
-        }
-        if (!options.dryRun) {
-            for (const page of graph.pages) {
-                if (store.value.pages[page.canonicalId])
-                    continue;
-                const commentInventory = commentsByPage.get(page.canonicalId);
-                const commentState = !commentsEnabled
-                    ? { status: 'skipped', threads: 0, comments: 0, participants: 0, attachments: 0, bytes: 0, updatedAt: new Date().toISOString() }
-                    : commentInventory?.status === 'empty'
-                        ? { status: 'complete', threads: 0, comments: 0, participants: 0, attachments: 0, bytes: 0, updatedAt: new Date().toISOString() }
-                        : commentInventory?.status === 'failed'
-                            ? {
-                                status: 'failed', threads: 0, comments: 0, participants: 0, attachments: 0, bytes: 0,
-                                ...(commentInventory.error ? { lastError: commentInventory.error } : {}), updatedAt: new Date().toISOString(),
-                            }
-                            : commentInventory
+            const resourcesByPage = new Map();
+            const commentsByPage = new Map();
+            const inventoryQueue = new PQueue({ concurrency: options.concurrency });
+            const inventory = { resources: 0, bytes: 0, unknownSizes: 0, grids: 0, links: 0, images: 0, tables: 0, codeBlocks: 0, commentThreads: 0, comments: 0, commentParticipants: 0, commentAttachments: 0, commentBytes: 0 };
+            status(`Inspecting content and resources for ${graph.pages.length} pages`);
+            const inventoryErrors = [];
+            await Promise.all(graph.pages.map((page) => inventoryQueue.add(async () => {
+                try {
+                    if (options.signal?.aborted)
+                        throw options.signal.reason ?? new Error('Transfer cancelled');
+                    const cachedPage = await loadCachedPage(options.cacheDirectory, page.canonicalId);
+                    const resources = await source.listResources(page);
+                    resourcesByPage.set(page.canonicalId, resources);
+                    let commentInventory;
+                    if (commentsEnabled) {
+                        try {
+                            if (!source.readComments)
+                                throw new Error(`${source.profile.name} does not implement comment reads`);
+                            commentInventory = await source.readComments(cachedPage);
+                            resolveCommentAttachmentReferences(commentInventory, resources);
+                            commentsByPage.set(page.canonicalId, commentInventory);
+                            inventory.commentThreads += commentInventory.threads.length;
+                            inventory.comments += commentInventory.comments;
+                            inventory.commentParticipants += commentInventory.participants;
+                            inventory.commentAttachments += commentInventory.attachments;
+                            inventory.commentBytes += commentInventory.knownBytes;
+                            for (const warning of commentInventory.warnings)
+                                report.issue({
+                                    code: `comment-inventory-warning:${warning}`,
+                                    severity: 'warning',
+                                    phase: 'inventory',
+                                    pageId: page.canonicalId,
+                                    retryable: false,
+                                    message: `${page.title}: ${warning}`,
+                                });
+                        }
+                        catch (error) {
+                            const message = `${page.title}: comments could not be read: ${error instanceof Error ? error.message : String(error)}`;
+                            commentInventory = { status: 'failed', threads: [], comments: 0, participants: 0, attachments: 0, knownBytes: 0, unknownSizes: 0, warnings: [], error: message };
+                            commentsByPage.set(page.canonicalId, commentInventory);
+                            report.issue({ code: 'comment-inventory-failed', severity: 'error', phase: 'inventory', pageId: page.canonicalId, retryable: true, message });
+                        }
+                    }
+                    const document = appendGridSnapshots(normalizePageContent(cachedPage), resources);
+                    await cacheDocument(options.cacheDirectory, page.canonicalId, document);
+                    inventory.resources += resources.filter((resource) => resource.kind !== 'grid').length;
+                    inventory.bytes += resources.reduce((total, resource) => total + (resource.size ?? 0), 0);
+                    inventory.unknownSizes += resources.filter((resource) => resource.kind !== 'grid' && resource.size === undefined).length;
+                    inventory.grids += resources.filter((resource) => resource.kind === 'grid').length;
+                    inventory.links += document.metrics.links;
+                    inventory.images += document.metrics.images;
+                    inventory.tables += document.metrics.tables;
+                    inventory.codeBlocks += document.metrics.codeBlocks;
+                    report.addPage(reportPage({
+                        page,
+                        status: 'planned',
+                        resources,
+                        document,
+                        commentsEnabled,
+                        ...(commentInventory ? { commentInventory } : {}),
+                    }), undefined, false);
+                    status(`Inspected ${page.title} · ${resources.length} resources`);
+                }
+                catch (error) {
+                    const message = `${page.title}: ${error instanceof Error ? error.message : String(error)}`;
+                    inventoryErrors.push(message);
+                    report.updatePage(page.canonicalId, { status: 'failed', inventoryStatus: 'failed', error: message });
+                    report.issue({
+                        code: 'source-inventory-failed',
+                        severity: 'error',
+                        phase: 'inventory',
+                        pageId: page.canonicalId,
+                        retryable: true,
+                        message,
+                    });
+                }
+            })));
+            await store.setRunComments(run.id, { threads: inventory.commentThreads, comments: inventory.comments, attachments: inventory.commentAttachments });
+            if (inventoryErrors.length > 0) {
+                const finalStatus = options.signal?.aborted ? 'cancelled' : 'failed';
+                report.finish(finalStatus);
+                const reportPaths = await report.write(options.reportsDirectory);
+                if (!options.dryRun)
+                    await store.finishRun(run.id, finalStatus, runOutcomeCounts(report.data.summary, graph.pages.length));
+                throw new MigrationRunError('Resource preflight failed before destination mutation', reportPaths, stateLocation.filename);
+            }
+            if (!options.dryRun) {
+                for (const page of graph.pages) {
+                    if (store.value.pages[page.canonicalId])
+                        continue;
+                    const commentInventory = commentsByPage.get(page.canonicalId);
+                    const commentState = !commentsEnabled
+                        ? { status: 'skipped', threads: 0, comments: 0, participants: 0, attachments: 0, bytes: 0, updatedAt: new Date().toISOString() }
+                        : commentInventory?.status === 'empty'
+                            ? { status: 'complete', threads: 0, comments: 0, participants: 0, attachments: 0, bytes: 0, updatedAt: new Date().toISOString() }
+                            : commentInventory?.status === 'failed'
                                 ? {
-                                    status: 'planned', ...(commentInventory.fingerprint ? { fingerprint: commentInventory.fingerprint } : {}),
-                                    threads: commentInventory.threads.length, comments: commentInventory.comments,
-                                    participants: commentInventory.participants, attachments: commentInventory.attachments,
-                                    bytes: commentInventory.knownBytes, updatedAt: new Date().toISOString(),
+                                    status: 'failed', threads: 0, comments: 0, participants: 0, attachments: 0, bytes: 0,
+                                    ...(commentInventory.error ? { lastError: commentInventory.error } : {}), updatedAt: new Date().toISOString(),
                                 }
-                                : undefined;
-                const resourceStates = Object.fromEntries((resourcesByPage.get(page.canonicalId) ?? [])
-                    .filter((resource) => resource.kind !== 'grid')
-                    .map((resource) => [resource.id, {
-                        sourceId: resource.id,
-                        sourceName: resource.name,
-                        destinationName: preferredDestinationName(resource),
-                        ...(resource.size !== undefined ? { size: resource.size } : {}),
-                        ...(resource.mimeType ? { mimeType: resource.mimeType } : {}),
-                        status: 'planned',
+                                : commentInventory
+                                    ? {
+                                        status: 'planned', ...(commentInventory.fingerprint ? { fingerprint: commentInventory.fingerprint } : {}),
+                                        threads: commentInventory.threads.length, comments: commentInventory.comments,
+                                        participants: commentInventory.participants, attachments: commentInventory.attachments,
+                                        bytes: commentInventory.knownBytes, updatedAt: new Date().toISOString(),
+                                    }
+                                    : undefined;
+                    const resourceStates = Object.fromEntries((resourcesByPage.get(page.canonicalId) ?? [])
+                        .filter((resource) => resource.kind !== 'grid')
+                        .map((resource) => [resource.id, {
+                            sourceId: resource.id,
+                            sourceName: resource.name,
+                            destinationName: preferredDestinationName(resource),
+                            ...(resource.size !== undefined ? { size: resource.size } : {}),
+                            ...(resource.mimeType ? { mimeType: resource.mimeType } : {}),
+                            status: 'planned',
+                            updatedAt: new Date().toISOString(),
+                        }]));
+                    await store.setPage({
+                        sourceId: page.id,
+                        sourceCanonicalId: page.canonicalId,
+                        sourceLocator: page.locator,
+                        sourceTitle: page.title,
+                        ...(page.projectedParentId ? { projectedParentId: page.projectedParentId } : {}),
+                        destinationTitle: page.title,
+                        sourceFingerprint: sourceFingerprints.get(page.canonicalId),
+                        status: 'discovered',
+                        resources: resourceStates,
+                        ...(commentState ? { comments: commentState } : {}),
+                        degradations: [],
                         updatedAt: new Date().toISOString(),
-                    }]));
-                await store.setPage({
-                    sourceId: page.id,
-                    sourceCanonicalId: page.canonicalId,
-                    sourceLocator: page.locator,
-                    sourceTitle: page.title,
-                    ...(page.projectedParentId ? { projectedParentId: page.projectedParentId } : {}),
-                    destinationTitle: page.title,
-                    sourceFingerprint: sourceFingerprints.get(page.canonicalId),
-                    status: 'discovered',
-                    resources: resourceStates,
-                    ...(commentState ? { comments: commentState } : {}),
-                    degradations: [],
-                    updatedAt: new Date().toISOString(),
-                });
+                    });
+                }
             }
-        }
-        const planSummary = `Plan ready: root + ${graph.selection.selectedDescendants}/${graph.selection.returnedDescendants} descendants (${graph.selection.excluded.length} excluded, depth ${graph.selection.maximumDepth}) · ${graph.pages.length} pages · ${inventory.resources} files (${inventory.bytes} known bytes${inventory.unknownSizes > 0 ? ` · ${inventory.unknownSizes} sizes unknown` : ''}) · ${inventory.links} links · ${inventory.images} images · ${inventory.tables} tables (${inventory.grids} grids) · ${inventory.codeBlocks} code blocks · ${commentsEnabled ? `${inventory.commentThreads} comment threads / ${inventory.comments} entries / ${inventory.commentAttachments} files (${inventory.commentBytes} known bytes)` : 'comments skipped'}`;
-        status(planSummary);
-        this.logger.info(planSummary);
-        let output;
-        let archive;
-        try {
-            if (options.destination.type === 'directory') {
-                const result = await this.exportFilesystem(source, graph, options.destination, options, stateLocation.id, store, report, sourceFingerprints, resourcesByPage, commentsByPage);
-                output = result.directory;
-                archive = result.archive;
-                const exportEntry = path.join(result.directory, options.destination.format === 'html' ? 'index.html' : 'index.md');
-                report.setDestinationUrl(pathToFileURL(exportEntry).toString());
-                report.output('directory', result.directory);
-                if (result.archive)
-                    report.output('archive', result.archive);
-                if (result.backup)
-                    report.output('backup', result.backup);
+            const planSummary = `Plan ready: root + ${graph.selection.selectedDescendants}/${graph.selection.returnedDescendants} descendants (${graph.selection.excluded.length} excluded, depth ${graph.selection.maximumDepth}) · ${graph.pages.length} pages · ${inventory.resources} files (${inventory.bytes} known bytes${inventory.unknownSizes > 0 ? ` · ${inventory.unknownSizes} sizes unknown` : ''}) · ${inventory.links} links · ${inventory.images} images · ${inventory.tables} tables (${inventory.grids} grids) · ${inventory.codeBlocks} code blocks · ${commentsEnabled ? `${inventory.commentThreads} comment threads / ${inventory.comments} entries / ${inventory.commentAttachments} files (${inventory.commentBytes} known bytes)` : 'comments skipped'}`;
+            status(planSummary);
+            this.logger.info(planSummary);
+            let output;
+            let archive;
+            try {
+                if (options.destination.type === 'directory') {
+                    const result = await this.exportFilesystem(source, graph, options.destination, options, stateLocation.id, store, report, sourceFingerprints, resourcesByPage, commentsByPage);
+                    output = result.directory;
+                    archive = result.archive;
+                    const exportEntry = path.join(result.directory, options.destination.format === 'html' ? 'index.html' : 'index.md');
+                    report.setDestinationUrl(pathToFileURL(exportEntry).toString());
+                    report.output('directory', result.directory);
+                    if (result.archive)
+                        report.output('archive', result.archive);
+                    if (result.backup)
+                        report.output('backup', result.backup);
+                }
+                else {
+                    await this.transferRemote({
+                        source,
+                        destination: destination,
+                        container: container,
+                        graph,
+                        options,
+                        store,
+                        report,
+                        sourceFingerprints,
+                        resourcesByPage,
+                        commentsByPage,
+                    });
+                    output = container.url;
+                    report.output('destination', container.url);
+                }
+                report.finish('completed');
+                const finalStatus = runStatus(report.data.summary.errors, report.data.summary.warnings, report.data.summary.degradations);
+                await store.finalizeOutcomes(graph.pages.map((page) => page.canonicalId), finalStatus, options.dryRun);
+                report.finish(finalStatus);
+                const reportPaths = await report.write(options.reportsDirectory);
+                if (!options.dryRun)
+                    await store.finishRun(run.id, finalStatus, runOutcomeCounts(report.data.summary, graph.pages.length));
+                status(`${finalStatus}: source ${report.data.summary.pages} pages · ${report.data.summary.complete} complete · ${report.data.summary.partial} partial · ${report.data.summary.failed + report.data.summary.blocked} failed/blocked · files ${report.data.summary.resourcesComplete}/${report.data.summary.resources} complete · ${report.data.summary.errors} errors · ${report.data.summary.warnings} warnings · ${report.data.summary.degradations} degradations`);
+                return {
+                    status: finalStatus,
+                    hasErrors: report.data.summary.errors > 0,
+                    reportPaths,
+                    stateId: stateLocation.id,
+                    stateFilename: stateLocation.filename,
+                    ...(store.loadInfo.backupFilename ? { stateBackupFilename: store.loadInfo.backupFilename } : {}),
+                    ...(output ? { output } : {}),
+                    ...(archive ? { archive } : {}),
+                    summary: report.data.summary,
+                };
             }
-            else {
-                await this.transferRemote({
-                    source,
-                    destination: destination,
-                    container: container,
-                    graph,
-                    options,
-                    store,
-                    report,
-                    sourceFingerprints,
-                    resourcesByPage,
-                    commentsByPage,
-                });
-                output = container.url;
-                report.output('destination', container.url);
+            catch (error) {
+                const cancelled = options.signal?.aborted;
+                const finalStatus = cancelled ? 'cancelled' : 'failed';
+                const message = error instanceof Error ? error.message : String(error);
+                report.error(message);
+                await store.finalizeOutcomes(graph.pages.map((page) => page.canonicalId), finalStatus, options.dryRun);
+                report.finish(finalStatus);
+                const reportPaths = await report.write(options.reportsDirectory);
+                if (!options.dryRun)
+                    await store.finishRun(run.id, finalStatus, runOutcomeCounts(report.data.summary, graph.pages.length));
+                this.logger.error(`${message}. Report: ${reportPaths.html}`);
+                throw new MigrationRunError(message, reportPaths, stateLocation.filename, { cause: error });
             }
-            report.finish('completed');
-            const finalStatus = runStatus(report.data.summary.errors, report.data.summary.warnings, report.data.summary.degradations);
-            await store.finalizeOutcomes(graph.pages.map((page) => page.canonicalId), finalStatus, options.dryRun);
-            report.finish(finalStatus);
-            const reportPaths = await report.write(options.reportsDirectory);
-            if (!options.dryRun)
-                await store.finishRun(run.id, finalStatus, runOutcomeCounts(report.data.summary, graph.pages.length));
-            status(`${finalStatus}: source ${report.data.summary.pages} pages · ${report.data.summary.complete} complete · ${report.data.summary.partial} partial · ${report.data.summary.failed + report.data.summary.blocked} failed/blocked · files ${report.data.summary.resourcesComplete}/${report.data.summary.resources} complete · ${report.data.summary.errors} errors · ${report.data.summary.warnings} warnings · ${report.data.summary.degradations} degradations`);
-            return {
-                status: finalStatus,
-                hasErrors: report.data.summary.errors > 0,
-                reportPaths,
-                stateId: stateLocation.id,
-                stateFilename: stateLocation.filename,
-                ...(store.loadInfo.backupFilename ? { stateBackupFilename: store.loadInfo.backupFilename } : {}),
-                ...(output ? { output } : {}),
-                ...(archive ? { archive } : {}),
-                summary: report.data.summary,
-            };
         }
-        catch (error) {
-            const cancelled = options.signal?.aborted;
-            const finalStatus = cancelled ? 'cancelled' : 'failed';
-            const message = error instanceof Error ? error.message : String(error);
-            report.error(message);
-            await store.finalizeOutcomes(graph.pages.map((page) => page.canonicalId), finalStatus, options.dryRun);
-            report.finish(finalStatus);
-            const reportPaths = await report.write(options.reportsDirectory);
-            if (!options.dryRun)
-                await store.finishRun(run.id, finalStatus, runOutcomeCounts(report.data.summary, graph.pages.length));
-            this.logger.error(`${message}. Report: ${reportPaths.html}`);
-            throw new MigrationRunError(message, reportPaths, stateLocation.filename, { cause: error });
+        finally {
+            await store.release();
         }
     }
     async exportFilesystem(source, graph, destination, options, identity, store, report, sourceFingerprints, resourcesByPage, commentsByPage) {
@@ -767,6 +861,7 @@ export class Migrator {
                 status: pageStatus,
                 resources,
                 degradations: manifestPage?.warnings ?? [],
+                adaptations: manifestPage?.adaptations ?? [],
                 ...(manifestPage?.comments ? { comments: {
                         status: manifestPage.comments.status,
                         ...(manifestPage.comments.fingerprint ? { fingerprint: manifestPage.comments.fingerprint } : {}),
@@ -798,6 +893,8 @@ export class Migrator {
                 resourceStates: resources,
                 ...(options.dryRun ? { resourceStatusOverride: 'planned' } : {}),
                 ...(manifestPage?.warnings ? { warnings: manifestPage.warnings } : {}),
+                ...(manifestPage?.adaptations ? { adaptations: manifestPage.adaptations } : {}),
+                preservedExternalReferences: manifestPage?.preservedExternalReferences ?? 0,
                 commentsEnabled: options.comments ?? true,
                 ...(commentsByPage.get(page.canonicalId) ? { commentInventory: commentsByPage.get(page.canonicalId) } : {}),
                 ...(manifestPage?.comments ? { commentState: {
@@ -917,23 +1014,7 @@ export class Migrator {
                 }
             }
             current ??= await destination.findArchiveComment?.(destinationPage, fingerprint);
-            if (current && previous?.destinationFingerprint && current.fingerprint !== previous.destinationFingerprint) {
-                const conflict = {
-                    fingerprint,
-                    destinationId: current.id,
-                    destinationFingerprint: current.fingerprint,
-                    ...counts,
-                    ...(previous.archiveResourceId ? { archiveResourceId: previous.archiveResourceId } : {}),
-                    ...(previous.archiveName ? { archiveName: previous.archiveName } : {}),
-                    ...(previous.archivePath ? { archivePath: previous.archivePath } : {}),
-                    ...(previous.archiveSha256 ? { archiveSha256: previous.archiveSha256 } : {}),
-                    status: 'conflict',
-                    lastError: 'Destination comment archive was changed manually and was preserved.',
-                    updatedAt: now(),
-                };
-                return conflict;
-            }
-            const remoteResources = await destination.listUploadedResources(destinationPage);
+            let remoteResources = await destination.listUploadedResources(destinationPage);
             const remoteMatches = async (remote, file, trustedMapping) => {
                 if (remote.size !== undefined && remote.size !== file.size)
                     return false;
@@ -957,18 +1038,37 @@ export class Migrator {
                 if (reusable)
                     return reusable;
                 const extension = path.extname(file.name);
-                const alternativeName = `${file.name.slice(0, file.name.length - extension.length)}-${file.sha256.slice(0, 8)}${extension}`;
-                const alternative = remoteResources.find((resource) => resource.name.toLocaleLowerCase() === alternativeName.toLocaleLowerCase());
-                if (alternative && await remoteMatches(alternative, file, false))
-                    return alternative;
-                const uploadName = mapped || byName ? alternativeName : file.name;
-                return destination.uploadResource({
-                    page: destinationPage,
-                    name: uploadName,
-                    filePath: file.path,
-                    size: file.size,
-                    ...(mimeType ? { mimeType } : {}),
-                });
+                const base = file.name.slice(0, file.name.length - extension.length);
+                let lastError;
+                for (let attempt = 0; attempt < 10; attempt += 1) {
+                    const uploadName = attempt === 0 && !mapped && !byName
+                        ? file.name
+                        : `${base}-${file.sha256.slice(0, Math.min(file.sha256.length, 8 + attempt * 2))}${extension}`;
+                    const occupied = remoteResources.find((resource) => resource.name.toLocaleLowerCase() === uploadName.toLocaleLowerCase());
+                    if (occupied && await remoteMatches(occupied, file, false))
+                        return occupied;
+                    if (occupied)
+                        continue;
+                    try {
+                        const uploaded = await destination.uploadResource({
+                            page: destinationPage,
+                            name: uploadName,
+                            filePath: file.path,
+                            size: file.size,
+                            ...(mimeType ? { mimeType } : {}),
+                        });
+                        remoteResources.push(uploaded);
+                        return uploaded;
+                    }
+                    catch (error) {
+                        lastError = error;
+                        remoteResources = await destination.listUploadedResources(destinationPage);
+                        const uncertain = remoteResources.find((resource) => resource.name.toLocaleLowerCase() === uploadName.toLocaleLowerCase());
+                        if (uncertain && await remoteMatches(uncertain, file, false))
+                            return uncertain;
+                    }
+                }
+                throw new Error(`Archive upload could not be reconciled after 10 deterministic names: ${lastError instanceof Error ? lastError.message : String(lastError ?? 'unknown provider response')}`);
             };
             const archiveResource = zip
                 ? await uploadArchive(zip, previous?.archiveResourceId, 'application/zip')
@@ -1046,7 +1146,15 @@ export class Migrator {
                 await prepareFullArchive(`Full comment archive exceeded ${maximumInlineBytes} inline bytes and was attached as Markdown.`);
             }
             let result = current;
-            const requiresWrite = !result || previous?.fingerprint !== fingerprint;
+            const verifies = (comment) => {
+                if (!comment)
+                    return false;
+                const verification = verifyCommentArchive(fullArchiveState.fullArchiveName ? fingerprint : inventory, comment.body, archiveResource?.name);
+                if (fullArchiveState.fullArchiveName && !comment.body.includes(fullArchiveState.fullArchiveName))
+                    return false;
+                return verification.ok && verifyDestinationContent(expectedBody, comment.body, destination.kind, page).status === 'complete';
+            };
+            const requiresWrite = !verifies(result);
             if (requiresWrite) {
                 const write = async (body) => {
                     if (input.signal?.aborted)
@@ -1054,7 +1162,30 @@ export class Migrator {
                     if (!result || !destination.capabilities.updateComments || !destination.updateArchiveComment) {
                         return destination.createArchiveComment({ page: destinationPage, body });
                     }
-                    return destination.updateArchiveComment({ comment: result, body });
+                    let currentComment = result;
+                    for (let attempt = 0;; attempt += 1) {
+                        try {
+                            return await destination.updateArchiveComment({ comment: currentComment, body });
+                        }
+                        catch (error) {
+                            if (!(error instanceof DestinationRevisionConflictError) || attempt >= REVISION_RETRY_DELAYS_MS.length)
+                                throw error;
+                            const delay = await revisionDelay(attempt, this.consistencyOptions);
+                            report.issue({
+                                code: 'destination-comment-revision-retry',
+                                severity: 'normalization',
+                                phase: 'comment',
+                                pageId: page.canonicalId,
+                                commentId: currentComment.id,
+                                retryable: true,
+                                message: `${page.title}: comment archive revision changed concurrently; retry ${attempt + 1} after ${delay} ms`,
+                            });
+                            currentComment = await destination.readArchiveComment({ page: destinationPage, commentId: currentComment.id });
+                            if (verifies(currentComment)) {
+                                return currentComment;
+                            }
+                        }
+                    }
                 };
                 const presentations = fallbackReason ? [] : ['native', 'quote', 'code'];
                 let lastError;
@@ -1101,14 +1232,41 @@ export class Migrator {
             }
             if (!result)
                 throw new Error('Destination comment archive was not created');
+            if (requiresWrite && current && destination.capabilities.updateComments && result.id === current.id) {
+                report.issue({
+                    code: 'destination-revision-updated',
+                    severity: 'normalization',
+                    phase: 'comment',
+                    pageId: page.canonicalId,
+                    commentId: result.id,
+                    retryable: false,
+                    message: `${page.title}: applied the current source discussion as comment version ${result.version ?? 'confirmed'}`,
+                });
+            }
             const verified = await destination.readArchiveComment({ page: destinationPage, commentId: result.id });
             const verification = verifyCommentArchive(fullArchiveState.fullArchiveName ? fingerprint : inventory, verified.body, archiveResource?.name);
             if (fullArchiveState.fullArchiveName && !verified.body.includes(fullArchiveState.fullArchiveName)) {
                 verification.ok = false;
                 verification.differences.push('full Markdown comment archive reference is missing');
             }
+            const semanticVerification = verifyDestinationContent(expectedBody, verified.body, destination.kind, page);
+            if (semanticVerification.status !== 'complete') {
+                verification.ok = false;
+                verification.differences.push(...semanticVerification.differences);
+            }
             if (!verification.ok)
                 throw new Error(`Comment verification failed: ${verification.differences.join('; ')}`);
+            if (fallbackReason) {
+                report.issue({
+                    code: 'comment-presentation-adapted',
+                    severity: 'adaptation',
+                    phase: 'comment',
+                    pageId: page.canonicalId,
+                    commentId: verified.id,
+                    retryable: false,
+                    message: `${page.title}: ${fallbackReason}`,
+                });
+            }
             const previousIds = result.id !== current?.id && current
                 ? [...new Set([...(previous?.previousDestinationIds ?? []), current.id])]
                 : previous?.previousDestinationIds;
@@ -1116,14 +1274,14 @@ export class Migrator {
                 fingerprint,
                 destinationId: verified.id,
                 destinationFingerprint: verified.fingerprint,
+                ...(verified.version ? { destinationVersion: verified.version } : {}),
                 ...(verified.url ? { destinationUrl: verified.url } : {}),
                 ...(previousIds?.length ? { previousDestinationIds: previousIds } : {}),
                 ...archiveState,
                 ...fullArchiveState,
-                status: inventory.warnings.length > 0 || fallbackReason ? 'partial' : 'complete',
+                status: inventory.warnings.length > 0 ? 'partial' : 'complete',
                 ...counts,
                 preview: verified.body,
-                ...(fallbackReason ? { lastError: fallbackReason } : {}),
                 updatedAt: now(),
             };
             pageState.comments = state;
@@ -1139,7 +1297,8 @@ export class Migrator {
                 ...counts,
                 ...(pageState.comments?.destinationId ? { destinationId: pageState.comments.destinationId } : {}),
                 ...(pageState.comments?.destinationFingerprint ? { destinationFingerprint: pageState.comments.destinationFingerprint } : {}),
-                status: /conflict/i.test(message) ? 'conflict' : 'failed',
+                ...(pageState.comments?.destinationVersion ? { destinationVersion: pageState.comments.destinationVersion } : {}),
+                status: 'failed',
                 lastError: message,
                 updatedAt: now(),
             };
@@ -1148,6 +1307,16 @@ export class Migrator {
     async transferRemote(input) {
         const { source, destination, container, graph, options, store, report, sourceFingerprints, resourcesByPage, commentsByPage } = input;
         const destinationPages = new Map();
+        const mappedOwners = new Map();
+        for (const page of Object.values(store.value.pages)) {
+            const destinationId = page.destinationId;
+            if (!destinationId)
+                continue;
+            mappedOwners.set(destinationId, [...(mappedOwners.get(destinationId) ?? []), page.sourceCanonicalId]);
+        }
+        const ownershipConflicts = new Map([...mappedOwners.entries()]
+            .filter(([, owners]) => owners.length > 1)
+            .flatMap(([destinationId, owners]) => owners.map((owner) => [owner, { destinationId, owners }])));
         const stagingFailures = new Map();
         const sourcePages = new Map(graph.pages.map((page) => [page.canonicalId, page]));
         const bootstrapBodies = new Map();
@@ -1208,6 +1377,7 @@ export class Migrator {
                     ...(previous?.previousDestinationIds ? { previousDestinationIds: previous.previousDestinationIds } : {}),
                     sourceFingerprint: sourceFingerprints.get(page.canonicalId),
                     ...(previous?.destinationFingerprint ? { destinationFingerprint: previous.destinationFingerprint } : {}),
+                    ...(previous?.destinationVersion ? { destinationVersion: previous.destinationVersion } : {}),
                     status: 'blocked',
                     resources: blockedResourceStates(resources, previous?.resources ?? {}, cause),
                     ...(comments ? { comments } : {}),
@@ -1232,10 +1402,16 @@ export class Migrator {
                 continue;
             }
             try {
+                const ownershipConflict = ownershipConflicts.get(page.canonicalId);
+                if (ownershipConflict) {
+                    throw new DestinationOwnershipConflictError('duplicate-source-mapping', [ownershipConflict.destinationId, ...ownershipConflict.owners], `Multiple source pages are mapped to destination page ${ownershipConflict.destinationId}: ${ownershipConflict.owners.join(', ')}`);
+                }
                 const cachedPage = await loadCachedPage(options.cacheDirectory, page.canonicalId);
                 const bootstrap = bootstrapBodies.get(page.canonicalId);
                 let created;
-                const title = saved?.destinationTitle ?? page.title;
+                const title = saved && saved.destinationTitle !== saved.sourceTitle
+                    ? saved.destinationTitle
+                    : page.title;
                 let resourcesForState = saved?.resources ?? {};
                 let commentsForState = saved?.comments;
                 let previousDestinationIds = saved?.previousDestinationIds ?? [];
@@ -1285,20 +1461,18 @@ export class Migrator {
                             message: `${page.title}: replaced unavailable destination mapping ${mapped.id} with ${created.id}`,
                         });
                     }
-                    const generatedPlaceholder = created.title === saved.destinationTitle
-                        && isLegacyTransferPlaceholder(created.content, destination.kind, cachedPage);
-                    if (!mappingRecovered && ['complete', 'partial'].includes(saved.status) && saved.destinationFingerprint && created.fingerprint !== saved.destinationFingerprint && !generatedPlaceholder) {
-                        throw new Error(`Destination conflict for ${page.title}: content changed since the last verified run`);
-                    }
-                    if (generatedPlaceholder && !options.dryRun) {
-                        created = await destination.updatePage({
-                            page: created,
-                            title: created.title,
-                            body: bootstrap.body,
-                            ...(created.fingerprint ? { expectedFingerprint: created.fingerprint } : {}),
+                    if (!mappingRecovered
+                        && saved.destinationFingerprint
+                        && created.fingerprint
+                        && created.fingerprint !== saved.destinationFingerprint) {
+                        report.issue({
+                            code: 'destination-revision-updated',
+                            severity: 'normalization',
+                            phase: 'page',
+                            pageId: page.canonicalId,
+                            retryable: false,
+                            message: `${page.title}: current destination revision differs from the last confirmed state and will be reconciled from source`,
                         });
-                        created = await verifyConfirmedDestinationPage(destination, created, this.consistencyOptions);
-                        assertDestinationContent(bootstrap.body, created.content, destination.kind, cachedPage);
                     }
                     if (!mappingRecovered && created.parentId !== parent.id) {
                         const oldPage = created;
@@ -1314,12 +1488,14 @@ export class Migrator {
                             });
                         }
                         else if (destination.capabilities.reparentPages && destination.reparentPage) {
-                            created = await destination.reparentPage({
-                                page: created,
+                            created = await reparentMappedPage({
+                                destination,
+                                current: created,
                                 parent,
-                                ...(created.fingerprint ? { expectedFingerprint: created.fingerprint } : {}),
+                                sourcePage: cachedPage,
+                                consistencyOptions: this.consistencyOptions,
+                                report,
                             });
-                            created = await verifyConfirmedDestinationPage(destination, created, this.consistencyOptions);
                             if (created.parentId !== parent.id) {
                                 throw new Error(`Destination hierarchy verification failed for ${page.title}: expected parent ${parent.id}, received ${created.parentId ?? 'none'}`);
                             }
@@ -1410,11 +1586,12 @@ export class Migrator {
                     destinationId: created.id,
                     destinationCanonicalId: created.canonicalId,
                     destinationLocator: created.url,
-                    destinationTitle: created.title,
+                    destinationTitle: saved?.destinationId && !mappingRecovered ? title : created.title,
                     ...(previousDestinationIds.length > 0 ? { previousDestinationIds } : {}),
                     sourceFingerprint: sourceFingerprints.get(page.canonicalId),
                     ...(created.fingerprint ? { destinationFingerprint: created.fingerprint } : {}),
-                    status: options.dryRun ? 'planned' : saved?.status ?? 'skeleton-created',
+                    ...(created.version ? { destinationVersion: created.version } : {}),
+                    status: options.dryRun ? 'planned' : 'skeleton-created',
                     resources: resourcesForState,
                     ...(commentsForState ? { comments: commentsForState } : {}),
                     degradations: saved?.degradations ?? [],
@@ -1427,8 +1604,9 @@ export class Migrator {
                 if (options.signal?.aborted)
                     throw options.signal.reason ?? error;
                 const message = `${page.title}: ${error instanceof Error ? error.message : String(error)}`;
-                const failureStatus = /conflict/i.test(message) ? 'conflict' : 'failed';
-                const failureCode = failureStatus === 'conflict' ? 'destination-conflict' : 'destination-page-staging-failed';
+                const ownershipConflict = error instanceof DestinationOwnershipConflictError ? error : undefined;
+                const failureStatus = ownershipConflict ? 'conflict' : 'failed';
+                const failureCode = ownershipConflict ? 'destination-ownership-ambiguity' : 'destination-page-staging-failed';
                 stagingFailures.set(page.canonicalId, {
                     status: failureStatus,
                     message,
@@ -1446,13 +1624,14 @@ export class Migrator {
                 });
                 const savedState = store.value.pages[page.canonicalId];
                 if (!options.dryRun) {
+                    const { conflictEvidence: _staleConflictEvidence, ...baseState } = savedState ?? {};
                     const cause = { blockedByPageId: page.canonicalId, blockedByCode: failureCode, blockedReason: message };
                     const resources = resourcesByPage.get(page.canonicalId) ?? [];
                     const comments = (options.comments ?? true)
                         ? blockedCommentState(commentsByPage.get(page.canonicalId), savedState?.comments, cause)
                         : undefined;
                     await store.setPage({
-                        ...(savedState ?? {}),
+                        ...baseState,
                         sourceId: page.id,
                         sourceCanonicalId: page.canonicalId,
                         sourceLocator: page.locator,
@@ -1464,6 +1643,8 @@ export class Migrator {
                         resources: blockedResourceStates(resources, savedState?.resources ?? {}, cause),
                         ...(comments ? { comments } : {}),
                         degradations: savedState?.degradations ?? [],
+                        adaptations: savedState?.adaptations ?? [],
+                        ...(ownershipConflict ? { conflictEvidence: { reason: ownershipConflict.reason, candidateIds: ownershipConflict.candidateIds } } : {}),
                         lastError: message,
                         updatedAt: new Date().toISOString(),
                     });
@@ -1503,6 +1684,7 @@ export class Migrator {
                     commentsEnabled: options.comments ?? true,
                     ...(commentsByPage.get(page.canonicalId) ? { commentInventory: commentsByPage.get(page.canonicalId) } : {}),
                     ...(commentState ? { commentState } : {}),
+                    ...(failedState?.conflictEvidence ? { conflictEvidence: failedState.conflictEvidence } : {}),
                     blockedBy,
                     error: currentFailure?.message ?? failedState?.lastError ?? 'Destination page with source-derived content was not created',
                 }));
@@ -1641,8 +1823,8 @@ export class Migrator {
                             updateProgress(`reconciled ${resource.name}`);
                             continue;
                         }
-                        const updateExisting = existing?.status === 'complete' && mappedRemote ? mappedRemote : undefined;
-                        const destinationName = updateExisting?.name ?? nameAllocator.allocate(resource, existing?.status === 'complete' && !nameAllocator.isOccupied(existing.destinationName) ? existing.destinationName : undefined);
+                        const updateExisting = destination.kind === 'confluence' && existing?.status === 'complete' && mappedRemote ? mappedRemote : undefined;
+                        let destinationName = updateExisting?.name ?? nameAllocator.allocate(resource, existing?.status === 'complete' && !nameAllocator.isOccupied(existing.destinationName) ? existing.destinationName : undefined);
                         state.resources[resource.id] = {
                             sourceId: resource.id,
                             sourceName: resource.name,
@@ -1655,9 +1837,19 @@ export class Migrator {
                             updatedAt: new Date().toISOString(),
                         };
                         await store.setPage({ ...state, updatedAt: new Date().toISOString() });
-                        const matchingName = remoteResources.find((item) => item.name.toLocaleLowerCase() === destinationName.toLocaleLowerCase());
-                        let result = matchingName && await remoteMatches(matchingName, downloaded) ? matchingName : undefined;
-                        if (!result) {
+                        let result;
+                        let lastUploadError;
+                        for (let attempt = 0; attempt < 10 && !result; attempt += 1) {
+                            const matchingName = remoteResources.find((item) => item.name.toLocaleLowerCase() === destinationName.toLocaleLowerCase());
+                            if (matchingName && await remoteMatches(matchingName, downloaded)) {
+                                result = matchingName;
+                                break;
+                            }
+                            if (matchingName) {
+                                nameAllocator.reserve(matchingName.name);
+                                destinationName = nameAllocator.allocate(resource);
+                                continue;
+                            }
                             try {
                                 result = await destination.uploadResource({
                                     page: destinationPage,
@@ -1665,26 +1857,25 @@ export class Migrator {
                                     filePath: downloaded.path,
                                     size: downloaded.size,
                                     ...(mimeType ? { mimeType } : {}),
-                                    ...(updateExisting ? { existingId: updateExisting.id } : {}),
+                                    ...(attempt === 0 && updateExisting ? { existingId: updateExisting.id } : {}),
                                 });
                             }
                             catch (uploadError) {
+                                lastUploadError = uploadError;
                                 remoteResources = await destination.listUploadedResources(destinationPage);
+                                for (const remote of remoteResources)
+                                    nameAllocator.reserve(remote.name);
                                 const uncertain = remoteResources.find((item) => item.name.toLocaleLowerCase() === destinationName.toLocaleLowerCase());
-                                if (uncertain && await remoteMatches(uncertain, downloaded))
+                                if (uncertain && await remoteMatches(uncertain, downloaded)) {
                                     result = uncertain;
-                                else {
-                                    const retryName = nameAllocator.allocate(resource);
-                                    result = await destination.uploadResource({
-                                        page: destinationPage,
-                                        name: retryName,
-                                        filePath: downloaded.path,
-                                        size: downloaded.size,
-                                        ...(mimeType ? { mimeType } : {}),
-                                    }).catch((retryError) => { throw new Error(`${retryError instanceof Error ? retryError.message : String(retryError)} (initial upload: ${uploadError instanceof Error ? uploadError.message : String(uploadError)})`); });
+                                    break;
                                 }
+                                destinationName = nameAllocator.allocate(resource);
                             }
                         }
+                        if (!result) {
+                            throw new Error(`Resource upload could not be reconciled after 10 deterministic names: ${lastUploadError instanceof Error ? lastUploadError.message : String(lastUploadError ?? 'unknown provider response')}`);
+                        }
                         if (!remoteResources.some((item) => item.id === result.id))
                             remoteResources.push(result);
                         setSourceResourceBinding(bindings, cachedPage, resources, resource, { kind: 'uploaded', resource: result });
@@ -1767,31 +1958,63 @@ export class Migrator {
                         sha256: sha256(cachedPage.rawContent),
                     };
                     try {
-                        const knownSnapshot = remoteResources.find((item) => item.id === existingSnapshot?.destinationId)
-                            ?? remoteResources.find((item) => item.name.toLocaleLowerCase() === snapshotName.toLocaleLowerCase());
-                        let snapshot = knownSnapshot && await remoteMatches(knownSnapshot, snapshotFile, true)
-                            ? knownSnapshot
+                        const mappedSnapshot = remoteResources.find((item) => item.id === existingSnapshot?.destinationId);
+                        let snapshot = mappedSnapshot && await remoteMatches(mappedSnapshot, snapshotFile, true)
+                            ? mappedSnapshot
                             : undefined;
-                        if (!snapshot) {
+                        const sameNameSnapshot = remoteResources.find((item) => item.name.toLocaleLowerCase() === snapshotName.toLocaleLowerCase());
+                        if (!snapshot && sameNameSnapshot && await remoteMatches(sameNameSnapshot, snapshotFile, false)) {
+                            snapshot = sameNameSnapshot;
+                        }
+                        const snapshotResource = {
+                            provider: cachedPage.provider,
+                            id: snapshotKey,
+                            pageId: cachedPage.id,
+                            name: snapshotName,
+                            preferredName: snapshotName,
+                            kind: 'attachment',
+                        };
+                        let destinationName = mappedSnapshot && destination.kind === 'confluence'
+                            ? mappedSnapshot.name
+                            : nameAllocator.allocate(snapshotResource);
+                        let lastUploadError;
+                        for (let attempt = 0; attempt < 10 && !snapshot; attempt += 1) {
+                            const occupied = remoteResources.find((item) => item.name.toLocaleLowerCase() === destinationName.toLocaleLowerCase());
+                            if (occupied && await remoteMatches(occupied, snapshotFile, occupied.id === mappedSnapshot?.id)) {
+                                snapshot = occupied;
+                                break;
+                            }
+                            if (occupied && occupied.id !== mappedSnapshot?.id) {
+                                nameAllocator.reserve(occupied.name);
+                                destinationName = nameAllocator.allocate(snapshotResource);
+                                continue;
+                            }
                             try {
                                 snapshot = await destination.uploadResource({
                                     page: destinationPage,
-                                    name: snapshotName,
+                                    name: destinationName,
                                     filePath: snapshotPath,
                                     size: snapshotFile.size,
                                     mimeType: page.rawFormat === 'yfm' ? 'text/markdown' : 'application/xml',
-                                    ...(knownSnapshot ? { existingId: knownSnapshot.id } : {}),
+                                    ...(attempt === 0 && mappedSnapshot && destination.kind === 'confluence' ? { existingId: mappedSnapshot.id } : {}),
                                 });
                             }
                             catch (uploadError) {
+                                lastUploadError = uploadError;
                                 remoteResources = await destination.listUploadedResources(destinationPage);
-                                const uncertain = remoteResources.find((item) => item.name.toLocaleLowerCase() === snapshotName.toLocaleLowerCase());
-                                if (uncertain && await remoteMatches(uncertain, snapshotFile, true))
+                                for (const remote of remoteResources)
+                                    nameAllocator.reserve(remote.name);
+                                const uncertain = remoteResources.find((item) => item.name.toLocaleLowerCase() === destinationName.toLocaleLowerCase());
+                                if (uncertain && await remoteMatches(uncertain, snapshotFile, uncertain.id === mappedSnapshot?.id)) {
                                     snapshot = uncertain;
-                                else
-                                    throw uploadError;
+                                    break;
+                                }
+                                destinationName = nameAllocator.allocate(snapshotResource);
                             }
                         }
+                        if (!snapshot) {
+                            throw new Error(`Raw snapshot upload could not be reconciled after 10 deterministic names: ${lastUploadError instanceof Error ? lastUploadError.message : String(lastUploadError ?? 'unknown provider response')}`);
+                        }
                         if (!remoteResources.some((item) => item.id === snapshot.id))
                             remoteResources.push(snapshot);
                         state.resources[snapshotKey] = {
@@ -1831,30 +2054,34 @@ export class Migrator {
                     state.degradations = [...new Set([...rendered.warnings, ...resourceProblems])];
                 }
                 let verified = destinationPage;
+                let verificationAdaptations = [];
                 let verificationDegradations = [];
                 if (!options.dryRun) {
                     const current = await verifyConfirmedDestinationPage(destination, destinationPage, this.consistencyOptions);
-                    if (destinationPage.contentFingerprint
-                        && current.contentFingerprint
-                        && current.contentFingerprint !== destinationPage.contentFingerprint) {
-                        const normalization = verifyDestinationContent(destinationPage.content ?? bootstrap.body, current.content, destination.kind, cachedPage);
-                        if (normalization.status !== 'complete') {
-                            throw new Error(`Destination conflict for ${page.title}: content changed while resources were transferred`);
-                        }
-                        rendered.normalizations.push('Destination normalized page markup without semantic content changes');
-                    }
-                    verified = await destination.updatePage({
-                        page: current,
-                        title: current.title,
+                    const update = await updateMappedPage({
+                        destination,
+                        current,
+                        title: state.destinationTitle,
                         body: rendered.body,
-                        ...(current.fingerprint ? { expectedFingerprint: current.fingerprint } : {}),
+                        sourcePage: cachedPage,
+                        consistencyOptions: this.consistencyOptions,
+                        report,
                     });
-                    if (verified.fingerprint) {
-                        state.destinationFingerprint = verified.fingerprint;
-                        await store.setPage({ ...state, updatedAt: new Date().toISOString() });
+                    verified = update.page;
+                    if (update.normalized)
+                        rendered.normalizations.push('Destination normalized page markup without semantic content changes');
+                    if (update.updated) {
+                        report.issue({
+                            code: 'destination-revision-updated',
+                            severity: 'normalization',
+                            phase: 'page',
+                            pageId: page.canonicalId,
+                            retryable: false,
+                            message: `${page.title}: applied the current source representation as destination version ${verified.version ?? 'confirmed'}`,
+                        });
                     }
-                    verified = await verifyConfirmedDestinationPage(destination, verified, this.consistencyOptions);
                     const verification = assertDestinationContent(rendered.body, verified.content, destination.kind, cachedPage);
+                    verificationAdaptations = verification.adaptations;
                     verificationDegradations = verification.status === 'partial' ? verification.differences : [];
                 }
                 const commentInventory = commentsByPage.get(page.canonicalId);
@@ -1901,7 +2128,10 @@ export class Migrator {
                     });
                 }
                 const commentPartial = !['complete', 'skipped', 'planned'].includes(commentState.status);
-                const partial = rendered.degraded || resourceProblems.length > 0 || verificationDegradations.length > 0 || commentPartial;
+                const renderedDegradations = rendered.notices
+                    .filter((notice) => notice.kind === 'degradation')
+                    .map((notice) => notice.message);
+                const partial = renderedDegradations.length > 0 || resourceProblems.length > 0 || verificationDegradations.length > 0 || commentPartial;
                 const lastResourceProblem = resourceProblems.at(-1);
                 const clearedState = { ...state };
                 delete clearedState.lastError;
@@ -1912,9 +2142,11 @@ export class Migrator {
                     destinationLocator: verified.url,
                     destinationTitle: verified.title,
                     ...(verified.fingerprint ? { destinationFingerprint: verified.fingerprint } : {}),
+                    ...(verified.version ? { destinationVersion: verified.version } : {}),
                     status: options.dryRun ? 'planned' : partial ? 'partial' : 'complete',
                     comments: commentState,
-                    degradations: [...new Set([...rendered.warnings, ...resourceProblems, ...verificationDegradations])],
+                    degradations: [...new Set([...renderedDegradations, ...resourceProblems, ...verificationDegradations])],
+                    adaptations: [...new Set([...rendered.adaptations, ...verificationAdaptations])],
                     ...(lastResourceProblem ? { lastError: lastResourceProblem } : {}),
                     updatedAt: new Date().toISOString(),
                 };
@@ -1936,6 +2168,8 @@ export class Migrator {
                     resourceFallbacks: fallbackDetails,
                     warnings: [...rendered.warnings, ...verificationDegradations],
                     normalizations: rendered.normalizations,
+                    adaptations: [...rendered.adaptations, ...verificationAdaptations],
+                    preservedExternalReferences: rendered.preservedExternalReferences,
                     commentsEnabled: options.comments ?? true,
                     ...(commentInventory ? { commentInventory } : {}),
                     commentState,
@@ -1943,7 +2177,8 @@ export class Migrator {
             }
             catch (error) {
                 const message = `${page.title}: ${error instanceof Error ? error.message : String(error)}`;
-                let failureStatus = /conflict/i.test(message) ? 'conflict' : 'failed';
+                const ownershipConflict = error instanceof DestinationOwnershipConflictError ? error : undefined;
+                let failureStatus = ownershipConflict ? 'conflict' : 'failed';
                 let actual;
                 if (failureStatus !== 'conflict' && !options.dryRun) {
                     try {
@@ -1956,7 +2191,7 @@ export class Migrator {
                     }
                 }
                 report.issue({
-                    code: failureStatus === 'conflict' ? 'destination-conflict' : 'page-transfer-failed',
+                    code: ownershipConflict ? 'destination-ownership-ambiguity' : 'page-transfer-failed',
                     severity: 'error',
                     phase: 'page',
                     pageId: page.canonicalId,
@@ -1966,7 +2201,9 @@ export class Migrator {
                 await store.setPage({
                     ...state,
                     ...(actual?.fingerprint ? { destinationFingerprint: actual.fingerprint } : {}),
+                    ...(actual?.version ? { destinationVersion: actual.version } : {}),
                     status: failureStatus,
+                    ...(ownershipConflict ? { conflictEvidence: { reason: ownershipConflict.reason, candidateIds: ownershipConflict.candidateIds } } : {}),
                     lastError: message,
                     updatedAt: new Date().toISOString(),
                 });
@@ -1989,6 +2226,7 @@ export class Migrator {
                     commentsEnabled: options.comments ?? true,
                     ...(commentsByPage.get(page.canonicalId) ? { commentInventory: commentsByPage.get(page.canonicalId) } : {}),
                     ...(state.comments ? { commentState: state.comments } : {}),
+                    ...(ownershipConflict ? { conflictEvidence: { reason: ownershipConflict.reason, candidateIds: ownershipConflict.candidateIds } } : {}),
                 }), actual?.content ? { source: normalizedPreviewHtml(document), destination: renderedPreviewHtml(actual.content, destination.kind) } : undefined);
             }
             finally {