Add transfer diagnostics, GPS helper & Phase One

Introduce concept-level transfer diagnostics and GPS altitude-reference helper, plus expanded vendor RAW classification and Python bindings. Adds TransferConceptDiagnostic(s) types, enums for action/reason, transfer_concept_diagnostics_from_store(), and name helpers for actions/reasons and GPS altitude reference; implements conversion to Python dicts and exposes snapshot/document methods. Enhances vendor_raw_processing classification (including Phase One/Leaf handling and broader private/computational/lens/sensor tagging). Updates docs, CHANGES, VERSION, and tests to reflect the new APIs and behavior.

Author: ssh4net

CHANGES.md

@@ -1,5 +1,21 @@
 # OpenMeta Changes
 
+## 0.4.11 - 2026-05-15
+
+Changes compared with `0.4.10`.
+
+### Added
+
+- Added concept-based transfer diagnostics so host/UI code can preflight
+  concept candidates as kept, dropped, requiring target image specs, or
+  conflict-bearing under compatible-file or rendered-image safety modes.
+- Added GPS altitude-reference presentation helpers for concept candidates.
+
+### Changed
+
+- Expanded transfer-critical MakerNote/source-processing classification for
+  Nikon, Canon, Sony, Fujifilm, and Phase One/Leaf-style raw-processing terms.
+
 ## 0.4.10 - 2026-05-15
 
 Changes compared with `0.4.9`.

VERSION

@@ -1 +1 @@
-0.4.10
+0.4.11

docs/api_stability.md

@@ -26,8 +26,9 @@ different status.
 | EXIF/TIFF/DNG numeric value names: `exif_tag_numeric_value_name(...)` and focused helpers | `openmeta/exif_value_names.h` | Stable | Small helper contract for common enum-like TIFF/EXIF/DNG numeric values such as compression, photometric interpretation, planar configuration, exposure program, metering mode, light source, flash, color space, white balance, scene capture type, gain control, CFA layout, and DNG calibration illuminants. Unknown values return an empty string and remain lossless numeric metadata. |
 | Semantic metadata query: `query_metadata(...)`, `query_crop_metadata(...)`, focused query helpers, and `metadata_query_fuzzy_search_available()` | `openmeta/metadata_query.h` | Experimental | Query contract for inspection matches plus normalized candidates. Current coverage includes crop/active-area/border margins, exposure/gain, white balance, color, lens correction, orientation, and RAW/source-processing metadata across standard tags, selected DNG tags, fuzzy XMP paths, and vendor RAW-processing classification. Matches report `exact_match`, `fuzzy_match`, and `fuzzy_score` so tools can label exact results separately from RapidFuzz near-miss hits. `OPENMETA_ENABLE_RAPIDFUZZ=ON` adds optional near-miss XMP/property-path scoring. Grouped candidates include `matrix_set`, `vector_set`, and `table` shapes for related non-crop metadata, including RAW black/white levels, linearization, CFA/sensor layout, source geometry, raw-storage identifiers, and source-processing buckets. Python `Document` and `TransferSourceSnapshot` mirror this as thin dictionary-returning wrappers. |
 | Structured metadata interpretation records: `interpret_metadata(...)`, `interpret_metadata_query(...)` | `openmeta/metadata_interpretation.h` | Experimental | Thin structured projection over semantic query candidates. Records carry query class, semantic kind, normalized shape, confidence, source entry ids, and normalized origin/size/rect/margins/value arrays where available. Current scope covers orientation, geometry/crop/border, exposure/gain, color/white-balance, lens-correction, and RAW/source-processing records. Python `Document` and `TransferSourceSnapshot` expose matching dictionary wrappers. |
