Nest x-medkit vendor fields on SOVD endpoint payloads

[bburda]

Summary

Migrates the two remaining SOVD-standard endpoint payloads that emit flat
x-medkit-* top-level vendor keys to the nested x-medkit: {...}
convention that every other endpoint already follows.

• GET /updates/{id}/status -> x-medkit.phase (was flat x-medkit-phase)
• GET /apps|components/{id}/configurations -> nested x-medkit.source
  on items, x-medkit.{source,node} on per-parameter entries (was flat
  x-medkit-source / x-medkit-node)

The OpenAPI schemas for UpdateStatus and ConfigurationMetaData now
declare the nested object so generated clients pick up accurate typing.

Adds test_openapi_response_drift - a runtime drift validator that
walks every GET endpoint declared in GET /docs, fetches a real
response, and validates it against the declared response schema. The
original x-medkit-phase divergence slipped past every typed client
because the schema never declared the field; this test catches that
class of regression. The compile-time emitter -> schema contract is
deferred to #338.

---

Issue

• closes Standardize vendor fields on SOVD-endpoint payloads as nested x-medkit object #385

---

Type

• Bug fix
• New feature or tests
• Breaking change
• Documentation only

Breaking on the wire format of two endpoints. Cross-repo grep showed
zero current consumers reading the legacy flat keys (web UI, MCP,
foxglove, demos, generated clients, commercial).

---

Testing

• colcon build --packages-up-to ros2_medkit_gateway ros2_medkit_integration_tests (Jazzy, Release)
• colcon test --packages-select ros2_medkit_gateway --ctest-args -L linter -> green
• ctest -R test_update_manager -> 24/24 passing (UpdateStatusToJson + UpdateManagerFailureTest assertions updated)
• Smoke: GET /api/v1/docs returns UpdateStatus.properties.x-medkit schema with phase enum
• Drift integration test (test_openapi_response_drift) runs in CI - requires python3-jsonschema (added to ros2_medkit_integration_tests/package.xml)

---

Checklist

• Breaking changes are clearly described
• Tests were added or updated if needed
• Docs were updated (docs/api/rest.rst example payload + vendor extension prose)

[Copilot]

Pull request overview

This PR standardizes remaining SOVD-standard payloads to use nested x-medkit: { ... } vendor extensions (instead of flat x-medkit-* keys) and strengthens spec/implementation consistency by adding an integration drift test that validates live GET responses against the runtime OpenAPI 3.1 schema served at /docs.

Changes:

• Migrate update status payload vendor extension from x-medkit-phase to x-medkit.phase and update schema/docs/tests accordingly.
• Migrate configurations payload vendor extension fields to nested x-medkit objects (per-item and per-parameter metadata).
• Add test_openapi_response_drift integration test and the python3-jsonschema test dependency.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/ros2_medkit_integration_tests/test/features/test_openapi_response_drift.test.py	New integration test validating live GET JSON responses against /docs OpenAPI response schemas.
src/ros2_medkit_integration_tests/package.xml	Adds python3-jsonschema as a test dependency for the drift validator.
src/ros2_medkit_gateway/test/test_update_manager.cpp	Updates unit tests to assert nested x-medkit.phase.
src/ros2_medkit_gateway/src/updates/update_manager.cpp	Comment updates to reflect nested vendor extension naming.
src/ros2_medkit_gateway/src/openapi/schema_builder.cpp	Updates OpenAPI schemas to declare nested x-medkit for UpdateStatus + ConfigurationMetaData.
src/ros2_medkit_gateway/src/http/handlers/config_handlers.cpp	Emits nested x-medkit metadata instead of flat x-medkit-source/x-medkit-node.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/updates/update_types.hpp	Switches UpdateStatus JSON serialization to nested x-medkit.phase.
docs/api/rest.rst	Updates REST docs examples/prose for nested x-medkit.phase.

[Copilot]

Pull request overview

This PR standardizes remaining flat x-medkit-* vendor keys on SOVD-standard payloads into the existing nested "x-medkit": {...} convention, updates the runtime OpenAPI schemas accordingly, and adds an integration test intended to detect handler-vs-schema response drift.

Changes:

