[debt] scheduler.py の状態機械を所有権別 module に分割する

[proboscis]

結論

scheduler.py は、タスク実行、Promise、待機関係、外部完了、並行数制御、効果の振り分けを一つの巨大な関数内で所有しています。個別の不具合修正を安全に続けるため、公開動作を変えずに状態の所有権ごとへ分割します。

確認できた事実

2026-07-16 の main (b69f77b7) で再検証しました。

• 対象ファイルは packages/doeff-core-effects/doeff_core_effects/scheduler.py で、約1,488行です（src/doeff/scheduler.py という path は存在しません。初版の記載誤りを 2026-07-16 の監査で訂正しました）。scheduler は root の doeff package ではなく doeff-core-effects package が所有しています。
• scheduled() は 349 行目から始まり約1,140行あり、内部に42個の局所関数を持ちます。
• タスクと Promise の登録、ready queue、waiter、deadlock 判定、external completion、semaphore、効果 dispatch が同じ lexical scope の可変状態を共有しています。
• scheduler 周辺には既存の正しさに関する issue が複数あります。例: scheduler: unawaited Spawn task failures are silently dropped; wrap_task try also wraps the Ok TaskCompleted perform #485、scheduler: unresolvable waits hang silently in external_queue.get(); semaphore deadlock detection is masked by any live external waiter and unreachable behind wait_external entries #495、scheduler: semaphore permit permanently lost when the receiving waiter is cancelled after ReleaseSemaphore transferred it #496、scheduler: root completion silently abandons queued runnable resumes and parked tasks; empty Race() leaks the caller continuation (#485 family) #501、scheduler: tasks/promises/semaphores grow monotonically and pin result/exception payloads for the run's lifetime #502、scheduler: task priority is honored only at initial dispatch — all wakes re-enqueue at NORMAL; spawner resume inverts IDLE/HIGH #504、scheduler: Gather/Race on external-promise futures bypass PRIORITY_EXTERNAL_WAIT — sim clock can advance past a pending external completion #505（2026-07-16 時点ですべて OPEN）。
• 2026-07-10 VM concurrency audit: index + minor-findings umbrella (scheduler / bridges / vm-core) #507 は scheduler の特定の挙動を扱う issue であり、本 issue の構造的な所有権分離とは重複しません。

なぜ技術的負債か

ある状態の更新規則を変更すると、同じ関数内の別の状態機械へ暗黙に影響します。局所的な修正でも、取消、待機解除、外部完了、deadlock 判定の組合せを再検証する必要があり、変更範囲と責任範囲が一致していません。

目標とする責務境界

少なくとも次の所有者を、明示的な型または内部 module として分けます。

1. task / Promise registry
2. ready queue と再開規則
3. waiter graph と deadlock 判定
4. external completion の登録・解決・取消
5. semaphore と並行数制御
6. effect routing と handler 呼出し

scheduler.scheduled() は、これらを組み合わせる小さな調停層にします。

完了条件

• 上記の状態ごとに、唯一の更新 API と所有 module が定義されている。
• 状態を直接変更するコードが所有 module の外へ漏れていない。
• 現在の公開 API と正常系の実行意味を変更しない。
• 既存の scheduler 回帰試験がすべて通る。
• 取消、Promise 待機、external completion、deadlock、semaphore について focused law test を追加する。
• 既存の scheduler 不具合 issue の再現試験が、分割後も通る。
• 内部 module 間の依存方向を文書化し、循環を作らない。
• 分割だけで挙動変更を同時に混ぜず、必要な挙動変更は別 issue として追跡する。