feat: shutdown_host and begin_stop_vm through the API

shutdown_host() posts command=shutdown to the node itself; its guests
stop as on any shutdown. begin_stop_vm(name) asks a guest for its clean
shutdown and returns once Proxmox took it, without waiting for the
task: the caller reads get_vm_status until it stopped. Both raise
RuntimeError when Proxmox refuses; an unknown guest is a ValueError.

The contracts HostShutdownMixin and VmStopRequestMixin of
napalm-device-types (NAPALM/napalm-device-types#55); for netOrk's graph
workflows (NetOrk/netork#1636).

napalm_proxmox/vm_contract_mixin.py

@@ -2,7 +2,9 @@
 
 ``power_vm`` stays for callers that already use it; these are what a
 hypervisor-neutral caller talks to. They raise instead of returning a
-``{"success": ...}`` dict, and block until Proxmox reports the task finished.
+``{"success": ...}`` dict, and block until Proxmox reports the task finished —
+except ``begin_stop_vm`` and ``shutdown_host``, which return once Proxmox took
+the request (``VmStopRequestMixin``, ``HostShutdownMixin``).
 """
 
 from __future__ import annotations
@@ -162,6 +164,14 @@ class ProxmoxVMContractMixin:
     def stop_vm(self, name: str, force: bool = False) -> None:
         self._run_power(*self._resolve_vm(name), "stop" if force else "shutdown")
 
+    def begin_stop_vm(self, name: str) -> None:
+        """Ask for the guest's clean shutdown; return once Proxmox accepted it."""
+        vmid, vm_type = self._resolve_vm(name)
+        try:
+            self._guest_api(vmid, vm_type).status.shutdown.post()
+        except Exception as exc:
+            raise RuntimeError(f"shutdown of {vm_type} {vmid} refused: {exc}") from exc
+
     def reboot_vm(self, name: str, force: bool = False) -> None:
         vmid, vm_type = self._resolve_vm(name)
         if not force:
@@ -191,3 +201,10 @@ class ProxmoxVMContractMixin:
             self._node_api().status.post(command="reboot")
         except Exception as exc:
             raise RuntimeError(f"Reboot of node {self._node_name!r} refused: {exc}") from exc
+
+    def shutdown_host(self) -> None:
+        """Shut this Proxmox node down through the API; its guests stop as on any shutdown."""
+        try:
+            self._node_api().status.post(command="shutdown")
+        except Exception as exc:
+            raise RuntimeError(f"Shutdown of node {self._node_name!r} refused: {exc}") from exc