Add writer target contract docs and test tool hooks

Introduce a new Writer Target Contract (docs/sphinx/writer_target_contract.rst and docs/writer_target_contract.md) that documents bounded preserve/replace rules and host-owned target image specs. Update multiple docs (quick_start, host_integration, development, metadata_transfer_plan, interop_api, xmp_sync_policy, and Sphinx indices) to reference the new contract and to document the target_image_spec and matching metatransfer/Python CLI --target-* flags and examples. Update CMake to add optional OPENMETA_OIIOTOOL_EXECUTABLE and OPENMETA_EXIFTOOL_EXECUTABLE cache vars (with find_program fallbacks) and wire those into test/gate targets; add a metatransfer image usability test target and integrate the executables into existing transfer_release and CLI/metatransfer smoke gate flows. Add the new tests/metatransfer_image_usability_test.cmake and other test updates to exercise external image usability checks.

Author: ssh4net

CMakeLists.txt

@@ -65,6 +65,27 @@ if(OPENMETA_PYTHON_EXECUTABLE)
   set(Python_EXECUTABLE "${OPENMETA_PYTHON_EXECUTABLE}" CACHE FILEPATH "Python interpreter" FORCE)
 endif()
 
+set(OPENMETA_OIIOTOOL_EXECUTABLE "" CACHE FILEPATH "Optional oiiotool executable for external image usability checks")
+if(NOT OPENMETA_OIIOTOOL_EXECUTABLE)
+  find_program(_openmeta_oiiotool_executable
+    NAMES oiiotool
+    HINTS ${CMAKE_PREFIX_PATH}
+    PATH_SUFFIXES bin)
+  if(_openmeta_oiiotool_executable)
+    set(OPENMETA_OIIOTOOL_EXECUTABLE "${_openmeta_oiiotool_executable}"
+      CACHE FILEPATH "Optional oiiotool executable for external image usability checks" FORCE)
+  endif()
+endif()
+
+set(OPENMETA_EXIFTOOL_EXECUTABLE "" CACHE FILEPATH "Optional exiftool executable for external metadata checks")
+if(NOT OPENMETA_EXIFTOOL_EXECUTABLE)
+  find_program(_openmeta_exiftool_executable NAMES exiftool)
+  if(_openmeta_exiftool_executable)
+    set(OPENMETA_EXIFTOOL_EXECUTABLE "${_openmeta_exiftool_executable}"
+      CACHE FILEPATH "Optional exiftool executable for external metadata checks" FORCE)
+  endif()
+endif()
+
 # Optional path to local dependency repos (used for the FuzzTest wrapper).
 # Expected layout:
 #   <root>/fuzztest
@@ -402,6 +423,20 @@ if(OPENMETA_BUILD_TOOLS)
       COMMENT "Running metatransfer smoke gate"
       VERBATIM
     )
