phronomy 0.23.0 → 0.24.0

data/docs/design/durable-semantic-coordination/IMPLEMENTATION_REPORT.md

@@ -0,0 +1,106 @@
+# Durable Semantic Coordination V2 revision 2 — Implementation report
+
+作成日: 2026-09-07。設計承認日: 2026-09-06。
+対象baseline: `5472116cd99a63ec27875024c955ea82be612d6b`。
+承認済みADR-029/030/031とRC-01〜05に対する新規実装です。
+旧Complete Durability overlay、既存の作業ZIP、synthetic fan-out executionは使用しません。
+
+## 実装範囲
+
+| 対象 | 実装した動作 |
+|---|---|
+| Persistence | root/transaction viewともに8 repository。新しい3 recordはcurrent format `0.1`。Backendはopaque DurableRecordと明示的なidentity/revision/index metadataを扱う |
+| Handoff | Agent-domain APIへ移設。Source terminal・Context・exact Target予約・責務移転を同じtransactionで保存。Target terminalとrouting安定化も同一transaction |
+| Orchestrator | 既存parent AgentExecutionのstatic subagent Toolにchild ID/input/knowledge/config/outcomeを保存。直接の`dispatch_parallel`/`fan_out`にはsynthetic parentを作らない |
+| Team | TeamRoot/TeamExecution、task、worker slot、exact assignment/outcomeをCASで保存。coordinator/workerは既存Agent engineを使用。スケジューリングは既存の逐次方式 |
+| Team内部操作 | 保存済みのauthorized Tool batchをProvider順に適用。各`tool_invocation_id`の結果を保持し、`enqueue_task`/`finalize`を自動照合 |
+| Aggregate | pure/replay-safeな計算。canonical JSON結果またはエラーをterminal commit。保存前のクラッシュでは再計算可能、保存済みterminalでは再計算しない |
+| Runtime | Teamのprocess-local所有・admission・drainを追加。新しいTeam FSM/Workflow engineは追加しない |
+| Recovery | framework-owned操作はexact factから再開。外部Toolと混在したbatchでは外部の事実だけを既存Recovery APIで解決する |
+| 終了・削除 | exact子のcancel/reconciliation情報を保持。idle main Agentの`purge!`はHandoff anchorも同時削除。未完了turnのanchor削除は拒否 |
+
+Handoff graphは同じPersistence **instance**を使います。元main Agent IDがrouting anchorです。
+保存済みContextを新しいpolicyで再投影せず、保存済みworker割当を現在のschedulerで選び直しません。
+RuntimeのClass/Proc、listener、Task、CancellationTokenは永続化しません。
+
+## 公開経路
+
+| 目的 | API / 返却値 |
+|---|---|
+| Agent結果参照 | `store.execution_result(execution_id)`。owner、status、phase、result/errorと参照IDの凍結Hash |
+| Handoff結果参照 | `store.handoff_result(source_execution_id)`。そのturnのexact Targetまで辿る。graph/Agent hydration不要 |
+| Agent実行発見 | `store.list_executions(agent_id, after: nil, limit: 100)`。immutable execution records。active/terminal双方 |
+| Team結果参照 | `store.team_execution_result(run_id)` または `team.result(run_id)` |
+| Team実行発見 | `store.list_team_executions(team_id, after: nil, limit: 100)` または `team.executions(...)` |
+| Handoffの実行/復旧 | `Agent::HandoffRunner.new(main_agent:, handoffs:).invoke(input, config: {})`。未完了turnがあれば保存済み予約・入力を使用 |
+| static childの復旧 | `Orchestrator#resume(execution_id, config: {})` |
+| Teamの作成/復旧 | `team_definition id:, version:`、`create(team_id:, persistence:)`、`load(team_id, persistence:, on_event:)`、`resume(run_id)` |
+| 明示cancel | `team.cancel(run_id)` / `handoff_runner.cancel(execution_id)`。Orchestratorを含むAgentの既存操作は`config[:cancellation_token]` |
+
+一覧順はsemantic IDの辞書順、`after`は排他的ID cursor、`limit`は正の整数です。
+時刻順やリクエスト一意対応を意味しません。Applicationは候補を自身の相関情報と照合します。
+
+Agentの結果statusは既存Symbol、Teamの結果statusはcanonical Stringです。
+Teamのdefault aggregate結果もcanonical JSONのためHash keyはString、errorは例外オブジェクトではなく
+`class`/`message`等のデータです。aggregateに渡すassignmentのトップレベルとtask keyはSymbolです。
+
+Handoffの未開始Target予約は`status: :active, phase: :target_pending, reserved: true`で識別します。
+明示cancelした未開始Targetは予約IDを保持し、過去turnの結果に後続turnを代用しません。
+不存在は`Persistence::NotFoundError`、読み取り/復号失敗はそのエラーを返します。
+削除された結果を復元する機能や無期限retentionは追加していません。
+
+`Team.load`はTeam factsのhydrationのみです。子の実行/復旧は`resume`で開始します。
+Agentの`load`は既存Recovery契約を維持します。結果だけが必要なら上記Persistence参照APIを使います。
+Teamの`on_event`はhidden Agentsへ渡し、必要なRecovery/approval eventを受け取ります。
+`Team.stream`はcommit済みassignmentのRuntime通知です。新しい通知配送保証はありません。
+
+## RC対応表
+
+パスはリポジトリroot相対です。共通の追加障害specは
+`spec/phronomy/multi_agent/durable_coordination_spec.rb`です。
+
+| 要件 | 主な実装 | 検証根拠 |
+|---|---|---|
+| RC-01-A/B | `Persistence#execution_result` / `list_executions`、Team対応API | owner未loadの再構築環境でactive/terminal候補・ページング・結果を読み、Provider/所有登録を増やさない |
+| RC-01-C | `Persistence#handoff_result`、読み取り専用materialization | graph/ownerなしの予約参照、read障害、purge済み結果のNotFound。callback政策は既存`stream_callback_error_policy_spec.rb`でも検証 |
+| RC-02-A | Agent準備の既存F1 readback、`reconcile_terminal_error`、Team `admit`/`update` | Teamの各revision commit直後の応答喪失、Source移転の応答喪失、確定worker/child outcomeの再利用 |
+| RC-02-B/C | exact予約照合・atomic admission/CAS・bounded readback | read失敗と不存在を区別。Team admission後のreadback失敗ではdispatchなし。Backend契約はstale CAS、active重複、8 repository rollbackを検証 |
+| RC-03-A | Team definition snapshot、static child slot定義、Handoff graph/Target照合 | worker version不一致とTarget/graph不足でfail closed。既存Handoff統合specで別Persistenceを拒否 |
+| RC-03-B | immutable Context/input/knowledge/assignment/outcome | 現在policyを変更しても保存済みHandoffContextを使用。worker結果・static child結果・knowledge metadataを保持 |
+| RC-04-A | 既存Task待機/Runtime shutdown契約 | `task_spec.rb`、`agent/acs16_task_quiescence_spec.rb`、Runtime/admission specs。Runtime再構築テストで暗黙cancelを追加しない |
+| RC-04-B/C/D | Team cancel flag、Handoff exact cancellation、Agent子admission条件、既存terminal barrier | 予約worker/Targetを起動せずID保持。外部fact待ちのactive childを持つparentはactiveのままcancel情報を保存し再起動後も保持。既存admission/physical-quiescence specsと合わせて確認 |
+| RC-04-E | Source terminal linkとTarget cancel。責務はTargetのまま | transfer後cancel→再起動→後続turnでもSourceへ戻らず、過去の予約IDとcancel結果を維持 |
+| RC-05 | callback/外部効果とsemantic recordの分離 | mixed external/framework Tool batchは外部factだけresolveし、完了childを再実行しない。内部`finalize`の事実をApplicationへ問い合わせない |
+
+`lib/phronomy/testing/persistence_contract/coordination_repositories.rb`の新shared examplesは、
+外部backendにも公開される`phronomy/testing/persistence_contract`経由で実行されます。
+raw SPI/API snapshot/RBS、旧Handoff定数削除、EventLoop単一writer/causal barrier、
+logical-operation tracingの既存guardも維持しています。
+
+## 検証の範囲と限界
+
+実測環境はRuby 3.3.6。使用gemは配布ZIPの`verification/gems.txt`に記録します。
+配布対象に対する実測コマンド、結果、ログは同梱の検証記録を参照してください。
+
+- 通常RSpecは外部LLMへの接続を要するintegration tagを除外します。
+- 選択したHandoff/Orchestrator/Team integrationはWebMockで実行します。
+- 追加F4テストは、commit済みDurableRecordを複製し、新Backendと新Runtimeで復旧するモデルです。
+  これは実OSプロセスの強制終了や物理ディスクへのfsyncの実証ではありません。
+- 実LLM、Redis、PostgreSQL、OpenTelemetry等を使う別スイートは今回の実測対象外です。
+  optional依存/service未設定59件と既存obsolete2件の計61件がpendingです。
+- 外部backendのF4保存性と複数processの排他は、そのbackendとdeploymentの契約に依存します。
+  InMemory自身はプロセス終了後の保存を保証しません。
+- semantic cancellationは外部効果のrollbackではありません。TokenオブジェクトはRuntime-onlyです。
+  durable cancel flag/factがcommitした後は保持し、未確定外部処理は既存Recoveryで照合します。
+  fact/approval待ちをfailedにして子を忘れず、`ExecutionRehydrationRequiredError`で制御を返します。
+
+Frameworkが実施するのは、確定outcomeの再利用と未完了実行の同じsemantic identityでの復旧です。
+callback outbox/ACK、global generic class registry、Proc/Class永続化、distributed transaction、
+Team専用の第二execution engineは追加していません。
+
+## パッケージ
+
+完全版ファイルと削除manifestを同梱します。baseline/適用前後のハッシュを検査して適用します。
+新しいClassの配置をZeitwerkの命名規則に合わせ、旧overlayのdecorator ignoreは不要です。
+旧`MultiAgent::Handoff*`、`Runner`、`Coordinator`、`CoordinationState`の実装を削除します。
+適用・依存関係・VERIFY手順は配布rootの`README_APPLY_JA.md`を参照してください。

