phronomy 0.26.0 → 0.28.0

data/docs/architecture/r8-unit1.md

@@ -0,0 +1,104 @@
+# r8第1適用版：Context／ToolとExecutionの共通基盤
+
+> Current boundary: r8 unit 6 supersedes the historical Chat/SDK ownership and
+> adapter extension SPI below. Agent uses LLMAdapter values; the backend owns SDK
+> construction/interception; Tool owns canonical schema validation. See
+> `docs/architecture/r8-unit6.md` and `docs/migrations/r8-unit6.md`.
+
+
+対象は2026-09-30に確認したmain `653e255a34fe4062d4beca47530e084fdd3a6ba9`。設計基準は同日更新のr8修正仕様・directory配置資料である。本変更はその第1適用単位であり、r8全体、S1全項目、S2/S3全受入条件の完了を意味しない。互換alias・転送だけの旧APIは残さない。
+
+## 実装した責務と操作
+
+| 所有者 | 共通基盤が実行すること | 利用側に残すこと |
+|---|---|---|
+| `Context::Assembly` | Policyを一度呼びPlanを検証する。内容を正規化し、最終予算を検査してManifestを保存する | Agentはsnapshotを取得し、保存直前のwatermark再確認とAgent実行記録更新を行う |
+| `Tool::DefinitionSet` | Tool定義の正規化、名前重複と保存済み定義の整合性を検証する | Agentは自身のTool alias・decorator・runtime実体を準備する |
+| `Tool::Authorization` | 不変の引数・認可contextでfacts→requirement→policy→decisionを評価する | Agentは対象実行の照合、承認状態、受付結果、supervisionを管理する |
+| `Tool::ToolExecutor` | cooperative/offloadedの実行規則と結果を扱う | Engineのpool選択はExecutionの機構接続へ委ねる |
+| `LLMAdapter::Base` / `RubyLLM` | 同期生成とchat構築・設定・message/tool-call構築。RubyLLM実装がSDK失敗を変換する | Agentは自身の保存データ・Tool定義を検証してadapterへ渡す |
+| `Execution` | submitの入口、fan-out/fan-in、結果合成、取消・期限・待機規則 | Engineはpool・timer・RuntimeとFSMの機構を実装する |
+| `Tracing::Observation` | 明示的な観測とPII秘匿。実際の返り値は変えない | Runnableはinvoke/stream/batchの実行契約を持つ |
+
+ContextとToolはAgentの薄い型定義の置場ではなく、実際の共通手順を所有する。ただし、Contextの現在の入力にはAgent由来の識別情報や由来情報が残る。完全に汎用の新domainモデルまで設計し直したものではない。ToolのDSL基底は引き続きRubyLLM::Toolを使用する。
+
+`Context::Assembly#prepare(input:, policy:, adapter_identity:)` は保存transaction外でPolicyを呼ぶ。`#store(prepared, contents:)` は呼出側が渡す同じtransactionのcontents repositoryだけを使い、自分では独立transactionを開始しない。初回とfollow-upのAgent commitは既存transaction内でManifestとAgentExecutionの参照を保存する。後続書込に失敗したときManifestもrollbackされ、Policyは再実行されない。live projectionをcommit後に適用する既存順序を維持する。これはP02のAgent／Context部分の検証であり、任意domainの外側transaction参加を完成させたものではない。
+
+Executionは`_ExecutionBackend`の操作に依存する。構成処理が遅延providerを設定し、Engineの`ExecutionBinding`がsubmit/afterを実装する。settled TaskResultの生成・map/flat_map/all_settled・待機制約の確認ではEngineを読み込まない。Runtime取得は実際のsubmit/タイマー登録時に行う。単なる名義移管に留めず、機構参照をここへ集約した。
+
+WorkflowのFINISHと終了値は`Workflow::Completion`が所有し、WorkflowRunnerがFSM側へ変換する。FSMSession専用のEvent／FSMProtocol／TerminalDecisionはEngineに置く。Agent・MultiAgentのFSM専用接続の全面分離は残っている。
+
+## 公開名・配置の変更
+
+| 旧配置・API | 新配置・API | 判断 |
+|---|---|---|
+| `agent/context_contract/` と `Agent::ContextPolicy` 等 | `context/`、`Context::ContextPolicy` 等 | Policy・Plan・Manifest・検証を共通操作と同じ所有者へ統合 |
+| `agent/context_policies/default.rb` | `context/default_policy.rb`、`Context::DefaultPolicy` | 具体Policyも同domainに配置 |
+| `Agent::Context::Instruction::PromptTemplate` | `Context::PromptTemplate` | Agent内の旧公開名を削除 |
+| `Agent::Selection::{Candidate,Constraint}` | `Context::{Candidate,Constraint}` | 薄いSelection下位区分を削除 |
+| `Agent::LLMInputPatch` / `LLMInputBuildContext` | `Context::LLMInputPatch` / `LLMInputBuildContext` | hook入力・返却値の所有を統一 |
+| `ContextBudgetExceededError` | `Context::BudgetExceededError` | LLMのprovider失敗ではなくContext予算失敗 |
+| `agent/context_assembly/` | `context/assembly.rb` とAgent直下の準備・状態・入力処理 | Context共通手順、Agent snapshot/state、LLM SDK処理を分離 |
+| `Agent::Context::Capability::Base` | 実装本体の `Tool::Base` | 旧名とaliasを削除 |
+| `agent/tool_execution/tool_definition_set.rb` | `tool/definition_set.rb` | 共通定義処理を移管。Agent固有生成はAgent内 |
+| `execution_contract/` と `execution_services/` | `execution/` と必要な `execution/concurrency/` | 操作・値・共通規則を統合。`execution_result`等の薄い別分割を追加しない |
+| `WorkerSubmission` | `Execution.submit` | 転送専用moduleを削除 |
+| `Runnable#trace` | `Tracing::Observation.trace` | 実行基盤から観測への依存を除去 |
+| `tool/contract`、`filter/contract`、`output_parser/contract`、`agent/lifecycle_contract` | 各所有domain配下の例外ファイル | 例外だけのdirectoryを削除。既存の意味を持つ例外定数名は実体として保持 |
+
+独自LLM adapterはcomplete/streamだけでなく、`build_chat`、`configure_chat`、`message`、`tool_call`を実装する。`identity`には基底の既定値、`input_budget`にはnilの既定値がある。正確なkeywordと返却契約は`sig/phronomy/llm_adapter/base.rbs`を参照する。SDK固有例外はadapter操作の境界でLLM失敗へ変換し、元のcauseを保持する。アプリ例外・取消は無関係なprovider失敗へ変換しない。
+
+既存設定APIの`tool_result_max_size`／loggerはアプリ構成から中立RuntimeSettingsへ供給する。Toolから構成factoryへの参照を除き、default・nil・scoped copyの意味を維持する。RBSは`sig/`と`sig/_private/`に置き、実装定数・宣言所有者に基づいて依存を解析する。
+
+## r8項目別の到達点
+
+| 項目 | この適用版 | 未完了部分 |
+|---|---|---|
+| DP01 Context集約 | 主対象を実装 | より広いdomain入力・公開操作レビューは残る |
+| DP02 Tool共通基盤 | 定義・認可評価・呼出しの共通部分を実装 | Agent側FSM接続と全親子認可の整理はDP12/P04 |
+| DP03 Execution統合 | 実装 | domain全体のFSM利用整理を完了としない |
+| DP04 Persistence | 未着手 | facade除去、共通transaction/参加/成否照合API |
+| DP05 domain保存schema | 未着手 | MultiAgent/Workflowのstorage_contract統合 |
+| DP06 LLM集約 | 前提部分のみ | llm_contractとllm_adapterの全面統合 |
+| DP07 薄い失敗directory統合 | 実装 | domainごとの失敗語彙全体の再設計ではない |
+| DP08 composition集約 | 接続追加のみ | runtime/persistence/agent構成の物理統合 |
+| DP09 Embeddings独立 | 未着手 | vector_storeからの独立配置 |
+| DP10 Documents | 未着手 | loader/splitter再配置 |
+| DP11 assembly/concerns分解 | 主対象を実装 | Agent固有処理はAgent直下に保持 |
+| DP12 domain実行接続 | Workflow終了境界など一部 | Agent/ToolInvocation/Teamのdomain判断とFSM接続の全面分離 |
+| DP13 Recovery/Handoff | 未着手 | domain復旧・Persistence成否照合・親子操作の所有整理 |
+| P02保存参加 | Agent/Contextの既存transactionで検証 | 外側scope、savepoint、複数domainの公開参加API |
+| P01/P03〜P06保存・親子連携 | 未着手 | 下記の原子性条件を確定する必要がある |
+| 155組・393件の三角形レビュー | 再判定未完了 | 図の再解析は判定完了の代わりにはならない |
+
+NC/F/RMの全項目を「対応済み」とする資料は作成していない。受入可否はこの表の実装単位と同梱テスト証拠に限定する。
+
+## Persistenceをこの適用単位から外した理由
+
+現在のAgent初回受付は保存transaction内でTeam予約を読む。AgentからTeam内部への参照は最終設計では解消すべきだが、検証を単純に先行呼出へ移すと次の競合が生じる。
+
+1. 親側が予約の有効性を確認する。
+2. 別の処理が予約を取り消す。
+3. Agentが新しいtransactionで受付記録を保存し、取消済みの子を開始してしまう。
+
+次の適用単位では、親が所有する予約確認とAgent受付記録を同一scopeで行う参加APIが必要である。親は予約規則、Agentは受付規則、Persistenceは参加とcommit境界を所有する。Agentが親kindをswitchしてTeamを選ぶ現在の逆依存を、新しいcallbackの裏へ隠すだけでは解決にならない。
+
+具体的に未確定なのは、参加操作の公開keyword/返却値、取消との競合条件、commit後のRuntime admission、停止後の同じ子IDによる照会・再開である。Workflowのhalt/finish snapshotだけで任意action内の子実行が耐障害化されるとは扱わない。Workflow→Agent/Teamの具体経路、checkpoint、結果取込一回性をP05で定める。成否不明は単一record一致だけで成功にせず、複数domainの証拠をP06で定める。
+
+そのため既存Persistence facade、Team受付検証、予約・子記録のtransaction境界を本変更では改変しない。保証を弱めた仮実装を入れず、次の仕様・実装単位として残す。
+
+## 解析図の読み方
+
+実ソースとRBSから再生成する。従来の水平帯・グループ色・個別module枠を維持し、文字の背景は透過。M33/M41/M44への矢印は表示のみ省略し、JSON・行列・境界判定にはすべて残す。旧IDは再利用せず退役させる。
+
+これは修正版candidateの実測図であり、全r8完了時の構想図ではない。残る循環・逆依存もそのまま出力する。静的解析で見えない注入先・動的dispatchはRBSだけで完全に証明できない。Engine機構接続とdomain保存の実行テストを併用する。
+
+```bash
+bundle exec rbs -I sig validate
+python -m pip install -r tools/architecture/tools/requirements.txt
+python -m unittest discover -s tools/architecture/tests -v
+# lib/sigをcommitした後、未公開candidateでは次の指定を用いる
+python tools/architecture/refresh_diagram.py . tmp/architecture-r8-unit1 --candidate
+```
+
+同梱SVGのSHAは作成用のローカルcandidateを示す。利用者が適用してcommitしたSHAとは異なるため、適用後の図はそのcheckoutで再生成する。Rubyの検証環境、件数、skip理由、未検証環境と適用手順は配布パッケージの検証報告を参照する。

