Add TransferSafetyMode and rendered-image filters

Introduce TransferSafetyMode (CompatibleFile, RenderedImage) and thread it through TransferProfile (default CompatibleFile). When RenderedImage is selected, prepare/apply logic filters safety-sensitive metadata: drop source ICC for rendered outputs, raw color calibration tags, camera raw settings XMP, opaque MakerNotes and non-C2PA JUMBF, and adjust C2PA handling (invalidate when appropriate). Implement counting and policy-decision reporting for filtered groups, apply safety-aware resolution of makernote/jumbf/c2pa policies, and add BMFF insertion compatibility changes (newly inserted item records use iloc construction method 0 with absolute file-offset extents and compact zero-width base-offset when safe). Update public docs, examples, Python/CLI wrappers (new --transfer-safety option), and tests to cover the new safety mode and the BMFF compatibility behavior.

Author: ssh4net

CHANGES.md

@@ -9,12 +9,29 @@ Changes compared with `0.4.7`.
 - Added bounded 32-bit BMFF item-id insertion for parseable foreign item graphs
   that already use `iloc` version 2. `iloc` version 0/1 targets remain on the
   existing 16-bit insertion path.
+- Added `TransferSafetyMode` on `TransferProfile`. The default
+  `CompatibleFile` mode keeps current transfer behavior, while `RenderedImage`
+  drops source raw color calibration/correction metadata, camera raw settings
+  XMP, source ICC profiles, MakerNotes, and non-C2PA JUMBF data for rendered
+  image outputs.
+- Added transfer policy decisions for filtered image properties, ICC profiles,
+  raw color calibration, and camera raw settings.
 
 ### Changed
 
 - Public BMFF writer-contract docs now state the remaining item-id-width limit
   explicitly: 32-bit inserted item IDs require an existing `iloc` v2 graph, and
   unsupported or exhausted item-id spaces fail safely instead of truncating IDs.
+- BMFF foreign-`meta` insertion keeps newly inserted metadata item records on
+  `iloc` construction method 0 with absolute file-offset extents for broad
+  reader compatibility.
+- BMFF foreign-`meta` insertion now compacts zero/foldable `iloc` base offsets
+  to a zero-width base-offset field when rebuilding supported item graphs,
+  preserving absolute self-contained item extents for simpler readers.
+- C++ and Python `metatransfer` wrappers now accept
+  `--transfer-safety compatible|rendered`.
+- Writer-contract docs now include a per-group transfer safety matrix for
+  rendered-image exports, including opaque MakerNote handling.
 
 ### Fixed
 
@@ -26,6 +43,19 @@ Changes compared with `0.4.7`.
 - Added a BMFF API roundtrip test that writes Exif and XMP into an `iloc` v2
   target with high item IDs and scans the result back as one Exif item and one
   XMP item.
+- Added focused BMFF coverage that verifies inserted Exif/XMP item records use
+  construction method 0 and absolute file-offset extents.
+- Extended the BMFF image-usability gate with an explicit ExifTool
+  reader-layout regression check for transferred Exif items in HEIF/AVIF/CR3
+  targets.
+- Extended rendered-image safety coverage to require policy decisions for
+  image-layout fields, ICC, RAW/DNG color and correction tags, camera raw
+  settings XMP, opaque MakerNotes, and non-C2PA JUMBF data.
+- Extended the `metatransfer` smoke gate to verify that
+  `--transfer-safety rendered` prints user-visible policy decisions for the
+  same safety-filtered groups.
+- Extended the Python `metatransfer` smoke gate with the same
+  `--transfer-safety rendered` policy-output coverage.
 
 ## 0.4.7 - 2026-04-27
 

docs/development.md

@@ -835,9 +835,10 @@ transfer path only runs for configured targets that match the 64x32,
 3-channel fixture shape, so the gate does not intentionally write mismatched
 image geometry. The configured XMP assertion is based on OpenMeta's BMFF
 summary; ExifTool title validation is also applied for formats where ExifTool
