@stll/folio-core 0.32.2 → 0.33.1

package/dist/compare/types.d.ts

@@ -0,0 +1,297 @@
+import { FolioAIBlockParagraphProperties, FolioAIBlockTableLocation, FolioAIEditSkippedOperation, FolioAIInlineFormatting } from "../ai-edits/types.js";
+import { WordDiffGranularity } from "../ai-edits/word-diff.js";
+import { FolioDocumentStoryHandle, FolioNumberingLevel } from "../ai-edits/headless.js";
+import { CompareVerification, CompareVerificationCause, CompareVerificationFailure, CompareVerificationInvariant, FinalParagraphMarkDeletion } from "./verification.js";
+//#region src/compare/types.d.ts
+/** Everything {@link compareDocx} needs; nothing it reads from the ambient clock. */
+type CompareDocxOptions = {
+  /** Author recorded on every generated tracked change. */
+  author: string;
+  /**
+   * ISO-8601 date stamped on every generated tracked change. Required rather
+   * than defaulted so a caller cannot get a nondeterministic package by
+   * omission; pass the base document's own timestamp, a release date, or a
+   * fixed epoch.
+   */
+  timestamp: string;
+  /**
+   * What to do when the round-trip self-check cannot prove the result.
+   *
+   * `"refuse"` (default) returns a {@link CompareDocxRoundTripError}: a
+   * redline that reads plausibly and is wrong is worse than no redline.
+   * `"emit"` returns the redline anyway, with `verification` naming every
+   * invariant that did not hold, for a caller that would rather show its best
+   * attempt and say what is missing.
+   */
+  onUnverified?: "refuse" | "emit";
+  /**
+   * Token size a changed paragraph's redline is cut at: `"word"` (default)
+   * marks whole words, `"character"` marks the changed letters inside one.
+   *
+   * Case and whitespace normalization are not options here, though
+   * `diffWordSegments` offers them: a comparison that leaves a difference
+   * unmarked does not accept back to the target, and the round trip is the
+   * one thing this call promises.
+   */
+  granularity?: WordDiffGranularity;
+};
+/** Where one change sits in the base or target document. */
+type CompareChangeLocation = {
+  story: FolioDocumentStoryHandle;
+  /** Innermost table cell, when the change is inside a table. */
+  cell?: FolioAIBlockTableLocation;
+};
+/** One run of characters whose inline formatting differs, in base-block offsets. */
+type CompareFormatRange = {
+  startOffset: number;
+  endOffset: number;
+  /** Only the properties that differ, set to the target document's value. */
+  formatting: FolioAIInlineFormatting;
+};
+/**
+ * One difference between the two documents, in target-document order with
+ * base-only entries slotted where they sat. Every variant is plain JSON, so a
+ * caller can hand the list to an agent instead of the package.
+ *
+ * A `move` is reported, not represented: the tracked-change grammar has no
+ * "this paragraph came from there" mark that Word round-trips, so the buffer
+ * carries a deletion at the source and an insertion at the destination while
+ * the change list keeps the relocation visible.
+ */
+type CompareChange = {
+  kind: "insert";
+  location: CompareChangeLocation;
+  /** Id of the inserted block in the target document. */
+  targetBlockId: string;
+  after: string;
+} | {
+  kind: "delete";
+  location: CompareChangeLocation;
+  baseBlockId: string;
+  before: string;
+} | {
+  kind: "replace";
+  location: CompareChangeLocation;
+  baseBlockId: string;
+  targetBlockId: string;
+  before: string;
+  after: string;
+} | {
+  kind: "move";
+  location: CompareChangeLocation;
+  /** The block's id where it sat in the base document. */
+  baseBlockId: string;
+  /** The same content's id where it sits in the target document. */
+  targetBlockId: string;
+  text: string;
+} |
+/**
+ * One paragraph became two: a paragraph mark was inserted and no words
+ * changed. Reported as its own kind so a reader is not told the tail was
+ * newly written.
+ */
+{
+  kind: "split";
+  location: CompareChangeLocation;
+  baseBlockId: string;
+  /** The two blocks the base block became, in target order. */
+  targetBlockIds: readonly string[];
+  text: string;
+} |
+/** Two paragraphs became one: a paragraph mark was deleted. */
+{
+  kind: "merge";
+  location: CompareChangeLocation;
+  /** The two blocks that became one, in base order. */
+  baseBlockIds: readonly string[];
+  targetBlockId: string;
+  text: string;
+} |
+/**
+ * A paragraph property moved and no words did: a list item demoted a level,
+ * a paragraph restyled. Written as `w:pPrChange`, so rejecting restores the
+ * whole previous property set the way Word does.
+ */
+{
+  kind: "paragraph-format";
+  location: CompareChangeLocation;
+  baseBlockId: string;
+  targetBlockId: string;
+  /** Only the properties that differ, set to the target document's value. */
+  properties: FolioAIBlockParagraphProperties;
+} | {
+  kind: "format";
+  location: CompareChangeLocation;
+  baseBlockId: string;
+  targetBlockId: string;
+  text: string;
+  ranges: readonly CompareFormatRange[];
+} | {
+  kind: "table-row-insert";
+  location: CompareChangeLocation;
+  tableIndex: number;
+  /** Row index in the target document's table. */
+  rowIndex: number;
+  /** The new row's cell texts, in physical cell order. */
+  cells: readonly string[];
+  targetBlockIds: readonly string[];
+} |
+/**
+ * A numbering definition that differs. It carries no `location`: numbering
+ * lives in the package, not in a story, and one definition governs every
+ * list that references it.
+ *
+ * Reported and not represented. A renumbering that FOLLOWS from an edit —
+ * an item inserted, so the ones below it count on — is already shown
+ * as-if-accepted, because labels are rendered from these definitions rather
+ * than stored on the paragraphs. A definition that itself changed is a
+ * different thing, and OOXML has no tracked-change grammar for it: Word
+ * does not track `numbering.xml` either.
+ */
+{
+  kind: "numbering";
+  numId: number;
+  level: number;
+  /** `null` when the target added this level. */
+  before: FolioNumberingLevel | null;
+  /** `null` when the target dropped it. */
+  after: FolioNumberingLevel | null;
+} |
+/** A whole table the target added. */
+{
+  kind: "table-insert";
+  location: CompareChangeLocation;
+  tableIndex: number;
+  /** Cell texts row by row, in physical cell order. */
+  rows: readonly (readonly string[])[];
+  targetBlockIds: readonly string[];
+} |
+/** A whole table the target dropped. */
+{
+  kind: "table-delete";
+  location: CompareChangeLocation;
+  tableIndex: number;
+  rows: readonly (readonly string[])[];
+  baseBlockIds: readonly string[];
+} | {
+  kind: "table-row-delete";
+  location: CompareChangeLocation;
+  tableIndex: number;
+  /** Row index in the base document's table. */
+  rowIndex: number;
+  cells: readonly string[];
+  baseBlockIds: readonly string[];
+} | {
+  kind: "table-column-insert";
+  location: CompareChangeLocation;
+  tableIndex: number;
+  /** Grid-column index in the target table. */
+  columnIndex: number;
+  /** Newly created physical-cell text in row order. */
+  cells: readonly string[];
+  targetBlockIds: readonly string[];
+} | {
+  kind: "table-column-delete";
+  location: CompareChangeLocation;
+  tableIndex: number;
+  /** Grid-column index in the base table. */
+  columnIndex: number;
+  cells: readonly string[];
+  baseBlockIds: readonly string[];
+};
+/** Why a part of the package is absent from `changes`. */
+declare const COMPARE_UNSUPPORTED_REASONS: readonly ["story-missing-in-base", "story-missing-in-target", "story-not-editable"];
+type CompareUnsupportedReason = (typeof COMPARE_UNSUPPORTED_REASONS)[number];
+/**
+ * A package part the comparison did not cover. Reported rather than dropped so
+ * a caller can tell "no differences" from "not looked at".
+ */
+type CompareUnsupportedPart = {
+  reason: CompareUnsupportedReason;
+  baseStory: FolioDocumentStoryHandle | null;
+  targetStory: FolioDocumentStoryHandle | null;
+};
+type CompareResult = {
+  /** The base package carrying the generated tracked changes. */
+  buffer: ArrayBuffer;
+  changes: readonly CompareChange[];
+  /**
+   * Whether the round trip was proven. Always `verified` unless the call asked
+   * for `onUnverified: "emit"`, which is the only way an unproven redline is
+   * returned at all.
+   */
+  verification: CompareVerification;
+  unsupported: readonly CompareUnsupportedPart[];
+};
+declare const InvalidCompareDocxOptionsError_base: import("better-result").TaggedErrorClass<"InvalidCompareDocxOptionsError">;
+declare class InvalidCompareDocxOptionsError extends InvalidCompareDocxOptionsError_base<{
+  message: string;
+  option: "timestamp";
+  receivedValue: unknown;
+}> {}
+declare const CompareDocxParseError_base: import("better-result").TaggedErrorClass<"CompareDocxParseError">;
+declare class CompareDocxParseError extends CompareDocxParseError_base<{
+  message: string;
+  side: "base" | "target";
+  cause: unknown;
+}> {}
+declare const CompareDocxApplyError_base: import("better-result").TaggedErrorClass<"CompareDocxApplyError">;
+/**
+ * The applier refused at least one derived operation, so accepting the result
+ * would not reproduce the target. Reported instead of returning a package that
+ * silently under-represents the difference.
+ */
+declare class CompareDocxApplyError extends CompareDocxApplyError_base<{
+  message: string;
+  skipped: readonly FolioAIEditSkippedOperation[];
+}> {}
+declare const CompareDocxRoundTripError_base: import("better-result").TaggedErrorClass<"CompareDocxRoundTripError">;
+/**
+ * The generated tracked changes do not accept back to the target. Raised by
+ * the self-check {@link compareDocx} runs before returning: a redline that
+ * quietly loses part of the difference is worse than no redline, so the
+ * mismatch is surfaced instead of the document.
+ */
+declare class CompareDocxRoundTripError extends CompareDocxRoundTripError_base<{
+  message: string;
+  story: FolioDocumentStoryHandle;
+  /** The invariant that did not hold, and what diverged under it. */
+  invariant: CompareVerificationInvariant;
+  cause: CompareVerificationCause;
+  /**
+   * Every invariant that failed, not only the one named above: a redline that
+   * loses a difference usually loses it in both directions, and a caller
+   * deciding what to do next wants the whole list. Each detail is structural,
+   * so it is safe to log or quote.
+   */
+  failures: readonly CompareVerificationFailure[];
+}> {}
+declare const CompareDocxOperationLimitError_base: import("better-result").TaggedErrorClass<"CompareDocxOperationLimitError">;
+/** The difference needs more operations than the engine will generate. */
+declare class CompareDocxOperationLimitError extends CompareDocxOperationLimitError_base<{
+  message: string;
+  limit: number;
+}> {}
+declare const CompareDocxSerializeError_base: import("better-result").TaggedErrorClass<"CompareDocxSerializeError">;
+declare class CompareDocxSerializeError extends CompareDocxSerializeError_base<{
+  message: string;
+  cause: unknown;
+}> {}
+declare const CompareDocxFinalParagraphMarkError_base: import("better-result").TaggedErrorClass<"CompareDocxFinalParagraphMarkError">;
+/**
+ * A container's final paragraph mark carries a deletion, so the package would
+ * not open.
+ *
+ * A deleted paragraph mark means "merge this paragraph into the following
+ * one", and a container's last paragraph has no following one. Checked before
+ * the package is written, and fatal under either `onUnverified` setting: there
+ * is no redline to emit when a consumer refuses the file.
+ */
+declare class CompareDocxFinalParagraphMarkError extends CompareDocxFinalParagraphMarkError_base<{
+  message: string;
+  /** Every container that carries one, each named structurally. */
+  deletions: readonly FinalParagraphMarkDeletion[];
+}> {}
+type CompareDocxError = CompareDocxApplyError | CompareDocxFinalParagraphMarkError | CompareDocxOperationLimitError | CompareDocxParseError | CompareDocxRoundTripError | CompareDocxSerializeError | InvalidCompareDocxOptionsError;
+//#endregion
+export { COMPARE_UNSUPPORTED_REASONS, CompareChange, CompareChangeLocation, CompareDocxApplyError, CompareDocxError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxOptions, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, CompareFormatRange, CompareResult, CompareUnsupportedPart, CompareUnsupportedReason, InvalidCompareDocxOptionsError };