data/docs/architecture/r8-unit10.md

@@ -0,0 +1,72 @@
+# r8 unit 10: C01 MultiAgent execution connection
+
+Contract placement follows ownership of meaning and invariants, not reuse.
+AdmissionRegistry and TeamOwnershipRegistry already existed in MultiAgent.
+They remain there; neither moves to Engine and no generic Registry is added.
+
+| Owner | Responsibility |
+| --- | --- |
+| MultiAgent AdmissionRegistry | One synchronous coordination call per live owner; close admission and wait for admitted calls |
+| MultiAgent TeamOwnershipRegistry | One live Team per ID and environment; class/store consistency, construction exclusion, shutdown cleanup |
+| MultiAgent TeamCoordinator / HandoffRunner | Coordination, durable reservations, child operations, scheduling, aggregation, recovery and outcomes |
+| MultiAgent ExecutionEnvironment | Private process-local connection needed by C01: registry access, owning-environment validity and submission |
+| MultiAgent EngineEnvironment in runtime_binding | Runtime selection, participant registration/lookup, Runtime identity comparison and Execution submission to the captured Runtime |
+| Engine Runtime | Generic participant lifecycle: close, wait under one deadline, stop resources, then finalize |
+| runtime_composition/multi_agent_defaults.rb | Lazy selection of the environment and default persistence factory |
+
+There are two registrations. Recording a Team or an active coordination call
+inside a Registry is a MultiAgent operation. Registering that Registry as a
+Runtime shutdown participant is an implementation connection. Previously the
+Registry class methods and their callers mixed these two responsibilities.
+Team/Handoff also selected Runtime directly, and Team cancellation submitted
+work directly to it. The environment port separates those concrete connections.
+
+Runtime's existing begin_draining / wait_until_idle / optional
+after_runtime_shutdown protocol remains unchanged. Registry methods define
+what those callbacks mean for MultiAgent. The admission registry waits for
+active coordination calls; Team ownership waits for in-progress construction,
+not for every retained Team to disappear. Live Team references are cleared
+only after successful resource shutdown. Runtime acquires no Team/Handoff rules.
+The shared callback protocol alone is not a reason to add a new logical Contract.
+
+The default adapter shares registries by their existing class keys within each
+Runtime. Concurrent adapters get the same registered instance. Lookup does not
+register a participant, including after draining starts. Admission acquisition
+continues to reject a stopped/failed Runtime; a retained ownership registry can
+still be looked up, while its own construction gate rejects new work.
+
+Team and Handoff capture their environment on construction. Existing objects do
+not switch registry or cancellation destination when the provider changes.
+The default adapter compares the captured Runtime with the current default to
+preserve stale-owner rejection. Cancellation submission uses the captured
+Runtime explicitly. The environment itself is neither persisted nor authority
+for a durable execution. This is an internal composition extension, not a new
+supported application plugin API.
+
+Public Team/Handoff signatures, exception classes, durable IDs, record schemas,
+CAS rules, parent/child atomic participation and recovery semantics are unchanged.
+ReservedChildAdmission still validates domain reservations within the shared
+persistence scope. It is distinct from the process-local AdmissionRegistry.
+Engine lifecycle and Execution completion/cancellation rules are unchanged.
+
+## Evidence and remaining scope
+
+Standalone tests use both registries without loading Engine. Connection tests
+exercise Team identity and store consistency, duplicate Handoff calls, release
+on failure, stale-owner rejection, original-environment cancellation, callback
+cleanup and real worker submission after default Runtime replacement. Existing
+shutdown tests cover concurrent registration, construction during draining,
+failed EventLoop closure, deadlines and finalization. Durable coordination and
+recovery suites remain acceptance gates.
+
+The dependency model adds M89/G63 for multi_agent/runtime_binding. AST guards
+reject Runtime/Engine selection and private shutdown registration/lookup inside
+MultiAgent domain files. Graph guards reject direct domain-to-Engine/binding
+dependencies while retaining lower-level reverse-dependency restrictions.
+Measured Ruby/RBS references remain visible; these are scoped rules, not proof
+that the complete dependency graph is acyclic or every Contract is complete.
+
+Remaining work includes Workflow connections and durable child outcomes,
+MultiAgent's existing global/default persistence selection, broader semantic
+dependency review, and live-service/additional persistence acceptance gates.
+This unit completes the proposed C01 Runtime connection split, not all C01 work.

