@iwonz/ywtc 3.4.0 → 3.5.0

package/dist/migrator.js

@@ -1,18 +1,23 @@
 import { createHash } from 'node:crypto';
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 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 { secretValues } from './config.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 {
@@ -65,10 +70,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);
@@ -104,6 +105,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}`);
@@ -120,6 +188,19 @@ function destinationFromState(state, adapter) {
     };
 }
 function reportPage(input) {
+    const inventory = input.commentInventory;
+    const commentResourceIds = new Set();
+    for (const thread of inventory?.threads ?? []) {
+        const stack = [thread.root];
+        while (stack.length > 0) {
+            const entry = stack.pop();
+            for (const attachment of entry.attachments) {
+                if (attachment.resourceId)
+                    commentResourceIds.add(attachment.resourceId);
+            }
+            stack.push(...entry.replies);
+        }
+    }
     const transferable = input.resources.filter((resource) => resource.kind !== 'grid');
     const resourceItems = transferable.map((resource) => {
         const state = input.resourceStates?.[resource.id];
@@ -128,36 +209,74 @@ function reportPage(input) {
         return {
             sourceId: resource.id,
             sourceName: resource.name,
-            kind: resource.kind,
+            ...(resource.downloadUrl ? { sourceUrl: resource.downloadUrl } : {}),
+            ...(resource.referenceAliases?.[0] ? { sourceReference: resource.referenceAliases[0] } : {}),
+            kind: commentResourceIds.has(resource.id) ? 'comment-attachment' : resource.kind,
             status,
             ...(sourceBytes !== undefined ? { sourceBytes } : {}),
             ...(status === 'complete' && sourceBytes !== undefined ? { transferredBytes: sourceBytes } : {}),
             ...(state?.destinationId ? { destinationId: state.destinationId } : {}),
             ...(state?.destinationName ? { destinationName: state.destinationName } : {}),
+            ...(state?.destinationUrl ? { destinationUrl: state.destinationUrl } : {}),
+            ...(state?.sha256 ? { sha256: state.sha256 } : {}),
             ...(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;
+    const commentItems = inventory?.threads.flatMap((thread) => {
+        const result = [];
+        const visit = (entry) => {
+            const author = entry.author.displayName
+                ?? entry.author.username
+                ?? entry.author.publicName
+                ?? entry.author.providerId;
+            result.push({
+                threadId: thread.id,
+                commentId: entry.id,
+                ...(entry.parentId ? { parentId: entry.parentId } : {}),
+                author,
+                ...(entry.createdAt ? { createdAt: entry.createdAt } : {}),
+                ...(entry.status ? { sourceStatus: entry.status } : {}),
+                outcome: commentStatus,
+                sourceUrl: `${input.page.url}#comment-${encodeURIComponent(entry.id)}`,
+                ...(commentState?.destinationUrl ? { destinationUrl: commentState.destinationUrl } : {}),
+                ...(commentError ? { error: commentError } : {}),
+            });
+            for (const reply of entry.replies)
+                visit(reply);
+        };
+        visit(thread.root);
+        return result;
+    });
     return {
         sourceCanonicalId: input.page.canonicalId,
         sourceId: input.page.id,
         sourceTitle: input.page.title,
         sourceUrl: input.page.url,
+        ...(input.page.parentId ? { sourceParentId: input.page.parentId } : {}),
+        ...(input.page.ancestorIds?.length ? { sourceAncestorIds: input.page.ancestorIds } : {}),
         ...(input.destination ? {
             destinationId: input.destination.id,
             destinationTitle: input.destination.title,
             destinationUrl: input.destination.url,
+            ...(input.destination.parentId ? { destinationParentId: input.destination.parentId } : {}),
         } : {}),
-        ...(input.page.projectedParentId ? { parentId: input.page.projectedParentId } : {}),
+        ...(input.destinationFile ? {
+            destinationId: input.destinationFile.id,
+            destinationTitle: input.page.title,
+            destinationUrl: input.destinationFile.url,
+            ...(input.destinationFile.parentId ? { destinationParentId: input.destinationFile.parentId } : {}),
+        } : {}),
+        ...(input.page.projectedParentId ? { parentId: input.page.projectedParentId, projectedParentId: input.page.projectedParentId } : {}),
         depth: input.page.depth,
         status: input.status,
         inventoryStatus: input.inventoryStatus ?? 'complete',
@@ -176,6 +295,7 @@ 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,
@@ -184,14 +304,51 @@ function reportPage(input) {
             attachments: commentState?.attachments ?? inventory?.attachments ?? 0,
             bytes: commentState?.bytes ?? inventory?.knownBytes ?? 0,
             ...(commentState?.archiveName ? { archiveName: commentState.archiveName } : {}),
+            ...(commentState?.archiveUrl ? { archiveUrl: commentState.archiveUrl } : {}),
             ...(commentState?.destinationId ? { destinationId: commentState.destinationId } : {}),
+            ...(commentState?.destinationUrl ? { destinationUrl: commentState.destinationUrl } : {}),
             ...(commentState?.previousDestinationIds?.length ? { revision: true } : {}),
             ...(commentState?.status === 'stale' ? { stale: true } : {}),
             ...(commentError ? { error: commentError } : {}),
             ...(commentState?.preview ? { preview: commentState.preview } : {}),
+            ...(commentItems?.length ? { items: commentItems } : {}),
+            ...(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) {
     if (errors > 0)
         return 'partial';
@@ -200,6 +357,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;
@@ -216,7 +384,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) {
@@ -267,6 +435,7 @@ export class Migrator {
             await store.save();
         const run = await store.beginRun(options.scope, options.dryRun, sourceStatus, commentsEnabled);
         const report = new TransferReport({
+            secrets: secretValues(this.config),
             dryRun: options.dryRun,
             commentsEnabled,
             scope: options.scope,
@@ -329,11 +498,7 @@ 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();
@@ -419,13 +584,58 @@ export class Migrator {
             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);
         }
+        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);
@@ -436,6 +646,8 @@ export class Migrator {
                 const result = await this.exportFilesystem(source, graph, options.destination, options, stateLocation.id, store, report, sourceFingerprints, resourcesByPage, commentsByPage);
                 output = result.directory;
                 archive = result.archive;
+                const exportEntry = path.join(result.directory, options.destination.format === 'html' ? 'index.html' : 'index.md');
+                report.setDestinationUrl(pathToFileURL(exportEntry).toString());
                 report.output('directory', result.directory);
                 if (result.archive)
                     report.output('archive', result.archive);
@@ -460,14 +672,11 @@ export class Migrator {
             }
             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,
@@ -486,14 +695,11 @@ 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 });
         }
@@ -536,6 +742,7 @@ export class Migrator {
                         sourceName: sourceResource?.name ?? resource.name,
                         destinationId: resource.path,
                         destinationName: resource.name,
+                        destinationUrl: pathToFileURL(path.join(destination.path, resource.path)).toString(),
                         ...(resource.sha256 ? { sha256: resource.sha256 } : {}),
                         ...(resource.size !== undefined ? { size: resource.size } : {}),
                         status: options.dryRun ? 'planned' : 'complete',
@@ -574,8 +781,16 @@ export class Migrator {
                     } } : {}),
                 updatedAt: new Date().toISOString(),
             });