data/docs/design/durable-semantic-coordination/RECOVERY_CONTRACT_CLARIFICATIONS.md

@@ -0,0 +1,179 @@
+# V2復旧契約の明確化 — 承認済み追補
+
+更新日: 2026-09-06 / 文書改訂: V2 revision 2
+
+## 0. 位置づけ
+
+本追補は、V2への追加提案5点に対するユーザーの承認を反映した規範的な実装契約である。
+ADR-029/030/031およびImplementation Design V2と合わせて適用する。
+元のV2責務境界を維持し、結果参照・保存成否不明・wiring互換性・キャンセル・保証表現を明確化する。
+同じ論点の旧記述と差がある場合、本改訂の明確化を優先する。それ以外の既存ADRの契約を置き換えない。
+
+対象baselineは `5472116cd99a63ec27875024c955ea82be612d6b` のままとする。
+これは仕様の承認であり、実装完了やテスト成功を意味しない。
+公開メソッド名・例外名・既存キャンセル実装への対応付けはbaseline確認後に確定する。
+本書の要件IDは追跡用の文書上のIDであり、新しいRuntime ID・永続ID・APIではない。
+
+## 1. RC-01 — 確定結果の参照と実行の発見
+
+### 必須契約
+
+- Applicationはsemantic execution IDを指定して、owner identity、実行状態、確定結果またはエラーを読み取り専用で取得できる。
+- 対象はAgentExecutionとTeamExecution。Handoff/Orchestratorは既存のrouting anchor・parent execution・予約済みchild/Target IDを使用し、参照のための新しい実行entityを作らない。
+- Handoffでは指定した実行に結び付いたTarget outcomeを識別する。後続ターンの「最新のactive Agentの結果」を過去の呼び出し結果として代用しない。
+- admissionがcommitした後、Applicationが実行IDを受け取る前に停止する場合に備え、既知のagent_id/team_idから実行候補を発見できる公開経路を用意する。activeだけでなくterminalとなった実行も対象とする。
+- 結果参照・候補列挙はProvider/Tool起動、Agent continuation、callback再配送、ownership取得を伴わない。復旧を起動する操作とは区別する。
+- 結果が未確定、不存在、参照不能を区別する。Persistence障害やresult materialization失敗を「実行なし」「処理中」「成功で結果なし」に変換しない。
+- 基本状態と確定結果は保存済みrecordから取得する。継続実行に必要なgraph/Procを結果参照だけのために要求しない。既存codec/schemaの互換性要件は維持する。
+
+### 範囲の制限
+
+候補の発見は、Applicationのリクエストとの自動一意対応やsubmissionのexactly-onceを保証しない。
+複数候補がある場合、時刻が最新という理由だけで対象と断定せず、Applicationが保持する相関情報と照合する。
+Application固有のrequest ID・outbox・dedupはApplication責務であり、参照要件だけを理由に汎用idempotency基盤を追加しない。
+
+既存のretention/delete契約を維持する。削除済み結果の復元、無期限保存、新しい履歴管理サービスは要求しない。
+一覧の範囲・順序・ページング等は既存API/SPIを確認して最小限の公開経路に対応付ける。
+既存APIで満たせない箇所のみ追加し、内部repositoryをそのまま公開契約として露出させない。
+
+## 2. RC-02 — 不存在・競合・保存成否不明の区別
+
+### 共通判断規則
+
+| 観測 | 許可する判断・動作 |
+|---|---|
+| 正常なauthoritative readで予約済みIDの不存在を確認 | 親の最新状態・予約・キャンセル条件を確認し、同じ予約済みIDでadmissionを試みる |
+| exact IDのnonterminalを確認 | 同じ実行の既存Recovery契約へ進む |
+| exact IDのterminalを確認 | 保存済みoutcomeを利用する。replacement executionを作らない |
+| read timeout / I/O failure / record decode failure | 不存在とみなさず、状態を保持して既存のerror/retry契約へ進む |
+| write応答消失などでcommit成否不明 | 同じoperation identity・予約済みIDを保持してreadbackする。確認前に別IDや別assignmentを作らない |
+| 明確なrevision/admission競合 | 最新のauthoritative factsを再読し、予約・owner・入力との整合を検証する。競合を単純な成功とみなさない |
+
+readbackが利用する整合性は、admission/CASを保護する既存Persistence契約を満たすこと。
+cache/indexの不一致や読み取り障害を新規admissionの根拠にしない。
+不存在確認とadmissionの間の競合は既存のatomic admission/CASで防ぐ。
+外部semantic workはadmissionの成功が確定した後にのみ開始する。
+
+適用対象: Source Handoff transfer、Target admission/stabilization、parent child reservation/outcome、
+Team admission/enqueue/finalize/assignment/worker outcome/terminal。
+Team-owned enqueue/finalizeは既存方針のstable tool_invocation_idによるfact照合を維持する。
+
+成否不明を解決できない間は、確定していないローカル推測で次のsemantic処理へ進まない。
+無期限に同期待機せず、既存のPersistence error/retry経路へ制御を返す。
+Applicationにストレージ上の事実を創作させるmanual resolutionは追加しない。
+既存Agent/Persistenceの成否不明処理を再利用し、coordination専用の第二transaction engineを作らない。
+
+## 3. RC-03 — 復旧時wiringの最低互換性
+
+### 照合対象
+
+| 対象 | 継続前に必要な照合 |
+|---|---|
+| Agent/Team定義 | 保存されたdefinition id/versionと現在の定義。既存の明示的な互換・移行契約がなければ一致を要求 |
+| Orchestrator child | 保存済みslotとstatic subagent登録から解決した定義、予約済みagent_id/execution_id、ownerとの一致 |
+| Handoff | original main anchor、保存済みactive/Target ID、必要なgraph接続、同じPersistence instance/domain |
+| Team worker/coordinator | Team lineage、保存済みworker slotと定義、予約済みAgent/実行ID、保存済みassignmentとの一致 |
+
+必要な登録やTargetがない、定義が不一致、Persistence境界が異なる場合は、semantic workを開始せずfail closedとする。
+エラーから対象identityと不足・不整合の種類が分かるようにする。既存のconfiguration/rehydration error契約を使う。
+結果の読み取りだけに不要な実行wiringを要求しない（RC-01）。
+
+### 確定済みfactの優先
+
+- 確定済みHandoffContextを現在のHandoffPolicyで再投影しない。
+- 確定済みchild input/configを現在のデフォルトで置き換えない。
+- 確定済みassignmentを現在のschedulerで選び直さない。
+- 確定済みchild/worker/final aggregate outcomeを再計算しない。
+- 未確定のscheduler/aggregateは既存V2のreplay-safe契約に従って再実行できる。保存済み入力に対する意味の互換性をApplicationが保つ。
+
+Phronomyが検査できるのは宣言されたidentity/versionと構造であり、Rubyコードの意味の同一性ではない。
+同じversionのまま非互換な実装に変更しないことはApplication責務。
+versionを上げるだけで旧実行の復旧が自動的に可能になるわけではなく、対応する定義または既存の明示的移行契約が必要。
+Proc/Classの永続化、ソースハッシュ、policy descriptor、global generic class registryは追加しない。
+
+## 4. RC-04 — 待機終了とsemantic cancellation
+
+### 操作の区別
+
+| 操作・状態 | 契約 |
+|---|---|
+| Applicationが待機をやめる・接続が切れる・観測timeout | それだけではdurable executionへのsemantic cancellationとしない |
+| Runtime shutdown / process loss | それだけではsemantic cancellationを確定しない。既存shutdown/draining契約で実行を保存・復旧可能に保つ |
+| 明示的なsemantic cancellation要求 | 既存Agent cancellation契約に従い、対象owner/runと予約済み実行に対応付ける |
+| recovery resolution / approval待ち | failureや自動cancelへ変換せず、既存V2のrehydration経路を維持する |
+
+既存Taskの明示cancelなど、もともとsemantic cancellationを要求するAPIはその契約を維持する。
+単なる観測終了と同じ操作として扱わない。具体的な公開API対応はbaseline確認時に記載する。
+
+### 子実行への適用
+
+| 子の状態 | 親runへのsemantic cancellationが受理された場合 |
+|---|---|
+| 予約済み・未開始 | 現在の親runに属する新規dispatchを止める。予約情報を失わず、キャンセルのために子を起動しない |
+| 実行中・admission競合中 | exact reserved IDの状態を確認し、既存Agent cancellationを適用する。単にローカルTaskを破棄して処理済みとみなさない |
+| terminal | durable outcomeを維持する。過去の成功・失敗をキャンセル済みに書き換えたり補償再実行したりしない |
+
+親cancelと子admissionの競合は、最新の親run状態・既存admission契約で処理する。
+既にadmitされた子は実行中の規則で照合し、別IDの子を作らない。
+親terminalizationと子settlementの順序は既存Agentのcancel/terminal barrier契約へ対応付ける。
+未完了の子がある場合、そのexact IDと必要なcancel/reconciliation状態を失ってはならない。
+restart後にも既存の復旧経路から対象を発見できることを必須とし、未対応の子を忘れたまま親の全処理完了を主張しない。
+新規の公開terminal statusや別のcancel schedulerを本追補だけで追加しない。
+
+キャンセルの範囲は当該親runが所有する子に限定し、共有Agentの別実行・後続Team runへ波及させない。
+HandoffのSourceはtransfer commit後にhanded_offであり、後からSourceをcancelしてtransferを取り消したことにしない。
+現在のHandoff turnに対する明示cancelは、保存済みrouting/予約から該当Target実行へ対応付ける。
+観測終了・cancelを理由にactive responsibilityを元のmain Agentへ戻さない。
+
+外部Provider/Toolのcancelは副作用の取り消しを保証しない。成否不明は既存Agent Recovery契約で解決する。
+既存機構で上記の順序・再発見を満たせず第二実行エンジン等が必要なら、Stop Conditionとして報告する。
+
+## 5. RC-05 — durability保証の統一表現
+
+> 確定済みのdurable outcomeは再利用する。未完了の実行は同じsemantic identityで復旧する。
+> 外部Provider/Tool処理の成否不明は既存Agent Recovery契約に従って解決する。
+
+「開始していないと確認できた場合だけ開始」はframework-owned execution admissionの判断を指す。
+外部システムへのリクエストが一度も届いていないことや、外部副作用のexactly-onceを意味しない。
+未完了実行を同じIDで復旧することも、内部の全Provider/Tool呼び出しの無条件再送を意味しない。
+callback喪失、ローカルTask喪失、観測timeoutをsemantic work再実行の理由にしない。
+
+## 6. 検証条件・対応付け
+
+以下は必要な振る舞いの検証条件であり、新しいspecファイルの本数指定ではない。
+既存specが契約を検証している場合はその根拠を記録し、不足ケースのみ追加する。
+
+| ID | 検証シナリオ | 必須結果 |
+|---|---|---|
+| RC-01-A | terminal commit後、callback前にprocess loss | exact IDで同じ結果を読み取れ、semantic work/callbackを再実行しない |
+| RC-01-B | admission応答前にcallerを失い、実行はterminalになる | owner identityから候補を発見できる。複数候補を勝手に一つへ決めない |
+| RC-01-C | graph/listenerなしで結果参照、または結果のread/decode失敗 | 不要なwiringを要求しない。参照失敗を成功・不存在に偽装しない |
+| RC-02-A | 各semantic commitの成功直後に応答を喪失 | readbackで既存factを採用し、別ID・二重assignmentを作らない |
+| RC-02-B | read障害、authoritative不存在、CAS競合を別々に注入 | 状態を混同せず、成功が確定したadmission後だけ実行する |
+| RC-02-C | 成否不明後のreadbackも失敗 | 状態を保ち制御を返す。無期限の同期待機・新規実行をしない |
+| RC-03-A | subagent登録削除、定義version不一致、Target不足 | 継続前にfail closed。別定義・別Targetに置き換えない |
+| RC-03-B | 互換な現在のwiringで復旧 | 確定済みContext/input/assignment/outcomeを再計算しない |
+| RC-04-A | 待機終了・shutdown・process loss | 暗黙のsemantic cancellationを確定しない |
+| RC-04-B | 親cancel時に子が未開始／active／terminal | 状態別規則を守り、exact ID・確定outcomeを維持する |
+| RC-04-C | 親cancelとchild admission/terminalを競合させる | 子を紛失せず、既存cancel/terminal barrierへ整合する |
+| RC-04-D | cancel要求後の各commit境界でprocess loss | 同じrunの未完了子を復旧経路から発見・照合できる |
+| RC-04-E | Handoff transfer後の観測終了・明示cancel | Sourceへ巻き戻さず、当該Target実行にだけ適用する |
+| RC-05-A | 外部Tool効果の成否不明とcallback喪失を別々に注入 | 前者は既存Recovery、後者は確定結果参照。盲目的再実行なし |
+
+baseline統合時には、各RC IDについて「公開API/SPI・実装箇所・既存/追加spec」を対応表に記録する。
+特に結果発見API、互換version扱い、cancel/terminal barrierは未確認のメソッド名で完了扱いにしない。
+focused・backend・fault・full suiteの実行成功は、target checkoutでの実測が必要。
+本資料改訂時点では実行していない。
+
+## 7. 増やさない責務
+
+callback outbox/ACK、terminal-delivery index、standalone fan-out用synthetic execution、
+Proc/Class serialization、global generic registry、独立Persistence間のdistributed transaction、
+Team専用の第二execution engineは引き続き対象外。
+公開結果参照はApplicationの通知配送・外部副作用dedupを代替しない。
+
+## 8. 実装との対応
+
+2026-09-07の実装・公開API/SPI・検証範囲は
+[IMPLEMENTATION_REPORT.md](IMPLEMENTATION_REPORT.md)を参照する。
+本追補の責務境界と必須契約は変更しない。

