Require numeric shapes for grouped color/WB/lens

Only promote grouped matrix/vector/table candidates when source payloads meet conservative numeric minimum shapes (e.g. 3x3 matrix -> 9 values, vector set -> 2 values). Implemented numeric-shape checks in metadata_query.cc (append_candidate_numeric_values_min, grouped_candidate_min_numeric_values) and applied them to EXIF/vendor grouping paths. Added role-specific rendered-transfer drop messages for source color transforms, white balance, and lens-correction in metadata_transfer.cc. Updated tests to cover skipping malformed/text-only grouped records and to assert updated safety flags/messages. Bumped VERSION to 0.4.16 and updated documentation to describe the new shape-checked grouping and rendered-transfer diagnostic wording.

Author: ssh4net

CHANGES.md

@@ -1,5 +1,23 @@
 # OpenMeta Changes
 
+## 0.4.16 - 2026-05-20
+
+Changes compared with `0.4.15`.
+
+### Added
+
+- Added stricter grouped color, white-balance, and lens-correction query
+  candidates so matrix sets, vector sets, and lens-correction tables only form
+  from numeric payloads with safe minimum shapes.
+- Added role-specific rendered-transfer diagnostic messages for source color
+  transforms, white balance, and lens correction.
+
+### Changed
+
+- Updated public interpretation and query documentation to describe grouped
+  color/white-balance/lens records as shape-checked inspection/source-bound
+  data.
+
 ## 0.4.15 - 2026-05-19
 
 Changes compared with `0.4.14`.

VERSION

@@ -1 +1 @@
-0.4.15
+0.4.16

docs/api_stability.md

@@ -24,10 +24,10 @@ different status.
 | `ExportNameStyle::FlatHost` | `openmeta/interop_export.h` | Stable | Stable v1 flat host naming contract. See [flat_host_mapping.md](flat_host_mapping.md). |
 | EXIF/TIFF orientation helpers: `interpret_exif_orientation(...)`, `exif_orientation_name(...)`, `exif_orientation_rotation_degrees_cw(...)`, `exif_orientation_rotation_only(...)` | `openmeta/orientation.h` | Stable | Small utility contract for user-facing orientation labels, clockwise rotation degrees, mirrored-state detection, dimension-swap detection, and rotation-only fallbacks. Python exposes the same helpers through thin scalar/dictionary wrappers. |
 | 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, Fujifilm RAF raw crop/zoom rectangles, Canon aspect/crop metadata, Nikon Capture crop bounds, Sony panorama crop margins, 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, source-processing buckets, and per-family vendor MakerNote/RAW white-balance, color, raw-storage, sensor, and source-processing groups. Python `Document` and `TransferSourceSnapshot` mirror this as thin dictionary-returning wrappers. |