+            const parentManifestPage = manifestPage?.parentId
+                ? result.manifest.pages.find((item) => item.sourceCanonicalId === manifestPage.parentId)
+                : undefined;
             report.addPage(reportPage({
                 page,
+                ...(manifestPage ? { destinationFile: {
+                        id: manifestPage.path,
+                        url: pathToFileURL(path.join(destination.path, manifestPage.path)).toString(),
+                        ...(parentManifestPage ? { parentId: parentManifestPage.path } : {}),
+                    } } : {}),
                 status: pageStatus,
                 resources: sourceResources,
                 document,
@@ -780,6 +995,7 @@ export class Migrator {
             const archiveState = zip ? {
                 ...(archiveResource ? { archiveResourceId: archiveResource.id } : {}),
                 archiveName: archiveResource?.name ?? zip.name,
+                ...(archiveResource?.url ? { archiveUrl: archiveResource.url } : {}),
                 archivePath: zip.path,
                 archiveSha256: zip.sha256,
             } : {};
@@ -899,6 +1115,7 @@ export class Migrator {
                 fingerprint,
                 destinationId: verified.id,
                 destinationFingerprint: verified.fingerprint,
+                ...(verified.url ? { destinationUrl: verified.url } : {}),
                 ...(previousIds?.length ? { previousDestinationIds: previousIds } : {}),
                 ...archiveState,
                 ...fullArchiveState,
@@ -966,15 +1183,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;
@@ -985,14 +1234,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 {
@@ -1014,77 +1269,8 @@ 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;
@@ -1155,27 +1341,7 @@ 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;
@@ -1216,9 +1382,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',
@@ -1229,22 +1395,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'}`);
@@ -1277,10 +1427,16 @@ export class Migrator {
                     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,
@@ -1288,8 +1444,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;
@@ -1307,16 +1484,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) } : {}),
-                    ...(failedState?.comments ? { commentState: failedState.comments } : {}),
+                    ...(commentState ? { commentState } : {}),
+                    blockedBy,
                     error: currentFailure?.message ?? failedState?.lastError ?? 'Destination page with source-derived content was not created',
                 }));
                 progress.pages += 1;
@@ -1418,6 +1604,7 @@ export class Migrator {
                                 sourceName: resource.name,
                                 destinationId: mappedRemote.id,
                                 destinationName: mappedRemote.name,
+                                ...(mappedRemote.url ? { destinationUrl: mappedRemote.url } : {}),
                                 sha256: downloaded.sha256,
                                 size: downloaded.size,
                                 cachePath: downloaded.path,
@@ -1441,6 +1628,7 @@ export class Migrator {
                                 sourceName: resource.name,
                                 destinationId: reconciled.id,
                                 destinationName: reconciled.name,
+                                ...(reconciled.url ? { destinationUrl: reconciled.url } : {}),
                                 sha256: downloaded.sha256,
                                 size: downloaded.size,
                                 cachePath: downloaded.path,
@@ -1504,6 +1692,7 @@ export class Migrator {
                             sourceName: resource.name,
                             destinationId: result.id,
                             destinationName: result.name,
+                            ...(result.url ? { destinationUrl: result.url } : {}),
                             sha256: downloaded.sha256,
                             size: downloaded.size,
                             cachePath: downloaded.path,