package/dist/compare/types.js

@@ -0,0 +1,42 @@
+import { TaggedError } from "better-result";
+//#region src/compare/types.ts
+/**
+* Public vocabulary of {@link ./compare.compareDocx}: the change list, the
+* options that pin its output, and the failures it reports.
+*/
+/** Why a part of the package is absent from `changes`. */
+const COMPARE_UNSUPPORTED_REASONS = Object.freeze([
+	"story-missing-in-base",
+	"story-missing-in-target",
+	"story-not-editable"
+]);
+var InvalidCompareDocxOptionsError = class extends TaggedError("InvalidCompareDocxOptionsError") {};
+var CompareDocxParseError = class extends TaggedError("CompareDocxParseError") {};
+/**
+* The applier refused at least one derived operation, so accepting the result
+* would not reproduce the target. Reported instead of returning a package that
+* silently under-represents the difference.
+*/
+var CompareDocxApplyError = class extends TaggedError("CompareDocxApplyError") {};
+/**
+* The generated tracked changes do not accept back to the target. Raised by
+* the self-check {@link compareDocx} runs before returning: a redline that
+* quietly loses part of the difference is worse than no redline, so the
+* mismatch is surfaced instead of the document.
+*/
+var CompareDocxRoundTripError = class extends TaggedError("CompareDocxRoundTripError") {};
+/** The difference needs more operations than the engine will generate. */
+var CompareDocxOperationLimitError = class extends TaggedError("CompareDocxOperationLimitError") {};
+var CompareDocxSerializeError = class extends TaggedError("CompareDocxSerializeError") {};
+/**
+* A container's final paragraph mark carries a deletion, so the package would
+* not open.
+*
+* A deleted paragraph mark means "merge this paragraph into the following
+* one", and a container's last paragraph has no following one. Checked before
+* the package is written, and fatal under either `onUnverified` setting: there
+* is no redline to emit when a consumer refuses the file.
+*/
+var CompareDocxFinalParagraphMarkError = class extends TaggedError("CompareDocxFinalParagraphMarkError") {};
+//#endregion
+export { COMPARE_UNSUPPORTED_REASONS, CompareDocxApplyError, CompareDocxFinalParagraphMarkError, CompareDocxOperationLimitError, CompareDocxParseError, CompareDocxRoundTripError, CompareDocxSerializeError, InvalidCompareDocxOptionsError };

