phronomy 0.30.0 → 0.31.0

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.

data/docs/getting-started.md

@@ -137,6 +137,26 @@ mutable Agent/Execution/Journal state before every LLM or Tool step. A conflicti
 external durable write is surfaced as `Phronomy::Persistence::StateConflictError` rather than
 silently merged into the live instance.
 
+Read persisted conversation values without interpreting Journal storage:
+
+```ruby
+messages = agent.transcript_messages
+messages.each { |message| puts "#{message.role}: #{message.content}" }
+```
+
+`transcript_messages_async` returns a TaskResult with the same frozen array of
+`LLMAdapter::Message` values. For the same durable root, these match
+`result[:messages]`, including Tool calls, Tool results, non-text content and
+opaque metadata. The operation selects root/generation and Journal records in one
+transaction, then restores immutable content off EventLoop. It holds Agent
+ownership until physical completion, including after logical cancellation.
+The synchronous method refuses to wait on EventLoop. Content and integrity
+failures propagate; an unreadable transcript is not an empty conversation.
+
+`agent.transcript` remains a JournalRecord view. Knowledge is excluded from the
+conversation. The application still owns authorization, role filtering and
+presentation; reading invokes no LLM or Tool and changes no durable state.
+
 The active transcript and Knowledge views can be advanced independently without
 deleting the append-only canonical Journal:
 
@@ -379,6 +399,12 @@ Agent-backed Tools return control to EventLoop while the child lifecycle is
 waiting. They do not occupy an OffloadPool worker merely to wait for a child
 Agent result.
 
+Each call owns and releases its fresh child Agent after physical work finishes.
+Normal completion includes that release; a failed release preserves the result,
+original error and child in `Tools::Agent::CleanupError`. See
+[child lifetime and cleanup](architecture/agent-tool-child-lifetime.md) for
+cancellation, approval and release-only retry rules.
+
 ## Filters
 
 Filters can transform or reject values at Agent boundaries:

data/docs/migrations/0.31.md

