phronomy 0.29.0 → 0.30.1

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

@@ -6,107 +6,107 @@
 > [ADR-034](../../decisions/034-handoff-runner-coordination-ownership.md).
 > Handoff and HandoffPolicy remain in Agent at this stage.
 
-作成日: 2026-09-07。設計承認日: 2026-09-06。
-対象baseline: `5472116cd99a63ec27875024c955ea82be612d6b`。
-承認済みADR-029/030/031とRC-01〜05に対する新規実装です。
-旧Complete Durability overlay、既存の作業ZIP、synthetic fan-out executionは使用しません。
+Created: 2026-09-07. Design approved: 2026-09-06.
+Baseline: `5472116cd99a63ec27875024c955ea82be612d6b`.
+This is a new implementation of the approved ADR-029/030/031 and RC-01 through RC-05.
+It does not use the old Complete Durability overlay, existing work ZIPs, or synthetic fan-out executions.
 
-## 実装範囲
+## Implementation scope
 
-| 対象 | 実装した動作 |
+| Area | Implemented behavior |
 |---|---|
-| 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 / 返却値 |
+| Persistence | Eight repositories in both root and transaction views; the three new records use current format `0.1`. Backend handles opaque DurableRecords and explicit identity/revision/index metadata |
+| Handoff | Moved to the Agent-domain API. Source terminal state, Context, exact Target reservation, and responsibility transfer are persisted in one transaction. Target terminal state and routing stabilization also share one transaction |
+| Orchestrator | Stores child ID/input/knowledge/config/outcome for static subagent Tools in the existing parent AgentExecution. Direct `dispatch_parallel`/`fan_out` calls do not create synthetic parents |
+| Team | Persists TeamRoot/TeamExecution, tasks, worker slots, and exact assignments/outcomes using CAS. Coordinators/workers use the existing Agent engine. Scheduling retains the existing sequential approach |
+| Internal Team operations | Applies persisted authorized Tool batches in Provider order. Retains the result of each `tool_invocation_id` and automatically reconciles `enqueue_task`/`finalize` |
+| Aggregate | Pure/replay-safe computation. Commits canonical JSON results or errors as terminal outcomes. Recalculation is possible after a crash before persistence, but not for a persisted terminal outcome |
+| Runtime | Adds process-local Team ownership, admission, and draining. Does not add a new Team FSM/Workflow engine |
+| Recovery | Resumes framework-owned operations from exact facts. In batches mixed with external Tools, only external facts are resolved through the existing Recovery API |
+| Termination and deletion | Retains cancellation/reconciliation information for exact children. `purge!` on an idle main Agent also deletes the Handoff anchor; deleting an anchor for an incomplete turn is rejected |
+
+A Handoff graph uses the same Persistence **instance**. The original main Agent ID is the routing anchor.
+Persisted Context is not reprojected using a new policy, and persisted worker assignments are not reselected using the current scheduler.
+Runtime Classes/Procs, listeners, Tasks, and CancellationTokens are not persisted.
+
+## Public entry points
+
+| Purpose | API / return value |
 |---|---|
