AI disclosure: This issue was drafted with Codex. I have reviewed the report, and I am responsible for the content.
Background
ReadyQueueProtocol is defined in src/graphon/runtime/graph_runtime_state.py, while ReadyQueue is defined in src/graphon/graph_engine/ready_queue/protocol.py.
Both protocols currently expose the same structural interface:
put(item: str) -> None
get(timeout: float | None = None) -> str
task_done() -> None
empty() -> bool
qsize() -> int
dumps() -> str
loads(data: str) -> None
The current duplication appears to exist because the runtime layer avoids importing graphon.graph_engine.ready_queue directly. GraphRuntimeState._build_ready_queue() also uses a lazy import to avoid crossing architecture boundaries.
Problem
The duplicated protocol definitions are easy to drift over time. If one side changes and the other does not, the type-level contract between runtime state and graph engine ready queue implementations can silently become inconsistent.
There is already a static contract in src/graphon/graph_engine/ready_queue/in_memory_type_contract.py that verifies InMemoryReadyQueue satisfies both ReadyQueue and ReadyQueueProtocol, which suggests these two definitions are intended to remain equivalent.
Proposal
Consolidate ReadyQueue and ReadyQueueProtocol to reduce duplication while preserving the existing architectural boundary between runtime and graph_engine.
Possible approaches:
- Move the shared ready queue protocol to a lower-level/common module that both
runtime and graph_engine are allowed to import.
- Keep
ReadyQueue as the canonical protocol and expose a runtime-safe import path if that does not violate import-linter boundaries.
- If the duplication is intentional, document the boundary explicitly and strengthen the static type contract to make drift obvious.
Acceptance Criteria
- There is a single canonical ready queue protocol, or the intentional duplication is clearly documented.
- Runtime and graph engine import boundaries remain valid.
- Existing ready queue implementations still satisfy the runtime state requirements.
- Static type contracts and tests are updated to cover the chosen design.
AI disclosure: This issue was drafted with Codex. I have reviewed the report, and I am responsible for the content.
Background
ReadyQueueProtocolis defined insrc/graphon/runtime/graph_runtime_state.py, whileReadyQueueis defined insrc/graphon/graph_engine/ready_queue/protocol.py.Both protocols currently expose the same structural interface:
The current duplication appears to exist because the runtime layer avoids importing
graphon.graph_engine.ready_queuedirectly.GraphRuntimeState._build_ready_queue()also uses a lazy import to avoid crossing architecture boundaries.Problem
The duplicated protocol definitions are easy to drift over time. If one side changes and the other does not, the type-level contract between runtime state and graph engine ready queue implementations can silently become inconsistent.
There is already a static contract in
src/graphon/graph_engine/ready_queue/in_memory_type_contract.pythat verifiesInMemoryReadyQueuesatisfies bothReadyQueueandReadyQueueProtocol, which suggests these two definitions are intended to remain equivalent.Proposal
Consolidate
ReadyQueueandReadyQueueProtocolto reduce duplication while preserving the existing architectural boundary betweenruntimeandgraph_engine.Possible approaches:
runtimeandgraph_engineare allowed to import.ReadyQueueas the canonical protocol and expose a runtime-safe import path if that does not violate import-linter boundaries.Acceptance Criteria