-| Cross-family concept resolution: `resolve_metadata_concepts(...)`, `resolve_metadata_concept(...)` | `openmeta/metadata_concepts.h` | Experimental | First bounded resolver for duplicated host-facing concepts. Current scope reports candidates, candidate source entries, source families, preferred entries, normalized numeric/text keys, full normalized value vectors, transfer hints, normalized date/time fields, date/time precision, timezone kind, normalized geometry fields, and same-role conflicts for orientation, date/time, color/profile, GPS, geometry, lens-correction, and RAW-processing evidence across EXIF, XMP, IPTC, ICC, PNG text, and query-backed interpretation records where applicable. Geometry candidates cover crop, active area, border, and sensor geometry with canonical origin, size, rect, and margin fields when available. Candidate transfer hints distinguish `safe`, `source_bound`, `rendered_unsafe`, and `requires_target_image_spec` evidence, with compatible-file and rendered-image safety booleans. Color/white-balance, lens-correction, and RAW-processing concepts preserve grouped matrix/vector/table values for host inspection; they do not make source-bound values safe to serialize into rendered targets. GPS date/time is combined from `GPSDateStamp` plus `GPSTimeStamp` when both entries exist, and GPS altitude candidates expose altitude-reference code plus below-sea-level state when reference metadata is present. It is intended for inspection UI and host policy decisions; it does not rewrite metadata or hide ambiguity. Python `Document` and `TransferSourceSnapshot` expose matching dictionary wrappers. |
-| Vendor RAW-processing summaries: `vendor_raw_processing_from_store(...)`, `classify_vendor_raw_processing_field(...)` | `openmeta/vendor_raw_processing.h` | Experimental | Conservative grouped source-RAW/source-processing field summaries for decoded Sony, Canon, Nikon, Fujifilm, Pentax, Panasonic, Olympus, Kodak, Minolta, Sigma, Samsung, Ricoh, Apple, DJI, Google, FLIR, Casio, Sanyo, KyoceraRaw, Reconyx, HP, JVC, GE, Motorola, Nintendo, and Microsoft MakerNotes, including vendor-private, computational, thermal, preview, face-geometry, stitch/panorama, Apple computational capture/HDR/motion, DJI pose/thermal, Google HDR+/shot-log, pixel-shift/multi-shot/composite/auto-lighting source processing, and FLIR radiometric/raw-value buckets. Intended for audit/UI and rendered-transfer safety decisions, not for writing vendor RAW/source-processing values into rendered targets. |
+| Cross-family concept resolution: `resolve_metadata_concepts(...)`, `resolve_metadata_concept(...)` | `openmeta/metadata_concepts.h` | Experimental | First bounded resolver for duplicated host-facing concepts. Current scope reports candidates, candidate source entries, source families, preferred entries, normalized numeric/text keys, full normalized value vectors, transfer hints, normalized date/time fields, date/time precision, timezone kind, normalized geometry fields, and same-role conflicts for orientation, date/time, color/profile, GPS, geometry, lens-correction, and RAW-processing evidence across EXIF, XMP, IPTC, ICC, PNG text, and query-backed interpretation records where applicable. Geometry candidates cover crop, active area, border, and sensor geometry with canonical origin, size, rect, and margin fields when available. Candidate transfer hints distinguish `safe`, `source_bound`, `rendered_unsafe`, and `requires_target_image_spec` evidence, with compatible-file and rendered-image safety booleans. Color/white-balance, lens-correction, and RAW-processing concepts preserve grouped matrix/vector/table values for host inspection; they do not make source-bound values safe to serialize into rendered targets. GPS date/time is combined from `GPSDateStamp` plus `GPSTimeStamp` when both entries exist, and GPS altitude candidates expose altitude-reference code plus below-sea-level state when reference metadata is present; `metadata_concept_gps_altitude_reference_name(...)` provides a stable display token for the reference code. It is intended for inspection UI and host policy decisions; it does not rewrite metadata or hide ambiguity. Python `Document` and `TransferSourceSnapshot` expose matching dictionary wrappers. |
+| Transfer concept diagnostics: `transfer_concept_diagnostics_from_store(...)` | `openmeta/metadata_transfer.h` | Experimental | Preflight view over concept candidates for `TransferSafetyMode`. Each diagnostic reports concept kind/role, transfer hint, keep/drop/requires-target-image-spec action, reason token, conflict flag, source entries, compatible/rendered safety booleans, and GPS altitude-reference presentation fields. Intended for UI previews and host policy messages before calling `prepare_metadata_for_target(...)`; it does not replace the actual transfer filter. Python `Document` and `TransferSourceSnapshot` expose `transfer_concept_diagnostics(...)` dictionaries. |
+| Vendor RAW-processing summaries: `vendor_raw_processing_from_store(...)`, `classify_vendor_raw_processing_field(...)` | `openmeta/vendor_raw_processing.h` | Experimental | Conservative grouped source-RAW/source-processing field summaries for decoded Sony, Canon, Nikon, Fujifilm, Pentax, Panasonic, Olympus, Kodak, Minolta, Sigma, Samsung, Ricoh, Apple, DJI, Google, FLIR, Casio, Sanyo, KyoceraRaw, Reconyx, HP, JVC, GE, Motorola, Nintendo, and Microsoft MakerNotes, including vendor-private, computational, thermal, preview, face-geometry, stitch/panorama, Apple computational capture/HDR/motion, DJI pose/thermal, Google HDR+/shot-log, pixel-shift/multi-shot/composite/auto-lighting source processing, and FLIR radiometric/raw-value buckets. Direct field classification also recognizes decoded Phase One/Leaf RAW-processing tags; use the dedicated Phase One/Leaf helpers for normalized geometry and processing summaries. Intended for audit/UI and rendered-transfer safety decisions, not for writing vendor RAW/source-processing values into rendered targets. |
 | Transfer safety audit: `transfer_safety_audit_from_store(...)` | `openmeta/metadata_transfer.h` | Experimental | Preflight summary of source entries and entries filtered or invalidated by `TransferSafetyMode`, including Sony/Canon/Nikon/Fujifilm/Pentax/Panasonic/Olympus/Kodak/Minolta/Sigma/Samsung/Ricoh/Apple/DJI/Google/FLIR/Casio/Sanyo/KyoceraRaw/Reconyx/HP/JVC/GE/Motorola/Nintendo/Microsoft RAW/source-processing buckets. Intended for diagnostics and host UI before preparing rendered-image transfers. |
 | Raw-carrier passthrough audit: `raw_carrier_passthrough_audit_from_snapshot(...)` | `openmeta/metadata_transfer.h` | Experimental | Diagnostic preflight for opt-in raw carriers. Reports candidate carriers and primary block reasons such as missing payload, target incompatibility, safety filtering, content-bound C2PA, explicit profile policy, missing decoded-entry links, or unsupported carrier kind. Hosts can call it directly before enabling snapshot passthrough. |
 | Source snapshot type and read helpers: `TransferSourceSnapshot`, `read_transfer_source_snapshot_file(...)`, `read_transfer_source_snapshot_bytes(...)`, `build_transfer_source_snapshot(...)` | `openmeta/metadata_transfer.h` | Experimental | Current snapshots are decoded-store-backed by default. Opt-in raw carriers preserve bounded source payload/provenance records and snapshot-local decoded entry ids for host diagnostics and bounded passthrough decisions. Const reuse is safe when callers do not mutate the snapshot and do not share returned result objects across writers. |

