Worker decouple — Phase 2 / Slice 8: BoundaryHandler

[Andrewxu313]

Phase 2 of the worker decouple initiative.

Scope

Extract page-boundary decision logic (worker:7575–7903 + half of PAGE BOUNDARY orchestrator, ~1000 LOC) into batchgen/worker/boundary.py.

Design

@dataclass(frozen=True)
class BoundaryDecisionRequest:
    sequence_metadata: Mapping[str, FrozenSequenceMeta]
    rank: int
    world_size: int
    cur_batch_sequence_ids: tuple[str, ...]
    page_table_state: PageTableSnapshot

@dataclass(frozen=True)
class BoundaryPlan:
    decisions: Mapping[str, BoundaryAction]
    # BoundaryAction is a typed enum: EXTEND_GPU, EVICT_TO_HOST, RELEASE_PAGE, NO_OP, ...

class BoundaryHandler:
    def plan(self, req: BoundaryDecisionRequest) -> BoundaryPlan: ...

Worker applies the plan.

3-PR plan

• PR-8.1 Port.
• PR-8.2 Dual-path gate + compare-mode + multi-rank L2-2048 + L2-4096 back-to-back.
• PR-8.3 Cleanup.

Pre-merge checklist (from scheduler-split Step 8 fix-up commits)

• No stray return after deletion.
• All 8 BoundaryAction variants exercised.
• Cross-rank synchronization happens in SyncCoordinator (Slice 3), not in this handler.

Design source reference

origin/tairan/scheduler-split:batchgen/worker/boundary.py (828 LOC).
origin/tairan/worker-reextract:batchgen/worker/boundary/ (decomposed into 7 sub-files) — out of scope here; single-file form for now.

Design: /Users/andrew/.claude/plans/the-task-for-this-declarative-melody.md (POIS-local). Builds on the Phase A/B/C cuda-graph contract pattern (PR #162/#163/#164, merged 2026-05-27).