data/docs/architecture/r8-unit11.md

@@ -0,0 +1,71 @@
+# r8 unit 11: C04 concrete Policy and LLM connection selection
+
+Contract placement follows ownership of meaning and invariants, not reuse.
+This unit addresses review findings B01 and B02: Agent::Base selected the
+concrete DefaultPolicy, and InvocationActions constructed the concrete LLM
+AsyncClient. Neither choice belongs to Agent progress decisions.
+
+| Owner | Responsibility |
+| --- | --- |
+| Agent::Base / C04 | Declare, validate, inherit and use a ContextPolicy |
+| ContextPolicy / C05 | Context-selection operation contract |
+| DefaultPolicy implementation / I01 | Existing selection strategy and token-budget allocation |
+| runtime_composition/agent_defaults.rb / A01 | Install DefaultPolicy through the existing Base.context_policy DSL |
+| Agent InvocationActions / C04 | Prepare the LLM request, request a client through the owning environment, track completion and deliver progress |
+| Agent ExecutionEnvironment | Private connection capability to build an LLM client for the supplied adapter |
+| Agent EngineEnvironment / I07 | Select AsyncClient and bind submission to the captured Runtime |
+| LLM AsyncClient / I06 | Run the complete C09 operation through C13 submission; forward stream chunks and cancellation |
+| LLMAdapter / C09 | Synchronous complete/stream operations and request/response rules |
+
+Ordinary require "phronomy" installs the existing DefaultPolicy instance.
+Base no longer supplies a concrete fallback; an unconfigured root raises a
+ConfigurationError. No supported loading path is left unconfigured. Class
+inheritance and explicit Policy overrides retain their existing semantics.
+Selecting the default does not create configuration, stores or a Runtime.
+This does not change DefaultPolicy's algorithm or introduce a policy registry.
+
+InvocationActions now asks its retained environment for the LLM client.
+It still reads the configured adapter at dispatch time. The Engine binding
+constructs AsyncClient with itself as the existing C13 submitter protocol;
+AsyncClient does not depend on the Agent environment type. No generic factory
+registry, new logical Contract or public application API is introduced.
+
+The client forwards the original TaskResult rather than replacing it. Logical
+cancellation and physical worker completion remain distinct. An explicit pool
+still uses Execution's existing pool-selection protocol and overrides the
+injected submitter. A standalone client with no injected submitter continues
+to resolve the current default Runtime at each call. Client construction
+starts no Runtime resources.
+
+For Agent calls, submission now uses the Agent's captured Runtime, matching
+its sessions and other work. Replacing the default Runtime cannot redirect
+only its LLM worker to a different owner. A stopped owner rejects new work
+through the existing RuntimeShutdownError. Provider errors, admission failure,
+chunk ordering, cancellation and completion are not translated by this change.
+Public Agent/Policy signatures, manifests, durable schemas and recovery rules
+are unchanged. The private AsyncClient constructor adds an optional submitter;
+its private RBS uses the existing _ExecutionSubmitter interface.
+
+## Evidence and remaining scope
+
+Regression tests cover ordinary lazy loading, inherited/explicit Policies,
+complete and streaming Agent calls after default Runtime replacement, live
+adapter selection, provider worker ownership and EventLoop callback ownership.
+Connection tests cover resource-free construction and stopped-owner rejection.
+Async client tests cover the narrow submitter, explicit pool precedence and
+physical completion after cancellation; existing failure/backpressure tests
+remain acceptance gates.
+
+Ruby AST guards reject DefaultPolicy and AsyncClient references in Agent domain
+files. The Ruby/RBS graph gate separately rejects Agent domain dependencies on
+llm_adapter/async and permits the binding connection. Existing lower-level
+reverse-dependency rules remain intact. These checks have the same static
+analysis limitations as the existing architecture tooling; they do not prove
+that all logical Contract dependencies are acyclic or complete.
+
+B01 and B02 are addressed in this candidate. C04 is not declared globally
+complete. Remaining review includes C01 Orchestrator inheritance from the
+concrete Agent tool, C02 Workflow execution connections and separately scoped
+durable child behavior, and Recovery's domain/persistence responsibilities.
+Existing domain-level explicit/configured/default store selection is not itself
+a defect: concrete default persistence factories are already in composition.

data/docs/architecture/r8-unit12.md

@@ -0,0 +1,67 @@
+# r8 unit 12: C01 subagent operations use the C06 Tool contract
+
+Contract placement follows ownership of meaning and invariants, not reuse.
+This unit addresses B03: Orchestrator.subagent generated a subclass of the
+concrete Tools::Agent implementation (I04). The generated class replaced Agent
+creation and child coordination, but inherited Tool operation rules incidentally.
+
+| Owner | Responsibility |
+| --- | --- |
+| MultiAgent / C01 | Define the subagent operation, child class, knowledge/context inheritance, child error policy and durable reconciliation |
+| Agent / C04 | Public child invocation and recovery outcomes |
+| Tool / C06 | Input schema, Tool error policy, result limits and completion-handle requirements |
+| Execution / C13 | Nonblocking completion composition and physical completion propagation |
+| Tools::Agent / I04 | Standalone concrete Agent Tool construction through from_agent |
+
+Orchestrator remains an Agent::Base subclass: a coordinating Agent is a valid
+C01-to-C04 relationship. Its generated subagent Tool now derives directly from
+Tool::Base and explicitly declares cooperative execution and its input schema.
+Generating this domain-owned operation belongs to C01; no runtime registry,
+factory, new logical Contract or composition layer is needed for that operation.
+
+Tool::Base has a private call_async_operation helper that validates inputs,
+requires a completion handle, applies Tool error policy and limits successful
+results. Its block supplies the domain operation. It does not create Agents,
+select implementations, wait for completion or decide how many application
+filters to run. Both the subagent operation and Tools::Agent use this helper.
+The default Tool::Base#call_async path and synchronous-call delegation are
+unchanged, including the unit 9 result-transformation behavior.
+
+ExecutionRehydrationRequiredError remains an Agent-domain outcome. Tools::Agent
+and the C01 operation retain their private pass-through hooks; C06 does not
+reference this error or interpret recovery. Generic errors retain their original
+backtrace when wrapped; ToolError and CancellationError remain unchanged.
+Suppression logging uses C06's existing RuntimeSettings logger capability.
+
+An ordinary asynchronous subagent call still checks cancellation before schema
+validation, starts the child without occupying a waiting offload worker, maps
+its output and applies Tool policy. The subagent on_error option continues to
+control child failure (raise or skip); it is distinct from Tool on_error policy.
+
+An admitted durable child follows the existing reconciliation path directly.
+It is reconciled even with a cancelled parent token; unknown outcomes and
+recovery requirements are not hidden. This path retains its existing validation,
+result and cancellation behavior, without adding the ordinary-call truncation
+or error-suppression pipeline. Agent-owned configured result transformations
+still wrap either path in the configured order, including repeated filters.
+Parent/child IDs, reservations, stores, persistence schemas and recovery rules
+are unchanged. Logical settlement does not falsely imply physical completion.
+
+## Evidence and remaining scope
+
+Non-Agent Tool tests cover asynchronous validation/coercion, errors, result
+limits, cancellation and separate physical completion. Subagent tests cover
+operation without Tools::Agent, ordinary and admitted-child cancellation,
+recovery error identity and repeated transformations after truncation. Existing
+pool-starvation, knowledge inheritance, durable coordination/restart and result
+transformation tests remain acceptance gates.
+
+The AST gate rejects concrete Tools references in C01 domain files and
+Agent recovery interpretation in C06. The Ruby/RBS graph gate rejects C01
+domain-to-tools implementation dependencies. Existing lower-level and Engine
+binding rules remain intact. These are targeted regression checks, not proof
+of all logical Contract dependencies or global acyclicity.
+
+B03 is addressed in this candidate. C02 Workflow execution connections, its
+separately scoped durable child guarantees, and broader Recovery responsibility
+review remain. No completed status is asserted for all of C01/C02/C04.