-| 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`です。
-
-| 要件 | 主な実装 | 検証根拠 |
+| Agent result access | `store.execution_result(execution_id)`; a frozen Hash containing owner, status, phase, result/error, and reference IDs |
+| Handoff result access | `store.handoff_result(source_execution_id)`; follows the exact Target of that turn. No graph/Agent hydration is required |
+| Agent execution discovery | `store.list_executions(agent_id, after: nil, limit: 100)`; immutable execution records, both active and terminal |
+| Team result access | `store.team_execution_result(run_id)` or `team.result(run_id)` |
+| Team execution discovery | `store.list_team_executions(team_id, after: nil, limit: 100)` or `team.executions(...)` |
+| Handoff execution/recovery | `Agent::HandoffRunner.new(main_agent:, handoffs:).invoke(input, config: {})`; uses the persisted reservation and input if an incomplete turn exists |
+| Static child recovery | `Orchestrator#resume(execution_id, config: {})` |
+| Team creation/recovery | `team_definition id:, version:`, `create(team_id:, persistence:)`, `load(team_id, persistence:, on_event:)`, `resume(run_id)` |
+| Explicit cancellation | `team.cancel(run_id)` / `handoff_runner.cancel(execution_id)`; existing Agent operations, including Orchestrator, use `config[:cancellation_token]` |
+
+Lists are ordered lexicographically by semantic ID; `after` is an exclusive ID cursor, and `limit` is a positive integer.
+This does not imply chronological ordering or unique correspondence to a request. Applications match candidates against their own correlation information.
+
+Agent result status uses existing Symbols; Team result status uses canonical Strings.
+The default Team aggregate result is also canonical JSON: Hash keys are Strings, and errors are data such as
+`class`/`message`, not exception objects. Top-level assignment keys and task keys passed to aggregate are Symbols.
+
+An unstarted Handoff Target reservation is identified by `status: :active, phase: :target_pending, reserved: true`.
+Explicit cancellation of an unstarted Target preserves its reserved ID; a later turn never substitutes for the result of an earlier turn.
+Absence produces `Persistence::NotFoundError`; read/decode failures produce their actual errors.
+No facility to restore deleted results or retain them indefinitely has been added.
+
+`Team.load` hydrates Team facts only. Child execution/recovery starts through `resume`.
+Agent `load` retains its existing Recovery contract. Use the Persistence access APIs above when only results are needed.
+Team's `on_event` is passed to hidden Agents to receive required Recovery/approval events.
+`Team.stream` provides Runtime notifications of committed assignments; it adds no notification-delivery guarantee.
+
+## RC mapping
+
+Paths are relative to the repository root. The shared additional fault specs are in
+`spec/phronomy/multi_agent/durable_coordination_spec.rb`.
+
+| Requirement | Main implementation | Validation evidence |
 |---|---|---|
