docs(files): expose adaptive handbook topics

tests/test_manifest_documentation.py

@@ -3,20 +3,97 @@ from __future__ import annotations
 import unittest
 
 
+TOPIC_IDS = {
+    "files.workflow.import-managed-snapshot",
+    "files.governed-connectors-and-provenance",
+    "files.reference.integrity-recovery-and-fail-closed-transports",
+    "files.reference.snapshot-provenance-and-capabilities",
+}
+HANDBOOK_HREF = "govoplan-files/docs/FILES_HANDBOOK.md"
+
+
 class FilesManifestDocumentationTests(unittest.TestCase):
-    def test_connector_topic_covers_governance_pinning_and_provenance_perspectives(self) -> None:
+    @classmethod
+    def setUpClass(cls) -> None:
         from govoplan_files.backend.manifest import manifest
 
-        topic = next(item for item in manifest.documentation if item.id == "files.governed-connectors-and-provenance")
+        cls.topics = {topic.id: topic for topic in manifest.documentation}
+
+    def topic(self, topic_id: str):
+        return self.topics[topic_id]
+
+    def test_adaptive_topics_have_role_scope_module_and_link_contracts(self) -> None:
+        self.assertEqual(TOPIC_IDS, set(self.topics))
+        self.assertEqual({"admin", "user"}, {item for topic in self.topics.values() for item in topic.documentation_types})
+
+        for topic in self.topics.values():
+            with self.subTest(topic=topic.id):
+                self.assertTrue(topic.audience)
+                self.assertTrue(topic.conditions)
+                self.assertTrue(any("files" in condition.required_modules for condition in topic.conditions))
+                self.assertTrue(any(condition.any_scopes or condition.required_scopes for condition in topic.conditions))
+                self.assertIn("runtime", {link.kind for link in topic.links})
+                self.assertIn("api", {link.kind for link in topic.links})
+                self.assertIn(HANDBOOK_HREF, {link.href for link in topic.links if link.kind == "repository"})
+
+    def test_import_topic_is_a_complete_user_workflow(self) -> None:
+        topic = self.topic("files.workflow.import-managed-snapshot")
+
+        self.assertEqual(("user",), topic.documentation_types)
+        self.assertEqual("workflow", topic.metadata["kind"])
+        self.assertEqual("/files", topic.metadata["route"])
+        self.assertEqual("Files", topic.metadata["screen"])
+        for key in ("prerequisites", "steps", "outcome", "verification"):
+            self.assertTrue(topic.metadata[key])
+        self.assertIn("never mutate the remote source", topic.body)
+        self.assertIn("/api/v1/files/connectors/profiles/{profile_id}/import", {link.href for link in topic.links})
+
+    def test_admin_topic_covers_policy_redaction_and_atomic_credential_deletion(self) -> None:
+        topic = self.topic("files.governed-connectors-and-provenance")
+
+        self.assertEqual(("admin",), topic.documentation_types)
+        self.assertEqual("reference", topic.metadata["kind"])
+        self.assertEqual("File connections", topic.metadata["screen"])
+        self.assertTrue(topic.metadata["section"])
+        self.assertIn("deny rules win", topic.body)
+        self.assertIn("redact secret values", topic.body)
+        self.assertIn("same transaction", topic.body)
+        self.assertTrue(any("non-owned external references" in item for item in topic.metadata["security_invariants"]))
+        self.assertIn("/api/v1/files/connectors/policies/tenant", {link.href for link in topic.links})
+        self.assertIn("/api/v1/files/connectors/credentials", {link.href for link in topic.links})
+
+    def test_operator_topic_covers_recovery_and_fail_closed_s3_smb(self) -> None:
+        topic = self.topic("files.reference.integrity-recovery-and-fail-closed-transports")
+
+        self.assertEqual(("admin",), topic.documentation_types)
+        self.assertEqual("reference", topic.metadata["kind"])
+        self.assertIn("S3", topic.body)
+        self.assertIn("SMB", topic.body)
+        self.assertIn("fail closed", topic.body)
+        self.assertIn("DFS referrals", topic.body)
+        self.assertIn("does not remove backend blob objects", topic.body)
+        self.assertIn("MASTER_KEY_B64", topic.metadata["recovery_unit"])
+        self.assertTrue(topic.metadata["verification"])
+        self.assertIn("GOVOPLAN_CONNECTOR_ALLOW_PRIVATE_NETWORKS", topic.configuration_keys)
+
+    def test_integrator_topic_exposes_capability_and_provenance_boundary(self) -> None:
+        topic = self.topic("files.reference.snapshot-provenance-and-capabilities")
 
         self.assertEqual(("admin", "user"), topic.documentation_types)
-        self.assertEqual({"user", "admin", "operator"}, set(topic.metadata["perspectives"]))
-        self.assertIn("fails closed", topic.body)
-        self.assertIn("DFS referrals", topic.body)
-        self.assertIn("immediately scrubs", topic.body)
-        self.assertTrue(any("non-owned external references" in item for item in topic.metadata["security_invariants"]))
+        self.assertEqual("reference", topic.metadata["kind"])
+        self.assertEqual(
+            ["files.access@0.1.6", "files.campaign_attachments@0.1.6"],
+            topic.metadata["provided_interfaces"],
+        )
         self.assertIn("revision", topic.metadata["provenance_fields"])
-        self.assertIn("/api/v1/files/connectors/profiles", {link.href for link in topic.links})
+        self.assertIn("exact asset, version, blob, checksum", topic.body)
+        self.assertIn("collaboration", topic.body)
+
+    def test_internal_related_topic_ids_resolve(self) -> None:
+        for topic in self.topics.values():
+            for related_id in topic.metadata.get("related_topic_ids", []):
+                if related_id.startswith("files."):
+                    self.assertIn(related_id, TOPIC_IDS, f"{topic.id} refers to missing topic {related_id}")
 
 
 if __name__ == "__main__":