• Migrate update status vendor field from flat x-medkit-phase to nested x-medkit.phase (code, schema, docs, and tests).
• Migrate configurations vendor fields to nested x-medkit objects (items and per-parameter entries) and update ConfigurationMetaData schema.
• Add test_openapi_response_drift and add python3-jsonschema as an integration-test dependency.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/ros2_medkit_integration_tests/test/features/test_openapi_response_drift.test.py	New integration test that fetches /docs, calls GET endpoints, and validates 200 JSON bodies against response schemas.
src/ros2_medkit_integration_tests/package.xml	Adds python3-jsonschema test dependency for the drift validator.
src/ros2_medkit_gateway/test/test_update_manager.cpp	Updates assertions for nested x-medkit.phase in update-status JSON.
src/ros2_medkit_gateway/src/updates/update_manager.cpp	Updates comments to reflect nested x-medkit.phase convention.
src/ros2_medkit_gateway/src/openapi/schema_builder.cpp	Updates UpdateStatus and ConfigurationMetaData schemas to declare nested x-medkit objects.
src/ros2_medkit_gateway/src/http/rest_server.cpp	Fixes spec response typing for GET /apps/{id}/is-located-on to match actual list payload shape.
src/ros2_medkit_gateway/src/http/handlers/config_handlers.cpp	Emits nested x-medkit objects for aggregated configuration metadata and per-parameter provenance.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/updates/update_types.hpp	Changes update status JSON serialization to emit nested x-medkit.phase.
docs/api/rest.rst	Updates REST docs examples and prose to use nested x-medkit.phase.
.github/workflows/quality.yml	Increases CI job timeout to accommodate cold-cache ASan builds.

[Copilot]

Pull request overview

This PR standardizes remaining SOVD endpoint vendor extensions to the nested "x-medkit": {...} convention (instead of flat x-medkit-* keys), updates the OpenAPI schemas accordingly, and adds an integration test to detect schema/handler response drift.

Changes:

• Migrate update status vendor field from x-medkit-phase to nested x-medkit.phase (payload + schema + tests + docs).
• Migrate configurations vendor fields to nested x-medkit (source on list items; source/node on per-parameter entries in the vendor extension payload).
• Add an integration drift test that validates live GET responses against the runtime /docs JSON Schemas; extend CI timeout to accommodate slower cold-cache ASan runs.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/ros2_medkit_integration_tests/test/features/test_openapi_response_drift.test.py	New integration test that walks GET endpoints from /docs and validates 200 JSON responses against declared schemas; includes a targeted guard for nested x-medkit.phase on update status.
src/ros2_medkit_integration_tests/package.xml	Adds python3-jsonschema as a test dependency to support the drift validator.
src/ros2_medkit_gateway/test/test_update_manager.cpp	Updates unit tests to assert nested x-medkit.phase using contains()/at() (non-mutating access).
src/ros2_medkit_gateway/src/updates/update_manager.cpp	Updates comments to reflect the new nested vendor extension naming.
src/ros2_medkit_gateway/src/openapi/schema_builder.cpp	Updates schemas for UpdateStatus and ConfigurationMetaData to declare nested x-medkit vendor extensions.
src/ros2_medkit_gateway/src/http/rest_server.cpp	Fixes the documented OpenAPI response type for GET /apps/{id}/is-located-on to EntityList (matches actual handler behavior).
src/ros2_medkit_gateway/src/http/handlers/config_handlers.cpp	Migrates configuration vendor keys from flat x-medkit-* to nested x-medkit objects.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/updates/update_types.hpp	Changes update_status_to_json() to emit nested x-medkit.phase instead of flat x-medkit-phase.
docs/api/rest.rst	Updates update status example payload and vendor extension prose to the nested x-medkit.phase format.
.github/workflows/quality.yml	Increases CI timeout from 45 to 60 minutes to avoid cancellations on cold-cache ASan runs.

Comments suppressed due to low confidence (1)

docs/api/rest.rst:1190

• The docs claim GET /updates/{id}/status includes an error object when status is failed, but the gateway currently serializes error as a string (see update_status_to_json() and the OpenAPI UpdateStatus schema). Please update the example/wording here to match the actual wire format so clients don’t implement the wrong type.

   When ``status`` is ``failed``, an ``error`` object is included:

   .. code-block:: json

      {
        "status": "failed",
        "error": {
          "error_code": "internal-error",
          "message": "Download failed: connection timeout"
        }
      }