-| 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`を参照してください。
+| RC-01-A/B | `Persistence#execution_result` / `list_executions`, and corresponding Team APIs | Reads active/terminal candidates, pagination, and results in a reconstructed environment without loading the owner; does not invoke Providers or add ownership registrations |
+| RC-01-C | `Persistence#handoff_result`, read-only materialization | Reservation access without graph/owner, read failures, and NotFound for purged results. Callback policy is also covered by the existing `stream_callback_error_policy_spec.rb` |
+| RC-02-A | Existing F1 readback during Agent preparation, `reconcile_terminal_error`, Team `admit`/`update` | Lost acknowledgements immediately after each Team revision commit and Source transfer; reuse of committed worker/child outcomes |
+| RC-02-B/C | Exact reservation reconciliation, atomic admission/CAS, bounded readback | Distinguishes read failure from absence. No dispatch after a failed readback following Team admission. Backend contracts check stale CAS, duplicate active records, and rollback across eight repositories |
+| RC-03-A | Team definition snapshots, static child slot definitions, Handoff graph/Target matching | Fails closed on worker-version mismatch or missing Target/graph. Existing Handoff integration specs reject a different Persistence instance |
+| RC-03-B | Immutable Context/input/knowledge/assignment/outcome | Uses persisted HandoffContext even when the current policy changes. Preserves worker results, static child results, and knowledge metadata |
+| RC-04-A | Existing Task waiting/Runtime shutdown contracts | `task_spec.rb`, `agent/acs16_task_quiescence_spec.rb`, and Runtime/admission specs. Runtime reconstruction tests introduce no implicit cancellation |
+| RC-04-B/C/D | Team cancellation flags, exact Handoff cancellation, Agent child-admission conditions, existing terminal barriers | Preserves reserved worker/Target IDs without starting them. A parent with an active child awaiting external facts remains active, persists cancellation information, and retains it after restart. Checked together with existing admission/physical-quiescence specs |
+| RC-04-E | Source terminal link and Target cancellation; responsibility remains with Target | Cancellation after transfer, restart, and a later turn do not return responsibility to Source; historical reserved IDs and cancellation results are preserved |
+| RC-05 | Separation of callbacks/external effects from semantic records | Mixed external/framework Tool batches resolve only external facts and do not rerun completed children. Application is not asked to determine facts about internal `finalize` |
+
+The new shared examples in `lib/phronomy/testing/persistence_contract/coordination_repositories.rb`
+run through `phronomy/testing/persistence_contract`, which is also exposed to external backends.
+Existing guards for raw SPI/API snapshots/RBS, removal of old Handoff constants, the EventLoop single writer/causal barrier,
+and logical-operation tracing are preserved.
+
+## Validation scope and limitations
+
+The measured environment is Ruby 3.3.6. Gem versions are recorded in the distribution ZIP's `verification/gems.txt`.
+See the accompanying verification records for commands, results, and logs measured against the distributed files.
+
+- Ordinary RSpec runs exclude integration tags requiring connections to external LLMs.
+- Selected Handoff/Orchestrator/Team integration tests run with WebMock.
+- Added F4 tests model recovery by copying committed DurableRecords and using a new Backend and Runtime.
+  They do not demonstrate forced termination of a real OS process or fsync to physical storage.
+- Separate suites using live LLMs, Redis, PostgreSQL, OpenTelemetry, and similar dependencies are outside this measurement.
+  There are 61 pending cases: 59 with optional dependencies/services unconfigured and two existing obsolete cases.
+- F4 durability and exclusion across multiple processes for external backends depend on the backend and deployment contracts.
+  InMemory itself does not guarantee persistence after process termination.
+- Semantic cancellation does not roll back external effects. Token objects are Runtime-only.
+  Committed durable cancellation flags/facts are retained, and uncertain external operations are reconciled through existing Recovery.
+  Waiting for facts/approval is not converted into failure that forgets a child; control returns through `ExecutionRehydrationRequiredError`.
+
+The framework reuses committed outcomes and recovers incomplete executions with the same semantic identity.
+It adds no callback outbox/ACK, global generic class registry, Proc/Class persistence, distributed transaction,
+or second execution engine dedicated to Team.
+
+## Package
+
+The package includes complete files and a deletion manifest. Application checks the baseline and pre/post-application hashes.
+New Class locations follow Zeitwerk naming conventions; the old overlay's decorator ignore is unnecessary.
+The old `MultiAgent::Handoff*`, `Runner`, `Coordinator`, and `CoordinationState` implementations are removed.
+See `README_APPLY_JA.md` at the distribution root for application, dependencies, and VERIFY procedures.

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

@@ -1,179 +1,178 @@
-# V2復旧契約の明確化 — 承認済み追補
+# V2 Recovery Contract Clarifications - Approved Addendum
 
-更新日: 2026-09-06 / 文書改訂: V2 revision 2
+Updated: 2026-09-06 / Document revision: V2 revision 2
 
-## 0. 位置づけ
+## 0. Purpose and authority
 
-本追補は、V2への追加提案5点に対するユーザーの承認を反映した規範的な実装契約である。
-ADR-029/030/031およびImplementation Design V2と合わせて適用する。
-元のV2責務境界を維持し、結果参照・保存成否不明・wiring互換性・キャンセル・保証表現を明確化する。
-同じ論点の旧記述と差がある場合、本改訂の明確化を優先する。それ以外の既存ADRの契約を置き換えない。
+This addendum is a normative implementation contract reflecting the user's approval of five additions to V2.
+Apply it together with ADR-029/030/031 and Implementation Design V2.
+It preserves the original V2 responsibility boundaries while clarifying result access, unknown persistence outcomes, wiring compatibility, cancellation, and guarantee wording.
+Where an earlier statement on the same issue differs, these clarifications take precedence. They do not otherwise replace existing ADR contracts.
 
