phronomy 0.27.0 → 0.29.0

data/docs/architecture/r8-unit19.md

@@ -0,0 +1,61 @@
+# R8 unit19: Engine resource lifetime
+
+## Confirmed failures
+
+Overlapping first default-pool lookups could construct two pools and retain only
+one. A pool lookup that passed Runtime's state check could also create a pool
+after shutdown had captured its resource list. Both cases left live workers
+outside the claimed completed cleanup.
+
+OffloadPool previously returned after each worker join timeout without reporting
+whether workers remained. Runtime interpreted the absence of an exception as
+successful cleanup. A real blocked worker was still active after the default
+30-second join while Runtime reported terminated, clean and complete.
+
+## Ownership
+
+PoolRegistry owns pool creation, registration and closure of that registration.
+The same mutex protects default and named pool construction and the transition
+to a closed registry. Runtime still admits resources during its draining phase
+for previously accepted continuations. PoolRegistry rejects requests after the
+shutdown resource set is captured, including lookups that passed an earlier
+Runtime check.
+
+OffloadPool owns worker admission and physical worker lifetime. begin_shutdown
+closes admission without waiting and preserves queue draining. shutdown waits
+using one monotonic deadline; its existing self return is preserved. terminated?
+reports that admission is closed and every owned worker has actually exited.
+TaskResult cancellation or timeout is not proof of physical worker termination.
+
+PoolRegistry first closes all pools, then waits outside its registration lock.
+Every pool uses the same absolute deadline. Cleanup continues for the remaining
+pools after an individual error; the first error is propagated after those
+attempts. Runtime still attempts timer cleanup in ensure.
+
+Runtime owns the aggregate decision. Its existing stop-phase deadline is shared
+by EventLoop and pool joins. Cleanup is incomplete while any worker remains;
+domain finalization and default-Runtime replacement remain blocked. Runtime's
+existing cached-result behavior is unchanged: an incomplete result is not later
+promoted to complete by calling shutdown again.
+
+## Scope
+
+This is an Engine lifecycle correctness fix, not only a file relocation. Pool
+shutdown no longer silently reports completed resource cleanup when workers
+remain. The pool waiting budget is shared instead of being restarted per worker
+or per pool. No worker is forcibly interrupted, and queued accepted work still
+drains. Applications retain responsibility for bounded synchronous operations
+and native I/O timeouts.
+
+Agent cancellation persistence, MultiAgent parent/child policy, Workflow
+persistence decisions, C13 result/subscription contracts, settings providers and
+durable formats are unchanged. No new domain Contract or notification mechanism
+is introduced. E03 passive metrics collection remains a separate follow-up.
+
+## Verification
+
+Queue-controlled tests reproduce overlapping first pool creation and lookups
+delayed until after shutdown. Real worker gates verify bounded shutdown,
+incomplete results, retained Runtime, withheld finalization and the difference
+between logical cancellation and physical completion. Additional cases preserve
+draining continuations and ensure all resources receive cleanup attempts.

data/docs/architecture/r8-unit2.md