data/docs/design/durable-semantic-coordination/RESPONSIBILITY_BOUNDARY_REVIEW.md

@@ -0,0 +1,302 @@
+# Phronomy Durability Responsibility-Boundary Review
+
+Status: Accepted V2 revision 2, 2026-09-06.
+
+## 1. Purpose
+
+The earlier "Complete Durability" plan attempted to make every visible completion
+boundary resilient to process loss. That produced technically defensible
+protocols, but responsibility analysis showed that several of those protocols
+belonged outside the Phronomy semantic execution engine.
+
+This review narrows durability to the state Phronomy **owns and can reconcile
+authoritatively**.
+
+The objective is not "persist everything". The objective is:
+
+> Preserve framework-owned semantic progress across process/runtime loss without
+> blindly repeating work already known to have completed.
+
+## 2. Responsibility test
+
+A fact belongs to Phronomy durability when all of the following are true:
+
+1. Phronomy creates or owns the semantic operation.
+2. Phronomy has a canonical durable identity for that operation.
+3. Phronomy can determine its authoritative state from `Persistence`.
+4. Repeating the operation after losing Runtime state could duplicate semantic
+   work or violate the public abstraction.
+5. The required recovery does not require Phronomy to emulate an Application
+   transaction coordinator.
+
+A concern remains Application responsibility when one or more of the following
+are true:
+
+1. it is an arbitrary callback or external side effect;
+2. its exactly-once/idempotency semantics depend on an external system;
+3. the Application can naturally handle it with an outbox, job queue,
+   idempotency key, database transaction, or its own Workflow;
+4. persisting it would force Phronomy to serialize or reconstruct Application
+   code/Runtime objects;
+5. the API is only a convenience operation and has no existing durable semantic
+   root.
+
+## 3. Revised boundary
+
+| Concern | Owner | Restart-spanning guarantee |
+|---|---|---|
+| AgentExecution semantic status | Phronomy | Yes |
+| Agent result/error durable evidence | Phronomy | Yes |
+| Agent `on_event` callback invocation | Runtime/Application | No |
+| Callback side-effect deduplication | Application | No framework guarantee |
+| Handoff active Agent responsibility | Phronomy | Yes |
+| Handoff reserved Target execution | Phronomy | Yes |
+| Handoff graph/Policy Ruby objects | Application Runtime wiring | Re-supplied, not persisted |
+| Orchestrator child reservation/outcome inside an AgentExecution | Phronomy | Yes |
+| Standalone `dispatch_parallel` / `fan_out` convenience call | Runtime | No |
+| Team task queue | Phronomy | Yes |
+| Team task -> worker assignment | Phronomy | Yes |
+| Team worker execution/result | Phronomy | Yes |
+| Team scheduler callback | Application pure/replay-safe function | May be rerun before assignment commit |
+| Team aggregator callback | Application pure/replay-safe function | May be rerun until result commit |
+| Team progress/terminal callback | Runtime/Application | No |
+| Email/webhook/DB side effect triggered by a result | Application | Use Application transaction/outbox/idempotency |
+
+## 4. Why restart-spanning `on_event` is removed
+
+The earlier design stored a terminal-delivery descriptor, indexed pending
+deliveries, redelivered them from `Agent.load`, and acknowledged callback attempts
+with a second CAS write.
+
+That protocol solved "terminal commit succeeded but callback was not observed".
+It did **not** solve exactly-once effects. If the process died after the callback
+performed an external action but before ACK, the callback could run again.
+
+Therefore the Application still needed idempotency/deduplication. Phronomy would
+have been maintaining an outbox-like protocol while being unable to own the
+external transaction.
+
+The revised boundary is:
+
+```text
+semantic completion              Phronomy
+same-process event observation   Runtime
+external side effect             Application
+restart-spanning notification    Application outbox/job/Workflow when required
+```
+
+Process loss after semantic terminal commit but before `on_event` is therefore
+allowed to lose the callback observation. It must **not** lose or replay the
+semantic result.
+
+## 5. Why Team aggregation is replay-safe instead of uncertainty-managed
+
+The earlier design treated arbitrary `aggregate` as an X0 callback:
+
+```text
+mark aggregation started
+invoke callback
+if process dies -> outcome unknown -> manual resolution
+```
+
+That is appropriate for an arbitrary external effect, but `aggregate` is part of
+Team result computation. Letting it perform one-shot external effects makes a
+simple result-composition hook behave like an application transaction.
+
+The revised contract is:
+
+- `aggregate` receives canonical durable assignment results;
+- it must have no externally observable one-shot side effects;
+- repeated invocation with the same canonical inputs must be semantically
+  equivalent;
+- if the process dies before the aggregate result is durably committed, Phronomy
+  may call `aggregate` again;
+- external actions based on the Team result happen **after** Team completion in
+  Application code.
+
+This removes `aggregation=started`, unknown-outcome recovery and manual
+aggregation resolution.
+
+## 6. Why standalone Orchestrator fan-out is Runtime-only
+
+`Orchestrator` already has a canonical durable root when it is executing as an
+Agent:
+
+```text
+Orchestrator AgentRoot
+  -> Orchestrator AgentExecution
+     -> durable child coordination snapshot
+```
+
+A direct Application call to:
+
+```ruby
+orchestrator.dispatch_parallel(...)
+orchestrator.fan_out(...)
+```
+
+has no such parent execution.
+
+The previous plan created a synthetic private AgentExecution only to make this
+convenience method durable. That:
+
+- changed Agent admission semantics;
+- restricted arbitrary invocation-only Agent classes;
+- required a new direct-fan-out recovery mode;
+- made a helper method participate in durable execution identity merely to satisfy
+  a blanket "everything durable" statement.
+
+The revised rule is:
+
+```text
+inside an existing Orchestrator AgentExecution
+  -> durable child coordination
+
+direct standalone convenience call
+  -> Runtime-only; current-process completion only
+```
+
+If an Application requires durable fan-out, it should run it through an
+Orchestrator AgentExecution or model the application process as a Workflow.
+
+## 7. Handoff remains framework-durable
+
+Handoff is not an Application notification problem.
+
+If Phronomy exposes "active responsibility moved A -> B", then process loss must
+not make the framework forget that B is active and rerun A merely to rediscover
+the route.
+
+Therefore Phronomy continues to own:
+
+- `main_agent.agent_id` as the durable Handoff routing anchor;
+- durable active Agent identity;
+- immutable transferred HandoffContext reference;
+- reserved exact Target `execution_id`;
+- target absent/active/terminal reconciliation;
+- multi-hop routing state.
+
+Application code still owns the current Handoff graph and Policy objects and must
+re-supply compatible wiring after restart.
+
+## 8. TeamCoordinator remains durable, but only for Team semantics
+
+The TeamCoordinator durable scope is retained because Phronomy itself owns the
+queue/assignment/worker abstraction.
+
+Phronomy therefore persists:
+
+```text
+TeamRoot
+TeamExecution
+canonical task records
+worker slot identities
+task -> worker assignment
+reserved worker Agent/execution IDs
+worker terminal result/error
+final Team result/error
+```
+
+It does **not** persist:
+
+```text
+scheduler Proc
+aggregator Proc
+stream callbacks
+terminal callbacks
+Task handles
+FSMSession
+external side effects
+```
+
+This is a deliberate product boundary. If durable Team semantics still proves
+disproportionately expensive after these reductions, implementation must stop and
+report that fact rather than silently expanding framework responsibilities again.
+
+## 9. Persistence consequence
+
+The durable root still expands to:
+
+```text
+contents
+agents
+journals
+executions
+workflow_states
+handoff_states
+teams
+team_executions
+```
+
+However the following previous additions are removed:
+
+```text
+executions.list_delivery_pending
+execution delivery_pending backend index
+team_executions.list_delivery_pending
+Team terminal-delivery descriptor/index
+```
+
+No second CAS terminal-delivery ACK protocol is required.
+
+## 10. Recovery consequence
+
+Recovery is now about semantic execution/coordination only:
+
+```text
+Agent
+  active/nonterminal execution recovery
+
+Handoff
+  active responsibility / exact Target continuation
+
+Orchestrator
+  existing parent AgentExecution + exact child reconciliation
+
+Team
+  active TeamExecution + task/assignment/worker reconciliation
+```
+
+It is **not** responsible for reconstructing missed Application callback delivery.
+
+## 11. Explicit non-goals
+
+This redesign does not provide:
+
+- exactly-once Provider, Tool, callback, webhook, email or database effects;
+- restart-spanning delivery of arbitrary callbacks;
+- recovered process-local Tasks;
+- a distributed transaction across external systems;
+- persistence of Ruby Classes, Procs, callbacks, FSMSessions or EventLoop queues;
+- durable semantics for every convenience method simply because it exists.
+
+## 12. Acceptance criterion for future implementation work
+
+Before adding any new durable field/protocol, ask:
+
+> If this state is lost, does Phronomy risk rerunning or misrouting semantic work
+> that Phronomy itself owns?
+
+If **no**, the state should normally remain Runtime/Application responsibility.
+
+If **yes**, add the smallest purpose-specific durable fact needed to reconcile it.
+
+## 13. Accepted clarification after V2 review
+
+The five accepted [recovery contracts](RECOVERY_CONTRACT_CLARIFICATIONS.md)
+make the existing responsibility boundary testable:
+
+1. Read-only outcome access and retained execution discovery replace reliance on
+   callback observation, without promising notification delivery or request dedup.
+2. Failed reads and unknown commit outcomes never authorize replacement work;
+   use existing authoritative reads, atomic admission and CAS reconciliation.
+3. Declared definition/slot/graph compatibility is checked before continuation;
+   committed facts outrank changed current wiring. Code compatibility is an
+   Application obligation, not Proc serialization or code hashing.
+4. Observation loss/shutdown and semantic cancellation are distinct. Cancellation
+   respects exact owned child executions and existing Agent terminal barriers.
+5. Durability means confirmed outcome reuse and exact execution recovery;
+   unknown external effects remain under existing Agent Recovery, not exactly once.
+
+These are implementation contracts within the accepted scope. No callback outbox,
+standalone synthetic parent, generic registry or second Team engine is authorized.

