[debt] 一般利用・handler 作者・VM 内部の公開 API を階層化する

[proboscis]

結論

root の doeff 名前空間が、日常的な Program API、handler 作者向けの制御命令、VM 内部型、scheduler の状態型、削除済み API の墓標を同じ面で公開しています。一部の低水準 API は handler 実装に必要なので単純削除は不適切ですが、「誰向けの安定契約か」が区別されていません。

確認済みの事実

2026-07-16 の main (b69f77b7) で確認しました。

• VM bridge: PyVM、K、Callable など
  • doeff/__init__.py:11-16
• 制御命令: Pass、Resume、Transfer、GetHandlers など
  • doeff/__init__.py:22-42
• 標準効果と scheduler API: Ask、Try、Spawn、Promise、Task など
  • doeff/__init__.py:50-82
• DoExpr / Program / ProgramBase の互換別名
  • doeff/__init__.py:101-130
• 削除済み概念を実行時に失敗させる多数の stub
  • doeff/__init__.py:154-187
• Pass / Resume / Transfer / K は handler 作者向け公開契約としてテストされています。
  • tests/core/test_spec_gaps.py:40-77
• 一方、公開面の整理テストは機械可読な公開契約が無いと判断して停止します。
  • tests/public_api/test_api_cleanup.py:11-13

問題

• 初学者が一般 API と VM 機構を区別できません。
• どの名前に後方互換性を負うか、変更時に判断できません。
• root re-export が配布依存循環を強め、import 順序の知識を root へ持ち込みます。
• 削除済み API の墓標が永続的な公開面として残り、廃止完了の定義がありません。
• Program、ProgramBase、DoExpr の複数名が同じ概念を表し、型・文書・検索の認知負荷を上げています。

望ましい設計

少なくとも次の利用者層を明示します。

1. 一般利用者: do、Program、標準効果、一般的な合成 API
2. handler 作者: continuation 制御、handler stack 観測、低水準 effect routing
3. runtime / VM 作者: PyVM、VM handle、scheduler 内部状態

低水準機能を消すことではなく、安定度と責任を名前空間・文書・テストで区切ることが目的です。

完了条件

• 現在の root export を「一般」「handler 作者」「runtime/VM」「互換墓標」に分類した inventory を作る。
• 各層の正規 import path と互換性方針を決める。
• 機械可読な公開 API 契約を追加し、追加・削除差分をテストで検出する。
• 一般向け文書が VM 内部型を読まなくても完結する。
• Program / ProgramBase / DoExpr の正規名を一つ決め、互換別名に期限または明示的な永続方針を付ける。
• 削除済み API stub ごとに、保持理由と削除条件を決める。
• handler 作者向け API の移動には移行警告と書き換え例を付ける。
• 配布依存循環を解消する issue と整合し、root facade が下位 package の初期化順に依存しない。

関連

• PR [codex] Delete public WithHandler shim #476 は WithHandler 一点の公開面整理を行った先行例です。
• 配布依存グラフの循環解消は [debt] doeff / core-effects / doeff-hy の配布依存を一方向へ直す #537 で追跡します。