phronomy 0.23.0 → 0.24.1

data/docs/decisions/030-agent-handoff-domain-and-durable-responsibility.md

@@ -0,0 +1,235 @@
+# ADR-030: Agent Handoff Domain and Durable Responsibility
+
+## Status
+
+Accepted. V2 revision 2, 2026-09-06.
+
+User approval covers the V2 boundary and the five recovery-contract clarifications.
+Acceptance is design authority; it is not a claim of repository integration or test success.
+
+## Date
+
+2026-09-06
+
+## Partially supersedes
+
+`016-semantic-multi-agent-handoff` for:
+
+- namespace/domain placement of Handoff;
+- Runtime-local-only active responsibility;
+- allowance for independent Source/Target Persistence domains in the durable
+  Handoff path; and
+- the public Handoff Runner namespace.
+
+ADR-016 remains the historical rationale and remains authoritative for the
+Source-to-Target semantic transfer model, HandoffPolicy category semantics,
+Context dependency grouping, immutable transferred Context, Target ContextPolicy
+ownership, and provenance rules except where this ADR explicitly changes them.
+
+## Context
+
+ADR-016 intentionally made active Handoff responsibility Runtime-local. Process
+reset therefore restarted responsibility at the main Agent.
+
+That behavior is insufficient for a framework-owned Handoff abstraction once the
+Source execution has durably committed `:handed_off`: process loss must not force
+Source semantic work to run again merely to rediscover the Target.
+
+This is a framework semantic-routing concern, not an Application callback concern.
+ADR-029 therefore does not make Handoff durability depend on restart-spanning
+notification delivery.
+
+## Decision
+
+### 1. Handoff moves to the Agent domain
+
+Public types move as a clean break:
+
+```text
+Phronomy::MultiAgent::Handoff
+  -> Phronomy::Agent::Handoff
+
+Phronomy::MultiAgent::HandoffPolicy
+  -> Phronomy::Agent::HandoffPolicy
+
+Phronomy::MultiAgent::Runner
+  -> Phronomy::Agent::HandoffRunner
+```
+
+Handoff-specific private types move under the Agent Handoff implementation
+boundary.
+
+No compatibility alias is required by this ADR.
+
+### 2. `main_agent.agent_id` is the durable routing anchor
+
+No generic coordination/thread/session identity is introduced.
+
+```text
+main_agent.agent_id
+  = durable Handoff routing anchor
+```
+
+One durable HandoffState is keyed by that identity.
+
+### 3. Persistence adds `handoff_states`
+
+The durable state contains semantic routing facts only:
+
+```text
+main_agent_id
+handoff_revision
+active_agent_id
+active_handoff_context_ref
+phase
+pending_source_execution_id
+pending_target_execution_id
+created_at
+updated_at
+metadata
+```
+
+It never stores Agent instances, Agent classes, Procs, HandoffPolicy objects,
+Tasks, FSMSessions or EventLoop routing state.
+
+### 4. One durable Handoff graph uses one Persistence domain
+
+The main/source/target Agents and HandoffState must use the same
+`Phronomy::Persistence` transaction domain.
+
+A graph requiring a distributed transaction across independent Persistence
+domains is rejected before semantic work.
+
+### 5. Source terminalization and responsibility transfer are one semantic transaction
+
+When a Source chooses a valid Handoff, Phronomy:
+
+1. resolves the current finalized Source Manifest;
+2. applies HandoffPolicy projection;
+3. materializes immutable HandoffContext;
+4. reserves the exact Target `execution_id`;
+5. commits Source `:handed_off` and HandoffState transfer atomically.
+
+The transaction records at least:
+
+```text
+Source AgentExecution -> :handed_off
+Source AgentRoot terminal/idle revision
+Source Journal audit facts
+HandoffContext content reference
+HandoffState.active_agent_id -> Target
+HandoffState.active_handoff_context_ref -> transferred Context
+HandoffState.phase -> target_pending
+HandoffState.pending_source_execution_id -> Source execution_id
+HandoffState.pending_target_execution_id -> reserved Target execution_id
+```
+
+There is no terminal callback-delivery descriptor in this transaction.
+
+### 6. Target execution identity is reserved before Target semantic work
+
+Recovery uses the exact reserved Target `execution_id`:
+
+```text
+authoritatively absent after a successful read
+  -> establish that exact reserved execution only after admission is confirmed
+
+nonterminal
+  -> recover that exact execution
+
+terminal
+  -> consume its durable outcome; never create a replacement execution
+```
+
+The execution ID is semantic Agent identity, not Runtime FSMSession identity.
+
+### 7. Active responsibility survives later turns and process loss
+
+When a Handoff turn ends normally at Target B, `active_agent_id` remains B.
+
+The next HandoffRunner turn starts at B.
+
+After process reset, compatible HandoffRunner wiring loads the same HandoffState
+and again starts/resumes from B rather than reverting to the original main Agent.
+
+### 8. Multi-hop updates the same HandoffState
+
+A -> B -> C updates the original main-Agent-anchored HandoffState.
+
+No nested generic coordination IDs are created.
+
+### 9. Runtime graph/Policy wiring is Application code
+
+HandoffRunner requires the current Application-supplied Handoff graph and Policies
+to reconstruct Runtime behavior.
+
+Those Ruby objects are never persisted.
+
+If required wiring is absent or incompatible, recovery fails closed instead of:
+
+- reverting to main Agent;
+- inventing a graph;
+- blindly replaying Source work.
+
+### 10. HandoffContext is durably materializable but not adopted automatically
+
+The canonical immutable HandoffContext value is stored in ContentStore and
+referenced by HandoffState/execution metadata.
+
+Transferred material remains request-scoped Target Context unless Target
+execution creates its own canonical Journal/Knowledge facts.
+
+### 11. Local Application events are Runtime-only
+
+A Source may emit a same-process `:handoff` event.
+
+That event is not durable routing authority and is not redelivered after restart.
+
+Handoff coordination correctness depends only on durable semantic routing facts.
+
+### 12. Recovery evidence, compatibility and cancellation
+
+Apply [RC-01 through RC-05](../design/durable-semantic-coordination/RECOVERY_CONTRACT_CLARIFICATIONS.md).
+Read failures/unknown commit outcomes must not be treated as Target absence.
+Readback reconciles the same reserved execution and transfer facts; admission
+races use existing atomic admission/CAS, never a replacement Target ID.
+
+Before continuation, check main/active/Target identities, current required graph
+connections, declared definition compatibility and the same Persistence instance.
+Absent an existing explicit migration/compatibility contract, definition id/version
+must match. Current wiring never reprojects committed HandoffContext. Proc/code
+hashing and automatic semantic code-compatibility detection are not introduced.
+
+Result reads follow the specified run's recorded Target, not an unrelated later
+turn's latest active result. Continuation wiring is not required merely to read
+stored status/canonical results.
+
+After transfer commit the Source remains handed_off. Observation loss or cancel
+must not roll active responsibility back to main. An explicit cancellation of the
+current turn is routed to that turn's exact reserved Target under existing Agent
+cancellation rules; it does not cancel unrelated/later executions. Preserve the
+facts needed to reconcile cancellation/admission races and process loss.
+
+## Required invariants
+
+1. Handoff is an Agent-domain capability.
+2. `main_agent.agent_id` is the durable routing anchor.
+3. Active responsibility survives process loss.
+4. Source `:handed_off` and durable responsibility transfer cannot diverge.
+5. Target semantic work never starts without a recoverable reserved execution ID.
+6. A committed Source Handoff is never blindly replayed.
+7. Recovery reconstructs fresh Runtime objects.
+8. Graph/Policy Ruby objects are supplied by Application code, not persisted.
+9. All durable graph participants share one Persistence domain.
+10. Application callback delivery is not part of Handoff durability.
+
+## Non-goals
+
+This ADR does not:
+
+- make arbitrary external effects exactly once;
+- provide restart-spanning local Handoff callback delivery;
+- add distributed transactions across Persistence domains;
+- add generic coordination/session/thread identity;
+- persist HandoffPolicy/Application code;
+- merge Source and Target Agent state.