-対象baselineは `5472116cd99a63ec27875024c955ea82be612d6b` のままとする。
-これは仕様の承認であり、実装完了やテスト成功を意味しない。
-公開メソッド名・例外名・既存キャンセル実装への対応付けはbaseline確認後に確定する。
-本書の要件IDは追跡用の文書上のIDであり、新しいRuntime ID・永続ID・APIではない。
+The baseline remains `5472116cd99a63ec27875024c955ea82be612d6b`.
+This is specification approval, not evidence of implementation completion or successful tests.
+Public method names, exception names, and mappings to the existing cancellation implementation will be finalized after inspecting the baseline.
+Requirement IDs in this document are for traceability; they are not new Runtime IDs, persistent IDs, or APIs.
 
-## 1. RC-01 — 確定結果の参照と実行の発見
+## 1. RC-01: Accessing final results and discovering executions
 
-### 必須契約
+### Required contract
 
-- 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 can obtain the owner identity, execution state, and committed result or error by semantic execution ID through read-only access.
+- This covers AgentExecution and TeamExecution. Handoff/Orchestrator use existing routing anchors, parent executions, and reserved child/Target IDs; they do not create a new execution entity just for result access.
+- Handoff identifies the Target outcome associated with the specified execution. The latest active Agent result from a later turn must not substitute for an earlier invocation's result.
+- Provide a public path to discover execution candidates from a known agent_id/team_id, covering an interruption after admission commits but before Application receives the execution ID. Include terminal as well as active executions.
+- Result access and candidate enumeration must not invoke Providers/Tools, continue Agent execution, redeliver callbacks, or acquire ownership. Distinguish these operations from operations that initiate recovery.
+- Distinguish an unresolved result, absence, and inability to read. Do not translate Persistence failures or result-materialization failures into no execution, in progress, or successful completion without a result.
+- Read basic state and committed results from persisted records. Do not require the graph/Procs needed for continuation merely to access results. Preserve existing codec/schema compatibility requirements.
 
-### 範囲の制限
+### Scope limitations
 
-候補の発見は、Applicationのリクエストとの自動一意対応やsubmissionのexactly-onceを保証しない。
-複数候補がある場合、時刻が最新という理由だけで対象と断定せず、Applicationが保持する相関情報と照合する。
-Application固有のrequest ID・outbox・dedupはApplication責務であり、参照要件だけを理由に汎用idempotency基盤を追加しない。
+Candidate discovery does not guarantee automatic unique correspondence to an Application request or exactly-once submission.
+When multiple candidates exist, do not select one merely because it has the latest timestamp; Application must match its own correlation information.
+Application-specific request IDs, outboxes, and deduplication remain Application responsibilities. Do not add generic idempotency infrastructure solely to meet result-access requirements.
 
-既存のretention/delete契約を維持する。削除済み結果の復元、無期限保存、新しい履歴管理サービスは要求しない。
-一覧の範囲・順序・ページング等は既存API/SPIを確認して最小限の公開経路に対応付ける。
-既存APIで満たせない箇所のみ追加し、内部repositoryをそのまま公開契約として露出させない。
+Preserve existing retention/deletion contracts. Restoring deleted results, indefinite retention, and a new history-management service are not required.
+Inspect existing API/SPI behavior and map list scope, ordering, pagination, and similar concerns to the smallest necessary public path.
+Add only capabilities that existing APIs cannot provide; do not expose internal repositories directly as the public contract.
 
-## 2. RC-02 — 不存在・競合・保存成否不明の区別
+## 2. RC-02: Distinguishing absence, conflicts, and unknown persistence outcomes
 
-### 共通判断規則
+### Shared decision rules
 
-| 観測 | 許可する判断・動作 |
+| Observation | Permitted decision or action |
 |---|---|
