@iwonz/ywtc 3.2.2 → 3.4.0

package/dist/migrator.js

@@ -4,10 +4,12 @@ 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 { commentAttachmentUses, createCommentArchiveZip, renderCommentArchive, renderCommentArchiveIndex, resolveCommentAttachmentReferences, verifyCommentArchive, } from './comments.js';
 import { ConfirmedDestinationMissingError, verifyConfirmedDestinationPage } from './consistency.js';
 import { assertTransferCapabilities } from './domain.js';
 import { FilesystemExporter } from './filesystem-export.js';
 import { discoverPageGraph } from './graph.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';
@@ -137,6 +139,14 @@ function reportPage(input) {
     });
     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 +176,20 @@ function reportPage(input) {
         warnings: [...new Set([...input.document.warnings, ...(input.warnings ?? [])])],
         normalizations: [...new Set([...(input.document.normalizations ?? []), ...(input.normalizations ?? [])])],
         ...(input.error ? { error: input.error } : {}),
+        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 } : {}),
+        },
     };
 }
 function runStatus(errors, warnings, degradations) {
@@ -211,11 +235,13 @@ export class Migrator {
         this.consistencyOptions = consistencyOptions;
     }
     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);
+        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([
@@ -239,10 +265,12 @@ 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);
+        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}`,
             source: { provider: source.kind, profile: source.profile.name, rootId: root.id, title: root.title, url: root.url },
             destination: options.destination.type === 'directory'
@@ -265,11 +293,14 @@ export class Migrator {
                 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
@@ -278,6 +309,7 @@ export class Migrator {
                 && 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);
@@ -305,8 +337,9 @@ export class Migrator {
             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 () => {
@@ -316,6 +349,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;
@@ -331,6 +394,8 @@ export class Migrator {
                     status: 'planned',
                     resources,
                     document,
+                    commentsEnabled,
+                    ...(commentInventory ? { commentInventory } : {}),
                 }), undefined, false);
                 status(`Inspected ${page.title} · ${resources.length} resources`);
             }
@@ -348,6 +413,7 @@ 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);
@@ -360,14 +426,14 @@ export class Migrator {
                 });
             throw new MigrationRunError('Resource preflight failed before destination mutation', reportPaths, stateLocation.filename);
         }
-        const planSummary = `Plan ready: ${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`;
+        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);
@@ -387,6 +453,7 @@ export class Migrator {
                     report,
                     sourceFingerprints,
                     resourcesByPage,
+                    commentsByPage,
                 });
                 output = container.url;
                 report.output('destination', container.url);
@@ -431,7 +498,7 @@ export class Migrator {
             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);
@@ -450,6 +517,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),
         });
@@ -473,7 +542,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,
@@ -489,6 +559,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({
@@ -499,7 +582,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);
@@ -507,18 +618,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([
@@ -566,8 +987,12 @@ export class Migrator {
                 let created;
                 let 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);
                 if (saved?.destinationId) {
                     const mapped = destinationFromState(saved, destination);
                     try {
@@ -613,14 +1038,31 @@ export class Migrator {
                         }
                         else {
                             let recoveryTitle = title;
-                            if (candidate) {
+                            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 findRecoveryChild(recoveryTitle))
+                                        if (!await findTitleConflict(recoveryTitle))
                                             break;
                                         sequence += 1;
                                         recoveryTitle = `${base} [${hash}${sequence > 1 ? `-${sequence}` : ''}]`;
@@ -645,6 +1087,7 @@ export class Migrator {
                         }
                         previousDestinationIds = [...new Set([...previousDestinationIds, mapped.id])];
                         resourcesForState = resetResourceDestinations(saved.resources);
+                        commentsForState = undefined;
                         mappingRecovered = true;
                         report.issue({
                             code: 'destination-mapping-recovered',
@@ -670,6 +1113,92 @@ export class Migrator {
                         created = await verifyConfirmedDestinationPage(destination, created, this.consistencyOptions);
                         assertDestinationContent(bootstrap.body, created.content, destination.kind, cachedPage);
                     }
+                    if (!mappingRecovered && created.parentId !== parent.id) {
+                        const oldPage = created;
+                        if (options.dryRun) {
+                            report.addHierarchyRepair({
+                                sourceCanonicalId: page.canonicalId,
+                                mode: destination.capabilities.reparentPages && destination.reparentPage ? 'moved' : 'recreated',
+                                ...(created.parentId ? { oldParentId: created.parentId } : {}),
+                                newParentId: parent.id,
+                                oldDestinationId: created.id,
+                                newDestinationId: created.id,
+                                verified: false,
+                            });
+                        }
+                        else if (destination.capabilities.reparentPages && destination.reparentPage) {
+                            created = await destination.reparentPage({
+                                page: created,
+                                parent,
+                                ...(created.fingerprint ? { expectedFingerprint: created.fingerprint } : {}),
+                            });
+                            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'}`);
+                            }
+                            report.addHierarchyRepair({
+                                sourceCanonicalId: page.canonicalId,
+                                mode: 'moved',
+                                ...(oldPage.parentId ? { oldParentId: oldPage.parentId } : {}),
+                                newParentId: parent.id,
+                                oldDestinationId: oldPage.id,
+                                newDestinationId: created.id,
+                                verified: true,
+                            });
+                            report.issue({
+                                code: 'destination-hierarchy-repaired',
+                                severity: 'normalization',
+                                phase: 'page',
+                                pageId: page.canonicalId,
+                                retryable: false,
+                                message: `${page.title}: moved destination page ${created.id} from parent ${oldPage.parentId ?? 'none'} to ${parent.id} and verified the hierarchy`,
+                            });
+                        }
+                        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'}`);
+                            }
+                            previousDestinationIds = [...new Set([...previousDestinationIds, oldPage.id])];
+                            resourcesForState = resetResourceDestinations(saved.resources);
+                            commentsForState = undefined;
+                            mappingRecovered = true;
+                            report.addHierarchyRepair({
+                                sourceCanonicalId: page.canonicalId,
+                                mode: 'recreated',
+                                ...(oldPage.parentId ? { oldParentId: oldPage.parentId } : {}),
+                                newParentId: parent.id,
+                                oldDestinationId: oldPage.id,
+                                newDestinationId: created.id,
+                                verified: true,
+                            });
+                            report.issue({
+                                code: 'destination-hierarchy-recreated',
+                                severity: 'normalization',
+                                phase: 'page',
+                                pageId: page.canonicalId,
+                                retryable: false,
+                                message: `${page.title}: created verified replacement ${created.id} below ${parent.id}; previous page ${oldPage.id} was left untouched`,
+                            });
+                        }
+                    }
                 }
                 else if (options.dryRun) {
                     created = {
@@ -680,25 +1209,45 @@ export class Migrator {
                         title,
                         url: container.url,
                         locator: `dry-run:${page.id}`,
+                        parentId: parent.id,
                         content: bootstrap.body,
                         contentLength: Buffer.byteLength(bootstrap.body),
                         ...(container.space ? { space: container.space } : {}),
                     };
                 }
                 else {
-                    if (await destination.findChild(parent, title)) {
-                        const base = collisionTitle(page);
-                        const hash = sha256(page.canonicalId).slice(0, 8);
-                        title = base;
-                        let sequence = 0;
-                        while (await destination.findChild(parent, title)) {
-                            sequence += 1;
-                            title = `${base} [${hash}${sequence > 1 ? `-${sequence}` : ''}]`;
+                    const existingChild = await destination.findChild(parent, title);
+                    if (existingChild && sourceDerivedTextMatches(bootstrap.body, existingChild.content, destination.kind, cachedPage)) {
+                        created = existingChild;
+                        mappingRecovered = true;
+                        report.issue({
+                            code: 'destination-unmapped-page-recovered',
+                            severity: 'normalization',
+                            phase: 'page',
+                            pageId: page.canonicalId,
+                            retryable: false,
+                            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);
                     }
-                    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'}`);
                 }
                 destinationPages.set(page.canonicalId, created);
                 const next = {
@@ -716,6 +1265,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(),
                 };
@@ -723,6 +1273,8 @@ 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 });
@@ -762,6 +1314,9 @@ export class Migrator {
                     document,
                     ...(failedState?.resources ? { resourceStates: failedState.resources } : {}),
                     ...(options.dryRun ? { resourceStatusOverride: 'planned' } : {}),
+                    commentsEnabled: options.comments ?? true,
+                    ...(commentsByPage.get(page.canonicalId) ? { commentInventory: commentsByPage.get(page.canonicalId) } : {}),
+                    ...(failedState?.comments ? { commentState: failedState.comments } : {}),
                     error: currentFailure?.message ?? failedState?.lastError ?? 'Destination page with source-derived content was not created',
                 }));
                 progress.pages += 1;