data/docs/features.md

@@ -78,7 +78,7 @@ rather than implicitly inheriting the parent revision. The Stable
 | Feature | Stability |
 |---|---|
 | **Workflow asynchronous pattern** — Start async work, return immediately, and continue through `Workflow#signal` | Beta |
-| **Semantic Multi-Agent Handoff** — `MultiAgent::Handoff` transfers active responsibility from an explicit Source Agent to a Target Agent, projects policy-bounded Context with provenance, keeps the Target active across user turns within the same Runtime/main-Agent lifetime, and does not claim durable continuation across Runtime reset | Beta |
+| **Durable Agent Handoff** — `Agent::Handoff` and `Agent::HandoffRunner` persist responsibility, immutable Context and exact Target reservation in one Persistence domain; current graph wiring is required for continuation | Beta |
 | **GeneratorVerifier** — Generator-Verifier loop with injectable prompts/parsers | Beta |
 | **`Phronomy::MultiAgent::Orchestrator`** — Parallel subagent dispatch, fan-out, and `subagent` DSL | Beta |
 | **`Phronomy::MultiAgent::TeamCoordinator`** — LLM coordinator with stateful worker Agents | Beta |
@@ -140,3 +140,37 @@ current compatibility contract.
 
 For runtime ownership and the distinction between public lifecycle APIs and
 private execution machinery, see [Runtime and concurrency](runtime-and-concurrency.md).