docs/host_integration.md

@@ -59,13 +59,17 @@ value vectors for grouped matrix/vector/table records. Date/time candidates
 include parsed date/time fields when the source value is recognizable, plus
 precision and timezone-kind fields. GPS timestamps combine `GPSDateStamp` with
 `GPSTimeStamp` when both are present, and GPS altitude candidates report
-whether `GPSAltitudeRef` marked the height as below sea level. Treat this as an
-inspection and policy input rather than an automatic metadata rewrite decision;
-source-bound color, lens, and RAW-processing values still need rendered-transfer
-safety filtering. Each candidate also carries a transfer hint:
-`safe`, `source_bound`, `rendered_unsafe`, or
+whether `GPSAltitudeRef` marked the height as below sea level; use
+`metadata_concept_gps_altitude_reference_name(...)` for a stable display token.
+Treat this as an inspection and policy input rather than an automatic metadata
+rewrite decision; source-bound color, lens, and RAW-processing values still need
+rendered-transfer safety filtering. Each candidate also carries a transfer
+hint: `safe`, `source_bound`, `rendered_unsafe`, or
 `requires_target_image_spec`, plus `compatible_file_safe` and
-`rendered_image_safe` booleans for host UI and preflight policy.
+`rendered_image_safe` booleans for host UI and preflight policy. For transfer
+previews, `transfer_concept_diagnostics_from_store(...)` converts those hints
+into keep/drop/requires-target-image-spec actions for a selected
+`TransferSafetyMode`.
 
 ## Adapter Classes
 
