phronomy 0.26.0 → 0.28.0

data/docs/architecture/r8-unit17.md

@@ -0,0 +1,73 @@
+# r8 unit17: Domain settings consumption
+
+This responsibility-only refactor is based on applied unit16, commit
+`fb551e1a1a8334b2547ecad126dd9c152c1b0f8c` (tree
+`1ddb3b0e3f4eb97c1738ad02f9035eeefa180c90`). It addresses B08.
+
+## Values and composition have different owners
+
+Agent::Settings owns Agent option values and the existing stream callback error
+policy validation. WorkflowSettings owns the Workflow progress limit and optional
+state repository. They contain actual domain values, never the application
+Configuration object. Their readers do not select a concrete adapter or backend.
+Configuration remains the application-facing facade and composes these values;
+its existing readers, writers, default values and zero-argument constructor remain.
+The application composition boundary supplies the defaults and lazy providers.
+
+The existing MultiAgent::Store receives a provider for the optional configured
+store. It does not construct a fallback. Team still falls back to its fresh-store
+factory; Orchestrator still permits no coordination store unless durable children
+require one. Explicit stores and execution participants keep their priority.
+A single store reader does not require a separate MultiAgent settings class.
+
+Logger reads use the existing neutral RuntimeSettings. Agent authorization pool
+size and queue capacity belong to the execution connection, which reads them
+when submitting authorization work to the owning Runtime. Agent retains timeout
+selection, approval evaluation, result interpretation, and operation supervision.
+The private ExecutionEnvironment#submit_authorization operation separates those
+resource choices from ToolInvocation. Generic Tool submission is unchanged.
+
+## Preserve read timing without notifications
+
+Each existing read remains at its previous execution boundary. Providers are
+bound without evaluating Configuration or starting Runtime resources. A read
+resolves the current domain values; it does not subscribe, poll, cache, or push
+changes. There is no observer, change event, background task, version counter,
+refresh loop, or new in-flight reconfiguration guarantee.
+
+The existing read positions and short-circuit rules remain significant:
+
+- Agent class model fallback is read when model is requested. Explicit class
+  models keep precedence. Already-created Agent stores are not replaced.
+- Hooks and LLM adapter operations are read at the existing input preparation,
+  identity check, and call sites. Hook order and validation remain Agent rules.
+- Workflow limits are read when starting or resuming execution. An admitted
+  execution retains its limit; a changed global default does not update it.
+- Explicit nil, per-invocation overrides, configured stores, and fresh fallback
+  stores retain their existing meanings. No new defaults are created on reads.
+- Configuration copies duplicate the domain value containers while retaining
+  injected component identities, preserving nested scoped overrides and reset.
+
+The new domain value types are internal, grouped by responsibility rather than
+one class per setting. Public Configuration continues to offer the same settings;
+applications do not need to inject every value manually. Its private instance
+variables and internal containers are not an application extension API.
+
+## Verification and limits
+
+Regression checks cover lazy boot and direct Configuration loading, nested scope
+restoration after failure, reset, component identities, nil, class and invocation
+overrides, hook read timing/order, Workflow admission-time limits, persistent
+Agent stores, and the distinct Team/Orchestrator fallback behavior. Execution
+connection tests verify authorization resource options and owning Runtime.
+Existing failure-policy/logging tests configure values through public writers
+instead of mocking the old composition getter. RBS records the new internal
+boundaries without erasing domain operation types.
+
+AST gates reject application Configuration references from Agent, Workflow, and
+MultiAgent domain code, including literal reflective access. They also reject
+pool sizing in domain code. These are targeted regression checks, not a proof of
+all dynamic dependencies or a whole-framework completion claim.
+
+B07 remains applied. F01 durable Workflow children and other feature work are
+outside this change. There are no storage schema or public operation changes.

data/docs/architecture/r8-unit18.md