data/docs/architecture/r8-unit13.md

@@ -0,0 +1,61 @@
+# r8 unit 13: C02 Workflow rules and Engine connections
+
+Contract placement follows ownership of meaning and invariants, not reuse.
+This unit addresses B04: WorkflowRunner and its registry previously selected
+Runtime, built FSMSession instances and constructed Engine event envelopes.
+The phase compiler also contained Workflow callback rules alongside the
+state_machines translation.
+
+| Owner | Responsibility |
+| --- | --- |
+| Workflow / C02 | Topology, callback rules, segment admission, identity/owner checks, hydration, snapshots, persistence outcome classification and recovery-required retention |
+| Workflow runtime binding | Compile topology into state_machines, build/register sessions, select the owning Runtime and translate classified outcomes into terminal decisions |
+| Execution / C13 | Completion handles and receiver lifecycle/routing protocol |
+| Engine | Serial dispatch, atomic delivery, generic FSM execution and terminal gate |
+| Application | State actions, guards, external event correlation and child operation choices |
+
+WorkflowActionRules owns synchronous entry, transition and exit callback
+constraints, optional event arguments and adoption of returned WorkflowContext
+values. The compiler installs these rules as machine callbacks. Initial entry
+callbacks also pass through the rules before reaching the generic FSM session.
+Application callback order remains exit, transition action, entry.
+
+WorkflowExecutionEnvironment is a private C02 connection port. Composition
+installs its provider; WorkflowEngineEnvironment implements it. Compiling a
+Workflow captures its environment without starting an EventLoop, workers or
+execution registration. Starts, durable loads, live signals, terminal saves,
+completion and admission release use that same owner. Changing the default
+Runtime does not silently move a compiled Workflow or its continuations to a
+different owner. Recompile the Workflow after replacing/stopping that Runtime.
+Scalar per-call configuration and configured repository resolution retain their
+existing behavior. Tracing keeps its independent existing execution composition.
+
+WorkflowExecutionRegistry remains in C02. workflow_instance_id, opaque owner
+token and fsm_session_id remain distinct. Routing resolves the current target
+under the existing lifecycle lock; ExecutionReceiverBinding constructs the
+Engine event within the same atomic delivery operation. No new registry or
+public extension API is introduced.
+
+Runner continues to classify terminal persistence results as success, known
+failure or outcome unknown. The binding only translates these outcomes into
+complete, fail or retire instructions. A successful terminal notification still
+requires confirmed persistence. An uncertain outcome still retires the session
+while retaining recovery-required admission; it does not announce success or
+release another owner's segment. Readback/reconciliation does not retry a save.
+Admission is acquired before durable load, and rejected competitors do not load.
+
+## Evidence and remaining scope
+
+Existing tests cover competing admission, immutable terminal snapshots, lost
+responses, unknown outcomes, shutdown, wait/resume, live event routing and action
+ordering. New tests cover standalone callback rules, resource-free compilation,
+owner retention across blocked load/save and default replacement, and rejection
+on a stopped owner. Ruby AST and Ruby/RBS graph checks reject C02-to-Engine or
+C02-to-binding dependencies while preserving lower-layer restrictions.
+
+The targeted C02 execution connection boundary is addressed. This is not proof
+that every logical Contract is complete or that the whole source graph is
+acyclic. F01 durable Workflow children still need an explicit specification for
+identity, reservation, completion persistence and recovery; application actions
+may still launch ordinary asynchronous work. Broader Recovery ownership review
+also remains. No durable child protocol or persistence schema is added here.