@@ -624,6 +628,21 @@ if (audit.filtered_raw_color_calibration > 0 ||
     audit.filtered_makernotes > 0) {
     // Show the host/user which source-bound metadata will not be transferred.
 }
+
+openmeta::TransferConceptDiagnostics diagnostics =
+    openmeta::transfer_concept_diagnostics_from_store(
+        store, openmeta::TransferSafetyMode::RenderedImage);
+
+for (size_t i = 0U; i < diagnostics.diagnostics.size(); ++i) {
+    const openmeta::TransferConceptDiagnostic& item =
+        diagnostics.diagnostics[i];
+    const char* action =
+        openmeta::transfer_concept_diagnostic_action_name(item.action);
+    const char* reason =
+        openmeta::transfer_concept_diagnostic_reason_name(item.reason);
+    (void)action;
+    (void)reason;
+}
 ```
 
 Python uses the same family enum:
@@ -635,6 +654,12 @@ if summary["fields_seen"]:
 
 audit = doc.transfer_safety_audit(openmeta.TransferSafetyMode.RenderedImage)
 print(audit["filtered_raw_color_calibration"])
+
+diagnostics = doc.transfer_concept_diagnostics(
+    openmeta.TransferSafetyMode.RenderedImage
+)
+for item in diagnostics["diagnostics"]:
+    print(item["kind_name"], item["role_name"], item["action_name"])
 ```
 
 `metaread` prints

docs/interpretation_status.md

@@ -36,12 +36,12 @@ explicit outcome:
 | Orientation | EXIF/TIFF orientation query, LibRaw flip mapping, generic orientation helpers for index, rotation degrees, mirrored state, dimension swap, rotation-only fallback, human-readable labels, and EXIF-vs-XMP conflict reporting in the LibRaw bridge. | High, about 90-95%. | Higher-level policy for resolving container and host pixel-orientation state remains host-specific. |
 | Geometry, crop, active area, and borders | DNG crop/active-area/masked-area tags, Phase One/Leaf geometry, canonical border margins, vendor RAW-processing geometry buckets, and fuzzy crop/border-style paths are queryable. | Medium-high, about 85-90%. | More vendor-specific normalized rectangles and stronger output contracts for ambiguous multi-tag geometry. |
 | Color, white balance, and matrices | DNG color/calibration/reduction/forward matrix groups, white-balance vector groups, ICC metadata, RAW color/source-processing safety buckets, transfer hints, and cross-family concept candidates with full grouped value vectors are identified. | Medium-high, about 79-87%. | Deeper camera/vendor color science interpretation is intentionally conservative, especially for rendered-image transfer. |