data/docs/decisions/031-durable-multi-agent-coordination.md

@@ -0,0 +1,301 @@
+# ADR-031: Durable Multi-Agent Semantic Coordination
+
+## Status
+
+Accepted. V2 revision 2, 2026-09-06.
+
+User approval covers the V2 boundary and the five recovery-contract clarifications.
+Acceptance is design authority; it is not a claim of repository integration or test success.
+
+## Date
+
+2026-09-06
+
+## Context
+
+Phronomy exposes:
+
+- `MultiAgent::Orchestrator < Agent::Base`, with child Agents/Tools and fan-out
+  helpers; and
+- `MultiAgent::TeamCoordinator`, with coordinator-generated tasks and a worker pool.
+
+Individual AgentExecutions are durable, but process-local coordination state is
+not. Losing child identities, task assignments or confirmed worker outcomes can
+cause Phronomy to repeat semantic work it owns.
+
+The previous proposal also attempted to make standalone fan-out convenience APIs,
+arbitrary Team aggregation callbacks and terminal Application callbacks durable.
+Responsibility review found those parts too broad.
+
+This ADR therefore defines durability at the **framework-owned semantic
+coordination boundary**, not at every callback/convenience API boundary.
+
+## Decision
+
+### 1. MultiAgent durability means semantic progress recovery
+
+For a durable MultiAgent operation:
+
+```text
+process/runtime loss
+  -> reconstruct from durable coordination facts
+  -> reuse confirmed child/worker outcomes
+  -> recover exact unfinished executions
+  -> admit absent reserved executions only after authoritative read/admission
+  -> resolve unknown external effects through existing Agent Recovery
+```
+
+FSMSession, Task, callback and Runtime queues remain disposable.
+
+### 2. Orchestrator durability is rooted in an existing Orchestrator AgentExecution
+
+`MultiAgent::Orchestrator < Agent::Base` already has canonical Agent identity.
+
+When child coordination occurs **inside an existing Orchestrator AgentExecution**,
+that AgentExecution references an immutable coordination snapshot containing, as
+needed:
+
+```text
+coordination kind / phase
+child slot
+child Agent definition identity/version
+reserved child agent_id
+reserved child execution_id
+restart-required input/config refs
+child semantic state
+result_ref / error_ref
+on_error / max_concurrency semantic options
+```
+
+No separate Orchestrator repository or generic multi-agent execution ID is added.
+
+### 3. Existing fan-out Runtime FSM remains reconstructable machinery
+
+`FanOutInvocation` / `FSMSession` remain Runtime projections.
+
+Recovery builds a fresh runtime invocation/session from the durable coordination
+snapshot and fresh Runtime identities.
+
+### 4. Framework-owned child identities are reserved before semantic work
+
+Before a durable Orchestrator child begins:
+
+```text
+reserve child agent_id
+reserve child execution_id
+persist parent child slot + restart-required refs
+then create/load child and start exact reserved execution
+```
+
+Recovery distinguishes absent/nonterminal/terminal exact child state and never
+creates a replacement simply because Runtime callbacks were lost.
+
+### 5. Durable child definitions must be reconstructable from stable wiring
+
+For the durable path, a child Agent class must be resolvable from stable current
+Orchestrator/Application wiring, initially the concrete Orchestrator class's
+registered subagents.
+
+Invocation-only anonymous/arbitrary class handles are not persisted.
+
+This restriction applies only to APIs/paths that claim restart durability.
+
+### 6. Standalone `dispatch_parallel*` / `fan_out*` remain Runtime-only convenience APIs
+
+A direct Application call to:
+
+```ruby
+orchestrator.dispatch_parallel(...)
+orchestrator.fan_out(...)
+```
+
+outside a live parent Orchestrator AgentExecution does **not** create a synthetic
+AgentExecution solely for durability.
+
+It keeps current-process semantics and may continue accepting Runtime-only Agent
+class wiring.
+
+If durable fan-out is required, the Application must place the work under:
+
+- an Orchestrator AgentExecution with stable child wiring; or
+- an Application Workflow when the operation is application-process
+  orchestration.
+
+This avoids inventing durable parent identity for a convenience call.
+
+### 7. Durable framework-owned Orchestrator children share the parent Persistence domain
+
+A durable parent/child coordination path uses the same Persistence domain.
+
+External remote effects reached through Tools/Application integration remain X0
+external effects.
+
+### 8. TeamCoordinator is a purpose-specific durable semantic entity
+
+TeamCoordinator remains under `MultiAgent`, not `Agent::Base`.
+
+It gains:
+
+```text
+team_id
+team_execution_id
+team_definition id/version
+TeamRoot
+TeamExecution
+```
+
+This is retained because Phronomy itself owns the Team queue/assignment/worker
+abstraction.
+
+### 9. Team task queue and worker assignment are durable facts
+
+TeamExecution durably records:
+
+```text
+canonical tasks
+task-generation finalized state
+worker slots / stable worker agent_id
+task -> worker assignment
+reserved worker execution_id
+worker terminal result/error
+final Team result/error
+```
+
+Before worker semantic execution starts, its assignment and reserved exact
+execution identity are committed.
+
+### 10. Worker identity is stable within one TeamExecution
+
+A worker slot reuses its logical Agent identity for that TeamExecution so worker
+context/transcript semantics remain coherent across assigned tasks.
+
+This ADR does not require worker identity/history to survive into another
+TeamExecution.
+
+### 11. Team scheduler is a replay-safe decision function
+
+Application `schedule` may run again while no assignment has been durably
+committed.
+
+Contract:
+
+- it must not perform externally observable one-shot effects;
+- it selects from the supplied available worker projection;
+- repeated execution before assignment commit is allowed;
+- after assignment commit, recovery uses the durable assignment and does not
+  rerun scheduling for that task.
+
+No scheduler result needs a separate unknown-outcome protocol.
+
+### 12. Team aggregation is pure/replay-safe result computation
+
+Application `aggregate` receives canonical durable assignment results.
+
+Contract:
+
+- no externally observable one-shot side effects;
+- repeated invocation with the same canonical assignments must be semantically
+  equivalent;
+- if process loss occurs before aggregate result/error is durably committed,
+  Phronomy may invoke `aggregate` again;
+- on normal return/raise, Phronomy durably records the final result/error before
+  Team terminalization.
+
+There is no `aggregation=started -> outcome unknown -> manual resolve` protocol.
+
+Applications perform external post-Team effects after obtaining/reconciling the
+Team result.
+
+### 13. Team progress and terminal callbacks are Runtime-only
+
+Streaming task-completion callbacks and final Application notifications are
+current-process observations.
+
+Canonical task/worker/Team semantic outcomes are durable; callback delivery is
+not.
+
+No Team delivery-pending index or restart redelivery obligation is introduced.
+
+### 14. Workflow remains the Application process-orchestration domain
+
+Public domain ownership remains:
+
+```text
+Agent
+  Agent semantic execution + Agent Handoff
+
+MultiAgent
+  durable framework-owned Orchestrator child coordination
+  durable Team queue/assignment/worker coordination
+  Runtime-only convenience fan-out outside a durable parent
+
+Workflow
+  explicit Application-defined durable process/state-machine orchestration
+  durable ordering of Application-owned steps/effects when modeled by the app
+```
+
+### 15. Recovery contract clarifications
+
+The normative [RC-01 through RC-05 contracts](../design/durable-semantic-coordination/RECOVERY_CONTRACT_CLARIFICATIONS.md)
+apply to existing Orchestrator executions and Team executions:
+
+- expose read-only status/result access and retained execution discovery;
+- distinguish authoritative absence from read failure/unknown commit outcome;
+- reconcile writes with the same reserved identities using existing Persistence
+  protocols, including Team-owned operation facts;
+- verify declared definition id/version, registered slot wiring and reserved
+  owner/Agent/execution identities before continuation;
+- preserve committed inputs/config, assignments and outcomes instead of
+  recalculating them with changed current code;
+- distinguish observation loss/shutdown from semantic cancellation;
+- stop new dispatch on accepted parent-run cancellation, reconcile already
+  admitted children using existing Agent cancellation and terminal barriers,
+  retain terminal outcomes and exact identities needed after restart;
+- restrict cancellation to the current run's owned children, never unrelated
+  executions or later runs.
+
+Stable version declarations do not prove Ruby code equivalence. Application code
+must maintain declared compatibility; no Proc hash or generic registry is added.
+Uncommitted replay-safe schedule/aggregate computation remains replayable.
+No dedicated cancellation execution engine or callback recovery service is added.
+
+## Persistence changes
+
+The durable root surface expands to include:
+
+```text
+handoff_states
+teams
+team_executions
+```
+
+Orchestrator continues to use Agent repositories.
+
+No execution/team terminal-delivery pending index is added.
+
+## Required invariants
+
+1. Durable coordination is claimed only where a durable semantic root exists.
+2. Confirmed child/worker terminal work is never blindly rerun.
+3. Child/worker semantic work begins only after exact recoverable identity is
+   durably known.
+4. Orchestrator durable child coordination uses its existing AgentExecution.
+5. Standalone convenience fan-out is explicitly Runtime-only.
+6. Team has stable identity/execution and durable tasks/assignments/worker results.
+7. Scheduler and aggregator are replay-safe Application functions, not arbitrary
+   side-effect transaction boundaries.
+8. Callback/Task/FSMSession/Proc objects are never persisted.
+9. Workflow remains the appropriate domain for Application-defined durable process
+   orchestration.
+
+## Non-goals
+
+This ADR does not:
+
+- make standalone convenience fan-out restart-durable;
+- make external Provider/Tool/Application effects exactly once;
+- persist scheduler/aggregator Procs or callbacks;
+- provide restart-spanning Team callback delivery;
+- require worker history across TeamExecutions;
+- add a generic global Agent class registry;
+- turn MultiAgent into a public Workflow alias.

