Add bounded EXR emit and XMP projection controls

Bounded first-class EXR metadata target and writer-side XMP projection controls. Adds EXR-specific types (PreparedExrEmitOp/Plan, EmittedExrAttributeSummary, ExrPreparedAttributeView), parsing/serialization helpers, unique EXR attribute naming, and OIIO attribute collection to prepare flattened string header attributes as prepared transfer blocks. Implements EXR emit/compile/compiled-emit paths and hot-path execution helpers, adapter op kind and adapter view support, and recording emitters/summaries. Add request flags (xmp_project_exif, xmp_project_iptc), XMP-sidecar IPTC inclusion, policy decision recording for EXIF/IPTC->XMP projection, and corresponding CLI/python flags (--xmp-no-exif-projection, --xmp-no-iptc-projection, --target-exr). Update docs/README to reflect EXR status and write-side sync controls and adjust XMP dump to honor IPTC projection option.

Author: ssh4net

README.md

@@ -80,13 +80,22 @@ Current target status:
 | JP2 | Bounded but real |
 | JXL | Bounded but real |
 | HEIF / AVIF / CR3 | Bounded but real |
-| EXR | Bridge-only today |
+| EXR | Bounded but real |
 
 In practice:
 - JPEG and TIFF are the strongest transfer targets today.
-- PNG, WebP, JP2, JXL, and bounded BMFF targets have real emit/edit paths.
-- EXR currently has an attribute bridge for host integrations, not a full
-  first-class transfer path.
+- PNG, WebP, JP2, JXL, bounded BMFF, and EXR all have real first-class
+  transfer entry points.
+- EXR is still narrower than the container-edit targets: it emits safe string
+  header attributes through the transfer core, but it does not rewrite full
+  EXR files yet.
+- 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.
+- 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
+  solve all EXIF/IPTC/XMP conflict resolution or canonical writeback policy.
 
 For transfer details, see
 [docs/metadata_transfer_plan.md](docs/metadata_transfer_plan.md).

docs/metadata_transfer_plan.md

@@ -34,6 +34,12 @@ Source-side readiness is already strong:
 
 The main remaining work is now on the target side.
 
+The first public write-side sync controls are also in place:
+- generated XMP can explicitly suppress EXIF-derived projection
+- generated XMP can explicitly suppress IPTC-derived projection
+- prepared bundles record those resolved projection decisions alongside the
+  existing preservation policies
+
 ## Target Status Matrix
 
 | Target | Status | Current shape | Main limits |
@@ -45,7 +51,7 @@ The main remaining work is now on the target side.
 | JP2 | Bounded but real | Prepared bundle, compiled emit, bounded box rewrite/edit, file-helper roundtrip | `jp2h` synthesis is still out of scope |
 | JXL | Bounded but real | Prepared bundle, compiled emit, bounded box rewrite/edit, file-helper roundtrip | Still narrower than JPEG/TIFF |
 | HEIF / AVIF / CR3 | Bounded but real | Prepared bundle, compiled emit, bounded BMFF item/property edit, file-helper roundtrip | Not broad BMFF writer parity |
-| EXR | Bridge-only today | EXR-native attribute export and replay for host integrations | No first-class transfer target path yet |
+| EXR | Bounded but real | Prepared bundle, compiled emit, direct backend attribute emit, CLI/Python transfer surface | No file rewrite/edit path yet; current transfer payload is safe string attributes only |
 
 ## What Is Already Implemented
 
@@ -71,7 +77,8 @@ These support the public transfer flow:
 - prepared payload and package batch persistence
 - adapter views for host integrations
 - explicit time-patch support for fixed-width EXIF date/time fields
-- transfer-policy decisions for MakerNote, JUMBF, and C2PA
+- transfer-policy decisions for MakerNote, JUMBF, C2PA, EXIF-to-XMP
+  projection, and IPTC-to-XMP projection
 
 ### Current File-Helper Regression Coverage
 
@@ -163,21 +170,34 @@ Implemented as a bounded BMFF target family:
 
 ### EXR
 