package/dist/compare/verification.d.ts

@@ -0,0 +1,83 @@
+import { FolioAIBlock } from "../ai-edits/types.js";
+import { FolioDocumentStoryHandle } from "../ai-edits/headless.js";
+//#region src/compare/verification.d.ts
+/** The two directions of the round trip, each an invariant of its own. */
+declare const COMPARE_VERIFICATION_INVARIANTS: readonly ["accept-reproduces-target", "reject-reproduces-base"];
+type CompareVerificationInvariant = (typeof COMPARE_VERIFICATION_INVARIANTS)[number];
+/**
+ * What diverged. Ordered from the structural to the textual: the first cause
+ * that fits is the one reported, because a block in the wrong container is a
+ * different finding from a block whose words are wrong even when both are true.
+ */
+declare const COMPARE_VERIFICATION_CAUSES: readonly ["invisible-structure", "block-count", "container", "style", "list-level", "inline-formatting", "whitespace", "text"];
+type CompareVerificationCause = (typeof COMPARE_VERIFICATION_CAUSES)[number];
+/** One invariant that did not hold, in one story. */
+type CompareVerificationFailure = {
+  invariant: CompareVerificationInvariant;
+  cause: CompareVerificationCause;
+  story: FolioDocumentStoryHandle;
+  /** Structural facts only: counts, offsets, container kinds. Safe to quote. */
+  detail: string;
+};
+/**
+ * Whether the redline was proven to round-trip.
+ *
+ * `unverified` is only ever returned when the caller asked for it with
+ * `onUnverified: "emit"`; the default refuses instead, because a redline that
+ * reads plausibly and is wrong is worse than no redline.
+ */
+type CompareVerification = {
+  status: "verified";
+} | {
+  status: "unverified";
+  failures: readonly CompareVerificationFailure[];
+};
+/** Effective supported formatting with equivalent adjacent runs normalized. */
+declare const projectSupportedInlineFormatting: ({ text, previewRuns }: FolioAIBlock) => string;
+/** Element by element, never by joining: a block's text may hold the separator. */
+declare const sameProjection: (left: readonly string[], right: readonly string[]) => boolean;
+type ClassifyOptions = {
+  invariant: CompareVerificationInvariant;
+  story: FolioDocumentStoryHandle;
+  /** What the redline actually leaves. */
+  actual: readonly string[];
+  /** What the invariant says it should leave. */
+  expected: readonly string[];
+};
+/**
+ * The failure two projections describe, or `null` when they agree.
+ *
+ * Total over the causes by construction: the last branch is unconditional, so
+ * a divergence always produces a failure rather than being dropped.
+ */
+declare const classifyProjectionMismatch: ({ invariant, story, actual, expected }: ClassifyOptions) => CompareVerificationFailure | null;
+/**
+ * A container whose last paragraph carries a deletion on its mark.
+ *
+ * Structural facts only — a path through the package model and an index — so
+ * the finding is safe to log, report or quote.
+ */
+type FinalParagraphMarkDeletion = {
+  /** Where the container sits in the package model, e.g. `package.document.content`. */
+  container: string;
+  /** The paragraph's index among its container's children. */
+  paragraphIndex: number;
+  /** The mark kind found there: `del`, or `moveFrom` for a relocation's source. */
+  kind: "del" | "moveFrom";
+};
+/**
+ * Every container in a package whose final paragraph mark carries a deletion.
+ *
+ * A deleted paragraph mark says "join this paragraph with the one after it".
+ * The last paragraph of a body, a table cell, a header or footer, a note or a
+ * text box has no paragraph after it, so the mark states an edit that cannot
+ * be carried out, and a consumer refuses the package rather than opening it.
+ *
+ * The walk is over the package model rather than over a list of the containers
+ * known today: a container is any sequence that ends in a paragraph, so a part
+ * the model grows later is covered the day it arrives instead of the day
+ * someone remembers this function.
+ */
+declare const deletedFinalParagraphMarks: (packageModel: unknown) => FinalParagraphMarkDeletion[];
+//#endregion
+export { COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, CompareVerification, CompareVerificationCause, CompareVerificationFailure, CompareVerificationInvariant, FinalParagraphMarkDeletion, classifyProjectionMismatch, deletedFinalParagraphMarks, projectSupportedInlineFormatting, sameProjection };