data/docs/decisions/README.md

@@ -64,7 +64,7 @@ resolved explicitly.
 | [`013-journal-backed-knowledge-as-context-candidates`](013-journal-backed-knowledge-as-context-candidates.md) | Accepted | Yes | Current persistent Knowledge authority. |
 | [`014-unified-persistence-durable-state`](014-unified-persistence-durable-state.md) | Accepted | Yes | Durable-backend and live-owner/no-reload intent remains current; live Agent execution mutation is refined by ADR-024, same-process Agent identity/admission ownership by ADR-025, and same-process Workflow admission/terminal-barrier ordering by ADR-026. Workflow identity terminology is superseded by ADR-020, generic `InvocationContext` / Agent correlation semantics by ADR-021, and concrete FSMSession/Agent-Tool routing identity by ADR-023. |
 | [`015-tool-public-facade-and-rbs-boundary`](015-tool-public-facade-and-rbs-boundary.md) | Accepted | Yes | Current Tool façade / extension-SPI / RBS boundary. |
-| [`016-semantic-multi-agent-handoff`](016-semantic-multi-agent-handoff.md) | Accepted | Yes | Current semantic Handoff intent; runtime/context-transfer reconciliation is implemented and reflected in current architecture documentation. |
+| [`016-semantic-multi-agent-handoff`](016-semantic-multi-agent-handoff.md) | Superseded | No | Superseded by [ADR-030](030-agent-handoff-domain-and-durable-responsibility.md), including Agent-domain ownership and exact Target recovery. |
 | [`017-design-authority-and-adr-governance`](017-design-authority-and-adr-governance.md) | Accepted | Yes | Repository-wide architecture authority and ADR governance. |
 | [`018-durability-guarantees-and-failure-model`](018-durability-guarantees-and-failure-model.md) | Accepted | Yes | Repository-wide durability/concurrency/external-effect guarantee vocabulary and F0-F4/X0 failure model. |
 | [`019-filter-contract-and-security-boundaries`](019-filter-contract-and-security-boundaries.md) | Accepted | Yes | Current Filter transform/block and bounded PromptInjectionFilter/isolation boundaries; the follow-up review adds no fourth Context Filter call site and places semantic Context trust in Application ContextPolicy. |