-| 正常な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・入力との整合を検証する。競合を単純な成功とみなさない |
+| A successful authoritative read confirms that the reserved ID is absent | Check the parent's latest state, reservation, and cancellation conditions, then attempt admission with the same reserved ID |
+| The exact ID is confirmed nonterminal | Follow the existing Recovery contract for the same execution |
+| The exact ID is confirmed terminal | Use the persisted outcome; do not create a replacement execution |
+| Read timeout / I/O failure / record decode failure | Preserve state and follow existing error/retry contracts; do not treat the failure as absence |
+| Commit outcome is unknown, for example after a lost write acknowledgement | Retain the same operation identity and reserved ID for readback; do not create another ID or assignment before confirmation |
+| A definite revision/admission conflict | Reread the latest authoritative facts and validate consistency with the reservation, owner, and input; do not treat the conflict as success by itself |
 
-readbackが利用する整合性は、admission/CASを保護する既存Persistence契約を満たすこと。
-cache/indexの不一致や読み取り障害を新規admissionの根拠にしない。
-不存在確認とadmissionの間の競合は既存のatomic admission/CASで防ぐ。
-外部semantic workはadmissionの成功が確定した後にのみ開始する。
+Readback consistency must satisfy the existing Persistence contract that protects admission/CAS.
+Cache/index discrepancies and read failures must not justify new admission.
+Use existing atomic admission/CAS to prevent races between confirming absence and admission.
+Start external semantic work only after admission success is confirmed.
 
-適用対象: 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照合を維持する。
+Scope: Source Handoff transfer, Target admission/stabilization, parent child reservation/outcome,
+and Team admission/enqueue/finalize/assignment/worker outcome/terminal state.
+Team-owned enqueue/finalize retain the existing policy of fact reconciliation using a stable tool_invocation_id.
 
-成否不明を解決できない間は、確定していないローカル推測で次のsemantic処理へ進まない。
-無期限に同期待機せず、既存のPersistence error/retry経路へ制御を返す。
-Applicationにストレージ上の事実を創作させるmanual resolutionは追加しない。
-既存Agent/Persistenceの成否不明処理を再利用し、coordination専用の第二transaction engineを作らない。
+While an unknown outcome remains unresolved, do not advance to the next semantic operation based on unconfirmed local assumptions.
+Return control through existing Persistence error/retry paths instead of waiting synchronously without a bound.
+Do not add manual resolution that requires Application to invent storage facts.
+Reuse existing Agent/Persistence handling of unknown outcomes; do not create a second transaction engine dedicated to coordination.
 
-## 3. RC-03 — 復旧時wiringの最低互換性
+## 3. RC-03: Minimum wiring compatibility for recovery
 
-### 照合対象
+### Required checks
 
-| 対象 | 継続前に必要な照合 |
+| Subject | Checks required before continuation |
 |---|---|
-| 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との一致 |
+| Agent/Team definition | Compare the persisted definition id/version with the current definition; require equality unless an existing explicit compatibility/migration contract permits otherwise |
+| Orchestrator child | Match the persisted slot, the definition resolved from static subagent registration, reserved agent_id/execution_id, and owner |
+| Handoff | Match the original main anchor, persisted active/Target IDs, required graph connections, and the same Persistence instance/domain |
+| Team worker/coordinator | Match Team lineage, the persisted worker slot and definition, reserved Agent/execution IDs, and the persisted assignment |
 
-必要な登録やTargetがない、定義が不一致、Persistence境界が異なる場合は、semantic workを開始せずfail closedとする。
-エラーから対象identityと不足・不整合の種類が分かるようにする。既存のconfiguration/rehydration error契約を使う。
-結果の読み取りだけに不要な実行wiringを要求しない（RC-01）。
+If a required registration or Target is missing, a definition is incompatible, or the Persistence boundary differs, fail closed without starting semantic work.
+Use existing configuration/rehydration error contracts and make the affected identity and type of missing/inconsistent information clear from the error.
+Do not require execution wiring unnecessary for read-only result access (RC-01).
 
-### 確定済みfactの優先
+### Committed facts take precedence
 
-- 確定済みHandoffContextを現在のHandoffPolicyで再投影しない。
-- 確定済みchild input/configを現在のデフォルトで置き換えない。
-- 確定済みassignmentを現在のschedulerで選び直さない。
-- 確定済みchild/worker/final aggregate outcomeを再計算しない。
-- 未確定のscheduler/aggregateは既存V2のreplay-safe契約に従って再実行できる。保存済み入力に対する意味の互換性をApplicationが保つ。
+- Do not reproject committed HandoffContext using the current HandoffPolicy.
+- Do not replace committed child input/config with current defaults.
+- Do not reselect committed assignments using the current scheduler.
+- Do not recompute committed child/worker/final aggregate outcomes.
+- Uncommitted scheduler/aggregate computations may rerun under the existing V2 replay-safe contract. Application must preserve semantic compatibility with the persisted inputs.
 
-Phronomyが検査できるのは宣言されたidentity/versionと構造であり、Rubyコードの意味の同一性ではない。
-同じversionのまま非互換な実装に変更しないことはApplication責務。
-versionを上げるだけで旧実行の復旧が自動的に可能になるわけではなく、対応する定義または既存の明示的移行契約が必要。
-Proc/Classの永続化、ソースハッシュ、policy descriptor、global generic class registryは追加しない。
+Phronomy can check declared identity/version and structure, not semantic equivalence of Ruby code.
+Application is responsible for not introducing incompatible implementations under an unchanged version.
+Increasing a version alone does not automatically enable recovery of old executions; the corresponding definition or an existing explicit migration contract is required.
+Do not add Proc/Class persistence, source hashes, policy descriptors, or a global generic class registry.
 
-## 4. RC-04 — 待機終了とsemantic cancellation
+## 4. RC-04: Ending observation and semantic cancellation
 
-### 操作の区別
+### Distinguish operations
 
-| 操作・状態 | 契約 |
+| Operation or state | Contract |
 |---|---|
-| 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経路を維持する |
+| Application stops waiting, a connection is lost, or observation times out | This alone is not semantic cancellation of the durable execution |
+| Runtime shutdown / process loss | This alone does not establish semantic cancellation; preserve execution and recoverability under existing shutdown/draining contracts |
+| Explicit semantic cancellation request | Map it to the target owner/run and reserved executions under the existing Agent cancellation contract |
+| Waiting for recovery resolution / approval | Preserve existing V2 rehydration paths; do not convert waiting into failure or automatic cancellation |
 
-既存Taskの明示cancelなど、もともとsemantic cancellationを要求するAPIはその契約を維持する。
-単なる観測終了と同じ操作として扱わない。具体的な公開API対応はbaseline確認時に記載する。
+APIs that already request semantic cancellation, such as explicit cancellation of an existing Task, retain that contract.
+Do not treat them as equivalent to merely ending observation. Record concrete public API mappings when inspecting the baseline.
 
-### 子実行への適用
+### Applying cancellation to child executions
 
-| 子の状態 | 親runへのsemantic cancellationが受理された場合 |
+| Child state | Behavior after semantic cancellation of the parent run is accepted |
 |---|---|
-| 予約済み・未開始 | 現在の親runに属する新規dispatchを止める。予約情報を失わず、キャンセルのために子を起動しない |
-| 実行中・admission競合中 | exact reserved IDの状態を確認し、既存Agent cancellationを適用する。単にローカルTaskを破棄して処理済みとみなさない |
-| terminal | durable outcomeを維持する。過去の成功・失敗をキャンセル済みに書き換えたり補償再実行したりしない |
+| Reserved, not started | Stop new dispatch owned by the current parent run; retain reservation information and do not start a child just to cancel it |
+| Running, or racing with admission | Check the exact reserved ID's state and apply existing Agent cancellation; discarding a local Task alone does not complete cancellation handling |
+| Terminal | Preserve the durable outcome; do not rewrite historical success/failure as cancellation or rerun it for compensation |
 