-Implemented today as an integration bridge, not a first-class transfer target:
+Implemented today as a bounded first-class target:
+- `prepare_metadata_for_target(...)`
+- `prepare_metadata_for_target_file(...)`
+- `compile_prepared_transfer_execution(...)`
+- `emit_prepared_bundle_exr(...)`
+- `emit_prepared_transfer_compiled(...)`
+- public CLI/Python `--target-exr` transfer surface
+
+It still keeps the older integration bridge:
 - `build_exr_attribute_batch(...)`
 - `build_exr_attribute_part_spans(...)`
 - `build_exr_attribute_part_views(...)`
 - `replay_exr_attribute_batch(...)`
 
-This is useful for OpenEXR / OIIO-style hosts, but it is not yet a true
-`prepare -> compile -> emit/edit` path in the same sense as JPEG or TIFF.
+Current EXR transfer scope is intentionally conservative:
+- safe flattened `string` header attributes
+- backend emission through `ExrTransferEmitter`
+- no general file-based EXR metadata rewrite/edit path yet
+- no typed EXR attribute synthesis beyond the current safe string projection
 
 ## Transfer Policies
 
-The public transfer contract already models three policy subjects:
+The public transfer contract now models five policy subjects:
 - MakerNote
 - JUMBF
 - C2PA
+- XMP EXIF projection
+- XMP IPTC projection
 
 Each uses explicit `TransferPolicyAction` values:
 - `Keep`
@@ -188,6 +208,39 @@ Each uses explicit `TransferPolicyAction` values:
 Prepared bundles also record the resolved policy decisions and reasons so
 callers do not have to infer behavior from warning text alone.
 
+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
+
+This gives callers stable write-side control over the most important projection
+behavior without forcing them to reverse-engineer the transfer output.
+
+## Write-Side Sync Controls
+
+OpenMeta now has a bounded public sync-policy layer for generated XMP.
+
+Current controls:
+- `xmp_project_exif`
+- `xmp_project_iptc`
+- CLI:
+  - `--xmp-no-exif-projection`
+  - `--xmp-no-iptc-projection`
+
+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
+- some targets without a native IPTC carrier can still use XMP as the bounded
+  fallback carrier when IPTC projection is enabled
+
+This is deliberately narrower than a full sync engine. It does not yet define:
+- full EXIF vs XMP precedence rules
+- MWG-style reconciliation
+- canonical sidecar vs embedded writeback policy
+- namespace-wide deduplication and normalization rules beyond the current
+  generated-XMP path
+
 ## Time Patch Plan
 
 Time patching is intentionally narrow and fixed-width.
@@ -214,9 +267,10 @@ OpenMeta still does not present one fully mature, general-purpose metadata
 editor across all formats. The current transfer core is real, but still more
 bounded than ExifTool or Exiv2.
 
-### 2. EXIF / IPTC / XMP sync policy
+### 2. Broader EXIF / IPTC / XMP sync policy
 
-This remains one of the biggest product gaps for writer adoption.
+This remains one of the biggest product gaps for writer adoption, even though
+the first public projection controls now exist.
 
 Missing pieces include:
 - conflict resolution rules
@@ -229,11 +283,12 @@ Missing pieces include:
 Read parity is strong, but broad rewrite guarantees for vendor metadata are not
 yet at the level of mature editing tools.
 
-### 4. EXR direction
+### 4. EXR depth
 
-The architectural question is now explicit:
-- keep EXR as an attribute bridge only, or
-- promote it to a first-class transfer target
+The architectural question is now how far to deepen the current bounded EXR
+target:
+- keep EXR as a backend-emitter target plus bridge helpers, or
+- add a broader EXR file rewrite/edit path
 
 ## Recommended Next Priorities
 
@@ -246,7 +301,7 @@ The architectural question is now explicit:
    - JP2
    - JXL
    - bounded BMFF
-3. Decide the EXR direction explicitly.
+3. Decide how deep EXR should go beyond the current bounded target.
 4. Add more transfer-focused roundtrip and compare gates where they improve
    confidence for adopters.
 5. Add an explicit EXIF / IPTC / XMP sync policy.

src/include/openmeta/metadata_transfer.h

@@ -113,6 +113,8 @@ enum class TransferPolicySubject : uint8_t {
     MakerNote,
     Jumbf,
     C2pa,
+    XmpExifProjection,
+    XmpIptcProjection,
 };
 
 /// Requested/effective action for a metadata family during transfer.
