@iwonz/ywtc 3.3.0 → 3.4.1

package/dist/migrator.js

@@ -3,14 +3,19 @@ import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import PQueue from 'p-queue';
 import { createProviderAdapter } from './adapters/factory.js';
-import { appendGridSnapshots, assertDestinationContent, isLegacyTransferPlaceholder, normalizePageContent, normalizedPreviewHtml, rawContentFallback, renderedPreviewHtml, renderConfluenceStorage, renderYfm, setSourceResourceBinding, sourceResourceBindings, verifyDestinationContent, } from './content-model.js';
+import { appendGridSnapshots, assertDestinationContent, emptyRendererFallbackReason, isLegacyTransferPlaceholder, 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 { assertTransferCapabilities } from './domain.js';
 import { FilesystemExporter } from './filesystem-export.js';
 import { discoverPageGraph } from './graph.js';
+import { HttpRequestError } from './http.js';
+import { safeFilename } from './input.js';
 import { profileBaseUrl, sameRemoteInstance } from './locators.js';
 import { TransferReport, } from './report.js';
 import { DestinationNameAllocator, preferredDestinationName, verifiedCacheFile } from './resource-reconciliation.js';
+import { destinationTitleCandidates } from './title-allocation.js';
 import { resolveStateLocation, StateStore, } from './state.js';
 function sourceIdentity(locator, root) {
     return {
@@ -63,10 +68,6 @@ async function cacheDocument(cacheDirectory, canonicalId, document) {
 async function loadCachedDocument(cacheDirectory, canonicalId) {
     return JSON.parse(await readFile(cachedDocumentPath(cacheDirectory, canonicalId), 'utf8'));
 }
-function collisionTitle(page) {
-    const suffix = page.locator.split('/').filter(Boolean).at(-1) ?? page.id;
-    return `${page.title} [${suffix}]`;
-}
 function cachePath(cacheDirectory, page, resource) {
     const pageKey = sha256(page.canonicalId).slice(0, 12);
     const resourceKey = sha256(`${resource.id}:${resource.name}`).slice(0, 12);
@@ -102,6 +103,73 @@ function sourceDerivedTextMatches(expectedBody, actualBody, provider, page) {
     const text = (value) => renderedPreviewHtml(value, provider).replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim();
     return text(expectedBody) === text(actualBody);
 }
+function ambiguousCreateOutcome(error) {
+    return error instanceof HttpRequestError
+        && (error.status === undefined || error.status >= 500);
+}
+async function createPageWithAllocatedTitle(input) {
+    const candidates = destinationTitleCandidates(input.sourcePage, input.preferredTitle);
+    for (const [index, title] of candidates.entries()) {
+        let child;
+        try {
+            child = input.destination.findRecoverablePage
+                ? await input.destination.findRecoverablePage(input.parent, title)
+                : await input.destination.findChild(input.parent, title);
+        }
+        catch (error) {
+            input.report.issue({
+                code: 'destination-recovery-lookup-failed',
+                severity: 'warning',
+                phase: 'page',
+                pageId: input.sourcePage.canonicalId,
+                retryable: true,
+                message: `${input.sourcePage.title}: parent-scoped recovery lookup failed for "${title}"; authoritative creation will be attempted: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+        if (child && sourceDerivedTextMatches(input.bootstrap.body, child.content, input.destination.kind, input.sourcePage)) {
+            return { page: child, reused: true };
+        }
+        const occupied = child ?? (input.destination.findTitleConflict
+            ? await input.destination.findTitleConflict(input.parent, title)
+            : undefined);
+        if (occupied)
+            continue;
+        let created;
+        try {
+            created = await input.destination.createPage({ container: input.parent, title, body: input.bootstrap.body });
+        }
+        catch (error) {
+            if (error instanceof DestinationTitleConflictError)
+                continue;
+            if (ambiguousCreateOutcome(error)) {
+                const recovered = input.destination.findRecoverablePage
+                    ? await input.destination.findRecoverablePage(input.parent, title)
+                    : await input.destination.findChild(input.parent, title);
+                if (recovered && sourceDerivedTextMatches(input.bootstrap.body, recovered.content, input.destination.kind, input.sourcePage)) {
+                    return { page: recovered, reused: true };
+                }
+            }
+            throw error;
+        }
+        created = await verifyConfirmedDestinationPage(input.destination, created, input.consistencyOptions);
+        assertDestinationContent(input.bootstrap.body, created.content, input.destination.kind, input.sourcePage);
+        if (created.parentId !== input.parent.id) {
+            throw new Error(`Destination hierarchy verification failed for ${input.sourcePage.title}: expected parent ${input.parent.id}, received ${created.parentId ?? 'none'}`);
+        }
+        if (index > 0) {
+            input.report.issue({
+                code: 'destination-title-renamed',
+                severity: 'normalization',
+                phase: 'page',
+                pageId: input.sourcePage.canonicalId,
+                retryable: false,
+                message: `${input.sourcePage.title}: destination title was allocated as "${created.title}" because an earlier candidate was occupied`,
+            });
+        }
+        return { page: created, reused: false };
+    }
+    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) {
         throw new Error(`Incomplete mapped destination for ${state.sourceTitle}`);
@@ -133,10 +201,19 @@ function reportPage(input) {
             ...(state?.destinationId ? { destinationId: state.destinationId } : {}),
             ...(state?.destinationName ? { destinationName: state.destinationName } : {}),
             ...(state?.lastError ? { error: state.lastError } : {}),
+            ...(status === 'blocked' && input.blockedBy ? input.blockedBy : {}),
         };
     });
     const knownBytes = resourceItems.reduce((total, resource) => total + (resource.sourceBytes ?? 0), 0);
     const transferredBytes = resourceItems.reduce((total, resource) => total + (resource.transferredBytes ?? 0), 0);
+    const commentsEnabled = input.commentsEnabled ?? true;
+    const inventory = input.commentInventory;
+    const commentState = input.commentState;
+    const commentStatus = !commentsEnabled
+        ? 'skipped'
+        : commentState?.status
+            ?? (inventory?.status === 'failed' ? 'failed' : inventory?.status === 'empty' ? 'complete' : 'planned');
+    const commentError = commentState?.lastError ?? inventory?.error;
     return {
         sourceCanonicalId: input.page.canonicalId,
         sourceId: input.page.id,
@@ -166,6 +243,55 @@ function reportPage(input) {
         warnings: [...new Set([...input.document.warnings, ...(input.warnings ?? [])])],
         normalizations: [...new Set([...(input.document.normalizations ?? []), ...(input.normalizations ?? [])])],
         ...(input.error ? { error: input.error } : {}),
+        ...(input.status === 'blocked' && input.blockedBy ? input.blockedBy : {}),
+        comments: {
+            status: commentStatus,
+            threads: commentState?.threads ?? inventory?.threads.length ?? 0,
+            comments: commentState?.comments ?? inventory?.comments ?? 0,
+            participants: commentState?.participants ?? inventory?.participants ?? 0,
+            attachments: commentState?.attachments ?? inventory?.attachments ?? 0,
+            bytes: commentState?.bytes ?? inventory?.knownBytes ?? 0,
+            ...(commentState?.archiveName ? { archiveName: commentState.archiveName } : {}),
+            ...(commentState?.destinationId ? { destinationId: commentState.destinationId } : {}),
+            ...(commentState?.previousDestinationIds?.length ? { revision: true } : {}),
+            ...(commentState?.status === 'stale' ? { stale: true } : {}),
+            ...(commentError ? { error: commentError } : {}),
+            ...(commentState?.preview ? { preview: commentState.preview } : {}),
+            ...(commentStatus === 'blocked' && input.blockedBy ? input.blockedBy : {}),
+        },
+    };
+}
+function blockedResourceStates(resources, previous, cause) {
+    return {
+        ...previous,
+        ...Object.fromEntries(resources.filter((resource) => resource.kind !== 'grid').map((resource) => {
+            const existing = previous[resource.id];
+            return [resource.id, {
+                    ...(existing ?? {}),
+                    sourceId: resource.id,
+                    sourceName: resource.name,
+                    destinationName: existing?.destinationName ?? preferredDestinationName(resource),
+                    ...(existing?.size !== undefined ? { size: existing.size } : resource.size !== undefined ? { size: resource.size } : {}),
+                    status: 'blocked',
+                    ...cause,
+                    lastError: cause.blockedReason,
+                    updatedAt: new Date().toISOString(),
+                }];
+        })),
+    };
+}
+function blockedCommentState(inventory, previous, cause) {
+    return {
+        ...(previous ?? {}),
+        status: 'blocked',
+        threads: previous?.threads ?? inventory?.threads.length ?? 0,
+        comments: previous?.comments ?? inventory?.comments ?? 0,
+        participants: previous?.participants ?? inventory?.participants ?? 0,
+        attachments: previous?.attachments ?? inventory?.attachments ?? 0,
+        bytes: previous?.bytes ?? inventory?.knownBytes ?? 0,
+        ...cause,
+        lastError: cause.blockedReason,
+        updatedAt: new Date().toISOString(),
     };
 }
 function runStatus(errors, warnings, degradations) {
@@ -176,6 +302,17 @@ function runStatus(errors, warnings, degradations) {
 function attentionCount(summary) {
     return summary.warnings + summary.degradations;
 }
+function runOutcomeCounts(summary, pages) {
+    return {
+        pages,
+        warnings: attentionCount(summary),
+        errors: summary.errors,
+        rootErrors: summary.rootErrors,
+        dependentPages: summary.dependentPages,
+        dependentFiles: summary.dependentFiles,
+        dependentComments: summary.dependentComments,
+    };
+}
 export class MigrationRunError extends Error {
     reportPaths;
     stateFilename;
@@ -192,7 +329,7 @@ async function renderRemoteDocument(input) {
             ? await renderConfluenceStorage(input.document, input.page, input.context, input.container.space ?? '')
             : await renderYfm(input.document, input.context);
         if (!rendered.body.trim())
-            return rawContentFallback(input.page, input.destination.kind, 'renderer returned an empty body');
+            return rawContentFallback(input.page, input.destination.kind, emptyRendererFallbackReason(input.document));
         return rendered;
     }
     catch (error) {
@@ -212,11 +349,12 @@ export class Migrator {
     }
     async run(options) {
         const sourceStatus = options.sourceStatus ?? 'all';
+        const commentsEnabled = options.comments ?? true;
         const source = this.adapterFactory(options.source.profile, this.config);
         const destination = options.destination.type === 'remote'
             ? this.adapterFactory(options.destination.profile, this.config)
             : undefined;
-        assertTransferCapabilities(source, destination, options.scope, sourceStatus);
+        assertTransferCapabilities(source, destination, options.scope, sourceStatus, commentsEnabled);
         const status = options.onStatus ?? (() => undefined);
         status('Checking source and destination capabilities');
         const [sourcePlatform, destinationPlatform, root, container] = await Promise.all([
@@ -240,9 +378,10 @@ export class Migrator {
         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);
+        const run = await store.beginRun(options.scope, options.dryRun, sourceStatus, commentsEnabled);
         const report = new TransferReport({
             dryRun: options.dryRun,
+            commentsEnabled,
             scope: options.scope,
             sourceStatus,
             direction: `${source.kind} → ${options.destination.type === 'directory' ? options.destination.format : destination.kind}`,
@@ -303,16 +442,13 @@ export class Migrator {
             report.finish(finalStatus);
             const reportPaths = await report.write(options.reportsDirectory);
             if (!options.dryRun)
-                await store.finishRun(run.id, finalStatus, {
-                    pages: 0,
-                    warnings: attentionCount(report.data.summary),
-                    errors: report.data.summary.errors,
-                });
+                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 };
+        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 () => {
@@ -322,6 +458,36 @@ export class Migrator {
                 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;
@@ -337,6 +503,8 @@ export class Migrator {
                     status: 'planned',
                     resources,
                     document,
+                    commentsEnabled,
+                    ...(commentInventory ? { commentInventory } : {}),
                 }), undefined, false);
                 status(`Inspected ${page.title} · ${resources.length} resources`);
             }
@@ -354,26 +522,72 @@ export class Migrator {
                 });
             }
         })));
+        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, {
-                    pages: graph.pages.length,
-                    warnings: attentionCount(report.data.summary),
-                    errors: report.data.summary.errors,
-                });
+                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);
         }
-        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`;
+        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
+                                ? {
+                                    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(),
+                });
+            }
+        }
+        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);
+                const result = await this.exportFilesystem(source, graph, options.destination, options, stateLocation.id, store, report, sourceFingerprints, resourcesByPage, commentsByPage);
                 output = result.directory;
                 archive = result.archive;
                 report.output('directory', result.directory);
@@ -393,20 +607,18 @@ export class Migrator {
                     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, {
-                    pages: graph.pages.length,
-                    warnings: attentionCount(report.data.summary),
-                    errors: report.data.summary.errors,
-                });
+                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,
@@ -425,19 +637,16 @@ export class Migrator {
             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, {
-                    pages: graph.pages.length,
-                    warnings: attentionCount(report.data.summary),
-                    errors: report.data.summary.errors,
-                });
+                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 });
         }
     }
-    async exportFilesystem(source, graph, destination, options, identity, store, report, sourceFingerprints, resourcesByPage) {
+    async exportFilesystem(source, graph, destination, options, identity, store, report, sourceFingerprints, resourcesByPage, commentsByPage) {
         const exporter = new FilesystemExporter(source, options.concurrency);
         const totalResources = [...resourcesByPage.values()].reduce((total, resources) => total + resources.filter((resource) => resource.kind !== 'grid').length, 0);
         const total = Math.max(1, graph.pages.length + totalResources);
@@ -456,6 +665,8 @@ export class Migrator {
                     options.onStatus?.(`Progress ${Math.min(100, Math.floor((processed / total) * 100))}% · ${processed}/${total} · ${message}`);
                 } } : {}),
             resourcesByPage,
+            commentsByPage,
+            commentsEnabled: options.comments ?? true,
             loadPage: (page) => loadCachedPage(options.cacheDirectory, page.canonicalId),
             loadDocument: (page) => loadCachedDocument(options.cacheDirectory, page.canonicalId),
         });
