Phase 1b: verify_rollback cross-check + packaging

verify_rollback tool: compares our Python rollback EVs to the
MC_V_<nodeId> named ranges ModelChoice writes when it renders a tree
(prefix confirmed from CellWriter.cs). Reports per-node diffs, a
max-abs-diff, and a verdict; flags "not rendered" when no MC_V_ cells
exist. bridge.read_node_values reads those named ranges (read-only).
Unit-tested (match / mismatch / not-rendered); the live cross-check
awaits a real add-in-rendered tree.

Verified: sdist + wheel build clean. 22 unit tests; ruff + mypy clean.
(CI + release workflows are a separate commit pending the `workflow`
token scope to push.)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: vosesoft

README.md

@@ -13,6 +13,7 @@ A sibling to [`modelrisk-mcp`](https://github.com/vosesoftware/modelrisk-mcp): w
 | `list_trees` | List the decision trees in a workbook with node-type counts. |
 | `get_tree` | Full structure of one tree — decision / chance / terminal nodes, branches, probabilities, values. |
 | `roll_up` | Roll the tree back to its expected values and **optimal policy** — the decision recommendation, in plain English. |
+| `verify_rollback` | Cross-check our rollback against the `MC_V_<id>` cells ModelChoice itself wrote — a correctness guarantee when the tree has been rendered. |
 
 Run it: `uv run python -m modelchoice_mcp` (stdio), or wire `modelchoice-mcp` into Claude Desktop like any MCP server.
 
@@ -29,7 +30,7 @@ The Python roller is validated against ModelChoice's own authoritative C# test (
 
 - **Phase 0 (done):** the read + rollback engine — parse `_MC_Store`, reconstruct each tree, roll back to EV + optimal policy. Validated against ModelChoice's own C# rollback test.
 - **Phase 1 (done):** the MCP server — `list_trees`, `get_tree`, `roll_up`, proven live against a real workbook.
-- **Phase 1b:** cross-check rolled-back EVs against the `MC_V_<id>` named ranges; packaging + CI + PyPI; Claude Desktop wiring docs.
+- **Phase 1b (done):** `verify_rollback` cross-checks our EVs against the `MC_V_<id>` named ranges; CI (ruff + mypy + pytest) and a tag-driven PyPI release pipeline; wheel + sdist build. *(First publish awaits a PyPI trusted-publisher; the live `MC_V_` cross-check awaits a real rendered tree.)*
 - **Phase 2:** drive analyses. ModelChoice's analyses (sensitivity, EVPI, EVII, strategy table, robustness) are currently UI/modal-dialog only; the clean path — since we own the source — is to add headless `[ExcelCommand]` entry points mirroring the existing `MC_RiskProfile_Auto`, then invoke + read them via `Application.Run`.
 - **Phase 3:** build/edit trees — write the model JSON into `_MC_Store` and trigger a re-render.
 

src/modelchoice_mcp/bridge.py

@@ -94,3 +94,42 @@ def get_tree(self, sheet_name: str | None = None, workbook: str | None = None) -
     def roll_up(self, sheet_name: str | None = None, workbook: str | None = None) -> RollupResult:
         """Read a tree and return its rolled-back EV + optimal policy."""
         return rollup(self.get_tree(sheet_name, workbook))
+
+    def read_node_values(self, workbook: str | None = None) -> dict[str, float]:
+        """Read the rolled-back expected values ModelChoice itself wrote
+        into the ``MC_V_<nodeId>`` named ranges on the rendered tree
+        sheet(s). Returns ``{nodeId: value}``. These are the add-in's own
+        rollback numbers — comparing them to our Python rollback proves
+        the two agree. Returns an empty dict if the tree hasn't been
+        rendered (named ranges only exist after a render)."""
+        book = self._book(workbook)
+        prefix = "MC_V_"
+        out: dict[str, float] = {}
+
+        name_objs: list[Any] = []
+        try:
+            name_objs.extend(list(book.names))
+        except Exception:
+            pass
+        for sht in book.sheets:
+            try:
+                name_objs.extend(list(sht.names))
+            except Exception:
+                pass
+
+        for nm in name_objs:
+            try:
+                full = str(nm.name)  # may be "MC_V_D" or "Sheet!MC_V_D"
+            except Exception:
+                continue
+            idx = full.find(prefix)
+            if idx < 0:
+                continue
+            node_id = full[idx + len(prefix):]
+            try:
+                val = nm.refers_to_range.value
+            except Exception:
+                continue
+            if isinstance(val, (int, float)) and not isinstance(val, bool):
+                out[node_id] = float(val)
+        return out

src/modelchoice_mcp/schemas.py

@@ -68,3 +68,28 @@ class RollupResponse(BaseModel):
     )
     recommendation: str = Field(description="Plain-English decision recommendation.")
     nodes: list[NodeResultView]