@@ -0,0 +1,55 @@
+# r8 unit 2：親の予約確認とAgent受付
+
+この単位はP02／P03の受付境界を実装する。基準はcore `16e6fcb2dd49836735598525114abfc256d0773e`。r8全体やPersistenceの全面整理の完了ではない。
+
+## 責務と操作
+
+| 担当 | 公開操作・共通規則 | 依存と内部実装 |
+|---|---|---|
+| 共通Persistence | `atomic`、`Transaction#participate`、`committed?`。同じPersistence、同期thread、有効scope、savepoint、commit応答を検証 | Storageの公開transaction・scope規則を利用。Agent／Team／Workflowや構成担当を選ばない |
+| Agent | `Admission#accept_in`。入力記録・実行ID・Agentの受付とrevision更新を同一scopeへ保存 | Agentの保存担当を使用。親のkind・Team割当・subagent snapshot・Handoff予約を解釈しない |
+| MultiAgent | `ReservedChildAdmission#admit`。親の取消・slot・子IDを検証し、Agent受付を同じscopeへ参加させる | 自分の保存担当が予約の根拠を読み、必要なguardを取得する |
+| 保存担当 | `Agent::Persistence::Admission`、`MultiAgent::Persistence::Reservation` | raw Storage viewはこの境界で使用。ドメイン操作へraw viewを渡さない |
+
+AgentのRuntime admission取得、FSM開始、live状態の反映は既存のExecutionCoordinatorが引き続き所有する。新しいAdmissionはその短い保存フェーズだけであり、Agent実行全体を親のDB transactionへ入れない。通常のアプリは新しい参加クラスを実装・生成する必要がない。
+
+`phronomy_admission` は内部の現在の配線であり、Procやオブジェクトを保存しない。永続化するのは従来の相関情報と親子IDだけ。Team／subagent／Handoffの開始・再開担当が現在の参加者を渡す。保存済み実行への再接続はExactExecutionの同一ID照合と復旧規則を維持する。
+
+## 保存順序と失敗
+
+1. Agentが既存のRuntime受付を取得し、同期workerで保存操作を開始する。
+2. MultiAgentが短い`atomic` scopeを開き、親のguardを取得してから予約を読み直す。
+3. 親の取消・割当・子の識別子を検証する。Agentは同じscopeで入力内容・AgentExecution・AgentRootを保存する。
+4. commit応答が成功した後に、Agent実行担当だけが受付結果を取得し、準備・FSM・live反映を進める。
+
+参加操作の戻り値はcommit成功を意味しない。`accept_in`はnilを返し、Agent内部の`result`は外側のcommitまで利用できない。二重参加、別Persistence、別thread、終了後scopeは拒否する。同じbackendを包む別Persistenceも同一scopeと扱わない。raw backend transactionの中から新しくcommit所有者を名乗ることも拒否する。
+
+明示的な入れ子はsavepointとして動く。内側が成功しても外側がrollbackした場合は未成立。参加処理中の例外を内側で捕捉しても、失敗したscopeの先行変更をcommitできない。LLM、Tool、scheduler、外部callback、非同期待機を参加処理へ入れない。
+
+Storageのscope違反は`Persistence::TransactionError`へcause・backtraceを保持して変換する。この名前の変更は、保存成否が既知であるとの宣言ではない。IOError等の成否不明な保存失敗は変換・自動retryせず、既存のAgent復旧規則へ渡す。今回、一般化した保存成否照合APIは追加していない。
+
+## 取消との競合
+
+TeamはTeamRoot、subagentは親AgentRoot、Handoffはrouting recordをguardとする。PostgreSQLではそのguardの行ロックと既存の条件付き更新によって、取消・変更と子受付を順序付ける。子受付側の通常readだけでは、この保証は成立しなかった。
+
+Handoff取消側は最初に子の状態を観測し、未完了／不在ならroutingをロックして**子の状態を再取得**する。待機中に子受付がcommitした場合、古い「不在」の判断を捨て、受付済みの子へ公開取消を送る。既に終端の実行への取消は従来どおり結果参照として扱う。
+
+InMemoryは共有Monitor、SQLiteはtransactionと書込競合検出、PostgreSQLは行ロックを使用する。SQLiteで競合したtransactionは成功とみなさず、backendの失敗を扱う。分散leaseや外部副作用のexactly-onceは追加しない。実PostgreSQLでの待機順序はexamplesの新しい3件の並行テストで確認する対象であり、InMemory／SQLiteの成功から推定して済ませない。
+
+## API・ファイル変更
+
+- Agent::InitialPreparationの`build_admitted_execution`と3種の親検証・kind分岐を削除。Agent自身の受付共通処理とMultiAgentの予約判断へ分離した。
+- 共通の参加frameworkを`persistence/transaction.rb`、Agent受付を`agent/admission.rb`、保存接続を既存の各domainの`persistence/`へ置いた。新しいディレクトリや独立Contractは増やしていない。
+- Storage SPIに同期contextの`transaction_open?`を追加。Storage::Backendの継承実装には共通実装が提供される。継承しない独自SPI実装はこの操作も提供する必要がある。RBS・SPI snapshot・duck-typed backendの検証を更新した。
+- Persistenceの既知scope失敗の公開型を`Persistence::TransactionError`へ統一し、旧Storage例外のaliasは設けない。Storageを直接使う処理では従来のStorage例外を使用する。
+- RBSはsigに配置し、参加者factory、Agent受付、MultiAgentの依存を宣言する。動的な`phronomy_admission`注入も本書と利用箇所で追跡する。
+- 依存解析のExecution境界規則を図のrevision表示名から分離した。unit名の更新で同期backendからExecutionへの禁止規則が解除されないことを回帰テストする。
+- 保存recordの形式、ID、revision規則は変更していない。データ移行は不要。
+
+## 残る課題
+
+`Persistence#transaction`とdomain repositoryの一括窓口は現行利用箇所が残るため、この単位では全面削除していない。互換維持のために新しい旧名aliasを追加したものではないが、P01／DP04の完了条件は未達である。次にdomain照会・保存構成を移し、不要な窓口を利用側と同時に削除する。
+
+MultiAgentの保存担当にはAgentのexecution／Handoff repositoryへの参照が残る。予約検証の所有者は整理したが、親子の公開投影・認可照会・結果取込まで隠蔽したとは扱わない。P04／F02／F03の残課題として、Agentが公開する操作と、MultiAgentが所有すべき保存形式を確定する。一般的なmetadata getterを足すだけの解決にはしない。
+
+Agent／TeamのFSM接続、Workflowのdurableな子連携（P05）、複数記録の保存成否照合（P06）、残りの配置整理、155組・393件の意味的再判定も残る。今回のSVGは実装候補を描き、全体の循環解消を示す構想図にはしない。

data/docs/architecture/r8-unit20.md

@@ -0,0 +1,51 @@
+# R8 unit20: Passive Engine observation
+
+## Problem
+
+Metrics.snapshot previously called Runtime.instance, Runtime#offload and
+Runtime#event_loop. A cold snapshot constructed the default Runtime, started
+default-pool workers and started the EventLoop. Looking at an existing Runtime
+could initialize its other resources. The same calls rejected observation after
+shutdown, precisely when diagnostics were useful. Diagnostics.snapshot and dump
+inherited these effects through Metrics.snapshot.
+
+## Responsibility
+
+Runtime retains ownership of its singleton and resource references. PoolRegistry
+retains ownership of its default pool. Both provide internal lookup operations
+using their existing mutexes, without construction or admission checks. Runtime's
+existing EventLoop lookup already provides the same behavior. These lookups can
+observe retained resources after shutdown without reopening them.
+
+Metrics samples the returned resources and formats the existing ten numeric
+fields. It does not inspect instance variables, decide resource initialization,
+read configuration as a substitute for measurements, or cache Runtime references.
+The test-only singleton lookup delegates to the internal lookup; production code
+does not call a test helper. RBS describes the optional resource references.
+
+## Behavior and scope
+
+Missing resources contribute zero. An uninitialized default pool therefore has
+size zero even if configuration would allocate ten workers on first use. For an
+existing pool, size continues to describe configured capacity, including after
+shutdown; it is not a count of living workers. Named pools remain outside these
+default-pool metrics. A subsequent snapshot follows the current default Runtime,
+so a reset neither recreates it nor keeps stale metrics in a cache.
+
+Counters remain independent observations. Concurrent activity or Runtime reset
+can occur during a snapshot; no globally atomic observation or lifecycle barrier
+is promised. Resource references are obtained under their owners' existing locks
+and metrics are read after those lookup locks are released. No new lock ordering,
+polling thread, subscription, observer registry or notification mechanism is added.
+
+Unit19 pool creation and shutdown rules, cancellation, domain finalization,
+shutdown deadlines and cached shutdown results are unchanged. Contract/domain
+code and dependencies are unchanged. All product-code changes stay in Engine.
+
+## Verification
+
+A fresh-process test exercises all three observation entry points and checks that
+no Runtime or thread is created. Tests cover partial initialization, named pools,
+real active/queued/abandoned worker metrics, EventLoop backlog and lag, draining,
+stopping, completed and incomplete shutdown, and default Runtime replacement.
+Queue barriers control concurrent boundaries without relying on chance schedules.

data/docs/architecture/r8-unit21.md

