feat(core): dispatch bounded postbox routes

src/govoplan_core/core/organizations.py

@@ -130,6 +130,13 @@ class OrganizationRelationTypeRef:
     status: OrganizationStatus = "active"
 
 
+@dataclass(frozen=True, slots=True)
+class OrganizationHierarchyCatalogRef:
+    tenant_id: str
+    structures: tuple[OrganizationStructureRef, ...] = ()
+    relation_types: tuple[OrganizationRelationTypeRef, ...] = ()
+
+
 @dataclass(frozen=True, slots=True)
 class OrganizationHierarchyEdgeRef:
     id: str
@@ -231,6 +238,12 @@ class OrganizationDirectory(Protocol):
 
 @runtime_checkable
 class OrganizationHierarchyDirectory(Protocol):
+    def hierarchy_catalog(
+        self,
+        tenant_id: str,
+    ) -> OrganizationHierarchyCatalogRef:
+        ...
+
     def get_unit_type(
         self,
         tenant_id: str,
@@ -355,6 +368,7 @@ __all__ = [
     "OrganizationFunctionTypeRef",
     "OrganizationFunctionTypeResolution",
     "OrganizationHierarchyDirection",
+    "OrganizationHierarchyCatalogRef",
     "OrganizationHierarchyDirectory",
     "OrganizationHierarchyEdgeRef",
     "OrganizationHierarchyMatchRef",

src/govoplan_core/core/postbox.py

@@ -12,6 +12,7 @@ CAPABILITY_POSTBOX_ACCESS = "postbox.access"
 CAPABILITY_POSTBOX_MESSAGES = "postbox.messages"
 CAPABILITY_POSTBOX_DELIVERY = "postbox.delivery"
 CAPABILITY_POSTBOX_EVIDENCE = "postbox.evidence"
+CAPABILITY_POSTBOX_ROUTING = "postbox.routing"
 
 PostboxAction = Literal["discover", "read", "send", "acknowledge", "administer"]
 PostboxMessageListState = Literal["all", "unread", "read", "acknowledged"]
@@ -317,6 +318,18 @@ class PostboxEvidenceProvider(Protocol):
         ...
 
 
+@runtime_checkable
+class PostboxRoutingProvider(Protocol):
+    def dispatch_due_routes(
+        self,
+        session: object,
+        *,
+        tenant_id: str | None = None,
+        limit: int = 50,
+    ) -> Mapping[str, object]:
+        ...
+
+
 def _postbox_provider(
     registry: object | None,
     *,
@@ -384,3 +397,14 @@ def postbox_evidence_provider(
         provider_type=PostboxEvidenceProvider,
     )
     return provider if isinstance(provider, PostboxEvidenceProvider) else None
+
+
+def postbox_routing_provider(
+    registry: object | None,
+) -> PostboxRoutingProvider | None:
+    provider = _postbox_provider(
+        registry,
+        capability_name=CAPABILITY_POSTBOX_ROUTING,
+        provider_type=PostboxRoutingProvider,
+    )
+    return provider if isinstance(provider, PostboxRoutingProvider) else None