feat(webui): govern actions, quick access, and metrics

Refs #264, #285, #289

src/govoplan_core/core/modules.py

@@ -113,7 +113,7 @@ class ProductAreaContribution:
 
 @dataclass(frozen=True, slots=True)
 class QuickAccessTool:
-    """Declare a compact module-owned tool for an optional Quick Access rail."""
+    """Declare a versioned, bounded module-owned Quick Access tool."""
 
     id: str
     module_id: str
@@ -128,6 +128,11 @@ class QuickAccessTool:
     order: int = 100
     default_enabled: bool = True
     modes: tuple[str, ...] = ("browse",)
+    contract_version: str = "1"
+    availability: Literal["global", "active_object"] = "global"
+    accepted_reference_kinds: tuple[str, ...] = ()
+    returned_reference_kinds: tuple[str, ...] = ()
+    help_context_id: str | None = None
 
 
 @dataclass(frozen=True, slots=True)

src/govoplan_core/core/registry.py

@@ -1468,6 +1468,28 @@ def _validate_quick_access_tool(
         raise RegistryError(
             f"Quick Access tool {tool.id!r} must declare at least one valid mode"
         )
+    if tool.contract_version != "1":
+        raise RegistryError(
+            f"Quick Access tool {tool.id!r} uses unsupported contract version "
+            f"{tool.contract_version!r}"
+        )
+    if tool.availability not in {"global", "active_object"}:
+        raise RegistryError(
+            f"Quick Access tool {tool.id!r} has invalid availability"
+        )
+    reference_kinds = (*tool.accepted_reference_kinds, *tool.returned_reference_kinds)
+    if any(not _QUICK_ACCESS_TOOL_ID_RE.fullmatch(kind) for kind in reference_kinds):
+        raise RegistryError(
+            f"Quick Access tool {tool.id!r} contains an invalid reference kind"
+        )
+    if tool.availability == "active_object" and not tool.accepted_reference_kinds:
+        raise RegistryError(
+            f"Contextual Quick Access tool {tool.id!r} must declare accepted reference kinds"
+        )
+    if tool.help_context_id is not None and not validate_view_surface_id(tool.help_context_id):
+        raise RegistryError(
+            f"Quick Access tool {tool.id!r} has an invalid help context id"
+        )
 
 
 def _validate_view_surfaces(manifest: ModuleManifest) -> None: