docxodus 9.9.0 → 11.0.0

package/dist/types.d.ts

@@ -149,7 +149,10 @@ export interface MarkdownProjection {
     anchorIndex: Record<string, MarkdownAnchorTarget>;
 }
 /**
- * Revision type enum matching the .NET WmlComparerRevisionType
+ * Revision type enum matching the .NET `DocxDiffRevisionType`, as returned by the `docxDiff*`
+ * comparison APIs. NOT the shape {@link getRevisions} returns — that reads a document's own markup
+ * and reports the markup-level kind on `RevisionListEntry.type` (`ins`/`del`/`moveFrom`), with the
+ * grouped classification on `family`.
  */
 export declare enum RevisionType {
     /** Text or content that was added/inserted */
@@ -161,24 +164,6 @@ export declare enum RevisionType {
     /** Text content unchanged but formatting (bold, italic, etc.) changed */
     FormatChanged = "FormatChanged"
 }
-/**
- * Which comparison engine {@link compareDocuments} / {@link compareDocumentsToHtml}
- * use to redline two documents.
- *
- * The numeric values are the contract shared with the .NET `ComparisonEngine` enum
- * and the WASM boundary (marshalled as an int); `0` remains
- * {@link ComparisonEngine.WmlComparer} for wire compatibility. Omitted selectors use
- * {@link ComparisonEngine.DocxDiff}.
- *
- * `DocxDiff` is the default comparison engine. `WmlComparer` remains available for
- * callers that explicitly require its historical behavior.
- */
-export declare enum ComparisonEngine {
-    /** The legacy WmlComparer engine (retained at wire value 0). */
-    WmlComparer = 0,
-    /** The default DocxDiff IR diff engine. */
-    DocxDiff = 1
-}
 /**
  * Comment render mode
  * Use -1 (Disabled) to not render comments, or a positive value to enable with that mode
@@ -306,8 +291,6 @@ export interface ConversionOptions {
 export interface CompareOptions {
     /** Author name for tracked changes (default: "Docxodus") */
     authorName?: string;
-    /** Detail threshold 0.0-1.0 (default: 0.15, lower = more detailed) */
-    detailThreshold?: number;
     /** Whether comparison is case-insensitive (default: false) */
     caseInsensitive?: boolean;
     /**
@@ -316,68 +299,6 @@ export interface CompareOptions {
      * If false: changes are accepted, output shows final "clean" document
      */
     renderTrackedChanges?: boolean;
-    /**
-     * Which comparison engine to use (default: {@link ComparisonEngine.DocxDiff}).
-     * Pass {@link ComparisonEngine.WmlComparer} only when its historical behavior is required.
-     */
-    engine?: ComparisonEngine;
-}
-/**
- * Information about a document revision extracted from a compared document.
- *
- * @example
- * ```typescript
- * const revisions = await getRevisions(comparedDoc);
- * for (const rev of revisions) {
- *   if (rev.revisionType === RevisionType.Inserted) {
- *     console.log(`${rev.author} added: "${rev.text}"`);
- *   } else if (rev.revisionType === RevisionType.Deleted) {
- *     console.log(`${rev.author} removed: "${rev.text}"`);
- *   }
- * }
- * ```
- */
-export interface Revision {
-    /**
-     * Author who made the revision.
-     * This comes from the Word document's tracked changes author attribute.
-     * May be empty string if the document doesn't specify an author.
-     */
-    author: string;
-    /**
-     * ISO 8601 date string when the revision was made.
-     * Format: "YYYY-MM-DDTHH:mm:ssZ" (e.g., "2024-01-15T10:30:00Z")
-     * May be empty string if the document doesn't specify a date.
-     */
-    date: string;
-    /**
-     * Type of revision - "Inserted", "Deleted", or "Moved".
-     * Use the RevisionType enum for type-safe comparisons.
-     */
-    revisionType: RevisionType | string;
-    /**
-     * Text content of the revision.
-     * For paragraph breaks, this will be a newline character.
-     * May be empty string for non-text elements (e.g., images, math equations).
-     */
-    text: string;
-    /**
-     * For Moved revisions, this ID links the source and destination.
-     * Both the "from" and "to" revisions share the same moveGroupId.
-     * Undefined for non-move revisions.
-     */
-    moveGroupId?: number;
-    /**
-     * For Moved revisions: true = source (content moved FROM here),
-     * false = destination (content moved TO here).
-     * Undefined for non-move revisions.
-     */
-    isMoveSource?: boolean;
-    /**
-     * For FormatChanged revisions: details about what formatting changed.
-     * Undefined for non-format-change revisions.
-     */
-    formatChange?: FormatChangeDetails;
 }
 /**
  * Which property container a FormatChanged revision describes.
@@ -417,7 +338,7 @@ export interface FormatChangeDetails {
 export declare enum DocxDiffRevisionGranularity {
     /** The engine's native one-revision-per-token-span grain (the default). */
     Fine = 0,
-    /** Coalesced to counts/texts comparable to the shipped WmlComparer's. */
+    /** Coalesced to the coarser contiguous-region grain the legacy comparer reported. */
     WmlComparerCompatible = 1
 }
 /**
@@ -529,6 +450,96 @@ export interface DocxDiffRevision {
      *  also set for a token-level delete inside a modified block; undefined for a whole-block deletion. */
     rightAnchor?: string;
 }
+/** A data product selectable in `docxDiffCompareProducts`. */
+export type DocxDiffProduct = "redline" | "revisions" | "editScript" | "semanticChanges";
+/**
+ * The requested products of ONE memoized comparison pass, from
+ * `docxDiffCompareProducts` (issue #594). Unrequested products are undefined.
+ * Each present product equals what the corresponding standalone function
+ * returns for the same inputs and settings — except `editScript`, which is
+ * handed over parsed (the standalone `docxDiffGetEditScript` returns the
+ * serialized string).
+ */
+export interface DocxDiffProducts {
+    /** The native tracked-changes redline (what `docxDiffCompare` returns). */
+    redline?: Uint8Array;
+    /** The anchor-addressed revision list (what `docxDiffGetRevisions` returns). */
+    revisions?: DocxDiffRevision[];
+    /** The engine's edit script, parsed. */
+    editScript?: Record<string, unknown>;
+    /** The stable semantic-change schema (what `docxDiffGetSemanticChanges` returns). */
+    semanticChanges?: SemanticChangeSet;
+}
+/** One candidate of a {@link docxDiffCompareBatch} run: the products of comparing the shared
+ *  baseline against it, or the error that comparing it produced. */
+export interface DocxDiffBatchResult extends DocxDiffProducts {
+    /** The candidate's name, echoed from the request (its index when none was given). */
+    name: string;
+    /** Set when this candidate failed; its products are then absent. The rest of the batch is
+     *  unaffected — one malformed counterparty markup must not cost the other ninety-nine. */
+    error?: string;
+}
+/** A candidate document for {@link docxDiffCompareBatch}. */
+export interface DocxDiffBatchCandidate {
+    /** Echoed back on the matching result. Defaults to the candidate's index. */
+    name?: string;
+    /** The candidate document. */
+    document: File | Uint8Array;
+}
+/** Stable v1 operation names emitted by the semantic-change schema. */
+export type SemanticChangeOperation = "insert" | "delete" | "move" | "modify";
+/** Stable v1 semantic families. New schema versions may append families. */
+export type SemanticChangeFamily = "text" | "block_structure" | "run_formatting" | "paragraph_formatting" | "style" | "numbering" | "list" | "table" | "table_row" | "table_cell" | "table_span" | "table_width" | "table_style" | "section" | "page_setup" | "header" | "footer" | "field" | "footnote" | "endnote" | "comment" | "hyperlink" | "bookmark" | "content_control" | "image" | "media" | "relationship" | "revision" | "annotation" | "opaque_package_part";
+/**
+ * Closed typed value used in {@link SemanticChange.before} and `after`.
+ * Schema v1 integers stay within `Number.MIN_SAFE_INTEGER..Number.MAX_SAFE_INTEGER`; a document
+ * value outside that range arrives as a decimal `string` rather than a rounded `integer`.
+ */
+export type SemanticValue = {
+    kind: "absent";
+} | {
+    kind: "string";
+    value: string;
+} | {
+    kind: "boolean";
+    value: boolean;
+} | {
+    kind: "integer";
+    value: number;
+} | {
+    kind: "digest";
+    algorithm: string;
+    profile: string | null;
+    value: string;
+} | {
+    kind: "object";
+    value: Record<string, SemanticValue>;
+} | {
+    kind: "array";
+    value: SemanticValue[];
+};
+/** One deterministic, anchor-addressed semantic change. */
+export interface SemanticChange {
+    id: string;
+    operation: SemanticChangeOperation;
+    family: SemanticChangeFamily;
+    partUri: string;
+    path: string;
+    leftAnchor: string | null;
+    rightAnchor: string | null;
+    leftScope: string | null;
+    rightScope: string | null;
+    moveId: string | null;
+    before: SemanticValue;
+    after: SemanticValue;
+}
+/** Public `docxodus.semantic-changes` schema returned by semantic comparison APIs. */
+export interface SemanticChangeSet {
+    schema: "docxodus.semantic-changes";
+    schemaVersion: 1;
+    changeCount: number;
+    changes: SemanticChange[];
+}
 /**
  * How overlapping reviewer edits at the same base token span are resolved.
  * Integer values match the .NET `ConflictResolution` enum positions.
@@ -601,7 +612,7 @@ export interface DocxDiffConsolidatedRevision extends DocxDiffRevision {
  * const insertions = revisions.filter(isInsertion);
  * ```
  */
-export declare function isInsertion(revision: Revision): boolean;
+export declare function isInsertion(revision: RevisionListEntry): boolean;
 /**
  * Type guard to check if a revision is a deletion.
  * @param revision - The revision to check
@@ -613,7 +624,7 @@ export declare function isInsertion(revision: Revision): boolean;
  * const deletions = revisions.filter(isDeletion);
  * ```
  */
-export declare function isDeletion(revision: Revision): boolean;
+export declare function isDeletion(revision: RevisionListEntry): boolean;
 /**
  * Type guard to check if a revision is a move operation.
  * @param revision - The revision to check
@@ -625,7 +636,7 @@ export declare function isDeletion(revision: Revision): boolean;
  * const moves = revisions.filter(isMove);
  * ```
  */
-export declare function isMove(revision: Revision): boolean;
+export declare function isMove(revision: RevisionListEntry): boolean;
 /**
  * Type guard to check if a revision is a format change.
  * @param revision - The revision to check
@@ -640,47 +651,7 @@ export declare function isMove(revision: Revision): boolean;
  * }
  * ```
  */
-export declare function isFormatChange(revision: Revision): boolean;
-/**
- * Type guard to check if a revision is a move source (content moved FROM here).
- * @param revision - The revision to check
- * @returns true if the revision is the source of a move
- *
- * @example
- * ```typescript
- * const revisions = await getRevisions(doc);
- * const moveSources = revisions.filter(isMoveSource);
- * ```
- */
-export declare function isMoveSource(revision: Revision): boolean;
-/**
- * Type guard to check if a revision is a move destination (content moved TO here).
- * @param revision - The revision to check
- * @returns true if the revision is the destination of a move
- *
- * @example
- * ```typescript
- * const revisions = await getRevisions(doc);
- * const moveDestinations = revisions.filter(isMoveDestination);
- * ```
- */
-export declare function isMoveDestination(revision: Revision): boolean;
-/**
- * Find the matching pair for a move revision.
- * @param revision - A move revision
- * @param allRevisions - All revisions from the document
- * @returns The matching move revision, or undefined if not found
- *
- * @example
- * ```typescript
- * const revisions = await getRevisions(doc);
- * for (const rev of revisions.filter(isMoveSource)) {
- *   const destination = findMovePair(rev, revisions);
- *   console.log(`"${rev.text}" moved to become "${destination?.text}"`);
- * }
- * ```
- */
-export declare function findMovePair(revision: Revision, allRevisions: Revision[]): Revision | undefined;
+export declare function isFormatChange(revision: RevisionListEntry): boolean;
 /**
  * Version information for the library
  */