@@ -408,6 +410,8 @@ struct PrepareTransferRequest final {
     bool include_icc_app2               = true;
     bool include_iptc_app13             = true;
     bool xmp_portable                   = true;
+    bool xmp_project_exif               = true;
+    bool xmp_project_iptc               = true;
     bool xmp_include_existing           = true;
     bool xmp_exiftool_gpsdatetime_alias = false;
 };
@@ -731,6 +735,17 @@ struct PreparedJp2EmitPlan final {
     std::vector<PreparedJp2EmitOp> ops;
 };
 
+/// One precompiled EXR emit operation (prepared block -> EXR attribute).
+struct PreparedExrEmitOp final {
+    uint32_t block_index = 0;
+};
+
+/// Reusable precompiled EXR emit plan for a prepared transfer bundle.
+struct PreparedExrEmitPlan final {
+    uint32_t contract_version = kMetadataTransferContractVersion;
+    std::vector<PreparedExrEmitOp> ops;
+};
+
 /// Kind of precompiled ISO-BMFF metadata emit operation.
 enum class PreparedBmffEmitKind : uint8_t {
     Item,
@@ -770,6 +785,7 @@ struct PreparedTransferExecutionPlan final {
     PreparedWebpEmitPlan webp_emit;
     PreparedPngEmitPlan png_emit;
     PreparedJp2EmitPlan jp2_emit;
+    PreparedExrEmitPlan exr_emit;
     PreparedBmffEmitPlan bmff_emit;
 };
 
@@ -781,9 +797,10 @@ enum class TransferAdapterOpKind : uint8_t {
     JxlIccProfile,
     WebpChunk,
     PngChunk,
+    Jp2Box,
+    ExrAttribute,
     BmffItem,
     BmffProperty,
-    Jp2Box,
 };
 
 /// One compiled adapter-facing operation derived from a prepared bundle.
@@ -980,6 +997,14 @@ struct EmittedJp2BoxSummary final {
     uint64_t bytes           = 0;
 };
 
+/// One emitted EXR attribute summary entry.
+struct EmittedExrAttributeSummary final {
+    std::string name;
+    std::string type_name;
+    uint32_t count = 0;
+    uint64_t bytes = 0;
+};
+
 /// One emitted ISO-BMFF metadata item summary entry.
 struct EmittedBmffItemSummary final {
     uint32_t item_type = 0U;
@@ -1093,6 +1118,7 @@ struct ExecutePreparedTransferResult final {
     std::vector<EmittedWebpChunkSummary> webp_chunk_summary;
     std::vector<EmittedPngChunkSummary> png_chunk_summary;
     std::vector<EmittedJp2BoxSummary> jp2_box_summary;
+    std::vector<EmittedExrAttributeSummary> exr_attribute_summary;
     std::vector<EmittedBmffItemSummary> bmff_item_summary;
     std::vector<EmittedBmffPropertySummary> bmff_property_summary;
     bool tiff_commit          = false;
@@ -1250,6 +1276,14 @@ struct ExrPreparedAttribute final {
     bool is_opaque = false;
 };
 
+/// Zero-copy EXR attribute view for prepared transfer emission.
+struct ExrPreparedAttributeView final {
+    std::string_view name;
+    std::string_view type_name;
+    std::span<const std::byte> value;
+    bool is_opaque = false;
+};
+
 /**
  * \brief Backend contract for OpenEXR header attribute emission.
  */
@@ -1259,6 +1293,16 @@ class ExrTransferEmitter {
     virtual TransferStatus
     set_attribute(const ExrPreparedAttribute& attr) noexcept
         = 0;
+    virtual TransferStatus
+    set_attribute_view(const ExrPreparedAttributeView& attr) noexcept
+    {
+        ExrPreparedAttribute owned;
+        owned.name.assign(attr.name.data(), attr.name.size());
+        owned.type_name.assign(attr.type_name.data(), attr.type_name.size());
+        owned.value.assign(attr.value.begin(), attr.value.end());
+        owned.is_opaque = attr.is_opaque;
+        return set_attribute(owned);
+    }
 };
 
 /// \brief Draft bundle preparation entry point.
@@ -1373,6 +1417,21 @@ emit_prepared_bundle_jp2(const PreparedTransferBundle& bundle,
                          const EmitTransferOptions& options
                          = EmitTransferOptions {}) noexcept;
 
+/**
+ * \brief Emit prepared metadata blocks into an EXR backend.
+ *
+ * Route mapping:
+ * - `exr:attribute-string` -> EXR `string` header attribute
+ *
+ * This first-class EXR target is intentionally bounded to safe flattened
+ * string attributes. It does not rewrite complete EXR files.
+ */
+EmitTransferResult
+emit_prepared_bundle_exr(const PreparedTransferBundle& bundle,
+                         ExrTransferEmitter& emitter,
+                         const EmitTransferOptions& options
+                         = EmitTransferOptions {}) noexcept;
+
 /**
  * \brief Emit prepared metadata blocks into an ISO-BMFF metadata backend.
  *
@@ -1488,6 +1547,15 @@ compile_prepared_bundle_jp2(const PreparedTransferBundle& bundle,
                             const EmitTransferOptions& options
                             = EmitTransferOptions {}) noexcept;
 
+/**
+ * \brief Compile a reusable EXR emit plan from a prepared bundle.
+ */
+EmitTransferResult
+compile_prepared_bundle_exr(const PreparedTransferBundle& bundle,
+                            PreparedExrEmitPlan* out_plan,
+                            const EmitTransferOptions& options
+                            = EmitTransferOptions {}) noexcept;
+
 /**
  * \brief Compile a reusable ISO-BMFF metadata emit plan from a prepared
  * bundle.
@@ -1528,6 +1596,16 @@ emit_prepared_bundle_jp2_compiled(const PreparedTransferBundle& bundle,
                                   const EmitTransferOptions& options
                                   = EmitTransferOptions {}) noexcept;
 
+/**
+ * \brief Emit a prepared bundle using a precompiled EXR emit plan.
+ */
+EmitTransferResult
+emit_prepared_bundle_exr_compiled(const PreparedTransferBundle& bundle,
+                                  const PreparedExrEmitPlan& plan,
+                                  ExrTransferEmitter& emitter,
+                                  const EmitTransferOptions& options
+                                  = EmitTransferOptions {}) noexcept;
+
 /**
  * \brief Emit a prepared bundle using a precompiled ISO-BMFF metadata emit
  * plan.
@@ -1900,6 +1978,18 @@ emit_prepared_transfer_compiled(
     const ApplyTimePatchOptions& time_patch     = ApplyTimePatchOptions {},
     uint32_t emit_repeat                        = 1U) noexcept;
 
+/**
+ * \brief Hot-path helper: apply non-owning time patches and emit through an
+ * EXR backend.
+ */
+ExecutePreparedTransferResult
+emit_prepared_transfer_compiled(
+    PreparedTransferBundle* bundle, const PreparedTransferExecutionPlan& plan,
+    ExrTransferEmitter& emitter,
+    std::span<const TimePatchView> time_patches = {},
+    const ApplyTimePatchOptions& time_patch     = ApplyTimePatchOptions {},
+    uint32_t emit_repeat                        = 1U) noexcept;
+
 /**
  * \brief Hot-path helper: apply non-owning time patches and emit through an
  * ISO-BMFF metadata backend.

src/include/openmeta/xmp_dump.h

@@ -46,6 +46,8 @@ struct XmpPortableOptions final {
     XmpDumpLimits limits;
     /// Include TIFF/EXIF/GPS derived properties.
     bool include_exif = true;
+    /// Include IPTC-IIM derived portable XMP properties.
+    bool include_iptc = true;
     /// Include \ref MetaKeyKind::XmpProperty entries already present in the store.
     ///
     /// \note Currently only simple `property_path` values are emitted (no `/` nesting).
@@ -82,6 +84,7 @@ struct XmpSidecarRequest final {
 
     /// Portable mode options (applied when format == Portable).
     bool include_exif                        = true;
+    bool include_iptc                        = true;
     bool include_existing_xmp                = false;
     bool portable_exiftool_gpsdatetime_alias = false;