@@ -479,7 +690,8 @@ export class Migrator {
                         updatedAt: new Date().toISOString(),
                     }];
             }));
-            const pageStatus = options.dryRun ? 'planned' : manifestPage?.degraded ? 'partial' : 'complete';
+            const commentIncomplete = manifestPage?.comments && !['complete', 'skipped'].includes(manifestPage.comments.status);
+            const pageStatus = options.dryRun ? 'planned' : manifestPage?.degraded || commentIncomplete ? 'partial' : 'complete';
             await store.setPage({
                 sourceId: page.id,
                 sourceCanonicalId: page.canonicalId,
@@ -495,6 +707,19 @@ export class Migrator {
                 status: pageStatus,
                 resources,
                 degradations: manifestPage?.warnings ?? [],
+                ...(manifestPage?.comments ? { comments: {
+                        status: manifestPage.comments.status,
+                        ...(manifestPage.comments.fingerprint ? { fingerprint: manifestPage.comments.fingerprint } : {}),
+                        ...(manifestPage.comments.archivePath ? { archivePath: manifestPage.comments.archivePath } : {}),
+                        ...(manifestPage.comments.archiveName ? { archiveName: manifestPage.comments.archiveName } : {}),
+                        threads: manifestPage.comments.threads,
+                        comments: manifestPage.comments.comments,
+                        participants: manifestPage.comments.participants,
+                        attachments: manifestPage.comments.attachments,
+                        bytes: manifestPage.comments.bytes,
+                        ...(manifestPage.comments.error ? { lastError: manifestPage.comments.error } : {}),
+                        updatedAt: new Date().toISOString(),
+                    } } : {}),
                 updatedAt: new Date().toISOString(),
             });
             report.addPage(reportPage({
@@ -505,7 +730,35 @@ export class Migrator {
                 resourceStates: resources,
                 ...(options.dryRun ? { resourceStatusOverride: 'planned' } : {}),
                 ...(manifestPage?.warnings ? { warnings: manifestPage.warnings } : {}),
+                commentsEnabled: options.comments ?? true,
+                ...(commentsByPage.get(page.canonicalId) ? { commentInventory: commentsByPage.get(page.canonicalId) } : {}),
+                ...(manifestPage?.comments ? { commentState: {
+                        status: manifestPage.comments.status,
+                        ...(manifestPage.comments.fingerprint ? { fingerprint: manifestPage.comments.fingerprint } : {}),
+                        ...(manifestPage.comments.archivePath ? { archivePath: manifestPage.comments.archivePath } : {}),
+                        ...(manifestPage.comments.archiveName ? { archiveName: manifestPage.comments.archiveName } : {}),
+                        threads: manifestPage.comments.threads,
+                        comments: manifestPage.comments.comments,
+                        participants: manifestPage.comments.participants,
+                        attachments: manifestPage.comments.attachments,
+                        bytes: manifestPage.comments.bytes,
+                        ...(manifestPage.comments.error ? { lastError: manifestPage.comments.error } : {}),
+                        updatedAt: new Date().toISOString(),
+                    } } : {}),
             }), { source: normalizedPreviewHtml(document), destination: normalizedPreviewHtml(document) });
+            if (manifestPage?.comments
+                && !['complete', 'skipped', 'planned'].includes(manifestPage.comments.status)
+                && !(manifestPage.comments.status === 'failed' && commentsByPage.get(page.canonicalId)?.status === 'failed')
+                && !(manifestPage.comments.status === 'partial' && (commentsByPage.get(page.canonicalId)?.warnings.length ?? 0) > 0)) {
+                report.issue({
+                    code: `comment-${manifestPage.comments.status}`,
+                    severity: manifestPage.comments.status === 'partial' || manifestPage.comments.status === 'stale' ? 'degradation' : 'error',
+                    phase: 'comment',
+                    pageId: page.canonicalId,
+                    retryable: manifestPage.comments.status === 'failed',
+                    message: `${page.title}: ${manifestPage.comments.error ?? `comment archive is ${manifestPage.comments.status}`}`,
+                });
+            }
         }
         for (const warning of result.warnings)
             report.warning(warning);
@@ -513,18 +766,328 @@ export class Migrator {
             report.error(error);
         return result;
     }
+    async transferRemoteComments(input) {
+        const { source, destination, page, destinationPage, inventory, resources, pageState, report, store } = input;
+        const now = () => new Date().toISOString();
+        const counts = {
+            threads: inventory?.threads.length ?? 0,
+            comments: inventory?.comments ?? 0,
+            participants: inventory?.participants ?? 0,
+            attachments: inventory?.attachments ?? 0,
+            bytes: inventory?.knownBytes ?? 0,
+        };
+        if (!inventory)
+            return { status: 'skipped', ...counts, updatedAt: now() };
+        if (inventory.status === 'failed') {
+            return { status: 'failed', ...counts, ...(inventory.error ? { lastError: inventory.error } : {}), updatedAt: now() };
+        }
+        if (inventory.status === 'empty') {
+            if (pageState.comments?.destinationId) {
+                return { ...pageState.comments, status: 'stale', lastError: 'Source no longer returns the previously archived comments; the destination archive was preserved.', updatedAt: now() };
+            }
+            return { status: 'complete', ...counts, updatedAt: now() };
+        }
+        const fingerprint = inventory.fingerprint;
+        if (!fingerprint)
+            return { status: 'failed', ...counts, lastError: 'Comment inventory fingerprint is missing', updatedAt: now() };
+        if (input.dryRun)
+            return { status: 'planned', fingerprint, ...counts, updatedAt: now() };
+        if (!destination.createArchiveComment || !destination.readArchiveComment) {
+            return { status: 'failed', fingerprint, ...counts, lastError: `${destination.profile.name} does not implement comment archive writes`, updatedAt: now() };
+        }
+        try {
+            if (input.signal?.aborted)
+                throw input.signal.reason ?? new Error('Transfer cancelled');
+            const resourceById = new Map(resources.map((resource) => [resource.id, resource]));
+            const downloads = new Map();
+            const archiveFiles = [];
+            for (const use of commentAttachmentUses(inventory)) {
+                if (input.signal?.aborted)
+                    throw input.signal.reason ?? new Error('Transfer cancelled');
+                const resourceId = use.reference.resourceId;
+                if (!resourceId)
+                    continue;
+                const resource = resourceById.get(resourceId);
+                if (!resource)
+                    continue;
+                let downloaded = downloads.get(resourceId);
+                if (!downloaded) {
+                    const resourceState = pageState.resources[resourceId];
+                    const filename = containedCachePath(input.cacheDirectory, resourceState?.cachePath)
+                        ?? cachePath(input.cacheDirectory, page, resource);
+                    const cached = await verifiedCacheFile(filename, resourceState?.sha256 ? {
+                        sha256: resourceState.sha256,
+                        ...(resourceState.size !== undefined ? { size: resourceState.size } : {}),
+                    } : undefined);
+                    downloaded = cached ?? await source.downloadResource(resource, filename);
+                    downloads.set(resourceId, downloaded);
+                }
+                archiveFiles.push({
+                    commentId: use.commentId,
+                    reference: use.reference.href,
+                    originalName: resource.preferredName ?? resource.name,
+                    ...downloaded,
+                });
+            }
+            const zip = await createCommentArchiveZip({
+                pageKey: page.id,
+                fingerprint,
+                files: archiveFiles,
+                destinationDirectory: path.join(input.cacheDirectory, 'comments', sha256(page.canonicalId).slice(0, 16)),
+            });
+            let current;
+            const previous = pageState.comments;
+            if (previous?.destinationId) {
+                try {
+                    current = await destination.readArchiveComment({ page: destinationPage, commentId: previous.destinationId });
+                }
+                catch (error) {
+                    report.issue({
+                        code: 'comment-mapping-missing', severity: 'warning', phase: 'comment', pageId: page.canonicalId,
+                        retryable: true, message: `${page.title}: mapped comment ${previous.destinationId} could not be read and will be recreated: ${error instanceof Error ? error.message : String(error)}`,
+                    });
+                }
+            }
+            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);
+            const remoteMatches = async (remote, file, trustedMapping) => {
+                if (remote.size !== undefined && remote.size !== file.size)
+                    return false;
+                if (!destination.downloadUploadedResource)
+                    return trustedMapping && (remote.size === undefined || remote.size === file.size);
+                const comparison = `${file.path}.destination-${sha256(remote.id).slice(0, 8)}`;
+                try {
+                    const actual = await destination.downloadUploadedResource({ page: destinationPage, resource: remote, destination: comparison });
+                    return actual.size === file.size && actual.sha256 === file.sha256;
+                }
+                finally {
+                    await rm(comparison, { force: true });
+                }
+            };
+            const uploadArchive = async (file, mappedId, mimeType) => {
+                const mapped = mappedId ? remoteResources.find((resource) => resource.id === mappedId) : undefined;
+                const byName = remoteResources.find((resource) => resource.name.toLocaleLowerCase() === file.name.toLocaleLowerCase());
+                const reusable = mapped && await remoteMatches(mapped, file, true)
+                    ? mapped
+                    : byName && await remoteMatches(byName, file, false) ? byName : undefined;
+                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 archiveResource = zip
+                ? await uploadArchive(zip, previous?.archiveResourceId, 'application/zip')
+                : undefined;
+            if (input.signal?.aborted)
+                throw input.signal.reason ?? new Error('Transfer cancelled');
+            const attachmentNames = new Map();
+            if (zip) {
+                const nameByHash = new Map(zip.files.map((entry) => [entry.sha256, entry.archiveName]));
+                for (const [resourceId, downloaded] of downloads) {
+                    const name = nameByHash.get(downloaded.sha256);
+                    if (name)
+                        attachmentNames.set(resourceId, name);
+                }
+            }
+            const render = (presentation, replaces) => renderCommentArchive(inventory, destination.kind, {
+                sourceUrl: page.url,
+                ...(zip ? { archiveName: archiveResource?.name ?? zip.name, archiveHref: archiveResource?.url ?? archiveResource?.name ?? zip.name } : {}),
+                ...(replaces ? { archiveReplaces: replaces } : {}),
+                attachmentNames,
+                pages: input.destinationPages,
+                sourcePages: input.sourcePages,
+                presentation,
+            });
+            const archiveState = zip ? {
+                ...(archiveResource ? { archiveResourceId: archiveResource.id } : {}),
+                archiveName: archiveResource?.name ?? zip.name,
+                archivePath: zip.path,
+                archiveSha256: zip.sha256,
+            } : {};
+            const replacement = destination.capabilities.updateComments ? undefined : current?.id;
+            let expectedBody = render('native', replacement);
+            let fallbackReason;
+            let fullArchiveState = {};
+            const maximumInlineBytes = 1_000_000;
+            const prepareFullArchive = async (reason) => {
+                if (fullArchiveState.fullArchiveName)
+                    return;
+                const fullBody = renderCommentArchive(inventory, 'markdown', {
+                    sourceUrl: page.url,
+                    ...(zip ? { archiveName: archiveResource?.name ?? zip.name, archiveHref: archiveResource?.url ?? archiveResource?.name ?? zip.name } : {}),
+                    ...(replacement ? { archiveReplaces: replacement } : {}),
+                    attachmentNames,
+                    pages: input.destinationPages,
+                    sourcePages: input.sourcePages,
+                });
+                const fullArchiveName = `ywtc-comments-${safeFilename(page.id)}-${fingerprint.slice(0, 12)}.md`;
+                const fullArchivePath = path.join(input.cacheDirectory, 'comments', sha256(page.canonicalId).slice(0, 16), fullArchiveName);
+                await mkdir(path.dirname(fullArchivePath), { recursive: true, mode: 0o700 });
+                await writeFile(fullArchivePath, `${fullBody}\n`, { mode: 0o600 });
+                const fullArchiveSha256 = sha256(`${fullBody}\n`);
+                const fullArchiveResource = await uploadArchive({
+                    path: fullArchivePath,
+                    name: fullArchiveName,
+                    size: Buffer.byteLength(`${fullBody}\n`),
+                    sha256: fullArchiveSha256,
+                }, previous?.fullArchiveResourceId, 'text/markdown');
+                const destinationFullArchiveName = fullArchiveResource.name;
+                expectedBody = renderCommentArchiveIndex(inventory, destination.kind, {
+                    sourceUrl: page.url,
+                    fullArchiveName: destinationFullArchiveName,
+                    fullArchiveHref: fullArchiveResource.url ?? destinationFullArchiveName,
+                    ...(zip ? { archiveName: archiveResource?.name ?? zip.name, archiveHref: archiveResource?.url ?? archiveResource?.name ?? zip.name } : {}),
+                });
+                fullArchiveState = {
+                    fullArchiveResourceId: fullArchiveResource.id,
+                    fullArchiveName: destinationFullArchiveName,
+                    fullArchivePath,
+                    fullArchiveSha256,
+                };
+                fallbackReason = reason;
+            };
+            if (Buffer.byteLength(expectedBody) > maximumInlineBytes) {
+                await prepareFullArchive(`Full comment archive exceeded ${maximumInlineBytes} inline bytes and was attached as Markdown.`);
+            }
+            let result = current;
+            const requiresWrite = !result || previous?.fingerprint !== fingerprint;
+            if (requiresWrite) {
+                const write = async (body) => {
+                    if (input.signal?.aborted)
+                        throw input.signal.reason ?? new Error('Transfer cancelled');
+                    if (!result || !destination.capabilities.updateComments || !destination.updateArchiveComment) {
+                        return destination.createArchiveComment({ page: destinationPage, body });
+                    }
+                    return destination.updateArchiveComment({ comment: result, body });
+                };
+                const presentations = fallbackReason ? [] : ['native', 'quote', 'code'];
+                let lastError;
+                if (fallbackReason) {
+                    result = await write(expectedBody);
+                }
+                else {
+                    for (const presentation of presentations) {
+                        try {
+                            expectedBody = render(presentation, replacement);
+                            result = await write(expectedBody);
+                            if (presentation !== 'native')
+                                fallbackReason = `Destination rejected the native collapsible archive; ${presentation} fallback was used.`;
+                            lastError = undefined;
+                            break;
+                        }
+                        catch (error) {
+                            lastError = error;
+                            const status = error.status;
+                            if (status === 413 || /(?:status[=: ]+413|too large|payload too large)/i.test(error instanceof Error ? error.message : String(error))) {
+                                try {
+                                    await prepareFullArchive('Destination rejected the inline archive size; the full archive was attached as Markdown.');
+                                    result = await write(expectedBody);
+                                    lastError = undefined;
+                                    break;
+                                }
+                                catch (fallbackError) {
+                                    lastError = fallbackError;
+                                }
+                            }
+                            const reconciled = await destination.findArchiveComment?.(destinationPage, fingerprint);
+                            if (reconciled) {
+                                result = reconciled;
+                                expectedBody = reconciled.body;
+                                fallbackReason = presentation === 'native' ? undefined : `Destination accepted the ${presentation} fallback after an ambiguous response.`;
+                                lastError = undefined;
+                                break;
+                            }
+                        }
+                    }
+                    if (lastError)
+                        throw lastError;
+                }
+            }
+            if (!result)
+                throw new Error('Destination comment archive was not created');
+            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');
+            }
+            if (!verification.ok)
+                throw new Error(`Comment verification failed: ${verification.differences.join('; ')}`);
+            const previousIds = result.id !== current?.id && current
+                ? [...new Set([...(previous?.previousDestinationIds ?? []), current.id])]
+                : previous?.previousDestinationIds;
+            const state = {
+                fingerprint,
+                destinationId: verified.id,
+                destinationFingerprint: verified.fingerprint,
+                ...(previousIds?.length ? { previousDestinationIds: previousIds } : {}),
+                ...archiveState,
+                ...fullArchiveState,
+                status: inventory.warnings.length > 0 || fallbackReason ? 'partial' : 'complete',
+                ...counts,
+                preview: verified.body,
+                ...(fallbackReason ? { lastError: fallbackReason } : {}),
+                updatedAt: now(),
+            };
+            pageState.comments = state;
+            await store.setPage({ ...pageState, comments: state, updatedAt: now() });
+            return state;
+        }
+        catch (error) {
+            if (input.signal?.aborted)
+                throw input.signal.reason ?? error;
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                fingerprint,
+                ...counts,
+                ...(pageState.comments?.destinationId ? { destinationId: pageState.comments.destinationId } : {}),
+                ...(pageState.comments?.destinationFingerprint ? { destinationFingerprint: pageState.comments.destinationFingerprint } : {}),
+                status: /conflict/i.test(message) ? 'conflict' : 'failed',
+                lastError: message,
+                updatedAt: now(),
+            };
+        }
+    }
     async transferRemote(input) {
-        const { source, destination, container, graph, options, store, report, sourceFingerprints, resourcesByPage } = input;
+        const { source, destination, container, graph, options, store, report, sourceFingerprints, resourcesByPage, commentsByPage } = input;
         const destinationPages = new Map();
         const stagingFailures = new Map();
         const sourcePages = new Map(graph.pages.map((page) => [page.canonicalId, page]));
         const bootstrapBodies = new Map();
         const totalResources = [...resourcesByPage.values()].reduce((total, resources) => total + resources.filter((resource) => resource.kind !== 'grid').length, 0);
-        const progress = { staged: 0, pages: 0, resources: 0 };
-        const totalUnits = Math.max(1, graph.pages.length * 2 + totalResources);
+        const totalCommentArchives = (options.comments ?? true) ? graph.pages.length : 0;
+        const progress = { staged: 0, pages: 0, resources: 0, comments: 0 };
+        const totalUnits = Math.max(1, graph.pages.length * 2 + totalResources + totalCommentArchives);
         const updateProgress = (active) => {
-            const completed = progress.staged + progress.pages + progress.resources;
-            options.onStatus?.(`Progress ${Math.min(100, Math.floor((completed / totalUnits) * 100))}% · pages ${progress.pages}/${graph.pages.length} · files ${progress.resources}/${totalResources} · ${active}`);
+            const completed = progress.staged + progress.pages + progress.resources + progress.comments;
+            options.onStatus?.(`Progress ${Math.min(100, Math.floor((completed / totalUnits) * 100))}% · pages ${progress.pages}/${graph.pages.length} · files ${progress.resources}/${totalResources} · comments ${progress.comments}/${totalCommentArchives} · ${active}`);
         };
         for (const page of graph.pages) {
             const [document, cachedPage] = await Promise.all([
@@ -551,15 +1114,47 @@ export class Migrator {
             const saved = store.value.pages[page.canonicalId];
             const parent = page.projectedParentId ? destinationPages.get(page.projectedParentId) : container;
             if (!parent) {
-                const message = `Destination parent is unavailable for ${page.title}`;
-                stagingFailures.set(page.canonicalId, { status: 'blocked', message });
-                report.updatePage(page.canonicalId, { status: 'blocked', error: message });
+                const upstream = page.projectedParentId ? stagingFailures.get(page.projectedParentId) : undefined;
+                const blockedByPageId = upstream?.blockedByPageId ?? page.projectedParentId ?? page.canonicalId;
+                const blockedByCode = upstream?.blockedByCode ?? 'destination-parent-unavailable';
+                const message = `Destination parent is unavailable for ${page.title}; blocked by ${blockedByPageId} (${blockedByCode})`;
+                const cause = { blockedByPageId, blockedByCode, blockedReason: message };
+                stagingFailures.set(page.canonicalId, { status: 'blocked', message, blockedByPageId, blockedByCode });
+                const previous = store.value.pages[page.canonicalId];
+                const resources = resourcesByPage.get(page.canonicalId) ?? [];
+                const comments = (options.comments ?? true)
+                    ? blockedCommentState(commentsByPage.get(page.canonicalId), previous?.comments, cause)
+                    : undefined;
+                await store.setPage({
+                    sourceId: page.id,
+                    sourceCanonicalId: page.canonicalId,
+                    sourceLocator: page.locator,
+                    sourceTitle: page.title,
+                    ...(page.projectedParentId ? { projectedParentId: page.projectedParentId } : {}),
+                    destinationTitle: previous?.destinationTitle ?? page.title,
+                    ...(previous?.destinationId ? { destinationId: previous.destinationId } : {}),
+                    ...(previous?.destinationCanonicalId ? { destinationCanonicalId: previous.destinationCanonicalId } : {}),
+                    ...(previous?.destinationLocator ? { destinationLocator: previous.destinationLocator } : {}),
+                    ...(previous?.previousDestinationIds ? { previousDestinationIds: previous.previousDestinationIds } : {}),
+                    sourceFingerprint: sourceFingerprints.get(page.canonicalId),
+                    ...(previous?.destinationFingerprint ? { destinationFingerprint: previous.destinationFingerprint } : {}),
+                    status: 'blocked',
+                    resources: blockedResourceStates(resources, previous?.resources ?? {}, cause),
+                    ...(comments ? { comments } : {}),
+                    degradations: previous?.degradations ?? [],
+                    ...cause,
+                    lastError: message,
+                    updatedAt: new Date().toISOString(),
+                });
+                report.updatePage(page.canonicalId, { status: 'blocked', error: message, ...cause });
                 report.issue({
                     code: 'destination-parent-unavailable',
-                    severity: 'error',
+                    severity: 'blocked',
                     phase: 'page',
                     pageId: page.canonicalId,
-                    retryable: true,
+                    retryable: false,
+                    blockedByPageId,
+                    blockedByCode,
                     message,
                 });
                 progress.staged += 1;
@@ -570,13 +1165,20 @@ export class Migrator {
                 const cachedPage = await loadCachedPage(options.cacheDirectory, page.canonicalId);
                 const bootstrap = bootstrapBodies.get(page.canonicalId);
                 let created;
-                let title = saved?.destinationTitle ?? page.title;
+                const title = saved?.destinationTitle ?? page.title;
                 let resourcesForState = saved?.resources ?? {};
+                let commentsForState = saved?.comments;
                 let previousDestinationIds = saved?.previousDestinationIds ?? [];
                 let mappingRecovered = false;
-                const findTitleConflict = (candidateTitle) => destination.findTitleConflict
-                    ? destination.findTitleConflict(parent, candidateTitle)
-                    : destination.findChild(parent, candidateTitle);
+                const allocatePage = (preferredTitle) => createPageWithAllocatedTitle({
+                    destination,
+                    parent,
+                    sourcePage: cachedPage,
+                    bootstrap,
+                    ...(preferredTitle ? { preferredTitle } : {}),
+                    consistencyOptions: this.consistencyOptions,
+                    report,
+                });
                 if (saved?.destinationId) {
                     const mapped = destinationFromState(saved, destination);
                     try {
@@ -598,79 +1200,11 @@ export class Migrator {
                         if (page.projectedParentId) {
                             await verifyConfirmedDestinationPage(destination, parent, this.consistencyOptions);
                         }
-                        const findRecoveryChild = (candidateTitle) => destination.findRecoverablePage
-                            ? destination.findRecoverablePage(parent, candidateTitle)
-                            : destination.findChild(parent, candidateTitle);
-                        let candidate;
-                        let recoveryLookupFailed = false;
-                        try {
-                            candidate = await findRecoveryChild(title);
-                        }
-                        catch (lookupError) {
-                            recoveryLookupFailed = true;
-                            report.issue({
-                                code: 'destination-recovery-lookup-failed',
-                                severity: 'warning',
-                                phase: 'page',
-                                pageId: page.canonicalId,
-                                retryable: true,
-                                message: `${page.title}: recovery lookup failed; bootstrap recreation will be attempted: ${lookupError instanceof Error ? lookupError.message : String(lookupError)}`,
-                            });
-                        }
-                        if (candidate && sourceDerivedTextMatches(bootstrap.body, candidate.content, destination.kind, cachedPage)) {
-                            created = candidate;
-                        }
-                        else {
-                            let recoveryTitle = title;
-                            let titleConflict = candidate;
-                            if (!titleConflict && !recoveryLookupFailed) {
-                                try {
-                                    titleConflict = await findTitleConflict(recoveryTitle);
-                                }
-                                catch (lookupError) {
-                                    recoveryLookupFailed = true;
-                                    report.issue({
-                                        code: 'destination-title-lookup-failed',
-                                        severity: 'warning',
-                                        phase: 'page',
-                                        pageId: page.canonicalId,
-                                        retryable: true,
-                                        message: `${page.title}: destination title lookup failed; bootstrap recreation will be attempted with a stable suffix: ${lookupError instanceof Error ? lookupError.message : String(lookupError)}`,
-                                    });
-                                }
-                            }
-                            if (titleConflict || recoveryLookupFailed) {
-                                const base = collisionTitle(page);
-                                const hash = sha256(page.canonicalId).slice(0, 8);
-                                recoveryTitle = base;
-                                let sequence = 0;
-                                while (!recoveryLookupFailed) {
-                                    try {
-                                        if (!await findTitleConflict(recoveryTitle))
-                                            break;
-                                        sequence += 1;
-                                        recoveryTitle = `${base} [${hash}${sequence > 1 ? `-${sequence}` : ''}]`;
-                                    }
-                                    catch (lookupError) {
-                                        recoveryLookupFailed = true;
-                                        recoveryTitle = `${base} [${hash}]`;
-                                        report.issue({
-                                            code: 'destination-recovery-lookup-failed',
-                                            severity: 'warning',
-                                            phase: 'page',
-                                            pageId: page.canonicalId,
-                                            retryable: true,
-                                            message: `${page.title}: suffixed-title lookup failed; bootstrap recreation will be attempted: ${lookupError instanceof Error ? lookupError.message : String(lookupError)}`,
-                                        });
-                                    }
-                                }
-                            }
-                            created = await destination.createPage({ container: parent, title: recoveryTitle, body: bootstrap.body });
-                            created = await verifyConfirmedDestinationPage(destination, created, this.consistencyOptions);
-                            assertDestinationContent(bootstrap.body, created.content, destination.kind, cachedPage);
-                        }
+                        const allocation = await allocatePage(title);
+                        created = allocation.page;
                         previousDestinationIds = [...new Set([...previousDestinationIds, mapped.id])];
                         resourcesForState = resetResourceDestinations(saved.resources);
+                        commentsForState = undefined;
                         mappingRecovered = true;
                         report.issue({
                             code: 'destination-mapping-recovered',
@@ -738,29 +1272,10 @@ export class Migrator {
                             });
                         }
                         else {
-                            let replacement = await destination.findChild(parent, title);
-                            const replacementMatches = replacement
-                                && sourceDerivedTextMatches(bootstrap.body, replacement.content, destination.kind, cachedPage);
-                            const titleConflict = replacementMatches ? undefined : replacement ?? await findTitleConflict(title);
-                            if (titleConflict) {
-                                const base = collisionTitle(page);
-                                const hash = sha256(page.canonicalId).slice(0, 8);
-                                title = base;
-                                let sequence = 0;
-                                while (await findTitleConflict(title)) {
-                                    sequence += 1;
-                                    title = `${base} [${hash}${sequence > 1 ? `-${sequence}` : ''}]`;
-                                }
-                                replacement = undefined;
-                            }
-                            created = replacement ?? await destination.createPage({ container: parent, title, body: bootstrap.body });
-                            created = await verifyConfirmedDestinationPage(destination, created, this.consistencyOptions);
-                            assertDestinationContent(bootstrap.body, created.content, destination.kind, cachedPage);
-                            if (created.parentId !== parent.id) {
-                                throw new Error(`Destination hierarchy verification failed for recreated page ${page.title}: expected parent ${parent.id}, received ${created.parentId ?? 'none'}`);
-                            }
+                            created = (await allocatePage(title)).page;
                             previousDestinationIds = [...new Set([...previousDestinationIds, oldPage.id])];
                             resourcesForState = resetResourceDestinations(saved.resources);
+                            commentsForState = undefined;
                             mappingRecovered = true;
                             report.addHierarchyRepair({
                                 sourceCanonicalId: page.canonicalId,
@@ -798,9 +1313,9 @@ export class Migrator {
                     };
                 }
                 else {
-                    const existingChild = await destination.findChild(parent, title);
-                    if (existingChild && sourceDerivedTextMatches(bootstrap.body, existingChild.content, destination.kind, cachedPage)) {
-                        created = existingChild;
+                    const allocation = await allocatePage(title);
+                    created = allocation.page;
+                    if (allocation.reused) {
                         mappingRecovered = true;
                         report.issue({
                             code: 'destination-unmapped-page-recovered',
@@ -811,22 +1326,6 @@ export class Migrator {
                             message: `${page.title}: adopted an existing source-derived page below the expected parent`,
                         });
                     }
-                    else {
-                        const titleConflict = existingChild ?? await findTitleConflict(title);
-                        if (titleConflict) {
-                            const base = collisionTitle(page);
-                            const hash = sha256(page.canonicalId).slice(0, 8);
-                            title = base;
-                            let sequence = 0;
-                            while (await findTitleConflict(title)) {
-                                sequence += 1;
-                                title = `${base} [${hash}${sequence > 1 ? `-${sequence}` : ''}]`;
-                            }
-                        }
-                        created = await destination.createPage({ container: parent, title, body: bootstrap.body });
-                        created = await verifyConfirmedDestinationPage(destination, created, this.consistencyOptions);
-                        assertDestinationContent(bootstrap.body, created.content, destination.kind, cachedPage);
-                    }
                 }
                 if (!options.dryRun && created.parentId !== parent.id) {
                     throw new Error(`Destination hierarchy verification failed for ${page.title}: expected parent ${parent.id}, received ${created.parentId ?? 'none'}`);
@@ -847,6 +1346,7 @@ export class Migrator {
                     ...(created.fingerprint ? { destinationFingerprint: created.fingerprint } : {}),
                     status: options.dryRun ? 'planned' : saved?.status ?? 'skeleton-created',
                     resources: resourcesForState,
+                    ...(commentsForState ? { comments: commentsForState } : {}),
                     degradations: saved?.degradations ?? [],
                     updatedAt: new Date().toISOString(),
                 };
@@ -854,12 +1354,20 @@ export class Migrator {
                 options.onStatus?.(`${options.dryRun ? 'Planned' : 'Staged content for'} ${page.title}`);
             }
             catch (error) {
+                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';
-                stagingFailures.set(page.canonicalId, { status: failureStatus, message });
+                const failureCode = failureStatus === 'conflict' ? 'destination-conflict' : 'destination-page-staging-failed';
+                stagingFailures.set(page.canonicalId, {
+                    status: failureStatus,
+                    message,
+                    blockedByPageId: page.canonicalId,
+                    blockedByCode: failureCode,
+                });
                 report.updatePage(page.canonicalId, { status: failureStatus, error: message });
                 report.issue({
-                    code: failureStatus === 'conflict' ? 'destination-conflict' : 'destination-page-staging-failed',
+                    code: failureCode,
                     severity: 'error',
                     phase: 'page',
                     pageId: page.canonicalId,
@@ -867,8 +1375,29 @@ export class Migrator {
                     message,
                 });
                 const savedState = store.value.pages[page.canonicalId];
-                if (savedState)
-                    await store.setPage({ ...savedState, status: failureStatus, lastError: message, updatedAt: new Date().toISOString() });
+                if (!options.dryRun) {
+                    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 ?? {}),
+                        sourceId: page.id,
+                        sourceCanonicalId: page.canonicalId,
+                        sourceLocator: page.locator,
+                        sourceTitle: page.title,
+                        ...(page.projectedParentId ? { projectedParentId: page.projectedParentId } : {}),
+                        destinationTitle: savedState?.destinationTitle ?? page.title,
+                        sourceFingerprint: sourceFingerprints.get(page.canonicalId),
+                        status: failureStatus,
+                        resources: blockedResourceStates(resources, savedState?.resources ?? {}, cause),
+                        ...(comments ? { comments } : {}),
+                        degradations: savedState?.degradations ?? [],
+                        lastError: message,
+                        updatedAt: new Date().toISOString(),
+                    });
+                }
             }
             finally {
                 progress.staged += 1;
@@ -886,13 +1415,25 @@ export class Migrator {
             if (!destinationPage) {
                 const currentFailure = stagingFailures.get(page.canonicalId);
                 const failedState = store.value.pages[page.canonicalId];
+                const blockedBy = {
+                    blockedByPageId: currentFailure?.blockedByPageId ?? page.canonicalId,
+                    blockedByCode: currentFailure?.blockedByCode ?? 'destination-page-unavailable',
+                    blockedReason: currentFailure?.message ?? failedState?.lastError ?? 'Destination page with source-derived content was not created',
+                };
+                const commentState = failedState?.comments ?? ((options.comments ?? true)
+                    ? blockedCommentState(commentsByPage.get(page.canonicalId), undefined, blockedBy)
+                    : undefined);
                 report.addPage(reportPage({
                     page,
                     status: currentFailure?.status ?? 'blocked',
                     resources,
                     document,
                     ...(failedState?.resources ? { resourceStates: failedState.resources } : {}),
-                    ...(options.dryRun ? { resourceStatusOverride: 'planned' } : {}),
+                    resourceStatusOverride: options.dryRun ? 'planned' : 'blocked',
+                    commentsEnabled: options.comments ?? true,
+                    ...(commentsByPage.get(page.canonicalId) ? { commentInventory: commentsByPage.get(page.canonicalId) } : {}),
+                    ...(commentState ? { commentState } : {}),
+                    blockedBy,
                     error: currentFailure?.message ?? failedState?.lastError ?? 'Destination page with source-derived content was not created',
                 }));
                 progress.pages += 1;
@@ -1243,7 +1784,51 @@ export class Migrator {
                     const verification = assertDestinationContent(rendered.body, verified.content, destination.kind, cachedPage);
                     verificationDegradations = verification.status === 'partial' ? verification.differences : [];
                 }
-                const partial = rendered.degraded || resourceProblems.length > 0 || verificationDegradations.length > 0;
+                const commentInventory = commentsByPage.get(page.canonicalId);
+                const commentState = (options.comments ?? true)
+                    ? await this.transferRemoteComments({
+                        source,
+                        destination,
+                        page: cachedPage,
+                        destinationPage: verified,
+                        inventory: commentInventory,
+                        resources,
+                        pageState: state,
+                        cacheDirectory: options.cacheDirectory,
+                        dryRun: options.dryRun,
+                        destinationPages,
+                        sourcePages,
+                        report,
+                        store,
+                        ...(options.signal ? { signal: options.signal } : {}),
+                    })
+                    : {
+                        status: 'skipped',
+                        threads: 0,
+                        comments: 0,
+                        participants: 0,
+                        attachments: 0,
+                        bytes: 0,
+                        updatedAt: new Date().toISOString(),
+                    };
+                if (options.comments ?? true) {
+                    progress.comments += 1;
+                    updateProgress(`comments ${commentState.status} → ${page.title}`);
+                }
+                if (['failed', 'conflict', 'stale', 'partial'].includes(commentState.status)
+                    && !(commentState.status === 'failed' && commentInventory?.status === 'failed')
+                    && !(commentState.status === 'partial' && (commentInventory?.warnings.length ?? 0) > 0 && !commentState.lastError)) {
+                    report.issue({
+                        code: `comment-${commentState.status}`,
+                        severity: commentState.status === 'partial' || commentState.status === 'stale' ? 'degradation' : 'error',
+                        phase: 'comment',
+                        pageId: page.canonicalId,
+                        retryable: commentState.status === 'failed',
+                        message: `${page.title}: ${commentState.lastError ?? `comment archive is ${commentState.status}`}`,
+                    });
+                }
+                const commentPartial = !['complete', 'skipped', 'planned'].includes(commentState.status);
+                const partial = rendered.degraded || resourceProblems.length > 0 || verificationDegradations.length > 0 || commentPartial;
                 const lastResourceProblem = resourceProblems.at(-1);
                 const clearedState = { ...state };
                 delete clearedState.lastError;
@@ -1255,6 +1840,7 @@ export class Migrator {
                     destinationTitle: verified.title,
                     ...(verified.fingerprint ? { destinationFingerprint: verified.fingerprint } : {}),
                     status: options.dryRun ? 'planned' : partial ? 'partial' : 'complete',
+                    comments: commentState,
                     degradations: [...new Set([...rendered.warnings, ...resourceProblems, ...verificationDegradations])],
                     ...(lastResourceProblem ? { lastError: lastResourceProblem } : {}),
                     updatedAt: new Date().toISOString(),
@@ -1277,6 +1863,9 @@ export class Migrator {
                     resourceFallbacks: fallbackDetails,
                     warnings: [...rendered.warnings, ...verificationDegradations],
                     normalizations: rendered.normalizations,
+                    commentsEnabled: options.comments ?? true,
+                    ...(commentInventory ? { commentInventory } : {}),
+                    commentState,
                 }), { source: normalizedPreviewHtml(document), destination: renderedPreviewHtml(verified.content ?? rendered.body, destination.kind) });
             }
             catch (error) {
@@ -1324,6 +1913,9 @@ export class Migrator {
                     ...(options.dryRun ? { resourceStatusOverride: 'planned' } : {}),
                     resourceFallbacks: fallbackDetails,
                     error: message,
+                    commentsEnabled: options.comments ?? true,
+                    ...(commentsByPage.get(page.canonicalId) ? { commentInventory: commentsByPage.get(page.canonicalId) } : {}),
+                    ...(state.comments ? { commentState: state.comments } : {}),
                 }), actual?.content ? { source: normalizedPreviewHtml(document), destination: renderedPreviewHtml(actual.content, destination.kind) } : undefined);
             }
             finally {