@senpi/runtime 3.0.9-dev.20260710204324 → 3.0.9-dev.feat-strategy-compos.20260716233548

package/dist/composer/registry/mcp_closure.py

@@ -0,0 +1,311 @@
+"""mcp_closure — the CI drift check that keeps "the source vocabulary FULLY maps the
+scanner-usable MCP read surface" PROVABLE, continuously (registry-mapping-audit.md Wave 3a).
+
+The read boundary is a blocklist on the server (senpi_mcp.py MUTATION_TOOLS), so this
+codebase can never prove completeness from its own side alone — it needs the authoritative
+tool catalog. The live prod ``tools/list`` is unauthenticated, so we can: a committed
+SNAPSHOT (``mcp-tools-snapshot.json``: tool names + a hash of each input schema) is diffed
+against the registry mapping (every source NodeDef declares the tool it wraps in the
+machine-readable ``NodeDef.mcp_tool`` field). The check reports three drifts:
+
+    unmapped reads   — a tool in the snapshot that is neither MAPPED by a source node nor on
+                       the committed ALLOWLIST (mutations + not-scanner-shaped reads). This is
+                       the load-bearing one: a NEW scanner-usable read appearing server-side,
+                       or a read we forgot to map, fails CI until it is mapped or allowlisted.
+    mapped-but-gone  — a tool a source node maps that is ABSENT from the snapshot (removed /
+                       renamed server-side; the wrapping node is now dead).
+    schema drift     — (refresh path only) a mapped/known tool whose LIVE input-schema hash
+                       differs from the committed snapshot; the input contract moved.
+
+The offline comparison (``compare``) runs with NO network against the committed snapshot —
+that is the default pytest. An OPT-IN refresh (``MCP_SNAPSHOT_REFRESH=1``) fetches the live
+unauthenticated ``tools/list`` and rewrites the snapshot, surfacing schema drift + tool
+add/remove; network is NEVER the default test path.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+SNAPSHOT_PATH = Path(__file__).resolve().parent / "mcp-tools-snapshot.json"
+PROD_MCP_URL = "https://mcp.prod.senpi.ai/mcp"
+
+# The money/state MUTATION tools, MIRRORED composer-side from the scaffold's authoritative
+# blocklist (src/scanners/external/scaffold/senpi_mcp.py `MUTATION_TOOLS`). This is the
+# defense-in-depth used by the mcp_read escape hatch's CHECK-time validation (CMP061): a
+# scanner is a read-only producer, so mcp_read refuses any tool named here before it ever
+# reaches a box (the scaffold's own call_tool blocklist is the runtime double-guard). The
+# scaffold source is the single source of truth — a sync test
+# (test_mcp_read_hatch.py::test_mutation_blocklist_matches_scaffold) AST-parses the scaffold
+# frozenset and fails if this duplicate drifts, so a new mutation added there cannot silently
+# slip past the composer-side check.
+MUTATION_TOOLS: frozenset[str] = frozenset(
+    {
+        "create_position",
+        "close_position",
+        "edit_position",
+        "cancel_order",
+        "send_usdc",
+        "transfer_spot_to_perps",
+        "strategy_create",
+        "strategy_create_custom_strategy",
+        "strategy_close",
+        "strategy_close_positions",
+        "strategy_update",
+        "strategy_pause",
+        "strategy_top_up",
+        "strategy_withdraw_funds",
+        "strategy_bridge_funds_from_hyperliquid_to_evm",
+        "ratchet_stop_add",
+        "ratchet_stop_edit",
+        "ratchet_stop_delete",
+        "user_claim_referral_rewards",
+    }
+)
+
+# The committed ALLOWLIST: every catalog tool that is deliberately NOT a scanner source, with
+# a reason. Seeded from the registry-mapping-audit classification (senpi_mcp.py MUTATION_TOOLS
+# for the mutations; the audit's "marginal/held" + recon "skip" verdicts for the reads). The
+# closure check treats (snapshot - mapped - allowlist) as "unmapped scanner-usable reads": a
+# non-empty result fails CI. Keep reasons honest — this file is where a maintainer decides a
+# newly-surfaced tool is out of scope.
+ALLOWLIST: dict[str, str] = {
+    # --- money/state mutations (senpi_mcp.py MUTATION_TOOLS; blocked for producers) ---
+    "create_position": "mutation — opens a position (blocked for producers).",
+    "close_position": "mutation — closes a position.",
+    "edit_position": "mutation — edits a position.",
+    "cancel_order": "mutation — cancels a resting order.",
+    "transfer_spot_to_perps": "mutation — moves funds spot->perps.",
+    "strategy_create": "mutation — creates a strategy.",
+    "strategy_create_custom_strategy": "mutation — creates + funds a strategy wallet.",
+    "strategy_close": "mutation — closes a strategy (flattens positions).",
+    "strategy_close_positions": "mutation — flattens a strategy's positions.",
+    "strategy_update": "mutation — updates strategy config.",
+    "strategy_pause": "mutation — pauses a strategy.",
+    "strategy_top_up": "mutation — adds funds to a strategy.",
+    "strategy_withdraw_funds": "mutation — withdraws strategy funds.",
+    "strategy_bridge_funds_from_hyperliquid_to_evm": "mutation — bridges funds HL->EVM.",
+    "ratchet_stop_add": "mutation — adds a server-side ratchet stop.",
+    "ratchet_stop_edit": "mutation — edits a ratchet stop.",
+    "ratchet_stop_delete": "mutation — deletes a ratchet stop.",
+    "user_claim_referral_rewards": "mutation — claims referral rewards.",
+    # --- reads that are NOT market-signal sources (not scanner-shaped) ---
+    "account_get_portfolio": ("own-account current snapshot; clearinghouse_state + "
+                              "strategy_pnl_snapshot already cover own-wallet state."),
+    "arena_pool": "Senpi Arena prize-pool metadata, not a market read.",
+    "arena_prizes": "Senpi Arena prize-structure metadata, not a market read.",
+    "arena_roe_chart": "Senpi Arena ROE chart data, not a market-signal read.",
+    "estimate_custom_strategy_positions_opening": ("pre-trade position-opening estimator "
+                                                   "(execution planning), not a signal source."),
+    "execution_estimate_position_opening": ("pre-trade position-opening estimator "
+                                            "(execution planning), not a signal source."),
+    "execution_get_closed_position_details": ("own-account closed-position execution detail "
+                                              "(ops surface), not a market read."),
+    "execution_get_open_position_details": ("own-account open-position execution detail "
+                                            "(ops surface), not a market read."),
+    "execution_get_order_status": "own-order status lookup (execution ops), not a signal.",
+    "get_loyalty_tiers": "loyalty-program metadata, not a market read.",
+    "leaderboard_get_status": "leaderboard service status/health, not trader data.",
+    "list_senpi_guides": "documentation/guide listing, not market data.",
+    "read_senpi_guide": "documentation/guide content, not market data.",
+    "ratchet_stop_events": "own-account ratchet-stop event log; DSL owns exits, not a source.",
+    "ratchet_stop_get": "own-account ratchet-stop config read; DSL owns exits.",
+    "ratchet_stop_list": "own-account ratchet-stop list; DSL owns exits.",
+    "strategy_get": ("single-strategy metadata by id; strategy_list_fetch covers the list "
+                     "read a scanner would use."),
+    "user_get_me": "own-user account read, not a market-signal source.",
+    "user_get_referral_rewards": "referral-rewards read, not a market source.",
+    "user_get_senpi_points": "Senpi-points read, not a market source.",
+    "user_get_senpi_points_leaderboard": "Senpi-points leaderboard, not a market source.",
+}
+
+
+@dataclass
+class ClosureReport:
+    """The outcome of comparing the committed snapshot against the registry mapping."""
+
+    unmapped_reads: list[str] = field(default_factory=list)
+    mapped_but_gone: list[str] = field(default_factory=list)
+    stale_allowlist: list[str] = field(default_factory=list)
+    overlap_allowlist_mapped: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not (self.unmapped_reads or self.mapped_but_gone
+                    or self.stale_allowlist or self.overlap_allowlist_mapped)
+
+    def render(self) -> str:
+        if self.ok:
+            return "MCP read surface fully mapped: no drift."
+        lines = ["MCP closure drift detected:"]
+        if self.unmapped_reads:
+            lines.append("  UNMAPPED scanner-usable reads (map them, or allowlist with a reason):")
+            lines += [f"    - {t}" for t in self.unmapped_reads]
+        if self.mapped_but_gone:
+            lines.append("  MAPPED-BUT-GONE (tool absent from snapshot — removed/renamed?):")
+            lines += [f"    - {t}" for t in self.mapped_but_gone]
+        if self.overlap_allowlist_mapped:
+            lines.append("  CONTRADICTION (tool is both mapped AND allowlisted):")
+            lines += [f"    - {t}" for t in self.overlap_allowlist_mapped]
+        if self.stale_allowlist:
+            lines.append("  STALE allowlist (name absent from snapshot — prune it):")
+            lines += [f"    - {t}" for t in self.stale_allowlist]
+        return "\n".join(lines)
+
+
+def schema_hash(schema) -> str:
+    """Deterministic sha256 of an input schema (canonical JSON: sorted keys, tight separators)."""
+    return hashlib.sha256(
+        json.dumps(schema or {}, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+
+
+def load_snapshot(path: Path = SNAPSHOT_PATH) -> dict:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def snapshot_tool_names(snapshot: dict | None = None) -> set[str]:
+    snapshot = snapshot if snapshot is not None else load_snapshot()
+    return set(snapshot.get("tools", {}))
+
+
+def registry_mapped_tools() -> set[str]:
+    """The set of MCP tool names the source registry declares it wraps (NodeDef.mcp_tool)."""
+    from .nodes import NODES
+    return {n.mcp_tool for n in NODES if n.mcp_tool}
+
+
+def compare(
+    snapshot: dict | None = None,
+    mapped: set[str] | None = None,
+    allowlist: dict[str, str] | None = None,
+) -> ClosureReport:
+    """Offline comparison of the committed snapshot vs the registry mapping + allowlist."""
+    snapshot = snapshot if snapshot is not None else load_snapshot()
+    mapped = mapped if mapped is not None else registry_mapped_tools()
+    allowlist = allowlist if allowlist is not None else ALLOWLIST
+
+    names = snapshot_tool_names(snapshot)
+    allowset = set(allowlist)
+    return ClosureReport(
+        unmapped_reads=sorted(names - mapped - allowset),
+        mapped_but_gone=sorted(mapped - names),
+        stale_allowlist=sorted(allowset - names),
+        overlap_allowlist_mapped=sorted(mapped & allowset),
+    )
+
+
+# ------------------------------------------------------------------- OPT-IN live refresh
+
+def build_snapshot(tools: list[dict]) -> dict:
+    """Trim a raw tools/list into the committed snapshot shape (names + schema hash)."""
+    ordered = sorted(tools, key=lambda t: t["name"])
+    return {
+        "_comment": (
+            "Trimmed snapshot of the live prod MCP tools/list (names + input-schema hash "
+            "only) for the registry closure check. Regenerate via MCP_SNAPSHOT_REFRESH=1 "
+            "pytest python-tests/composer/test_mcp_closure.py. Do not hand-edit."
+        ),
+        "source": PROD_MCP_URL,
+        "tool_count": len(ordered),
+        "tools": {t["name"]: {"schema_sha256": schema_hash(t.get("inputSchema"))} for t in ordered},
+    }
+
+
+def diff_snapshots(committed: dict, live: dict) -> dict:
+    """added / removed / schema_changed between two snapshots (the refresh drift report)."""
+    c = committed.get("tools", {})
+    lv = live.get("tools", {})
+    added = sorted(set(lv) - set(c))
+    removed = sorted(set(c) - set(lv))
+    changed = sorted(
+        n for n in set(c) & set(lv)
+        if c[n].get("schema_sha256") != lv[n].get("schema_sha256")
+    )
+    return {"added": added, "removed": removed, "schema_changed": changed}
+
+
+def fetch_live_tools(url: str = PROD_MCP_URL, timeout: float = 20.0) -> list[dict]:
+    """Fetch the live unauthenticated tools/list (initialize + tools/list) over MCP streamable
+    HTTP. No API key needed. Used only by the opt-in refresh path — never the default test."""
+    import urllib.request
+
+    session_id: dict[str, str] = {}
+
+    def _post(payload: dict, notify: bool = False):
+        body = json.dumps(payload).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+        }
+        if session_id.get("id"):
+            headers["mcp-session-id"] = session_id["id"]
+        req = urllib.request.Request(url, data=body, headers=headers, method="POST")
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            sid = resp.headers.get("mcp-session-id")
+            if sid:
+                session_id["id"] = sid
+            raw = resp.read().decode("utf-8")
+        if notify:
+            return None
+        return _parse_jsonrpc(raw)
+
+    def _parse_jsonrpc(raw: str) -> dict:
+        raw = raw.strip()
+        if not raw:
+            return {}
+        if raw.startswith("{"):
+            return json.loads(raw)
+        # text/event-stream: pull the JSON out of the `data:` lines.
+        for line in raw.splitlines():
+            line = line.strip()
+            if line.startswith("data:"):
+                chunk = line[len("data:"):].strip()
+                if chunk and chunk != "[DONE]":
+                    return json.loads(chunk)
+        return {}
+
+    _post({
+        "jsonrpc": "2.0", "id": 1, "method": "initialize",
+        "params": {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {"name": "composer-mcp-closure", "version": "1.0"},
+        },
+    })
+    _post({"jsonrpc": "2.0", "method": "notifications/initialized"}, notify=True)
+    result = _post({"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}})
+    tools = (result or {}).get("result", {}).get("tools", [])
+    if not tools:
+        raise RuntimeError(f"tools/list returned no tools (response: {result!r})")
+    return tools
+
+
+def refresh_snapshot(url: str = PROD_MCP_URL, path: Path = SNAPSHOT_PATH) -> tuple[dict, dict]:
+    """Fetch live, diff against the committed snapshot, rewrite it. Returns (drift, new_snapshot)."""
+    committed = load_snapshot(path) if path.exists() else {"tools": {}}
+    live = build_snapshot(fetch_live_tools(url))
+    drift = diff_snapshots(committed, live)
+    path.write_text(json.dumps(live, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return drift, live
+
+
+def main(argv: list[str] | None = None) -> int:
+    import sys
+    argv = sys.argv[1:] if argv is None else argv
+    if "--refresh" in argv:
+        drift, _ = refresh_snapshot()
+        print("refreshed snapshot; drift vs previous:", json.dumps(drift))
+        report = compare()
+        print(report.render())
+        return 0 if report.ok else 1
+    report = compare()
+    print(report.render())
+    return 0 if report.ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())