data/docs/architecture/r8-unit14.md

@@ -0,0 +1,72 @@
+# r8 unit 14: assign existing recovery rules to their owners
+
+The former private `Phronomy::Recovery` combined Agent operation subjects and
+factual resolutions with general persistence evidence comparison. Sharing a
+file or using the word recovery does not make these one Contract.
+
+| Responsibility | Owner after this change |
+| --- | --- |
+| LLM/Tool subject identity, resolution material, resumability classification | C04 Agent, private `Agent::RecoveryRules` |
+| Revision/snapshot evidence comparison and normalization | C07 Persistence, private `Persistence::SnapshotComparison` |
+| Selection of Workflow evidence and interpretation of pre/post/conflict | C02 Workflow, existing WorkflowRunner |
+| Agent restoration, resolution save/readback and continuation | C04 Agent, existing RecoveryCoordinator |
+| Parent/child coordination and durable reconciliation | C01 MultiAgent, unchanged |
+
+There is no independent Recovery Contract. C14 remains retired; C17 is
+OutputParser. M50/G34 are retired in the current source architecture without
+reusing their identifiers. Historical phase configurations retain their history.
+
+## Behavioral scope
+
+This is a relocation of existing rules and their call sites. No public API,
+persisted schema, outcome value, retry, observer, admission or ownership rule is
+added. Error classes/messages and validation ordering are retained. Ordinary
+framework boot still loads the relocated definitions. The former private
+namespace and file are removed, without a compatibility alias. The existing
+public `Phronomy::ExecutionRehydrationRequiredError` moves to `agent/api` while
+retaining its root namespace, superclass and lazy-loading behavior; it remains
+an Agent-domain outcome, also consumed by delegation callers.
+
+`Agent::RecoveryRules` describes external operation facts as `succeeded`,
+`failed` or `not_performed`. Its `Classification` describes resumability. The
+existing structural `persistence_operation` subject normalization is retained
+to avoid changing accepted input or errors; it does not provide a new generic
+durable operation identity or a new supported Agent resolution operation.
+
+`Persistence::SnapshotComparison` returns `pre_state`, `post_state` or
+`conflict`. It performs no I/O. Workflow supplies authoritative readback and
+intended evidence, handles read errors, and decides completion, known failure
+or recovery-waiting admission retention. In particular:
+
+- An absent record with an absent expected pre revision remains pre-state.
+- Without an explicit post revision, a matching normalized snapshot and a
+  revision different from the expected pre revision identifies post-state.
+- With an explicit post revision, both revision and snapshot must match.
+- Otherwise a matching pre revision identifies pre-state, even if the snapshot
+  differs. The explicit post comparison still precedes this check.
+- Accessors precede symbol keys, which precede string keys. Nested hash keys
+  and symbol values normalize to strings. Read/accessor errors propagate to
+  the owning domain as before.
+
+`Persistence::SaveOutcome` is unchanged. It compares domain-supplied before/after
+evidence using its existing equality and reports `committed`, `not_committed`
+or `unknown`. It is not substituted for snapshot comparison: their predicates
+and error handling differ. Agent-specific execution metadata comparisons also
+remain in Agent.
+
+## Verification and limits
+
+The relocated specs retain existing cases. Additional regressions fix comparison
+priority, normalization, accessor precedence, error identity, resolution error
+ordering and subject immutability. The same 45 primitive examples pass against
+the unit13 definitions and the relocated definitions. Existing Agent recovery
+and Workflow terminal persistence tests cover their surrounding behavior.
+
+AST and combined Ruby/RBS graph gates reject dependencies from other domains on
+Agent recovery rules and domain references in generic persistence comparison.
+These checks guard this boundary, not all possible semantic coupling. Root
+loader wiring and dynamic injection require separate review and runtime tests.
+
+Durable Workflow children (F01) remain deferred feature work, outside this
+responsibility refactor and outside its acceptance criteria. This change does
+not establish global acyclicity or completion of every Contract.