@@ -0,0 +1,79 @@
+# r8 unit21: Tool and Tracing settings ownership
+
+This responsibility-only refactor is based on applied unit20, commit
+`bda5da03da5a4da33041953cf0eebaa32de7bb81` (tree
+`dc601f86825116b34ff294200815809ee9e0ea7a`). It addresses B10 from the
+Contract review. It is not a new execution feature or a unit20 regression fix.
+
+## Ownership
+
+| Owner | Responsibility |
+| --- | --- |
+| C06 Tool | Own the default result-length value and the existing truncation rules |
+| C15 Tracing | Own tracer access, the recording option and the existing observation/redaction rules |
+| C05 Context | Obtain its default tracer through C15 at Assembly construction; honor explicit injection |
+| Application composition | Select values and concrete tracers, expose the existing Configuration facade, bind lazy accessors |
+| Neutral RuntimeSettings | Retain logger and execution resource sizes/time thresholds |
+
+Tool::Settings contains one optional max_result_size value. Tracing::Settings
+contains tracer and trace_pii. These private value containers have no settings
+hierarchy, backend selection, notification service or execution resources.
+Composition supplies them through lazy providers, following the existing Agent
+and Workflow pattern. No Contract receives the whole application Configuration.
+No new logical Contract is introduced merely because values are shared.
+
+The public tool_result_max_size, tracer and trace_pii accessors keep their names,
+defaults, writers and return values. Application choices remain application
+choices. Tool truncation and Tracing redaction already belonged to their domains;
+their algorithms are unchanged. Logger access remains neutral and is not moved
+simply because Tracing also uses it for diagnostic messages.
+
+This amends ADR-060's earlier grouping of tracer and recording options with
+neutral runtime settings. The static graph treated that container as common;
+its lack of reverse references did not prove that every field belonged there.
+
+## Preserve lifecycle and read positions
+
+- Binding providers does not evaluate global configuration or start Runtime.
+- Tool reads its default at the existing result-processing site, after
+  synchronous execution or successful asynchronous completion. An explicit
+  class limit keeps priority and bypasses the default read. Nil and zero retain
+  their existing meanings. Result transformations retain their order and count.
+- Automatic tracing reads settings at span start and retains the same tracer
+  and recording flag in its existing handle until finish. A configuration reset
+  during execution does not transfer an open span to a different tracer.
+- Observation keeps its existing reads before entering the application block;
+  it does not adopt a new snapshot policy or re-read settings after the block.
+- Context::Assembly keeps its constructor-time tracer. Explicit injection,
+  including explicit nil, does not resolve the default provider.
+- Configuration copies duplicate the value containers and preserve injected
+  tracer/logger identities. Nested scopes, exception restoration and reset keep
+  the previous behavior. A read resolves the current container without caching.
+
+There is no change notification, polling, version counter, cache, live resource
+resizing or new thread-local configuration behavior. This does not add a
+guarantee of atomic reconfiguration across several independent reads.
+
+## Regression boundaries
+
+Public behavior tests run unchanged on unit20 and unit21. They cover late Tool
+limits for sync/cooperative/offloaded/deferred operations, transformation order
+and repetition, physical completion, reset, nested scopes and tracer identity.
+Tracing checks cover both recording policies, redaction, errors and open spans;
+Context checks cover constructor timing and explicit injection.
+
+Separate ownership tests inject domain values without the application facade
+or neutral settings. Isolated loading verifies provider laziness and prevents
+loading a concrete backend or Runtime. RBS assigns the internal declarations to
+their actual owners. AST gates extend the application-configuration prohibition
+to Tool, Tracing and Context, reject domain fields in neutral RuntimeSettings,
+and reject direct or literal-reflective reads through its old accessors.
+
+These are targeted regression guards. They do not prove arbitrary dynamic Ruby
+dependencies. Full suite, integration, existing privacy tests, examples offline
+verification and Ruby/RBS architecture analysis remain package validation gates.
+The complete source/tree and validation results are recorded in the package.
+
+Unit19/20 Engine lifecycle and passive metrics behavior remain unchanged.
+F01 durable Workflow children remain separate feature work. There is no stored
+data migration, public operation change or source change to examples.

data/docs/architecture/r8-unit22.md