@@ -805,7 +1360,9 @@ export class Migrator {
                 await store.setPage({ ...state, status: 'partial', lastError: detail, updatedAt: new Date().toISOString() });
             };
             try {
-                let remoteResources = options.dryRun ? [] : await destination.listUploadedResources(destinationPage);
+                let remoteResources = options.dryRun || transferableResources.length === 0
+                    ? []
+                    : await destination.listUploadedResources(destinationPage);
                 const nameAllocator = new DestinationNameAllocator(remoteResources.map((resource) => resource.name));
                 for (const resourceState of Object.values(state.resources)) {
                     if (resourceState.status === 'complete')
@@ -1004,6 +1561,9 @@ export class Migrator {
                 };
                 const rendered = await renderRemoteDocument({ destination, container, document, page: cachedPage, context });
                 if (rendered.degraded && !options.dryRun) {
+                    if (transferableResources.length === 0) {
+                        remoteResources = await destination.listUploadedResources(destinationPage);
+                    }
                     const extension = page.rawFormat === 'yfm' ? 'yfm' : 'storage.xml';
                     const snapshotName = `ywtc-source-${sha256(page.canonicalId).slice(0, 8)}.${extension}`;
                     const snapshotPath = path.join(options.cacheDirectory, 'snapshots', snapshotName);
@@ -1107,7 +1667,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;
@@ -1119,6 +1723,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(),
@@ -1141,6 +1746,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) {
@@ -1188,6 +1796,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 {