Skip to content

refactor(runtime): consolidate ReadyQueue and ReadyQueueProtocol #140

@QuantumGhost

Description

@QuantumGhost

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:

  1. Move the shared ready queue protocol to a lower-level/common module that both runtime and graph_engine are allowed to import.
  2. Keep ReadyQueue as the canonical protocol and expose a runtime-safe import path if that does not violate import-linter boundaries.
  3. 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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions