phronomy 0.27.0 → 0.28.0

data/docs/architecture/backend-groups.md

@@ -0,0 +1,152 @@
+# Backend responsibilities and asynchronous execution clients
+
+The diagram distinguishes responsibility **groups** from its display layers.
+The earlier B1-B6 horizontal bands and topical columns are restored for
+readability. `G14`, `G46`, `G47` and `G48` remain stable responsibility identifiers;
+boundary permissions follow those responsibilities, not B/G numbers or positions.
+Each source directory keeps its own module box and stable module ID. Restoring
+the display does not undo the separation of backend contracts and execution.
+
+The restored display puts separated Backend Contracts in B5, alongside but
+distinct from Engine Internals and Execution Contracts. B4 holds Async Clients and separately grouped Implementations. Execution
+operations and values now share G58; the former G59 service split is removed. Backend directories awaiting separation remain visibly mixed
+in B4; their contracts move to B5 in their implemented phase. These are display
+positions, not a shared architectural level or namespace.
+
+| Group | Responsibility | Dependency rule |
+|---|---|---|
+| G14 Engine Internals | Runtime, workers, FSM and EventLoop | No feature-specific backend or client dependencies |
+| G58 Execution Framework | Submission protocol, TaskResult, Execution, Blocking, controls and common rules | Only Execution and Common, including neutral settings; Engine implements the mechanism |
+| G46 Async Clients | Execute synchronous backend operations through Execution | Use Backend and Execution contracts; no direct Engine or concrete backend selection |
+| G47 Backend Contracts | Synchronous SPI, values, errors and shared rules | No Engine, Execution Services, Async Client or concrete implementation dependencies |
+| G48 Backend Implementations | Implement the synchronous backend SPI | Depend on the corresponding Contracts; no Engine, Execution Services or client dependencies |
+| G57 Content Service | Content IDs, canonical text/JSON and digest integrity over Storage | Uses neutral Storage and Common; no physical backend, Engine or domain orchestration dependencies |
+
+Composition chooses concrete backends and supplies them to consumers. These
+are source-ownership groups, not shared Ruby namespaces. Synchronous APIs can
+be called directly. Diagram links represent source references; calls through
+injected objects require separate runtime review.
+
+## Implemented phase: P1/P2/P3/P4 (`storage`)
+
+P3 adds public VectorStore and Embeddings AsyncClients. Their synchronous
+contracts and implementations have no Engine dependencies. See the
+[public receiver migration](../migrations/vector-async-clients.md).
+
+### P2: LLM
+
+- Install the AST analyzer, group annotations, SVG formatter and boundary gate
+  in `tools/architecture/`. The Architecture workflow checks the committed
+  phase and generates evidence for its actual checkout SHA.
+- `LLMAdapter::Base` now defines synchronous generation plus chat construction,
+  configuration, message/tool-call values, identity and optional input budget.
+  RubyLLM-specific construction and error translation belong to its backend.
+  Adapter extensions must implement the new operations; no legacy wrapper remains.
+- `LLMAdapter::AsyncClient` owns the internal `complete_async` and `stream_async`
+  operations in `llm_adapter/async/`. It is not a public extension API.
+- `LLMAdapter::RubyLLM` lives in `llm_adapter/backends/` and still inherits Base.
+  Its public name, synchronous signatures and default configuration are unchanged.
+- Zeitwerk collapses these two new directories. Neither `Phronomy::Async` nor
+  `LLMAdapter::Async` / `LLMAdapter::Backends` is introduced.
+- Agent constructs the framework client around the configured synchronous
+  adapter. Custom adapters implement no async methods and need no pool logic.
+
+The client preserves `on_full: :raise`, the original pool TaskResult, token
+forwarding and per-chunk cancellation. Transport timeout/retry stays with the
+adapter/provider. Construction starts no Runtime, and the default pool is
+resolved again on each operation; an injected pool stays caller-owned. Only an
+internal lightweight sink runs on the worker; application event callbacks
+continue to run on EventLoop.
+
+Use `require "phronomy"` and the public constants. The old implementation path
+`phronomy/llm_adapter/ruby_llm` moves to
+`phronomy/llm_adapter/backends/ruby_llm`; arbitrary partial-load paths are not the
+public loading contract. No shim in the contract directory reintroduces an
+implementation dependency. No public RBS or Stable/Beta API snapshot changes
+are needed in this phase; both are verified unchanged.
+
+### P3: VectorStore and Embeddings
+
+- `VectorStore::AsyncClient` owns public add/search/remove/clear async operations;
+  `VectorStore::Embeddings::AsyncClient` owns public `embed_async`.
+- Backends implement only synchronous methods. The old `AsyncBackend` mixin
+  and inherited async methods are removed; application callers change receiver.
+- InMemory, Pgvector, RedisSearch and RubyLLMEmbeddings move into `backends/`
+  directories. Their public constants, synchronous signatures and bodies stay
+  unchanged. Zeitwerk explicitly collapses the new `async/` and `backends/` paths.
+- Synchronous RBS uses structural `_CancellationSignal`; async signatures keep
+  TaskResult and the execution token. The public API snapshot records the new
+  receivers and the intentional removals from Base/InMemory.
+- All three original backend-to-Engine edges are removed. In the measured view,
+  M28/M29 join G47 Contracts in B5. M67/M68 are clients in B4 and M71/M72 are
+  separately grouped implementations. No pending Storage clients are drawn.
+
+### P4: Storage execution
+
+- Public `Storage::AsyncClient#transaction_async` opens the raw backend transaction
+  on a worker and yields its scoped Storage::View. Backends stay synchronous.
+- Private `Storage::AsyncClient.submit(pool:)` executes existing domain units
+  without adding a transaction, timeout or token. All 16 durable submission sites
+  are recorded in the [execution inventory](storage-execution-boundaries.md).
+- M69 is an Async Client and M35 a concrete Storage backend in B4.
+  Existing `Storage::Backends` is not collapsed.
+- See the [public API and transaction rules](../migrations/storage-async-client.md).
+
+### ContentStore service ownership
+
+ContentStore is a content management service using Storage, not a peer physical
+backend. Its API, canonicalization, StoredContents implementation and owned
+StorageSchema live in `content_store/`. Base remains shared by StoredContents
+and the Persistence exception facade. The unnecessary `backends/` subdivision
+and Zeitwerk collapse are removed without a forwarding file or alias.
+
+M10 belongs to G57 Content Service in the persistence column of display band B3.
+M73 is retired, not reused. G47/G48 contain no ContentStore modules. The real
+M10-to-Storage dependency remains in both the drawing and the full graph.
+The boundary gate rejects reverse Storage-to-ContentStore dependencies and any
+service path to a physical backend, Engine, client or domain orchestration.
+Public constants, signatures, content IDs, exceptions and transaction behavior
+remain unchanged. See [ADR-062](../decisions/062-content-store-service.md).
+
+## r8 unit 1 framework boundaries
+
+G58/M76/M77 now owns the common Execution framework under `execution/`.
+Engine owns FSM-specific values and the pool/timer/runtime binding, while
+composition selects that binding. Tracing owns explicit observation. Context
+and Tool now own their shared operations, not merely value/error declarations.
+The former G59/M78 split is retired. See [r8 unit 1](r8-unit1.md) for the exact
+implemented scope, API removals and incomplete Persistence/domain work.
+
+The full architecture still contains existing cycles outside the checked scope.
+The recorded graph is not an ideal final r8 diagram.
+
+## Pending phase
+
+P5 completes the final cross-repository/API/docs review after application.
+All retained P2-P4 responsibilities exist in source; the unnecessary M73 split
+is superseded by G57 service ownership. The measured SVG still comes from
+actual Ruby analysis; the target concept is a separate explanatory artifact.
+
+## Regenerate and review
+
+See [tool instructions](../../tools/architecture/README.md). The normal command
+reads `tools/architecture/phase.json`:
+
+```sh
+python tools/architecture/refresh_diagram.py . tmp/architecture
+```
+
+The output includes the matrix, source hashes, boundary report, module/file
+cycles and the delta from baseline 84668606. Source/module/group changes require
+matching annotation updates. No up/down rule or coordinate controls the gate.
+Ruby loader, RBS, cancellation, admission, streaming and configuration tests
+remain necessary: static analysis does not replace them.
+
+An unpublished local candidate must use `--candidate`. Its SVG states that it
+is unapplied and disables GitHub source links. Applied commits and CI output
+use actual source links. CI artifacts are generated after the source commit;
+there is no self-referential SVG commit hash or automatic commit/push.
+
+Text panels are transparent and module outlines/group colors remain intact.
+Arrows into M33/M41/M44 are hidden by presentation settings; their AST edges,
+source evidence and matrix cells are preserved. Boundary rules inspect all edges.

data/docs/architecture/before-llm-input.md

@@ -28,10 +28,10 @@ candidates are accumulated in hook order.
 
 ## 3. Input and result
 
-Hooks receive immutable `Phronomy::Agent::LLMInputBuildContext` metadata. They do
+Hooks receive immutable `Phronomy::Context::LLMInputBuildContext` metadata. They do
 not receive a mutable Provider chat/message array.
 
-A hook returns `Phronomy::Agent::LLMInputPatch` or `nil`.
+A hook returns `Phronomy::Context::LLMInputPatch` or `nil`.
 
 These two types live in the shared `agent/context_contract/` implementation
 directory together with the Policy input and result contracts. Zeitwerk
@@ -40,7 +40,7 @@ names. Hook registration, invocation, and result handling are unchanged; see
 [ADR-036](../decisions/036-context-contract-ownership.md).
 
 ```ruby
-Phronomy::Agent::LLMInputPatch.new(
+Phronomy::Context::LLMInputPatch.new(
   model_config_patch: {temperature: 0.2},
   segment_candidates: [
     {

data/docs/architecture/context-management.md

@@ -85,7 +85,7 @@ same abstraction level.
 Application code supplies an ordinary reusable Ruby strategy object:
 
 ```ruby
-class SearchContextPolicy < Phronomy::Agent::ContextPolicy
+class SearchContextPolicy < Phronomy::Context::ContextPolicy
   def initialize(search:)
     @search = search
   end

data/docs/architecture/execution-abstraction-review.md

@@ -0,0 +1,88 @@
+# Execution abstraction revision (local review candidate, 2026-09-29)
+
+This candidate supersedes the unapplied Results split. It is based on main
+653e255a, with the earlier execution-boundary prototype included. It is not a
+record of application to main. The historical D02 reports describe their original
+revisions; the control ownership decision below supersedes them for this candidate.
+
+## Responsibilities
+
+| Owner | Owns | Consumers should know |
+|---|---|---|
+| Execution Contracts (G58, B5) | Context, TaskResult/Outcome, cancellation/deadline values, shared errors, neutral scope/result implementation | Public inputs, result handles and errors |
+| Execution Services (G59, B4) | Fan-out, child control lifetime, invocation admission checks, completion adaptation, worker submission and deadline registration | Start/observe APIs and domain value/error policies |
+| Engine Internals (G14, B5) | Runtime resources, EventLoop, FSMSession | Only runner/lifecycle/composition owners connect here |
+| Engine Concurrency (G61, B5) | Pools and queues | Engine supplies scheduling and wait-policy context |
+
+Bands are visual organization, not a dependency order. Backend Contracts remain
+in B5. `execution_contract/errors`, `execution_result` and
+`execution_result/concurrency` are removed. Their neutral implementation is
+integrated into the existing `execution_contract` and its `concurrency` child.
+M79/M80/M81 and G60 are retired. TaskResult is not returned to Services: doing so
+would recreate Engine→Services. The two contract directories remain mutually
+referencing within G58; the design does not claim zero cycles or pure declarations.
+
+## Actual hiding, beyond renaming dependency hubs
+
+| Consumer | Previous knowledge | Current entry point |
+|---|---|---|
+| Agent::ExecutionCoordinator | Extracted context scope, checked open/cancelled state, selected scope error | InvocationControls.attach + check_start!; Agent still owns admission and its result production |
+| MultiAgent::Orchestrator | Called Execution's private fan-out, constructed OperationBinding, linked tokens, selected context, closed subscriptions | Execution.run_async(max_concurrency:) + start_child; supplies child invocation |
+| Tools::Agent / generated subagent tools | Created deferred result and relayed completion/failure callbacks | AsyncOperation.call/capture; supplies output/error policy |
+| Agent::ToolBinding | Called TaskResult.__map_completion, a special internal composition path | AsyncOperation.map; supplies filters |
+| Workflow builder (earlier included change) | Used FSM's finish vocabulary | Workflow::Completion; runner translates to FSM |
+
+InvocationControls extends the existing service helper and absorbs the removed
+OperationBinding's lifetime logic. It is not a pass-through factory that still
+forces callers to manage cleanup. AsyncOperation encapsulates notification
+multiplicity, startup/transformation failure, and physical completion. Domain
+consumers still legitimately depend on TaskResult return types and cancellation
+inputs; hiding those via aliases would not improve the abstraction.
+
+ExecutionCoordinator, WorkflowRunner and durable reconciliation coordinators
+remain result producers. Their lifecycle, registry and terminal policy code has
+not all been turned into a generic facade. The public user-facing async APIs and
+backend contracts retain their namespaces.
+
+## Investigation heuristic
+
+Detect each M0→M1, M1→M2, M0→M2 triangle in the complete Ruby + RBS graph.
+Prioritize adjacent descending display bands, then other descending bands, then
+all remaining graph triangles. Keep sidebar modules and visually hidden arrows.
+Do not remove edges or make a triangle a CI violation solely on that basis.
+
+For M0's direct M2 usage, inspect its actual source operation:
+
+- Internal detail: Orchestrator linked child tokens and closed subscriptions;
+  Execution now owns this through start_child.
+- Connection: a runner registers its session with Runtime; this can belong to
+  that runner. Move it only if its current owner mixes unrelated responsibilities.
+- Shared/public contract: AsyncClient returns TaskResult and callers handle its
+  result. Keep the declared RBS dependency instead of erasing the type.
+
+Multiple M1 paths may identify the same direct edge. Reports include both the
+triangle count and the number of distinct M0→M2 pairs. RBS-only direct edges are
+marked, not automatically accepted. Directory aggregation can combine different
+classes/functions, so a graph path is not proof of a call chain. Dynamic dispatch
+can also leak details without any constant-reference triangle.
+
+`dependency_triangles.json` preserves all three edges' source evidence;
+`dependency_triangles.csv` is the review queue. Entries start as unreviewed.
+A separate narrow AST regression gate rejects the already-corrected private
+scope methods and selected consumers' manual result settlement. It does not
+purport to detect every possible abstraction leak.
+
+## Compatibility and verification scope
+
+Execution.run/run_async accept additive max_concurrency. No new backend methods
+are required from application authors. The included earlier candidate removes
+InvocationContext#effective_timeout_token/#effective_cancellation_token and the
+internal Deadline#attach_to, CancellationScope, old FSM vocabulary ownership.
+This revision removes internal OperationBinding and TaskResult.__map_completion.
+There are no backward aliases that point neutral contracts back at services.
+
+Tests cover bounded admission, cancellation before queued start, explicit child
+context identity, cleanup after completion/start failure, duplicate callback
+notifications, original error identity, recovery errors, and physical completion.
+Existing Agent, Tool, Workflow, persistence/recovery and async tests remain gates.
+The delivered evidence report records actual execution results and limitations.

data/docs/architecture/execution-boundaries.md

@@ -0,0 +1,28 @@
+# Execution dependency ownership
+
+Use the highest existing operation that expresses the caller's responsibility.
+A facade is useful when it owns real coordination, not just because it reduces
+arrows. These cases distinguish shared contracts from executable machinery.
+
+| Caller / operation | Dependency after this change | Decision |
+|---|---|---|
+| ToolBinding result filter | TaskResult private completion mapping | Remove duplicate physical-completion handling; source completion alone must not finish the filtered result |
+| Tracing span finish | Blocking.call_async | Generic default-pool work; observe rejection in the returned result |
+| Approval listener dispatch | Blocking.call_async | Generic default-pool work; log admission and later callback errors |
+| Agent/Workflow synchronous entry guard | Runtime.in_event_loop_context? | Query context without creating Runtime |
+| Prompt parser, Runnable users | Execution Contracts | Public callable/value contract, not pool internals |
+| Agent lifecycle/state, capability and journal input markers | Execution Contracts | Methodless classification; preserve direct include and validation |
+| Tool and async-client RBS token/result references | Execution Contracts / Execution Services | Keep real public type use in the graph; do not invent a domain facade for a token |
+| LLM, VectorStore, Embeddings and Storage AsyncClients | Contracts + TaskResult + Runtime/pools | Intended bridge; keep specialized submission, token and admission rules |
+| Agent ExecutionCoordinator / MultiAgent binding | Concurrency operation binding | Own cancellation/deadline scope across an operation; generic Blocking is not equivalent |
+| Agent and Workflow runners / execution registries | Runtime, FSM session and control delivery | Framework connection and single-writer ownership; retain these explicit dependencies |
+| Engine worker pool | TaskResult and execution errors | Produces shared results; the service/Engine relationship is not acyclic |
+
+The full dependency graph still includes references through shared error classes,
+markers and RBS. Moving their source owners changes the interpretation of the
+old Engine fan-in; it does not remove their actual use. The architecture gate
+enforces Contracts-to-Contracts/Common only and rejects domain/backend/client
+dependencies from Services or Engine. Layout is independent of those rules.
+
+See [ADR-063](../decisions/063-execution-contracts-and-services.md) for the source
+layout, behavior change and compatibility boundary.

data/docs/architecture/execution-metadata-and-values.md

@@ -1,5 +1,11 @@
 # Shared execution metadata and value conversion
 
+> 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`.
+
+
 Refactor 38 addresses the remaining R03 and R11 responsibilities against core
 `e7e6618493df03c2eb386d78a9303796e1e13cdc`. The candidate must be applied and
 verified before those items are closed. Tool restoration itself was completed

data/docs/architecture/multi-agent-handoff.md

@@ -24,14 +24,14 @@ Normative Handoff intent is
 with the Runner ownership amendment in
 [ADR-034](../decisions/034-handoff-runner-coordination-ownership.md).
 
-The Runner owns the cross-Agent turn. Handoff edges, Policy, Context and
-Agent terminal/persistence integration remain in Agent during this first
-migration step. See the [Runner migration](../migrations/handoff-runner-multi-agent.md).
+MultiAgent owns the cross-Agent turn, Handoff edges, Policy, routing and reservations.
+Agent owns generic control requests, finalized Context projection and its own
+execution commits. See [r8 unit 4](r8-unit4.md).
 
 ## 2. Public API
 
 ```ruby
-handoff = Phronomy::Agent::Handoff.new(
+handoff = Phronomy::MultiAgent::Handoff.new(
   source_agent: triage,
   target_agent: billing,
   description: "Transfer billing responsibility",
@@ -40,6 +40,7 @@ handoff = Phronomy::Agent::Handoff.new(
 
 runner = Phronomy::MultiAgent::HandoffRunner.new(
   main_agent: triage,
+  persistence: stores.multi_agent,
   handoffs: [handoff]
 )
 
@@ -56,7 +57,7 @@ schemas. The generated Tool name is private transport encoding, not Handoff
 identity or public semantic contract.
 
 Phronomy intercepts the Provider Tool Call into a typed private
-`HandoffRequest`. It does not execute an ordinary `ToolInvocation` or emit a
+`Agent::ControlRequest`. It does not execute an ordinary `ToolInvocation` or emit a
 sentinel Tool result.
 
 ## 4. Handoff Policy

data/docs/architecture/persistence.md

@@ -9,9 +9,11 @@
 
 ## 1. Durable boundary
 
-`Phronomy::Persistence` is the domain-facing service for the single durable-state
-transaction domain used by Agents, Teams, and Workflows. It composes a
-`Storage::Backend`; storage implementations do not inherit the domain service.
+`Phronomy::Persistence` owns domain-neutral atomic scopes over a `Storage::Backend`.
+`Agent::Store` and `MultiAgent::Store` own domain operations and result queries;
+Workflow consumes its checkpoint repository directly. These roles share a
+coordinator when operations must commit together. Storage implementations do not
+inherit a domain service. See [r8 unit 3](r8-unit3.md) for construction and migration.
 
 The `storage/` directory owns record carriers, portable errors, repository views,
 and the Backend contract. `storage/backends/` owns physical storage implementations.
@@ -20,13 +22,29 @@ directories own their domain codecs and repositories. Agent and Team result
 queries live with those domains. `storage/record_codec.rb` contains only shared
 record-envelope and scalar validation; it does not select a domain schema.
 `persistence_composition/` assembles the domain repositories over one raw view.
-The public `Phronomy::Persistence` entry point delegates to those components and
-retains its observation-thread guard.
-The root and transaction paths use the same facade construction, with transaction
-facades bound to the raw backend view for that transaction.
+`content_store/` is a content management service over Storage, not a physical
+backend family. Its Base shares text/JSON conversion with StoredContents and
+the Persistence content facade. StoredContents generates content IDs, verifies
+digest identity and uses the injected view's Blobs. Its StorageSchema belongs
+to this service. Storage owns byte immutability, transactions and physical I/O.
+The service and its schema live together; there is no `content_store/backends/`
+directory or backend-selection API. See [ADR-062](../decisions/062-content-store-service.md).
+Domain stores receive their record adapters from `PersistenceComposition` and
+retain their observation-thread guards. The common Persistence does not select
+domains, assemble repositories, or delegate domain result queries. Domain-only
+record protocols bind to the exact scope when participating; there is no shared
+all-domain repository facade.
 See [ADR-032](../decisions/032-storage-backend-composition.md) and
 [ADR-033](../decisions/033-domain-persistence-ownership.md).
 
+`persistence/errors.rb` owns the shared domain-facing failure classes. Repository
+boundaries translate four known raw Storage categories to Persistence categories,
+retaining the original exception as `cause`. Upper domain state contradictions
+use `Persistence::StateConflictError < Persistence::ConflictError`. Unknown and
+commit-outcome-uncertain exceptions are not reclassified. Backend contracts never
+depend on these upper errors. See [ADR-061](../decisions/061-persistence-failure-contracts.md)
+and the [rescue-clause migration](../migrations/persistence-failure-contracts.md).
+
 Shared value copying belongs to `Values::Immutable` in `values/`. Agent records,
 Team records, Recovery classifications, and Persistence result views use this
 internal helper without borrowing an Agent implementation. It copies and freezes
@@ -41,7 +59,7 @@ does not change record formats, transaction ownership, or recovery guarantees.
 | `agents` | AgentRoot |
 | `journals` | Append-only Agent journal |
 | `executions` | AgentExecution and owned child coordination |
-| `workflow_states` | Workflow snapshots |
+| Workflow checkpoint repository | Workflow snapshots |
 | `handoff_states` | Active responsibility and exact Target reservation |
 | `teams` | TeamRoot |
 | `team_executions` | Team tasks, assignments and outcomes |
@@ -93,7 +111,7 @@ Defined semantic durable transitions are atomic according to the Persistence
 transaction contract and conforming backend.
 
 Revision/watermark/CAS checks reject stale durable transitions with
-`Storage::ConflictError` rather than silently merging/reloading competing
+`Persistence::ConflictError` rather than silently merging/reloading competing
 state.
 
 Conflict detection is not competing-execution exclusion and cannot undo an

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.