+| 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, Fujifilm RAF raw crop/zoom rectangles, Canon aspect/crop metadata, Nikon Capture crop bounds, Sony panorama crop margins, 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, source-processing buckets, and per-family vendor MakerNote/RAW white-balance, color, raw-storage, sensor, and source-processing groups. Matrix/vector/table groups are promoted only when the available numeric payloads meet conservative minimum shapes, so malformed color matrices, white-balance vectors, and lens-correction records remain per-entry inspection data instead of becoming normalized groups. 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 including Fujifilm RAF, Canon, Nikon Capture, and Sony panorama geometry patterns, exposure/gain, color/white-balance, lens-correction, RAW/source-processing records, and grouped vendor-family table/vector records where classification supports them. 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, including normalized DNG, Phase One/Leaf, Fujifilm RAF, Canon, Nikon Capture, and Sony panorama geometry patterns. 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(...)`, `transfer_concept_diagnostic_message(...)` | `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, severity token, default message text, 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 with `severity_name` and `message` fields. |
+| Transfer concept diagnostics: `transfer_concept_diagnostics_from_store(...)`, `transfer_concept_diagnostic_message(...)` | `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, severity token, default message text, conflict flag, source entries, compatible/rendered safety booleans, and GPS altitude-reference presentation fields. Rendered-transfer drop messages distinguish source color transforms, white balance, and lens-correction records from generic source-processing metadata. 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 with `severity_name` and `message` fields. |
 | 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. |

docs/development.md

@@ -18,7 +18,7 @@ model should stay compact:
 | --- | --- | --- |
 | Decoding | Find metadata carriers and decode EXIF, XMP, IPTC, ICC, Photoshop IRB, JUMBF/C2PA, EXR, and related blocks into `MetaStore` entries. | High, about 98-100% for the current target scope. |
 | Interpretation | Normalize names and values, group entries by meaning, and classify source-bound data such as RAW crop, color, lens-correction, sensor, computational capture state, and vendor-private fields. | Medium-high, about 85%. |
-| Query | Find entries by name, fuzzy term, or semantic group, then expose normalized query candidates, structured interpretation records, bounded cross-family concept resolutions, transfer hints, and conflict flags for crop/border/active-area, exposure/gain, color/WB, orientation, date/time, GPS, lens-correction, and RAW/source-processing fields across standard and vendor metadata. | Medium, about 70-76%. |
+| Query | Find entries by name, fuzzy term, or semantic group, then expose normalized query candidates, structured interpretation records, bounded cross-family concept resolutions, transfer hints, and conflict flags for crop/border/active-area, exposure/gain, color/WB, orientation, date/time, GPS, lens-correction, and RAW/source-processing fields across standard and vendor metadata. | Medium, about 72-78%. |
 | Creation | Build fresh metadata entries from host-provided values. | Medium, about 55-65%. |
 | Editing | Modify existing logical metadata entries while preserving valid surrounding structure. | Medium, about 60-70%. |
 | Transfer | Move metadata between files using explicit compatible-file or rendered-image safety policies. | Medium-high, about 80-85%. |
@@ -53,6 +53,9 @@ sensor, and source-processing records. RAW-processing queries add conservative
 groups for black/white levels, linearization tables, CFA/sensor layout, source
 geometry, raw-storage identifiers, and source-private processing buckets.
 Grouped candidates use `matrix_set`, `vector_set`, and `table` value shapes.
+Color matrix sets, white-balance vector sets, and lens-correction tables are
+promoted only when the numeric payloads meet conservative minimum shapes; other
+records stay visible as per-entry matches/candidates.
 When
 `OPENMETA_ENABLE_RAPIDFUZZ=ON`, the same query helpers also use RapidFuzz to
 score near-miss XMP/property paths; default builds keep the deterministic

docs/host_integration.md

@@ -57,7 +57,10 @@ canonical origin, size, rect, and margin fields when available, including
 known DNG, Phase One/Leaf, Fujifilm RAF, Canon, Nikon Capture, and Sony
 panorama geometry patterns. Color/white balance, lens-correction, and
 RAW-processing candidates expose full normalized value vectors for grouped
-matrix/vector/table records. Date/time candidates
+matrix/vector/table records when the source payloads satisfy conservative
+numeric shape checks. Malformed or text-only source records remain visible as
+individual metadata, but they are not promoted into normalized grouped color,
+white-balance, or lens-correction candidates. 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
@@ -72,8 +75,10 @@ hint: `safe`, `source_bound`, `rendered_unsafe`, or
 previews, `transfer_concept_diagnostics_from_store(...)` converts those hints
 into keep/drop/requires-target-image-spec actions for a selected
 `TransferSafetyMode`, plus stable severity tokens and default message text for
-host UI. Hosts can localize or replace the wording, but they do not need to
-invent the basic safe/drop/rewrite reasons.
+host UI. Rendered-transfer drop messages distinguish source color transforms,
+white balance, lens correction, source-bound RAW processing, and target-owned
+image properties. Hosts can localize or replace the wording, but they do not
+need to invent the basic safe/drop/rewrite reasons.
 
 ## Adapter Classes