@@ -704,13 +675,387 @@ export interface CompareResult {
     /** The redlined document as a Uint8Array */
     document: Uint8Array;
     /** List of revisions found */
-    revisions: Revision[];
+    revisions: RevisionListEntry[];
+}
+/** Algorithm-labelled digest in a verification artifact. */
+export interface VerificationDigest {
+    algorithm: string;
+    /** Lower-case hexadecimal digest bytes. */
+    value: string;
+}
+/** Stable package location attached to a verification finding. */
+export interface ChangeLocation {
+    entryUri: string | null;
+    ownerUri: string | null;
+    relationshipId: string | null;
+    targetUri: string | null;
+    propertyPath: string | null;
+}
+export type VerificationFindingSeverity = "info" | "warning" | "error";
+/** Machine-readable package validation or safety finding. */
+export interface VerificationFinding {
+    code: string;
+    severity: VerificationFindingSeverity;
+    message: string;
+    location: ChangeLocation | null;
+}
+/** One physical ZIP entry. Duplicate names remain separate occurrences. */
+export interface PackageManifestEntry {
+    uri: string;
+    occurrence: number;
+    contentType: string | null;
+    contentTypeSource: "override" | "default" | "implicit" | "unresolved";
+    /** Exact declared uncompressed byte length as a base-10 integer string. */
+    size: string;
+    /** Exact compressed ZIP byte length as a base-10 integer string. */
+    compressedSize: string;
+    rawBytesDigest: VerificationDigest | null;
+    normalizedXmlDigest: VerificationDigest | null;
+    isXml: boolean;
+    /** null when central-directory encryption flags could not be parsed authoritatively. */
+    isEncrypted: boolean | null;
+}
+export interface PackageContentTypeDeclaration {
+    kind: "default" | "override";
+    key: string;
+    contentType: string;
+    occurrence: number;
+}
+export interface PackageRelationship {
+    ownerUri: string;
+    id: string;
+    type: string;
+    target: string;
+    targetMode: "Internal" | "External";
+    resolvedTargetUri: string | null;
+    isTargetPresent: boolean | null;
+}
+export interface PackageRevisionCounts {
+    insertions: number;
+    deletions: number;
+    moveFrom: number;
+    moveTo: number;
+    propertyChanges: number;
+    /** The `rPrChange` subset of `propertyChanges`; not added into `total`. */
+    runPropertyChanges: number;
+    structuralChanges: number;
+    otherChanges: number;
+    total: number;
+}
+export interface PackageAnnotationCounts {
+    comments: number;
+    commentReplies: number;
+    threadedCommentMetadata: number;
+    resolvedComments: number;
+    people: number;
+    docxodusAnnotations: number;
+}
+export interface PackageManifestFacts {
+    mainDocumentUri: string | null;
+    isStrictOoxml: boolean;
+    isMacroEnabled: boolean;
+    hasCoreProperties: boolean;
+    hasExtendedProperties: boolean;
+    hasCustomProperties: boolean;
+    sectionCount: number;
+    paragraphCount: number;
+    tableCount: number;
+    headerPartCount: number;
+    footerPartCount: number;
+    footnoteCount: number;
+    endnoteCount: number;
+    styleCount: number;
+    numberingDefinitionCount: number;
+    themePartCount: number;
+    mediaPartCount: number;
+    customXmlPartCount: number;
+    drawingCount: number;
+    altChunkCount: number;
+    fieldCount: number;
+    revisions: PackageRevisionCounts;
+    annotations: PackageAnnotationCounts;
+}
+/** Deterministic schema-v1 description of a DOCX/OPC package. */
+export interface PackageManifest {
+    schema: "https://docxodus.dev/schemas/verification/package-manifest/v1";
+    schemaVersion: 1;
+    packageKind: "opc" | "zip" | "zip-encrypted" | "ole-encrypted" | "ole" | "malformed";
+    isValid: boolean;
+    rawPackageBytesDigest: VerificationDigest;
+    orderedOpcContentDigest: VerificationDigest | null;
+    normalizedSemanticDigest: VerificationDigest | null;
+    entries: readonly PackageManifestEntry[];
+    contentTypes: readonly PackageContentTypeDeclaration[];
+    relationships: readonly PackageRelationship[];
+    facts: PackageManifestFacts;
+    findings: readonly VerificationFinding[];
+}
+/** Policy preset used by the default deliverable gate. */
+export type DeliverableVerificationMode = "standard" | "strict" | "reportOnly";
+/** Final policy decision in a deliverable-verification report. */
+export type DeliverableVerificationDecision = "passed" | "passedWithPreExistingFindings" | "failed" | "notEvaluated";
+/** How a delivered finding relates to the exact opening/baseline package. */
+export type DeliverableFindingDisposition = "new" | "preExisting" | "resolved" | "unclassified";
+export type DeliverableFindingCategory = "package" | "openXml" | "relationship" | "structure" | "workflow" | "delta" | "render" | "artifact";
+export type DeliverableCheckStatus = "completed" | "skippedPrerequisiteFailed" | "unavailableEvidence";
+export type DeliverablePackageChangeKind = "entryAdded" | "entryRemoved" | "entryModified" | "relationshipAdded" | "relationshipRemoved" | "relationshipModified";
+export type DeliverableArtifactRole = "html" | "pdf" | "pageMap" | "pageImage" | "renderReport" | "other";
+export type DeliverableArtifactAvailability = "available" | "unavailable";
+/** Camel-case enum values used by the deliverable report's semantic summary. */
+export type DeliverableSemanticChangeFamily = "text" | "blockStructure" | "runFormatting" | "paragraphFormatting" | "style" | "numbering" | "list" | "table" | "tableRow" | "tableCell" | "tableSpan" | "tableWidth" | "tableStyle" | "section" | "pageSetup" | "header" | "footer" | "field" | "footnote" | "endnote" | "comment" | "hyperlink" | "bookmark" | "contentControl" | "image" | "media" | "relationship" | "revision" | "annotation" | "opaquePackagePart";
+export interface DeliverablePackageIdentity {
+    packageKind: string;
+    manifestValid: boolean;
+    rawPackageBytesDigest: VerificationDigest;
+    orderedOpcContentDigest: VerificationDigest | null;
+    normalizedSemanticDigest: VerificationDigest | null;
+}
+export interface DeliverableCheckResult {
+    check: string;
+    status: DeliverableCheckStatus;
+    findingCount: number;
+    diagnostic: string | null;
+}
+export interface DeliverableFinding {
+    findingId: string;
+    code: string;
+    category: DeliverableFindingCategory;
+    severity: VerificationFindingSeverity;
+    disposition: DeliverableFindingDisposition;
+    blocksDelivery: boolean;
+    message: string;
+    owningPartUri: string;
+    location: ChangeLocation | null;
+    anchorId: string | null;
+    scope: string | null;
+    xPath: string | null;
+    remediation: string;
+}
+export interface DeliverablePackageChange {
+    changeId: string;
+    kind: DeliverablePackageChangeKind;
+    location: ChangeLocation;
+    beforeDigest: VerificationDigest | null;
+    afterDigest: VerificationDigest | null;
+    beforeValue: string | null;
+    afterValue: string | null;
+}
+export interface DeliverableSemanticChange {
+    changeId: string;
+    fingerprint: string;
+    operation: SemanticChangeOperation;
+    family: DeliverableSemanticChangeFamily;
+    partUri: string;
+    path: string;
+    leftAnchor: string | null;
+    rightAnchor: string | null;
+}
+export interface DeliverableSemanticDelta {
+    schema: "docxodus.semantic-changes";
+    schemaVersion: 1;
+    changeCount: number;
+    canonicalDigest: VerificationDigest;
+    changes: readonly DeliverableSemanticChange[];
+}
+export interface DeliverableArtifactMetadata {
+    artifactId: string;
+    role: DeliverableArtifactRole;
+    mediaType: string;
+    availability: DeliverableArtifactAvailability;
+    byteLength: number | null;
+    digest: VerificationDigest | null;
+    unavailableReason: string | null;
+    pageCount: number | null;
+    rendererFingerprint: string | null;
+    sourcePackageDigest: VerificationDigest | null;
+    pageMapDigest: VerificationDigest | null;
+    renderDiagnosticCount: number;
+}
+/** Canonical schema-v1 report returned by every default verification transport. */
+/** One recorded artifact's independent re-hash verdict from receipt verification. */
+export type DeliveryArtifactVerificationStatus = "verified" | "unavailable" | "missing" | "length_mismatch" | "digest_mismatch" | "invalid_record";
+export interface DeliveryArtifactVerification {
+    artifactId: string;
+    status: DeliveryArtifactVerificationStatus;
+    expectedLength?: number;
+    actualLength?: number;
+    expectedDigest?: VerificationDigest;
+    actualDigest?: VerificationDigest;
+}
+/**
+ * Portable delivery change receipt verification verdict — the shared facade wire
+ * shape every transport returns (issue #520).
+ */
+export interface DeliveryReceiptVerificationResult {
+    isValid: boolean;
+    receiptDigestValid: boolean;
+    contractValid: boolean;
+    citationBindingsValid: boolean;
+    artifacts: DeliveryArtifactVerification[];
+    findings: string[];
+}
+export interface DeliverableVerificationResult {
+    schema: "https://docxodus.dev/schemas/verification/deliverable-verification/v1";
+    schemaVersion: 1;
+    mode: DeliverableVerificationMode;
+    decision: DeliverableVerificationDecision;
+    analysisCompleted: boolean;
+    baselineCompared: boolean;
+    baselinePackage: DeliverablePackageIdentity | null;
+    deliverablePackage: DeliverablePackageIdentity;
+    checks: readonly DeliverableCheckResult[];
+    findings: readonly DeliverableFinding[];
+    resolvedFindings: readonly DeliverableFinding[];
+    semanticDelta: DeliverableSemanticDelta | null;
+    packageChanges: readonly DeliverablePackageChange[];
+    companionArtifacts: readonly DeliverableArtifactMetadata[];
+}
+/** How a revision in a redline relates to the selected baseline. */
+export type RedlineRevisionDisposition = "preExisting" | "intendedFinalPreExisting" | "generated" | "conflicted";
+/** Which of the two proof paths a result or finding belongs to. */
+export type RedlineProofDirection = "acceptToFinal" | "rejectToBaseline";
+/** How a package entry differs from a path's expected document. */
+export type RedlinePackageDivergenceKind = "added" | "removed" | "modified";
+/** Fail-closed resolution status of one native revision — the session registry's vocabulary. */
+export type RedlineRevisionResolutionStatus = RevisionResolutionStatus;
+/** Coarse family of one native revision. */
+export type RedlineRevisionFamily = "contentInsert" | "contentDelete" | "move" | "paragraphMark" | "rowInsert" | "rowDelete" | "cellInsert" | "cellDelete" | "cellMerge" | "contentControlInsert" | "contentControlDelete" | "numberingPropertiesInsert" | "numberingChange" | "propertiesChange" | "unsupported";
+/** Why a revision could not be resolved — the session registry's shape. */
+export type RedlineRevisionDiagnostic = RevisionDiagnostic;
+/** Input or output package identity recorded by the proof. */
+export interface RedlineProofPackageIdentity {
+    rawPackageBytesDigest: VerificationDigest;
+    orderedOpcContentDigest: VerificationDigest | null;
+    normalizedWholePackageDigest: VerificationDigest | null;
+}
+/** A stable, part-qualified identity for one native Word revision. */
+export interface RedlineRevisionIdentity {
+    id: string;
+    partUri: string;
+    scope: string;
+    type: string;
+    family: RedlineRevisionFamily;
+    constituentIds: readonly string[];
+    constituentKeys: readonly string[];
+    author: string;
+    date: string | null;
+    dateUtc: string | null;
+    text: string;
+    anchorId: string | null;
+    affectedAnchorIds: readonly string[];
+    resolutionStatus: RedlineRevisionResolutionStatus;
+    diagnostic: RedlineRevisionDiagnostic | null;
+}
+/** Classification of a baseline/intended-final/redline revision identity triple. */
+export interface RedlineRevisionClassification {
+    disposition: RedlineRevisionDisposition;
+    baseline: RedlineRevisionIdentity | null;
+    intendedFinal: RedlineRevisionIdentity | null;
+    redline: RedlineRevisionIdentity | null;
+    reason: string;
+}
+/**
+ * Modeled semantic comparison for one path. `available` and `changeCount` are explicit so an
+ * empty modeled change set is never mistaken for complete package equality.
+ */
+export interface RedlineModeledSemanticComparison {
+    available: boolean;
+    equivalent: boolean | null;
+    schema: string | null;
+    changeCount: number | null;
+    diagnostic: string | null;
+}
+/** One added, removed, or modified package entry on a proof path. */
+export interface RedlinePackageDivergence {
+    kind: RedlinePackageDivergenceKind;
+    partUri: string;
+    occurrence: number;
+    anchorId: string | null;
+    applicableRevisionIds: readonly string[];
+    expectedRawDigest: VerificationDigest | null;
+    actualRawDigest: VerificationDigest | null;
+    expectedNormalizedDigest: VerificationDigest | null;
+    actualNormalizedDigest: VerificationDigest | null;
+    /** Whether the semantic change set reports a modeled change for this part. */
+    hasModeledSemanticChange: boolean;
+    /**
+     * Conservatively true when the normalized difference may contain content outside the modeled
+     * semantic projection. A modeled change in one part never proves every change in it was modeled.
+     */
+    unknownOrUnmodeled: boolean;
+}
+/** A structured, actionable proof finding. */
+export interface RedlineProofFinding {
+    code: string;
+    severity: VerificationFindingSeverity;
+    message: string;
+    direction: RedlineProofDirection | null;
+    location: ChangeLocation | null;
+    anchorId: string | null;
+    revisionIds: readonly string[];
+    remediation: string | null;
+}
+/** Result of accepting or rejecting only the generated revision set. */
+export interface RedlineProofPathResult {
+    direction: RedlineProofDirection;
+    completed: boolean;
+    equivalent: boolean;
+    requestedRevisionIds: readonly string[];
+    resolvedRevisionIds: readonly string[];
+    implicitlyResolvedRevisionIds: readonly string[];
+    survivingPreExistingRevisions: readonly RedlineRevisionIdentity[];
+    preExistingRevisionsPreserved: boolean;
+    modeledSemantic: RedlineModeledSemanticComparison;
+    normalizedWholePackageEquivalent: boolean;
+    orderedOpcContentEquivalent: boolean;
+    exactPackageBytesEquivalent: boolean;
+    /**
+     * Whether the complete bounded package delta was available. A false value never exposes a
+     * potentially misleading prefix of `divergences`.
+     */
+    divergenceAnalysisCompleted: boolean;
+    expectedPackage: RedlineProofPackageIdentity;
+    actualPackage: RedlineProofPackageIdentity | null;
+    firstDivergence: RedlinePackageDivergence | null;
+    divergences: readonly RedlinePackageDivergence[];
+    findings: readonly RedlineProofFinding[];
+}
+/**
+ * Canonical schema-v1 proof that a redline's generated changes accept to the intended final and
+ * reject to the baseline without consuming pre-existing review state.
+ */
+export interface RedlineReversibilityProof {
+    schema: "https://docxodus.dev/schemas/verification/redline-reversibility-proof/v1";
+    schemaVersion: 1;
+    success: boolean;
+    requireExactPackageBytes: boolean;
+    baselinePackage: RedlineProofPackageIdentity;
+    intendedFinalPackage: RedlineProofPackageIdentity;
+    redlinePackage: RedlineProofPackageIdentity;
+    revisionClassifications: readonly RedlineRevisionClassification[];
+    acceptToFinal: RedlineProofPathResult | null;
+    rejectToBaseline: RedlineProofPathResult | null;
+    findings: readonly RedlineProofFinding[];
+}
+/** Effective #493 inspection limits applied while the manifest is being generated. */
+export interface PackageManifestInspectionLimits {
+    opcEntries: number;
+    expandedOpcBytes: number;
+    xmlPartBytes: number;
+    opcUriCharacters: number;
+    opcCompressionRatio: number;
 }
 /**
  * Internal WASM exports structure
  */
 export interface DocxodusWasmExports {
     DocumentConverter: {
+        GeneratePackageManifest: (bytes: Uint8Array) => string;
+        VerifyDeliverable: (bytes: Uint8Array) => string;
+        VerifyDeliveryReceipt: (receiptJson: string, artifactsJson: string) => string;
+        VerifyDeliverableWithBaseline: (baselineBytes: Uint8Array, bytes: Uint8Array) => string;
+        ProveRedlineReversibility: (baselineBytes: Uint8Array, intendedFinalBytes: Uint8Array, redlineBytes: Uint8Array) => string;
+        GeneratePackageManifestWithOptions: (bytes: Uint8Array, maxEntryCount: number, maxTotalUncompressedBytes: number, maxXmlPartBytes: number, maxCompressionRatio: number, maxUriLength: number) => string;
         ConvertDocxToHtml: (bytes: Uint8Array) => string;
         RenderBlockHtml: (bytes: Uint8Array, anchorId: string, cssPrefix: string, fabricateClasses: boolean) => string;
         ConvertDocxToHtmlWithOptions: (bytes: Uint8Array, pageTitle: string, cssPrefix: string, fabricateClasses: boolean, additionalCss: string, commentRenderMode: number, commentCssClassPrefix: string) => string;
@@ -747,15 +1092,12 @@ export interface DocxodusWasmExports {
          * Idempotent — assemblies load only once.
          */
         Warmup: () => string;
-        CompareDocuments: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, engine: number) => Uint8Array;
+        CompareDocuments: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string) => Uint8Array;
         CompareDocumentsToHtml: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string) => string;
