Add exposure/gain concept resolver and docs

Bump version to 0.4.18 and introduce experimental exposure/gain concept resolution. Adds a new MetadataConceptKind::Exposure and roles (exposure_time, aperture, iso_sensitivity, exposure_bias, exposure_program, gain, raw_exposure_adjustment), maps EXIF/XMP/DNG tags and query-backed interpretation records into these roles, and promotes capture exposure facts as safe while marking raw/DNG exposure adjustments rendered-unsafe. Exposes the new kind and roles via the Python bindings, updates interpretation/host-integration/query docs and changelog, and updates tests to cover the new behavior.

Author: ssh4net

CHANGES.md

@@ -1,5 +1,24 @@
 # OpenMeta Changes
 
+## 0.4.18 - 2026-05-20
+
+Changes compared with `0.4.17`.
+
+### Added
+
+- Added an experimental exposure/gain concept resolver that maps
+  query-backed exposure records into exposure time, aperture, ISO sensitivity,
+  exposure bias, exposure program, gain, and raw exposure-adjustment roles.
+- Added conservative transfer hints for exposure concepts: capture exposure
+  facts remain safe, while raw/DNG exposure adjustment fields are marked
+  unsafe for rendered-image transfer.
+- Exposed the new exposure concept and roles through the Python bindings.
+
+### Changed
+
+- Updated public interpretation and host-integration documentation for
+  exposure/gain concept coverage and rendered-transfer safety behavior.
+
 ## 0.4.17 - 2026-05-20
 
 Changes compared with `0.4.16`.

VERSION

@@ -1 +1 @@
-0.4.17
+0.4.18

docs/api_stability.md

@@ -26,7 +26,7 @@ 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, 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. Long-tail source color/style aliases such as camera-to-XYZ/RGB matrices, creative/picture style, film simulation, dynamic-range, optical-correction, and raw-development terms are classified for query and transfer-policy inspection. 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. |
+| 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, normalized exposure values, and same-role conflicts for orientation, date/time, exposure/gain, color/profile, GPS, geometry, lens-correction, and RAW-processing evidence across EXIF, XMP, IPTC, ICC, PNG text, and query-backed interpretation records where applicable. Exposure candidates cover exposure time, aperture, ISO sensitivity, exposure bias, exposure program, gain, and raw exposure-adjustment roles; capture exposure facts are safe, while raw/DNG exposure adjustments stay rendered-unsafe. 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. 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-style processing, and FLIR radiometric/raw-value buckets. Long-tail aliases cover source color/style, camera-to-XYZ/RGB matrix, white-balance gain, optical/lens correction, dynamic-range, and raw-development terms. 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. |

docs/development.md

@@ -17,7 +17,7 @@ model should stay compact:
 | Area | Purpose | Readiness |
 | --- | --- | --- |
 | 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%. |
+| Interpretation | Normalize names and values, group entries by meaning, and classify source-bound data such as RAW crop, exposure adjustment, color, lens-correction, sensor, computational capture state, and vendor-private fields. | Medium-high, about 86%. |
 | 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 73-79%. |
 | 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%. |
@@ -52,6 +52,10 @@ form per-family grouped candidates for white balance, color, raw-storage,
 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.
+Exposure/gain concept resolution promotes exposure time, aperture, ISO,
+exposure bias, exposure program, gain, and raw exposure-adjustment records into
+host-visible roles, with raw exposure adjustments kept unsafe for rendered
+targets.
 Current source-private aliases include camera-to-XYZ/RGB matrices, creative and
 picture styles, film simulation, dynamic-range processing, optical/lens
 correction, white-balance gains, and raw-development terms.
@@ -74,15 +78,16 @@ into records with query class, semantic kind, normalized shape, confidence,
 source entries, and normalized geometry/value arrays where available.
 
 For cross-family duplicated concepts, use `openmeta/metadata_concepts.h`.
-It currently resolves orientation, date/time, color/profile, GPS, geometry,
-lens-correction, and RAW-processing into candidate lists with candidate source
-entries, source families, preferred entries, normalized compare keys, parsed
-date/time fields, date/time precision, timezone kind, GPS altitude-reference
-state, canonical geometry origin/size/rect/margins, full normalized value
-vectors for grouped matrix/vector/table records, transfer hints, compatible and
-rendered safety booleans, and same-role conflict flags. This is deliberately
-an inspection/policy surface; host code still decides whether a conflict should
-be shown, ignored, or corrected during editing/transfer.
+It currently resolves orientation, date/time, exposure/gain, color/profile,
+GPS, geometry, lens-correction, and RAW-processing into candidate lists with
+candidate source entries, source families, preferred entries, normalized
+compare keys, parsed date/time fields, date/time precision, timezone kind, GPS
+altitude-reference state, canonical geometry origin/size/rect/margins,
+normalized exposure values, full normalized value vectors for grouped
+matrix/vector/table records, transfer hints, compatible and rendered safety
+booleans, and same-role conflict flags. This is deliberately an
+inspection/policy surface; host code still decides whether a conflict should be
+shown, ignored, or corrected during editing/transfer.
 
 ## Build Prerequisites
 

docs/host_integration.md

@@ -50,17 +50,21 @@ confidence, and normalized geometry/value arrays.
 
 For host code that needs to reconcile duplicated concepts across metadata
 families, use `metadata_concepts.h`. It reports orientation, date/time,
-color/profile, GPS, geometry, lens-correction, and RAW-processing candidates
-with source families, preferred entries, and same-role conflict flags. Geometry
-candidates expose crop, active-area, border, and sensor-geometry roles with
-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 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
+exposure/gain, color/profile, GPS, geometry, lens-correction, and
+RAW-processing candidates with source families, preferred entries, and
+same-role conflict flags. Exposure candidates expose capture facts such as
+exposure time, aperture, ISO, exposure bias, exposure program, and gain as
+safe transfer facts, while raw/DNG exposure adjustment fields remain unsafe for
+rendered-image transfer. Geometry candidates expose crop, active-area, border,
+and sensor-geometry roles with 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 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
@@ -103,7 +107,8 @@ OpenMeta splits host integration surfaces deliberately:
   `metadata_interpretation.h` for query-backed semantic records
 - concept-resolution utility:
   `metadata_concepts.h` for cross-family orientation, date/time, color/profile,
-  GPS, geometry, lens-correction, and RAW-processing conflict inspection
+  exposure/gain, GPS, geometry, lens-correction, and RAW-processing conflict
+  inspection
 
 ## 1. Read Into `MetaStore`