-親cancelと子admissionの競合は、最新の親run状態・既存admission契約で処理する。
-既にadmitされた子は実行中の規則で照合し、別IDの子を作らない。
-親terminalizationと子settlementの順序は既存Agentのcancel/terminal barrier契約へ対応付ける。
-未完了の子がある場合、そのexact IDと必要なcancel/reconciliation状態を失ってはならない。
-restart後にも既存の復旧経路から対象を発見できることを必須とし、未対応の子を忘れたまま親の全処理完了を主張しない。
-新規の公開terminal statusや別のcancel schedulerを本追補だけで追加しない。
+Handle races between parent cancellation and child admission using the latest parent-run state and existing admission contracts.
+Reconcile an already admitted child under the running-child rules; do not create a child with a different ID.
+Map the ordering of parent terminalization and child settlement to existing Agent cancellation/terminal-barrier contracts.
+If a child is incomplete, retain its exact ID and required cancellation/reconciliation state.
+Require rediscovery through existing recovery paths after restart; do not claim that all parent work is complete while forgetting an unhandled child.
+Do not add a new public terminal status or a separate cancellation scheduler solely for this addendum.
 
-キャンセルの範囲は当該親runが所有する子に限定し、共有Agentの別実行・後続Team runへ波及させない。
-HandoffのSourceはtransfer commit後にhanded_offであり、後からSourceをcancelしてtransferを取り消したことにしない。
-現在のHandoff turnに対する明示cancelは、保存済みrouting/予約から該当Target実行へ対応付ける。
-観測終了・cancelを理由にactive responsibilityを元のmain Agentへ戻さない。
+Limit cancellation to children owned by the affected parent run; it must not affect other executions of a shared Agent or later Team runs.
+A Handoff Source is handed_off after transfer commits. Cancelling Source later must not be treated as reversing the transfer.
+Map explicit cancellation of the current Handoff turn to the relevant Target execution using persisted routing/reservations.
+Do not return active responsibility to the original main Agent because observation ends or cancellation occurs.
 
-外部Provider/Toolのcancelは副作用の取り消しを保証しない。成否不明は既存Agent Recovery契約で解決する。
-既存機構で上記の順序・再発見を満たせず第二実行エンジン等が必要なら、Stop Conditionとして報告する。
+Cancellation of external Providers/Tools does not guarantee reversal of side effects. Resolve uncertain outcomes through the existing Agent Recovery contract.
+If existing mechanisms cannot satisfy the required ordering and rediscovery without a second execution engine or similar addition, report a Stop Condition.
 
-## 5. RC-05 — durability保証の統一表現
+## 5. RC-05: Consistent durability guarantee wording
 
-> 確定済みのdurable outcomeは再利用する。未完了の実行は同じsemantic identityで復旧する。
-> 外部Provider/Tool処理の成否不明は既存Agent Recovery契約に従って解決する。
+> Reuse committed durable outcomes. Recover incomplete executions with the same semantic identity.
+> Resolve uncertain outcomes of external Provider/Tool operations under the existing Agent Recovery contract.
 
-「開始していないと確認できた場合だけ開始」はframework-owned execution admissionの判断を指す。
-外部システムへのリクエストが一度も届いていないことや、外部副作用のexactly-onceを意味しない。
-未完了実行を同じIDで復旧することも、内部の全Provider/Tool呼び出しの無条件再送を意味しない。
-callback喪失、ローカルTask喪失、観測timeoutをsemantic work再実行の理由にしない。
+Starting only when execution is confirmed not to have started refers to framework-owned execution admission.
+It does not mean that no request ever reached an external system, nor does it guarantee exactly-once external side effects.
+Recovering an incomplete execution with the same ID also does not mean unconditionally resending every internal Provider/Tool call.
+Loss of a callback or local Task, or an observation timeout, must not justify rerunning semantic work.
 