@@ -0,0 +1,92 @@
+# R8 unit18: durable cancellation receipt
+
+## Problem
+
+An Orchestrator load can return while recovery of a framework-owned child is still
+in flight. If the child needs external factual resolution, Agent captures an
+immutable terminal command that will retain the active parent in coordination
+wait. A cancelled token supplied to `resume` after command capture previously
+cancelled only the live invocation. The earlier command could then persist a
+false cancellation snapshot and release the owner. Restart lost the request.
+
+Controlled scheduling reproduced this in both unit16 and unit17, three times out
+of three. The original example passed 200 natural repetitions. Without the
+applicant's original failure log, equivalence to that initial failure is not
+established. The controlled race is independently demonstrated.
+
+## Ownership
+
+Agent owns receipt of cancellation for an exact execution, its existing durable
+cancellation ledger, and persistence of the parent execution. MultiAgent still
+owns the unresolved-child and pending-parent rules. Execution owns notification
+registration and delivery; Engine owns runtime connections. No Agent decision is
+moved into those mechanisms or into neutral Persistence/Storage.
+
+`ExactExecution` validates identity, reservation, input and participant binding
+before recording a supplied cancellation through `Store#request_cancellation`.
+The write runs in its existing off-EventLoop preparation, before recovery or
+waiting. If cancellation first becomes visible during EventLoop delivery,
+preparation runs again before the live owner is signalled. Recording errors fail
+the observer and do not proceed to recovery or notification.
+
+`ExecutionChange#prepare_in` already reads the monotonic cancellation ledger
+inside the participant transaction. `ExecutionOutcomeCommitter` now uses that
+prepared fact for a pending execution's cancellation metadata. The worker's
+captured command remains immutable; it does not query a live invocation or token.
+
+## Ordering and preserved semantics
+
+- Before outcome commit: the transaction sees the accepted ledger entry and saves
+  cancellation in both Agent pending metadata and MultiAgent extension state.
+- After outcome commit: the ledger retains newly accepted intent without changing
+  execution revision or invalidating the in-flight result. The previously saved
+  metadata/extension remain a snapshot; the next recovery/change incorporates the
+  ledger. Immediate equality between those snapshots and the ledger is not an API
+  guarantee. The ledger is the durable source of accepted cancellation intent.
+- After owner release: receipt records intent before recovery installation.
+- An absent execution is not assigned a cancellation record. A terminal result,
+  including one that wins against cancellation receipt, remains unchanged.
+- Unknown child external outcomes still require factual resolution. No LLM replay,
+  forced child completion or new recovery capability is introduced.
+
+There is no schema change, public API change, new Contract, Registry, subscription
+or polling mechanism. This fixes receipt of cancellation observed by the existing
+exact-execution path; it does not introduce continuous subscription to an incoming
+token after observer registration.
+
+## Verification design
+
+Queue gates hold the outcome worker before commit and after commit/before result
+publication. Gates never block EventLoop or hold a storage transaction. Tests
+assert ledger persistence, unchanged revision during receipt, pending snapshots,
+restart preservation, unknown-child activity and zero LLM replay. Additional
+component tests cover validation rejection, write failure, recovery ordering,
+late token observation and terminal-result preservation. The pending commit test
+also covers committed-response loss.
+
+The original checkpoint fixture now performs phase inspection and snapshot copy
+under one backend lock, preventing concurrent after-commit hooks from replacing a
+selected checkpoint. Its initial assertion uses the durable ledger because a
+request arriving after a saved waiting snapshot need not rewrite that snapshot.
+Separate deterministic tests assert the snapshot on each side of the commit.
+
+## Unit18 delivery correction
+
+The first unit18 version checked the incoming token twice inside delivery: once
+to decide whether to record, and again to decide whether to signal. Cancellation
+between those observations could skip recording but still signal the owner.
+A suspended approval execution then exited without a completion reconciliation,
+leaving the durable ledger empty.
+
+Delivery now uses one cancellation observation for both decisions. After finding
+and validating the current owner, an observed cancellation returns to off-loop
+preparation if unrecorded, or signals the owner if already recorded. The separate
+preparation and delivery observations remain intentional: scheduling between those
+stages can change the token. A notification is never authorized by a different
+observation from the one used to enforce its recording prerequisite.
+
+Regression tests use the real suspended owner, registry and EventLoop. They
+cancel the incoming token just before delivery or during the owner lookup, and
+cover both successful recording and recording failure. They assert recording
+before notification, no notification on write failure, off-loop persistence and
+unchanged suspended execution contents. No polling or new subscription is added.

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.