-| Lens correction and RAW processing | Lens-correction groups, black/white levels, linearization, CFA/sensor layout, raw-storage identifiers, vendor RAW/source-processing buckets, transfer hints, and concept candidates with grouped table/vector values are classified for query and transfer safety. | Medium-high, about 76-84%. | Long-tail per-model correction tables and richer numeric normalization. |
-| Vendor MakerNotes | Broad MakerNote naming and source-processing classification exists for common vendors and several live computational/thermal vendors. Unknown entries remain lossless and source-private subgroups distinguish preview, face geometry, computational, thermal, stitch/panorama, pixel-shift, multi-shot, composite, auto-lighting, RAW crop/active-area, source color-transform, lens-correction, and raw-level processing data. | Medium-high, about 79-87%. | ExifTool-style long-tail print conversions, encrypted/custom settings, and per-model private tables. |
+| Lens correction and RAW processing | Lens-correction groups, black/white levels, linearization, CFA/sensor layout, raw-storage identifiers, vendor RAW/source-processing buckets, transfer hints, transfer diagnostics, and concept candidates with grouped table/vector values are classified for query and transfer safety. | Medium-high, about 78-85%. | Long-tail per-model correction tables and richer numeric normalization. |
+| Vendor MakerNotes | Broad MakerNote naming and source-processing classification exists for common vendors and several live computational/thermal vendors. Unknown entries remain lossless and source-private subgroups distinguish preview, face geometry, computational, thermal, stitch/panorama, pixel-shift, multi-shot, composite, auto-lighting, RAW crop/active-area, source color-transform, lens-correction, raw-level processing data, and Phase One/Leaf RAW-processing fields handled by direct classification plus dedicated normalized helpers. | Medium-high, about 80-88%. | ExifTool-style long-tail print conversions, encrypted/custom settings, and per-model private tables. |
 | BMFF item graph, HEIF/AVIF/CR3, JUMBF, and C2PA | BMFF derived fields, item-info rows, bounded relations, primary-linked roles, aux semantics, and draft C2PA/JUMBF structural fields are exposed. | Medium, about 60-70%. | Full BMFF scene modeling and full C2PA manifest/policy semantics. |
 | Photoshop IRB | Raw resources are preserved and a bounded interpreted subset is decoded for fixed-layout resources. | Medium, about 60-70%. | Broader resource-specific interpretation. |
-| Semantic query/search and records | Query helpers expose raw matches, confidence, provenance, value shapes, normalized candidates, canonical crop/active-area rectangles, border margins, source-processing buckets, optional RapidFuzz near-miss matching, structured interpretation records, and bounded cross-family concept resolution for orientation, date/time, color/profile, GPS, geometry, lens-correction, and RAW-processing with parsed date/time fields, timezone/precision classification, combined GPS timestamps, GPS altitude-reference state, canonical geometry origin/size/rect/margins, full grouped value vectors, transfer hints, rendered/compatible safety booleans, and tolerance-aware GPS/color/geometry conflicts. | Medium, about 66-72%. | More long-tail per-model concept aliases and clearer user-facing policy messages. |
-| Transfer-safety classification | Compatible-file versus rendered-image safety policies classify source-specific image geometry, color/profile, RAW-processing, MakerNote, JUMBF/C2PA, and vendor-private data. | High, about 85-90%. | More user-facing diagnostics and additional per-family policy tests. |
+| Semantic query/search and records | Query helpers expose raw matches, confidence, provenance, value shapes, normalized candidates, canonical crop/active-area rectangles, border margins, source-processing buckets, optional RapidFuzz near-miss matching, structured interpretation records, and bounded cross-family concept resolution for orientation, date/time, color/profile, GPS, geometry, lens-correction, and RAW-processing with parsed date/time fields, timezone/precision classification, combined GPS timestamps, GPS altitude-reference state and display token, canonical geometry origin/size/rect/margins, full grouped value vectors, transfer hints, rendered/compatible safety booleans, and tolerance-aware GPS/color/geometry conflicts. | Medium, about 68-74%. | More long-tail per-model concept aliases and clearer user-facing policy messages. |
+| Transfer-safety classification | Compatible-file versus rendered-image safety policies classify source-specific image geometry, color/profile, RAW-processing, MakerNote, JUMBF/C2PA, and vendor-private data, with concept-level diagnostics that report keep/drop/requires-target-image-spec actions before prepare. | High, about 87-91%. | More per-family policy tests and richer host-authored message text. |
 
 ## Competitor Position
 
@@ -57,10 +57,10 @@ outputs.
 
 ## Next Interpretation Priorities
 
-1. Turn concept transfer hints into higher-level user-facing diagnostics for
-   transfer previews and GUI workflows.
-2. Expand GPS policy beyond current coordinate tolerance and altitude-reference
-   state, including unit/reference presentation and cross-family timestamp
+1. Deepen transfer diagnostics into host-authored message templates for GUI
+   workflows.
+2. Expand GPS policy beyond current coordinate tolerance, altitude-reference
+   display, and EXIF timestamp assembly into broader cross-family
    reconciliation.
 3. Expand MakerNote meaning depth in vendor order: Nikon, Canon, Sony,
    Fujifilm, Phase One/Leaf, then remaining active vendors.