Add XMP destination strip policies & persistence

Introduce explicit destination XMP handling and a bounded persistence helper. Adds enums XmpDestinationEmbeddedMode and XmpDestinationSidecarMode and new ExecutePreparedTransferFileOptions fields to control preserve/strip behavior for embedded XMP and sibling .xmp sidecars. propagate a strip_existing_xmp flag throughout JPEG/TIFF/PNG/WebP/JP2/JXL planning and emit paths so existing embedded XMP can be removed when sidecar-only writeback is selected for supported formats. Implement file helpers (path_exists, write_file_bytes, find_existing_xmp_sidecar_path), TIFF payload scrubbing, and related rewrite logic to remove XMP carriers as requested.

Add persist_prepared_transfer_file_result and its options/result structs to let hosts persist edited output, write generated XMP sidecars, and optionally remove a stale destination sidecar without reimplementing CLI/python logic. execute_prepared_transfer_file now computes cleanup actions for destination sidecars and applies strip policies during planning/emit.

Expose the new modes to the Python CLI and wrapper: new --xmp-destination-embedded and --xmp-destination-sidecar flags, wiring the Python wrapper to call transfer_file/unsafe_transfer_file when persisting output and to pass the new options through. Various minor messaging and validation updates accompany the new behavior.

Author: ssh4net

README.md

@@ -104,6 +104,18 @@ In practice:
   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.
+- 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`.
+- Embedded-only writeback can also strip an existing sibling `.xmp`
+  destination sidecar explicitly, so exports can move back to embedded-only
+  XMP without leaving stale sidecar state behind.
+- C++ hosts now also have a bounded persistence helper for file-helper
+  results, so edited output bytes, generated sidecars, and stale-sidecar
+  cleanup can be applied without copying wrapper logic.
+- Python hosts also have matching `transfer_file(...)` and
+  `unsafe_transfer_file(...)` bindings, and the public Python transfer wrapper
+  now uses that same core-backed persistence path for real writes.
 - 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

@@ -236,13 +236,18 @@ Current controls:
   - `EmbeddedOnly`
   - `SidecarOnly`
   - `EmbeddedAndSidecar`
+- `xmp_destination_embedded_mode` on the file-helper execution path:
+  - `PreserveExisting`
+  - `StripExisting`
 - 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|embedded_and_sidecar>`
+  - `--xmp-destination-embedded <preserve_existing|strip_existing>`
+  - `--xmp-destination-sidecar <preserve_existing|strip_existing>`
 
 Current behavior:
 - existing XMP can still be included independently