@@ -0,0 +1,72 @@
+# Migrating to Phronomy 0.31
+
+Phronomy 0.31 adds explicit schema delivery and durable transcript reads, and
+fixes ownership and release of one-shot and Agent Tool children. Review these
+compatibility boundaries when upgrading from 0.30.1.
+
+## Stored executions
+
+New structured executions store output-contract version 2 with `schema_delivery`
+and use AgentExecution envelope 0.3. The schema remains saved and locally
+validated even with `schema_delivery: :none`; omitting native schema delivery is
+an explicit application choice, not an automatic fallback or output repair.
+
+Deploy compatible readers before writing these records. Older readers reject
+0.3, including completed executions; do not downgrade a store containing them.
+Version 0.31 still reads envelope 0.2 and existing version-1 native output
+contracts without rewriting them merely on read. Existing free-text records do
+not acquire a schema retroactively. See the
+[structured-output persistence contract](../architecture/structured-output-and-scope.md#failure-and-persistence).
+
+## One-shot Agent ownership
+
+`Agent.run_once` owns its fresh Agent and ephemeral Store through
+`Agent.open_scope` and releases the live Agent before returning. A reusable
+Agent must instead use `create`/`load` or an explicit ownership scope.
+
+When release succeeds, the original invocation value or exception is preserved.
+Unsafe or failed release raises `Agent::ScopeCleanupError`, retaining the result,
+primary error, failed owners and scope. Resolve the release condition before
+retrying `error.scope.release!`; this does not repeat model or Tool work.
+Approval waits, physical work, independent leases, retention and recovery still
+prevent unsafe release. No records are purged and no shared Store or Runtime is
+shut down. See [single-invocation ownership](../architecture/structured-output-and-scope.md#single-invocation-ownership).
+
+## Agent-backed Tools
+
+Both synchronous `execute` and asynchronous `call_async` now invoke the child
+through `invoke_async`. A subclass that overrides only `invoke` no longer
+changes the synchronous Tool path. Move the intended customization to the
+asynchronous entry point and preserve its TaskResult contract.
+
+Each call owns its fresh child and ephemeral Store until invocation and physical
+work have finished and safe release completes. Normal return includes release;
+successful output conversion remains unchanged. Waiting does not consume an
+OffloadPool worker solely to join the child.
+
+A release failure raises `Phronomy::Tools::Agent::CleanupError` with code
+`tool.agent_cleanup_failed`. It retains `child_agent`, `agent_id`, `result`,
+`primary_error` and `cleanup_error`; the cause is the primary failure when one
+exists, otherwise the release failure. Resolve the release condition, then retry
+`error.child_agent.unload_async` for release only. These live handles are
+process-local and are not reconstructed from saved error diagnostics.
+
+Cleanup failures are also diagnosed after observer cancellation and are not
+hidden by ordinary Tool error suppression. Completed runtime wiring no longer
+retains released children through generated callbacks, temporary tracker context
+or completed participation changes. Session ownership, commit/readback ordering,
+physical leases and recovery guards remain unchanged. See the
+[Agent Tool child lifetime contract](../architecture/agent-tool-child-lifetime.md).
+
+## Live-provider limits
+
+LM Studio/gpt-oss PEG output parsing remains unresolved. Known-error
+identification and one bounded retry do not establish the root cause or prevent
+recurrence. The existing evidence distinguishes a failed call stopped after two
+POSTs from a separate application invocation that succeeded on its first POST;
+it does not show recovery by retry within one call.
+
+The DX1/DX2 normal live path, streaming, Tool use and history restoration remain
+unverified in that environment. Source review, offline tests and CI support this
+release; they do not establish live LLM acceptance. See the
+[LM Studio policy and evidence limits](../architecture/lm-studio-output-failures.md).

data/lib/phronomy/agent/async_event_api.rb

@@ -12,12 +12,12 @@ module Phronomy
     # - approval notifications share the Agent listener as :approval_required;
     # - Recovery resolution uses resolve/resolve_async.
     module AsyncEventApi
-      def start_reserved_async(reservation:, input:, config: {}, output_schema: nil)
+      def start_reserved_async(reservation:, input:, config: {}, output_schema: nil, schema_delivery: nil)
         __with_operation(async: true) do
           unless reservation.is_a?(ReservedExecution) && reservation.agent_id == agent_id
             raise ArgumentError, "reservation must belong to this Agent"
           end
-          config = __invocation_config(_prepare_output_config(config, nil, output_schema))
+          config = __invocation_config(_prepare_output_config(config, nil, output_schema, schema_delivery))
           ExactExecution.start(agent: self, execution_id: reservation.execution_id, input: input,
             config: config.merge(phronomy_reservation: reservation.correlation))
         end
@@ -54,12 +54,13 @@ module Phronomy
         config: {},
         invocation_context: nil,
         output_schema: nil,
+        schema_delivery: nil,
         **removed_options,
         &removed_block
       )
         __with_operation do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
-          config = _prepare_output_config(config, invocation_context, output_schema)
+          config = _prepare_output_config(config, invocation_context, output_schema, schema_delivery)
           _check_event_loop_reentrancy(:invoke, :invoke_async)
           _start_agent_operation(
             input,
@@ -75,12 +76,13 @@ module Phronomy
         config: {},
         invocation_context: nil,
         output_schema: nil,
+        schema_delivery: nil,
         **removed_options,
         &removed_block
       )
         __with_operation(async: true) do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
-          config = _prepare_output_config(config, invocation_context, output_schema)
+          config = _prepare_output_config(config, invocation_context, output_schema, schema_delivery)
           _start_agent_operation(
             input,
             config: config,
@@ -95,13 +97,14 @@ module Phronomy
         config: {},
         invocation_context: nil,
         output_schema: nil,
+        schema_delivery: nil,
         **removed_options,
         &removed_block
       )
         __with_operation do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
           listener = _required_stream_listener!(:stream)
-          config = _prepare_output_config(config, invocation_context, output_schema)
+          config = _prepare_output_config(config, invocation_context, output_schema, schema_delivery)
           _check_event_loop_reentrancy(:stream, :stream_async)
           _start_agent_operation(
             input,
@@ -117,13 +120,14 @@ module Phronomy
         config: {},
         invocation_context: nil,
         output_schema: nil,
+        schema_delivery: nil,
         **removed_options,
         &removed_block
       )
         __with_operation(async: true) do
           _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
           listener = _required_stream_listener!(:stream_async)
-          config = _prepare_output_config(config, invocation_context, output_schema)
+          config = _prepare_output_config(config, invocation_context, output_schema, schema_delivery)
           _start_agent_operation(
             input,
             config: config,
@@ -206,9 +210,14 @@ module Phronomy
 
       private
 
-      def _prepare_output_config(config, invocation_context, schema)
+      def _prepare_output_config(config, invocation_context, schema, schema_delivery)
         config = _prepare_invocation_config(config, invocation_context)
-        schema.nil? ? config : config.merge(phronomy_output_contract: OutputContract.new(schema))
+        if schema.nil?
+          raise ArgumentError, "schema_delivery requires output_schema" unless schema_delivery.nil?
+          return config
+        end
+        contract = OutputContract.new(schema, schema_delivery: schema_delivery.nil? ? :native : schema_delivery)
+        config.merge(phronomy_output_contract: contract)
       end
 
       def _start_agent_operation(input, config:, mode:, listener:)

data/lib/phronomy/agent/base.rb

@@ -400,6 +400,31 @@ module Phronomy
         end
       end
 
+      # Materializes the current durable transcript as immutable Message values.
+      # Application authorization and presentation filtering remain caller-owned.
+      # @return [Array<LLMAdapter::Message>]
+      # @api public
+      def transcript_messages
+        _check_event_loop_reentrancy(:transcript_messages, :transcript_messages_async)
+        transcript_messages_async.wait_result
+      end
+
+      # Holds Agent ownership until the submitted read physically completes.
+      # @return [TaskResult<Array<LLMAdapter::Message>>]
+      # @api public
+      def transcript_messages_async
+        __with_operation(async: true, read_only: true) do
+          __execution_environment.submit(on_full: :raise) do
+            root, records = persistence.transaction do |tx|
+              current = tx.agents.load(agent_id)
+              [current, tx.journals.read(agent_id, limit: current.journal_position)]
+            end
+            RuntimeInput.new(agent: self, persistence: persistence)
+              .materialize_transcript(root: root, records: records)
+          end
+        end
+      end
+
       def clear_transcript!
         __with_operation do
           mutate_context!(:transcript_cleared) do |root|
@@ -730,8 +755,8 @@ module Phronomy
       def _prepare_invocation_config(config, invocation_context)
         __assert_live_agent!
         _reject_removed_generic_identity_keys!(config)
-        if config.keys.any? { |key| %w[output_schema response_schema phronomy_output_contract].include?(key.to_s) }
-          raise ArgumentError, "Use the output_schema keyword on a new Agent execution"
+        if config.keys.any? { |key| %w[output_schema schema_delivery response_schema phronomy_output_contract].include?(key.to_s) }
+          raise ArgumentError, "Use the output_schema and schema_delivery keywords on a new Agent execution"
         end
         invocation_context ?
           config.merge(invocation_context: invocation_context) : config

data/lib/phronomy/agent/composition/run_once.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# This convenience API composes a fresh ephemeral Persistence with an Agent.
+# This convenience API owns a fresh ephemeral Persistence and a scoped Agent.
 # The application entry loads the method definition; Agent execution does not
 # delegate to or require this higher-level composition implementation.
 module Phronomy
@@ -18,15 +18,16 @@ module Phronomy
         raise ArgumentError, "Provide either on_event: or a block, not both"
       end
 
-      persistence = Phronomy::PersistenceComposition.agent
-      agent = definition.create(
-        context: context,
-        knowledge: knowledge,
-        persistence: persistence,
-        on_event: on_event,
-        &event_block
-      )
-      agent.invoke(input, **invoke_options)
+      open_scope do |scope|
+        persistence = Phronomy::PersistenceComposition.agent
+        agent = scope.create(definition,
+          context: context,
+          knowledge: knowledge,
+          persistence: persistence,
+          on_event: on_event,
+          &event_block)
+        agent.invoke(input, **invoke_options)
+      end
     end
   end
 end