feat(snmp): explicit host binding (host_id / steward_host) with implicit fallback

SNMP devices map onto a Steward host's detail page via _devices_for_host,
which previously matched the device's `host` field (the SNMP poll target)
against the Host's address/name — a coincidence of strings that breaks when
the poll target differs from how the Host is recorded.

Add two optional per-device config fields that decouple the binding from the
poll target:
  • host_id      — exact Steward Host UUID match (the explicit link)
  • steward_host — friendly bind by Host name or address (case-insensitive)

An explicit binding is exclusive: a device bound to host A never implicitly
matches host B by a coincidental address. No explicit binding → existing
implicit `host`-string match (fully backward compatible).

host_panel passes host.id and badges explicitly-bound devices. plugin.yaml
documents the new fields. Tests cover explicit id/name, exclusivity, wrong
uuid, and legacy fallback.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Jg27rgypiW2efULXJDtMC

plugins/snmp/routes.py

@@ -93,15 +93,40 @@ async def index():
                                  poll_interval=poll_interval)
 
 
-def _devices_for_host(devices_cfg: list, address: str | None, name: str | None) -> list[dict]:
-    """SNMP devices whose configured `host` matches a Steward host's address or
-    name (case-insensitive). SNMP devices are config-defined by IP/hostname, so
-    this is how they map onto a host's page."""
+def _device_binds_to_host(d: dict, keys: set[str], host_id: str) -> bool:
+    """Does config device `d` belong on the host identified by `keys`
+    (lowercased {address, name}) / `host_id`?
+
+    A device may declare an **explicit** binding that decouples "which Steward
+    host this belongs to" from "where to poll" (the `host` field):
+      • `host_id`       — the Steward Host UUID (exact match), the explicit link.
+      • `steward_host`  — a friendly bind by Host name or address (case-insensitive).
+    An explicit binding is **exclusive**: a device bound to host A must not also
+    match host B by a coincidental poll-target string. Only when no explicit
+    binding is present do we fall back to the implicit `host`-string match
+    (backward compatible with configs that only set `host`).
+    """
+    explicit_id = str(d.get("host_id", "")).strip()
+    explicit_name = str(d.get("steward_host", "")).strip().lower()
+    if explicit_id or explicit_name:
+        if explicit_id and host_id and explicit_id == host_id:
+            return True
+        return bool(explicit_name and explicit_name in keys)
+    return str(d.get("host", "")).strip().lower() in keys
+
+
+def _devices_for_host(devices_cfg: list, address: str | None, name: str | None,
+                      host_id: str | None = None) -> list[dict]:
+    """SNMP devices that map onto a Steward host's page. Prefers an explicit
+    per-device binding (`host_id` / `steward_host`); otherwise falls back to
+    matching the device's `host` (poll target) against the host's address or
+    name (case-insensitive). See `_device_binds_to_host` for the precedence."""
     keys = {(address or "").strip().lower(), (name or "").strip().lower()}
     keys.discard("")
+    hid = (host_id or "").strip()
     return [
         d for d in devices_cfg
-        if isinstance(d, dict) and str(d.get("host", "")).strip().lower() in keys
+        if isinstance(d, dict) and _device_binds_to_host(d, keys, hid)
     ]
 
 
@@ -120,7 +145,7 @@ async def host_panel(host_id: str):
             select(Host).where(Host.id == host_id))).scalar_one_or_none()
         if host is None:
             return ""
-        matched = _devices_for_host(devices_cfg, host.address, host.name)
+        matched = _devices_for_host(devices_cfg, host.address, host.name, host.id)
         if not matched:
             return ""
         names = [d.get("name") or d.get("host", "?") for d in matched]
@@ -131,6 +156,8 @@ async def host_panel(host_id: str):
         "host": d.get("host", ""),
         "oids": d.get("oids", []),
         "readings": latest.get(d.get("name") or d.get("host", "?"), {}),
+        "bound": bool(str(d.get("host_id", "")).strip()
+                      or str(d.get("steward_host", "")).strip()),
     } for d in matched]
     return await render_template("snmp/host_panel.html", devices=devices)