@stll/folio-core 0.37.4 → 0.38.0

package/dist/compare/content-alignment.js

@@ -7,7 +7,8 @@ import { panic } from "better-result";
 * The block walk is split by structural container before any textual
 * alignment runs. Body blocks are compared with body blocks; tables are
 * aligned table by table, then row by row and cell by cell. All quadratic
-* text alignment in one caller-owned work session shares one hard budget.
+* structural candidate alignment in one caller-owned work session shares
+* one hard budget; block exact-text anchors are gap-local and non-quadratic.
 */
 const MAX_CONTENT_ALIGNMENT_LCS_CELLS = 4e6;
 const MAX_CONTENT_STRUCTURE_TOKEN_LOOKUPS = 4e6;
@@ -28,6 +29,13 @@ const claimFolioContentAlignmentCells = (baseCount, revisedCount, workSession) =
 	workSession.remainingLcsCells -= baseCount * revisedCount;
 	return true;
 };
+const NON_WHITESPACE = /\S/u;
+const PARAGRAPH_MARK_KIND_FAMILY = {
+	heading: "paragraphMark",
+	listItem: "paragraphMark",
+	paragraph: "paragraphMark"
+};
+const blockKindsCanPair = (baseKind, revisedKind) => baseKind === revisedKind || Object.hasOwn(PARAGRAPH_MARK_KIND_FAMILY, baseKind) && Object.hasOwn(PARAGRAPH_MARK_KIND_FAMILY, revisedKind);
 const folioContentIdStability = (block) => block.idStability ?? "stable";
 /**
 * Longest strictly increasing subsequence by revised index.
@@ -91,20 +99,75 @@ const longestIncreasingFolioContentPairs = (pairs) => {
 	}
 	return ordered.toReversed();
 };
-const pairByStableId = (base, revised, idStability) => {
-	const revisedIndexById = /* @__PURE__ */ new Map();
-	revised.forEach((block, revisedIndex) => {
-		if (idStability(block) === "stable") revisedIndexById.set(block.id, revisedIndex);
-	});
+const containerPathKeyOf = ({ containerPath }) => containerPath === void 0 || containerPath.length === 0 ? null : JSON.stringify(containerPath.map(({ kind, id }) => [kind, id]));
+const blockPairingTableFactsOf = ({ table }) => {
+	if (!table) return { type: "body" };
+	return {
+		type: "table",
+		outerTableIndex: table.outerTableIndex,
+		tableIndex: table.tableIndex,
+		rowIndex: table.rowIndex,
+		cellIndex: table.cellIndex
+	};
+};
+const prepareAlignmentBlocks = ({ baseBlocks, revisedBlocks, idStability }) => {
+	const ROOT_CONTAINER_PATH_TOKEN = 0;
+	const containerPathTokens = /* @__PURE__ */ new Map();
+	let nextContainerPathToken = 1;
+	const containerPathTokenOf = (block) => {
+		const key = containerPathKeyOf(block);
+		if (key === null) return ROOT_CONTAINER_PATH_TOKEN;
+		const existing = containerPathTokens.get(key);
+		if (existing !== void 0) return existing;
+		const token = nextContainerPathToken++;
+		containerPathTokens.set(key, token);
+		return token;
+	};
+	const prepare = (blocks) => blocks.map((block, index) => ({
+		block,
+		index,
+		pairingFacts: {
+			containerPathToken: containerPathTokenOf(block),
+			id: block.id,
+			idStability: idStability(block),
+			kind: block.kind,
+			table: blockPairingTableFactsOf(block)
+		}
+	}));
+	return {
+		base: prepare(baseBlocks),
+		revised: prepare(revisedBlocks)
+	};
+};
+/** Every alignment pass shares this complete structural pairing policy. */
+const blocksCanPair = ({ base, revised, stableIdMismatch, structuralScope }) => {
+	if (!blockKindsCanPair(base.kind, revised.kind) || base.containerPathToken !== revised.containerPathToken) return false;
+	if (base.table.type !== revised.table.type) return false;
+	if (structuralScope === "document" && base.table.type === "table" && revised.table.type === "table" && (base.table.outerTableIndex !== revised.table.outerTableIndex || base.table.tableIndex !== revised.table.tableIndex || base.table.rowIndex !== revised.table.rowIndex || base.table.cellIndex !== revised.table.cellIndex)) return false;
+	return !(stableIdMismatch === "separate" && base.idStability === "stable" && revised.idStability === "stable" && base.id !== revised.id);
+};
+const uniqueStableBlocks = (blocks) => {
+	const blocksById = /* @__PURE__ */ new Map();
+	for (const block of blocks) {
+		if (block.pairingFacts.idStability !== "stable") continue;
+		blocksById.set(block.pairingFacts.id, blocksById.has(block.pairingFacts.id) ? null : block);
+	}
+	return blocksById;
+};
+/** Stable identity is authoritative only when it is unique on both sides. */
+const pairByStableId = ({ base, revised, canPair }) => {
+	const baseBlockById = uniqueStableBlocks(base);
+	const revisedBlockById = uniqueStableBlocks(revised);
 	const candidates = [];
-	base.forEach((block, baseIndex) => {
-		if (idStability(block) !== "stable") return;
-		const revisedIndex = revisedIndexById.get(block.id);
-		if (revisedIndex !== void 0) candidates.push({
-			baseIndex,
-			revisedIndex
+	for (const baseBlock of base) {
+		if (baseBlockById.get(baseBlock.pairingFacts.id) !== baseBlock) continue;
+		const revisedBlock = revisedBlockById.get(baseBlock.pairingFacts.id);
+		if (!revisedBlock) continue;
+		if (canPair(baseBlock, revisedBlock)) candidates.push({
+			baseIndex: baseBlock.index,
+			revisedIndex: revisedBlock.index
 		});
-	});
+	}
 	return longestIncreasingFolioContentPairs(candidates);
 };
 /**
@@ -116,180 +179,191 @@ const pairByStableId = (base, revised, idStability) => {
 * already bounded by stable/exact anchors, so it cannot turn a positional id
 * into a move or pull a block across an established correspondence.
 */
-const pairByResidualIdContinuity = ({ baseBlocks, revisedBlocks, baseFrom, baseTo, revisedFrom, revisedTo, idStability }) => {
-	const uniqueIndexesById = ({ blocks, from, to }) => {
-		const indexes = /* @__PURE__ */ new Map();
+const pairByResidualIdContinuity = ({ baseBlocks, revisedBlocks, baseFrom, baseTo, revisedFrom, revisedTo, canPair }) => {
+	const uniqueBlocksById = ({ blocks, from, to }) => {
+		const blocksById = /* @__PURE__ */ new Map();
 		for (let index = from; index < to; index++) {
-			const id = blocks[index]?.id;
-			if (id === void 0) continue;
-			indexes.set(id, indexes.has(id) ? null : index);
+			const block = blocks[index];
+			if (!block) continue;
+			blocksById.set(block.pairingFacts.id, blocksById.has(block.pairingFacts.id) ? null : block);
 		}
-		return indexes;
+		return blocksById;
 	};
-	const baseIndexes = uniqueIndexesById({
+	const baseBlocksById = uniqueBlocksById({
 		blocks: baseBlocks,
 		from: baseFrom,
 		to: baseTo
 	});
-	const revisedIndexes = uniqueIndexesById({
+	const revisedBlocksById = uniqueBlocksById({
 		blocks: revisedBlocks,
 		from: revisedFrom,
 		to: revisedTo
 	});
 	const candidates = [];
-	for (const [id, baseIndex] of baseIndexes) {
-		const revisedIndex = revisedIndexes.get(id);
-		if (baseIndex === null || revisedIndex === void 0 || revisedIndex === null) continue;
-		const baseBlock = baseBlocks[baseIndex];
-		const revisedBlock = revisedBlocks[revisedIndex];
+	for (const [id, baseBlock] of baseBlocksById) {
+		const revisedBlock = revisedBlocksById.get(id);
 		if (!baseBlock || !revisedBlock) continue;
-		if (idStability(baseBlock) === idStability(revisedBlock)) continue;
+		if (baseBlock.pairingFacts.idStability === revisedBlock.pairingFacts.idStability || !canPair(baseBlock, revisedBlock)) continue;
 		candidates.push({
-			baseIndex,
-			revisedIndex
+			baseIndex: baseBlock.index,
+			revisedIndex: revisedBlock.index
 		});
 	}
 	return longestIncreasingFolioContentPairs(candidates);
 };
-const pairByExactText = (base, revised, workSession, idStability, stableIdMismatch) => {
-	const baseCount = base.length;
-	const revisedCount = revised.length;
-	if (baseCount === 0 || revisedCount === 0) return [];
-	if (!claimFolioContentAlignmentCells(baseCount, revisedCount, workSession)) return [];
-	const textKeys = /* @__PURE__ */ new Map();
-	let nextTextKey = 0;
-	const internText = (text) => {
-		const existing = textKeys.get(text);
-		if (existing !== void 0) return existing;
-		const key = nextTextKey++;
-		textKeys.set(text, key);
-		return key;
-	};
-	const baseTextKeys = base.map(({ block }) => internText(block.text));
-	const revisedTextKeys = revised.map(({ block }) => internText(block.text));
-	const entriesCanPair = (baseIndex, revisedIndex) => {
-		const baseBlock = base[baseIndex]?.block;
-		const revisedBlock = revised[revisedIndex]?.block;
-		if (!baseBlock || !revisedBlock || baseTextKeys[baseIndex] !== revisedTextKeys[revisedIndex]) return false;
-		return stableIdMismatch === "pair" || !(idStability(baseBlock) === "stable" && idStability(revisedBlock) === "stable" && baseBlock.id !== revisedBlock.id);
+/** Exact anchors are gap-local; repeated or blank text is not identity evidence. */
+const pairByUniqueExactText = ({ base, revised, baseFrom, baseTo, revisedFrom, revisedTo, canPair }) => {
+	const uniqueBlocks = (blocks, from, to) => {
+		const blocksByText = /* @__PURE__ */ new Map();
+		for (let index = from; index < to; index++) {
+			const block = blocks[index];
+			if (!block) continue;
+			const text = block.block.text;
+			if (!NON_WHITESPACE.test(text)) continue;
+			blocksByText.set(text, blocksByText.has(text) ? null : block);
+		}
+		return blocksByText;
 	};
-	const stride = revisedCount + 1;
-	const lengths = new Int32Array((baseCount + 1) * stride);
-	for (let baseIndex = baseCount - 1; baseIndex >= 0; baseIndex--) {
-		const rowOffset = baseIndex * stride;
-		const nextRowOffset = (baseIndex + 1) * stride;
-		for (let revisedIndex = revisedCount - 1; revisedIndex >= 0; revisedIndex--) lengths[rowOffset + revisedIndex] = entriesCanPair(baseIndex, revisedIndex) ? (lengths[nextRowOffset + revisedIndex + 1] ?? 0) + 1 : Math.max(lengths[nextRowOffset + revisedIndex] ?? 0, lengths[rowOffset + revisedIndex + 1] ?? 0);
+	const baseBlocksByText = uniqueBlocks(base, baseFrom, baseTo);
+	const revisedBlocksByText = uniqueBlocks(revised, revisedFrom, revisedTo);
+	const candidates = [];
+	for (const [text, baseBlock] of baseBlocksByText) {
+		const revisedBlock = revisedBlocksByText.get(text);
+		if (!baseBlock || !revisedBlock) continue;
+		if (canPair(baseBlock, revisedBlock)) candidates.push({
+			baseIndex: baseBlock.index,
+			revisedIndex: revisedBlock.index
+		});
 	}
-	const pairs = [];
-	let baseIndex = 0;
-	let revisedIndex = 0;
-	while (baseIndex < baseCount && revisedIndex < revisedCount) {
-		const baseEntry = base[baseIndex];
-		const revisedEntry = revised[revisedIndex];
-		if (!baseEntry || !revisedEntry) break;
-		if (entriesCanPair(baseIndex, revisedIndex)) {
-			pairs.push({
-				baseIndex: baseEntry.index,
-				revisedIndex: revisedEntry.index
-			});
-			baseIndex += 1;
-			revisedIndex += 1;
-			continue;
+	const orderedCandidates = candidates.toSorted((left, right) => left.baseIndex - right.baseIndex || left.revisedIndex - right.revisedIndex);
+	if (orderedCandidates.length === 0) return [];
+	const tailRevisedIndexes = [];
+	const tailCandidateIndexes = [];
+	const predecessors = new Int32Array(orderedCandidates.length).fill(-1);
+	orderedCandidates.forEach((candidate, candidateIndex) => {
+		let lower = 0;
+		let upper = tailRevisedIndexes.length;
+		while (lower < upper) {
+			const middle = lower + Math.floor((upper - lower) / 2);
+			if ((tailRevisedIndexes[middle] ?? Number.POSITIVE_INFINITY) < candidate.revisedIndex) lower = middle + 1;
+			else upper = middle;
 		}
-		if ((lengths[(baseIndex + 1) * stride + revisedIndex] ?? 0) >= (lengths[baseIndex * stride + revisedIndex + 1] ?? 0)) baseIndex += 1;
-		else revisedIndex += 1;
+		predecessors[candidateIndex] = lower === 0 ? -1 : tailCandidateIndexes[lower - 1] ?? -1;
+		tailRevisedIndexes[lower] = candidate.revisedIndex;
+		tailCandidateIndexes[lower] = candidateIndex;
+	});
+	const pairs = [];
+	for (let candidateIndex = tailCandidateIndexes.at(-1) ?? -1; candidateIndex !== -1; candidateIndex = predecessors[candidateIndex] ?? -1) {
+		const candidate = orderedCandidates[candidateIndex];
+		if (candidate) pairs.push(candidate);
+	}
+	return pairs.toReversed();
+};
+const pairsInAnchorGaps = ({ baseLength, revisedLength, anchors, pairGap }) => {
+	const pairs = [];
+	let baseFrom = 0;
+	let revisedFrom = 0;
+	for (const anchor of [...anchors, {
+		baseIndex: baseLength,
+		revisedIndex: revisedLength
+	}]) {
+		pairs.push(...pairGap(baseFrom, anchor.baseIndex, revisedFrom, anchor.revisedIndex));
+		baseFrom = anchor.baseIndex + 1;
+		revisedFrom = anchor.revisedIndex + 1;
 	}
 	return pairs;
 };
-const alignFolioContentBlocks = (baseBlocks, revisedBlocks, options = {}) => {
-	const workSession = options.workSession ?? createFolioContentAlignmentWorkSession();
+const alignFolioContentBlocksInScope = (baseBlocks, revisedBlocks, options) => {
 	const stableIdMismatch = options.stableIdMismatch ?? "separate";
 	const idStability = options.idStability ?? folioContentIdStability;
-	const stableIdAnchors = pairByStableId(baseBlocks, revisedBlocks, idStability);
-	const usedBaseIndexes = new Set(stableIdAnchors.map(({ baseIndex }) => baseIndex));
-	const usedRevisedIndexes = new Set(stableIdAnchors.map(({ revisedIndex }) => revisedIndex));
-	const baseRemaining = baseBlocks.flatMap((block, index) => usedBaseIndexes.has(index) ? [] : [{
-		block,
-		index
-	}]);
-	const revisedRemaining = revisedBlocks.flatMap((block, index) => usedRevisedIndexes.has(index) ? [] : [{
-		block,
-		index
-	}]);
-	const exactTextAnchors = pairByExactText(baseRemaining, revisedRemaining, workSession, idStability, stableIdMismatch);
-	const anchors = longestIncreasingFolioContentPairs([...stableIdAnchors, ...exactTextAnchors].toSorted((left, right) => left.baseIndex - right.baseIndex));
+	const prepared = prepareAlignmentBlocks({
+		baseBlocks,
+		revisedBlocks,
+		idStability
+	});
+	const canPair = (baseBlock, revisedBlock) => blocksCanPair({
+		base: baseBlock.pairingFacts,
+		revised: revisedBlock.pairingFacts,
+		stableIdMismatch,
+		structuralScope: options.structuralScope
+	});
+	const stableIdAnchors = pairByStableId({
+		base: prepared.base,
+		revised: prepared.revised,
+		canPair
+	});
+	const exactTextAnchors = pairsInAnchorGaps({
+		baseLength: prepared.base.length,
+		revisedLength: prepared.revised.length,
+		anchors: stableIdAnchors,
+		pairGap: (baseFrom, baseTo, revisedFrom, revisedTo) => pairByUniqueExactText({
+			base: prepared.base,
+			revised: prepared.revised,
+			baseFrom,
+			baseTo,
+			revisedFrom,
+			revisedTo,
+			canPair
+		})
+	});
+	const exactAndStableAnchors = [...stableIdAnchors, ...exactTextAnchors].toSorted((left, right) => left.baseIndex - right.baseIndex || left.revisedIndex - right.revisedIndex);
+	const continuityAnchors = pairsInAnchorGaps({
+		baseLength: prepared.base.length,
+		revisedLength: prepared.revised.length,
+		anchors: exactAndStableAnchors,
+		pairGap: (baseFrom, baseTo, revisedFrom, revisedTo) => pairByResidualIdContinuity({
+			baseBlocks: prepared.base,
+			revisedBlocks: prepared.revised,
+			baseFrom,
+			baseTo,
+			revisedFrom,
+			revisedTo,
+			canPair
+		})
+	});
+	const anchors = [...exactAndStableAnchors, ...continuityAnchors].toSorted((left, right) => left.baseIndex - right.baseIndex || left.revisedIndex - right.revisedIndex);
 	const events = [];
 	const emitPositionalGap = (baseFrom, baseTo, revisedFrom, revisedTo) => {
 		const pairedCount = Math.min(baseTo - baseFrom, revisedTo - revisedFrom);
 		for (let offset = 0; offset < pairedCount; offset++) {
-			const baseBlock = baseBlocks[baseFrom + offset];
-			const revisedBlock = revisedBlocks[revisedFrom + offset];
-			if (baseBlock && revisedBlock) if (idStability(baseBlock) === "stable" && idStability(revisedBlock) === "stable" && baseBlock.id !== revisedBlock.id && stableIdMismatch === "separate") {
+			const baseBlock = prepared.base[baseFrom + offset];
+			const revisedBlock = prepared.revised[revisedFrom + offset];
+			if (baseBlock && revisedBlock) if (!canPair(baseBlock, revisedBlock)) {
 				events.push({
 					type: "baseOnly",
-					block: baseBlock
+					block: baseBlock.block
 				});
 				events.push({
 					type: "revisedOnly",
-					block: revisedBlock
+					block: revisedBlock.block
 				});
 			} else events.push({
 				type: "pair",
-				baseBlock,
-				revisedBlock
+				baseBlock: baseBlock.block,
+				revisedBlock: revisedBlock.block
 			});
 		}
 		for (let index = baseFrom + pairedCount; index < baseTo; index++) {
-			const block = baseBlocks[index];
+			const block = prepared.base[index]?.block;
 			if (block) events.push({
 				type: "baseOnly",
 				block
 			});
 		}
 		for (let index = revisedFrom + pairedCount; index < revisedTo; index++) {
-			const block = revisedBlocks[index];
+			const block = prepared.revised[index]?.block;
 			if (block) events.push({
 				type: "revisedOnly",
 				block
 			});
 		}
 	};
-	const emitGap = (baseFrom, baseTo, revisedFrom, revisedTo) => {
-		if (baseFrom === baseTo || revisedFrom === revisedTo) {
-			emitPositionalGap(baseFrom, baseTo, revisedFrom, revisedTo);
-			return;
-		}
-		const continuityPairs = pairByResidualIdContinuity({
-			baseBlocks,
-			revisedBlocks,
-			baseFrom,
-			baseTo,
-			revisedFrom,
-			revisedTo,
-			idStability
-		});
-		let baseCursor = baseFrom;
-		let revisedCursor = revisedFrom;
-		for (const pair of continuityPairs) {
-			emitPositionalGap(baseCursor, pair.baseIndex, revisedCursor, pair.revisedIndex);
-			const baseBlock = baseBlocks[pair.baseIndex];
-			const revisedBlock = revisedBlocks[pair.revisedIndex];
-			if (baseBlock && revisedBlock) events.push({
-				type: "pair",
-				baseBlock,
-				revisedBlock
-			});
-			baseCursor = pair.baseIndex + 1;
-			revisedCursor = pair.revisedIndex + 1;
-		}
-		emitPositionalGap(baseCursor, baseTo, revisedCursor, revisedTo);
-	};
 	let baseCursor = 0;
 	let revisedCursor = 0;
 	for (const anchor of anchors) {
-		emitGap(baseCursor, anchor.baseIndex, revisedCursor, anchor.revisedIndex);
-		const baseBlock = baseBlocks[anchor.baseIndex];
-		const revisedBlock = revisedBlocks[anchor.revisedIndex];
+		emitPositionalGap(baseCursor, anchor.baseIndex, revisedCursor, anchor.revisedIndex);
+		const baseBlock = prepared.base[anchor.baseIndex]?.block;
+		const revisedBlock = prepared.revised[anchor.revisedIndex]?.block;
 		if (baseBlock && revisedBlock) events.push({
 			type: "pair",
 			baseBlock,
@@ -298,9 +372,13 @@ const alignFolioContentBlocks = (baseBlocks, revisedBlocks, options = {}) => {
 		baseCursor = anchor.baseIndex + 1;
 		revisedCursor = anchor.revisedIndex + 1;
 	}
-	emitGap(baseCursor, baseBlocks.length, revisedCursor, revisedBlocks.length);
+	emitPositionalGap(baseCursor, prepared.base.length, revisedCursor, prepared.revised.length);
 	return events;
 };
+const alignFolioContentBlocks = (baseBlocks, revisedBlocks, options = {}) => alignFolioContentBlocksInScope(baseBlocks, revisedBlocks, {
+	...options,
+	structuralScope: "document"
+});
 const BODY_MOVE_BUCKET = 0;
 const scopedAlignmentSteps = (events, context, bucketForBlock) => {
 	const steps = [];
@@ -321,7 +399,6 @@ const scopedAlignmentSteps = (events, context, bucketForBlock) => {
 	}
 	return steps;
 };
-const containerPathKeyOf = (block) => block.containerPath === void 0 || block.containerPath.length === 0 ? null : JSON.stringify(block.containerPath.map(({ kind, id }) => [kind, id]));
 const contentBlocksShareContainerPath = (left, right) => containerPathKeyOf(left) === containerPathKeyOf(right);
 const splitSegments = (blocks) => {
 	const segments = [];
@@ -633,7 +710,7 @@ const ALIGNMENT_DIRECTION = {
 	baseOnly: 2,
 	revisedOnly: 3
 };
-const alignProfiledContentSequence = ({ base, revised, workSession, canPair = () => true, pairSoleStructuralSlot = false, primaryEvidence = "stable", similarityFactor = () => 1 }) => {
+const alignProfiledContentSequence = ({ base, revised, workSession, canPair = () => true, pairSoleStructuralSlot = false, soleShiftedPairResiduePolicy = "conservative", primaryEvidence = "stable", similarityFactor = () => 1 }) => {
 	if (base.length === 0 || revised.length === 0) return unpairedContentSequence(base.map(({ item }) => item), revised.map(({ item }) => item));
 	if ((base.length !== 1 || revised.length !== 1) && !claimFolioContentAlignmentCells(base.length, revised.length, workSession)) return unpairedContentSequence(base.map(({ item }) => item), revised.map(({ item }) => item));
 	const stablePairs = stableContentSequencePairs(base, revised);
@@ -805,7 +882,7 @@ const alignProfiledContentSequence = ({ base, revised, workSession, canPair = ()
 		});
 		hasRevisedOnly = true;
 	}
-	if (pairCount === 1 && solePairIsShifted && hasBaseOnly && hasRevisedOnly) return aligned.flatMap((entry) => entry.type === "pair" ? [{
+	if ((soleShiftedPairResiduePolicy === "conservative" || base.length === revised.length) && pairCount === 1 && solePairIsShifted && hasBaseOnly && hasRevisedOnly) return aligned.flatMap((entry) => entry.type === "pair" ? [{
 		type: "baseOnly",
 		item: entry.base
 	}, {
@@ -839,10 +916,11 @@ const alignRowCells = ({ baseRow, revisedRow, workSession, moveScopeContext, sta
 	for (const cellIndex of cellIndexes) {
 		const baseBlocks = baseCells.get(cellIndex) ?? [];
 		const revisedBlocks = revisedCells.get(cellIndex) ?? [];
-		const aligned = alignFolioContentBlocks(baseBlocks, revisedBlocks, {
+		const aligned = alignFolioContentBlocksInScope(baseBlocks, revisedBlocks, {
 			workSession,
 			idStability,
-			stableIdMismatch
+			stableIdMismatch,
+			structuralScope: "pairedTableCell"
 		}).flatMap((event) => {
 			if (event.type === "pair" && !contentBlocksShareContainerPath(event.baseBlock, event.revisedBlock)) return [{
 				type: "baseOnly",
@@ -876,6 +954,7 @@ const pairTableRows = ({ baseRows, revisedRows, workSession, idStability }) => {
 		revised: revisedRows.map(profile),
 		workSession,
 		pairSoleStructuralSlot: true,
+		soleShiftedPairResiduePolicy: "row-count-evidence",
 		primaryEvidence: "exact",
 		similarityFactor: (base, revised) => base.profile.physicalCellCount === revised.profile.physicalCellCount ? 1 : .5
 	}).map((alignment) => {

package/dist/compare/content-types.d.ts

@@ -1,6 +1,8 @@
 //#region src/compare/content-types.d.ts
 /** How callers expect a block identifier to behave across document revisions. */
 type FolioContentIdStability = "stable" | "positional";
+/** Text-bearing block kinds that share one editable paragraph-mark structure. */
+type FolioContentParagraphKind = "heading" | "listItem" | "paragraph";
 /** One enclosing structural container, ordered outermost to innermost in a block path. */
 type FolioContentContainerPathEntry = {
   kind: string;
@@ -17,7 +19,24 @@ type FolioContentInlineFormatting = Partial<Record<FolioContentInlineBooleanProp
  * An inline-formatting mutation: `false` is an explicit off value, while
  * `null` removes the direct property so its inherited value becomes effective.
  */
-type FolioContentInlineFormattingPatch = Omit<FolioContentInlineFormatting, FolioContentInlineBooleanProperty> & Partial<Record<FolioContentInlineBooleanProperty, boolean | null>>;
+type FolioContentInlineFormattingPatch = { [Property in keyof FolioContentInlineFormatting]?: FolioContentInlineFormatting[Property] | null; };
+/** Presentation differences for one UTF-16 range in a text-aligned block pair. */
+type FolioContentFormatRange = {
+  startOffset: number;
+  endOffset: number;
+  formatting: FolioContentInlineFormattingPatch;
+};
+/** A trusted inline projection or an explicit reason no ranges can be used. */
+type FolioContentInlineComparisonResult = {
+  status: "compared";
+  segments: readonly FolioContentFormatRange[];
+} | {
+  status: "unalignable";
+  side: "base" | "revised" | "both";
+} | {
+  status: "budget-exceeded";
+  maximum: number;
+};
 type FolioContentRun = {
   text: string;
   bold?: boolean;
@@ -59,6 +78,18 @@ type FolioContentTableLocation = {
 type FolioContentParagraphAlignment = "left" | "center" | "right" | "both" | "distribute" | "mediumKashida" | "highKashida" | "lowKashida" | "thaiDistribute";
 /** Line-height interpretation understood by the neutral comparison model. */
 type FolioContentLineSpacingRule = "auto" | "exact" | "atLeast";
+/** The complete modeled attribute set of direct paragraph indentation. */
+type FolioContentParagraphIndentation = {
+  indentLeft?: number;
+  indentRight?: number;
+  indentFirstLine?: number;
+  hangingIndent?: boolean;
+};
+/** A concrete numbering instance and its zero-based level. */
+type FolioContentListReference = {
+  numId: number;
+  level: number;
+};
 /**
  * The complete modeled attribute set of direct paragraph spacing. Optional
  * fields distinguish an absent attribute from an explicit zero or false value.
@@ -85,8 +116,11 @@ type FolioContentBlock<Kind extends string = string> = {
   directAlignment?: FolioContentParagraphAlignment;
   /** Direct paragraph spacing; absent when every spacing value is inherited. */
   directSpacing?: FolioContentParagraphSpacing;
+  /** Direct paragraph indentation; absent when every indentation value is inherited. */
+  directIndentation?: FolioContentParagraphIndentation;
   /** Zero-based list indent level when the block carries numbering. */
   listLevel?: number;
+  listReference?: FolioContentListReference;
   previewRuns?: readonly FolioContentRun[];
   table?: FolioContentTableLocation;
   /** Structural ancestry, ordered from the outermost to the innermost container. */
@@ -97,4 +131,4 @@ type FolioContentSnapshot<Block extends FolioContentBlock = FolioContentBlock> =
   blocks: readonly Block[];
 };
 //#endregion
-export { FolioContentBlock, FolioContentContainerPathEntry, FolioContentIdStability, FolioContentInlineBooleanProperty, FolioContentInlineFormatting, FolioContentInlineFormattingPatch, FolioContentLineSpacingRule, FolioContentParagraphAlignment, FolioContentParagraphSpacing, FolioContentRun, FolioContentSnapshot, FolioContentTableLocation };
+export { FolioContentBlock, FolioContentContainerPathEntry, FolioContentFormatRange, FolioContentIdStability, FolioContentInlineBooleanProperty, FolioContentInlineComparisonResult, FolioContentInlineFormatting, FolioContentInlineFormattingPatch, FolioContentLineSpacingRule, FolioContentListReference, FolioContentParagraphAlignment, FolioContentParagraphIndentation, FolioContentParagraphKind, FolioContentParagraphSpacing, FolioContentRun, FolioContentSnapshot, FolioContentTableLocation };

package/dist/compare/content.d.ts

@@ -1,4 +1,4 @@
-import { FolioContentBlock, FolioContentIdStability, FolioContentInlineFormattingPatch, FolioContentParagraphSpacing, FolioContentSnapshot } from "./content-types.js";
+import { FolioContentBlock, FolioContentFormatRange, FolioContentIdStability, FolioContentListReference, FolioContentParagraphIndentation, FolioContentParagraphSpacing, FolioContentSnapshot } from "./content-types.js";
 import { WordDiffGranularity, createWordDiffSession } from "../ai-edits/word-diff.js";
 import { FolioContentAlignmentStep, FolioContentAlignmentWorkSession } from "./content-alignment.js";
 import { Result } from "better-result";
@@ -34,8 +34,15 @@ declare class FolioContentComparisonLimitError extends FolioContentComparisonLim
   blockIndex?: number;
   field?: string;
 }> {}
+declare const FolioContentInlinePresentationProjectionError_base: import("better-result").TaggedErrorClass<"FolioContentInlinePresentationProjectionError">;
+declare class FolioContentInlinePresentationProjectionError extends FolioContentInlinePresentationProjectionError_base<{
+  message: string;
+  side: "base" | "revised" | "both";
+  baseBlockId: string;
+  revisedBlockId: string;
+}> {}
 /** Errors returned by {@link compareContent}. */
-type FolioContentComparisonError = InvalidFolioContentComparisonError | FolioContentComparisonLimitError;
+type FolioContentComparisonError = InvalidFolioContentComparisonError | FolioContentComparisonLimitError | FolioContentInlinePresentationProjectionError;
 /** One Folio word-diff segment with JavaScript-slice-compatible offsets. */
 type FolioContentTextSegment = {
   type: "equal" | "del" | "ins";
@@ -49,14 +56,10 @@ type FolioContentTextSegment = {
 type FolioContentParagraphFormattingPatch = {
   styleId?: string | null;
   listLevel?: number | null;
+  listReference?: FolioContentListReference | null;
   alignment?: FolioContentBlock["directAlignment"] | null;
   spacing?: FolioContentParagraphSpacing | null;
-};
-/** Presentation differences for one text-aligned block pair. */
-type FolioContentFormatRange = {
-  startOffset: number;
-  endOffset: number;
-  formatting: FolioContentInlineFormattingPatch;
+  indentation?: FolioContentParagraphIndentation | null;
 };
 /** Presentation differences for one text-aligned block pair. */
 type FolioContentFormattingChange = {
@@ -202,8 +205,8 @@ type CompareAlignedContentOptions<Block extends FolioContentBlock> = {
   maxChanges: number;
   idStability?: (block: Block) => FolioContentIdStability;
 };
-declare const compareAlignedFolioContent: <Block extends FolioContentBlock>({ baseBlocks, revisedBlocks, steps, workSession, maxChanges, idStability }: CompareAlignedContentOptions<Block>) => Result<FolioContentComparison<Block>, FolioContentComparisonLimitError>;
+declare const compareAlignedFolioContent: <Block extends FolioContentBlock>({ baseBlocks, revisedBlocks, steps, workSession, maxChanges, idStability }: CompareAlignedContentOptions<Block>) => Result<FolioContentComparison<Block>, FolioContentComparisonLimitError | FolioContentInlinePresentationProjectionError>;
 /** Compare two representation-neutral ordered content snapshots. */
 declare const compareContent: <Block extends FolioContentBlock = FolioContentBlock>(options: CompareContentOptions<Block>) => Result<FolioContentComparison<Block>, FolioContentComparisonError>;
 //#endregion
-export { CompareContentOptions, FOLIO_CONTENT_COMPARISON_LIMITS, FolioContentBlockProperty, FolioContentComparison, FolioContentComparisonError, FolioContentComparisonEvent, FolioContentComparisonLimit, FolioContentComparisonLimitError, FolioContentComparisonWorkSession, FolioContentFormatRange, FolioContentFormattingChange, FolioContentParagraphFormattingPatch, FolioContentStructuralChange, FolioContentTextSegment, InvalidFolioContentComparisonError, changedFolioContentParagraphFormatting, compareAlignedFolioContent, compareContent, createContentComparisonWorkSession, detectFolioContentMoves, detectFolioContentParagraphMarkPlans };
+export { CompareContentOptions, FOLIO_CONTENT_COMPARISON_LIMITS, FolioContentBlockProperty, FolioContentComparison, FolioContentComparisonError, FolioContentComparisonEvent, FolioContentComparisonLimit, FolioContentComparisonLimitError, FolioContentComparisonWorkSession, type FolioContentFormatRange, FolioContentFormattingChange, FolioContentInlinePresentationProjectionError, FolioContentParagraphFormattingPatch, FolioContentStructuralChange, FolioContentTextSegment, InvalidFolioContentComparisonError, changedFolioContentParagraphFormatting, compareAlignedFolioContent, compareContent, createContentComparisonWorkSession, detectFolioContentMoves, detectFolioContentParagraphMarkPlans };