@@ -0,0 +1,74 @@
+# r8 unit22: MCP connection lifecycle
+
+This change is based on applied unit21, commit
+`4525e71ca808acac9eb0302a59c32f00478a7782` (tree
+`957baf18c23ce5659c11454f3a89e893c07b2138`). It corrects two concrete MCP
+lifecycle defects and removes an unnecessary application-composition reference.
+It is not a new Contract or an Execution/Engine refactor.
+
+## Ownership
+
+| Owner | Responsibility |
+| --- | --- |
+| MCP Tool implementation | Translate SDK cancellation and results, own the client/transport, delimit one SDK call's notification lifetime |
+| Existing Execution ResultSubscriptions | Register and remove explicit-cancellation callbacks |
+| Existing Execution/Engine | Admit and execute cleanup work, reject submissions after shutdown, drain accepted work |
+| Neutral RuntimeSettings | Supply the currently configured common logger |
+
+The production change is confined to `lib/phronomy/tools/mcp.rb`. Execution,
+Engine, Tool Contract, runtime composition, public signatures and storage
+formats are unchanged.
+
+## Cancellation bridge lifetime
+
+Previously each SDK call registered a callback directly on its supplied
+CancellationToken and retained it until that token was cancelled or collected.
+Completed and failed calls therefore accumulated callbacks when a caller reused
+a token. A later cancellation also touched obsolete MCP cancellation handles.
+
+Each call now owns an existing ResultSubscriptions collection, registers its
+bridge with explicit_cancellation, and closes the collection in ensure. This
+also covers SDK errors, malformed responses and cleanup failures. Other
+subscribers on the same token are preserved.
+
+The lifetime is the concrete SDK invocation, not its caller-facing TaskResult.
+If OffloadPool settles a timeout while SDK work is still running, a subsequent
+explicit cancellation must still reach that work. No timer, deadline promotion,
+polling thread or TaskResult completion callback is introduced by the bridge.
+
+ResultSubscriptions.close does not revoke a callback already taken by a
+concurrent cancel!. Such a callback can finish after the SDK call returns. It
+only captures that call's MCP cancellation handle, whose cancellation is
+idempotent; it does not look up the next client or cancel a replacement call.
+This preserves the existing Execution notification semantics.
+
+## Cleanup rejection at Runtime shutdown
+
+After SDK cancellation the MCP instance detaches the old client before it can
+be reused. Normally its transport is closed on the named Runtime cleanup pool.
+Previously the synchronous fallback handled queue saturation and a stopped
+pool, but not RuntimeShutdownError raised before pool acquisition. In that
+case close was skipped and the shutdown error replaced the cancellation result.
+
+MCP now applies its existing synchronous close fallback to RuntimeShutdownError
+too. It does not reopen Runtime, create another worker, retry the Tool call or
+relax Engine admission. Accepted cleanup remains owned and drained by Runtime.
+MCP attempts to close a rejected transport and preserves the existing best-effort
+close behavior if the SDK's close itself raises.
+
+## Logging and validation
+
+MCP warning output reads RuntimeSettings.current.logger once per warning and
+retains the existing stderr fallback. It no longer reaches the application
+Configuration facade just to obtain this common value. Logger choice is still
+made by application configuration; no new setting or provider is introduced.
+
+Focused regressions cover repeated success, SDK/response failures, explicit and
+already-delivered cancellation, timeout before physical completion, cancellation
+racing completion, accepted cleanup, stopped Runtime, rejected submission,
+failing close and both logger paths. Concurrency tests use barriers and an
+injected monotonic clock rather than timing-dependent sleeps.
+
+These are lifecycle corrections, not merely file moves. They require no data
+migration or examples source change. Deferred features, including durable
+Workflow children, remain outside this change.

data/docs/architecture/r8-unit23.md

@@ -0,0 +1,81 @@
+# r8 unit23: concrete consumer composition
+
+This change is based on applied unit22, commit
+`17cf02eb1ec0ec534b3dd8e1e64c75e13c961cfc` (tree
+`dc591b3d8dfb1edace4f98e68f5e505a6c457f58`). It normalizes two concrete
+composition paths identified as NC02 and NC08 in the target diagrams.
+These were responsibility improvements, not demonstrated runtime failures.
+
+## Agent Tool
+
+The synchronous implementation previously called the application convenience
+API `Agent.run_once`, which selected an ephemeral store through
+`PersistenceComposition.agent`. Its asynchronous implementation already obtained
+the same default through the boot-supplied `Agent::DefaultPersistence` factory.
+
+Both paths now obtain a fresh store from that existing factory. The synchronous
+path uses public Agent creation and invocation, preserving the explicit
+`context: nil`, `knowledge: []`, and `on_event: nil` creation arguments that
+`run_once` supplied. It forwards the same invocation options and converts the
+output to a String as before. The asynchronous implementation is unchanged.
+
+Each call still creates its own Agent and store, even when an application-level
+Agent store is configured. No Agent or store is cached. Tool definitions and
+instances do not acquire persistence. Cancellation propagation, asynchronous
+config token priority, Tool validation, result transforms and recovery errors
+retain their existing behavior.
+
+`Agent.run_once` remains the public application convenience API. It continues to
+own explicit composition; only the concrete Tool stops depending on that facade.
+Calling a public composition API is not inherently invalid. Here the narrower
+existing factory lets both Tool paths follow the same ownership boundary.
+
+## LlmJudge
+
+The scorer owns prompt construction, the public LLM Request, score parsing and
+clamping, and its warning/raise policy. It no longer selects the configured
+adapter or constructs `LLMAdapter::AsyncClient` inside `score`.
+
+`runtime_composition/evaluation_defaults.rb` supplies a single factory during
+normal application loading. The factory selects the currently configured
+adapter and constructs the client. Installation creates no Configuration,
+client or Runtime. It uses a private, one-time binding in the existing scorer
+class, not a new Contract, module registry or application extension API.
+
+Each score invokes the factory after prompt and Request preparation, at the
+same point as the previous client construction. The adapter is therefore read
+again after configuration updates, reset and scoped restoration. Neither the
+adapter nor the client is cached by the scorer. The factory does not move client
+construction onto a worker; the existing AsyncClient still offloads the whole
+backend operation. No polling, notification, retry or scheduling mechanism is
+introduced.
+
+The constructor signature is unchanged. Subclasses inherit the same default
+binding. Client construction/admission/provider failures remain within the
+existing `raise_on_error` policy. Normal and eager loading remain resource-free
+and do not load RSpec. The scorer can also be tested with an explicitly bound
+client and its public Request dependency without loading composition or Execution.
+
+## Boundaries and validation
+
+| Owner | Responsibility |
+| --- | --- |
+| Concrete Agent Tool | Per-call Agent creation, invocation, cancellation forwarding and output conversion |
+| Existing Agent default factory | Obtain a fresh store from the supplied boot binding |
+| LlmJudge | Prompt, Request, score interpretation and scoring failure policy |
+| Runtime composition | Select the configured LLM adapter and build its AsyncClient |
+| Existing Execution and Engine | Submission, result completion, waiting and resource ownership |
+
+Production changes are limited to the two consumers, the new composition file
+and its explicit loader wiring. Contract source, Engine, Execution, persistence
+formats, RBS and public API snapshots are unchanged. Examples need no source
+change. The target diagrams remain at the applied unit22 baseline until this
+candidate is applied; their two concrete composition items are addressed here.
+
+Focused tests cover fresh construction and forwarding, default binding isolation,
+score-time configuration changes, scoped restoration/reset, request/client order,
+worker execution, failure behavior, inheritance and resource-free boot.
+The targeted AST gate prevents either consumer from reintroducing these
+composition dependencies; application composition itself remains permitted to
+construct the client and public convenience API. Static graphs do not certify
+all dynamically injected implementations or external providers.

data/docs/architecture/r8-unit3.md

@@ -0,0 +1,130 @@
+# r8 unit 3: Persistence ownership and Team/Agent operations
+
+This is a candidate based on core `a82974a7fd2360a13af71831a0c3ddc75942fae3`
+and examples `70b7244c9f6542062849869a7106c5a627868a80`. It implements P01 and
+removes concrete adapter selection from the unit 2 admission framework. P04 is
+partially implemented for Team authorization and scheduling. It is not completion
+of the full contract architecture.
+
+## Ownership and public application construction
+
+```ruby
+stores = Phronomy::PersistenceComposition.in_memory
+# Or: PersistenceComposition.build(backend: configured_storage_backend)
+
+Phronomy.configure do |config|
+  config.agent_store = stores.agent
+  config.team_store = stores.team
+  config.workflow_store = stores.workflow
+end
+
+agent = MyAgent.create(persistence: stores.agent)
+team = MyTeam.create(persistence: stores.team)
+workflow = Phronomy::Workflow.define(MyContext, persistence: stores.workflow) do
+  # Workflow definition
+end
+
+agent_result = stores.agent.result(agent_execution_id)
+team_result = stores.team.result(team_execution_id)
+```
+
+For an isolated Agent, `PersistenceComposition.agent(backend: optional_backend)`
+constructs only the Agent/content components. Ordinary Agent defaults use this
+factory. A composition result is a construction bundle, not a query or execution
+service; pass only the relevant component to each consumer.
+
+| Owner | Operation / responsibility |
+|---|---|
+| `Persistence` | `atomic`, scope validity, participation and outer commit |
+| `Agent::Store` | Agent result/list/presence/authorization operations, injected Agent record protocol |
+| `MultiAgent::Store` | Team result/list operations, injected Team record protocol and Agent public operations |
+| Workflow checkpoint port | `load`, `save`, `delete` with instance ID and expected revision |
+| Domain `persistence/` implementations | physical resource schema, records, codecs and guards |
+| `PersistenceComposition` | selects backend and adapters, validates schemas and binds components |
+
+The stores are roles inside the existing domain framework, not new independent
+contracts. Logical acceptance and state-transition decisions remain in Admission,
+TeamCoordinator, and the owning domain operations. Record accessors on stores are
+internal protocols for their own domain, not cross-domain application APIs.
+Common Persistence neither knows these types nor imports composition.
+
+## Atomic participation remains unchanged
+
+The parent reservation is committed first. At child acceptance, the parent guard
+is acquired before reading the current reservation, then Agent input/execution
+and root revision are written in that same scope. The parent's domain owns its
+reservation/cancellation/identity checks. Agent does not interpret parent schemas.
+Only after the outer commit does Agent expose its accepted state and start work.
+
+Domain adapters are injected at construction and receive the exact scope's view.
+They never select another connection or commit independently. The coordinator
+identity, same-thread lifetime, savepoint behavior, conflict classification,
+rollback, and uncertain-commit behavior remain in force. LLM/Tool work and async
+waiting remain outside these short transactions. Wrapping ordinary async invoke
+in an application transaction is not a newly supported API.
+
+## Team uses Agent authorization, not execution metadata
+
+`Agent::Store#authorized_operations(scope, agent_id:, execution_id:,
+invocation_id:, name:, arguments:, names:)` validates the exact requested call
+against one persisted execution snapshot in the caller's scope. It checks the
+Agent owner, invocation identity, authorization state, name, arguments and
+requested operation family. It returns immutable `AuthorizedOperation` values
+with only `invocation_id`, `name`, and `arguments`, in Provider order.
+
+Team applies these operations and owns its durable operation-result ledger.
+A committed replay returns that ledger result without reapplying the batch.
+`finalize` cannot overtake earlier authorized `enqueue_task` calls. A mismatch
+raises `Persistence::StateConflictError` before Team's changes commit.
+`Agent::Store#exist?` reports authoritative absence; failed reads still raise.
+
+Team scheduling now uses its own retained assignment count. The default chooses
+the worker with the fewest assignments, breaking ties in worker order. Custom
+schedulers receive `WorkerState#assignment_count` instead of `transcript_size`.
+The count is derived from existing assignments, including failures; there is no
+extra mutable counter and no Agent journal read. This deliberately changes the
+default balancing metric. It does not estimate tokens, duration or resource load.
+
+## Removed APIs and directories
+
+- `Persistence.in_memory`, common `transaction`, `capabilities`, repository
+  accessors, result/list queries and Agent watermark facade methods are removed.
+  `Persistence.new(backend:)` constructs only the neutral coordinator.
+- Domain result queries are `stores.agent.result` / `.runs` and
+  `stores.team.result` / `.runs`; Handoff observation remains on the Agent store
+  pending the ownership work below.
+- `Configuration#persistence` is replaced by `agent_store`, `team_store`, and
+  `workflow_store`; explicit `persistence:` arguments accept the relevant port.
+- The all-domain `PersistenceComposition::Repositories` and the fixed admission
+  adapter classes are deleted. There are no legacy API aliases.
+- `persistence/api/` and the six-file `persistence/contract/` error subdivision
+  are removed. Shared failures are in `persistence/errors.rb`.
+- Team/Workflow schema declarations are consolidated into their existing domain
+  `persistence/` directories; their separate `storage_contract/` directories and
+  root schema constants are removed.
+
+Storage SPI 2 and physical SQL tables/indexes are unchanged. Existing Agent,
+Handoff and Workflow record codecs are unchanged. New Team worker entries omit
+`transcript_size`; older entries can still be decoded and the unused field is
+ignored by scheduling. Assignment history remains the authority. This does not
+add an API compatibility wrapper or change saved operation results.
+
+## Remaining work (explicitly not claimed complete)
+
+1. Subagent and Handoff still interpret Agent execution/routing records and
+   coordination data. Storage adapter class selection has been removed, but
+   renaming raw record access does not make it a proper public domain operation.
+   Resolve logical ownership, cancellation, responsibility transfer and restart
+   together before changing these paths; existing atomic transfer is preserved.
+2. Orchestrator's preparation/resume integration still accesses Agent-owned
+   execution and context details. Team's new operation projection is not a
+   general solution to those ownership questions.
+3. Domain-to-FSM connections, durable Workflow child protocols, multi-record
+   uncertain-commit evidence and the remaining semantic dependency review are
+   outside this implementation unit. Workflow FINISH translation already exists.
+4. PostgreSQL concurrency verification for this candidate requires the matching
+   core/examples branch or local PostgreSQL setup. Unit 2 CI evidence is not
+   evidence that this candidate has passed PostgreSQL.
+
+The source SVG and full Ruby/RBS evidence report remaining dependencies. Visual
+suppression of shared common-value arrows does not remove graph evidence.

