Merge existing destination embedded XMP support

Add support to include and merge existing embedded XMP from the edit target into generated transfer XMP with explicit precedence controls. Introduces XmpExistingDestinationEmbeddedMode and XmpExistingDestinationEmbeddedPrecedence enums and extends Prepare/Execute options and results to carry the requested merge and status information. Implements decode_existing_destination_embedded_xmp_into_store and helpers (value copying, append) to read, validate and merge XMP entries into the transfer MetaStore, and threads the feature through prepare/execute flows. Adds CLI and Python flags/arguments, updates the Python bindings and metatransfer tool to accept precedence and inclusion flags, and updates docs/README and tests to reflect the new behavior. Also includes TIFF/IFD pointer-preservation logic to preserve standard pointer tags (e.g. ExifIFD->InteropIFD) when replacing front subsets.

Author: ssh4net

README.md

@@ -96,7 +96,8 @@ In practice:
   chain rewrite (`ifd1`, `ifd2`, and preserved downstream tails), and bounded
   TIFF/DNG-style SubIFD rewrite with preserved downstream auxiliary tails
   and preserved trailing existing children when only the front subset is
-  replaced.
+  replaced. Replaced `ExifIFD` blocks can also preserve an existing target
+  `InteropIFD` when the source does not supply its own interop child.
 - For DNG-like TIFF sources, the current bounded merge policy is:
   replace the source-supplied front preview-page/aux front structures, preserve
   existing target page tails and trailing auxiliary children.
@@ -118,11 +119,18 @@ In practice:
   the destination path into generated portable XMP when that bounded mode is
   requested, with explicit `sidecar_wins` or `source_wins` precedence against
   source-embedded existing XMP.
+- Transfer preparation and file-helper execution can also fold existing
+  embedded XMP from the destination file into generated portable XMP when
+  that bounded mode is requested, with explicit `destination_wins` or
+  `source_wins` precedence against source-embedded existing XMP.
 - File-helper execution, `metatransfer`, and the Python transfer wrapper now
   share a bounded XMP carrier choice:
   embedded XMP only, sidecar-only writeback to a sibling `.xmp`, or dual
   embedded-plus-sidecar writeback when a generated XMP packet exists for the
   prepared transfer.
+- `metatransfer` and the Python transfer wrapper also expose the bounded
+  destination-embedded merge controls directly instead of hiding them behind
+  lower-level bindings.
 - Sidecar-only writeback also has an explicit destination embedded-XMP policy:
   preserve existing embedded XMP by default, or strip it for
   `jpeg`, `tiff`, `png`, `webp`, `jp2`, and `jxl`.

docs/metadata_transfer_plan.md

@@ -47,7 +47,7 @@ The first public write-side sync controls are also in place:
 | Target | Status | Current shape | Main limits |
 | --- | --- | --- | --- |
 | JPEG | First-class | Prepared bundle, compiled emit, byte-writer emit, edit planning/apply, file helper, bounded JUMBF/C2PA staging | Not a full arbitrary metadata editor yet |
-| TIFF | First-class | Prepared bundle, compiled emit, classic-TIFF and BigTIFF edit planning/apply, bounded `ifd1` chain rewrite with preserved downstream page tails, bounded TIFF/DNG-style SubIFD rewrite with preserved downstream auxiliary tails and preserved trailing existing children when only the front subset is replaced, file helper, streaming edit path | Broader TIFF/DNG rewrite coverage is still narrower than JPEG |
+| TIFF | First-class | Prepared bundle, compiled emit, classic-TIFF and BigTIFF edit planning/apply, bounded preview-page chain rewrite (`ifd1`, `ifd2`, and preserved downstream tails), bounded TIFF/DNG-style SubIFD rewrite with preserved downstream auxiliary tails and preserved trailing existing children when only the front subset is replaced, bounded `ExifIFD -> InteropIFD` preservation when a replaced ExifIFD omits its own interop child, file helper, streaming edit path | Broader TIFF/DNG rewrite coverage is still narrower than JPEG |
 | PNG | Bounded but real | Prepared bundle, compiled emit, bounded chunk rewrite/edit, file-helper roundtrip | Not a general PNG chunk editor |
 | WebP | Bounded but real | Prepared bundle, compiled emit, bounded chunk rewrite/edit, file-helper roundtrip | Not a general WebP chunk editor |
 | JP2 | Bounded but real | Prepared bundle, compiled emit, bounded box rewrite/edit, file-helper roundtrip | `jp2h` synthesis is still out of scope |
