Canonical v5.5 Metadata Adapter & Extraction Engine

[brightyorcerf]

Linked issue

• Closes [Task] [Proposal/Architecture] Canonical CLEWS Result Extraction & Validation Layer for OG-Core Integration #348, Addresses [Task] Fix result metadata and shadow-price rendering from MUIO v5.5 #392
• Related Draft: PoC - Canonical CLEWS Result Extraction for OG-Core Integration #349, fix: adopt v5.5 result metadata and register missing result groups (#392) #405, [v5.5] Fix result metadata and shadow-price rendering (align with upstream Variables.json) #406
• Supersedes Draft: PoC - Canonical CLEWS Result Extraction for OG-Core Integration #349 (after discussion)

Existing related work reviewed

• Issues/PRs reviewed: Issues/PRs reviewed: Draft: PoC - Canonical CLEWS Result Extraction for OG-Core Integration #349, fix: adopt v5.5 result metadata and register missing result groups (#392) #405, [v5.5] Fix result metadata and shadow-price rendering (align with upstream Variables.json) #406

Overlap assessment

• Classification: backend (Metadata Adapter & Extraction Engine)
• Overlapping items: Supersedes Draft: PoC - Canonical CLEWS Result Extraction for OG-Core Integration #349; Alternatives to fix: adopt v5.5 result metadata and register missing result groups (#392) #405/[v5.5] Fix result metadata and shadow-price rendering (align with upstream Variables.json) #406.
• Why this is not duplicate/superseded: This PR moves from the static "PoC" state of Draft: PoC - Canonical CLEWS Result Extraction for OG-Core Integration #349 to a production-ready, metadata-driven architecture. Unlike fix: adopt v5.5 result metadata and register missing result groups (#392) #405/406, which use manual string-mapping and invasive if/else logic in the UI, this PR implements a backend Metadata Resolver that treats the upstream Variables.json as the dynamic source of truth, eliminating the need for manual maintenance as OSeMOSYS versions evolve.

Why this PR should proceed

This PR provides the canonical backend implementation for #392. It successfully adopts the upstream Variables.json as the source of truth for result extraction and metadata resolution, fulfilling the core architectural requirements for the v5.5 stability track. By moving the 'knowledge' of result groups and units into a dynamic MetadataResolver, we eliminate local reinterpretation and prepare the codebase for consistent frontend rendering

Summary

What changed:

• Introduced a singleton MetadataResolver to dynamically parse Variables.json and Units.json.
• Implemented a dimension-agnostic ResultAdapter engine for CBC/GLPK result extraction.
• Added automated Mid-Year discounting math for Shadow Price (DUAL) variables.
• Integrated strict Pathlib enforcement and is_relative_to(Config.DATA_STORAGE) write-protection.

Why: To replace hardcoded variable dictionaries (technical debt) with a reactive system that automatically honors v5.5 metadata and dimensionality.

Validation

• Tests added/updated (Mock suite passes 4/4 assertions covering 4D mapping and security blocks)
• Validation steps documented (Verified via python3.12 -m API.Integration.test_result_adapter)
• Evidence attached (Backend logs confirm SecurityError fires on unauthorized write attempts)

Documentation

• Docs updated in this PR (In-code docstrings for Resolver and Adapter)
• Any setup/workflow changes reflected in repo docs (Uses existing v5.5 Variables.json path)

Scope check

• No unrelated refactors
• Implemented from a feature branch
• Change is deliverable without upstream OSeMOSYS/MUIO dependency
• Base repo/branch is EAPD-DRB/MUIOGO:main (not upstream)

Exception rationale

blank

[brightyorcerf]

Note on the significant diff: Half of it is from the mock test suite (test_result_adapter.py) which proves dimension-agnosticism and verify security guardrails.

To maintain the Stability Track standards, I’ve focused this PR strictly on the Backend Infrastructure.

If this architectural foundation is reviewed/merged, I will submit a follow-up UI PR to bridge the frontend components to this resolver. This ensures a clean, two-stage transition that avoids 'half-ported' inconsistencies in the rendering layer