+
+### Durable semantic coordination (V2 revision 2)
+
+Static `Orchestrator.subagent` Tools invoked inside a parent AgentExecution reserve
+child Agent/execution identities before dispatch and reuse retained outcomes.
+Direct `dispatch_parallel` / `fan_out` calls remain Runtime-only convenience APIs.
+`Orchestrator#resume(execution_id)` continues retained parent coordination.
+
+`TeamCoordinator` requires `team_definition id:, version:` and provides
+`create`, `load`, `get`, `resume`, `executions`, `result` and scoped `cancel`.
+Team tasks, worker assignments, exact child identities and aggregate outcomes
+are durable facts. Workers still execute sequentially through the existing Agent
+engine. `schedule` and `aggregate` must be pure and replay-safe; aggregate returns
+canonical JSON data. Default assignment results have string keys and error data
+contains class/message strings. Arbitrary Ruby objects are not durable results.
+
+`Persistence#execution_result` / `team_execution_result` read exact results;
+`list_executions` / `list_team_executions` discover retained active and terminal
+runs by known owner ID. Reads do not load Runtime owners or deliver callbacks.
+The cursor is an exclusive lexical execution ID and limit must be positive.
+Retention and request correlation remain Application/backend policy.
+
+Guarantee: confirmed outcomes are reused, unfinished work keeps its semantic ID,
+and external outcome uncertainty uses Agent Recovery. For F1/F4 this is
+conditional on a conforming retained Persistence domain and compatible current
+wiring. InMemory provides transaction/CAS semantics but is not durable disk storage.
+Callbacks/streams/Tasks are Runtime observations; there is no restart-spanning
+notification outbox, ACK, synthetic fan-out execution or external exactly-once
+claim. See [the migration](migrations/durable-semantic-coordination-v2.md).
+
+`Persistence#handoff_result(source_execution_id)` also resolves the exact Handoff
+turn read-only, including a current absent-but-reserved Target, without graph or
+Agent hydration. Purging an idle main Agent removes its Handoff anchor; pending
+coordination rejects purge rather than discarding its reservation.