chore: harden Protocol contract checks (#138)

This PR hardens protocol contracts by:

1. Preventing nominal subclasses from inadvertently becoming instantiable unless they explicitly override the protocol methods.
2. Statically checking all in-source protocol implementations.

Author: QuantumGhost

src/graphon/dsl/entities.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from abc import abstractmethod
 from collections.abc import Mapping
 from enum import StrEnum, auto
 from typing import Any, Protocol
@@ -125,4 +126,5 @@ def loadable(self) -> bool:
 
 
 class TypedNodeFactory(Protocol):
+    @abstractmethod
     def create_node(self, node_config: NodeConfigDict) -> Any: ...

src/graphon/file/protocols.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from abc import abstractmethod
 from collections.abc import Generator
 from typing import TYPE_CHECKING, Literal, Protocol
 
@@ -18,26 +19,32 @@ class WorkflowFileRuntimeProtocol(Protocol):
     """
 
     @property
+    @abstractmethod
     def multimodal_send_format(self) -> str: ...
 
+    @abstractmethod
     def http_get(
         self,
         url: str,
         *,
         follow_redirects: bool = True,
     ) -> HttpResponseProtocol: ...
 
+    @abstractmethod
     def storage_load(self, path: str, *, stream: bool = False) -> bytes | Generator: ...
 
+    @abstractmethod
     def load_file_bytes(self, *, file: File) -> bytes: ...
 
+    @abstractmethod
     def resolve_file_url(
         self,
         *,
         file: File,
         for_external: bool = True,
     ) -> str | None: ...
 
+    @abstractmethod
     def resolve_upload_file_url(
         self,
         *,
@@ -46,6 +53,7 @@ def resolve_upload_file_url(
         for_external: bool = True,
     ) -> str: ...
 
+    @abstractmethod
     def resolve_tool_file_url(
         self,
         *,
@@ -54,6 +62,7 @@ def resolve_tool_file_url(
         for_external: bool = True,
     ) -> str: ...
 
+    @abstractmethod
     def verify_preview_signature(
         self,
         *,

src/graphon/graph/graph.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+from abc import abstractmethod
 from collections import defaultdict
 from collections.abc import Mapping, Sequence
 from typing import Any, Protocol, final
@@ -27,6 +28,7 @@ class NodeFactory(Protocol):
     allowing for different node creation strategies while maintaining type safety.
     """
 
+    @abstractmethod
     def create_node(self, node_config: NodeConfigDict) -> Node:
         """Create a Node instance from node configuration data.
 

src/graphon/graph/validation.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from abc import abstractmethod
 from collections.abc import Sequence
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Protocol
@@ -34,6 +35,7 @@ def __init__(self, issues: Sequence[GraphValidationIssue]) -> None:
 class GraphValidationRule(Protocol):
     """Protocol that individual validation rules must satisfy."""
 
+    @abstractmethod
     def validate(self, graph: Graph) -> Sequence[GraphValidationIssue]:
         """Validate the provided graph and return any discovered issues."""
         ...

src/graphon/graph_engine/command_channels/protocol.py

@@ -4,6 +4,7 @@
 to/from a GraphEngine instance, supporting both local and distributed scenarios.
 """
 
+from abc import abstractmethod
 from typing import Protocol
 
 from ..entities.commands import GraphEngineCommand
@@ -16,6 +17,7 @@ class CommandChannel(Protocol):
     this channel is dedicated to that single execution.
     """
 
+    @abstractmethod
     def fetch_commands(self) -> list[GraphEngineCommand]:
         """Fetch pending commands for this GraphEngine instance.
 
@@ -27,6 +29,7 @@ def fetch_commands(self) -> list[GraphEngineCommand]:
         """
         ...
 
+    @abstractmethod
     def send_command(self, command: GraphEngineCommand) -> None:
         """Send a command to be processed by this GraphEngine instance.
 

src/graphon/graph_engine/command_channels/redis_channel.py

@@ -6,6 +6,7 @@
 """
 
 import json
+from abc import abstractmethod
 from contextlib import AbstractContextManager
 from typing import Any, Protocol, final
 
@@ -27,18 +28,32 @@
 class RedisPipelineProtocol(Protocol):
     """Minimal Redis pipeline contract used by the command channel."""
 
+    @abstractmethod
     def lrange(self, name: str, start: int, end: int) -> Any: ...
+
+    @abstractmethod
     def delete(self, *names: str) -> Any: ...
+
+    @abstractmethod
     def execute(self) -> list[Any]: ...
+
+    @abstractmethod
     def rpush(self, name: str, *values: str) -> Any: ...
+
+    @abstractmethod
     def expire(self, name: str, time: int) -> Any: ...
+
+    @abstractmethod
     def set(self, name: str, value: str, ex: int | None = None) -> Any: ...
+
+    @abstractmethod
     def get(self, name: str) -> Any: ...
 
 
 class RedisClientProtocol(Protocol):
     """Redis client contract required by the command channel."""
 
+    @abstractmethod
     def pipeline(self) -> AbstractContextManager[RedisPipelineProtocol]: ...
 
 

src/graphon/graph_engine/command_processing/command_processor.py

@@ -1,6 +1,7 @@
 """Main command processor for handling external commands."""
 
 import logging
+from abc import abstractmethod
 from collections.abc import Callable
 from typing import Protocol, final
 
@@ -15,6 +16,7 @@
 class CommandHandler[CommandT: GraphEngineCommand](Protocol):
     """Protocol for command handlers."""
 
+    @abstractmethod
     def handle(
         self,
         command: CommandT,

src/graphon/graph_engine/domain/graph_execution.py

@@ -10,7 +10,6 @@
 
 from graphon.entities.pause_reason import PauseReason
 from graphon.enums import NodeState
-from graphon.runtime.graph_runtime_state import GraphExecutionProtocol
 
 from .node_execution import NodeExecution
 
@@ -246,6 +245,3 @@ def loads(self, data: str) -> None:
     def record_node_failure(self) -> None:
         """Increment the count of node failures encountered during execution."""
         self.exceptions_count += 1
-
-
-_: GraphExecutionProtocol = GraphExecution(workflow_id="")

src/graphon/graph_engine/ready_queue/protocol.py

@@ -4,6 +4,7 @@
 for execution, supporting both in-memory and persistent storage scenarios.
 """
 
+from abc import abstractmethod
 from collections.abc import Sequence
 from typing import Protocol
 
@@ -35,6 +36,7 @@ class ReadyQueue(Protocol):
     that can be serialized for state storage.
     """
 
+    @abstractmethod
     def put(self, item: str) -> None:
         """Add a node ID to the ready queue.
 
@@ -44,6 +46,7 @@ def put(self, item: str) -> None:
         """
         ...
 
+    @abstractmethod
     def get(self, timeout: float | None = None) -> str:
         """Retrieve and remove a node ID from the queue.
 
@@ -56,6 +59,7 @@ def get(self, timeout: float | None = None) -> str:
         """
         ...
 
+    @abstractmethod
     def task_done(self) -> None:
         """Indicate that a previously retrieved task is complete.
 
@@ -64,6 +68,7 @@ def task_done(self) -> None:
         """
         ...
 
+    @abstractmethod
     def empty(self) -> bool:
         """Check if the queue is empty.
 
@@ -73,6 +78,7 @@ def empty(self) -> bool:
         """
         ...
 
+    @abstractmethod
     def qsize(self) -> int:
         """Get the approximate size of the queue.
 
@@ -82,6 +88,7 @@ def qsize(self) -> int:
         """
         ...
 
+    @abstractmethod
     def dumps(self) -> str:
         """Serialize the queue state to a JSON string for storage.
 
@@ -92,6 +99,7 @@ def dumps(self) -> str:
         """
         ...
 
+    @abstractmethod
     def loads(self, data: str) -> None:
         """Restore the queue state from a JSON string.
 

src/graphon/http/protocols.py

@@ -1,3 +1,4 @@
+from abc import abstractmethod
 from collections.abc import Mapping
 from typing import Any, Protocol
 
@@ -6,45 +7,59 @@
 
 class HttpResponseProtocol(Protocol):
     @property
+    @abstractmethod
     def headers(self) -> Mapping[str, str]: ...
 
     @property
+    @abstractmethod
     def content(self) -> bytes: ...
 
     @property
+    @abstractmethod
     def status_code(self) -> int: ...
 
     @property
+    @abstractmethod
     def text(self) -> str: ...
 
     @property
+    @abstractmethod
     def is_success(self) -> bool: ...
 
+    @abstractmethod
     def raise_for_status(self) -> None: ...
 
 
 class HttpClientProtocol(Protocol):
     @property
+    @abstractmethod
     def max_retries_exceeded_error(self) -> type[Exception]: ...
 
     @property
+    @abstractmethod
     def request_error(self) -> type[Exception]: ...
 
+    @abstractmethod
     def get(self, url: str, max_retries: int = ..., **kwargs: Any) -> HttpResponse: ...
 
+    @abstractmethod
     def head(self, url: str, max_retries: int = ..., **kwargs: Any) -> HttpResponse: ...
 
+    @abstractmethod
     def post(self, url: str, max_retries: int = ..., **kwargs: Any) -> HttpResponse: ...
 
+    @abstractmethod
     def put(self, url: str, max_retries: int = ..., **kwargs: Any) -> HttpResponse: ...
 
+    @abstractmethod
     def delete(
         self,
         url: str,
         max_retries: int = ...,
         **kwargs: Any,
     ) -> HttpResponse: ...
 
+    @abstractmethod
     def patch(
         self,
         url: str,