docxodus 12.4.0 → 12.5.0

package/dist/types.d.ts

@@ -886,6 +886,50 @@ export interface DeliveryArtifactVerification {
  * Portable delivery change receipt verification verdict — the shared facade wire
  * shape every transport returns (issue #520).
  */
+/** What the session's host-owned delivery evidence recorder holds (issue #748). */
+export interface DeliveryEvidenceStatus {
+    enabled: boolean;
+    transactionCount: number;
+    lineageEventCount: number;
+    /** Version steps applied by direct calls: exact packages, unknown request. */
+    unlabeledTransactionCount: number;
+    retainedStateCount: number;
+    retainedBytes: number;
+    sourceVersion: number;
+    currentVersion: number;
+    /** Null when a complete receipt can be minted; otherwise the first reason it cannot. */
+    unavailableReason: string | null;
+}
+export type DeliveryReceiptPrivacyProfile = "hashOnly" | "hashAndSummary" | "fullEvidence";
+export interface DeliveryReceiptBuildOptions {
+    privacyProfile?: DeliveryReceiptPrivacyProfile;
+    failOnUnexpectedChanges?: boolean;
+}
+export interface DeliveryBundleArtifact {
+    artifactId: string;
+    kind: string;
+    requiredness: "required" | "optional";
+    availability: "available" | "unavailable";
+    relativePath: string;
+    mediaType: string;
+    /** Present when available. */
+    bytes?: Uint8Array;
+    /** Present when unavailable. */
+    unavailableReason?: string;
+}
+/**
+ * A delivery bundle as every transport publishes it: the verified manifest, its canonical bytes,
+ * and each artifact with its bytes or the reason it is unavailable. `evidence` is the session's
+ * recorder status at delivery time.
+ */
+export interface DeliveryBundleResult {
+    status: "complete" | "incomplete" | "failed";
+    verified: boolean;
+    manifest: Record<string, unknown>;
+    manifestBytes: Uint8Array;
+    artifacts: readonly DeliveryBundleArtifact[];
+    evidence?: DeliveryEvidenceStatus;
+}
 export interface DeliveryReceiptVerificationResult {
     isValid: boolean;
     receiptDigestValid: boolean;
@@ -894,6 +938,85 @@ export interface DeliveryReceiptVerificationResult {
     artifacts: DeliveryArtifactVerification[];
     findings: string[];
 }
+/** One approved package-level delta the deliverable is expected to show (issue #747). */
+export interface DeliverablePackageChangeExpectation {
+    kind: DeliverablePackageChangeKind;
+    location: ChangeLocation;
+    beforeDigest?: VerificationDigest;
+    afterDigest?: VerificationDigest;
+    beforeValue?: string;
+    afterValue?: string;
+}
+export type DeliverableRenderDiagnosticKind = "warning" | "unsupportedContent" | "missingFont" | "fontSubstitution";
+/** One render warning or limitation reported by the companion renderer. */
+export interface DeliverableRenderDiagnostic {
+    kind: DeliverableRenderDiagnosticKind;
+    message: string;
+    severity?: VerificationFindingSeverity;
+    code?: string;
+    phase?: string;
+}
+/** Bytes and renderer/document binding for one companion artifact submitted for verification. */
+export interface DeliverableCompanionArtifactInput {
+    artifactId: string;
+    role: DeliverableArtifactRole;
+    mediaType: string;
+    /** Defaults to `available`. */
+    availability?: DeliverableArtifactAvailability;
+    bytes?: Uint8Array;
+    unavailableReason?: string;
+    pageCount?: number;
+    rendererFingerprint?: string;
+    /** Digest of the exact package the renderer consumed; a mismatch is a stale artifact. */
+    sourcePackageDigest?: VerificationDigest;
+    pageMapDigest?: VerificationDigest;
+    renderDiagnostics?: readonly DeliverableRenderDiagnostic[];
+}
+/**
+ * Policy and inspection limits for verification (issue #747). Every field is optional; an
+ * omitted field takes the verifier's own default. Unknown fields are rejected.
+ */
+export interface DeliverableVerificationPolicyOptions {
+    mode?: DeliverableVerificationMode;
+    openXmlVersion?: string;
+    failOnUnexpectedChanges?: boolean;
+    requireNoPlaceholders?: boolean;
+    detectBracketedAlternativeClauses?: boolean;
+    editorialMarkers?: readonly string[];
+    placeholderTokens?: readonly string[];
+    maxPackageBytes?: number;
+    maxFindings?: number;
+    maxDetectorNodes?: number;
+    maxDetectorRelationships?: number;
+    maxDetectorTextCharacters?: number;
+    maxDetectorRegexMatches?: number;
+    maxDetectorSteps?: number;
+    maxCompanionArtifactBytes?: number;
+    maxTotalCompanionArtifactBytes?: number;
+    maxCompanionArtifacts?: number;
+    maxRenderDiagnostics?: number;
+    maxExpectedChanges?: number;
+    maxReportedDeltaChanges?: number;
+    packageManifest?: {
+        maxEntryCount?: number;
+        maxEntryUncompressedBytes?: number;
+        maxTotalUncompressedBytes?: number;
+        maxXmlPartBytes?: number;
+        maxCompressionRatio?: number;
+        maxUriLength?: number;
+    };
+}
+/**
+ * The full bounded verification request (issue #747): what the typed .NET request adds to the
+ * package bytes. Package bytes are passed alongside, never inside, this object.
+ */
+export interface DeliverableVerificationRequest {
+    options?: DeliverableVerificationPolicyOptions;
+    /** The canonical semantic-changes object (as `getSemanticChanges` returns it). */
+    expectedSemanticChanges?: SemanticChangeSet;
+    expectedPackageChanges?: readonly DeliverablePackageChangeExpectation[];
+    companionArtifacts?: readonly DeliverableCompanionArtifactInput[];
+}
 export interface DeliverableVerificationResult {
     schema: "https://docxodus.dev/schemas/verification/deliverable-verification/v1";
     schemaVersion: 1;
@@ -1054,6 +1177,8 @@ export interface DocxodusWasmExports {
     DocumentConverter: {
         GeneratePackageManifest: (bytes: Uint8Array) => string;
         VerifyDeliverable: (bytes: Uint8Array) => string;
+        VerifyDeliverableWithRequest?: (bytes: Uint8Array, requestJson: string) => string;
+        VerifyDeliverableWithBaselineAndRequest?: (baselineBytes: Uint8Array, bytes: Uint8Array, requestJson: string) => string;
         VerifyDeliveryReceipt: (receiptJson: string, artifactsJson: string) => string;
         VerifyDeliverableWithBaseline: (baselineBytes: Uint8Array, bytes: Uint8Array) => string;
         ProveRedlineReversibility: (baselineBytes: Uint8Array, intendedFinalBytes: Uint8Array, redlineBytes: Uint8Array) => string;
@@ -1140,6 +1265,16 @@ export interface DocxodusWasmExports {
         GetPageMapStatus: (handle: number, requestJson: string) => string;
         GetPageCitation: (handle: number, anchorId: string, requestJson: string) => string;
         GetPackageContentHash?: (handle: number) => string;
+        BeginMutationTransaction?: (handle: number, transactionId: string, requestJson: string) => string;
+        CompleteMutationTransaction?: (handle: number, transactionId: string, serializedResponse: string) => void;
+        AbandonMutationTransaction?: (handle: number, transactionId: string) => void;
+        RetainPreview?: (shadowHandle: number) => string;
+        CommitPreview?: (handle: number, previewId: string) => string;
+        GetDeliveryEvidenceStatus?: (handle: number) => string;
+        BuildDeliveryReceipt?: (handle: number, optionsJson: string) => string;
+        BeginDeliveryEvidence?: (handle: number, operationsJson: string, mode: string, identityJson: string) => boolean;
+        CompleteDeliveryEvidence?: (handle: number, stepsJson: string) => void;
+        AbandonDeliveryEvidence?: (handle: number) => void;
         GetPackageManifest: (handle: number) => string;
         RenderPreviewHtml?: (handle: number) => string;
         RenderPreviewBlockHtml?: (handle: number, anchorId: string) => string;
@@ -1183,6 +1318,8 @@ export interface DocxodusWasmExports {
         /** Batch block render with the editor profile — `RenderBlocksHtml` plus comment markup;
          *  same JSON-object result (`{ [anchorId]: html | null }`, or `{"error": …}`). */
         RenderEditorBlocksHtml?: (handle: number, anchorIdsJson: string, optionsJson: string) => string;
+        RenderEditorChromeHtml?: (handle: number, optionsJson: string) => string;
+        RenderEditorRangeHtml?: (handle: number, anchorIdsJson: string, optionsJson: string) => string;
         /** Single-block render with the editor profile — `RenderBlockHtml` plus comment markup. */
         RenderEditorBlockHtml?: (handle: number, anchorId: string, optionsJson: string) => string;
         ReplaceText: (handle: number, anchor: string, md: string) => string;
@@ -1249,6 +1386,7 @@ export interface DocxodusWasmExports {
         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;
+        EmbedLinkedImage: (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;
@@ -1268,6 +1406,8 @@ export interface DocxodusWasmExports {
         MoveBookmark: (handle: number, name: string, startAnchor: string, startOffset: number, endAnchor: string, endOffset: number) => string;
         RemoveBookmark: (handle: number, name: string) => string;
         ListRevisions: (handle: number) => string;
+        ListRevisionRepairs?: (handle: number) => string;
+        RepairRevisions?: (handle: number, repairsJson: string) => string;
         AcceptRevision: (handle: number, revisionId: string) => string;
         RejectRevision: (handle: number, revisionId: string) => string;
         AcceptAllRevisions: (handle: number) => string;
@@ -1298,6 +1438,7 @@ export interface DocxodusWasmExports {
         GetDiff: (handle: number, format: number) => string;
         GetSemanticChanges: (handle: number) => string;
         VerifyDeliverable: (handle: number) => string;
+        VerifyDeliverableWithRequest?: (handle: number, requestJson: string) => string;
         FindByAnnotation: (handle: number, annotationId: string) => string;
         FindByAnnotationWithCitations: (handle: number, annotationId: string, requestJson: string) => string;
         FindByLabel: (handle: number, labelId: string) => string;
@@ -1336,7 +1477,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" | "text_not_found" | "unknown_style" | "invalid_list_level" | "invalid_list_start_value" | "invalid_page_numbering" | "invalid_page_setup" | "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 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_page_setup" | "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" | "preview_not_found" | "preview_stale" | "revision_repair_rejected" | "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;
@@ -1389,6 +1530,11 @@ export interface MutationBatchStep {
     mutation: () => EditResult | readonly EditResult[];
     /** Optional read-only validation: all run up front in atomic mode, per-step in best-effort. */
     preflight?: () => EditError | undefined;
+    /**
+     * The step's request arguments, recorded as the normalized request in delivery evidence
+     * (issue #748) when the session captures it. The callback hides them, so name them here.
+     */
+    args?: Record<string, unknown>;
 }
 /** A preview callback receives the isolated shadow session it must mutate/read. */
 export interface MutationBatchPreviewStep {
@@ -1401,6 +1547,24 @@ export interface MutationBatchPreviewOptions {
     html?: "none" | "scoped" | "full";
     /** Required for scoped HTML. */
     htmlAnchorId?: string;
+    /**
+     * Keep a successful preview's exact result package so {@link DocxSession.commitPreview} can
+     * later make it the live document with the previewed generated ids, timestamps and
+     * `packageHash`. The receipt then carries {@link MutationBatchResult.retention}. Retention
+     * is bounded (count, bytes and time) and cleared when the session closes.
+     */
+    retain?: boolean;
+}
+/**
+ * Identity of a preview retained for a guarded commit (issue #760). `baseVersion` and
+ * `basePackageHash` describe the live state the preview was predicted from; the commit refuses
+ * once either has moved. `expiresAt` is the ISO-8601 UTC instant after which the entry is gone.
+ */
+export interface MutationPreviewRetention {
+    previewId: string;
+    baseVersion: number;
+    basePackageHash: string;
+    expiresAt: string;
 }
 export interface MutationBatchStepResult {
     index: number;
@@ -1446,6 +1610,36 @@ export interface MutationBatchResult {
     warnings: readonly string[];
     /** Shadow-only preview HTML when requested; null otherwise. */
     html: string | null;
+    /**
+     * Present only for a batch executed under a {@link MutationTransaction}: the identity the
+     * session's journal bound the request to — the same on the original call and on a replay.
+     */
+    transaction?: MutationTransactionIdentity;
+    /**
+     * Present on a preview retained with {@link MutationBatchPreviewOptions.retain} and on the
+     * result of {@link DocxSession.commitPreview}.
+     */
+    retention?: MutationPreviewRetention;
+}
+/** The versioned identity a transaction-aware batch result carries (issue #761). */
+export interface MutationTransactionIdentity {
+    schemaVersion: number;
+    transactionId: string;
+    /** SHA-256 over the canonical rendering of {@link MutationTransaction.request} plus the mode. */
+    requestFingerprint: string;
+}
+/**
+ * Retry deduplication for {@link DocxSession.executeBatch}. The session's journal replays the
+ * original result for an identical retry under the same `transactionId` without executing the
+ * steps again, and refuses the id for a different request with `transaction_conflict`. Because
+ * the batch is composed from callbacks, `request` is the caller's own serializable description
+ * of what the batch does and is what the fingerprint covers: pass the same descriptor on a retry.
+ */
+export interface MutationTransaction {
+    /** Non-blank, at most 256 Unicode scalar values; scoped to this open session. */
+    transactionId: string;
+    /** A JSON object describing the batch (step kinds, targets, payloads). */
+    request: Record<string, unknown>;
 }
 export interface MarkdownPatch {
     scopeAnchorId: string;
@@ -1490,6 +1684,20 @@ export type ImageHorizontalReference = "page" | "margin" | "column" | "character
 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";
+/** One vertex of a tight/through wrap outline in DrawingML's 21600-unit picture space. */
+export interface ImageWrapPoint {
+    x: number;
+    y: number;
+}
+/**
+ * The outline text follows under tight/through wrap: a start vertex plus at least two line
+ * segments. Omit it on write to get the picture rectangle; a layout read from the document
+ * always carries the outline it holds.
+ */
+export interface ImageWrapPolygon {
+    points: ImageWrapPoint[];
+    edited?: boolean;
+}
 export interface FloatingImageLayout {
     horizontalRelativeFrom?: ImageHorizontalReference;
     horizontalOffsetEmu?: number | null;
@@ -1499,6 +1707,7 @@ export interface FloatingImageLayout {
     verticalAlignment?: ImageVerticalAlignment | null;
     wrapMode?: ImageWrapMode;
     wrapSide?: ImageWrapSide;
+    wrapPolygon?: ImageWrapPolygon | null;
     distanceTopEmu?: number;
     distanceBottomEmu?: number;
     distanceLeftEmu?: number;
@@ -1532,6 +1741,12 @@ export interface ImageDimensions {
     heightPoints?: number;
     preserveAspect?: boolean;
 }
+/** Whether one image operation applies to one occurrence in the session's current mode. */
+export interface ImageOperationSupport {
+    operation: string;
+    canMutate: boolean;
+    reason?: string;
+}
 export interface ImageOccurrence {
     id: string;
     markupKind: ImageMarkupKind;
@@ -1561,6 +1776,14 @@ export interface ImageOccurrence {
     title?: string;
     floatingLayout?: FloatingImageLayout;
     floatingLayoutSupported: boolean;
+    /** replace, embed_linked, set_dimensions, set_metadata, set_floating_layout and remove, each answered. */
+    operations: ImageOperationSupport[];
+}
+/** Which operations one markup family accepts, independent of any occurrence. */
+export interface ImageMarkupCapability {
+    markup: string;
+    operations: string[];
+    limitation?: string;
 }
 export interface ImageFormatCapability {
     format: ImageBinaryFormat;
@@ -1585,12 +1808,36 @@ export interface ImageCapabilities {
     acceptsBinaryBytes: boolean;
     supportsNetworkFetch: boolean;
     supportsFileIo: boolean;
+    markups: ImageMarkupCapability[];
+    trackedOperations: string[];
 }
 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";
+/** How a whole-control fill treats nested controls inside its target (issue #763). */
+export type ContentControlNestedPolicy = "refuse" | "preserve" | "replace";
 export interface ContentControlFillOptions {
     bindingPolicy?: ContentControlBindingPolicy;
+    /**
+     * Default `refuse`. `preserve` keeps every nested control in place and replaces only the
+     * content outside them; `replace` discards the whole payload, nested controls included
+     * (each is reported removed; a locked or data-bound nested control refuses).
+     */
+    nestedControls?: ContentControlNestedPolicy;
+    /**
+     * With `preserve`: plain-text fills for nested text/rich-text controls of the target, keyed
+     * by their `sdt` anchor, applied in the same operation. A key that is not a nested textual
+     * control, or a child that fails its own gates, fails the whole call without mutating.
+     */
+    childFills?: Record<string, string>;
+}
+/** Whether one operation would succeed on a control right now, by the gates the operation applies. */
+export interface ContentControlOperationSupport {
+    operation: "fill_text" | "fill_rich_text" | "set_checked" | "set_date" | "select_item" | "fill_picture" | "add_repeating_item" | "remove_repeating_item";
+    /** The nested policy this entry describes, when the target contains nested controls. */
+    nestedControls?: ContentControlNestedPolicy;
+    canMutate: boolean;
+    reason?: string;
 }
 export interface ContentControlBindingInfo {
     storeItemId?: string;
@@ -1619,6 +1866,13 @@ export interface ContentControlInfo {
     unsupportedReason?: string;
     text: string;
     itemValues: string[];
+    /** Anchors of the controls nested anywhere inside this control's payload, in story order. */
+    nestedControlAnchorIds: string[];
+    /**
+     * Per-operation support for this control's family, including nested-policy variants of a
+     * fill when the target contains nested controls and the session's tracked-change mode.
+     */
+    operations: ContentControlOperationSupport[];
 }
 export interface DocumentRange {
     startAnchorId: string;
@@ -1675,6 +1929,47 @@ export interface CommentListEntry {
 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";
+/** The explicit repairs the revision registry can perform on markup it refuses to resolve. */
+export type RevisionRepairKind = "assign_identity" | "reattach_numbering_change" | "reattach_cell_marker" | "restore_orphan_text" | "wrap_orphan_text_as_deletion";
+/** One repair the registry offers for one listed entry, and whether it can perform it. */
+export interface RevisionRepairProposal {
+    revisionId: string;
+    kind: RevisionRepairKind;
+    partUri: string;
+    diagnostic: RevisionDiagnostic;
+    /** Every native carrier the repair touches, as QName@element-path keys. */
+    carriers: readonly string[];
+    repairable: boolean;
+    /** What the repair does, or why the package's evidence does not permit it. */
+    reason: string;
+    /** The request must supply `author` and `date`. */
+    requiresAuthorship: boolean;
+}
+export interface RevisionRepairRequest {
+    revisionId: string;
+    kind: RevisionRepairKind;
+    author?: string;
+    date?: string;
+}
+/** One carrier's identity before and after a repair; `newId` is empty when it was moved, not renumbered. */
+export interface RevisionCarrierIdentity {
+    carrier: string;
+    oldId: string | null;
+    newId: string;
+}
+export interface RevisionRepairOutcome {
+    revisionId: string;
+    kind: RevisionRepairKind;
+    partUri: string;
+    identities: readonly RevisionCarrierIdentity[];
+}
+/** Atomic, one undo step; repaired entries get new ids, so re-list afterwards. */
+export interface RevisionRepairResult {
+    success: boolean;
+    error?: EditError;
+    repairs: readonly RevisionRepairOutcome[];
+    modified: readonly AnchorRef[];
+}
 export interface RevisionDiagnostic {
     code: string;
     message: string;
@@ -2088,12 +2383,28 @@ export interface DocxSessionSettings {
      * do not plan to call either comparison API.
      */
     captureInitialProjection?: boolean;
+    /**
+     * Record the evidence a delivery change receipt needs as edits execute (issue #748): the
+     * exact package before and after every version step, each batch's described request,
+     * transaction ids, and undo/redo lineage. {@link DocxSession.buildDeliveryReceipt} then mints
+     * a verifiable receipt. Default false: every version step serializes a clean package copy
+     * and retention holds them (bounded: 256 states / 512 MiB) until delivery. Requires
+     * `captureInitialProjection`.
+     */
+    captureDeliveryEvidence?: boolean;
 }
 /** One top-level render unit in a {@link RenderPlan}: a body block (`p`/`h`/`li`),
  *  one whole table (`tbl`), or one footnote/endnote definition (`fn`/`en`). */
 export interface RenderUnit {
     id: string;
     kind: string;
+    /** Content signature for change detection (leaf blocks omit it). */
+    sig?: string;
+    /** Index of the section wrapper (`[data-section-index]`) the unit renders into. */
+    section?: number;
+    /** Ordinal of the border box the renderer groups adjacent bordered paragraphs into; units
+     *  sharing a group render inside one wrapper, so a windowed mount never splits one. */
+    group?: number;
 }
 /** Ordered top-level render units per scope container — the authority for "what
  *  blocks exist, in what order" that the incremental reconciler diffs against. */
@@ -3208,7 +3519,7 @@ export interface DocumentMetadata {
 /**
  * Message types sent from main thread to worker.
  */
-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";
+export type WorkerRequestType = "init" | "generatePackageManifest" | "verifyDeliverable" | "proveRedlineReversibility" | "projectReviewProfile" | "convertDocxToHtml" | "compareDocuments" | "compareDocumentsToHtml" | "getSemanticChanges" | "createExternalAnnotationSet" | "validateExternalAnnotations" | "projectAnnotationsOntoHtml" | "convertDocxToHtmlWithExternalAnnotations" | "exportToOpenContract" | "getRevisions" | "getDocumentMetadata" | "getVersion" | "prepare" | "sessionOpen" | "sessionGetPackageManifest" | "sessionGetSemanticChanges" | "sessionVerifyDeliverable" | "sessionClose" | "sessionAddAnnotation" | "sessionRemoveAnnotation" | "sessionUpdateAnnotation" | "sessionMoveAnnotation";
 /**
  * Base structure for worker requests.
  */
@@ -3263,6 +3574,8 @@ export interface WorkerVerifyDeliverableRequest extends WorkerRequestBase {
     type: "verifyDeliverable";
     documentBytes: Uint8Array;
     baselineBytes?: Uint8Array;
+    /** The serialized full request (issue #747); absent means the default policy. */
+    requestJson?: string;
 }
 /**
  * Prove redline accept/reject reversibility off the main thread. Three packages are inspected and
@@ -3305,6 +3618,38 @@ export interface WorkerGetSemanticChangesRequest extends WorkerRequestBase {
     rightBytes: Uint8Array;
     settings?: DocxDiffSettings;
 }
+/** Create an empty external annotation set bound to a document's hash (issue #775). */
+export interface WorkerCreateExternalAnnotationSetRequest extends WorkerRequestBase {
+    type: "createExternalAnnotationSet";
+    documentBytes: Uint8Array;
+    documentId: string;
+}
+/** Validate an external annotation set against a document. */
+export interface WorkerValidateExternalAnnotationsRequest extends WorkerRequestBase {
+    type: "validateExternalAnnotations";
+    documentBytes: Uint8Array;
+    annotationSet: ExternalAnnotationSet;
+}
+/** Project an annotation set onto already-rendered (XML-well-formed) HTML. */
+export interface WorkerProjectAnnotationsOntoHtmlRequest extends WorkerRequestBase {
+    type: "projectAnnotationsOntoHtml";
+    html: string;
+    annotationSet: ExternalAnnotationSet;
+    projectionOptions?: ExternalAnnotationProjectionSettings;
+}
+/** Convert a document and project an annotation set onto it in one round trip. */
+export interface WorkerConvertWithExternalAnnotationsRequest extends WorkerRequestBase {
+    type: "convertDocxToHtmlWithExternalAnnotations";
+    documentBytes: Uint8Array;
+    annotationSet: ExternalAnnotationSet;
+    conversionOptions?: ConversionOptions;
+    projectionOptions?: ExternalAnnotationProjectionSettings;
+}
+/** Export a document to the OpenContracts format. */
+export interface WorkerExportToOpenContractRequest extends WorkerRequestBase {
+    type: "exportToOpenContract";
+    documentBytes: Uint8Array;
+}
 /**
  * Get revisions from a document request.
  */
@@ -3358,6 +3703,8 @@ export interface WorkerSessionGetSemanticChangesRequest extends WorkerRequestBas
 export interface WorkerSessionVerifyDeliverableRequest extends WorkerRequestBase {
     type: "sessionVerifyDeliverable";
     handle: number;
+    /** The serialized full request (issue #747); absent means the default policy. */
+    requestJson?: string;
 }
 /**
  * Close a worker DocxSession.
@@ -3409,7 +3756,7 @@ export interface WorkerSessionMoveAnnotationRequest extends WorkerRequestBase {
 /**
  * Union type of all possible worker requests.
  */
-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;
+export type WorkerRequest = WorkerInitRequest | WorkerGeneratePackageManifestRequest | WorkerVerifyDeliverableRequest | WorkerProveRedlineReversibilityRequest | WorkerProjectReviewProfileRequest | WorkerConvertRequest | WorkerCompareRequest | WorkerCompareToHtmlRequest | WorkerGetSemanticChangesRequest | WorkerCreateExternalAnnotationSetRequest | WorkerValidateExternalAnnotationsRequest | WorkerProjectAnnotationsOntoHtmlRequest | WorkerConvertWithExternalAnnotationsRequest | WorkerExportToOpenContractRequest | WorkerGetRevisionsRequest | WorkerGetDocumentMetadataRequest | WorkerGetVersionRequest | WorkerPrepareRequest | WorkerSessionOpenRequest | WorkerSessionGetPackageManifestRequest | WorkerSessionGetSemanticChangesRequest | WorkerSessionVerifyDeliverableRequest | WorkerSessionCloseRequest | WorkerSessionAddAnnotationRequest | WorkerSessionRemoveAnnotationRequest | WorkerSessionUpdateAnnotationRequest | WorkerSessionMoveAnnotationRequest;
 /**
  * Base structure for worker responses.
  */
@@ -3481,6 +3828,26 @@ export interface WorkerGetSemanticChangesResponse extends WorkerResponseBase {
     type: "getSemanticChanges";
     semanticChanges?: SemanticChangeSet;
 }
+export interface WorkerCreateExternalAnnotationSetResponse extends WorkerResponseBase {
+    type: "createExternalAnnotationSet";
+    annotationSet?: ExternalAnnotationSet;
+}
+export interface WorkerValidateExternalAnnotationsResponse extends WorkerResponseBase {
+    type: "validateExternalAnnotations";
+    validation?: ExternalAnnotationValidationResult;
+}
+export interface WorkerProjectAnnotationsOntoHtmlResponse extends WorkerResponseBase {
+    type: "projectAnnotationsOntoHtml";
+    html?: string;
+}
+export interface WorkerConvertWithExternalAnnotationsResponse extends WorkerResponseBase {
+    type: "convertDocxToHtmlWithExternalAnnotations";
+    html?: string;
+}
+export interface WorkerExportToOpenContractResponse extends WorkerResponseBase {
+    type: "exportToOpenContract";
+    export?: OpenContractDocExport;
+}
 /**
  * Response from getRevisions request.
  */
@@ -3551,7 +3918,7 @@ export interface WorkerSessionEditResponse extends WorkerResponseBase {
 /**
  * Union type of all possible worker responses.
  */
-export type WorkerResponse = WorkerInitResponse | WorkerGeneratePackageManifestResponse | WorkerVerifyDeliverableResponse | WorkerProveRedlineReversibilityResponse | WorkerProjectReviewProfileResponse | WorkerConvertResponse | WorkerCompareResponse | WorkerCompareToHtmlResponse | WorkerGetSemanticChangesResponse | WorkerGetRevisionsResponse | WorkerGetDocumentMetadataResponse | WorkerGetVersionResponse | WorkerPrepareResponse | WorkerSessionOpenResponse | WorkerSessionGetPackageManifestResponse | WorkerSessionGetSemanticChangesResponse | WorkerSessionVerifyDeliverableResponse | WorkerSessionCloseResponse | WorkerSessionEditResponse;
+export type WorkerResponse = WorkerInitResponse | WorkerGeneratePackageManifestResponse | WorkerVerifyDeliverableResponse | WorkerProveRedlineReversibilityResponse | WorkerProjectReviewProfileResponse | WorkerConvertResponse | WorkerCompareResponse | WorkerCompareToHtmlResponse | WorkerGetSemanticChangesResponse | WorkerCreateExternalAnnotationSetResponse | WorkerValidateExternalAnnotationsResponse | WorkerProjectAnnotationsOntoHtmlResponse | WorkerConvertWithExternalAnnotationsResponse | WorkerExportToOpenContractResponse | WorkerGetRevisionsResponse | WorkerGetDocumentMetadataResponse | WorkerGetVersionResponse | WorkerPrepareResponse | WorkerSessionOpenResponse | WorkerSessionGetPackageManifestResponse | WorkerSessionGetSemanticChangesResponse | WorkerSessionVerifyDeliverableResponse | WorkerSessionCloseResponse | WorkerSessionEditResponse;
 /**
  * Options for creating a worker-based Docxodus instance.
  */