@@ -76,6 +76,10 @@ resolved explicitly.
 | [`025-process-local-agent-ownership-and-runtime-admission`](025-process-local-agent-ownership-and-runtime-admission.md) | Accepted | Yes | One mutable live Agent owner per `agent_id` per Runtime; EventLoop is the primary same-process top-level admission authority while Persistence admission remains durable defense. |
 | [`026-workflow-runtime-admission-and-durable-terminal-barrier`](026-workflow-runtime-admission-and-durable-terminal-barrier.md) | Accepted | Yes | EventLoop-owned opaque Workflow admission owner, admission-before-hydration ordering, and FSMSession-integrated durable terminal save barrier with fail-closed uncertain outcomes. |
 | [`027-llm-adapter-provider-boundary`](027-llm-adapter-provider-boundary.md) | Accepted | Yes | Phronomy-owned Provider-call extension boundary; RubyLLM is the default adapter/integration while current input materialization remains RubyLLM-specific. |
+| [`028-preparing-recovery-replay-contract`](028-preparing-recovery-replay-contract.md) | Accepted | Yes | Adds replay-safe same-`execution_id` recovery for durably admitted Agent `:preparing` executions when replayability is durably established; unsupported Runtime-only dependencies fail closed. |
+| [`029-semantic-completion-and-application-effect-boundary`](029-semantic-completion-and-application-effect-boundary.md) | Accepted | Yes | V2 revision 2; framework semantic coordination and Application effect boundary. |
+| [`030-agent-handoff-domain-and-durable-responsibility`](030-agent-handoff-domain-and-durable-responsibility.md) | Accepted | Yes | V2 revision 2; framework semantic coordination and Application effect boundary. |
+| [`031-durable-multi-agent-coordination`](031-durable-multi-agent-coordination.md) | Accepted | Yes | V2 revision 2; framework semantic coordination and Application effect boundary. |
 
 ## Legacy duplicate `011`
 

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