+
+    if(OPENMETA_OIIOTOOL_EXECUTABLE)
+      add_custom_target(openmeta_gate_metatransfer_image_usability
+        DEPENDS metatransfer
+        COMMAND ${CMAKE_COMMAND}
+          "-DMETATRANSFER_BIN=$<TARGET_FILE:metatransfer>"
+          "-DOIIOTOOL_BIN=${OPENMETA_OIIOTOOL_EXECUTABLE}"
+          "-DEXIFTOOL_BIN=${OPENMETA_EXIFTOOL_EXECUTABLE}"
+          "-DWORK_DIR=${CMAKE_CURRENT_BINARY_DIR}/_metatransfer_image_usability"
+          -P "${CMAKE_CURRENT_SOURCE_DIR}/tests/metatransfer_image_usability_test.cmake"
+        COMMENT "Running metatransfer external image usability gate"
+        VERBATIM
+      )
+    endif()
   endif()
 
   if(TARGET metaread AND TARGET metadump AND TARGET thumdump
@@ -662,6 +697,8 @@ if(OPENMETA_BUILD_TESTS)
         "-DWORK_DIR=${CMAKE_CURRENT_BINARY_DIR}/_transfer_release_gate"
         "-DOPENMETA_PYTHON_EXECUTABLE=${Python_EXECUTABLE}"
         "-DOPENMETA_PYTHONPATH=${CMAKE_CURRENT_BINARY_DIR}/python"
+        "-DOIIOTOOL_BIN=${OPENMETA_OIIOTOOL_EXECUTABLE}"
+        "-DEXIFTOOL_BIN=${OPENMETA_EXIFTOOL_EXECUTABLE}"
         -P "${CMAKE_CURRENT_SOURCE_DIR}/tests/transfer_release_gate.cmake"
       COMMENT "Running transfer release gate"
       VERBATIM
@@ -674,6 +711,8 @@ if(OPENMETA_BUILD_TESTS)
         "-DWORK_DIR=${CMAKE_CURRENT_BINARY_DIR}/_transfer_release_gate"
         "-DOPENMETA_PYTHON_EXECUTABLE=${Python_EXECUTABLE}"
         "-DOPENMETA_PYTHONPATH=${CMAKE_CURRENT_BINARY_DIR}/python"
+        "-DOIIOTOOL_BIN=${OPENMETA_OIIOTOOL_EXECUTABLE}"
+        "-DEXIFTOOL_BIN=${OPENMETA_EXIFTOOL_EXECUTABLE}"
         -P "${CMAKE_CURRENT_SOURCE_DIR}/tests/transfer_release_gate.cmake"
     )
   elseif(TARGET metatransfer)
@@ -683,6 +722,8 @@ if(OPENMETA_BUILD_TESTS)
         "-DOPENMETA_TESTS_BIN=$<TARGET_FILE:openmeta_tests>"
         "-DMETATRANSFER_BIN=$<TARGET_FILE:metatransfer>"
         "-DWORK_DIR=${CMAKE_CURRENT_BINARY_DIR}/_transfer_release_gate"
+        "-DOIIOTOOL_BIN=${OPENMETA_OIIOTOOL_EXECUTABLE}"
+        "-DEXIFTOOL_BIN=${OPENMETA_EXIFTOOL_EXECUTABLE}"
         -P "${CMAKE_CURRENT_SOURCE_DIR}/tests/transfer_release_gate.cmake"
       COMMENT "Running transfer release gate"
       VERBATIM
@@ -693,6 +734,8 @@ if(OPENMETA_BUILD_TESTS)
         "-DOPENMETA_TESTS_BIN=$<TARGET_FILE:openmeta_tests>"
         "-DMETATRANSFER_BIN=$<TARGET_FILE:metatransfer>"
         "-DWORK_DIR=${CMAKE_CURRENT_BINARY_DIR}/_transfer_release_gate"
+        "-DOIIOTOOL_BIN=${OPENMETA_OIIOTOOL_EXECUTABLE}"
+        "-DEXIFTOOL_BIN=${OPENMETA_EXIFTOOL_EXECUTABLE}"
         -P "${CMAKE_CURRENT_SOURCE_DIR}/tests/transfer_release_gate.cmake"
     )
   endif()
@@ -729,6 +772,18 @@ if(OPENMETA_BUILD_TESTS)
         "-DWORK_DIR=${CMAKE_CURRENT_BINARY_DIR}/_cli_metatransfer_smoke"
         -P "${CMAKE_CURRENT_SOURCE_DIR}/tests/cli_metatransfer_smoke_test.cmake"
     )