package/dist/compare/verification.js

@@ -0,0 +1,189 @@
+//#region src/compare/verification.ts
+/** The two directions of the round trip, each an invariant of its own. */
+const COMPARE_VERIFICATION_INVARIANTS = Object.freeze(["accept-reproduces-target", "reject-reproduces-base"]);
+/**
+* What diverged. Ordered from the structural to the textual: the first cause
+* that fits is the one reported, because a block in the wrong container is a
+* different finding from a block whose words are wrong even when both are true.
+*/
+const COMPARE_VERIFICATION_CAUSES = Object.freeze([
+	"invisible-structure",
+	"block-count",
+	"container",
+	"style",
+	"list-level",
+	"inline-formatting",
+	"whitespace",
+	"text"
+]);
+const supportedInlineStyle = ({ bold, italic, underline, strike }) => `${bold === true ? "b" : ""}${italic === true ? "i" : ""}${underline === true ? "u" : ""}${strike === true ? "s" : ""}`;
+/** Effective supported formatting with equivalent adjacent runs normalized. */
+const projectSupportedInlineFormatting = ({ text, previewRuns }) => {
+	const projected = [];
+	for (const run of previewRuns ?? [{ text }]) {
+		if (run.text.length === 0) continue;
+		const style = supportedInlineStyle(run);
+		const previous = projected.at(-1);
+		if (previous?.style === style) {
+			previous.length += run.text.length;
+			continue;
+		}
+		projected.push({
+			length: run.text.length,
+			style
+		});
+	}
+	return projected.map(({ length, style }) => `${String(length)}:${style}`).join(",");
+};
+const parseProjection = (entry) => {
+	const first = entry.indexOf("|");
+	const second = entry.indexOf("|", first + 1);
+	const third = entry.indexOf("|", second + 1);
+	if (first === -1 || second === -1 || third === -1) return {
+		container: "",
+		styleId: "",
+		listLevel: "",
+		text: entry
+	};
+	return {
+		container: entry.slice(0, first),
+		styleId: entry.slice(first + 1, second),
+		listLevel: entry.slice(second + 1, third),
+		text: entry.slice(third + 1)
+	};
+};
+const CONTAINER_PATTERN = /^t(\d+)r(\d+)c(\d+)p(\d+)$/u;
+const containerKind = (container) => CONTAINER_PATTERN.test(container) ? "cell" : "body";
+const collapseWhitespace = (text) => text.replace(/\s+/gu, " ").trim();
+/** Element by element, never by joining: a block's text may hold the separator. */
+const sameProjection = (left, right) => left.length === right.length && left.every((entry, index) => entry === right[index]);
+/**
+* The same projection with every table coordinate renumbered by first
+* appearance, so it counts the blocks the model holds rather than the
+* paragraphs the package contains.
+*
+* The snapshot skips a hidden row's whole subtree, so a table that hides a row
+* on one side only reports every later row one position along. No operation
+* can put a block at those coordinates, because none can create or remove the
+* hidden row that produces them. When two projections agree here and disagree
+* on the raw coordinates, the redline holds every block the other side does,
+* in order, and the difference is one the block model cannot see.
+*/
+const byVisibleOrdinal = (entries) => {
+	const ordinals = /* @__PURE__ */ new Map();
+	const counts = /* @__PURE__ */ new Map();
+	const ordinalWithin = (scope, index) => {
+		const key = `${scope}:${index}`;
+		const existing = ordinals.get(key);
+		if (existing !== void 0) return existing;
+		const next = counts.get(scope) ?? 0;
+		counts.set(scope, next + 1);
+		ordinals.set(key, next);
+		return next;
+	};
+	const paragraphCounts = /* @__PURE__ */ new Map();
+	return entries.map((entry) => {
+		const first = entry.indexOf("|");
+		const match = CONTAINER_PATTERN.exec(entry.slice(0, first));
+		if (!match) return entry;
+		const [, table = "", row = "", cell = ""] = match;
+		const tableOrdinal = ordinalWithin("t", table);
+		const rowScope = `r${String(tableOrdinal)}`;
+		const rowOrdinal = ordinalWithin(rowScope, row);
+		const cellScope = `c${String(tableOrdinal)}.${String(rowOrdinal)}`;
+		const cellOrdinal = ordinalWithin(cellScope, cell);
+		const cellKey = `${cellScope}:${cell}`;
+		const paragraphOrdinal = paragraphCounts.get(cellKey) ?? 0;
+		paragraphCounts.set(cellKey, paragraphOrdinal + 1);
+		return `t${String(tableOrdinal)}r${String(rowOrdinal)}c${String(cellOrdinal)}p${String(paragraphOrdinal)}` + entry.slice(first);
+	});
+};
+/**
+* Where two projections first diverge, and what diverged there. A pair that
+* matches everywhere but in length diverges at the shorter one's end.
+*/
+const firstDivergence = (actual, expected) => {
+	const shared = Math.min(actual.length, expected.length);
+	for (let index = 0; index < shared; index++) if (actual[index] !== expected[index]) return {
+		index,
+		actual: parseProjection(actual[index] ?? ""),
+		expected: parseProjection(expected[index] ?? "")
+	};
+	return {
+		index: shared,
+		actual: shared < actual.length ? parseProjection(actual[shared] ?? "") : null,
+		expected: shared < expected.length ? parseProjection(expected[shared] ?? "") : null
+	};
+};
+/**
+* The failure two projections describe, or `null` when they agree.
+*
+* Total over the causes by construction: the last branch is unconditional, so
+* a divergence always produces a failure rather than being dropped.
+*/
+const classifyProjectionMismatch = ({ invariant, story, actual, expected }) => {
+	if (sameProjection(actual, expected)) return null;
+	const failure = (cause, detail) => ({
+		invariant,
+		cause,
+		story,
+		detail
+	});
+	if (sameProjection(byVisibleOrdinal(actual), byVisibleOrdinal(expected))) return failure("invisible-structure", `every block matches once table coordinates count visible blocks (${String(expected.length)} blocks)`);
+	const divergence = firstDivergence(actual, expected);
+	const at = `at block ${String(divergence.index)}/${String(expected.length)}`;
+	const counts = `${String(actual.length)} blocks against ${String(expected.length)}`;
+	if (divergence.actual === null || divergence.expected === null) return failure("block-count", `${actual.length > expected.length ? "more" : "fewer"} blocks than expected (${counts}), diverging ${at}`);
+	const { actual: left, expected: right } = divergence;
+	if (left.container !== right.container) return failure("container", `a block sits in a ${containerKind(left.container)} where it is expected in a ${containerKind(right.container)}, ${at} (${counts})`);
+	if (left.text === right.text && left.styleId !== right.styleId) return failure("style", `the paragraph style did not move ${at} (${counts})`);
+	if (left.text === right.text && left.listLevel !== right.listLevel) return failure("list-level", `the list level did not move ${at} (${counts})`);
+	if (collapseWhitespace(left.text) === collapseWhitespace(right.text)) return failure("whitespace", `a block's text differs only in whitespace ${at} (${counts})`);
+	if (actual.length !== expected.length) return failure("block-count", `${counts}, first differing ${at}`);
+	return failure("text", `a ${containerKind(left.container)} block's text does not match ${at}, length ${String(left.text.length)} against ${String(right.text.length)} (${counts})`);
+};
+/** The mark kinds that resolve by joining the paragraph with the one after it. */
+const JOINS_FORWARD_ON_ACCEPT = Object.freeze(["del", "moveFrom"]);
+const joinsForwardOnAccept = (value) => JOINS_FORWARD_ON_ACCEPT.some((kind) => kind === value);
+const isRecord = (value) => typeof value === "object" && value !== null;
+const isParagraph = (value) => isRecord(value) && value["type"] === "paragraph";
+/**
+* Every container in a package whose final paragraph mark carries a deletion.
+*
+* A deleted paragraph mark says "join this paragraph with the one after it".
+* The last paragraph of a body, a table cell, a header or footer, a note or a
+* text box has no paragraph after it, so the mark states an edit that cannot
+* be carried out, and a consumer refuses the package rather than opening it.
+*
+* The walk is over the package model rather than over a list of the containers
+* known today: a container is any sequence that ends in a paragraph, so a part
+* the model grows later is covered the day it arrives instead of the day
+* someone remembers this function.
+*/
+const deletedFinalParagraphMarks = (packageModel) => {
+	const found = [];
+	const visit = (value, path) => {
+		if (Array.isArray(value)) {
+			const last = value.at(-1);
+			const mark = isParagraph(last) ? last["pPrMark"] : void 0;
+			const kind = isRecord(mark) ? mark["kind"] : void 0;
+			if (joinsForwardOnAccept(kind)) found.push({
+				container: path,
+				paragraphIndex: value.length - 1,
+				kind
+			});
+			for (const [index, item] of value.entries()) visit(item, `${path}[${String(index)}]`);
+			return;
+		}
+		if (value instanceof Map) {
+			for (const [key, item] of value) visit(item, `${path}.${String(key)}`);
+			return;
+		}
+		if (!isRecord(value) || value instanceof Date || ArrayBuffer.isView(value)) return;
+		for (const [key, item] of Object.entries(value)) visit(item, `${path}.${key}`);
+	};
+	visit(packageModel, "package");
+	return found;
+};
+//#endregion
+export { COMPARE_VERIFICATION_CAUSES, COMPARE_VERIFICATION_INVARIANTS, classifyProjectionMismatch, deletedFinalParagraphMarks, projectSupportedInlineFormatting, sameProjection };