+
+
+class NodeDiff(BaseModel):
+    node_id: str
+    name: str
+    computed: float = Field(description="Our Python rollback EV for this node.")
+    cell: float = Field(description="The MC_V_<nodeId> value ModelChoice wrote.")
+    diff: float = Field(description="computed - cell.")
+
+
+class RollbackVerification(BaseModel):
+    """Cross-check of our Python rollback against the EVs ModelChoice
+    itself wrote into the MC_V_<nodeId> named ranges."""
+
+    name: str
+    rendered: bool = Field(
+        description="True if the tree has MC_V_ cells (i.e. it has been rendered by the add-in)."
+    )
+    compared_count: int = Field(description="Nodes present in both our rollback and the cells.")
+    matches: int
+    max_abs_diff: float = Field(description="Largest |computed - cell| across compared nodes.")
+    mismatches: list[NodeDiff] = Field(
+        default_factory=list, description="Nodes whose values differ beyond the tolerance."
+    )
+    verdict: str

src/modelchoice_mcp/tools.py

@@ -14,8 +14,10 @@
 from modelchoice_mcp.bridge import ModelChoiceBridge
 from modelchoice_mcp.schemas import (
     BranchView,
+    NodeDiff,
     NodeResultView,
     NodeView,
+    RollbackVerification,
     RollupResponse,
     TreeList,
     TreeStructure,
@@ -178,4 +180,76 @@ def roll_up(
     )
 
 
-__all__ = ["get_bridge", "get_tree", "list_trees", "roll_up", "set_bridge_for_testing"]
+@mcp.tool(
+    description=(
+        "ModelChoice: Cross-check our rollback against ModelChoice's own. The "
+        "add-in writes each node's rolled-back EV into an MC_V_<nodeId> named "
+        "range when it renders a tree; this compares those cells to our Python "
+        "rollback and reports any node that differs beyond `tolerance`. A clean "
+        "result is strong evidence the read+rollback is faithful. If the tree "
+        "hasn't been rendered (no MC_V_ cells), `rendered` is false — open the "
+        "tree in ModelChoice so it renders, then re-run."
+    )
+)
+def verify_rollback(
+    tree_name: Annotated[
+        str | None, Field(description="Tree sheet name. Omit for the first tree.")
+    ] = None,
+    workbook_name: str | None = None,
+    tolerance: Annotated[
+        float, Field(gt=0, description="Max allowed |computed - cell| difference. Default 0.01.")
+    ] = 0.01,
+) -> RollbackVerification:
+    bridge = get_bridge()
+    trees = bridge.list_trees(workbook_name)
+    if tree_name is None:
+        tree_name = next(iter(trees))
+    r = rollup(parse_model(trees[tree_name]))
+    cells = bridge.read_node_values(workbook_name)
+
+    common = [nid for nid in r.node_results if nid in cells]
+    mismatches: list[NodeDiff] = []
+    max_abs = 0.0
+    for nid in common:
+        computed = r.node_results[nid].expected_value
+        cell = cells[nid]
+        diff = computed - cell
+        max_abs = max(max_abs, abs(diff))
+        if abs(diff) > tolerance:
+            mismatches.append(
+                NodeDiff(
+                    node_id=nid, name=r.node_results[nid].name,
+                    computed=computed, cell=cell, diff=diff,
+                )
+            )
+
+    rendered = len(cells) > 0
+    matches = len(common) - len(mismatches)
+    if not rendered:
+        verdict = "Tree not rendered — no MC_V_ cells found. Open it in ModelChoice first."
+    elif not common:
+        verdict = "No overlapping node IDs between the model and the rendered cells."
+    elif not mismatches:
+        verdict = f"Rollback verified: all {matches} compared nodes match (max diff {max_abs:.2g})."
+    else:
+        verdict = f"{len(mismatches)} of {len(common)} nodes differ beyond {tolerance}."
+
+    return RollbackVerification(
+        name=tree_name,
+        rendered=rendered,
+        compared_count=len(common),
+        matches=matches,
+        max_abs_diff=max_abs,
+        mismatches=mismatches,
+        verdict=verdict,
+    )
+
+
+__all__ = [
+    "get_bridge",
+    "get_tree",
+    "list_trees",
+    "roll_up",
+    "set_bridge_for_testing",
+    "verify_rollback",
+]

tests/test_tools.py

@@ -9,7 +9,12 @@
 import pytest
 
 from modelchoice_mcp import tools
-from modelchoice_mcp.schemas import RollupResponse, TreeList, TreeStructure
+from modelchoice_mcp.schemas import (
+    RollbackVerification,
+    RollupResponse,
+    TreeList,
+    TreeStructure,
+)
 
 # Ground-truth tree (matches ModelChoice's C# rollback test): EV 50, Option2.
 _MODEL = json.dumps({
@@ -29,12 +34,18 @@
 
 
 class _FakeBridge:
-    def __init__(self, trees: dict[str, str]) -> None:
+    def __init__(
+        self, trees: dict[str, str], node_values: dict[str, float] | None = None
+    ) -> None:
         self._trees = trees
+        self._node_values = node_values or {}
 
     def list_trees(self, workbook: str | None = None) -> dict[str, str]:
         return dict(self._trees)
 
+    def read_node_values(self, workbook: str | None = None) -> dict[str, float]:
+        return dict(self._node_values)
+
 
 @pytest.fixture
 def bridge() -> Iterator[_FakeBridge]:
@@ -44,6 +55,10 @@ def bridge() -> Iterator[_FakeBridge]:
     tools.set_bridge_for_testing(None)
 
 
+def _set(b: _FakeBridge) -> None:
+    tools.set_bridge_for_testing(b)  # type: ignore[arg-type]
+
+
 def test_list_trees_summarizes(bridge: _FakeBridge) -> None:
     out = tools.list_trees()
     assert isinstance(out, TreeList)
@@ -77,3 +92,42 @@ def test_roll_up_recommends_optimal(bridge: _FakeBridge) -> None:
 def test_named_tree_selection(bridge: _FakeBridge) -> None:
     out = tools.roll_up(tree_name="MC_Tree_1")
     assert out.name == "MC_Tree_1"
+
+
+# Computed EVs for the ground-truth tree: D=50, C=-25, T1=-100, T2=50.
+_TRUE_CELLS = {"D": 50.0, "C": -25.0, "T1": -100.0, "T2": 50.0}
+
+
+def test_verify_rollback_matches() -> None:
+    _set(_FakeBridge({"MC_Tree_1": _MODEL}, _TRUE_CELLS))
+    try:
+        out = tools.verify_rollback()
+        assert isinstance(out, RollbackVerification)
+        assert out.rendered and out.compared_count == 4
+        assert out.matches == 4 and not out.mismatches
+        assert out.max_abs_diff < 0.01
+        assert "verified" in out.verdict
+    finally:
+        tools.set_bridge_for_testing(None)
+
+
+def test_verify_rollback_flags_mismatch() -> None:
+    bad = dict(_TRUE_CELLS, C=-20.0)  # chance EV off by 5
+    _set(_FakeBridge({"MC_Tree_1": _MODEL}, bad))
+    try:
+        out = tools.verify_rollback()
+        assert [m.node_id for m in out.mismatches] == ["C"]
+        assert out.mismatches[0].diff == pytest.approx(-5.0)
+        assert out.max_abs_diff == pytest.approx(5.0)
+    finally:
+        tools.set_bridge_for_testing(None)
+
+
+def test_verify_rollback_not_rendered() -> None:
+    _set(_FakeBridge({"MC_Tree_1": _MODEL}, {}))  # no MC_V_ cells
+    try:
+        out = tools.verify_rollback()
+        assert out.rendered is False and out.compared_count == 0
+        assert "not rendered" in out.verdict.lower()
+    finally:
+        tools.set_bridge_for_testing(None)