@@ -265,11 +270,27 @@ 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
+- 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`,
+    and `jxl`
+- embedded-only writeback now has an explicit destination sidecar policy:
+  - preserve an existing sibling `.xmp` by default
+  - strip an existing sibling `.xmp` when explicitly requested
+- the C++ API now also has a bounded persistence helper for
+  `execute_prepared_transfer_file(...)` results, so applications can write the
+  edited file, write the generated `.xmp` sidecar, and remove a stale sibling
+  `.xmp` without reimplementing wrapper-side file logic
+- the Python binding now exposes the same persistence path through
+  `transfer_file(...)` and `unsafe_transfer_file(...)`, and the public Python
+  wrapper uses that core helper instead of maintaining its own sidecar write
+  and cleanup implementation
 
 This is deliberately narrower than a full sync engine. It does not yet define:
 - full EXIF vs XMP precedence rules
 - MWG-style reconciliation
-- canonical destination embedded-vs-sidecar reconciliation policy
+- full destination embedded-vs-sidecar reconciliation policy beyond the
+  current bounded carrier modes and strip rules
 - namespace-wide deduplication and normalization rules beyond the current
   generated-XMP path
 

src/include/openmeta/metadata_transfer.h

@@ -452,6 +452,7 @@ struct PlanJpegEditOptions final {
     JpegEditMode mode        = JpegEditMode::Auto;
     bool require_in_place    = false;
     bool skip_empty_payloads = true;
+    bool strip_existing_xmp  = false;
 };
 
 /// Planned JPEG edit summary (draft API).
@@ -460,6 +461,7 @@ struct JpegEditPlan final {
     JpegEditMode requested_mode              = JpegEditMode::Auto;
     JpegEditMode selected_mode               = JpegEditMode::MetadataRewrite;
     bool in_place_possible                   = false;
+    bool strip_existing_xmp                  = false;
     uint32_t emitted_segments                = 0;
     uint32_t replaced_segments               = 0;
     uint32_t appended_segments               = 0;
@@ -476,13 +478,15 @@ struct JpegEditPlan final {
 struct PlanTiffEditOptions final {
     /// If true, fail planning when the bundle has no TIFF-applicable updates.
     bool require_updates = true;
+    bool strip_existing_xmp = false;
 };
 
 /// Planned TIFF edit summary (draft API).
 struct TiffEditPlan final {
     TransferStatus status = TransferStatus::Ok;
     uint32_t tag_updates  = 0;
     bool has_exif_ifd     = false;
+    bool strip_existing_xmp = false;
     uint64_t input_size   = 0;
     uint64_t output_size  = 0;
     std::string message;
@@ -1122,6 +1126,7 @@ struct ExecutePreparedTransferOptions final {
     bool edit_requested                    = false;
     bool edit_apply                        = false;
     TransferByteWriter* edit_output_writer = nullptr;
+    bool strip_existing_xmp                = false;
     PlanJpegEditOptions jpeg_edit;
     PlanTiffEditOptions tiff_edit;
 };
@@ -1149,6 +1154,7 @@ struct ExecutePreparedTransferResult final {
     std::vector<EmittedBmffPropertySummary> bmff_property_summary;
     bool tiff_commit          = false;
     uint64_t emit_output_size = 0;
+    bool strip_existing_xmp   = false;
 
     bool edit_requested             = false;
     TransferStatus edit_plan_status = TransferStatus::Unsupported;
@@ -1168,13 +1174,30 @@ enum class XmpWritebackMode : uint8_t {
     EmbeddedAndSidecar,
 };
 
+/// Destination embedded-XMP handling for file-helper transfer execution.
+enum class XmpDestinationEmbeddedMode : uint8_t {
+    PreserveExisting,
+    StripExisting,
+};
+
+/// Destination sibling XMP sidecar handling for file-helper transfer
+/// execution.
+enum class XmpDestinationSidecarMode : uint8_t {
+    PreserveExisting,
+    StripExisting,
+};
+
 /// 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;
+    XmpDestinationEmbeddedMode xmp_destination_embedded_mode
+        = XmpDestinationEmbeddedMode::PreserveExisting;
+    XmpDestinationSidecarMode xmp_destination_sidecar_mode
+        = XmpDestinationSidecarMode::PreserveExisting;
     bool c2pa_stage_requested = false;
     PreparedTransferC2paSignerInput c2pa_signer_input;
     bool c2pa_signed_package_provided = false;
@@ -1190,8 +1213,57 @@ struct ExecutePreparedTransferFileResult final {
     std::string xmp_sidecar_message;
     std::string xmp_sidecar_path;
     std::vector<std::byte> xmp_sidecar_output;
+    bool xmp_sidecar_cleanup_requested = false;
+    TransferStatus xmp_sidecar_cleanup_status = TransferStatus::Unsupported;
+    std::string xmp_sidecar_cleanup_message;
+    std::string xmp_sidecar_cleanup_path;
+};
+
+/// Options for \ref persist_prepared_transfer_file_result.
+struct PersistPreparedTransferFileOptions final {
+    std::string output_path;
+    bool write_output = true;
+    bool overwrite_output = false;
+    uint64_t prewritten_output_bytes = 0;
+    bool overwrite_xmp_sidecar = false;
+    bool remove_destination_xmp_sidecar = true;
 };
 
+/// Result for \ref persist_prepared_transfer_file_result.
+struct PersistPreparedTransferFileResult final {
+    TransferStatus status = TransferStatus::Unsupported;
+    std::string message;
+
+    TransferStatus output_status = TransferStatus::Unsupported;
+    std::string output_message;
+    std::string output_path;
+    uint64_t output_bytes = 0;
+
+    TransferStatus xmp_sidecar_status = TransferStatus::Unsupported;
+    std::string xmp_sidecar_message;
+    std::string xmp_sidecar_path;
+    uint64_t xmp_sidecar_bytes = 0;
+
+    TransferStatus xmp_sidecar_cleanup_status = TransferStatus::Unsupported;
+    std::string xmp_sidecar_cleanup_message;
+    std::string xmp_sidecar_cleanup_path;
+    bool xmp_sidecar_cleanup_removed = false;
+};
+
+/**
+ * \brief Persists edited output, generated XMP sidecar output, and any
+ * requested destination-sidecar cleanup from
+ * \ref execute_prepared_transfer_file.
+ *
+ * This is a bounded file helper for host applications that want the same
+ * output/sidecar behavior as the CLI or Python wrapper without reimplementing
+ * write and cleanup logic.
+ */
+PersistPreparedTransferFileResult
+persist_prepared_transfer_file_result(
+    const ExecutePreparedTransferFileResult& prepared,
+    const PersistPreparedTransferFileOptions& options) noexcept;
+
 /**
  * \brief Materializes the final persisted package batch for one executed
  * transfer state.