Add XMP sidecar handling and conflict policy

Introduce explicit XMP conflict and sidecar handling for transfer preparation and execution.

Key additions:
- New enums: XmpConflictPolicy, XmpExistingSidecarMode, XmpExistingSidecarPrecedence, XmpWritebackMode.
- Prepare/execute API extensions: PrepareTransferFileOptions/Result and ExecutePreparedTransferFileOptions/Result now carry sidecar paths, status, messages and generated_xmp_sidecar bytes; PrepareTransferRequest gains xmp_conflict_policy.
- Support to discover, load and decode existing sibling .xmp sidecars (load_existing_xmp_sidecar_bytes, decode_existing_xmp_sidecar_into_store) and to merge them into the MetaStore when requested, with configurable precedence vs source-embedded XMP.
- Portable XMP generation updated to honor conflict policy: claim/owner map replaces the simple key set and emits properties in ordered passes (EXIF/Existing/IPTC) according to CurrentBehavior/ExistingWins/GeneratedWins.
- Prepared bundle now captures generated portable XMP bytes and execute_prepared_transfer_file can emit sidecar output and strip embedded XMP blocks when sidecar writeback is requested.
- Python CLI, wrapper and module bindings extended: new arguments (--xmp-include-existing-sidecar, --xmp-existing-sidecar-precedence, --xmp-conflict-policy, --xmp-writeback), corresponding OpenMeta enums exposed to Python, and logic to write generated .xmp sidecars alongside edited outputs.
- Documentation updated (README and docs/metadata_transfer_plan.md) describing the new knobs and behaviors.

These changes make XMP generation, merging and writeback behavior explicit and configurable without implementing a full sync engine.

Author: ssh4net

README.md

@@ -92,6 +92,17 @@ In practice:
 - Writer-side sync behavior is now partially explicit instead of implicit:
   generated XMP can independently keep or suppress EXIF-derived and
   IPTC-derived projection during transfer preparation.
+- Generated portable XMP also has an explicit conflict policy for existing
+  decoded XMP versus generated EXIF/IPTC mappings:
+  current behavior, `existing_wins`, or `generated_wins`.
+- Transfer preparation can also fold an existing sibling `.xmp` sidecar from
+  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.
+- File-helper execution, `metatransfer`, and the Python transfer wrapper now
+  share a bounded XMP carrier choice:
+  embedded XMP only, or sidecar-only writeback to a sibling `.xmp` when a
+  generated XMP packet exists for the prepared transfer.
 - Prepared bundles record resolved policy decisions for MakerNote, JUMBF,
   C2PA, EXIF-to-XMP projection, and IPTC-to-XMP projection.
 - This is still not a full MWG-style sync engine. OpenMeta does not yet try to

docs/metadata_transfer_plan.md

@@ -212,6 +212,8 @@ For the XMP projection subjects, the current public knobs are intentionally
 simple:
 - EXIF-derived properties can be mirrored into generated XMP or suppressed
 - IPTC-derived properties can be mirrored into generated XMP or suppressed
+- generated portable XMP can choose how existing decoded XMP conflicts with
+  generated EXIF/IPTC mappings
 
 This gives callers stable write-side control over the most important projection
 behavior without forcing them to reverse-engineer the transfer output.
@@ -223,16 +225,43 @@ OpenMeta now has a bounded public sync-policy layer for generated XMP.
 Current controls:
 - `xmp_project_exif`
 - `xmp_project_iptc`
+- `xmp_conflict_policy`
+- `xmp_existing_sidecar_mode` on the file-read/prepare path:
+  - `Ignore`
+  - `MergeIfPresent`
+- `xmp_existing_sidecar_precedence` on the file-read/prepare path:
+  - `SidecarWins`
+  - `SourceWins`
+- `xmp_writeback_mode` on the file-helper execution path:
+  - `EmbeddedOnly`
+  - `SidecarOnly`
 - CLI:
+  - `--xmp-include-existing-sidecar`
+  - `--xmp-existing-sidecar-precedence <sidecar_wins|source_wins>`
   - `--xmp-no-exif-projection`
   - `--xmp-no-iptc-projection`
+  - `--xmp-conflict-policy <current|existing_wins|generated_wins>`
+  - `--xmp-writeback <embedded|sidecar>`
 
 Current behavior:
 - existing XMP can still be included independently
 - EXIF payload emission stays independent from EXIF-to-XMP projection
 - IPTC native carrier emission stays independent from IPTC-to-XMP projection
+- portable generated XMP can keep the historical mixed order, prefer existing
+  decoded XMP, or prefer generated EXIF/IPTC mappings when the same portable
+  property would collide
+- existing sibling `.xmp` sidecars from the destination path can be merged
+  into generated portable XMP before transfer packaging when explicitly
+  requested
+- that sidecar merge path now has 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
+  canonical sidecar output guidance instead
+- the public `metatransfer` CLI and Python transfer wrapper can now persist
+  that generated XMP as a sibling `.xmp` sidecar when sidecar writeback is
+  selected
 
 This is deliberately narrower than a full sync engine. It does not yet define:
 - full EXIF vs XMP precedence rules
@@ -274,7 +303,7 @@ the first public projection controls now exist.
 
 Missing pieces include:
 - conflict resolution rules
-- sidecar vs embedded policy
+- broader sidecar vs embedded policy beyond the current bounded writeback mode
 - canonical writeback policy
 - broader namespace reconciliation behavior
 

src/include/openmeta/metadata_transfer.h

@@ -3,6 +3,7 @@
 #include "openmeta/meta_store.h"
 #include "openmeta/resource_policy.h"
 #include "openmeta/simple_meta.h"