-        CompareDocumentsToHtmlWithOptions: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, renderTrackedChanges: boolean, engine: number) => string;
-        CompareDocumentsToHtmlFull: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, detailThreshold: number, caseInsensitive: boolean, renderTrackedChanges: boolean, engine: number) => string;
-        CompareDocumentsWithOptions: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, detailThreshold: number, caseInsensitive: boolean, engine: number) => Uint8Array;
+        CompareDocumentsToHtmlWithOptions: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, renderTrackedChanges: boolean) => string;
+        CompareDocumentsToHtmlFull: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, caseInsensitive: boolean, renderTrackedChanges: boolean) => string;
+        CompareDocumentsWithOptions: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, caseInsensitive: boolean) => Uint8Array;
         GetRevisionsJson: (comparedDocBytes: Uint8Array) => string;
-        GetRevisionsJsonWithOptions: (comparedDocBytes: Uint8Array, detectMoves: boolean, moveSimilarityThreshold: number, moveMinimumWordCount: number, caseInsensitive: boolean) => string;
-        CompareDocumentsWithLog: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, detailThreshold: number, caseInsensitive: boolean) => string;
-        CompareDocumentsToHtmlWithLog: (originalBytes: Uint8Array, modifiedBytes: Uint8Array, authorName: string, detailThreshold: number, caseInsensitive: boolean, renderTrackedChanges: boolean) => string;
     };
     DocxDiffBridge: {
         /** Redlined DOCX bytes (native markup), or empty array on error. */
@@ -764,6 +1106,14 @@ export interface DocxodusWasmExports {
         GetRevisionsJson: (leftBytes: Uint8Array, rightBytes: Uint8Array, settingsJson: string) => string;
         /** Edit-script JSON (diff-as-data), or a JSON error object. */
         GetEditScriptJson: (leftBytes: Uint8Array, rightBytes: Uint8Array, settingsJson: string) => string;
+        /** Canonical `docxodus.semantic-changes` JSON, or a JSON error object. */
+        GetSemanticChangesJson: (leftBytes: Uint8Array, rightBytes: Uint8Array, settingsJson: string) => string;
+        /** One memoized pass, every requested product: `{"redlineB64":…, "revisions":[…],
+         *  "editScript":…, "semanticChanges":…}` JSON (issue #594), or a JSON error object. */
+        CompareProductsJson: (leftBytes: Uint8Array, rightBytes: Uint8Array, settingsJson: string, productsJson: string) => string;
+        /** One baseline read once, compared against many candidates:
+         *  `{"results":[{"name":…, …products…}]}` JSON (issue #617), or a JSON error object. */
+        CompareBatchJson: (baselineBytes: Uint8Array, candidatesJson: string, settingsJson: string, productsJson: string) => string;
         /** Accept all tracked revisions in a redlined DOCX → "right"-side bytes, or empty array on error. */
         AcceptRevisions: (bytes: Uint8Array) => Uint8Array;
         /** Reject all tracked revisions in a redlined DOCX → "left"-side bytes, or empty array on error. */
@@ -779,10 +1129,24 @@ export interface DocxodusWasmExports {
     };
     DocxSessionBridge: {
         OpenSession: (bytes: Uint8Array, settingsJson: string) => number;
+        OpenPreviewSession?: (liveHandle: number) => number;
         CloseSession: (handle: number) => void;
         CreateBlankDocx: () => Uint8Array;
         Project: (handle: number) => string;
+        GetVersion: (handle: number) => string;
+        RegisterPageMap: (handle: number, pageMapJson: string, expectedRendererFingerprint: string) => string;
+        GetPageMapStatus: (handle: number, requestJson: string) => string;
+        GetPageCitation: (handle: number, anchorId: string, requestJson: string) => string;
+        GetPackageContentHash?: (handle: number) => string;
+        GetPackageManifest: (handle: number) => string;
+        RenderPreviewHtml?: (handle: number) => string;
+        RenderPreviewBlockHtml?: (handle: number, anchorId: string) => string;
+        CheckPreconditions: (handle: number, preconditionsJson: string) => string;
+        BeginTransaction: (handle: number) => number;
+        CommitTransaction: (transactionHandle: number) => void;
+        RollbackTransaction: (transactionHandle: number) => void;
         ProjectAnchor: (handle: number, anchorId: string, depth: number) => string;
+        ProjectAnchorWithCitations: (handle: number, anchorId: string, depth: number, requestJson: string) => string;
         /** Ordered top-level render units per scope container (JSON {@link RenderPlan}) —
          *  what the editor's incremental reconciler diffs its DOM against. Optional:
          *  absent on older WASM bundles. */
@@ -822,6 +1186,9 @@ export interface DocxodusWasmExports {
         MergeParagraphs: (handle: number, first: string, second: string) => string;
         InsertHorizontalRule: (handle: number, anchor: string, pos: string, ruleJson: string) => string;
         InsertTable: (handle: number, anchor: string, pos: string, rows: number, cols: number, optionsJson: string) => string;
+        GetTableMetadata: (handle: number, tableAnchor: string) => string;
+        ResolveTableCellAnchor: (handle: number, cellAnchor: string) => string;
+        ResolveTableCellCoordinate: (handle: number, tableAnchor: string, rowIndex: number, columnIndex: number) => string;
         InsertTableRow: (handle: number, cellAnchor: string, pos: string) => string;
         InsertTableColumn: (handle: number, cellAnchor: string, pos: string) => string;
         DeleteTableRow: (handle: number, cellAnchor: string) => string;
@@ -832,13 +1199,18 @@ export interface DocxodusWasmExports {
         SetTableBorders: (handle: number, cellAnchor: string, specJson: string) => string;
         SetCellShading: (handle: number, cellAnchor: string, fill: string, scope: string) => string;
         SetRepeatHeaderRow: (handle: number, cellAnchor: string, repeat: boolean) => string;
+        SetTableRowOptions: (handle: number, cellAnchor: string, repeatHeader: boolean | null, allowBreakAcrossPages: boolean | null, heightTwips: number | null, heightRule: string) => string;
         SetHeaderText: (handle: number, anchor: string, kind: string, markdown: string) => string;
         SetFooterText: (handle: number, anchor: string, kind: string, markdown: string) => string;
         InsertPageNumberField: (handle: number, anchor: string, field: string, format: string) => string;
         SetPageNumbering: (handle: number, anchor: string, opJson: string) => string;
+        InsertTableOfContents: (handle: number, anchor: string, pos: string, optionsJson: string) => string;
+        InsertTableOfFigures: (handle: number, anchor: string, pos: string, optionsJson: string) => string;
+        InsertTableOfAuthorities: (handle: number, anchor: string, pos: string, optionsJson: string) => string;
         ClearPageNumbering: (handle: number, anchor: string) => string;
         EnsureHeaderFooterVisible: (handle: number, anchor: string, kind: string) => string;
         InsertFootnote: (handle: number, anchor: string, characterOffset: number, markdown: string) => string;
+        InsertCrossReference: (handle: number, anchor: string, characterOffset: number, bookmarkName: string, optionsJson: string) => string;
         InsertEndnote: (handle: number, anchor: string, characterOffset: number, markdown: string) => string;
         AddComment: (handle: number, anchor: string, spanJson: string, author: string, initials: string, date: string, markdown: string) => string;
         AddCommentToRevision: (handle: number, revisionId: string, author: string, initials: string, date: string, markdown: string) => string;
@@ -847,9 +1219,37 @@ export interface DocxodusWasmExports {
         SetCommentResolved: (handle: number, commentAnchor: string, resolved: boolean) => string;
         RemoveComment: (handle: number, commentAnchor: string) => string;
         ListComments: (handle: number) => string;
+        ListHyperlinks: (handle: number, scopes: number) => string;
+        AddHyperlink: (handle: number, anchor: string, start: number, length: number, kind: string, target: string) => string;
+        UpdateHyperlink: (handle: number, hyperlinkId: string, kind: string, target: string) => string;
+        RemoveHyperlink: (handle: number, hyperlinkId: string) => string;
+        GetImageCapabilities: () => string;
+        ListImages: (handle: number, scopes: number) => string;
+        InsertImage: (handle: number, anchor: string, characterOffset: number, imageBase64: string, optionsJson: string) => string;
+        ReplaceImage: (handle: number, imageId: string, imageBase64: string) => string;
+        SetImageDimensions: (handle: number, imageId: string, dimensionsJson: string) => string;
+        SetImageMetadata: (handle: number, imageId: string, altText: string | null, title: string | null) => string;
+        SetImageFloatingLayout: (handle: number, imageId: string, layoutJson: string) => string;
+        RemoveImage: (handle: number, imageId: string) => string;
+        ListContentControls: (handle: number, scopes: number) => string;
+        FillContentControlText: (handle: number, anchorId: string, text: string, optionsJson: string) => string;
+        FillContentControlRichText: (handle: number, anchorId: string, markdown: string, optionsJson: string) => string;
+        SetContentControlChecked: (handle: number, anchorId: string, isChecked: boolean, optionsJson: string) => string;
+        SetContentControlDate: (handle: number, anchorId: string, value: string, displayText: string | null, optionsJson: string) => string;
+        SelectContentControlItem: (handle: number, anchorId: string, value: string, optionsJson: string) => string;
+        FillContentControlPicture: (handle: number, anchorId: string, imageBase64: string, optionsJson: string) => string;
+        AddRepeatingSectionItem: (handle: number, sectionAnchorId: string, afterItemAnchorId: string, optionsJson: string) => string;
+        RemoveRepeatingSectionItem: (handle: number, itemAnchorId: string) => string;
+        ListBookmarks: (handle: number, scopes: number) => string;
+        AddBookmark: (handle: number, name: string, startAnchor: string, startOffset: number, endAnchor: string, endOffset: number) => string;
+        RenameBookmark: (handle: number, name: string, newName: string) => string;
+        MoveBookmark: (handle: number, name: string, startAnchor: string, startOffset: number, endAnchor: string, endOffset: number) => string;
+        RemoveBookmark: (handle: number, name: string) => string;
         ListRevisions: (handle: number) => string;
         AcceptRevision: (handle: number, revisionId: string) => string;
         RejectRevision: (handle: number, revisionId: string) => string;
+        AcceptAllRevisions: (handle: number) => string;
+        RejectAllRevisions: (handle: number) => string;
         ApplyFormat: (handle: number, anchor: string, spanJson: string, opJson: string) => string;
         ApplyFormatBySubstring: (handle: number, anchor: string, substring: string, opJson: string) => string;
         SetParagraphStyle: (handle: number, anchor: string, styleId: string) => string;
@@ -870,23 +1270,33 @@ export interface DocxodusWasmExports {
         ReplaceTextAtSpan: (handle: number, anchor: string, spanStart: number, spanLength: number, replace: string) => string;
         ReplaceInner: (handle: number, matchText: string, anchor: string, spanStart: number, spanLength: number, newInner: string) => string;
         FindPlaceholders: (handle: number, kinds: number, scope: number, contextChars: number, boundary: number) => string;
+        FindPlaceholdersWithCitations: (handle: number, kinds: number, scope: number, contextChars: number, boundary: number, requestJson: string) => string;
         GetEditSummary: (handle: number) => string;
         RemainingPlaceholders: (handle: number, kinds: number) => string;
         GetDiff: (handle: number, format: number) => string;
+        GetSemanticChanges: (handle: number) => string;
+        VerifyDeliverable: (handle: number) => string;
         FindByAnnotation: (handle: number, annotationId: string) => string;
+        FindByAnnotationWithCitations: (handle: number, annotationId: string, requestJson: string) => string;
         FindByLabel: (handle: number, labelId: string) => string;
+        FindByLabelWithCitations: (handle: number, labelId: string, requestJson: string) => string;
         FindByBookmark: (handle: number, bookmarkName: string) => string;
+        FindByBookmarkWithCitations: (handle: number, bookmarkName: string, requestJson: string) => string;
         Exists: (handle: number, anchorId: string) => boolean;
         FindByText: (handle: number, needle: string, optionsJson: string) => string;
         FindAllByText: (handle: number, needle: string, optionsJson: string) => string;
         FindByRegex: (handle: number, pattern: string, regexOptions: number, optionsJson: string) => string;
         FindByKind: (handle: number, kind: string, scope: string) => string;
+        FindByKindWithCitations: (handle: number, kind: string, scope: string, requestJson: string) => string;
         GetAnchorInfo: (handle: number, anchorId: string) => string;
         GetAnchorInfos: (handle: number, anchorIdsJson: string) => string;
         GetBlockMetadata: (handle: number, anchorId: string) => string;
         GetBlockMetadatas: (handle: number, anchorIdsJson: string) => string;
         GetListMembership: (handle: number, anchorId: string) => string;
         GetSectionInfo: (handle: number, anchorId: string) => string;
+        ListStyles: (handle: number) => string;
+        GetFormatting: (handle: number, anchorId: string) => string;
+        ListInlineSpans: (handle: number, anchorId: string) => string;
         ListAnnotations: (handle: number) => string;
         AddAnnotation: (handle: number, anchorId: string, spanJson: string, annotationJson: string) => string;
         SessionRemoveAnnotation: (handle: number, annotationId: string) => string;
@@ -904,7 +1314,7 @@ export interface DocxodusWasmExports {
         SaveWithAnchorIds: (handle: number) => Uint8Array;
     };
 }
-export type EditErrorCode = "anchor_not_found" | "anchor_wrong_kind" | "anchors_not_adjacent" | "session_disposed" | "malformed_markdown" | "unsupported_markdown_syntax" | "table_insert_not_supported" | "footnote_ref_not_supported" | "comment_marker_not_supported" | "image_insert_not_supported" | "anchor_token_in_payload" | "offset_out_of_range" | "invalid_position" | "unknown_style" | "invalid_list_level" | "invalid_list_start_value" | "invalid_page_numbering" | "invalid_paragraph_format" | "invalid_table_styling" | "invalid_table_merge" | "malformed_xml" | "disallowed_namespace" | "incompatible_element_type" | "validation_failed" | "nothing_to_undo" | "nothing_to_redo" | "duplicate_annotation_id" | "annotation_not_found" | "empty_annotation_span" | "empty_comment_span" | "revision_not_found" | "internal_error";
+export type EditErrorCode = "anchor_not_found" | "anchor_wrong_kind" | "anchors_not_adjacent" | "session_disposed" | "malformed_markdown" | "unsupported_markdown_syntax" | "table_insert_not_supported" | "footnote_ref_not_supported" | "comment_marker_not_supported" | "image_insert_not_supported" | "anchor_token_in_payload" | "offset_out_of_range" | "invalid_position" | "text_not_found" | "unknown_style" | "invalid_list_level" | "invalid_list_start_value" | "invalid_page_numbering" | "invalid_reference_field" | "invalid_paragraph_format" | "invalid_table_styling" | "invalid_table_merge" | "table_anchor_migration_required" | "malformed_xml" | "disallowed_namespace" | "incompatible_element_type" | "validation_failed" | "nothing_to_undo" | "nothing_to_redo" | "duplicate_annotation_id" | "annotation_not_found" | "empty_annotation_span" | "empty_comment_span" | "revision_not_found" | "precondition_failed" | "invalid_batch_step" | "invalid_transaction" | "transaction_conflict" | "transaction_result_evicted" | "transaction_incomplete" | "hyperlink_not_found" | "bookmark_not_found" | "duplicate_bookmark_name" | "invalid_bookmark_name" | "invalid_hyperlink_target" | "missing_bookmark_target" | "bookmark_in_use" | "managed_bookmark" | "empty_hyperlink_span" | "unsupported_inline_boundary" | "revision_unsupported" | "revision_malformed" | "revision_ambiguous" | "tracked_operation_unsupported" | "unresolved_structural_revision" | "content_control_not_found" | "content_control_malformed" | "content_control_unsupported" | "content_control_locked" | "content_control_bound" | "content_control_wrong_type" | "invalid_content_control_value" | "content_control_placement_unsupported" | "content_control_nested_fill_unsupported" | "repeating_section_constraint" | "image_not_found" | "invalid_image_data" | "unsupported_image_format" | "image_too_large" | "invalid_image_dimensions" | "unsupported_image_markup" | "linked_image_read_only" | "invalid_image_layout" | "internal_error";
 export interface AnchorRef {
     id: string;
     kind: string;
@@ -915,6 +1325,105 @@ export interface EditError {
     code: EditErrorCode;
     message: string;
     anchorId?: string;
+    precondition?: PreconditionFailure;
+}
+export interface PreconditionTarget {
+    exists: boolean;
+    anchorId?: string;
+    kind?: string;
+    scope?: string;
+    contentHash?: string;
+    visibleText?: string;
+}
+export interface PreconditionFailure {
+    condition: string;
+    expected: unknown;
+    actual: unknown;
+    currentVersion: number;
+    currentTarget?: PreconditionTarget;
+}
+export interface TextRangePrecondition {
+    start: number;
+    length: number;
+    text: string;
+}
+/** Optimistic guards checked immediately before a mutation. */
+export interface MutationPreconditions {
+    expectedVersion?: number;
+    /** Optional explicit target; target-addressed methods infer their own anchor when omitted. */
+    anchorId?: string;
+    expectedContentHash?: string;
+    expectedText?: string;
+    expectedTextRange?: TextRangePrecondition;
+    expectedKind?: string;
+    expectedScope?: string;
+    expectedMatchCount?: number;
+}
+export type MutationBatchMode = "atomic" | "best_effort";
+/** One synchronous npm batch step. Atomic is the default execution mode. */
+export interface MutationBatchStep {
+    tool: string;
+    action: string;
+    mutation: () => EditResult | readonly EditResult[];
+    /** Optional read-only validation: all run up front in atomic mode, per-step in best-effort. */
+    preflight?: () => EditError | undefined;
+}
+/** A preview callback receives the isolated shadow session it must mutate/read. */
+export interface MutationBatchPreviewStep {
+    tool: string;
+    action: string;
+    mutation: (shadow: import("./session.js").DocxSession) => EditResult | readonly EditResult[];
+    preflight?: (shadow: import("./session.js").DocxSession) => EditError | undefined;
+}
+export interface MutationBatchPreviewOptions {
+    html?: "none" | "scoped" | "full";
+    /** Required for scoped HTML. */
+    htmlAnchorId?: string;
+}
+export interface MutationBatchStepResult {
+    index: number;
+    tool: string;
+    action: string;
+    success: boolean;
+    rolledBack: boolean;
+    results: readonly EditResult[];
+}
+export interface MutationBatchFailure {
+    index: number;
+    tool: string;
+    action: string;
+    error: EditError;
+    rolledBack: boolean;
+}
+export interface MutationBatchChangeSet<T> {
+    added: readonly T[];
+    removed: readonly T[];
+    modified: readonly T[];
+}
+export interface MutationBatchResult {
+    mode: MutationBatchMode;
+    status: "ok" | "failed" | "partial";
+    preview: boolean;
+    success: boolean;
+    rolledBack: boolean;
+    baseVersion: number;
+    resultVersion: number;
+    /**
+     * Canonical SHA-256 of this result package, or `null` when it could not be computed.
+     * Exact replay equality is guaranteed only for deterministic batches, so consult
+     * {@link MutationBatchResult.warnings} before asserting on it — and note that `null`
+     * never equals `null` for the purposes of a replay assertion: an absent hash proves
+     * nothing and must be handled explicitly rather than compared.
+     */
+    packageHash: string | null;
+    steps: readonly MutationBatchStepResult[];
+    failure?: MutationBatchFailure;
+    revisionChanges: MutationBatchChangeSet<RevisionListEntry>;
+    commentChanges: MutationBatchChangeSet<CommentListEntry>;
+    annotationChanges: MutationBatchChangeSet<DocumentAnnotation>;
+    warnings: readonly string[];
+    /** Shadow-only preview HTML when requested; null otherwise. */
+    html: string | null;
 }
 export interface MarkdownPatch {
     scopeAnchorId: string;
@@ -926,10 +1435,196 @@ export interface EditResult {
     created: AnchorRef[];
     removed: AnchorRef[];
     modified: AnchorRef[];
+    /** Deterministic structural identity map for table shape mutations. */
+    tableAnchors?: TableAnchorMapping;
     patch?: MarkdownPatch;
     /** Set by the annotation ops (addAnnotation/removeAnnotation/updateAnnotation/
      * moveAnnotation) with the affected annotation id; absent for every other op. */
     annotationId?: string;
+    hyperlinkId?: string;
+    bookmarkName?: string;
+    imageId?: string;
+}
+export type HyperlinkKind = "external" | "internal";
+export interface HyperlinkInfo {
+    id: string;
+    kind: HyperlinkKind;
+    owningPartUri: string;
+    scope: string;
+    anchorId: string;
+    span: CharSpan;
+    text: string;
+    target?: string;
+    relationshipId?: string;
+    relationshipIsExternal?: boolean;
+    isBroken: boolean;
+}
+export type ImageBinaryFormat = "unknown" | "png" | "jpeg" | "gif" | "bmp" | "tiff" | "webp";
+export type ImageMarkupKind = "modern_drawing" | "legacy_vml" | "unsupported_drawing";
+export type ImagePlacement = "inline" | "floating";
+export type ImageWrapMode = "none" | "square" | "tight" | "through" | "top_and_bottom" | "unknown";
+export type ImageWrapSide = "both_sides" | "left" | "right" | "largest" | "unknown";
+export type ImageHorizontalReference = "page" | "margin" | "column" | "character" | "unknown";
+export type ImageVerticalReference = "page" | "margin" | "paragraph" | "line" | "unknown";
+export type ImageHorizontalAlignment = "left" | "center" | "right" | "inside" | "outside" | "unknown";
+export type ImageVerticalAlignment = "top" | "center" | "bottom" | "inside" | "outside" | "unknown";
+export interface FloatingImageLayout {
+    horizontalRelativeFrom?: ImageHorizontalReference;
+    horizontalOffsetEmu?: number | null;
+    horizontalAlignment?: ImageHorizontalAlignment | null;
+    verticalRelativeFrom?: ImageVerticalReference;
+    verticalOffsetEmu?: number | null;
+    verticalAlignment?: ImageVerticalAlignment | null;
+    wrapMode?: ImageWrapMode;
+    wrapSide?: ImageWrapSide;
+    distanceTopEmu?: number;
+    distanceBottomEmu?: number;
+    distanceLeftEmu?: number;
+    distanceRightEmu?: number;
+    relativeHeight?: number;
+    behindDocument?: boolean;
+    locked?: boolean;
+    layoutInCell?: boolean;
+    allowOverlap?: boolean;
+    rawHorizontalReference?: string;
+    rawVerticalReference?: string;
+    rawHorizontalPosition?: string;
+    rawVerticalPosition?: string;
+    rawWrapMode?: string;
+    rawWrapSide?: string;
+    rawRelativeSizeHorizontal?: string;
+    rawRelativeSizeVertical?: string;
+    rawFlagTokens?: Record<string, string>;
+}
+export interface ImageInsertOptions {
+    placement?: ImagePlacement;
+    widthPoints?: number;
+    heightPoints?: number;
+    preserveAspect?: boolean;
+    altText?: string | null;
+    title?: string | null;
+    floatingLayout?: FloatingImageLayout;
+}
+export interface ImageDimensions {
+    widthPoints?: number;
+    heightPoints?: number;
+    preserveAspect?: boolean;
+}
+export interface ImageOccurrence {
+    id: string;
+    markupKind: ImageMarkupKind;
+    placement?: ImagePlacement;
+    canMutate: boolean;
+    unsupportedReason?: string;
+    owningPartUri: string;
+    scope: string;
+    anchorId: string;
+    span: CharSpan;
+    relationshipId?: string;
+    targetPartUri?: string;
+    linkedRelationshipId?: string;
+    linkedTarget?: string;
+    isEmbedded: boolean;
+    isLinked: boolean;
+    isBroken: boolean;
+    mediaFileName?: string;
+    contentType?: string;
+    format: ImageBinaryFormat;
+    contentTypeMatchesBytes?: boolean;
+    intrinsicWidthPixels?: number;
+    intrinsicHeightPixels?: number;
+    renderedWidthPoints?: number;
+    renderedHeightPoints?: number;
+    altText?: string;
+    title?: string;
+    floatingLayout?: FloatingImageLayout;
+    floatingLayoutSupported: boolean;
+}
+export interface ImageFormatCapability {
+    format: ImageBinaryFormat;
+    contentType: string;
+    canInspect: boolean;
+    canInsert: boolean;
+    canReplace: boolean;
+    limitation?: string;
+}
+export interface ImageCapabilities {
+    schemaVersion: number;
+    runtime: string;
+    formats: ImageFormatCapability[];
+    operations: string[];
+    mutableWrapModes: ImageWrapMode[];
+    horizontalReferences: ImageHorizontalReference[];
+    verticalReferences: ImageVerticalReference[];
+    maxInputBytes: number;
+    maxRenderedPoints: number;
+    defaultDpi: number;
+    usesHeaderParsingOnly: boolean;
+    acceptsBinaryBytes: boolean;
+    supportsNetworkFetch: boolean;
+    supportsFileIo: boolean;
+}
+export type ContentControlType = "plain_text" | "rich_text" | "checkbox" | "date" | "drop_down_list" | "combo_box" | "picture" | "repeating_section" | "repeating_section_item" | "unsupported";
+export type ContentControlPlacement = "inline" | "block" | "row" | "cell" | "unknown";
+export type ContentControlBindingPolicy = "preserve" | "detach_target";
+export interface ContentControlFillOptions {
+    bindingPolicy?: ContentControlBindingPolicy;
+}
+export interface ContentControlBindingInfo {
+    storeItemId?: string;
+    xpath?: string;
+    prefixMappings?: string;
+}
+export interface ContentControlInfo {
+    anchorId: string;
+    type: ContentControlType;
+    placement: ContentControlPlacement;
+    nativeId?: string;
+    tag?: string;
+    alias?: string;
+    lock?: string;
+    isShowingPlaceholder: boolean;
+    isBound: boolean;
+    binding?: ContentControlBindingInfo;
+    owningPartUri: string;
+    scope: string;
+    parentAnchorId?: string;
+    depth: number;
+    hasValidNativeId: boolean;
+    hasDuplicateNativeId: boolean;
+    canMutate: boolean;
+    canDetachTargetBinding: boolean;
+    unsupportedReason?: string;
+    text: string;
+    itemValues: string[];
+}
+export interface DocumentRange {
+    startAnchorId: string;
+    startOffset: number;
+    endAnchorId: string;
+    endOffset: number;
+}
+export interface BookmarkRangeSegment {
+    owningPartUri: string;
+    scope: string;
+    anchorId: string;
+    span: CharSpan;
+    text: string;
+}
+export interface BookmarkInfo {
+    name: string;
+    bookmarkId: string;
+    startPartUri: string;
+    startScope: string;
+    endPartUri?: string;
+    endScope?: string;
+    range?: DocumentRange;
+    segments: BookmarkRangeSegment[];
+    text: string;
+    isPaired: boolean;
+    isManaged: boolean;
+    isValid: boolean;
+    validationError?: string;
 }
 /**
  * One native Word comment, in comments-part order — see {@link DocxSession.listComments}.
@@ -951,23 +1646,40 @@ export interface CommentListEntry {
 }
 /** Revision kind in a markup-native revision listing. A `move` entry is a linked
  * move pair — both sides resolve together. */
-export type SessionRevisionType = "insert" | "delete" | "move" | "format";
+export type SessionRevisionType = "insert" | "delete" | "move" | "format" | "structure";
+export type RevisionFamily = "content_insert" | "content_delete" | "move" | "paragraph_mark" | "row_insert" | "row_delete" | "cell_insert" | "cell_delete" | "cell_merge" | "content_control_insert" | "content_control_delete" | "numbering_properties_insert" | "numbering_change" | "properties_change" | "unsupported";
+export type RevisionResolutionStatus = "supported" | "unsupported" | "malformed" | "ambiguous";
+export interface RevisionDiagnostic {
+    code: string;
+    message: string;
+}
 /**
- * One tracked revision read directly off the live markup, in document order — see
- * {@link DocxSession.listRevisions}. `id` is stable while the underlying markup exists
- * (derived from the markup's own `w:id` attributes — resolving OTHER revisions never
- * renames it) and is what acceptRevision/rejectRevision address. `author`/`date` are
- * the markup's true `w:author`/`w:date`. `text` is the revision's visible text (deleted
- * text for deletions, `¶` for a revised paragraph mark, the affected text for format
- * changes). `anchorId` is the containing block's anchor when addressable.
+ * One part-qualified atomic revision from the live registry. `id` is an opaque,
+ * deterministic `rev2-…` identity; `constituentIds` exposes the native Word ids.
+ * `family` identifies the exact operation, while `type` is its coarse display class.
+ * Unsafe native topology remains listed through `resolutionStatus` and `diagnostic`.
  */
 export interface RevisionListEntry {
     id: string;
     type: SessionRevisionType;
+    family: RevisionFamily;
+    constituentIds: string[];
+    /**
+     * QName-qualified native carrier identities. Unlike `constituentIds`, these
+     * distinguish revision roles which legally use the same numeric `w:id` value.
+     */
+    constituentKeys: string[];
     author: string;
     date?: string;
+    /** The `w16du:dateUtc` timestamp, when the markup carries one. */
+    dateUtc?: string;
     text: string;
+    partUri: string;
+    scope: string;
     anchorId?: string;
+    affectedAnchors: AnchorRef[];
+    resolutionStatus: RevisionResolutionStatus;
+    diagnostic?: RevisionDiagnostic;
 }
 export interface CharSpan {
     start: number;
@@ -1056,6 +1768,49 @@ export interface ParagraphFormatOp {
  * `"even"` (even pages; sets `w:evenAndOddHeaders`).
  */
 export type HeaderFooterKind = "default" | "first" | "even";
+/**
+ * Options for {@link DocxSession.insertTableOfContents} (issue #607). Every field is a typed switch
+ * on the underlying `TOC` field, so a caller never writes `\o "1-3"` by hand — a malformed switch
+ * string renders as nothing in Word, silently, which is the failure these exist to prevent.
+ */
+export interface TableOfContentsOptions {
+    /** Heading levels to list (`\o`): a level or a range within 1-9, e.g. `"1-3"`. Default `"1-3"`. */
+    levels?: string;
+    /** Make each entry a hyperlink to its heading (`\h`). Default true. */
+    hyperlinks?: boolean;
+    /** Hide the leader tab and page numbers in Word's web view (`\z`). Default true. */
+    hideTabAndPageNumbersInWeb?: boolean;
+    /** Include paragraphs with an outline level but no heading style (`\u`). Default true. */
+    useOutlineLevels?: boolean;
+    /** Heading above the table, in Word's `TOCHeading` style. `null` or `""` inserts no heading.
+     *  Default `"Contents"`. */
+    title?: string | null;
+    /** Right-aligned dot-leader tab stop in twips. Default 9350 (US Letter, one-inch margins). */
+    rightTabPos?: number;
+}
+/** Options for {@link DocxSession.insertTableOfFigures}. A table of figures is a `TOC` field
+ *  selecting by caption label rather than outline level — Word's own encoding. */
+export interface TableOfFiguresOptions {
+    /** The caption label whose captions to list (`\c`) — `"Figure"`, `"Table"`, `"Exhibit"`. */
+    captionLabel?: string;
+    /** Make each entry a hyperlink to its caption (`\h`). Default true. */
+    hyperlinks?: boolean;
+    /** Right-aligned dot-leader tab stop in twips. Default 9350. */
+    rightTabPos?: number;
+}
+/** Word's fixed table-of-authorities categories. */
+export type AuthorityCategory = "cases" | "statutes" | "other_authorities" | "rules" | "treatises" | "regulations" | "constitutional_provisions";
+/** Options for {@link DocxSession.insertTableOfAuthorities}. */
+export interface TableOfAuthoritiesOptions {
+    /** Which category of authority to list (`\c`). Default `"cases"`. */
+    category?: AuthorityCategory;
+    /** Make each entry a hyperlink to its citation (`\h`). Default true. */
+    hyperlinks?: boolean;
+    /** Separator between an entry and its page numbers (`\e`), e.g. a tab. Default: Word's own. */
+    entryPageSeparator?: string;
+    /** Right-aligned dot-leader tab stop in twips. Default 9350. */
+    rightTabPos?: number;
+}
 /** Which page-number field `DocxSession.insertPageNumberField` emits: `"currentPage"` → PAGE,
  * `"totalPages"` → NUMPAGES. */
 export type PageNumberField = "currentPage" | "totalPages";
@@ -1092,6 +1847,77 @@ export interface TableInsertOptions {
      *  wide-left / narrow-right filing-header row. */
     columnWidths?: number[];
 }
+export type TableVerticalMergeRole = "none" | "restart" | "continue";
+export type TableAnchorEntityKind = "table" | "row" | "column" | "cell";
+export interface TableCellMetadata {
+    anchor: AnchorRef;
+    tableAnchorId: string;
+    rowAnchorId: string;
+    rowIndex: number;
+    columnIndex: number;
+    rowSpan: number;
+    columnSpan: number;
+    verticalMerge: TableVerticalMergeRole;
+    /** Direct cell paragraphs only; nested-table paragraphs belong to their own cells. */
+    paragraphAnchors: AnchorRef[];
+}
+export interface TableRowMetadata {
+    anchor: AnchorRef;
+    tableAnchorId: string;
+    rowIndex: number;
+    gridBefore: number;
+    gridAfter: number;
+    cells: TableCellMetadata[];
+}
+export interface TableColumnMetadata {
+    anchor: AnchorRef;
+    tableAnchorId: string;
+    columnIndex: number;
+    widthTwips: number;
+    /** True when an absent/underspecified tblGrid required a read-only coordinate identity. */
+    isVirtual: boolean;
+    cellAnchorIds: string[];
+}
+export interface TableMetadata {
+    anchor: AnchorRef;
+    columns: TableColumnMetadata[];
+    rows: TableRowMetadata[];
+}
+export interface TableMetadataResult {
+    success: boolean;
+    error?: EditError;
+    metadata?: TableMetadata;
+}
+export interface TableCellResolutionResult {
+    success: boolean;
+    error?: EditError;
+    cell?: TableCellMetadata;
+}
+export interface TableAnchorLocation {
+    anchor: AnchorRef;
+    entityKind: TableAnchorEntityKind;
+    rowIndex?: number;
+    columnIndex?: number;
+    rowSpan?: number;
+    columnSpan?: number;
+    isVirtual?: boolean;
+}
+export interface TableAnchorMapping {
+    retained: {
+        before: TableAnchorLocation;
+        after: TableAnchorLocation;
+    }[];
+    added: TableAnchorLocation[];
+    invalidated: TableAnchorLocation[];
+}
+export type TableRowHeightRule = "auto" | "atLeast" | "exact";
+export interface TableRowOptions {
+    repeatHeader?: boolean;
+    allowBreakAcrossPages?: boolean;
+    /** Zero removes an explicit height. */
+    heightTwips?: number;
+    heightRule?: TableRowHeightRule;
+}
 /** Which table edges `DocxSession.setTableBorders` targets: `"outside"` = top/left/bottom/right,
  * `"inside"` = the inner grid lines (`w:insideH`/`w:insideV`), `"all"` = both. */
 export type TableBorderScope = "all" | "outside" | "inside";
@@ -1117,7 +1943,21 @@ export interface TableBorderSpec {
     color?: string;
 }
 export interface DocxSessionSettings {
+    /**
+     * Maximum undo steps retained. Default 20 (was 50).
+     *
+     * Each step is a full snapshot of every snapshot-scoped part, so this is a STEP count and not
+     * a memory bound — the cost of one step scales with the document. Use `undoMemoryBudgetBytes`
+     * to bound the heap.
+     */
     undoDepth?: number;
+    /**
+     * Approximate ceiling, in bytes, on memory held by undo/redo snapshots. Default 134217728
+     * (128 MiB). When exceeded the oldest history is discarded, so on a large document undo may
+     * not reach the full `undoDepth`; one step is always retained. Set to 0 to bound by depth
+     * alone (the pre-9.10 behavior).
+     */
+    undoMemoryBudgetBytes?: number;
     validateRawOps?: boolean;
     trackedChanges?: "accept" | "render_inline" | "strip_deletions";
     revisionAuthor?: string;
@@ -1145,8 +1985,10 @@ export interface DocxSessionSettings {
     emitMarkdownPatch?: boolean;
     /**
      * When `true` (default), the session projects the document at construction
-     * time so {@link DocxSession.getDiff} can compare initial vs. current.
-     * Set to `false` to skip the ~200ms upfront cost if you don't plan to diff.
+     * time so {@link DocxSession.getDiff} can compare initial vs. current, and
+     * retains the exact opening package for `getSemanticChanges()`.
+     * Set to `false` to skip the upfront projection plus package-copy cost if you
+     * do not plan to call either comparison API.
      */
     captureInitialProjection?: boolean;
 }
@@ -1179,6 +2021,56 @@ export interface DocxSessionProjection {
         scope: string;
         textPreview: string;
     }>;
+    /** Present only when projectAnchor requested citations. */
+    pageCitations?: Record<string, PageCitation>;
+}
+export interface PageCitationRequest {
+    documentVersion: number;
+    rendererFingerprint: string;
+}
+export type PageCitationUnavailableReason = "no_page_map" | "continuous_mode" | "stale_document_version" | "renderer_fingerprint_mismatch" | "anchor_not_mapped";
+export interface PageCitationFragment {
+    fragmentId: string;
+    anchorId: string;
+    fragmentIndex: number;
+    pageNumber: number;
+    geometry: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    story: "body" | "header" | "footer" | "footnote" | "endnote" | "comment";
+    inTableCell: boolean;
+}
+export interface PageCitationPage {
+    pageNumber: number;
+    pageInSection: number;
+    width: number;
+    height: number;
+    sectionIndex?: number;
+    pageName: string;
+}
+export interface PageCitation {
+    anchorId: string;
+    availability: "available" | "unavailable";
+    unavailableReason?: PageCitationUnavailableReason;
+    documentVersion: number;
+    rendererFingerprint: string;
+    pages: PageCitationPage[];
+    fragments: PageCitationFragment[];
+}
+export interface PageMapRegistrationResult {
+    success: boolean;
+    error?: "unsupported_schema_version" | "stale_document_version" | "renderer_fingerprint_mismatch" | "invalid_map";
+    message?: string;
+}
+export interface PageMapStatus {
+    availability: "available" | "unavailable";
+    unavailableReason?: PageCitationUnavailableReason;
+    documentVersion: number;
+    rendererFingerprint?: string;
+    mode?: "paginated" | "continuous";
 }
 /**
  * Per-fragment visible formatting reported by {@link DocxSession.grep}.
@@ -1219,6 +2111,8 @@ export interface TextMatch {
     contextAfter: string;
     /** Regex capture groups; index 0 is always the whole match. */
     groups: string[];
+    /** Present only when grep requested a citation for this exact render. */
+    citation?: PageCitation;
 }
 /**
  * One block's contribution to a {@link CrossBlockMatch}. The slice's `fragments`
@@ -1249,6 +2143,18 @@ export interface CrossBlockMatch {
     contextAfter: string;
     /** Regex capture groups; index 0 is always the whole match. */
     groups: string[];
+    /** One per enclosingAnchors entry when requested. */
+    citations?: PageCitation[];
+}
+/**
+ * Options for {@link DocxSession.insertCrossReference} — each flag is one of the REF
+ * field's switches: `\r` (reference the target's auto-number), `\h` (hyperlink),
+ * `\p` (relative position, cached as "above"/"below").
+ */
+export interface CrossReferenceOptions {
+    referenceNumber?: boolean;
+    hyperlink?: boolean;
+    includePosition?: boolean;
 }
 /**
  * Options for {@link DocxSession.replaceTextRange}.
@@ -1258,6 +2164,10 @@ export interface ReplaceOptions {
     ignoreCase?: boolean;
     /** Cap the number of replacements; omitted = unlimited. */
     maxReplacements?: number;
+    /** Require exactly this many occurrences before applying any replacement. */
+    expectedMatchCount?: number;
+    /** Optional document/anchor guards evaluated before searching. */
+    preconditions?: MutationPreconditions;
 }
 /**
  * Categories of bracketed placeholders {@link DocxSession.findPlaceholders} recognizes.
@@ -1431,6 +2341,8 @@ export interface GrepOptions {
      * `contextChars`.
      */
     boundary?: number;
+    /** Attach citations only if this exact registered layout is still valid. */
+    citation?: PageCitationRequest;
 }
 /**
  * Options that tune the `findBy*` helpers on {@link DocxSession}. Mirrors the
@@ -1456,6 +2368,8 @@ export interface FindOptions {
      * for whole-category filtering; this is for the rare single-part case.
      */
     scopeFilter?: string;
+    /** Attach citations only if this exact registered layout is still valid. */
+    citation?: PageCitationRequest;
 }
 /**
  * Resolved location of an anchor — what {@link DocxSession.findByAnnotation} and
@@ -1470,6 +2384,8 @@ export interface AnchorTargetRef extends AnchorRef {
     /** Resolved auto-numbering prefix (e.g. "1.", "First") when the element carries
      *  numbering. Absent otherwise. See {@link MarkdownAnchorTarget.autoNumberPrefix}. */
     autoNumberPrefix?: string;
+    /** Present only when the discovery call requested an exact page citation. */
+    citation?: PageCitation;
 }
 /**
  * The shape returned by {@link DocxSession.getAnchorInfo}.
@@ -1481,6 +2397,10 @@ export interface AnchorInfo {
     kind: string;
     scope: string;
     textPreview: string;
+    /** Exact live subtree hash suitable for expectedContentHash. */
+    contentHash: string;
+    /** Exact (untruncated) reader-visible text suitable for expectedText. */
+    visibleText: string;
     /** Resolved auto-numbering prefix (e.g. "1.", "First") when the element carries
      *  numbering. Absent for un-numbered paragraphs or non-paragraph kinds. */
     autoNumberPrefix?: string;
@@ -1492,6 +2412,8 @@ export type NumberFormat = "decimal" | "upperLetter" | "lowerLetter" | "upperRom
 /** Numbering facts for a list-item paragraph. Returned by
  *  {@link DocxSession.getListMembership} and surfaced as {@link BlockMetadata.list}. */
 export interface ListMembership {
+    /** Stable paragraph anchor accepted unchanged by every list mutation method. */
+    anchorId: string;
     /** The w:numId the paragraph belongs to (the w:num instance). */
     numId: number;
     /** The w:abstractNumId the paragraph's w:num points at. */
@@ -1506,6 +2428,14 @@ export interface ListMembership {
     fromStyle: boolean;
     /** Start-override from w:lvlOverride/w:startOverride for this level, if any. */
     startOverride?: number;
+    /** Level definition's w:start value (1 when omitted). */
+    start: number;
+    /** Marker template such as "%1." or "(%2)". */
+    levelText?: string;
+    leftIndentTwips?: number;
+    rightIndentTwips?: number;
+    firstLineIndentTwips?: number;
+    hangingIndentTwips?: number;
     /** Resolved label (e.g. "1.", "(a)") — same value surfaced via AnchorInfo.autoNumberPrefix. */
     generatedLabel?: string;
 }
@@ -1538,6 +2468,8 @@ export interface HeaderFooterRef {
 /** Page-layout snapshot for the w:sectPr that governs an anchor.
  *  Returned by {@link DocxSession.getSectionInfo}. */
 export interface SectionInfo {
+    /** Body anchor used for the lookup; accepted unchanged by section mutation methods. */
+    anchorId: string;
     sectionUnid: string;
     pageWidthTwips: number;
     pageHeightTwips: number;
@@ -1563,6 +2495,91 @@ export interface SectionInfo {
      *  "explicitly decimal" and avoid writing an attribute the document never had. */
     pageNumberFormat?: NumberFormat;
 }
+/** High-signal paragraph properties. Optional fields are deliberately absent when a
+ * direct formatting layer did not write them; effective layers include schema defaults. */
+export interface ParagraphFormatting {
+    styleId?: string;
+    alignment?: "left" | "center" | "right" | "justify";
+    leftIndentTwips?: number;
+    rightIndentTwips?: number;
+    firstLineIndentTwips?: number;
+    hangingIndentTwips?: number;
+    spacingBeforeTwips?: number;
+    spacingAfterTwips?: number;
+    lineSpacing?: number;
+    lineSpacingRule?: LineSpacingRule;
+    keepNext?: boolean;
+    keepLines?: boolean;
+    pageBreakBefore?: boolean;
+    outlineLevel?: number;
+    shadingFill?: string;
+    topBorder?: ParagraphBorderEdge;
+    bottomBorder?: ParagraphBorderEdge;
+}
+/** High-signal character properties. Nullable-at-source fields are optional on the wire so
+ * an absent direct property remains distinguishable from an explicit false/zero. */
+export interface RunFormattingInfo {
+    styleId?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    underlineStyle?: string;
+    strike?: boolean;
+    code?: boolean;
+    color?: string;
+    highlight?: string;
+    vertAlign?: string;
+    fontSizePts?: number;
+    fontFamily?: string;
+    caps?: boolean;
+    smallCaps?: boolean;
+    hidden?: boolean;
+}
+export interface TableStyleFormatting {
+    alignment?: string;
+    widthTwips?: number;
+    indentTwips?: number;
+    layout?: string;
+    hasBorders?: boolean;
+    cellShadingFill?: string;
+}
+/** One explicit document style. `id` is accepted unchanged by paragraph/run style mutations. */
+export interface StyleInfo {
+    id: string;
+    name: string;
+    type: "paragraph" | "character" | "table" | "numbering" | string;
+    basedOn?: string;
+    next?: string;
+    isDefault: boolean;
+    isCustom: boolean;
+    hasLatentException: boolean;
+    uiPriority?: number;
+    semiHidden?: boolean;
+    unhideWhenUsed?: boolean;
+    quickFormat?: boolean;
+    locked?: boolean;
+    resolvedParagraph?: ParagraphFormatting;
+    resolvedRun?: RunFormattingInfo;
+    resolvedTable?: TableStyleFormatting;
+}
+/** One text-bearing run. `anchorId` + `span` can be passed unchanged to applyFormat. */
+export interface InlineSpan {
+    anchorId: string;
+    runUnid: string;
+    span: CharSpan;
+    text: string;
+    direct: RunFormattingInfo;
+    effective: RunFormattingInfo;
+    /** Outer-to-inner native content controls containing this run. */
+    contentControlAnchorIds: string[];
+}
+/** Explicitly separated direct and effective formatting for one paragraph anchor. */
+export interface FormattingInspection {
+    anchorId: string;
+    directParagraph: ParagraphFormatting;
+    effectiveParagraph: ParagraphFormatting;
+    runs: InlineSpan[];
+}
 /**
  * A custom annotation persisted in the document via Docxodus' annotation system.
  * Returned by {@link DocxSession.listAnnotations}; mirrors the wire-relevant
@@ -1617,61 +2634,6 @@ export declare enum ComparisonLogLevel {
     /** Error that may affect comparison results but didn't stop processing */
     Error = "Error"
 }
-/**
- * A single log entry from the comparison process.
- */
-export interface ComparisonLogEntry {
-    /** Severity level: "Info", "Warning", or "Error" */
-    level: ComparisonLogLevel | string;
-    /**
-     * Machine-readable code identifying the type of issue.
-     * Examples: "ORPHANED_FOOTNOTE_REFERENCE", "MISSING_STYLE"
-     */
-    code: string;
-    /** Human-readable description of the issue */
-    message: string;
-    /** Additional context or technical details (optional) */
-    details?: string;
-    /**
-     * Location in the document where the issue occurred (optional).
-     * Format: "part/xpath" e.g., "document.xml/w:footnoteReference[@w:id='3']"
-     */
-    location?: string;
-}
-/**
- * Result from comparison operations that includes a log of warnings/errors.
- */
-export interface CompareResultWithLog {
-    /** Whether the comparison succeeded */
-    success: boolean;
-    /** The redlined document as a Uint8Array (only if success is true) */
-    document?: Uint8Array;
-    /** Error message if success is false */
-    error?: string;
-    /** Log entries from the comparison process */
-    log: ComparisonLogEntry[];
-    /** Whether the log contains any warnings */
-    hasWarnings: boolean;
-    /** Whether the log contains any errors */
-    hasErrors: boolean;
-}
-/**
- * Result from HTML comparison operations that includes a log of warnings/errors.
- */
-export interface CompareToHtmlResultWithLog {
-    /** Whether the comparison succeeded */
-    success: boolean;
-    /** The HTML output (only if success is true) */
-    html?: string;
-    /** Error message if success is false */
-    error?: string;
-    /** Log entries from the comparison process */
-    log: ComparisonLogEntry[];
-    /** Whether the log contains any warnings */
-    hasWarnings: boolean;
-    /** Whether the log contains any errors */
-    hasErrors: boolean;
-}
 /**
  * Well-known log entry codes used by the comparison engine.
  */
@@ -1693,34 +2655,6 @@ export declare const ComparisonLogCodes: {
     /** A bookmark reference has no corresponding bookmark start/end */
     readonly OrphanedBookmark: "ORPHANED_BOOKMARK";
 };
-/**
- * Options for revision extraction with move detection configuration.
- */
-export interface GetRevisionsOptions {
-    /**
-     * Whether to detect and mark moved content.
-     * When enabled, deletions and insertions with similar text are linked as move pairs.
-     * @default true
-     */
-    detectMoves?: boolean;
-    /**
-     * Jaccard similarity threshold for move detection (0.0 to 1.0).
-     * Higher values require more exact word overlap between deletion and insertion.
-     * @default 0.8
-     */
-    moveSimilarityThreshold?: number;
-    /**
-     * Minimum word count for content to be considered for move detection.
-     * Short phrases below this threshold are excluded to avoid false positives.
-     * @default 3
-     */
-    moveMinimumWordCount?: number;
-    /**
-     * Whether similarity matching ignores case differences.
-     * @default false
-     */
-    caseInsensitive?: boolean;
-}
 /**
  * A custom annotation on a document range.
  */
@@ -1833,6 +2767,8 @@ export declare enum DocumentElementType {
 export interface DocumentElement {
     /** Unique element ID (path-based, e.g., "doc/tbl-0/tr-1/tc-2") */
     id: string;
+    /** Canonical session anchor when this element is addressable. */
+    anchorId?: string;
     /** Element type */
     type: DocumentElementType | string;
     /** Preview of text content (first ~100 characters) */
@@ -1856,10 +2792,17 @@ export interface DocumentElement {
 export interface TableColumnInfo {
     /** ID of the table this column belongs to */
     tableId: string;
+    /** Canonical `col` anchor. */
+    anchorId: string;
+    /** Canonical owning `tbl` anchor. */
+    tableAnchorId: string;
+    isVirtual: boolean;
     /** Zero-based column index */
     columnIndex: number;
     /** IDs of all cells in this column */
     cellIds: string[];
+    /** Canonical `tc` anchors for cells covering this column. */
+    cellAnchorIds: string[];
     /** Total number of rows in this column */
     rowCount: number;
 }
@@ -2148,11 +3091,13 @@ export interface DocumentMetadata {
     hasComments: boolean;
     /** Estimated total page count (heuristic based on content volume and page sizes) */
     estimatedPageCount: number;
+    /** Explicit provenance: always "heuristic"; use PageMap for authoritative pages. */
+    estimatedPageCountSource: "heuristic";
 }
 /**
  * Message types sent from main thread to worker.
  */
-export type WorkerRequestType = "init" | "convertDocxToHtml" | "compareDocuments" | "compareDocumentsToHtml" | "getRevisions" | "getDocumentMetadata" | "getVersion" | "prepare" | "sessionOpen" | "sessionClose" | "sessionAddAnnotation" | "sessionRemoveAnnotation" | "sessionUpdateAnnotation" | "sessionMoveAnnotation";
+export type WorkerRequestType = "init" | "generatePackageManifest" | "verifyDeliverable" | "proveRedlineReversibility" | "projectReviewProfile" | "convertDocxToHtml" | "compareDocuments" | "compareDocumentsToHtml" | "getSemanticChanges" | "getRevisions" | "getDocumentMetadata" | "getVersion" | "prepare" | "sessionOpen" | "sessionGetPackageManifest" | "sessionGetSemanticChanges" | "sessionVerifyDeliverable" | "sessionClose" | "sessionAddAnnotation" | "sessionRemoveAnnotation" | "sessionUpdateAnnotation" | "sessionMoveAnnotation";
 /**
  * Base structure for worker requests.
  */
@@ -2175,10 +3120,48 @@ export interface WorkerInitRequest extends WorkerRequestBase {
  */
 export interface WorkerConvertRequest extends WorkerRequestBase {
     type: "convertDocxToHtml";
-    /** Document bytes (transferred, not copied) */
+    /** Private exact-view copy of the caller's document bytes, transferred to the worker. */
     documentBytes: Uint8Array;
     /** Conversion options */
     options?: ConversionOptions;
+    /** Optional main-thread admission ceiling for the UTF-8 response. */
+    maximumOutputBytes?: number;
+}
+/** Generate a deterministic package manifest without opening a live session. */
+export interface WorkerGeneratePackageManifestRequest extends WorkerRequestBase {
+    type: "generatePackageManifest";
+    documentBytes: Uint8Array;
+    /** When present, these lower ceilings constrain #493 inspection itself. */
+    limits?: PackageManifestInspectionLimits;
+    /**
+     * Which representation the caller needs. A manifest near the entry ceiling is multi-megabyte,
+     * so returning both costs a parse plus a structured clone nobody reads. Defaults to `"both"`.
+     */
+    representation?: "object" | "json" | "both";
+}
+/** Derive exact final/original package bytes before conversion. */
+export interface WorkerProjectReviewProfileRequest extends WorkerRequestBase {
+    type: "projectReviewProfile";
+    documentBytes: Uint8Array;
+    profile: "final" | "original";
+    /** Do not transfer a derived package larger than this many bytes. */
+    maximumOutputBytes?: number;
+}
+/** Run the default deliverable gate directly over exact supplied bytes. */
+export interface WorkerVerifyDeliverableRequest extends WorkerRequestBase {
+    type: "verifyDeliverable";
+    documentBytes: Uint8Array;
+    baselineBytes?: Uint8Array;
+}
+/**
+ * Prove redline accept/reject reversibility off the main thread. Three packages are inspected and
+ * two are rebuilt, so this is the heaviest verification request the worker serves.
+ */
+export interface WorkerProveRedlineReversibilityRequest extends WorkerRequestBase {
+    type: "proveRedlineReversibility";
+    baselineBytes: Uint8Array;
+    intendedFinalBytes: Uint8Array;
+    redlineBytes: Uint8Array;
 }
 /**
  * Compare two documents request.
@@ -2204,6 +3187,13 @@ export interface WorkerCompareToHtmlRequest extends WorkerRequestBase {
     /** Comparison options */
     options?: CompareOptions;
 }
+/** Compare two packages into the stable, versioned semantic-change schema. */
+export interface WorkerGetSemanticChangesRequest extends WorkerRequestBase {
+    type: "getSemanticChanges";
+    leftBytes: Uint8Array;
+    rightBytes: Uint8Array;
+    settings?: DocxDiffSettings;
+}
 /**
  * Get revisions from a document request.
  */
@@ -2211,8 +3201,6 @@ export interface WorkerGetRevisionsRequest extends WorkerRequestBase {
     type: "getRevisions";
     /** Document bytes */
     documentBytes: Uint8Array;
-    /** Revision extraction options */
-    options?: GetRevisionsOptions;
 }
 /**
  * Get document metadata for lazy loading request.
@@ -2240,11 +3228,26 @@ export interface WorkerPrepareRequest extends WorkerRequestBase {
  */
 export interface WorkerSessionOpenRequest extends WorkerRequestBase {
     type: "sessionOpen";
-    /** Document bytes transferred to the worker */
+    /** Private exact-view copy of the caller's document bytes, transferred to the worker. */
     documentBytes: Uint8Array;
     /** Session settings as JSON */
     settingsJson?: string;
 }
+/** Generate a manifest from the current logical checkpoint of a worker session. */
+export interface WorkerSessionGetPackageManifestRequest extends WorkerRequestBase {
+    type: "sessionGetPackageManifest";
+    handle: number;
+}
+/** Compare a worker session's current checkpoint with its opening package. */
+export interface WorkerSessionGetSemanticChangesRequest extends WorkerRequestBase {
+    type: "sessionGetSemanticChanges";
+    handle: number;
+}
+/** Run the default deliverable gate over a worker session's clean-save checkpoint. */
+export interface WorkerSessionVerifyDeliverableRequest extends WorkerRequestBase {
+    type: "sessionVerifyDeliverable";
+    handle: number;
+}
 /**
  * Close a worker DocxSession.
  */
@@ -2295,7 +3298,7 @@ export interface WorkerSessionMoveAnnotationRequest extends WorkerRequestBase {
 /**
  * Union type of all possible worker requests.
  */
-export type WorkerRequest = WorkerInitRequest | WorkerConvertRequest | WorkerCompareRequest | WorkerCompareToHtmlRequest | WorkerGetRevisionsRequest | WorkerGetDocumentMetadataRequest | WorkerGetVersionRequest | WorkerPrepareRequest | WorkerSessionOpenRequest | WorkerSessionCloseRequest | WorkerSessionAddAnnotationRequest | WorkerSessionRemoveAnnotationRequest | WorkerSessionUpdateAnnotationRequest | WorkerSessionMoveAnnotationRequest;
+export type WorkerRequest = WorkerInitRequest | WorkerGeneratePackageManifestRequest | WorkerVerifyDeliverableRequest | WorkerProveRedlineReversibilityRequest | WorkerProjectReviewProfileRequest | WorkerConvertRequest | WorkerCompareRequest | WorkerCompareToHtmlRequest | WorkerGetSemanticChangesRequest | WorkerGetRevisionsRequest | WorkerGetDocumentMetadataRequest | WorkerGetVersionRequest | WorkerPrepareRequest | WorkerSessionOpenRequest | WorkerSessionGetPackageManifestRequest | WorkerSessionGetSemanticChangesRequest | WorkerSessionVerifyDeliverableRequest | WorkerSessionCloseRequest | WorkerSessionAddAnnotationRequest | WorkerSessionRemoveAnnotationRequest | WorkerSessionUpdateAnnotationRequest | WorkerSessionMoveAnnotationRequest;
 /**
  * Base structure for worker responses.
  */
@@ -2306,7 +3309,14 @@ export interface WorkerResponseBase {
     success: boolean;
     /** Error message if success is false */
     error?: string;
+    /**
+     * Machine-readable cause when success is false. Callers classify failures from this
+     * rather than by matching `error`, whose wording is not a contract.
+     */
+    errorCode?: WorkerErrorCode;
 }
+/** Closed set of machine-readable worker failure causes. */
+export type WorkerErrorCode = "resource_limit";
 /**
  * Response from init request.
  */
@@ -2321,6 +3331,24 @@ export interface WorkerConvertResponse extends WorkerResponseBase {
     /** The converted HTML string */
     html?: string;
 }
+export interface WorkerGeneratePackageManifestResponse extends WorkerResponseBase {
+    type: "generatePackageManifest";
+    manifest?: PackageManifest;
+    /** Exact canonical JSON, retained for strict duplicate-property/schema validation. */
+    manifestJson?: string;
+}
+export interface WorkerProjectReviewProfileResponse extends WorkerResponseBase {
+    type: "projectReviewProfile";
+    documentBytes?: Uint8Array;
+}
+export interface WorkerVerifyDeliverableResponse extends WorkerResponseBase {
+    type: "verifyDeliverable";
+    verification?: DeliverableVerificationResult;
+}
+export interface WorkerProveRedlineReversibilityResponse extends WorkerResponseBase {
+    type: "proveRedlineReversibility";
+    proof?: RedlineReversibilityProof;
+}
 /**
  * Response from compareDocuments request.
  */
@@ -2337,13 +3365,18 @@ export interface WorkerCompareToHtmlResponse extends WorkerResponseBase {
     /** The HTML string with redlines */
     html?: string;
 }
+/** Response containing the public semantic-change schema. */
+export interface WorkerGetSemanticChangesResponse extends WorkerResponseBase {
+    type: "getSemanticChanges";
+    semanticChanges?: SemanticChangeSet;
+}
 /**
  * Response from getRevisions request.
  */
 export interface WorkerGetRevisionsResponse extends WorkerResponseBase {
     type: "getRevisions";
     /** Array of revisions */
-    revisions?: Revision[];
+    revisions?: RevisionListEntry[];
 }
 /**
  * Response from getDocumentMetadata request.
@@ -2375,6 +3408,20 @@ export interface WorkerSessionOpenResponse extends WorkerResponseBase {
     /** Integer handle identifying the session in the worker */
     handle?: number;
 }
+/** Response containing the current worker-session package manifest. */
+export interface WorkerSessionGetPackageManifestResponse extends WorkerResponseBase {
+    type: "sessionGetPackageManifest";
+    manifest?: PackageManifest;
+}
+/** Response containing a session's public semantic-change schema. */
+export interface WorkerSessionGetSemanticChangesResponse extends WorkerResponseBase {
+    type: "sessionGetSemanticChanges";
+    semanticChanges?: SemanticChangeSet;
+}
+export interface WorkerSessionVerifyDeliverableResponse extends WorkerResponseBase {
+    type: "sessionVerifyDeliverable";
+    verification?: DeliverableVerificationResult;
+}
 /**
  * Response from sessionClose request.
  */
@@ -2393,7 +3440,7 @@ export interface WorkerSessionEditResponse extends WorkerResponseBase {
 /**
  * Union type of all possible worker responses.
  */
-export type WorkerResponse = WorkerInitResponse | WorkerConvertResponse | WorkerCompareResponse | WorkerCompareToHtmlResponse | WorkerGetRevisionsResponse | WorkerGetDocumentMetadataResponse | WorkerGetVersionResponse | WorkerPrepareResponse | WorkerSessionOpenResponse | WorkerSessionCloseResponse | WorkerSessionEditResponse;
+export type WorkerResponse = WorkerInitResponse | WorkerGeneratePackageManifestResponse | WorkerVerifyDeliverableResponse | WorkerProveRedlineReversibilityResponse | WorkerProjectReviewProfileResponse | WorkerConvertResponse | WorkerCompareResponse | WorkerCompareToHtmlResponse | WorkerGetSemanticChangesResponse | WorkerGetRevisionsResponse | WorkerGetDocumentMetadataResponse | WorkerGetVersionResponse | WorkerPrepareResponse | WorkerSessionOpenResponse | WorkerSessionGetPackageManifestResponse | WorkerSessionGetSemanticChangesResponse | WorkerSessionVerifyDeliverableResponse | WorkerSessionCloseResponse | WorkerSessionEditResponse;
 /**
  * Options for creating a worker-based Docxodus instance.
  */
@@ -2403,6 +3450,8 @@ export interface WorkerDocxodusOptions {
      * Defaults to auto-detection from module URL.
      */
     wasmBasePath?: string;
+    /** Abort the owned worker, including an initialization that has not completed. */
+    signal?: AbortSignal;
 }
 /**
  * OpenContracts document export format.