[debt] doeff run の入力形式ごとの実行意味を単一 runtime 契約へ統一する

[proboscis]

結論

doeff run は、同じ Program を指定しても、入力形式と --runner の有無によって、入るハンドラと scheduler が変わります。利用者から見た「Program を実行する」という一つの操作に複数の意味があり、入力形式の変更だけで効果の処理結果が変わり得ます。

ここでいう runtime は、Program を実値へ評価する interpreter、handler stack、scheduler、env 解決を合わせた実行境界です。

確認済みの事実

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

• --program と通常の -c は resolve_context -> execute -> interpreter を通り、既定では default_interpreter が標準ハンドラと scheduled(...) を入れます。
  • doeff/cli/run_services.py:146-215
  • doeff/cli/run_services.py:215-292
• --hy は --runner を明示しなくても _dispatch_runner を通り、既定の doeff.runners.local.run_local は bare な run(program) を呼びます。
  • doeff/__main__.py:310-367
  • doeff/runners/local.py:13-35
• --program / -c で非既定 runner を指定した場合も、env、transform、apply、interpreter の通常経路を使わず runner 側へ分岐します。
  • doeff/__main__.py:368-403
• runner のテストは Pure(42) だけで同値性を確認しており、Ask、時間、並行処理、外部 promise を使う Program の意味が同じことは検証していません。
  • tests/cli/test_cli_runner.py:43-64

影響

• source form を --program から --hy へ変えただけで、Ask や scheduler effect が処理不能になり得ます。
• remote runner が通常経路の env / transform / interpreter 契約を再実装する必要があります。
• doeff.runners.local の説明する「従来経路と同一」が、効果を持つ Program では成立しません。
• 実行時の問題が Program 自体ではなく入口の違いに依存するため、必要な修正箇所が予測しにくくなります。

望ましい設計

入力形式は Program の作り方だけを担当し、その後は一つの runtime request と一つの実行契約へ合流させます。

概念上は次の形です。

--program / --hy / -c
        |
        v
 Program + RunRequest
        |
        v
runner (local / remote)
        |
        v
runtime(program, env=?, ctx=?)

runner は実行場所を選び、runtime は handler / scheduler / env の意味を所有します。同じ local runtime を通る限り、入力形式によって意味が変わらないことを構造的に保証します。

完了条件

• --program、--hy、-c が同じ中間契約へ合流する。
• local runner が通常の interpreter/runtime 契約を迂回して bare run(program) を呼ばない。
• env、--set、--apply、--transform、DoeffRunContext の扱いが入口間で明文化され、意図的に同一または明示的に拒否される。
• Ask、Spawn/Gather、Wait、missing env の各 Program を全入力形式で実行し、意味の同値性を検証する。
• custom/remote runner 向け契約を公開し、CLI 引数の再解析を不要にする。
• 既存の --runner と interpreter の責任重複を整理し、移行・廃止方針を文書化する。

関連

• feat: DoeffRunContext — pass CLI context to interpreters for remote execution #384 は interpreter へ CLI context を渡す機能を扱います。本 issue は、その context を渡す前後を含む実行意味の単一化を扱うため、完全な重複ではありません。

[proboscis]

監査追記 (2026-07-16, main b69f77b7 で再現確認)

本 issue の「同じ Program でも入口によって実行意味が変わる」という前提を、現行 main で正確な再現コマンドとして固定しました。

再現コマンド

状態効果（Put/Get）をトップレベルで使う同一ソースを、3通りの入口で実行します。

cd /path/to/doeff
SRC='from doeff_core_effects.effects import Get, Put
yield Put("count", 41)
c = yield Get("count")
c + 1'

# A: 既定（interpreter 経路） → result 42, exit 0
uv run doeff run -c "$SRC" --format json --no-runbox

# B: --runner doeff.runners.local.run_local（既定と同一文字列） → result 42, exit 0
uv run doeff run -c "$SRC" --format json --runner doeff.runners.local.run_local --no-runbox

# C: --runner doeff.runners.run_local（B と同一関数の別名参照） → UnhandledEffect, exit 1
uv run doeff run -c "$SRC" --format json --runner doeff.runners.run_local --no-runbox

実測結果:

A: {"status": "ok", ..., "result": 42, "result_type": "int"}          exit 0
B: {"status": "ok", ..., "result": 42, "result_type": "int"}          exit 0
C: UnhandledEffect: unhandled effect: Put (Put('count', 41)) (no handlers in scope)
   {"status": "error", "error": "UnhandledEffect", ...}               exit 1

分岐の機構（本文への補足）

B と C が分かれる直接の原因は、runner の分岐が関数の同一性ではなく参照文字列の比較で行われていることです。

• doeff/__main__.py:34 の _DEFAULT_RUNNER = "doeff.runners.local.run_local" に対し、handle_run は args.runner != _DEFAULT_RUNNER という文字列比較で経路を選びます（doeff/__main__.py:376,396）。
• そのため B（文字列が既定と一致）は runner を経由せず interpreter 経路（default_interpreter = 標準ハンドラ + scheduled()、doeff/cli/run_services.py:190-212）へ入り、C（同じ関数だが別名 doeff.runners.run_local、doeff/runners/__init__.py:18 の再公開）は runner 経路へ入って bare run(program)（doeff/runners/local.py:37）となり、ハンドラ不在で失敗します。
• doeff/runners/__init__.py:5-8 の「run_local は従来経路と同一の挙動」という docstring は、効果を持つ Program では成立しません（上記 C が反例）。

つまり本 issue の完了条件にある「意味の同値性検証」には、--runner の**参照文字列の正規化（resolve 後の callable 同一性で判定するか、既定 runner でも同じ runtime 契約を通す）**も含める必要があります。