docs: declare institutional architecture boundary

AGENTS.md

@@ -0,0 +1,16 @@
+# GovOPlaN SOAP Connector Codex Guide
+
+## Scope
+
+This repository owns governed SOAP operation publication, envelopes, serialization, connector policy, throttling, and transport diagnostics.
+
+## Documentation Contract
+
+- Treat documentation as part of every behavior change. Update this module's manifest-driven `DocumentationTopic` contributions for affected user and administrator behavior.
+- Keep feature content here; `govoplan-docs` projects it without importing SOAP internals.
+- Maintain a static user/admin baseline and run `/mnt/DATA/git/govoplan/tools/checks/check-manifest-shapes.py` after behavior or manifest changes.
+
+## Boundaries
+
+- Published modules retain validation, authorization, idempotency, and side-effect ownership.
+- Never expose an unrestricted bridge to internal operations.

src/govoplan_soap/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 ModuleContext, ModuleInterfaceProvider, ModuleManifest, PermissionDefinition, RoleTemplate
+from govoplan_core.core.modules import DocumentationTopic, ModuleContext, ModuleInterfaceProvider, ModuleManifest, PermissionDefinition, RoleTemplate
+from govoplan_core.core.provider_governance import declared_module_architecture
 
 SOAP_READ_SCOPE = "soap:endpoint:read"
 SOAP_READ_SCOPES = (SOAP_READ_SCOPE, "system:settings:read", "admin:settings:read")
@@ -49,7 +50,31 @@ manifest = ModuleManifest(
             level="system",
         ),
     ),
+    documentation=(
+        DocumentationTopic(
+            id="soap.published-operation-boundary",
+            title="Use governed SOAP publications",
+            summary="SOAP adapts explicitly published module operations without taking ownership of their business behavior.",
+            body="Only operations registered through the publication contract are visible. The source module retains validation, authorization facts, idempotency, and side effects; SOAP owns envelopes, serialization, transport policy, throttling, and diagnostics. The current surface is a provider contract and discovery API, not an unrestricted bridge to internal endpoints.",
+            documentation_types=("admin", "user"),
+            audience=("integration_user", "operator", "module_admin"),
+            related_modules=("policy", "audit", "docs"),
+            metadata={"kind": "reference"},
+        ),
+    ),
     route_factory=_route_factory,
+    architecture=declared_module_architecture(
+        layer="data_reporting_integration",
+        kind="integration",
+        maturity="vertical_slice",
+        documentation_ref="README.md",
+        test_ref="tests/test_soap_module_contract.py",
+        known_limits=("Only governed operation discovery/publication contracts are implemented; arbitrary SOAP proxying is excluded.",),
+        supported_authority_modes=("governance_overlay", "linked_reference"),
+        owned_concepts=("SOAP transport binding", "SOAP serialization", "transport diagnostics"),
+        non_owned_concepts=("published business operation", "domain authorization", "domain effect"),
+        security_docs=("README.md",),
+    ),
 )