Add the OG-Core coupling engine (Linker-Reverse pass)

[Adityakushwaha2006]

Parent Issue : #538 | Relates to Solution of Stage 1 - Reverse Pass

Dependency

Stack on top of PR #498, #520 & #537 .

Summary

• What changed: adds the reverse direction of the coupling. After a coupled run solves OG-Core, this
  reads OG-Core's demand feedback, turns it into an absolute change on the CLEWS case, applies it through the
  existing /oglink/applyPatch seam, and reports the re-solved CLEWS result. The forward pass sends an energy
  price into the economy; this sends the economy's demand response back into the energy model.

This is the other half of one coupling pass. It builds on the forward pass (537) and the applyPatch seam,
and it stops at a single pass.

Where this sits

flowchart LR
  CLEWS["CLEWS<br/>energy, land, water model"]
  OGC["OG-Core<br/>macroeconomy model"]

  subgraph LINK["The linker add-on"]
    direction TB
    F["FORWARD PASS<br/>energy price and costs to macro results<br/>(done)"]:::done
    B["REVERSE PASS<br/>macro demand back to energy inputs<br/>(this PR)"]:::now
    L["CONVERGENCE LOOP<br/>repeat until both models agree<br/>(later)"]:::later
  end

  CLEWS -->|price, emissions, capex| F
  F -->|run in its own env| OGC
  OGC -->|activity demand ratio| B
  B -->|clews_patch.json to applyPatch| CLEWS
  F -.-> L
  B -.-> L

  classDef done fill:#e7eff7,stroke:#5a86b3,color:#1f3a56;
  classDef now fill:#d3f5df,stroke:#1f9d57,color:#0f3d22;
  classDef later fill:#eeeeee,stroke:#999999,color:#555555;
  style LINK fill:none,stroke:#555555,stroke-dasharray:6 5

Loading

How it works, step by step

1. Start from a finished coupled run. The forward pass leaves a per-year demand feedback (the reform to
   base ratio of the economy's activity). The reverse pass reads that ratio straight from the run folder.
2. Read the case's base demand. It reads the base annual demand for the target commodity from the case,
   the same rows the seam will overwrite, so the value it scales and the value that gets set are the same.
3. Turn the ratio into an absolute demand. For each forecast year it computes base demand times the ratio.
   It targets the household final-demand commodity that actually carries load, only for years at or after the
   model start year, and skips any year the change would leave unchanged.
4. Build the change list and post it. It writes a small clews_patch.json of absolute values and posts it
   to /oglink/applyPatch over HTTP. Nothing is written into the case directly.
5. The seam does the safe re-solve. applyPatch copies the case, validates every change before writing,
   regenerates the datafile, checks the structure did not change, solves, and returns the results folder.
6. Report. It prints the copied case, the new caserun, and the results path, and it treats any no-op
   warning from the seam as a failure, since that means the base demand it read had drifted.

Validation

• Unit tests (fast, no server, no solve). The patch builder is covered on known inputs: ratio to absolute,
  year clipping, no-op suppression, the all-zero base guard, the guard against zeroing a live cell, the
  discount-rate deferral, and the change shape. The HTTP client is covered for the success path, a blocked
  patch (the seam's reasons are surfaced), and an unreachable server.
• End to end on a real case (dry run). A build against the bundled demo case confirms the emitted values
  equal base demand times the ratio and that the change list is well formed, with no network call.
• Opt-in live round-trip. A slow test posts to a running app and checks the re-solve; it skips cleanly when
  no app URL is set, so the default test run stays fast and server-free.
• Isolation confirmed. The new modules import no OG-Core, no app code, and no third-party HTTP library, and
  every module still imports with OG-Core absent.

Notes for review

• Depends on the forward-pass PR (which ships the package and produces the demand feedback) and the
  applyPatch seam. It targets main once both land.
• Two small confirmations, neither blocking. The demand target is the household final-demand commodity
  rather than the price-facing code; and the demand driver is the sector-output ratio. Both follow the
  established behaviour and are one-line settings if preferred otherwise.
• Discount rate is deferred currently. The economy's equilibrium rate is a region-level parameter, which
  the seam's change model (single-entity year tables) cannot express. It is recorded as a deferred note to be
  taken up at the coupling stage.

Checklist

• Change is scoped — no unrelated refactors
• Builds on the forward pass and the applyPatch seam; targets EAPD-DRB/MUIOGO:main
• Docs updated for any setup, workflow, or architecture change

Note on the True Diff :

• 8 files / ~690 lines : visible cleanly on main once all predecessor PRs are merged.