+
+    if(OPENMETA_OIIOTOOL_EXECUTABLE)
+      add_test(
+        NAME openmeta_cli_metatransfer_image_usability
+        COMMAND ${CMAKE_COMMAND}
+          "-DMETATRANSFER_BIN=$<TARGET_FILE:metatransfer>"
+          "-DOIIOTOOL_BIN=${OPENMETA_OIIOTOOL_EXECUTABLE}"
+          "-DEXIFTOOL_BIN=${OPENMETA_EXIFTOOL_EXECUTABLE}"
+          "-DWORK_DIR=${CMAKE_CURRENT_BINARY_DIR}/_metatransfer_image_usability"
+          -P "${CMAKE_CURRENT_SOURCE_DIR}/tests/metatransfer_image_usability_test.cmake"
+      )
+    endif()
   endif()
 
   if(TARGET metaread AND TARGET metadump AND TARGET thumdump

docs/development.md

@@ -175,6 +175,14 @@ Portable sidecar note:
   --source-meta source.jpg \
   --target-tiff target.tif \
   -o injected.tif
+
+#Inject target-owned image facts when source and output pixels differ
+./build/metatransfer \
+  --target-jpeg target.jpg \
+  --target-width 320 --target-height 240 \
+  --target-samples-per-pixel 3 --target-bits-per-sample 8 \
+  --target-photometric 2 --target-exif-color-space 1 \
+  -o injected.jpg source.jpg
 ```
 
 `metatransfer` is a thin CLI wrapper over the public transfer APIs. It uses
@@ -189,6 +197,12 @@ exposes
 used, the CLI passes a `TransferByteWriter` sink into the shared execution
 path so edited output can stream directly to disk instead of always
 materializing a full output buffer.
+The `--target-width`, `--target-height`, `--target-orientation`,
+`--target-samples-per-pixel`, `--target-bits-per-sample`,
+`--target-sample-format`, `--target-photometric`,
+`--target-planar-configuration`, `--target-compression`, and
+`--target-exif-color-space` flags populate
+`PrepareTransferRequest::target_image_spec`.
 Current v1 behavior is:
 
 - JPEG edit output is streamed directly from the shared core path.
@@ -1287,6 +1301,12 @@ Python transfer entry point:
     `xmp_existing_sidecar_base_path` from `xmp_sidecar_base_path`, and they
     also expose `xmp_existing_destination_embedded_path` plus
     `xmp_existing_destination_sidecar_state` for pathless host flows.
+  - `openmeta.python.metatransfer` remains a thin command-line wrapper: its
+    `--xmp-writeback`, `--xmp-destination-embedded`,
+    `--xmp-destination-sidecar`, `--output`, and `--force` flags map directly
+    onto the C++ file-helper options and persistence flags. It reports the
+    sidecar and cleanup paths returned by the C++ result instead of deriving a
+    separate Python-side contract.
 
 Transfer probe contract hardening (stable machine fields):
 - `overall_status`, `overall_status_name`

docs/host_integration.md

@@ -18,6 +18,8 @@ For deterministic host compatibility baselines, see
 [compatibility_dump.md](compatibility_dump.md).
 For generated XMP merge and writeback precedence, see
 [xmp_sync_policy.md](xmp_sync_policy.md).
+For per-target writer preserve/replace guarantees, see
+[writer_target_contract.md](writer_target_contract.md).
 
 ## Pick The Integration Path
 
@@ -328,6 +330,20 @@ Python now exposes those same split path/state controls directly:
 `xmp_existing_destination_embedded_path`, and
 `xmp_existing_destination_sidecar_state`.
 
+The CLI and Python command-line wrapper do not implement their own transfer
+semantics. They map flags onto the same file-helper contract:
+- `--output` is the sidecar base for `sidecar` and `embedded_and_sidecar`
+  writeback, so the generated sidecar is `output-stem.xmp`.
+- `--xmp-writeback sidecar` suppresses generated embedded XMP.
+- `--xmp-writeback embedded_and_sidecar` writes generated XMP to both the
+  edited output and the generated sidecar.
+- embedded-only writeback preserves an existing destination sidecar unless
+  `--xmp-destination-sidecar strip_existing` is selected.
+- sidecar-only writeback preserves existing destination embedded XMP unless
+  `--xmp-destination-embedded strip_existing` is selected.
+- `--force` maps to the C++ persistence overwrite flags for the primary
+  output and generated sidecar.
+
 ## 7. Query Runtime Capabilities
 
 Hosts can ask OpenMeta what the current build supports before wiring format
@@ -395,6 +411,66 @@ openmeta::apply_prepared_dng_sdk_metadata(
 This bridge is for applications that already use the Adobe DNG SDK. OpenMeta
 still does not encode pixels or invent raw-image structure.
 
+### Host-Owned Image Specs
+
+If a transfer target is produced from a different image buffer than the source,
+the host writer owns the target image facts: dimensions, channel count, sample
+type, compression, orientation, colorspace, ICC profile, and TIFF strip/tile
+storage. OpenMeta does not infer those values from copied metadata. During
+prepared transfer it filters source EXIF/XMP image-layout fields so stale source
+properties are not written into a different output image.
+
+Host code that encodes pixels should keep those fields from the target
+container or inject values derived from the actual output buffer. Enable source
+ICC transfer only when the host has verified that the profile matches the target
+pixel buffer; otherwise preserve or write the target profile.
+
+```cpp
+openmeta::PrepareTransferRequest request;
+request.target_format = openmeta::TransferTargetFormat::Jpeg;
+
+request.target_image_spec.has_dimensions = true;
+request.target_image_spec.width = encoded_width;
+request.target_image_spec.height = encoded_height;
+
+request.target_image_spec.has_samples_per_pixel = true;
+request.target_image_spec.samples_per_pixel = 3;
+request.target_image_spec.bits_per_sample_count = 1;
+request.target_image_spec.bits_per_sample[0] = 8;
+request.target_image_spec.has_photometric_interpretation = true;
+request.target_image_spec.photometric_interpretation = 2; // RGB
+request.target_image_spec.has_exif_color_space = true;
+request.target_image_spec.exif_color_space = 1; // sRGB
+```
+
+Python exposes the same structure as `openmeta.TransferTargetImageSpec` and the
+command-line wrappers pass it through without a separate policy layer:
+
+```python
+spec = openmeta.TransferTargetImageSpec()
+spec.has_dimensions = True
+spec.width = encoded_width
+spec.height = encoded_height
+spec.has_samples_per_pixel = True
+spec.samples_per_pixel = 3
+spec.bits_per_sample = [8]
+spec.has_photometric_interpretation = True
+spec.photometric_interpretation = 2
+spec.has_exif_color_space = True
+spec.exif_color_space = 1
+```
+
+For smoke testing the file-helper path, `metatransfer` and
+`python -m openmeta.python.metatransfer` expose equivalent flags:
+
+```bash
+metatransfer --target-jpeg target.jpg -o output.jpg \
+  --target-width 320 --target-height 240 \
+  --target-samples-per-pixel 3 --target-bits-per-sample 8 \
+  --target-photometric 2 --target-exif-color-space 1 \
+  source.jpg
+```
+
 ## 9. Build `MetaStore` Yourself
 
 If your application creates metadata directly, build the store first and then

docs/metadata_backend_matrix.md

@@ -7,6 +7,9 @@ Date: March 5, 2026
 Define one OpenMeta write/transfer contract that can target multiple container
 backends without per-backend metadata logic duplication.
 
+For the public per-target preserve/replace guarantees, see
+[writer_target_contract.md](writer_target_contract.md).
+
 ## Capability Matrix
 
 | Backend | Native metadata write primitives | Best use in OpenMeta |
@@ -143,6 +146,10 @@ backends without per-backend metadata logic duplication.
   now performs bounded metadata-only edit by appending one OpenMeta-authored
   metadata-only top-level `meta` box and replacing any prior OpenMeta-authored
   metadata-only `meta` box from the same bounded contract.
+- Embedded-XMP strip mode removes only OpenMeta-authored metadata `meta` boxes.
+  Foreign BMFF XMP item graphs are preserved; recognized foreign XMP `mime`
+  items, including `iinf` version 0/1/2 tables, make strip mode fail
+  explicitly instead of silently claiming removal.
 - The same bounded BMFF edit contract now also participates in the core /
   file-helper C2PA signer path:
   - sign-request derivation