data/docs/architecture/r8-unit4.md

@@ -0,0 +1,79 @@
+# r8 unit 4: Agent execution and MultiAgent responsibility
+
+Core baseline: `3c5fddcae31cc98f8e081feae9b955cf536e5834`.
+Examples baseline: `0370d09fb1608b9596e1803275f713b1a204af26`.
+The foundation mapping dated 2026-09-30 and its target/concept diagrams remain the
+refactoring goal. This change implements the C01/C04 boundary; it does not claim
+that the whole existing implementation already matches the target DAG.
+
+| Responsibility | Owner and current entry point |
+|---|---|
+| Exact execution identity, admission and observation | Agent `ReservedExecution`, `start_reserved_async`, `resume_async`, `cancel_async`, `Store#observe_execution` |
+| Finalized input, groups and provenance | Agent `ControlRequest`, `TransferContext`, `TransferProjection` with Context assembly |
+| Selection policy, Source/Target mapping and routing | MultiAgent `HandoffPolicy`, capability binding, `HandoffRunner`, `HandoffParticipant` |
+| Static subagent slot, definition, input, inherited knowledge and import progress | MultiAgent `DurableSubagentCoordinator`; immutable content snapshot |
+| Execution/Root/journal mutation and publication authority | Agent `ExecutionChange` and `ExecutionOutcomeCommitter` |
+| Whole-Agent retention and durable cancellation intent | Agent public operations; Agent-owned record resources |
+| History removal and release of its own holds | MultiAgent `Store#forget_subagents`, `Store#forget_handoff` |
+| Physical record adapters and schema | Each domain's Persistence implementation; composition assembles them |
+| Offline old-format conversion | `PersistenceComposition::Unit4Migration`; examples SQL runner |
+
+Agent interprets neither child states nor routing phases. MultiAgent uses public
+Agent values and operations; it does not read AgentExecution, raw metadata,
+journals, ContextImporter values or a private event-listener getter. Child results
+are observed from their authoritative execution, never mirrored as mutable child
+statuses in the parent snapshot. IDs for new slots are derived from canonical
+parent Agent/execution/slot identity. Migration preserves existing IDs.
+
+## Commit participant contract
+
+A current, synchronous participant declares a `binding` key/version and implements
+`commit`, `guard_change`, and `change_evidence`. `ExecutionChange` exposes semantic
+inputs only. In one outer `Persistence#atomic` scope the participant:
+
+1. Locks routing/Team guards where needed, then Agent roots in lexical ID order.
+2. Calls `change.prepare_in(scope)` before its own writes. This captures complete
+   pre-state, including cancellation intent, under those guards.
+3. Changes its own records and calls `change.commit_in(scope, state:, transfer_receipt:, pending:)` once.
+4. Returns after the outer commit. Agent publishes the captured result only then.
+
+The change is bound to the original thread, coordinator and prepared scope. It
+checks its Agent watermark and expected execution revision. A nested savepoint
+cannot authorize publication. Reconciliation compares Root, execution payload,
+appended journal, extension content, cancellation intent, and participant evidence
+in a consistent scope. Exact post-state proves commit; exact pre-state proves no
+commit; different state or failed reads require recovery. There is no write retry.
+An updated record at the expected revision alone is insufficient evidence.
+
+Subagent cancellation retains unresolved active work. Known business errors may
+follow `on_error: :skip`; unknown external outcomes cannot be skipped into success.
+Handoff Source transfer and Target terminal stabilization join the same Agent
+change. A suspended or recovery-required Target does not stabilize routing.
+Current participant key/version and Target definition must match before resuming.
+Terminal results can still be read without re-creating application wiring.
+
+## Retention and cancellation
+
+`agent.retentions` prevents purge independently of MultiAgent schema. C01 records
+its parent/child or conversation holds when reserving/creating work. History
+removal checks unfinished work, removes its references and releases only its own
+owner key in the same transaction. Other holds remain authoritative.
+`agent.cancellations` stores monotonic intent separately from execution revision,
+so an external cancel does not invalidate an in-flight worker's captured revision.
+Signal delivery follows the durable write; restored executions read that intent.
+
+`Agent::Admission` remains the same-scope acceptance boundary. A participant never
+starts a child inside a transaction or waits for its lifetime on a worker thread.
+Ordinary Agent composition does not load MultiAgent routing repositories.
+Standalone `dispatch_parallel` keeps its existing Runtime-scoped behavior.
+
+## Remaining boundaries
+
+`MultiAgent::AdmissionRegistry` still uses Runtime shutdown coordination. Agent,
+Tool and Workflow execution internals still depend on existing Engine mechanisms.
+These are later r8 work, not erased by constructor injection or diagram grouping.
+The measured source diagram includes those edges and cycles. PostgreSQL lock
+ordering needs its actual database gate; SQLite/InMemory results do not establish
+PostgreSQL behavior. The application package records executed and unexecuted gates.
+
+See [API and saved-data migration](../migrations/r8-unit4.md).