Add metadata capability query API and bindings

ssh4net · ssh4net · commit 82cdc5d0ef06 · 2026-04-23T20:01:49.000+09:00
Introduce a runtime capability query API for host integrations: adds C++ header and implementation (MetadataCapability, families, support levels, helpers) to report read/structured_decode/transfer_prepare/target_edit/raw_preservation per format/family and a stable contract version. Adds Python bindings to expose enums and a dict-shaped query result, updates CMake to build the sources and tests, and adds comprehensive unit tests and smoke-test coverage. Updates documentation and sphinx pages with usage examples and notes about support states (unsupported/supported/bounded/disabled) and build-time XMP disabling when XML support is absent.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -256,6 +256,7 @@ set(OPENMETA_SOURCES
   src/openmeta/jumbf_decode.cc
   src/openmeta/libraw_adapter.cc
   src/openmeta/meta_key.cc
+  src/openmeta/metadata_capabilities.cc
   src/openmeta/metadata_transfer.cc
   src/openmeta/meta_store.cc
   src/openmeta/meta_edit.cc
@@ -608,6 +609,7 @@ if(OPENMETA_BUILD_TESTS)
     tests/interop_export_test.cc
     tests/dji_app4_decode_test.cc
     tests/makernote_decode_test.cc
+    tests/metadata_capabilities_test.cc
     tests/metadata_transfer_api_test.cc
     tests/flir_fff_decode_test.cc
     tests/meta_store_test.cc
diff --git a/docs/host_integration.md b/docs/host_integration.md
@@ -321,7 +321,40 @@ Python now exposes those same split path/state controls directly:
 `xmp_existing_destination_embedded_path`, and
 `xmp_existing_destination_sidecar_state`.
 
-## 7. Use The Optional Adobe DNG SDK Bridge
+## 7. Query Runtime Capabilities
+
+Hosts can ask OpenMeta what the current build supports before wiring format
+menus, warnings, or integration feature flags.
+
+```cpp
+#include "openmeta/metadata_capabilities.h"
+
+openmeta::MetadataCapability cap = openmeta::metadata_capability(
+    openmeta::TransferTargetFormat::Avif,
+    openmeta::MetadataCapabilityFamily::Xmp);
+
+if (openmeta::metadata_capability_available(cap.target_edit)) {
+    // The current build can edit AVIF XMP within the reported support level.
+}
+```
+
+Each operation reports one of `unsupported`, `supported`, `bounded`, or
+`disabled`. `bounded` means the capability exists within OpenMeta's documented
+contract, not that it is arbitrary metadata-editor parity. `disabled` is used
+for compile-time-disabled support such as XMP decode when XML support is not
+available.
+
+Python exposes the same query:
+
+```python
+cap = openmeta.metadata_capability(
+    openmeta.TransferTargetFormat.Avif,
+    openmeta.MetadataCapabilityFamily.Xmp,
+)
+print(cap["target_edit_name"])
+```
+
+## 8. Use The Optional Adobe DNG SDK Bridge
 
 If OpenMeta was built with `OPENMETA_WITH_DNG_SDK_ADAPTER=ON`, you can use the
 optional SDK bridge in two ways.
@@ -355,7 +388,7 @@ 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.
 
-## 8. Build `MetaStore` Yourself
+## 9. Build `MetaStore` Yourself
 
 If your application creates metadata directly, build the store first and then
 reuse the same export and transfer APIs.
diff --git a/docs/metadata_support.md b/docs/metadata_support.md
@@ -14,6 +14,11 @@ It is meant to answer four basic questions:
 - `Partial`: supported, but still bounded or best-effort
 - `No`: not supported yet
 
+Host integrations can query the same kind of runtime support information with
+`openmeta/metadata_capabilities.h`. That API reports read, structured decode,
+transfer preparation, target edit, and raw-preservation support by target
+format and metadata family.
+
 ## Coverage Snapshot
 
 Current tracked-gate status:
diff --git a/docs/metadata_transfer_plan.md b/docs/metadata_transfer_plan.md
@@ -777,7 +777,7 @@ writer-confidence slice above; it should be sequenced around it.
 
 #### Near-Term Host Contract Work
 
-- [ ] add a small runtime capability query API for read, structured decode,
+- [x] add a small runtime capability query API for read, structured decode,
   transfer preparation, and target edit support by format and metadata family
 - [ ] mark public host-facing APIs with stability levels such as stable,
   experimental, or internal; start with `visit_metadata(...)`, snapshot
diff --git a/docs/quick_start.md b/docs/quick_start.md
@@ -286,7 +286,39 @@ The Python snapshot helpers intentionally cover the core transfer/edit/persist
 path. The older `transfer_probe(...)` / `unsafe_transfer_probe(...)` entry
 points remain the broader artifact-dump/debug surface.
 
-## 8. Prepare Metadata For Host-Owned Encoders
+## 8. Check Runtime Capabilities
+
+Use the capability API before enabling format/family operations in a host UI
+or integration layer.
+
+```cpp
+#include "openmeta/metadata_capabilities.h"
+
+const openmeta::MetadataCapability cap = openmeta::metadata_capability(
+    openmeta::TransferTargetFormat::Avif,
+    openmeta::MetadataCapabilityFamily::Xmp);
+
+if (openmeta::metadata_capability_available(cap.target_edit)) {
+    // The current build can edit AVIF XMP within the reported support level.
+}
+```
+
+Each operation reports `unsupported`, `supported`, `bounded`, or `disabled`.
+`bounded` means the capability exists within OpenMeta's documented contract.
+`disabled` is used for compile-time-disabled support such as XMP decode when
+XML support is not available.
+
+Python exposes the same query:
+
+```python
+cap = openmeta.metadata_capability(
+    openmeta.TransferTargetFormat.Avif,
+    openmeta.MetadataCapabilityFamily.Xmp,
+)
+print(cap["target_edit_name"])
+```
+
+## 9. Prepare Metadata For Host-Owned Encoders
 
 Some applications do not want a file helper. They already own the encoder or
 the output container and just want OpenMeta to prepare metadata bytes.
@@ -375,7 +407,7 @@ transfer path is designed for that kind of integration through
 For fuller C++ host-side examples, see
 [host_integration.md](host_integration.md).
 
-## 9. Optional Adobe DNG SDK Bridge
+## 10. Optional Adobe DNG SDK Bridge
 
 If OpenMeta was built with `OPENMETA_WITH_DNG_SDK_ADAPTER=ON`, you can update
 an existing DNG file through the Adobe SDK bridge:
@@ -390,7 +422,7 @@ openmeta::ApplyDngSdkMetadataFileResult result =
 This is for applications that already use the Adobe DNG SDK. It is not a raw
 image encoder.
 
-## 10. CLI And Python Are Convenience Layers
+## 11. CLI And Python Are Convenience Layers
 
 The CLI and Python bindings are useful, but they are thin layers over the same
 public C++ APIs.
@@ -413,7 +445,7 @@ print(doc.entry_count)
 PY
 ```
 
-## 11. Pick The Next Doc
+## 12. Pick The Next Doc
 
 - Detailed read support:
   [metadata_support.md](metadata_support.md)
diff --git a/docs/sphinx/host_integration.rst b/docs/sphinx/host_integration.rst
@@ -284,6 +284,40 @@ Python now exposes those same split path/state controls directly:
 ``xmp_existing_destination_embedded_path``, and
 ``xmp_existing_destination_sidecar_state``.
 
+Query runtime capabilities
+--------------------------
+
+Hosts can ask OpenMeta what the current build supports before wiring format
+menus, warnings, or integration feature flags.
+
+.. code-block:: cpp
+
+   #include "openmeta/metadata_capabilities.h"
+
+   openmeta::MetadataCapability cap = openmeta::metadata_capability(
+       openmeta::TransferTargetFormat::Avif,
+       openmeta::MetadataCapabilityFamily::Xmp);
+
+   if (openmeta::metadata_capability_available(cap.target_edit)) {
+       // The current build can edit AVIF XMP within the reported support level.
+   }
+
+Each operation reports one of ``unsupported``, ``supported``, ``bounded``, or
+``disabled``. ``bounded`` means the capability exists within OpenMeta's
+documented contract, not that it is arbitrary metadata-editor parity.
+``disabled`` is used for compile-time-disabled support such as XMP decode when
+XML support is not available.
+
+Python exposes the same query:
+
+.. code-block:: python
+
+   cap = openmeta.metadata_capability(
+       openmeta.TransferTargetFormat.Avif,
+       openmeta.MetadataCapabilityFamily.Xmp,
+   )
+   print(cap["target_edit_name"])
+
 Optional Adobe DNG SDK bridge
 -----------------------------
 
diff --git a/docs/sphinx/quick_start.rst b/docs/sphinx/quick_start.rst
@@ -243,6 +243,39 @@ The Python snapshot helpers intentionally cover the core transfer/edit/persist
 path. The older ``transfer_probe(...)`` / ``unsafe_transfer_probe(...)``
 entry points remain the broader artifact-dump/debug surface.
 
+Check runtime capabilities
+--------------------------
+
+Use the capability API before enabling format/family operations in a host UI
+or integration layer.
+
+.. code-block:: cpp
+
+   #include "openmeta/metadata_capabilities.h"
+
+   const openmeta::MetadataCapability cap = openmeta::metadata_capability(
+       openmeta::TransferTargetFormat::Avif,
+       openmeta::MetadataCapabilityFamily::Xmp);
+
+   if (openmeta::metadata_capability_available(cap.target_edit)) {
+       // The current build can edit AVIF XMP within the reported support level.
+   }
+
+Each operation reports ``unsupported``, ``supported``, ``bounded``, or
+``disabled``. ``bounded`` means the capability exists within OpenMeta's
+documented contract. ``disabled`` is used for compile-time-disabled support
+such as XMP decode when XML support is not available.
+
+Python exposes the same query:
+
+.. code-block:: python
+
+   cap = openmeta.metadata_capability(
+       openmeta.TransferTargetFormat.Avif,
+       openmeta.MetadataCapabilityFamily.Xmp,
+   )
+   print(cap["target_edit_name"])
+
 Next steps
 ----------
 
diff --git a/src/include/openmeta/metadata_capabilities.h b/src/include/openmeta/metadata_capabilities.h
@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include "openmeta/metadata_transfer.h"
+
+#include <cstdint>
+
+/**
+ * \file metadata_capabilities.h
+ * \brief Runtime capability query API for host integrations.
+ */
+
+namespace openmeta {
+
+/// Stable metadata capability contract version.
+inline constexpr uint32_t kMetadataCapabilitiesContractVersion = 1U;
+
+/// Metadata family used by \ref metadata_capability.
+enum class MetadataCapabilityFamily : uint8_t {
+    Exif,
+    Xmp,
+    Icc,
+    Iptc,
+    MakerNote,
+    PhotoshopIrb,
+    Jumbf,
+    C2pa,
+    BmffFields,
+    GeoTiff,
+    ExrAttribute,
+};
+
+/// Support level for one operation in \ref MetadataCapability.
+enum class MetadataCapabilitySupport : uint8_t {
+    Unsupported,
+    Supported,
+    Bounded,
+    Disabled,
+};
+
+/// Capability record for one format/family pair.
+struct MetadataCapability final {
+    TransferTargetFormat format = TransferTargetFormat::Jpeg;
+    MetadataCapabilityFamily family = MetadataCapabilityFamily::Exif;
+
+    MetadataCapabilitySupport read = MetadataCapabilitySupport::Unsupported;
+    MetadataCapabilitySupport structured_decode
+        = MetadataCapabilitySupport::Unsupported;
+    MetadataCapabilitySupport transfer_prepare
+        = MetadataCapabilitySupport::Unsupported;
+    MetadataCapabilitySupport target_edit
+        = MetadataCapabilitySupport::Unsupported;
+
+    /// Existing raw-carrier preservation in current transfer flows. This does
+    /// not imply raw-preserving source snapshots.
+    MetadataCapabilitySupport raw_preservation
+        = MetadataCapabilitySupport::Unsupported;
+};
+
+const char*
+metadata_capability_family_name(MetadataCapabilityFamily family) noexcept;
+
+const char*
+metadata_capability_support_name(MetadataCapabilitySupport support) noexcept;
+
+bool
+metadata_capability_available(MetadataCapabilitySupport support) noexcept;
+
+MetadataCapability
+metadata_capability(TransferTargetFormat format,
+                    MetadataCapabilityFamily family) noexcept;
+
+}  // namespace openmeta
+
diff --git a/src/openmeta/metadata_capabilities.cc b/src/openmeta/metadata_capabilities.cc
diff --git a/src/python/src/openmeta_module.cc b/src/python/src/openmeta_module.cc
diff --git a/tests/metadata_capabilities_test.cc b/tests/metadata_capabilities_test.cc
diff --git a/tests/python_transfer_probe_smoke_test.cmake b/tests/python_transfer_probe_smoke_test.cmake