@@ -87,9 +87,10 @@ These support the public transfer flow:
 OpenMeta now has explicit end-to-end read-backed transfer tests for:
 - source JPEG -> JPEG edit/apply -> read-back
 - source JPEG -> TIFF edit/apply -> read-back
-- source JPEG -> TIFF edit/apply with `ifd1` -> read-back
-- source TIFF/BigTIFF with existing multi-page `ifd1 -> next` chain ->
-  replace `ifd1` -> preserve downstream tail
+- source JPEG -> TIFF edit/apply with bounded preview-page chain ->
+  read-back
+- source TIFF/BigTIFF with existing multi-page preview chain ->
+  replace the front preview pages and preserve downstream tails
 - source DNG-like TIFF with `subifd0` + `ifd1` -> TIFF edit/apply -> read-back
 - source DNG-like TIFF with `subifd0` + `ifd1` -> BigTIFF edit/apply -> read-back
 - source TIFF/BigTIFF with existing `subifd0 -> next` auxiliary chain ->
@@ -135,6 +136,8 @@ Implemented:
   existing downstream auxiliary tail when `subifdN` is replaced
 - bounded front-subset `SubIFD` replacement that preserves trailing existing
   children from the target file
+- bounded `ExifIFD` replacement that preserves an existing target
+  `InteropIFD` when the source replacement omits its own interop child
 - bounded DNG-style merge policy in the file-helper path:
   source-supplied preview/aux front structures replace the target front
   structures, while existing target page tails and trailing auxiliary
@@ -265,6 +268,14 @@ Current controls:
 - `xmp_existing_sidecar_precedence` on the file-read/prepare path:
   - `SidecarWins`
   - `SourceWins`
+- `xmp_existing_destination_embedded_mode` on the file-read/prepare and
+  file-helper execution paths:
+  - `Ignore`
+  - `MergeIfPresent`
+- `xmp_existing_destination_embedded_precedence` on the file-read/prepare and
+  file-helper execution paths:
+  - `DestinationWins`
+  - `SourceWins`
 - `xmp_writeback_mode` on the file-helper execution path:
   - `EmbeddedOnly`
   - `SidecarOnly`
@@ -275,6 +286,8 @@ Current controls:
 - CLI:
   - `--xmp-include-existing-sidecar`
   - `--xmp-existing-sidecar-precedence <sidecar_wins|source_wins>`
+  - `--xmp-include-existing-destination-embedded`
+  - `--xmp-existing-destination-embedded-precedence <destination_wins|source_wins>`
   - `--xmp-no-exif-projection`
   - `--xmp-no-iptc-projection`
   - `--xmp-conflict-policy <current|existing_wins|generated_wins>`
@@ -294,6 +307,12 @@ Current behavior:
   requested
 - that sidecar merge path now has explicit precedence against source-embedded
   existing XMP instead of relying on implicit decode order
+- existing embedded XMP from the destination file can also be merged into
+  generated portable XMP on the file-read/prepare path and on the file-helper
+  path when explicitly requested
+- that destination-embedded merge path has its own explicit precedence
+  against source-embedded existing XMP instead of relying on implicit decode
+  order
 - some targets without a native IPTC carrier can still use XMP as the bounded
   fallback carrier when IPTC projection is enabled
 - file-helper export can now strip prepared embedded XMP blocks and return
@@ -303,6 +322,8 @@ Current behavior:
 - the public `metatransfer` CLI and Python transfer wrapper can now persist
   that generated XMP as a sibling `.xmp` sidecar when sidecar or dual-write
   XMP writeback is selected
+- the public `metatransfer` CLI and Python transfer wrapper now also expose
+  the bounded destination-embedded merge and precedence controls directly
 - sidecar-only writeback now has an explicit destination embedded-XMP policy:
   - preserve existing embedded XMP by default
   - strip existing embedded XMP for `jpeg`, `tiff`, `png`, `webp`, `jp2`,
@@ -323,7 +344,7 @@ This is deliberately narrower than a full sync engine. It does not yet define:
 - full EXIF vs XMP precedence rules
 - MWG-style reconciliation
 - full destination embedded-vs-sidecar reconciliation policy beyond the
-  current bounded carrier modes and strip rules
+  current bounded merge, precedence, carrier-mode, and strip rules
 - namespace-wide deduplication and normalization rules beyond the current
   generated-XMP path
 

src/include/openmeta/metadata_transfer.h

@@ -917,17 +917,38 @@ enum class XmpExistingSidecarPrecedence : uint8_t {
     SourceWins,
 };
 
+/// Existing destination embedded-XMP handling for file-helper transfer
+/// execution.
+enum class XmpExistingDestinationEmbeddedMode : uint8_t {
+    Ignore,
+    MergeIfPresent,
+};
+
+/// Conflict precedence between merged destination embedded XMP and
+/// source-embedded existing XMP.
+enum class XmpExistingDestinationEmbeddedPrecedence : uint8_t {
+    DestinationWins,
+    SourceWins,
+};
+
 /// File-read + decode options for \ref prepare_metadata_for_target_file.
 struct PrepareTransferFileOptions final {
     bool include_pointer_tags       = true;
     bool decode_makernote           = false;
     bool decode_embedded_containers = true;
     bool decompress                 = true;
     std::string xmp_existing_sidecar_base_path;
+    std::string xmp_existing_destination_embedded_path;
     XmpExistingSidecarMode xmp_existing_sidecar_mode
         = XmpExistingSidecarMode::Ignore;
     XmpExistingSidecarPrecedence xmp_existing_sidecar_precedence
         = XmpExistingSidecarPrecedence::SidecarWins;
+    XmpExistingDestinationEmbeddedMode
+        xmp_existing_destination_embedded_mode
+        = XmpExistingDestinationEmbeddedMode::Ignore;
+    XmpExistingDestinationEmbeddedPrecedence
+        xmp_existing_destination_embedded_precedence
+        = XmpExistingDestinationEmbeddedPrecedence::DestinationWins;
 
     OpenMetaResourcePolicy policy;
     PrepareTransferRequest prepare;
@@ -943,6 +964,11 @@ struct PrepareTransferFileResult final {
     TransferStatus xmp_existing_sidecar_status = TransferStatus::Unsupported;
     std::string xmp_existing_sidecar_message;
     std::string xmp_existing_sidecar_path;
+    bool xmp_existing_destination_embedded_loaded = false;
+    TransferStatus xmp_existing_destination_embedded_status
+        = TransferStatus::Unsupported;
+    std::string xmp_existing_destination_embedded_message;
+    std::string xmp_existing_destination_embedded_path;
 
     SimpleMetaResult read;
     PrepareTransferResult prepare;
@@ -1193,6 +1219,12 @@ struct ExecutePreparedTransferFileOptions final {
     ExecutePreparedTransferOptions execute;
     std::string edit_target_path;
     std::string xmp_sidecar_base_path;
+    XmpExistingDestinationEmbeddedMode
+        xmp_existing_destination_embedded_mode
+        = XmpExistingDestinationEmbeddedMode::Ignore;
+    XmpExistingDestinationEmbeddedPrecedence
+        xmp_existing_destination_embedded_precedence
+        = XmpExistingDestinationEmbeddedPrecedence::DestinationWins;
     XmpWritebackMode xmp_writeback_mode = XmpWritebackMode::EmbeddedOnly;
     XmpDestinationEmbeddedMode xmp_destination_embedded_mode
         = XmpDestinationEmbeddedMode::PreserveExisting;
@@ -1208,6 +1240,11 @@ struct ExecutePreparedTransferFileOptions final {
 struct ExecutePreparedTransferFileResult final {
     PrepareTransferFileResult prepared;
     ExecutePreparedTransferResult execute;
+    bool xmp_existing_destination_embedded_loaded = false;
+    TransferStatus xmp_existing_destination_embedded_status
+        = TransferStatus::Unsupported;
+    std::string xmp_existing_destination_embedded_message;
+    std::string xmp_existing_destination_embedded_path;
     bool xmp_sidecar_requested      = false;
     TransferStatus xmp_sidecar_status = TransferStatus::Unsupported;
     std::string xmp_sidecar_message;