data/docs/architecture/r8-unit15.md

@@ -0,0 +1,65 @@
+# r8 unit15: Generation contract boundaries
+
+This responsibility refactor is based on applied unit14, commit
+`97c3d76b35594bb971a60a2932410ddf22e48d3a` (tree
+`c326196212a4ac369294a9ccb936619813e51250`).
+
+## B05: Agent operation connection
+
+Generation previously used `send(:__invoke_async_with_event_sink, ...)` to
+select Agent's private per-execution listener. It now constructs each Agent
+once with its public `on_event:` option and calls public `invoke_async`.
+
+The private Generation `AgentOperation` owns the connection, not Agent execution:
+
+- Each returned TaskResult supplies that call's terminal result or original
+  failure. Terminal incarnation notifications are not interpreted a second time.
+- Approval remains a listener notification while the Agent TaskResult is pending.
+  Generation retains its existing policy: approval suspension fails the pipeline.
+- Pending submissions retain their Generation listeners in Workflow entry order.
+  Agent continues to own admission. A rejected overlapping call cannot replace
+  another call's approval listener; a queued call may be admitted after the prior
+  result settles. Only the corresponding settled or synchronously failed request
+  is removed. Result callbacks are thread-safe and never wait on the EventLoop.
+- Agent instances and their conversations are reused across iterations and
+  pipeline invocations. No per-call Agent creation, automatic cancellation,
+  retry policy, durable child tracking, or new runtime registry is introduced.
+- The unused private Agent event-sink method is removed. Per-invocation public
+  `on_event:` arguments remain unsupported.
+
+`AgentResultReceiver` and `PipelineState` retain event interpretation, parsing,
+request correlation, stale-result rejection, review feedback and trust decisions.
+Their rule bodies are unchanged. `WorkflowBuilder` retains state definitions and
+entry order. Its private operation port is not a new public Agent API.
+
+The connection relies on existing public Agent guarantees: one admitted
+execution per Agent, ordered incarnation notifications, and TaskResult settlement
+for terminal results. Approval does not settle the TaskResult. Handoff remains
+outside GeneratorVerifier completion semantics, as before.
+
+## B06: Default parser composition
+
+`runtime_composition/generation_defaults.rb` selects the existing JsonParser
+through a private one-time factory binding. Generation lazily creates and reuses
+one default parser per pipeline only when default parsing is needed. Boot creates
+no parser, Agent, Persistence or Runtime for this binding.
+
+Generation owns `default_parse_draft` and `default_parse_review`, including the
+existing ParseError fallback payloads. Existing custom parser callables take
+precedence. No application configuration changes are required. OutputParser's
+contract and its concrete implementations are unchanged.
+
+## Scope and verification
+
+AST regression gates reject concrete parser selection and the removed private
+Agent invocation in Generation. Public-only Agent doubles cover inline completion,
+busy failure, queued admission, stale terminal notifications, timeout, cancellation
+and approval while pending. Real Agent integration covers approval in both phases
+and retained conversations. Domain event-rule tests use the private Generation
+operation port; they no longer pretend a private Agent method is the public API.
+
+Public signatures, result shape, stored schemas, generation/review decisions,
+parser fallback values and default iteration limits are preserved. The internal
+result-observation plumbing changes; this is not merely a physical file move.
+F01 durable Workflow children remain deferred feature work. This checkpoint does
+not certify all framework dependencies or all concrete Engine responsibilities.