@@ -0,0 +1,33 @@
+# V2 revision 2 — 改訂内容
+
+更新日: 2026-09-06 / 状態: Accepted
+
+## 合意反映
+
+| 項目 | 今回の修正 |
+|---|---|
+| RC-01 結果参照 | exact実行IDで状態・結果を読み取る契約と、ID受領前の停止に備えたownerからの候補発見を追加 |
+| RC-02 保存成否不明 | 正常な不存在、read障害、CAS競合、commit成否不明を区別。同じ予約済みidentityで照合 |
+| RC-03 wiring互換性 | 定義id/version・slot・graph・Persistence境界の最低照合と、確定済みfactの優先を明記 |
+| RC-04 cancellation | 観測終了/shutdownとsemantic cancelを区別。子の状態別処理、競合、restart後の再発見を明記 |
+| RC-05 保証表現 | 確定outcome再利用・同一identity復旧・外部成否不明は既存Recovery、に統一 |
+
+ADR-029/030/031、実装設計、責務境界レビュー、READMEへ対応する規範的記述を反映した。
+詳細契約と検証条件はRECOVERY_CONTRACT_CLARIFICATIONS.mdにまとめ、資料間で参照する。
+承認前のProposed表記をAcceptedへ更新した。新機能の再承認を要求しない。
+
+## 実装状態の訂正
+
+引き継ぎ文書の旧実装件数・静的検証成功は、前セッションの報告として残す。
+この分岐先で実装を再検証した事実にはしない。現在取得できたのは設計資料と引き継ぎ文書であり、
+旧overlay/apply.py/APPLY.sh/VERIFY.shは未取得。再開手順も実ファイルの回収から始める形に更新した。
+
+## 今回実施した確認
+
+- 対象資料の承認状態、baseline、相互参照の整合確認。
+- 旧い「未承認のため実装停止」表現と、外部効果のexactly-onceに読める保証表現の修正。
+- RC-01〜05のADR・実装設計・検証条件への対応確認。
+- ZIP構成、全文書のSHA256SUMS、ZIP/引き継ぎ文書の外部SHA256の検証。
+
+対象repositoryのコード変更・RSpec実行は行っていない。
+API名や例外名は未確認のものを作らず、baselineへの対応付けを実装前の必須作業とした。