-exposes the generic BMFF XMP item. If the local `oiiotool` build cannot decode
-a configured BMFF target after rewrite, `OPENMETA_FFMPEG_EXECUTABLE` can
-provide the decode fallback.
+exposes the generic BMFF XMP item. ExifTool is also used for BMFF EXIF/ICC
+reader checks when available. If the local `oiiotool` build cannot decode a
+configured BMFF target after rewrite, `OPENMETA_FFMPEG_EXECUTABLE` can provide
+the decode fallback.
 
 The public GitHub Actions workflow `.github/workflows/ci.yml` runs two Linux
 variants of these public release gates:

docs/host_integration.md

@@ -425,9 +425,20 @@ 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.
 
+Use `TransferProfile::safety` for the broad source/destination relationship:
+
+| Mode | Use when | Transfer policy |
+| --- | --- | --- |
+| `CompatibleFile` | Metadata is repackaged or recompressed into a compatible file/pixel representation | Preserve source camera, color, ICC, and camera-specific data except target-owned image-layout fields |
+| `RenderedImage` | Pixels may have changed, especially RAW-to-JPEG/PNG/WebP/JXL/HEIF/AVIF export | Keep general/time/GPS/IPTC/portable XMP; drop source raw color calibration, linearization/crop/correction metadata, camera raw settings XMP, source ICC, opaque MakerNotes, and non-C2PA JUMBF |
+
+See [writer_target_contract.md](writer_target_contract.md#transfer-safety-matrix)
+for the detailed per-group transfer matrix.
+
 ```cpp
 openmeta::PrepareTransferRequest request;
 request.target_format = openmeta::TransferTargetFormat::Jpeg;
+request.profile.safety = openmeta::TransferSafetyMode::RenderedImage;
 
 request.target_image_spec.has_dimensions = true;
 request.target_image_spec.width = encoded_width;

docs/metadata_backend_matrix.md

@@ -156,6 +156,10 @@ For the public per-target preserve/replace guarantees, see
   Inserted item IDs follow the existing `iloc` item-id width: `iloc` version 0/1
   remains a 16-bit insertion path, while `iloc` version 2 can use 32-bit item IDs
   and emits wider `infe`/`iref` records when needed.
+  Newly inserted metadata item records keep `iloc` construction method 0 and
+  use absolute file-offset extents for broad reader
+  compatibility. When retained self-contained records can be represented that
+  way, the rebuilt `iloc` also compacts the base-offset field width to zero.
 - Foreign-`meta` ICC property merge is bounded to
   `bmff:property-colr-icc`. OpenMeta removes prior ICC `colr/prof` and
   `colr/rICC` properties from `iprp/ipco`, compacts/remaps existing `ipma`

docs/metadata_transfer_plan.md

@@ -41,6 +41,9 @@ 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
+- `TransferProfile::safety` can distinguish compatible metadata
+  repackage/recompression from rendered-image export, so callers can select a
+  safe coarse policy without hand-picking individual tags
 - prepared bundles record those resolved projection decisions alongside the
   existing preservation policies
 
@@ -113,6 +116,8 @@ OpenMeta now has explicit end-to-end read-backed transfer tests for:
 - source XMP -> bounded BMFF XMP item edit/apply -> read-back and external
   validation on configured HEIF/AVIF/CR3 targets where local tools expose the
   transferred XMP payload
+- source EXIF -> bounded BMFF Exif item edit/apply -> explicit ExifTool
+  reader-layout regression check on configured HEIF/AVIF/CR3 targets
 
 That does not make all targets equally mature, but it does mean the transfer
 core has real roundtrip regression gates across the primary supported export
@@ -147,7 +152,8 @@ CR3 target files via CMake cache paths when local tools cannot create those
 formats. Arbitrary configured BMFF targets exercise the ICC property and XMP
 item transfer/read-back routes; the EXIF image-property route remains limited
 to the 64x32, 3-channel fixture shape to avoid intentionally mismatched
-geometry.
+geometry. ExifTool is used when available for BMFF EXIF/XMP/ICC reader
+compatibility checks.
 
 ## Per-Target Notes
 
@@ -199,6 +205,12 @@ Implemented:
   source image-layout fields have been filtered. The Python binding and both
   command-line transfer wrappers now expose the same target image spec surface
   for file-helper integration tests.
+- rendered-output safety mode: `TransferProfile::safety =
+  TransferSafetyMode::RenderedImage` additionally drops source raw color
+  calibration, linearization/crop/correction metadata, camera raw settings XMP,
+  source ICC profiles, MakerNotes, and non-C2PA JUMBF data. It is intended for
+  RAW-to-rendered or otherwise pixel-changing exports where host code must
+  provide target-correct color/profile data.
 - 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
@@ -307,6 +319,10 @@ Implemented as a bounded BMFF target family:
 - bounded 32-bit item-id insertion for foreign item graphs that already use
   `iloc` version 2; `iloc` version 0/1 targets remain constrained to 16-bit
   inserted item IDs
+- inserted metadata item records keep `iloc` construction method 0 and use
+  absolute file-offset extents for broad reader compatibility
+- rebuilt foreign `iloc` graphs compact foldable self-contained base offsets to
+  a zero-width base-offset field when safe
 - bounded foreign top-level `meta` ICC property merge by replacing prior ICC
   `colr/prof` and `colr/rICC` properties, remapping `ipma`, and associating the
   transferred `colr/prof` property with the primary item
@@ -893,8 +909,8 @@ writer-confidence slice above; it should be sequenced around it.
   offset or byte range where available, and short host-facing messages
 - [ ] extend resource accounting beyond current hard limits with preflight
   estimates for prepared transfers, sidecar output, and serialized snapshots
-- [ ] add clean-room public micro fixtures for host integration tests; do not use
-  private corpus files, vendor drops, or scraped/spec text
+- [ ] add clean-room public micro fixtures for host integration tests; do not
+  vendor large binary assets, third-party source drops, or scraped/spec text
 - [ ] add examples for `read bytes -> snapshot -> target bytes -> edited bytes`
   and `visit_metadata(...) -> flat host attribute list`
 - [ ] consider a bounded random-access IO callback only after bytes/file APIs

docs/quick_start.md

@@ -207,6 +207,8 @@ This is the common export workflow:
 
 openmeta::ExecutePreparedTransferFileOptions options;
 options.prepare.prepare.target_format = openmeta::TransferTargetFormat::Jpeg;
+options.prepare.prepare.profile.safety =
+    openmeta::TransferSafetyMode::RenderedImage;
 options.edit_target_path = "rendered.jpg";
 
 const openmeta::ExecutePreparedTransferFileResult exec =

docs/sphinx/host_integration.rst

@@ -393,10 +393,29 @@ 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.
 
+Use ``TransferProfile::safety`` for the broad source/destination relationship:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 32 50
+
+   * - Mode
+     - Use when
+     - Transfer policy
+   * - ``CompatibleFile``
+     - Metadata is repackaged or recompressed into a compatible file/pixel representation
+     - Preserve source camera, color, ICC, and camera-specific data except target-owned image-layout fields
+   * - ``RenderedImage``
+     - Pixels may have changed, especially RAW-to-JPEG/PNG/WebP/JXL/HEIF/AVIF export
+     - Keep general/time/GPS/IPTC/portable XMP; drop source raw color calibration, linearization/crop/correction metadata, camera raw settings XMP, source ICC, opaque MakerNotes, and non-C2PA JUMBF
+
+See :ref:`transfer-safety-matrix` for the detailed per-group transfer matrix.
+
 .. code-block:: cpp
 
    openmeta::PrepareTransferRequest request;
    request.target_format = openmeta::TransferTargetFormat::Jpeg;
+   request.profile.safety = openmeta::TransferSafetyMode::RenderedImage;
 
    request.target_image_spec.has_dimensions = true;
    request.target_image_spec.width = encoded_width;

docs/sphinx/quick_start.rst

@@ -168,6 +168,8 @@ Copy metadata into an existing target
 
    openmeta::ExecutePreparedTransferFileOptions options;
    options.prepare.prepare.target_format = openmeta::TransferTargetFormat::Jpeg;
+   options.prepare.prepare.profile.safety =
+       openmeta::TransferSafetyMode::RenderedImage;
    options.edit_target_path = "rendered.jpg";
 
    openmeta::ExecutePreparedTransferFileResult exec =

docs/sphinx/testing.rst

@@ -117,9 +117,10 @@ transfer path only runs for configured targets that match the 64x32,
 3-channel fixture shape, so the gate does not intentionally write mismatched
 image geometry. The configured XMP assertion is based on OpenMeta's BMFF
 summary; ExifTool title validation is also applied for formats where ExifTool
-exposes the generic BMFF XMP item. If the local ``oiiotool`` build cannot
-decode a configured BMFF target after rewrite, ``OPENMETA_FFMPEG_EXECUTABLE``
-can provide the decode fallback.
+exposes the generic BMFF XMP item. ExifTool is also used for BMFF EXIF/ICC
+reader checks when available. If the local ``oiiotool`` build cannot decode a
+configured BMFF target after rewrite, ``OPENMETA_FFMPEG_EXECUTABLE`` can
+provide the decode fallback.
 
 The public GitHub Actions workflow ``.github/workflows/ci.yml`` runs two Linux
 variants of these public release gates:

docs/sphinx/writer_target_contract.rst

@@ -51,6 +51,123 @@ inject the target profile. The Python binding exposes the same structure as
 command wrappers expose matching ``--target-*`` flags for smoke tests and
 file-helper integration checks.
 
+For coarse transfer safety, use ``TransferProfile::safety``. The default
+``CompatibleFile`` mode is for metadata repackage or recompression into a
+compatible target and preserves source camera/color metadata after the
+target-owned image-layout filter above. ``RenderedImage`` is for exports whose
+pixels may have changed, including RAW-to-rendered outputs. It keeps general
+descriptive metadata, time fields, GPS, IPTC, and portable XMP, but filters
+source raw color calibration, linearization/crop/correction tags, camera raw
+settings XMP, source ICC profiles, MakerNotes, and non-C2PA JUMBF data. Host
+code should provide target-correct ICC/profile data and image specs separately.
+
+.. _transfer-safety-matrix:
+
+Transfer Safety Matrix
+----------------------
+
+The table below is the public coarse policy for automatic transfer. It is not
+a privacy policy and it is not a replacement for application-specific metadata
+controls. Hosts may still strip more metadata.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 28 18 18 18
+
+   * - Metadata group
+     - Examples
+     - ``CompatibleFile``
+     - ``RenderedImage``
+     - Notes
+   * - General descriptive metadata
+     - title, description, creator, artist, copyright, rating, label, keywords
+     - Keep
+     - Keep
+     - Safe because it describes the asset or authorship rather than the source
+       pixel encoding.
+   * - Capture time
+     - ``DateTimeOriginal``, ``CreateDate``, subsecond fields, timezone offset
+       fields, GPS time
+     - Keep
+     - Keep
+     - If the output represents a new capture or synthetic composition, host
+       policy should replace or strip these values.
+   * - Camera and lens acquisition facts
+     - ``Make``, ``Model``, ``LensModel``, exposure time, f-number, ISO, focal
+       length, flash, metering mode
+     - Keep
+     - Keep
+     - These are safe as capture facts. They are not treated as processing
+       instructions.
+   * - Location and IPTC editorial fields
+     - EXIF GPS, XMP GPS aliases, IPTC location, caption, byline, credit,
+       rights, job/reference fields
+     - Keep
+     - Keep
+     - Privacy-sensitive data is intentionally left to host policy.
+   * - Portable XMP
+     - Dublin Core, XMP Rights, IPTC Extension, generated EXIF/IPTC projections
+     - Keep after image-layout filtering
+     - Keep after image-layout and rendered-safety filtering
+     - XMP properties from raw-processing namespaces are handled separately
+       below.
+   * - Target image layout and storage
+     - width, height, orientation, samples per pixel, bits per sample, sample
+       format, photometric interpretation, compression, rows/strips/tiles,
+       offsets, byte counts, thumbnail/interchange offsets
+     - Target-owned; source values filtered
+     - Target-owned; source values filtered
+     - Host code must preserve target values or provide
+       ``target_image_spec``.
+   * - Output color/profile metadata
+     - ICC profile blocks, EXIF/XMP ``ColorSpace``, color-space aliases,
+       Photoshop ICC profile name
+     - Keep only when the source profile is valid for the target pixel buffer
+     - Drop source ICC/profile facts; host writes target profile
+     - Rendered exports often need a new output profile such as sRGB, Display
+       P3, or a host-managed working/output profile.
+   * - RAW/DNG sensor and color pipeline
+     - CFA pattern, black/white levels, linearization tables,
+       ``ColorMatrix*``, ``ForwardMatrix*``, ``CameraCalibration*``,
+       ``AsShotNeutral``, DNG private/profile tags
+     - Keep only for compatible RAW/DNG-style transfer
+     - Drop
+     - These values describe how to turn original sensor data into rendered
+       color. Reusing them on already-rendered pixels can make CMS or editors
+       apply the raw transform twice.
+   * - RAW crop, geometry, and correction data
+     - ``ActiveArea``, ``DefaultCrop*``, masked areas, opcode lists,
+       distortion/vignetting/camera-profile correction data
+     - Keep only for compatible RAW/DNG-style transfer
+     - Drop
+     - These values are tied to the original sensor geometry and raw-processing
+       pipeline.
+   * - Camera raw settings XMP
+     - ``crs:*`` development settings and raw-edit recipe metadata
+     - Keep
+     - Drop
+     - A rendered file should not normally carry a source raw-edit recipe
+       unless the host intentionally writes a sidecar/workflow record.
+   * - Opaque MakerNote payloads
+     - vendor MakerNote blobs and private nested IFDs
+     - Keep by default, or follow explicit MakerNote policy
+     - Drop
+     - Decoded safe facts can still be carried through standard EXIF/XMP
+       fields; the opaque vendor blob is not copied for rendered outputs.
+   * - C2PA and JUMBF
+     - APP11/JUMBF boxes, C2PA manifests, assertions, signatures
+     - Follow explicit JUMBF/C2PA policy
+     - Drop non-C2PA JUMBF; invalidate C2PA by default if it would otherwise
+       be kept
+     - Pixel-changing exports need a new content binding and signature from
+       the host or signer.
+   * - Embedded previews and thumbnails
+     - TIFF preview pages, SubIFD previews, JPEG interchange thumbnail data
+     - Preserve only within bounded target-owned rewrite rules
+     - Target-owned; host should regenerate or preserve target previews
+     - Source previews commonly describe the source pixels, not the rendered
+       target.
+
 Target Summary
 --------------
 
@@ -266,6 +383,13 @@ targets, OpenMeta can allocate 32-bit item IDs and uses ``infe`` version 3 plus
 existing graph has exhausted the usable item-id space or mixes item-table widths
 outside this shape, the edit fails instead of truncating IDs.
 
+Newly inserted metadata item payloads are appended to the rebuilt ``idat``
+payload. To preserve broad reader compatibility, their ``iloc`` records keep
+construction method 0 and use absolute file-offset extents within the existing
+field widths. When all retained self-contained item locations can be
+represented as absolute extents, OpenMeta compacts the rebuilt ``iloc``
+base-offset field width to zero for simpler reader compatibility.
+
 For bounded ICC transfer, OpenMeta removes prior ICC ``colr/prof`` and
 ``colr/rICC`` properties from ``iprp/ipco``, compacts/remaps existing ``ipma``
 associations, appends the transferred ``colr/prof`` property, and associates it