data/docs/architecture/r8-unit16.md

@@ -0,0 +1,54 @@
+# r8 unit16: Explicit cancellation subscription ownership
+
+This responsibility refactor is based on applied unit15, commit
+`9aebef9217383cebb7fa3ec8b2d17b5763cd3c5e` (tree
+`fcc1bd3bc72ed611a7d4e9090dcf2391b6bc7471`). It addresses B07 only.
+
+## C13 owns registration lifetime
+
+`Concurrency::ResultSubscriptions#explicit_cancellation` registers the existing
+CancellationToken notification and owns its disposal through `close`. This is
+an internal Execution operation, reusing the existing subscription collection;
+it is not a new public registry or a new Tool implementation.
+
+The existing `cancellation` operation delegates its registration bookkeeping to
+this method and retains its additional `cancelled?` check. Its `Subscriptions`
+subclass retains deadline scheduling. An explicit registration alone neither
+checks an elapsed deadline nor schedules a timer.
+
+CancellationToken still owns callback storage, delivery, exception isolation,
+and private removal. `on_cancel` still returns the token. Public signatures,
+exception types, and the callback behavior are unchanged. In particular, closing
+a registration does not retract a callback already taken by concurrent `cancel!`.
+
+## Consumers retain their execution decisions
+
+- C01 TeamCoordinator registers its existing cancellation callback through C13
+  and closes the collection in the existing `ensure` block. Team still owns the
+  durable cancel request, child cancellation, and terminal outcome interpretation.
+- I09 OffloadPool registers its existing operation cancellation callback through
+  the same operation. It still owns queue/worker admission, logical settlement,
+  deadline promotion, abandonment, and physical completion. Timer registrations
+  are closed before cancellation registrations, preserving cleanup order.
+- C06 Tool already passes its token to the standard offloaded submitter. Its
+  operation dispatch and cooperative/custom-async paths are unchanged. No
+  Tool-specific subscription or symmetric copy of Team logic is introduced.
+
+An already-cancelled token may deliver during registration and close the
+subscription collection before registration returns. The existing collection's
+`add` behavior disposes such a late-added registration immediately. The same
+mechanism covers a concurrent `close` during registration.
+
+## Verification and remaining scope
+
+Behavioral checks cover explicit cancellation, expired deadlines without explicit
+cancellation, inline and concurrent close, delivery already in flight, callback
+failure isolation, and Team/worker cleanup after success and failure. Existing
+OffloadPool timeout, cancellation, and physical-completion tests remain applicable.
+The AST gate rejects private token-removal calls outside Execution, including
+literal reflective calls in Engine and domain code.
+
+B08 configuration access and F01 durable Workflow children are not implemented
+here. Public API/RBS, storage schemas, default configuration, and domain rules
+are retained. This change does not certify all Contract boundaries or eliminate
+the aggregate implementation graph's cycles.