-## 6. 検証条件・対応付け
+## 6. Validation conditions and implementation mapping
 
-以下は必要な振る舞いの検証条件であり、新しいspecファイルの本数指定ではない。
-既存specが契約を検証している場合はその根拠を記録し、不足ケースのみ追加する。
+The following are behavioral validation conditions, not a required count of new spec files.
+Where existing specs verify a contract, record that evidence and add only missing cases.
 
-| ID | 検証シナリオ | 必須結果 |
+| ID | Validation scenario | Required outcome |
 |---|---|---|
-| 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)を参照する。
-本追補の責務境界と必須契約は変更しない。
+| RC-01-A | Process loss after terminal commit and before callback | Read the same result by exact ID without rerunning semantic work or callbacks |
+| RC-01-B | Caller is lost before the admission acknowledgement; execution later becomes terminal | Discover candidates from owner identity; do not arbitrarily choose one when multiple candidates exist |
+| RC-01-C | Access results without a graph/listener, or inject result read/decode failure | Require no unnecessary wiring; do not disguise an access failure as success or absence |
+| RC-02-A | Lose the acknowledgement immediately after each successful semantic commit | Adopt the existing fact through readback; create neither another ID nor duplicate assignments |
+| RC-02-B | Independently inject read failure, authoritative absence, and CAS conflict | Keep the states distinct; execute only after admission success is confirmed |
+| RC-02-C | Readback also fails after an unknown outcome | Preserve state and return control; do not wait synchronously without a bound or create a new execution |
+| RC-03-A | Remove subagent registration, mismatch definition version, or omit Target | Fail closed before continuation; do not substitute another definition or Target |
+| RC-03-B | Recover with compatible current wiring | Do not recompute committed Context/input/assignment/outcome |
+| RC-04-A | End waiting, shut down Runtime, or lose the process | Do not establish implicit semantic cancellation |
+| RC-04-B | Parent cancellation with an unstarted/active/terminal child | Follow state-specific rules and preserve exact IDs and committed outcomes |
+| RC-04-C | Race parent cancellation against child admission/terminal state | Do not lose the child; remain consistent with existing cancellation/terminal barriers |
+| RC-04-D | Lose the process at each commit boundary after a cancellation request | Rediscover and reconcile incomplete children of the same run through recovery paths |
+| RC-04-E | End observation or explicitly cancel after Handoff transfer | Do not roll responsibility back to Source; apply cancellation only to the relevant Target execution |
+| RC-05-A | Independently inject an uncertain external Tool effect and a lost callback | Use existing Recovery for the former and committed-result access for the latter; never rerun blindly |
+
+When integrating with the baseline, record the public API/SPI, implementation locations, and existing/additional specs for each RC ID in a mapping table.
+In particular, do not mark result-discovery APIs, compatible-version handling, or cancellation/terminal barriers complete using unverified method names.
+Successful focused, backend, fault, and full-suite runs require actual measurement on the target checkout.
+They have not been run at the time of this document revision.
+
+## 7. Responsibilities that remain out of scope
+
+Callback outbox/ACK, a terminal-delivery index, synthetic executions for standalone fan-out,
+Proc/Class serialization, a global generic registry, distributed transactions across independent Persistence instances,
+and a second execution engine dedicated to Team remain out of scope.
+Public result access does not replace Application notification delivery or deduplication of external effects.
+
+## 8. Implementation mapping
+
+See [IMPLEMENTATION_REPORT.md](IMPLEMENTATION_REPORT.md) for the implementation, public API/SPI, and validation scope as of 2026-09-07.
+The responsibility boundaries and required contracts in this addendum remain unchanged.