feat: expose institutional architecture and runtime state

src/govoplan_ops/backend/manifest.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
 from govoplan_core.core.access import CAPABILITY_AUTH_PERMISSION_EVALUATOR, CAPABILITY_AUTH_PRINCIPAL_RESOLVER
-from govoplan_core.core.modules import FrontendModule, FrontendRoute, ModuleContext, ModuleManifest, NavItem, PermissionDefinition, RoleTemplate
+from govoplan_core.core.modules import DocumentationCondition, DocumentationTopic, FrontendModule, FrontendRoute, ModuleContext, ModuleManifest, NavItem, PermissionDefinition, RoleTemplate
+from govoplan_core.core.provider_governance import ModuleArchitectureDeclaration, ModuleArchitectureDocumentation, ModuleMaturityEvidence
 from govoplan_core.core.views import ViewSurface
 
 OPS_READ_SCOPE = "ops:operations:read"
@@ -9,6 +10,33 @@ OPS_READ_SCOPES = (OPS_READ_SCOPE, "system:settings:read", "admin:settings:read"
 OPS_RUN_SCOPE = "ops:operations:run"
 OPS_RUN_SCOPES = (OPS_RUN_SCOPE, "system:settings:write")
 
+ARCHITECTURE = ModuleArchitectureDeclaration(
+    layer="runtime_meta",
+    kind="operations",
+    maturity="vertical_slice",
+    evidence=(
+        ModuleMaturityEvidence(
+            kind="test",
+            reference="tests/test_governance_inventory.py",
+            summary="Tests safe operational projection of module governance declarations.",
+        ),
+        ModuleMaturityEvidence(
+            kind="documentation",
+            reference="docs/SCALABILITY_PROFILES.md",
+            summary="Documents operational topology and scaling posture.",
+        ),
+    ),
+    known_limits=(
+        "Provider health observations depend on module-owned operational probes and may be unavailable until configured.",
+    ),
+    owned_concepts=("operations status projection", "bounded operational probes"),
+    non_owned_concepts=("domain repair", "external provider credentials"),
+    documentation=ModuleArchitectureDocumentation(
+        recovery=("docs/SCALABILITY_PROFILES.md",),
+        operations=("docs/SCALABILITY_PROFILES.md",),
+    ),
+)
+
 
 def _permission(scope: str, label: str, description: str) -> PermissionDefinition:
     module_id, resource, action = scope.split(":", 2)
@@ -65,6 +93,48 @@ manifest = ModuleManifest(
             level="system",
         ),
     ),
+    documentation=(
+        DocumentationTopic(
+            id="ops.health-governance-and-sizing",
+            title="Inspect platform health and deployment posture",
+            summary="Ops combines module-owned health checks with deployment profile, governance inventory, worker assumptions, and sizing guidance.",
+            body="Read-only status distinguishes configured capabilities from healthy integrations. Authorized operators can run bounded probes; a probe must not perform unbounded business work or silently repair data. Use readiness and worker results when diagnosing a node, and use the deployment profile and sizing assumptions when planning horizontal capacity.",
+            documentation_types=("admin", "user"),
+            audience=("operator", "system_admin"),
+            related_modules=("audit", "docs", "notifications"),
+            metadata={"kind": "reference"},
+        ),
+        DocumentationTopic(
+            id="ops.runtime-coordination-and-recovery",
+            title="Drain runtime nodes and inspect recovery evidence",
+            summary="Ops projects shared runtime heartbeats, replica gaps, drain controls, and recovery states that require operator attention.",
+            body="Use the runtime table to identify stale or composition-skewed API and worker replicas. Drain before replacement so API readiness closes and workers stop taking new queue work; cancellation is available while the node is still draining. The recovery table reports durable Core recovery operations, but a recorded forward-recovery or manual-intervention state is not an automatic database restore.",
+            documentation_types=("admin", "user"),
+            audience=("operator", "system_admin"),
+            conditions=(
+                DocumentationCondition(
+                    required_modules=("ops",),
+                    any_scopes=OPS_READ_SCOPES,
+                ),
+            ),
+            related_modules=("audit", "notifications"),
+            metadata={
+                "kind": "workflow",
+                "route": "/ops",
+                "screen": "Runtime cluster and recovery evidence",
+                "steps": [
+                    "Compare active non-stale nodes with the configured API and worker replica expectations.",
+                    "Request drain and wait for the node to report draining before replacing it.",
+                    "Inspect every recovery-required, outcome-unknown, or manual-intervention operation and follow its recorded recovery mode.",
+                    "Verify replacement composition, readiness, queue consumers, and recovery evidence before closing the operation.",
+                ],
+                "limitations": [
+                    "Drain is observed on the runtime heartbeat interval and does not forcibly terminate active work.",
+                    "Ops does not create database backups or make an unsafe post-migration rollback reversible.",
+                ],
+            },
+        ),
+    ),
     route_factory=_route_factory,
     nav_items=(NavItem(path="/ops", label="Ops", icon="activity", required_any=OPS_READ_SCOPES, order=890),),
     frontend=FrontendModule(
@@ -76,6 +146,7 @@ manifest = ModuleManifest(
             ViewSurface(id="ops.widget.health", module_id="ops", kind="section", label="Operations health widget", order=100),
         ),
     ),
+    architecture=ARCHITECTURE,
 )