+#include "openmeta/xmp_dump.h"
 
 #include <array>
 #include <cstddef>
@@ -393,6 +394,7 @@ struct PreparedTransferBundle final {
     std::vector<PreparedTransferPolicyDecision> policy_decisions;
     std::vector<PreparedTransferBlock> blocks;
     std::vector<TimePatchSlot> time_patch_map;
+    std::vector<std::byte> generated_xmp_sidecar;
 };
 
 /// Options for explicit raw JUMBF append into a prepared JPEG bundle.
@@ -413,6 +415,8 @@ struct PrepareTransferRequest final {
     bool xmp_project_exif               = true;
     bool xmp_project_iptc               = true;
     bool xmp_include_existing           = true;
+    XmpConflictPolicy xmp_conflict_policy
+        = XmpConflictPolicy::CurrentBehavior;
     bool xmp_exiftool_gpsdatetime_alias = false;
 };
 
@@ -896,12 +900,30 @@ class TransferAdapterSink {
         = 0;
 };
 
+/// Existing sibling XMP sidecar handling for transfer preparation.
+enum class XmpExistingSidecarMode : uint8_t {
+    Ignore,
+    MergeIfPresent,
+};
+
+/// Conflict precedence between a merged destination-side `.xmp` and
+/// source-embedded existing XMP.
+enum class XmpExistingSidecarPrecedence : uint8_t {
+    SidecarWins,
+    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;
+    XmpExistingSidecarMode xmp_existing_sidecar_mode
+        = XmpExistingSidecarMode::Ignore;
+    XmpExistingSidecarPrecedence xmp_existing_sidecar_precedence
+        = XmpExistingSidecarPrecedence::SidecarWins;
 
     OpenMetaResourcePolicy policy;
     PrepareTransferRequest prepare;
@@ -913,6 +935,10 @@ struct PrepareTransferFileResult final {
     PrepareTransferFileCode code   = PrepareTransferFileCode::None;
     uint64_t file_size             = 0;
     uint32_t entry_count           = 0;
+    bool xmp_existing_sidecar_loaded = false;
+    TransferStatus xmp_existing_sidecar_status = TransferStatus::Unsupported;
+    std::string xmp_existing_sidecar_message;
+    std::string xmp_existing_sidecar_path;
 
     SimpleMetaResult read;
     PrepareTransferResult prepare;
@@ -1135,11 +1161,19 @@ struct ExecutePreparedTransferResult final {
     std::vector<std::byte> edited_output;
 };
 
+/// XMP carrier preference for file-helper transfer execution.
+enum class XmpWritebackMode : uint8_t {
+    EmbeddedOnly,
+    SidecarOnly,
+};
+
 /// Options for \ref execute_prepared_transfer_file.
 struct ExecutePreparedTransferFileOptions final {
     PrepareTransferFileOptions prepare;
     ExecutePreparedTransferOptions execute;
     std::string edit_target_path;
+    std::string xmp_sidecar_base_path;
+    XmpWritebackMode xmp_writeback_mode = XmpWritebackMode::EmbeddedOnly;
     bool c2pa_stage_requested = false;
     PreparedTransferC2paSignerInput c2pa_signer_input;
     bool c2pa_signed_package_provided = false;
@@ -1150,6 +1184,11 @@ struct ExecutePreparedTransferFileOptions final {
 struct ExecutePreparedTransferFileResult final {
     PrepareTransferFileResult prepared;
     ExecutePreparedTransferResult execute;
+    bool xmp_sidecar_requested      = false;
+    TransferStatus xmp_sidecar_status = TransferStatus::Unsupported;
+    std::string xmp_sidecar_message;
+    std::string xmp_sidecar_path;
+    std::vector<std::byte> xmp_sidecar_output;
 };
 
 /**

src/include/openmeta/xmp_dump.h

@@ -14,6 +14,20 @@
 
 namespace openmeta {
 
+/// Conflict policy for existing XMP versus generated portable XMP properties.
+///
+/// This currently applies to portable XMP generation only.
+enum class XmpConflictPolicy : uint8_t {
+    /// Preserve the historical OpenMeta order:
+    /// EXIF-derived properties first, then existing XMP, then IPTC-derived
+    /// properties.
+    CurrentBehavior,
+    /// Existing decoded XMP properties win over generated EXIF/IPTC mappings.
+    ExistingWins,
+    /// Generated EXIF/IPTC mappings win over existing decoded XMP properties.
+    GeneratedWins,
+};
+
 /// XMP dump result status.
 enum class XmpDumpStatus : uint8_t {
     Ok,
@@ -52,6 +66,9 @@ struct XmpPortableOptions final {
     ///
     /// \note Currently only simple `property_path` values are emitted (no `/` nesting).
     bool include_existing_xmp = false;
+    /// Conflict policy between existing decoded XMP and generated portable
+    /// EXIF/IPTC mappings.
+    XmpConflictPolicy conflict_policy = XmpConflictPolicy::CurrentBehavior;
     /// Emit `exif:GPSDateTime` instead of `exif:GPSTimeStamp` for GPS time.
     ///
     /// Default keeps standard portable naming. This compatibility mode is
@@ -86,6 +103,8 @@ struct XmpSidecarRequest final {
     bool include_exif                        = true;
     bool include_iptc                        = true;
     bool include_existing_xmp                = false;
+    XmpConflictPolicy portable_conflict_policy
+        = XmpConflictPolicy::CurrentBehavior;
     bool portable_exiftool_gpsdatetime_alias = false;
 
     /// Lossless mode options (applied when format == Lossless).